@expresscsv/sdk 0.1.25 → 1.0.0

package/README.md

@@ -36,21 +36,20 @@ const schema = x.row({
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   title: "Import Users",
 });
 
 // Open the importer and process data in chunks
 importer.open({
   onData: (chunk, next) => {
-    console.log(`Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
+    console.log(`Chunk ${chunk.chunkIndex + 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: ({ sessionId }) => {
+  onComplete: ({ sessionId, deliveryId }) => {
     console.log("All chunks processed successfully for", sessionId);
   },
   onError: (error, { sessionId }) => {
@@ -69,18 +68,19 @@ ExpressCSV delivers imported data through `onData`. Your app receives validated
 
 ```typescript
 importer.open({
-  chunkSize: 500,
+  chunkSize: { unit: "kb", value: 500 },
   onData: async (chunk, next) => {
-    const response = await fetch("/api/import-users/chunks", {
+    const response = await fetch("/your-api/import-users/chunks", {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
       },
       body: JSON.stringify({
         sessionId: chunk.sessionId,
-        chunkIdempotencyKey: chunk.chunkIdempotencyKey,
+        deliveryId: chunk.deliveryId,
+        chunkIndex: chunk.chunkIndex,
         records: chunk.records,
-        currentChunkIndex: chunk.currentChunkIndex,
         totalChunks: chunk.totalChunks,
         totalRecords: chunk.totalRecords,
       }),
@@ -92,8 +92,15 @@ importer.open({
 
     next();
   },
-  onComplete: ({ sessionId }) => {
-    console.log("Import complete for", sessionId);
+  onComplete: async ({ sessionId, deliveryId }) => {
+    await fetch("/your-api/import-users/complete", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${accessToken}`,
+      },
+      body: JSON.stringify({ sessionId, deliveryId }),
+    });
   },
 });
 ```
@@ -102,12 +109,13 @@ Each delivered chunk includes:
 
 - `records`
 - `sessionId`
-- `chunkIdempotencyKey`
-- `currentChunkIndex`
+- `deliveryId`
+- `chunkIndex`
 - `totalChunks`
 - `totalRecords`
 
-Use `sessionId` and `chunkIdempotencyKey` to stage writes safely and deduplicate retries from your own app logic.
+Each time the user finishes the import, ExpressCSV creates a new `deliveryId` for that `sessionId`. Your `onData` code can fail, and the user can retry delivery without starting the import over. Store chunks by `(sessionId, deliveryId, chunkIndex)`, then finalize the `deliveryId` from `onComplete` after all of its chunks are accepted.
+
 
 ## Preloading
 
@@ -118,7 +126,7 @@ By default, the SDK preloads the importer in a hidden iframe for instant display
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
 });
 
 // Later, the importer appears instantly
@@ -131,7 +139,7 @@ To disable preloading (there will be a brief loading screen instead):
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   preload: false,
 });
 ```
@@ -155,7 +163,7 @@ const candidateSchema = x.row({
 const importer = new CSVImporter({
   schema: candidateSchema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "candidate-import",
+  importNamespace: "candidate-import",
   templateDownload: {
     source: "generate",
     formats: ["csv", "xlsx"],
@@ -179,10 +187,10 @@ Customize the importer's appearance with the `theme`, `colorMode`, `customCSS`,
 Use the `theme` option to override CSS variables (colors, radius, typography). Pass either a single theme (applies to both light and dark) or a dual-mode theme with separate light/dark values:
 
 ```typescript
-import { CSVImporter, x, type ECSVTheme } from "@expresscsv/sdk";
+import { CSVImporter, x, type Theme } from "@expresscsv/sdk";
 
 // Single theme (both modes)
-const theme: ECSVTheme = {
+const theme: Theme = {
   primary: "#4F46E5",
   "primary-foreground": "#ffffff",
   background: "#ffffff",
@@ -193,7 +201,7 @@ const theme: ECSVTheme = {
 };
 
 // Dual-mode (light and dark)
-const dualTheme: ECSVTheme = {
+const dualTheme: Theme = {
   modes: {
     light: {
       primary: "#4F46E5",
@@ -211,7 +219,7 @@ const dualTheme: ECSVTheme = {
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   theme,
 });
 ```
@@ -255,7 +263,7 @@ Control light/dark mode with `colorMode`:
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   colorMode: "system", // 'light' | 'dark' | 'system'
 });
 ```
@@ -268,7 +276,7 @@ Inject custom CSS for fine-grained styling overrides.
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   customCSS: `
     .ecsv [data-step="upload"] {
       border-radius: 1rem;
@@ -288,7 +296,7 @@ Load custom fonts via the `fonts` option:
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   fonts: {
     title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
     body: { source: "custom", url: "https://example.com/font.woff2", format: "woff2" },
@@ -411,7 +419,6 @@ All field types support:
 |---|---|
 | `.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) |
 | `.refine(fn)` | Custom validation function |
 
@@ -551,26 +558,26 @@ new CSVImporter(options: SDKOptions)
 |---|---|---|---|---|
 | `schema` | Schema | Yes | - | Schema definition created with `x.row()` |
 | `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 |
+| `importNamespace` | `string` | Yes | - | Stable namespace string your app assigns to this importer configuration. Keep it the same for the same workflow; use a different value for different importers. |
 | `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 |
+| `theme` | `Theme` | No | - | Custom theme configuration |
 | `colorMode` | `ColorModePref` | No | - | Light/dark mode (`'light'`, `'dark'`, or `'system'`) |
 | `customCSS` | `string` | No | - | Custom CSS to inject into the importer |
-| `fonts` | `Record<string, ECSVFontSource>` | No | - | Custom font sources |
+| `fonts` | `Record<string, FontSource>` | 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 |
+| `columnMatching` | `{ type: "managed"; exact?: boolean; caseInsensitive?: boolean; normalized?: boolean; inference?: boolean } \| { type: "custom"; columnMatchHandler: (...) => Promise<...> }` | No | `undefined` | Configure managed column matching or provide a custom matcher |
+| `promptedEdits` | `{ type: "managed" } \| { type: "custom"; promptedEditHandler: (...) => Promise<...> }` | No | `undefined` | Enable managed prompted edits or provide a custom edit handler |
 | `templateDownload` | `TemplateDownloadOptions<TSchema>` | No | - | Template download configuration with optional schema-typed example rows |
-| `storage` | `{ type: "local" } \| { type: "custom", ... }` | No | - | Enable Recovered Sessions with the built-in local backend or a custom adapter implementing `get`, `set`, and `remove` |
+| `sessionRecovery` | `SessionRecoveryOptions` | 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.
+Opens the importer.
 
 ```typescript
 importer.open(options: OpenOptions): void
@@ -578,14 +585,13 @@ importer.open(options: OpenOptions): void
 
 | Option | Type | Required | Description |
 |---|---|---|---|
-| `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) |
+| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | Yes | Callback for each delivered chunk of records. Call `next()` after your backend accepts the current chunk. |
+| `chunkSize` | `ChunkSize` | No | Delivery packet size. Defaults to `{ unit: "kb", value: 500 }`. `kb` uses decimal kilobytes (`1 KB = 1000 bytes`). Use `{ unit: "kb", value: 500 }` for KB or `{ unit: "rows", value: 500 }` for row counts. Zero or negative values send all records in one chunk. |
 | `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 |
+| `onOpen` | `(context: { sessionId: string }) => void` | No | Called when the importer opens |
+| `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the importer step changes |
 
 #### `close(reason?)`
 
@@ -601,13 +607,13 @@ await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): P
 
 | Method | Returns | Description |
 |---|---|---|
-| `getState()` | `ImporterState` | Current importer lifecycle state |
+| `getStatus()` | `ImporterStatus` | Current importer lifecycle status |
 | `getIsReady()` | `boolean` | Whether the importer is ready or open |
 | `getIsOpen()` | `boolean` | Whether the importer is currently open |
 | `getConnectionStatus()` | `boolean` | Whether the iframe connection is active |
 | `getCanRestart()` | `boolean` | Whether the importer can be restarted |
 | `getLastError()` | `Error \| null` | Last error, if any |
-| `getStatus()` | `object` | Comprehensive status snapshot |
+| `getStatusSnapshot()` | `object` | Comprehensive status snapshot |
 
 #### `restart(newOptions?)`
 
@@ -621,10 +627,10 @@ The object passed to `onData` callbacks:
 interface RecordsChunk<T> {
   records: T[]; // Automatically typed to your schema
   totalChunks: number;
-  currentChunkIndex: number;
+  chunkIndex: number;
   totalRecords: number;
   sessionId: string;
-  chunkIdempotencyKey: string;
+  deliveryId: string;
 }
 ```
 
@@ -647,7 +653,7 @@ type Row = Infer<typeof schema>;
 const importer = new CSVImporter({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
 });
 
 importer.open({