@expresscsv/sdk 0.1.22 → 0.1.24

package/dist/index.d.mts

@@ -1256,6 +1256,8 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private importerMode;
     private canRestart;
     private lastError;
+    private stateChangeListeners;
+    private lastTerminalSessionState;
     private openOptions;
     private cachedSchemaJson;
     private initCompletePromise;
@@ -1263,11 +1265,17 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private resolvedTemplateDownload;
     private importerStartupGeneration;
     constructor(options: SDKOptions<TSchema>);
+    private getCustomStorageRpcHandler;
     /**
      * Enhanced state management
      */
     private setState;
     private updateDerivedState;
+    private createSessionId;
+    private getOrCreateSessionId;
+    private getImportSessionContext;
+    private getChunkIdempotencyKey;
+    private createRecordsChunk;
     private handleError;
     private sendImportProgress;
     private waitForEvent;
@@ -1297,16 +1305,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      */
     private createImportSession;
     /**
-     * Deliver results to webhook endpoint via backend API
-     * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
-     */
-    private deliverToWebhook;
-    /**
-     * Send a single chunk to backend webhook API with retry logic
-     */
-    private sendChunkToBackend;
-    /**
-     * Process results in chunks, calling onData and/or webhook for each chunk with backpressure control
+     * Process results in chunks, calling onData with backpressure control
      */
     private processResultsInChunks;
     /**
@@ -1342,6 +1341,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private handleImporterClosed;
     private hideContainer;
     getConnectionStatus(): boolean;
+    subscribeToStateChanges(listener: StateChangeListener): () => void;
     getState(): ImporterState;
     getMode(): ImporterMode;
     getIsReady(): boolean;
@@ -1358,7 +1358,6 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
         lastError: Error | null;
         connectionStatus: boolean;
     };
-    getVersion(): string;
 }
 
 /**
@@ -2004,6 +2003,13 @@ declare const CurrencyCodes: readonly [{
     readonly numeric: "932";
 }];
 
+export declare type CustomStorageOptions = {
+    type: 'custom';
+    get: (key: StorageKey) => Promise<StoredSession | null>;
+    set: (key: StorageKey, value: StoredSession) => Promise<void>;
+    remove: (key: StorageKey) => Promise<void>;
+};
+
 declare interface DatetimeOptions {
     message?: string;
 }
@@ -2012,19 +2018,9 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-/**
- * Delivery options - requires at least one of onData or webhook
- */
-export declare type DeliveryOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'>;
-
-/**
- * Base delivery options - at least one must be provided
- */
-declare interface DeliveryOptionsBase<T> {
-    /** Local callback for processing chunks */
-    onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-    /** Webhook configuration for remote delivery */
-    webhook?: WebhookConfig;
+export declare interface DeliveryOptions<T> {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
 }
 
 /**
@@ -3624,12 +3620,21 @@ export declare enum ImporterState {
     DESTROYED = "destroyed"
 }
 
+export declare interface ImportSessionContext {
+    /** Generated session ID for the current import run */
+    sessionId: string;
+}
+
 export declare type Infer<T extends ExType<unknown, ExBaseDef, unknown>> = T extends ExType<infer Output, ExBaseDef, unknown> ? Output : never;
 
 export declare type InferCSVImporter<TSchema extends ExType<unknown, ExBaseDef, unknown>> = CSVImporter<TSchema>;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3637,17 +3642,17 @@ declare interface MultiselectOptions {
 
 /**
  * Options for the open() method
- * Requires at least one of onData or webhook for delivery
+ * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'> & {
+export declare type OpenOptions<T> = DeliveryOptions<T> & {
     /** Number of records per chunk (default: 1000) */
     chunkSize?: number;
     /** Called when all chunks have been processed */
-    onComplete?: () => void;
+    onComplete?: (context: ImportSessionContext) => void;
     /** Called when the user cancels the import */
-    onCancel?: () => void;
+    onCancel?: (context: ImportSessionContext) => void;
     /** Called when an error occurs */
-    onError?: (error: Error) => void;
+    onError?: (error: Error, context: ImportSessionContext) => void;
     /** Called when the importer opens */
     onImporterOpen?: () => void;
     /** Called when the importer closes */
@@ -3656,6 +3661,17 @@ export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, '
     onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
 };
 
+declare interface PersistedImportSessionData {
+    data: PersistedImportSessionPayload;
+}
+
+declare type PersistedImportSessionKey = string;
+
+declare type PersistedImportSessionPayload = {
+    rowData: Record<string, unknown>[];
+    columnKeys: string[];
+};
+
 declare type PhoneNumberFormat = 'international' | 'national' | 'both';
 
 declare type PhoneNumberOutput = 'e164' | 'formatted' | 'digits';
@@ -3762,6 +3778,10 @@ export declare interface RecordsChunk<T> {
     currentChunkIndex: number;
     /** Total number of records across all chunks */
     totalRecords: number;
+    /** Generated session ID for the current import run */
+    sessionId: string;
+    /** Stable per-chunk idempotency key */
+    chunkIdempotencyKey: string;
 }
 
 declare type RefineBatchResultItem = {
@@ -3793,13 +3813,6 @@ declare type RefineResultItem = {
     };
 };
 
-/**
- * Type helper that requires at least one of the specified keys to be present
- */
-declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
-    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
-}[Keys];
-
 export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
     schema: TSchema;
     getSessionToken: () => Promise<string>;
@@ -3813,8 +3826,10 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
+    aiColumnMatching?: boolean;
+    aiTransform?: boolean;
     templateDownload?: TemplateDownloadOptions<TSchema>;
-    saveSession?: boolean;
+    storage?: StorageOptions;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
 }
@@ -3831,6 +3846,16 @@ 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 StoredSession = PersistedImportSessionData;
+
+export declare type StoredSessionData = PersistedImportSessionPayload;
+
 declare type StripBrand<T> = {
     [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
 };
@@ -3927,31 +3952,6 @@ declare interface ValidatorCheck {
     message?: string;
 }
 
-/**
- * Webhook configuration for remote delivery of results
- */
-export declare interface WebhookConfig {
-    /** The URL to send webhook requests to */
-    url: string;
-    /** Optional HTTP headers to include in the request */
-    headers?: Record<string, string>;
-    /** HTTP method to use (default: 'POST') */
-    method?: 'POST' | 'PUT' | 'PATCH';
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Number of retry attempts on failure (default: 0) */
-    retries?: number;
-    /** Arbitrary developer-provided metadata */
-    metadata?: Record<string, unknown>;
-    /**
-     * Whether to wait for the delivery service to confirm the webhook was
-     * successfully received before considering the import complete.
-     * When false, the import completes as soon as all chunks are queued.
-     * Default: false
-     */
-    awaitWebhookArrival?: boolean;
-}
-
 export declare const x: {
     string: typeof ExString.create;
     number: typeof ExNumber.create;

package/dist/index.d.ts

@@ -1256,6 +1256,8 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private importerMode;
     private canRestart;
     private lastError;
+    private stateChangeListeners;
+    private lastTerminalSessionState;
     private openOptions;
     private cachedSchemaJson;
     private initCompletePromise;
@@ -1263,11 +1265,17 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private resolvedTemplateDownload;
     private importerStartupGeneration;
     constructor(options: SDKOptions<TSchema>);
+    private getCustomStorageRpcHandler;
     /**
      * Enhanced state management
      */
     private setState;
     private updateDerivedState;
+    private createSessionId;
+    private getOrCreateSessionId;
+    private getImportSessionContext;
+    private getChunkIdempotencyKey;
+    private createRecordsChunk;
     private handleError;
     private sendImportProgress;
     private waitForEvent;
@@ -1297,16 +1305,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      */
     private createImportSession;
     /**
-     * Deliver results to webhook endpoint via backend API
-     * Chunks data using SDK-determined chunk size (independent of customer's chunkSize)
-     */
-    private deliverToWebhook;
-    /**
-     * Send a single chunk to backend webhook API with retry logic
-     */
-    private sendChunkToBackend;
-    /**
-     * Process results in chunks, calling onData and/or webhook for each chunk with backpressure control
+     * Process results in chunks, calling onData with backpressure control
      */
     private processResultsInChunks;
     /**
@@ -1342,6 +1341,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private handleImporterClosed;
     private hideContainer;
     getConnectionStatus(): boolean;
+    subscribeToStateChanges(listener: StateChangeListener): () => void;
     getState(): ImporterState;
     getMode(): ImporterMode;
     getIsReady(): boolean;
@@ -1358,7 +1358,6 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
         lastError: Error | null;
         connectionStatus: boolean;
     };
-    getVersion(): string;
 }
 
 /**
@@ -2004,6 +2003,13 @@ declare const CurrencyCodes: readonly [{
     readonly numeric: "932";
 }];
 
+export declare type CustomStorageOptions = {
+    type: 'custom';
+    get: (key: StorageKey) => Promise<StoredSession | null>;
+    set: (key: StorageKey, value: StoredSession) => Promise<void>;
+    remove: (key: StorageKey) => Promise<void>;
+};
+
 declare interface DatetimeOptions {
     message?: string;
 }
@@ -2012,19 +2018,9 @@ export declare type DeepPartial<T> = {
     [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
 };
 
-/**
- * Delivery options - requires at least one of onData or webhook
- */
-export declare type DeliveryOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'>;
-
-/**
- * Base delivery options - at least one must be provided
- */
-declare interface DeliveryOptionsBase<T> {
-    /** Local callback for processing chunks */
-    onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
-    /** Webhook configuration for remote delivery */
-    webhook?: WebhookConfig;
+export declare interface DeliveryOptions<T> {
+    /** Callback for processing delivered chunks */
+    onData: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
 }
 
 /**
@@ -3624,12 +3620,21 @@ export declare enum ImporterState {
     DESTROYED = "destroyed"
 }
 
+export declare interface ImportSessionContext {
+    /** Generated session ID for the current import run */
+    sessionId: string;
+}
+
 export declare type Infer<T extends ExType<unknown, ExBaseDef, unknown>> = T extends ExType<infer Output, ExBaseDef, unknown> ? Output : never;
 
 export declare type InferCSVImporter<TSchema extends ExType<unknown, ExBaseDef, unknown>> = CSVImporter<TSchema>;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3637,17 +3642,17 @@ declare interface MultiselectOptions {
 
 /**
  * Options for the open() method
- * Requires at least one of onData or webhook for delivery
+ * Requires an onData callback for delivery
  */
-export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'> & {
+export declare type OpenOptions<T> = DeliveryOptions<T> & {
     /** Number of records per chunk (default: 1000) */
     chunkSize?: number;
     /** Called when all chunks have been processed */
-    onComplete?: () => void;
+    onComplete?: (context: ImportSessionContext) => void;
     /** Called when the user cancels the import */
-    onCancel?: () => void;
+    onCancel?: (context: ImportSessionContext) => void;
     /** Called when an error occurs */
-    onError?: (error: Error) => void;
+    onError?: (error: Error, context: ImportSessionContext) => void;
     /** Called when the importer opens */
     onImporterOpen?: () => void;
     /** Called when the importer closes */
@@ -3656,6 +3661,17 @@ export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, '
     onStepChange?: (stepId: ExpressCSVStep, previousStepId?: ExpressCSVStep) => void;
 };
 
+declare interface PersistedImportSessionData {
+    data: PersistedImportSessionPayload;
+}
+
+declare type PersistedImportSessionKey = string;
+
+declare type PersistedImportSessionPayload = {
+    rowData: Record<string, unknown>[];
+    columnKeys: string[];
+};
+
 declare type PhoneNumberFormat = 'international' | 'national' | 'both';
 
 declare type PhoneNumberOutput = 'e164' | 'formatted' | 'digits';
@@ -3762,6 +3778,10 @@ export declare interface RecordsChunk<T> {
     currentChunkIndex: number;
     /** Total number of records across all chunks */
     totalRecords: number;
+    /** Generated session ID for the current import run */
+    sessionId: string;
+    /** Stable per-chunk idempotency key */
+    chunkIdempotencyKey: string;
 }
 
 declare type RefineBatchResultItem = {
@@ -3793,13 +3813,6 @@ declare type RefineResultItem = {
     };
 };
 
-/**
- * Type helper that requires at least one of the specified keys to be present
- */
-declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
-    [K in Keys]-?: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
-}[Keys];
-
 export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
     schema: TSchema;
     getSessionToken: () => Promise<string>;
@@ -3813,8 +3826,10 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
     previewSchemaBeforeUpload?: boolean;
+    aiColumnMatching?: boolean;
+    aiTransform?: boolean;
     templateDownload?: TemplateDownloadOptions<TSchema>;
-    saveSession?: boolean;
+    storage?: StorageOptions;
     locale?: DeepPartial<ExpressCSVLocaleInput>;
     disableStatusStep?: boolean;
 }
@@ -3831,6 +3846,16 @@ 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 StoredSession = PersistedImportSessionData;
+
+export declare type StoredSessionData = PersistedImportSessionPayload;
+
 declare type StripBrand<T> = {
     [K in keyof T]: T[K] extends TemplateString<string> ? string : T[K] extends object ? StripBrand<T[K]> : T[K];
 };
@@ -3927,31 +3952,6 @@ declare interface ValidatorCheck {
     message?: string;
 }
 
-/**
- * Webhook configuration for remote delivery of results
- */
-export declare interface WebhookConfig {
-    /** The URL to send webhook requests to */
-    url: string;
-    /** Optional HTTP headers to include in the request */
-    headers?: Record<string, string>;
-    /** HTTP method to use (default: 'POST') */
-    method?: 'POST' | 'PUT' | 'PATCH';
-    /** Request timeout in milliseconds (default: 30000) */
-    timeout?: number;
-    /** Number of retry attempts on failure (default: 0) */
-    retries?: number;
-    /** Arbitrary developer-provided metadata */
-    metadata?: Record<string, unknown>;
-    /**
-     * Whether to wait for the delivery service to confirm the webhook was
-     * successfully received before considering the import complete.
-     * When false, the import completes as soon as all chunks are queued.
-     * Default: false
-     */
-    awaitWebhookArrival?: boolean;
-}
-
 export declare const x: {
     string: typeof ExString.create;
     number: typeof ExNumber.create;