@opencxh/domain 1.164.0 → 1.165.0

package/dist/platform/account.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Laag 1 van de integratielagen: **Account** — het credential.
+ *
+ * Vier lagen, en dit is de onderste:
+ * | Laag | Vraag | Woord |
+ * |---|---|---|
+ * | 1 Credential | mag ik erin? | **Account** (`ManagedAccount`) |
+ * | 2 Connector | waar is het, welk protocol? | **Connector** (`McpServerEntity`) |
+ * | 3 Capability | wat kan ik ermee? | **Source** (`sync-source`, `memory-source`, …) |
+ * | 4 Usage | staat het aan, met welke instellingen? | **Connection** (`SyncConnection`, `Channel`) |
+ *
+ * `ManagedAccount` is een **platform**-primitive, niet een comms-entiteit — dat het type
+ * historisch in `entities/communication/types.ts` stond kwam alleen doordat de *store* daar
+ * woont. De store blijft in comms (daar zitten de scope-guard en de OAuth-orchestrator);
+ * het type hoort hier, want ai, mail, ftp, s3, google en microsoft hangen er allemaal aan.
+ *
+ * ## Niet verwarren met een Registration
+ *
+ * `google_account`, `microsoft_account`, `shopify_account`, `slack_account` en `meta_app` zijn
+ * GEEN accounts in deze zin. Dat zijn **registraties**: de clientId/clientSecret waarmee de
+ * organisatie zichzelf bij de vendor aanmeldt. Eén registratie draagt N accounts. Ze delen
+ * alleen het woord.
+ *
+ * ## Scope: `userId` is de enige eigendom-as
+ *
+ * `userId` afwezig/`null` = org-breed, gedeeld. Gezet = persoonlijk, van die ene gebruiker.
+ * Er is bewust **geen** `ownerScope` en **geen** `createdBy` op een credential:
+ * - `ownerScope` (`personal`/`team`/`org`) is de as van een *resource* — met wie deel ik dit
+ *   contact, werkitem of geheugen. Een token heeft geen teamvariant.
+ * - "wat eist de vendor" (één gedeeld token vs. iedereen zijn eigen) is een eigenschap van de
+ *   **connector**, niet van de accountrij: zie `credentialScope` in `entities/mcp/types.ts`.
+ */
+export type AuthState = {
+    type: "oauth2";
+    accessToken: string;
+    refreshToken?: string;
+    /** Epoch ms */
+    expiresAt: number;
+    scopes: string[];
+    idToken?: string;
+} | {
+    type: "password";
+    username: string;
+    /** Rauw wachtwoord (geen secret-store in repo). Alleen via internal-path. */
+    password: string;
+    /** Toekomstige secret-store-referentie i.p.v. raw `password`. */
+    passwordRef?: string;
+} | {
+    type: "certificate";
+    certRef: string;
+} | {
+    type: "apikey";
+    /** Rauwe API-key (geen secret-store in repo). Alleen via internal-path. */
+    apiKey: string;
+} | {
+    type: "static";
+};
+export type ManagedAccountStatus = "connected" | "disconnected" | "error" | "expired";
+export interface ManagedAccount {
+    id: string;
+    organizationId: string;
+    /**
+     * Afwezig/`null` = org-breed gedeeld account. Gezet = persoonlijk account van die gebruiker.
+     * De enige eigendom-as op dit niveau — zie de moduledoc.
+     */
+    userId?: string;
+    providerId: string;
+    /** "oauth2" | "imap" | "sip" | "webhook" | "apikey" | provider-eigen string */
+    protocol: string;
+    displayName: string;
+    status: ManagedAccountStatus;
+    auth: AuthState;
+    /** Provider-specifieke metadata (tenantId, externalUserId, scope-flags). */
+    metadata: Record<string, unknown>;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/**
+ * Public-view zonder tokens — wat `account/list` en `account/get` aan UI/comm-server
+ * retourneren. `auth` is gestript tot alleen het type.
+ *
+ * **Leesasymmetrie, en dit is de valkuil:** de publieke `account/list` filtert op de
+ * *huidige* gebruiker, dus een job of cron (die geen sessie heeft) ziet daar niets — ook
+ * geen org-brede rijen. Server-side code die accounts moet zien gebruikt altijd de
+ * `account-internal/`-route (`listManagedAccountsInternal` / `getManagedAccountInternal`).
+ */
+export type ManagedAccountPublic = Omit<ManagedAccount, "auth"> & {
+    authType: AuthState["type"];
+    scopes?: string[];
+    expiresAt?: number;
+};

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

@@ -0,0 +1,442 @@
+/**
+ * Data van buiten naar binnen halen, één keer geregeld.
+ *
+ * Het platform ingest vandaag op vier onafhankelijke manieren — een cron-sync per provider-app,
+ * webhooks, een event-driven verrijkingsjob en losse backfills — en elk van die vier herbouwt
+ * zelfstandig dezelfde zes dingen: cursor, batching, locking, idempotentie, foutafhandeling en
+ * observability. Dat is te zien: `cursorKey()` staat drie keer los in de repo,
+ * `microsoft_sync_state` groeit per sub-sync een kolom, en een sync die stilvalt is een
+ * `console.error` die niemand ziet.
+ *
+ * De splitsing die dat oplost is de industriestandaard (Singer/Airbyte, Nango, Fivetran): **een
+ * smal bron-contract met een dikke generieke runtime.** De bron weet hoe je één pagina uit
+ * Microsoft Graph of Asana haalt; de runtime weet hoe je cursors checkpoint, batches
+ * doorschakelt, backoff doet en er een run-log van bijhoudt. Dit bestand is dat smalle contract.
+ *
+ * Drie endpoints, in de vorm van `memory-source` en `analytics-source` — dus een providerrol en
+ * geen servicebus-sleutel, want dit draait server-side zonder gebruiker erbij:
+ *
+ * | Rol | Endpoint | Antwoord |
+ * |---|---|---|
+ * | `sync-source` | `GET /provider/sync/describe` | {@link SyncSourceDescribe} |
+ * | `sync-source` | `POST /provider/sync/pull` | {@link SyncPullResponse} |
+ * | `sync-target` | `POST /provider/sync/land` | {@link SyncLandResponse} |
+ *
+ * Bron en doel zijn **losse rollen**: `apps/microsoft` levert records en landt niets,
+ * `apps/work` landt records en levert niets. Een app mag beide zijn, maar hoeft dat niet.
+ */
+/** De providerrol-groepen, als constante zodat een typefout niet stil een lege lijst oplevert. */
+export declare const SYNC_SOURCE_PROVIDER_GROUP = "sync-source";
+export declare const SYNC_TARGET_PROVIDER_GROUP = "sync-target";
+/**
+ * Continu of eenmalig — en dat is een echt verschil, geen label.
+ *
+ * `continuous` draait op een tik en moet dus goedkoop kunnen niksdoen (een cursor die zegt
+ * "niets nieuws"). `once` wordt door een mens gestart, mag duur zijn, en moet **uitputtend**
+ * zijn: een migratie die 95% ophaalt is geen migratie. Die eis is precies waarom niet elke bron
+ * beide kan — zie {@link SyncSourceDefinition.transport}.
+ */
+export type SyncMode = "continuous" | "once";
+/**
+ * Hoe de records feitelijk binnenkomen.
+ *
+ * Dit staat in het contract omdat het de verwachtingen bepaalt die de runtime en de UI mogen
+ * hebben, niet als documentatie:
+ *
+ * - **`native`** — de app praat zelf met de API van de leverancier. Kent delta-tokens en
+ *   pagination, dus geschikt voor `continuous` én `once`.
+ * - **`tool`** — de app gaat via de AI-tool/MCP-laag. Prima voor de lange staart aan systemen
+ *   waarvoor een eigen connector niet loont, maar een MCP-zoektool antwoordt "top-N relevant"
+ *   en niet "alles sinds X", en het protocol kent geen change-token. Een `tool`-bron die
+ *   `once` claimt belooft volledigheid die hij niet kan leveren.
+ * - **`file`** — een geüpload bestand (CSV). Per definitie `once`, en per definitie volledig.
+ */
+export type SyncTransport = "native" | "tool" | "file";
+/** Eén ding dat een app van buiten kan halen. */
+/**
+ * Eén instelling van een koppeling, zoals de bron hem declareert.
+ *
+ * Bewust geen ui-kit-types hier: `packages/domain` heeft geen UI-afhankelijkheden, en het
+ * formulier mapt deze declaratie zelf op zijn eigen velden.
+ */
+export interface SyncSettingsField {
+    /** Sleutel in het settings-object dat de bron bij `pull` terugkrijgt. */
+    key: string;
+    label: string;
+    type: "text" | "number" | "boolean" | "select";
+    required?: boolean;
+    /** Alleen bij `type: "select"`. */
+    options?: {
+        value: string;
+        label: string;
+    }[];
+    /** Uitleg onder het veld. Voor "leeg = ..."-gevallen, die anders raadwerk zijn. */
+    help?: string;
+    /**
+     * Hint dat deze waarde een resource in een andere app aanwijst (`"work_project"`).
+     *
+     * Vandaag rendert het formulier hem als tekstveld; de hint staat er zodat een picker later
+     * toegevoegd kan worden zonder dat de bron verandert. Een hint en geen belofte.
+     */
+    resource?: string;
+}
+export interface SyncSourceDefinition {
+    /**
+     * Stabiel en app-genamespaced: `microsoft.todo`, `asana.tasks`, `csv.contacts`.
+     *
+     * Dit is een **opgeslagen verwijzing** — `SyncConnection.sourceId` bewaart hem — dus
+     * hernoemen breekt bestaande koppelingen. Punt als scheidingsteken, zoals `MemoryKindId`
+     * voor app-eigen kinds.
+     */
+    id: string;
+    label: string;
+    description?: string;
+    /**
+     * De scope-soorten die deze bron landt: `work_item`, `interaction`, `company`, `contact`.
+     *
+     * Hetzelfde vocabulaire als `ScopeDescribe.kinds`, en dat is geen cosmetische keuze — de
+     * runtime routeert een record naar de bezittende app met `findScopeOwner(kind)`. Een soort
+     * die geen scope-eigenaar heeft, kan dus niet geland worden, en dat merk je bij het
+     * registreren in plaats van halverwege een run.
+     */
+    kinds: string[];
+    /** Welke modi deze bron ondersteunt. Leeg is zinloos; minstens één. */
+    modes: SyncMode[];
+    transport: SyncTransport;
+    /**
+     * De `providerId` van de {@link ManagedAccount} die deze bron nodig heeft.
+     *
+     * Afwezig = geen credential nodig (een bestand-upload). Aanwezig betekent dat een koppeling
+     * niet werkt zonder gekozen account, en dat de UI dat vóór de eerste run kan zeggen in
+     * plaats van een mislukte run te laten zien.
+     */
+    accountProviderId?: string;
+    /**
+     * Instellingen die per koppeling verschillen en dus niet in code horen.
+     *
+     * Declaratief, zodat een connector-app **geen frontend nodig heeft** om configureerbaar te
+     * zijn: het Koppelingen-formulier rendert deze velden. Dat is wat `apps/asana` (nul
+     * frontend-bestanden) mogelijk houdt.
+     *
+     * Plat gehouden met opzet. Een genest schema zou een mapping-DSL worden, en die is eerder
+     * afgewezen: datumformaten en enums verschillen per bron, en fouten verschuiven dan van `tsc`
+     * naar runtime.
+     */
+    settingsSchema?: SyncSettingsField[];
+    /**
+     * Alleen bij `transport: "tool"`: de catalogus-sleutel waarop de connector-picker
+     * voorfiltert (`"asana"`, `"linear"`).
+     *
+     * Een **hint**, geen resolutie: hij bepaalt welke van de MCP-verbindingen van de
+     * organisatie als kandidaat worden voorgesteld. Wat de koppeling daarna bewaart is het
+     * connector-**id** ({@link SyncConnection.connectorId}). Zonder hint krijgt de gebruiker
+     * simpelweg de volledige lijst.
+     */
+    connectorHint?: string;
+    /**
+     * Alleen bij `transport: "tool"`: deze bron kan alleen draaien op een gedeeld
+     * organisatie-credential.
+     *
+     * Waarom dit bestaat: een onbemande ronde (cron, sync) heeft geen handelende gebruiker, dus
+     * een connector met `credentialScope: "per-user"` levert daar per definitie nul tools — en dat
+     * zag je vroeger alleen als "de sync doet niets". Met deze vlag weigert het opslaan van een
+     * `continuous`-koppeling meteen, met een uitleg.
+     *
+     * Alleen voor `continuous`: een `once`-koppeling start een mens, en dan is er wél een
+     * handelende gebruiker wiens token gebruikt kan worden.
+     */
+    requiresCredentialScope?: "shared";
+    /**
+     * Aanbevolen minimale tijd tussen twee rondes, in ms. De organisatie mag hem overschrijven.
+     *
+     * Een **interval** en geen cron-expressie, omdat dat is wat er daadwerkelijk uitvoerbaar is:
+     * `JobOptions.schedule` staat vast bij registratie, dus een cron-string per koppeling zou
+     * nooit geëvalueerd worden — een veld dat belooft wat het niet doet. De runtime tikt op een
+     * grof raster en poort daarop.
+     *
+     * Bij de bron en niet in de runtime, omdat alleen de bron weet wat zijn API verdraagt: een
+     * delta-feed mag elke minuut, een lijst-endpoint dat elke keer alles teruggeeft niet.
+     */
+    defaultIntervalMs?: number;
+    /**
+     * Hoe vaak de bron zijn cursor moet negeren en alles opnieuw lezen (ms).
+     *
+     * De reconcile-sweep uit het Stripe/Shopify-patroon, en in deze codebase al bewezen als
+     * `CHAT_FULL_SWEEP_INTERVAL_MS`: cursors rusten op de aanname dat de leverancier een
+     * `updatedAt` bumpt voor alles wat telt, en dat houdt voor nieuwe records maar is
+     * onbetrouwbaar voor edits en verwijderingen. Afwezig = nooit vegen (juist voor een
+     * delta-feed die verwijderingen zelf meldt).
+     */
+    fullSweepIntervalMs?: number;
+}
+/**
+ * Bare payload van `GET /provider/sync/describe` — **niet** in `ResponseFactory` verpakt
+ * (mal: {@link MemorySourceDescription} en `AnalyticsSourceDescription`).
+ */
+export interface SyncSourceDescribe {
+    /** De declarerende app (== `manifest.name` == `req.source.app`). */
+    source: string;
+    sources: SyncSourceDefinition[];
+}
+/**
+ * Eén record uit een bronsysteem, klaar om geland te worden.
+ *
+ * De bron doet de mapping naar de vorm die de doel-app verwacht. Dat is bewust: de runtime kent
+ * geen enkel veld van geen enkele leverancier, en zodra hij dat wél zou doen is hij niet meer
+ * generiek. Zie {@link SyncRecord.data}.
+ */
+export interface SyncRecord {
+    /**
+     * Het stabiele id in het bronsysteem, genamespaced door de bron zelf
+     * (`asana_task:12345`, `graph-todo:AAMk…`).
+     *
+     * Dit is de dedupe-as: de doel-app upsert hierop via zijn
+     * `upsert_by_external_provider_id`-route, dus dezelfde run twee keer draaien schrijft één
+     * rij. "Stabiel" is de hele eis — een id dat per pagina verandert maakt van elke sync een
+     * duplicaat-fabriek.
+     */
+    externalId: string;
+    /**
+     * Ids die de **container** aanwijzen en niet deze rij: de lijst, het project, het board.
+     *
+     * Ze worden wél bewaard (uitgaande dispatch heeft ze nodig) maar mogen nooit meedoen in de
+     * dedupe. Dit veld bestaat omdat het al één keer fout is gegaan: Microsoft Graph stuurt
+     * naast het taak-id ook `graph-todolist:<id>`, dat voor élke taak in die lijst hetzelfde is,
+     * en zoeken daarop klapte de hele lijst op één rij (`task/external-ids.ts`). Daar is het
+     * met een prefix-lijst gerepareerd; hier zegt de bron het zelf, zodat die lijst niet hoeft
+     * te groeien.
+     */
+    containerExternalIds?: string[];
+    /** De scope-soort, uit {@link SyncSourceDefinition.kinds}. Bepaalt naar welke app dit gaat. */
+    kind: string;
+    /**
+     * De velden voor de doel-app.
+     *
+     * **Vaste veldnamen, nooit een map met een extern id als sleutel.** De SDK-client mangelt
+     * object-sleutels tussen camel- en snake-case, dus data die ín een sleutel zit komt
+     * verminkt aan. Dezelfde les die `chatCursors` een lijst maakte en `ContactSource.sourceId`
+     * een veldwaarde.
+     */
+    data: Record<string, unknown>;
+    /**
+     * Dit record is bij de bron verwijderd.
+     *
+     * Alleen zinvol als de bron dat kán weten: een delta-feed meldt verwijderingen, een
+     * lijst-endpoint laat ze simpelweg weg. Afwezigheid uit een lijst is géén verwijdering —
+     * dat verschil niet respecteren betekent dat een gefilterde of gepagineerde respons je
+     * halve administratie opruimt.
+     */
+    deleted?: boolean;
+}
+/** `POST /provider/sync/pull` — haal één pagina op. */
+export interface SyncPullRequest {
+    sourceId: string;
+    /** Zodat de bron kan loggen en zijn eigen per-koppeling state kan vinden als hij die heeft. */
+    connectionId: string;
+    /** De {@link ManagedAccount} om mee te praten. Afwezig bij `transport: "file"`. */
+    accountId?: string;
+    /**
+     * Bij `transport: "tool"`: het id van de MCP-connector die deze koppeling mag gebruiken,
+     * gekozen tóen de koppeling werd geconfigureerd.
+     *
+     * Hiermee is de toolnaam een pure string — `mcpToolPrefix(connectorId) + toolnaam` — en is
+     * er per pagina géén resolutie-RPC nodig. Eerder zocht een bron zijn connector op
+     * catalogus-sleutel op, en dat kon bij twee kandidaten (een org-rij naast een persoonlijke,
+     * of twee gebruikers met elk hun eigen) geen winnaar kiezen; een app kon zelfs het prefix
+     * van iemands persoonlijke connector krijgen.
+     */
+    connectorId?: string;
+    /**
+     * De instellingen van deze koppeling, volgens {@link SyncSourceDefinition.settingsSchema}.
+     *
+     * Een **object** hier en een JSON-string in de opslag. Let op: dat is NIET omdat de
+     * SDK-client uitgaande sleutels zou mangelen — dat doet hij niet, de verzendkant is
+     * `removeUndefined` + `JSON.stringify`. Alleen *antwoorden* worden gecamelCase't. De string in
+     * de opslag is er om dezelfde reden als de cursor: één schemaveld dat elke vorm moet kunnen
+     * dragen.
+     */
+    settings?: Record<string, unknown>;
+    /**
+     * Opaak, exact zoals de bron hem vorige keer teruggaf. `undefined` = vanaf het begin.
+     *
+     * **De runtime kijkt er nooit in.** Een Graph `deltaLink`, een tijdstempel, een
+     * pagina-token — het maakt niet uit, en juist daarom hoeft er geen kolom per sub-sync te
+     * bestaan. Dat `microsoft_sync_state` vandaag `todoDeltaLink` náást `chatCursors` náást
+     * `chatFullSweepAt` heeft, is precies wat een opaak veld voorkomt.
+     */
+    cursor?: unknown;
+    /** Negeer de cursor en lees alles opnieuw — de reconcile-sweep. */
+    fullSweep?: boolean;
+    /** Maximum aantal records in dit antwoord. De bron mag minder geven, nooit meer. */
+    limit: number;
+}
+/** Antwoord op `POST /provider/sync/pull`. Wél in `ResponseFactory` verpakt. */
+export interface SyncPullResponse {
+    records: SyncRecord[];
+    /**
+     * De cursor ná deze pagina. De runtime bewaart hem **pas nadat de records geland zijn**.
+     *
+     * Dat is de Singer/Airbyte-regel en de reden dat crash-herstel werkt: valt de boel om
+     * tussen pull en land, dan wordt de batch herhaald (idempotent, want upsert op
+     * `externalId`) in plaats van overgeslagen. Andersom — cursor eerst — verlies je records
+     * stil, en stil is hier het probleem.
+     */
+    cursor?: unknown;
+    /** Geen data meer na deze pagina. De runtime schakelt dan niet door. */
+    done: boolean;
+    /**
+     * De bron is gerate-limit; wacht minstens zo lang voor de volgende poging.
+     *
+     * In milliseconden, zoals elke andere duur in dit platform. Een bron die dit vult in
+     * plaats van te gooien, houdt de run `partial` in plaats van `failed` — het is uitstel,
+     * geen fout.
+     */
+    retryAfterMs?: number;
+}
+/** `POST /provider/sync/land` — schrijf deze records weg. Alleen app-callers. */
+export interface SyncLandRequest {
+    /** Waar ze vandaan komen, voor `source`/attributie op de gelande rij. */
+    sourceId: string;
+    records: SyncRecord[];
+}
+/** Wat er met één record gebeurde. */
+export interface SyncLandOutcome {
+    externalId: string;
+    /**
+     * `created` en `updated` zijn beide "geschreven"; `unchanged` bestaat apart omdat een
+     * idempotente resync die niets veranderde géén SSE-ruis mag maken en niet als werk mag
+     * tellen (het patroon uit `lib/upsert-dedup.ts`). `failed` is één rij, niet de batch.
+     */
+    result: "created" | "updated" | "unchanged" | "deleted" | "failed";
+    /** De scopeKey van de gelande rij, zodat de run-log naar het resultaat kan linken. */
+    scopeKey?: string;
+    /** Alleen bij `failed`. Kort genoeg voor een tabelregel. */
+    error?: string;
+}
+/** Antwoord op `POST /provider/sync/land`. Wél in `ResponseFactory` verpakt. */
+export interface SyncLandResponse {
+    outcomes: SyncLandOutcome[];
+}
+/**
+ * Bare payload van `GET /provider/sync/land-describe`: welke soorten deze app kan landen.
+ *
+ * Apart van `ScopeDescribe`, ook al overlappen de soorten meestal: een app kan een soort
+ * autoriseren zonder er een ingest-route voor te hebben. Dat verschil zichtbaar maken is
+ * goedkoper dan een run die halverwege een 404 vindt.
+ */
+export interface SyncTargetDescribe {
+    source: string;
+    kinds: string[];
+}
+/** Hoe gezond een koppeling is. Wat de lijst als badge toont. */
+export type SyncHealth = 
+/** Laatste run geslaagd. */
+"ok"
+/** Laatste run deels geslaagd, of gerate-limit. Loopt nog, maar niet schoon. */
+ | "degraded"
+/** Laatste run gefaald — meestal een verlopen credential. Vraagt een mens. */
+ | "broken"
+/** Nooit gedraaid, of een verplicht account ontbreekt. Nog geen fout. */
+ | "unconfigured";
+/**
+ * Eén geconfigureerde koppeling: deze bron, met dit account, in deze organisatie.
+ *
+ * De credential zit hier **niet** in — `accountId` verwijst naar de canonieke
+ * {@link ManagedAccount}-store. Een tweede plek waar tokens leven is een tweede plek waar ze
+ * verlopen zonder dat iemand het weet.
+ */
+export interface SyncConnection {
+    id: string;
+    organizationId: string;
+    /** → {@link SyncSourceDefinition.id} */
+    sourceId: string;
+    /** → {@link ManagedAccount.id}. Afwezig bij een bron zonder credential. */
+    accountId?: string;
+    /**
+     * Bij `transport: "tool"`: de gekozen MCP-connector. Expliciet, niet run-time geraden —
+     * zo is in de UI te zien welke verbinding deze koppeling gebruikt, en verandert het antwoord
+     * niet doordat iemand anders dezelfde catalogus-entry toevoegt.
+     *
+     * Is de rij weg of uitgezet, dan gaat de koppeling naar `health: "unconfigured"` en faalt de
+     * run luid — nooit een stille lege pagina waarop de cursor doorschuift.
+     */
+    connectorId?: string;
+    /**
+     * De ingevulde instellingen, geparsed. In de opslag staat hij als JSON-string, om dezelfde
+     * reden als de cursor: één schemaveld dat elke vorm moet kunnen dragen. **Niet** vanwege
+     * sleutel-mangeling — de client transformeert uitgaande sleutels niet.
+     */
+    settings?: Record<string, unknown>;
+    /** Vrije naam; afwezig = het label van de bron. */
+    label?: string;
+    mode: SyncMode;
+    enabled: boolean;
+    /**
+     * Minimale tijd tussen twee rondes, in ms.
+     *
+     * Bij het aanmaken gekopieerd uit {@link SyncSourceDefinition.defaultIntervalMs}, zodat de
+     * tik hem kan lezen zonder per koppeling de bron-catalogus te bevragen — en zodat het
+     * effectieve interval te zien en te wijzigen is in plaats van ergens in code te zitten.
+     */
+    intervalMs?: number;
+    /** Opaak, van de bron. Zie {@link SyncPullRequest.cursor}. */
+    cursor?: unknown;
+    /** Epoch ms van de laatste volledige veegronde. */
+    lastFullSweepAt?: number;
+    health: SyncHealth;
+    lastRunAt?: number;
+    /** De fout van de laatste gefaalde run, zodat de lijst hem kan tonen zonder een run te lezen. */
+    lastError?: string;
+    createdBy?: string;
+    createdAt?: number;
+    updatedAt?: number;
+}
+/** Waardoor een run begon. */
+export type SyncRunTrigger = "cron" | "manual" | "webhook";
+/**
+ * `partial` bestaat naast `done` en `failed` omdat "12 van de 500 rijen deden het niet" geen
+ * van beide is: de koppeling werkt, de cursor mag opschuiven, en er is toch iets om te melden.
+ * Zonder die derde staat wordt het óf een fout die de sync stilzet óf een succes dat de fouten
+ * verzwijgt.
+ */
+export type SyncRunStatus = "running" | "done" | "partial" | "failed";
+/**
+ * Wat er tijdens één ronde gebeurde.
+ *
+ * Bewust dezelfde vorm als `PlaybookRun`: het is dezelfde vraag ("wat deed het systeem
+ * ongevraagd, en ging het goed?"), dus dezelfde velden en dezelfde schermen.
+ */
+export interface SyncRun {
+    id: string;
+    organizationId: string;
+    connectionId: string;
+    sourceId: string;
+    trigger: SyncRunTrigger;
+    status: SyncRunStatus;
+    startedAt: number;
+    finishedAt?: number;
+    /** Hoeveel pagina's deze run gelezen heeft. Verraadt een bron die niet opschiet. */
+    pages: number;
+    scanned: number;
+    /** `created` + `updated`. Expliciet niet `unchanged`, anders lijkt een lege resync werk. */
+    written: number;
+    /** `unchanged` — de gezonde uitkomst van een idempotente resync. */
+    skipped: number;
+    failed: number;
+    /** Was dit een veegronde? Verklaart waarom `scanned` ineens veel hoger is. */
+    fullSweep?: boolean;
+    /** De fout die de hele run stopte. Bij `partial` leeg — die staan in {@link SyncRun.errors}. */
+    error?: string;
+    /**
+     * De eerste N mislukte rijen, met hun `externalId`.
+     *
+     * Begrensd en niet volledig: een bron waarvan élke rij faalt zou anders een run-rij van
+     * megabytes opleveren. Het doel is debuggen ("welke rij, en waarom"), niet boekhouden.
+     */
+    errors?: {
+        externalId: string;
+        message: string;
+    }[];
+}
+/** Hoeveel mislukte rijen een {@link SyncRun} onthoudt. */
+export declare const SYNC_RUN_MAX_ERRORS = 20;

package/package.json

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