Agent integration rules

Paste this into AGENTS.md, Cursor rules, or your agent system prompt when adding Bootstrapware Importer. The same text ships inside the npm package as AGENTS.md.

What the package does

Client-side CSV / TSV / XLSX import UI. Parsing, mapping, validation, preview, duplicate detection, and error export run in the browser.

On the upload step, once local or hosted fields are known, the widget offers Download template.csv. Headers use field labels (empty labels fall back to keys). One example row is derived from field type. Generated in the browser; never fetched from Bootstrapware.

Never send file contents, parsed rows, or filenames to Bootstrapware. The customer's onComplete callback receives normalized objects. Send those to the customer's own backend.

Hosted mode only fetches published field configuration and reports non-content session metadata.

Install

pnpm add @bootstrapware/importer

Local schema

import { Importer } from "@bootstrapware/importer";
import "@bootstrapware/importer/styles.css";

<Importer
  fields={[
    { key: "email", label: "Email", type: "email", required: true, aliases: ["Email Address", "E-mail"] },
    { key: "name", label: "Name", type: "string", required: true },
  ]}
  duplicateKey="email"
  dateOrder="MDY"
  numberLocale="auto"
  onComplete={async (rows) => {
    await fetch("/api/customers/import", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ rows }),
    });
  }}
/>

Hosted configuration

Publishable keys may appear in the browser. Secret keys must stay server-side.

<Importer
  importerId="imp_..."
  publishableKey="bsw_live_pub_..."
  onComplete={(rows) => {
    void fetch("/api/customers/import", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ rows }),
    });
  }}
/>

Optional apiBaseUrl defaults to https://importer.bootstrapware.co.

Hosted management (secret key)

Secret keys (bsw_test_sec_ / bsw_live_sec_) must stay server-side. Use them as Authorization: Bearer against https://importer.bootstrapware.co to create, draft, and publish hosted importers without the dashboard.

Local fields schema remains free forever. Live publishable config fetch still requires a paid Importer plan ($19.99). API keys, webhooks, importer delete, and branding stay dashboard-only.

# Create
curl -s -X POST https://importer.bootstrapware.co/api/v1/importers \
  -H "Authorization: Bearer $BSW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customers"}'

# Save draft (replace IMPORTER_ID)
curl -s -X PATCH https://importer.bootstrapware.co/api/v1/importers/IMPORTER_ID \
  -H "Authorization: Bearer $BSW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name":"Customers","config":{"fields":[{"key":"email","label":"Email","type":"email","required":true},{"key":"name","label":"Name","type":"string","required":true}],"duplicateKey":"email"}}'

# Publish
curl -s -X POST https://importer.bootstrapware.co/api/v1/importers/IMPORTER_ID \
  -H "Authorization: Bearer $BSW_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"action":"publish"}'

Also available with the same secret key: GET /api/v1/importers, GET /api/v1/importers/:id, GET /api/v1/usage.

Hosted MCP (Cursor)

HTTP MCP endpoint: https://importer.bootstrapware.co/mcp. Prefer OAuth Connect (no secret in mcp.json). Secret Bearer keys remain a fallback. Never send spreadsheet file contents or row payloads through MCP tools.

Cursor plugin: github.com/BootstrapWare/bootstrapware-cursor. Use Keys → Add to Cursor (OAuth), then Connect and sign in.

Tools:

list_importers
get_importer
create_importer
update_draft (does not publish)
publish_importer
get_published_config
list_capabilities

Dashboard-only: API key mint/revoke, webhooks, importer delete, branding, billing. Prefer list_capabilities before inventing endpoints.

Publishing stores hosted config. Live bsw_live_pub_ fetch still needs a paid Importer plan ($19.99). Test publishable keys work without that.

Revoke Cursor OAuth grants under Keys → Active Cursor connections. Marketplace listing may still be pending.

First-run setup

Open Importer → Keys and click Add to Cursor (OAuth) (or install the plugin).
In Cursor, click Connect, sign in on Bootstrapware, and Allow.
Secret fallback: mint a test secret and paste the Keys-page mcp.json snippet if OAuth is unavailable.

Open Keys (Connect Cursor)

{
  "mcpServers": {
    "bootstrapware-importer": {
      "type": "http",
      "url": "https://importer.bootstrapware.co/mcp"
    }
  }
}

Field types

enum requires enumValues.

Optional aliases is a string array of extra spreadsheet header names used during auto-map (in addition to key and label).

Optional unique: true on a field rejects duplicate values for that field within the file.

Numbers accept US and European formats, currency symbols, percentages as fractions, and accounting negatives ($1,234.50, 1.234,56, 50% → 0.5, (500)). With numberLocale="eu" (or semicolon-delimited files under auto), bare 1.234 is thousands. Common empty placeholders (N/A, -, null) are treated as blank. Emails like Name <addr@domain> or mailto:addr@domain are normalized to the address. Booleans accept true/false, yes/no, y/n, 1/0, on/off. URLs accept http/https and bare www.example.com. Mapped cells are trimmed and internal whitespace is collapsed.

CSV delimiter is auto-detected between comma, semicolon, and pipe. .tsv / .tab use tabs.

Optional component props: dateOrder (MDY | DMY), numberLocale (us | eu | auto), dir (ltr | rtl). Multi-sheet Excel files show a sheet picker.

Security

Do not put bsw_live_sec_ or bsw_test_sec_ in client code.
Do not upload spreadsheet contents to Bootstrapware.
onComplete is the data path.