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

package/dist/index.js

@@ -313,10 +313,80 @@ function applyOrders(portfolio, orders) {
   return { ...portfolio, positions };
 }
 
+// src/tax/dividends.ts
+var MS_PER_DAY2 = 864e5;
+function isQualifiedForLot(lot, exDate, opts = {}) {
+  const required = opts.holdingDaysRequired ?? 60;
+  const window = opts.windowDays ?? 121;
+  const half = Math.floor(window / 2);
+  const windowStart = new Date(exDate.getTime() - half * MS_PER_DAY2);
+  const windowEnd = new Date(exDate.getTime() + half * MS_PER_DAY2);
+  const heldFrom = lot.openDate > windowStart ? lot.openDate : windowStart;
+  const heldTo = exDate < windowEnd ? exDate : windowEnd;
+  const days = Math.max(0, (heldTo.getTime() - heldFrom.getTime()) / MS_PER_DAY2);
+  return days >= required;
+}
+function distributeDividend(event, lotsHeldAtExDate) {
+  const eligible = event.incomeKind === "qualified-eligible";
+  const perLot = [];
+  let qualified = 0, ordinary = 0;
+  for (const lot of lotsHeldAtExDate) {
+    if (lot.quantity <= 0 || lot.openDate > event.exDate || lot.asset.id !== event.asset.id) continue;
+    const cash = lot.quantity * event.amountPerShare;
+    const isQ = eligible && isQualifiedForLot(lot, event.exDate);
+    perLot.push({ lotId: lot.id, cash, qualified: isQ });
+    if (isQ) qualified += cash;
+    else ordinary += cash;
+  }
+  return { totals: { qualified, ordinary }, perLot };
+}
+function reinvestDividend(cashAvailable, asset, pricePayDate, payDate, dripParent) {
+  const shares = Math.floor(cashAvailable / pricePayDate);
+  const cost = shares * pricePayDate;
+  return {
+    newLot: {
+      id: nextLotId(),
+      asset,
+      quantity: shares,
+      openDate: payDate,
+      openPrice: pricePayDate,
+      basis: cost,
+      dripParent
+    },
+    residual: cashAvailable - cost
+  };
+}
+
+// src/tax/cash-interest.ts
+function accrueCashInterest(cash, dailyRate) {
+  const interest = cash * dailyRate;
+  return { newCash: cash + interest, interest };
+}
+
 // src/strategy/run-backtest.ts
+var CASH_ASSET = { kind: "equity", id: "_cash", symbol: "CASH" };
 function isStateResult(r) {
   return !Array.isArray(r);
 }
+var DRIP_PRICE_WINDOW_MS = 7 * 864e5;
+async function firstUnadjustedClose(feed, asset, payDate, freq) {
+  const to = new Date(payDate.getTime() + DRIP_PRICE_WINDOW_MS);
+  for await (const bar of feed.bars(asset, { from: payDate, to }, freq, "unadjusted")) return bar.close;
+  return void 0;
+}
+async function resolveDailyRate(cfg, t, feed, freq) {
+  if (!cfg || cfg.kind === "none") return 0;
+  if (cfg.kind === "flat") return cfg.apy / 365;
+  const id = cfg.assetId ?? "DGS3MO";
+  const asset = { kind: "macro", id, symbol: id, source: "FRED" };
+  const to = new Date(t.getTime() + 864e5);
+  let last;
+  for await (const bar of feed.bars(asset, { from: new Date(t.getTime() - 7 * 864e5), to }, freq, "unadjusted")) {
+    last = bar.close;
+  }
+  if (last === void 0) return 0;
+  return Math.max(0, (last / 100 - cfg.spread) / 365);
+}
 async function runBacktest(opts) {
   const initialStateValue = opts.strategy.initialState?.();
   const sessions = opts.calendar.sessions(opts.range);
@@ -334,6 +404,16 @@ async function runBacktest(opts) {
   const cashEvents = [...opts.cashEvents ?? []].sort((a, b) => a.t.getTime() - b.t.getTime());
   let eventCursor = 0;
   let warnedNegativeCash = false;
+  let warnedDripFallback = false;
+  const divByAsset = /* @__PURE__ */ new Map();
+  if (opts.dataFeed.dividends && sessions.length > 0) {
+    const u0 = opts.strategy.universe(sessions[0], opts.initialPortfolio);
+    for (const asset of u0) {
+      divByAsset.set(asset.id, await opts.dataFeed.dividends(asset, opts.range));
+    }
+  }
+  const allDivs = [...divByAsset.values()].flat().sort((a, b) => a.exDate.getTime() - b.exDate.getTime());
+  let divCursor = 0;
   for (const t of sessions) {
     let cashFlow = 0;
     while (eventCursor < cashEvents.length && cashEvents[eventCursor].t.getTime() <= t.getTime()) {
@@ -349,6 +429,72 @@ async function runBacktest(opts) {
         );
       }
     }
+    let qualifiedTotal = 0;
+    let ordinaryTotal = 0;
+    while (divCursor < allDivs.length && allDivs[divCursor].exDate.getTime() <= t.getTime()) {
+      const div = allDivs[divCursor];
+      divCursor++;
+      const dist = distributeDividend(div, portfolio.lots ?? []);
+      if (dist.perLot.length === 0) continue;
+      qualifiedTotal += dist.totals.qualified;
+      ordinaryTotal += dist.totals.ordinary;
+      const reinvest = opts.dividends?.reinvest === true;
+      const lots = [...portfolio.lots ?? []];
+      const realized = [...portfolio.realized ?? []];
+      let cashCredit = 0;
+      const reinvestPrice = reinvest ? await firstUnadjustedClose(opts.dataFeed, div.asset, div.payDate, opts.freq ?? "1d") : void 0;
+      for (const slice of dist.perLot) {
+        realized.push({
+          asset: div.asset,
+          lotId: slice.lotId,
+          quantity: 0,
+          openDate: t,
+          closeDate: t,
+          proceeds: slice.cash,
+          basis: 0,
+          termType: "long",
+          gain: slice.cash,
+          incomeKind: slice.qualified ? "qualified-dividend" : "ordinary-dividend"
+        });
+        if (reinvest && reinvestPrice && reinvestPrice > 0) {
+          const { newLot, residual } = reinvestDividend(slice.cash, div.asset, reinvestPrice, div.payDate, slice.lotId);
+          if (newLot.quantity > 0) lots.push(newLot);
+          cashCredit += residual;
+        } else {
+          if (reinvest && !warnedDripFallback) {
+            warnedDripFallback = true;
+            console.warn(
+              `[runBacktest] DRIP fell back to a cash credit for ${div.asset.id} (pay date ${div.payDate.toISOString()}): no unadjusted bar within 7 days of the pay date. Further occurrences this run are suppressed.`
+            );
+          }
+          cashCredit += slice.cash;
+        }
+      }
+      portfolio = { ...portfolio, cash: portfolio.cash + cashCredit, lots, realized };
+    }
+    const dividendIncome = qualifiedTotal + ordinaryTotal > 0 ? { qualified: qualifiedTotal, ordinary: ordinaryTotal } : void 0;
+    let interestThisSession = 0;
+    const dailyRate = await resolveDailyRate(opts.cashYield, t, opts.dataFeed, opts.freq ?? "1d");
+    if (dailyRate > 0 && portfolio.cash > 0) {
+      const { newCash, interest } = accrueCashInterest(portfolio.cash, dailyRate);
+      const realized = [
+        ...portfolio.realized ?? [],
+        {
+          asset: CASH_ASSET,
+          lotId: "cash",
+          quantity: 0,
+          openDate: t,
+          closeDate: t,
+          proceeds: interest,
+          basis: 0,
+          termType: "short",
+          gain: interest,
+          incomeKind: "interest"
+        }
+      ];
+      portfolio = { ...portfolio, cash: newCash, realized };
+      interestThisSession = interest;
+    }
     const universe = opts.strategy.universe(t, portfolio);
     const features = await opts.strategy.features(universe, portfolio, t);
     const buildResult = opts.strategy.build(features, portfolio, state, t);
@@ -361,7 +507,15 @@ async function runBacktest(opts) {
     }
     const fills = await opts.executor.submit(orders, t, portfolio);
     portfolio = applyFills(portfolio, fills, orders);
-    snapshots.push({ t, portfolio, orders, fills, ...cashFlow !== 0 ? { cashFlow } : {} });
+    snapshots.push({
+      t,
+      portfolio,
+      orders,
+      fills,
+      ...cashFlow !== 0 ? { cashFlow } : {},
+      ...dividendIncome ? { dividendIncome } : {},
+      ...interestThisSession !== 0 ? { interestIncome: interestThisSession } : {}
+    });
   }
   const bars = opts.featureRuntime?.getAllBars() ?? /* @__PURE__ */ new Map();
   return { snapshots, finalPortfolio: portfolio, finalState: state, bars };
@@ -1280,7 +1434,7 @@ function pollingStreamFromHistorical(opts) {
 import { DateTime } from "luxon";
 
 // src/calendars/holiday-rules.ts
-var MS_PER_DAY2 = 864e5;
+var MS_PER_DAY3 = 864e5;
 function nthWeekdayOfMonth(year, month, weekday, n) {
   const first = new Date(Date.UTC(year, month - 1, 1));
   const offset = (weekday - first.getUTCDay() + 7) % 7;
@@ -1289,7 +1443,7 @@ function nthWeekdayOfMonth(year, month, weekday, n) {
 function lastWeekdayOfMonth(year, month, weekday) {
   const last = new Date(Date.UTC(year, month, 0));
   const offset = (last.getUTCDay() - weekday + 7) % 7;
-  return new Date(last.getTime() - offset * MS_PER_DAY2);
+  return new Date(last.getTime() - offset * MS_PER_DAY3);
 }
 function easter(year) {
   const a = year % 19;
@@ -1310,8 +1464,8 @@ function easter(year) {
 }
 function observed(d) {
   const dow = d.getUTCDay();
-  if (dow === 6) return new Date(d.getTime() - MS_PER_DAY2);
-  if (dow === 0) return new Date(d.getTime() + MS_PER_DAY2);
+  if (dow === 6) return new Date(d.getTime() - MS_PER_DAY3);
+  if (dow === 0) return new Date(d.getTime() + MS_PER_DAY3);
   return d;
 }
 function resolveHolidays(rules, year) {
@@ -1349,21 +1503,21 @@ function resolveSpecialOpens(rules, year) {
   return out;
 }
 function sundayToMonday(d) {
-  return d.getUTCDay() === 0 ? new Date(d.getTime() + MS_PER_DAY2) : d;
+  return d.getUTCDay() === 0 ? new Date(d.getTime() + MS_PER_DAY3) : d;
 }
 function nearestWorkday(d) {
   const dow = d.getUTCDay();
-  if (dow === 6) return new Date(d.getTime() - MS_PER_DAY2);
-  if (dow === 0) return new Date(d.getTime() + MS_PER_DAY2);
+  if (dow === 6) return new Date(d.getTime() - MS_PER_DAY3);
+  if (dow === 0) return new Date(d.getTime() + MS_PER_DAY3);
   return d;
 }
 function firstMondayOnOrAfter(year, month, day, nth = 1) {
   const start = new Date(Date.UTC(year, month - 1, day));
   const offset = (1 - start.getUTCDay() + 7) % 7;
-  return new Date(start.getTime() + (offset + 7 * (nth - 1)) * MS_PER_DAY2);
+  return new Date(start.getTime() + (offset + 7 * (nth - 1)) * MS_PER_DAY3);
 }
 function easterPlus(year, dayDelta) {
-  return new Date(easter(year).getTime() + dayDelta * MS_PER_DAY2);
+  return new Date(easter(year).getTime() + dayDelta * MS_PER_DAY3);
 }
 function dropIfNotInDays(d, allowed) {
   if (d === null) return null;
@@ -1371,7 +1525,7 @@ function dropIfNotInDays(d, allowed) {
 }
 
 // src/calendars/exchange-calendar.ts
-var MS_PER_DAY3 = 864e5;
+var MS_PER_DAY4 = 864e5;
 var DEFAULT_WEEKMASK = /* @__PURE__ */ new Set([1, 2, 3, 4, 5]);
 var EMPTY_ADHOC = /* @__PURE__ */ new Map();
 function ymdKey(d) {
@@ -1532,14 +1686,14 @@ var ExchangeCalendar = class {
   }
   /** Returns the first trading day strictly after `t`. */
   next(t) {
-    let d = new Date(this.normalize(t).getTime() + MS_PER_DAY3);
-    while (!this.isOpen(d)) d = new Date(d.getTime() + MS_PER_DAY3);
+    let d = new Date(this.normalize(t).getTime() + MS_PER_DAY4);
+    while (!this.isOpen(d)) d = new Date(d.getTime() + MS_PER_DAY4);
     return d;
   }
   /** Returns the first trading day strictly before `t`. */
   previous(t) {
-    let d = new Date(this.normalize(t).getTime() - MS_PER_DAY3);
-    while (!this.isOpen(d)) d = new Date(d.getTime() - MS_PER_DAY3);
+    let d = new Date(this.normalize(t).getTime() - MS_PER_DAY4);
+    while (!this.isOpen(d)) d = new Date(d.getTime() - MS_PER_DAY4);
     return d;
   }
   /**
@@ -1552,7 +1706,7 @@ var ExchangeCalendar = class {
     const end = this.normalize(range.to).getTime();
     while (d.getTime() < end) {
       if (this.isOpen(d)) out.push(d);
-      d = new Date(d.getTime() + MS_PER_DAY3);
+      d = new Date(d.getTime() + MS_PER_DAY4);
     }
     return out;
   }
@@ -1603,7 +1757,7 @@ var ExchangeCalendar = class {
 };
 
 // src/calendars/nyse.ts
-var MS_PER_DAY4 = 864e5;
+var MS_PER_DAY5 = 864e5;
 var SUN = 0;
 var MON = 1;
 var TUE = 2;
@@ -1767,7 +1921,7 @@ var REGULAR_HOLIDAYS = [
     resolve: (y) => {
       const start = utcDate(y, 11, 2);
       const offset = (TUE - start.getUTCDay() + 7) % 7;
-      return new Date(start.getTime() + offset * MS_PER_DAY4);
+      return new Date(start.getTime() + offset * MS_PER_DAY5);
     }
   },
   // ── Veterans/Armistice Day (Nov 11, 1934-1953) ─────────────────────────────
@@ -1798,7 +1952,7 @@ var REGULAR_HOLIDAYS = [
     validUntil: 1941,
     resolve: (y) => {
       const last = lastWeekdayOfMonth(y, 11, THU);
-      return new Date(last.getTime() - 7 * MS_PER_DAY4);
+      return new Date(last.getTime() - 7 * MS_PER_DAY5);
     }
   },
   // ── Christmas ──────────────────────────────────────────────────────────────
@@ -2155,7 +2309,7 @@ function* generateSummerSaturdays() {
     const end = /* @__PURE__ */ new Date(`${to}T00:00:00.000Z`);
     while (d.getTime() <= end.getTime()) {
       if (d.getUTCDay() === SAT) yield ymd(d);
-      d = new Date(d.getTime() + MS_PER_DAY4);
+      d = new Date(d.getTime() + MS_PER_DAY5);
     }
   }
 }
@@ -2165,7 +2319,7 @@ function* generateWWIShutdown() {
   while (d.getTime() <= end.getTime()) {
     const dow = d.getUTCDay();
     if (dow !== SUN) yield ymd(d);
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 }
 var ADHOC_HOLIDAYS = /* @__PURE__ */ new Set([
@@ -2183,7 +2337,7 @@ var SPECIAL_CLOSES = [
     closeAt: { h: 13, m: 0 },
     resolve: (y) => {
       const t = nthWeekdayOfMonth(y, 11, THU, 4);
-      return new Date(t.getTime() + MS_PER_DAY4);
+      return new Date(t.getTime() + MS_PER_DAY5);
     }
   },
   {
@@ -2193,7 +2347,7 @@ var SPECIAL_CLOSES = [
     closeAt: { h: 14, m: 0 },
     resolve: (y) => {
       const t = nthWeekdayOfMonth(y, 11, THU, 4);
-      return new Date(t.getTime() + MS_PER_DAY4);
+      return new Date(t.getTime() + MS_PER_DAY5);
     }
   },
   {
@@ -2354,7 +2508,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 14, m: 0 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 (() => {
@@ -2365,7 +2519,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 14, m: 0 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 (() => {
@@ -2376,7 +2530,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 14, m: 0 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 (() => {
@@ -2387,7 +2541,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 14, m: 0 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 (() => {
@@ -2398,7 +2552,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 14, m: 30 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 (() => {
@@ -2409,7 +2563,7 @@ var SPECIAL_CLOSES_ADHOC = /* @__PURE__ */ new Map([
     if (dow >= MON && dow <= FRI) {
       SPECIAL_CLOSES_ADHOC.set(ymd(d), { h: 15, m: 0 });
     }
-    d = new Date(d.getTime() + MS_PER_DAY4);
+    d = new Date(d.getTime() + MS_PER_DAY5);
   }
 })();
 var SPECIAL_OPENS = [];
@@ -2526,7 +2680,7 @@ var NYSEExchangeCalendar = class extends ExchangeCalendar {
 };
 
 // src/calendars/lse.ts
-var MS_PER_DAY5 = 864e5;
+var MS_PER_DAY6 = 864e5;
 var SUN2 = 0;
 var MON2 = 1;
 var TUE2 = 2;
@@ -2538,14 +2692,14 @@ var WEEKDAYS_MON_FRI2 = /* @__PURE__ */ new Set([1, 2, 3, 4, 5]);
 var MON_TUE = /* @__PURE__ */ new Set([MON2, TUE2]);
 function weekendToMonday(d) {
   const dow = d.getUTCDay();
-  if (dow === SAT2) return new Date(d.getTime() + 2 * MS_PER_DAY5);
-  if (dow === SUN2) return new Date(d.getTime() + MS_PER_DAY5);
+  if (dow === SAT2) return new Date(d.getTime() + 2 * MS_PER_DAY6);
+  if (dow === SUN2) return new Date(d.getTime() + MS_PER_DAY6);
   return d;
 }
 function previousFriday(d) {
   const dow = d.getUTCDay();
-  if (dow === SAT2) return new Date(d.getTime() - MS_PER_DAY5);
-  if (dow === SUN2) return new Date(d.getTime() - 2 * MS_PER_DAY5);
+  if (dow === SAT2) return new Date(d.getTime() - MS_PER_DAY6);
+  if (dow === SUN2) return new Date(d.getTime() - 2 * MS_PER_DAY6);
   return d;
 }
 var REGULAR_HOLIDAYS2 = [
@@ -2737,7 +2891,7 @@ function getCalendar(name) {
 }
 
 // src/calendars/crypto-24x7.ts
-var MS_PER_DAY6 = 864e5;
+var MS_PER_DAY7 = 864e5;
 function midnightUtc(d) {
   return new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
 }
@@ -2746,10 +2900,10 @@ var Crypto24x7Calendar = class {
     return true;
   }
   next(t) {
-    return new Date(midnightUtc(t).getTime() + MS_PER_DAY6);
+    return new Date(midnightUtc(t).getTime() + MS_PER_DAY7);
   }
   previous(t) {
-    return new Date(midnightUtc(t).getTime() - MS_PER_DAY6);
+    return new Date(midnightUtc(t).getTime() - MS_PER_DAY7);
   }
   sessions(range) {
     const out = [];
@@ -2757,7 +2911,7 @@ var Crypto24x7Calendar = class {
     const end = range.to.getTime();
     while (cursor.getTime() < end) {
       out.push(cursor);
-      cursor = new Date(cursor.getTime() + MS_PER_DAY6);
+      cursor = new Date(cursor.getTime() + MS_PER_DAY7);
     }
     return out;
   }
@@ -2765,7 +2919,7 @@ var Crypto24x7Calendar = class {
     return this.sessions(range).map((date) => ({
       date,
       open: date,
-      close: new Date(date.getTime() + MS_PER_DAY6)
+      close: new Date(date.getTime() + MS_PER_DAY7)
     }));
   }
   isEarlyClose(_t) {
@@ -3219,14 +3373,18 @@ __export(features_exports, {
 var tax_exports = {};
 __export(tax_exports, {
   ORDINARY_OFFSET_CAP: () => ORDINARY_OFFSET_CAP,
+  accrueCashInterest: () => accrueCashInterest,
   aggregateByYear: () => aggregateByYear,
   bucketByTerm: () => bucketByTerm,
   computeTaxBill: () => computeTaxBill,
   crossOffset: () => crossOffset,
+  distributeDividend: () => distributeDividend,
   holdingPeriodDays: () => holdingPeriodDays,
   isLongTerm: () => isLongTerm,
+  isQualifiedForLot: () => isQualifiedForLot,
   netWithinBucket: () => netWithinBucket,
   realize: () => realize,
+  reinvestDividend: () => reinvestDividend,
   selectFIFO: () => selectFIFO,
   selectHIFO: () => selectHIFO,
   selectLIFO: () => selectLIFO,
@@ -3367,6 +3525,7 @@ export {
   RoutingQuoteFeedError,
   RoutingStreamingDataFeed,
   RoutingStreamingDataFeedError,
+  accrueCashInterest,
   aggregateByYear,
   applyFills,
   applyOrders,
@@ -3376,6 +3535,7 @@ export {
   computeTaxBill,
   crossOffset,
   defineFeature,
+  distributeDividend,
   drawdown,
   ema,
   evaluateFeatureSpecs,
@@ -3386,6 +3546,7 @@ export {
   getFeatureCompute,
   holdingPeriodDays,
   isLongTerm,
+  isQualifiedForLot,
   isRebalanceDay,
   netWithinBucket,
   paramsHash,
@@ -3394,6 +3555,7 @@ export {
   positionsByAsset,
   realize,
   reconcile,
+  reinvestDividend,
   returnSeries,
   rsi,
   runBacktest,