sentisense 0.49.0 → 0.50.0

package/dist/index.d.mts

@@ -657,6 +657,129 @@ interface OptionsOverview {
     /** Full ETF board size on a FREE response, mirroring what the envelope's `totalCount` does for stocks. */
     etfTotalCount?: number;
 }
+/** The six dimensions the composite is blended from, by stable `key`. */
+type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings";
+/**
+ * Why a stock has no grade.
+ *
+ * `stale` means a row exists but the nightly has not written recently, which is an
+ * operational gap rather than a coverage one. `not_rated_today` means no row and no refusal
+ * on record: an ETF, a ticker outside the swept universe, or one that entered coverage after
+ * the last run. The other two mean the run looked and declined to grade.
+ */
+type RatingNotRatedReason = "stale" | "not_rated_today" | "insufficient_dimensions" | "insufficient_coverage_weight";
+/**
+ * One constituent leg behind a dimension's percentile.
+ *
+ * Only the smart-money dimension carries legs today; every other dimension omits the field
+ * entirely, so an absent `subLegs` means "this dimension has no legs", never "the legs were
+ * all zero".
+ */
+interface RatingSubLeg {
+    /** Stable snake_case identifier, e.g. `"inst_13f"`. */
+    key: string;
+    label: string;
+    /** The leg's natural-scale reading. `null` when the leg had no data. */
+    raw: number | null;
+    /** `"%"` for a percentage, `"ratio"` for a scale-free balance. */
+    unit: string;
+}
+/**
+ * One of the six dimensions the composite is blended from.
+ *
+ * **All six always arrive, in a fixed order, whether or not they had data.** An absent
+ * dimension is a full row with `present` false and a `null` percentile; the server never
+ * drops it, precisely so a client cannot mistake a gap for a five-dimension rating. Read
+ * `present` before reading `percentile`, and never substitute zero for a `null`: zero is the
+ * bottom of the cross-section, absence is not a position on it.
+ */
+interface RatingDimension {
+    key: RatingDimensionKey;
+    /** Display label, owned by the API so every surface agrees on the wording. */
+    label: string;
+    /** The dimension's cross-sectional rank, 0 to 100. `null` when absent. */
+    percentile: number | null;
+    /** The natural-scale reading behind the percentile, when the dimension has one. */
+    raw: number | null;
+    /** What `raw` means and in what unit, e.g. `"Operating margin, percent"`. */
+    rawLabel: string | null;
+    /** Whether this dimension had data for this stock. */
+    present: boolean;
+    /** Constituent legs, currently smart-money only. Absent on every other dimension. */
+    subLegs?: RatingSubLeg[];
+}
+/**
+ * One anomaly flag evaluated alongside the rating.
+ *
+ * Flags are informational and never move the composite. A flag the run could not evaluate is
+ * absent from the list rather than reported inactive, so present-and-false and absent stay
+ * distinguishable.
+ */
+interface RatingFlag {
+    /** Stable snake_case identifier, e.g. `"unusual_options_flow"`. */
+    key: string;
+    label: string;
+    active: boolean;
+}
+/** The fields both rating shapes carry, graded or not. */
+interface RatingBase {
+    ticker: string;
+    /**
+     * The stock's knowledge base id, e.g. `"kb/company/1"`. Addresses the metrics time series
+     * without a second lookup.
+     */
+    kbEntityId: string;
+    /** The New York calendar day this answer describes, `"YYYY-MM-DD"`. */
+    asOf: string;
+    /** Always all six, in a fixed order, absent ones with `present` false. */
+    dimensions: RatingDimension[];
+    flags: RatingFlag[];
+    /** The standard financial disclaimer. Display it alongside the grade. */
+    disclaimer: string;
+}
+/** A stock that has a grade for `asOf`. */
+interface RatedStockRating extends RatingBase {
+    rated: true;
+    /**
+     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`. Served as stored, never re-derived from
+     * `percentile`, so read it rather than computing your own bucket edges.
+     */
+    letter: string;
+    /** Rank of `composite` among the day's rated stocks, 0 to 100. */
+    percentile: number;
+    /** The weighted blend before ranking, in [-1, +1]. */
+    composite: number;
+    /** How many stocks were rated that day: the rank's denominator. */
+    ratedCount: number;
+    /** The weights and floors in force when the row was written, e.g. `"2026.09-v1"`. */
+    methodologyVersion: string;
+}
+/**
+ * A stock with no grade for `asOf`. A normal 200, not an error: ETFs and tickers outside
+ * the swept universe answer this way, and the composition still arrives so a card can render.
+ */
+interface UnratedStockRating extends RatingBase {
+    rated: false;
+    /** Why there is no grade. */
+    reason: RatingNotRatedReason;
+    /** How many of the six dimensions had data. */
+    dimensionsPresent?: number;
+    /** Which dimensions had data, by `key`. */
+    presentDimensions: RatingDimensionKey[];
+}
+/**
+ * The SentiSense Rating for one stock: where it ranks against the day's rated set.
+ *
+ * A discriminated union on `rated`, so `if (rating.rated)` narrows to the graded fields and
+ * the `else` branch narrows to `reason`. Branch on that flag rather than testing a field for
+ * `undefined`.
+ *
+ * The rating is a *relative* research signal, informational and educational only. It ranks a
+ * stock against the others rated that day; it is not financial, investment or trading advice
+ * and it is not a recommendation about any security. Carry `disclaimer` wherever you display
+ * a grade. Methodology: https://sentisense.ai/methodology/#sentisense-rating
+ */
+type StockRating = RatedStockRating | UnratedStockRating;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1375,7 +1498,12 @@ interface PreviewResponse<T> {
     data: T;
 }
 /** Supported metric types for the v2 Serving Metrics API. */
-type MetricType = "mentions" | "sentiment" | "sentisense_score" | "social_dominance" | "creators";
+type MetricType = "mentions" | "sentiment" | "sentisense_score"
+/**
+ * The SentiSense Rating percentile, 0 to 100. Time series only: it has no source
+ * breakdown, so `getDistribution` answers with an empty distribution for it.
+ */
+ | "sentisense_rating" | "social_dominance" | "creators";
 /** Options for `EntityMetrics.getMetrics()`. */
 interface MetricsOptions {
     /** Metric to retrieve. Defaults to `"sentiment"`. */
@@ -2179,6 +2307,23 @@ interface AnalystCoverageFirm {
     latestNote: AnalystNote | null;
     firmRating: AnalystFirmRating | null;
 }
+/**
+ * Covering firms counted by the tier of their current rating. Counted over the whole
+ * book before the free truncation, so `buy + hold + sell + unrated === total` and a free
+ * key reads the same numbers as a PRO one.
+ */
+interface AnalystRatingBuckets {
+    /** Buy-tier grades: Buy, Overweight, Outperform, Strong Buy, Sector Outperform. */
+    buy: number;
+    /** Hold-tier grades: Hold, Neutral, Equal-Weight, Market Perform. */
+    hold: number;
+    /** Sell-tier grades. */
+    sell: number;
+    /** No current rating on record (a price-target-only desk), or a grade we do not recognise. */
+    unrated: number;
+    /** Every covering firm. Equals `firmCount`. */
+    total: number;
+}
 interface AnalystCoverage {
     ticker: string;
     /** Window actually applied after clamping, in days. */
@@ -2192,6 +2337,12 @@ interface AnalystCoverage {
      * target are `firmCount - ratingOnlyFirmCount`.
      */
     ratingOnlyFirmCount: number;
+    /**
+     * The same firms split by the tier of their current rating. A different population from
+     * `strongBuy`..`strongSell` on the consensus endpoint, which report the provider's
+     * analyst survey rather than the firms in this book, so do not reconcile the two.
+     */
+    ratingBuckets?: AnalystRatingBuckets;
     namedAnalystCount: number;
     noteCount: number;
     /** Notes that name an individual. */
@@ -3195,6 +3346,36 @@ declare class Stocks {
      * years, so it can answer with nearly the same series as `"2y"`.
      */
     getOptionsHistory(ticker: string, options?: GetOptionsHistoryOptions): Promise<PreviewResponse<OptionsHistory>>;
+    /**
+     * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
+     * that day, and the six dimensions the rank is blended from.
+     *
+     * The Rating is a *relative*, automatically generated research signal, for informational
+     * and educational purposes only. It ranks a stock against its cross-section; it is not
+     * financial, investment or trading advice and it is not a recommendation about any
+     * security. `disclaimer` carries the wording to display alongside a grade. Methodology:
+     * https://sentisense.ai/methodology/#sentisense-rating
+     *
+     * **A discriminated union on `rated`.** `if (rating.rated)` narrows to `letter`,
+     * `percentile`, `composite`, `ratedCount` and `methodologyVersion`; the `else` branch
+     * narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on the flag
+     * rather than testing a field for `undefined`.
+     *
+     * **Having no grade is a normal 200, not a 404.** ETFs and tickers outside the swept
+     * universe answer with `rated` false, and the composition still arrives so a card can
+     * render. Only a ticker that resolves to nothing we track rejects with
+     * {@link NotFoundError}; a request with no usable key rejects with
+     * {@link AuthenticationError}.
+     *
+     * `dimensions` always holds all six rows in a fixed order, including the ones with no
+     * data, which arrive with `present` false and a `null` percentile. Read `present` first
+     * and never read a missing percentile as zero. `letter` is served as stored rather than
+     * derived from `percentile`, so read it instead of computing your own bucket edges.
+     *
+     * For the daily history of a stock's percentile, ask `client.entityMetrics.getMetrics`
+     * for the `sentisense_rating` metric.
+     */
+    getRating(ticker: string): Promise<StockRating>;
 }
 
 /**
@@ -3351,6 +3532,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.49.0";
+declare const VERSION = "0.50.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type StockSocialDominance, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatedStockRating, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockSocialDominance, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, type UnratedStockRating, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };

package/dist/index.d.ts

@@ -657,6 +657,129 @@ interface OptionsOverview {
     /** Full ETF board size on a FREE response, mirroring what the envelope's `totalCount` does for stocks. */
     etfTotalCount?: number;
 }
+/** The six dimensions the composite is blended from, by stable `key`. */
+type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings";
+/**
+ * Why a stock has no grade.
+ *
+ * `stale` means a row exists but the nightly has not written recently, which is an
+ * operational gap rather than a coverage one. `not_rated_today` means no row and no refusal
+ * on record: an ETF, a ticker outside the swept universe, or one that entered coverage after
+ * the last run. The other two mean the run looked and declined to grade.
+ */
+type RatingNotRatedReason = "stale" | "not_rated_today" | "insufficient_dimensions" | "insufficient_coverage_weight";
+/**
+ * One constituent leg behind a dimension's percentile.
+ *
+ * Only the smart-money dimension carries legs today; every other dimension omits the field
+ * entirely, so an absent `subLegs` means "this dimension has no legs", never "the legs were
+ * all zero".
+ */
+interface RatingSubLeg {
+    /** Stable snake_case identifier, e.g. `"inst_13f"`. */
+    key: string;
+    label: string;
+    /** The leg's natural-scale reading. `null` when the leg had no data. */
+    raw: number | null;
+    /** `"%"` for a percentage, `"ratio"` for a scale-free balance. */
+    unit: string;
+}
+/**
+ * One of the six dimensions the composite is blended from.
+ *
+ * **All six always arrive, in a fixed order, whether or not they had data.** An absent
+ * dimension is a full row with `present` false and a `null` percentile; the server never
+ * drops it, precisely so a client cannot mistake a gap for a five-dimension rating. Read
+ * `present` before reading `percentile`, and never substitute zero for a `null`: zero is the
+ * bottom of the cross-section, absence is not a position on it.
+ */
+interface RatingDimension {
+    key: RatingDimensionKey;
+    /** Display label, owned by the API so every surface agrees on the wording. */
+    label: string;
+    /** The dimension's cross-sectional rank, 0 to 100. `null` when absent. */
+    percentile: number | null;
+    /** The natural-scale reading behind the percentile, when the dimension has one. */
+    raw: number | null;
+    /** What `raw` means and in what unit, e.g. `"Operating margin, percent"`. */
+    rawLabel: string | null;
+    /** Whether this dimension had data for this stock. */
+    present: boolean;
+    /** Constituent legs, currently smart-money only. Absent on every other dimension. */
+    subLegs?: RatingSubLeg[];
+}
+/**
+ * One anomaly flag evaluated alongside the rating.
+ *
+ * Flags are informational and never move the composite. A flag the run could not evaluate is
+ * absent from the list rather than reported inactive, so present-and-false and absent stay
+ * distinguishable.
+ */
+interface RatingFlag {
+    /** Stable snake_case identifier, e.g. `"unusual_options_flow"`. */
+    key: string;
+    label: string;
+    active: boolean;
+}
+/** The fields both rating shapes carry, graded or not. */
+interface RatingBase {
+    ticker: string;
+    /**
+     * The stock's knowledge base id, e.g. `"kb/company/1"`. Addresses the metrics time series
+     * without a second lookup.
+     */
+    kbEntityId: string;
+    /** The New York calendar day this answer describes, `"YYYY-MM-DD"`. */
+    asOf: string;
+    /** Always all six, in a fixed order, absent ones with `present` false. */
+    dimensions: RatingDimension[];
+    flags: RatingFlag[];
+    /** The standard financial disclaimer. Display it alongside the grade. */
+    disclaimer: string;
+}
+/** A stock that has a grade for `asOf`. */
+interface RatedStockRating extends RatingBase {
+    rated: true;
+    /**
+     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`. Served as stored, never re-derived from
+     * `percentile`, so read it rather than computing your own bucket edges.
+     */
+    letter: string;
+    /** Rank of `composite` among the day's rated stocks, 0 to 100. */
+    percentile: number;
+    /** The weighted blend before ranking, in [-1, +1]. */
+    composite: number;
+    /** How many stocks were rated that day: the rank's denominator. */
+    ratedCount: number;
+    /** The weights and floors in force when the row was written, e.g. `"2026.09-v1"`. */
+    methodologyVersion: string;
+}
+/**
+ * A stock with no grade for `asOf`. A normal 200, not an error: ETFs and tickers outside
+ * the swept universe answer this way, and the composition still arrives so a card can render.
+ */
+interface UnratedStockRating extends RatingBase {
+    rated: false;
+    /** Why there is no grade. */
+    reason: RatingNotRatedReason;
+    /** How many of the six dimensions had data. */
+    dimensionsPresent?: number;
+    /** Which dimensions had data, by `key`. */
+    presentDimensions: RatingDimensionKey[];
+}
+/**
+ * The SentiSense Rating for one stock: where it ranks against the day's rated set.
+ *
+ * A discriminated union on `rated`, so `if (rating.rated)` narrows to the graded fields and
+ * the `else` branch narrows to `reason`. Branch on that flag rather than testing a field for
+ * `undefined`.
+ *
+ * The rating is a *relative* research signal, informational and educational only. It ranks a
+ * stock against the others rated that day; it is not financial, investment or trading advice
+ * and it is not a recommendation about any security. Carry `disclaimer` wherever you display
+ * a grade. Methodology: https://sentisense.ai/methodology/#sentisense-rating
+ */
+type StockRating = RatedStockRating | UnratedStockRating;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1375,7 +1498,12 @@ interface PreviewResponse<T> {
     data: T;
 }
 /** Supported metric types for the v2 Serving Metrics API. */
-type MetricType = "mentions" | "sentiment" | "sentisense_score" | "social_dominance" | "creators";
+type MetricType = "mentions" | "sentiment" | "sentisense_score"
+/**
+ * The SentiSense Rating percentile, 0 to 100. Time series only: it has no source
+ * breakdown, so `getDistribution` answers with an empty distribution for it.
+ */
+ | "sentisense_rating" | "social_dominance" | "creators";
 /** Options for `EntityMetrics.getMetrics()`. */
 interface MetricsOptions {
     /** Metric to retrieve. Defaults to `"sentiment"`. */
@@ -2179,6 +2307,23 @@ interface AnalystCoverageFirm {
     latestNote: AnalystNote | null;
     firmRating: AnalystFirmRating | null;
 }
+/**
+ * Covering firms counted by the tier of their current rating. Counted over the whole
+ * book before the free truncation, so `buy + hold + sell + unrated === total` and a free
+ * key reads the same numbers as a PRO one.
+ */
+interface AnalystRatingBuckets {
+    /** Buy-tier grades: Buy, Overweight, Outperform, Strong Buy, Sector Outperform. */
+    buy: number;
+    /** Hold-tier grades: Hold, Neutral, Equal-Weight, Market Perform. */
+    hold: number;
+    /** Sell-tier grades. */
+    sell: number;
+    /** No current rating on record (a price-target-only desk), or a grade we do not recognise. */
+    unrated: number;
+    /** Every covering firm. Equals `firmCount`. */
+    total: number;
+}
 interface AnalystCoverage {
     ticker: string;
     /** Window actually applied after clamping, in days. */
@@ -2192,6 +2337,12 @@ interface AnalystCoverage {
      * target are `firmCount - ratingOnlyFirmCount`.
      */
     ratingOnlyFirmCount: number;
+    /**
+     * The same firms split by the tier of their current rating. A different population from
+     * `strongBuy`..`strongSell` on the consensus endpoint, which report the provider's
+     * analyst survey rather than the firms in this book, so do not reconcile the two.
+     */
+    ratingBuckets?: AnalystRatingBuckets;
     namedAnalystCount: number;
     noteCount: number;
     /** Notes that name an individual. */
@@ -3195,6 +3346,36 @@ declare class Stocks {
      * years, so it can answer with nearly the same series as `"2y"`.
      */
     getOptionsHistory(ticker: string, options?: GetOptionsHistoryOptions): Promise<PreviewResponse<OptionsHistory>>;
+    /**
+     * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
+     * that day, and the six dimensions the rank is blended from.
+     *
+     * The Rating is a *relative*, automatically generated research signal, for informational
+     * and educational purposes only. It ranks a stock against its cross-section; it is not
+     * financial, investment or trading advice and it is not a recommendation about any
+     * security. `disclaimer` carries the wording to display alongside a grade. Methodology:
+     * https://sentisense.ai/methodology/#sentisense-rating
+     *
+     * **A discriminated union on `rated`.** `if (rating.rated)` narrows to `letter`,
+     * `percentile`, `composite`, `ratedCount` and `methodologyVersion`; the `else` branch
+     * narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on the flag
+     * rather than testing a field for `undefined`.
+     *
+     * **Having no grade is a normal 200, not a 404.** ETFs and tickers outside the swept
+     * universe answer with `rated` false, and the composition still arrives so a card can
+     * render. Only a ticker that resolves to nothing we track rejects with
+     * {@link NotFoundError}; a request with no usable key rejects with
+     * {@link AuthenticationError}.
+     *
+     * `dimensions` always holds all six rows in a fixed order, including the ones with no
+     * data, which arrive with `present` false and a `null` percentile. Read `present` first
+     * and never read a missing percentile as zero. `letter` is served as stored rather than
+     * derived from `percentile`, so read it instead of computing your own bucket edges.
+     *
+     * For the daily history of a stock's percentile, ask `client.entityMetrics.getMetrics`
+     * for the `sentisense_rating` metric.
+     */
+    getRating(ticker: string): Promise<StockRating>;
 }
 
 /**
@@ -3351,6 +3532,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.49.0";
+declare const VERSION = "0.50.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type StockSocialDominance, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatedStockRating, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockSocialDominance, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, type UnratedStockRating, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };

package/dist/index.mjs

@@ -1070,6 +1070,38 @@ var Stocks = class {
       options
     );
   }
+  /**
+   * Get the SentiSense Rating for one stock: where it ranks against the other stocks rated
+   * that day, and the six dimensions the rank is blended from.
+   *
+   * The Rating is a *relative*, automatically generated research signal, for informational
+   * and educational purposes only. It ranks a stock against its cross-section; it is not
+   * financial, investment or trading advice and it is not a recommendation about any
+   * security. `disclaimer` carries the wording to display alongside a grade. Methodology:
+   * https://sentisense.ai/methodology/#sentisense-rating
+   *
+   * **A discriminated union on `rated`.** `if (rating.rated)` narrows to `letter`,
+   * `percentile`, `composite`, `ratedCount` and `methodologyVersion`; the `else` branch
+   * narrows to `reason`, `dimensionsPresent` and `presentDimensions`. Branch on the flag
+   * rather than testing a field for `undefined`.
+   *
+   * **Having no grade is a normal 200, not a 404.** ETFs and tickers outside the swept
+   * universe answer with `rated` false, and the composition still arrives so a card can
+   * render. Only a ticker that resolves to nothing we track rejects with
+   * {@link NotFoundError}; a request with no usable key rejects with
+   * {@link AuthenticationError}.
+   *
+   * `dimensions` always holds all six rows in a fixed order, including the ones with no
+   * data, which arrive with `present` false and a `null` percentile. Read `present` first
+   * and never read a missing percentile as zero. `letter` is served as stored rather than
+   * derived from `percentile`, so read it instead of computing your own bucket edges.
+   *
+   * For the daily history of a stock's percentile, ask `client.entityMetrics.getMetrics`
+   * for the `sentisense_rating` metric.
+   */
+  async getRating(ticker) {
+    return this.client.get(`/api/v1/rating/${encodeURIComponent(ticker.toUpperCase())}`);
+  }
 };
 
 // src/resources/indexes.ts
@@ -1149,7 +1181,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.49.0";
+var VERSION = "0.50.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";