@opencxh/domain 1.226.0 → 1.228.0

package/dist/platform/connector.d.ts

@@ -0,0 +1,426 @@
+import { SyncRecord } from './sync';
+/** The provider role group, as a constant so a typo does not silently yield an empty list. */
+export declare const CONNECTOR_PROVIDER_GROUP = "connector";
+/**
+ * What a connector can do with a kind — read by the UI instead of branching on a connector id.
+ *
+ * An empty list is a valid answer: it says "declared, but nothing works yet". Same shape and same
+ * reason as `StorageCapability`, which already proves it — the browser there asks what a backend
+ * supports rather than knowing which backend it is talking to.
+ *
+ * A capability without a route is a promise the caller cannot collect on, so each arrived with
+ * its route. `get` is the one a connector only declares when its records carry detail the
+ * headline deliberately omits — a Jira issue has a description, comments and custom fields; a
+ * To Do task has nothing the headline leaves out, and declares none.
+ */
+export type ConnectorCapability = "list" | "get" | "fields" | "write" | "comment" | "options";
+/**
+ * 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. Not every connector can do both.
+ */
+export type SyncMode = "continuous" | "once";
+/**
+ * One setting of a connection, as the connector 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 connector gets back on `list`. */
+    key: string;
+    label: string;
+    type: "text" | "number" | "boolean" | "select" | "multiselect";
+    required?: boolean;
+    /**
+     * Fixed choices, known when the connector was written.
+     *
+     * For anything the *account* decides — which projects, which boards, which folders — a static
+     * list cannot be honest, and that is what {@link SyncSettingsField.optionsFromConnector} is
+     * for. Only one of the two means anything per field.
+     */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /**
+     * Ask the connector for this field's choices, once an account is picked.
+     *
+     * The alternative is what this replaces: a text field where a person types project keys from
+     * memory, and a typo becomes an empty sync round with no error anywhere. The connector is the
+     * only side that can list them, and it can only do so with a credential — hence "once an
+     * account is picked" rather than at declaration time.
+     */
+    optionsFromConnector?: boolean;
+    /** 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 connector changing. A hint, not a promise.
+     */
+    resource?: string;
+    /**
+     * Rarely needed: the form hides it behind a collapsed "Advanced".
+     *
+     * Declared by the connector and not guessed by the form, because only the connector knows which
+     * of its settings are the everyday ones. A generic connector 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;
+}
+export interface ConnectorDefinition {
+    /**
+     * Stable and app-namespaced: `microsoft.todo`, `atlassian.jira`.
+     *
+     * 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 connector delivers: `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[];
+    /**
+     * What this connector can do. The UI reads this instead of branching on {@link
+     * ConnectorDefinition.id} — hardcoding per vendor breaks at vendor N+1.
+     */
+    capabilities: ConnectorCapability[];
+    /** Which modes this connector supports. Empty is pointless; at least one. */
+    modes: SyncMode[];
+    /**
+     * The `providerId` of the {@link ManagedAccount} this connector needs.
+     *
+     * Absent = no credential needed. 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;
+    /**
+     * 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 a connector app free of frontend files.
+     *
+     * Kept flat on purpose. A nested schema would turn into a mapping DSL, which was rejected
+     * earlier: date formats and enums differ per vendor, and errors move from `tsc` to runtime.
+     */
+    settingsSchema?: SyncSettingsField[];
+    /**
+     * 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 connector and not in the runtime, because only it 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 connector 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/connector/describe` — **not** wrapped in `ResponseFactory`
+ * (template: `MemorySourceDescription` and `AnalyticsSourceDescription`).
+ */
+export interface ConnectorDescribe {
+    /** The declaring app (== `manifest.name` == `req.source.app`). */
+    source: string;
+    connectors: ConnectorDefinition[];
+}
+/** `POST /provider/connector/list` — fetch one page. */
+export interface ConnectorListRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    /** So the connector can log and find its own per-connection state, if it has any. */
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    /**
+     * The settings of this connection, per {@link ConnectorDefinition.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 connector 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 connector may give fewer, never more. */
+    limit: number;
+}
+/** Answer to `POST /provider/connector/list`. This one *is* wrapped in `ResponseFactory`. */
+export interface ConnectorListResponse {
+    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 connector is rate-limited; wait at least this long before the next attempt.
+     *
+     * In milliseconds, like every other duration in this platform. A connector 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/connector/write` — apply a change in the system that owns the record.
+ *
+ * **This is not two-way sync.** Two-way is hard because both sides hold truth: conflicts, echo
+ * loops, delete detection. A proxy row holds none — it is an index. So a change is one remote
+ * call, and whatever comes back replaces what we had. Nothing to merge.
+ */
+export interface ConnectorWriteRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    /** The record to change, in the source system's own id space. */
+    externalId: string;
+    /**
+     * The change, in the **target app's** field names — the same vocabulary as
+     * {@link SyncRecord.data}, travelling the other way.
+     *
+     * The connector translates to vendor fields itself, exactly as it does on the way in. The
+     * runtime never learns a vendor field name; the moment it did it would stop being generic.
+     *
+     * `null` clears a field. Unlike the client-facing API there is no separate `clear` list here:
+     * this payload is assembled server-side, so a `null` survives the trip.
+     */
+    patch: Record<string, unknown>;
+}
+/** Answer to `POST /provider/connector/write`. Wrapped in `ResponseFactory`. */
+export interface ConnectorWriteResponse {
+    externalId: string;
+    /**
+     * The record as it now stands **at the source**, in the target app's field names.
+     *
+     * The whole reason the write returns anything: a vendor may refuse a field, round a date,
+     * or move a status somewhere else than asked. Storing what we sent instead of what they kept
+     * would make our index quietly disagree with the system that owns the record — and disagree
+     * in the direction of looking successful.
+     *
+     * Fields the connector does not mention are left as they are here.
+     */
+    data: Record<string, unknown>;
+}
+/**
+ * One editable field of a **record**, as the connector describes it.
+ *
+ * Deliberately not {@link SyncSettingsField}, which looks almost identical and answers a
+ * different question: that one configures a *connection* once, this one describes what a person
+ * may change on *a row*, and it is fetched per record context rather than declared in code.
+ *
+ * `key` is in the **target app's** vocabulary — the same field names as {@link SyncRecord.data}
+ * and {@link ConnectorWriteRequest.patch}. The vendor's own names never reach the runtime.
+ *
+ * Needed in three places and not one: the edit form, the list columns and filters, and turning a
+ * stored option id back into a label. Without the third, a screen shows `10004` where `Done`
+ * belongs.
+ */
+export interface FieldDescriptor {
+    key: string;
+    label: string;
+    type: "text" | "textarea" | "number" | "boolean" | "date" | "select";
+    /**
+     * The values this field accepts. Present means the UI shows a picker **and** can resolve an
+     * id to a label; absent means free input.
+     */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** `select` only: several at once — Jira's labels, a multi-select custom field. */
+    multiValued?: boolean;
+    /**
+     * What the record holds now, in the same vocabulary as {@link FieldDescriptor.options}.
+     *
+     * Here and not in {@link ConnectorGetResponse.extra} because this is the *editable* view: an
+     * editor has to start from the current value, and a display string cannot be edited back into
+     * an option id. A connector that only wants to show something uses `extra`.
+     */
+    value?: unknown;
+    required?: boolean;
+    /** Shown, never sent. A vendor field a person may read but not change. */
+    readOnly?: boolean;
+    help?: string;
+}
+/**
+ * `POST /provider/connector/fields` — what may be changed on a record like this one.
+ *
+ * Per context, not once per connector. Jira is the case that sets the shape: `/rest/api/3/field`
+ * is global, `createmeta` is per project and issue type, and `editmeta` is **per issue** — and
+ * that last one is the good answer for an existing record, because it also folds in the workflow
+ * and the reading user's permissions. A field a project admin may change is one a reporter may
+ * not, and a static list would promise fields the save then refuses.
+ *
+ * So all three of `externalId`, `containerExternalId` and `typeId` are optional and a connector
+ * uses what it has. `microsoft.todo` ignores all three and answers the same list every time.
+ */
+export interface ConnectorFieldsRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    /**
+     * The record itself, when there is one.
+     *
+     * Absent means "what could be filled in for a *new* record here". A connector whose schema
+     * narrows per record — by workflow, by permission — has a much better answer with it than
+     * without, so it travels whenever the caller has it.
+     */
+    externalId?: string;
+    /** The container this record lives in (the project, the board, the list). */
+    containerExternalId?: string;
+    /** The record type, where the vendor has more than one. */
+    typeId?: string;
+}
+/** Answer to `POST /provider/connector/fields`. Wrapped in `ResponseFactory`. */
+export interface ConnectorFieldsResponse {
+    fields: FieldDescriptor[];
+}
+/**
+ * `POST /provider/connector/get` — the detail a headline leaves out.
+ *
+ * Deliberately *not* the same shape as a {@link SyncRecord}: nothing here is stored. This is what
+ * a screen renders while it is open, and the reason the row underneath can stay thin.
+ */
+export interface ConnectorGetRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    externalId: string;
+}
+/** One comment on a record, flattened to what a reader needs. */
+export interface ConnectorComment {
+    id: string;
+    /** The author's display name. Never an account id — that says nothing to a reader. */
+    author: string;
+    /** Plain text. Vendor markup is flattened by the connector, which is the only side that knows it. */
+    body: string;
+    /** Epoch ms. */
+    createdAt?: number;
+}
+/** Answer to `POST /provider/connector/get`. Wrapped in `ResponseFactory`. */
+export interface ConnectorGetResponse {
+    /** Plain text. Empty is a valid answer and means the record has none. */
+    description?: string;
+    comments?: ConnectorComment[];
+    /** A deep link into the source system, so a person can always go to the real thing. */
+    url?: string;
+    /**
+     * Anything else the connector wants to show, already labelled.
+     *
+     * An escape hatch on purpose: a vendor's custom fields have no place in our schema and no
+     * meaning to the runtime, but a person reading the issue expects to see them.
+     */
+    extra?: {
+        label: string;
+        value: string;
+    }[];
+}
+/**
+ * `POST /provider/connector/options` — the choices for one settings field.
+ *
+ * Separate from {@link ConnectorFieldsRequest}, which describes the fields of a *record*. This
+ * one describes the choices for a field of the *connection* — asked while somebody is still
+ * configuring it, so before there is a connection at all.
+ */
+export interface ConnectorOptionsRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    /** The settings filled in so far: one field's choices may depend on another's value. */
+    settings?: Record<string, unknown>;
+    /** → {@link SyncSettingsField.key} */
+    field: string;
+}
+/** Answer to `POST /provider/connector/options`. Wrapped in `ResponseFactory`. */
+export interface ConnectorOptionsResponse {
+    options: {
+        value: string;
+        label: string;
+    }[];
+}
+/**
+ * `POST /provider/connector/comment` — say something on the record, where it lives.
+ *
+ * Its own capability rather than a field on {@link ConnectorWriteRequest}, because a comment is
+ * not a field: it is appended, never replaced, and a vendor that lets you edit a summary may not
+ * let you comment at all. A connector that cannot do it simply does not declare it, and the
+ * screen keeps the comment local instead of pretending it travelled.
+ */
+export interface ConnectorCommentRequest {
+    /** → {@link ConnectorDefinition.id} */
+    sourceId: string;
+    connectionId: string;
+    /** The {@link ManagedAccount} to talk with. Absent when no credential is needed. */
+    accountId?: string;
+    settings?: Record<string, unknown>;
+    /** From {@link ConnectorDefinition.kinds}. */
+    kind: string;
+    externalId: string;
+    /**
+     * Plain text.
+     *
+     * The connector converts to whatever its vendor wants — Jira needs a document, Slack needs
+     * its own blocks — because it is the only side that knows. The runtime never learns a markup.
+     */
+    body: string;
+}
+/** Answer to `POST /provider/connector/comment`. Wrapped in `ResponseFactory`. */
+export interface ConnectorCommentResponse {
+    /** As the source stored it, so the screen shows what is really there. */
+    comment: ConnectorComment;
+}

package/dist/platform/sync.d.ts

@@ -0,0 +1,225 @@
+import { OwnerScope } from '../entities/scope/types';
+import { SyncMode } from './connector';
+/** The provider role group, as a constant so a typo does not silently yield an empty list. */
+export declare const SYNC_TARGET_PROVIDER_GROUP = "sync-target";
+/**
+ * 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 `ConnectorDefinition.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>;
+    /**
+     * Who owns what lands here, stamped by the source from the connection settings.
+     *
+     * Envelope, not data, and stamped by `registerSyncTarget` next to `externalId`. It comes from
+     * the connection and not from the vendor, so no source field can ever produce it.
+     */
+    ownerScope?: OwnerScope;
+    /**
+     * 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/land` — write these records. App callers only. */
+export interface SyncLandRequest {
+    /** Where they came from, for `source`/attribution on the landed row. */
+    sourceId: string;
+    /**
+     * Which connection delivered them. The landing app stores it on a proxied row, because that
+     * is what tells a later edit *which* credential to write back with — two connections to the
+     * same product are two different answers.
+     */
+    connectionId?: string;
+    /**
+     * These records are a **headline index**, not a copy: their truth stays at the source.
+     *
+     * The landing app stores only the columns it was given and renders the rest live, and an edit
+     * is written back instead of applied locally. Per connection and not per record: "who owns
+     * this data" is a decision about the link, not something a row can differ on.
+     */
+    proxy?: boolean;
+    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[];
+}
+/**
+ * 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[];
+}
+/** 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;
+    /** → `ConnectorDefinition.id` */
+    sourceId: string;
+    /** → {@link ManagedAccount.id}. Absent for a source without a credential. */
+    accountId?: 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>;
+    /** Free-form name; absent = the source's label. */
+    label?: string;
+    mode: SyncMode;
+    enabled: boolean;
+    /**
+     * Minimum time between two rounds, in ms.
+     *
+     * Copied from `ConnectorDefinition.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;
+    /**
+     * This connection is a proxy: keep the headline, render the rest live, write edits back.
+     *
+     * Absent or false = an ordinary import, where a landed row becomes ours. The two modes differ
+     * in who owns the truth, which is why it is one flag and not a spectrum.
+     */
+    proxy?: boolean;
+    /** Opaque, from the connector. See `ConnectorListRequest.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 source
+     * still deliver what we expect", not an import. `written` therefore stays 0 and the rows that
+     * would have landed are counted as `skipped`.
+     */
+    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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.226.0",
+  "version": "1.228.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",