@dossier-wiki/os-sdk 0.7.0 → 1.4.0

package/docs/REFERENCE.md

@@ -16,6 +16,12 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 
 ## Resource map
 
+### `sessions` and `channelEndpoints`
+
+Both expose `list()`, `get(id)`, and `update(id, input)`. Creation is owned by
+transaction ingestion resolution. Timestamp updates widen, rather than narrow,
+the recorded event-time bounds.
+
 ### `auth`
 
 | Method | Endpoint |
@@ -34,11 +40,24 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | `get(customerId, query?)` | `GET /v1/customers/individuals/{customerId}` |
 | `update(customerId, input)` | `PATCH /v1/customers/individuals/{customerId}` |
 
+`create(input)` requires `externalId` and `fullName`. Optional create fields are
+`status`, `preferredName`, `aliases`, `dateOfBirth`, `nationality[]`,
+`countryOfResidence[]`, `taxId`, `emails[]`, `phones[]`,
+`identificationDocuments[]`, `faceImageFileIds[]`, `addresses[]`, `tags[]`,
+`assignedToUserIds[]`, and `assignedToTeamIds[]`. Contact entries are
+`{ value, primary }`.
+
+Legacy field names from the pre-1.0 contract are still accepted on create and
+map onto the canonical ones — `email` / `phone` scalars fold into `emails[]` /
+`phones[]`, an identification document's `issuingCountry` folds into `country`,
+and `createdAt` backfills the creation timestamp. The canonical field wins
+whenever both are supplied. Prefer the canonical names in new integrations.
+
 `individuals.identificationDocuments`
 
 | Method | Endpoint |
 | --- | --- |
-| `add(customerId, input)` | `POST .../identification-documents` |
+| `create(customerId, input)` | `POST .../identification-documents` |
 | `update(customerId, documentId, input)` | `PATCH .../identification-documents/{documentId}` |
 | `delete(customerId, documentId)` | `DELETE .../identification-documents/{documentId}` |
 
@@ -59,6 +78,20 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | `get(customerId, query?)` | `GET /v1/customers/entities/{customerId}` |
 | `update(customerId, input)` | `PATCH /v1/customers/entities/{customerId}` |
 
+`create(input)` requires `externalId` and `legalName`. Optional create fields
+are `status`, `tradingNames[]`, `registrationNumber`, `taxId`,
+`countryOfIncorporation`, `dateOfIncorporation`, `entityType`, `websites[]`,
+`stakeholders[]`, `locations[]`, `tags[]`, `assignedToUserIds[]`, and
+`assignedToTeamIds[]`. Each stakeholder has required `name` and uppercase
+`role` (`SHAREHOLDER`, `UBO`, or `DIRECTOR`). Entity locations use the same
+`AddressInputDto` shape as individual addresses.
+
+Migration: prefer individual `fullName`, contact-entry arrays, and country-code
+arrays; prefer entity `tradingNames` and `locations`. The older create-time
+`createdAt`, scalar `email` / `phone`, entity `addresses`, and entity
+`parentEntityId` remain accepted as deprecated aliases so existing integrations
+keep working — the canonical field wins whenever both are supplied.
+
 `entities.stakeholders`
 
 | Method | Endpoint |
@@ -87,8 +120,30 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | Method | Endpoint |
 | --- | --- |
 | `trigger(customerId)` | `POST .../screen` |
+| `listHistory(customerId, { limit? })` | `GET .../screening-history` |
+| `getLast(customerId)` | `GET .../screening-history/latest` |
+| `listResults(customerId, { disposition? })` | `GET .../screening-results` |
 | `listConfirmedMatches(customerId)` | `GET .../confirmed-matches` |
 
+`listResults` returns every match for the customer (`ScreeningMatchResultDto[]`) with its current disposition — true positives (`CONFIRMED`), false positives (`FALSE_POSITIVE`) and unresolved (`PENDING`). Pass `disposition` to filter. `listConfirmedMatches` is the `CONFIRMED`-only alias.
+
+Every result carries `tagline` as a string: the provider's short role/bio line for `HIGH_RISK` (PEP) matches, and `""` for every other match type or where no tagline exists. It is never omitted or `null`.
+
+**Not every `FALSE_POSITIVE` was set by a human.** Where the provider supports it, every match is compared against the customer's date of birth, geography, role timeline and entity kind; one that is positively contradicted is dispositioned `FALSE_POSITIVE` automatically, and an alert whose every match is eliminated this way closes itself. The verdict is on `disambiguation` (`MatchDisambiguationDto`):
+
+```ts
+const matches = await os.customers.screening.listResults(customerId);
+
+for (const m of matches.filter((m) => m.disposition === 'FALSE_POSITIVE')) {
+  if (m.disambiguation?.decision === 'discard') {
+    // Cleared by the provider, not by one of your users.
+    console.log(m.matchedName, m.disambiguation.reasonCodes, m.disambiguation.rationale);
+  }
+}
+```
+
+The assessment only ever eliminates on a contradiction — never on a missing attribute, never on geography alone, and never on a sanctions listing unless the contradiction is hard. A `retain` is not a confirmation, only the absence of grounds to eliminate, and an absent `disambiguation` means the match was never assessed. `resolvedBy` distinguishes the automation from your users.
+
 `customers.riskRating` — `update(customerId, input)` → `PUT .../risk-rating`
 
 `customers.riskAssessments` — `list`, `create` on `.../risk-assessments`
@@ -103,6 +158,87 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | `register(customerId, input)` | `POST .../devices` |
 | `updateTrust(customerId, deviceId, input)` | `PUT .../devices/{deviceId}/trust` |
 
+Registration and transaction ingestion share one canonical identity path. Send
+one or more raw identities; the server converts each to a tenant-bound protected
+key in memory, links the resulting canonical Device, and never persists or
+returns the raw values:
+
+```ts
+const device = await os.customers.devices.register(customerId, {
+  fingerprints: [
+    { value: browserVisitorId },
+    { value: mobileInstallationId, provider: 'MOBILE_SDK', type: 'INSTALLATION_ID' },
+  ],
+  browserDetails: { browserName: 'Chrome', os: 'ANDROID', device: 'MOBILE' },
+});
+```
+
+`list`, `register`, `updateTrust`, and `os.devices.get` return the same safe
+`DeviceResponseDto`. It excludes raw fingerprints, protected hashes, and raw IP
+addresses; temporal network and location evidence is exposed through dedicated
+observation contracts.
+
+`customers.assignment`
+
+| Method | Endpoint |
+| --- | --- |
+| `assign(customerId, targets)` | `POST /v1/customers/{customerId}/assignment` |
+| `unassign(customerId, targets)` | `DELETE /v1/customers/{customerId}/assignment` |
+| `assignMany({ customerIds, ...targets })` | `POST /v1/customers/assignment` |
+
+Standing assignment can also be stamped at create via `assignedToUserIds` / `assignedToTeamIds` on `individuals.create` / `entities.create`.
+
+`individuals.create(input, { screening: 'sync' })` / `entities.create(input, { screening: 'sync' })` run the INITIAL screening inline and return it under `screening` (`InitialScreeningResultDto`: run status, `alertId`, and the `matches` array in the `listResults` shape). Without the option the call queues the screening as before and the response has no `screening` field.
+
+`targets` must contain at least one non-empty `userIds` or `teamIds` array.
+Bulk assignment requires at least one `customerId` and validates the complete
+request before writing: an unknown or archived customer, or an invalid target,
+rejects the whole request instead of returning partial success. Assignment
+writes require `customer:update`; archived customers return 422.
+
+### `identificationDocuments` (document-scoped)
+
+Top-level resource for operating on a single identification document by its id
+— the review workflow's surface. Customer-scoped create/update/delete also
+exist on `individuals.identificationDocuments` / `entities.identificationDocuments`.
+
+| Method | Endpoint |
+| --- | --- |
+| `get(id)` | `GET /v1/identification-documents/{id}` |
+| `update(id, input)` | `PATCH /v1/identification-documents/{id}` |
+| `transition(id, input)` | `POST /v1/identification-documents/{id}/transitions` |
+| `archive(id, input)` | `POST /v1/identification-documents/{id}/archive` |
+| `restore(id)` | `POST /v1/identification-documents/{id}/restore` |
+| `delete(id)` | `DELETE /v1/identification-documents/{id}` |
+
+`transition(id, input)` moves the review verdict (`PENDING → APPROVED /
+REJECTED`); `rejectionNarrative` is required when `status = REJECTED`, and
+`rejectionTags` optionally classify the rejection. `update(id, input)` corrects
+captured document fields (name, number, DOB, addresses, …) — allowed while the
+document is `PENDING`; captured fields on an `APPROVED` document are frozen
+until it is transitioned back to `PENDING` (notes/tags/attachments stay
+editable). Every update is activity-logged with a per-field `{field, from, to}`
+diff. `comments` proxy: `identificationDocuments.comments`.
+
+### `teams`
+
+| Method | Endpoint |
+| --- | --- |
+| `list({ search?, tags? })` | `GET /v1/teams` |
+| `get(id)` | `GET /v1/teams/{id}` |
+| `create(input)` | `POST /v1/teams` |
+| `update(id, input)` | `PATCH /v1/teams/{id}` |
+| `archive(id)` | `POST /v1/teams/{id}/archive` |
+| `delete(id)` | `DELETE /v1/teams/{id}` |
+| `addMembers(id, { userIds })` | `POST /v1/teams/{id}/members` |
+| `removeMembers(id, { userIds })` | `DELETE /v1/teams/{id}/members` |
+
+`list` / `get` are open to any authenticated caller. Every other method needs the `team:create` / `team:update` / `team:delete` org permissions, which only `owner` and `admin` hold. An API key inherits the role of the user who created it, so a key created by a `member` gets a 403 — make the key under an owner or admin account if it has to manage teams.
+
+`archive(id)` keeps the team resolvable for history but takes it out of `list` and out of notification fan-out. Prefer it to `delete(id)`, which leaves historical assignment ids dangling as tombstones.
+
+Teams carry catalogue-governed tags under the `team.tags` field-key. `create` and `update` accept `tags: TagValueInput[]`, and every read returns `tags: TagValue[]`. `update` replaces the whole set — send every tag the team should end up with, omit the field to leave the tags alone, or pass `[]` to clear them. `list({ tags: ['aml-review'] })` is an any-of filter: a team matches when it carries at least one of the given values.
+
 ### `accounts`
 
 | Method | Endpoint |
@@ -124,6 +260,7 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | `update(id, input)` | `PATCH /v1/counterparties/{id}` |
 | `link(id, input)` | `POST /v1/counterparties/{id}/link` |
 | `unlink(id, input)` | `POST /v1/counterparties/{id}/unlink` |
+| `merge(id, input)` | `POST /v1/counterparties/{id}/merge` |
 
 `counterparties.riskAssessments` — `list`, `create` on `.../risk-assessments`
 
@@ -134,6 +271,26 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | Method | Endpoint |
 | --- | --- |
 | `get(deviceId)` | `GET /v1/devices/{deviceId}` |
+| `merge(targetDeviceId, input)` | `POST /v1/devices/{targetDeviceId}/merge` |
+
+`merge` makes the target canonical without deleting source history. Its required
+`reason` and actor are retained in the immutable merge audit record.
+
+### `paymentInstruments`
+
+| Method | Endpoint |
+| --- | --- |
+| `list()` | `GET /v1/payment-instruments` |
+| `get(id)` | `GET /v1/payment-instruments/{id}` |
+| `create(input)` | `POST /v1/payment-instruments` |
+| `update(id, input)` | `PATCH /v1/payment-instruments/{id}` |
+| `linkAccount(id, input)` | `POST /v1/payment-instruments/{id}/accounts` |
+| `unlinkAccount(id, relationshipId, validTo?)` | `POST /v1/payment-instruments/{id}/accounts/{relationshipId}/unlink` |
+| `linkCustomer(id, input)` | `POST /v1/payment-instruments/{id}/customers` |
+| `unlinkCustomer(id, relationshipId, validTo?)` | `POST /v1/payment-instruments/{id}/customers/{relationshipId}/unlink` |
+
+Account and Customer links are temporal relationships. Unlinking closes the
+relationship at `validTo` (or the server's current time); it does not delete it.
 
 ### `transactions`
 
@@ -141,6 +298,89 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | --- | --- |
 | `ingest(input)` | `POST /v1/transactions` |
 | `patchStatus(input)` | `PATCH /v1/transactions` |
+| `get(reference, { by? })` | `GET /v1/transactions/{transactionId}` — returns `TransactionResponseDto`; `by: 'id'` looks up the internal UUID |
+
+`ingest` accepts canonical `paymentInstrument` identity by internal ID,
+integration `externalId`, or typed fingerprint. Transaction resolution creates
+a Payment Instrument on a deterministic miss. `transaction.channel` may include
+an endpoint `identifier`, provider namespace, display name, physical location,
+and bounded scalar `context`.
+
+### `transactionAttempts`
+
+| Method | Endpoint |
+| --- | --- |
+| `ingest(input)` | `POST /v1/transaction-attempts` |
+| `list(input?)` | `GET /v1/transaction-attempts` |
+| `get(id)` | `GET /v1/transaction-attempts/{id}` |
+
+`attemptId` is a tenant-scoped idempotency key. Reusing it with identical
+content returns the existing record; reusing it with changed content returns
+`409 ATTEMPT_IDEMPOTENCY_CONFLICT`. Attempts are behavioural history and do not
+trigger rule evaluation or contribute to transaction financial analytics.
+Its `paymentInstrument` resolution is lookup-only: a matching ID, external ID,
+or protected typed fingerprint is linked to the attempt, while a miss remains
+unresolved and never creates a Payment Instrument.
+
+`list` supports opaque cursor pagination and safe filters for outcomes,
+operation, observation time, resolved subjects, IIN, device, session, and
+channel endpoint. Read projections exclude request hashes and protected
+payment-instrument/IP lookup hashes.
+
+### `behaviorSettings`
+
+| Method | Endpoint |
+| --- | --- |
+| `get()` | `GET /v1/config/behavior-settings` |
+| `update(input)` | `PATCH /v1/config/behavior-settings` |
+
+The partial update controls attempt retention (1–3650 days) and attempt coverage
+(`ALL` or `SELECTIVE`). Existing attempt expiry timestamps are unchanged; the
+new retention applies to later ingestion and cleanup remains explicit.
+
+`alerts.attemptEvidence(alertId)` returns the immutable, bounded Transaction
+Attempt facts captured when attempt history contributed to an alert. Evidence
+retention is independent of source-attempt cleanup.
+
+### `alerts`
+
+| Method | Endpoint |
+| --- | --- |
+| `create(input)` | `POST /v1/alerts` |
+| `get(alertId)` | `GET /v1/alerts/{alertId}` |
+| `updateNotes(alertId, { notes })` | `PATCH /v1/alerts/{alertId}/notes` |
+| `resources.list(alertId)` | `GET /v1/alerts/{alertId}/resources` |
+| `resources.add(alertId, { resourceType, resourceId })` | `POST /v1/alerts/{alertId}/resources` |
+| `resources.remove(alertId, alertResourceId)` | `DELETE /v1/alerts/{alertId}/resources/{alertResourceId}` |
+| `attemptEvidence(alertId)` | `GET /v1/alerts/{alertId}/attempt-evidence` |
+| `comments.*` | `/v1/platform/v1/comments` (resourceType `ALERT`) |
+
+`create` raises a **custom alert** by hand. `alertType` is optional: name one of
+the organisation's Custom Alert Types (`config.customAlertTypes`) by its machine
+name and `fields` are Tier A typed fields validated against its schema (unknown
+keys rejected, required keys enforced, at creation only); omit it for a
+free-form alert whose `fields` are self-declaring (Tier B). `riskLevel`
+defaults to the type's `defaultRiskLevel`, or MEDIUM without a type. `assignedToUserIds` / `assignedToTeamIds` set at
+creation notify the assignees. On tenants using Defined workflows the alert is
+enrolled into the "Custom alerts" workflow (Initial review → Secondary review →
+Resolved by default); otherwise it follows the simple Open/Closed process.
+
+`externalRequestId` is an idempotency key scoped per **organization**, not per
+API key: two integrations replaying the same upstream event converge on one
+alert, and the replay returns the existing alert with `201`.
+
+`resources` accept any registered resource type (`customer`, `account`,
+`transaction`, `counterparty`, `alert`, `rule`, …); the key is case-insensitive
+and the target must exist in the organisation. Links are idempotent on
+`(resourceType, resourceId)`. `remove` takes the **link id** returned by
+`list` / `add`.
+
+`notes` is a single markdown narrative on any alert type (screening and
+rule-trigger alerts included). Writes obey the same owner-only editing rule as
+the rest of the alert on workflow alerts that restrict editing to owners.
+
+These endpoints need the `alerts:read` / `alerts:write` API-key permissions
+(`Alerts Read` / `Alerts Write` in Settings → Developer).
 
 ### `events`
 
@@ -148,6 +388,100 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | --- | --- |
 | `ingest(input)` | `POST /v1/events` |
 
+Every Event is about exactly one resource, named as
+`resource: { type, id }`. `type` is one of `CUSTOMER`, `ACCOUNT`,
+`COUNTERPARTY`, `EMPLOYEE`, `BRANCH`, `PAYMENT_INSTRUMENT` (`EventResourceType`
+— there is no `INSTRUMENT` spelling). The resource must already exist in the
+organization.
+
+A bare top-level `customerId` is the deprecated legacy spelling of
+`resource: { type: 'CUSTOMER', id }` and is still accepted; `resource` wins when
+both are sent, and alongside a non-customer `resource` the `customerId` is
+context read by customer-scoped event aggregates. An event naming neither is
+rejected with 400. `deviceId` / `sessionId` qualify an event but never
+substitute for its primary resource.
+
+`IngestEventResponse` carries `eventId`, `id`, `type`, the resolved `resource`,
+and `riskSignalIds` — the Risk Signals emitted by the event definition's
+`riskSignalEffects`. Event and signals are written in one transaction, and the
+event's idempotency covers them: a replayed `eventId` echoes the original ids
+(`cached: true`) instead of emitting a second set.
+
+### `riskSignals`
+
+| Method | Endpoint |
+| --- | --- |
+| `create(input)` | `POST /v1/risk-signals` |
+| `list(query)` | `GET /v1/risk-signals` |
+
+A Risk Signal is time-decaying evidence attached to one resource — evidence,
+**not** an Alert. Creating one raises no alert, notification, assignment or
+task, and does not change the resource's Risk Rating.
+
+`create(input)` (`CreateRiskSignalInput`) requires `type`, `resourceType`
+(`RiskSignalResourceType`, the same six values), `resourceId`, `weight` (> 0)
+and `halfLife` (a positive ISO 8601 duration; calendar units Y/M are rejected).
+Optional: `externalId` (idempotency key — a resubmission returns the original
+signal), `occurredAt` (defaults to now), `note`. The server always sets
+`sourceType: 'MANUAL'` and captures the authenticated actor; a caller cannot
+claim a signal came from an Event or a Rule.
+
+`list(query)` (`ListRiskSignalsQuery`) requires `resourceType` + `resourceId`
+and accepts `asOf`, `type[]`, `sourceType[]`, `limit` (1–200, default 50) and
+`offset`. It returns `RiskSignalListResponse`: `edges` / `pageInfo` /
+`totalCount` plus `asOf`, `aggregateEffectiveWeight`, `contributingCount`,
+`latestAt` and `uniqueTypeCount`.
+
+Decay is `weight * 2 ^ (-ageSeconds / halfLifeSeconds)`; `weight`, `halfLife`
+and `halfLifeSeconds` on a stored signal are an immutable snapshot, while
+`effectiveWeight` is what they have decayed to at `asOf`. The aggregate is
+computed on read, never cached on the resource, so a historical `asOf` returns
+what the resource looked like then. `type` / `sourceType` choose which records
+contribute; they never change how far a contributing signal has decayed.
+
+### `employees`
+
+| Method | Endpoint |
+| --- | --- |
+| `list(query?)` | `GET /v1/employees` |
+| `get(id)` | `GET /v1/employees/{id}` |
+| `create(input)` | `POST /v1/employees` |
+| `update(id, input)` | `PATCH /v1/employees/{id}` |
+
+People acting inside the financial institution's ecosystem, and an attachable
+resource for Events and Risk Signals. Deliberately distinct from 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, not
+an identity.
+
+`create(input)` requires `fullName`; optional `externalEmployeeId` (unique per
+organization, rejected with 400 on a duplicate), `email`, `jobTitle`,
+`department`, `branchId` (must be in the same organization), `status`
+(`ACTIVE` | `INACTIVE` | `SUSPENDED` | `TERMINATED`, default `ACTIVE`) and
+`orgMemberId`. `update` additionally accepts `metadata`.
+
+`list` returns `EmployeeListResponse` — `data` plus the connection shape
+(`edges`, `pageInfo`, `meta`). The endpoint declares `cursor` / `limit`, but
+the server currently resolves its own paging defaults (first page, 50 records).
+
+### `branches`
+
+| Method | Endpoint |
+| --- | --- |
+| `list(query?)` | `GET /v1/branches` |
+| `get(id)` | `GET /v1/branches/{id}` |
+| `create(input)` | `POST /v1/branches` |
+| `update(id, input)` | `PATCH /v1/branches/{id}` |
+
+The institution's own physical or organizational units, through which Employees
+act; also an attachable resource for Events and Risk Signals.
+
+`create(input)` requires `name`; optional `externalBranchId` (unique per
+organization), `code`, `country`, `city`, `institutionId` and `status`
+(`ACTIVE` | `INACTIVE` | `CLOSED`, default `ACTIVE`). `update` additionally
+accepts `metadata`. `list` returns `BranchListResponse` with the same shape and
+the same paging caveat as `employees`.
+
 ### `exchangeRates`
 
 | Method | Endpoint |
@@ -162,6 +496,42 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 
 `config.rules`, `config.constants`, `config.products`, `config.eventDefinitions`, `config.webhooks` — each exposes `list(query?)`, `create(input)`, `getBySyncKey(syncKey)`, `get(id)`, `update(id, input)`, `delete(id)` on `/v1/config/{resource}`.
 
+`config.eventDefinitions` create/update accept `riskSignalEffects:
+RiskSignalEffect[]` — the Risk Signals emitted on every valid occurrence of the
+event. Each effect is `{ type, weight, halfLife, target? }`, where `target`
+defaults to `EVENT_RESOURCE` (the event's own primary resource). Effects are
+tenant configuration: an integration pushing an event cannot add, change, or
+suppress one. `weight` and `halfLife` are snapshotted onto each emitted signal,
+so editing a definition never rewrites evidence already recorded.
+
+`config.rules` actions accept `ADD_RISK_SIGNAL` with `signalType`, `weight`
+(> 0), `halfLife` (positive ISO 8601 duration) and
+`target: { resource: 'customer' | 'account' | 'counterparty' | 'paymentInstrument' }`.
+`target.resource` is a closed selector over the evaluation, never a field
+expression. `employee` and `branch` are **not** valid — no evaluation envelope
+resolves either slot yet, so such an action could never fire, and both are
+rejected at save time with a 400 saying so. Unlike other action types,
+`ADD_RISK_SIGNAL` may appear several times on one rule; what is rejected is the
+same `signalType` on the same `target.resource` twice, which would double-count
+in every aggregate.
+
+`config.customAlertTypes` — org-defined alert types for `alerts.create`.
+
+| Method | Endpoint |
+| --- | --- |
+| `list({ lifecycle? })` | `GET /v1/config/custom-alert-types` |
+| `create(input)` | `POST /v1/config/custom-alert-types` |
+| `getByName(name)` | `GET /v1/config/custom-alert-types/by-name/{name}` |
+| `get(id)` | `GET /v1/config/custom-alert-types/{id}` |
+| `update(id, input)` | `PATCH /v1/config/custom-alert-types/{id}` |
+| `archive(id)` / `unarchive(id)` | `POST /v1/config/custom-alert-types/{id}/archive` / `/unarchive` |
+| `delete(id)` | `DELETE /v1/config/custom-alert-types/{id}` (tombstone; archive first) |
+
+`name` is snake_case and immutable; `fields` is a `TypedFieldDefinition[]`
+schema. Editing `fields` never re-validates existing alerts — new required
+fields apply to alerts raised afterwards. Archive is refused (409) while any
+alert of the type is OPEN.
+
 `config.currencies`
 
 | Method | Endpoint |
@@ -183,7 +553,52 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 
 | Method | Endpoint |
 | --- | --- |
-| `getSyncExport()` | `GET /v1/settings/sync-export` |
+| `listSyncSnapshots()` | `GET /v1/settings/sync-snapshots` |
+| `getSyncDrift()` | `GET /v1/settings/sync-snapshots/drift` |
+| `createSyncSnapshot(input?)` | `POST /v1/settings/sync-snapshots` |
+| `downloadSyncSnapshot(id)` | `GET /v1/settings/sync-snapshots/{id}/download` |
+
+For a typed live configuration export, use `config.sync.export()`.
+Its `SyncConfig.behaviorSettings` singleton carries attempt retention and attempt
+coverage (`ALL` or `SELECTIVE`). The section is optional/unmanaged when absent;
+properties are partial.
+
+### `customLists`
+
+Custom screening lists — tenant-managed lists checked by every screening run
+alongside external providers. Archived lists are read-only and never screened;
+disabled lists are skipped but stay editable. List tags (catalogue-governed)
+are shown against every match the list produces.
+
+| Method | Endpoint |
+| --- | --- |
+| `list(params?)` | `GET /v1/screening/custom-lists` |
+| `create(input)` | `POST /v1/screening/custom-lists` |
+| `get(listId)` | `GET /v1/screening/custom-lists/{listId}` |
+| `update(listId, input)` | `PATCH /v1/screening/custom-lists/{listId}` |
+| `archive(listId)` | `POST /v1/screening/custom-lists/{listId}/archive` |
+| `unarchive(listId)` | `POST /v1/screening/custom-lists/{listId}/unarchive` |
+| `listEntries(listId, params?)` | `GET /v1/screening/custom-lists/{listId}/entries` |
+| `createEntry(listId, input)` | `POST /v1/screening/custom-lists/{listId}/entries` |
+| `bulkCreateEntries(listId, rows)` | `POST /v1/screening/custom-lists/{listId}/entries/bulk` (≤500 rows/request; per-row rejection; `externalRef` upsert) |
+| `updateEntry(listId, entryId, input)` | `PATCH /v1/screening/custom-lists/{listId}/entries/{entryId}` |
+| `deleteEntry(listId, entryId)` | `DELETE /v1/screening/custom-lists/{listId}/entries/{entryId}` |
+
+Entry fields: `name` (required), `entryType` (`INDIVIDUAL` \| `ENTITY`, default
+`INDIVIDUAL` — entries only match subjects of the same type), `aliases`,
+`dateOfBirth` (`YYYY-MM-DD`), `country` (ISO 3166-1 **alpha-3**), `idNumber`,
+`notes`, `externalRef`.
+
+### `reports`
+
+On-demand PDF reports. Every method resolves to the raw PDF bytes as a `Uint8Array`; write them to disk (`fs.writeFileSync`) or stream them to your own download response. Gated on `report:read`. Each call records a `report.generated` activity on the subject record.
+
+| Method | Endpoint |
+| --- | --- |
+| `reports.alert(alertId)` | `GET /v1/reports/alerts/{alertId}/pdf` |
+| `reports.customerProfile(customerId)` | `GET /v1/reports/customers/{customerId}/pdf` |
+| `reports.counterpartyProfile(counterpartyId)` | `GET /v1/reports/counterparties/{counterpartyId}/pdf` |
+| `reports.resourceProfile(resourceType, resourceId)` | `GET /v1/reports/resources/{resourceType}/{resourceId}/pdf` — `ACCOUNT`, `DEVICE`, `INSTITUTION`, `PRODUCT`, `TASK`, … (`ALERT` / `CUSTOMER` / `COUNTERPARTY` → 400, use the dedicated methods) |
 
 ## Typed Fields types
 
@@ -192,12 +607,15 @@ Available since `v0.2.0`. Spec: [`docs/specs/typed-fields/README.md`](../../../d
 ```ts
 type TypedFieldType =
     | 'TEXT' | 'NUMBER' | 'BOOLEAN' | 'DATE'
-    | 'SET' | 'CURRENCY' | 'MONETARY';
+    | 'LIST' | 'SINGLE_SELECT' | 'MULTI_SELECT'
+    | 'CURRENCY' | 'MONETARY'
+    | 'SET'; // deprecated
 
 interface TypedFieldDefinition {
     key: string;
     displayName: string;
     type: TypedFieldType;
+    options?: string[] | null; // required for select types
     required: boolean;
     defaultValue?: unknown;
     description?: string | null;
@@ -208,7 +626,8 @@ interface TypedFieldDefinition {
 //   TEXT / DATE / CURRENCY → string
 //   NUMBER → finite JS number
 //   BOOLEAN → boolean
-//   SET → string[]
+//   LIST / MULTI_SELECT / legacy SET → string[]
+//   SINGLE_SELECT → string from the definition's options
 //   MONETARY → denominated literal `"<amount>@<TYPE:CODE>"`
 interface TypedFieldValueInput {
     key: string;
@@ -227,6 +646,9 @@ type TypedFieldStored =
     | { key: string; type: 'number';   value: number }
     | { key: string; type: 'boolean';  value: boolean }
     | { key: string; type: 'date';     value: string }
+    | { key: string; type: 'list';     value: string[] }
+    | { key: string; type: 'single_select'; value: string }
+    | { key: string; type: 'multi_select'; value: string[] }
     | { key: string; type: 'set';      value: string[] }
     | { key: string; type: 'currency'; value: string }
     | { key: string; type: 'monetary'; amountMinor: number; currency: string; precision: number };
@@ -239,7 +661,10 @@ DTOs that carry these:
 | DTO | Field | Tier |
 | --- | --- | --- |
 | `CreateAccountDto` / `AccountResponseDto` | `fields`, `otherProperties` | A/B + C |
-| `CreateProductDto` / `UpdateProductDto` | `typedAccountFieldConfig`, `fields`, `otherProperties` | schema + B + C |
+| `CreateProductDto` / `UpdateProductDto` | `accountFieldConfig` (`typedAccountFieldConfig` deprecated alias), `fields`, `otherProperties` | schema + B + C |
+| `CreateEventDefinitionDto` / `UpdateEventDefinitionDto` | `properties` (`TypedFieldDefinition[]`) | schema |
+| `CreateCustomAlertTypeDto` / `UpdateCustomAlertTypeDto` | `fields` (`TypedFieldDefinition[]`) | schema |
+| `CreateCustomAlertDto` / `AlertResponseDto` | `fields` | A |
 | `CounterpartyResponseDto` | `otherProperties` | C |
 | Event ingestion (`POST /v1/events`) | `fields` | B |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dossier-wiki/os-sdk",
-  "version": "0.7.0",
+  "version": "1.4.0",
   "description": "TypeScript SDK for the Dossiers OS API — customers, accounts, transactions, rules, screening, and configuration.",
   "license": "MIT",
   "type": "module",