Developer documentation

@csvmod/embed · SDK reference for the embeddable importer.

Installation

Copy the single self-contained file to your CDN and load it. No build step, no iframe, no dependencies:

<script src="https://cdn.csvmod.com/csvmod.embed.js"></script>

<csvmod-importer license-key="pk_live_123456789" theme="auto"></csvmod-importer>

npm packages for bundler workflows are on the roadmap:

import { CSVMod } from '@csvmod/embed';
const importer = new CSVMod({
  licenseKey: 'pk_live_123456789',
  theme: 'auto',
  el: '#importer',
  schema: { fields: [
    { key: 'full_name', label: 'Full Name', required: true },
    { key: 'email', label: 'Email Address', required: true, type: 'email' },
    { key: 'role', label: 'User Role', type: 'select', options: ['Admin', 'Member'] }
  ]},
  onComplete: async (data) => {
    console.log('Cleaned Rows:', data.validRows);
  }
});
importer.open();

The same CSVMod class is exposed as a global in the script-tag build; CsvMod.create(options) is an alias for it.

Schema reference

Option	Type	Default	Description
`key`	string	—	Output key on the delivered row objects.
`label`	string	key	Human label shown in mapping + grid, used for fuzzy matching.
`type`	string	string	One of `string \| email \| number \| boolean \| date \| select \| unique`.
`required`	bool	false	Row is invalid if the mapped column is empty.
`options`	string[]	—	Allowed values for `select`; case-insensitive with auto-correction.

Events & callbacks

Hook	Signature	When
`onComplete`	`(data) => void \| Promise`	Clean rows confirmed by the user.
`csvmod-complete`	`CustomEvent.detail`	DOM event, same payload as onComplete.

Payload shape:

{
  validRows: [{ key: value, ... }, ...], // clean, mapped rows
  rejected: 3,             // rows the user chose to skip
  total: 12,               // data rows in the file
  meta: {
    licenseKey: "pk_live_...",
    ai: true,               // DeepSeek was configured
    delimiter: ",",         // sniffed
    encoding: "UTF-8",      // sniffed
    parseMs: 14,
    worker: "web-worker"    // or "main-thread" fallback
  }
}

AI orchestration (DeepSeek)

CsvMod detects AI features automatically when a key is configured:

CsvMod.configureAI({
  apiKey: 'sk-...',
  baseURL: 'https://api.deepseek.com',  // SSE / compatible endpoint ok
  model: 'deepseek-chat'                // deepseek-reasoner also supported
});

Schema mapping — headers + sample rows are sent; the model returns suggested column mappings with confidence, shown as green/amber/red dots.
Error repair — the "✨ AI Fix Common Errors" button batches dirty cells, lets the model propose repairs, and applies the confident ones.

Without a key, deterministic local rules cover emails, numbers, booleans, dates and enums — so the demo and self-hosted installs degrade gracefully.

Server-side automation (OpenClaw)

For scheduled or long-running work, the @csvmod/openclaw runner consumes the same schema and replayable file events. See the bundled example in server/ of this repo. Typical jobs: nightly de-duplication, phone/normalization sweeps, or re-ingesting files that failed a downstream webhook.

Browser support

Chrome/Edge/Firefox/Safari current + 1 major version.
Web Components and TextEncoder required; the parser degrades to main-thread if Worker is unavailable.
Shadow DOM guarantees zero style leakage in both directions.

Roadmap

Un-pivot / matrix-to-columns transform.
Excel (.xlsx) ingestion via SheetJS core.
Inline cell editing with re-validation.
Multi-sheet and fetch-from-URL sources.