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

import { APIResource } from '../../../resource';
import * as Core from '../../../core';
import * as SurpriseAPI from './surprise';

export class Surprise extends APIResource {
  /**
   * Returns FactSet Estimates surprise data using rolling fiscal dates.
   */
  create(body: SurpriseCreateParams, options?: Core.RequestOptions): Core.APIPromise<SurpriseResponse> {
    return this._client.post('/factset-estimates/v2/surprise', { body, ...options });
  }

  /**
   * Returns FactSet Estimates surprise data using rolling fiscal dates.
   */
  retrieve(query: SurpriseRetrieveParams, options?: Core.RequestOptions): Core.APIPromise<SurpriseResponse> {
    return this._client.get('/factset-estimates/v2/surprise', { query, ...options });
  }
}

export interface SurpriseResponse {
  /**
   * Array of surprises
   */
  data?: Array<SurpriseResponse.Data>;
}

export namespace SurpriseResponse {
  export interface Data {
    /**
     * Currency code for adjusting the data. Use 'ESTIMATE' as input value for the
     * values in Estimate Currency. For a list of currency ISO codes, visit
     * [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).
     */
    currency?: string | null;

    /**
     * Date for data expressed in YYYY-MM-DD format.
     */
    date?: string | null;

    /**
     * Estimate currency of the requested Security
     */
    estimateCurrency?: string | null;

    /**
     * Description of event. For more details, visit
     * [Online Assistant Page #16601](https://oa.apps.factset.com/pages/16601).
     */
    eventDescription?: string | null;

    /**
     * Flag for event. Code of Event Flag, where 0 = results and 1 = profit warning.
     * For more details, visit
     * [Online Assistant Page #16601](https://oa.apps.factset.com/pages/16601).
     */
    eventFlag?: number | null;

    /**
     * Company's 'fiscal end date' for the estimate record expressed in YYYY-MM-DD
     * format
     */
    fiscalEndDate?: string | null;

    /**
     * Company's 'fiscal period' for the estimate record. 'Periodicity' defines context
     * for period.
     */
    fiscalPeriod?: number | null;

    /**
     * Company's 'fiscal year' for the estimate record
     */
    fiscalYear?: number | null;

    fsymId?: string | null;

    /**
     * Company's Financial statement 'metric' that is estimated. Use the
     * factset-estimates/v#/metrics endpoint for a complete list. For more details,
     * visit [Online Assistant Page #15034](https://oa.apps.factset.com/pages/15034).
     */
    metric?: string | null;

    /**
     * Company's 'periodicity' for the estimate record, reflecting Annual, Quarterly,
     * or Semi-Annual report periods. Next-twelve-months (NTMA) and Last-twelve-months
     * (LTMA) also supported.
     */
    periodicity?: string | null;

    requestId?: string;

    /**
     * Method of calculation for the consensus 'statistic'. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114).
     */
    statistic?: string | null;

    /**
     * Actual value after event. For more details, visit
     * [Online Assistant Page #16145](https://oa.apps.factset.com/pages/16145).
     */
    surpriseAfter?: number | null;

    /**
     * Amount of difference between last consensus and actual. For more details, visit
     * [Online Assistant Page #16145](https://oa.apps.factset.com/pages/16145).
     */
    surpriseAmount?: number | null;

    /**
     * Last consensus before event. For more details, visit
     * [Online Assistant Page #16145](https://oa.apps.factset.com/pages/16145).
     */
    surpriseBefore?: number | null;

    /**
     * Date of the reported event expressed in YYYY-MM-DD format. For more details,
     * visit [Online Assistant Page #16601](https://oa.apps.factset.com/pages/16601).
     */
    surpriseDate?: string | null;

    /**
     * Percent difference between last consensus and actual. For more details, visit
     * [Online Assistant Page #16145](https://oa.apps.factset.com/pages/16145).
     */
    surprisePercent?: number | null;
  }
}

export interface SurpriseCreateParams {
  /**
   * The requested list of security identifiers. Accepted ID types include Market
   * Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. _ Make Note - id limit
   * of 3000 for defaults, otherwise the service is limited to a 30 second duration.
   * This can be reached when increasing total number of metrics requested and depth
   * of history. _
   */
  ids: Array<string>;

  /**
   * Requested metrics. Use the metrics endpoint for a list of estimate items. Note,
   * the number of metrics you are allowed to supply is limited to 1 for now. For
   * more details, visit
   * [Online Assistant Page #15034](https://oa.apps.factset.com/pages/15034).
   */
  metrics: Array<string>;

  /**
   * Currency code for adjusting the data. Use input as 'ESTIMATE' for values in
   * Estimate currency. For a list of currency ISO codes, visit
   * [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).
   */
  currency?: string;

  /**
   * The end date requested for a given date range in **YYYY-MM-DD** format. If left
   * blank, the API will default to previous close. Future dates (T+1) are not
   * accepted in this endpoint.
   */
  endDate?: string;

  /**
   * Controls the display frequency of the data returned.
   *
   * - **D** = Daily
   * - **W** = Weekly, based on the last day of the week of the start date.
   * - **AM** = Monthly, based on the start date (e.g., if the start date is June 16,
   *   data is displayed for June 16, May 16, April 16 etc.).
   * - **AQ** = Quarterly, based on the start date.
   * - **AY** = Actual Annual, based on the start date.
   */
  frequency?: 'D' | 'W' | 'AM' | 'AQ' | 'AY';

  /**
   * The periodicity for the estimates, reflecting Annual, Semi-Annual and Quarterly
   * Estimates.
   */
  periodicity?: 'ANN' | 'QTR' | 'SEMI';

  /**
   * The start date requested for a given date range in **YYYY-MM-DD** format. If
   * left blank, the API will default to previous close. Future dates (T+1) are not
   * accepted in this #endpoint.
   */
  startDate?: string;

  /**
   * Statistic for consensus calculation.
   */
  statistic?: 'MEAN' | 'MEDIAN' | 'HIGH' | 'LOW' | 'COUNT' | 'STDDEV';
}

export interface SurpriseRetrieveParams {
  /**
   * Security or Entity identifiers. FactSet Identifiers, tickers, CUSIP and SEDOL
   * are accepted input. <p>**\*ids limit** = 3000 per request*</p> * Make Note - id
   * limit of 3000 for defaults, otherwise the service is limited to a 30 second
   * duration. This can be reached when increasing total number of metrics requested
   * and depth of history. \*
   */
  ids: Array<string>;

  /**
   * Requested metrics. Use the /metrics endpoint to return a list of available
   * estimate items. Note, the number of metrics you are allowed to supply is limited
   * to 1 for now. **Top 10** most used metrics are **EPS, SALES, DPS, EBITDA,EBIT,
   * PRICE_TGT, CFPS, BPS, NET_INC, and ASSETS**. For more details, visit
   * [Online Assistant Page #15034](https://oa.apps.factset.com/pages/15034).
   */
  metrics: Array<string>;

  /**
   * Currency code for adjusting the data. Use 'ESTIMATE' as input value for the
   * values in Estimate Currency. For a list of currency ISO codes, visit
   * [Online Assistant Page #1470](https://oa.apps.factset.com/pages/1470).
   */
  currency?: string;

  /**
   * End date for point in time of estimates expressed in YYYY-MM-DD format.
   */
  endDate?: string;

  /**
   * Controls the frequency of the data returned.
   *
   * - **D** = Daily
   * - **W** = Weekly, based on the last day of the week of the start date.
   * - **AM** = Monthly, based on the start date (e.g., if the start date is June 16,
   *   data is displayed for June 16, May 16, April 16 etc.).
   * - **AQ** = Quarterly, based on the start date.
   * - **AY** = Actual Annual, based on the start date.
   */
  frequency?: 'D' | 'W' | 'AM' | 'AQ' | 'AY';

  /**
   * The periodicity for the estimates requested, allowing you to fetch Quarterly,
   * Semi-Annual and Annual Estimates.
   *
   * - **ANN** - Annual
   * - **QTR** - Quarterly
   * - **SEMI** - Semi-Annual
   */
  periodicity?: 'ANN' | 'QTR' | 'SEMI';

  /**
   * Start date for point in time of estimates expressed in YYYY-MM-DD format.
   */
  startDate?: string;

  /**
   * Statistic for consensus calculation.
   */
  statistic?: 'MEAN' | 'MEDIAN' | 'HIGH' | 'LOW' | 'COUNT' | 'STDDEV';
}

export namespace Surprise {
  export import SurpriseResponse = SurpriseAPI.SurpriseResponse;
  export import SurpriseCreateParams = SurpriseAPI.SurpriseCreateParams;
  export import SurpriseRetrieveParams = SurpriseAPI.SurpriseRetrieveParams;
}