@expresscsv/sdk 0.1.26 → 1.0.0

package/dist/index.d.mts

@@ -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
  */