sentisense 0.34.0 → 0.36.0

package/dist/index.d.mts

@@ -308,6 +308,11 @@ interface GetProfileOptions {
 }
 interface GetAISummaryOptions {
     depth?: "basic" | "deep";
+    /**
+     * @deprecated Has no effect and is no longer sent. Reports are curated and served
+     * as published, so there is nothing for a caller to regenerate on demand. Accepted
+     * only so existing code keeps compiling; drop it from your call.
+     */
     forceRefresh?: boolean;
 }
 interface GetMetricsBreakdownOptions {
@@ -834,6 +839,110 @@ interface GetEarningsCalendarOptions {
     /** Session filter. */
     time?: "before_open" | "after_close" | "during_market" | "unknown";
 }
+/**
+ * One KPI card on a reported quarter.
+ *
+ * `value` and `yoy` are display strings, already formatted (`"$109.4B"`,
+ * `"+16% YoY"`), not numbers to compute with. `yoy` is absent when the quarter
+ * carries no year-over-year comparison for that line, which is common on
+ * call highlights.
+ */
+interface EarningsKpiHighlight {
+    label: string;
+    value: string;
+    yoy?: string;
+}
+/** A citation backing a reported quarter. */
+interface EarningsSource {
+    title: string;
+    url: string;
+}
+/**
+ * One fiscal quarter of the earnings analysis report, from
+ * `client.earnings.getSummaries()`.
+ *
+ * The wire shape depends on the caller's tier, so branch on the envelope's
+ * `isPreview` rather than on field presence. `fiscalPeriod`, `reportDate`,
+ * `headline`, `hasTranscript`, `generatedAt` and `source` arrive on both tiers.
+ *
+ * PRO adds the bodies: `summaryMd`, the full `kpiHighlights`, `guidance`,
+ * `transcriptSummaryMd`, `transcriptHighlights`, `transcriptGeneratedAt` and
+ * `sources`.
+ *
+ * The FREE preview replaces those bodies with shape: up to two `kpiHighlights`
+ * cards (without `yoy`) plus `kpiHighlightCount`, the section titles in
+ * `summaryTopics` and `transcriptTopics`, and `hasGuidance` with
+ * `guidanceDirection` in place of the guidance language. It never carries a
+ * body, a KPI history, or a guidance figure.
+ *
+ * Absence is explicit: a quarter with no call summary sets `hasTranscript` to
+ * `false` rather than dropping the concept, so a client can say "no call
+ * summary yet" instead of rendering nothing.
+ */
+interface EarningsQuarter {
+    /** Display fiscal period, e.g. `"Q2 FY2026"`. */
+    fiscalPeriod: string;
+    /** Date the results were reported, ISO calendar day `"YYYY-MM-DD"`. */
+    reportDate: string;
+    /** One-line editorial summary of the quarter. */
+    headline: string;
+    /** True when a summary of the earnings call exists for this quarter. */
+    hasTranscript: boolean;
+    /** When the quarter summary was generated, epoch seconds. */
+    generatedAt: number;
+    /** Provenance of the quarter summary. */
+    source: "press_release" | "transcript";
+    /** PRO: markdown body summarizing the reported results. */
+    summaryMd?: string;
+    /** PRO carries the full set; a preview carries up to two cards without `yoy`. */
+    kpiHighlights?: EarningsKpiHighlight[];
+    /** PRO: forward-guidance language as reported. Absent when the quarter carries none. */
+    guidance?: string;
+    /** PRO: markdown body summarizing the call. Absent when `hasTranscript` is false. */
+    transcriptSummaryMd?: string;
+    /** PRO: call-specific highlights. Absent when there is no call summary. */
+    transcriptHighlights?: EarningsKpiHighlight[];
+    /** PRO: when the call summary was generated, epoch seconds. Can post-date `generatedAt`. */
+    transcriptGeneratedAt?: number;
+    /** PRO: citations backing the quarter. */
+    sources?: EarningsSource[];
+    /** Preview: how many KPI cards the full quarter carries. */
+    kpiHighlightCount?: number;
+    /** Preview: section titles of the summary, never body text. */
+    summaryTopics?: string[];
+    /** Preview: section titles of the call summary, never body text. */
+    transcriptTopics?: string[];
+    /** Preview: whether the quarter carries guidance at all. */
+    hasGuidance?: boolean;
+    /** Preview: the direction only, in place of the guidance language. */
+    guidanceDirection?: "RAISED" | "CUT" | "HELD" | "MIXED" | null;
+}
+/** One company that reported inside the recent window. */
+interface RecentEarningsEntry {
+    ticker: string;
+    /** Display fiscal period, e.g. `"Q2 FY2026"`. */
+    fiscalPeriod: string;
+    /** Date the results were reported, ISO calendar day `"YYYY-MM-DD"`. */
+    reportDate: string;
+    headline: string;
+    /** True when a summary of the earnings call exists for this quarter. */
+    hasTranscriptSummary: boolean;
+    /** Latest content written for this quarter, epoch seconds. */
+    generatedAt: number;
+}
+interface GetEarningsSummariesOptions {
+    /**
+     * Max quarters returned, 1 to 40. Omitted, the API applies its own default
+     * of 12. A FREE key receives one quarter whatever you pass.
+     */
+    limit?: number;
+}
+interface GetRecentEarningsOptions {
+    /** Look-back window in days, 1 to 31. Omitted, the API applies its own default of 7. */
+    days?: number;
+    /** Max rows returned, 1 to 100. Omitted, the API applies its own default of 50. */
+    limit?: number;
+}
 interface PreviewResponse<T> {
     isPreview: boolean;
     previewReason: "PRO_REQUIRED" | null;
@@ -1188,6 +1297,114 @@ interface TrackerSnapshotResponse {
     totalCount?: number;
     data: TrackerSnapshot;
 }
+/** Per-index discovery row returned by `client.indexes.list()`. */
+interface IndexListing {
+    indexId: string;
+    displayName: string;
+    /** One-sentence summary, suitable for a card subtitle. */
+    description: string;
+    /** Output scale: `"SENTIMENT"` (signed, -1 to +1) or `"PERCENT_0_100"`. Set axis bounds from this, not from the id. */
+    scale: string;
+    /** Access tier: `"free"` or `"pro"`. Every index is `"free"` today; read it rather than assuming. */
+    accessTier?: string;
+    /**
+     * Richest view of this index, which is NOT always the detail route. Market
+     * Mood points at `/api/v2/market-mood`, which carries a phase band, weekly
+     * change, per-signal breakdown and per-sector map that the shared envelope
+     * cannot hold. Every advertised `indexId` still resolves on
+     * {@link Indexes.get}, so a generic client can iterate the listing without
+     * special-casing anything.
+     */
+    canonicalUrl: string;
+}
+/** Discovery envelope returned by `client.indexes.list()`. */
+interface IndexListResponse {
+    indexes: IndexListing[];
+}
+/** One entity's row in a basket index's constituent breakdown. */
+interface IndexConstituent {
+    /** Ontology entity id, resolvable via the entities API. */
+    kbEntityId: string;
+    displayName: string;
+    /** The entity's role in this basket; the role is what carries the weight. */
+    role: string;
+    /** Relative weight on this date. `0` when `staleness` is `"OUT_OF_SEGMENT"`. */
+    weight: number;
+    /** The entity's own reading. */
+    value: number | null;
+    /** Mentions behind that reading in the lookback window. */
+    mentionsCount: number | null;
+    /**
+     * `"FRESH"` (mentioned inside the lookback), `"CARRIED_FORWARD"` (last known
+     * value standing in), `"EXCLUDED"` (no usable reading, renormalized out), or
+     * `"OUT_OF_SEGMENT"` (not in the basket on this date, reported only for
+     * transparency).
+     */
+    staleness: string;
+    /**
+     * Reserved. The API currently returns `null` here on every constituent, so do
+     * not build on it. To get the same number today, compute `weight * value`
+     * over the sum of `weight` across constituents whose `staleness` is not
+     * `"EXCLUDED"`.
+     */
+    contribution: number | null;
+    /** Detail page for the entity, or `null` when there is no resolvable target. */
+    link: string | null;
+}
+/**
+ * Latest reading for one index, returned by `client.indexes.get()`.
+ *
+ * Two archetypes share this envelope, and the difference is load-bearing. A
+ * **basket** index (`fed-sentiment`, `ai-sentiment`) weight-averages tracked
+ * entities, so `constituents`, `basketSize`, `coverage` and `totalMentions`
+ * describe how the headline was built. A **composite** index (`market-mood`) is
+ * built from signals rather than entities, so those four are `null` *by
+ * construction*, not because data is missing. Branch on them; never treat
+ * `null` there as an error.
+ */
+interface IndexSnapshot {
+    indexId: string;
+    displayName: string;
+    /** Date the reading covers, `"YYYY-MM-DD"`. Bucket start for weekly indexes. */
+    asOf: string;
+    /** The headline scalar, on `scale`. */
+    value: number | null;
+    scale: string;
+    /** Constituents that actually contributed. `null` on a composite index. */
+    coverage: number | null;
+    /** Constituents in the basket on this date. `null` on a composite index. */
+    basketSize: number | null;
+    /** Mentions behind the reading. `null` on a composite index. */
+    totalMentions: number | null;
+    /** How the value was computed, and what any `null` fields mean. */
+    methodologyNote: string;
+    /** Per-entity breakdown. `null` on a composite index. */
+    constituents: IndexConstituent[] | null;
+}
+/** One point on an index's scalar series. */
+interface IndexHistoryPoint {
+    /** `"YYYY-MM-DD"`. */
+    date: string;
+    value: number | null;
+}
+/**
+ * Historical series returned by `client.indexes.history()`.
+ *
+ * Point spacing follows the index, not the calendar: a weekly index emits one
+ * point per Monday-Sunday bucket, a daily index one per day, and Market Mood
+ * trading days only. Thin or low-coverage buckets are withheld rather than
+ * published, so `history` can be shorter than `days` and can contain gaps. Plot
+ * against `date`; never assume a fixed interval, and never read a missing date
+ * as zero.
+ */
+interface IndexHistoryResponse {
+    indexId: string;
+    displayName: string;
+    scale: string;
+    /** The window you requested, echoed back. */
+    days: number;
+    history: IndexHistoryPoint[];
+}
 
 interface AnalystConsensus {
     ticker: string;
@@ -1309,6 +1526,58 @@ declare class Documents {
     getStoriesByTicker(ticker: string, options?: GetStoriesByTickerOptions): Promise<Story[]>;
 }
 
+/**
+ * Earnings: what a company actually reported, after the fact.
+ *
+ * A quarter's results arrive as a press release, a filing, and a call, none of
+ * which is a data structure. {@link getSummaries} is the assembled version, one
+ * object per fiscal quarter, and {@link getRecent} is the cross-ticker view of
+ * who reported lately. Pair them to drive a post-earnings sweep: list the
+ * window, then pull each ticker's analysis report.
+ *
+ * The forward-looking half of the family lives on `client.calendar.getEarnings()`,
+ * which covers scheduled dates and consensus EPS rather than results.
+ *
+ * @see EarningsQuarter
+ */
+declare class Earnings {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * Per-quarter earnings analysis report for one ticker, newest first.
+     *
+     * Each quarter carries the editorial headline, the KPI cards that matter for
+     * that company with year-over-year deltas, the guidance language as
+     * management phrased it, and a summary of the earnings call.
+     *
+     * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
+     * FREE key receives the latest quarter shaped rather than truncated, plus
+     * `totalCount`. {@link EarningsQuarter} documents which fields each tier
+     * carries.
+     *
+     * A quarter typically appears within 48 hours of the company reporting, and
+     * the call summary can arrive after the press-release content for the same
+     * quarter, so read `generatedAt` and `transcriptGeneratedAt` rather than
+     * assuming a fixed lag. A ticker with no stored quarter answers with an empty
+     * `data` array, not a 404.
+     *
+     * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
+     */
+    getSummaries(ticker: string, options?: GetEarningsSummariesOptions): Promise<PreviewResponse<EarningsQuarter[]>>;
+    /**
+     * Which covered companies reported on or after `today - days`, newest first.
+     *
+     * Every API key receives the full window it asks for, so `isPreview` is
+     * always `false` here. The window is bounded by `reportDate`, so a quarter
+     * reported inside it appears even when its call summary lands later, and an
+     * empty `data` array means nobody in the covered set reported in that window.
+     *
+     * This is the backward-looking feed; `client.calendar.getEarnings()` is the
+     * forward-looking one.
+     */
+    getRecent(options?: GetRecentEarningsOptions): Promise<PreviewResponse<RecentEarningsEntry[]>>;
+}
+
 declare class EntityMetrics {
     private client;
     constructor(client: APIClient);
@@ -1502,7 +1771,7 @@ declare class Insider {
     /**
      * Get market-wide insider activity: top buys and sells aggregated by ticker.
      *
-     * PRO-gated. Free/unauthenticated users receive a preview (top 5 per direction)
+     * PRO-gated. Free-tier users receive a preview (top 5 per direction)
      * with `isPreview: true` in the response.
      */
     getActivity(options?: GetInsiderOptions): Promise<PreviewResponse<InsiderActivityResponse>>;
@@ -1526,7 +1795,7 @@ declare class Politicians {
     /**
      * Get recent congressional STOCK Act trading activity across all politicians.
      *
-     * PRO-gated. Free/unauthenticated users receive a preview (top 5 trades)
+     * PRO-gated. Free-tier users receive a preview (top 5 trades)
      * with `isPreview: true` in the response.
      *
      * The feed is longer than one response: a default 90-day window is routinely well over a
@@ -1621,7 +1890,7 @@ declare class Insights {
     user(options?: GetUserInsightsOptions): Promise<PreviewResponse<Insight[]>>;
     /**
      * Get available insight types for a specific stock.
-     * No authentication required.
+     * API key required.
      *
      * Returns an array of insight type strings (e.g., `["sentiment_shift", "options_activity"]`).
      */
@@ -1755,7 +2024,14 @@ declare class Stocks {
     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. */
+    /**
+     * Get AI-generated stock analysis report. Requires PRO tier.
+     *
+     * `depth: "deep"` returns the full curated report and consumes one report view on
+     * metered tiers; the default `"basic"` returns the one-paragraph summary.
+     *
+     * The deprecated `forceRefresh` option is accepted and discarded, not forwarded.
+     */
     getAISummary(ticker: string, options?: GetAISummaryOptions): Promise<AISummary>;
     /** Get sentiment/mention metrics breakdown by entity. */
     getMetricsBreakdown(ticker: string, metricType: string, options?: GetMetricsBreakdownOptions): Promise<MetricsBreakdown>;
@@ -1823,6 +2099,54 @@ declare class Stocks {
     getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
 }
 
+/**
+ * Indexes: composite scalars tracked over time, each blending its own inputs
+ * into one number on a stated scale. Every index answers on the same envelope,
+ * so you write one renderer and get every current and future SentiSense index.
+ *
+ * Two archetypes share that envelope. A **basket** index weight-averages
+ * tracked entities and fills `constituents` / `basketSize` / `coverage` /
+ * `totalMentions`; a **composite** index is built from signals instead and
+ * returns `null` for all four by construction. See {@link IndexSnapshot}.
+ *
+ * @see IndexSnapshot
+ */
+declare class Indexes {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * List every index the platform publishes: id, display name, one-line
+     * description, the scale it lives on, its access tier, and where its richest
+     * view lives.
+     *
+     * Iterate this rather than hardcoding ids. Every `indexId` it advertises
+     * resolves on {@link get} and {@link history}.
+     */
+    list(): Promise<IndexListResponse>;
+    /**
+     * Latest reading for one index.
+     *
+     * Check `constituents` for `null` before iterating: it is `null` on a
+     * composite index like `market-mood`, which has no constituents by
+     * construction. For Market Mood this is the narrowed view; the phase band,
+     * weekly change, per-signal breakdown and per-sector map live on
+     * `client.marketMood.get()`, and both report the same headline number.
+     *
+     * @param indexId slug from {@link list}, e.g. `"fed-sentiment"`.
+     */
+    get(indexId: string): Promise<IndexSnapshot>;
+    /**
+     * Historical scalar series for one index, for charting.
+     *
+     * Thin or low-coverage buckets are withheld, so the series can be shorter
+     * than `days` and can contain gaps. Plot against each point's `date`.
+     *
+     * @param indexId slug from {@link list}.
+     * @param days days of history to return. Defaults to the API's own 180.
+     */
+    history(indexId: string, days?: number): Promise<IndexHistoryResponse>;
+}
+
 /**
  * Trackers: observational data products published as a standardized
  * `TrackerSnapshot` envelope. Every tracker (institution rankings,
@@ -1877,8 +2201,10 @@ declare class SentiSense implements APIClient {
     readonly marketMood: MarketMoodResource;
     readonly marketSummary: MarketSummaryResource;
     readonly kb: KB;
+    readonly indexes: Indexes;
     readonly trackers: Trackers;
     readonly calendar: Calendar;
+    readonly earnings: Earnings;
     constructor(options?: SentiSenseOptions);
     /** @internal */
     get<T = unknown>(path: string, params?: object): Promise<T>;
@@ -1924,6 +2250,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.34.0";
+declare const VERSION = "0.36.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, 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 GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, 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 EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, 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 GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, 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 PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, 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 };