@expresscsv/sdk 0.1.4 → 0.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ExpressCSV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,9 @@
-# ExpressCSV Importer
+# @expresscsv/sdk
 
-A TypeScript SDK for integrating the ExpressCSV widget into your web application.
+[![npm version](https://img.shields.io/npm/v/@expresscsv/sdk.svg)](https://www.npmjs.com/package/@expresscsv/sdk)
+![license](https://img.shields.io/npm/l/@expresscsv/sdk.svg)
+
+A TypeScript SDK for embedding the [ExpressCSV](https://expresscsv.com) CSV import widget into any web application. Define a schema, open the widget, and receive validated, typed data in chunks.
 
 ## Installation
 
@@ -15,191 +18,475 @@ npm install @expresscsv/sdk
 yarn add @expresscsv/sdk
 ```
 
-## Usage
+> **Looking for React?** Use [`@expresscsv/react`](https://www.npmjs.com/package/@expresscsv/react) for a hook-based integration.
 
-### Basic Usage
+## Quick Start
 
 ```typescript
-import { CSVImporter } from "@expresscsv/sdk";
+import { CSVImporter, x } from "@expresscsv/sdk";
 
-// Initialize the importer
-const importer = new CSVImporter({
-  title: "CSV Import",
+const schema = x.row({
+  name: x.string().label("Full Name"),
+  email: x.string().email().label("Email Address"),
+  age: x.number().label("Age").min(18).max(120),
 });
 
-// Open the widget
-await importer.open();
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  title: "Import Users",
+});
 
-// Send a message to the widget
-await importer.sendMessage({
-  type: "example",
-  payload: {
-    /* your data */
+// Open the widget and process data in chunks
+importer.open({
+  onData: (chunk, next) => {
+    console.log(`Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
+    console.log("Records:", chunk.records);
+    // Process your validated, typed records here
+    next();
+  },
+  onComplete: () => {
+    console.log("All chunks processed successfully");
+  },
+  onError: (error) => {
+    console.error("Import failed:", error);
   },
 });
-
-// Clean up when done
-importer.close();
 ```
 
-### Field Schema Validation
+Your `publishableKey` is available from the [ExpressCSV dashboard](https://expresscsv.com). Two key types are available: **production** keys for live usage, and **dev/testing** keys that provide unlimited test imports.
+
+## Webhook Delivery
 
-ExpressCSV SDK provides a Zod-like schema validation system for CSV imports. This allows you to define the expected structure of your CSV data and receive type-safe results.
+Deliver imported data directly to your backend via webhook instead of (or in addition to) a local callback:
 
 ```typescript
-import { CSVImporter, x } from "@expresscsv/sdk";
+importer.open({
+  webhook: {
+    url: "https://api.example.com/webhooks/csv-import",
+    method: "POST",
+    headers: {
+      Authorization: "Bearer your-api-token",
+    },
+    metadata: {
+      source: "web-app",
+      userId: "user-123",
+    },
+  },
+  onComplete: () => {
+    console.log("Webhook delivery initiated");
+  },
+  onError: (error) => {
+    console.error("Delivery error:", error);
+  },
+});
+```
 
-// Define your schema
-const schema = x.row({
-  name: x.string().humanLabel("Full Name"),
-  email: x.email().humanLabel("Email Address"),
-  age: x.number().humanLabel("Age").min(18).max(100),
-  role: x.select(["admin", "user", "guest"]).humanLabel("User Role")
+### Combined Local Callback and Webhook
+
+You can use both `onData` and `webhook` simultaneously:
+
+```typescript
+importer.open({
+  chunkSize: 500,
+  onData: async (chunk, next) => {
+    await saveToLocalDatabase(chunk.records);
+    next();
+  },
+  webhook: {
+    url: "https://api.example.com/webhooks/csv-import",
+    headers: { Authorization: "Bearer your-api-token" },
+  },
+  onComplete: () => {
+    console.log("Local processing and webhook delivery complete");
+  },
 });
+```
+
+## Preloading
+
+By default, the SDK preloads the widget in a hidden iframe for instant display when `open()` is called. This provides the best user experience.
 
-// Initialize with schema and results handler
+```typescript
+// Preload is enabled by default
 const importer = new CSVImporter({
-  title: "User Import",
-  fields: schema,
-  onResults: (data) => {
-    // data is fully typed based on your schema
-    console.log(`Imported ${data.length} users`);
-    
-    // Access properties with full type safety
-    data.forEach(user => {
-      console.log(`Name: ${user.name}, Email: ${user.email}`);
-      if (user.age) {
-        console.log(`Age: ${user.age + 1}`); // Numbers are typed correctly
-      }
-    });
-  }
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
 });
 
-// Or set the handler separately
-importer.onResults = (data) => {
-  // Process the validated data
-  processUsers(data);
-};
+// Later, the widget appears instantly
+importer.open({ onData: (chunk, next) => { /* ... */ next(); } });
+```
+
+To disable preloading (there will be a brief loading screen instead):
 
-// Open the widget
-await importer.open();
+```typescript
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  preload: false,
+});
 ```
 
-### Preload for Instant Display
+## Theming and Styling
+
+Customize the widget's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
 
-By default, the SDK preloads the widget in the background for instant display when opened. This provides the best user experience with minimal perceived loading time.
+### Theme
+
+Use the `theme` option to override CSS variables (colors, radius, typography). Pass either a single theme (applies to both light and dark) or a dual-mode theme with separate light/dark values:
 
 ```typescript
-import { CSVImporter, x } from "@expresscsv/sdk";
+import { CSVImporter, x, type ECSVTheme } from "@expresscsv/sdk";
+
+// Single theme (both modes)
+const theme: ECSVTheme = {
+  primary: "#4F46E5",
+  "primary-foreground": "#ffffff",
+  background: "#ffffff",
+  foreground: "#0f172a",
+  border: "#e5e7eb",
+  ring: "#A5B4FC",
+  radius: "0.5rem",
+};
 
-const schema = x.row({
-  name: x.string().humanLabel("Full Name"),
-  email: x.email().humanLabel("Email Address"),
+// Dual-mode (light and dark)
+const dualTheme: ECSVTheme = {
+  modes: {
+    light: {
+      primary: "#4F46E5",
+      background: "#ffffff",
+      foreground: "#0f172a",
+    },
+    dark: {
+      primary: "#a5b4fc",
+      background: "#09090b",
+      foreground: "#fafafa",
+    },
+  },
+};
+
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  theme,
 });
+```
 
-// Preload is enabled by default - widget loads in background
+Theme variables:
+
+| Variable | Default |
+|---|---|
+| `radius` | `0.625rem` |
+| `background` | `oklch(1 0 0)` |
+| `foreground` | `oklch(0.145 0 0)` |
+| `card` | `oklch(1 0 0)` |
+| `card-foreground` | `oklch(0.145 0 0)` |
+| `popover` | `oklch(1 0 0)` |
+| `popover-foreground` | `oklch(0.145 0 0)` |
+| `primary` | `oklch(0.205 0 0)` |
+| `primary-foreground` | `oklch(0.985 0 0)` |
+| `secondary` | `oklch(0.97 0 0)` |
+| `secondary-foreground` | `oklch(0.205 0 0)` |
+| `muted` | `oklch(0.97 0 0)` |
+| `muted-foreground` | `oklch(0.556 0 0)` |
+| `accent` | `oklch(0.7 0.2 145)` |
+| `accent-foreground` | `oklch(0.985 0 0)` |
+| `destructive` | `oklch(0.577 0.245 27.325)` |
+| `destructive-foreground` | `oklch(0.985 0 0)` |
+| `success` | `oklch(0.7 0.2 145)` |
+| `success-foreground` | `oklch(0.985 0 0)` |
+| `warning` | `oklch(0.769 0.188 70)` |
+| `warning-foreground` | `oklch(0.985 0 0)` |
+| `border` | `oklch(0.922 0 0)` |
+| `input` | `oklch(0.922 0 0)` |
+| `ring` | `oklch(0.708 0 0)` |
+| `font-title` | `inherit` |
+| `font-body` | `inherit` |
+
+### Color Mode
+
+Control light/dark mode with `colorMode`:
+
+```typescript
 const importer = new CSVImporter({
   schema,
+  publishableKey: "your-publishable-key",
   importIdentifier: "user-import",
-  title: "User Import",
+  colorMode: "system", // 'light' | 'dark' | 'system'
 });
+```
+
+### Custom CSS
+
+Inject custom CSS for fine-grained styling overrides.
 
-// Later, when user clicks import button, widget displays instantly
-await importer.open();
+```typescript
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+  customCSS: `
+    .ecsv [data-step="upload"] {
+      border-radius: 1rem;
+    }
+    .ecsv button {
+      font-weight: 600;
+    }
+  `,
+});
 ```
 
-To disable preload (not recommended for most use cases):
+### Custom Fonts
+
+Load custom fonts via the `fonts` option:
 
 ```typescript
 const importer = new CSVImporter({
   schema,
+  publishableKey: "your-publishable-key",
   importIdentifier: "user-import",
-  title: "User Import",
-  preload: false, // Opt-out of preload
+  fonts: {
+    title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
+    body: { source: "custom", url: "https://example.com/font.woff2", format: "woff2" },
+  },
+  theme: {
+    "font-title": "'Space Grotesk', sans-serif",
+    "font-body": "'Custom Font', sans-serif",
+  },
+});
+```
+
+## Schema Builder
+
+The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
+
+### Field Types
+
+```typescript
+import { x } from "@expresscsv/sdk";
+
+const schema = x.row({
+  // Strings with validation
+  name: x.string().label("Full Name").min(2).max(100),
+  email: x.string().email().label("Email"),
+  website: x.string().url().label("Website").optional(),
+
+  // Numbers with constraints
+  age: x.number().label("Age").min(0).max(150).integer(),
+  salary: x.number().currency("USD").label("Salary").min(0),
+
+  // Boolean
+  isActive: x.boolean().label("Active"),
+
+  // Dates and times
+  startDate: x.date().label("Start Date"),
+  createdAt: x.datetime().label("Created At"),
+
+  // Single selection (requires { label, value } objects)
+  role: x.select([
+    { label: "Admin", value: "admin" },
+    { label: "Editor", value: "editor" },
+    { label: "Viewer", value: "viewer" },
+  ]).label("Role"),
+
+  // Multi-selection
+  tags: x.multiselect([
+    { label: "Engineering", value: "eng" },
+    { label: "Design", value: "design" },
+    { label: "Marketing", value: "mkt" },
+  ]).label("Tags"),
 });
 ```
 
+### Common Modifiers
+
+All field types support:
+
+| Modifier | Description |
+|---|---|
+| `.label(text)` | User-facing label shown in the widget |
+| `.description(text)` | Help text for the field |
+| `.example(text)` | Example value shown as placeholder |
+| `.optional()` | Makes the field optional (default is required) |
+| `.refine(fn)` | Custom validation function |
+
+### String Modifiers
+
+| Modifier | Description |
+|---|---|
+| `.email()` | Validates email format |
+| `.url()` | Validates URL format |
+| `.uuid()` | Validates UUID format |
+| `.ip()` | Validates IP address |
+| `.phone()` | Validates phone number |
+| `.regex(pattern)` | Matches a regular expression |
+| `.min(n)` | Minimum string length |
+| `.max(n)` | Maximum string length |
+| `.length(n)` | Exact string length |
+| `.includes(str)` | Must contain substring |
+| `.startsWith(str)` | Must start with prefix |
+| `.endsWith(str)` | Must end with suffix |
+
+### Number Modifiers
+
+| Modifier | Description |
+|---|---|
+| `.min(n)` | Minimum value |
+| `.max(n)` | Maximum value |
+| `.integer()` | Must be a whole number |
+| `.multipleOf(n)` | Must be a multiple of n |
+| `.currency(code)` | Formats as currency (e.g. `"USD"`) |
+| `.percentage()` | Formats as percentage |
+
 ## API Reference
 
-### Constructor Options
+### `CSVImporter`
 
-| Option           | Type                   | Required | Default | Description                                |
-|------------------|------------------------|----------|---------|--------------------------------------------|
-| schema           | ExType                 | Yes      | -       | Schema definition for CSV field validation |
-| importIdentifier | string                 | Yes      | -       | Unique identifier for this import          |
-| title            | string                 | No       | -       | Title to display in the widget             |
-| publishableKey  | string                 | Yes      | -       | Publishable key for webhook authentication |
-| debug            | boolean                | No       | false   | Enable debug logging                       |
-| developerMode    | boolean                | No       | false   | Enable developer mode features             |
-| preload          | boolean                | No       | true    | Preload widget in background for instant display. Set to `false` to disable |
+#### Constructor
 
-### Methods
+```typescript
+new CSVImporter(options: SDKOptions)
+```
 
-#### `open(): Promise<void>`
+| Option | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `schema` | Schema | Yes | - | Schema definition created with `x.row()` |
+| `publishableKey` | `string` | Yes | - | Your publishable key from the [dashboard](https://expresscsv.com) |
+| `importIdentifier` | `string` | Yes | - | Unique identifier for this import type |
+| `title` | `string` | No | - | Title shown in the widget header |
+| `preload` | `boolean` | No | `true` | Preload widget for instant display |
+| `debug` | `boolean` | No | `false` | Enable debug logging |
+| `developerMode` | `boolean` | No | `false` | Enable developer mode features |
+| `theme` | `ECSVTheme` | No | - | Custom theme configuration |
+| `colorMode` | `ColorModePref` | No | - | Light/dark mode (`'light'`, `'dark'`, or `'system'`) |
+| `customCSS` | `string` | No | - | Custom CSS to inject into the widget |
+| `fonts` | `Record<string, ECSVFontSource>` | No | - | Custom font sources |
+| `stepDisplay` | `'progressBar' \| 'segmented' \| 'numbered'` | No | `'progressBar'` | Step indicator style |
+| `previewSchemaBeforeUpload` | `boolean` | No | `true` | Show schema preview before upload |
+| `templateDownload` | `TemplateDownloadConfig` | No | - | Template download configuration |
+| `saveSession` | `boolean` | No | - | Persist session state |
+| `locale` | `DeepPartial<ExpressCSVLocaleInput>` | No | - | Localization overrides |
+
+#### `open(options)`
+
+Opens the widget and begins the import flow. At least one of `onData` or `webhook` must be provided.
 
-Opens the ExpressCSV widget as a modal and establishes communication using iframe-comm.
+```typescript
+importer.open(options: OpenOptions): void
+```
 
-#### `sendMessage(message: Message): Promise<void>`
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `onData` | `(chunk: RecordsChunk<T>, next: () => void) => void` | * | Callback for each chunk of records. Call `next()` to continue. |
+| `webhook` | `WebhookConfig` | * | Webhook endpoint for server-side delivery |
+| `chunkSize` | `number` | No | Records per chunk (default: 1000) |
+| `onComplete` | `() => void` | No | Called when all chunks have been processed |
+| `onCancel` | `() => void` | No | Called when the user cancels the import |
+| `onError` | `(error: Error) => void` | No | Called when an error occurs |
+| `onWidgetOpen` | `() => void` | No | Called when the widget opens |
+| `onWidgetClose` | `(reason: string) => void` | No | Called when the widget closes |
+| `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the wizard step changes |
 
-Sends a message to the ExpressCSV widget.
+\* At least one of `onData` or `webhook` is required.
 
-#### `close(): void`
+#### `close(reason?)`
 
 Closes the widget and cleans up resources.
 
-#### `getConnectionStatus(): boolean`
+```typescript
+await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>
+```
+
+#### Status Methods
 
-Returns whether the widget is currently connected.
 
-#### `getVersion(): string`
 
-Returns the current version of the SDK.
+| Method | Returns | Description |
+|---|---|---|
+| `getState()` | `WidgetState` | Current widget state |
+| `getIsReady()` | `boolean` | Whether the widget is ready or open |
+| `getIsOpen()` | `boolean` | Whether the widget is currently open |
+| `getConnectionStatus()` | `boolean` | Whether the iframe connection is active |
+| `getCanRestart()` | `boolean` | Whether the widget can be restarted |
+| `getLastError()` | `Error \| null` | Last error, if any |
+| `getStatus()` | `object` | Comprehensive status snapshot |
+| `getVersion()` | `string` | SDK version |
 
-### Event Handlers
+#### `restart(newOptions?)`
 
-| Handler      | Type                 | Description                                    |
-|--------------|----------------------|------------------------------------------------|
-| onConnected  | () => void           | Called when connection is established          |
-| onError      | (error: Error) => void | Called when an error occurs                  |
-| onClose      | () => void           | Called when the widget is closed               |
-| onResults    | (data: T[]) => void  | Called with schema-validated CSV data          |
+Restarts the widget, optionally with updated options. Returns `Promise<void>`.
 
-### Schema Builder API
+### `RecordsChunk<T>`
 
-The SDK exports a Zod-like API for defining field validation schemas:
+The object passed to `onData` callbacks:
 
-#### Field Types
+```typescript
+interface RecordsChunk<T> {
+  records: T[]; // Automatically typed to your schema
+  totalChunks: number;
+  currentChunkIndex: number;
+  totalRecords: number;
+}
+```
 
-- `x.string()` - String fields
-- `x.number()` - Number fields
-- `x.email()` - Email fields
-- `x.select(['option1', 'option2'])` - Dropdown selection fields
+### `WebhookConfig`
 
-#### Field Modifiers
+```typescript
+interface WebhookConfig {
+  url: string;
+  headers?: Record<string, string>;
+  method?: "POST" | "PUT" | "PATCH";
+  timeout?: number;
+  retries?: number;
+  metadata?: Record<string, unknown>;
+}
+```
 
-- `.humanLabel(string)` - Sets a user-friendly label for the field
-- `.required(boolean)` - Marks a field as required
-- `.minLength(number)` - Sets minimum length for string fields
-- `.maxLength(number)` - Sets maximum length for string fields
-- `.min(number)` - Sets minimum value for number fields
-- `.max(number)` - Sets maximum value for number fields
+## TypeScript
 
-## Development
+The SDK is written in TypeScript and provides full type inference from your schema:
 
-```bash
-# Install dependencies
-pnpm install
+```typescript
+import { CSVImporter, x, type Infer } from "@expresscsv/sdk";
+
+const schema = x.row({
+  name: x.string(),
+  age: x.number(),
+  email: x.string().email().optional(),
+});
 
-# Start development mode
-pnpm dev
+type Row = Infer<typeof schema>;
+// { name: string; age: number; email?: string }
 
-# Build the package
-pnpm build
+const importer = new CSVImporter({
+  schema,
+  publishableKey: "your-publishable-key",
+  importIdentifier: "user-import",
+});
 
-# Run linting
-pnpm lint
+importer.open({
+  onData: (chunk, next) => {
+    // chunk.records is fully typed as Row[]
+    for (const row of chunk.records) {
+      console.log(row.name);  // string
+      console.log(row.age);   // number
+      console.log(row.email); // string | undefined
+    }
+    next();
+  },
+});
 ```
 
+## Resources
+
+- [ExpressCSV Dashboard](https://expresscsv.com) -- manage your imports and API keys
+- [`@expresscsv/react`](https://www.npmjs.com/package/@expresscsv/react) -- React hook wrapper
+
 ## License
 
-ISC
+[MIT](./LICENSE)

package/dist/index.d.mts

@@ -4,15 +4,6 @@ declare interface BICOptions {
 
 declare type BooleanControlType = 'toggle' | 'checkbox' | 'dropdown';
 
-/**
- * Color mode configuration
- */
-export declare interface ColorModeConfig {
-    default?: ColorModePref;
-    persist?: boolean;
-    onChange?: (mode: ColorModePref) => void;
-}
-
 /**
  * Color mode preference
  */
@@ -1326,7 +1317,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private createAndAppendIframe;
     private destroy;
     close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>;
-    resetWidget(): Promise<void>;
+    private resetWidget;
     restart(newOptions?: Partial<SDKOptions<TSchema>>): Promise<void>;
     private handleWidgetClosed;
     private hideContainer;
@@ -3755,7 +3746,7 @@ export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, u
     developerMode?: boolean;
     preload?: boolean;
     theme?: ECSVTheme;
-    colorMode?: ColorModeConfig;
+    colorMode?: ColorModePref;
     customCSS?: string;
     fonts?: Record<string, ECSVFontSource>;
     stepDisplay?: 'progressBar' | 'segmented' | 'numbered';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expresscsv/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "SDK for integrating widget",
   "module": "dist/index.mjs",
   "types": "dist/index.d.mts",

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

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

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

@@ -1,207 +0,0 @@
-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 };