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

import { APIResource } from '../../../resource';
import * as Core from '../../../core';
import * as DetailRatingsAPI from './detail-ratings';

export class DetailRatings extends APIResource {
  /**
   * Retrieves the Broker Level ratings for the requested Id and date range. Ratings
   * include Buy, Hold, Sell, Overweight, and Underweight.
   *
   * <p>The `startDate` and `endDate` parameters controls the range of perspective dates. By default, the service will return the range of estimateDates within the latest company's reporting period. As you expand the date range, additional full historical reporting periods and all ratings estimateDates per broker will be returned.</p>
   */
  create(
    body: DetailRatingCreateParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DetailRatingsResponse> {
    return this._client.post('/factset-estimates/v2/detail-ratings', { body, ...options });
  }

  /**
   * Retrieves the Broker Level ratings for the requested Id and date range. Ratings
   * include Buy, Hold, Sell, Overweight, and Underweight.
   *
   * <p>The `startDate` and `endDate` parameters controls the range of perspective dates. By default, the service will return the range of estimateDates within the latest company's reporting period. As you expand the date range, additional full historical reporting periods and all ratings estimateDates per broker will be returned.</p>
   */
  retrieve(
    query: DetailRatingRetrieveParams,
    options?: Core.RequestOptions,
  ): Core.APIPromise<DetailRatingsResponse> {
    return this._client.get('/factset-estimates/v2/detail-ratings', { query, ...options });
  }
}

export interface DetailRatingsResponse {
  /**
   * Array of detail ratings estimate objects
   */
  data?: Array<DetailRatingsResponse.Data>;
}

export namespace DetailRatingsResponse {
  export interface Data {
    /**
     * The FactSet Entity Identifier for the analyst making the estimate.
     */
    analystId?: string | null;

    /**
     * The name of the analyst making the estimate.
     */
    analystName?: string | null;

    /**
     * The FactSet Entity Identifier for the broker making the estimate.
     */
    brokerId?: string | null;

    /**
     * The name of the broker making the estimate.
     */
    brokerName?: string | null;

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

    fsymId?: string | null;

    /**
     * Date and time when the data is available at the source.
     */
    inputDateTime?: string | null;

    /**
     * The date at which a broker provided an estimate that is a revision.
     */
    lastModifiedDate?: string | null;

    /**
     * A textual representation of the analysts rating. Broker recommendations are
     * divided into five main broad categories- **Buy, Overweight, Hold, Underweight,
     * and Sell**.<p>Additional recommendations may be displayed for the below
     * reasons -
     *
     * - Without- A rating "Without" is displayed when a broker provides estimates but
     *   does not provide a rating.
     * - Dropping- When a broker stops covering an equity, the recommendation will show
     *   "Dropping."
     * - Not Available- A broker may be "Not Available" due to outstanding
     *   circumstances with that particular security. Ratings are not displayed until a
     *   new rating is provided.
     * - Most/Least- "Most" or "Least" favorable rating is displayed for top or bottom
     *   rating available for a particular security.
     */
    ratingsNoteText?: string | null;

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

export interface DetailRatingCreateParams {
  /**
   * 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>;

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

  /**
   * Include All filter is used to identify included and excluded broker details from
   * the consensus By default the service would return only the brokers included in
   * the consensus-
   *
   * - **TRUE** = Returns all the brokers included and excluded in the consensus
   * - **FALSE** = Returns only the broker details included in the consensus
   */
  includeAll?: boolean;

  /**
   * 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 DetailRatingRetrieveParams {
  /**
   * 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>;

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

  /**
   * Include All filter is used to identify included and excluded broker details from
   * the consensus By default the service would return only the brokers included in
   * the consensus-
   *
   * - **TRUE** = Returns all the brokers included and excluded in the consensus
   * - **FALSE** = Returns only the broker details included in the consensus
   */
  includeAll?: boolean;

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

export namespace DetailRatings {
  export import DetailRatingsResponse = DetailRatingsAPI.DetailRatingsResponse;
  export import DetailRatingCreateParams = DetailRatingsAPI.DetailRatingCreateParams;
  export import DetailRatingRetrieveParams = DetailRatingsAPI.DetailRatingRetrieveParams;
}