feat: align main exports across node and browser

README.md

@@ -268,6 +268,7 @@ node ./dist/cli.js
 npm run test             # All tests
 npm run test:unit        # Unit tests only
 npm run test:integration # Integration tests
+npm run test:browser     # Browser tests
 npm run lint:fix         # Fix formatting
 ```
 

package.json

@@ -7,6 +7,10 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
+      "browser": {
+        "types": "./dist/index.browser.d.ts",
+        "default": "./dist/index.browser.js"
+      },
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
@@ -75,9 +79,10 @@
     "build": "tsc && node scripts/write-version.mjs",
     "dev": "tsx watch src/cli.ts server",
     "start": "node dist/cli.js server",
-    "test": "npm run lint && npm run typecheck && npm run test:unit && npm run test:integration",
-    "test:unit": "vitest run src/test/unit",
-    "test:integration": "vitest run src/test/integration",
+    "test": "npm run lint && npm run typecheck && vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:browser": "vitest run --project browser",
     "test:watch": "vitest",
     "lint": "tsc && biome check --no-errors-on-unmatched --files-ignore-unknown=true .",
     "lint:fix": "biome check --no-errors-on-unmatched --files-ignore-unknown=true --fix .",
@@ -122,10 +127,12 @@
     "@ipld/dag-cbor": "^9.2.5",
     "@types/node": "^24.5.1",
     "@types/semver": "^7.5.8",
-    "@vitest/coverage-v8": "^4.0.12",
+    "@vitest/browser-playwright": "^4.0.13",
+    "@vitest/coverage-v8": "^4.0.13",
+    "playwright-chromium": "^1.56.1",
     "tsx": "^4.20.5",
     "typescript": "^5.9.2",
-    "vitest": "^4.0.12"
+    "vitest": "^4.0.13"
   },
   "publishConfig": {
     "access": "public"

src/index-types.ts

@@ -0,0 +1,48 @@
+import type { getDataSetPieces, getDetailedDataSet, listDataSets } from './core/data-set/index.js'
+import type { getPaymentStatus, validatePaymentCapacity } from './core/payments/index.js'
+import type { cleanupSynapseService, setupSynapse } from './core/synapse/index.js'
+import type { createCarFromFile, createCarFromFiles } from './core/unixfs/browser-car-builder.js'
+import type { createCarFromPath } from './core/unixfs/car-builder.js'
+import type { checkUploadReadiness, executeUpload } from './core/upload/index.js'
+
+export interface FilecoinPinAPI {
+  getDataSetPieces: typeof getDataSetPieces
+  getDetailedDataSet: typeof getDetailedDataSet
+  listDataSets: typeof listDataSets
+  getPaymentStatus: typeof getPaymentStatus
+  validatePaymentCapacity: typeof validatePaymentCapacity
+  cleanupSynapseService: typeof cleanupSynapseService
+  setupSynapse: typeof setupSynapse
+  createCarFromFile: typeof createCarFromFile
+  createCarFromFiles: typeof createCarFromFiles
+  createCarFromPath: typeof createCarFromPath
+  checkUploadReadiness: typeof checkUploadReadiness
+  executeUpload: typeof executeUpload
+}
+
+export type { ProviderInfo } from '@filoz/synapse-sdk'
+export type {
+  DataSetPiecesResult,
+  DataSetSummary,
+  GetDataSetPiecesOptions,
+  ListDataSetsOptions,
+  PieceInfo,
+  Warning as DataSetWarning,
+} from './core/data-set/index.js'
+export type { PaymentCapacityCheck, PaymentStatus } from './core/payments/index.js'
+export type {
+  CreateStorageContextOptions,
+  DatasetOptions,
+  SynapseService,
+  SynapseSetupConfig,
+} from './core/synapse/index.js'
+export type { CreateCarOptions, CreateCarResult } from './core/unixfs/car-builder.js'
+export type {
+  SynapseUploadOptions,
+  SynapseUploadResult,
+  UploadExecutionOptions,
+  UploadExecutionResult,
+  UploadProgressEvents,
+  UploadReadinessOptions,
+  UploadReadinessResult,
+} from './core/upload/index.js'

src/index.browser.ts

@@ -0,0 +1,53 @@
+/**
+ * High-level API for filecoin-pin
+ *
+ * This file exports the most common functions and types for interacting with the filecoin-pin library in the browser.
+ * For more advanced use cases, you can import from the granular `./core/*` modules.
+ */
+import * as dataSet from './core/data-set/index.js'
+import * as payments from './core/payments/index.js'
+import * as synapse from './core/synapse/index.js'
+import * as browserCar from './core/unixfs/browser-car-builder.js'
+import type { CreateCarOptions } from './core/unixfs/car-builder.js'
+import * as upload from './core/upload/index.js'
+import type { FilecoinPinAPI } from './index-types.js'
+
+export * from './index-types.js'
+
+const publicApi = {
+  getDataSetPieces: dataSet.getDataSetPieces,
+  getDetailedDataSet: dataSet.getDetailedDataSet,
+  listDataSets: dataSet.listDataSets,
+  getPaymentStatus: payments.getPaymentStatus,
+  validatePaymentCapacity: payments.validatePaymentCapacity,
+  cleanupSynapseService: synapse.cleanupSynapseService,
+  setupSynapse: synapse.setupSynapse,
+  createCarFromFile: browserCar.createCarFromFile,
+  createCarFromFiles: browserCar.createCarFromFiles,
+  /**
+   * Not available in the browser; use createCarFromFile or createCarFromFiles.
+   *
+   * @remarks Node-only helper; preserved for API parity with the Node entrypoint.
+   * @throws Always throws in browser builds.
+   */
+  createCarFromPath: (_path: string, _options?: CreateCarOptions): never => {
+    throw new Error('Function not available in the browser.')
+  },
+  checkUploadReadiness: upload.checkUploadReadiness,
+  executeUpload: upload.executeUpload,
+} satisfies FilecoinPinAPI
+
+export const {
+  getDataSetPieces,
+  getDetailedDataSet,
+  listDataSets,
+  getPaymentStatus,
+  validatePaymentCapacity,
+  cleanupSynapseService,
+  setupSynapse,
+  createCarFromFile,
+  createCarFromFiles,
+  createCarFromPath,
+  checkUploadReadiness,
+  executeUpload,
+} = publicApi

src/index.ts

@@ -0,0 +1,31 @@
+/**
+ * High-level API for filecoin-pin
+ *
+ * This file exports the most common functions and types for interacting with the filecoin-pin library in Node.js.
+ * For more advanced use cases, you can import from the granular `./core/*` modules.
+ */
+import { createCarFromPath as createCarFromPathCore } from './core/unixfs/car-builder.js'
+import * as browser from './index.browser.js'
+import type { FilecoinPinAPI } from './index-types.js'
+
+export * from './index-types.js'
+
+const publicApi = {
+  ...browser,
+  createCarFromPath: createCarFromPathCore,
+} satisfies FilecoinPinAPI
+
+export const {
+  getDataSetPieces,
+  getDetailedDataSet,
+  listDataSets,
+  getPaymentStatus,
+  validatePaymentCapacity,
+  cleanupSynapseService,
+  setupSynapse,
+  createCarFromFile,
+  createCarFromFiles,
+  createCarFromPath,
+  checkUploadReadiness,
+  executeUpload,
+} = publicApi

src/test/unit/package-import.iso.test.ts

@@ -0,0 +1,20 @@
+import { describe, expect, it } from 'vitest'
+
+describe('filecoin-pin isomorphic import', () => {
+  it('doesnt throw when importing filecoin-pin', async () => {
+    await expect(import('filecoin-pin')).resolves.toBeDefined()
+  })
+
+  it('browser and node.js exports are handled properly', async () => {
+    const { createCarFromPath, createCarFromFiles, createCarFromFile } = await import('filecoin-pin')
+
+    expect(typeof createCarFromPath).toBe('function')
+    expect(typeof createCarFromFile).toBe('function')
+    expect(typeof createCarFromFiles).toBe('function')
+    if (typeof window !== 'undefined') {
+      expect(() => createCarFromPath('foo')).toThrow('Function not available in the browser.')
+    } else {
+      await expect(createCarFromPath('foo')).rejects.toThrow('ENOENT')
+    }
+  })
+})

vitest.config.ts

@@ -1,11 +1,45 @@
+import { playwright } from '@vitest/browser-playwright'
 import { defineConfig } from 'vitest/config'
 
 export default defineConfig({
   test: {
     globals: true,
-    environment: 'node',
     root: '.',
-    include: ['src/**/*.test.ts'],
-    setupFiles: ['src/test/setup.ts'],
+    projects: [
+      {
+        // unit tests for node.js (also isomorphic tests)
+        test: {
+          name: 'unit',
+          environment: 'node',
+          include: ['src/test/unit/**/*.test.ts', 'src/test/**/*.iso.test.ts'],
+          exclude: ['src/test/**/*.browser.test.ts'],
+          setupFiles: ['src/test/setup.ts'],
+        },
+      },
+      {
+        // integration tests
+        test: {
+          name: 'integration',
+          environment: 'node',
+          include: ['src/test/integration/**/*.test.ts'],
+          exclude: ['src/test/**/*.browser.test.ts'],
+          setupFiles: ['src/test/setup.ts'],
+        },
+      },
+      {
+        // browser tests (also isomorphic tests)
+        test: {
+          name: 'browser',
+          include: ['src/test/**/*.browser.test.ts', 'src/test/**/*.iso.test.ts'],
+          browser: {
+            enabled: true,
+            provider: playwright(),
+            instances: [{ browser: 'chromium' }],
+            headless: true,
+            screenshotFailures: false,
+          },
+        },
+      },
+    ],
   },
 })