@expresscsv/sdk 0.1.20 → 0.1.22

package/README.md

@@ -3,7 +3,7 @@
 [![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.
+A TypeScript SDK for embedding the [ExpressCSV](https://expresscsv.com) CSV importer into any web application. Define a schema, open the importer, and receive validated, typed data in chunks.
 
 If you want to define schemas in shared or backend code without any frontend dependencies, use [`@expresscsv/schemas`](https://www.npmjs.com/package/@expresscsv/schemas) for the schema definition itself, then pass that schema into `@expresscsv/sdk`.
 
@@ -35,12 +35,12 @@ const schema = x.row({
 
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   title: "Import Users",
 });
 
-// Open the widget and process data in chunks
+// Open the importer and process data in chunks
 importer.open({
   onData: (chunk, next) => {
     console.log(`Chunk ${chunk.currentChunkIndex + 1}/${chunk.totalChunks}`);
@@ -59,7 +59,7 @@ importer.open({
 
 If your schema is assembled dynamically at runtime, still use `x.row(...)`. Just note that dynamic schema assembly can widen TypeScript inference, so use it intentionally when you need runtime-driven columns.
 
-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.
+Have your backend keep the ExpressCSV secret key, call the ExpressCSV session-creation endpoint, and return a short-lived importer session token to the browser via `getSessionToken`. The SDK opens the importer immediately, then completes the initial session bootstrap in the background.
 
 ## Webhook Delivery
 
@@ -105,7 +105,6 @@ interface WebhookPayload {
   metadata?: Record<string, unknown>;
   /** Delivery context added by ExpressCSV */
   delivery: {
-    publishableKey: string;
     environmentName: string;
     environmentType: string;
     teamSlug: string;
@@ -134,7 +133,6 @@ Example payload:
     "userId": "user-123"
   },
   "delivery": {
-    "publishableKey": "pk_live_abc123",
     "environmentName": "Production",
     "environmentType": "production",
     "teamSlug": "my-team",
@@ -241,17 +239,17 @@ importer.open({
 
 ## 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.
+By default, the SDK preloads the importer in a hidden iframe for instant display when `open()` is called. This provides the best user experience while the initial session bootstrap continues in the background.
 
 ```typescript
 // Preload is enabled by default
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
 });
 
-// Later, the widget appears instantly
+// Later, the importer appears instantly
 importer.open({ onData: (chunk, next) => { /* ... */ next(); } });
 ```
 
@@ -260,7 +258,7 @@ To disable preloading (there will be a brief loading screen instead):
 ```typescript
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   preload: false,
 });
@@ -284,7 +282,7 @@ const candidateSchema = x.row({
 
 const importer = new CSVImporter({
   schema: candidateSchema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "candidate-import",
   templateDownload: {
     source: "generate",
@@ -302,7 +300,7 @@ const importer = new CSVImporter({
 
 ## Theming and Styling
 
-Customize the widget's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
+Customize the importer's appearance with the `theme`, `colorMode`, `customCSS`, and `fonts` options.
 
 ### Theme
 
@@ -340,7 +338,7 @@ const dualTheme: ECSVTheme = {
 
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   theme,
 });
@@ -384,7 +382,7 @@ Control light/dark mode with `colorMode`:
 ```typescript
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   colorMode: "system", // 'light' | 'dark' | 'system'
 });
@@ -397,7 +395,7 @@ Inject custom CSS for fine-grained styling overrides.
 ```typescript
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   customCSS: `
     .ecsv [data-step="upload"] {
@@ -417,7 +415,7 @@ Load custom fonts via the `fonts` option:
 ```typescript
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
   fonts: {
     title: { source: "google", name: "Space Grotesk", weights: [400, 600, 700] },
@@ -434,7 +432,7 @@ const importer = new CSVImporter({
 
 The `x` schema builder provides a type-safe, fluent API for defining your CSV structure.
 
-For apps that share schema definitions with backend code or webhook handlers, prefer defining the schema in `@expresscsv/schemas` and importing it into your frontend. That keeps schema authoring free of widget/runtime dependencies.
+For apps that share schema definitions with backend code or webhook handlers, prefer defining the schema in `@expresscsv/schemas` and importing it into your frontend. That keeps schema authoring free of importer/runtime dependencies.
 
 ### Field Types
 
@@ -539,7 +537,7 @@ All field types support:
 
 | Modifier | Description |
 |---|---|
-| `.label(text)` | User-facing label shown in the widget |
+| `.label(text)` | User-facing label shown in the importer |
 | `.description(text)` | Help text for the field |
 | `.example(text)` | Example value shown as placeholder |
 | `.optional()` | Makes the field optional (default is required) |
@@ -590,7 +588,7 @@ x.string().refine(
 )
 ```
 
-**Object-returning validator** — inline `valid`, `message`, and an optional `suggestedFix` the widget can offer the user:
+**Object-returning validator** — inline `valid`, `message`, and an optional `suggestedFix` the importer can offer the user:
 
 ```typescript
 x.string().refine((value) => ({
@@ -657,7 +655,7 @@ x.string().refineBatch((values) => {
 
 ### `suggestedFix`
 
-Both `.refine()` and `.refineBatch()` support returning a `suggestedFix` object that the widget offers as a one-click fix for the user:
+Both `.refine()` and `.refineBatch()` support returning a `suggestedFix` object that the importer offers as a one-click fix for the user:
 
 ```typescript
 interface SuggestedFix {
@@ -680,14 +678,14 @@ new CSVImporter(options: SDKOptions)
 | 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) |
+| `getSessionToken` | `() => Promise<string>` | Yes | - | Async callback that asks your backend for a short-lived importer session token |
 | `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 |
+| `title` | `string` | No | - | Title shown in the importer header |
+| `preload` | `boolean` | No | `true` | Preload the importer for instant display |
 | `debug` | `boolean` | No | `false` | Enable debug logging |
 | `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 |
+| `customCSS` | `string` | No | - | Custom CSS to inject into the importer |
 | `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 |
@@ -697,7 +695,7 @@ new CSVImporter(options: SDKOptions)
 
 #### `open(options)`
 
-Opens the widget and begins the import flow. At least one of `onData` or `webhook` must be provided.
+Opens the importer and begins the import flow. At least one of `onData` or `webhook` must be provided.
 
 ```typescript
 importer.open(options: OpenOptions): void
@@ -711,15 +709,15 @@ importer.open(options: OpenOptions): void
 | `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 |
+| `onImporterOpen` | `() => void` | No | Called when the importer opens |
+| `onImporterClose` | `(reason: string) => void` | No | Called when the importer closes |
 | `onStepChange` | `(stepId, previousStepId?) => void` | No | Called when the wizard step changes |
 
 \* At least one of `onData` or `webhook` is required.
 
 #### `close(reason?)`
 
-Closes the widget and cleans up resources.
+Closes the importer and cleans up resources.
 
 ```typescript
 await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): Promise<void>
@@ -731,18 +729,18 @@ await importer.close(reason?: 'user_close' | 'cancel' | 'complete' | 'error'): P
 
 | 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 |
+| `getState()` | `ImporterState` | Current importer lifecycle state |
+| `getIsReady()` | `boolean` | Whether the importer is ready or open |
+| `getIsOpen()` | `boolean` | Whether the importer is currently open |
 | `getConnectionStatus()` | `boolean` | Whether the iframe connection is active |
-| `getCanRestart()` | `boolean` | Whether the widget can be restarted |
+| `getCanRestart()` | `boolean` | Whether the importer can be restarted |
 | `getLastError()` | `Error \| null` | Last error, if any |
 | `getStatus()` | `object` | Comprehensive status snapshot |
 | `getVersion()` | `string` | SDK version |
 
 #### `restart(newOptions?)`
 
-Restarts the widget, optionally with updated options. Returns `Promise<void>`.
+Restarts the importer, optionally with updated options. Returns `Promise<void>`.
 
 ### `RecordsChunk<T>`
 
@@ -788,7 +786,7 @@ type Row = Infer<typeof schema>;
 
 const importer = new CSVImporter({
   schema,
-  publishableKey: "your-publishable-key",
+  getSessionToken: async () => fetchSessionToken(),
   importIdentifier: "user-import",
 });
 

package/dist/index.d.cts

@@ -1244,12 +1244,16 @@ 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 openOptions;
@@ -1257,6 +1261,7 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private initCompletePromise;
     private resolveInitComplete;
     private resolvedTemplateDownload;
+    private importerStartupGeneration;
     constructor(options: SDKOptions<TSchema>);
     /**
      * Enhanced state management
@@ -1264,10 +1269,24 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
     private setState;
     private updateDerivedState;
     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
      */
@@ -1282,11 +1301,6 @@ export declare class CSVImporter<TSchema extends ExType<unknown, ExBaseDef, unkn
      * 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
      */
@@ -1312,7 +1326,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>;
     /**
@@ -1323,20 +1337,20 @@ 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;
+    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;
@@ -2866,7 +2880,7 @@ declare interface ExpressCSVLocale {
         nextDisabledReviewValidating: string;
         nextDisabledReviewInvalid: string;
     };
-    widget: {
+    importer: {
         title: string;
         loading: string;
         closeConfirmTitle: string;
@@ -2875,7 +2889,6 @@ declare interface ExpressCSVLocale {
         closeConfirmContinue: string;
         errorTitle: string;
         startOver: string;
-        invalidPublishableKey: string;
     };
     sessionRecovery: {
         message: string;
@@ -2995,6 +3008,7 @@ declare interface ExpressCSVLocale {
     };
     review: {
         completing: string;
+        processing: string;
         loading: string;
         title: string;
         subtitle: string;
@@ -3587,6 +3601,29 @@ 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 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>;
@@ -3611,12 +3648,12 @@ export declare type OpenOptions<T> = RequireAtLeastOne<DeliveryOptionsBase<T>, '
     onCancel?: () => void;
     /** Called when an error occurs */
     onError?: (error: Error) => void;
-    /** Called when the widget opens */
-    onWidgetOpen?: () => 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 type PhoneNumberFormat = 'international' | 'national' | 'both';
@@ -3765,7 +3802,7 @@ declare type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Excl
 
 export declare interface SDKOptions<TSchema extends ExType<unknown, ExBaseDef, unknown>> {
     schema: TSchema;
-    publishableKey: string;
+    getSessionToken: () => Promise<string>;
     importIdentifier: string;
     title?: string;
     debug?: boolean;
@@ -3858,7 +3895,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 & {
@@ -3910,34 +3947,11 @@ export declare interface WebhookConfig {
      * 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: true
+     * 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;