sentisense 0.31.0 → 0.33.0

package/dist/index.d.mts

@@ -87,6 +87,61 @@ interface StockEntity {
     type: string;
     [key: string]: unknown;
 }
+/** Per-source tone for a stock: where the conversation is, and how it leans. */
+interface SentimentSourceTone {
+    source: string;
+    /** "Bullish" | "Neutral" | "Bearish". */
+    direction: string;
+    /** Share of this stock's mentions coming from this source. */
+    mentionShare: number;
+    /** Exact polarity in [-1, 1]. */
+    value?: number;
+}
+/** A news story moving a stock's sentiment, with its own tone. */
+interface SentimentDriver {
+    title: string;
+    /** Tone of this driver in [-1, 1]. */
+    tone: number;
+}
+interface StockSentiment {
+    ticker: string;
+    companyName?: string;
+    /** ISO date (YYYY-MM-DD) the data is current as of. */
+    asOf?: string;
+    /** Latest SentiSense Score: a 0-centered composite of sentiment and mentions, unbounded. */
+    sentisenseScore?: number;
+    /** 30-day average Score, the stable regime figure. */
+    sentisenseScoreAvg30d?: number;
+    sentisenseScoreDelta30d?: number;
+    /** Seven-band label of the 30-day average. */
+    scoreLabel?: string;
+    /** "Bullish" | "Neutral" | "Bearish", from the 30-day average. */
+    direction?: string;
+    /** Same three bands, from today's read. */
+    latestDirection?: string;
+    /** "UP" | "DOWN" | "FLAT". */
+    trend?: string;
+    /** Daily Score series. */
+    scoreSparkline?: number[];
+    /** Today's mention volume. */
+    mentions?: number;
+    /** 30-day average mentions per day. */
+    mentionsAvg30d?: number;
+    socialDominance?: number;
+    bySource?: SentimentSourceTone[];
+    relatedTickers?: Array<{
+        ticker: string;
+        name: string;
+    }>;
+    drivers?: SentimentDriver[];
+    /** Plain-language summary of why the Score sits where it does. */
+    narrative?: string;
+    faq?: Array<{
+        question: string;
+        answer: string;
+    }>;
+    [key: string]: unknown;
+}
 interface ChartDataPoint {
     /** Unix timestamp in milliseconds. */
     timestamp?: number;
@@ -112,9 +167,47 @@ interface MarketStatus {
     status: string;
     [key: string]: unknown;
 }
+/**
+ * One period of filed financial statement data from `stocks.getFundamentals()`.
+ *
+ * The index signature is deliberate: the response carries the full income statement, balance
+ * sheet, and cash flow line items, and more are added over time, so every field is reachable
+ * whether or not it is typed here. The cash-flow block below is typed because its sign and
+ * relationships are easy to get wrong.
+ */
 interface Fundamentals {
     ticker: string;
     timeframe: string;
+    /**
+     * The currency the filer reports in ("USD", "KRW", "EUR", ...). Statement figures are as
+     * reported in this currency and are never converted to US dollars: foreign companies listed
+     * as ADRs file in their home currency while their listed share price is in USD. Absent means
+     * the currency is unknown, not implicitly USD. For non-USD filers the API serves `peRatio`,
+     * `psRatio`, and `pbRatio` as `null` on purpose (a USD price over a home-currency per-share
+     * figure is a unit mismatch); do not recompute them client-side.
+     */
+    reportedCurrency?: string;
+    /** Net cash from operating activities, in the reporting currency (see `reportedCurrency`). */
+    operatingCashFlow?: number | null;
+    /** Net cash from investing activities, in the reporting currency. */
+    investingCashFlow?: number | null;
+    /** Net cash from financing activities, in the reporting currency. */
+    financingCashFlow?: number | null;
+    /**
+     * Capital expenditure, in the reporting currency, signed as filed: normally NEGATIVE,
+     * because it is an outflow. Take the absolute value before treating it as a magnitude.
+     */
+    capitalExpenditure?: number | null;
+    /**
+     * Free cash flow, in the reporting currency: `operatingCashFlow - Math.abs(capitalExpenditure)`.
+     *
+     * `null` rather than a guess when the period's capital expenditure is not available, so a
+     * screen for positive free cash flow can never match on a fabricated number. Do not
+     * substitute `operatingCashFlow + investingCashFlow`: investing cash flow also carries
+     * marketable-securities and acquisition activity, which for a company holding a large
+     * securities portfolio is wrong by billions and can flip the sign.
+     */
+    freeCashFlow?: number | null;
     [key: string]: unknown;
 }
 /**
@@ -169,7 +262,14 @@ interface AISummary {
     [key: string]: unknown;
 }
 interface GetChartOptions {
-    timeframe?: "1D" | "5D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "ALL";
+    /**
+     * Chart range. "MAX" returns the full available history (up to ~26 years); "10Y" and "5Y"
+     * return weekly bars. Ranges of "5Y" and longer are split- and dividend-adjusted; shorter
+     * ranges are split-adjusted only.
+     *
+     * "ALL" is a legacy alias of "5Y", retained so existing code keeps compiling.
+     */
+    timeframe?: "1D" | "5D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "5Y" | "10Y" | "MAX" | "ALL";
 }
 interface GetImagesOptions {
     forced?: boolean;
@@ -1089,14 +1189,15 @@ declare class EntityMetrics {
     /**
      * Get time-series metric data for an entity using the v2 Serving Metrics API.
      *
-     * @param symbol   Ticker symbol (e.g. "AAPL") — the backend resolves the entity.
+     * @param symbol   Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
+     *                 case-insensitive; discover slugs via stocks.getEntities()).
      * @param options  Metric type and optional time range / resolution.
      */
     getMetrics(symbol: string, options?: MetricsOptions): Promise<ServingMetric[]>;
     /**
      * Get distribution data for a metric, broken down by a dimension (default: source).
      *
-     * @param symbol     Ticker symbol (e.g. "AAPL").
+     * @param symbol     Ticker symbol (e.g. "AAPL") or entity urlSlug.
      * @param metricType The metric to break down (e.g. "mentions", "sentiment").
      * @param options    Optional dimension parameter.
      */
@@ -1492,6 +1593,18 @@ declare class Stocks {
     getSimilar(ticker: string, options?: GetSimilarOptions): Promise<SimilarStock[]>;
     /** Get company profile (CEO, sector, industry, market data). */
     getProfile(ticker: string, options?: GetProfileOptions): Promise<StockProfile>;
+    /**
+     * Get the headline sentiment picture for a stock in one call.
+     *
+     * Returns the SentiSense Score with its 30-day regime, mention volume and social
+     * dominance, per-source tone in `bySource`, plus related tickers, story drivers, a
+     * narrative and an FAQ. Available in full on every API-key tier.
+     *
+     * Use `entityMetrics.getMetrics(ticker, "sentiment", ...)` instead when you need a time
+     * series over a specific window rather than the headline read. Returns 404 for tickers
+     * with no sentiment coverage.
+     */
+    getSentiment(ticker: string): Promise<PreviewResponse<StockSentiment>>;
     /** Get related KB entities (people, products, partners). */
     getEntities(ticker: string): Promise<StockEntity[]>;
     /** Get AI-generated stock analysis report. Requires PRO tier. */
@@ -1508,7 +1621,13 @@ declare class Stocks {
     getChart(ticker: string, options?: GetChartOptions): Promise<ChartData>;
     /** Get current market open/closed/pre-market/after-hours status. */
     getMarketStatus(): Promise<MarketStatus>;
-    /** Get financial statement data. */
+    /**
+     * Get financial statement data for one reporting period: income statement, balance sheet,
+     * and cash flow, including `capitalExpenditure` and `freeCashFlow`.
+     *
+     * Capital expenditure is signed as filed, so normally negative. See {@link Fundamentals}
+     * for the free-cash-flow relationship and when it is `null`.
+     */
     getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
     /** Get available fiscal periods. The periods are in `periods`. */
     getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriodsResponse>;
@@ -1632,6 +1751,17 @@ declare class AuthenticationError extends SentiSenseError {
 declare class NotFoundError extends SentiSenseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown when a deep chart range is still being assembled.
+ *
+ * The API answers 202 for "10Y" and "MAX" the first time a rarely-requested stock is asked
+ * for. It deliberately does not substitute a shorter range, so a successful response always
+ * carries the timeframe you asked for. Retry after a few seconds.
+ */
+declare class DeepHistoryUnavailableError extends SentiSenseError {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
 declare class RateLimitError extends SentiSenseError {
     retryAfter?: number;
     constructor(message: string, code?: string, retryAfter?: number);
@@ -1640,6 +1770,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.31.0";
+declare const VERSION = "0.33.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, 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 PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, 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 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 AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, 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 EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, 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 PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, 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 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

@@ -87,6 +87,61 @@ interface StockEntity {
     type: string;
     [key: string]: unknown;
 }
+/** Per-source tone for a stock: where the conversation is, and how it leans. */
+interface SentimentSourceTone {
+    source: string;
+    /** "Bullish" | "Neutral" | "Bearish". */
+    direction: string;
+    /** Share of this stock's mentions coming from this source. */
+    mentionShare: number;
+    /** Exact polarity in [-1, 1]. */
+    value?: number;
+}
+/** A news story moving a stock's sentiment, with its own tone. */
+interface SentimentDriver {
+    title: string;
+    /** Tone of this driver in [-1, 1]. */
+    tone: number;
+}
+interface StockSentiment {
+    ticker: string;
+    companyName?: string;
+    /** ISO date (YYYY-MM-DD) the data is current as of. */
+    asOf?: string;
+    /** Latest SentiSense Score: a 0-centered composite of sentiment and mentions, unbounded. */
+    sentisenseScore?: number;
+    /** 30-day average Score, the stable regime figure. */
+    sentisenseScoreAvg30d?: number;
+    sentisenseScoreDelta30d?: number;
+    /** Seven-band label of the 30-day average. */
+    scoreLabel?: string;
+    /** "Bullish" | "Neutral" | "Bearish", from the 30-day average. */
+    direction?: string;
+    /** Same three bands, from today's read. */
+    latestDirection?: string;
+    /** "UP" | "DOWN" | "FLAT". */
+    trend?: string;
+    /** Daily Score series. */
+    scoreSparkline?: number[];
+    /** Today's mention volume. */
+    mentions?: number;
+    /** 30-day average mentions per day. */
+    mentionsAvg30d?: number;
+    socialDominance?: number;
+    bySource?: SentimentSourceTone[];
+    relatedTickers?: Array<{
+        ticker: string;
+        name: string;
+    }>;
+    drivers?: SentimentDriver[];
+    /** Plain-language summary of why the Score sits where it does. */
+    narrative?: string;
+    faq?: Array<{
+        question: string;
+        answer: string;
+    }>;
+    [key: string]: unknown;
+}
 interface ChartDataPoint {
     /** Unix timestamp in milliseconds. */
     timestamp?: number;
@@ -112,9 +167,47 @@ interface MarketStatus {
     status: string;
     [key: string]: unknown;
 }
+/**
+ * One period of filed financial statement data from `stocks.getFundamentals()`.
+ *
+ * The index signature is deliberate: the response carries the full income statement, balance
+ * sheet, and cash flow line items, and more are added over time, so every field is reachable
+ * whether or not it is typed here. The cash-flow block below is typed because its sign and
+ * relationships are easy to get wrong.
+ */
 interface Fundamentals {
     ticker: string;
     timeframe: string;
+    /**
+     * The currency the filer reports in ("USD", "KRW", "EUR", ...). Statement figures are as
+     * reported in this currency and are never converted to US dollars: foreign companies listed
+     * as ADRs file in their home currency while their listed share price is in USD. Absent means
+     * the currency is unknown, not implicitly USD. For non-USD filers the API serves `peRatio`,
+     * `psRatio`, and `pbRatio` as `null` on purpose (a USD price over a home-currency per-share
+     * figure is a unit mismatch); do not recompute them client-side.
+     */
+    reportedCurrency?: string;
+    /** Net cash from operating activities, in the reporting currency (see `reportedCurrency`). */
+    operatingCashFlow?: number | null;
+    /** Net cash from investing activities, in the reporting currency. */
+    investingCashFlow?: number | null;
+    /** Net cash from financing activities, in the reporting currency. */
+    financingCashFlow?: number | null;
+    /**
+     * Capital expenditure, in the reporting currency, signed as filed: normally NEGATIVE,
+     * because it is an outflow. Take the absolute value before treating it as a magnitude.
+     */
+    capitalExpenditure?: number | null;
+    /**
+     * Free cash flow, in the reporting currency: `operatingCashFlow - Math.abs(capitalExpenditure)`.
+     *
+     * `null` rather than a guess when the period's capital expenditure is not available, so a
+     * screen for positive free cash flow can never match on a fabricated number. Do not
+     * substitute `operatingCashFlow + investingCashFlow`: investing cash flow also carries
+     * marketable-securities and acquisition activity, which for a company holding a large
+     * securities portfolio is wrong by billions and can flip the sign.
+     */
+    freeCashFlow?: number | null;
     [key: string]: unknown;
 }
 /**
@@ -169,7 +262,14 @@ interface AISummary {
     [key: string]: unknown;
 }
 interface GetChartOptions {
-    timeframe?: "1D" | "5D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "ALL";
+    /**
+     * Chart range. "MAX" returns the full available history (up to ~26 years); "10Y" and "5Y"
+     * return weekly bars. Ranges of "5Y" and longer are split- and dividend-adjusted; shorter
+     * ranges are split-adjusted only.
+     *
+     * "ALL" is a legacy alias of "5Y", retained so existing code keeps compiling.
+     */
+    timeframe?: "1D" | "5D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "5Y" | "10Y" | "MAX" | "ALL";
 }
 interface GetImagesOptions {
     forced?: boolean;
@@ -1089,14 +1189,15 @@ declare class EntityMetrics {
     /**
      * Get time-series metric data for an entity using the v2 Serving Metrics API.
      *
-     * @param symbol   Ticker symbol (e.g. "AAPL") — the backend resolves the entity.
+     * @param symbol   Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
+     *                 case-insensitive; discover slugs via stocks.getEntities()).
      * @param options  Metric type and optional time range / resolution.
      */
     getMetrics(symbol: string, options?: MetricsOptions): Promise<ServingMetric[]>;
     /**
      * Get distribution data for a metric, broken down by a dimension (default: source).
      *
-     * @param symbol     Ticker symbol (e.g. "AAPL").
+     * @param symbol     Ticker symbol (e.g. "AAPL") or entity urlSlug.
      * @param metricType The metric to break down (e.g. "mentions", "sentiment").
      * @param options    Optional dimension parameter.
      */
@@ -1492,6 +1593,18 @@ declare class Stocks {
     getSimilar(ticker: string, options?: GetSimilarOptions): Promise<SimilarStock[]>;
     /** Get company profile (CEO, sector, industry, market data). */
     getProfile(ticker: string, options?: GetProfileOptions): Promise<StockProfile>;
+    /**
+     * Get the headline sentiment picture for a stock in one call.
+     *
+     * Returns the SentiSense Score with its 30-day regime, mention volume and social
+     * dominance, per-source tone in `bySource`, plus related tickers, story drivers, a
+     * narrative and an FAQ. Available in full on every API-key tier.
+     *
+     * Use `entityMetrics.getMetrics(ticker, "sentiment", ...)` instead when you need a time
+     * series over a specific window rather than the headline read. Returns 404 for tickers
+     * with no sentiment coverage.
+     */
+    getSentiment(ticker: string): Promise<PreviewResponse<StockSentiment>>;
     /** Get related KB entities (people, products, partners). */
     getEntities(ticker: string): Promise<StockEntity[]>;
     /** Get AI-generated stock analysis report. Requires PRO tier. */
@@ -1508,7 +1621,13 @@ declare class Stocks {
     getChart(ticker: string, options?: GetChartOptions): Promise<ChartData>;
     /** Get current market open/closed/pre-market/after-hours status. */
     getMarketStatus(): Promise<MarketStatus>;
-    /** Get financial statement data. */
+    /**
+     * Get financial statement data for one reporting period: income statement, balance sheet,
+     * and cash flow, including `capitalExpenditure` and `freeCashFlow`.
+     *
+     * Capital expenditure is signed as filed, so normally negative. See {@link Fundamentals}
+     * for the free-cash-flow relationship and when it is `null`.
+     */
     getFundamentals(ticker: string, options?: GetFundamentalsOptions): Promise<Fundamentals>;
     /** Get available fiscal periods. The periods are in `periods`. */
     getFundamentalsPeriods(ticker: string): Promise<FundamentalsPeriodsResponse>;
@@ -1632,6 +1751,17 @@ declare class AuthenticationError extends SentiSenseError {
 declare class NotFoundError extends SentiSenseError {
     constructor(message: string, code?: string);
 }
+/**
+ * Thrown when a deep chart range is still being assembled.
+ *
+ * The API answers 202 for "10Y" and "MAX" the first time a rarely-requested stock is asked
+ * for. It deliberately does not substitute a shorter range, so a successful response always
+ * carries the timeframe you asked for. Retry after a few seconds.
+ */
+declare class DeepHistoryUnavailableError extends SentiSenseError {
+    retryAfter?: number;
+    constructor(message: string, retryAfter?: number);
+}
 declare class RateLimitError extends SentiSenseError {
     retryAfter?: number;
     constructor(message: string, code?: string, retryAfter?: number);
@@ -1640,6 +1770,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.31.0";
+declare const VERSION = "0.33.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, 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 PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, 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 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 AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, 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 EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, 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 PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, 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 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

@@ -19,6 +19,13 @@ var NotFoundError = class extends SentiSenseError {
     this.name = "NotFoundError";
   }
 };
+var DeepHistoryUnavailableError = class extends SentiSenseError {
+  constructor(message, retryAfter) {
+    super(message, 202);
+    this.name = "DeepHistoryUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+};
 var RateLimitError = class extends SentiSenseError {
   constructor(message, code, retryAfter) {
     super(message, 429, code);
@@ -152,7 +159,8 @@ var EntityMetrics = class {
   /**
    * Get time-series metric data for an entity using the v2 Serving Metrics API.
    *
-   * @param symbol   Ticker symbol (e.g. "AAPL") — the backend resolves the entity.
+   * @param symbol   Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
+   *                 case-insensitive; discover slugs via stocks.getEntities()).
    * @param options  Metric type and optional time range / resolution.
    */
   async getMetrics(symbol, options = {}) {
@@ -169,7 +177,7 @@ var EntityMetrics = class {
   /**
    * Get distribution data for a metric, broken down by a dimension (default: source).
    *
-   * @param symbol     Ticker symbol (e.g. "AAPL").
+   * @param symbol     Ticker symbol (e.g. "AAPL") or entity urlSlug.
    * @param metricType The metric to break down (e.g. "mentions", "sentiment").
    * @param options    Optional dimension parameter.
    */
@@ -564,6 +572,22 @@ var Stocks = class {
   async getProfile(ticker, options) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/profile`, options);
   }
+  /**
+   * Get the headline sentiment picture for a stock in one call.
+   *
+   * Returns the SentiSense Score with its 30-day regime, mention volume and social
+   * dominance, per-source tone in `bySource`, plus related tickers, story drivers, a
+   * narrative and an FAQ. Available in full on every API-key tier.
+   *
+   * Use `entityMetrics.getMetrics(ticker, "sentiment", ...)` instead when you need a time
+   * series over a specific window rather than the headline read. Returns 404 for tickers
+   * with no sentiment coverage.
+   */
+  async getSentiment(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker)}/sentiment`
+    );
+  }
   /** Get related KB entities (people, products, partners). */
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
@@ -597,7 +621,13 @@ var Stocks = class {
   async getMarketStatus() {
     return this.client.get("/api/v1/stocks/market-status");
   }
-  /** Get financial statement data. */
+  /**
+   * Get financial statement data for one reporting period: income statement, balance sheet,
+   * and cash flow, including `capitalExpenditure` and `freeCashFlow`.
+   *
+   * Capital expenditure is signed as filed, so normally negative. See {@link Fundamentals}
+   * for the free-cash-flow relationship and when it is `null`.
+   */
   async getFundamentals(ticker, options) {
     return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
   }
@@ -699,7 +729,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.31.0";
+var VERSION = "0.33.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -707,6 +737,16 @@ var DEFAULT_TIMEOUT = 3e4;
 var DEFAULT_MAX_RETRIES = 3;
 var BASE_DELAY_MS = 1e3;
 var MAX_DELAY_MS = 6e4;
+var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
+var MAX_DEEP_HISTORY_WAIT_S = 30;
+var MAX_RATE_LIMIT_WAIT_S = 120;
+var RATE_LIMIT_FALLBACK_WAIT_S = 60;
+function retryAfterSeconds(raw, defaultS, maxWaitS) {
+  if (!raw) return defaultS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) return defaultS;
+  return Math.min(Math.max(0.5, parsed), maxWaitS);
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -757,12 +797,34 @@ var SentiSense = class {
           headers,
           signal: controller.signal
         });
+        if (response.status === 202) {
+          const waitSeconds = retryAfterSeconds(
+            response.headers.get("Retry-After"),
+            DEEP_HISTORY_FALLBACK_WAIT_S,
+            MAX_DEEP_HISTORY_WAIT_S
+          );
+          try {
+            await response.body?.cancel();
+          } catch {
+          }
+          if (attempt < this.maxRetries) {
+            delayMs = waitSeconds * 1e3;
+            continue;
+          }
+          throw new DeepHistoryUnavailableError(
+            "Deep history is still being assembled. Retry in a few seconds.",
+            waitSeconds
+          );
+        }
         if (!response.ok) {
           const isRetryable = response.status === 429 || response.status >= 500;
           if (isRetryable && attempt < this.maxRetries) {
             if (response.status === 429) {
-              const ra = response.headers.get("Retry-After");
-              delayMs = (ra ? parseInt(ra, 10) : 60) * 1e3;
+              delayMs = retryAfterSeconds(
+                response.headers.get("Retry-After"),
+                RATE_LIMIT_FALLBACK_WAIT_S,
+                MAX_RATE_LIMIT_WAIT_S
+              ) * 1e3;
             } else {
               delayMs = Math.min(BASE_DELAY_MS * Math.pow(2, attempt), MAX_DELAY_MS) + Math.random() * 1e3;
             }
@@ -864,6 +926,7 @@ var SentiSense = class {
 export {
   APIError,
   AuthenticationError,
+  DeepHistoryUnavailableError,
   NotFoundError,
   RateLimitError,
   SentiSense,