@comms-id/asx 0.4.1 → 1.0.0

package/dist/snapshot.d.ts

@@ -0,0 +1,295 @@
+import { Schema } from "effect";
+import { DirectoryEntry } from "./model.js";
+import { ConfirmedEnrichment } from "./enrichment.js";
+export declare const CompanyRecord: 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 observation: Schema.NullOr<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 sources: Schema.optionalKey<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>;
+        }>>;
+    }>>;
+    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 missingAt: Schema.optionalKey<Schema.Struct<{
+        readonly startedAt: Schema.String;
+        readonly observedAt: Schema.String;
+    }>>;
+}>;
+export interface CompanyRecord extends Schema.Schema.Type<typeof CompanyRecord> {
+}
+declare const Dataset: Schema.Struct<{
+    readonly formatVersion: Schema.Literal<1>;
+    readonly directoryObservedAt: Schema.String;
+    readonly records: 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 observation: Schema.NullOr<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 sources: Schema.optionalKey<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>;
+            }>>;
+        }>>;
+        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 missingAt: Schema.optionalKey<Schema.Struct<{
+            readonly startedAt: Schema.String;
+            readonly observedAt: Schema.String;
+        }>>;
+    }>>;
+}>;
+export type AsxDataset = typeof Dataset.Type;
+export declare const SnapshotOutcome: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"found">;
+    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 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 generation: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"missing">;
+    readonly generation: Schema.String;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"unavailable">;
+    readonly generation: Schema.String;
+}>]>;
+export type SnapshotOutcome = typeof SnapshotOutcome.Type;
+export interface AsxSnapshot {
+    readonly generation: string;
+    /** Entire company row, including independent source payloads even when ASX details are absent. */
+    readonly record: (ticker: string) => CompanyRecord | null;
+    readonly lookup: (ticker: string, signal?: AbortSignal) => Promise<SnapshotOutcome>;
+    readonly suggest: (query: string, limit?: number) => readonly DirectoryEntry[];
+    readonly findByAbn: (abn: string) => readonly {
+        directory: DirectoryEntry;
+        enrichment: ConfirmedEnrichment;
+    }[];
+    readonly metadata: () => {
+        directoryObservedAt: string;
+        records: number;
+        availableProfiles: number;
+        confirmedAbns: number;
+        unresolvedAbns: number;
+        confirmedWebsites: number;
+    };
+}
+export declare function decodeDataset(input: unknown): AsxDataset;
+/** Build content-addressed bytes; the host must verify its write before selection. */
+export declare function encodeSnapshot(input: unknown): Promise<{
+    generation: string;
+    text: string;
+}>;
+/** The trusted host pins the expected generation; body content cannot choose it. */
+export declare function openSnapshot(text: string, expectedGeneration: string): Promise<AsxSnapshot>;
+export {};

package/dist/snapshot.js

@@ -0,0 +1,131 @@
+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";
+export const CompanyRecord = Schema.Struct({
+    directory: DirectoryEntry,
+    observation: Schema.NullOr(Observation),
+    sources: Schema.optionalKey(CompanySources),
+    enrichment: Schema.optionalKey(ConfirmedEnrichment),
+    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) }]
+                : []);
+        },
+        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": "1.0.0",
   "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,