sentisense 0.40.0 → 0.42.0

package/dist/index.d.mts

@@ -3,6 +3,17 @@ interface SentiSenseOptions {
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * Extra token appended to the `User-Agent`, after `sentisense-node/{version}`.
+     *
+     * Use it to say what is calling on top of the SDK, so your traffic is legible in your own
+     * logs and in ours: a tool name and version (`"my-bot/1.4"`), and optionally an agent
+     * label (`"agent/research-desk"`). Node only, since browsers set the header themselves.
+     *
+     * Carriage returns and newlines are collapsed to spaces before the header is built, and an
+     * empty or whitespace-only value is ignored.
+     */
+    userAgentSuffix?: string;
 }
 interface StockPrice {
     ticker: string;
@@ -378,6 +389,107 @@ interface GetFundamentalsOptions {
     fiscalPeriod?: string;
     fiscalYear?: number;
 }
+/**
+ * One session's aggregate options activity for a ticker.
+ *
+ * Every field is optional because the response omits anything it cannot compute rather than
+ * sending a null, so check for presence rather than comparing against `null`. Ratio and
+ * implied-volatility fields drop out first: `pcVol` is absent when call volume is zero.
+ */
+interface OptionsAggregate {
+    /** Session date, ISO calendar day `"YYYY-MM-DD"`. */
+    date?: string;
+    callVol?: number;
+    putVol?: number;
+    callOi?: number;
+    putOi?: number;
+    /** Put/call volume ratio. */
+    pcVol?: number;
+    /** Put/call open-interest ratio. */
+    pcOi?: number;
+    /** Volume-weighted implied volatility. */
+    vwIv?: number;
+    /** At-the-money implied volatility. */
+    atmIv?: number;
+    /** `iv25p - iv25c`: positive means puts are bid up relative to calls. */
+    skew25d?: number;
+    /** Roughly 60-day and 90-day at-the-money implied volatility: the term structure. */
+    atmIv60?: number;
+    atmIv90?: number;
+    /** Raw 25-delta call and put implied volatilities. */
+    iv25c?: number;
+    iv25p?: number;
+    netDelta?: number;
+    notionalVol?: number;
+    contracts?: number;
+}
+/**
+ * Percentile context for {@link OptionsAggregate}, against that ticker's own trailing
+ * history rather than against other tickers.
+ *
+ * A percentile whose window holds too few observations is omitted while the baseline builds,
+ * which is why a covered ticker can answer with readings and no percentiles.
+ */
+interface OptionsContext {
+    pcVolPctl1y?: number;
+    pcVolPctl5y?: number;
+    pcOiPctl1y?: number;
+    /** Where today's at-the-money implied volatility sits in its own trailing year. */
+    ivRank1y?: number;
+    skewPctl1y?: number;
+    observations1y?: number;
+}
+/** One open-interest concentration at a strike. */
+interface OptionsWall {
+    strike?: number;
+    oi?: number;
+}
+/** Open-interest wall structure for the dossier's expiry, up to three walls a side. */
+interface OptionsOiWalls {
+    expiry?: string;
+    maxPain?: number;
+    callWalls?: OptionsWall[];
+    putWalls?: OptionsWall[];
+}
+/** A contract whose session volume far exceeds its open interest: fresh positioning. */
+interface OptionsUnusualContract {
+    /** Exchange-style option symbol, e.g. `"NVDA260821C00200000"`. */
+    contract?: string;
+    /** Side of the contract. Arrives lower case (`"call"` / `"put"`), so compare case-insensitively. */
+    type?: string;
+    strike?: number;
+    expiry?: string;
+    /** Days to expiry. */
+    dte?: number;
+    volume?: number;
+    oi?: number;
+    volOiRatio?: number;
+    premium?: number;
+}
+/**
+ * The options dossier for one stock or ETF, from `client.stocks.getOptionsSummary()`.
+ *
+ * End of day, not live: it describes the latest completed session and refreshes the
+ * following morning.
+ */
+interface OptionsSummary {
+    /** Session the dossier describes, ISO calendar day. */
+    asOf?: string;
+    /**
+     * Positioning lean for the session, roughly -1 to 1, negative for put-heavy.
+     *
+     * A number on the wire, not a label. Sampled across several tickers to confirm that,
+     * because the field name reads like it could carry a word.
+     */
+    sentiment?: number;
+    /** Today's aggregate. */
+    latest?: OptionsAggregate;
+    /** Percentiles of `latest` against this ticker's own history. */
+    context?: OptionsContext;
+    oiWalls?: OptionsOiWalls;
+    /** Top contracts by premium. */
+    unusual?: OptionsUnusualContract[];
+}
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -490,6 +602,20 @@ interface Quarter {
     value: string;
     label: string;
     reportDate: string;
+    /**
+     * True while this quarter's 13F filing window is still open, which is the 45 days after
+     * quarter end.
+     *
+     * Read it before you pick a quarter to query. The list leads with the current quarter, so
+     * the newest entry is pending for six weeks of every quarter, and a holders request against
+     * a pending quarter answers `200` with few rows or none: correct server behaviour, and
+     * indistinguishable from "this stock has no institutional owners" unless you checked here
+     * first. For a complete picture take the newest quarter with `pending` false.
+     *
+     * Typed optional so existing object literals keep compiling; the API sends the key on
+     * every row.
+     */
+    pending?: boolean;
 }
 interface InstitutionalFlow {
     ticker: string;
@@ -776,8 +902,14 @@ interface CongressTrade {
     firstName: string;
     lastName: string;
     chamber: "SENATE" | "HOUSE";
-    party: string;
-    state: string;
+    /**
+     * Party affiliation, or `null` when the disclosure carries none. Nulls are uncommon but
+     * real on the ticker-scoped feed, so build a label from what is present rather than
+     * interpolating this directly.
+     */
+    party: string | null;
+    /** Two-letter state, or `null` when the disclosure carries none. Same caveat as `party`. */
+    state: string | null;
     bioguideId: string;
     imageUrl: string | null;
     ticker: string;
@@ -890,6 +1022,20 @@ interface GetPoliticianActivityOptions extends GetPoliticiansOptions {
      */
     offset?: number;
 }
+/** Paging over one member's trade history on `getMember`. */
+interface GetPoliticianMemberOptions {
+    /**
+     * Trades 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,
+     * which covers a member's entire history for all but a dozen of them.
+     */
+    limit?: number;
+    /**
+     * Trade offset to start from. Defaults to 0. An offset past the end returns an
+     * empty `recentTrades` array, not an error.
+     */
+    offset?: number;
+}
 /** Generic preview wrapper used by PRO-gated endpoints. */
 interface EarningsEvent {
     ticker: string;
@@ -2194,8 +2340,23 @@ declare class Politicians {
      * Get detailed profile for a single politician: summary, recent trades, top tickers.
      *
      * PRO-gated. Free users receive a preview-wrapped response.
+     *
+     * `data.recentTrades` is one page of the member's history, not all of it. Most members
+     * have a few dozen disclosures and arrive complete in the default page; a handful have
+     * thousands. `totalCount` on the envelope is the size of the whole history on every
+     * tier, so page with `limit` and `offset` rather than reading `recentTrades.length` as
+     * the total. `data.profile` and `data.topTickers` describe the whole history whatever
+     * page you ask for, so `profile.totalTrades` does not shrink with a small `limit`.
+     *
+     * ```typescript
+     * const first = await client.politicians.getMember("Ro-Khanna", { limit: 500 });
+     * for (let offset = 500; offset < first.totalCount!; offset += 500) {
+     *   const page = await client.politicians.getMember("Ro-Khanna", { limit: 500, offset });
+     *   // ... page.data.recentTrades
+     * }
+     * ```
      */
-    getMember(slug: string): Promise<PreviewResponse<PoliticianDetail>>;
+    getMember(slug: string, options?: GetPoliticianMemberOptions): Promise<PreviewResponse<PoliticianDetail>>;
 }
 
 interface GetStockInsightsRangeOptions {
@@ -2570,6 +2731,28 @@ declare class Stocks {
      * Auth: API key required, no quota cost. 404 if the ticker has no curated KPIs.
      */
     getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
+    /**
+     * Get the end-of-day options dossier for one stock or ETF: the session's aggregate, its
+     * percentile context, the open-interest wall structure with max pain, and the contracts
+     * whose volume ran far ahead of their open interest.
+     *
+     * End of day, not live. `asOf` is the prior trading session and the data refreshes the
+     * following morning, so this is positioning, not a quote feed.
+     *
+     * **`data` is `null` for a ticker outside the covered universe**, which is the most
+     * actively optioned US names plus the tracked ETFs, and for a covered ticker with no
+     * snapshot yet. An unknown symbol behaves the same way rather than answering 404, so treat
+     * a null as "no coverage", never as an error. A covered ticker still building its baseline
+     * returns its raw readings with the percentiles omitted.
+     *
+     * Percentiles compare a ticker to its own trailing history, never to another ticker, so an
+     * ETF's readings are not comparable with a single stock's.
+     *
+     * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
+     * ten calls each calendar month and a headline-only preview after that, with `isPreview`
+     * true; calls that return a null `data` never spend that allowance.
+     */
+    getOptionsSummary(ticker: string): Promise<PreviewResponse<OptionsSummary | null>>;
 }
 
 /**
@@ -2662,6 +2845,7 @@ declare class SentiSense implements APIClient {
     private apiKey;
     private timeout;
     private maxRetries;
+    private userAgent;
     readonly stocks: Stocks;
     readonly documents: Documents;
     readonly etfs: Etfs;
@@ -2724,6 +2908,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.40.0";
+declare const VERSION = "0.42.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 EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsOiWalls, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, 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 };

package/dist/index.d.ts

@@ -3,6 +3,17 @@ interface SentiSenseOptions {
     baseUrl?: string;
     timeout?: number;
     maxRetries?: number;
+    /**
+     * Extra token appended to the `User-Agent`, after `sentisense-node/{version}`.
+     *
+     * Use it to say what is calling on top of the SDK, so your traffic is legible in your own
+     * logs and in ours: a tool name and version (`"my-bot/1.4"`), and optionally an agent
+     * label (`"agent/research-desk"`). Node only, since browsers set the header themselves.
+     *
+     * Carriage returns and newlines are collapsed to spaces before the header is built, and an
+     * empty or whitespace-only value is ignored.
+     */
+    userAgentSuffix?: string;
 }
 interface StockPrice {
     ticker: string;
@@ -378,6 +389,107 @@ interface GetFundamentalsOptions {
     fiscalPeriod?: string;
     fiscalYear?: number;
 }
+/**
+ * One session's aggregate options activity for a ticker.
+ *
+ * Every field is optional because the response omits anything it cannot compute rather than
+ * sending a null, so check for presence rather than comparing against `null`. Ratio and
+ * implied-volatility fields drop out first: `pcVol` is absent when call volume is zero.
+ */
+interface OptionsAggregate {
+    /** Session date, ISO calendar day `"YYYY-MM-DD"`. */
+    date?: string;
+    callVol?: number;
+    putVol?: number;
+    callOi?: number;
+    putOi?: number;
+    /** Put/call volume ratio. */
+    pcVol?: number;
+    /** Put/call open-interest ratio. */
+    pcOi?: number;
+    /** Volume-weighted implied volatility. */
+    vwIv?: number;
+    /** At-the-money implied volatility. */
+    atmIv?: number;
+    /** `iv25p - iv25c`: positive means puts are bid up relative to calls. */
+    skew25d?: number;
+    /** Roughly 60-day and 90-day at-the-money implied volatility: the term structure. */
+    atmIv60?: number;
+    atmIv90?: number;
+    /** Raw 25-delta call and put implied volatilities. */
+    iv25c?: number;
+    iv25p?: number;
+    netDelta?: number;
+    notionalVol?: number;
+    contracts?: number;
+}
+/**
+ * Percentile context for {@link OptionsAggregate}, against that ticker's own trailing
+ * history rather than against other tickers.
+ *
+ * A percentile whose window holds too few observations is omitted while the baseline builds,
+ * which is why a covered ticker can answer with readings and no percentiles.
+ */
+interface OptionsContext {
+    pcVolPctl1y?: number;
+    pcVolPctl5y?: number;
+    pcOiPctl1y?: number;
+    /** Where today's at-the-money implied volatility sits in its own trailing year. */
+    ivRank1y?: number;
+    skewPctl1y?: number;
+    observations1y?: number;
+}
+/** One open-interest concentration at a strike. */
+interface OptionsWall {
+    strike?: number;
+    oi?: number;
+}
+/** Open-interest wall structure for the dossier's expiry, up to three walls a side. */
+interface OptionsOiWalls {
+    expiry?: string;
+    maxPain?: number;
+    callWalls?: OptionsWall[];
+    putWalls?: OptionsWall[];
+}
+/** A contract whose session volume far exceeds its open interest: fresh positioning. */
+interface OptionsUnusualContract {
+    /** Exchange-style option symbol, e.g. `"NVDA260821C00200000"`. */
+    contract?: string;
+    /** Side of the contract. Arrives lower case (`"call"` / `"put"`), so compare case-insensitively. */
+    type?: string;
+    strike?: number;
+    expiry?: string;
+    /** Days to expiry. */
+    dte?: number;
+    volume?: number;
+    oi?: number;
+    volOiRatio?: number;
+    premium?: number;
+}
+/**
+ * The options dossier for one stock or ETF, from `client.stocks.getOptionsSummary()`.
+ *
+ * End of day, not live: it describes the latest completed session and refreshes the
+ * following morning.
+ */
+interface OptionsSummary {
+    /** Session the dossier describes, ISO calendar day. */
+    asOf?: string;
+    /**
+     * Positioning lean for the session, roughly -1 to 1, negative for put-heavy.
+     *
+     * A number on the wire, not a label. Sampled across several tickers to confirm that,
+     * because the field name reads like it could carry a word.
+     */
+    sentiment?: number;
+    /** Today's aggregate. */
+    latest?: OptionsAggregate;
+    /** Percentiles of `latest` against this ticker's own history. */
+    context?: OptionsContext;
+    oiWalls?: OptionsOiWalls;
+    /** Top contracts by premium. */
+    unusual?: OptionsUnusualContract[];
+}
 type DocumentSource = "news" | "reddit" | "x" | "substack" | "youtube";
 /** Per-entity sentiment classification with resolved entity details. */
 interface SentimentEntry {
@@ -490,6 +602,20 @@ interface Quarter {
     value: string;
     label: string;
     reportDate: string;
+    /**
+     * True while this quarter's 13F filing window is still open, which is the 45 days after
+     * quarter end.
+     *
+     * Read it before you pick a quarter to query. The list leads with the current quarter, so
+     * the newest entry is pending for six weeks of every quarter, and a holders request against
+     * a pending quarter answers `200` with few rows or none: correct server behaviour, and
+     * indistinguishable from "this stock has no institutional owners" unless you checked here
+     * first. For a complete picture take the newest quarter with `pending` false.
+     *
+     * Typed optional so existing object literals keep compiling; the API sends the key on
+     * every row.
+     */
+    pending?: boolean;
 }
 interface InstitutionalFlow {
     ticker: string;
@@ -776,8 +902,14 @@ interface CongressTrade {
     firstName: string;
     lastName: string;
     chamber: "SENATE" | "HOUSE";
-    party: string;
-    state: string;
+    /**
+     * Party affiliation, or `null` when the disclosure carries none. Nulls are uncommon but
+     * real on the ticker-scoped feed, so build a label from what is present rather than
+     * interpolating this directly.
+     */
+    party: string | null;
+    /** Two-letter state, or `null` when the disclosure carries none. Same caveat as `party`. */
+    state: string | null;
     bioguideId: string;
     imageUrl: string | null;
     ticker: string;
@@ -890,6 +1022,20 @@ interface GetPoliticianActivityOptions extends GetPoliticiansOptions {
      */
     offset?: number;
 }
+/** Paging over one member's trade history on `getMember`. */
+interface GetPoliticianMemberOptions {
+    /**
+     * Trades 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,
+     * which covers a member's entire history for all but a dozen of them.
+     */
+    limit?: number;
+    /**
+     * Trade offset to start from. Defaults to 0. An offset past the end returns an
+     * empty `recentTrades` array, not an error.
+     */
+    offset?: number;
+}
 /** Generic preview wrapper used by PRO-gated endpoints. */
 interface EarningsEvent {
     ticker: string;
@@ -2194,8 +2340,23 @@ declare class Politicians {
      * Get detailed profile for a single politician: summary, recent trades, top tickers.
      *
      * PRO-gated. Free users receive a preview-wrapped response.
+     *
+     * `data.recentTrades` is one page of the member's history, not all of it. Most members
+     * have a few dozen disclosures and arrive complete in the default page; a handful have
+     * thousands. `totalCount` on the envelope is the size of the whole history on every
+     * tier, so page with `limit` and `offset` rather than reading `recentTrades.length` as
+     * the total. `data.profile` and `data.topTickers` describe the whole history whatever
+     * page you ask for, so `profile.totalTrades` does not shrink with a small `limit`.
+     *
+     * ```typescript
+     * const first = await client.politicians.getMember("Ro-Khanna", { limit: 500 });
+     * for (let offset = 500; offset < first.totalCount!; offset += 500) {
+     *   const page = await client.politicians.getMember("Ro-Khanna", { limit: 500, offset });
+     *   // ... page.data.recentTrades
+     * }
+     * ```
      */
-    getMember(slug: string): Promise<PreviewResponse<PoliticianDetail>>;
+    getMember(slug: string, options?: GetPoliticianMemberOptions): Promise<PreviewResponse<PoliticianDetail>>;
 }
 
 interface GetStockInsightsRangeOptions {
@@ -2570,6 +2731,28 @@ declare class Stocks {
      * Auth: API key required, no quota cost. 404 if the ticker has no curated KPIs.
      */
     getKpiTypes(ticker: string): Promise<KpiTypeEntry[]>;
+    /**
+     * Get the end-of-day options dossier for one stock or ETF: the session's aggregate, its
+     * percentile context, the open-interest wall structure with max pain, and the contracts
+     * whose volume ran far ahead of their open interest.
+     *
+     * End of day, not live. `asOf` is the prior trading session and the data refreshes the
+     * following morning, so this is positioning, not a quote feed.
+     *
+     * **`data` is `null` for a ticker outside the covered universe**, which is the most
+     * actively optioned US names plus the tracked ETFs, and for a covered ticker with no
+     * snapshot yet. An unknown symbol behaves the same way rather than answering 404, so treat
+     * a null as "no coverage", never as an error. A covered ticker still building its baseline
+     * returns its raw readings with the percentiles omitted.
+     *
+     * Percentiles compare a ticker to its own trailing history, never to another ticker, so an
+     * ETF's readings are not comparable with a single stock's.
+     *
+     * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
+     * ten calls each calendar month and a headline-only preview after that, with `isPreview`
+     * true; calls that return a null `data` never spend that allowance.
+     */
+    getOptionsSummary(ticker: string): Promise<PreviewResponse<OptionsSummary | null>>;
 }
 
 /**
@@ -2662,6 +2845,7 @@ declare class SentiSense implements APIClient {
     private apiKey;
     private timeout;
     private maxRetries;
+    private userAgent;
     readonly stocks: Stocks;
     readonly documents: Documents;
     readonly etfs: Etfs;
@@ -2724,6 +2908,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.40.0";
+declare const VERSION = "0.42.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 EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockPrice, type StockProfile, type StockQuote, type Story, type StoryCluster, type TickerHolders, type TrackerEvent, type TrackerGeoEntry, type TrackerHeadlineMetric, type TrackerListResponse, type TrackerListing, type TrackerMetricValue, type TrackerSignal, type TrackerSnapshot, type TrackerSnapshotResponse, type TrackerSourceRef, type TrackerTableRow, type TrackerTimeSeriesPoint, type TtmFundamentals, VERSION, type WeightedConsensus, type WeightedNetFlow, SentiSense as default };
+export { type AISummary, APIError, type AnalystAction, type AnalystConsensus, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AssetMetadata, AuthenticationError, type CalendarMeta, type ChartData, type ChartDataPoint, type ClusterBuy, type CompanyKpisData, type CongressTrade, DeepHistoryUnavailableError, type Document, type DocumentSearchResponse, type DocumentSource, type EarningsCalendarResponse, type EarningsEvent, type EarningsKpiHighlight, type EarningsQuarter, type EarningsSource, type EtfAggregateCoverage, type EtfAnalystAggregate, type EtfAnalystContributor, type EtfHolding, type EtfHoldings, type EtfInfo, type EtfInsiderAggregate, type EtfInsiderContributor, type EtfScreenerExecuteResponse, type EtfScreenerRow, type EtfSentimentAggregate, type EtfSentimentReading, type FeaturedScreen, type FloatInfo, type Fundamentals, type FundamentalsPeriod, type FundamentalsPeriodsResponse, type GetAnalystActionsOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetPoliticianActivityOptions, type GetPoliticianDirectoryOptions, type GetPoliticianMemberOptions, type GetPoliticiansOptions, type GetRecentEarningsOptions, type GetStockInsightsRangeOptions, type GetUserInsightsOptions, type Holder, type HolderNotableChanges, type IndexConstituent, type IndexHistoryPoint, type IndexHistoryResponse, type IndexListResponse, type IndexListing, type IndexSnapshot, type InsiderActivityResponse, type InsiderActivitySummary, type InsiderTrade, type Insight, type InsightPreviewResponse, type InstitutionList, type InstitutionListResponse, type InstitutionSummary, type InstitutionalFlow, type InstitutionalFlows, type InstitutionalFlowsResponse, type KBEntity, type KpiCoverageEntry, type KpiCoverageResponse, type KpiDataPoint, type KpiSeries, type KpiTypeEntry, type ListInstitutionsOptions, type LockedInsight, type MarketMood, type MarketStatus, type MarketSummary, type MetricDistribution, type MetricDistributionOptions, type MetricType, type MetricsBreakdown, type MetricsOptions, NotFoundError, type OptionsAggregate, type OptionsContext, type OptionsOiWalls, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RecentEarningsEntry, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, 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 };

package/dist/index.mjs

@@ -398,10 +398,26 @@ var Politicians = class {
    * Get detailed profile for a single politician: summary, recent trades, top tickers.
    *
    * PRO-gated. Free users receive a preview-wrapped response.
+   *
+   * `data.recentTrades` is one page of the member's history, not all of it. Most members
+   * have a few dozen disclosures and arrive complete in the default page; a handful have
+   * thousands. `totalCount` on the envelope is the size of the whole history on every
+   * tier, so page with `limit` and `offset` rather than reading `recentTrades.length` as
+   * the total. `data.profile` and `data.topTickers` describe the whole history whatever
+   * page you ask for, so `profile.totalTrades` does not shrink with a small `limit`.
+   *
+   * ```typescript
+   * const first = await client.politicians.getMember("Ro-Khanna", { limit: 500 });
+   * for (let offset = 500; offset < first.totalCount!; offset += 500) {
+   *   const page = await client.politicians.getMember("Ro-Khanna", { limit: 500, offset });
+   *   // ... page.data.recentTrades
+   * }
+   * ```
    */
-  async getMember(slug) {
+  async getMember(slug, options) {
     return this.client.get(
-      `/api/v1/politicians/member/${encodeURIComponent(slug)}`
+      `/api/v1/politicians/member/${encodeURIComponent(slug)}`,
+      options
     );
   }
 };
@@ -881,6 +897,32 @@ var Stocks = class {
       `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/kpis/types`
     );
   }
+  /**
+   * Get the end-of-day options dossier for one stock or ETF: the session's aggregate, its
+   * percentile context, the open-interest wall structure with max pain, and the contracts
+   * whose volume ran far ahead of their open interest.
+   *
+   * End of day, not live. `asOf` is the prior trading session and the data refreshes the
+   * following morning, so this is positioning, not a quote feed.
+   *
+   * **`data` is `null` for a ticker outside the covered universe**, which is the most
+   * actively optioned US names plus the tracked ETFs, and for a covered ticker with no
+   * snapshot yet. An unknown symbol behaves the same way rather than answering 404, so treat
+   * a null as "no coverage", never as an error. A covered ticker still building its baseline
+   * returns its raw readings with the percentiles omitted.
+   *
+   * Percentiles compare a ticker to its own trailing history, never to another ticker, so an
+   * ETF's readings are not comparable with a single stock's.
+   *
+   * Tiering: a PRO key always receives the full dossier. A FREE key receives it for the first
+   * ten calls each calendar month and a headline-only preview after that, with `isPreview`
+   * true; calls that return a null `data` never spend that allowance.
+   */
+  async getOptionsSummary(ticker) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/options/summary`
+    );
+  }
 };
 
 // src/resources/indexes.ts
@@ -960,7 +1002,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.40.0";
+var VERSION = "0.42.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -990,6 +1032,8 @@ var SentiSense = class {
     this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    const suffix = options.userAgentSuffix?.replace(/[\r\n]+/g, " ").trim();
+    this.userAgent = suffix ? `sentisense-node/${VERSION} ${suffix}` : `sentisense-node/${VERSION}`;
     this.stocks = new Stocks(this);
     this.documents = new Documents(this);
     this.etfs = new Etfs(this);
@@ -1018,7 +1062,7 @@ var SentiSense = class {
       headers["X-SentiSense-API-Key"] = this.apiKey;
     }
     if (typeof process !== "undefined" && process.versions?.node) {
-      headers["User-Agent"] = `sentisense-node/${VERSION}`;
+      headers["User-Agent"] = this.userAgent;
     }
     let delayMs = 0;
     for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
@@ -1099,7 +1143,7 @@ var SentiSense = class {
       headers["X-SentiSense-API-Key"] = this.apiKey;
     }
     if (typeof process !== "undefined" && process.versions?.node) {
-      headers["User-Agent"] = `sentisense-node/${VERSION}`;
+      headers["User-Agent"] = this.userAgent;
     }
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeout);