@opencxh/domain 1.226.0 → 1.227.0

package/dist/platform/sync-source.d.ts

@@ -1,517 +0,0 @@
-/**
- * Pulling outside data in, settled once.
- *
- * The platform ingests in four independent ways today — a cron sync per provider app, webhooks, an
- * event-driven enrichment job and loose backfills — and each of the four rebuilds the same six
- * things: cursor, batching, locking, idempotency, error handling and observability. It shows:
- * `cursorKey()` sits in the repo three times, `microsoft_sync_state` grows a column per sub-sync,
- * and a sync that stalls is a `console.error` nobody sees.
- *
- * The split that fixes that is the industry standard (Singer/Airbyte, Nango, Fivetran): **a narrow
- * source contract with a thick generic runtime.** The source knows how to fetch one page from
- * Microsoft Graph or Asana; the runtime knows how to checkpoint cursors, chain batches, back off
- * and keep a run log. This file is that narrow contract.
- *
- * Three endpoints, shaped like `memory-source` and `analytics-source` — so a provider role and not
- * a service-bus key, because this runs server-side with no user present:
- *
- * | Role | Endpoint | Answer |
- * |---|---|---|
- * | `sync-source` | `GET /provider/sync/describe` | {@link SyncSourceDescribe} |
- * | `sync-source` | `POST /provider/sync/pull` | {@link SyncPullResponse} |
- * | `sync-target` | `POST /provider/sync/land` | {@link SyncLandResponse} |
- *
- * Source and target are **separate roles**: `apps/microsoft` delivers records and lands none,
- * `apps/work` lands records and delivers none. An app may be both, but need not be.
- */
-/** The provider role groups, as constants so a typo does not silently yield an empty list. */
-export declare const SYNC_SOURCE_PROVIDER_GROUP = "sync-source";
-export declare const SYNC_TARGET_PROVIDER_GROUP = "sync-target";
-/**
- * Continuous or one-off — a real difference, not a label.
- *
- * `continuous` runs on a tick and so has to be able to do nothing cheaply (a cursor saying
- * "nothing new"). `once` is started by a person, may be expensive, and has to be **exhaustive**: a
- * migration that fetches 95% is not a migration. That requirement is exactly why not every source
- * can do both — see {@link SyncSourceDefinition.transport}.
- */
-export type SyncMode = "continuous" | "once";
-/**
- * How the records actually arrive.
- *
- * This sits in the contract because it sets the expectations the runtime and the UI may have, not
- * as documentation:
- *
- * - **`native`** — the app talks to the vendor's API itself. Knows delta tokens and pagination,
- *   so suitable for `continuous` as well as `once`.
- * - **`tool`** — the app goes through the AI tool/MCP layer. Fine for the long tail of systems
- *   where a dedicated connector does not pay off, but an MCP search tool answers "top-N relevant"
- *   and not "everything since X", and the protocol has no change token. A `tool` source claiming
- *   `once` promises completeness it cannot deliver.
- * - **`file`** — an uploaded file (CSV). `once` by definition, and complete by definition.
- */
-export type SyncTransport = "native" | "tool" | "file";
-/**
- * One setting of a connection, as the source declares it.
- *
- * Deliberately no ui-kit types here: `packages/domain` has no UI dependencies, and the form maps
- * this declaration onto its own fields itself.
- */
-export interface SyncSettingsField {
-    /** Key in the settings object the source gets back on `pull`. */
-    key: string;
-    label: string;
-    type: "text" | "number" | "boolean" | "select";
-    required?: boolean;
-    /** Only with `type: "select"`. */
-    options?: {
-        value: string;
-        label: string;
-    }[];
-    /** Explanation under the field. For "empty = ..." cases, which are guesswork otherwise. */
-    help?: string;
-    /**
-     * Hint that this value points at a resource in another app (`"work_project"`).
-     *
-     * Today the form renders it as a text field; the hint is here so a picker can be added later
-     * without the source changing. A hint, not a promise.
-     */
-    resource?: string;
-    /**
-     * Rarely needed: the form hides it behind a collapsed "Advanced".
-     *
-     * Declared by the source and not guessed by the form, because only the source knows which of
-     * its settings are the everyday ones. A generic source has fifteen settings of which nine are
-     * paging and delta plumbing, and showing those at the same level as "which tool" is what makes
-     * such a form unreadable.
-     */
-    advanced?: boolean;
-    /**
-     * This setting changes **what a trial call answers with**, so it belongs with that call.
-     *
-     * Two things at once: the form puts the field next to the trial-run button instead of among
-     * the rest, and the trial call sends it along. Without it the form would have to know which
-     * keys of which source are probe input — vendor knowledge in exactly the place that must not
-     * have any.
-     */
-    probe?: boolean;
-}
-export interface SyncSourceDefinition {
-    /**
-     * Stable and app-namespaced: `microsoft.todo`, `asana.tasks`, `csv.contacts`.
-     *
-     * A **stored reference** — `SyncConnection.sourceId` keeps it — so renaming breaks existing
-     * connections. Dot as separator, like `MemoryKindId` for app-owned kinds.
-     */
-    id: string;
-    label: string;
-    description?: string;
-    /**
-     * The scope kinds this source lands: `work_item`, `interaction`, `company`, `contact`.
-     *
-     * The same vocabulary as `ScopeDescribe.kinds`, and not a cosmetic choice — the runtime routes a
-     * record to the owning app with `findScopeOwner(kind)`. A kind without a scope owner cannot be
-     * landed, and you notice that while registering instead of halfway a run.
-     */
-    kinds: string[];
-    /** Which modes this source supports. Empty is pointless; at least one. */
-    modes: SyncMode[];
-    transport: SyncTransport;
-    /**
-     * The `providerId` of the {@link ManagedAccount} this source needs.
-     *
-     * Absent = no credential needed (a file upload). Present means a connection does not work
-     * without a chosen account, and the UI can say so before the first run instead of showing a
-     * failed one.
-     */
-    accountProviderId?: string;
-    /**
-     * The settings key that decides which kind this connection lands.
-     *
-     * Most sources know that at build time and list it in {@link SyncSourceDefinition.kinds}. A
-     * generic source does not: one MCP tool answers with one kind of thing, but *which* kind is a
-     * choice made per connection. Declaring the key here — rather than letting the UI guess that a
-     * setting called `kind` is special — keeps the mapping step showing the fields of the one kind
-     * this connection will actually produce, instead of every kind the source could ever land.
-     */
-    kindSetting?: string;
-    /**
-     * Settings that differ per connection and therefore do not belong in code.
-     *
-     * Declarative, so a connector app needs **no frontend** to be configurable: the Connections form
-     * renders these fields. That is what keeps `apps/asana` (zero frontend files) possible.
-     *
-     * Kept flat on purpose. A nested schema would turn into a mapping DSL, which was rejected
-     * earlier: date formats and enums differ per source, and errors then move from `tsc` to runtime.
-     */
-    settingsSchema?: SyncSettingsField[];
-    /**
-     * Only with `transport: "tool"`: the catalog key the connector picker pre-filters on
-     * (`"asana"`, `"linear"`).
-     *
-     * A **hint**, not a resolution: it decides which of the organisation's MCP connections are
-     * offered as candidates. What the connection stores afterwards is the connector **id**
-     * ({@link SyncConnection.connectorId}). Without a hint the user simply gets the full list.
-     */
-    connectorHint?: string;
-    /**
-     * Only with `transport: "tool"`: this source can only run on a shared organisation credential.
-     *
-     * Why this exists: an unattended round (cron, sync) has no acting user, so a connector with
-     * `credentialScope: "per-user"` yields zero tools there by definition — which used to show up
-     * only as "the sync does nothing". With this flag, saving a `continuous` connection is refused
-     * right away, with an explanation.
-     *
-     * Only for `continuous`: a `once` connection is started by a person, and then there *is* an
-     * acting user whose token can be used.
-     */
-    requiresCredentialScope?: "shared";
-    /**
-     * Recommended minimum time between two rounds, in ms. The organisation may override it.
-     *
-     * An **interval** and not a cron expression, because that is what is actually executable:
-     * `JobOptions.schedule` is fixed at registration, so a per-connection cron string would never be
-     * evaluated — a field promising what it does not do. The runtime ticks on a coarse grid and
-     * gates on this.
-     *
-     * On the source and not in the runtime, because only the source knows what its API tolerates: a
-     * delta feed may run every minute, a list endpoint returning everything every time may not.
-     */
-    defaultIntervalMs?: number;
-    /**
-     * How often the source should ignore its cursor and read everything again (ms).
-     *
-     * The reconcile sweep from the Stripe/Shopify pattern, already proven in this codebase as
-     * `CHAT_FULL_SWEEP_INTERVAL_MS`: cursors rest on the assumption that the vendor bumps an
-     * `updatedAt` for everything that counts, which holds for new records but is unreliable for
-     * edits and deletions. Absent = never sweep (right for a delta feed that reports deletions).
-     */
-    fullSweepIntervalMs?: number;
-}
-/**
- * Bare payload of `GET /provider/sync/describe` — **not** wrapped in `ResponseFactory` (template:
- * {@link MemorySourceDescription} and `AnalyticsSourceDescription`).
- */
-export interface SyncSourceDescribe {
-    /** The declaring app (== `manifest.name` == `req.source.app`). */
-    source: string;
-    sources: SyncSourceDefinition[];
-}
-/**
- * One record from a source system, ready to be landed.
- *
- * The source does the mapping into the shape the target app expects. Deliberately so: the runtime
- * knows no field of any vendor, and the moment it did it would stop being generic. See
- * {@link SyncRecord.data}.
- */
-export interface SyncRecord {
-    /**
-     * The stable id in the source system, namespaced by the source itself (`asana_task:12345`,
-     * `graph-todo:AAMk…`).
-     *
-     * This is the dedupe axis: the target app upserts on it through its
-     * `upsert_by_external_provider_id` route, so running the same run twice writes one row.
-     * "Stable" is the whole requirement — an id that changes per page turns every sync into a
-     * duplicate factory.
-     */
-    externalId: string;
-    /**
-     * Ids pointing at the **container** and not at this row: the list, the project, the board.
-     *
-     * They are stored (outgoing dispatch needs them) but must never take part in the dedupe. This
-     * field exists because it went wrong once: next to the task id Microsoft Graph also sends
-     * `graph-todolist:<id>`, identical for every task in that list, and searching on it collapsed
-     * the whole list onto one row (`task/external-ids.ts`). Repaired there with a prefix list; here
-     * the source says it itself, so that list does not have to grow.
-     */
-    containerExternalIds?: string[];
-    /** The scope kind, from {@link SyncSourceDefinition.kinds}. Decides which app this goes to. */
-    kind: string;
-    /**
-     * The fields for the target app.
-     *
-     * **Fixed field names, never a map keyed by an external id.** The target app has to be able to
-     * *type* the fields: `{ "asana_gid_123": {...} }` cannot be read by `upsertWorkItemFromExternal`
-     * without first knowing what the source put in there, and then every error moves from `tsc` to
-     * runtime.
-     */
-    data: Record<string, unknown>;
-    /**
-     * This record was deleted at the source.
-     *
-     * Only meaningful when the source *can* know: a delta feed reports deletions, a list endpoint
-     * simply leaves them out. Absence from a list is **not** a deletion — not respecting that
-     * difference means a filtered or paginated response clears out half your administration.
-     */
-    deleted?: boolean;
-}
-/** `POST /provider/sync/pull` — fetch one page. */
-export interface SyncPullRequest {
-    sourceId: string;
-    /** So the source can log and find its own per-connection state, if it has any. */
-    connectionId: string;
-    /** The {@link ManagedAccount} to talk with. Absent with `transport: "file"`. */
-    accountId?: string;
-    /**
-     * With `transport: "tool"`: the id of the MCP connector this connection may use, chosen when the
-     * connection was configured.
-     *
-     * This makes the tool name a pure string — `mcpToolPrefix(connectorId) + tool name` — with no
-     * resolution RPC per page. A source used to look its connector up by catalog key, which could
-     * not pick a winner with two candidates (an org row next to a personal one, or two users each
-     * with their own); an app could even end up with the prefix of somebody's personal connector.
-     */
-    connectorId?: string;
-    /**
-     * The settings of this connection, per {@link SyncSourceDefinition.settingsSchema}.
-     *
-     * An **object** here and a JSON string in storage — for the same reason as the cursor: one
-     * schema field that has to be able to carry any shape. Not because of key mangling; the client
-     * does not transform outgoing keys.
-     */
-    settings?: Record<string, unknown>;
-    /**
-     * Opaque, exactly as the source returned it last time. `undefined` = from the start.
-     *
-     * **The runtime never looks inside.** A Graph `deltaLink`, a timestamp, a page token — it does
-     * not matter, and that is precisely why no column per sub-sync has to exist. That
-     * `microsoft_sync_state` today carries `todoDeltaLink` next to `chatCursors` next to
-     * `chatFullSweepAt` is exactly what an opaque field prevents.
-     */
-    cursor?: unknown;
-    /** Ignore the cursor and read everything again — the reconcile sweep. */
-    fullSweep?: boolean;
-    /** Maximum number of records in this answer. The source may give fewer, never more. */
-    limit: number;
-}
-/** Answer to `POST /provider/sync/pull`. This one *is* wrapped in `ResponseFactory`. */
-export interface SyncPullResponse {
-    records: SyncRecord[];
-    /**
-     * The cursor after this page. The runtime stores it **only once the records have landed**.
-     *
-     * That is the Singer/Airbyte rule and the reason crash recovery works: if things fall over
-     * between pull and land, the batch is repeated (idempotent, because upsert on `externalId`)
-     * instead of skipped. The other way round — cursor first — loses records silently, and silent is
-     * the problem here.
-     */
-    cursor?: unknown;
-    /** No more data after this page. The runtime then does not chain on. */
-    done: boolean;
-    /**
-     * The source is rate-limited; wait at least this long before the next attempt.
-     *
-     * In milliseconds, like every other duration in this platform. A source that fills this in
-     * instead of throwing keeps the run `partial` rather than `failed` — it is a delay, not an
-     * error.
-     */
-    retryAfterMs?: number;
-}
-/** `POST /provider/sync/land` — write these records. App callers only. */
-export interface SyncLandRequest {
-    /** Where they came from, for `source`/attribution on the landed row. */
-    sourceId: string;
-    records: SyncRecord[];
-}
-/** What happened to one record. */
-export interface SyncLandOutcome {
-    externalId: string;
-    /**
-     * `created` and `updated` are both "written"; `unchanged` exists separately because an
-     * idempotent resync that changed nothing must not make SSE noise and must not count as work
-     * (the pattern from `lib/upsert-dedup.ts`). `failed` is one row, not the batch.
-     */
-    result: "created" | "updated" | "unchanged" | "deleted" | "failed";
-    /** The scopeKey of the landed row, so the run log can link to the result. */
-    scopeKey?: string;
-    /** Only on `failed`. Short enough for a table row. */
-    error?: string;
-}
-/** Answer to `POST /provider/sync/land`. This one *is* wrapped in `ResponseFactory`. */
-export interface SyncLandResponse {
-    outcomes: SyncLandOutcome[];
-}
-/**
- * One field a target app accepts for a kind — the right-hand side of a column mapping.
- *
- * Deliberately **flat and scalar only**. A field that carries structure (a contact's endpoint
- * list, a work item's assignees) cannot come out of a CSV column or a tool answer anyway, and
- * declaring it would promise a mapping UI something it cannot render. An app that wants such a
- * value mappable declares a scalar alias instead (`email`) and assembles the structure itself —
- * that conversion belongs with the app that owns the shape, not in the pipeline.
- */
-export interface SyncTargetField {
-    key: string;
-    label: string;
-    /** Missing after mapping ⇒ that one row fails, not the batch. */
-    required?: boolean;
-    type?: "text" | "number" | "boolean" | "date";
-    /** Explanation under the field in the mapping UI. */
-    help?: string;
-}
-/**
- * Bare payload of `GET /provider/sync/land-describe`: which kinds this app can land.
- *
- * Separate from `ScopeDescribe`, even though the kinds usually overlap: an app can authorize a
- * kind without having an ingest route for it. Making that difference visible is cheaper than a run
- * that finds a 404 halfway.
- */
-export interface SyncTargetDescribe {
-    source: string;
-    kinds: string[];
-    /**
-     * Per kind, the fields a mapping may fill. Absent = this app does not support column mapping,
-     * and only a source that maps in code (`transport: "native"`) can feed it.
-     */
-    fields?: Record<string, SyncTargetField[]>;
-}
-/**
- * The target field key that always has to be mapped, next to whatever the app declares.
- *
- * It is not in {@link SyncTargetDescribe.fields} because no app owns it: it is the dedupe axis of
- * the pipeline itself. A mapping without it would land every row as a new one, every round.
- */
-export declare const SYNC_MAPPING_EXTERNAL_ID = "externalId";
-/** How healthy a connection is. What the list shows as a badge. */
-export type SyncHealth = 
-/** Last run succeeded. */
-"ok"
-/** Last run partly succeeded, or was rate-limited. Still running, but not cleanly. */
- | "degraded"
-/** Last run failed — usually an expired credential. Needs a person. */
- | "broken"
-/** Never ran, or a required account is missing. Not an error yet. */
- | "unconfigured";
-/**
- * One configured connection: this source, with this account, in this organisation.
- *
- * The credential is **not** in here — `accountId` points at the canonical
- * {@link ManagedAccount} store. A second place where tokens live is a second place where they
- * expire without anyone knowing.
- */
-export interface SyncConnection {
-    id: string;
-    organizationId: string;
-    /** → {@link SyncSourceDefinition.id} */
-    sourceId: string;
-    /** → {@link ManagedAccount.id}. Absent for a source without a credential. */
-    accountId?: string;
-    /**
-     * With `transport: "tool"`: the chosen MCP connector. Explicit, not guessed at run time — so the
-     * UI shows which connection this one uses, and the answer does not change because somebody else
-     * adds the same catalog entry.
-     *
-     * If the row is gone or disabled, the connection goes to `health: "unconfigured"` and the run
-     * fails loudly — never a silent empty page the cursor advances over.
-     */
-    connectorId?: string;
-    /**
-     * The filled-in settings, parsed. In storage it is a JSON string, for the same reason as the
-     * cursor: one schema field that has to be able to carry any shape.
-     */
-    settings?: Record<string, unknown>;
-    /**
-     * The field names this connection's source actually delivers — the left-hand side of the
-     * mapping UI.
-     *
-     * On the **connection** and not on the source definition, because that is where the truth is:
-     * for a CSV they are the column headers of *this* file, for a tool the keys of *this* answer.
-     * A static declaration on the source would have to lie about both.
-     */
-    rawFields?: string[];
-    /**
-     * Target field key → raw field name. Absent = the source maps in code and the runtime passes
-     * records through untouched, which is what every `native` source does.
-     */
-    mapping?: Record<string, string>;
-    /**
-     * Namespace stamped in front of every mapped external id (`hubspot` ⇒ `hubspot:5591`).
-     *
-     * A source that maps in code namespaces its own ids, and must: a bare `12345` from two systems
-     * is the same row as far as the dedupe index is concerned, so without this two connections
-     * would merge each other's records. A mapped source cannot do it itself — the mapping runs
-     * after the pull and is the thing that decides which field is the id — so the runtime does it,
-     * and the connection carries the namespace. Required as soon as a mapping exists.
-     */
-    externalIdPrefix?: string;
-    /** Free-form name; absent = the source's label. */
-    label?: string;
-    mode: SyncMode;
-    enabled: boolean;
-    /**
-     * Minimum time between two rounds, in ms.
-     *
-     * Copied from {@link SyncSourceDefinition.defaultIntervalMs} on creation, so the tick can read
-     * it without querying the source catalog per connection — and so the effective interval is
-     * visible and changeable instead of buried in code.
-     */
-    intervalMs?: number;
-    /** Opaque, from the source. See {@link SyncPullRequest.cursor}. */
-    cursor?: unknown;
-    /** Epoch ms of the last full sweep. */
-    lastFullSweepAt?: number;
-    health: SyncHealth;
-    lastRunAt?: number;
-    /** The error of the last failed run, so the list can show it without reading a run. */
-    lastError?: string;
-    createdBy?: string;
-    createdAt?: number;
-    updatedAt?: number;
-}
-/** What started a run. */
-export type SyncRunTrigger = "cron" | "manual" | "webhook";
-/**
- * `partial` exists next to `done` and `failed` because "12 of the 500 rows did not make it" is
- * neither: the connection works, the cursor may advance, and there is still something to report.
- * Without that third state it becomes either an error that halts the sync or a success that hides
- * the failures.
- */
-export type SyncRunStatus = "running" | "done" | "partial" | "failed";
-/**
- * What happened during one round.
- *
- * Deliberately the same shape as `PlaybookRun`: it is the same question ("what did the system do
- * unasked, and did it go well?"), so the same fields and the same screens.
- */
-export interface SyncRun {
-    id: string;
-    organizationId: string;
-    connectionId: string;
-    sourceId: string;
-    trigger: SyncRunTrigger;
-    status: SyncRunStatus;
-    startedAt: number;
-    finishedAt?: number;
-    /** How many pages this run read. Gives away a source that is not making progress. */
-    pages: number;
-    scanned: number;
-    /** `created` + `updated`. Explicitly not `unchanged`, or an empty resync looks like work. */
-    written: number;
-    /** `unchanged` — the healthy outcome of an idempotent resync. */
-    skipped: number;
-    failed: number;
-    /** Was this a sweep? Explains why `scanned` is suddenly much higher. */
-    fullSweep?: boolean;
-    /**
-     * A trial round: mapped and checked, but nothing written and no cursor moved.
-     *
-     * It reads **one page**, on purpose — a dry run is a sample that answers "does this mapping
-     * hold up", not an import. `written` therefore stays 0 and the rows that would have landed are
-     * counted as `skipped`; only rows the mapping could not produce count as `failed`.
-     */
-    dryRun?: boolean;
-    /** The error that stopped the whole run. Empty on `partial` — see {@link SyncRun.errors}. */
-    error?: string;
-    /**
-     * The first N failed rows, with their `externalId`.
-     *
-     * Bounded and not complete: a source where every row fails would otherwise produce a run row of
-     * megabytes. The goal is debugging ("which row, and why"), not bookkeeping.
-     */
-    errors?: {
-        externalId: string;
-        message: string;
-    }[];
-}
-/** How many failed rows a {@link SyncRun} remembers. */
-export declare const SYNC_RUN_MAX_ERRORS = 20;