sentisense 0.50.0 → 0.52.0

package/dist/index.d.mts

@@ -668,6 +668,24 @@ type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fu
  * 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.
  *
@@ -737,18 +755,59 @@ interface RatingBase {
     /** The standard financial disclaimer. Display it alongside the grade. */
     disclaimer: string;
 }
-/** A stock that has a grade for `asOf`. */
-interface RatedStockRating extends RatingBase {
+/**
+ * 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;
     /**
-     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`. Served as stored, never re-derived from
-     * `percentile`, so read it rather than computing your own bucket edges.
+     * 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;
-    /** Rank of `composite` among the day's rated stocks, 0 to 100. */
+    /**
+     * 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"`. */
@@ -758,7 +817,7 @@ interface RatedStockRating extends RatingBase {
  * 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 {
+interface StockNotRated extends RatingBase {
     rated: false;
     /** Why there is no grade. */
     reason: RatingNotRatedReason;
@@ -779,7 +838,7 @@ interface UnratedStockRating extends RatingBase {
  * 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 StockRatingResponse = StockRating | StockNotRated;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1500,7 +1559,7 @@ interface PreviewResponse<T> {
 /** Supported metric types for the v2 Serving Metrics API. */
 type MetricType = "mentions" | "sentiment" | "sentisense_score"
 /**
- * The SentiSense Rating percentile, 0 to 100. Time series only: it has no source
+ * 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";
@@ -3026,11 +3085,48 @@ declare class Institutional {
     getInstitutionDetail(slugOrCik: string): Promise<unknown>;
 }
 
+/** Public entity types the search `type` filter accepts, and that come back on a hit. */
+type EntitySearchType = "person" | "company" | "product" | "organization" | "etf" | "topic" | "country";
+/**
+ * One ranked match from {@link KB.searchEntities}.
+ *
+ * `urlSlug` is the handle the metric endpoints address an entity by, which is the reason
+ * this endpoint exists: it answers "what is the handle for the thing I typed".
+ */
+interface EntitySearchResult {
+    name: string;
+    /** Stable handle for this entity, or `null` when it has none. */
+    urlSlug: string | null;
+    /** `"person"`, `"company"`, `"product"`, `"organization"`, `"etf"`, `"topic"`, `"country"`. */
+    type: EntitySearchType | string | null;
+    /** The listed symbol for a tradeable entity, `null` for everything else. */
+    ticker: string | null;
+}
+interface SearchEntitiesOptions {
+    /** Narrow to one entity type. An unrecognised value is rejected with a 400. */
+    type?: EntitySearchType | string;
+    /** Matches to return, 1 to 25. Omitted, the API applies its own default of 10. */
+    limit?: number;
+}
 declare class KB {
     private client;
     constructor(client: APIClient);
     /** Get popular entities for search suggestions. */
     getPopularEntities(): Promise<KBEntity[]>;
+    /**
+     * Resolve a name, alias, ticker or slug to the entities we track, best match first.
+     *
+     * This is resolution, not enumeration: the query must be at least 2 characters and the
+     * result count is capped, so it answers "which handle did the user mean" rather than
+     * dumping the graph. Use it when someone typed "Tesla" and the rest of your code needs
+     * `TSLA`, or when you need the `urlSlug` an entity's metric series is addressed by.
+     *
+     * Returns a bare array, not a `PreviewResponse` envelope, and an empty array is the
+     * normal answer for a query that matches nothing.
+     *
+     * @param q What the user typed. At least 2 characters, or the API answers 400.
+     */
+    searchEntities(q: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult[]>;
 }
 
 declare class MarketMoodResource {
@@ -3356,10 +3452,10 @@ declare class Stocks {
      * 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`.
+     * **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
@@ -3369,13 +3465,24 @@ declare class Stocks {
      *
      * `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.
+     * 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 percentile, ask `client.entityMetrics.getMetrics`
-     * for the `sentisense_rating` metric.
+     * For the daily history of a stock's score, ask `client.entityMetrics.getMetrics` for
+     * the `sentisense_rating` metric.
      */
-    getRating(ticker: string): Promise<StockRating>;
+    getRating(ticker: string): Promise<StockRatingResponse>;
 }
 
 /**
@@ -3532,6 +3639,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.50.0";
+declare const VERSION = "0.52.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 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 };
+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 EntitySearchResult, type EntitySearchType, 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, type SearchEntitiesOptions, 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

@@ -668,6 +668,24 @@ type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fu
  * 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.
  *
@@ -737,18 +755,59 @@ interface RatingBase {
     /** The standard financial disclaimer. Display it alongside the grade. */
     disclaimer: string;
 }
-/** A stock that has a grade for `asOf`. */
-interface RatedStockRating extends RatingBase {
+/**
+ * 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;
     /**
-     * `"A"`, `"B"`, `"C"`, `"D"` or `"F"`. Served as stored, never re-derived from
-     * `percentile`, so read it rather than computing your own bucket edges.
+     * 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;
-    /** Rank of `composite` among the day's rated stocks, 0 to 100. */
+    /**
+     * 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"`. */
@@ -758,7 +817,7 @@ interface RatedStockRating extends RatingBase {
  * 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 {
+interface StockNotRated extends RatingBase {
     rated: false;
     /** Why there is no grade. */
     reason: RatingNotRatedReason;
@@ -779,7 +838,7 @@ interface UnratedStockRating extends RatingBase {
  * 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 StockRatingResponse = StockRating | StockNotRated;
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -1500,7 +1559,7 @@ interface PreviewResponse<T> {
 /** Supported metric types for the v2 Serving Metrics API. */
 type MetricType = "mentions" | "sentiment" | "sentisense_score"
 /**
- * The SentiSense Rating percentile, 0 to 100. Time series only: it has no source
+ * 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";
@@ -3026,11 +3085,48 @@ declare class Institutional {
     getInstitutionDetail(slugOrCik: string): Promise<unknown>;
 }
 
+/** Public entity types the search `type` filter accepts, and that come back on a hit. */
+type EntitySearchType = "person" | "company" | "product" | "organization" | "etf" | "topic" | "country";
+/**
+ * One ranked match from {@link KB.searchEntities}.
+ *
+ * `urlSlug` is the handle the metric endpoints address an entity by, which is the reason
+ * this endpoint exists: it answers "what is the handle for the thing I typed".
+ */
+interface EntitySearchResult {
+    name: string;
+    /** Stable handle for this entity, or `null` when it has none. */
+    urlSlug: string | null;
+    /** `"person"`, `"company"`, `"product"`, `"organization"`, `"etf"`, `"topic"`, `"country"`. */
+    type: EntitySearchType | string | null;
+    /** The listed symbol for a tradeable entity, `null` for everything else. */
+    ticker: string | null;
+}
+interface SearchEntitiesOptions {
+    /** Narrow to one entity type. An unrecognised value is rejected with a 400. */
+    type?: EntitySearchType | string;
+    /** Matches to return, 1 to 25. Omitted, the API applies its own default of 10. */
+    limit?: number;
+}
 declare class KB {
     private client;
     constructor(client: APIClient);
     /** Get popular entities for search suggestions. */
     getPopularEntities(): Promise<KBEntity[]>;
+    /**
+     * Resolve a name, alias, ticker or slug to the entities we track, best match first.
+     *
+     * This is resolution, not enumeration: the query must be at least 2 characters and the
+     * result count is capped, so it answers "which handle did the user mean" rather than
+     * dumping the graph. Use it when someone typed "Tesla" and the rest of your code needs
+     * `TSLA`, or when you need the `urlSlug` an entity's metric series is addressed by.
+     *
+     * Returns a bare array, not a `PreviewResponse` envelope, and an empty array is the
+     * normal answer for a query that matches nothing.
+     *
+     * @param q What the user typed. At least 2 characters, or the API answers 400.
+     */
+    searchEntities(q: string, options?: SearchEntitiesOptions): Promise<EntitySearchResult[]>;
 }
 
 declare class MarketMoodResource {
@@ -3356,10 +3452,10 @@ declare class Stocks {
      * 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`.
+     * **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
@@ -3369,13 +3465,24 @@ declare class Stocks {
      *
      * `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.
+     * 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 percentile, ask `client.entityMetrics.getMetrics`
-     * for the `sentisense_rating` metric.
+     * For the daily history of a stock's score, ask `client.entityMetrics.getMetrics` for
+     * the `sentisense_rating` metric.
      */
-    getRating(ticker: string): Promise<StockRating>;
+    getRating(ticker: string): Promise<StockRatingResponse>;
 }
 
 /**
@@ -3532,6 +3639,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.50.0";
+declare const VERSION = "0.52.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 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 };
+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 EntitySearchResult, type EntitySearchType, 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, type SearchEntitiesOptions, 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.mjs

@@ -676,6 +676,22 @@ var KB = class {
   async getPopularEntities() {
     return this.client.get("/api/v1/kb/entities/popular");
   }
+  /**
+   * Resolve a name, alias, ticker or slug to the entities we track, best match first.
+   *
+   * This is resolution, not enumeration: the query must be at least 2 characters and the
+   * result count is capped, so it answers "which handle did the user mean" rather than
+   * dumping the graph. Use it when someone typed "Tesla" and the rest of your code needs
+   * `TSLA`, or when you need the `urlSlug` an entity's metric series is addressed by.
+   *
+   * Returns a bare array, not a `PreviewResponse` envelope, and an empty array is the
+   * normal answer for a query that matches nothing.
+   *
+   * @param q What the user typed. At least 2 characters, or the API answers 400.
+   */
+  async searchEntities(q, options) {
+    return this.client.get("/api/v1/kb/entities/search", { q, ...options });
+  }
 };
 
 // src/resources/marketMood.ts
@@ -1080,10 +1096,10 @@ var Stocks = class {
    * 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`.
+   * **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
@@ -1093,11 +1109,22 @@ var Stocks = class {
    *
    * `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.
+   * 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.
    */
   async getRating(ticker) {
     return this.client.get(`/api/v1/rating/${encodeURIComponent(ticker.toUpperCase())}`);
@@ -1181,7 +1208,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.50.0";
+var VERSION = "0.52.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";