@cyanheads/secedgar-mcp-server 0.7.0 → 0.7.2

package/dist/services/edgar/mirror/companyfacts-sync.js

@@ -0,0 +1,157 @@
+/**
+ * @fileoverview Ingester for the XBRL company-facts layer. Streams SEC's
+ * `companyfacts.zip` (~1.3 GB) through fflate, parsing each `CIK*.json` entry
+ * into one row per (cik, taxonomy, tag) with the concept's `units` map stored as
+ * a JSON blob. Bounded memory: one entry is buffered at a time and rows drain to
+ * the framework in batched pages. Upsert-only — a company dropped from the bulk
+ * archive lingers (low-harm; re-upserted whenever it reappears).
+ * @module services/edgar/mirror/companyfacts-sync
+ */
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { Unzip, UnzipInflate } from 'fflate';
+import { COMPANY_FACTS_ZIP_URL, lastModifiedToIso } from './types.js';
+/** Rows drained to the framework per page (one transaction each). */
+const BATCH_ROWS = 2000;
+const EMPTY = new Uint8Array(0);
+/** Expand one company's `facts` into per-(taxonomy, tag) rows. Exported for tests. */
+export function fileToRows(json) {
+    const rows = [];
+    if (typeof json.cik !== 'number' || !json.facts)
+        return rows;
+    const cik = String(json.cik).padStart(10, '0');
+    const entityName = json.entityName ?? '';
+    for (const [taxonomy, tags] of Object.entries(json.facts)) {
+        for (const [tag, concept] of Object.entries(tags)) {
+            if (!concept?.units)
+                continue;
+            rows.push({
+                id: `${cik}|${taxonomy}|${tag}`,
+                cik,
+                taxonomy,
+                tag,
+                entity_name: entityName,
+                label: concept.label ?? tag,
+                description: concept.description ?? null,
+                units_json: JSON.stringify(concept.units),
+            });
+        }
+    }
+    return rows;
+}
+/** HEAD the bulk archive for its `Last-Modified`, normalized to ISO. Best-effort. */
+async function headLastModifiedIso(userAgent, signal) {
+    try {
+        const res = await fetch(COMPANY_FACTS_ZIP_URL, {
+            method: 'HEAD',
+            headers: { 'User-Agent': userAgent },
+            signal,
+        });
+        const lm = res.headers.get('last-modified');
+        return lm ? lastModifiedToIso(lm) : undefined;
+    }
+    catch {
+        return;
+    }
+}
+/**
+ * Build the company-facts ingester. On `refresh`, a HEAD check short-circuits
+ * when the archive has not been rebuilt since the stored checkpoint. The bulk
+ * archive is a full nightly snapshot, so a sync re-streams it whole and relies
+ * on idempotent upserts; the framework persists each page transactionally, so an
+ * interrupted run is crash-safe (a resume re-applies harmlessly).
+ */
+export function makeCompanyFactsSync(opts) {
+    return async function* companyFactsSync(ctx) {
+        const lastModified = await headLastModifiedIso(opts.userAgent, ctx.signal);
+        if (ctx.mode === 'refresh' &&
+            ctx.checkpoint &&
+            lastModified &&
+            lastModified <= ctx.checkpoint) {
+            opts.log?.info?.('companyfacts.zip unchanged since last sync; skipping', {
+                checkpoint: ctx.checkpoint,
+            });
+            return;
+        }
+        const response = await fetch(COMPANY_FACTS_ZIP_URL, {
+            headers: { 'User-Agent': opts.userAgent },
+            signal: ctx.signal,
+        });
+        if (!response.ok || !response.body) {
+            throw serviceUnavailable(`SEC companyfacts.zip download failed (HTTP ${response.status})`, {
+                url: COMPANY_FACTS_ZIP_URL,
+                status: response.status,
+            });
+        }
+        const checkpoint = lastModifiedToIso(response.headers.get('last-modified')) || lastModified;
+        const pending = [];
+        let completedFiles = 0;
+        let skipped = 0;
+        let streamError;
+        const unzip = new Unzip();
+        unzip.register(UnzipInflate);
+        unzip.onfile = (file) => {
+            const isCik = /CIK\d+\.json$/i.test(file.name);
+            const chunks = [];
+            file.ondata = (err, chunk, final) => {
+                if (err) {
+                    streamError ??= err;
+                    return;
+                }
+                if (!isCik)
+                    return;
+                if (chunk?.length)
+                    chunks.push(chunk);
+                if (!final)
+                    return;
+                try {
+                    const json = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+                    const rows = fileToRows(json);
+                    if (rows.length)
+                        pending.push(...rows);
+                }
+                catch {
+                    skipped += 1;
+                    opts.log?.warning?.('Skipping unparseable companyfacts entry', { name: file.name });
+                }
+                completedFiles += 1;
+                chunks.length = 0;
+            };
+            file.start();
+        };
+        const reader = response.body.getReader();
+        try {
+            for (;;) {
+                if (ctx.signal.aborted) {
+                    throw ctx.signal.reason instanceof Error
+                        ? ctx.signal.reason
+                        : new Error('companyfacts sync aborted');
+                }
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                unzip.push(value, false);
+                if (streamError)
+                    throw streamError;
+                while (pending.length >= BATCH_ROWS) {
+                    yield {
+                        records: pending.splice(0, BATCH_ROWS),
+                        cursor: String(completedFiles),
+                        checkpoint,
+                    };
+                }
+            }
+            unzip.push(EMPTY, true);
+            if (streamError)
+                throw streamError;
+        }
+        finally {
+            reader.releaseLock();
+        }
+        if (skipped > 0)
+            opts.log?.notice?.('companyfacts sync complete with skips', { completedFiles, skipped });
+        while (pending.length) {
+            yield { records: pending.splice(0, BATCH_ROWS), cursor: String(completedFiles), checkpoint };
+        }
+    };
+}
+//# sourceMappingURL=companyfacts-sync.js.map

package/dist/services/edgar/mirror/companyfacts-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companyfacts-sync.js","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/companyfacts-sync.ts"],"names":[],"mappings":"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"}

package/dist/services/edgar/mirror/edgar-mirror.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @fileoverview `EdgarMirror` — owns the two framework `Mirror` instances (the
+ * ticker/CIK layer and the XBRL company-facts layer) and the read helpers that
+ * reconstruct the live API's `companyconcept` and `frames` response shapes off
+ * the local SQLite stores. The service routes through these when the mirror is
+ * ready; callers gate on `tickersReady()` / `companyFactsReady()`.
+ * @module services/edgar/mirror/edgar-mirror
+ */
+import { type Mirror, type MirrorLogger, type SyncProgress, type SyncResult } from '@cyanheads/mcp-ts-core/mirror';
+import type { CompanyConceptResponse, FramesResponse } from '../types.js';
+import { type TickerRow } from './types.js';
+export interface EdgarMirrorOptions {
+    /** Directory holding the SQLite databases (`EDGAR_MIRROR_PATH`). */
+    dir: string;
+    /** Logger for ingester warnings (per-file skips, refresh no-ops). */
+    log?: MirrorLogger;
+    /** SEC User-Agent for the bulk downloads. */
+    userAgent: string;
+}
+type MirrorLayer = 'tickers' | 'companyfacts';
+export interface MirrorRunArgs {
+    onProgress?: (layer: MirrorLayer, info: Parameters<SyncProgress>[0]) => void;
+    signal: AbortSignal;
+}
+export declare class EdgarMirror {
+    readonly tickers: Mirror;
+    readonly companyFacts: Mirror;
+    private _tickersReady;
+    private _companyFactsReady;
+    constructor(opts: EdgarMirrorOptions);
+    /** Memoized readiness — the durable completion marker only flips false→true. */
+    tickersReady(): Promise<boolean>;
+    companyFactsReady(): Promise<boolean>;
+    /** All ticker rows, for rebuilding the in-memory CIK index. Assumes the layer is ready. */
+    getTickerRows(): Promise<TickerRow[]>;
+    /**
+     * One company's full concept series in `companyconcept` API shape, or null when
+     * the mirror has no row for this (cik, taxonomy, tag). Assumes the layer is ready.
+     */
+    getCompanyConcept(cik: string, taxonomy: string, tag: string): Promise<CompanyConceptResponse | null>;
+    /**
+     * Cross-company frame in `frames` API shape, assembled by scanning every company
+     * reporting (taxonomy, tag) and extracting the period's frame-aligned value.
+     * Returns null when no company reports the combination. Assumes the layer is ready.
+     *
+     * `unit` arrives in the dashed wire form the tool uses (`USD-per-shares`); the
+     * `units` map is keyed by the slashed form (`USD/shares`). `loc` (business
+     * location) is absent — companyfacts carries no location; the live frames API
+     * adds it. The tool treats an empty `loc` as absent.
+     */
+    getFrames(taxonomy: string, tag: string, unit: string, period: string): Promise<FramesResponse | null>;
+    /** Full init (bootstrap) of both layers — tickers first (fast), then company-facts. */
+    runInit(args: MirrorRunArgs): Promise<{
+        tickers: SyncResult;
+        companyFacts: SyncResult;
+    }>;
+    /** Incremental refresh of both layers. */
+    runRefresh(args: MirrorRunArgs): Promise<{
+        tickers: SyncResult;
+        companyFacts: SyncResult;
+    }>;
+    private runBothLayers;
+    /** Combined status of both layers, for the verify script and operability checks. */
+    status(): Promise<{
+        tickers: import("@cyanheads/mcp-ts-core/mirror").MirrorStatus;
+        companyFacts: import("@cyanheads/mcp-ts-core/mirror").MirrorStatus;
+    }>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=edgar-mirror.d.ts.map

package/dist/services/edgar/mirror/edgar-mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgar-mirror.d.ts","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/edgar-mirror.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAEL,KAAK,MAAM,EACX,KAAK,YAAY,EAEjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAEhB,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EACV,sBAAsB,EAGtB,cAAc,EACf,MAAM,aAAa,CAAC;AAGrB,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,oEAAoE;IACpE,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,GAAG,CAAC,EAAE,YAAY,CAAC;IACnB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,KAAK,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAC7E,MAAM,EAAE,WAAW,CAAC;CACrB;AAWD,qBAAa,WAAW;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,kBAAkB,CAAS;gBAEvB,IAAI,EAAE,kBAAkB;IAuCpC,gFAAgF;IAC1E,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAKhC,iBAAiB,IAAI,OAAO,CAAC,OAAO,CAAC;IAK3C,2FAA2F;IACrF,aAAa,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAK3C;;;OAGG;IACG,iBAAiB,CACrB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAgBzC;;;;;;;;;OASG;IACG,SAAS,CACb,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAoDjC,uFAAuF;IACvF,OAAO,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,YAAY,EAAE,UAAU,CAAA;KAAE,CAAC;IAIxF,0CAA0C;IAC1C,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,YAAY,EAAE,UAAU,CAAA;KAAE,CAAC;YAI7E,aAAa;IAiB3B,oFAAoF;IAC9E,MAAM;;;;IAON,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/services/edgar/mirror/edgar-mirror.js

@@ -0,0 +1,190 @@
+/**
+ * @fileoverview `EdgarMirror` — owns the two framework `Mirror` instances (the
+ * ticker/CIK layer and the XBRL company-facts layer) and the read helpers that
+ * reconstruct the live API's `companyconcept` and `frames` response shapes off
+ * the local SQLite stores. The service routes through these when the mirror is
+ * ready; callers gate on `tickersReady()` / `companyFactsReady()`.
+ * @module services/edgar/mirror/edgar-mirror
+ */
+import { join } from 'node:path';
+import { defineMirror, sqliteMirrorStore, } from '@cyanheads/mcp-ts-core/mirror';
+import { makeCompanyFactsSync } from './companyfacts-sync.js';
+import { makeTickersSync } from './tickers-sync.js';
+import { COMPANY_CONCEPTS_TABLE, COMPANY_FACTS_DB_FILE, TICKERS_DB_FILE, TICKERS_TABLE, } from './types.js';
+export class EdgarMirror {
+    tickers;
+    companyFacts;
+    _tickersReady = false;
+    _companyFactsReady = false;
+    constructor(opts) {
+        this.tickers = defineMirror({
+            name: 'edgar-tickers',
+            store: sqliteMirrorStore({
+                path: join(opts.dir, TICKERS_DB_FILE),
+                table: TICKERS_TABLE,
+                primaryKey: 'ticker',
+                columns: { ticker: 'TEXT', cik: 'TEXT', name: 'TEXT' },
+                indexes: [{ columns: ['cik'] }],
+            }),
+            sync: makeTickersSync({ userAgent: opts.userAgent }),
+            ...(opts.log ? { logger: opts.log } : {}),
+        });
+        this.companyFacts = defineMirror({
+            name: 'edgar-companyfacts',
+            store: sqliteMirrorStore({
+                path: join(opts.dir, COMPANY_FACTS_DB_FILE),
+                table: COMPANY_CONCEPTS_TABLE,
+                primaryKey: 'id',
+                columns: {
+                    id: 'TEXT',
+                    cik: 'TEXT',
+                    taxonomy: 'TEXT',
+                    tag: 'TEXT',
+                    entity_name: 'TEXT',
+                    label: 'TEXT',
+                    description: 'TEXT',
+                    units_json: 'TEXT',
+                },
+                indexes: [{ columns: ['taxonomy', 'tag'] }],
+            }),
+            sync: makeCompanyFactsSync({
+                userAgent: opts.userAgent,
+                ...(opts.log ? { log: opts.log } : {}),
+            }),
+            ...(opts.log ? { logger: opts.log } : {}),
+        });
+    }
+    /** Memoized readiness — the durable completion marker only flips false→true. */
+    async tickersReady() {
+        if (!this._tickersReady)
+            this._tickersReady = await this.tickers.ready();
+        return this._tickersReady;
+    }
+    async companyFactsReady() {
+        if (!this._companyFactsReady)
+            this._companyFactsReady = await this.companyFacts.ready();
+        return this._companyFactsReady;
+    }
+    /** All ticker rows, for rebuilding the in-memory CIK index. Assumes the layer is ready. */
+    async getTickerRows() {
+        const handle = await this.tickers.raw();
+        return handle.prepare(`SELECT ticker, cik, name FROM ${TICKERS_TABLE}`).all();
+    }
+    /**
+     * One company's full concept series in `companyconcept` API shape, or null when
+     * the mirror has no row for this (cik, taxonomy, tag). Assumes the layer is ready.
+     */
+    async getCompanyConcept(cik, taxonomy, tag) {
+        const id = `${cik.padStart(10, '0')}|${taxonomy}|${tag}`;
+        const [row] = await this.companyFacts.getByIds([id]);
+        if (!row)
+            return null;
+        const description = row.description == null ? undefined : String(row.description);
+        return {
+            cik: Number(row.cik),
+            entityName: String(row.entity_name ?? ''),
+            taxonomy: String(row.taxonomy ?? taxonomy),
+            tag: String(row.tag ?? tag),
+            label: String(row.label ?? tag),
+            units: JSON.parse(String(row.units_json ?? '{}')),
+            ...(description !== undefined ? { description } : {}),
+        };
+    }
+    /**
+     * Cross-company frame in `frames` API shape, assembled by scanning every company
+     * reporting (taxonomy, tag) and extracting the period's frame-aligned value.
+     * Returns null when no company reports the combination. Assumes the layer is ready.
+     *
+     * `unit` arrives in the dashed wire form the tool uses (`USD-per-shares`); the
+     * `units` map is keyed by the slashed form (`USD/shares`). `loc` (business
+     * location) is absent — companyfacts carries no location; the live frames API
+     * adds it. The tool treats an empty `loc` as absent.
+     */
+    async getFrames(taxonomy, tag, unit, period) {
+        const unitKey = unit.replace('-per-', '/');
+        const handle = await this.companyFacts.raw();
+        const rows = handle
+            .prepare(`SELECT cik, entity_name, label, description, units_json FROM ${COMPANY_CONCEPTS_TABLE} WHERE taxonomy = ? AND tag = ?`)
+            .all(taxonomy, tag);
+        if (rows.length === 0)
+            return null;
+        const data = [];
+        let label = tag;
+        let description;
+        for (const row of rows) {
+            const units = JSON.parse(row.units_json);
+            const series = units[unitKey];
+            if (!series)
+                continue;
+            // The frame members are the datapoints whose `frame` equals the period; if a
+            // value was re-filed, the latest filing wins (matches get_financials dedup).
+            let best;
+            for (const u of series) {
+                if (u.frame !== period)
+                    continue;
+                if (!best || u.filed > best.filed)
+                    best = u;
+            }
+            if (!best)
+                continue;
+            if (label === tag && row.label) {
+                label = row.label;
+                description = row.description ?? undefined;
+            }
+            data.push({
+                accn: best.accn,
+                cik: Number(row.cik),
+                end: best.end,
+                entityName: row.entity_name,
+                loc: '',
+                ...(best.start !== undefined ? { start: best.start } : {}),
+                val: best.val,
+            });
+        }
+        if (data.length === 0)
+            return null;
+        return {
+            ccp: period,
+            data,
+            label,
+            pts: data.length,
+            tag,
+            taxonomy,
+            uom: unit,
+            ...(description !== undefined ? { description } : {}),
+        };
+    }
+    /** Full init (bootstrap) of both layers — tickers first (fast), then company-facts. */
+    runInit(args) {
+        return this.runBothLayers('init', args);
+    }
+    /** Incremental refresh of both layers. */
+    runRefresh(args) {
+        return this.runBothLayers('refresh', args);
+    }
+    async runBothLayers(mode, args) {
+        const tickers = await this.tickers.runSync({
+            mode,
+            signal: args.signal,
+            ...(args.onProgress ? { onProgress: (i) => args.onProgress?.('tickers', i) } : {}),
+        });
+        const companyFacts = await this.companyFacts.runSync({
+            mode,
+            signal: args.signal,
+            ...(args.onProgress ? { onProgress: (i) => args.onProgress?.('companyfacts', i) } : {}),
+        });
+        return { tickers, companyFacts };
+    }
+    /** Combined status of both layers, for the verify script and operability checks. */
+    async status() {
+        return {
+            tickers: await this.tickers.status(),
+            companyFacts: await this.companyFacts.status(),
+        };
+    }
+    async close() {
+        await this.tickers.close();
+        await this.companyFacts.close();
+    }
+}
+//# sourceMappingURL=edgar-mirror.js.map

package/dist/services/edgar/mirror/edgar-mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edgar-mirror.js","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/edgar-mirror.ts"],"names":[],"mappings":"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"}

package/dist/services/edgar/mirror/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Public barrel and server-side singleton for the EDGAR local
+ * mirror. The singleton is constructed in `setup()` only when the mirror is
+ * enabled and the runtime supports it (Node/Bun, not Workers); `getEdgarMirror()`
+ * returns `undefined` otherwise and the service stays on the live API.
+ * @module services/edgar/mirror
+ */
+import { EdgarMirror, type EdgarMirrorOptions } from './edgar-mirror.js';
+export { EdgarMirror, type EdgarMirrorOptions, type MirrorRunArgs } from './edgar-mirror.js';
+export * from './types.js';
+/** Construct and register the server-side mirror singleton. */
+export declare function initEdgarMirror(opts: EdgarMirrorOptions): EdgarMirror;
+/** The registered mirror singleton, or `undefined` when the mirror is disabled. */
+export declare function getEdgarMirror(): EdgarMirror | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/services/edgar/mirror/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAC7F,cAAc,YAAY,CAAC;AAI3B,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAGrE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,IAAI,WAAW,GAAG,SAAS,CAExD"}

package/dist/services/edgar/mirror/index.js

@@ -0,0 +1,21 @@
+/**
+ * @fileoverview Public barrel and server-side singleton for the EDGAR local
+ * mirror. The singleton is constructed in `setup()` only when the mirror is
+ * enabled and the runtime supports it (Node/Bun, not Workers); `getEdgarMirror()`
+ * returns `undefined` otherwise and the service stays on the live API.
+ * @module services/edgar/mirror
+ */
+import { EdgarMirror } from './edgar-mirror.js';
+export { EdgarMirror } from './edgar-mirror.js';
+export * from './types.js';
+let _mirror;
+/** Construct and register the server-side mirror singleton. */
+export function initEdgarMirror(opts) {
+    _mirror = new EdgarMirror(opts);
+    return _mirror;
+}
+/** The registered mirror singleton, or `undefined` when the mirror is disabled. */
+export function getEdgarMirror() {
+    return _mirror;
+}
+//# sourceMappingURL=index.js.map

package/dist/services/edgar/mirror/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAA2B,MAAM,mBAAmB,CAAC;AAEzE,OAAO,EAAE,WAAW,EAA+C,MAAM,mBAAmB,CAAC;AAC7F,cAAc,YAAY,CAAC;AAE3B,IAAI,OAAgC,CAAC;AAErC,+DAA+D;AAC/D,MAAM,UAAU,eAAe,CAAC,IAAwB;IACtD,OAAO,GAAG,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;IAChC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/services/edgar/mirror/tickers-sync.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Ingester for the ticker/CIK layer. Downloads SEC's
+ * `company_tickers.json` (small direct-download JSON) and yields one page of
+ * rows. Upsert-only: the directory rarely drops entries and CIKs are permanent,
+ * so a delisted ticker lingering with its historical CIK is low-harm.
+ * @module services/edgar/mirror/tickers-sync
+ */
+import type { SyncGenerator } from '@cyanheads/mcp-ts-core/mirror';
+/**
+ * Build the ticker-layer ingester. The returned generator downloads the full
+ * directory and yields it as a single page; the file is tiny, so refresh simply
+ * re-downloads and re-upserts.
+ */
+export declare function makeTickersSync(opts: {
+    userAgent: string;
+}): SyncGenerator;
+//# sourceMappingURL=tickers-sync.d.ts.map

package/dist/services/edgar/mirror/tickers-sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickers-sync.d.ts","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/tickers-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAGV,aAAa,EAEd,MAAM,+BAA+B,CAAC;AAUvC;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CA+B1E"}

package/dist/services/edgar/mirror/tickers-sync.js

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Ingester for the ticker/CIK layer. Downloads SEC's
+ * `company_tickers.json` (small direct-download JSON) and yields one page of
+ * rows. Upsert-only: the directory rarely drops entries and CIKs are permanent,
+ * so a delisted ticker lingering with its historical CIK is low-harm.
+ * @module services/edgar/mirror/tickers-sync
+ */
+import { serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { lastModifiedToIso, TICKERS_URL } from './types.js';
+/**
+ * Build the ticker-layer ingester. The returned generator downloads the full
+ * directory and yields it as a single page; the file is tiny, so refresh simply
+ * re-downloads and re-upserts.
+ */
+export function makeTickersSync(opts) {
+    return async function* tickersSync(ctx) {
+        const response = await fetch(TICKERS_URL, {
+            headers: { 'User-Agent': opts.userAgent, Accept: 'application/json' },
+            signal: ctx.signal,
+        });
+        if (!response.ok) {
+            throw serviceUnavailable(`SEC company_tickers.json download failed (HTTP ${response.status})`, {
+                url: TICKERS_URL,
+                status: response.status,
+            });
+        }
+        const raw = (await response.json());
+        const records = [];
+        for (const entry of Object.values(raw)) {
+            if (!entry?.ticker)
+                continue;
+            records.push({
+                ticker: entry.ticker.toUpperCase(),
+                cik: String(entry.cik_str).padStart(10, '0'),
+                name: entry.title ?? '',
+            });
+        }
+        // Checkpoint must be lexicographically monotonic — store ISO 8601, not the raw HTTP-date.
+        const checkpoint = lastModifiedToIso(response.headers.get('last-modified'));
+        yield { records, checkpoint };
+    };
+}
+//# sourceMappingURL=tickers-sync.js.map

package/dist/services/edgar/mirror/tickers-sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tickers-sync.js","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/tickers-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAOnE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAS5D;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAA2B;IACzD,OAAO,KAAK,SAAS,CAAC,CAAC,WAAW,CAAC,GAAgB;QACjD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,WAAW,EAAE;YACxC,OAAO,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,kBAAkB,EAAE;YACrE,MAAM,EAAE,GAAG,CAAC,MAAM;SACnB,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,kBAAkB,CACtB,kDAAkD,QAAQ,CAAC,MAAM,GAAG,EACpE;gBACE,GAAG,EAAE,WAAW;gBAChB,MAAM,EAAE,QAAQ,CAAC,MAAM;aACxB,CACF,CAAC;QACJ,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAmC,CAAC;QACtE,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,CAAC,KAAK,EAAE,MAAM;gBAAE,SAAS;YAC7B,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE;gBAClC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;gBAC5C,IAAI,EAAE,KAAK,CAAC,KAAK,IAAI,EAAE;aACxB,CAAC,CAAC;QACL,CAAC;QAED,0FAA0F;QAC1F,MAAM,UAAU,GAAG,iBAAiB,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;QAC5E,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,CAAC;IAChC,CAAC,CAAC;AACJ,CAAC"}

package/dist/services/edgar/mirror/types.d.ts

@@ -0,0 +1,56 @@
+/**
+ * @fileoverview Constants and row shapes for the EDGAR local mirror — the two
+ * bounded SEC reference layers (ticker/CIK resolution and XBRL company-facts)
+ * mirrored into embedded SQLite via the framework `MirrorService`.
+ * @module services/edgar/mirror/types
+ */
+/** SEC ticker→CIK directory (small direct-download JSON, ~200 KB). */
+export declare const TICKERS_URL = "https://www.sec.gov/files/company_tickers.json";
+/** SEC bulk XBRL company-facts archive, recompiled nightly (~1.3 GB). */
+export declare const COMPANY_FACTS_ZIP_URL = "https://www.sec.gov/Archives/edgar/daily-index/xbrl/companyfacts.zip";
+/** Primary table for the ticker/CIK layer. */
+export declare const TICKERS_TABLE = "tickers";
+/** Primary table for the XBRL company-facts layer (one row per cik×taxonomy×tag). */
+export declare const COMPANY_CONCEPTS_TABLE = "company_concepts";
+/** SQLite filenames inside the mirror directory (`EDGAR_MIRROR_PATH`). */
+export declare const TICKERS_DB_FILE = "tickers.sqlite";
+export declare const COMPANY_FACTS_DB_FILE = "companyfacts.sqlite";
+/**
+ * Convert an HTTP `Last-Modified` value to a lexicographically-monotonic ISO 8601
+ * checkpoint string, falling back to the current timestamp when absent or unparseable.
+ */
+export declare function lastModifiedToIso(httpDate: string | null | undefined): string;
+/** One row of the `tickers` table — a single entry from company_tickers.json. */
+export interface TickerRow {
+    /** Zero-padded 10-digit CIK. */
+    cik: string;
+    /** SEC-conformed entity name (the `title` field). */
+    name: string;
+    /** Uppercased ticker symbol — primary key (e.g. "AAPL", "BRK-A"). */
+    ticker: string;
+}
+/**
+ * One row of the `company_concepts` table — a single (cik, taxonomy, tag) concept
+ * from a company's `companyfacts` entry. The full `units` map is stored verbatim
+ * as a JSON blob so a point read reconstructs the `companyconcept` API shape and a
+ * `taxonomy+tag` scan reconstructs the `frames` API shape, both off one table.
+ */
+export interface CompanyConceptRow {
+    /** Zero-padded 10-digit CIK. */
+    cik: string;
+    /** Taxonomy description; null when the source omits it. */
+    description: string | null;
+    /** SEC-conformed entity name. */
+    entity_name: string;
+    /** `${cik}|${taxonomy}|${tag}` — primary key. */
+    id: string;
+    /** Concept label. */
+    label: string;
+    /** XBRL tag (e.g. "Revenues"). */
+    tag: string;
+    /** XBRL taxonomy (e.g. "us-gaap", "ifrs-full", "dei"). */
+    taxonomy: string;
+    /** `JSON.stringify` of the concept's `units` map (`{ [unit]: CompanyConceptUnit[] }`). */
+    units_json: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/edgar/mirror/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/services/edgar/mirror/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,sEAAsE;AACtE,eAAO,MAAM,WAAW,mDAAmD,CAAC;AAE5E,yEAAyE;AACzE,eAAO,MAAM,qBAAqB,yEACsC,CAAC;AAEzE,8CAA8C;AAC9C,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,qFAAqF;AACrF,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,0EAA0E;AAC1E,eAAO,MAAM,eAAe,mBAAmB,CAAC;AAChD,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAM7E;AAED,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,0FAA0F;IAC1F,UAAU,EAAE,MAAM,CAAC;CACpB"}