Target catalogs — your import schema without code

A target catalog is the schema behind an import: the record types a customer can create (Contact, Deal, Invoice…) and the fields each carries — labels, types, validators, matcher aliases. You can pass it in code via the targets property, or store it server-side and let the widget resolve it by key:

Validation follows an errors-vs-warnings model at review: a missing required value always blocks, while failed checks on optional fields only warn — the rows import as is. When your system hard-enforces a constraint (say, a unique SKU), declare severity: "error" on that validator in the catalog and it blocks too; fully blank rows are skipped automatically.

<mildport-import
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
  catalog-key="zoho-crm"
></mildport-import>

Publish a change to the catalog and every embed picks it up on its next load — no host release, no redeploy. Published catalogs are versioned and cached with standard HTTP revalidation, so the extra request costs almost nothing.

Zero-config embeds: with neither targets nor catalog-key set, the widget adopts your license’s single listed published catalog automatically — the minimal embed is just api-base-url + license-key. The context bar above the steps still shows a picker (even with one catalog) so importers can see the count and open Need more catalogs?. With several listed catalogs the widget never guesses: the picker lets the user choose (switching mid-import asks to restart first). The user’s last pick is remembered per browser; pin one catalog with catalog-key when a page should always import into a specific schema — pinned embeds show the catalog name without a picker.

Record-type choice inside the catalog: when the active catalog declares several record types (contacts and invoices, say), the same context bar offers an “Importing into” pick — scope the import to one record type, let the matcher detect it automatically, or choose Create your own fields to shape a one-off schema for this run. It works the same for zero-config, pinned, and targets embeds.

Preset catalogs

Nobody should have to author a schema before their first import. The engine ships a registry of preset catalogs — contacts & companies, a CRM with deals, invoices, products, plus CRM-flavored starters — and every surface offers them wherever a fresh account would otherwise dead-end:

• Cloud signup: minting a tenant asks “What would you like to import?” — the pick is published as your first catalog before you’ve even copied the key.
• Playground and catalog editor: an account with no catalogs gets the preset gallery; one click creates and publishes.
• API: GET /catalog-presets lists the registry; POST /catalog-presets/:id/adopt copies one into a real catalog under your account (never overwriting an existing key, so retries are safe).

Adoption is a copy: the catalog becomes yours, editable and deletable like any other, and later preset updates never touch it. Presets count toward the plan’s catalog allowance like any created catalog. Self-hosted deployments have the same registry built into the engine — the hosted editor’s first-run gallery and the adopt endpoint work identically, no extra setup or data migration.

Star and unlist — server-side, no embed config. Two per-catalog settings, toggled in the catalog editor (or via PATCH /target-catalog/:key/settings), control what zero-config embeds see for the whole account:

• Starred (at most one): the default — zero-config embeds adopt it without asking while the picker stays available. Starring a catalog unstars the previous one.
• Unlisted: removed from the widget’s listing and picker entirely. An embed that explicitly pins the key with catalog-key still resolves it — the pattern for “don’t offer this broadly, but the invoices page uses it deliberately.”

Edit fields without touching code

<mildport-catalog-editor> is a second custom element, shipped as a separate entry so your importer bundle doesn’t grow:

import { defineCatalogEditorElement } from '@capitality-io/mildport-widget/editor';
await defineCatalogEditorElement('mildport-catalog-editor');

<mildport-catalog-editor
  api-base-url="https://imports.your-infra.example"
  license-key="SIGNED_TENANT_KEY"
></mildport-catalog-editor>

Catalog writes (save draft, publish, scan, rollback, delete, overrides) are included in every plan — what scales with the plan is the number of catalogs you can create: 1 on Free/Starter, 3 on Pro, 5 on Enterprise. The cap applies to creating new catalogs only; editing existing ones is never blocked, and reads are never gated: published catalogs keep resolving in every embed regardless of plan. Deleting a catalog (editor → More tools) frees a slot — but embeds using its key stop resolving, so treat it as an explicit admin action.

Embed it in your own admin area so ops teams — or your customers — manage fields themselves:

• Multiple catalogs per license (one key per CRM or workflow).
• Field table with types, required flags, aliases; bulk-add from a pasted header row or a sample JSON record; starter templates for common CRMs.
• Live preview — the editor mounts the real importer with the unsaved draft, so you see exactly what customers will see in Match and Verify.
• Draft → publish with a field-level diff; nothing goes live by accident.
• Events: catalog-saved, catalog-published.

Need more catalogs?

Your plan caps how many catalogs you can create: 1 on Free and Starter, 3 on Pro, 5 on Enterprise. The cap never blocks editing a catalog you already have, and published catalogs keep resolving in every embed.

Add another catalog when your plan still has a slot:

1. Open Catalogs — hosted at /admin/catalogs on your import origin, or from your Mildport account.
2. Create a new key, shape the fields, and publish. Drafts stay out of the importer picker until you publish.

Raise the cap when you are already at the limit: upgrade the plan, or write [email protected] for a higher allowance on a paid key.

Hosted editor — no embed required

Don’t want to embed the editor? Every Mildport instance can serve it as a ready-made admin page at /admin/catalogs. The page asks for your license key once (kept in sessionStorage, never in the URL) and mounts the same editor against the same API.

Self-hosting with the official images (service, Bun, or all-in-one)? The page works out of the box — the editor assets ship in the image. On a custom build, point CATALOG_EDITOR_STATIC_DIR at the dist/ contents of the @capitality-io/mildport-hosted-admin npm package and restart — the page explains this itself until it’s configured. Plans without catalogWrite see the page read-only.

Draft the schema from your API spec

Instead of typing fields by hand, point the editor’s Scan panel at what you already have:

• an OpenAPI / Swagger spec (JSON or YAML) — pasted or by URL,
• a JSON Schema or GraphQL introspection result,
• a sample API response, or
• freeform input — type definitions or an API docs page.

Mildport drafts the catalog from it: record types, fields, types, and matching hints. The result always lands as a draft with per-field provenance badges — a human reviews and publishes; nothing is published automatically. Structured specs draft even with AI assist disabled. URL fetches are strictly limited to public addresses with size and time caps.

When a catalog was drafted from a spec URL, Mildport can re-check the spec and flag drift in the editor — “your CRM added 2 fields” — so the schema never silently goes stale.

Versions and rollback

Publishing snapshots an immutable version. The editor’s Version history panel lists them all; restoring an older version republishes it as a new one, and embeds pick it up on their next load. A bad publish is a one-click rollback, not an incident.

Per-project and per-launch overrides

One catalog can serve many contexts without forking:

• Sub-project overrides — store a patch per project key; an embed opts in with catalog-project="acme" and sees the base catalog plus its own override only.
• Per-launch patches — set targets-mode="patch" and pass targets as a patch: add or override fields by key, hide with hidden: true. The server catalog stays the base.

<mildport-import catalog-key="zoho-crm" targets-mode="patch"></mildport-import>

el.targets = [
  {
    id: 'contact',
    fields: [
      { key: 'contact.fax', hidden: true },
      { key: 'contact.source', label: 'Lead source' },
    ],
  },
];

Resolution rules

Host provides	Widget uses
targets only	The host catalog (exactly as today)
catalog-key only	The published server catalog
catalog-key + catalog-project	Server catalog with that project’s override
catalog-key + targets-mode=patch	Server catalog with the host patch merged in

An explicit targets value always wins over the server catalog unless you opt into patch mode — a broken host configuration fails loudly instead of being silently masked.

API-first

The editor is optional — everything it does goes through the same license-keyed REST API, so catalogs can live in your CI instead:

Verb	Path	Purpose
GET	/api/import/v1/target-catalog	List catalogs
GET	/api/import/v1/target-catalog/:key	Published catalog (?project= opt.)
PUT	/api/import/v1/target-catalog/:key/draft	Save the draft
POST	/api/import/v1/target-catalog/:key/publish	Publish a new version
GET	/api/import/v1/target-catalog/:key/versions	Version history
POST	/api/import/v1/target-catalog/:key/rollback	Restore a version
PUT	/api/import/v1/target-catalog/:key/overrides/…	Save a sub-project override
POST	/api/import/v1/target-catalog/:key/scan	Draft the catalog from a spec
DELETE	/api/import/v1/target-catalog/:key	Delete the catalog (frees a slot)

Next: Events & apply.