@expresscsv/sdk 0.1.26 → 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 |
-| `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 |
 
 #### `open(options)`
 
-Opens the importer and begins the import flow.
+Opens the importer.
 
 ```typescript
 importer.open(options: OpenOptions): void
@@ -579,13 +586,12 @@ 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()` 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 |
 
 #### `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({

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>;
@@ -1275,7 +1291,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private connection;
     private connectionState;
     private debug;
-    private importIdentifier;
+    private importNamespace;
     private sessionId;
     private currentSessionToken;
     private currentSessionTokenExpiresAt;
@@ -1285,13 +1301,15 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private _beforeUnloadHandler;
     private importerUrl;
     private appUrl;
-    private importerState;
+    private status;
     private importerMode;
     private canRestart;
     private lastError;
-    private stateChangeListeners;
+    private statusChangeListeners;
     private lastTerminalSessionState;
     private openOptions;
+    /** Mirrors the active delivery while slicing one `event:results` batch into chunks. */
+    private deliveryIdForActiveBatch;
     private cachedSchemaJson;
     private initCompletePromise;
     private resolveInitComplete;
@@ -1301,16 +1319,22 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private getCustomStorageRpcHandler;
     private getCustomFeatureRpcHandler;
     /**
-     * Enhanced state management
+     * Enhanced status management
      */
-    private setState;
+    private setStatus;
     private updateDerivedState;
     private createSessionId;
     private getOrCreateSessionId;
     private getImportSessionContext;
-    private getChunkIdempotencyKey;
+    private getImportDeliveryContext;
     private createRecordsChunk;
+    private normalizeChunkSize;
+    private getRecordsChunkByteLength;
+    private groupResultsIntoChunks;
+    private groupResultsByByteQuota;
+    private buildByteQuotaChunks;
     private handleError;
+    private completeOpenLifecycleForClose;
     private sendImportProgress;
     private waitForEvent;
     private fetchImporterSessionToken;
@@ -1327,7 +1351,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private sendStartupErrorToImporter;
     private bootstrapImporterSession;
     /**
-     * Open the import flow with chunk-based data processing.
+     * Open the importer with chunk-based data processing.
      * Automatically opens the importer if not already open.
      *
      * @param options Configuration including onData callback for processing chunks
@@ -1342,6 +1366,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      * Process results in chunks, calling onData with backpressure control
      */
     private processResultsInChunks;
+    private parseImporterResultsPayload;
     /**
      * Initialize the iframe and connection.
      * @param hidden Whether to create the iframe hidden (for preload) or visible (for normal open)
@@ -1369,21 +1394,21 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private setupMessageHandlers;
     private createAndAppendIframe;
     private destroy;
-    close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>;
+    close(reason?: ImporterCloseReason): Promise<void>;
     private resetImporter;
     restart(newOptions?: Partial<SDKOptions<TSchema>>): Promise<void>;
     private handleImporterClosed;
     private hideContainer;
     getConnectionStatus(): boolean;
-    subscribeToStateChanges(listener: StateChangeListener): () => void;
-    getState(): ImporterState;
+    subscribeToStatusChanges(listener: StatusChangeListener): () => void;
+    getStatus(): ImporterStatus;
     getMode(): ImporterMode;
     getIsReady(): boolean;
     getIsOpen(): boolean;
     getCanRestart(): boolean;
     getLastError(): Error | null;
-    getStatus(): {
-        state: ImporterState;
+    getStatusSnapshot(): {
+        status: ImporterStatus;
         mode: ImporterMode;
         isReady: boolean;
         isOpen: boolean;
@@ -2039,12 +2064,12 @@ declare const CurrencyCodes: readonly [{
 
 export declare type CustomColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    match: ColumnMatchingFn<SchemaFieldName<TSchema>>;
+    columnMatchHandler: ColumnMatchHandler<TSchema>;
 };
 
 export declare type CustomPromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    edit: PromptedEditsFn<SchemaFieldName<TSchema>>;
+    promptedEditHandler: PromptedEditHandler<TSchema>;
 };
 
 export declare type CustomSessionRecoveryOptions = {
@@ -2062,39 +2087,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;
-    };
-}
-
 export declare interface ExBaseDef {
     typeName: string;
 }
@@ -3170,11 +3162,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<{
@@ -3630,6 +3617,19 @@ export declare abstract class ExType<Output, Def extends ExBaseDef, Input = Outp
     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;
 }
@@ -3646,6 +3646,13 @@ 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;
+}
+
+declare type ImporterCloseReason = 'user_close' | 'cancel' | 'complete' | 'error';
+
 /**
  * Importer preload mode
  */
@@ -3654,10 +3661,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",
@@ -3669,8 +3681,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;
 }
 
@@ -3708,20 +3725,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 {
@@ -3750,7 +3765,6 @@ declare interface PrimitiveExBaseDef extends ExBaseDef {
     columnNameAliases?: string[];
     description?: string;
     label?: string;
-    example?: string;
     message?: string;
     checks?: ValidatorCheck[];
     defaultValue?: unknown | (() => unknown);
@@ -3778,13 +3792,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.
      *
@@ -3827,6 +3834,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>>;
@@ -3882,14 +3893,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;
@@ -3925,19 +3936,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>;
@@ -3964,7 +3976,7 @@ export declare type SessionRecoveryKey = PersistedImportSessionKey;
 
 export declare type SessionRecoveryOptions = LocalSessionRecoveryOptions | CustomSessionRecoveryOptions;
 
-declare type StateChangeListener = (state: ImporterState) => void;
+declare type StatusChangeListener = (status: ImporterStatus) => void;
 
 declare type StripBrand<T> = {
     [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
@@ -4038,6 +4050,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
  */