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

import { APIResource } from '../../../resource';
import * as Core from '../../../core';
import * as SegmentsAPI from './segments';

export class Segments extends APIResource {
  /**
   * Returns FactSet Estimates Data for the segments gathered from the Business,
   * Geographical, or Actual Reconciliation (ADJUSTMENT) classifications by using
   * fiscal periods with a reporting frequency.
   */
  create(body: SegmentCreateParams, options?: Core.RequestOptions): Core.APIPromise<SegmentsResponse> {
    return this._client.post('/factset-estimates/v2/segments', { body, ...options });
  }

  /**
   * Returns FactSet Estimates Consensus Data for the segments gathered from the
   * Business, Geographical, or Actual Reconciliation (ADJUSTMENT) classifications by
   * using fiscal periods with a reporting frequency.
   */
  retrieve(query: SegmentRetrieveParams, options?: Core.RequestOptions): Core.APIPromise<SegmentsResponse> {
    return this._client.get('/factset-estimates/v2/segments', { query, ...options });
  }
}

export interface SegmentsResponse {
  /**
   * Array of Segments objects
   */
  data?: Array<SegmentsResponse.Data>;
}

export namespace SegmentsResponse {
  export interface Data {
    /**
     * Currency used estimates in consensus calculations. Use 'ESTIMATE' as input 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 | null;

    /**
     * Number of Up Revisions within the consensus for the metric and period. The
     * default window size is 100 days. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114).
     */
    down?: number | null;

    /**
     * Count or NEST of estimates in consensus calculation. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114)
     */
    estimateCount?: number | null;

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

    /**
     * The date the estimates are as of in YYYY-MM-DD format.
     */
    estimateDate?: string | null;

    /**
     * Company's 'fiscal end date' for the estimate record expressed in YYYY-MM-DD
     * format. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16598)
     */
    fiscalEndDate?: string | null;

    /**
     * Company's 'fiscal period' for the estimate record. Periods for periodicity of
     * ANN = 1, and SEMI = 2. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16598).
     */
    fiscalPeriod?: number | null;

    /**
     * Company's 'fiscal year' for the estimate record. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16598)
     */
    fiscalYear?: number | null;

    /**
     * Factset Regional Security Identifier. Six alpha-numeric characters, excluding
     * vowels, with an -R suffix (XXXXXX-R). Identifies the security’s best regional
     * security data series per currency. For equities, all primary listings per region
     * and currency are allocated a regional-level permanent identifier. The
     * regional-level permanent identifier will be available once a SEDOL representing
     * the region/currency has been allocated and the identifiers are on FactSet.
     */
    fsymId?: string | null;

    /**
     * Highest estimate in consensus calculation. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114).
     */
    high?: number | null;

    /**
     * Lowest estimate in consensus calculation. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114)
     */
    low?: number | null;

    /**
     * Mean of estimates in consensus calculation. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114)
     */
    mean?: number | null;

    /**
     * Median of estimates in consensus calculation. For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114)
     */
    median?: number | 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;

    /**
     * Identifier that was used for the request.
     */
    requestId?: string;

    /**
     * Displays the specific label of the segment.
     */
    segmentLabel?: string | null;

    /**
     * Returns the level of the segment item as either P = Parent or S = Subordinate
     */
    segmentLevel?: string | null;

    /**
     * Segment selected
     */
    segmentType?: string | null;

    /**
     * Standard deviation of estimates in consensus calculation. For more details,
     * visit [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114)
     */
    standardDeviation?: number | null;

    /**
     * Number of Up Revisions within the consensus for the metric and period. The
     * default window size is 100 days For more details, visit
     * [Online Assistant Page #16598](https://oa.apps.factset.com/pages/16114).
     */
    up?: number | null;
  }
}

export interface SegmentCreateParams {
  /**
   * The requested list of security identifiers. Accepted ID types include Market
   * Tickers, SEDOL, ISINs, CUSIPs, or FactSet Permanent Ids. _ Make Note - id limit
   * of 50 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. Next-twelve-months (NTMA) and Last-twelve-months (LTMA) also
   * supported.
   */
  periodicity?: 'ANN' | 'QTR' | 'SEMI' | 'LTMA' | 'NTMA';

  /**
   * Relative fiscal period, expressed as an integer, used to filter results.
   */
  relativeFiscalEnd?: number;

  /**
   * Relative fiscal period, expressed as an integer, used to filter results.
   */
  relativeFiscalStart?: number;

  /**
   * Controls the type of segment selected.
   *
   * - **BUS** = Business
   * - **GEO** = Geographic
   */
  segmentType?: 'BUS' | 'GEO';

  /**
   * 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;
}

export interface SegmentRetrieveParams {
  /**
   * Security or Entity identifiers. FactSet Identifiers, tickers, CUSIP and SEDOL
   * are accepted input. <p>**\*ids limit** = 50 per request*</p> * Make Note - id
   * limit of 50 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>;

  /**
   * Controls the type of segment selected.
   *
   * - **BUS** = Business / Product Segment
   * - **GEO** = Geographic Segment
   */
  segmentType: 'BUS' | 'GEO';

  /**
   * 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, Annual, and NTMA/LTMA Estimates.
   *
   * - **ANN** - Annual
   * - **QTR** - Quarterly
   * - **SEMI** - Semi-Annual
   * - **NTMA** - Next-Twelve-Months - Time-weighted Annual. Estimates use a
   *   percentage of annual estimates from two fiscal years to create an estimate
   *   based on the 12-month period. Visit
   *   [OA 16614](https://my.apps.factset.com/oa/pages/16614) for detail.
   * - **LTMA** - Last-Twelve-Months - Time-weighted Annual. Estimates use a
   *   percentage of annual estimates from two fiscal years to create an estimate
   *   based on the 12-month period. Visit
   *   [OA 16614](https://my.apps.factset.com/oa/pages/16614) for detail.
   */
  periodicity?: 'ANN' | 'QTR' | 'SEMI' | 'NTMA' | 'LTMA';

  /**
   * Relative fiscal period, expressed as an integer, used to filter results. This is
   * combined with the periodicity parameter to specify a relative estimate period.
   * For example, set to 2 and periodicity to ANN to ask for relative Fiscal Year 1
   * (FY2).
   */
  relativeFiscalEnd?: number;

  /**
   * Relative fiscal period, expressed as an integer, used to filter results. This is
   * combined with the periodicity parameter to specify a relative estimate period.
   * For example, set to 1 and periodicity to ANN to ask for relative Fiscal Year 1
   * (FY1).
   */
  relativeFiscalStart?: number;

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

export namespace Segments {
  export import SegmentsResponse = SegmentsAPI.SegmentsResponse;
  export import SegmentCreateParams = SegmentsAPI.SegmentCreateParams;
  export import SegmentRetrieveParams = SegmentsAPI.SegmentRetrieveParams;
}