@expresscsv/react 0.1.21 → 0.1.23

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/@expresscsv/react.svg)](https://www.npmjs.com/package/@expresscsv/react)
 ![license](https://img.shields.io/npm/l/@expresscsv/react.svg)
 
-React hook for embedding the [ExpressCSV](https://expresscsv.com) CSV import widget. Wraps [`@expresscsv/sdk`](https://www.npmjs.com/package/@expresscsv/sdk) with automatic lifecycle management and reactive state.
+React hook for embedding the [ExpressCSV](https://expresscsv.com) CSV importer. Wraps [`@expresscsv/sdk`](https://www.npmjs.com/package/@expresscsv/sdk) with automatic lifecycle management and reactive state.
 
 If you want to define schemas in shared or backend code without any frontend dependencies, use [`@expresscsv/schemas`](https://www.npmjs.com/package/@expresscsv/schemas) for the schema definition itself, then pass that schema into `@expresscsv/react`.
 
@@ -36,7 +36,7 @@ const schema = x.row({
 function App() {
   const { open, isOpen } = useExpressCSV({
     schema,
-    publishableKey: "your-publishable-key",
+    getSessionToken: async () => fetchSessionToken(),
     importIdentifier: "user-import",
     title: "Import Users",
   });
@@ -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);
       },
     });
   };
@@ -71,20 +73,20 @@ function App() {
 }
 ```
 
-Your `publishableKey` is available from the [ExpressCSV dashboard](https://expresscsv.com). Two key types are available: **production** keys for live usage, and **dev/testing** keys that provide unlimited test imports.
+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`.
 
 ## Preloading
 
-By default the widget preloads in a hidden iframe so it appears instantly when `open()` is called:
+By default the importer preloads in a hidden iframe so it appears instantly when `open()` is called:
 
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
 });
 
-// Widget displays instantly
+// Importer displays instantly
 const handleImport = () => {
   open({
     onData: (chunk, next) => {
@@ -100,7 +102,7 @@ To disable preloading (there will be a brief loading screen instead):
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   preload: false,
 });
@@ -124,7 +126,7 @@ const candidateSchema = x.row({
 
 const { open } = useExpressCSV({
   schema: candidateSchema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "candidate-import",
   templateDownload: {
     source: "generate",
@@ -142,7 +144,7 @@ const { open } = useExpressCSV({
 
 ## Theming and Styling
 
-Customize the widget's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
+Customize the importer's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
 
 ### Theme
 
@@ -181,7 +183,7 @@ const dualTheme: ECSVTheme = {
 function App() {
   const { open } = useExpressCSV({
     schema,
-    publishableKey: "your-publishable-key",
+    getSessionToken: async () => fetchSessionToken(),
     importIdentifier: "user-import",
     theme,
   });
@@ -227,7 +229,7 @@ Control light/dark mode with `colorMode`:
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   colorMode: "system", // 'light' | 'dark' | 'system'
 });
@@ -240,7 +242,7 @@ Inject custom CSS for fine-grained styling overrides.
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   customCSS: `
     .ecsv [data-step="upload"] {
@@ -260,7 +262,7 @@ Load custom fonts via the `fonts` option:
 ```tsx
 const { open } = useExpressCSV({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   fonts: {
     title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
@@ -273,202 +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,
-    publishableKey: "your-publishable-key",
-    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: {
-    publishableKey: string;
-    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": {
-    "publishableKey": "pk_live_abc123",
-    "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
@@ -494,7 +344,7 @@ function CandidateImporter() {
 
   const { open, isOpen } = useExpressCSV({
     schema: candidateSchema,
-    publishableKey: "your-publishable-key",
+    getSessionToken: async () => fetchSessionToken(),
     importIdentifier: "candidate-import",
     title: "Import Candidates",
   });
@@ -510,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);
       },
     });
@@ -542,7 +393,7 @@ function useExpressCSV<TSchema>(
   options: UseExpressCSVOptions<TSchema>
 ): {
   open: (options: OpenOptions<Infer<TSchema>>) => void;
-  widgetState: WidgetState;
+  importerState: ImporterState;
   isInitialising: boolean;
   isOpen: boolean;
 };
@@ -553,48 +404,48 @@ function useExpressCSV<TSchema>(
 | Option | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `schema` | Schema | Yes | - | Schema definition created with `x.row()` |
-| `publishableKey` | `string` | Yes | - | Your publishable key from the [dashboard](https://expresscsv.com) |
+| `getSessionToken` | `() => Promise<string>` | Yes | - | Async callback that asks your backend for a short-lived importer session token |
 | `importIdentifier` | `string` | Yes | - | Unique identifier for this import type |
-| `title` | `string` | No | - | Title shown in the widget header |
-| `preload` | `boolean` | No | `true` | Preload widget for instant display |
+| `title` | `string` | No | - | Title shown in the importer header |
+| `preload` | `boolean` | No | `true` | Preload the importer for instant display |
 | `debug` | `boolean` | No | `false` | Enable debug logging |
 | `theme` | `ECSVTheme` | No | - | Custom theme configuration |
 | `colorMode` | `ColorModePref` | No | - | Light/dark mode (`'light'`, `'dark'`, or `'system'`) |
-| `customCSS` | `string` | No | - | Custom CSS to inject into the widget |
+| `customCSS` | `string` | No | - | Custom CSS to inject into the importer |
 | `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 widget. Requires at least one of `onData` or `webhook`. |
-| `widgetState` | `WidgetState` | Current widget state (reactive) |
-| `isInitialising` | `boolean` | `true` while the widget is initializing or opening |
-| `isOpen` | `boolean` | `true` while the widget is open |
+| `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 |
-| `onWidgetOpen` | `() => void` | No | Called when the widget opens |
-| `onWidgetClose` | `(reason: string) => void` | No | Called when the widget closes |
+| `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: '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
@@ -603,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;
 }
 ```
 
@@ -623,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 widget 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
 
@@ -728,7 +568,7 @@ All field types support:
 
 | Modifier | Description |
 |---|---|
-| `.label(text)` | User-facing label shown in the widget |
+| `.label(text)` | User-facing label shown in the importer |
 | `.description(text)` | Help text for the field |
 | `.example(text)` | Example value shown as placeholder |
 | `.optional()` | Makes the field optional (default is required) |
@@ -780,7 +620,7 @@ x.string().refine(
 )
 ```
 
-**Object-returning validator** — inline `valid`, `message`, and an optional `suggestedFix` the widget can offer the user:
+**Object-returning validator** — inline `valid`, `message`, and an optional `suggestedFix` the importer can offer the user:
 
 ```tsx
 x.string().refine((value) => ({
@@ -847,7 +687,7 @@ x.string().refineBatch((values) => {
 
 ### `suggestedFix`
 
-Both `.refine()` and `.refineBatch()` support returning a `suggestedFix` object that the widget offers as a one-click fix for the user:
+Both `.refine()` and `.refineBatch()` support returning a `suggestedFix` object that the importer offers as a one-click fix for the user:
 
 ```tsx
 interface SuggestedFix {