@comms-id/asx 0.4.1 → 1.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Typed client for the Comms.ID ASX API (`https://api.comms.id/asx/v1`): ASX-listed companies: suggest as a user types, and look one up.
 
-`src/` is generated from the ASX contract (`packages/asx-service/openapi/asx.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 ASX contract (`packages/asx-service/openapi/asx.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 { createAsxClient } from "@comms-id/asx/server";

package/dist/browser-profile.d.ts

@@ -0,0 +1,21 @@
+export type BrowserProfileSource = "morningstar" | "google-finance";
+export interface ProfileScrapeRequest {
+    readonly url: string;
+    readonly elements: readonly {
+        readonly selector: string;
+    }[];
+    readonly waitForSelector: {
+        readonly selector: string;
+        readonly timeout: number;
+        readonly visible: true;
+    };
+    readonly gotoOptions: {
+        readonly waitUntil: "domcontentloaded" | "networkidle2";
+        readonly timeout: number;
+    };
+}
+export type ProfileScraper = (request: ProfileScrapeRequest, signal: AbortSignal) => Promise<unknown>;
+/** Fixed public-page selectors; no LLM, login, cookies, provider token extraction or inferred URLs. */
+export declare function profileScrapeRequest(source: BrowserProfileSource, input: string): ProfileScrapeRequest;
+/** The host supplies an authorized browser runner. This adapter never chooses or provisions one. */
+export declare function createBrowserProfileSource(source: BrowserProfileSource, scrape: ProfileScraper): (input: string, signal?: AbortSignal) => Promise<import("./source-record.js").SourceObservation>;

package/dist/browser-profile.js

@@ -0,0 +1,115 @@
+import { Effect, Result, Schema } from "effect";
+import { failure, Failure } from "./model.js";
+import { normalizeTicker } from "./parse.js";
+import { decodeSourceObservation } from "./source-record.js";
+const Scrape = Schema.Struct({
+    success: Schema.Literal(true),
+    result: Schema.Array(Schema.Struct({
+        selector: Schema.String,
+        results: Schema.Array(Schema.Struct({
+            text: Schema.String,
+            html: Schema.String,
+            attributes: Schema.Array(Schema.Struct({ name: Schema.String, value: Schema.String })),
+        })),
+    })),
+});
+const selectors = {
+    morningstar: {
+        profile: ".sal-component-body:has(.sal-dp-pair-contact)",
+        links: ".sal-dp-pair-contact a",
+    },
+    "google-finance": { profile: ".LuLFhc", links: ".LuLFhc a" },
+};
+/** Fixed public-page selectors; no LLM, login, cookies, provider token extraction or inferred URLs. */
+export function profileScrapeRequest(source, input) {
+    const ticker = normalizeTicker(input);
+    const selected = selectors[source];
+    if (!selected)
+        throw failure("INVALID_INPUT");
+    return {
+        url: source === "morningstar"
+            ? `https://www.morningstar.com.au/investments/security/ASX/${ticker}/profile`
+            : `https://www.google.com/finance/beta/quote/${ticker}:ASX`,
+        elements: [{ selector: "title" }, { selector: selected.profile }, { selector: selected.links }],
+        waitForSelector: {
+            selector: source === "morningstar" ? ".sal-dp-pair-contact .sal-dp-value" : selected.profile,
+            timeout: 15_000,
+            visible: true,
+        },
+        // Morningstar renders its contact section after the initial document loads.
+        gotoOptions: {
+            waitUntil: source === "morningstar" ? "networkidle2" : "domcontentloaded",
+            timeout: 15_000,
+        },
+    };
+}
+/** The host supplies an authorized browser runner. This adapter never chooses or provisions one. */
+export function createBrowserProfileSource(source, scrape) {
+    return async (input, signal) => {
+        const ticker = normalizeTicker(input);
+        const request = profileScrapeRequest(source, ticker);
+        const startedAt = new Date().toISOString();
+        const program = Effect.tryPromise({
+            try: (signal) => scrape(request, signal),
+            catch: (error) => Schema.is(Failure)(error) ? failure(error.code) : failure("TRANSPORT_FAILED"),
+        }).pipe(Effect.flatMap((input) => Effect.try({
+            try: () => {
+                const decoded = Schema.decodeUnknownResult(Scrape)(input);
+                const raw = Schema.decodeUnknownResult(Schema.JsonObject)(input);
+                if (Result.isFailure(decoded) || Result.isFailure(raw))
+                    throw failure("PARSE_FAILED");
+                const sections = decoded.success.result;
+                const title = sections.find((section) => section.selector === "title")?.results;
+                const profile = sections.find((section) => section.selector === selectors[source].profile)?.results;
+                const links = sections.find((section) => section.selector === selectors[source].links)?.results;
+                const marker = source === "morningstar" ? `(ASX:${ticker})` : `(${ticker})`;
+                if (title?.length !== 1 || !title[0].text.includes(marker))
+                    throw failure("SOURCE_MISMATCH");
+                if (!profile?.length ||
+                    !links ||
+                    !profile.some((item) => source === "morningstar"
+                        ? /\bContact\b/.test(item.text)
+                        : item.text.trim().startsWith("Website")))
+                    throw failure("PARSE_FAILED");
+                const websites = [
+                    ...new Set(links
+                        .filter((link) => source === "morningstar" ||
+                        (link.text.trim() &&
+                            profile.some((item) => item.text.trim().startsWith("Website") &&
+                                item.text.includes(link.text.trim()))))
+                        .flatMap((link) => link.attributes
+                        .filter((attribute) => attribute.name === "href" && /^https?:\/\//i.test(attribute.value))
+                        .map((attribute) => attribute.value))),
+                ];
+                return decodeSourceObservation({
+                    source,
+                    ticker,
+                    sourceId: `${ticker}:ASX`,
+                    sourceUrl: request.url,
+                    startedAt,
+                    observedAt: new Date().toISOString(),
+                    status: "found",
+                    websites,
+                    payload: { format: "rendered-profile", response: raw.success },
+                }, ticker, source);
+            },
+            catch: (error) => Schema.is(Failure)(error) ? failure(error.code) : failure("PARSE_FAILED"),
+        })), 
+        // A partially rendered public profile may recover on one fresh navigation.
+        // Access/rate refusals and identity mismatches must not trigger a retry.
+        Effect.retry({ times: 1, while: (error) => error.code === "PARSE_FAILED" }), Effect.timeoutOrElse({ duration: 30_000, orElse: () => Effect.fail(failure("TIMEOUT")) }));
+        try {
+            const result = await Effect.runPromise(Effect.result(program), { signal });
+            if (Result.isFailure(result))
+                throw result.failure;
+            return result.success;
+        }
+        catch (error) {
+            throw signal?.aborted
+                ? failure("CANCELLED")
+                : Schema.is(Failure)(error)
+                    ? error
+                    : failure("INTERNAL_ERROR");
+        }
+    };
+}

package/dist/client-replies.d.ts

@@ -0,0 +1,161 @@
+import { Schema } from "effect";
+export declare const LookupResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"found">;
+    readonly source: Schema.Literal<"live">;
+    readonly observation: Schema.Struct<{
+        readonly company: Schema.Struct<{
+            readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            readonly ticker: Schema.String;
+            readonly sourceId: Schema.String;
+            readonly companyName: Schema.String;
+            readonly address: Schema.NullOr<Schema.String>;
+            readonly tel: Schema.NullOr<Schema.String>;
+            readonly fax: Schema.NullOr<Schema.String>;
+            readonly website: Schema.NullOr<Schema.String>;
+            readonly description: Schema.NullOr<Schema.String>;
+            readonly issueType: Schema.NullOr<Schema.String>;
+            readonly foreignExempt: Schema.NullOr<Schema.Boolean>;
+            readonly people: Schema.$Array<Schema.Struct<{
+                readonly sourceName: Schema.String;
+                readonly displayName: Schema.String;
+                readonly title: Schema.String;
+                readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+            }>>;
+        }>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly lastChangedAt: Schema.String;
+    }>;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"missing">;
+    readonly source: Schema.Literal<"live">;
+    readonly startedAt: Schema.String;
+    readonly observedAt: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"found">;
+    readonly source: Schema.Literal<"snapshot">;
+    readonly observation: Schema.Struct<{
+        readonly company: Schema.Struct<{
+            readonly raw: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            readonly ticker: Schema.String;
+            readonly sourceId: Schema.String;
+            readonly companyName: Schema.String;
+            readonly address: Schema.NullOr<Schema.String>;
+            readonly tel: Schema.NullOr<Schema.String>;
+            readonly fax: Schema.NullOr<Schema.String>;
+            readonly website: Schema.NullOr<Schema.String>;
+            readonly description: Schema.NullOr<Schema.String>;
+            readonly issueType: Schema.NullOr<Schema.String>;
+            readonly foreignExempt: Schema.NullOr<Schema.Boolean>;
+            readonly people: Schema.$Array<Schema.Struct<{
+                readonly sourceName: Schema.String;
+                readonly displayName: Schema.String;
+                readonly title: Schema.String;
+                readonly sourceCategory: Schema.Literals<readonly ["directors", "secretaries"]>;
+            }>>;
+        }>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly lastChangedAt: Schema.String;
+    }>;
+    readonly generation: Schema.String;
+    readonly enrichment: Schema.optionalKey<Schema.Struct<{
+        readonly ticker: Schema.String;
+        readonly sourceId: Schema.NonEmptyString;
+        readonly abn: Schema.String;
+        readonly acn: Schema.NullOr<Schema.String>;
+        readonly legalName: Schema.NonEmptyString;
+        readonly identityEvidence: Schema.Struct<{
+            readonly url: Schema.String;
+            readonly sha256: Schema.String;
+            readonly observedAt: Schema.String;
+            readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+        }>;
+        readonly abrEvidence: Schema.Struct<{
+            readonly source: Schema.Literals<readonly ["abr-live", "abr-snapshot"]>;
+            readonly observedAt: Schema.String;
+        }>;
+        readonly website: Schema.NullOr<Schema.Struct<{
+            readonly url: Schema.String;
+            readonly evidence: Schema.Struct<{
+                readonly url: Schema.String;
+                readonly sha256: Schema.String;
+                readonly observedAt: Schema.String;
+                readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+            }>;
+        }>>;
+    }>>;
+    readonly requiresRecheck: Schema.Literal<true>;
+    readonly fallbackReason: Schema.optionalKey<Schema.Literals<readonly ["INVALID_INPUT", "PARSE_FAILED", "SOURCE_MISMATCH", "TRANSPORT_FAILED", "TIMEOUT", "RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "CONFIGURATION_ERROR", "SNAPSHOT_UNAVAILABLE", "CANCELLED", "INTERNAL_ERROR", "ACCESS_DENIED", "UPSTREAM_REJECTED", "PERSISTENCE_FAILED", "PUBLICATION_CONFLICT", "COVERAGE_REJECTED"]>>;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"missing">;
+    readonly source: Schema.Literal<"snapshot">;
+    readonly generation: Schema.String;
+}>]>;
+export declare const SuggestionsResponse: Schema.Union<readonly [Schema.Struct<{
+    readonly source: Schema.Literal<"live">;
+    readonly directoryObservedAt: Schema.String;
+    readonly suggestions: Schema.$Array<Schema.Struct<{
+        readonly ticker: Schema.String;
+        readonly companyName: Schema.String;
+        readonly industryGroup: Schema.NullOr<Schema.String>;
+        readonly listingDate: Schema.NullOr<Schema.String>;
+        readonly marketCapitalisation: Schema.NullOr<Schema.Number>;
+    }>>;
+}>, Schema.Struct<{
+    readonly source: Schema.Literal<"snapshot">;
+    readonly generation: Schema.String;
+    readonly directoryObservedAt: Schema.String;
+    readonly requiresRecheck: Schema.Literal<true>;
+    readonly suggestions: Schema.$Array<Schema.Struct<{
+        readonly ticker: Schema.String;
+        readonly companyName: Schema.String;
+        readonly industryGroup: Schema.NullOr<Schema.String>;
+        readonly listingDate: Schema.NullOr<Schema.String>;
+        readonly marketCapitalisation: Schema.NullOr<Schema.Number>;
+    }>>;
+    readonly fallbackReason: Schema.optionalKey<Schema.Literals<readonly ["INVALID_INPUT", "PARSE_FAILED", "SOURCE_MISMATCH", "TRANSPORT_FAILED", "TIMEOUT", "RATE_LIMITED", "UPSTREAM_UNAVAILABLE", "CONFIGURATION_ERROR", "SNAPSHOT_UNAVAILABLE", "CANCELLED", "INTERNAL_ERROR", "ACCESS_DENIED", "UPSTREAM_REJECTED", "PERSISTENCE_FAILED", "PUBLICATION_CONFLICT", "COVERAGE_REJECTED"]>>;
+}>]>;
+export type SuggestionsReply = typeof SuggestionsResponse.Type;
+export declare const AbnMatchesResponse: Schema.Struct<{
+    readonly source: Schema.Literal<"snapshot">;
+    readonly generation: Schema.String;
+    readonly directoryObservedAt: Schema.String;
+    readonly requiresRecheck: Schema.Literal<true>;
+    readonly matches: Schema.$Array<Schema.Struct<{
+        readonly directory: Schema.Struct<{
+            readonly ticker: Schema.String;
+            readonly companyName: Schema.String;
+            readonly industryGroup: Schema.NullOr<Schema.String>;
+            readonly listingDate: Schema.NullOr<Schema.String>;
+            readonly marketCapitalisation: Schema.NullOr<Schema.Number>;
+        }>;
+        readonly enrichment: Schema.Struct<{
+            readonly ticker: Schema.String;
+            readonly sourceId: Schema.NonEmptyString;
+            readonly abn: Schema.String;
+            readonly acn: Schema.NullOr<Schema.String>;
+            readonly legalName: Schema.NonEmptyString;
+            readonly identityEvidence: Schema.Struct<{
+                readonly url: Schema.String;
+                readonly sha256: Schema.String;
+                readonly observedAt: Schema.String;
+                readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+            }>;
+            readonly abrEvidence: Schema.Struct<{
+                readonly source: Schema.Literals<readonly ["abr-live", "abr-snapshot"]>;
+                readonly observedAt: Schema.String;
+            }>;
+            readonly website: Schema.NullOr<Schema.Struct<{
+                readonly url: Schema.String;
+                readonly evidence: Schema.Struct<{
+                    readonly url: Schema.String;
+                    readonly sha256: Schema.String;
+                    readonly observedAt: Schema.String;
+                    readonly kind: Schema.Literals<readonly ["issuer-filing", "issuer-website"]>;
+                }>;
+            }>>;
+        }>;
+    }>>;
+}>;
+export type AbnMatchesReply = typeof AbnMatchesResponse.Type;

package/dist/client-replies.js

@@ -0,0 +1,54 @@
+import { Schema } from "effect";
+import { ConfirmedEnrichment } from "./enrichment.js";
+import { DirectoryEntry, Failure, Observation, Timestamp } from "./model.js";
+const Generation = Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/));
+export const LookupResponse = Schema.Union([
+    Schema.Struct({
+        status: Schema.Literal("found"),
+        source: Schema.Literal("live"),
+        observation: Observation,
+    }),
+    Schema.Struct({
+        status: Schema.Literal("missing"),
+        source: Schema.Literal("live"),
+        startedAt: Timestamp,
+        observedAt: Timestamp,
+    }),
+    Schema.Struct({
+        status: Schema.Literal("found"),
+        source: Schema.Literal("snapshot"),
+        observation: Observation,
+        generation: Generation,
+        enrichment: Schema.optionalKey(ConfirmedEnrichment),
+        requiresRecheck: Schema.Literal(true),
+        fallbackReason: Schema.optionalKey(Failure.fields.code),
+    }),
+    Schema.Struct({
+        status: Schema.Literal("missing"),
+        source: Schema.Literal("snapshot"),
+        generation: Generation,
+    }),
+]);
+const Saved = {
+    source: Schema.Literal("snapshot"),
+    generation: Generation,
+    directoryObservedAt: Timestamp,
+    requiresRecheck: Schema.Literal(true),
+};
+const Suggestions = Schema.Array(DirectoryEntry).check(Schema.isMaxLength(10));
+export const SuggestionsResponse = Schema.Union([
+    Schema.Struct({
+        source: Schema.Literal("live"),
+        directoryObservedAt: Timestamp,
+        suggestions: Suggestions,
+    }),
+    Schema.Struct({
+        ...Saved,
+        suggestions: Suggestions,
+        fallbackReason: Schema.optionalKey(Failure.fields.code),
+    }),
+]);
+export const AbnMatchesResponse = Schema.Struct({
+    ...Saved,
+    matches: Schema.Array(Schema.Struct({ directory: DirectoryEntry, enrichment: ConfirmedEnrichment })).check(Schema.isMaxLength(20_000)),
+});

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import { type AbnMatchesReply, type SuggestionsReply } from "./client-replies.js";
+import type { LookupMode, LookupReply } from "./service.js";
+export type { AbnMatchesReply, SuggestionsReply } from "./client-replies.js";
+export interface AsxClientConfig {
+    readonly baseUrl: string;
+    /** Return a short-lived service capability. Honour cancellation while acquiring it. */
+    readonly capability: (signal: AbortSignal) => Promise<string>;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly timeoutMs?: number;
+}
+export interface AsxRequestOptions {
+    readonly signal?: AbortSignal;
+}
+/** Read-only hosted-service client. This does not contact ASX directly or supply fallback itself. */
+export declare function createAsxClient(config: AsxClientConfig): {
+    observe: (input: string, options?: import("./company-stream.js").CompanyStreamOptions) => AsyncGenerator<import("./company-stream.js").CompanyEvent>;
+    lookup: (input: string, options?: AsxRequestOptions & {
+        readonly mode?: LookupMode;
+    }) => Promise<LookupReply>;
+    suggest: (query: string, options?: AsxRequestOptions & {
+        readonly limit?: number;
+        readonly mode?: LookupMode;
+    }) => Promise<SuggestionsReply>;
+    findByAbn: (abn: string, options?: AsxRequestOptions) => Promise<AbnMatchesReply>;
+};

package/dist/client.js

@@ -0,0 +1,179 @@
+import { Effect, Result, Schema } from "effect";
+import { AbnMatchesResponse, LookupResponse, SuggestionsResponse, } from "./client-replies.js";
+import { validAbn, validEnrichment } from "./enrichment.js";
+import { boundedText } from "./http.js";
+import { failure, Failure, isFallbackEligible, isTimestamp, validObservation, } from "./model.js";
+import { normalizeTicker } from "./parse.js";
+import { createCompanyStreamClient } from "./company-stream-client.js";
+const safe = (error) => Schema.is(Failure)(error) ? failure(error.code) : failure("TRANSPORT_FAILED");
+const ErrorResponse = Schema.Struct({ code: Failure.fields.code });
+/** Read-only hosted-service client. This does not contact ASX directly or supply fallback itself. */
+export function createAsxClient(config) {
+    let base;
+    try {
+        base = new URL(config.baseUrl.endsWith("/") ? config.baseUrl : `${config.baseUrl}/`);
+        if (base.protocol !== "https:" ||
+            base.username ||
+            base.password ||
+            base.search ||
+            base.hash ||
+            typeof config.capability !== "function")
+            throw new Error();
+    }
+    catch {
+        throw failure("CONFIGURATION_ERROR");
+    }
+    const timeoutMs = config.timeoutMs ?? 20_000;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 60_000)
+        throw failure("CONFIGURATION_ERROR");
+    const transport = config.fetch ?? globalThis.fetch;
+    const request = async (path, body, schema, options) => {
+        if (options.signal?.aborted)
+            throw failure("CANCELLED");
+        const program = Effect.gen(function* () {
+            const token = yield* Effect.tryPromise({
+                try: (signal) => config.capability(signal),
+                catch: () => failure("ACCESS_DENIED"),
+            });
+            if (typeof token !== "string" ||
+                !token.trim() ||
+                token.length > 8192 ||
+                /\s/.test(token.trim()))
+                return yield* Effect.fail(failure("CONFIGURATION_ERROR"));
+            const input = yield* Effect.tryPromise({
+                try: async (signal) => {
+                    const response = await transport(new URL(path, base), {
+                        method: "POST",
+                        body: JSON.stringify(body),
+                        signal,
+                        redirect: "manual",
+                        cache: "no-store",
+                        headers: {
+                            "content-type": "application/json",
+                            accept: "application/json",
+                            authorization: `Bearer ${token.trim()}`,
+                        },
+                    });
+                    if (response.status === 401 ||
+                        response.status === 403 ||
+                        (response.status >= 300 && response.status < 400)) {
+                        await response.body?.cancel();
+                        throw failure(response.status < 400 ? "UPSTREAM_REJECTED" : "ACCESS_DENIED");
+                    }
+                    const text = await boundedText(response, response.ok ? 1024 * 1024 : 4096, signal);
+                    let payload;
+                    try {
+                        payload = JSON.parse(text);
+                    }
+                    catch {
+                        throw failure(response.ok ? "PARSE_FAILED" : "UPSTREAM_UNAVAILABLE");
+                    }
+                    if (!response.ok) {
+                        const decoded = Schema.decodeUnknownResult(ErrorResponse)(payload);
+                        if (Result.isSuccess(decoded))
+                            throw failure(decoded.success.code);
+                        throw failure(response.status === 429
+                            ? "RATE_LIMITED"
+                            : response.status >= 500
+                                ? "UPSTREAM_UNAVAILABLE"
+                                : "UPSTREAM_REJECTED");
+                    }
+                    return payload;
+                },
+                catch: safe,
+            });
+            return yield* Schema.decodeUnknownEffect(schema)(input).pipe(Effect.mapError(() => failure("PARSE_FAILED")));
+        }).pipe(Effect.timeoutOrElse({ duration: timeoutMs, orElse: () => Effect.fail(failure("TIMEOUT")) }));
+        try {
+            const result = await Effect.runPromise(Effect.result(program), { signal: options.signal });
+            if (Result.isFailure(result))
+                throw result.failure;
+            return result.success;
+        }
+        catch (error) {
+            throw options.signal?.aborted ? failure("CANCELLED") : safe(error);
+        }
+    };
+    return {
+        observe: createCompanyStreamClient(config, base),
+        lookup: async (input, options = {}) => {
+            const ticker = normalizeTicker(input);
+            const mode = options.mode ?? "live-first";
+            if (!["live", "snapshot", "live-first"].includes(mode))
+                throw failure("INVALID_INPUT");
+            const reply = await request("lookup", { ticker, mode }, LookupResponse, options);
+            if ((mode === "live" && reply.source !== "live") ||
+                (mode === "snapshot" && reply.source !== "snapshot") ||
+                (mode === "live-first" && reply.source === "snapshot" && reply.status === "missing"))
+                throw failure("SOURCE_MISMATCH");
+            if (reply.status === "found") {
+                if (!validObservation(reply.observation))
+                    throw failure("PARSE_FAILED");
+                if (reply.observation.company.ticker !== ticker)
+                    throw failure("SOURCE_MISMATCH");
+                if (reply.source === "snapshot") {
+                    if (reply.enrichment && !validEnrichment(reply.enrichment, reply.observation.company))
+                        throw failure("SOURCE_MISMATCH");
+                    if (reply.fallbackReason && !isFallbackEligible(reply.fallbackReason))
+                        throw failure("PARSE_FAILED");
+                    if ((mode === "live-first" && reply.fallbackReason === undefined) ||
+                        (mode === "snapshot" && reply.fallbackReason !== undefined))
+                        throw failure("SOURCE_MISMATCH");
+                }
+            }
+            else if (reply.source === "live" &&
+                (!isTimestamp(reply.startedAt) ||
+                    !isTimestamp(reply.observedAt) ||
+                    reply.startedAt > reply.observedAt))
+                throw failure("PARSE_FAILED");
+            return reply;
+        },
+        suggest: async (query, options = {}) => {
+            const limit = options.limit ?? 8;
+            const mode = options.mode ?? "snapshot";
+            if (!["live", "snapshot", "live-first"].includes(mode))
+                throw failure("INVALID_INPUT");
+            if (typeof query !== "string" ||
+                query.length > 200 ||
+                !Number.isInteger(limit) ||
+                limit < 1 ||
+                limit > 10)
+                throw failure("INVALID_INPUT");
+            const reply = await request("suggest", { query, limit, ...(options.mode ? { mode } : {}) }, SuggestionsResponse, options);
+            if (!isTimestamp(reply.directoryObservedAt) ||
+                reply.suggestions.length > limit ||
+                new Set(reply.suggestions.map((entry) => entry.ticker)).size !== reply.suggestions.length ||
+                reply.suggestions.some((entry) => !entry.companyName.trim()))
+                throw failure("PARSE_FAILED");
+            if ((mode === "live" && reply.source !== "live") ||
+                (mode === "snapshot" && reply.source !== "snapshot"))
+                throw failure("SOURCE_MISMATCH");
+            if (reply.source === "snapshot") {
+                if (reply.fallbackReason !== undefined && !isFallbackEligible(reply.fallbackReason))
+                    throw failure("PARSE_FAILED");
+                if ((mode === "live-first" && reply.fallbackReason === undefined) ||
+                    (mode === "snapshot" && reply.fallbackReason !== undefined))
+                    throw failure("SOURCE_MISMATCH");
+            }
+            return reply;
+        },
+        findByAbn: async (abn, options = {}) => {
+            if (typeof abn !== "string" || !validAbn(abn))
+                throw failure("INVALID_INPUT");
+            const reply = await request("abn", { abn }, AbnMatchesResponse, options);
+            if (!isTimestamp(reply.directoryObservedAt) ||
+                new Set(reply.matches.map((match) => match.directory.ticker)).size !== reply.matches.length)
+                throw failure("PARSE_FAILED");
+            for (const { directory, enrichment } of reply.matches) {
+                if (enrichment.abn !== abn || enrichment.ticker !== directory.ticker)
+                    throw failure("SOURCE_MISMATCH");
+                if (!directory.companyName.trim() ||
+                    !isTimestamp(enrichment.identityEvidence.observedAt) ||
+                    !isTimestamp(enrichment.abrEvidence.observedAt) ||
+                    (enrichment.website && !isTimestamp(enrichment.website.evidence.observedAt)))
+                    throw failure("PARSE_FAILED");
+            }
+            return reply;
+        },
+    };
+}