@comms-id/charity

Typed client for the Comms.ID Charity API (https://api.comms.id/acnc-charity-lookup/v1): the ACNC register record and details of an Australian charity, looked up by ABN.

src/ is generated from the Charity contract (packages/acnc-register/openapi/acnc-charity-lookup.v1.json) by @comms-id/forge-transformers. Do not edit it: change the contract and run pnpm --filter @comms-id/forge-transformers generate.

import { createAcncCharityLookupClient } from "@comms-id/acnc-charity-lookup/server";

const client = createAcncCharityLookupClient({
  clientId: process.env.COMMS_ID_CLIENT_ID!,
  privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
});
const reply = await client.lookup({"abn": "51824753556", "mode": "register"});

Operations

• lookup: Look up an Australian charity by ABN: the ACNC register record and the charity's details, each with its source and provenance.

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

createAcncCharityLookupFixtureClient() from @comms-id/acnc-charity-lookup/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.

COMMS_ID_PRIVATE_JWK is an ML-DSA-87 private JWK (kty AKP, with priv and pub). The server entry needs Node.js 24.7 or later, or a Cloudflare Worker with the compatibility flag webcrypto_modern_algorithms.

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).

LICENSE is the consumer client licence.

The field

@comms-id/acnc-charity-lookup/controller is the headless controller of a charity ABN field: input, debounce, suggestions, identifier checks, choice and errors, with the WAI-ARIA combobox attributes and key handler. It has no framework and no DOM. @comms-id/acnc-charity-lookup-react (a hook and a component) and <comms-id-acnc-charity-lookup> (a web element) run on it, and so can your own UI.

import { createAcncCharityLookupController } from "@comms-id/acnc-charity-lookup/controller";

const controller = createAcncCharityLookupController({ client, onSelect: (record, timing) => console.log(record, timing.ms) });
controller.subscribe(() => render(controller.getState()));
controller.setQuery("…");

src/local/profile.ts is the only product-specific part: it reads the typed text, calls the client and reduces every reply to the text the UIs show and the record onSelect receives. Everything else is generated.