@expresscsv/react 0.1.22 → 0.1.23

package/README.md

@@ -48,17 +48,19 @@ function App() {
         console.log(
           `Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`
         );
+        console.log("Session:", chunk.sessionId);
+        console.log("Idempotency key:", chunk.chunkIdempotencyKey);
         console.log("Records:", chunk.records);
         next();
       },
-      onComplete: () => {
-        console.log("All chunks processed");
+      onComplete: ({ sessionId }) => {
+        console.log("All chunks processed for", sessionId);
       },
-      onCancel: () => {
-        console.log("User cancelled");
+      onCancel: ({ sessionId }) => {
+        console.log("User cancelled", sessionId);
       },
-      onError: (error) => {
-        console.error("Import error:", error);
+      onError: (error, { sessionId }) => {
+        console.error("Import error for", sessionId, error);
       },
     });
   };
@@ -273,200 +275,50 @@ const { open } = useExpressCSV({
 });
 ```
 
-## Webhook Delivery
+## Delivery
 
-Deliver data to a server endpoint instead of (or in addition to) processing locally:
+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.
 
 ```tsx
-import { useExpressCSV, x } from "@expresscsv/react";
-
-const schema = x.row({
-  name: x.string().label("Full Name"),
-  email: x.string().email().label("Email Address"),
-});
-
-function App() {
-  const { open } = useExpressCSV({
-    schema,
-    getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "user-import",
-    title: "Import Users",
-  });
-
-  const handleImport = () => {
-    open({
-      webhook: {
-        url: "https://api.example.com/webhooks/csv-import",
-        method: "POST",
-        headers: {
-          Authorization: "Bearer your-api-token",
-        },
-        metadata: {
-          source: "react-app",
-          userId: "user-123",
-        },
-      },
-      onComplete: () => {
-        console.log("Webhook delivery initiated");
-      },
-      onError: (error) => {
-        console.error("Delivery error:", error);
+open({
+  chunkSize: 500,
+  onData: async (chunk, next) => {
+    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,
+      }),
     });
-  };
-
-  return <button onClick={handleImport}>Import CSV via Webhook</button>;
-}
-```
-
-### 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" },
-    { "name": "Bob Smith", "email": "bob@example.com" }
-  ],
-  "chunkIndex": 0,
-  "totalChunks": 3,
-  "totalRecords": 2500,
-  "metadata": {
-    "source": "react-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 lives in shared or backend code via `@expresscsv/schemas`, you can reuse the built-in webhook payload helper in your webhook handler:
-
-```typescript
-import express from "express";
-import type { InferWebhookPayload } from "@expresscsv/schemas";
-import { candidateSchema } from "../shared/candidate-schema";
-
-const app = express();
-app.use(express.json());
-
-app.post("/webhooks/csv-import", async (req, res) => {
-  const payload = req.body as InferWebhookPayload<typeof candidateSchema>;
-
-  await importCandidates(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
+    if (!response.ok) {
+      throw new Error("Backend rejected this import chunk");
+    }
 
-```tsx
-open({
-  chunkSize: 500,
-  onData: async (chunk, next) => {
-    await saveToLocalDatabase(chunk.records);
     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`
+
 ## Advanced Example
 
 ```tsx
@@ -508,13 +360,14 @@ function CandidateImporter() {
         await importCandidates(chunk.records);
         next();
       },
-      onComplete: () => {
-        setStatus("Import complete!");
+      onComplete: ({ sessionId }) => {
+        setStatus(`Import complete: ${sessionId}`);
       },
-      onError: (error) => {
-        setStatus(`Error: ${error.message}`);
+      onError: (error, { sessionId }) => {
+        setStatus(`Error in ${sessionId}: ${error.message}`);
       },
-      onCancel: () => {
+      onCancel: ({ sessionId }) => {
+        console.log("Cancelled session", sessionId);
         setStatus(null);
       },
     });
@@ -562,37 +415,37 @@ function useExpressCSV<TSchema>(
 | `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 |
 
 #### Return Value
 
 | Property | Type | Description |
 |---|---|---|
-| `open` | `(options: OpenOptions) => void` | Opens the importer. Requires at least one of `onData` or `webhook`. |
+| `open` | `(options: OpenOptions) => void` | Opens the importer. Requires `onData` for delivery. |
 | `importerState` | `ImporterState` | Current importer lifecycle state (reactive) |
 | `isInitialising` | `boolean` | `true` while the importer is initializing or opening |
 | `isOpen` | `boolean` | `true` while the importer is open |
 
 ### `OpenOptions<T>`
 
-Options passed to `open()`. At least one of `onData` or `webhook` must be provided.
+Options passed to `open()`.
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | * | Callback for each chunk. 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. 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.
-
 ### `RecordsChunk<T>`
 
 ```typescript
@@ -601,19 +454,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;
 }
 ```
 
@@ -621,7 +463,7 @@ interface WebhookConfig {
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
 
-For apps that share schemas with backend code or webhook receivers, prefer defining the schema in `@expresscsv/schemas` and importing it into your React app. That keeps schema authoring free of React and importer dependencies, while also giving your backend access to `InferWebhookPayload<typeof schema>`.
+For apps that share schemas with backend code, prefer defining the schema in `@expresscsv/schemas` and importing it into your React app. That keeps schema authoring free of React and importer dependencies.
 
 #### Field Types
 

package/dist/index.d.cts

@@ -1878,6 +1878,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;
 }
@@ -1886,19 +1893,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>;
 }
 
 /**
@@ -3498,10 +3495,19 @@ 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;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3509,17 +3515,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 */
@@ -3528,6 +3534,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';
@@ -3634,6 +3651,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 = {
@@ -3665,13 +3686,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];
-
 declare interface SelectOption<TValue extends string | number = string | number> {
     label: string;
     value: TValue;
@@ -3684,6 +3698,14 @@ declare interface SelectOptions {
     message?: string;
 }
 
+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];
 };
@@ -3772,7 +3794,7 @@ declare interface URLOptions {
     message?: string;
 }
 
-export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, templateDownload, saveSession, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
+export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, aiColumnMatching, aiTransform, templateDownload, storage, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
     open: (options: OpenOptions<Infer<TSchema>>) => void;
     importerState: ImporterState;
     isInitialising: boolean;
@@ -3792,8 +3814,10 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     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;
 }
@@ -3806,31 +3830,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;