@livefolio/sdk 0.5.0-rc.4 → 0.5.0-rc.5

package/dist/index.d.ts

@@ -1651,6 +1651,26 @@ type CashEvent = {
      */
     reason?: 'deposit' | 'withdrawal' | 'interest' | 'dividend';
 };
+/** How dividends are handled during a backtest. `reinvest: true` enables DRIP (dividend reinvestment). */
+type DividendsConfig = {
+    reinvest: boolean;
+};
+/**
+ * How idle cash earns interest during a backtest.
+ * - `none` — cash earns nothing (default).
+ * - `flat` — a constant annual percentage yield; daily rate is `apy / 365`.
+ * - `tbill` — track a macro yield series (default `DGS3MO`) minus `spread`, as `(yield/100 - spread) / 365`.
+ */
+type CashYieldConfig = {
+    kind: 'none';
+} | {
+    kind: 'flat';
+    apy: number;
+} | {
+    kind: 'tbill';
+    spread: number;
+    assetId?: AssetId;
+};
 /**
  * All inputs required to run a historical backtest.
  *
@@ -1715,6 +1735,32 @@ type RunBacktestOptions<F extends Features = Features, S = unknown> = {
      * fund withdrawals is deferred to a later release, so this behavior may change.
      */
     cashEvents?: ReadonlyArray<CashEvent>;
+    /**
+     * Optional dividend handling. When `dataFeed.dividends` exists, the universe's
+     * day-0 dividends are pre-fetched and dividends are applied to held lots on the
+     * first session on/after their `exDate`: cash mode credits cash, DRIP mode
+     * (`reinvest: true`) reinvests into a new lot at the unadjusted pay-date close.
+     *
+     * @remarks Default = no dividends applied unless `dataFeed.dividends` exists;
+     * `reinvest` defaults to `false` (cash mode).
+     * @remarks Static-universe assumption: dividends are queried once for the day-0
+     * universe (`strategy.universe(sessions[0], initialPortfolio)`). Assets that
+     * enter the universe on later sessions — e.g. a dynamic-universe strategy that
+     * opens a new position mid-run — will NOT have their dividends applied. This is
+     * a non-issue for `fromSpec` strategies, whose universe is statically declared.
+     */
+    dividends?: DividendsConfig;
+    /**
+     * Optional idle-cash interest accrual. Each session — after dividends, before
+     * the strategy runs — interest is accrued on positive cash at a daily rate
+     * resolved from this config (`flat` → `apy/365`; `tbill` → macro yield series
+     * `(yield/100 - spread)/365`, clamped ≥ 0). The interest is credited to cash,
+     * recorded as an `interest` `RealizedEvent` on the synthetic cash asset, and
+     * reported via `BacktestSnapshot.interestIncome`.
+     *
+     * @remarks Default = `{ kind: 'none' }` (no interest → today's behavior).
+     */
+    cashYield?: CashYieldConfig;
 };
 /**
  * A point-in-time snapshot of the simulation at the end of a single trading session.
@@ -1735,6 +1781,13 @@ type BacktestSnapshot = {
      * Net cash delta applied this session via `cashEvents`. Omitted when zero.
      */
     cashFlow?: number;
+    /** Dividend income recognized this session, split by qualified status. Omitted when zero. */
+    dividendIncome?: {
+        qualified: number;
+        ordinary: number;
+    };
+    /** Interest income accrued on cash this session. Omitted when zero. */
+    interestIncome?: number;
 };
 /**
  * The return value of `runBacktest`, containing the full simulation history
@@ -3994,25 +4047,166 @@ declare function computeTaxBill(income: TaxableIncome, rates: TaxRates): {
     };
 };
 
+/**
+ * Options for the 60-of-121-day qualified-dividend holding test.
+ *
+ * Both fields default to values for common stock dividends: the investor must
+ * have held the lot throughout the 60-day window ending at the ex-dividend date, within
+ * the 121-day window that begins 60 days before the ex-date.
+ */
+type QualificationOpts = {
+    /** Minimum days the lot must be held within the window. Defaults to `60`. */
+    holdingDaysRequired?: number;
+    /** Width of the holding window in calendar days. Defaults to `121`. */
+    windowDays?: number;
+};
+/**
+ * Determines whether a single {@link Lot} satisfies the IRS 60-of-121-day
+ * qualified-dividend holding requirement as of a given `exDate`.
+ *
+ * The 121-day window is centred on `exDate` with `half = floor(121 / 2) = 60`,
+ * so it spans the 60 days before `exDate`, the ex-date itself, and the 60 days
+ * after. Only days the lot was held **on or before** `exDate` count — `heldTo`
+ * is capped at `exDate` so future hold time never qualifies a dividend. This
+ * keeps the test lookahead-free and conservative: it never over-grants
+ * qualified status. Because `heldTo` is capped at `exDate`, the most a lot can
+ * accumulate is the 60-day run-up to the ex-date, so the default threshold of
+ * `60` models "held throughout the 60-day window ending at ex-date"
+ * (`60 >= 60`). Returns `true` when the days held within the window are
+ * `>= holdingDaysRequired`.
+ *
+ * @param lot - The tax lot to test.
+ * @param exDate - The dividend ex-dividend date.
+ * @param opts - Optional overrides for `holdingDaysRequired` (default `60` —
+ *   "held throughout the 60-day window ending at ex-date") and `windowDays`
+ *   (default `121`).
+ * @returns `true` when the lot satisfies the holding-period test.
+ */
+declare function isQualifiedForLot(lot: Lot, exDate: Date, opts?: QualificationOpts): boolean;
+/**
+ * The result of {@link distributeDividend}: per-lot cash amounts with
+ * qualified/ordinary classification, plus rolled-up totals.
+ */
+type DividendDistribution = {
+    /** Rolled-up qualified and ordinary dividend totals across all participating lots. */
+    totals: {
+        qualified: number;
+        ordinary: number;
+    };
+    /** One entry per participating lot: the cash received and whether it is qualified. */
+    perLot: {
+        lotId: string;
+        cash: number;
+        qualified: boolean;
+    }[];
+};
+/**
+ * Distributes a {@link DividendEvent} across a set of lots held at the
+ * ex-dividend date, classifying each lot's income as qualified or ordinary.
+ *
+ * Only lots that pass all three eligibility tests participate:
+ * - `quantity > 0`
+ * - `openDate <= exDate` (lot was open before or on the ex-date)
+ * - `asset.id === event.asset.id` (same asset)
+ *
+ * For `incomeKind: 'ordinary'` or `'interest'` events every participating lot
+ * is classified as ordinary regardless of how long it was held. For
+ * `'qualified-eligible'` events each lot is tested individually via
+ * {@link isQualifiedForLot} using the default 60-of-121-day rule.
+ *
+ * @param event - The dividend event to distribute.
+ * @param lotsHeldAtExDate - All lots in the portfolio at the ex-dividend date
+ *   (the function filters to eligible ones internally).
+ * @returns A {@link DividendDistribution} with per-lot breakdown and rolled-up totals.
+ */
+declare function distributeDividend(event: DividendEvent, lotsHeldAtExDate: readonly Lot[]): DividendDistribution;
+/**
+ * Converts dividend cash into a new whole-share DRIP tax lot at the pay-date price.
+ *
+ * Computes `shares = floor(cashAvailable / pricePayDate)` and opens a fresh
+ * {@link Lot} with `openDate = payDate`, `openPrice = pricePayDate`,
+ * `basis = shares * pricePayDate`, and `dripParent` set to the originating lot
+ * id. Any fractional-share remainder is returned as `residual`.
+ *
+ * When `cashAvailable` is less than one share (`shares === 0`), `newLot.quantity`
+ * will be `0` and `residual` will equal `cashAvailable`. The caller is
+ * responsible for skipping zero-quantity lots.
+ *
+ * @param cashAvailable - Total dividend cash to reinvest.
+ * @param asset - The asset being purchased.
+ * @param pricePayDate - Share price on the dividend pay date.
+ * @param payDate - The dividend pay date; becomes `openDate` on the new lot.
+ * @param dripParent - Id of the originating lot that generated the dividend cash.
+ * @returns An object with `newLot` (the freshly created {@link Lot}) and
+ *   `residual` (uninvested cash remainder).
+ */
+declare function reinvestDividend(cashAvailable: number, asset: Asset, pricePayDate: number, payDate: Date, dripParent: string): {
+    newLot: Lot;
+    residual: number;
+};
+
+/**
+ * Result of a single {@link accrueCashInterest} call: the updated cash balance
+ * and the interest earned in that session.
+ */
+type CashInterestResult = {
+    /** Cash balance after interest has been credited: `cash + interest`. */
+    newCash: number;
+    /** Interest earned in this session: `cash * dailyRate`. */
+    interest: number;
+};
+/**
+ * Pure per-session interest accrual using the actual/365 day-count convention.
+ *
+ * Computes simple (non-compounding within a single call) interest for one
+ * trading session. To model compounding over multiple sessions, call this
+ * function repeatedly, passing the returned `newCash` as `cash` in each
+ * subsequent call.
+ *
+ * `dailyRate` should be `APY / 365` for an actual/365 day-count (e.g.
+ * `0.05 / 365` for a 5% APY). A daily rate of `0` returns the original cash
+ * balance with zero interest.
+ *
+ * @param cash - The current cash balance before interest is applied.
+ * @param dailyRate - The per-session interest rate expressed as a decimal
+ *   fraction (e.g. `0.05 / 365` for 5% APY on an actual/365 basis).
+ * @returns A {@link CashInterestResult} with `newCash` (updated balance) and
+ *   `interest` (amount earned this session).
+ *
+ * @example
+ * ```ts
+ * // Single session at 5% APY
+ * const { newCash, interest } = accrueCashInterest(10_000, 0.05 / 365);
+ * ```
+ */
+declare function accrueCashInterest(cash: number, dailyRate: number): CashInterestResult;
+
+type index_CashInterestResult = CashInterestResult;
+type index_DividendDistribution = DividendDistribution;
 type index_LotSlice = LotSlice;
 declare const index_ORDINARY_OFFSET_CAP: typeof ORDINARY_OFFSET_CAP;
+type index_QualificationOpts = QualificationOpts;
 type index_RealizeResult = RealizeResult;
 type index_TaxRates = TaxRates;
 type index_TaxableIncome = TaxableIncome;
+declare const index_accrueCashInterest: typeof accrueCashInterest;
 declare const index_aggregateByYear: typeof aggregateByYear;
 declare const index_bucketByTerm: typeof bucketByTerm;
 declare const index_computeTaxBill: typeof computeTaxBill;
 declare const index_crossOffset: typeof crossOffset;
+declare const index_distributeDividend: typeof distributeDividend;
 declare const index_holdingPeriodDays: typeof holdingPeriodDays;
 declare const index_isLongTerm: typeof isLongTerm;
+declare const index_isQualifiedForLot: typeof isQualifiedForLot;
 declare const index_netWithinBucket: typeof netWithinBucket;
 declare const index_realize: typeof realize;
+declare const index_reinvestDividend: typeof reinvestDividend;
 declare const index_selectFIFO: typeof selectFIFO;
 declare const index_selectHIFO: typeof selectHIFO;
 declare const index_selectLIFO: typeof selectLIFO;
 declare const index_selectMinTax: typeof selectMinTax;
 declare namespace index {
-  export { type index_LotSlice as LotSlice, index_ORDINARY_OFFSET_CAP as ORDINARY_OFFSET_CAP, type index_RealizeResult as RealizeResult, type index_TaxRates as TaxRates, type index_TaxableIncome as TaxableIncome, index_aggregateByYear as aggregateByYear, index_bucketByTerm as bucketByTerm, index_computeTaxBill as computeTaxBill, index_crossOffset as crossOffset, index_holdingPeriodDays as holdingPeriodDays, index_isLongTerm as isLongTerm, index_netWithinBucket as netWithinBucket, index_realize as realize, index_selectFIFO as selectFIFO, index_selectHIFO as selectHIFO, index_selectLIFO as selectLIFO, index_selectMinTax as selectMinTax };
+  export { type index_CashInterestResult as CashInterestResult, type index_DividendDistribution as DividendDistribution, type index_LotSlice as LotSlice, index_ORDINARY_OFFSET_CAP as ORDINARY_OFFSET_CAP, type index_QualificationOpts as QualificationOpts, type index_RealizeResult as RealizeResult, type index_TaxRates as TaxRates, type index_TaxableIncome as TaxableIncome, index_accrueCashInterest as accrueCashInterest, index_aggregateByYear as aggregateByYear, index_bucketByTerm as bucketByTerm, index_computeTaxBill as computeTaxBill, index_crossOffset as crossOffset, index_distributeDividend as distributeDividend, index_holdingPeriodDays as holdingPeriodDays, index_isLongTerm as isLongTerm, index_isQualifiedForLot as isQualifiedForLot, index_netWithinBucket as netWithinBucket, index_realize as realize, index_reinvestDividend as reinvestDividend, index_selectFIFO as selectFIFO, index_selectHIFO as selectHIFO, index_selectLIFO as selectLIFO, index_selectMinTax as selectMinTax };
 }
 
 /**
@@ -4128,4 +4322,4 @@ declare function applyOrders(portfolio: Portfolio, orders: ReadonlyArray<Order>)
  */
 declare function positionsByAsset(portfolio: Portfolio): Position[];
 
-export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CashEvent, CashEventQueue, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type DividendEvent, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };
+export { type AdhocTimeOverrides, type AdjustOrder, type AllocateNode, type Asset, type AssetId, type AssetRef, BacktestExecutor, type BacktestExecutorOptions, type BacktestResult, type BacktestSnapshot, type Bar, type BarField, type Calendar, type CashEvent, CashEventQueue, type CashInterestResult, type CashYieldConfig, type CloseOrder, type Comparison, type ComparisonOp, type ComputeFn, Crypto24x7Calendar, type DataEvent, type DataFeed, type DateRange, type DividendDistribution, type DividendEvent, type DividendsConfig, type EquityAsset, type EventKind, ExchangeCalendar, type ExchangeName, type Executor, type FeatureCache, type FeatureKey, type FeatureKind, type FeatureRef, FeatureRuntime, type FeatureRuntimeOptions, type FeatureScope, type FeatureSpec, type Features, type Fill, type Frequency, type FromSpecOptions, type Fundamentals, type HolidayRule, type IfNode, type IncomeKind, LSEExchangeCalendar, type LiveEvent, type Lot, type LotSlice, type MacroAsset, MemoryFeatureCache, NYSEExchangeCalendar, type NextOpenFn, ORDINARY_OFFSET_CAP, type OpenOrder, type Order, type PollingSchedule, type PollingStreamOptions, type Portfolio, type Position, type PositionId, type PriceMap, type QualificationOpts, type Quote, type QuoteFeed, type RealizeResult, type RealizedEvent, type RebalanceConfig, type RebalanceFrequency, type RebalanceOrder, type ReturnMode, RoutingDataFeed, RoutingDataFeedError, type RoutingDataFeedRouteFn, type RoutingDataFeedRouteMap, RoutingQuoteFeed, RoutingQuoteFeedError, type RoutingQuoteFeedRouteFn, type RoutingQuoteFeedRouteMap, RoutingStreamingDataFeed, RoutingStreamingDataFeedError, type RoutingStreamingDataFeedRouteFn, type RoutingStreamingDataFeedRouteMap, type RuleNode, type RuleTreeState, type RunBacktestOptions, type RunLiveOptions, type Series, type Session, type SpecialClose, type SpecialOpen, type Strategy, type StreamingBar, type StreamingDataFeed, type SyntheticAsset, type TacticalFeatureKind, type TacticalFeatureSpec, type TacticalFeatures, type TacticalSpec, type TargetWeights, type TaxRates, type TaxableIncome, type TimeOfDay, type Tolerance, type WithStreamingSyntheticsOptions, accrueCashInterest, aggregateByYear, applyFills, applyOrders, barsToSeries, bucketByTerm, collectBars, computeTaxBill, crossOffset, defineFeature, distributeDividend, drawdown, ema, evaluateFeatureSpecs, evaluateRuleTree, index$1 as features, fromSpec, getCalendar, getFeatureCompute, holdingPeriodDays, isLongTerm, isQualifiedForLot, isRebalanceDay, netWithinBucket, paramsHash, periodKey, pollingStreamFromHistorical, positionsByAsset, realize, reconcile, reinvestDividend, returnSeries, rsi, runBacktest, runLive, selectFIFO, selectHIFO, selectLIFO, selectMinTax, seriesAt, sma, index$2 as tactical, index as tax, volatility, withStreamingSynthetics, withSynthetics };