@expresscsv/sdk 0.1.25 → 1.0.0

package/dist/index.d.ts

@@ -4,11 +4,60 @@ 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
  */
 export declare type ColorModePref = 'light' | 'dark' | 'system';
 
+export declare interface ColumnMatch<TTargetField extends string = string> {
+    sourceColumnIndex: number;
+    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>;
+
+export declare interface ColumnMatchingParams {
+    sessionId: string;
+    sourceColumns: ColumnMatchingSourceColumn[];
+    targetFields: ColumnMatchingTargetField[];
+}
+
+export declare interface ColumnMatchingResult<TTargetField extends string = string> {
+    matches: Array<ColumnMatch<TTargetField>>;
+}
+
+export declare interface ColumnMatchingSourceColumn {
+    sourceColumnIndex: number;
+    name: string;
+    sampleValues: string[];
+}
+
+export declare interface ColumnMatchingTargetField {
+    name: string;
+    label?: string;
+    type: string;
+    description?: string;
+    aliases: string[];
+}
+
 declare const Countries: readonly [{
     readonly name: "Afghanistan";
     readonly alpha2: "AF";
@@ -1242,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;
@@ -1252,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;
@@ -1266,17 +1317,24 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private importerStartupGeneration;
     constructor(options: SDKOptions<TSchema>);
     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;
@@ -1293,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
@@ -1308,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)
@@ -1335,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;
@@ -2003,11 +2062,21 @@ declare const CurrencyCodes: readonly [{
     readonly numeric: "932";
 }];
 
-export declare type CustomStorageOptions = {
+export declare type CustomColumnMatchingOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
     type: 'custom';
-    get: (key: StorageKey) => Promise<StoredSession | null>;
-    set: (key: StorageKey, value: StoredSession) => Promise<void>;
-    remove: (key: StorageKey) => Promise<void>;
+    columnMatchHandler: ColumnMatchHandler<TSchema>;
+};
+
+export declare type CustomPromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = {
+    type: 'custom';
+    promptedEditHandler: PromptedEditHandler<TSchema>;
+};
+
+export declare type CustomSessionRecoveryOptions = {
+    type: 'custom';
+    get: (key: SessionRecoveryKey) => Promise<RecoveredSession | null>;
+    set: (key: SessionRecoveryKey, value: RecoveredSession) => Promise<void>;
+    remove: (key: SessionRecoveryKey) => Promise<void>;
 };
 
 declare interface DatetimeOptions {
@@ -2018,44 +2087,6 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-export declare interface DeliveryOptions<T> {
-    /** Callback for processing delivered chunks */
-    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-}
-
-/**
- * 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;
 }
@@ -2950,6 +2981,8 @@ declare interface ExpressCSVLocale {
         showAll: string;
         moveUp: string;
         moveDown: string;
+        /** When the selected row has zero columns (cannot continue) */
+        rowNotSelectable: string;
     };
     matchColumns: {
         loading: string;
@@ -2984,6 +3017,8 @@ declare interface ExpressCSVLocale {
         previewTooltip: string;
         /** Available: {rowCount}, {columnName} */
         previewShowing: TemplateString<'rowCount' | 'columnName'>;
+        /** Available: {columnNumber} — 1-based index when the sheet header cell is empty */
+        unnamedSourceColumn: TemplateString<'columnNumber'>;
     };
     matchOptions: {
         loading: string;
@@ -3076,27 +3111,27 @@ declare interface ExpressCSVLocale {
         filteredColumns: string;
         unfilteredColumns: string;
         columnsLabel: string;
-        transformTooltip: string;
-        transformTitle: string;
-        transformClose: string;
-        transformCloseDiscardTooltip: string;
-        transformCloseTooltip: string;
-        transformError: string;
-        transformPlaceholder: string;
-        transformGenerating: string;
-        transformApplying: string;
-        transformDiscard: string;
-        transformApply: string;
-        transformUnappliedTitle: string;
-        transformUnappliedDescription: string;
-        transformKeepEditing: string;
-        transformDiscardClose: string;
-        transformAbortTitle: string;
-        transformAbortDescription: string;
-        transformAbortClose: string;
-        transformSubmit: string;
+        promptedEditsTooltip: string;
+        promptedEditsTitle: string;
+        promptedEditsClose: string;
+        promptedEditsCloseDiscardTooltip: string;
+        promptedEditsCloseTooltip: string;
+        promptedEditsError: string;
+        promptedEditsPlaceholder: string;
+        promptedEditsGenerating: string;
+        promptedEditsApplying: string;
+        promptedEditsDiscard: string;
+        promptedEditsApply: string;
+        promptedEditsUnappliedTitle: string;
+        promptedEditsUnappliedDescription: string;
+        promptedEditsKeepEditing: string;
+        promptedEditsDiscardClose: string;
+        promptedEditsAbortTitle: string;
+        promptedEditsAbortDescription: string;
+        promptedEditsAbortClose: string;
+        promptedEditsSubmit: string;
     };
-    phantomColumn: {
+    emptyColumn: {
         /** Available: {number} */
         defaultName: TemplateString<'number'>;
         remove: string;
@@ -3127,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<{
@@ -3587,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;
 }
@@ -3603,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
  */
@@ -3611,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",
@@ -3626,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;
 }
 
@@ -3637,10 +3697,22 @@ export declare type InferCSVImporter<TSchema extends ExType<unknown, ExBaseDef,
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
-export declare type LocalStorageOptions = {
+export declare type LocalSessionRecoveryOptions = {
     type: 'local';
 };
 
+export declare type ManagedColumnMatchingOptions = {
+    type: 'managed';
+    exact?: boolean;
+    caseInsensitive?: boolean;
+    normalized?: boolean;
+    inference?: boolean;
+};
+
+export declare type ManagedPromptedEditsOptions = {
+    type: 'managed';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3650,21 +3722,21 @@ declare interface MultiselectOptions {
  * Options for the open() method
  * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = DeliveryOptions<T> & {
-    /** Number of records per chunk (default: 1000) */
-    chunkSize?: number;
+export declare type OpenOptions<T> = {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
+    /** 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 {
@@ -3693,7 +3765,6 @@ declare interface PrimitiveExBaseDef extends ExBaseDef {
     columnNameAliases?: string[];
     description?: string;
     label?: string;
-    example?: string;
     message?: string;
     checks?: ValidatorCheck[];
     defaultValue?: unknown | (() => unknown);
@@ -3721,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.
      *
@@ -3770,6 +3834,55 @@ 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>>;
+} | {
+    type: 'update';
+    rowId: string;
+    values: Partial<Record<TField, unknown>>;
+} | {
+    type: 'remove';
+    rowId: string;
+};
+
+export declare interface PromptedEditsField<TField extends string = string> {
+    key: TField;
+    name: string;
+    type: string;
+    sampleValues: unknown[];
+}
+
+export declare type PromptedEditsFn<TField extends string = string> = (data: PromptedEditsParams<TField>) => Promise<PromptedEditsResult<TField>>;
+
+export declare type PromptedEditsOptions<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> = ManagedPromptedEditsOptions | CustomPromptedEditsOptions<TSchema>;
+
+export declare interface PromptedEditsParams<TField extends string = string> {
+    sessionId: string;
+    prompt: string;
+    fields: Array<PromptedEditsField<TField>>;
+    rows: Array<PromptedEditsRow<TField>>;
+    totalRows: number;
+}
+
+export declare type PromptedEditsResult<TField extends string = string> = {
+    type: 'success';
+    changes: Array<PromptedEditsChange<TField>>;
+} | {
+    type: 'no-op';
+    message: string;
+};
+
+export declare interface PromptedEditsRow<TField extends string = string> {
+    rowId: string;
+    rowIndex: number;
+    values: Partial<Record<TField, unknown>>;
+}
+
 declare type Protocol = 'http' | 'https' | 'ftp' | 'sftp' | 'file' | 'mailto' | 'tel';
 
 /**
@@ -3780,16 +3893,20 @@ 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;
+
+export declare type RecoveredSessionData = PersistedImportSessionPayload;
+
 declare type RefineBatchResultItem = {
     valid: boolean;
     message?: string;
@@ -3819,23 +3936,26 @@ declare type RefineResultItem = {
     };
 };
 
+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;
-    aiColumnMatching?: boolean;
-    aiTransform?: boolean;
+    columnMatching?: ColumnMatchingOptions<TSchema>;
+    promptedEdits?: PromptedEditsOptions<TSchema>;
     templateDownload?: TemplateDownloadOptions<TSchema>;
-    storage?: StorageOptions;
+    sessionRecovery?: SessionRecoveryOptions;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
 }
@@ -3852,15 +3972,11 @@ declare interface SelectOptions {
     message?: string;
 }
 
-declare type StateChangeListener = (state: ImporterState) => void;
-
-export declare type StorageKey = PersistedImportSessionKey;
-
-export declare type StorageOptions = LocalStorageOptions | CustomStorageOptions;
+export declare type SessionRecoveryKey = PersistedImportSessionKey;
 
-export declare type StoredSession = PersistedImportSessionData;
+export declare type SessionRecoveryOptions = LocalSessionRecoveryOptions | CustomSessionRecoveryOptions;
 
-export declare type StoredSessionData = PersistedImportSessionPayload;
+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];
@@ -3934,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
  */