@comms-id/sanctions 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+Copyright (c) 2026 COMMS.ID PTY LTD. Proprietary software; not open source.
+
+Subject to the Comms.ID policy agreement, you may install, copy, bundle, run and
+deliver this client or component within your applications, adapt the supplied
+component source, and use the designated local functions and fixtures offline.
+Hosted operations are provided by the Comms.ID service.
+
+You may keep replies for your own customers and transactions, and your registered
+application may relay requests for its own users.
+
+You may not republish these packages as a standalone offering, resell access, offer
+a substitute lookup service, or harvest replies to reconstruct or redistribute a
+source dataset.
+
+Preserve this notice and any applicable third-party notices.

package/README.md

@@ -0,0 +1,33 @@
+# @comms-id/sanctions
+
+Typed client for the Comms.ID Sanctions API (`https://api.comms.id/sanctions/v1`): screening of one individual, entity or vessel against the Australian Sanctions Consolidated List.
+
+`src/` is generated from the Sanctions contract (`packages/dfat-consolidated-list/openapi/sanctions.v1.json`) by `@comms-id/forge-transformers`. Do not edit it: change the contract and run `pnpm --filter @comms-id/forge-transformers generate`.
+
+```ts
+import { createSanctionsClient } from "@comms-id/sanctions/server";
+
+const client = createSanctionsClient({
+  clientId: process.env.COMMS_ID_CLIENT_ID!,
+  privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
+});
+const reply = await client.screen({"type": "Individual", "name": "Example Person", "dateOfBirth": "1970-06-15"});
+```
+
+## Operations
+
+- `screen`: Screen one individual, entity or vessel against the Australian Sanctions Consolidated List (DFAT): exact names and aliases, optionally narrowed by date and place of birth. The reply carries every possible match with its evidence, the list generation and its freshness. It refuses to answer from a stale list.
+
+Every operation is a read, safe to repeat, and is retried after a retryable failure. A reply that is not a match is one of the outcomes of the reply convention: an error with `outcomeOf(error)` of `no-match`, `source-unavailable` or `failed`; an outage is never a "no match".
+
+## Test it first
+
+`createSanctionsFixtureClient()` from `@comms-id/sanctions/fixtures` answers from the contract's own examples with no network and says so (`fixture: true`). To call the TEST service (synthetic replies, your development app's key), pass `environment: "test"`; going live changes only the environment and the key.
+
+## Server only
+
+Sanctions screening is not open to a browser holding no credential: call it from your own server, or through a relay (`@comms-id/relay`). `./browser` takes your relay route and never signs.
+
+Entries: `.` (types and errors, safe in a browser), `./server` (signs each call), `./browser` (your relay route; never signs), `./fixtures` (LOCAL FIXTURES, no network), `./descriptor` (what `@comms-id/relay` may forward).
+
+The package is private until the publishing path exists (#515). `LICENSE` is the consumer client licence.

package/dist/browser.d.ts

@@ -0,0 +1,5 @@
+import { type SanctionsClient } from "./generated/client.js";
+import { type BrowserOptions } from "./runtime/browser-core.js";
+export type { Environment } from "./runtime/environment.js";
+export type { BrowserOptions, CapabilityOptions, RelayOptions } from "./runtime/browser-core.js";
+export declare const createSanctionsBrowserClient: (options: BrowserOptions) => SanctionsClient;

package/dist/browser.js

@@ -0,0 +1,6 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Browser entry: it never signs and holds no secret. Use the consumer's relay route, or a
+// short-lived capability that the caller supplies.
+import { buildClient } from "./generated/client.js";
+import { createBrowserTransport } from "./runtime/browser-core.js";
+export const createSanctionsBrowserClient = (options) => buildClient(createBrowserTransport(options));

package/dist/descriptor.d.ts

@@ -0,0 +1,11 @@
+export declare const sanctionsProduct: {
+    readonly product: "sanctions";
+    readonly audience: "dfat-consolidated-list";
+    readonly scope: "dfat-consolidated-list:read";
+    readonly maxBodyBytes: 16384;
+    readonly operations: readonly [{
+        readonly name: "screen";
+        readonly method: "POST";
+        readonly path: "/sanctions/v1/screen";
+    }];
+};

package/dist/descriptor.js

@@ -0,0 +1,15 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// The product descriptor that @comms-id/relay reads: which operations may be forwarded.
+export const sanctionsProduct = {
+    product: "sanctions",
+    audience: "dfat-consolidated-list",
+    scope: "dfat-consolidated-list:read",
+    maxBodyBytes: 16_384,
+    operations: [
+        {
+            "name": "screen",
+            "method": "POST",
+            "path": "/sanctions/v1/screen"
+        }
+    ],
+};

package/dist/fixtures.d.ts

@@ -0,0 +1,5 @@
+import { type SanctionsClient } from "./generated/client.js";
+export { FIXTURE_HEADER, FIXTURE_NOTICE } from "./runtime/fixture-core.js";
+export declare const createSanctionsFixtureClient: () => SanctionsClient & {
+    readonly fixture: true;
+};

package/dist/fixtures.js

@@ -0,0 +1,10 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// LOCAL FIXTURES: no network. The client runs the same request and reply checks as a real call.
+import { buildClient } from "./generated/client.js";
+import { fixtures } from "./generated/fixtures.js";
+import { createFixtureTransport } from "./runtime/fixture-core.js";
+export { FIXTURE_HEADER, FIXTURE_NOTICE } from "./runtime/fixture-core.js";
+export const createSanctionsFixtureClient = () => ({
+    ...buildClient(createFixtureTransport(fixtures)),
+    fixture: true,
+});

package/dist/generated/client.d.ts

@@ -0,0 +1,8 @@
+import { type CallOptions, type TransportConfig } from "../runtime/http.js";
+import type { ScreenRequest, ScreenResponse } from "./types.js";
+/** The client of Comms.ID Sanctions: one method for each operation. */
+export interface SanctionsClient {
+    /** Screen one individual, entity or vessel against the Australian Sanctions Consolidated List (DFAT): exact names and aliases, optionally narrowed by date and place of birth. The reply carries every possible match with its evidence, the list generation and its freshness. It refuses to answer from a stale list. */
+    readonly screen: (input: ScreenRequest, options?: CallOptions) => Promise<ScreenResponse>;
+}
+export declare const buildClient: (transport: TransportConfig) => SanctionsClient;

package/dist/generated/client.js

@@ -0,0 +1,6 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+import { call } from "../runtime/http.js";
+import { operations } from "./operations.js";
+export const buildClient = (transport) => ({
+    screen: (input, options) => call(transport, operations.screen, input, options),
+});

package/dist/generated/fixtures.d.ts

@@ -0,0 +1,2 @@
+/** LOCAL FIXTURES: one canned reply for each operation path. Fake data. */
+export declare const fixtures: Readonly<Record<string, unknown>>;

package/dist/generated/fixtures.js

@@ -0,0 +1,44 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Every reply is the example in the contract.
+/** LOCAL FIXTURES: one canned reply for each operation path. Fake data. */
+export const fixtures = {
+    "/sanctions/v1/screen": {
+        "format": 2,
+        "generation": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
+        "checkedAt": "2026-10-03T00:00:00.000Z",
+        "sourceLastModified": "Mon, 22 Sep 2026 03:10:00 GMT",
+        "candidates": [
+            {
+                "record": {
+                    "reference": "1234",
+                    "name": "EXAMPLE PERSON",
+                    "type": "Individual",
+                    "nameType": "Primary Name",
+                    "dobRanges": [
+                        [
+                            "1970-01-01",
+                            "1970-12-31"
+                        ]
+                    ],
+                    "placeOfBirth": [
+                        "Example City"
+                    ],
+                    "raw": {
+                        "Reference": "1234",
+                        "Name of Individual or Entity": "EXAMPLE PERSON"
+                    }
+                },
+                "nameMatch": true,
+                "dobMatch": true,
+                "pobMatch": null
+            }
+        ],
+        "freshness": {
+            "status": "ready",
+            "lastSuccess": "2026-10-02T20:00:00.000Z",
+            "lastChecked": "2026-10-03T00:00:00.000Z",
+            "expiresAt": "2026-10-04T20:00:00.000Z",
+            "lastFailure": null
+        }
+    }
+};

package/dist/generated/operations.d.ts

@@ -0,0 +1,6 @@
+import type { Operation } from "../runtime/http.js";
+export type OperationName = "screen";
+/** The operations of Comms.ID Sanctions, with the schemas the client checks. */
+export declare const operations: Readonly<Record<OperationName, Operation>>;
+/** The error codes the contract documents for each operation. */
+export declare const errorCodes: Readonly<Record<OperationName, readonly string[]>>;

package/dist/generated/operations.js

@@ -0,0 +1,258 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+/** The operations of Comms.ID Sanctions, with the schemas the client checks. */
+export const operations = {
+    screen: {
+        name: "screen",
+        method: "POST",
+        path: "/sanctions/v1/screen",
+        safeToRetry: true,
+        request: {
+            "t": "obj",
+            "props": {
+                "type": {
+                    "t": "str",
+                    "values": [
+                        "Individual",
+                        "Entity",
+                        "Vessel"
+                    ]
+                },
+                "name": {
+                    "t": "str",
+                    "min": 1,
+                    "max": 1024
+                },
+                "dateOfBirth": {
+                    "t": "str",
+                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                },
+                "placeOfBirth": {
+                    "t": "str",
+                    "min": 1,
+                    "max": 1024
+                }
+            },
+            "req": [
+                "type",
+                "name"
+            ],
+            "extra": false
+        },
+        response: {
+            "t": "obj",
+            "props": {
+                "format": {
+                    "t": "num",
+                    "values": [
+                        2
+                    ]
+                },
+                "generation": {
+                    "t": "str",
+                    "pattern": "^[a-f0-9]{64}$"
+                },
+                "checkedAt": {
+                    "t": "str"
+                },
+                "sourceLastModified": {
+                    "t": "any_of",
+                    "of": [
+                        {
+                            "t": "str"
+                        },
+                        {
+                            "t": "null"
+                        }
+                    ]
+                },
+                "candidates": {
+                    "t": "arr",
+                    "of": {
+                        "t": "obj",
+                        "props": {
+                            "record": {
+                                "t": "obj",
+                                "props": {
+                                    "reference": {
+                                        "t": "str",
+                                        "min": 1,
+                                        "max": 1024
+                                    },
+                                    "name": {
+                                        "t": "str",
+                                        "min": 1,
+                                        "max": 1024
+                                    },
+                                    "type": {
+                                        "t": "str",
+                                        "values": [
+                                            "Individual",
+                                            "Entity",
+                                            "Vessel"
+                                        ]
+                                    },
+                                    "nameType": {
+                                        "t": "str"
+                                    },
+                                    "dobRanges": {
+                                        "t": "arr",
+                                        "of": {
+                                            "t": "tup",
+                                            "of": [
+                                                {
+                                                    "t": "str",
+                                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                                                },
+                                                {
+                                                    "t": "str",
+                                                    "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+                                                }
+                                            ]
+                                        }
+                                    },
+                                    "placeOfBirth": {
+                                        "t": "arr",
+                                        "of": {
+                                            "t": "str"
+                                        }
+                                    },
+                                    "raw": {
+                                        "t": "map",
+                                        "of": {
+                                            "t": "str"
+                                        }
+                                    }
+                                },
+                                "req": [
+                                    "reference",
+                                    "name",
+                                    "type",
+                                    "nameType",
+                                    "dobRanges",
+                                    "placeOfBirth",
+                                    "raw"
+                                ],
+                                "extra": false
+                            },
+                            "nameMatch": {
+                                "t": "bool"
+                            },
+                            "dobMatch": {
+                                "t": "any_of",
+                                "of": [
+                                    {
+                                        "t": "bool"
+                                    },
+                                    {
+                                        "t": "null"
+                                    }
+                                ]
+                            },
+                            "pobMatch": {
+                                "t": "any_of",
+                                "of": [
+                                    {
+                                        "t": "bool"
+                                    },
+                                    {
+                                        "t": "null"
+                                    }
+                                ]
+                            }
+                        },
+                        "req": [
+                            "record",
+                            "nameMatch",
+                            "dobMatch",
+                            "pobMatch"
+                        ],
+                        "extra": false
+                    }
+                },
+                "freshness": {
+                    "t": "obj",
+                    "props": {
+                        "status": {
+                            "t": "str",
+                            "values": [
+                                "ready",
+                                "degraded"
+                            ]
+                        },
+                        "lastSuccess": {
+                            "t": "str"
+                        },
+                        "lastChecked": {
+                            "t": "str"
+                        },
+                        "expiresAt": {
+                            "t": "str"
+                        },
+                        "lastFailure": {
+                            "t": "any_of",
+                            "of": [
+                                {
+                                    "t": "obj",
+                                    "props": {
+                                        "at": {
+                                            "t": "str"
+                                        },
+                                        "code": {
+                                            "t": "str",
+                                            "values": [
+                                                "INVALID_INPUT",
+                                                "INVALID_DATASET",
+                                                "UNAVAILABLE",
+                                                "STALE",
+                                                "CONFLICT",
+                                                "CANCELLED",
+                                                "UNAUTHORISED"
+                                            ]
+                                        },
+                                        "stage": {
+                                            "t": "str",
+                                            "values": [
+                                                "download",
+                                                "validation",
+                                                "publication"
+                                            ]
+                                        }
+                                    },
+                                    "req": [
+                                        "at",
+                                        "code"
+                                    ],
+                                    "extra": false
+                                },
+                                {
+                                    "t": "null"
+                                }
+                            ]
+                        }
+                    },
+                    "req": [
+                        "status",
+                        "lastSuccess",
+                        "lastChecked",
+                        "expiresAt",
+                        "lastFailure"
+                    ],
+                    "extra": false
+                }
+            },
+            "req": [
+                "format",
+                "generation",
+                "checkedAt",
+                "sourceLastModified",
+                "candidates",
+                "freshness"
+            ],
+            "extra": false
+        },
+    },
+};
+/** The error codes the contract documents for each operation. */
+export const errorCodes = {
+    screen: ["INVALID_INPUT", "UNAUTHORIZED", "VERSION_RETIRED", "FAIR_USE_CEILING", "UNAVAILABLE"],
+};

package/dist/generated/types.d.ts

@@ -0,0 +1,39 @@
+/** The body of screen. */
+export type ScreenRequest = {
+    readonly type: "Individual" | "Entity" | "Vessel";
+    readonly name: string;
+    readonly dateOfBirth?: string;
+    readonly placeOfBirth?: string;
+};
+/** The reply of screen. */
+export type ScreenResponse = {
+    readonly format: 2;
+    readonly generation: string;
+    readonly checkedAt: string;
+    readonly sourceLastModified: string | null;
+    readonly candidates: ReadonlyArray<{
+        readonly record: {
+            readonly reference: string;
+            readonly name: string;
+            readonly type: "Individual" | "Entity" | "Vessel";
+            readonly nameType: string;
+            readonly dobRanges: ReadonlyArray<readonly [string, string]>;
+            readonly placeOfBirth: readonly string[];
+            readonly raw: Readonly<Record<string, string>>;
+        };
+        readonly nameMatch: boolean;
+        readonly dobMatch: boolean | null;
+        readonly pobMatch: boolean | null;
+    }>;
+    readonly freshness: {
+        readonly status: "ready" | "degraded";
+        readonly lastSuccess: string;
+        readonly lastChecked: string;
+        readonly expiresAt: string;
+        readonly lastFailure: {
+            readonly at: string;
+            readonly code: "INVALID_INPUT" | "INVALID_DATASET" | "UNAVAILABLE" | "STALE" | "CONFLICT" | "CANCELLED" | "UNAUTHORISED";
+            readonly stage?: "download" | "validation" | "publication";
+        } | null;
+    };
+};

package/dist/generated/types.js

@@ -0,0 +1,2 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { SanctionsClient } from "./generated/client.js";
+export { errorCodes, operations } from "./generated/operations.js";
+export type { OperationName } from "./generated/operations.js";
+export type { ScreenRequest, ScreenResponse } from "./generated/types.js";
+export { CommsIdError, isCommsIdError, outcomeOf } from "./runtime/errors.js";
+export type { Outcome } from "./runtime/errors.js";
+export type { CallOptions } from "./runtime/http.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+// Generated by @comms-id/forge-transformers from the service's OpenAPI contract. Do not edit: change the contract and regenerate.
+// Browser-safe entry: types, errors and the operation table. No signing code is imported here.
+export { errorCodes, operations } from "./generated/operations.js";
+export { CommsIdError, isCommsIdError, outcomeOf } from "./runtime/errors.js";

package/dist/runtime/browser-core.d.ts

@@ -0,0 +1,23 @@
+import { type Environment } from "./environment.js";
+import type { TransportConfig } from "./http.js";
+interface Common {
+    readonly deadlineMs?: number;
+    readonly fetch?: typeof fetch;
+    readonly maxRetries?: number;
+}
+/** Calls the consumer's own server route, which signs for the app (the relay). */
+export interface RelayOptions extends Common {
+    /** For example "/api/comms-id/address". The operation name is appended. */
+    readonly relayUrl: string;
+}
+/** Calls the hosted service with a short-lived capability that the caller supplies. */
+export interface CapabilityOptions extends Common {
+    /** Another host. It wins over `environment`. */
+    readonly baseUrl?: string;
+    /** "live" (the default) or "test". */
+    readonly environment?: Environment;
+    readonly getCapability: () => Promise<string>;
+}
+export type BrowserOptions = RelayOptions | CapabilityOptions;
+export declare const createBrowserTransport: (options: BrowserOptions) => TransportConfig;
+export {};

package/dist/runtime/browser-core.js

@@ -0,0 +1,41 @@
+// Runtime template: copied into every generated client package as src/runtime/browser-core.ts.
+// Browser entry: it never signs and never holds a secret. It either calls the consumer's own
+// relay route, or sends a short-lived capability that the caller obtains by other means.
+import { resolveBaseUrl } from "./environment.js";
+import { CommsIdError } from "./errors.js";
+const TRAILING_SLASHES = /\/+$/;
+const passThrough = (options) => ({
+    ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+    ...(options.deadlineMs === undefined ? {} : { deadlineMs: options.deadlineMs }),
+    ...(options.maxRetries === undefined ? {} : { maxRetries: options.maxRetries }),
+});
+/** A browser client with neither a relay nor a capability source has no identified caller. */
+const requireCaller = (options) => {
+    const relay = options.relayUrl;
+    const capability = options.getCapability;
+    if ((typeof relay !== "string" || relay === "") && typeof capability !== "function") {
+        throw new CommsIdError({
+            code: "NOT_CONFIGURED",
+            message: "Set relayUrl (your server route) or getCapability: the browser holds no credential of its own.",
+            status: 0,
+            retryable: false,
+        });
+    }
+};
+export const createBrowserTransport = (options) => {
+    requireCaller(options);
+    if ("relayUrl" in options) {
+        const relay = options.relayUrl.replace(TRAILING_SLASHES, "");
+        return {
+            urlFor: (operation) => `${relay}/${operation.name}`,
+            headers: () => Promise.resolve({}),
+            ...passThrough(options),
+        };
+    }
+    const base = resolveBaseUrl(options.environment, options.baseUrl).replace(TRAILING_SLASHES, "");
+    return {
+        urlFor: (operation) => `${base}${operation.path}`,
+        headers: async () => ({ authorization: `Bearer ${await options.getCapability()}` }),
+        ...passThrough(options),
+    };
+};

package/dist/runtime/environment.d.ts

@@ -0,0 +1,5 @@
+export type Environment = "live" | "test";
+export declare const BASE_URLS: Readonly<Record<Environment, string>>;
+export declare const isEnvironment: (value: unknown) => value is Environment;
+/** The base URL: an explicit one wins, then the environment (live by default). */
+export declare const resolveBaseUrl: (environment: unknown, baseUrl: string | undefined) => string;

package/dist/runtime/environment.js

@@ -0,0 +1,30 @@
+// Runtime template: copied into every generated client package as src/runtime/environment.ts.
+// The two environments of the hosted API (platform #515, T4). They differ in the base URL and in
+// the keys the service knows: TEST answers with synthetic replies for apps registered in the
+// development directory; LIVE answers with real data for apps registered in production. The API,
+// the errors and the authentication are the same, so going live changes only the environment and
+// the key.
+import { CommsIdError } from "./errors.js";
+export const BASE_URLS = {
+    live: "https://api.comms.id",
+    test: "https://api-test.comms.id",
+};
+export const isEnvironment = (value) => value === "live" || value === "test";
+/** The base URL: an explicit one wins, then the environment (live by default). */
+export const resolveBaseUrl = (environment, baseUrl) => {
+    if (baseUrl !== undefined) {
+        return baseUrl;
+    }
+    if (environment === undefined) {
+        return BASE_URLS.live;
+    }
+    if (!isEnvironment(environment)) {
+        throw new CommsIdError({
+            code: "NOT_CONFIGURED",
+            message: 'environment must be "test" or "live".',
+            status: 0,
+            retryable: false,
+        });
+    }
+    return BASE_URLS[environment];
+};

package/dist/runtime/errors.d.ts

@@ -0,0 +1,29 @@
+/** The three results a lookup can have besides a match. */
+export type Outcome = "no-match" | "source-unavailable" | "failed";
+export interface ErrorInit {
+    /** The reply's own body, when the service answered an error status with a structured reply instead of an error body. */
+    readonly body?: unknown;
+    readonly code: string;
+    readonly message: string;
+    readonly requestId?: string | undefined;
+    readonly retryable: boolean;
+    /** The HTTP status, or 0 when no reply was received or the call never left the client. */
+    readonly status: number;
+}
+/**
+ * Every failure of a call. The service sends `code`, `message`, `retryable` and `requestId`.
+ * The client adds the codes INVALID_REQUEST (refused before any request), NETWORK, TIMEOUT,
+ * ABORTED and INVALID_RESPONSE.
+ */
+export declare class CommsIdError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly requestId: string | undefined;
+    /** The structured reply of a status such as 503 whose body is an outcome, not an error body (code HTTP_<status>). */
+    readonly body: unknown;
+    constructor(init: ErrorInit);
+}
+export declare const isCommsIdError: (value: unknown) => value is CommsIdError;
+/** Maps an error to the outcome that the reply convention names. A match never reaches this. */
+export declare const outcomeOf: (error: unknown) => Outcome;