sentisense 0.33.0 → 0.34.0

package/dist/index.d.mts

@@ -49,6 +49,17 @@ interface StockQuote {
     dividendYield: number | null;
     /** 200-day simple moving average of daily closes. Null when fewer than 200 trading days of history exist. */
     movingAverage200Day: number | null;
+    /**
+     * Currency the issuer reports its financials in ("USD", "TWD", "JPY", ...). Absent when
+     * the currency is unknown, which is not the same as implicitly USD. Same field and same
+     * meaning as {@link Fundamentals.reportedCurrency}.
+     *
+     * Price fields on this response are always in the listing currency of the quoted symbol,
+     * so on an ADR filing in a home currency the price and the per-share statement figures are
+     * in different units. The valuation ratios derived from both (`peRatio`, `epsTTM`) are
+     * omitted rather than computed in that case, so treat them as possibly absent, not zero.
+     */
+    reportedCurrency?: string;
     timestamp: number | null;
     /** Extended-hours view (pre-market or after-hours). Null/absent during RTH, overnight, and weekends. */
     extendedHours?: ExtendedHoursInfo | null;
@@ -89,10 +100,15 @@ interface StockEntity {
 }
 /** Per-source tone for a stock: where the conversation is, and how it leans. */
 interface SentimentSourceTone {
+    /** "News", "Reddit", "X", "YouTube", "Substack". */
     source: string;
     /** "Bullish" | "Neutral" | "Bearish". */
     direction: string;
-    /** Share of this stock's mentions coming from this source. */
+    /**
+     * Whole-number percent of this stock's mentions, not a fraction. Each source's share is
+     * rounded independently, so the array sums to about 100 rather than exactly 100: 101 is
+     * common and is not a data error. Do not use the shares to reconstruct per-source counts.
+     */
     mentionShare: number;
     /** Exact polarity in [-1, 1]. */
     value?: number;
@@ -127,7 +143,9 @@ interface StockSentiment {
     mentions?: number;
     /** 30-day average mentions per day. */
     mentionsAvg30d?: number;
+    /** Latest share of voice, as a fraction (0.021 = 2.1%). Note this is NOT the same unit as `mentionShare`. */
     socialDominance?: number;
+    /** Per-source tone, loudest source first. */
     bySource?: SentimentSourceTone[];
     relatedTickers?: Array<{
         ticker: string;
@@ -263,9 +281,14 @@ interface AISummary {
 }
 interface GetChartOptions {
     /**
-     * Chart range. "MAX" returns the full available history (up to ~26 years); "10Y" and "5Y"
-     * return weekly bars. Ranges of "5Y" and longer are split- and dividend-adjusted; shorter
-     * ranges are split-adjusted only.
+     * Chart range. "MAX" returns the full available history (up to ~26 years) as monthly bars;
+     * "10Y" and "5Y" return weekly bars.
+     *
+     * Price basis differs by range, so do not compare closes across two ranges without
+     * checking this: "10Y" and "MAX" are split- and dividend-adjusted, while "5Y" and every
+     * shorter range are split-adjusted only. A "5Y" weekly close equals the "1Y" daily close of
+     * that week's last trading day; the "10Y" bar for the same week is lower by the dividends
+     * paid since, and the gap widens the further back you read.
      *
      * "ALL" is a legacy alias of "5Y", retained so existing code keeps compiling.
      */
@@ -310,6 +333,15 @@ interface Document {
     id: string;
     url: string;
     source: "NEWS" | "REDDIT" | "X" | "SUBSTACK" | "YOUTUBE";
+    /**
+     * Publisher name for a news article, e.g. `"The Motley Fool"`. Null on social sources,
+     * where the publisher is the platform already named in `source`, so fall back to
+     * `source` for a label rather than printing an empty string.
+     *
+     * Typed optional so existing object literals keep compiling; the API sends the key on
+     * every document row.
+     */
+    sourceName?: string | null;
     published: number;
     averageSentiment: number;
     reliability: number;
@@ -430,7 +462,7 @@ interface InstitutionalFlow {
     avgClosePrice?: number | null;
     /**
      * Dollar-weighted net flow: `netSharesChange × avgClosePrice`. 0 when
-     * `avgClosePrice` is missing — fall back to displaying `netSharesChange`.
+     * `avgClosePrice` is missing, so fall back to displaying `netSharesChange`.
      */
     dollarFlowUsd: number;
 }
@@ -443,6 +475,36 @@ interface Holder {
     changeType: "NEW" | "INCREASED" | "DECREASED" | "SOLD_OUT" | "UNCHANGED";
     sharesChange: number;
     sharesChangePct: number;
+    /**
+     * URL slug for this filer, to pass straight to
+     * `institutional.getInstitutionDetail()`. Null when the filer has no curated
+     * institution page, so check it before building a link.
+     *
+     * Typed optional so existing object literals keep compiling; the API sends the key
+     * on every holder row.
+     */
+    entitySlug?: string | null;
+    /**
+     * Number of SEC filer CIKs rolled up into this row, when the row aggregates a
+     * multi-filer manager. Null for a single-CIK filer, which is the common case, so
+     * read it as "1 or unknown" rather than zero.
+     */
+    cikCount?: number | null;
+}
+/**
+ * A server-side shortlist of the quarter's significant position changes, so a caller
+ * paging through thousands of rows does not have to fetch them all to find the movers.
+ *
+ * Scoped to the whole ticker, not to the page you asked for: the same values come back
+ * whatever `limit` and `offset` you send. The server picks both the threshold behind
+ * `count` and the ranking behind `top`, and neither is part of the API contract, so treat
+ * this as a display aid and re-derive anything you need to sort or filter on from `holders`.
+ */
+interface HolderNotableChanges {
+    /** How many holders the server judged to have changed significantly this quarter. */
+    count: number;
+    /** The shortlist itself, already ranked. Same row shape as `holders`. */
+    top: Holder[];
 }
 /**
  * Institutional ownership for one ticker: the `data` payload of
@@ -456,8 +518,25 @@ interface TickerHolders {
     reportDate: string;
     totalInstitutionalShares: number;
     totalInstitutionalValue: number;
+    /** Every institutional holder of this ticker for the quarter, ignoring any paging. */
     holderCount: number;
     holders: Holder[];
+    /**
+     * Rows actually returned in `holders`. Sent only when you passed `limit`, so use
+     * `holders.length` if you need a count that is always there. On the last page it is
+     * smaller than the `limit` you asked for, which is how you know to stop.
+     */
+    returnedCount?: number;
+    /**
+     * Row offset these `holders` start at, echoing the request. Sent only when you passed
+     * `limit`; the unpaged response omits it rather than sending 0.
+     */
+    offset?: number;
+    /**
+     * Ticker-wide summary of the quarter's biggest position changes. Sent only when you
+     * passed `limit`, since it exists to spare a paging caller a full scan.
+     */
+    notableChanges?: HolderNotableChanges;
 }
 /**
  * The flows payload inside the response envelope: `institutional.getFlows()` returns
@@ -494,6 +573,27 @@ type InstitutionalFlowsResponse = InstitutionalFlows;
 interface GetFlowsOptions {
     limit?: number;
 }
+/**
+ * Paging and sort options for `institutional.getHolders`.
+ *
+ * `limit` is the switch for the whole set: sent on its own it pages, and it is also what
+ * turns on `offset`, `sortBy`, `sortDir`, and the `returnedCount` / `offset` /
+ * `notableChanges` fields on the response. Send any of the others without `limit` and the
+ * server ignores them and returns the full unsorted list, silently, with a 200.
+ */
+interface GetHoldersOptions {
+    /**
+     * Maximum holder rows to return. Must be >= 1; values above 1000 are capped
+     * server-side. Omit to get the full, unbounded holder list.
+     */
+    limit?: number;
+    /** Row offset to start from. Server default is 0. Requires `limit`. */
+    offset?: number;
+    /** Sort field. Server default is `"shares"`. Requires `limit`. */
+    sortBy?: "shares" | "valueUsd" | "sharesChangePct";
+    /** Sort direction. Server default is `"desc"`. Requires `limit`. */
+    sortDir?: "asc" | "desc";
+}
 /** A single institution summary from the discovery list. */
 interface InstitutionSummary {
     /** SEC Central Index Key of the (rolled-up) institution. */
@@ -669,6 +769,26 @@ interface GetPoliticiansOptions {
     /** Number of days to look back (1-365). Defaults to 90. */
     lookbackDays?: number;
 }
+/**
+ * Options for `politicians.getActivity`, which pages on top of the shared lookback window.
+ *
+ * The market-wide feed is far longer than one response: a 90-day window is routinely well
+ * over a thousand disclosures and the server returns 200 of them by default. Read
+ * `totalCount` on the envelope to size the walk, then step through with `limit` and
+ * `offset`. Omitting both keeps the original single 200-row request.
+ */
+interface GetPoliticianActivityOptions extends GetPoliticiansOptions {
+    /**
+     * Rows to return. Must be >= 1; the server rejects 0 or negative with HTTP 400
+     * (`invalid_limit`) and caps anything above 500 at 500. Omit for the default 200.
+     */
+    limit?: number;
+    /**
+     * Row offset to start from. Defaults to 0, and unlike the holders endpoint it works
+     * without `limit`. An offset past the end returns an empty `data` array, not an error.
+     */
+    offset?: number;
+}
 /** Generic preview wrapper used by PRO-gated endpoints. */
 interface EarningsEvent {
     ticker: string;
@@ -718,9 +838,15 @@ interface PreviewResponse<T> {
     isPreview: boolean;
     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
-     * "showing N of totalCount". Absent on full PRO responses.
+     * Size of the full result set, before any truncation your response went through.
+     *
+     * Sent whenever the server knows that number and the response might not hold all of it:
+     * on a preview (`isPreview: true`), so you can render "showing N of totalCount", and on a
+     * paged endpoint such as `politicians.getActivity`, where it is the full match count for
+     * your filters on every tier, including a PRO response with `isPreview: false`.
+     *
+     * Absent on the endpoints that simply return everything, so a missing `totalCount` means
+     * "ask `data` for the count", never "zero results".
      */
     totalCount?: number;
     data: T;
@@ -930,7 +1056,7 @@ interface TrackerListing {
 interface TrackerListResponse {
     trackers: TrackerListing[];
 }
-/** One row of a `viewType: "table"` tracker — a ranked leaderboard cell. */
+/** 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;
@@ -1218,18 +1344,18 @@ interface EtfHolding {
     name: string | null;
     /** Weight in the fund as a percentage (0-100). */
     weightPct: number;
-    /** ISO date "YYYY-MM-DD" — first date this holding appeared in the composition. */
+    /** ISO date "YYYY-MM-DD". First date this holding appeared in the composition. */
     firstSeen: string | null;
 }
 interface EtfHoldings {
     ticker: string;
     issuer: string;
     issuerEndpoint: string | null;
-    /** ISO date "YYYY-MM-DD" — composition snapshot date from the issuer. */
+    /** ISO date "YYYY-MM-DD". Composition snapshot date from the issuer. */
     asOfDate: string;
     /** Epoch seconds when SentiSense refreshed the composition. */
     fetchedAt: number | null;
-    /** ISO date "YYYY-MM-DD" — when the composition is scheduled to be refreshed next. */
+    /** ISO date "YYYY-MM-DD". When the composition is scheduled to be refreshed next. */
     nextRefreshDue: string;
     totalHoldings: number;
     holdings: EtfHolding[];
@@ -1263,7 +1389,7 @@ interface EtfAnalystContributor {
 }
 interface EtfAnalystAggregate {
     ticker: string;
-    /** ISO date "YYYY-MM-DD" — composition snapshot date. */
+    /** ISO date "YYYY-MM-DD". Composition snapshot date. */
     asOfDate: string | null;
     /** Epoch seconds when this rollup was computed. */
     computedAt: number;
@@ -1294,7 +1420,7 @@ interface EtfInsiderContributor {
 }
 interface EtfInsiderAggregate {
     ticker: string;
-    /** ISO date "YYYY-MM-DD" — composition snapshot date. */
+    /** ISO date "YYYY-MM-DD". Composition snapshot date. */
     asOfDate: string | null;
     /** Epoch seconds when this rollup was computed. */
     computedAt: number;
@@ -1313,7 +1439,7 @@ interface EtfSentimentReading {
 }
 interface EtfSentimentAggregate {
     ticker: string;
-    /** ISO date "YYYY-MM-DD" — composition snapshot date. */
+    /** ISO date "YYYY-MM-DD". Composition snapshot date. */
     asOfDate: string | null;
     /** Epoch seconds when this aggregate was assembled. */
     computedAt: number;
@@ -1402,8 +1528,21 @@ declare class Politicians {
      *
      * PRO-gated. Free/unauthenticated 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
+     * thousand disclosures, and without `limit` the server sends the first 200 with no marker
+     * that it stopped. `totalCount` on the envelope is the real size on every tier, so page
+     * with `limit` and `offset` rather than reading `data.length` as the total.
+     *
+     * ```typescript
+     * const first = await client.politicians.getActivity({ limit: 100 });
+     * for (let offset = 100; offset < first.totalCount!; offset += 100) {
+     *   const page = await client.politicians.getActivity({ limit: 100, offset });
+     *   // ... page.data
+     * }
+     * ```
      */
-    getActivity(options?: GetPoliticiansOptions): Promise<PreviewResponse<CongressTrade[]>>;
+    getActivity(options?: GetPoliticianActivityOptions): Promise<PreviewResponse<CongressTrade[]>>;
     /**
      * Get congressional trades for a specific stock.
      *
@@ -1512,8 +1651,17 @@ declare class Institutional {
      * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
      * totals like `holderCount`. Free callers get a truncated `holders` array with
      * `isPreview: true`.
+     *
+     * A widely held ticker returns thousands of rows: a megacap quarter is about
+     * 6,000 holders and 1.5 MB. Pass `limit` unless you really want all of them.
+     * Omitting `options` sends the original unbounded request.
+     *
+     * `limit` is the switch for the whole option set. With it, the response also carries
+     * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
+     * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
+     * server and you get the full unsorted list back with a 200.
      */
-    getHolders(ticker: string, reportDate: string): Promise<PreviewResponse<TickerHolders>>;
+    getHolders(ticker: string, reportDate: string, options?: GetHoldersOptions): Promise<PreviewResponse<TickerHolders>>;
     /**
      * Get activist investor positions (NEW or INCREASED).
      *
@@ -1666,8 +1814,8 @@ declare class Stocks {
      */
     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
+     * 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.
@@ -1676,10 +1824,10 @@ declare class Stocks {
 }
 
 /**
- * Trackers — observational data products published as a standardized
+ * 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
+ * returns the same shape, so consumers write one renderer per `viewType` and
  * get every current and future SentiSense tracker for free.
  *
  * @see TrackerSnapshot
@@ -1688,7 +1836,7 @@ declare class Trackers {
     private client;
     constructor(client: APIClient);
     /**
-     * List every publicly-visible tracker — id, display name, category,
+     * List every publicly-visible tracker: id, display name, category,
      * one-line description, and the methodology anchor to link out to.
      */
     list(): Promise<TrackerListResponse>;
@@ -1700,8 +1848,8 @@ declare class Trackers {
      * `"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
+     * @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>;
@@ -1763,6 +1911,12 @@ declare class DeepHistoryUnavailableError extends SentiSenseError {
     constructor(message: string, retryAfter?: number);
 }
 declare class RateLimitError extends SentiSenseError {
+    /**
+     * Seconds to wait before retrying, from the server's `Retry-After` header, clamped to
+     * `[0.5, 120]`. Always either a finite number or `undefined`: an absent header, or one
+     * carrying an HTTP-date instead of a number of seconds, leaves it undefined rather than
+     * `NaN`, so `setTimeout(fn, err.retryAfter * 1000)` can never fire immediately.
+     */
     retryAfter?: number;
     constructor(message: string, code?: string, retryAfter?: number);
 }
@@ -1770,6 +1924,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.33.0";
+declare const VERSION = "0.34.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 GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticiansOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfSentimentAggregate, type EtfSentimentReading, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEtfInsiderAggregateOptions, type 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 };