sentisense 0.18.0 → 0.22.0

package/dist/index.d.ts

@@ -60,6 +60,7 @@ interface StockDetail {
 interface SimilarStock {
     symbol: string;
     name: string;
+    /** @deprecated No longer returned by the API; use `symbol` to identify the peer. Will be removed in a future release. */
     kbEntityId?: string;
     price: number | null;
     changePercent: number | null;
@@ -286,6 +287,54 @@ interface InstitutionalFlowsResponse {
 interface GetFlowsOptions {
     limit?: number;
 }
+/** A single institution summary from the discovery list. */
+interface InstitutionSummary {
+    /** SEC Central Index Key of the (rolled-up) institution. */
+    cik: string;
+    /** URL slug for routing to `getInstitutionDetail`. */
+    urlSlug: string;
+    displayName: string;
+    /** Filer category, or null if unclassified. */
+    filerCategory: string | null;
+    /** Total AUM in USD for the quarter (rolled-up across the filer group). */
+    totalValueUsd: number;
+    /** Distinct equity tickers held this quarter (rolled-up, de-duped). */
+    holdingsCount: number;
+    /** True when this institution aggregates multiple related filer CIKs. */
+    multiCikRollup: boolean;
+    /** Number of subsidiary filers rolled up under this institution (0 when not a rollup). */
+    childCikCount: number;
+}
+/** The `data` payload of the institution discovery list. */
+interface InstitutionList {
+    /** Quarter of the AUM snapshot, e.g. `"2026Q1"`. */
+    quarter: string;
+    /** Total institutions matching the filters, before pagination. */
+    totalCount: number;
+    offset: number;
+    limit: number;
+    institutions: InstitutionSummary[];
+}
+/** Wire envelope for the discovery list (always full, never a preview). */
+interface InstitutionListResponse {
+    isPreview: boolean;
+    previewReason: "PRO_REQUIRED" | null;
+    data: InstitutionList;
+}
+interface ListInstitutionsOptions {
+    /** Filer category filter (e.g. `"HEDGE_FUND"`). */
+    category?: string;
+    /** Minimum total AUM in USD (e.g. `10_000_000_000`). */
+    minAumUsd?: number;
+    /** Page size (default 50, max 200). */
+    limit?: number;
+    /** Pagination offset (default 0). */
+    offset?: number;
+    /** `"aumDesc"` (default), `"aumAsc"`, or `"nameAsc"`. */
+    sort?: "aumDesc" | "aumAsc" | "nameAsc";
+    /** AUM snapshot quarter as `YYYYQN` (e.g. `"2026Q1"`); defaults to latest. */
+    quarter?: string;
+}
 interface InsiderActivitySummary {
     ticker: string;
     companyName: string;
@@ -391,9 +440,59 @@ 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;
+    /**
+     * Number of items in the full PRO dataset, before preview truncation.
+     * Present on preview (free-tier) list responses so callers can show
+     * "showing N of totalCount". Absent on full PRO responses.
+     */
+    totalCount?: number;
     data: T;
 }
 /** Supported metric types for the v2 Serving Metrics API. */
@@ -576,6 +675,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;
@@ -662,6 +916,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);
@@ -1021,6 +1289,18 @@ declare class Institutional {
     getHolders(ticker: string, reportDate: string): Promise<Holder[]>;
     /** Get activist investor positions (NEW or INCREASED). */
     getActivists(reportDate: string): Promise<Holder[]>;
+    /**
+     * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
+     * so you can find what to query without knowing slugs upfront.
+     *
+     * Each institution is rolled up by parent filer, so a multi-filer manager
+     * (e.g. Vanguard) appears once with combined AUM. Summary only; use
+     * `getInstitutionDetail` for a filer's full holdings.
+     *
+     * Requires an API key but does not consume monthly quota (per-minute rate
+     * limits still apply). Returns the unwrapped list payload.
+     */
+    listInstitutions(options?: ListInstitutionsOptions): Promise<InstitutionList>;
     /**
      * Get the full profile, summary stats, and current-quarter holdings for a
      * specific institutional filer.
@@ -1128,7 +1408,7 @@ declare class Stocks {
      * 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]
+     * (rate-limit-per-minute still applies).
      */
     listKpiCoverage(): Promise<KpiCoverageResponse>;
     /**
@@ -1141,6 +1421,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>;
@@ -1163,6 +1475,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>;
@@ -1191,6 +1505,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.18.0";
+declare const VERSION = "0.22.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 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 };
+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.mjs

@@ -75,6 +75,24 @@ var Analyst = class {
   }
 };
 
+// src/resources/calendar.ts
+var Calendar = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * 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.
+   */
+  async getEarnings(options) {
+    return this.client.get("/api/v1/calendar/earnings", options);
+  }
+};
+
 // src/resources/documents.ts
 var Documents = class {
   constructor(client) {
@@ -451,6 +469,24 @@ var Institutional = class {
   async getActivists(reportDate) {
     return this.client.get("/api/v1/institutional/activist", { reportDate });
   }
+  /**
+   * Discover institutions: a paginated, AUM-ranked list of filers (slug + metadata)
+   * so you can find what to query without knowing slugs upfront.
+   *
+   * Each institution is rolled up by parent filer, so a multi-filer manager
+   * (e.g. Vanguard) appears once with combined AUM. Summary only; use
+   * `getInstitutionDetail` for a filer's full holdings.
+   *
+   * Requires an API key but does not consume monthly quota (per-minute rate
+   * limits still apply). Returns the unwrapped list payload.
+   */
+  async listInstitutions(options) {
+    const resp = await this.client.get(
+      "/api/v1/institutional/institutions",
+      { ...options }
+    );
+    return resp.data;
+  }
   /**
    * Get the full profile, summary stats, and current-quarter holdings for a
    * specific institutional filer.
@@ -494,6 +530,8 @@ var MarketMoodResource = class {
   async get() {
     return this.client.get("/api/v2/market-mood");
   }
+  // TODO: accept a `days` param to control history length (the endpoint supports ?days=N).
+  // TODO: add a sibling `indexes` resource for /api/v1/indexes/{id} (+ /history), e.g. fed-sentiment.
 };
 
 // src/resources/marketSummary.ts
@@ -641,7 +679,7 @@ var Stocks = class {
    * 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]
+   * (rate-limit-per-minute still applies).
    */
   async listKpiCoverage() {
     return this.client.get("/api/v1/stocks/with-kpis");
@@ -660,8 +698,37 @@ var Stocks = class {
   }
 };
 
+// src/resources/trackers.ts
+var Trackers = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * List every publicly-visible tracker — id, display name, category,
+   * one-line description, and the methodology anchor to link out to.
+   */
+  async list() {
+    return this.client.get("/api/v1/trackers");
+  }
+  /**
+   * 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.
+   */
+  async get(trackerId, params) {
+    return this.client.get(`/api/v1/trackers/${trackerId}`, params);
+  }
+};
+
 // src/version.ts
-var VERSION = "0.18.0";
+var VERSION = "0.22.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -690,6 +757,8 @@ var SentiSense = class {
     this.marketMood = new MarketMoodResource(this);
     this.marketSummary = new MarketSummaryResource(this);
     this.kb = new KB(this);
+    this.trackers = new Trackers(this);
+    this.calendar = new Calendar(this);
   }
   /** @internal */
   async get(path, params) {