// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import * as FilingAPI from '../edgar/filing/filing';
import { PageNumber, type PageNumberParams, PagePromise } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

/**
 * Look up companies by ticker and browse their EDGAR filings and Quartr documents.
 */
export class Edgar extends APIResource {
  /**
   * List SEC filings for a company identified by ticker, with pagination and
   * filtering.
   *
   * Accepts a qualified ticker in SYMBOL:EXCHANGE format (e.g. 'AAPL:NASDAQ'). An
   * unqualified symbol (e.g. 'AAPL') is also accepted.
   *
   * Resolves the ticker to an EDGAR entity, then returns filings in reverse
   * chronological order. Each filing is annotated with the entity's relationship to
   * it (e.g. filer, reporting owner).
   *
   * Use `form_types` to filter by individual SEC form codes (e.g. `10-K`, `8-K`)
   * and/or `form_categories` to filter by named groups of form types (e.g.
   * `INSIDER_TRADING`). Pass multiple values by repeating the query parameter. When
   * both are provided, their form types are unioned together. Use `earliest_date` /
   * `latest_date` to restrict by filing date.
   */
  listFilings(
    qualifiedTicker: string,
    query: EdgarListFilingsParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<EdgarListFilingsResponsesPageNumber, EdgarListFilingsResponse> {
    return this._client.getAPIList(
      path`/company/${qualifiedTicker}/edgar/filings`,
      PageNumber<EdgarListFilingsResponse>,
      { query, ...options },
    );
  }
}

export type EdgarListFilingsResponsesPageNumber = PageNumber<EdgarListFilingsResponse>;

/**
 * The type of relationship between an entity and a filing.
 */
export type EntityFilingRelationship =
  | 'filer'
  | 'reporting_owner'
  | 'issuer'
  | 'issuing_entity'
  | 'subject_company'
  | 'serial_company'
  | 'filed_by'
  | 'depositor'
  | 'securitizer'
  | 'filed_for'
  | 'underwriter';

/**
 * An SEC filing paired with its relationship to a specific entity.
 */
export interface EdgarListFilingsResponse extends FilingAPI.EdgarFiling {
  /**
   * The type of relationship between the entity and this filing (e.g. filer,
   * reporting owner).
   */
  relationship: EntityFilingRelationship;
}

export interface EdgarListFilingsParams extends PageNumberParams {
  /**
   * Only include filings with a filing date on or after this date (inclusive). This
   * filters on the SEC filing date, not the period of report.
   */
  earliest_date?: string | null;

  /**
   * Form category keys to filter by (e.g. `INSIDER_TRADING`, `NEWS`). Repeat the
   * parameter to specify multiple values. Each category expands into its member form
   * types and is unioned with any explicit `form_types`. Use the
   * `GET /edgar/form-categories` endpoint to discover available categories.
   */
  form_categories?: Array<string> | null;

  /**
   * SEC form type codes to filter by (e.g. `10-K`, `8-K`, `4`). Repeat the parameter
   * to specify multiple values.
   */
  form_types?: Array<string> | null;

  /**
   * Only include filings with a filing date on or before this date (inclusive). This
   * filters on the SEC filing date, not the period of report.
   */
  latest_date?: string | null;
}

export declare namespace Edgar {
  export {
    type EntityFilingRelationship as EntityFilingRelationship,
    type EdgarListFilingsResponse as EdgarListFilingsResponse,
    type EdgarListFilingsResponsesPageNumber as EdgarListFilingsResponsesPageNumber,
    type EdgarListFilingsParams as EdgarListFilingsParams,
  };
}