@dossier-wiki/os-sdk 0.7.0 → 1.4.0

package/README.md

@@ -22,7 +22,7 @@ const os = new DossiersOSAPIService({
 
 const customer = await os.individuals.get('cus_123', { isExternal: true });
 
-await os.individuals.identificationDocuments.add(customer.id, {
+await os.individuals.identificationDocuments.create(customer.id, {
     type: 'passport',
     number: 'X1234567',
     country: 'USA',
@@ -42,25 +42,341 @@ The service composes resource namespaces — call them off the root client:
 | Namespace | Covers |
 | --- | --- |
 | `os.auth` | Invitations, session tokens, API keys, admin password reset |
+| `os.sessions` | Read and manage transaction-monitoring sessions resolved during ingestion |
+| `os.channelEndpoints` | Read and manage POS terminal, page, API client, and other endpoint identities resolved during ingestion |
 | `os.individuals` | Individual customers + nested `identificationDocuments`, `faceImages` |
 | `os.entities` | Entity customers + nested `stakeholders` |
-| `os.customers` | Cross-cutting per-customer: `notes`, `files`, `screening`, `riskRating`, `riskQuestionnaires`, `expectedActivity`, `devices` |
+| `os.customers` | Cross-cutting per-customer: `notes`, `files`, `screening`, `riskRating`, `riskAssessments`, `expectedActivity`, `devices`, `assignment` (assign / unassign / assignMany) |
+| `os.teams` | Domain teams: list/get/create/update/archive/delete, plus `addMembers` / `removeMembers`. Teams carry catalogue-governed `team.tags`, and `list({ tags })` filters on them |
 | `os.accounts` | Per-customer accounts, including `freeze` / `unfreeze` |
 | `os.counterparties` | Counterparties + nested `riskAssessments`, `files` |
-| `os.devices` | Direct device lookup |
-| `os.transactions` | Ingest transactions, patch terminal status |
-| `os.events` | Event ingestion |
+| `os.partyRelationships` | Define, list, create, and end audited named relationships between Customers and Counterparties |
+| `os.devices` | Safe canonical Device lookup and audited merge; raw fingerprint/IP identity material is never returned |
+| `os.paymentInstruments` | Explicit Payment Instrument CRUD and temporal Account/Customer relationships |
+| `os.transactions` | Ingest transactions with canonical Payment Instrument, channel endpoint, device, and session context (the response carries the resolved `transaction`; optionally with catalogue-governed `tags`, e.g. `['top-up']`, readable by rules as `txn.tags` and filterable inside aggregates); patch terminal status; `get(reference)` to read one back (by your reference, or `{ by: 'id' }` for the internal UUID) |
+| `os.transactionAttempts` | Ingest, filter, paginate, and read failed, blocked, or unknown payment-operation attempts |
+| `os.behaviorSettings` | Attempt retention and ingestion coverage |
+| `os.events` | Event ingestion — every event names the single `resource` it is about |
+| `os.riskSignals` | Add time-decaying risk evidence to a resource; read a resource's signals and their aggregate effective weight |
+| `os.employees` | People acting inside the institution's ecosystem — list/get/create/update |
+| `os.branches` | The institution's own physical or organizational units — list/get/create/update |
 | `os.exchangeRates` | Push exchange rates |
-| `os.config` | `rules`, `constants`, `products`, `currencies`, `eventDefinitions`, `webhooks`, `tagCatalogue`, `sync`, plus org-wide `reset` |
+| `os.states` | Read and atomically set, increment, or decrement resource state; read immutable change history |
+| `os.alerts` | Raise alerts by hand (`create` — free-form, or against an optional custom alert type; org-scoped `externalRequestId` idempotency), read any alert (`get`), edit markdown `notes` (`updateNotes`), link records (`resources.list/add/remove`), plus `comments` and `attemptEvidence`. Needs the `alerts:read` / `alerts:write` API-key permissions |
+| `os.config` | `rules` (incl. `rules.backtest` — dry-run simulation over historical or synthetic transactions), `constants`, `states`, `alertWorkflows` (one per alert type — `SCREENING`, `RULE_TRIGGER`, `CUSTOM`: list/get/save), `assignmentPolicies` (read-only legacy archive), `products`, `currencies`, `eventDefinitions`, `customAlertTypes` (org-defined alert types with a typed-field schema), `webhooks`, `tagCatalogue`, `sync`, plus org-wide `reset` |
 | `os.setup` | Org setup status + initialization |
 | `os.settings` | Sync snapshots + drift |
+| `os.reports` | On-demand PDF reports: `alert`, `customerProfile`, `counterpartyProfile`, `resourceProfile` — each resolves to the PDF bytes (`Uint8Array`); needs the `report:read` grant |
+| `os.customLists` | Custom screening lists: list/entry CRUD, ≤500-row bulk import (per-row rejection + `externalRef` upsert), enable/disable, archive/unarchive. Enabled LIVE lists are checked by every screening run alongside external providers. |
 
 See [docs/REFERENCE.md](./docs/REFERENCE.md) for the full method list and endpoint mapping.
 
+### Transaction attempts
+
+Use a transaction attempt when an operation did not become a transaction in
+the source/core system. Attempts are idempotent behavioural records; ingesting
+one does not run rules and does not contribute to transaction financial totals.
+
+```ts
+await os.transactionAttempts.ingest({
+    attemptId: 'auth-20260828-0042',
+    timestamp: '2026-08-28T10:30:00Z',
+    operation: 'CARD_AUTHORIZATION',
+    outcome: {
+        type: 'FAILED',
+        code: 'DO_NOT_HONOUR',
+        retryable: true,
+        final: true,
+    },
+    amount: { amountMinor: 12500, currency: 'FIAT:USD', precision: 2 },
+    paymentInstrument: {
+        type: 'CARD',
+        iin: '424242',
+        last4: '4242',
+        // A fingerprint lookup miss is retained as an unresolved attempt;
+        // it never creates a Payment Instrument.
+        fingerprint: { type: 'CARD_PAN', value: '4242424242424242' },
+    },
+});
+
+const failedAuthorizations = await os.transactionAttempts.list({
+    outcomes: ['FAILED', 'BLOCKED'],
+    operation: 'CARD_AUTHORIZATION',
+    limit: 50,
+});
+
+await os.behaviorSettings.update({
+    attemptRetentionDays: 180,
+    attemptCoverage: 'ALL',
+});
+```
+
+Raw fingerprint values are accepted only in the typed `fingerprint` field and
+are protected in memory for lookup; they are never retained in the attempt.
+Other snapshot objects must contain safe descriptors only.
+
+For a resolved transaction, `paymentInstrument` uses the same identity shape
+and creates the Payment Instrument on a deterministic lookup miss.
+
+```ts
+await os.transactions.ingest({
+    transactionId: 'txn-20260828-0043',
+    timestamp: '2026-08-28T10:31:00Z',
+    transaction,
+    paymentInstrument: {
+        type: 'CARD',
+        fingerprint: { type: 'CARD_PAN', value: '4242424242424242' },
+    },
+    device: {
+        fingerprint: 'visitor-91f2',
+        ipSessions: [{ ipAddress: '203.0.113.8', seenAt: '2026-08-28T10:31:00Z' }],
+        location: { latitude: 6.9271, longitude: 79.8612, accuracyMeters: 25, source: 'GEOLOCATION' },
+    },
+});
+```
+
+## Events and Risk Signals
+
+### Every event names its resource
+
+An Event is about exactly one resource, named explicitly:
+
+```ts
+const { id, resource, riskSignalIds } = await os.events.ingest({
+    eventId: 'evt-20260829-teller-001',
+    type: 'security.pin_reset',
+    timestamp: '2026-08-29T02:14:33.000Z',
+    resource: { type: 'EMPLOYEE', id: 'emp_9f21' },
+    fields: [{ key: 'channel', type: 'TEXT', value: 'BRANCH_TERMINAL' }],
+});
+```
+
+`resource.type` is one of `CUSTOMER`, `ACCOUNT`, `COUNTERPARTY`, `EMPLOYEE`,
+`BRANCH`, `PAYMENT_INSTRUMENT` — the closed set of attachable resources. There
+is no `INSTRUMENT` spelling; `PAYMENT_INSTRUMENT` is the only instrument
+concept.
+
+A bare top-level `customerId` is still accepted as the **legacy spelling** of
+`resource: { type: 'CUSTOMER', id }`, so existing integrations keep working:
+
+```ts
+// legacy — still accepted, equivalent to resource: { type: 'CUSTOMER', id }
+await os.events.ingest({ type: 'customer.failed_login', timestamp, customerId: 'cus_123' });
+```
+
+`resource` wins when both are sent, and alongside a non-customer `resource` the
+`customerId` is context that customer-scoped event aggregates read. An event
+naming neither is rejected with 400. Prefer `resource` in new integrations —
+it is the only way to attach an event to an account, counterparty, employee,
+branch, or payment instrument.
+
+The response echoes the resolved `resource` and the `riskSignalIds` the event
+emitted. `deviceId` and `sessionId` may still qualify an event but never
+substitute for its primary resource.
+
+### Risk Signals — evidence, not alerts
+
+A Risk Signal is a piece of time-decaying evidence attached to one resource.
+Adding one creates **no** alert, notification, assignment or task, and does not
+change the resource's Risk Rating. Rules read the aggregate and decide.
+
+```ts
+await os.riskSignals.create({
+    externalId: 'case-note:2026-08-29:customer-2847:1',
+    type: 'analyst.concerning_account_behaviour',
+    resourceType: 'CUSTOMER',
+    resourceId: 'cus_2847',
+    weight: 35,
+    halfLife: 'P14D',
+    note: 'Third unexplained cash deposit this month.',
+});
+
+const signals = await os.riskSignals.list({
+    resourceType: 'CUSTOMER',
+    resourceId: 'cus_2847',
+    asOf: '2026-09-12T00:00:00Z',
+    type: ['analyst.concerning_account_behaviour'],
+});
+
+signals.aggregateEffectiveWeight; // decayed sum at `asOf`
+```
+
+The signal records the strength it had at `occurredAt` and how fast that
+strength halves:
+
+```
+effectiveWeight = weight * 2 ^ (-ageSeconds / halfLifeSeconds)
+```
+
+So weight 40 with half-life `P7D` reads 20 after seven days and 10 after
+fourteen. The aggregate is computed on read as of `asOf` (defaulting to server
+time) — it is never a cached score column, so a historical `asOf` returns what
+the resource looked like at that moment. `type` / `sourceType` filter which
+records contribute; they never change how far a contributing signal has
+decayed.
+
+`externalId` makes retries safe. The server always sets the source to `MANUAL`
+and captures the authenticated actor — a caller cannot claim a signal came from
+an Event or a Rule. Half-lives are positive ISO 8601 durations; calendar units
+(Y/M) are rejected because they have no fixed length.
+
+### Emitting signals from event definitions
+
+An event definition can declare the signals every valid occurrence emits. This
+is tenant configuration — an integration pushing an event cannot add, change,
+or suppress an effect.
+
+```ts
+await os.config.eventDefinitions.create({
+    name: 'security.pin_reset',
+    category: 'AUTHENTICATION',
+    riskSignalEffects: [
+        { type: 'authentication.pin_reset', weight: 20, halfLife: 'P3D' },
+    ],
+});
+```
+
+`target` defaults to `EVENT_RESOURCE` — the signal attaches to the event's own
+primary resource. The event and its signals are written in one transaction, and
+the event's idempotency covers them: replaying an `eventId` echoes the original
+`riskSignalIds` rather than emitting a second set.
+
+### Emitting signals from rules
+
+`ADD_RISK_SIGNAL` records evidence when a rule fires:
+
+```ts
+await os.config.rules.create({
+    name: 'Rapid counterparty fan-out',
+    subject: 'TRANSACTION',
+    severity: 'MEDIUM',
+    actions: [
+        {
+            type: 'ADD_RISK_SIGNAL',
+            signalType: 'behaviour.counterparty_fan_out',
+            weight: 25,
+            halfLife: 'P7D',
+            target: { resource: 'counterparty' },
+        },
+    ],
+});
+```
+
+`target.resource` is a closed selector over the evaluation, never a field
+expression: `customer`, `account`, `counterparty`, or `paymentInstrument`.
+`employee` and `branch` are **not** accepted — no evaluation envelope resolves
+either slot yet, so such a rule could never fire; both are rejected at save
+time with a 400 explaining why.
+
+Unlike other action types, `ADD_RISK_SIGNAL` may appear more than once on a
+rule (one rule can record several kinds of evidence, or the same evidence
+against several resources). What is rejected is the same `signalType` on the
+same `target.resource` twice — that would double-count in every aggregate.
+
+### Employees and Branches
+
+Employees and Branches are monitored domain data describing the institution's
+own operating structure, and are attachable resources for Events and Risk
+Signals. An Employee is deliberately **not** a Dossiers organization member: an
+Employee need not have a Dossiers login, and an Employee id is never an
+org-member id. `orgMemberId` is an optional link for the case where the two
+happen to be the same person.
+
+```ts
+const branch = await os.branches.create({ name: 'Colombo Fort', externalBranchId: 'BR-014', country: 'LK' });
+
+const teller = await os.employees.create({
+    fullName: 'Aruni Fernando',
+    externalEmployeeId: 'STAFF-10982',
+    jobTitle: 'Branch Teller',
+    branchId: branch.id,
+});
+
+await os.riskSignals.create({
+    type: 'staff.override_pattern',
+    resourceType: 'EMPLOYEE',
+    resourceId: teller.id,
+    weight: 15,
+    halfLife: 'P30D',
+});
+```
+
+`externalEmployeeId` / `externalBranchId` are unique within the organization
+and let ingestion resolve a record without a Dossiers UUID round-trip.
+
+## Customer creation (BREAKING)
+
+`individuals.create` and `entities.create` now use the same canonical inputs as
+GraphQL. The SDK exports `CreateIndividualInput` and `CreateEntityInput`;
+the former `*Dto` names remain deprecated aliases.
+
+```ts
+await os.individuals.create({
+    externalId: 'USR-10042',
+    fullName: 'Ahmed Al-Rashidi',
+    status: 'ONBOARDING',
+    aliases: ['Ahmed Rashidi'],
+    nationality: ['KWT'],
+    countryOfResidence: ['USA'],
+    emails: [{ value: 'ahmed@example.com', primary: true }],
+    phones: [{ value: '+1-555-0142', primary: true }],
+    addresses: [{ category: 'HOME', line1: '4521 Maple Drive', country: 'USA' }],
+});
+
+await os.entities.create({
+    externalId: 'ENT-30021',
+    legalName: 'Meridian Holdings Ltd',
+    tradingNames: ['Meridian Holdings'],
+    websites: ['https://meridian.example'],
+    locations: [{ category: 'REGISTERED', line1: '42 Makarios III Avenue', country: 'CYP' }],
+    stakeholders: [{ name: 'Viktor Petrov', role: 'UBO', ownershipPercentage: 45 }],
+});
+```
+
+### Synchronous initial screening
+
+By default `create` queues the customer's INITIAL screening and returns at
+once. Pass `{ screening: 'sync' }` to run it before the call returns; the
+outcome and every match it surfaced arrive under `screening`, so an onboarding
+flow can branch without polling `screening.history` or waiting for a webhook.
+
+```ts
+const created = await os.individuals.create(
+    { externalId: 'USR-10043', fullName: 'Ahmed Al-Rashidi', nationality: ['KWT'] },
+    { screening: 'sync' },
+);
+
+if (created.screening?.status === 'FAILED') {
+    // No provider configured or every provider failed. The customer exists;
+    // rerun with os.customers.screening.trigger(created.id).
+} else if (created.screening?.alertId) {
+    // Matches found: created.screening.matches holds each hit and its
+    // disposition; auto-dismissed hits arrive as FALSE_POSITIVE.
+} else {
+    // Clear run — no matches, no alert.
+}
+```
+
+The same option works on `os.entities.create`. Screening failure never rolls
+back the customer, and the response without the option is unchanged.
+
+Migration:
+
+- Individual names are one required `fullName`; remove `firstName`/`lastName`.
+- Prefer `emails`/`phones` contact-entry arrays over the scalar `email`/`phone`.
+- `nationality` and `countryOfResidence` are arrays of alpha-3 country codes.
+- Entities use `tradingNames[]` and `locations[]` (not `tradingName`/`addresses`).
+- On an identification document, prefer `country` over `issuingCountry`.
+- The older spellings — scalar `email`/`phone`, `issuingCountry`, create-time
+  `createdAt`, entity `addresses`, and entity `parentEntityId` — are still
+  accepted as deprecated aliases; the canonical field wins when both are sent.
+- Use `status` for the initial customer lifecycle state. New records default to
+  `ONBOARDING`; `monitoringStatus` and `riskRating` are not create inputs.
+
 ## Tenant sync — config-as-code (BREAKING in v0.7.0)
 
 `os.config.sync` drives declarative tenant config (products, constants, event
-definitions, webhooks, rules, currencies). You build a `SyncConfig` and the
+definitions, webhooks, rules, currencies, and tenant behaviour settings). You build a `SyncConfig` and the
 **server** validates, diffs, and applies it — clients hold no diff/apply logic.
 This backs the `dossiers-sync` CLI.
 
@@ -75,6 +391,10 @@ const result = await os.config.sync.apply(config);            // validate → di
 const live = await os.config.sync.export({ includeUnsynced: true }); // → SyncConfig
 ```
 
+`behaviorSettings` is an optional, singleton section. Omit it to leave the
+target tenant unmanaged; supplied fields update partially. Exports and sync
+snapshots include the full effective policy.
+
 **Breaking:** `os.settings.getSyncExport()` (opaque zip) was **removed** — use
 `os.config.sync.export()`, which returns a typed `SyncConfig`. The `SyncExportDto`
 type was removed accordingly. Snapshot/drift methods on `os.settings` are
@@ -96,15 +416,21 @@ await os.config.rules.create({
 });
 ```
 
-A per-org **tag catalogue** defines the available vocabulary per field-key and,
-when a field-key's enforcement is `strict`, rejects off-catalogue writes (422):
+A per-org **tag catalogue** defines the available vocabulary per field-key. The
+catalogue is **closed**: a write whose value is not in the catalogue is rejected,
+always. There is no enforcement setting to relax — register the tag first.
 
 ```ts
 await os.config.tagCatalogue.create({ fieldKey: 'rule.tags', label: 'AML' });
-await os.config.tagCatalogue.setEnforcement({ fieldKey: 'rule.tags', enforcement: 'strict' });
 const entries = await os.config.tagCatalogue.list({ fieldKey: 'rule.tags' });
+const { tokens } = await os.config.tagCatalogue.palette(); // valid `color` values
 ```
 
+> **Breaking change:** `setEnforcement()` / `enforcement()` and the
+> `TagCatalogueEnforcement`, `TagFieldEnforcement`, and `SetTagEnforcementInput`
+> types are removed. Tag vocabulary is now managed exclusively through catalogue
+> entries and tenant config. Ad-hoc, per-record detail belongs in notes.
+
 ## Typed Fields (v0.2.0+)
 
 > **v0.3.0 breaking change:** `IngestEventDto.data` has been removed in
@@ -115,8 +441,10 @@ const entries = await os.config.tagCatalogue.list({ fieldKey: 'rule.tags' });
 
 Accounts, products, and event ingestion accept the platform's Typed Fields
 primitive — a typed key/value bag (`fields`) plus an untyped escape hatch
-(`otherProperties`). Seven types: `TEXT`, `NUMBER`, `BOOLEAN`, `DATE`, `SET`,
-`CURRENCY`, `MONETARY`.
+(`otherProperties`). Collection fields are explicit: `LIST` is open-ended,
+while `SINGLE_SELECT` and `MULTI_SELECT` are constrained by the declared
+`options` on the parent schema (`Product.accountFieldConfig` or
+`EventDefinition.properties`). Legacy `SET` remains supported but is deprecated.
 
 ```ts
 import type { TypedFieldValueInput } from '@dossier-wiki/os-sdk';
@@ -130,7 +458,7 @@ await os.accounts.create('cus_123', {
         { key: 'rate',   type: 'NUMBER',   value: 0.045 },
         { key: 'opened', type: 'DATE',     value: '2026-03-01' },
         { key: 'limit',  type: 'MONETARY', value: '5000.00@FIAT:USD' }, // denominated literal
-        { key: 'tags',   type: 'SET',      value: ['retail', 'priority'] },
+        { key: 'aliases', type: 'LIST',    value: ['everyday', 'current'] },
     ],
     otherProperties: [
         { key: 'sourceImportBatch', value: { id: 'batch-42', source: 'csv' } },
@@ -138,10 +466,11 @@ await os.accounts.create('cus_123', {
 });
 ```
 
-When a product declares a `typedAccountFieldConfig` schema (Tier A), the
+When a product declares an `accountFieldConfig` template (Tier A), the
 runtime validator enforces type match, required keys, and unknown-key
 rejection. Otherwise the same input shape passes through self-declaring
 validation (Tier B) — same semantics as `txn.metadata`.
+`typedAccountFieldConfig` remains as a deprecated API alias.
 
 Updates apply with **merge semantics**: each supplied key overwrites; absent
 keys preserved. Pass an empty array to clear.
@@ -151,6 +480,25 @@ pre-resolved `amountMinor` + `currency` + `precision`.
 
 Spec: [`docs/specs/typed-fields/README.md`](../../docs/specs/typed-fields/README.md).
 
+### Party relationships
+
+```ts
+const employer = await os.partyRelationships.createType({
+    key: 'employer',
+    label: 'Employer',
+    direction: 'DIRECTED',
+});
+
+await os.partyRelationships.create({
+    typeId: employer.id,
+    sourceType: 'CUSTOMER',
+    sourceId: customerId,
+    targetType: 'COUNTERPARTY',
+    targetId: employerCounterpartyId,
+    description: 'Declared during onboarding',
+});
+```
+
 ## Configuration
 
 ```ts
@@ -179,3 +527,42 @@ try {
 ## License
 
 MIT
+
+Screening-result dispositions stay `PENDING | CONFIRMED | FALSE_POSITIVE`. A match a workflow reviewer marked inconclusive is still undecided, so the REST API reports and filters it as `PENDING`; the inconclusive state itself is visible only in the app and GraphQL.
+
+### Alert workflows
+
+The application uses the same disposition cards, reason field, and optional catalogue tags for closing Simple alerts and resolving workflow alerts. Workflow resolution still requires a disposition and respects the pinned stage’s comment requirement. The GraphQL `transitionAlertReview` input accepts optional `tags: [{ value, label }]` for `RESOLVE`; tags are validated against the tenant’s `alert.dispositionTags` catalogue, stored with the disposition, and cleared on reopening.
+
+New workflow saves require one shared **Resolved** stage. Set its `next` to a router or an automatic `action` node for follow-ups. Routers can combine `resolution.outcome` with alert, customer, screening or rule fields; after resolution, `$end` means no further action. Action nodes support `CREATE_TASK` (linked to the alert) and `NOTIFY` (in-app notification), with current alert owners or specific members/teams as recipients. Follow-ups run atomically with closure using the saved verdict and leave the alert resolved. Reopen remains a separate review action. Reopening and resolving again can run follow-ups again; retrying the same transition cannot duplicate them. Existing alerts retain their pinned definition.
+
+Each organization has one workflow per alert type: `SCREENING` and `RULE_TRIGGER`. Initial assignment and later handovers are stage settings; routers provide ordered conditions and a fallback. Router branches may have an optional `name`, and the router may have a `fallbackName` (nonblank, up to 200 characters). These names appear in the workflow graph and routing history; they do not change branch IDs, order, or destinations. Omitting them preserves the numbered condition and fallback labels. Read the current revision before saving:
+
+```ts
+const workflow = await client.config.alertWorkflows.get('SCREENING');
+await client.config.alertWorkflows.save('SCREENING', {
+  id: workflow.id,
+  name: workflow.name,
+  expectedRevision: workflow.revision,
+  definition: workflow.draft,
+  publish: false, // true publishes for future alerts
+});
+```
+
+Requires `config:read` / `config:write`. Stale saves return HTTP 409. Existing alerts keep their published version. `config.assignmentPolicies` remains available to inspect archived rules, but its write methods now return HTTP 410. The `assignmentPolicies` tenant-sync section is retired; use `config.alertWorkflows` instead. Existing assignment rules are converted automatically to the initial workflow graph.
+
+Set `definition.restrictEditingToOwners` to `true` to make alerts read-only for everyone except currently assigned people and members of active assigned teams, including administrators. This covers assignments, match decisions, alert comments and attachments, task links, and every stage transition (including return and reopen), overriding the progression-only policy. Omitting it or setting it to `false` preserves existing editing permissions. The policy is pinned when the alert is created; publishing does not change older alerts or Simple alerts. Linked tasks retain their own editing permissions. Organization admins and owners can explicitly add themselves through the application’s **Assign to me** action (`takeOverAlert` in GraphQL). This administrative recovery preserves all other assignees, status and pinned workflow settings, and is recorded in activity history; it also supports resolved alerts so an administrator can assume ownership before reopening.
+
+Set `definition.restrictProgressionToOwners` to `true` to limit forward progression (including resolution) to currently assigned people and members of active assigned teams. Administrators must also be assigned. Set it to `false` to allow other organization members with `alert:update` permission to progress alerts. Stage requirements still apply. Return and reopen permissions are unchanged. Omitting the field preserves the original current-reviewers-or-administrators behavior for older API clients and stored definitions. The builder defaults the policy to enabled when editing; publishing affects new alerts only.
+
+For Screening workflows, `definition.matchAssessment` sets shared `{ note, attachment }` booleans for `CONFIRMED`, `INCONCLUSIVE`, and `FALSE_POSITIVE`. These apply to every Initial Review stage and to Secondary Review when `definition.allowSecondaryReviewMatchOverrides` is `true`; set each stage's legacy `screening` field to `null`. Enabling overrides requires a shared `matchAssessment` policy. Initial Review reviewers can replace individual match verdicts directly without resetting to pending. Authorized secondary reviewers can then also replace a match verdict directly, with the required evidence and an audit record of the previous verdict. Existing reviewer and editing permissions still apply; resolved alerts remain read-only for match decisions. Overrides default to off, and non-screening workflows must omit both settings. Older definitions that omit `matchAssessment` retain their stage-specific requirements. The builder's General policy tab consolidates older stage requirements into a shared draft, preserving the strictest requirement where they differ. Publishing never updates existing alerts.
+
+### Linking comments to screening matches
+
+Attach screening matches explicitly with `links: { matchIds: ["<match UUID>"] }` when creating or updating an alert comment. A comment can attach multiple matches belonging to that alert. Comment responses include `matchReferences` with each match's ID, category and saved display name. Editing the body preserves attachments unless `links` is supplied; `links: { matchIds: [] }` detaches all matches. Mentions in the body do not create associations. Existing saved associations and historical match labels are preserved.
+
+### Alert experience
+
+Use `client.config.alertWorkflows.getExperience()` to read the tenant's choice and revision. `saveExperience({ experience: 'SIMPLE' | 'DEFINED', expectedRevision })` changes only newly created alerts, across both supported alert types. Simple uses direct assignment and Open/Closed resolution; Defined uses the published workflow for the alert type. Existing alerts retain their process and policy version. Saved definitions are retained in Simple mode, and publishing a definition does not enable Defined mode. The initial default is Simple. Select Defined explicitly to enable the published workflow for new alerts. Existing saved choices are preserved when upgrading.
+
+Published workflow history is available through `config.alertWorkflows.versions(alertType)` (newest first, with publisher and date). `config.alertWorkflows.restore(alertType, { version, expectedRevision })` copies a version into the draft without changing the published workflow or existing alerts. Review the returned draft, then call `save` with `publish: true` and its updated revision to publish it as a new version. Old versions with no recoverable definition return `definition: null` and cannot be restored. Both operations are organization-scoped and require `config:read` / `config:write` respectively.

package/dist/alert-workflow-types.d.ts

@@ -0,0 +1,115 @@
+/** Shared JSON wire contract. The backend validates this structure before saving. */
+export type WorkflowAlertType = "SCREENING" | "RULE_TRIGGER" | "CUSTOM";
+export type WorkflowStageGroup = "INITIAL_REVIEW" | "SECONDARY_REVIEW" | "RESOLVED";
+export interface WorkflowCondition {
+    field: string;
+    operator: string;
+    value: string;
+    /** Compare to another available field instead of a literal. */
+    valueField?: string;
+    whenMissing?: string;
+}
+export interface WorkflowConditions {
+    logic: "AND" | "OR";
+    conditions: WorkflowCondition[];
+}
+export interface WorkflowAssignment {
+    mode: "KEEP" | "HANDOVER" | "ADD";
+    source: "SPECIFIC" | "CUSTOMER_MEMBERS" | "CUSTOMER_TEAMS" | "CUSTOMER_OWNERS" | "ORIGINAL";
+    userIds: string[];
+    teamIds: string[];
+}
+export interface ScreeningDecisionPolicy {
+    note: boolean;
+    attachment: boolean;
+}
+export type MatchAssessmentPolicy = Record<"CONFIRMED" | "FALSE_POSITIVE" | "INCONCLUSIVE", ScreeningDecisionPolicy>;
+export interface WorkflowStage {
+    id: string;
+    kind: "stage";
+    name: string;
+    group: WorkflowStageGroup;
+    next: string | null;
+    actionLabel: string;
+    assignment: WorkflowAssignment;
+    conditions: WorkflowConditions;
+    requireComment: boolean;
+    requiredReviews: ("CUSTOMER_RISK" | "COUNTERPARTY_RISK")[];
+    /** Legacy stage policy. New definitions use matchAssessment and set this to null. */
+    screening: MatchAssessmentPolicy | null;
+}
+export interface WorkflowRouter {
+    id: string;
+    kind: "router";
+    name: string;
+    branches: {
+        id: string;
+        /** Optional display name (1–200 characters). Omission uses the condition number. */
+        name?: string;
+        conditions: WorkflowConditions;
+        target: string;
+    }[];
+    fallback: string;
+    /** Optional display name (1–200 characters). Omission displays Fallback. */
+    fallbackName?: string;
+}
+/** Automatic follow-up after resolution. It never changes the alert's stage or owners. */
+export interface WorkflowAction {
+    id: string;
+    kind: "action";
+    name: string;
+    action: "CREATE_TASK" | "NOTIFY";
+    next: string | null;
+    title: string;
+    body: string;
+    recipients: {
+        source: "ALERT_OWNERS" | "SPECIFIC";
+        userIds: string[];
+        teamIds: string[];
+    };
+}
+export type WorkflowNode = WorkflowStage | WorkflowRouter | WorkflowAction;
+export interface WorkflowDefinition {
+    schemaVersion: 1;
+    alertType: WorkflowAlertType;
+    /** Forward progression only. True requires a current assigned person or active-team member, including admins; false allows any organization member with alert:update. Omission preserves the original reviewers-or-admins policy. */
+    restrictProgressionToOwners?: boolean;
+    /** All alert editing requires current ownership, including administrators. Organization admins/owners may explicitly take over by adding themselves as an assignee. Overrides progression permissions. Omission/false preserves existing editing permissions. */
+    restrictEditingToOwners?: boolean;
+    /** Screening-only requirements shared by Initial Review and enabled Secondary Review overrides. Omission preserves legacy stage policies. */
+    matchAssessment?: MatchAssessmentPolicy;
+    /** Screening only. Allow reviewers to override match verdicts in Secondary Review using matchAssessment requirements. Omission/false keeps decisions in Initial Review. */
+    allowSecondaryReviewMatchOverrides?: boolean;
+    entry: string;
+    /** Exactly one Resolved stage. Its optional next step runs automatically after closure.
+     * Routers and actions after resolution may use "$end" to finish without another action. */
+    nodes: WorkflowNode[];
+}
+export interface WorkflowPublication extends WorkflowDefinition {
+    publication?: {
+        name: string;
+    };
+}
+export interface WorkflowField {
+    key: string;
+    label: string;
+    type: "enum" | "number" | "boolean" | "set" | "string";
+    values?: string[];
+    operators: string[];
+    creation: boolean;
+}
+export interface WorkflowExecution {
+    version: 2;
+    workflowId: string;
+    workflowName: string;
+    publishedVersion: number;
+    definition: WorkflowDefinition;
+    stage: WorkflowStageGroup;
+    nodeId: string;
+    revision: number;
+    history: string[];
+    enteredAt: string;
+    initialUserIds: string[];
+    initialTeamIds: string[];
+}
+//# sourceMappingURL=alert-workflow-types.d.ts.map

package/dist/alert-workflow-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-workflow-types.d.ts","sourceRoot":"","sources":["../src/alert-workflow-types.ts"],"names":[],"mappings":"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"}

package/dist/alert-workflow-types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=alert-workflow-types.js.map

package/dist/alert-workflow-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"alert-workflow-types.js","sourceRoot":"","sources":["../src/alert-workflow-types.ts"],"names":[],"mappings":""}