@expresscsv/react 0.1.21 → 0.1.23

package/dist/index.d.cts

@@ -1878,6 +1878,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;
 }
@@ -1886,19 +1893,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>;
 }
 
 /**
@@ -2754,7 +2751,7 @@ declare interface ExpressCSVLocale {
         nextDisabledReviewValidating: string;
         nextDisabledReviewInvalid: string;
     };
-    widget: {
+    importer: {
         title: string;
         loading: string;
         closeConfirmTitle: string;
@@ -2763,7 +2760,6 @@ declare interface ExpressCSVLocale {
         closeConfirmContinue: string;
         errorTitle: string;
         startOver: string;
-        invalidPublishableKey: string;
     };
     sessionRecovery: {
         message: string;
@@ -3476,10 +3472,42 @@ 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;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3487,23 +3515,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';
@@ -3612,6 +3651,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 = {
@@ -3643,13 +3686,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];
-
 declare interface SelectOption<TValue extends string | number = string | number> {
     label: string;
     value: TValue;
@@ -3662,6 +3698,14 @@ declare interface SelectOptions {
     message?: string;
 }
 
+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];
 };
@@ -3726,7 +3770,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 & {
@@ -3750,9 +3794,9 @@ declare interface URLOptions {
     message?: string;
 }
 
-export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, publishableKey, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, templateDownload, saveSession, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
+export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, aiColumnMatching, aiTransform, templateDownload, storage, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
     open: (options: OpenOptions<Infer<TSchema>>) => void;
-    widgetState: WidgetState;
+    importerState: ImporterState;
     isInitialising: boolean;
     isOpen: boolean;
 };
@@ -3761,7 +3805,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     schema: TSchema;
     title?: string;
     importIdentifier: string;
-    publishableKey: string;
+    getSessionToken: () => Promise<string>;
     debug?: boolean;
     preload?: boolean;
     theme?: ECSVTheme;
@@ -3770,8 +3814,10 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     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;
 }
@@ -3784,54 +3830,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;

package/dist/index.d.mts

@@ -1878,6 +1878,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;
 }
@@ -1886,19 +1893,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>;
 }
 
 /**
@@ -2754,7 +2751,7 @@ declare interface ExpressCSVLocale {
         nextDisabledReviewValidating: string;
         nextDisabledReviewInvalid: string;
     };
-    widget: {
+    importer: {
         title: string;
         loading: string;
         closeConfirmTitle: string;
@@ -2763,7 +2760,6 @@ declare interface ExpressCSVLocale {
         closeConfirmContinue: string;
         errorTitle: string;
         startOver: string;
-        invalidPublishableKey: string;
     };
     sessionRecovery: {
         message: string;
@@ -3476,10 +3472,42 @@ 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;
 
 declare type IPAddressVersion = 'v4' | 'v6' | 'all';
 
+export declare type LocalStorageOptions = {
+    type: 'local';
+};
+
 declare interface MultiselectOptions {
     enforceCaseSensitiveMatch?: boolean;
     message?: string;
@@ -3487,23 +3515,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';
@@ -3612,6 +3651,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 = {
@@ -3643,13 +3686,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];
-
 declare interface SelectOption<TValue extends string | number = string | number> {
     label: string;
     value: TValue;
@@ -3662,6 +3698,14 @@ declare interface SelectOptions {
     message?: string;
 }
 
+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];
 };
@@ -3726,7 +3770,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 & {
@@ -3750,9 +3794,9 @@ declare interface URLOptions {
     message?: string;
 }
 
-export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, publishableKey, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, templateDownload, saveSession, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
+export declare function useExpressCSV<TSchema extends ExType<unknown, ExBaseDef, unknown>>({ schema, title, importIdentifier, getSessionToken, debug, preload, theme, colorMode, customCSS, fonts, stepDisplay, previewSchemaBeforeUpload, aiColumnMatching, aiTransform, templateDownload, storage, locale, disableStatusStep, }: UseExpressCSVOptions<TSchema>): {
     open: (options: OpenOptions<Infer<TSchema>>) => void;
-    widgetState: WidgetState;
+    importerState: ImporterState;
     isInitialising: boolean;
     isOpen: boolean;
 };
@@ -3761,7 +3805,7 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     schema: TSchema;
     title?: string;
     importIdentifier: string;
-    publishableKey: string;
+    getSessionToken: () => Promise<string>;
     debug?: boolean;
     preload?: boolean;
     theme?: ECSVTheme;
@@ -3770,8 +3814,10 @@ export declare interface UseExpressCSVOptions<TSchema extends ExType<unknown, Ex
     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;
 }
@@ -3784,54 +3830,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;