edgar-cli 0.1.4 → 0.2.2

package/dist/core/config.d.ts

@@ -1,23 +0,0 @@
-export interface RuntimeOptions {
-    jsonMode: boolean;
-    humanMode: boolean;
-    view: 'summary' | 'full';
-    fields?: string[];
-    limit?: number;
-    verbose: boolean;
-    userAgent?: string;
-}
-export interface RuntimeInput {
-    json?: boolean;
-    human?: boolean;
-    view?: string;
-    fields?: string;
-    limit?: string | number;
-    verbose?: boolean;
-    userAgent?: string;
-}
-export declare function buildRuntimeOptions(input: RuntimeInput, env: NodeJS.ProcessEnv): RuntimeOptions;
-export declare function requireUserAgent(userAgent: string | undefined): string;
-export declare function parsePositiveInt(value: string, argName: string): number;
-export declare function parseNonNegativeInt(value: string, argName: string): number;
-export declare function parseDateString(value: string, argName: string): string;

package/dist/core/config.js

@@ -1,51 +0,0 @@
-import { z } from 'zod';
-import { CLIError, ErrorCode } from './errors.js';
-import { parseFields } from './output-shape.js';
-const positiveIntSchema = z.coerce.number().int().min(1);
-const nonNegativeIntSchema = z.coerce.number().int().min(0);
-const dateSchema = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
-export function buildRuntimeOptions(input, env) {
-    const humanMode = Boolean(input.human);
-    const jsonMode = !humanMode;
-    const view = input.view === 'full' ? 'full' : 'summary';
-    const parsedFields = parseFields(input.fields);
-    const parsedLimit = input.limit === undefined || input.limit === null
-        ? undefined
-        : parsePositiveInt(String(input.limit), '--limit');
-    return {
-        jsonMode,
-        humanMode,
-        view,
-        fields: parsedFields,
-        limit: parsedLimit,
-        verbose: Boolean(input.verbose),
-        userAgent: input.userAgent?.trim() || env.EDGAR_USER_AGENT?.trim() || undefined
-    };
-}
-export function requireUserAgent(userAgent) {
-    if (userAgent && userAgent.trim().length > 0) {
-        return userAgent.trim();
-    }
-    throw new CLIError(ErrorCode.IDENTITY_REQUIRED, 'Missing SEC identity. Set --user-agent "Name email@domain.com" or EDGAR_USER_AGENT.');
-}
-export function parsePositiveInt(value, argName) {
-    const parsed = positiveIntSchema.safeParse(value);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must be a positive integer`);
-    }
-    return parsed.data;
-}
-export function parseNonNegativeInt(value, argName) {
-    const parsed = nonNegativeIntSchema.safeParse(value);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must be a non-negative integer`);
-    }
-    return parsed.data;
-}
-export function parseDateString(value, argName) {
-    const parsed = dateSchema.safeParse(value);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, `${argName} must use YYYY-MM-DD`);
-    }
-    return parsed.data;
-}

package/dist/core/envelope.d.ts

@@ -1,28 +0,0 @@
-import { ErrorCode } from './errors.js';
-export interface BrokerError {
-    code: ErrorCode;
-    message: string;
-    retriable: boolean;
-}
-export interface OutputEnvelope {
-    ok: boolean;
-    command: string;
-    provider: 'sec';
-    data: unknown;
-    error: BrokerError | null;
-    meta: Record<string, unknown>;
-}
-export declare function successEnvelope(params: {
-    command: string;
-    data: unknown;
-    view: string;
-    metaUpdates?: Record<string, unknown>;
-}): OutputEnvelope;
-export declare function failureEnvelope(params: {
-    command: string;
-    code: ErrorCode;
-    message: string;
-    retriable?: boolean;
-    view: string;
-    metaUpdates?: Record<string, unknown>;
-}): OutputEnvelope;

package/dist/core/envelope.js

@@ -1,37 +0,0 @@
-function nowIso() {
-    return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
-}
-export function successEnvelope(params) {
-    return {
-        ok: true,
-        command: params.command,
-        provider: 'sec',
-        data: params.data,
-        error: null,
-        meta: {
-            timestamp: nowIso(),
-            output_schema: 'v1',
-            view: params.view,
-            ...(params.metaUpdates ?? {})
-        }
-    };
-}
-export function failureEnvelope(params) {
-    return {
-        ok: false,
-        command: params.command,
-        provider: 'sec',
-        data: null,
-        error: {
-            code: params.code,
-            message: params.message,
-            retriable: params.retriable ?? false
-        },
-        meta: {
-            timestamp: nowIso(),
-            output_schema: 'v1',
-            view: params.view,
-            ...(params.metaUpdates ?? {})
-        }
-    };
-}

package/dist/core/errors.d.ts

@@ -1,18 +0,0 @@
-export declare enum ErrorCode {
-    VALIDATION_ERROR = "VALIDATION_ERROR",
-    DOCS_REQUIRED = "DOCS_REQUIRED",
-    IDENTITY_REQUIRED = "IDENTITY_REQUIRED",
-    RATE_LIMITED = "RATE_LIMITED",
-    NOT_FOUND = "NOT_FOUND",
-    NETWORK_ERROR = "NETWORK_ERROR",
-    PARSE_ERROR = "PARSE_ERROR",
-    INTERNAL_ERROR = "INTERNAL_ERROR"
-}
-export declare const EXIT_CODE_MAP: Record<ErrorCode, number>;
-export declare class CLIError extends Error {
-    readonly code: ErrorCode;
-    readonly retriable: boolean;
-    constructor(code: ErrorCode, message: string, retriable?: boolean);
-    get exitCode(): number;
-}
-export declare function isCLIError(err: unknown): err is CLIError;

package/dist/core/errors.js

@@ -1,37 +0,0 @@
-export var ErrorCode;
-(function (ErrorCode) {
-    ErrorCode["VALIDATION_ERROR"] = "VALIDATION_ERROR";
-    ErrorCode["DOCS_REQUIRED"] = "DOCS_REQUIRED";
-    ErrorCode["IDENTITY_REQUIRED"] = "IDENTITY_REQUIRED";
-    ErrorCode["RATE_LIMITED"] = "RATE_LIMITED";
-    ErrorCode["NOT_FOUND"] = "NOT_FOUND";
-    ErrorCode["NETWORK_ERROR"] = "NETWORK_ERROR";
-    ErrorCode["PARSE_ERROR"] = "PARSE_ERROR";
-    ErrorCode["INTERNAL_ERROR"] = "INTERNAL_ERROR";
-})(ErrorCode || (ErrorCode = {}));
-export const EXIT_CODE_MAP = {
-    [ErrorCode.VALIDATION_ERROR]: 2,
-    [ErrorCode.DOCS_REQUIRED]: 2,
-    [ErrorCode.IDENTITY_REQUIRED]: 3,
-    [ErrorCode.RATE_LIMITED]: 4,
-    [ErrorCode.NOT_FOUND]: 5,
-    [ErrorCode.NETWORK_ERROR]: 6,
-    [ErrorCode.PARSE_ERROR]: 7,
-    [ErrorCode.INTERNAL_ERROR]: 10
-};
-export class CLIError extends Error {
-    code;
-    retriable;
-    constructor(code, message, retriable = false) {
-        super(message);
-        this.code = code;
-        this.retriable = retriable;
-        this.name = 'CLIError';
-    }
-    get exitCode() {
-        return EXIT_CODE_MAP[this.code] ?? 10;
-    }
-}
-export function isCLIError(err) {
-    return err instanceof CLIError;
-}

package/dist/core/output-shape.d.ts

@@ -1,10 +0,0 @@
-export interface ShapedData {
-    data: unknown;
-    metaUpdates: Record<string, unknown>;
-}
-export declare function parseFields(raw: string | undefined): string[] | undefined;
-export declare function shapeData(params: {
-    data: unknown;
-    fields?: string[];
-    limit?: number;
-}): ShapedData;

package/dist/core/output-shape.js

@@ -1,61 +0,0 @@
-import { CLIError, ErrorCode } from './errors.js';
-export function parseFields(raw) {
-    if (!raw) {
-        return undefined;
-    }
-    const fields = raw
-        .split(',')
-        .map((field) => field.trim())
-        .filter((field) => field.length > 0);
-    if (fields.length === 0) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields requires at least one field');
-    }
-    return [...new Set(fields)];
-}
-function projectObject(source, fields) {
-    const projected = {};
-    for (const field of fields) {
-        projected[field] = source[field];
-    }
-    return projected;
-}
-function applyFields(data, fields) {
-    if (!fields) {
-        return data;
-    }
-    if (Array.isArray(data)) {
-        if (data.length === 0) {
-            return data;
-        }
-        if (!data.every((item) => item && typeof item === 'object' && !Array.isArray(item))) {
-            throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields can only be applied to object results or lists of objects');
-        }
-        return data.map((item) => projectObject(item, fields));
-    }
-    if (data && typeof data === 'object' && !Array.isArray(data)) {
-        return projectObject(data, fields);
-    }
-    throw new CLIError(ErrorCode.VALIDATION_ERROR, '--fields can only be applied to object results or lists of objects');
-}
-export function shapeData(params) {
-    const fieldShaped = applyFields(params.data, params.fields);
-    const metaUpdates = {};
-    if (Array.isArray(fieldShaped) && typeof params.limit === 'number') {
-        if (params.limit < 1) {
-            throw new CLIError(ErrorCode.VALIDATION_ERROR, '--limit must be at least 1');
-        }
-        const totalCount = fieldShaped.length;
-        const data = fieldShaped.slice(0, params.limit);
-        metaUpdates.total_count = totalCount;
-        metaUpdates.returned_count = data.length;
-        metaUpdates.truncated = data.length < totalCount;
-        return {
-            data,
-            metaUpdates
-        };
-    }
-    return {
-        data: fieldShaped,
-        metaUpdates
-    };
-}

package/dist/core/runtime.d.ts

@@ -1,10 +0,0 @@
-import { RuntimeOptions } from './config.js';
-import { SecClient } from '../sec/client.js';
-export interface CommandContext {
-    runtime: RuntimeOptions;
-    secClient: SecClient;
-}
-export interface CommandResult {
-    data: unknown;
-    metaUpdates?: Record<string, unknown>;
-}

package/dist/core/runtime.js

@@ -1 +0,0 @@
-export {};

package/dist/sec/client.d.ts

@@ -1,17 +0,0 @@
-export interface SecClientOptions {
-    userAgent: string;
-    verbose?: boolean;
-    fetchImpl?: typeof fetch;
-    logger?: (message: string) => void;
-}
-export declare class SecClient {
-    private readonly userAgent;
-    private readonly verbose;
-    private readonly fetchImpl;
-    private readonly logger;
-    constructor(options: SecClientOptions);
-    fetchSecJson<T>(url: string): Promise<T>;
-    fetchSecText(url: string): Promise<string>;
-    private log;
-    private request;
-}

package/dist/sec/client.js

@@ -1,154 +0,0 @@
-import pLimit from 'p-limit';
-import { CLIError, ErrorCode } from '../core/errors.js';
-const REQUEST_INTERVAL_MS = 125;
-const MAX_ATTEMPTS = 4;
-const paceGate = pLimit(1);
-let nextAllowedAt = 0;
-const sleep = async (ms) => {
-    if (ms <= 0) {
-        return;
-    }
-    await new Promise((resolve) => setTimeout(resolve, ms));
-};
-const jitter = () => Math.floor(Math.random() * 120);
-function retryAfterMs(headerValue) {
-    if (!headerValue) {
-        return null;
-    }
-    const seconds = Number.parseInt(headerValue, 10);
-    if (!Number.isNaN(seconds)) {
-        return Math.max(0, seconds * 1000);
-    }
-    const retryAt = Date.parse(headerValue);
-    if (Number.isNaN(retryAt)) {
-        return null;
-    }
-    return Math.max(0, retryAt - Date.now());
-}
-async function paceRequests() {
-    await paceGate(async () => {
-        const now = Date.now();
-        const delay = Math.max(0, nextAllowedAt - now);
-        if (delay > 0) {
-            await sleep(delay);
-        }
-        nextAllowedAt = Math.max(nextAllowedAt, Date.now()) + REQUEST_INTERVAL_MS;
-    });
-}
-function isUndeclaredAutomationBody(value) {
-    const lowered = value.toLowerCase();
-    return (lowered.includes('undeclared automated tool') ||
-        lowered.includes('please declare your traffic') ||
-        lowered.includes('acceptable policy'));
-}
-function isRetriableNetworkError(err) {
-    return err instanceof TypeError;
-}
-function toNetworkError(url, message, retriable = false) {
-    return new CLIError(ErrorCode.NETWORK_ERROR, `SEC request failed for ${url}: ${message}`, retriable);
-}
-function toRateLimitedError(url) {
-    return new CLIError(ErrorCode.RATE_LIMITED, `SEC rate limit reached for ${url}`, true);
-}
-export class SecClient {
-    userAgent;
-    verbose;
-    fetchImpl;
-    logger;
-    constructor(options) {
-        this.userAgent = options.userAgent;
-        this.verbose = options.verbose ?? false;
-        this.fetchImpl = options.fetchImpl ?? fetch;
-        this.logger = options.logger ?? (() => undefined);
-    }
-    async fetchSecJson(url) {
-        const raw = await this.request(url, 'json');
-        try {
-            return JSON.parse(raw);
-        }
-        catch (error) {
-            throw new CLIError(ErrorCode.PARSE_ERROR, `Unable to parse SEC JSON response from ${url}: ${error.message}`);
-        }
-    }
-    async fetchSecText(url) {
-        return this.request(url, 'text');
-    }
-    log(message) {
-        if (!this.verbose) {
-            return;
-        }
-        this.logger(message);
-    }
-    async request(url, kind) {
-        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt += 1) {
-            try {
-                await paceRequests();
-                this.log(`GET ${url} (attempt ${attempt}/${MAX_ATTEMPTS})`);
-                const response = await this.fetchImpl(url, {
-                    method: 'GET',
-                    headers: {
-                        'User-Agent': this.userAgent,
-                        'Accept-Encoding': 'identity'
-                    }
-                });
-                if (response.status === 403) {
-                    const body = await response.text();
-                    if (isUndeclaredAutomationBody(body)) {
-                        throw new CLIError(ErrorCode.IDENTITY_REQUIRED, 'SEC rejected request as undeclared automation. Use a valid --user-agent or EDGAR_USER_AGENT.');
-                    }
-                    throw toNetworkError(url, '403 Forbidden');
-                }
-                if (response.status === 404) {
-                    throw new CLIError(ErrorCode.NOT_FOUND, `SEC resource not found at ${url}`);
-                }
-                if (response.status === 429) {
-                    if (attempt < MAX_ATTEMPTS) {
-                        const headerDelay = retryAfterMs(response.headers.get('retry-after'));
-                        const delay = headerDelay ?? 250 * 2 ** (attempt - 1) + jitter();
-                        this.log(`429 received, waiting ${delay}ms before retry`);
-                        await sleep(delay);
-                        continue;
-                    }
-                    throw toRateLimitedError(url);
-                }
-                if (response.status === 503) {
-                    if (attempt < MAX_ATTEMPTS) {
-                        const headerDelay = retryAfterMs(response.headers.get('retry-after'));
-                        const delay = headerDelay ?? 250 * 2 ** (attempt - 1) + jitter();
-                        this.log(`503 received, waiting ${delay}ms before retry`);
-                        await sleep(delay);
-                        continue;
-                    }
-                    throw toNetworkError(url, '503 Service Unavailable', true);
-                }
-                if (!response.ok) {
-                    if (response.status >= 500 && attempt < MAX_ATTEMPTS) {
-                        const delay = 250 * 2 ** (attempt - 1) + jitter();
-                        this.log(`HTTP ${response.status}, waiting ${delay}ms before retry`);
-                        await sleep(delay);
-                        continue;
-                    }
-                    throw toNetworkError(url, `HTTP ${response.status}`);
-                }
-                const body = await response.text();
-                if (kind === 'json' && body.trim().length === 0) {
-                    throw new CLIError(ErrorCode.PARSE_ERROR, `SEC returned empty JSON response from ${url}`);
-                }
-                return body;
-            }
-            catch (error) {
-                if (error instanceof CLIError) {
-                    throw error;
-                }
-                if (attempt < MAX_ATTEMPTS && isRetriableNetworkError(error)) {
-                    const delay = 250 * 2 ** (attempt - 1) + jitter();
-                    this.log(`Transient network error, waiting ${delay}ms before retry`);
-                    await sleep(delay);
-                    continue;
-                }
-                throw toNetworkError(url, error.message, isRetriableNetworkError(error));
-            }
-        }
-        throw toNetworkError(url, 'Request failed after retries');
-    }
-}

package/dist/sec/endpoints.d.ts

@@ -1,10 +0,0 @@
-export declare const SEC_DATA_HOST = "https://data.sec.gov";
-export declare const SEC_WWW_HOST = "https://www.sec.gov";
-export declare function submissionsUrl(cik: string): string;
-export declare function companyFactsUrl(cik: string): string;
-export declare function tickerMapUrl(): string;
-export declare function filingDocumentUrl(params: {
-    cik: string;
-    accession: string;
-    primaryDocument: string;
-}): string;

package/dist/sec/endpoints.js

@@ -1,19 +0,0 @@
-import { normalizeAccession, normalizeCik } from './normalizers.js';
-export const SEC_DATA_HOST = 'https://data.sec.gov';
-export const SEC_WWW_HOST = 'https://www.sec.gov';
-export function submissionsUrl(cik) {
-    const cik10 = normalizeCik(cik);
-    return `${SEC_DATA_HOST}/submissions/CIK${cik10}.json`;
-}
-export function companyFactsUrl(cik) {
-    const cik10 = normalizeCik(cik);
-    return `${SEC_DATA_HOST}/api/xbrl/companyfacts/CIK${cik10}.json`;
-}
-export function tickerMapUrl() {
-    return `${SEC_WWW_HOST}/files/company_tickers.json`;
-}
-export function filingDocumentUrl(params) {
-    const cikNumeric = String(Number.parseInt(normalizeCik(params.cik), 10));
-    const accessionNoDash = normalizeAccession(params.accession).replace(/-/g, '');
-    return `${SEC_WWW_HOST}/Archives/edgar/data/${cikNumeric}/${accessionNoDash}/${params.primaryDocument}`;
-}

package/dist/sec/normalizers.d.ts

@@ -1,5 +0,0 @@
-export declare function isLikelyCik(value: string): boolean;
-export declare function normalizeCik(value: string): string;
-export declare function normalizeTicker(value: string): string;
-export declare function normalizeAccession(value: string): string;
-export declare function dateInRange(value: string, from?: string, to?: string): boolean;

package/dist/sec/normalizers.js

@@ -1,44 +0,0 @@
-import { z } from 'zod';
-import { CLIError, ErrorCode } from '../core/errors.js';
-const cikSchema = z.string().regex(/^\d{1,10}$/);
-const tickerSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9.-]{0,14}$/);
-const accessionSchema = z.string().regex(/^\d{10}-\d{2}-\d{6}$/);
-export function isLikelyCik(value) {
-    return /^\d+$/.test(value.trim());
-}
-export function normalizeCik(value) {
-    const trimmed = value.trim();
-    const parsed = cikSchema.safeParse(trimmed);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, `Invalid CIK: ${value}`);
-    }
-    return parsed.data.padStart(10, '0');
-}
-export function normalizeTicker(value) {
-    const trimmed = value.trim();
-    const parsed = tickerSchema.safeParse(trimmed);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, `Invalid ticker: ${value}`);
-    }
-    return parsed.data.toUpperCase();
-}
-export function normalizeAccession(value) {
-    const trimmed = value.trim();
-    const parsed = accessionSchema.safeParse(trimmed);
-    if (!parsed.success) {
-        throw new CLIError(ErrorCode.VALIDATION_ERROR, '--accession must match XXXXXXXXXX-XX-XXXXXX');
-    }
-    return parsed.data;
-}
-export function dateInRange(value, from, to) {
-    if (!from && !to) {
-        return true;
-    }
-    if (from && value < from) {
-        return false;
-    }
-    if (to && value > to) {
-        return false;
-    }
-    return true;
-}

package/dist/sec/ticker-map.d.ts

@@ -1,16 +0,0 @@
-import { SecClient } from './client.js';
-export interface TickerRecord {
-    cik_str: number;
-    ticker: string;
-    title: string;
-}
-export interface ResolvedEntity {
-    input: string;
-    cik: string;
-    cik_numeric: number;
-    ticker: string | null;
-    title: string | null;
-}
-export declare function resolveEntity(id: string, client: SecClient, options?: {
-    strictMapMatch?: boolean;
-}): Promise<ResolvedEntity>;

package/dist/sec/ticker-map.js

@@ -1,57 +0,0 @@
-import { CLIError, ErrorCode } from '../core/errors.js';
-import { tickerMapUrl } from './endpoints.js';
-import { isLikelyCik, normalizeCik, normalizeTicker } from './normalizers.js';
-let cachedMap = null;
-let cachedAtMs = 0;
-const CACHE_TTL_MS = 15 * 60 * 1000;
-async function getTickerMap(client) {
-    const now = Date.now();
-    if (cachedMap && now - cachedAtMs < CACHE_TTL_MS) {
-        return cachedMap;
-    }
-    const payload = await client.fetchSecJson(tickerMapUrl());
-    const records = Object.values(payload)
-        .filter((record) => record && typeof record === 'object')
-        .filter((record) => typeof record.cik_str === 'number' && typeof record.ticker === 'string');
-    cachedMap = records;
-    cachedAtMs = now;
-    return records;
-}
-function findByTicker(records, ticker) {
-    return records.find((record) => record.ticker.toUpperCase() === ticker);
-}
-function findByCik(records, cik10) {
-    const cikNumeric = Number.parseInt(cik10, 10);
-    return records.find((record) => record.cik_str === cikNumeric);
-}
-export async function resolveEntity(id, client, options) {
-    const strictMapMatch = options?.strictMapMatch ?? false;
-    const records = await getTickerMap(client);
-    if (isLikelyCik(id)) {
-        const cik = normalizeCik(id);
-        const cikNumeric = Number.parseInt(cik, 10);
-        const match = findByCik(records, cik);
-        if (!match && strictMapMatch) {
-            throw new CLIError(ErrorCode.NOT_FOUND, `No SEC ticker-map record found for CIK ${cik}`);
-        }
-        return {
-            input: id,
-            cik,
-            cik_numeric: cikNumeric,
-            ticker: match?.ticker ?? null,
-            title: match?.title ?? null
-        };
-    }
-    const ticker = normalizeTicker(id);
-    const match = findByTicker(records, ticker);
-    if (!match) {
-        throw new CLIError(ErrorCode.NOT_FOUND, `No SEC ticker-map record found for ticker ${ticker}`);
-    }
-    return {
-        input: id,
-        cik: String(match.cik_str).padStart(10, '0'),
-        cik_numeric: match.cik_str,
-        ticker: match.ticker,
-        title: match.title
-    };
-}