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

import { APIResource } from '../../../core/resource';
import * as FilingAPI from './filing';
import { APIPromise } from '../../../core/api-promise';
import { buildHeaders } from '../../../internal/headers';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

/**
 * Direct access to SEC EDGAR filings and documents by accession number.
 */
export class Document extends APIResource {
  /**
   * Retrieve a specific document from an SEC filing by its accession number and
   * sequence number. Returns the document metadata (ToC) along with the parent
   * filing's metadata, documents, and entities.
   */
  retrieve(
    sequence: number,
    params: DocumentRetrieveParams,
    options?: RequestOptions,
  ): APIPromise<DocumentRetrieveResponse> {
    const { accession_number } = params;
    return this._client.get(path`/edgar/filing/${accession_number}/document/${sequence}`, options);
  }

  /**
   * Download the rendered PDF version of an SEC filing document.
   *
   * The response is served with indefinite cache headers since rendered PDFs are
   * immutable artifacts.
   */
  downloadPdf(
    sequence: number,
    params: DocumentDownloadPdfParams,
    options?: RequestOptions,
  ): APIPromise<Response> {
    const { accession_number } = params;
    return this._client.get(path`/edgar/filing/${accession_number}/document/${sequence}/pdf`, {
      ...options,
      headers: buildHeaders([{ Accept: 'application/pdf' }, options?.headers]),
      __binaryResponse: true,
    });
  }

  /**
   * Get the extracted plaintext of an SEC filing document.
   *
   * Returns the document's text content reconstructed from parsed chunks, served
   * with indefinite cache headers since extracted text is an immutable artifact.
   */
  getText(sequence: number, params: DocumentGetTextParams, options?: RequestOptions): APIPromise<string> {
    const { accession_number } = params;
    return this._client.get(path`/edgar/filing/${accession_number}/document/${sequence}/text`, {
      ...options,
      headers: buildHeaders([{ Accept: 'text/plain' }, options?.headers]),
    });
  }
}

/**
 * An EDGAR document with the full parent filing attached.
 */
export interface DocumentRetrieveResponse extends FilingAPI.EdgarDocument {
  /**
   * The parent filing that contains this document.
   */
  filing: FilingAPI.EdgarFilingFull;

  /**
   * The table of contents of the document.
   */
  toc: Array<DocumentRetrieveResponse.Toc>;
}

export namespace DocumentRetrieveResponse {
  /**
   * A section of the table of contents.
   */
  export interface Toc {
    /**
     * The depth of the heading (1 for top-level, 2 for sub-section, etc.).
     */
    heading_level: number;

    /**
     * The 0-based page index where this section begins.
     */
    page_idx: number;

    /**
     * The heading text of this section.
     */
    title: string;
  }
}

export type DocumentGetTextResponse = string;

export interface DocumentRetrieveParams {
  /**
   * The SEC accession number of the filing (e.g. '0000320193-23-000077').
   */
  accession_number: string;
}

export interface DocumentDownloadPdfParams {
  /**
   * The SEC accession number of the filing (e.g. '0000320193-23-000077').
   */
  accession_number: string;
}

export interface DocumentGetTextParams {
  /**
   * The SEC accession number of the filing (e.g. '0000320193-23-000077').
   */
  accession_number: string;
}

export declare namespace Document {
  export {
    type DocumentRetrieveResponse as DocumentRetrieveResponse,
    type DocumentGetTextResponse as DocumentGetTextResponse,
    type DocumentRetrieveParams as DocumentRetrieveParams,
    type DocumentDownloadPdfParams as DocumentDownloadPdfParams,
    type DocumentGetTextParams as DocumentGetTextParams,
  };
}