sentisense 0.20.0 → 0.23.0

package/dist/index.d.mts

@@ -196,7 +196,9 @@ interface StoryCluster {
 }
 interface Story {
     cluster: StoryCluster;
+    /** Human-formatted labels for display, e.g. `"Apple Inc (AAPL)"`. For display only; do not parse symbols out of these. Use `tickers` programmatically. */
     displayTickers: string[];
+    /** Bare ticker symbols for programmatic use, e.g. `"AAPL"`. Use these to filter or look up stocks. */
     tickers: string[];
     primaryEntityNames: string[];
     impactScore: number;
@@ -440,9 +442,53 @@ interface GetPoliticiansOptions {
     lookbackDays?: number;
 }
 /** Generic preview wrapper used by PRO-gated endpoints. */
+interface EarningsEvent {
+    ticker: string;
+    companyName: string;
+    /** Report date, ISO calendar day "YYYY-MM-DD". */
+    earningsDate: string;
+    /** Session timing. */
+    earningsTime: "before_open" | "after_close" | "during_market" | "unknown";
+    /** Fiscal period label (e.g. "Q2 2026"), nullable. */
+    fiscalQuarter: string | null;
+    /** Whether the company has confirmed the date (vs. estimated/projected). */
+    confirmed: boolean;
+    /** Consensus EPS estimate, nullable. */
+    estimatedEps: number | null;
+}
+interface CalendarMeta {
+    /** When the snapshot was generated, epoch seconds. */
+    generatedAt: number | null;
+    /** First day covered, ISO "YYYY-MM-DD". */
+    windowStart: string | null;
+    /** Last day covered, ISO "YYYY-MM-DD". */
+    windowEnd: string | null;
+    /** Number of events in this response. */
+    count: number;
+    /** Always "sentisense". */
+    source: string;
+}
+interface EarningsCalendarResponse {
+    earnings: EarningsEvent[];
+    metadata: CalendarMeta;
+}
+interface GetEarningsCalendarOptions {
+    /** Filter to a single ticker. */
+    ticker?: string;
+    /** Shorthand window: "this" (current Mon-Sun) or "next". */
+    week?: "this" | "next";
+    /** Inclusive lower date bound, ISO "YYYY-MM-DD". Overrides `week`. */
+    from?: string;
+    /** Inclusive upper date bound, ISO "YYYY-MM-DD". */
+    to?: string;
+    /** When true, only company-confirmed dates. */
+    confirmed?: boolean;
+    /** Session filter. */
+    time?: "before_open" | "after_close" | "during_market" | "unknown";
+}
 interface PreviewResponse<T> {
     isPreview: boolean;
-    previewReason: "LOGIN_REQUIRED" | "PRO_REQUIRED" | null;
+    previewReason: "PRO_REQUIRED" | null;
     /**
      * Number of items in the full PRO dataset, before preview truncation.
      * Present on preview (free-tier) list responses so callers can show
@@ -553,7 +599,7 @@ interface LockedInsight {
 /** Preview response returned to free/unauthenticated users on insights endpoints. */
 interface InsightPreviewResponse {
     isPreview: true;
-    previewReason: "LOGIN_REQUIRED" | "PRO_REQUIRED";
+    previewReason: "PRO_REQUIRED";
     /** Full insight objects for the top N results. */
     insights: Insight[];
     /** Metadata-only entries for the remaining signals. */
@@ -631,6 +677,161 @@ interface KBEntity {
     name: string;
     [key: string]: unknown;
 }
+/** Per-tracker discovery row returned by `client.trackers.list()`. */
+interface TrackerListing {
+    trackerId: string;
+    displayName: string;
+    /** Coarse grouping for hub filtering: `"institutional"`, `"epidemiology"`, etc. */
+    category: string;
+    /** Sentence-long subtitle for hub cards + API discovery. */
+    description: string;
+    /** Renderer hint: `"table"`, `"choropleth"`, `"timeseries"`, `"heatmap"`. */
+    viewType: string;
+    /** Access tier: `"free"` or `"pro"`. A `pro` tracker truncates to a free preview for FREE callers; a `free` tracker returns the full snapshot to everyone. */
+    accessTier?: string;
+    /** Fragment on `/methodology` explaining the tracker (e.g. `"#institution-rankings"`). */
+    methodologyAnchor: string;
+    /** Expected snapshot refresh cadence, in seconds. Informational. */
+    refreshIntervalSeconds: number;
+    /** Canonical detail URL (e.g. `"/api/v1/trackers/institution-concentration"`). */
+    canonicalUrl: string;
+}
+/** Discovery envelope returned by `client.trackers.list()`. */
+interface TrackerListResponse {
+    trackers: TrackerListing[];
+}
+/** One row of a `viewType: "table"` tracker — a ranked leaderboard cell. */
+interface TrackerTableRow {
+    /** 1-based rank on the sort the tracker is built for; may be null. */
+    rank: number | null;
+    /** Stable identifier for the entity (CIK, ticker, etc.). */
+    rowId: string;
+    /** Display name. */
+    name: string;
+    /** Optional category tag (e.g. `"HEDGE_FUND"`). */
+    category: string | null;
+    /** Optional canonical link to the entity behind the row (e.g. `"/institutions/Berkshire-Hathaway"`). */
+    url: string | null;
+    /** Per-cell metric values; each carries its own label and unit. */
+    metrics: TrackerMetricValue[];
+}
+/**
+ * A labeled quantitative reading attached to a row, geo region, or
+ * time-series point. `value` is `unknown` because it can be a number or a
+ * status string ("Severe", "Resolved") without forcing a separate type.
+ */
+interface TrackerMetricValue {
+    label: string;
+    value: unknown;
+    unit?: string | null;
+    trend?: string | null;
+    /** Primary-source URL for this cell's value, when the tracker is citation-backed. */
+    sourceUrl?: string | null;
+    /** Short quote from the primary source supporting this cell's value. */
+    sourceQuote?: string | null;
+    /** The period this cell refers to (e.g. "2025", "2026-YTD"), when it varies per row. */
+    periodLabel?: string | null;
+}
+/** Top-of-page stat tile. A tracker may have 0–N headline metrics. */
+interface TrackerHeadlineMetric {
+    label: string;
+    value: unknown;
+    unit?: string | null;
+    asOf?: string | null;
+    methodologyNote?: string | null;
+    trend?: string | null;
+}
+/** One geographic row for a `viewType: "choropleth"` tracker. */
+interface TrackerGeoEntry {
+    geoId?: string | null;
+    /** Two-letter ISO country code, when applicable. */
+    isoCode?: string | null;
+    /** FIPS code with leading zeros preserved (e.g. `"06"`), when applicable. */
+    fips?: string | null;
+    name: string;
+    metrics: TrackerMetricValue[];
+    lastEvent?: {
+        date?: string;
+        url?: string;
+        summary?: string;
+    } | null;
+}
+/** One point on a time series for a `viewType: "timeseries"` tracker. */
+interface TrackerTimeSeriesPoint {
+    /** Free-form date string; trackers pick the granularity. */
+    date: string;
+    label?: string | null;
+    values: TrackerMetricValue[];
+}
+/** A notable event (outbreak, disruption, enforcement action). */
+interface TrackerEvent {
+    id: string;
+    title: string;
+    status: string;
+    asOf?: string | null;
+    severity?: string | null;
+    geoIds?: string[] | null;
+    metrics?: TrackerMetricValue[] | null;
+    summary?: string | null;
+    sources?: TrackerSourceRef[] | null;
+}
+/** Recent news/alert signal. `tier`: 1=authoritative, 2=secondary, 3=mainstream press. */
+interface TrackerSignal {
+    tier?: number | null;
+    source: string;
+    publishedAt: string;
+    url: string;
+    summary?: string | null;
+}
+/** Citation reference. */
+interface TrackerSourceRef {
+    name: string;
+    url: string;
+    date?: string | null;
+}
+/**
+ * Standardized envelope every tracker returns. Exactly one of the payload
+ * fields (`rows`, `geo`, `timeSeries`) is populated based on `viewType`;
+ * `headline`, `events`, `signals`, `sources`, and `narrative` are
+ * companion fields that may appear on any tracker.
+ */
+interface TrackerSnapshot {
+    trackerId: string;
+    /** Optional sub-scope (e.g. `"us"` for hantavirus). Null for unscoped trackers. */
+    scope?: string | null;
+    schemaVersion: string;
+    displayName: string;
+    description?: string | null;
+    /** Renderer hint: `"table"`, `"choropleth"`, `"timeseries"`, `"heatmap"`. */
+    viewType: string;
+    /** Free-form "data as of" label (typically a quarter, date, or week). */
+    asOf?: string | null;
+    generatedAt?: string | null;
+    generatedBy?: string | null;
+    /** Optional Markdown narrative. */
+    narrative?: string | null;
+    headline?: TrackerHeadlineMetric[] | null;
+    geo?: TrackerGeoEntry[] | null;
+    timeSeries?: TrackerTimeSeriesPoint[] | null;
+    /** Populated when `viewType === "table"`. */
+    rows?: TrackerTableRow[] | null;
+    events?: TrackerEvent[] | null;
+    signals?: TrackerSignal[] | null;
+    sources?: TrackerSourceRef[] | null;
+}
+/**
+ * Wire response from `client.trackers.get()`. The snapshot is at `.data`;
+ * for FREE callers on a PRO-gated tracker, `isPreview` is `true`, `data`
+ * carries a truncated row set, and `totalCount` reports the full set size.
+ */
+interface TrackerSnapshotResponse {
+    isPreview: boolean;
+    /** `"PRO_REQUIRED"` for FREE callers on a gated tracker; otherwise `null`. */
+    previewReason: "PRO_REQUIRED" | null;
+    /** Full row count before truncation. Only set on preview responses. */
+    totalCount?: number;
+    data: TrackerSnapshot;
+}
 
 interface AnalystConsensus {
     ticker: string;
@@ -717,6 +918,20 @@ declare class Analyst {
     marketActivity(options?: GetAnalystMarketActivityOptions): Promise<PreviewResponse<AnalystAction[]>>;
 }
 
+declare class Calendar {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * Upcoming company earnings, sorted by date.
+     *
+     * Key-required. A FREE key returns the current week (`isPreview: true`); a PRO
+     * key returns the full forward window (about 30 days). Field richness is
+     * identical across tiers: the gate is how far ahead you can see, not which
+     * columns you get. On a preview, `totalCount` is the full-window event count.
+     */
+    getEarnings(options?: GetEarningsCalendarOptions): Promise<PreviewResponse<EarningsCalendarResponse>>;
+}
+
 declare class Documents {
     private client;
     constructor(client: APIClient);
@@ -1159,7 +1374,13 @@ declare class Stocks {
     getAISummary(ticker: string, options?: GetAISummaryOptions): Promise<AISummary>;
     /** Get sentiment/mention metrics breakdown by entity. */
     getMetricsBreakdown(ticker: string, metricType: string, options?: GetMetricsBreakdownOptions): Promise<MetricsBreakdown>;
-    /** Get historical OHLCV chart data. */
+    /**
+     * Get historical OHLCV chart data.
+     *
+     * The API returns a bare array of points; this normalizes it to
+     * `{ ticker, timeframe, data }`. `timeframe` echoes the requested value
+     * (defaulting to "1M", matching the server default when omitted).
+     */
     getChart(ticker: string, options?: GetChartOptions): Promise<ChartData>;
     /** Get current market open/closed/pre-market/after-hours status. */
     getMarketStatus(): Promise<MarketStatus>;
@@ -1208,6 +1429,38 @@ declare class Stocks {
     getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
 }
 
+/**
+ * Trackers — observational data products published as a standardized
+ * `TrackerSnapshot` envelope. Every tracker (institution rankings,
+ * hedge-fund reported returns, social trackers, surveillance dashboards)
+ * returns the same shape — consumers write one renderer per `viewType` and
+ * get every current and future SentiSense tracker for free.
+ *
+ * @see TrackerSnapshot
+ */
+declare class Trackers {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * List every publicly-visible tracker — id, display name, category,
+     * one-line description, and the methodology anchor to link out to.
+     */
+    list(): Promise<TrackerListResponse>;
+    /**
+     * Standardized snapshot envelope for one tracker.
+     *
+     * Returns the envelope as-is: `{ isPreview, previewReason, totalCount?, data }`.
+     * When `data.viewType === "table"` the rows live at `data.rows[]`; when
+     * `"choropleth"` they live at `data.geo[]`; etc. Dispatch on `viewType`
+     * in your renderer.
+     *
+     * @param trackerId — slug from {@link list}, e.g. `"institution-concentration"`.
+     * @param params — provider-specific query params (e.g. `{ scope: "us" }` for
+     *   geographically-scoped trackers like hantavirus). Unknown keys are ignored.
+     */
+    get(trackerId: string, params?: Record<string, string | number | boolean>): Promise<TrackerSnapshotResponse>;
+}
+
 /** @internal HTTP interface exposed to resource classes. */
 interface APIClient {
     get<T = unknown>(path: string, params?: object): Promise<T>;
@@ -1230,6 +1483,8 @@ declare class SentiSense implements APIClient {
     readonly marketMood: MarketMoodResource;
     readonly marketSummary: MarketSummaryResource;
     readonly kb: KB;
+    readonly trackers: Trackers;
+    readonly calendar: Calendar;
     constructor(options?: SentiSenseOptions);
     /** @internal */
     get<T = unknown>(path: string, params?: object): Promise<T>;
@@ -1258,6 +1513,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.20.0";
+declare const VERSION = "0.23.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, AuthenticationError, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSource, 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 GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, 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 InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, 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 SentimentData, 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, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, 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 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 InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, 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 SentimentData, 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 TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };

package/dist/index.d.ts

@@ -196,7 +196,9 @@ interface StoryCluster {
 }
 interface Story {
     cluster: StoryCluster;
+    /** Human-formatted labels for display, e.g. `"Apple Inc (AAPL)"`. For display only; do not parse symbols out of these. Use `tickers` programmatically. */
     displayTickers: string[];
+    /** Bare ticker symbols for programmatic use, e.g. `"AAPL"`. Use these to filter or look up stocks. */
     tickers: string[];
     primaryEntityNames: string[];
     impactScore: number;
@@ -440,9 +442,53 @@ interface GetPoliticiansOptions {
     lookbackDays?: number;
 }
 /** Generic preview wrapper used by PRO-gated endpoints. */
+interface EarningsEvent {
+    ticker: string;
+    companyName: string;
+    /** Report date, ISO calendar day "YYYY-MM-DD". */
+    earningsDate: string;
+    /** Session timing. */
+    earningsTime: "before_open" | "after_close" | "during_market" | "unknown";
+    /** Fiscal period label (e.g. "Q2 2026"), nullable. */
+    fiscalQuarter: string | null;
+    /** Whether the company has confirmed the date (vs. estimated/projected). */
+    confirmed: boolean;
+    /** Consensus EPS estimate, nullable. */
+    estimatedEps: number | null;
+}
+interface CalendarMeta {
+    /** When the snapshot was generated, epoch seconds. */
+    generatedAt: number | null;
+    /** First day covered, ISO "YYYY-MM-DD". */
+    windowStart: string | null;
+    /** Last day covered, ISO "YYYY-MM-DD". */
+    windowEnd: string | null;
+    /** Number of events in this response. */
+    count: number;
+    /** Always "sentisense". */
+    source: string;
+}
+interface EarningsCalendarResponse {
+    earnings: EarningsEvent[];
+    metadata: CalendarMeta;
+}
+interface GetEarningsCalendarOptions {
+    /** Filter to a single ticker. */
+    ticker?: string;
+    /** Shorthand window: "this" (current Mon-Sun) or "next". */
+    week?: "this" | "next";
+    /** Inclusive lower date bound, ISO "YYYY-MM-DD". Overrides `week`. */
+    from?: string;
+    /** Inclusive upper date bound, ISO "YYYY-MM-DD". */
+    to?: string;
+    /** When true, only company-confirmed dates. */
+    confirmed?: boolean;
+    /** Session filter. */
+    time?: "before_open" | "after_close" | "during_market" | "unknown";
+}
 interface PreviewResponse<T> {
     isPreview: boolean;
-    previewReason: "LOGIN_REQUIRED" | "PRO_REQUIRED" | null;
+    previewReason: "PRO_REQUIRED" | null;
     /**
      * Number of items in the full PRO dataset, before preview truncation.
      * Present on preview (free-tier) list responses so callers can show
@@ -553,7 +599,7 @@ interface LockedInsight {
 /** Preview response returned to free/unauthenticated users on insights endpoints. */
 interface InsightPreviewResponse {
     isPreview: true;
-    previewReason: "LOGIN_REQUIRED" | "PRO_REQUIRED";
+    previewReason: "PRO_REQUIRED";
     /** Full insight objects for the top N results. */
     insights: Insight[];
     /** Metadata-only entries for the remaining signals. */
@@ -631,6 +677,161 @@ interface KBEntity {
     name: string;
     [key: string]: unknown;
 }
+/** Per-tracker discovery row returned by `client.trackers.list()`. */
+interface TrackerListing {
+    trackerId: string;
+    displayName: string;
+    /** Coarse grouping for hub filtering: `"institutional"`, `"epidemiology"`, etc. */
+    category: string;
+    /** Sentence-long subtitle for hub cards + API discovery. */
+    description: string;
+    /** Renderer hint: `"table"`, `"choropleth"`, `"timeseries"`, `"heatmap"`. */
+    viewType: string;
+    /** Access tier: `"free"` or `"pro"`. A `pro` tracker truncates to a free preview for FREE callers; a `free` tracker returns the full snapshot to everyone. */
+    accessTier?: string;
+    /** Fragment on `/methodology` explaining the tracker (e.g. `"#institution-rankings"`). */
+    methodologyAnchor: string;
+    /** Expected snapshot refresh cadence, in seconds. Informational. */
+    refreshIntervalSeconds: number;
+    /** Canonical detail URL (e.g. `"/api/v1/trackers/institution-concentration"`). */
+    canonicalUrl: string;
+}
+/** Discovery envelope returned by `client.trackers.list()`. */
+interface TrackerListResponse {
+    trackers: TrackerListing[];
+}
+/** One row of a `viewType: "table"` tracker — a ranked leaderboard cell. */
+interface TrackerTableRow {
+    /** 1-based rank on the sort the tracker is built for; may be null. */
+    rank: number | null;
+    /** Stable identifier for the entity (CIK, ticker, etc.). */
+    rowId: string;
+    /** Display name. */
+    name: string;
+    /** Optional category tag (e.g. `"HEDGE_FUND"`). */
+    category: string | null;
+    /** Optional canonical link to the entity behind the row (e.g. `"/institutions/Berkshire-Hathaway"`). */
+    url: string | null;
+    /** Per-cell metric values; each carries its own label and unit. */
+    metrics: TrackerMetricValue[];
+}
+/**
+ * A labeled quantitative reading attached to a row, geo region, or
+ * time-series point. `value` is `unknown` because it can be a number or a
+ * status string ("Severe", "Resolved") without forcing a separate type.
+ */
+interface TrackerMetricValue {
+    label: string;
+    value: unknown;
+    unit?: string | null;
+    trend?: string | null;
+    /** Primary-source URL for this cell's value, when the tracker is citation-backed. */
+    sourceUrl?: string | null;
+    /** Short quote from the primary source supporting this cell's value. */
+    sourceQuote?: string | null;
+    /** The period this cell refers to (e.g. "2025", "2026-YTD"), when it varies per row. */
+    periodLabel?: string | null;
+}
+/** Top-of-page stat tile. A tracker may have 0–N headline metrics. */
+interface TrackerHeadlineMetric {
+    label: string;
+    value: unknown;
+    unit?: string | null;
+    asOf?: string | null;
+    methodologyNote?: string | null;
+    trend?: string | null;
+}
+/** One geographic row for a `viewType: "choropleth"` tracker. */
+interface TrackerGeoEntry {
+    geoId?: string | null;
+    /** Two-letter ISO country code, when applicable. */
+    isoCode?: string | null;
+    /** FIPS code with leading zeros preserved (e.g. `"06"`), when applicable. */
+    fips?: string | null;
+    name: string;
+    metrics: TrackerMetricValue[];
+    lastEvent?: {
+        date?: string;
+        url?: string;
+        summary?: string;
+    } | null;
+}
+/** One point on a time series for a `viewType: "timeseries"` tracker. */
+interface TrackerTimeSeriesPoint {
+    /** Free-form date string; trackers pick the granularity. */
+    date: string;
+    label?: string | null;
+    values: TrackerMetricValue[];
+}
+/** A notable event (outbreak, disruption, enforcement action). */
+interface TrackerEvent {
+    id: string;
+    title: string;
+    status: string;
+    asOf?: string | null;
+    severity?: string | null;
+    geoIds?: string[] | null;
+    metrics?: TrackerMetricValue[] | null;
+    summary?: string | null;
+    sources?: TrackerSourceRef[] | null;
+}
+/** Recent news/alert signal. `tier`: 1=authoritative, 2=secondary, 3=mainstream press. */
+interface TrackerSignal {
+    tier?: number | null;
+    source: string;
+    publishedAt: string;
+    url: string;
+    summary?: string | null;
+}
+/** Citation reference. */
+interface TrackerSourceRef {
+    name: string;
+    url: string;
+    date?: string | null;
+}
+/**
+ * Standardized envelope every tracker returns. Exactly one of the payload
+ * fields (`rows`, `geo`, `timeSeries`) is populated based on `viewType`;
+ * `headline`, `events`, `signals`, `sources`, and `narrative` are
+ * companion fields that may appear on any tracker.
+ */
+interface TrackerSnapshot {
+    trackerId: string;
+    /** Optional sub-scope (e.g. `"us"` for hantavirus). Null for unscoped trackers. */
+    scope?: string | null;
+    schemaVersion: string;
+    displayName: string;
+    description?: string | null;
+    /** Renderer hint: `"table"`, `"choropleth"`, `"timeseries"`, `"heatmap"`. */
+    viewType: string;
+    /** Free-form "data as of" label (typically a quarter, date, or week). */
+    asOf?: string | null;
+    generatedAt?: string | null;
+    generatedBy?: string | null;
+    /** Optional Markdown narrative. */
+    narrative?: string | null;
+    headline?: TrackerHeadlineMetric[] | null;
+    geo?: TrackerGeoEntry[] | null;
+    timeSeries?: TrackerTimeSeriesPoint[] | null;
+    /** Populated when `viewType === "table"`. */
+    rows?: TrackerTableRow[] | null;
+    events?: TrackerEvent[] | null;
+    signals?: TrackerSignal[] | null;
+    sources?: TrackerSourceRef[] | null;
+}
+/**
+ * Wire response from `client.trackers.get()`. The snapshot is at `.data`;
+ * for FREE callers on a PRO-gated tracker, `isPreview` is `true`, `data`
+ * carries a truncated row set, and `totalCount` reports the full set size.
+ */
+interface TrackerSnapshotResponse {
+    isPreview: boolean;
+    /** `"PRO_REQUIRED"` for FREE callers on a gated tracker; otherwise `null`. */
+    previewReason: "PRO_REQUIRED" | null;
+    /** Full row count before truncation. Only set on preview responses. */
+    totalCount?: number;
+    data: TrackerSnapshot;
+}
 
 interface AnalystConsensus {
     ticker: string;
@@ -717,6 +918,20 @@ declare class Analyst {
     marketActivity(options?: GetAnalystMarketActivityOptions): Promise<PreviewResponse<AnalystAction[]>>;
 }
 
+declare class Calendar {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * Upcoming company earnings, sorted by date.
+     *
+     * Key-required. A FREE key returns the current week (`isPreview: true`); a PRO
+     * key returns the full forward window (about 30 days). Field richness is
+     * identical across tiers: the gate is how far ahead you can see, not which
+     * columns you get. On a preview, `totalCount` is the full-window event count.
+     */
+    getEarnings(options?: GetEarningsCalendarOptions): Promise<PreviewResponse<EarningsCalendarResponse>>;
+}
+
 declare class Documents {
     private client;
     constructor(client: APIClient);
@@ -1159,7 +1374,13 @@ declare class Stocks {
     getAISummary(ticker: string, options?: GetAISummaryOptions): Promise<AISummary>;
     /** Get sentiment/mention metrics breakdown by entity. */
     getMetricsBreakdown(ticker: string, metricType: string, options?: GetMetricsBreakdownOptions): Promise<MetricsBreakdown>;
-    /** Get historical OHLCV chart data. */
+    /**
+     * Get historical OHLCV chart data.
+     *
+     * The API returns a bare array of points; this normalizes it to
+     * `{ ticker, timeframe, data }`. `timeframe` echoes the requested value
+     * (defaulting to "1M", matching the server default when omitted).
+     */
     getChart(ticker: string, options?: GetChartOptions): Promise<ChartData>;
     /** Get current market open/closed/pre-market/after-hours status. */
     getMarketStatus(): Promise<MarketStatus>;
@@ -1208,6 +1429,38 @@ declare class Stocks {
     getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
 }
 
+/**
+ * Trackers — observational data products published as a standardized
+ * `TrackerSnapshot` envelope. Every tracker (institution rankings,
+ * hedge-fund reported returns, social trackers, surveillance dashboards)
+ * returns the same shape — consumers write one renderer per `viewType` and
+ * get every current and future SentiSense tracker for free.
+ *
+ * @see TrackerSnapshot
+ */
+declare class Trackers {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * List every publicly-visible tracker — id, display name, category,
+     * one-line description, and the methodology anchor to link out to.
+     */
+    list(): Promise<TrackerListResponse>;
+    /**
+     * Standardized snapshot envelope for one tracker.
+     *
+     * Returns the envelope as-is: `{ isPreview, previewReason, totalCount?, data }`.
+     * When `data.viewType === "table"` the rows live at `data.rows[]`; when
+     * `"choropleth"` they live at `data.geo[]`; etc. Dispatch on `viewType`
+     * in your renderer.
+     *
+     * @param trackerId — slug from {@link list}, e.g. `"institution-concentration"`.
+     * @param params — provider-specific query params (e.g. `{ scope: "us" }` for
+     *   geographically-scoped trackers like hantavirus). Unknown keys are ignored.
+     */
+    get(trackerId: string, params?: Record<string, string | number | boolean>): Promise<TrackerSnapshotResponse>;
+}
+
 /** @internal HTTP interface exposed to resource classes. */
 interface APIClient {
     get<T = unknown>(path: string, params?: object): Promise<T>;
@@ -1230,6 +1483,8 @@ declare class SentiSense implements APIClient {
     readonly marketMood: MarketMoodResource;
     readonly marketSummary: MarketSummaryResource;
     readonly kb: KB;
+    readonly trackers: Trackers;
+    readonly calendar: Calendar;
     constructor(options?: SentiSenseOptions);
     /** @internal */
     get<T = unknown>(path: string, params?: object): Promise<T>;
@@ -1258,6 +1513,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.20.0";
+declare const VERSION = "0.23.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, AuthenticationError, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, type DocumentSource, 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 GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, 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 InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, 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 SentimentData, 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, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, type Document, 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 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 InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MentionCount, type MentionData, 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 SentimentData, 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 TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };