@expresscsv/sdk 0.1.21 → 0.1.23

package/dist/index.d.mts

@@ -1244,31 +1244,57 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private debug;
     private importIdentifier;
     private sessionId;
+    private currentSessionToken;
+    private currentSessionTokenExpiresAt;
+    private sessionTokenRefreshTimer;
+    private sessionTokenRefreshPromise;
     private _destroyTimer;
     private _beforeUnloadHandler;
-    private widgetUrl;
+    private importerUrl;
     private appUrl;
-    private widgetState;
-    private widgetMode;
+    private importerState;
+    private importerMode;
     private canRestart;
     private lastError;
+    private stateChangeListeners;
+    private lastTerminalSessionState;
     private openOptions;
     private cachedSchemaJson;
     private initCompletePromise;
     private resolveInitComplete;
     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;
+    private fetchImporterSessionToken;
+    private updateSessionToken;
+    private clearSessionTokenRefreshTimer;
+    private scheduleSessionTokenRefresh;
+    private ensureActiveSessionToken;
+    private refreshSessionBoundToken;
+    private beginImporterStartup;
+    private cancelImporterStartup;
+    private assertActiveImporterStartup;
+    private withTimeout;
+    private sendSessionDetailsToImporter;
+    private sendStartupErrorToImporter;
+    private bootstrapImporterSession;
     /**
      * Open the import flow with chunk-based data processing.
-     * Automatically opens the widget if not already open.
+     * Automatically opens the importer if not already open.
      *
      * @param options Configuration including onData callback for processing chunks
      */
@@ -1279,21 +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;
-    /**
-     * Poll the delivery status endpoint until the delivery reaches a terminal state
-     * ('success' or 'failed'), or until the timeout is exceeded.
-     */
-    private pollDeliveryStatus;
-    /**
-     * 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;
     /**
@@ -1313,7 +1325,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private removeBeforeUnloadListener;
     private waitForIframeLoad;
     private setupConnectionAndInit;
-    openWidget(options?: {
+    openImporter(options?: {
         reset?: boolean;
     }): Promise<void>;
     /**
@@ -1324,20 +1336,21 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private createAndAppendIframe;
     private destroy;
     close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>;
-    private resetWidget;
+    private resetImporter;
     restart(newOptions?: Partial<SDKOptions<TSchema>>): Promise<void>;
-    private handleWidgetClosed;
+    private handleImporterClosed;
     private hideContainer;
     getConnectionStatus(): boolean;
-    getState(): WidgetState;
-    getMode(): WidgetMode;
+    subscribeToStateChanges(listener: StateChangeListener): () => void;
+    getState(): ImporterState;
+    getMode(): ImporterMode;
     getIsReady(): boolean;
     getIsOpen(): boolean;
     getCanRestart(): boolean;
     getLastError(): Error | null;
     getStatus(): {
-        state: WidgetState;
-        mode: WidgetMode;
+        state: ImporterState;
+        mode: ImporterMode;
         isReady: boolean;
         isOpen: boolean;
         canRestart: boolean;
@@ -1345,7 +1358,6 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
         lastError: Error | null;
         connectionStatus: boolean;
     };
-    getVersion(): string;
 }
 
 /**
@@ -1991,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;
 }
@@ -1999,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>;
 }
 
 /**
@@ -2867,7 +2876,7 @@ declare interface ExpressCSVLocale {
         nextDisabledReviewValidating: string;
         nextDisabledReviewInvalid: string;
     };
-    widget: {
+    importer: {
         title: string;
         loading: string;
         closeConfirmTitle: string;
@@ -2876,7 +2885,6 @@ declare interface ExpressCSVLocale {
         closeConfirmContinue: string;
         errorTitle: string;
         startOver: string;
-        invalidPublishableKey: string;
     };
     sessionRecovery: {
         message: string;
@@ -3589,12 +3597,44 @@ export declare class ImportCancelledError extends Error {
     constructor(message?: string);
 }
 
+/**
+ * Importer preload mode
+ */
+export declare enum ImporterMode {
+    NORMAL = "normal",
+    PRELOAD = "preload"
+}
+
+/**
+ * Importer lifecycle state
+ */
+export declare enum ImporterState {
+    UNINITIALIZED = "uninitialized",
+    INITIALIZING = "initializing",
+    READY = "ready",
+    OPENING = "opening",
+    OPEN = "open",
+    CLOSING = "closing",
+    RESETTING = "resetting",
+    ERROR = "error",
+    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;
@@ -3602,23 +3642,34 @@ 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;
-    /** Called when the widget opens */
-    onWidgetOpen?: () => void;
+    onError?: (error: Error, context: ImportSessionContext) => 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;
-    /** Called when the widget closes */
-    onWidgetClose?: (reason: 'user_close' | 'cancel' | 'complete' | 'error') => 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';
@@ -3727,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 = {
@@ -3758,16 +3813,9 @@ 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;
-    publishableKey: string;
+    getSessionToken: () => Promise<string>;
     importIdentifier: string;
     title?: string;
     debug?: boolean;
@@ -3778,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;
 }
@@ -3796,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];
 };
@@ -3860,7 +3920,7 @@ export declare type TemplateDownloadOptions<TSchema extends ExType<unknown, ExBa
 
 /**
  * A branded string type for locale entries that require interpolation via `{variable}` syntax.
- * Widget code cannot render a `TemplateString` directly in JSX — it must go through the `t()` function.
+ * Importer code cannot render a `TemplateString` directly in JSX — it must go through the `t()` function.
  * The generic `TVars` encodes the expected variable names so `t()` enforces the correct vars argument.
  */
 declare type TemplateString<TVars extends string = string> = string & {
@@ -3892,54 +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;
-}
-
-/**
- * Widget mode enumeration
- */
-export declare enum WidgetMode {
-    NORMAL = "normal",
-    PRELOAD = "preload"
-}
-
-/**
- * Widget state enumeration for consistent state management
- */
-export declare enum WidgetState {
-    UNINITIALIZED = "uninitialized",
-    INITIALIZING = "initializing",
-    READY = "ready",
-    OPENING = "opening",
-    OPEN = "open",
-    CLOSING = "closing",
-    RESETTING = "resetting",
-    ERROR = "error",
-    DESTROYED = "destroyed"
-}
-
 export declare const x: {
     string: typeof ExString.create;
     number: typeof ExNumber.create;