sentisense 0.9.1 → 0.14.0

package/dist/index.d.ts

@@ -6,16 +6,31 @@ interface SentiSenseOptions {
 }
 interface StockPrice {
     ticker: string;
+    /** Regular-session price. During RTH: live last trade. Otherwise: most recent RTH close. */
     price: number;
     change: number;
     changePercent: number;
     previousClose: number;
     /** Unix timestamp in milliseconds of the price quote. */
     timestamp: number;
+    /** Extended-hours view (pre-market or after-hours). Null/absent during RTH, overnight, and weekends. */
+    extendedHours?: ExtendedHoursInfo | null;
+}
+/**
+ * Extended-hours session view embedded in price / quote responses when the snapshot sees
+ * pre-market (04:00–09:30 ET) or after-hours (16:00–20:00 ET) activity. `change` and
+ * `changePercent` are computed by the server vs the regular-session `currentPrice`.
+ */
+interface ExtendedHoursInfo {
+    session: "pre" | "post";
+    price: number;
+    change: number;
+    changePercent: number;
 }
 /** Aggregate quote snapshot from GET /api/v1/stocks/{ticker}/quote. */
 interface StockQuote {
     ticker: string;
+    /** Regular-session price. During RTH: live last trade. Otherwise: most recent RTH close. */
     currentPrice: number | null;
     change: number | null;
     changePercent: number | null;
@@ -31,7 +46,8 @@ interface StockQuote {
     epsTTM: number | null;
     dividendYield: number | null;
     timestamp: number | null;
-    extendedHours: boolean | null;
+    /** Extended-hours view (pre-market or after-hours). Null/absent during RTH, overnight, and weekends. */
+    extendedHours?: ExtendedHoursInfo | null;
 }
 interface StockDetail {
     ticker: string;
@@ -67,12 +83,20 @@ interface StockEntity {
     [key: string]: unknown;
 }
 interface ChartDataPoint {
+    /** Unix timestamp in milliseconds. */
+    timestamp?: number;
     date: string;
     open: number;
     high: number;
     low: number;
     close: number;
     volume: number;
+    /**
+     * US-equity market session: "pre" (04:00–09:30 ET), "regular" (09:30–16:00 ET),
+     * or "post" (16:00–20:00 ET). Populated for intraday timeframes (1D / 5D / 1W / 1M);
+     * `null` for daily / weekly bars (3M and longer) that span whole sessions.
+     */
+    session?: "pre" | "regular" | "post" | null;
 }
 interface ChartData {
     ticker: string;
@@ -112,7 +136,7 @@ interface AISummary {
     [key: string]: unknown;
 }
 interface GetChartOptions {
-    timeframe?: "1M" | "3M" | "6M" | "1Y";
+    timeframe?: "1D" | "5D" | "1W" | "1M" | "3M" | "6M" | "1Y" | "ALL";
 }
 interface GetImagesOptions {
     forced?: boolean;
@@ -485,12 +509,157 @@ interface GetInsightsOptions {
     /** Filter by insight type (e.g., `"insider_buy_signal"`). */
     insightType?: string;
 }
+/** One period value in a KPI time series. */
+interface KpiDataPoint {
+    /** e.g. "Q2 FY2026" */
+    period: string;
+    /** ISO date, e.g. "2025-12-27" */
+    date: string;
+    value: number;
+    /** Preliminary flag; often null. */
+    isEstimate?: boolean | null;
+}
+/** A single KPI time series for a company. */
+interface KpiSeries {
+    /** Stable per-ticker identifier, e.g. "iphone_revenue". */
+    id: string;
+    /** Human-readable name, e.g. "iPhone Revenue". */
+    name: string;
+    /** Logical category, e.g. "product_revenue", "segment_revenue". */
+    category: string;
+    /** Unit of measurement, e.g. "USD". */
+    unit: string;
+    /** Display hint, e.g. "currency_abbreviated". */
+    displayFormat: string;
+    /** Default chart type, e.g. "bar" or "line". */
+    chartType: string;
+    /** Time-series data points. */
+    values: KpiDataPoint[];
+    /** Citation for the source filing. */
+    sourceRef?: string;
+    /** Set when the company has stopped reporting this metric. */
+    discontinued?: boolean;
+    /** Optional human-readable note about discontinuation. */
+    discontinuedNote?: string;
+}
+/** Full KPI payload for a company. Returned by `client.stocks.getKpis`. */
+interface CompanyKpisData {
+    ticker: string;
+    companyName: string;
+    cik?: string;
+    lastUpdated: string;
+    kpis: KpiSeries[];
+}
+/** Lightweight coverage entry. Returned by `client.stocks.listKpiCoverage`. */
+interface KpiCoverageEntry {
+    ticker: string;
+    companyName: string;
+    lastUpdated: string;
+    kpiCount: number;
+}
+/** Coverage listing envelope: count + list of covered tickers. */
+interface KpiCoverageResponse {
+    count: number;
+    tickers: KpiCoverageEntry[];
+}
+/** Lightweight KPI metadata tuple. Returned by `client.stocks.getKpiTypes`. */
+interface KpiTypeEntry {
+    id: string;
+    name: string;
+    category: string;
+    chartType: string;
+}
 interface KBEntity {
     entityId: string;
     name: string;
     [key: string]: unknown;
 }
 
+interface AnalystConsensus {
+    ticker: string;
+    currentPrice: number | null;
+    targetLow: number | null;
+    targetMean: number | null;
+    targetHigh: number | null;
+    targetMedian: number | null;
+    numberOfAnalysts: number;
+    upsidePercent: number | null;
+    consensusLabel: string | null;
+    recommendationMean: number | null;
+    /** PRO-only; zero in the free preview. */
+    strongBuy: number;
+    /** PRO-only; zero in the free preview. */
+    buy: number;
+    /** PRO-only; zero in the free preview. */
+    hold: number;
+    /** PRO-only; zero in the free preview. */
+    sell: number;
+    /** PRO-only; zero in the free preview. */
+    strongSell: number;
+    updatedAt: string | null;
+}
+interface AnalystAction {
+    ticker: string;
+    actionDate: string;
+    firm: string;
+    /** UPGRADE, DOWNGRADE, INITIATE, REITERATE, OTHER */
+    actionType: string;
+    fromGrade: string | null;
+    toGrade: string | null;
+}
+interface AnalystEstimate {
+    /** Fiscal period descriptor (provider-specific shape). */
+    [key: string]: unknown;
+}
+interface AnalystEarningsSurprise {
+    /** Past report descriptor (provider-specific shape). */
+    [key: string]: unknown;
+}
+interface AnalystEstimatesResponse {
+    estimates: AnalystEstimate[];
+    surprises: AnalystEarningsSurprise[];
+}
+interface GetAnalystActionsOptions {
+    /** Days of history to return. Default 90. */
+    lookbackDays?: number;
+}
+interface GetAnalystMarketActivityOptions {
+    /** Days of history to return. Default 30. */
+    lookbackDays?: number;
+}
+/**
+ * Wall Street analyst coverage: aggregate price targets, recommendation distribution,
+ * recent upgrade/downgrade actions, and forward EPS estimates with earnings surprise history.
+ *
+ * Free users receive the price target band (low/mean/high + analyst count + consensus label)
+ * in full -- it powers the public projection cone. The buy/hold/sell distribution counts
+ * and full action/estimate history are PRO-only.
+ */
+declare class Analyst {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * Get the aggregate Wall Street consensus for a ticker. Returns 404 if no
+     * coverage exists.
+     */
+    consensus(ticker: string): Promise<PreviewResponse<AnalystConsensus>>;
+    /**
+     * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
+     * Free users receive the 3 most recent.
+     */
+    actions(ticker: string, options?: GetAnalystActionsOptions): Promise<PreviewResponse<AnalystAction[]>>;
+    /**
+     * Get forward EPS estimates and earnings surprise history for a ticker.
+     * Free users receive 1 estimate (current quarter) plus the 2 most recent surprises.
+     */
+    estimates(ticker: string): Promise<PreviewResponse<AnalystEstimatesResponse>>;
+    /**
+     * Get market-wide recent analyst actions across all covered tickers, newest first.
+     * Free users receive the 5 most recent.
+     */
+    marketActivity(options?: GetAnalystMarketActivityOptions): Promise<PreviewResponse<AnalystAction[]>>;
+}
+
 declare class Documents {
     private client;
     constructor(client: APIClient);
@@ -556,6 +725,163 @@ declare class EntityMetrics {
     getAverageSentiment(symbol: string, options?: EntityMetricsDateRange): Promise<SentimentData>;
 }
 
+interface EtfInfo {
+    ticker: string;
+    name: string;
+    kbEntityId: string | null;
+    urlSlug: string | null;
+    issuer: string | null;
+    trackedIndex: string | null;
+    assetClass: string | null;
+}
+interface EtfHolding {
+    ticker: string;
+    name: string | null;
+    /** Weight in the fund as a percentage (0-100). */
+    weight_pct: number;
+    /** First date this holding appeared in the composition. */
+    first_seen: string | null;
+}
+interface EtfHoldings {
+    ticker: string;
+    issuer: string;
+    issuer_endpoint: string | null;
+    as_of_date: string;
+    fetched_at: string;
+    next_refresh_due: string;
+    total_holdings: number;
+    holdings: EtfHolding[];
+    /** True when this is a top-N view rather than the full fund. */
+    partial?: boolean | null;
+    /** Issuer's reported total holdings when `partial=true`. */
+    total_known_holdings?: number | null;
+}
+interface EtfAggregateCoverage {
+    holdingsCount: number;
+    holdingsCovered: number;
+    /** Sum of weights (0-100) for the covered holdings. */
+    weightCovered: number;
+    partial?: boolean | null;
+    totalKnownHoldings?: number | null;
+}
+interface WeightedConsensus {
+    upsidePercent: number | null;
+    consensusLabel: string | null;
+    /** Fractions of covered AUM in each bucket. Sums to ~1.0. */
+    distribution: Record<string, number>;
+    totalAnalysts: number;
+}
+interface EtfAnalystContributor {
+    ticker: string;
+    weightPct: number;
+    upsidePercent: number | null;
+    consensusLabel: string | null;
+    /** Signed contribution to the fund's weighted upside in percentage points. */
+    contributionPp: number;
+}
+interface EtfAnalystAggregate {
+    ticker: string;
+    asOfDate: string | null;
+    computedAt: string;
+    coverage: EtfAggregateCoverage;
+    weightedConsensus: WeightedConsensus;
+    /** PRO-only; null on the free preview. */
+    topContributors: EtfAnalystContributor[] | null;
+}
+interface WeightedNetFlow {
+    /** Weighted net dollar flow (buys - sells). Negative = net selling. */
+    netDollars: number;
+    buyDollars: number;
+    sellDollars: number;
+    /** Unweighted; for context. */
+    buyTradeCount: number;
+    /** Unweighted; for context. */
+    sellTradeCount: number;
+    distinctInsiderCount: number;
+}
+interface EtfInsiderContributor {
+    ticker: string;
+    weightPct: number;
+    /** Per-stock net flow over the window (signed). */
+    netDollars: number;
+    /** Signed contribution to the weighted headline. */
+    weightedNetDollars: number;
+    tradeCount: number;
+}
+interface EtfInsiderAggregate {
+    ticker: string;
+    asOfDate: string | null;
+    computedAt: string;
+    lookbackDays: number;
+    coverage: EtfAggregateCoverage;
+    weightedNetFlow: WeightedNetFlow;
+    /** PRO-only; null on the free preview. */
+    topContributors: EtfInsiderContributor[] | null;
+}
+interface EtfSentimentReading {
+    sentiSenseScore: number | null;
+    /** BULLISH / NEUTRAL / BEARISH. */
+    scoreLabel: string;
+    /** Epoch millis when the underlying metric was produced. */
+    asOfTimestamp: number | null;
+}
+interface EtfSentimentAggregate {
+    ticker: string;
+    asOfDate: string | null;
+    computedAt: string;
+    coverage: EtfAggregateCoverage;
+    /** Holdings-weighted SentiSense across the fund's constituents. */
+    constituentsWeighted: EtfSentimentReading;
+    /** Direct reading from mentions of the fund's own ticker. Null for low-mention funds. */
+    direct: EtfSentimentReading | null;
+}
+interface GetEtfInsiderAggregateOptions {
+    /** Trailing window for the trade aggregation. Typical values: 30, 90. Default 30. */
+    lookbackDays?: number;
+}
+/**
+ * ETF discovery, composition (holdings), and holdings-weighted aggregate views.
+ *
+ * Funds aren't rated by analysts directly, don't have insiders of their own, and
+ * may not get many direct news mentions -- but the companies inside them do. The
+ * aggregate endpoints synthesize fund-level views from each constituent's per-stock
+ * data, weighted by allocation, with a coverage block so consumers see how much of
+ * the fund's AUM the underlying data covered.
+ *
+ * Beta as of 2026-05-15: starting with a limited set of widely-traded funds.
+ */
+declare class Etfs {
+    private client;
+    constructor(client: APIClient);
+    /**
+     * List every ETF tracked by SentiSense, sorted by ticker.
+     */
+    list(): Promise<EtfInfo[]>;
+    /**
+     * Get the full holdings composition for an ETF, including per-holding weights
+     * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
+     */
+    holdings(ticker: string): Promise<EtfHoldings>;
+    /**
+     * Get the holdings-weighted analyst consensus for an ETF. Free users receive
+     * the headline and coverage block; PRO unlocks per-holding `topContributors`.
+     */
+    analystAggregate(ticker: string): Promise<PreviewResponse<EtfAnalystAggregate>>;
+    /**
+     * Get the holdings-weighted SEC Form 4 insider aggregate for an ETF over a
+     * configurable trailing window. Free users receive the headline + buy/sell
+     * split; PRO unlocks per-holding `topContributors` with signed contribution.
+     */
+    insiderAggregate(ticker: string, options?: GetEtfInsiderAggregateOptions): Promise<PreviewResponse<EtfInsiderAggregate>>;
+    /**
+     * Get two SentiSense Score readings side-by-side: `constituentsWeighted`
+     * (precomputed daily weighted average across the fund's holdings) and `direct`
+     * (score from mentions of the fund's own ticker). The two can diverge, and the
+     * gap is itself information.
+     */
+    sentimentAggregate(ticker: string): Promise<PreviewResponse<EtfSentimentAggregate>>;
+}
+
 declare class Insider {
     private client;
     constructor(client: APIClient);
@@ -610,6 +936,20 @@ declare class Politicians {
     getMember(slug: string): Promise<PreviewResponse<PoliticianDetail>>;
 }
 
+interface GetStockInsightsRangeOptions {
+    startDate: string;
+    endDate: string;
+    urgency?: "low" | "medium" | "high";
+    insightType?: string;
+}
+interface GetLatestInsightsOptions {
+    limit?: number;
+    urgency?: "low" | "medium" | "high";
+}
+interface GetUserInsightsOptions {
+    limit?: number;
+    category?: string;
+}
 declare class Insights {
     private client;
     constructor(client: APIClient);
@@ -622,6 +962,13 @@ declare class Insights {
      * (type, urgency, timestamp) showing what additional signals exist.
      */
     stock(ticker: string, options?: GetInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    /**
+     * Get AI insights for a stock within a date range.
+     *
+     * Free users receive the top 3; PRO users receive the full list.
+     * The server returns 400 if `startDate` is after `endDate`.
+     */
+    stockRange(ticker: string, options: GetStockInsightsRangeOptions): Promise<Insight[] | InsightPreviewResponse>;
     /**
      * Get AI-generated market-level insights, sorted by urgency then confidence.
      *
@@ -630,6 +977,19 @@ declare class Insights {
      * the top 5 insights in full, and a `locked` array with metadata-only entries.
      */
     market(): Promise<Insight[] | InsightPreviewResponse>;
+    /**
+     * Get the latest AI insights across all tracked stocks, newest first.
+     *
+     * Free users receive the top 5; PRO users receive up to `limit` (clamped to 1-200).
+     */
+    latest(options?: GetLatestInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
+    /**
+     * Get personalized insights for the authenticated user.
+     *
+     * Biased toward the user's watchlist and portfolio when available; falls back
+     * to market-level insights otherwise. API key authentication required.
+     */
+    user(options?: GetUserInsightsOptions): Promise<Insight[] | InsightPreviewResponse>;
     /**
      * Get available insight types for a specific stock.
      * No authentication required.
@@ -650,6 +1010,15 @@ declare class Institutional {
     getHolders(ticker: string, reportDate: string): Promise<Holder[]>;
     /** Get activist investor positions (NEW or INCREASED). */
     getActivists(reportDate: string): Promise<Holder[]>;
+    /**
+     * Get the full profile, summary stats, and current-quarter holdings for a
+     * specific institutional filer.
+     *
+     * Resolved by URL slug (e.g. `Berkshire-Hathaway`) or numeric SEC CIK.
+     * Free users receive the profile and top 10 holdings; PRO users receive the
+     * full holdings array. Returns 404 if the slug or CIK is unknown.
+     */
+    getInstitutionDetail(slugOrCik: string): Promise<unknown>;
 }
 
 declare class KB {
@@ -732,11 +1101,41 @@ declare class Stocks {
     getFloat(ticker: string): Promise<FloatInfo>;
     /** Get short volume trading data. */
     getShortVolume(ticker: string): Promise<ShortVolume>;
+    /**
+     * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
+     * non-GAAP metrics from earnings filings (e.g. iPhone unit sales, Tesla deliveries,
+     * AWS revenue).
+     *
+     * Free users receive metadata only with an empty `kpis` list; PRO users receive
+     * the full series. Returns 404 for tickers that do not yet have curated coverage.
+     *
+     * Coverage today: near-complete for the S&P 500 plus extended universe
+     * (~500 tickers). Use `listKpiCoverage()` to enumerate.
+     */
+    getKpis(ticker: string): Promise<PreviewResponse<CompanyKpisData>>;
+    /**
+     * List every ticker with curated KPI coverage. Returns `{count, tickers: [...]}`
+     * with lightweight metadata (ticker, companyName, lastUpdated, kpiCount).
+     * Sorted alphabetically by ticker.
+     *
+     * Auth: API key required, but the call does NOT consume your monthly quota
+     * (rate-limit-per-minute still applies). [COMP-421]
+     */
+    listKpiCoverage(): Promise<KpiCoverageResponse>;
+    /**
+     * List the KPI metadata tuples available for a ticker — `id, name, category,
+     * chartType` — without paying the cost of the full series payload. Mirrors
+     * the `/api/v1/insights/stock/{ticker}/types` precedent.
+     *
+     * Auth: API key required, no quota cost. 404 if the ticker has no curated KPIs.
+     */
+    getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
 }
 
 /** @internal HTTP interface exposed to resource classes. */
 interface APIClient {
     get<T = unknown>(path: string, params?: object): Promise<T>;
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
 }
 declare class SentiSense implements APIClient {
     private baseUrl;
@@ -745,10 +1144,12 @@ declare class SentiSense implements APIClient {
     private maxRetries;
     readonly stocks: Stocks;
     readonly documents: Documents;
+    readonly etfs: Etfs;
     readonly institutional: Institutional;
     readonly insider: Insider;
     readonly politicians: Politicians;
     readonly insights: Insights;
+    readonly analyst: Analyst;
     readonly entityMetrics: EntityMetrics;
     readonly marketMood: MarketMoodResource;
     readonly marketSummary: MarketSummaryResource;
@@ -756,6 +1157,8 @@ declare class SentiSense implements APIClient {
     constructor(options?: SentiSenseOptions);
     /** @internal */
     get<T = unknown>(path: string, params?: object): Promise<T>;
+    /** @internal */
+    post<T = unknown>(path: string, body: unknown): Promise<T>;
     private buildUrl;
     private handleErrorResponse;
 }
@@ -779,6 +1182,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.9.1";
+declare const VERSION = "0.14.0";
 
-export { type AISummary, APIError, AuthenticationError, type ChartData, type ChartDataPoint, type ClusterBuy, type CongressTrade, type Document, type DocumentSource, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type GetInsiderOptions, type GetInsightsOptions, type GetPoliticiansOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionalFlow, type InstitutionalFlowsResponse, type KBEntity, 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, SentiSense as default };
+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 InstitutionalFlow, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, 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 };