@expresscsv/sdk 0.1.22 → 0.1.23

package/README.md

@@ -44,15 +44,17 @@ const importer = new CSVImporter({
 importer.open({
   onData: (chunk, next) => {
     console.log(`Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
+    console.log("Session:", chunk.sessionId);
+    console.log("Idempotency key:", chunk.chunkIdempotencyKey);
     console.log("Records:", chunk.records);
     // Process your validated, typed records here
     next();
   },
-  onComplete: () => {
-    console.log("All chunks processed successfully");
+  onComplete: ({ sessionId }) => {
+    console.log("All chunks processed successfully for", sessionId);
   },
-  onError: (error) => {
-    console.error("Import failed:", error);
+  onError: (error, { sessionId }) => {
+    console.error("Import failed for", sessionId, error);
   },
 });
 ```
@@ -61,182 +63,52 @@ If your schema is assembled dynamically at runtime, still use `x.row(...)`. Just
 
 Have your backend keep the ExpressCSV secret key, call the ExpressCSV session-creation endpoint, and return a short-lived importer session token to the browser via `getSessionToken`. The SDK opens the importer immediately, then completes the initial session bootstrap in the background.
 
-## Webhook Delivery
+## Delivery
 
-Deliver imported data directly to your backend via webhook instead of (or in addition to) a local callback:
-
-```typescript
-importer.open({
-  webhook: {
-    url: "https://api.example.com/webhooks/csv-import",
-    method: "POST",
-    headers: {
-      Authorization: "Bearer your-api-token",
-    },
-    metadata: {
-      source: "web-app",
-      userId: "user-123",
-    },
-  },
-  onComplete: () => {
-    console.log("Webhook delivery initiated");
-  },
-  onError: (error) => {
-    console.error("Delivery error:", error);
-  },
-});
-```
-
-### Webhook Payload Structure
-
-Each chunk is delivered as a JSON `POST` (or whichever method you configured) to your endpoint. The request body has this shape:
-
-```typescript
-interface WebhookPayload {
-  /** Imported records for this chunk, matching your schema */
-  records: Record<string, unknown>[];
-  /** 0-based index of the current chunk */
-  chunkIndex: number;
-  /** Total number of chunks in this delivery */
-  totalChunks: number;
-  /** Total number of records across all chunks */
-  totalRecords: number;
-  /** Present only if you passed `metadata` in `WebhookConfig` */
-  metadata?: Record<string, unknown>;
-  /** Delivery context added by ExpressCSV */
-  delivery: {
-    environmentName: string;
-    environmentType: string;
-    teamSlug: string;
-    importIdentifier: string;
-    deliveryId: string;
-    timestamp: string; // ISO 8601
-  };
-}
-```
-
-When you already have a schema, prefer `InferWebhookPayload<typeof schema>` from `@expresscsv/schemas` instead of rewriting this object shape by hand.
-
-Example payload:
-
-```json
-{
-  "records": [
-    { "name": "Alice Johnson", "email": "alice@example.com", "age": 32 },
-    { "name": "Bob Smith", "email": "bob@example.com", "age": 45 }
-  ],
-  "chunkIndex": 0,
-  "totalChunks": 3,
-  "totalRecords": 2500,
-  "metadata": {
-    "source": "web-app",
-    "userId": "user-123"
-  },
-  "delivery": {
-    "environmentName": "Production",
-    "environmentType": "production",
-    "teamSlug": "my-team",
-    "importIdentifier": "user-import",
-    "deliveryId": "del_abc123",
-    "timestamp": "2026-03-02T14:30:00.000Z"
-  }
-}
-```
-
-The request includes a `Content-Type: application/json` header plus any custom `headers` you specified in `WebhookConfig`.
-
-### Handling Webhooks on Your Server
-
-Your endpoint should return a **2xx** status code to acknowledge each chunk. Non-2xx responses trigger the following retry behaviour:
-
-- **5xx** and **429** responses are retried automatically (up to 5 attempts per chunk).
-- **4xx** responses (except 429) are treated as permanent failures and are **not** retried.
-
-Chunks are delivered **serially** — the next chunk is only sent after the previous one succeeds.
-
-If your schema is defined in shared or backend code with `@expresscsv/schemas`, you can reuse the built-in webhook payload helper when handling deliveries:
-
-```typescript
-import express from "express";
-import type { InferWebhookPayload } from "@expresscsv/schemas";
-import { employeeSchema } from "../shared/employee-schema";
-
-const app = express();
-app.use(express.json());
-
-app.post("/webhooks/csv-import", async (req, res) => {
-  const payload = req.body as InferWebhookPayload<typeof employeeSchema>;
-
-  await db.insertMany("users", payload.records);
-
-  res.status(200).json({ ok: true });
-});
-```
-
-Below is a minimal Express.js example:
-
-```typescript
-import express from "express";
-
-const app = express();
-app.use(express.json());
-
-app.post("/webhooks/csv-import", async (req, res) => {
-  const token = req.headers.authorization;
-  if (token !== "Bearer your-api-token") {
-    return res.status(401).json({ error: "Unauthorized" });
-  }
-
-  const { records, chunkIndex, totalChunks, totalRecords, metadata, delivery } =
-    req.body;
-
-  try {
-    // Process the records — e.g. insert into your database
-    await db.insertMany("users", records);
-
-    console.log(
-      `Chunk ${chunkIndex + 1}/${totalChunks} processed ` +
-        `(${records.length} records, delivery ${delivery.deliveryId})`
-    );
-
-    res.status(200).json({ success: true });
-  } catch (error) {
-    // Return 500 so ExpressCSV retries this chunk
-    console.error("Failed to process chunk:", error);
-    res.status(500).json({ error: "Internal server error" });
-  }
-});
-
-app.listen(3000);
-```
-
-**Tips:**
-
-- Use `delivery.deliveryId` and `chunkIndex` to **deduplicate** retried chunks (the same chunk may be delivered more than once on retry).
-- Use `chunkIndex` and `totalChunks` to track progress and know when the full import is complete (`chunkIndex === totalChunks - 1` for the last chunk).
-- Store `metadata` alongside imported records if you need to correlate the import with a specific user or action in your app.
-
-### Combined Local Callback and Webhook
-
-You can use both `onData` and `webhook` simultaneously:
+ExpressCSV delivers imported data through `onData`. Your app receives validated chunks in the browser and can forward them to your backend using whatever request shape fits your stack.
 
 ```typescript
 importer.open({
   chunkSize: 500,
   onData: async (chunk, next) => {
-    await saveToLocalDatabase(chunk.records);
+    const response = await fetch("/api/import-users/chunks", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        sessionId: chunk.sessionId,
+        chunkIdempotencyKey: chunk.chunkIdempotencyKey,
+        records: chunk.records,
+        currentChunkIndex: chunk.currentChunkIndex,
+        totalChunks: chunk.totalChunks,
+        totalRecords: chunk.totalRecords,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error("Backend rejected this import chunk");
+    }
+
     next();
   },
-  webhook: {
-    url: "https://api.example.com/webhooks/csv-import",
-    headers: { Authorization: "Bearer your-api-token" },
-  },
-  onComplete: () => {
-    console.log("Local processing and webhook delivery complete");
+  onComplete: ({ sessionId }) => {
+    console.log("Import complete for", sessionId);
   },
 });
 ```
 
+Each delivered chunk includes:
+
+- `records`
+- `sessionId`
+- `chunkIdempotencyKey`
+- `currentChunkIndex`
+- `totalChunks`
+- `totalRecords`
+
+Use `sessionId` and `chunkIdempotencyKey` to stage writes safely and deduplicate retries from your own app logic.
+
 ## Preloading
 
 By default, the SDK preloads the importer in a hidden iframe for instant display when `open()` is called. This provides the best user experience while the initial session bootstrap continues in the background.
@@ -432,7 +304,7 @@ const importer = new CSVImporter({
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
 
-For apps that share schema definitions with backend code or webhook handlers, prefer defining the schema in `@expresscsv/schemas` and importing it into your frontend. That keeps schema authoring free of importer/runtime dependencies.
+For apps that share schema definitions with backend code, prefer defining the schema in `@expresscsv/schemas` and importing it into your frontend. That keeps schema authoring free of importer/runtime dependencies.
 
 ### Field Types
 
@@ -689,13 +561,16 @@ new CSVImporter(options: SDKOptions)
 | `fonts` | `Record<string, ECSVFontSource>` | No | - | Custom font sources |
 | `stepDisplay` | `'progressBar' \| 'segmented' \| 'numbered'` | No | `'progressBar'` | Step indicator style |
 | `previewSchemaBeforeUpload` | `boolean` | No | `true` | Show schema preview before upload |
+| `aiColumnMatching` | `boolean` | No | `true` | Enable AI-assisted column matching |
+| `aiTransform` | `boolean` | No | `true` | Enable AI-assisted transform generation |
 | `templateDownload` | `TemplateDownloadOptions<TSchema>` | No | - | Template download configuration with optional schema-typed example rows |
-| `saveSession` | `boolean` | No | - | Persist session state |
+| `storage` | `{ type: "local" } \| { type: "custom", ... }` | No | - | Enable Recovered Sessions with the built-in local backend or a custom adapter implementing `get`, `set`, and `remove` |
 | `locale` | `DeepPartial<ExpressCSVLocaleInput>` | No | - | Localization overrides |
+| `disableStatusStep` | `boolean` | No | - | Skip the success/error status screen |
 
 #### `open(options)`
 
-Opens the importer and begins the import flow. At least one of `onData` or `webhook` must be provided.
+Opens the importer and begins the import flow.
 
 ```typescript
 importer.open(options: OpenOptions): void
@@ -703,18 +578,15 @@ importer.open(options: OpenOptions): void
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | * | Callback for each chunk of records. Call `next()` to continue. |
-| `webhook` | `WebhookConfig` | * | Webhook endpoint for server-side delivery |
+| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | Yes | Callback for each delivered chunk of records. Call `next()` to continue. |
 | `chunkSize` | `number` | No | Records per chunk (default: 1000) |
-| `onComplete` | `() => void` | No | Called when all chunks have been processed |
-| `onCancel` | `() => void` | No | Called when the user cancels the import |
-| `onError` | `(error: Error) => void` | No | Called when an error occurs |
+| `onComplete` | `(context: { sessionId: string }) => void` | No | Called when all chunks have been processed |
+| `onCancel` | `(context: { sessionId: string }) => void` | No | Called when the user cancels the import |
+| `onError` | `(error: Error, context: { sessionId: string }) => void` | No | Called when an error occurs |
 | `onImporterOpen` | `() => void` | No | Called when the importer opens |
-| `onImporterClose` | `(reason: string) => void` | No | Called when the importer closes |
+| `onImporterClose` | `(reason: 'user_close' \| 'cancel' \| 'complete' \| 'error') => void` | No | Called when the importer closes |
 | `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the wizard step changes |
 
-\* At least one of `onData` or `webhook` is required.
-
 #### `close(reason?)`
 
 Closes the importer and cleans up resources.
@@ -736,7 +608,6 @@ await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): P
 | `getCanRestart()` | `boolean` | Whether the importer can be restarted |
 | `getLastError()` | `Error \| null` | Last error, if any |
 | `getStatus()` | `object` | Comprehensive status snapshot |
-| `getVersion()` | `string` | SDK version |
 
 #### `restart(newOptions?)`
 
@@ -752,19 +623,8 @@ interface RecordsChunk<T> {
   totalChunks: number;
   currentChunkIndex: number;
   totalRecords: number;
-}
-```
-
-### `WebhookConfig`
-
-```typescript
-interface WebhookConfig {
-  url: string;
-  headers?: Record<string, string>;
-  method?: "POST" | "PUT" | "PATCH";
-  timeout?: number;
-  retries?: number;
-  metadata?: Record<string, unknown>;
+  sessionId: string;
+  chunkIdempotencyKey: string;
 }
 ```
 

package/dist/index.d.cts

@@ -1256,6 +1256,8 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private importerMode;
     private canRestart;
     private lastError;
+    private stateChangeListeners;
+    private lastTerminalSessionState;
     private openOptions;
     private cachedSchemaJson;
     private initCompletePromise;
@@ -1263,11 +1265,17 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private resolvedTemplateDownload;
     private importerStartupGeneration;
     constructor(options: SDKOptions<TSchema>);
+    private getCustomStorageRpcHandler;
     /**
      * Enhanced state management
      */
     private setState;
     private updateDerivedState;
+    private createSessionId;
+    private getOrCreateSessionId;
+    private getImportSessionContext;
+    private getChunkIdempotencyKey;
+    private createRecordsChunk;
     private handleError;
     private sendImportProgress;
     private waitForEvent;
@@ -1297,16 +1305,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      */
     private createImportSession;
     /**
-     * Deliver results to webhook endpoint via backend API
-     * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
-     */
-    private deliverToWebhook;
-    /**
-     * Send a single chunk to backend webhook API with retry logic
-     */
-    private sendChunkToBackend;
-    /**
-     * Process results in chunks, calling onData and/or webhook for each chunk with backpressure control
+     * Process results in chunks, calling onData with backpressure control
      */
     private processResultsInChunks;
     /**
@@ -1342,6 +1341,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private handleImporterClosed;
     private hideContainer;
     getConnectionStatus(): boolean;
+    subscribeToStateChanges(listener: StateChangeListener): () => void;
     getState(): ImporterState;
     getMode(): ImporterMode;
     getIsReady(): boolean;
@@ -1358,7 +1358,6 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
         lastError: Error | null;
         connectionStatus: boolean;
     };
-    getVersion(): string;
 }
 
 /**
@@ -2004,6 +2003,13 @@ declare const CurrencyCodes: readonly [{
     readonly numeric: "932";
 }];
 
+export declare type CustomStorageOptions = {
+    type: 'custom';
+    get: (key: StorageKey) => Promise<StoredSession | null>;
+    set: (key: StorageKey, value: StoredSession) => Promise<void>;
+    remove: (key: StorageKey) => Promise<void>;
+};
+
 declare interface DatetimeOptions {
     message?: string;
 }
@@ -2012,19 +2018,9 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-/**
- * Delivery options - requires at least one of onData or webhook
- */
-export declare type DeliveryOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'>;
-
-/**
- * Base delivery options - at least one must be provided
- */
-declare interface DeliveryOptionsBase<T> {
-    /** Local callback for processing chunks */
-    onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-    /** Webhook configuration for remote delivery */
-    webhook?: WebhookConfig;
+export declare interface DeliveryOptions<T> {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
 }
 
 /**
@@ -3624,12 +3620,21 @@ export declare enum ImporterState {
     DESTROYED = "destroyed"
 }
 
+export declare interface ImportSessionContext {
+    /** Generated session ID for the current import run */
+    sessionId: string;
+}
+
 export declare type Infer<T extends ExType<unknown, ExBaseDef, unknown>> = T extends ExType<infer Output, ExBaseDef, unknown> ? Output : never;
 
 export declare type InferCSVImporter<TSchema extends ExType<unknown, ExBaseDef, unknown>> = CSVImporter<TSchema>;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3637,17 +3642,17 @@ declare interface MultiselectOptions {
 
 /**
  * Options for the open() method
- * Requires at least one of onData or webhook for delivery
+ * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'> & {
+export declare type OpenOptions<T> = DeliveryOptions<T> & {
     /** Number of records per chunk (default: 1000) */
     chunkSize?: number;
     /** Called when all chunks have been processed */
-    onComplete?: () => void;
+    onComplete?: (context: ImportSessionContext) => void;
     /** Called when the user cancels the import */
-    onCancel?: () => void;
+    onCancel?: (context: ImportSessionContext) => void;
     /** Called when an error occurs */
-    onError?: (error: Error) => void;
+    onError?: (error: Error, context: ImportSessionContext) => void;
     /** Called when the importer opens */
     onImporterOpen?: () => void;
     /** Called when the importer closes */
@@ -3656,6 +3661,17 @@ export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, '
     onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
 };
 
+declare interface PersistedImportSessionData {
+    data: PersistedImportSessionPayload;
+}
+
+declare type PersistedImportSessionKey = string;
+
+declare type PersistedImportSessionPayload = {
+    rowData: Record<string, unknown>[];
+    columnKeys: string[];
+};
+
 declare type PhoneNumberFormat = 'international' | 'national' | 'both';
 
 declare type PhoneNumberOutput = 'e164' | 'formatted' | 'digits';
@@ -3762,6 +3778,10 @@ export declare interface RecordsChunk<T> {
     currentChunkIndex: number;
     /** Total number of records across all chunks */
     totalRecords: number;
+    /** Generated session ID for the current import run */
+    sessionId: string;
+    /** Stable per-chunk idempotency key */
+    chunkIdempotencyKey: string;
 }
 
 declare type RefineBatchResultItem = {
@@ -3793,13 +3813,6 @@ declare type RefineResultItem = {
     };
 };
 
-/**
- * Type helper that requires at least one of the specified keys to be present
- */
-declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
-    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
-}[Keys];
-
 export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
     schema: TSchema;
     getSessionToken: () => Promise<string>;
@@ -3813,8 +3826,10 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
+    aiColumnMatching?: boolean;
+    aiTransform?: boolean;
     templateDownload?: TemplateDownloadOptions<TSchema>;
-    saveSession?: boolean;
+    storage?: StorageOptions;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
 }
@@ -3831,6 +3846,16 @@ declare interface SelectOptions {
     message?: string;
 }
 
+declare type StateChangeListener = (state: ImporterState) => void;
+
+export declare type StorageKey = PersistedImportSessionKey;
+
+export declare type StorageOptions = LocalStorageOptions | CustomStorageOptions;
+
+export declare type StoredSession = PersistedImportSessionData;
+
+export declare type StoredSessionData = PersistedImportSessionPayload;
+
 declare type StripBrand<T> = {
     [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
 };
@@ -3927,31 +3952,6 @@ declare interface ValidatorCheck {
     message?: string;
 }
 
-/**
- * Webhook configuration for remote delivery of results
- */
-export declare interface WebhookConfig {
-    /** The URL to send webhook requests to */
-    url: string;
-    /** Optional HTTP headers to include in the request */
-    headers?: Record<string, string>;
-    /** HTTP method to use (default: 'POST') */
-    method?: 'POST' | 'PUT' | 'PATCH';
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Number of retry attempts on failure (default: 0) */
-    retries?: number;
-    /** Arbitrary developer-provided metadata */
-    metadata?: Record<string, unknown>;
-    /**
-     * Whether to wait for the delivery service to confirm the webhook was
-     * successfully received before considering the import complete.
-     * When false, the import completes as soon as all chunks are queued.
-     * Default: false
-     */
-    awaitWebhookArrival?: boolean;
-}
-
 export declare const x: {
     string: typeof ExString.create;
     number: typeof ExNumber.create;