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

import { APIResource } from '../../core/resource';
import * as DocumentAPI from '../quartr/document';
import { PageNumber, type PageNumberParams, PagePromise } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';
import * as QuartrAPI_ from '../quartr/quartr';

/**
 * Look up companies by ticker and browse their EDGAR filings and Quartr documents.
 */
export class Quartr extends APIResource {
  /**
   * List IR documents 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 a Quartr company, then returns documents ordered by event
   * date. Each document includes its associated event. Use `type_ids` to filter by
   * document type; pass multiple values by repeating the query parameter. Use
   * `earliest_date` / `latest_date` to restrict by event date.
   */
  listDocuments(
    qualifiedTicker: string,
    query: QuartrListDocumentsParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<QuartrListDocumentsResponsesPageNumber, QuartrListDocumentsResponse> {
    return this._client.getAPIList(
      path`/company/${qualifiedTicker}/quartr/documents`,
      PageNumber<QuartrListDocumentsResponse>,
      { query, ...options },
    );
  }

  /**
   * List events for a company identified by ticker, with pagination and date
   * 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 a Quartr company, then returns events in reverse
   * chronological order. Each event includes its associated documents, deduplicated
   * by document type. Only events that have at least one document are included. Use
   * `earliest_date` / `latest_date` to restrict by event date.
   */
  listEvents(
    qualifiedTicker: string,
    query: QuartrListEventsParams | null | undefined = {},
    options?: RequestOptions,
  ): PagePromise<QuartrListEventsResponsesPageNumber, QuartrListEventsResponse> {
    return this._client.getAPIList(
      path`/company/${qualifiedTicker}/quartr/events`,
      PageNumber<QuartrListEventsResponse>,
      { query, ...options },
    );
  }
}

export type QuartrListDocumentsResponsesPageNumber = PageNumber<QuartrListDocumentsResponse>;

export type QuartrListEventsResponsesPageNumber = PageNumber<QuartrListEventsResponse>;

/**
 * A Quartr document with its associated event.
 */
export interface QuartrListDocumentsResponse extends DocumentAPI.QuartrDocument {
  /**
   * The event associated with this document.
   */
  event: QuartrAPI_.QuartrEvent;
}

/**
 * An event with its associated documents (deduplicated by type).
 */
export interface QuartrListEventsResponse extends QuartrAPI_.QuartrEvent {
  /**
   * Documents associated with this event, deduplicated by document type.
   */
  documents: Array<DocumentAPI.QuartrDocument>;
}

export interface QuartrListDocumentsParams extends PageNumberParams {
  /**
   * Only include documents with an event date on or after this date (inclusive).
   */
  earliest_date?: string | null;

  /**
   * Only include documents with an event date on or before this date (inclusive).
   */
  latest_date?: string | null;

  /**
   * Quartr document type IDs to filter by. Repeat the parameter to specify multiple
   * values. Use the `GET /quartr/document-types` endpoint to discover available type
   * IDs and their meanings.
   */
  type_ids?: Array<number> | null;
}

export interface QuartrListEventsParams extends PageNumberParams {
  /**
   * Only include events with a date on or after this date (inclusive).
   */
  earliest_date?: string | null;

  /**
   * Only include events with a date on or before this date (inclusive).
   */
  latest_date?: string | null;
}

export declare namespace Quartr {
  export {
    type QuartrListDocumentsResponse as QuartrListDocumentsResponse,
    type QuartrListEventsResponse as QuartrListEventsResponse,
    type QuartrListDocumentsResponsesPageNumber as QuartrListDocumentsResponsesPageNumber,
    type QuartrListEventsResponsesPageNumber as QuartrListEventsResponsesPageNumber,
    type QuartrListDocumentsParams as QuartrListDocumentsParams,
    type QuartrListEventsParams as QuartrListEventsParams,
  };
}