@expresscsv/sdk 0.1.1 → 0.1.3

package/dist/.dts/errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Error thrown when the user cancels the import operation
+ */
+export declare class ImportCancelledError extends Error {
+    constructor(message?: string);
+}

package/dist/.dts/index.d.ts

@@ -0,0 +1,207 @@
+import { type ExRow, type ExRowShape, type ExType, type Infer, x } from '@expresscsv/fields';
+import { WidgetMode, WidgetState } from '@expresscsv/iframe-comm';
+import type { ExBaseDef } from '@expresscsv/fields';
+import type { ColorModeConfig, ECSVFontSource, ECSVTheme } from '@expresscsv/theme';
+export { ImportCancelledError } from './errors';
+/**
+ * A chunk of records passed to the onData callback
+ */
+export interface RecordsChunk<T> {
+    /** The records in this chunk */
+    records: T[];
+    /** Total number of chunks */
+    totalChunks: number;
+    /** Current chunk index (0-based) */
+    currentChunkIndex: number;
+    /** Total number of records across all chunks */
+    totalRecords: number;
+}
+/**
+ * Webhook configuration for remote delivery of results
+ */
+export 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>;
+}
+/**
+ * Type helper that requires at least one of the specified keys to be present
+ */
+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];
+/**
+ * Base delivery options - at least one must be provided
+ */
+interface DeliveryOptionsBase<T> {
+    /** Local callback for processing chunks */
+    onData?: (chunk: RecordsChunk<T>, next: () => void) => void | Promise<void>;
+    /** Webhook configuration for remote delivery */
+    webhook?: WebhookConfig;
+}
+/**
+ * Delivery options - requires at least one of onData or webhook
+ */
+export type DeliveryOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'>;
+/**
+ * Options for the open() method
+ * Requires at least one of onData or webhook for delivery
+ */
+export type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, 'onData' | 'webhook'> & {
+    /** Number of records per chunk (default: 1000) */
+    chunkSize?: number;
+    /** Called when all chunks have been processed */
+    onComplete?: () => void;
+    /** Called when the user cancels the import */
+    onCancel?: () => void;
+    /** Called when an error occurs */
+    onError?: (error: Error) => void;
+    /** Called when the widget opens */
+    onWidgetOpen?: () => 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;
+};
+export type InferCSVImporter<TSchema extends ExType<unknown, ExBaseDef, unknown>> = CSVImporter<TSchema>;
+export type { ColorModeConfig, ColorModePref, ECSVFontSource, ECSVTheme, TailwindThemeVars, } from '@expresscsv/theme';
+export interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
+    schema: TSchema;
+    publishableKey: string;
+    importIdentifier: string;
+    title?: string;
+    debug?: boolean;
+    developerMode?: boolean;
+    preload?: boolean;
+    theme?: ECSVTheme;
+    colorMode?: ColorModeConfig;
+    customCSS?: string;
+    fonts?: Record<string, ECSVFontSource>;
+    stepDisplay?: 'progressBar' | 'segmented' | 'numbered';
+    previewSchemaBeforeUpload?: boolean;
+    templateDownload?: TemplateDownloadConfig;
+    saveSession?: boolean;
+    locale?: DeepPartial<ExpressCSVLocaleInput>;
+}
+declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unknown> = ExRow<ExRowShape>> {
+    private options;
+    private iframe;
+    private container;
+    private connection;
+    private connectionState;
+    private debug;
+    private developerMode;
+    private importIdentifier;
+    private sessionId;
+    private _destroyTimer;
+    private _beforeUnloadHandler;
+    private widgetUrl;
+    private widgetState;
+    private widgetMode;
+    private canRestart;
+    private lastError;
+    private openOptions;
+    private cachedSchemaJson;
+    private initCompletePromise;
+    private resolveInitComplete;
+    constructor(options: SDKOptions<TSchema>);
+    /**
+     * Enhanced state management
+     */
+    private setState;
+    private updateDerivedState;
+    private handleError;
+    private waitForEvent;
+    /**
+     * Open the import flow with chunk-based data processing.
+     * Automatically opens the widget if not already open.
+     *
+     * @param options Configuration including onData callback for processing chunks
+     */
+    open(options: OpenOptions<Infer<TSchema>>): void;
+    /**
+     * Create import session on backend with configuration
+     * Idempotent: safe to call multiple times with same sessionId
+     */
+    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
+     */
+    private processResultsInChunks;
+    /**
+     * Initialize the iframe and connection.
+     * @param hidden Whether to create the iframe hidden (for preload) or visible (for normal open)
+     */
+    private initializeIframe;
+    private log;
+    private error;
+    /**
+     * Add beforeunload event listener to warn users about losing progress
+     */
+    private addBeforeUnloadListener;
+    /**
+     * Remove beforeunload event listener
+     */
+    private removeBeforeUnloadListener;
+    private waitForIframeLoad;
+    private setupConnectionAndInit;
+    openWidget(options?: {
+        reset?: boolean;
+    }): Promise<void>;
+    /**
+     * Makes a hidden container visible for instant display of preloaded iframe
+     */
+    private makeContainerVisible;
+    private setupMessageHandlers;
+    private createAndAppendIframe;
+    private destroy;
+    close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>;
+    resetWidget(): Promise<void>;
+    restart(newOptions?: Partial<SDKOptions<TSchema>>): Promise<void>;
+    private handleWidgetClosed;
+    private hideContainer;
+    getConnectionStatus(): boolean;
+    getState(): WidgetState;
+    getMode(): WidgetMode;
+    getIsReady(): boolean;
+    getIsOpen(): boolean;
+    getCanRestart(): boolean;
+    getLastError(): Error | null;
+    getStatus(): {
+        state: WidgetState;
+        mode: WidgetMode;
+        isReady: boolean;
+        isOpen: boolean;
+        canRestart: boolean;
+        hasError: boolean;
+        lastError: Error | null;
+        connectionStatus: boolean;
+    };
+    getVersion(): string;
+}
+export { x };
+export type { Infer, ExType } from '@expresscsv/fields';
+export type { ExBaseDef } from '@expresscsv/fields';
+export type { ExpressCSVStep } from '@expresscsv/core';
+export type { ExpressCSVLocaleInput, DeepPartial } from '@expresscsv/core';
+export { WidgetState, WidgetMode } from '@expresscsv/iframe-comm';
+import type { DeepPartial, ExpressCSVLocaleInput, ExpressCSVStep, TemplateDownloadConfig } from '@expresscsv/core';
+export { CSVImporter };