@comms-id/asx 0.4.1 → 0.4.2

package/dist/snapshot.js

@@ -0,0 +1,151 @@
+import { suggestDirectory } from "./directory-search.js";
+import { Result, Schema } from "effect";
+import { DirectoryEntry, failure, isTimestamp, Observation, validObservation } from "./model.js";
+import { normalizeTicker } from "./parse.js";
+import { ConfirmedEnrichment, validAbn, validEnrichment } from "./enrichment.js";
+import { CompanySources, decodeCompanySources } from "./source-record.js";
+/**
+ * An ABN matched to a listed company by the owner-accepted name rules (#385): the
+ * full legal name, one trailing company suffix removed, a trailing "(THE)" moved to
+ * the front, or a comma ignored. A name match, never proof of issuer identity.
+ */
+export const AbnNameMatch = Schema.Struct({
+    abn: Schema.String.check(Schema.makeFilter(validAbn)),
+    acn: Schema.NullOr(Schema.String.check(Schema.isPattern(/^\d{9}$/))),
+    abnEntityName: Schema.NonEmptyString,
+    rule: Schema.Literals(["full-name", "suffix-removed", "the-moved", "comma-ignored"]),
+    abnSnapshotDate: Schema.String.check(Schema.isPattern(/^\d{4}-\d{2}-\d{2}$/)),
+});
+export const CompanyRecord = Schema.Struct({
+    directory: DirectoryEntry,
+    observation: Schema.NullOr(Observation),
+    sources: Schema.optionalKey(CompanySources),
+    enrichment: Schema.optionalKey(ConfirmedEnrichment),
+    abnNameMatch: Schema.optionalKey(AbnNameMatch),
+    missingAt: Schema.optionalKey(Schema.Struct({ startedAt: Schema.String, observedAt: Schema.String })),
+});
+const Dataset = Schema.Struct({
+    formatVersion: Schema.Literal(1),
+    directoryObservedAt: Schema.String,
+    records: Schema.Array(CompanyRecord),
+});
+const Generation = Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/));
+export const SnapshotOutcome = Schema.Union([
+    Schema.Struct({
+        status: Schema.Literal("found"),
+        observation: Observation,
+        enrichment: Schema.optionalKey(ConfirmedEnrichment),
+        generation: Generation,
+    }),
+    Schema.Struct({ status: Schema.Literal("missing"), generation: Generation }),
+    Schema.Struct({ status: Schema.Literal("unavailable"), generation: Generation }),
+]);
+const MAX_BYTES = 32 * 1024 * 1024;
+export function decodeDataset(input) {
+    const decoded = Schema.decodeUnknownResult(Dataset)(input);
+    if (Result.isFailure(decoded))
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    const dataset = decoded.success;
+    if (!isTimestamp(dataset.directoryObservedAt) ||
+        dataset.records.length === 0 ||
+        dataset.records.length > 20_000)
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    const tickers = new Set();
+    for (const record of dataset.records) {
+        if (tickers.has(record.directory.ticker) || !record.directory.companyName.trim())
+            throw failure("SNAPSHOT_UNAVAILABLE");
+        tickers.add(record.directory.ticker);
+        if (record.sources)
+            decodeCompanySources(record.sources, record.directory.ticker);
+        if (record.enrichment &&
+            (!record.observation || !validEnrichment(record.enrichment, record.observation.company)))
+            throw failure("SNAPSHOT_UNAVAILABLE");
+        if (record.missingAt &&
+            (record.observation !== null ||
+                !isTimestamp(record.missingAt.startedAt) ||
+                !isTimestamp(record.missingAt.observedAt) ||
+                record.missingAt.startedAt > record.missingAt.observedAt))
+            throw failure("SNAPSHOT_UNAVAILABLE");
+        if (record.observation &&
+            (!validObservation(record.observation) ||
+                record.observation.company.ticker !== record.directory.ticker))
+            throw failure("SNAPSHOT_UNAVAILABLE");
+    }
+    return dataset;
+}
+async function digest(text) {
+    const bytes = new TextEncoder().encode(text);
+    if (bytes.byteLength > MAX_BYTES)
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    const hash = await crypto.subtle.digest("SHA-256", bytes);
+    return Array.from(new Uint8Array(hash), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Build content-addressed bytes; the host must verify its write before selection. */
+export async function encodeSnapshot(input) {
+    const dataset = decodeDataset(input);
+    const text = JSON.stringify(dataset);
+    return { generation: await digest(text), text };
+}
+/** The trusted host pins the expected generation; body content cannot choose it. */
+export async function openSnapshot(text, expectedGeneration) {
+    if (!/^[a-f0-9]{64}$/.test(expectedGeneration) ||
+        typeof text !== "string" ||
+        text.length > MAX_BYTES)
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    if ((await digest(text)) !== expectedGeneration)
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    let input;
+    try {
+        input = JSON.parse(text);
+    }
+    catch {
+        throw failure("SNAPSHOT_UNAVAILABLE");
+    }
+    const dataset = decodeDataset(input);
+    const records = new Map(dataset.records.map((record) => [record.directory.ticker, record]));
+    return {
+        generation: expectedGeneration,
+        record: (ticker) => structuredClone(records.get(normalizeTicker(ticker)) ?? null),
+        lookup: async (inputTicker, signal) => {
+            if (signal?.aborted)
+                throw failure("CANCELLED");
+            const record = records.get(normalizeTicker(inputTicker));
+            if (!record)
+                return { status: "missing", generation: expectedGeneration };
+            if (record.missingAt)
+                return { status: "missing", generation: expectedGeneration };
+            if (!record.observation)
+                return { status: "unavailable", generation: expectedGeneration };
+            return {
+                status: "found",
+                observation: structuredClone(record.observation),
+                ...(record.enrichment ? { enrichment: structuredClone(record.enrichment) } : {}),
+                generation: expectedGeneration,
+            };
+        },
+        suggest: (query, limit = 8) => suggestDirectory(dataset.records.map((record) => record.directory), query, limit),
+        findByAbn: (abn) => {
+            if (typeof abn !== "string" || !validAbn(abn))
+                throw failure("INVALID_INPUT");
+            return dataset.records.flatMap((record) => record.enrichment?.abn === abn
+                ? [{ directory: { ...record.directory }, enrichment: structuredClone(record.enrichment) }]
+                : []);
+        },
+        findNameMatchesByAbn: (abn) => {
+            if (typeof abn !== "string" || !validAbn(abn))
+                throw failure("INVALID_INPUT");
+            return dataset.records.flatMap((record) => record.abnNameMatch?.abn === abn
+                ? [{ directory: { ...record.directory }, nameMatch: { ...record.abnNameMatch } }]
+                : []);
+        },
+        metadata: () => ({
+            directoryObservedAt: dataset.directoryObservedAt,
+            records: records.size,
+            availableProfiles: dataset.records.filter((record) => record.observation !== null).length,
+            confirmedAbns: dataset.records.filter((record) => record.enrichment !== undefined).length,
+            unresolvedAbns: dataset.records.filter((record) => record.enrichment === undefined).length,
+            confirmedWebsites: dataset.records.filter((record) => record.enrichment?.website != null)
+                .length,
+        }),
+    };
+}

package/dist/source-record.d.ts

@@ -0,0 +1,63 @@
+import { Schema } from "effect";
+import { type LiveOutcome } from "./model.js";
+export declare const ASX_COMPANY_BASE = "https://asx.api.markitdigital.com/asx-research/1.0/companies/";
+export declare function asxSourceObservation(ticker: string, result: LiveOutcome): SourceObservation;
+export declare const SourceName: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+export type SourceName = typeof SourceName.Type;
+export declare const SOURCE_NAMES: readonly SourceName[];
+/** Provider data remains separate. These fields do not select a preferred website. */
+export declare const SourceObservation: Schema.Struct<{
+    readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+    readonly ticker: Schema.String;
+    readonly sourceUrl: Schema.String;
+    readonly sourceId: Schema.NonEmptyString;
+    readonly status: Schema.Literals<readonly ["found", "missing"]>;
+    readonly startedAt: Schema.String;
+    readonly observedAt: Schema.String;
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly websites: Schema.$Array<Schema.String>;
+}>;
+export interface SourceObservation extends Schema.Schema.Type<typeof SourceObservation> {
+}
+export declare const CompanySources: Schema.Struct<{
+    readonly asx: Schema.optionalKey<Schema.Struct<{
+        readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+        readonly ticker: Schema.String;
+        readonly sourceUrl: Schema.String;
+        readonly sourceId: Schema.NonEmptyString;
+        readonly status: Schema.Literals<readonly ["found", "missing"]>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly websites: Schema.$Array<Schema.String>;
+    }>>;
+    readonly morningstar: Schema.optionalKey<Schema.Struct<{
+        readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+        readonly ticker: Schema.String;
+        readonly sourceUrl: Schema.String;
+        readonly sourceId: Schema.NonEmptyString;
+        readonly status: Schema.Literals<readonly ["found", "missing"]>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly websites: Schema.$Array<Schema.String>;
+    }>>;
+    readonly "google-finance": Schema.optionalKey<Schema.Struct<{
+        readonly source: Schema.Literals<readonly ["asx", "morningstar", "google-finance"]>;
+        readonly ticker: Schema.String;
+        readonly sourceUrl: Schema.String;
+        readonly sourceId: Schema.NonEmptyString;
+        readonly status: Schema.Literals<readonly ["found", "missing"]>;
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+        readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly websites: Schema.$Array<Schema.String>;
+    }>>;
+}>;
+export interface CompanySources extends Schema.Schema.Type<typeof CompanySources> {
+}
+/** Decode at every collector, storage and consumer boundary; never discard unknown payload fields. */
+export declare function decodeSourceObservation(input: unknown, ticker: string, source: SourceName): SourceObservation;
+export declare function decodeCompanySources(input: unknown, ticker: string): CompanySources;
+/** Only a newer observation of this source can replace it. Failure is not an observation. */
+export declare function mergeCompanySources(ticker: string, previous: CompanySources, incoming: CompanySources): CompanySources;

package/dist/source-record.js

@@ -0,0 +1,91 @@
+import { Result, Schema } from "effect";
+import { failure, isTimestamp, Ticker, Timestamp } from "./model.js";
+export const ASX_COMPANY_BASE = "https://asx.api.markitdigital.com/asx-research/1.0/companies/";
+export function asxSourceObservation(ticker, result) {
+    const found = result.status === "found" ? result.observation : null;
+    return decodeSourceObservation({
+        ticker,
+        source: "asx",
+        sourceId: found?.company.sourceId ?? ticker,
+        sourceUrl: `${ASX_COMPANY_BASE}${ticker}/about`,
+        status: result.status,
+        startedAt: found?.startedAt ?? (result.status === "missing" ? result.startedAt : ""),
+        observedAt: found?.observedAt ?? (result.status === "missing" ? result.observedAt : ""),
+        payload: found?.company.raw ?? (result.status === "missing" ? result.raw : undefined),
+        websites: found?.company.website ? [found.company.website] : [],
+    }, ticker, "asx");
+}
+export const SourceName = Schema.Literals(["asx", "morningstar", "google-finance"]);
+export const SOURCE_NAMES = ["asx", "morningstar", "google-finance"];
+/** Provider data remains separate. These fields do not select a preferred website. */
+export const SourceObservation = Schema.Struct({
+    source: SourceName,
+    ticker: Ticker,
+    sourceUrl: Schema.String,
+    sourceId: Schema.NonEmptyString,
+    status: Schema.Literals(["found", "missing"]),
+    startedAt: Timestamp,
+    observedAt: Timestamp,
+    payload: Schema.JsonObject,
+    websites: Schema.Array(Schema.String).check(Schema.isMaxLength(100)),
+});
+export const CompanySources = Schema.Struct({
+    asx: Schema.optionalKey(SourceObservation),
+    morningstar: Schema.optionalKey(SourceObservation),
+    "google-finance": Schema.optionalKey(SourceObservation),
+});
+function publicUrl(value) {
+    try {
+        const url = new URL(value);
+        return ["http:", "https:"].includes(url.protocol) && !url.username && !url.password;
+    }
+    catch {
+        return false;
+    }
+}
+/** Decode at every collector, storage and consumer boundary; never discard unknown payload fields. */
+export function decodeSourceObservation(input, ticker, source) {
+    const result = Schema.decodeUnknownResult(SourceObservation)(input);
+    if (Result.isFailure(result))
+        throw failure("PARSE_FAILED");
+    const value = result.success;
+    if (value.ticker !== ticker || value.source !== source)
+        throw failure("SOURCE_MISMATCH");
+    if (!isTimestamp(value.startedAt) ||
+        !isTimestamp(value.observedAt) ||
+        value.startedAt > value.observedAt ||
+        !publicUrl(value.sourceUrl) ||
+        value.websites.some((url) => !publicUrl(url)) ||
+        (value.status === "missing" && value.websites.length > 0) ||
+        new TextEncoder().encode(JSON.stringify(value)).byteLength > 1024 * 1024)
+        throw failure("PARSE_FAILED");
+    return structuredClone(value);
+}
+export function decodeCompanySources(input, ticker) {
+    const decoded = Schema.decodeUnknownResult(CompanySources)(input);
+    if (Result.isFailure(decoded))
+        throw failure("PARSE_FAILED");
+    const sources = {};
+    for (const source of SOURCE_NAMES) {
+        const value = decoded.success[source];
+        if (value)
+            sources[source] = decodeSourceObservation(value, ticker, source);
+    }
+    return sources;
+}
+/** Only a newer observation of this source can replace it. Failure is not an observation. */
+export function mergeCompanySources(ticker, previous, incoming) {
+    const merged = Object.assign({}, decodeCompanySources(previous, ticker));
+    const next = decodeCompanySources(incoming, ticker);
+    for (const source of SOURCE_NAMES) {
+        const value = next[source];
+        const prior = merged[source];
+        if (value &&
+            (!prior ||
+                value.startedAt > prior.startedAt ||
+                (value.startedAt === prior.startedAt && value.observedAt > prior.observedAt))) {
+            merged[source] = value;
+        }
+    }
+    return merged;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comms-id/asx",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Typed client for the Comms.ID ASX API: ASX-listed companies: suggest as a user types, and look one up",
   "type": "module",
   "sideEffects": false,