SDK Reference

@expresscsv/sdk is centered around the CSVImporter class. You configure it once, then call open() when you want to start an import.

`new CSVImporter(options)`

Common constructor options:

Option	Description
`schema`	Schema definition created with `x.row()`
`publishableKey`	Your publishable key from the dashboard
`importIdentifier`	Unique identifier for this import type
`title`	Title shown in the widget header
`preload`	Preload widget in a hidden iframe for instant display
`theme`	Theme variable overrides
`colorMode`	`'light'`, `'dark'`, or `'system'`
`customCSS`	Custom CSS injected into the widget
`fonts`	Custom font sources
`stepDisplay`	Step indicator style
`previewSchemaBeforeUpload`	Show expected columns before upload
`templateDownload`	Offer downloadable template files
`saveSession`	Persist session for resuming interrupted imports
`locale`	Locale string overrides
`disableStatusStep`	Skip the success/error status screen

`open(options)`

You must provide at least one of onData or webhook.

Option	Description
`onData`	Callback for each chunk. Call `next()` to receive the next chunk.
`webhook`	Webhook endpoint for server-side delivery
`chunkSize`	Records per chunk (default: 1000)
`onComplete`	Called when all chunks have been processed
`onCancel`	Called when the user cancels the import
`onError`	Called when an error occurs
`onWidgetOpen`	Called when the widget opens
`onWidgetClose`	Called when the widget closes
`onStepChange`	Called when the wizard step changes

Lifecycle And Status Methods

Method	Description
`close(reason?)`	Closes the widget, optionally with a close reason
`restart(newOptions?)`	Resets and reopens the widget for a new import
`getState()`	Returns the current widget state
`getIsReady()`	Returns `true` when the widget is initialized and ready to open
`getIsOpen()`	Returns `true` while the widget is open
`getConnectionStatus()`	Returns the current iframe connection status
`getCanRestart()`	Returns `true` when the widget can be restarted
`getLastError()`	Returns the most recent error, if any
`getStatus()`	Returns a snapshot of importer status helpers
`getVersion()`	Returns the SDK version

Example

const importer = new CSVImporter({
  schema,
  publishableKey: "your-publishable-key",
  importIdentifier: "user-import",
});

console.log(importer.getStatus());

await importer.close("user_close");

When To Use TypeScript Vs React

Use the base SDK when:

your app is not built with React
you want an imperative importer instance
you need direct lifecycle and status methods

If you want hook-based state and component lifecycle integration, use the React API instead.

new CSVImporter(options)

open(options)

Lifecycle And Status Methods

Example

When To Use TypeScript Vs React

On this page

`new CSVImporter(options)`

`open(options)`