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:

<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.

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>

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.

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

Next: Events & apply.