@expresscsv/react 0.1.26 → 1.0.0

package/README.md

@@ -25,7 +25,7 @@ yarn add @expresscsv/react
 ## Quick Start
 
 ```tsx
-import { useExpressCSV, x } from "@expresscsv/react";
+import { ImporterStatus, useExpressCSV, x } from "@expresscsv/react";
 
 const schema = x.row({
   name: x.string().label("Full Name"),
@@ -34,26 +34,26 @@ const schema = x.row({
 });
 
 function App() {
-  const { open, isOpen } = useExpressCSV({
+  const { open, status } = useExpressCSV({
     schema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "user-import",
+    importNamespace: "user-import",
     title: "Import Users",
   });
 
   const handleImport = () => {
     open({
-      chunkSize: 500,
+      chunkSize: { unit: "kb", value: 500 },
       onData: async (chunk, next) => {
         console.log(
-          `Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`
+          `Chunk ${chunk.chunkIndex + 1}/${chunk.totalChunks}`
         );
         console.log("Session:", chunk.sessionId);
-        console.log("Idempotency key:", chunk.chunkIdempotencyKey);
+        console.log("Delivery ID:", chunk.deliveryId);
         console.log("Records:", chunk.records);
         next();
       },
-      onComplete: ({ sessionId }) => {
+      onComplete: ({ sessionId, deliveryId }) => {
         console.log("All chunks processed for", sessionId);
       },
       onCancel: ({ sessionId }) => {
@@ -66,7 +66,7 @@ function App() {
   };
 
   return (
-    <button onClick={handleImport} disabled={isOpen}>
+    <button onClick={handleImport} disabled={status === ImporterStatus.OPEN}>
       Import CSV
     </button>
   );
@@ -83,7 +83,7 @@ By default the importer preloads in a hidden iframe so it appears instantly when
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
 });
 
 // Importer displays instantly
@@ -103,7 +103,7 @@ To disable preloading (there will be a brief loading screen instead):
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   preload: false,
 });
 ```
@@ -127,7 +127,7 @@ const candidateSchema = x.row({
 const { open } = useExpressCSV({
   schema: candidateSchema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "candidate-import",
+  importNamespace: "candidate-import",
   templateDownload: {
     source: "generate",
     formats: ["csv", "xlsx"],
@@ -151,10 +151,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:
 
 ```tsx
-import { useExpressCSV, x, type ECSVTheme } from "@expresscsv/react";
+import { useExpressCSV, x, type Theme } from "@expresscsv/react";
 
 // Single theme (both modes)
-const theme: ECSVTheme = {
+const theme: Theme = {
   primary: "#4F46E5",
   "primary-foreground": "#ffffff",
   background: "#ffffff",
@@ -165,7 +165,7 @@ const theme: ECSVTheme = {
 };
 
 // Dual-mode (light and dark)
-const dualTheme: ECSVTheme = {
+const dualTheme: Theme = {
   modes: {
     light: {
       primary: "#4F46E5",
@@ -184,7 +184,7 @@ function App() {
   const { open } = useExpressCSV({
     schema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "user-import",
+    importNamespace: "user-import",
     theme,
   });
   // ...
@@ -230,7 +230,7 @@ Control light/dark mode with `colorMode`:
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   colorMode: "system", // 'light' | 'dark' | 'system'
 });
 ```
@@ -243,7 +243,7 @@ Inject custom CSS for fine-grained styling overrides.
 const { open } = useExpressCSV({
   schema,
   getSessionToken: async () => fetchSessionToken(),
-  importIdentifier: "user-import",
+  importNamespace: "user-import",
   customCSS: `
     .ecsv [data-step="upload"] {
       border-radius: 1rem;
@@ -263,7 +263,7 @@ Load custom fonts via the `fonts` option:
 const { open } = useExpressCSV({
   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" },
@@ -281,18 +281,19 @@ ExpressCSV delivers imported data through `onData`. Your app receives validated
 
 ```tsx
 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,
       }),
@@ -304,8 +305,15 @@ 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 }),
+    });
   },
 });
 ```
@@ -314,15 +322,18 @@ Each delivered chunk includes:
 
 - `records`
 - `sessionId`
-- `chunkIdempotencyKey`
-- `currentChunkIndex`
+- `deliveryId`
+- `chunkIndex`
 - `totalChunks`
 - `totalRecords`
 
+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.
+
+
 ## Advanced Example
 
 ```tsx
-import { useExpressCSV, x, type Infer } from "@expresscsv/react";
+import { ImporterStatus, useExpressCSV, x, type Infer } from "@expresscsv/react";
 import { useState } from "react";
 
 const candidateSchema = x.row({
@@ -342,10 +353,10 @@ const candidateSchema = x.row({
 function CandidateImporter() {
   const [status, setStatus] = useState<string | null>(null);
 
-  const { open, isOpen } = useExpressCSV({
+  const { open, status: importerStatus } = useExpressCSV({
     schema: candidateSchema,
     getSessionToken: async () => fetchSessionToken(),
-    importIdentifier: "candidate-import",
+    importNamespace: "candidate-import",
     title: "Import Candidates",
   });
 
@@ -355,12 +366,12 @@ function CandidateImporter() {
     open({
       onData: async (chunk, next) => {
         setStatus(
-          `Processing chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}...`
+          `Processing chunk ${chunk.chunkIndex + 1}/${chunk.totalChunks}...`
         );
         await importCandidates(chunk.records);
         next();
       },
-      onComplete: ({ sessionId }) => {
+      onComplete: ({ sessionId, deliveryId }) => {
         setStatus(`Import complete: ${sessionId}`);
       },
       onError: (error, { sessionId }) => {
@@ -375,8 +386,13 @@ function CandidateImporter() {
 
   return (
     <div>
-      <button onClick={handleImport} disabled={isOpen}>
-        {isOpen ? "Importing..." : "Import Candidates"}
+      <button
+        onClick={handleImport}
+        disabled={importerStatus === ImporterStatus.OPEN}
+      >
+        {importerStatus === ImporterStatus.OPEN
+          ? "Importing..."
+          : "Import Candidates"}
       </button>
       {status && <p>{status}</p>}
     </div>
@@ -393,9 +409,7 @@ function useExpressCSV<TSchema>(
   options: UseExpressCSVOptions<TSchema>
 ): {
   open: (options: OpenOptions<Infer<TSchema>>) => void;
-  importerState: ImporterState;
-  isInitialising: boolean;
-  isOpen: boolean;
+  status: ImporterStatus;
 };
 ```
 
@@ -405,20 +419,20 @@ function useExpressCSV<TSchema>(
 |---|---|---|---|---|
 | `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 |
-| `columnMatching` | `{ type: "managed"; exact?: boolean; caseInsensitive?: boolean; normalized?: boolean; inference?: boolean } \| { type: "custom"; match: (...) => Promise<...> }` | No | `undefined` | Configure managed column matching or provide a custom matcher |
-| `promptedEdits` | `{ type: "managed" } \| { type: "custom"; edit: (...) => Promise<...> }` | No | `undefined` | Enable managed prompted edits or provide a custom edit handler |
+| `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 |
-| `sessionRecovery` | `SessionRecoveryOptions` | 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 |
 
@@ -427,9 +441,7 @@ function useExpressCSV<TSchema>(
 | Property | Type | Description |
 |---|---|---|
 | `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 |
+| `status` | `ImporterStatus` | Current importer lifecycle status (reactive) |
 
 ### `OpenOptions<T>`
 
@@ -438,13 +450,12 @@ Options passed to `open()`.
 | Option | Type | Required | Description |
 |---|---|---|---|
 | `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | Yes | Callback for each delivered chunk. Call `next()` after your backend accepts the current chunk. |
-| `chunkSize` | `number` | No | Records per chunk (default: 1000) |
+| `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 |
 
 ### `RecordsChunk<T>`
 
@@ -452,10 +463,10 @@ Options passed to `open()`.
 interface RecordsChunk<T> {
   records: T[]; // Automatically typed to your schema
   totalChunks: number;
-  currentChunkIndex: number;
+  chunkIndex: number;
   totalRecords: number;
   sessionId: string;
-  chunkIdempotencyKey: string;
+  deliveryId: string;
 }
 ```
 
@@ -570,7 +581,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, params?)` | Custom per-value validation — any sync or async JS function |
 | `.refineBatch(fn, params?)` | Custom whole-column validation — receives all values at once |

package/dist/index.d.cts

@@ -4,6 +4,18 @@ declare interface BICOptions {
 
 declare type BooleanControlType = 'toggle' | 'checkbox' | 'dropdown';
 
+export declare type ChunkSize = {
+    /** Size quota unit. */
+    unit: 'kb';
+    /** KB quota. Values <= 0 send all rows in one chunk. */
+    value: number;
+} | {
+    /** Chunk by row count. */
+    unit: 'rows';
+    /** Rows per chunk. Values <= 0 send all rows in one chunk. */
+    value: number;
+};
+
 /**
  * Color mode preference
  */
@@ -14,6 +26,10 @@ export declare interface ColumnMatch<TTargetField extends string = string> {
     targetField: TTargetField;
 }
 
+export declare type ColumnMatchHandler<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ColumnMatchingFn<SchemaFieldName<TSchema>>;
+
+export declare type ColumnMatchHandlerResult<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ColumnMatchingResult<SchemaFieldName<TSchema>>;
+
 export declare type ColumnMatchingFn<TTargetField extends string = string> = (data: ColumnMatchingParams) => Promise<ColumnMatchingResult<TTargetField>>;
 
 export declare type ColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ManagedColumnMatchingOptions | CustomColumnMatchingOptions<TSchema>;
@@ -1913,12 +1929,12 @@ declare const CurrencyCodes: readonly [{
 
 declare type CustomColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    match: ColumnMatchingFn<SchemaFieldName<TSchema>>;
+    columnMatchHandler: ColumnMatchHandler<TSchema>;
 };
 
 declare type CustomPromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    edit: PromptedEditsFn<SchemaFieldName<TSchema>>;
+    promptedEditHandler: PromptedEditHandler<TSchema>;
 };
 
 export declare type CustomSessionRecoveryOptions = {
@@ -1936,39 +1952,6 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-/**
- * Font source configuration for custom fonts
- */
-export declare type ECSVFontSource = {
-    source: 'google';
-    name: string;
-    weights?: (number | string)[];
-} | {
-    source: 'custom';
-    url: string;
-    format?: 'woff2' | 'woff';
-};
-
-/**
- * Theme - can be either dual-mode (light/dark) or single-mode (applies to both)
- */
-export declare type ECSVTheme = ECSVThemeWithModes | ECSVThemeSingle;
-
-/**
- * Single theme that applies to both light and dark modes
- */
-declare type ECSVThemeSingle = TailwindThemeVars;
-
-/**
- * Theme with light and dark mode support
- */
-declare interface ECSVThemeWithModes {
-    modes: {
-        light: TailwindThemeVars;
-        dark: TailwindThemeVars;
-    };
-}
-
 declare interface ExBaseDef {
     typeName: string;
 }
@@ -3044,11 +3027,6 @@ declare interface ExpressCSVLocale {
 /** User-facing locale type where every leaf is a plain `string`. */
 export declare type ExpressCSVLocaleInput = StripBrand<ExpressCSVLocale>;
 
-/**
- * Core step identifiers for the CSV import wizard
- */
-export declare type ExpressCSVStep = 'upload' | 'select-sheet' | 'select-header' | 'match-columns' | 'match-options' | 'review';
-
 declare type ExPrimitiveType = ExString | ExNumber | ExCurrencyNumber | ExPercentageNumber | ExBoolean | ExDate | ExTime | ExDatetime | ExSelect<string | number> | ExMultiselect<string | number> | ExOptionalPrimitiveType;
 
 declare class ExRow<T extends ExRowShape> extends ExType<{
@@ -3504,6 +3482,19 @@ declare abstract class ExType<Output, Def extends ExBaseDef, Input = Output> {
     protected _addCheck(type: string, params?: Record<string, unknown>, message?: string): ValidatorCheck;
 }
 
+/**
+ * Font source configuration for custom fonts
+ */
+export declare type FontSource = {
+    source: 'google';
+    name: string;
+    weights?: (number | string)[];
+} | {
+    source: 'custom';
+    url: string;
+    format?: 'woff2' | 'woff';
+};
+
 declare interface GTINOptions {
     message?: string;
 }
@@ -3520,6 +3511,11 @@ export declare class ImportCancelledError extends Error {
     constructor(message?: string);
 }
 
+export declare interface ImportDeliveryContext extends ImportSessionContext {
+    /** Stable ID for the delivery attempt that completed or failed */
+    deliveryId: string;
+}
+
 /**
  * Importer preload mode
  */
@@ -3528,10 +3524,15 @@ export declare enum ImporterMode {
     PRELOAD = "preload"
 }
 
+export declare type ImportErrorContext = ImportSessionContext & {
+    /** Present when an error occurs while delivering records */
+    deliveryId?: string;
+};
+
 /**
- * Importer lifecycle state
+ * Importer lifecycle status
  */
-export declare enum ImporterState {
+export declare enum ImporterStatus {
     UNINITIALIZED = "uninitialized",
     INITIALIZING = "initializing",
     READY = "ready",
@@ -3543,8 +3544,13 @@ export declare enum ImporterState {
     DESTROYED = "destroyed"
 }
 
+/**
+ * Core step identifiers for the CSV importer
+ */
+export declare type ImporterStep = 'upload' | 'select-sheet' | 'select-header' | 'match-columns' | 'match-options' | 'review';
+
 export declare interface ImportSessionContext {
-    /** Generated session ID for the current import run */
+    /** Stable ID that groups one import run across chunks and lifecycle callbacks */
     sessionId: string;
 }
 
@@ -3580,20 +3586,18 @@ declare interface MultiselectOptions {
 export declare type OpenOptions<T> = {
     /** Callback for processing delivered chunks */
     onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-    /** Number of records per chunk (default: 1000) */
-    chunkSize?: number;
+    /** Chunk size by KB quota or row count. Defaults to 500 KB. Values <= 0 send one chunk. */
+    chunkSize?: ChunkSize;
     /** Called when all chunks have been processed */
-    onComplete?: (context: ImportSessionContext) => void;
+    onComplete?: (context: ImportDeliveryContext) => void;
     /** Called when the user cancels the import */
     onCancel?: (context: ImportSessionContext) => void;
     /** Called when an error occurs */
-    onError?: (error: Error, context: ImportSessionContext) => void;
+    onError?: (error: Error, context: ImportErrorContext) => void;
     /** Called when the importer opens */
-    onImporterOpen?: () => void;
-    /** Called when the importer closes */
-    onImporterClose?: (reason: 'user_close' | 'cancel' | 'complete' | 'error') => void;
-    /** Called when the step changes in the wizard */
-    onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
+    onOpen?: (context: ImportSessionContext) => void;
+    /** Called when the importer step changes */
+    onStepChange?: (stepId: ImporterStep, previousStepId?: ImporterStep) => void;
 };
 
 declare interface PersistedImportSessionData {
@@ -3622,7 +3626,6 @@ declare interface PrimitiveExBaseDef extends ExBaseDef {
     columnNameAliases?: string[];
     description?: string;
     label?: string;
-    example?: string;
     message?: string;
     checks?: ValidatorCheck[];
     defaultValue?: unknown | (() => unknown);
@@ -3650,13 +3653,6 @@ declare abstract class PrimitiveExType<Output, Def extends PrimitiveExBaseDef, I
      * @returns The type instance for method chaining
      */
     label(text: string): this;
-    /**
-     * Sets an example value for this field
-     *
-     * @param text - Example text
-     * @returns The type instance for method chaining
-     */
-    example(text: string): this;
     /**
      * Adds a custom refinement validator to this field.
      *
@@ -3699,6 +3695,10 @@ declare abstract class PrimitiveExType<Output, Def extends PrimitiveExBaseDef, I
     protected _replaceOrAddCheck(check: ValidatorCheck, existingIndex: number): void;
 }
 
+export declare type PromptedEditHandler<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = PromptedEditsFn<SchemaFieldName<TSchema>>;
+
+export declare type PromptedEditResult<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = PromptedEditsResult<SchemaFieldName<TSchema>>;
+
 export declare type PromptedEditsChange<TField extends string = string> = {
     type: 'add';
     values: Partial<Record<TField, unknown>>;
@@ -3754,14 +3754,14 @@ export declare interface RecordsChunk<T> {
     records: T[];
     /** Total number of chunks */
     totalChunks: number;
-    /** Current chunk index (0-based) */
-    currentChunkIndex: number;
+    /** Chunk index within this delivery (0-based) */
+    chunkIndex: number;
     /** Total number of records across all chunks */
     totalRecords: number;
-    /** Generated session ID for the current import run */
+    /** Stable ID that groups one import run across chunks and lifecycle callbacks */
     sessionId: string;
-    /** Stable per-chunk idempotency key */
-    chunkIdempotencyKey: string;
+    /** Stable ID for this delivery attempt within the import session */
+    deliveryId: string;
 }
 
 export declare type RecoveredSession = PersistedImportSessionData;
@@ -3797,19 +3797,20 @@ declare type RefineResultItem = {
     };
 };
 
-declare type SchemaFieldName<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Extract<keyof Infer<TSchema>, string>;
+export declare type SchemaFieldName<TSchema extends ExType<unknown, ExBaseDef, unknown>> = Extract<keyof Infer<TSchema>, string>;
 
 export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
     schema: TSchema;
     getSessionToken: () => Promise<string>;
-    importIdentifier: string;
+    /** Stable namespace string your app assigns to this importer configuration or workflow */
+    importNamespace: string;
     title?: string;
     debug?: boolean;
     preload?: boolean;
-    theme?: ECSVTheme;
+    theme?: Theme;
     colorMode?: ColorModePref;
     customCSS?: string;
-    fonts?: Record<string, ECSVFontSource>;
+    fonts?: Record<string, FontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
     columnMatching?: ColumnMatchingOptions<TSchema>;
@@ -3908,6 +3909,26 @@ declare type TemplateString<TVars extends string = string> = string & {
     readonly __vars: TVars;
 };
 
+/**
+ * Theme - can be either dual-mode (light/dark) or single-mode (applies to both)
+ */
+export declare type Theme = ThemeWithModes | ThemeSingle;
+
+/**
+ * Single theme that applies to both light and dark modes
+ */
+declare type ThemeSingle = TailwindThemeVars;
+
+/**
+ * Theme with light and dark mode support
+ */
+declare interface ThemeWithModes {
+    modes: {
+        light: TailwindThemeVars;
+        dark: TailwindThemeVars;
+    };
+}
+
 /**
  * Time validation options
  */
@@ -3924,11 +3945,9 @@ 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, columnMatching, promptedEdits, templateDownload, sessionRecovery, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
+export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importNamespace, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, columnMatching, promptedEdits, templateDownload, sessionRecovery, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
     open: (options: OpenOptions<Infer<TSchema>>) => void;
-    importerState: ImporterState;
-    isInitialising: boolean;
-    isOpen: boolean;
+    status: ImporterStatus;
 };
 
 export declare type UseExpressCSVOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> = SDKOptions<TSchema>;