sentisense 0.52.0 → 0.54.0

package/dist/index.d.mts

@@ -453,6 +453,26 @@ interface OptionsAggregate {
     /** Raw 25-delta call and put implied volatilities. */
     iv25c?: number;
     iv25p?: number;
+    /**
+     * Calibrated 90% expected move over 1 trading session, as a fraction of price, so `0.0407`
+     * is 4.07%. `k * atmIv * Math.sqrt(h / 252)` with an empirical `k` (1.48 here) fit on
+     * SentiSense's own stored option history. The 90% is a measured historical coverage rate,
+     * not a guarantee, and the range carries no direction and no price target.
+     */
+    expectedMove1d?: number;
+    /** The same calibrated 90% range over 5 trading sessions (`k` = 1.56). */
+    expectedMove5d?: number;
+    /** The same calibrated 90% range over 20 trading sessions (`k` = 1.56). */
+    expectedMove20d?: number;
+    /**
+     * One-sigma expected move over 1 trading session, `atmIv * Math.sqrt(h / 252)`: the industry
+     * convention, roughly 68% of moves, with no calibration applied.
+     */
+    expectedMove1s1d?: number;
+    /** One-sigma expected move over 5 trading sessions. */
+    expectedMove1s5d?: number;
+    /** One-sigma expected move over 20 trading sessions. */
+    expectedMove1s20d?: number;
     netDelta?: number;
     notionalVol?: number;
     contracts?: number;
@@ -600,6 +620,18 @@ interface OptionsOverviewRow {
     notionalVol?: number;
     /** Signed change of `atmIv` against its ~20-session mean. Rank "biggest IV moves" by absolute value. */
     ivMove20?: number;
+    /** Calibrated 90% expected move over 1 trading session, as a fraction of price. */
+    expectedMove1d?: number;
+    /** The same calibrated 90% range over 5 trading sessions. */
+    expectedMove5d?: number;
+    /** The same calibrated 90% range over 20 trading sessions. */
+    expectedMove20d?: number;
+    /** One-sigma expected move over 1 trading session: the industry convention, uncalibrated. */
+    expectedMove1s1d?: number;
+    /** One-sigma expected move over 5 trading sessions. */
+    expectedMove1s5d?: number;
+    /** One-sigma expected move over 20 trading sessions. */
+    expectedMove1s20d?: number;
     /** Trailing-1y observation count, which is what drives the building-baseline state. */
     observations1y?: number;
     /** Unusually-active contracts this session. */
@@ -657,8 +689,8 @@ interface OptionsOverview {
     /** Full ETF board size on a FREE response, mirroring what the envelope's `totalCount` does for stocks. */
     etfTotalCount?: number;
 }
-/** The six dimensions the composite is blended from, by stable `key`. */
-type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings";
+/** The seven dimensions the composite is blended from, by stable `key`. */
+type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings" | "technicals";
 /**
  * Why a stock has no grade.
  *
@@ -703,9 +735,9 @@ interface RatingSubLeg {
     unit: string;
 }
 /**
- * One of the six dimensions the composite is blended from.
+ * One of the seven dimensions the composite is blended from.
  *
- * **All six always arrive, in a fixed order, whether or not they had data.** An absent
+ * **All seven always arrive, in a fixed order, whether or not they had data.** An absent
  * dimension is a full row with `present` false and a `null` percentile; the server never
  * drops it, precisely so a client cannot mistake a gap for a five-dimension rating. Read
  * `present` before reading `percentile`, and never substitute zero for a `null`: zero is the
@@ -749,7 +781,7 @@ interface RatingBase {
     kbEntityId: string;
     /** The New York calendar day this answer describes, `"YYYY-MM-DD"`. */
     asOf: string;
-    /** Always all six, in a fixed order, absent ones with `present` false. */
+    /** Always all seven, in a fixed order, absent ones with `present` false. */
     dimensions: RatingDimension[];
     flags: RatingFlag[];
     /** The standard financial disclaimer. Display it alongside the grade. */
@@ -821,7 +853,7 @@ interface StockNotRated extends RatingBase {
     rated: false;
     /** Why there is no grade. */
     reason: RatingNotRatedReason;
-    /** How many of the six dimensions had data. */
+    /** How many of the seven dimensions had data. */
     dimensionsPresent?: number;
     /** Which dimensions had data, by `key`. */
     presentDimensions: RatingDimensionKey[];
@@ -892,6 +924,37 @@ interface StoryCluster {
     averageSentiment: number;
     /** Unix timestamp in seconds when the cluster was assembled by our pipeline. */
     clusteredAt: number;
+    /**
+     * How the story was authored: `"ORIGINAL"` for an editorially authored SentiSense
+     * Original, `"AI"` for a pipeline-generated story. Optional because an older API
+     * build omits it, in which case it is `undefined` rather than `"AI"`.
+     */
+    storySource?: "ORIGINAL" | "AI";
+    /**
+     * True while the story is still being revised as the event develops. Optional
+     * because an older API build omits it, in which case it is `undefined` rather than
+     * `false`: read that as "not known", not as "settled".
+     */
+    isLive?: boolean;
+}
+/**
+ * One dated update on a live story, as served inside the story detail response's
+ * `timeline` array (newest first, empty when a story has none).
+ *
+ * `documents.getStoryDetail()` returns `unknown`, so this type is exported for callers
+ * that narrow the response themselves.
+ */
+interface StoryTimelineEntry {
+    /** Publication time of this update, Unix milliseconds. */
+    publishedAt: number;
+    /**
+     * `"INITIAL"`, `"UPDATE"` or `"CORRECTION"`. Left open: an unrecognised label is
+     * served through rather than rejected, so branch on the three known values and let
+     * anything else fall through to a neutral rendering.
+     */
+    updateType: "INITIAL" | "UPDATE" | "CORRECTION" | (string & {});
+    /** The update text, markdown. */
+    content: string;
 }
 interface Story {
     cluster: StoryCluster;
@@ -1210,6 +1273,8 @@ interface InsiderTrade {
     transactionCode: string;
     transactionType: "BUY" | "SELL" | "EXERCISE" | "AWARD" | "GIFT" | "OTHER";
     securityTitle: string;
+    /** The security the row was filed in when it is not the US listing `ticker` names (e.g. "Common Shares (2330.TW)"); null on the ordinary case, and when set `pricePerShare` is null because the filed price is per foreign ordinary share. */
+    securityBasis?: string | null;
     sharesTransacted: number;
     pricePerShare: number | null;
     totalValue: number;
@@ -1539,9 +1604,33 @@ interface GetRecentEarningsOptions {
     /** Max rows returned, 1 to 100. Omitted, the API applies its own default of 50. */
     limit?: number;
 }
+/**
+ * What lifts the gate on a preview response, in a form you can show a user directly.
+ *
+ * Present only when `isPreview` is `true`. Every field is optional: the copy and the
+ * offer are set server-side and can change without an SDK release, so read what is
+ * there rather than depending on any one field.
+ */
+interface UpgradeHint {
+    /** Plan that lifts the gate, e.g. `"PRO"`. */
+    plan?: string;
+    /** One sentence naming what was withheld. Safe to show verbatim. */
+    message?: string;
+    /** Current price, including any active discount code. */
+    price?: string;
+    /** Where to complete the upgrade. */
+    url?: string;
+    /** What an automated caller should do with this object. */
+    relay?: string;
+}
 interface PreviewResponse<T> {
     isPreview: boolean;
     previewReason: "PRO_REQUIRED" | null;
+    /**
+     * How to lift the gate. Present only on a preview; absent from full responses.
+     * Surface `message` and `url` to your user rather than hard-coding a price.
+     */
+    upgrade?: UpgradeHint;
     /**
      * Size of the full result set, before any truncation your response went through.
      *
@@ -1896,6 +1985,8 @@ interface TrackerSnapshotResponse {
     previewReason: "PRO_REQUIRED" | null;
     /** Full row count before truncation. Only set on preview responses. */
     totalCount?: number;
+    /** How to lift the gate. Only set on preview responses. */
+    upgrade?: UpgradeHint;
     data: TrackerSnapshot;
 }
 /** Per-index discovery row returned by `client.indexes.list()`. */
@@ -2607,7 +2698,14 @@ declare class Documents {
     getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<DocumentSearchResponse>;
     /** Get AI-curated news story clusters. */
     getStories(options?: GetStoriesOptions): Promise<Story[]>;
-    /** Get full story detail by cluster ID. */
+    /**
+     * Get full story detail by cluster ID.
+     *
+     * Deliberately untyped: narrow it yourself. The response carries `storySource` and
+     * `isLive` alongside the story body, plus a `timeline` array of dated updates,
+     * newest first and empty when the story has none. {@link StoryTimelineEntry} is
+     * exported for that array.
+     */
     getStoryDetail(clusterId: string): Promise<unknown>;
     /** Get stories for a specific stock. */
     getStoriesByTicker(ticker: string, options?: GetStoriesByTickerOptions): Promise<Story[]>;
@@ -2702,12 +2800,19 @@ interface EtfInfo {
     imageUrl: string | null;
 }
 interface EtfHolding {
+    /** The symbol as the issuer filed it. For an international fund this is the local exchange code, not a US ticker, so resolve stocks with `linkedTicker` instead. */
     ticker: string;
     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. */
     firstSeen: string | null;
+    /** Listing venue the issuer reported for this position, verbatim (e.g. "NYSE", "SIX Swiss Exchange"). Null when the source carries no venue column. */
+    exchange?: string | null;
+    /** The symbol as listed on `exchange`. Same value as `ticker`, named to make it clear the symbol is venue-local and may not identify a US company. */
+    localTicker?: string | null;
+    /** The US stock symbol this holding resolves to, or null when it cannot be resolved to one. */
+    linkedTicker?: string | null;
 }
 interface EtfHoldings {
     ticker: string;
@@ -3639,6 +3744,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.52.0";
+declare const VERSION = "0.54.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EntitySearchResult, type EntitySearchType, 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 GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, 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 OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, 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 AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EntitySearchResult, type EntitySearchType, 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 GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, 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 OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, 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

@@ -453,6 +453,26 @@ interface OptionsAggregate {
     /** Raw 25-delta call and put implied volatilities. */
     iv25c?: number;
     iv25p?: number;
+    /**
+     * Calibrated 90% expected move over 1 trading session, as a fraction of price, so `0.0407`
+     * is 4.07%. `k * atmIv * Math.sqrt(h / 252)` with an empirical `k` (1.48 here) fit on
+     * SentiSense's own stored option history. The 90% is a measured historical coverage rate,
+     * not a guarantee, and the range carries no direction and no price target.
+     */
+    expectedMove1d?: number;
+    /** The same calibrated 90% range over 5 trading sessions (`k` = 1.56). */
+    expectedMove5d?: number;
+    /** The same calibrated 90% range over 20 trading sessions (`k` = 1.56). */
+    expectedMove20d?: number;
+    /**
+     * One-sigma expected move over 1 trading session, `atmIv * Math.sqrt(h / 252)`: the industry
+     * convention, roughly 68% of moves, with no calibration applied.
+     */
+    expectedMove1s1d?: number;
+    /** One-sigma expected move over 5 trading sessions. */
+    expectedMove1s5d?: number;
+    /** One-sigma expected move over 20 trading sessions. */
+    expectedMove1s20d?: number;
     netDelta?: number;
     notionalVol?: number;
     contracts?: number;
@@ -600,6 +620,18 @@ interface OptionsOverviewRow {
     notionalVol?: number;
     /** Signed change of `atmIv` against its ~20-session mean. Rank "biggest IV moves" by absolute value. */
     ivMove20?: number;
+    /** Calibrated 90% expected move over 1 trading session, as a fraction of price. */
+    expectedMove1d?: number;
+    /** The same calibrated 90% range over 5 trading sessions. */
+    expectedMove5d?: number;
+    /** The same calibrated 90% range over 20 trading sessions. */
+    expectedMove20d?: number;
+    /** One-sigma expected move over 1 trading session: the industry convention, uncalibrated. */
+    expectedMove1s1d?: number;
+    /** One-sigma expected move over 5 trading sessions. */
+    expectedMove1s5d?: number;
+    /** One-sigma expected move over 20 trading sessions. */
+    expectedMove1s20d?: number;
     /** Trailing-1y observation count, which is what drives the building-baseline state. */
     observations1y?: number;
     /** Unusually-active contracts this session. */
@@ -657,8 +689,8 @@ interface OptionsOverview {
     /** Full ETF board size on a FREE response, mirroring what the envelope's `totalCount` does for stocks. */
     etfTotalCount?: number;
 }
-/** The six dimensions the composite is blended from, by stable `key`. */
-type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings";
+/** The seven dimensions the composite is blended from, by stable `key`. */
+type RatingDimensionKey = "crowd" | "smart_money" | "options" | "analysts" | "fundamentals" | "earnings" | "technicals";
 /**
  * Why a stock has no grade.
  *
@@ -703,9 +735,9 @@ interface RatingSubLeg {
     unit: string;
 }
 /**
- * One of the six dimensions the composite is blended from.
+ * One of the seven dimensions the composite is blended from.
  *
- * **All six always arrive, in a fixed order, whether or not they had data.** An absent
+ * **All seven always arrive, in a fixed order, whether or not they had data.** An absent
  * dimension is a full row with `present` false and a `null` percentile; the server never
  * drops it, precisely so a client cannot mistake a gap for a five-dimension rating. Read
  * `present` before reading `percentile`, and never substitute zero for a `null`: zero is the
@@ -749,7 +781,7 @@ interface RatingBase {
     kbEntityId: string;
     /** The New York calendar day this answer describes, `"YYYY-MM-DD"`. */
     asOf: string;
-    /** Always all six, in a fixed order, absent ones with `present` false. */
+    /** Always all seven, in a fixed order, absent ones with `present` false. */
     dimensions: RatingDimension[];
     flags: RatingFlag[];
     /** The standard financial disclaimer. Display it alongside the grade. */
@@ -821,7 +853,7 @@ interface StockNotRated extends RatingBase {
     rated: false;
     /** Why there is no grade. */
     reason: RatingNotRatedReason;
-    /** How many of the six dimensions had data. */
+    /** How many of the seven dimensions had data. */
     dimensionsPresent?: number;
     /** Which dimensions had data, by `key`. */
     presentDimensions: RatingDimensionKey[];
@@ -892,6 +924,37 @@ interface StoryCluster {
     averageSentiment: number;
     /** Unix timestamp in seconds when the cluster was assembled by our pipeline. */
     clusteredAt: number;
+    /**
+     * How the story was authored: `"ORIGINAL"` for an editorially authored SentiSense
+     * Original, `"AI"` for a pipeline-generated story. Optional because an older API
+     * build omits it, in which case it is `undefined` rather than `"AI"`.
+     */
+    storySource?: "ORIGINAL" | "AI";
+    /**
+     * True while the story is still being revised as the event develops. Optional
+     * because an older API build omits it, in which case it is `undefined` rather than
+     * `false`: read that as "not known", not as "settled".
+     */
+    isLive?: boolean;
+}
+/**
+ * One dated update on a live story, as served inside the story detail response's
+ * `timeline` array (newest first, empty when a story has none).
+ *
+ * `documents.getStoryDetail()` returns `unknown`, so this type is exported for callers
+ * that narrow the response themselves.
+ */
+interface StoryTimelineEntry {
+    /** Publication time of this update, Unix milliseconds. */
+    publishedAt: number;
+    /**
+     * `"INITIAL"`, `"UPDATE"` or `"CORRECTION"`. Left open: an unrecognised label is
+     * served through rather than rejected, so branch on the three known values and let
+     * anything else fall through to a neutral rendering.
+     */
+    updateType: "INITIAL" | "UPDATE" | "CORRECTION" | (string & {});
+    /** The update text, markdown. */
+    content: string;
 }
 interface Story {
     cluster: StoryCluster;
@@ -1210,6 +1273,8 @@ interface InsiderTrade {
     transactionCode: string;
     transactionType: "BUY" | "SELL" | "EXERCISE" | "AWARD" | "GIFT" | "OTHER";
     securityTitle: string;
+    /** The security the row was filed in when it is not the US listing `ticker` names (e.g. "Common Shares (2330.TW)"); null on the ordinary case, and when set `pricePerShare` is null because the filed price is per foreign ordinary share. */
+    securityBasis?: string | null;
     sharesTransacted: number;
     pricePerShare: number | null;
     totalValue: number;
@@ -1539,9 +1604,33 @@ interface GetRecentEarningsOptions {
     /** Max rows returned, 1 to 100. Omitted, the API applies its own default of 50. */
     limit?: number;
 }
+/**
+ * What lifts the gate on a preview response, in a form you can show a user directly.
+ *
+ * Present only when `isPreview` is `true`. Every field is optional: the copy and the
+ * offer are set server-side and can change without an SDK release, so read what is
+ * there rather than depending on any one field.
+ */
+interface UpgradeHint {
+    /** Plan that lifts the gate, e.g. `"PRO"`. */
+    plan?: string;
+    /** One sentence naming what was withheld. Safe to show verbatim. */
+    message?: string;
+    /** Current price, including any active discount code. */
+    price?: string;
+    /** Where to complete the upgrade. */
+    url?: string;
+    /** What an automated caller should do with this object. */
+    relay?: string;
+}
 interface PreviewResponse<T> {
     isPreview: boolean;
     previewReason: "PRO_REQUIRED" | null;
+    /**
+     * How to lift the gate. Present only on a preview; absent from full responses.
+     * Surface `message` and `url` to your user rather than hard-coding a price.
+     */
+    upgrade?: UpgradeHint;
     /**
      * Size of the full result set, before any truncation your response went through.
      *
@@ -1896,6 +1985,8 @@ interface TrackerSnapshotResponse {
     previewReason: "PRO_REQUIRED" | null;
     /** Full row count before truncation. Only set on preview responses. */
     totalCount?: number;
+    /** How to lift the gate. Only set on preview responses. */
+    upgrade?: UpgradeHint;
     data: TrackerSnapshot;
 }
 /** Per-index discovery row returned by `client.indexes.list()`. */
@@ -2607,7 +2698,14 @@ declare class Documents {
     getBySource(source: DocumentSource, options?: GetBySourceOptions): Promise<DocumentSearchResponse>;
     /** Get AI-curated news story clusters. */
     getStories(options?: GetStoriesOptions): Promise<Story[]>;
-    /** Get full story detail by cluster ID. */
+    /**
+     * Get full story detail by cluster ID.
+     *
+     * Deliberately untyped: narrow it yourself. The response carries `storySource` and
+     * `isLive` alongside the story body, plus a `timeline` array of dated updates,
+     * newest first and empty when the story has none. {@link StoryTimelineEntry} is
+     * exported for that array.
+     */
     getStoryDetail(clusterId: string): Promise<unknown>;
     /** Get stories for a specific stock. */
     getStoriesByTicker(ticker: string, options?: GetStoriesByTickerOptions): Promise<Story[]>;
@@ -2702,12 +2800,19 @@ interface EtfInfo {
     imageUrl: string | null;
 }
 interface EtfHolding {
+    /** The symbol as the issuer filed it. For an international fund this is the local exchange code, not a US ticker, so resolve stocks with `linkedTicker` instead. */
     ticker: string;
     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. */
     firstSeen: string | null;
+    /** Listing venue the issuer reported for this position, verbatim (e.g. "NYSE", "SIX Swiss Exchange"). Null when the source carries no venue column. */
+    exchange?: string | null;
+    /** The symbol as listed on `exchange`. Same value as `ticker`, named to make it clear the symbol is venue-local and may not identify a US company. */
+    localTicker?: string | null;
+    /** The US stock symbol this holding resolves to, or null when it cannot be resolved to one. */
+    linkedTicker?: string | null;
 }
 interface EtfHoldings {
     ticker: string;
@@ -3639,6 +3744,6 @@ declare class APIError extends SentiSenseError {
     constructor(message: string, status: number, code?: string);
 }
 
-declare const VERSION = "0.52.0";
+declare const VERSION = "0.54.0";
 
-export { type AISummary, APIError, type AnalystAction, type AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EntitySearchResult, type EntitySearchType, 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 GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, 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 OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, 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 AnalystCall, type AnalystConsensus, type AnalystCoverage, type AnalystCoverageAnalyst, type AnalystCoverageBookEntry, type AnalystCoverageFirm, type AnalystEarningsSurprise, type AnalystEstimate, type AnalystEstimatesResponse, type AnalystFirmRating, type AnalystFirmTenure, type AnalystNote, type AnalystProfile, type AnalystRatingBuckets, 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 EntitySearchResult, type EntitySearchType, 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 GetAnalystCallsOptions, type GetAnalystCoverageOptions, type GetAnalystMarketActivityOptions, type GetEarningsCalendarOptions, type GetEarningsSummariesOptions, type GetEtfInsiderAggregateOptions, type GetHoldersOptions, type GetInsiderOptions, type GetInsightsOptions, type GetLatestInsightsOptions, type GetOptionsHistoryOptions, 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 OptionsHistory, type OptionsHistoryWindow, type OptionsOiWalls, type OptionsOverview, type OptionsOverviewRow, type OptionsSummary, type OptionsUnusualContract, type OptionsWall, type PoliticianDetail, type PoliticianDirectory, type PoliticianDirectoryEntry, type PoliticianDirectoryResponse, type PoliticianSummary, type PreviewResponse, type Quarter, RateLimitError, type RatingBase, type RatingDimension, type RatingDimensionKey, type RatingFlag, type RatingNotRatedReason, type RatingSubLeg, type RecentEarningsEntry, type RiskAdjustment, type RiskCondition, type ScreenerExecuteOptions, type ScreenerExecuteResponse, type ScreenerFieldCatalog, type ScreenerFieldDescriptor, type ScreenerFieldOption, type ScreenerFilter, type ScreenerPlan, type ScreenerRow, type ScreenerScreensResponse, type ScreenerSort, type SearchEntitiesOptions, SentiSense, SentiSenseError, type SentiSenseOptions, type SentimentEntry, type ServingMetric, type ShortInterest, type ShortVolume, type SimilarStock, type StockDetail, type StockEntity, type StockImage, type StockNotRated, type StockPrice, type StockProfile, type StockQuote, type StockRating, type StockRatingResponse, type StockSocialDominance, type Story, type StoryCluster, type StoryTimelineEntry, 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

@@ -221,7 +221,14 @@ var Documents = class {
   async getStories(options) {
     return this.client.get("/api/v1/documents/stories", options);
   }
-  /** Get full story detail by cluster ID. */
+  /**
+   * Get full story detail by cluster ID.
+   *
+   * Deliberately untyped: narrow it yourself. The response carries `storySource` and
+   * `isLive` alongside the story body, plus a `timeline` array of dated updates,
+   * newest first and empty when the story has none. {@link StoryTimelineEntry} is
+   * exported for that array.
+   */
   async getStoryDetail(clusterId) {
     return this.client.get(`/api/v1/documents/stories/${encodeURIComponent(clusterId)}`);
   }
@@ -1208,7 +1215,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.52.0";
+var VERSION = "0.54.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";