@dossier-wiki/os-sdk 1.5.0 → 1.6.0-staging.769

package/docs/REFERENCE.md

@@ -14,6 +14,38 @@ new DossiersOSAPIService({ baseUrl, apiKey, fetch? })
 | `apiKey` | `string` | Required. Long-lived JWT issued by `POST /v1/auth/keys`. |
 | `fetch` | `typeof fetch` | Optional. Inject for testing. |
 
+## Listing, filtering and sorting
+
+`individuals.list`, `entities.list`, `accounts.list`, `counterparties.list`,
+`transactions.list` and `alerts.list` share one shape: `{ data, pagination: { nextCursor, totalCount } }`.
+Pass `pagination.nextCursor` back as `cursor` until it is `null`; `limit` is 1 to 100 (default 25).
+
+Every filter is optional, and a call with none returns what it always has (newest
+first). Array filters match any of their values and are sent as repeated query
+parameters; separate filters must all match. Timestamps are ISO 8601 strings.
+`totalCount` counts the rows that match the filters.
+
+`sortBy` takes the fields listed on each query type (`ListIndividualsQuery`,
+`ListCustomersQuery`, `ListAccountsQuery`, `ListCounterpartiesQuery`,
+`ListTransactionsQuery`, `ListAlertsQuery`); an unknown field is a 400.
+`sortOrder` is `asc` or `desc` (default `desc`). Rows with no value for the sort
+field come last in either direction, and cursors stay valid across the walk.
+
+```ts
+const highRisk = await os.individuals.list({
+  riskRating: ['HIGH', 'CRITICAL'],
+  country: ['LKA'],
+  sortBy: 'riskRating',
+});
+
+let cursor: string | undefined;
+do {
+  const page = await os.transactions.list({ customerId, status: ['COMPLETE'], sortBy: 'baseAmount', cursor });
+  // ...
+  cursor = page.pagination.nextCursor ?? undefined;
+} while (cursor);
+```
+
 ## Resource map
 
 ### `sessions` and `channelEndpoints`
@@ -41,7 +73,7 @@ the recorded event-time bounds.
 
 | Method | Endpoint |
 | --- | --- |
-| `list(query?)` | `GET /v1/customers/individuals` |
+| `list(query?)` | `GET /v1/customers/individuals` — filters and sort: `ListIndividualsQuery` (status, riskRating, search, country, kycStatus, createdFrom/To, hasActiveAlerts, assignedToUserId, archived) |
 | `create(input)` | `POST /v1/customers/individuals` |
 | `get(customerId, query?)` | `GET /v1/customers/individuals/{customerId}` |
 | `update(customerId, input)` | `PATCH /v1/customers/individuals/{customerId}` |
@@ -91,7 +123,7 @@ whenever both are supplied. Prefer the canonical names in new integrations.
 
 | Method | Endpoint |
 | --- | --- |
-| `list(query?)` | `GET /v1/customers/entities` |
+| `list(query?)` | `GET /v1/customers/entities` — filters and sort: `ListCustomersQuery` (as individuals, without `kycStatus`) |
 | `create(input)` | `POST /v1/customers/entities` |
 | `get(customerId, query?)` | `GET /v1/customers/entities/{customerId}` |
 | `update(customerId, input)` | `PATCH /v1/customers/entities/{customerId}` |
@@ -305,7 +337,7 @@ Teams carry catalogue-governed tags under the `team.tags` field-key. `create` an
 
 | Method | Endpoint |
 | --- | --- |
-| `list(customerId, query?)` | `GET .../accounts` |
+| `list(customerId, query?)` | `GET .../accounts` — filters and sort: `ListAccountsQuery` (productId, accountCategory, accountType, status, search) |
 | `create(customerId, input)` | `POST .../accounts` |
 | `get(customerId, accountId)` | `GET .../accounts/{accountId}` |
 | `update(customerId, accountId, input)` | `PATCH .../accounts/{accountId}` |
@@ -316,7 +348,7 @@ Teams carry catalogue-governed tags under the `team.tags` field-key. `create` an
 
 | Method | Endpoint |
 | --- | --- |
-| `list(query?)` | `GET /v1/counterparties` |
+| `list(query?)` | `GET /v1/counterparties` — filters and sort: `ListCounterpartiesQuery` (customerId, identity, classification, riskRating, country, isHighRiskJurisdiction, isSanctionedEntity, hasActiveAlerts, search) |
 | `create(input)` | `POST /v1/counterparties` |
 | `get(id)` | `GET /v1/counterparties/{id}` |
 | `update(id, input)` | `PATCH /v1/counterparties/{id}` |
@@ -360,8 +392,16 @@ relationship at `validTo` (or the server's current time); it does not delete it.
 | --- | --- |
 | `ingest(input)` | `POST /v1/transactions` |
 | `patchStatus(input)` | `PATCH /v1/transactions` |
+| `list(query?)` | `GET /v1/transactions` — `TransactionResponseDto` rows, most recently executed first; filters and sort: `ListTransactionsQuery` |
 | `get(reference, { by? })` | `GET /v1/transactions/{transactionId}` — returns `TransactionResponseDto`; `by: 'id'` looks up the internal UUID |
 
+`list` filters on executedFrom/To, base amount in minor units
+(`baseAmountMinMinor` / `baseAmountMaxMinor`), account, customer (both include
+the receiving side of internal transfers), counterparty, payment instrument,
+channel endpoint, institution, kind, status, direction, currency, country,
+isFlagged and search. There is no origin-amount filter: amounts in different
+currencies do not compare. It needs the same API-key permission as `ingest`.
+
 `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
@@ -409,6 +449,7 @@ retention is independent of source-attempt cleanup.
 | Method | Endpoint |
 | --- | --- |
 | `create(input)` | `POST /v1/alerts` |
+| `list(query?)` | `GET /v1/alerts` — flat rows without `resources`, newest first; filters and sort: `ListAlertsQuery` (status, type, riskLevel, ruleIds, customerId, counterpartyId, assignedToUserId, assignedToTeamIds, createdFrom/To, search) |
 | `get(alertId)` | `GET /v1/alerts/{alertId}` |
 | `updateNotes(alertId, { notes })` | `PATCH /v1/alerts/{alertId}/notes` |
 | `resources.list(alertId)` | `GET /v1/alerts/{alertId}/resources` |
@@ -523,8 +564,8 @@ organization, rejected with 400 on a duplicate), `email`, `jobTitle`,
 `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).
+(`edges`, `pageInfo`, `meta`). It pages with `limit` (default 25) and `cursor`:
+pass the previous page's `pageInfo.endCursor` while `pageInfo.hasNextPage` is true.
 
 ### `branches`
 
@@ -542,7 +583,7 @@ act; also an attachable resource for Events and Risk Signals.
 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`.
+the same paging as `employees`.
 
 ### `exchangeRates`
 

package/package.json

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