sentisense 0.49.0 → 0.51.0

package/dist/index.d.mts

@@ -657,6 +657,188 @@ 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";
+/**
+ * A risk condition evaluated against a rated stock. An active one deducts points from the
+ * score, up to 12 apiece; `percentile` itself is never touched by them.
+ */
+type RiskCondition = "thin_coverage" | "weak_dimension" | "unprofitable" | "no_fundamentals" | "high_leverage" | "unseasoned_listing" | "small_market_cap" | "thin_liquidity" | "extended_price" | "insider_selling" | "institutional_outflow";
+/**
+ * One graded deduction applied to a rated stock's score.
+ *
+ * A condition is graded rather than binary, so `points` is the share of the 12-point
+ * maximum this one actually cost. Only active conditions appear, and `penaltyPoints` is
+ * the sum of these.
+ */
+interface RiskAdjustment {
+    /** Which condition, by the same key `riskConditions` reports. */
+    condition: RiskCondition;
+    /** Points deducted, to one decimal, up to 12 for a single condition. */
+    points: number;
+}
+/**
+ * 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`.
+ *
+ * `score`, `bucketLetter`, `riskConditions`, `riskAdjustments` and `penaltyPoints` arrive
+ * from the next API deploy onward and are optional here because a response served before
+ * then omits them.
+ */
+interface StockRating extends RatingBase {
+    rated: true;
+    /**
+     * The headline number, 0 to 100 with one decimal, and the number `letter` is the band
+     * of: `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10
+     * when fewer than five dimensions are available and at 0 otherwise. Absent on a
+     * response served before this field shipped.
+     */
+    score?: number;
+    /**
+     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`: the band `score` falls in, at edges 90, 70, 30
+     * and 10. Served as stored, so read it rather than deriving your own edges. Deriving
+     * it from `percentile` disagrees with the API for every stock carrying a risk
+     * condition.
+     */
+    letter: string;
+    /**
+     * The band `percentile` alone would fall in, so a difference from `letter` is exactly
+     * what the risk conditions cost. Absent on a response served before this field
+     * shipped.
+     */
+    bucketLetter?: string;
+    /**
+     * Rank of `composite` among the day's rated stocks, 0 to 100. This stays the true rank
+     * of the blended signals: the risk conditions are subtracted from `score`, never here.
+     */
+    percentile: number;
+    /** The weighted blend before ranking, in [-1, +1]. */
+    composite: number;
+    /**
+     * Which risk conditions were active. An empty array means none were, and the field is
+     * absent on a response served before it shipped.
+     */
+    riskConditions?: RiskCondition[];
+    /**
+     * The same conditions with the points each one actually cost, since a condition is
+     * graded rather than binary and can cost anything up to 12. Absent on a response
+     * served before this field shipped.
+     */
+    riskAdjustments?: RiskAdjustment[];
+    /**
+     * The sum of `riskAdjustments` points, to one decimal: how far `score` sits below
+     * `percentile` before the floor applies. Absent on a response served before this field
+     * shipped.
+     */
+    penaltyPoints?: 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 StockNotRated 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 StockRatingResponse = StockRating | StockNotRated;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1375,7 +1557,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 score, 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 +2366,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 +2396,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 +3405,47 @@ 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 `score`,
+     * `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.
+     *
+     * **`score` and `percentile` are different numbers.** `percentile` is the rank of the
+     * blended signals against the day's rated set, and
+     * `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when
+     * fewer than five dimensions are available and at 0 otherwise. `letter` is the band
+     * `score` falls in, at edges 90, 70, 30 and 10, while `bucketLetter` is the band the
+     * percentile alone would fall in, so a difference between the two letters is exactly
+     * what the conditions cost. `riskConditions` names the active ones, `riskAdjustments`
+     * gives the points each cost (graded, up to 12 apiece), and `penaltyPoints` is their
+     * sum. `letter` is served as stored, so read it instead of computing your own bucket
+     * edges. The five fields arrive from the next API deploy onward and are optional, so a
+     * response served before then still parses.
+     *
+     * For the daily history of a stock's score, ask `client.entityMetrics.getMetrics` for
+     * the `sentisense_rating` metric.
+     */
+    getRating(ticker: string): Promise<StockRatingResponse>;
 }
 
 /**
@@ -3351,6 +3602,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.49.0";
+declare const VERSION = "0.51.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 RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, 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 StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, 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 };

package/dist/index.d.ts

@@ -657,6 +657,188 @@ 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";
+/**
+ * A risk condition evaluated against a rated stock. An active one deducts points from the
+ * score, up to 12 apiece; `percentile` itself is never touched by them.
+ */
+type RiskCondition = "thin_coverage" | "weak_dimension" | "unprofitable" | "no_fundamentals" | "high_leverage" | "unseasoned_listing" | "small_market_cap" | "thin_liquidity" | "extended_price" | "insider_selling" | "institutional_outflow";
+/**
+ * One graded deduction applied to a rated stock's score.
+ *
+ * A condition is graded rather than binary, so `points` is the share of the 12-point
+ * maximum this one actually cost. Only active conditions appear, and `penaltyPoints` is
+ * the sum of these.
+ */
+interface RiskAdjustment {
+    /** Which condition, by the same key `riskConditions` reports. */
+    condition: RiskCondition;
+    /** Points deducted, to one decimal, up to 12 for a single condition. */
+    points: number;
+}
+/**
+ * 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`.
+ *
+ * `score`, `bucketLetter`, `riskConditions`, `riskAdjustments` and `penaltyPoints` arrive
+ * from the next API deploy onward and are optional here because a response served before
+ * then omits them.
+ */
+interface StockRating extends RatingBase {
+    rated: true;
+    /**
+     * The headline number, 0 to 100 with one decimal, and the number `letter` is the band
+     * of: `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10
+     * when fewer than five dimensions are available and at 0 otherwise. Absent on a
+     * response served before this field shipped.
+     */
+    score?: number;
+    /**
+     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`: the band `score` falls in, at edges 90, 70, 30
+     * and 10. Served as stored, so read it rather than deriving your own edges. Deriving
+     * it from `percentile` disagrees with the API for every stock carrying a risk
+     * condition.
+     */
+    letter: string;
+    /**
+     * The band `percentile` alone would fall in, so a difference from `letter` is exactly
+     * what the risk conditions cost. Absent on a response served before this field
+     * shipped.
+     */
+    bucketLetter?: string;
+    /**
+     * Rank of `composite` among the day's rated stocks, 0 to 100. This stays the true rank
+     * of the blended signals: the risk conditions are subtracted from `score`, never here.
+     */
+    percentile: number;
+    /** The weighted blend before ranking, in [-1, +1]. */
+    composite: number;
+    /**
+     * Which risk conditions were active. An empty array means none were, and the field is
+     * absent on a response served before it shipped.
+     */
+    riskConditions?: RiskCondition[];
+    /**
+     * The same conditions with the points each one actually cost, since a condition is
+     * graded rather than binary and can cost anything up to 12. Absent on a response
+     * served before this field shipped.
+     */
+    riskAdjustments?: RiskAdjustment[];
+    /**
+     * The sum of `riskAdjustments` points, to one decimal: how far `score` sits below
+     * `percentile` before the floor applies. Absent on a response served before this field
+     * shipped.
+     */
+    penaltyPoints?: 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 StockNotRated 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 StockRatingResponse = StockRating | StockNotRated;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1375,7 +1557,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 score, 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 +2366,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 +2396,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 +3405,47 @@ 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 `score`,
+     * `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.
+     *
+     * **`score` and `percentile` are different numbers.** `percentile` is the rank of the
+     * blended signals against the day's rated set, and
+     * `score = percentile - sum(riskAdjustments.map((a) => a.points))`, floored at 10 when
+     * fewer than five dimensions are available and at 0 otherwise. `letter` is the band
+     * `score` falls in, at edges 90, 70, 30 and 10, while `bucketLetter` is the band the
+     * percentile alone would fall in, so a difference between the two letters is exactly
+     * what the conditions cost. `riskConditions` names the active ones, `riskAdjustments`
+     * gives the points each cost (graded, up to 12 apiece), and `penaltyPoints` is their
+     * sum. `letter` is served as stored, so read it instead of computing your own bucket
+     * edges. The five fields arrive from the next API deploy onward and are optional, so a
+     * response served before then still parses.
+     *
+     * For the daily history of a stock's score, ask `client.entityMetrics.getMetrics` for
+     * the `sentisense_rating` metric.
+     */
+    getRating(ticker: string): Promise<StockRatingResponse>;
 }
 
 /**
@@ -3351,6 +3602,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.49.0";
+declare const VERSION = "0.51.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 RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, 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 StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, 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 };