FetchCompanyFactsTask.ts

/**
 * @license
 * Copyright 2025 Steven Roussey <sroussey@gmail.com>
 * SPDX-License-Identifier: Apache-2.0
 */

import { Static, Type } from "typebox";
import { DataPortSchemaObject, IExecuteContext, Task, TaskAbortedError, TaskError } from "workglow";
import { SecCachedFetchTask } from "../fetch/SecCachedFetchTask";
import { CompanyFacts, Factoid, FactoidSchema, normalizeFp } from "../../sec/facts/CompanyFacts";
import { TypeSecCik } from "../../sec/submissions/EnititySubmissionSchema";
import { secDate, TypeOptionalSecDate } from "../../util/parseDate";

// NOTE: company facts are mutable, so we need to pass in a date to break the cache

const FetchCompanyFactsTaskInput = () =>
  Type.Object({
    cik: TypeSecCik(),
    date: TypeOptionalSecDate(),
  });

export type FetchCompanyFactsTaskInput = Static<ReturnType<typeof FetchCompanyFactsTaskInput>>;

const FetchCompanyFactsTaskOutput = () =>
  Type.Object({
    cik: TypeSecCik(),
    facts: Type.Array(FactoidSchema),
    date: TypeOptionalSecDate(),
  });
export type FetchCompanyFactsTaskOutput = Static<ReturnType<typeof FetchCompanyFactsTaskOutput>>;

class SecFetchCompanyFactsTask extends SecCachedFetchTask<FetchCompanyFactsTaskInput> {
  static readonly type = "SecFetchCompanyFactsTask";
  static readonly category = "Hidden";
  static readonly immutable = false;

  public static inputSchema() {
    return FetchCompanyFactsTaskInput() as DataPortSchemaObject;
  }

  inputToFileName(input: FetchCompanyFactsTaskInput): string {
    return `companyfacts/CIK${input.cik.toString().padStart(10, "0")}.json`;
  }
  inputToUrl(input: FetchCompanyFactsTaskInput): string {
    const date = input.date ? secDate(input.date) : undefined;
    return `https://data.sec.gov/api/xbrl/companyfacts/CIK${input.cik
      .toString()
      .padStart(10, "0")}.json${date ? `?date=${date}` : ""}`;
  }
}

/**
 * Task for fetching the daily index of SEC filings and parsing it into a list of CIKs to update
 */
export class FetchCompanyFactsTask extends Task<
  FetchCompanyFactsTaskInput,
  FetchCompanyFactsTaskOutput
> {
  static readonly type = "FetchCompanyFactsTask";
  static readonly category = "SEC";
  static readonly cacheable = true;

  public static inputSchema() {
    return FetchCompanyFactsTaskInput();
  }

  public static outputSchema() {
    return FetchCompanyFactsTaskOutput();
  }

  private _secFetch?: SecFetchCompanyFactsTask;
  async execute(
    input: FetchCompanyFactsTaskInput,
    context: IExecuteContext
  ): Promise<FetchCompanyFactsTaskOutput> {
    const cik = input.cik;
    if (!cik) {
      return { facts: [], cik: 0, date: input.date ? secDate(input.date) : undefined };
    }

    this._secFetch ??= context.own(new SecFetchCompanyFactsTask(input));
    this._secFetch.setDefaults(input);
    const secData = await this._secFetch.run();
    const companyFacts = secData.json as unknown as CompanyFacts | undefined;
    const facts = companyFacts?.facts;
    if (!facts || typeof facts !== "object") {
      throw new TaskError(`Company facts JSON for CIK ${cik} has no 'facts' object`);
    }
    // linearize the facts

    const factsArray: Factoid[] = [];
    Object.entries(facts).forEach(([grouping, names]) => {
      Object.entries(names).forEach(([name, info]) => {
        Object.entries(info.units).forEach(([unit, summaries]) => {
          for (const summary of summaries) {
            if (context.signal?.aborted) {
              throw new TaskAbortedError();
            }
            factsArray.push({
              cik,
              grouping,
              name,
              filed_date: summary.filed,
              form: summary.form,
              val_unit: unit,
              frame: summary.frame || null,
              accession_number: summary.accn,
              start_date: summary.start || null,
              end_date: summary.end,
              val: summary.val,
              fy: summary.fy,
              fp: normalizeFp(summary.fp),
            });
          }
        });
      });
    });
    return { cik, facts: factsArray, date: input.date ? secDate(input.date) : undefined };
  }
}