@comms-id/company 0.5.0 → 1.0.0

package/README.md

@@ -1,8 +1,8 @@
 # @comms-id/company
 
-Typed client for the Comms.ID Company API (`https://api.comms.id/company/v1`): Australian companies from ASIC's public registers: search by name, look up one by ACN.
+Typed client for the Comms.ID Company API (`https://api.comms.id/company/v2`): Australian companies from ASIC's public registers: search by name, look up one by ACN or ARBN. Each record names its number `asicNumber` and its kind `asicNumberType` (`ACN`, or `ARBN` for a registered foreign company or registered Australian body). Company v1 and its `acn` field are retired (ADR-0050, #714); earlier versions of this package call v1 and get `VERSION_RETIRED`.
 
-`src/` is generated from the Company contract (`packages/asic-public-registers/openapi/company.v1.json`) by `@comms-id/forge-transformers`. Do not edit it: change the contract and run `pnpm --filter @comms-id/forge-transformers generate`.
+`src/` is generated from the Company contract (`packages/asic-public-registers/openapi/company.v2.json`) by `@comms-id/forge-transformers`. Do not edit it: change the contract and run `pnpm --filter @comms-id/forge-transformers generate`.
 
 ```ts
 import { createCompanyClient } from "@comms-id/company/server";
@@ -11,12 +11,12 @@ const client = createCompanyClient({
   clientId: process.env.COMMS_ID_CLIENT_ID!,
   privateJwk: JSON.parse(process.env.COMMS_ID_PRIVATE_JWK!),
 });
-const reply = await client.lookup({"acn": "001234567"});
+const reply = await client.lookup({"asicNumber": "001234564"});
 ```
 
 ## Operations
 
-- `lookup`: Look up one nine-digit ACN in the company snapshot. ABN lookup is not offered in v1. At most ten rows; no uniqueness or complete history claim.
+- `lookup`: Look up one nine-digit ASIC number (ACN or ARBN) with a valid ASIC check digit in the company snapshot. ABN lookup is not offered. At most ten rows; no uniqueness or complete history claim.
 - `search`: Search the company snapshot by case-insensitive name prefix and optional exact status. Default eight rows, maximum ten, no paging. A snapshot miss does not prove absence from the live register.
 
 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".
@@ -31,7 +31,7 @@ Entries: `.` (types and errors, safe in a browser), `./server` (signs each call)
 
 ## The field
 
-`@comms-id/company/controller` is the headless controller of a company name or ACN 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/company-react` (a hook and a component) and `<comms-id-company>` (a web element) run on it, and so can your own UI.
+`@comms-id/company/controller` is the headless controller of a company name, ACN or ARBN 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/company-react` (a hook and a component) and `<comms-id-company>` (a web element) run on it, and so can your own UI.
 
 ```ts
 import { createCompanyController } from "@comms-id/company/controller";

package/dist/descriptor.d.ts

@@ -6,10 +6,10 @@ export declare const companyProduct: {
     readonly operations: readonly [{
         readonly name: "lookup";
         readonly method: "POST";
-        readonly path: "/company/v1/lookup";
+        readonly path: "/company/v2/lookup";
     }, {
         readonly name: "search";
         readonly method: "POST";
-        readonly path: "/company/v1/search";
+        readonly path: "/company/v2/search";
     }];
 };

package/dist/descriptor.js

@@ -9,12 +9,12 @@ export const companyProduct = {
         {
             "name": "lookup",
             "method": "POST",
-            "path": "/company/v1/lookup"
+            "path": "/company/v2/lookup"
         },
         {
             "name": "search",
             "method": "POST",
-            "path": "/company/v1/search"
+            "path": "/company/v2/search"
         }
     ],
 };

package/dist/generated/client.d.ts

@@ -2,7 +2,7 @@ import { type CallOptions, type TransportConfig } from "../runtime/http.js";
 import type { LookupRequest, LookupResponse, SearchRequest, SearchResponse } from "./types.js";
 /** The client of Comms.ID Company: one method for each operation. */
 export interface CompanyClient {
-    /** Look up one nine-digit ACN in the company snapshot. ABN lookup is not offered in v1. At most ten rows; no uniqueness or complete history claim. Only the nine-digit normal form is accepted. identifierState is current or retired when ASIC establishes it, with a source deregistration date as YYYY-MM-DD when available; unknown statuses omit it. No successor ACN is invented. */
+    /** Look up one nine-digit ASIC number in the company snapshot. Only the nine-digit normal form with a valid ASIC check digit is accepted. Each record names its asicNumber and asicNumberType: ACN for an Australian company (APTY, APUB, CCIV), ARBN for a registered foreign company or registered Australian body (FNOS, RACN). ABN lookup is not offered. At most ten rows; no uniqueness or complete history claim. identifierState is current or retired when ASIC establishes it, with a source deregistration date as YYYY-MM-DD when available; unknown statuses omit it. No successor number is invented. */
     readonly lookup: (input: LookupRequest, options?: CallOptions) => Promise<LookupResponse>;
     /** Search the company snapshot by case-insensitive name prefix and optional exact status. Default eight rows, maximum ten, no paging. A snapshot miss does not prove absence from the live register. */
     readonly search: (input: SearchRequest, options?: CallOptions) => Promise<SearchResponse>;

package/dist/generated/fixtures.js

@@ -2,7 +2,7 @@
 // Every reply is the example in the contract.
 /** LOCAL FIXTURES: one canned reply for each operation path. Fake data. */
 export const fixtures = {
-    "/company/v1/lookup": {
+    "/company/v2/lookup": {
         "activatedAt": "2026-10-01T00:01:00Z",
         "attribution": "Australian Securities and Investments Commission via data.gov.au; Creative Commons Attribution 3.0 Australia",
         "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
@@ -13,11 +13,12 @@ export const fixtures = {
         "records": [
             {
                 "register": "companies",
-                "acn": "001234567",
+                "asicNumber": "001234564",
+                "asicNumberType": "ACN",
                 "name": "EXAMPLE COMPANY PTY LTD",
                 "status": "Registered",
                 "abn": "99001234567",
-                "type": null,
+                "type": "APTY",
                 "companyClass": null,
                 "subClass": null,
                 "registeredAt": null,
@@ -42,11 +43,11 @@ export const fixtures = {
             "license": "http://creativecommons.org/licenses/by/3.0/au/"
         },
         "identifierState": {
-            "value": "001234567",
+            "value": "001234564",
             "state": "current"
         }
     },
-    "/company/v1/search": {
+    "/company/v2/search": {
         "activatedAt": "2026-10-01T00:01:00Z",
         "attribution": "Australian Securities and Investments Commission via data.gov.au; Creative Commons Attribution 3.0 Australia",
         "generation": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
@@ -57,11 +58,12 @@ export const fixtures = {
         "records": [
             {
                 "register": "companies",
-                "acn": "001234567",
+                "asicNumber": "001234564",
+                "asicNumberType": "ACN",
                 "name": "EXAMPLE COMPANY PTY LTD",
                 "status": "Registered",
                 "abn": "99001234567",
-                "type": null,
+                "type": "APTY",
                 "companyClass": null,
                 "subClass": null,
                 "registeredAt": null,

package/dist/generated/operations.js

@@ -4,18 +4,18 @@ export const operations = {
     lookup: {
         name: "lookup",
         method: "POST",
-        path: "/company/v1/lookup",
+        path: "/company/v2/lookup",
         safeToRetry: true,
         request: {
             "t": "obj",
             "props": {
-                "acn": {
+                "asicNumber": {
                     "t": "str",
-                    "pattern": "^[0-9]{9}$"
+                    "pattern": "^\\d{9}$"
                 }
             },
             "req": [
-                "acn"
+                "asicNumber"
             ],
             "extra": false
         },
@@ -70,15 +70,18 @@ export const operations = {
                                     "companies"
                                 ]
                             },
-                            "acn": {
-                                "t": "any_of",
-                                "of": [
-                                    {
-                                        "t": "str"
-                                    },
-                                    {
-                                        "t": "null"
-                                    }
+                            "asicNumber": {
+                                "t": "str",
+                                "pattern": "^\\d{9}$"
+                            },
+                            "asicNumberType": {
+                                "t": "str",
+                                "values": [
+                                    "ACN",
+                                    "ARBN",
+                                    "ARSN",
+                                    "ARFN",
+                                    "undetermined"
                                 ]
                             },
                             "name": {
@@ -227,7 +230,8 @@ export const operations = {
                         },
                         "req": [
                             "register",
-                            "acn",
+                            "asicNumber",
+                            "asicNumberType",
                             "name",
                             "status",
                             "abn",
@@ -420,7 +424,7 @@ export const operations = {
     search: {
         name: "search",
         method: "POST",
-        path: "/company/v1/search",
+        path: "/company/v2/search",
         safeToRetry: true,
         request: {
             "t": "obj",
@@ -497,15 +501,18 @@ export const operations = {
                                     "companies"
                                 ]
                             },
-                            "acn": {
-                                "t": "any_of",
-                                "of": [
-                                    {
-                                        "t": "str"
-                                    },
-                                    {
-                                        "t": "null"
-                                    }
+                            "asicNumber": {
+                                "t": "str",
+                                "pattern": "^\\d{9}$"
+                            },
+                            "asicNumberType": {
+                                "t": "str",
+                                "values": [
+                                    "ACN",
+                                    "ARBN",
+                                    "ARSN",
+                                    "ARFN",
+                                    "undetermined"
                                 ]
                             },
                             "name": {
@@ -654,7 +661,8 @@ export const operations = {
                         },
                         "req": [
                             "register",
-                            "acn",
+                            "asicNumber",
+                            "asicNumberType",
                             "name",
                             "status",
                             "abn",
@@ -847,6 +855,6 @@ export const operations = {
 };
 /** The error codes the contract documents for each operation. */
 export const errorCodes = {
-    lookup: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
-    search: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
+    lookup: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VERSION_RETIRED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
+    search: ["INVALID_INPUT", "UNAUTHORIZED", "RESIDENCY_INGRESS", "NOT_FOUND", "METHOD_NOT_ALLOWED", "VERSION_RETIRED", "LIMIT_REACHED", "FAIR_USE_CEILING", "CANCELLED", "INTERNAL_ERROR", "UNAVAILABLE", "RESIDENCY_UNAVAILABLE"],
 };

package/dist/generated/types.d.ts

@@ -1,6 +1,6 @@
 /** The body of lookup. */
 export type LookupRequest = {
-    readonly acn: string;
+    readonly asicNumber: string;
 };
 /** The reply of lookup. */
 export type LookupResponse = {
@@ -13,7 +13,9 @@ export type LookupResponse = {
     readonly offset: 0;
     readonly records: ReadonlyArray<{
         readonly register: "companies";
-        readonly acn: string | null;
+        /** The ASIC number the register lists for this row (ACN or ARBN; see asicNumberType). */
+        readonly asicNumber: string;
+        readonly asicNumberType: "ACN" | "ARBN" | "ARSN" | "ARFN" | "undetermined";
         readonly name: string | null;
         readonly status: string | null;
         readonly abn: string | null;
@@ -80,7 +82,9 @@ export type SearchResponse = {
     readonly offset: 0;
     readonly records: ReadonlyArray<{
         readonly register: "companies";
-        readonly acn: string | null;
+        /** The ASIC number the register lists for this row (ACN or ARBN; see asicNumberType). */
+        readonly asicNumber: string;
+        readonly asicNumberType: "ACN" | "ARBN" | "ARSN" | "ARFN" | "undetermined";
         readonly name: string | null;
         readonly status: string | null;
         readonly abn: string | null;

package/dist/local/profile.d.ts

@@ -4,8 +4,13 @@ import type { FieldProfile } from "../runtime/field-types.js";
 /** One company record of the ASIC register snapshot. */
 export type ProductRecord = LookupResponse["records"][number];
 export declare const ATTRIBUTION = "Company data: Australian Securities and Investments Commission, via data.gov.au (CC BY 3.0 AU).";
-/** "001234567" as "001 234 567"; anything else is shown as it is. */
-export declare const formatAcn: (acn: string) => string;
-/** One line for a found company: name, ACN and status. The full record is in `onSelect`. */
+/** "001234564" as "001 234 564"; anything else is shown as it is. */
+export declare const formatAsicNumber: (value: string) => string;
+/**
+ * "ACN 001 234 564", "ARBN 001 234 591": the number named by the kind the register gives it
+ * (#714, #719). A number of unknown kind is an "ASIC number", never assumed to be an ACN.
+ */
+export declare const describeAsicNumber: (record: ProductRecord) => string;
+/** One line for a found company: name, the ASIC number with its kind, and status. The full record is in `onSelect`. */
 export declare const describeCompany: (record: ProductRecord) => string;
 export declare const profile: FieldProfile<CompanyClient, ProductRecord>;

package/dist/local/profile.js

@@ -1,27 +1,36 @@
 // The Company field's profile: the only company-specific code of the field. It reads the typed
-// text (a nine-digit ACN is looked up, anything else is searched by name), calls the client, and
+// text (a nine-digit ASIC number is looked up, anything else is searched by name), calls the client, and
 // reduces every reply to the text the UIs show and the record the consumer receives. The
 // controller, the React package and the web element are generated and know nothing else.
 import { isCommsIdError } from "../runtime/errors.js";
 export const ATTRIBUTION = "Company data: Australian Securities and Investments Commission, via data.gov.au (CC BY 3.0 AU).";
-const ACN_DIGITS = 9;
+const NUMBER_DIGITS = 9;
+const WEIGHTS = [8, 7, 6, 5, 4, 3, 2, 1];
 /** The contract allows ten rows at most. */
 const MAX_LIMIT = 10;
 const NUMBER_TEXT = /^[\d\s-]+$/;
 const SEPARATORS = /[\s-]/g;
-/** "001234567" as "001 234 567"; anything else is shown as it is. */
-export const formatAcn = (acn) => acn.length === ACN_DIGITS ? `${acn.slice(0, 3)} ${acn.slice(3, 6)} ${acn.slice(6)}` : acn;
+/** "001234564" as "001 234 564"; anything else is shown as it is. */
+export const formatAsicNumber = (value) => value.length === NUMBER_DIGITS ? `${value.slice(0, 3)} ${value.slice(3, 6)} ${value.slice(6)}` : value;
+/** ASIC's check digit, shared by every kind of ASIC number (#721): it validates, it never types. */
+const checkDigitIsValid = (digits) => (10 - (WEIGHTS.reduce((sum, weight, index) => sum + weight * Number(digits[index]), 0) % 10)) % 10 ===
+    Number(digits[NUMBER_DIGITS - 1]);
+/**
+ * "ACN 001 234 564", "ARBN 001 234 591": the number named by the kind the register gives it
+ * (#714, #719). A number of unknown kind is an "ASIC number", never assumed to be an ACN.
+ */
+export const describeAsicNumber = (record) => `${record.asicNumberType === "undetermined" ? "ASIC number" : record.asicNumberType} ${formatAsicNumber(record.asicNumber)}`;
 const nameOf = (record) => record.name ?? record.currentName ?? "Unnamed company";
 const compact = (parts) => parts.filter((part) => part !== null && part !== undefined && part !== "");
-/** One line for a found company: name, ACN and status. The full record is in `onSelect`. */
-export const describeCompany = (record) => compact([nameOf(record), record.acn === null ? undefined : `ACN ${formatAcn(record.acn)}`, record.status]).join(" · ");
+/** One line for a found company: name, the ASIC number with its kind, and status. The full record is in `onSelect`. */
+export const describeCompany = (record) => compact([nameOf(record), describeAsicNumber(record), record.status]).join(" · ");
 const foundOf = (reply, record) => ({
     record,
     summary: describeCompany(record),
     asAt: reply.activatedAt ?? reply.source.observedAt,
     attribution: reply.attribution,
 });
-/** The service answers an unknown name or ACN with NOT_FOUND: that is "no match", not a failure. */
+/** The service answers an unknown name or ASIC number with NOT_FOUND: that is "no match", not a failure. */
 const orNothing = async (call) => {
     try {
         return await call;
@@ -35,7 +44,7 @@ const orNothing = async (call) => {
 };
 export const profile = {
     attribution: ATTRIBUTION,
-    label: "Company name or ACN",
+    label: "Company name, ACN or ARBN",
     listLabel: "Company suggestions",
     noun: "company",
     notFound: "No company found.",
@@ -45,17 +54,24 @@ export const profile = {
     read: (text, context) => {
         const trimmed = text.trim();
         if (NUMBER_TEXT.test(trimmed)) {
-            const acn = trimmed.replace(SEPARATORS, "");
-            if (acn.length < ACN_DIGITS) {
+            const asicNumber = trimmed.replace(SEPARATORS, "");
+            if (asicNumber.length < NUMBER_DIGITS) {
                 return { kind: "incomplete" };
             }
-            if (acn.length > ACN_DIGITS) {
-                return { kind: "invalid", reason: "LENGTH", message: "An ACN has 9 digits." };
+            if (asicNumber.length > NUMBER_DIGITS) {
+                return { kind: "invalid", reason: "LENGTH", message: "An ACN or ARBN has 9 digits." };
+            }
+            if (!checkDigitIsValid(asicNumber)) {
+                return {
+                    kind: "invalid",
+                    reason: "CHECK_DIGIT",
+                    message: "This is not a valid ACN or ARBN: check the digits.",
+                };
             }
             return {
                 kind: "lookup",
                 run: async (client, options) => {
-                    const reply = await orNothing(client.lookup({ acn }, options));
+                    const reply = await orNothing(client.lookup({ asicNumber }, options));
                     const record = reply?.records[0];
                     return {
                         found: reply === undefined || record === undefined ? undefined : foundOf(reply, record),
@@ -81,9 +97,9 @@ export const profile = {
                     return { suggestions: [], attribution: undefined };
                 }
                 const suggestions = reply.records.map((record, index) => ({
-                    key: `${record.acn ?? "none"}-${index}`,
+                    key: `${record.asicNumber}-${index}`,
                     primary: nameOf(record),
-                    secondary: compact([record.acn === null ? undefined : `ACN ${formatAcn(record.acn)}`, record.status]).join(" · "),
+                    secondary: compact([describeAsicNumber(record), record.status]).join(" · "),
                     // The search already returned the whole record: choosing it needs no second call.
                     choose: { kind: "found", found: foundOf(reply, record) },
                 }));

package/dist/runtime/http.js

@@ -142,7 +142,9 @@ const prepare = (operation, input) => {
 /** Sends one operation and returns its decoded reply, or throws a CommsIdError. */
 export const call = async (transport, operation, input, options = {}) => {
     const body = prepare(operation, input);
-    const deadline = AbortSignal.timeout(options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS);
+    const deadlineMs = options.deadlineMs ?? transport.deadlineMs ?? DEFAULT_DEADLINE_MS;
+    const startedAt = performance.now();
+    const deadline = AbortSignal.timeout(deadlineMs);
     const signal = options.signal === undefined ? deadline : AbortSignal.any([options.signal, deadline]);
     const maxRetries = operation.safeToRetry ? (transport.maxRetries ?? DEFAULT_MAX_RETRIES) : 0;
     const sleep = transport.sleep ?? defaultSleep;
@@ -155,6 +157,11 @@ export const call = async (transport, operation, input, options = {}) => {
             throw result.error;
         }
         const delay = result.retryAfterMs ?? Math.min(BASE_DELAY_MS * 2 ** attempt, MAX_DELAY_MS);
+        // A retry that cannot start within this call's budget must not replace a real
+        // service failure (notably 429) with a later timeout or violate Retry-After.
+        if (delay >= deadlineMs - (performance.now() - startedAt)) {
+            throw result.error;
+        }
         try {
             await sleep(delay, signal);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comms-id/company",
-  "version": "0.5.0",
+  "version": "1.0.0",
   "description": "Typed client for the Comms.ID Company API: Australian companies from ASIC's public registers: search by name, look up one by ACN",
   "type": "module",
   "sideEffects": false,