@livefolio/sdk 0.5.0-rc.1 → 0.5.0-rc.2

package/dist/index.js

@@ -54,6 +54,36 @@ function nextLotId() {
   return `lot_${++_lotCounter}`;
 }
 
+// src/tax/holding-period.ts
+var MS_PER_DAY = 864e5;
+function holdingPeriodDays(lot, asOf) {
+  return (asOf.getTime() - lot.openDate.getTime()) / MS_PER_DAY;
+}
+function isLongTerm(days) {
+  return days > 365;
+}
+function realize(lot, qty, salePrice, asOf) {
+  if (qty <= 0) throw new RangeError(`realize: qty must be positive, got ${qty}`);
+  if (qty > lot.quantity) throw new RangeError(`realize: lot ${lot.id} has ${lot.quantity}, cannot sell ${qty}`);
+  const basisPerShare = lot.basis / lot.quantity;
+  const basis = basisPerShare * qty;
+  const proceeds = qty * salePrice;
+  const event = {
+    asset: lot.asset,
+    lotId: lot.id,
+    quantity: qty,
+    openDate: lot.openDate,
+    closeDate: asOf,
+    proceeds,
+    basis,
+    termType: isLongTerm(holdingPeriodDays(lot, asOf)) ? "long" : "short",
+    gain: proceeds - basis,
+    incomeKind: "capital-gain"
+  };
+  const remainingLot = qty === lot.quantity ? null : { ...lot, quantity: lot.quantity - qty, basis: lot.basis - basis };
+  return { event, remainingLot };
+}
+
 // src/portfolio/apply.ts
 var newPositionId = /* @__PURE__ */ (() => {
   let n = 0;
@@ -62,8 +92,6 @@ var newPositionId = /* @__PURE__ */ (() => {
 function findOrder(orders, id) {
   return orders.find((o) => o.id === id);
 }
-var MS_PER_DAY = 864e5;
-var isLong = (openDate, closeDate) => (closeDate.getTime() - openDate.getTime()) / MS_PER_DAY > 365;
 function consumeLots(lots, realized, assetId, qty, price, fees, closeDate, preferLotId) {
   const sortedLots = lots.filter((l) => l.asset.id === assetId && l.quantity > 0).sort((a, b) => {
     if (preferLotId) {
@@ -80,25 +108,25 @@ function consumeLots(lots, realized, assetId, qty, price, fees, closeDate, prefe
   const totalQty = qty;
   for (const l of sortedLots) {
     if (need <= 0) break;
-    const take = Math.min(l.quantity, need);
+    const take2 = Math.min(l.quantity, need);
     const basisPerShare = l.basis / l.quantity;
-    const consumedBasis = basisPerShare * take;
-    const proceeds = take * price - take / totalQty * fees;
+    const consumedBasis = basisPerShare * take2;
+    const proceeds = take2 * price - take2 / totalQty * fees;
     realized.push({
       asset: l.asset,
       lotId: l.id,
-      quantity: take,
+      quantity: take2,
       openDate: l.openDate,
       closeDate,
       proceeds,
       basis: consumedBasis,
-      termType: isLong(l.openDate, closeDate) ? "long" : "short",
+      termType: isLongTerm(holdingPeriodDays(l, closeDate)) ? "long" : "short",
       gain: proceeds - consumedBasis,
       incomeKind: "capital-gain"
     });
-    l.quantity -= take;
+    l.quantity -= take2;
     l.basis -= consumedBasis;
-    need -= take;
+    need -= take2;
   }
 }
 function applyFills(portfolio, fills, orders) {
@@ -3039,6 +3067,164 @@ __export(features_exports, {
   volatility: () => volatility
 });
 
+// src/tax/index.ts
+var tax_exports = {};
+__export(tax_exports, {
+  ORDINARY_OFFSET_CAP: () => ORDINARY_OFFSET_CAP,
+  aggregateByYear: () => aggregateByYear,
+  bucketByTerm: () => bucketByTerm,
+  computeTaxBill: () => computeTaxBill,
+  crossOffset: () => crossOffset,
+  holdingPeriodDays: () => holdingPeriodDays,
+  isLongTerm: () => isLongTerm,
+  netWithinBucket: () => netWithinBucket,
+  realize: () => realize,
+  selectFIFO: () => selectFIFO,
+  selectHIFO: () => selectHIFO,
+  selectLIFO: () => selectLIFO,
+  selectMinTax: () => selectMinTax
+});
+
+// src/tax/lot-selection.ts
+function take(sorted, qty) {
+  let need = qty;
+  const out = [];
+  for (const lot of sorted) {
+    if (lot.quantity <= 0) continue;
+    if (need <= 0) break;
+    const q = Math.min(lot.quantity, need);
+    out.push({ lotId: lot.id, quantity: q });
+    need -= q;
+  }
+  if (need > 1e-9) {
+    const held = sorted.reduce((s, l) => s + Math.max(0, l.quantity), 0);
+    throw new RangeError(`lot-selection: need ${qty} but only ${held} held`);
+  }
+  return out;
+}
+function selectFIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => a.openDate.getTime() - b.openDate.getTime()),
+    qty
+  );
+}
+function selectLIFO(lots, qty) {
+  return take(
+    [...lots].sort((a, b) => b.openDate.getTime() - a.openDate.getTime()),
+    qty
+  );
+}
+function selectHIFO(lots, qty) {
+  return take(
+    [...lots].filter((l) => l.quantity > 0).sort((a, b) => b.basis / b.quantity - a.basis / a.quantity),
+    qty
+  );
+}
+function selectMinTax(lots, qty, ctx) {
+  const tier = (l) => {
+    const gainPerShare = ctx.price - l.basis / l.quantity;
+    const lt = isLongTerm(holdingPeriodDays(l, ctx.asOf));
+    if (gainPerShare < 0) return lt ? 0 : 1;
+    return lt ? 2 : 3;
+  };
+  const sorted = [...lots].filter((l) => l.quantity > 0).sort((a, b) => {
+    const ta = tier(a);
+    const tb = tier(b);
+    if (ta !== tb) return ta - tb;
+    const gainA = ctx.price - a.basis / a.quantity;
+    const gainB = ctx.price - b.basis / b.quantity;
+    return gainA - gainB;
+  });
+  return take(sorted, qty);
+}
+
+// src/tax/aggregation.ts
+var ORDINARY_OFFSET_CAP = 3e3;
+function bucketByTerm(events) {
+  const short = [];
+  const long = [];
+  for (const e of events) {
+    if (e.incomeKind !== "capital-gain") continue;
+    (e.termType === "long" ? long : short).push(e);
+  }
+  return { short, long };
+}
+function netWithinBucket(events) {
+  let gains = 0;
+  let losses = 0;
+  for (const e of events) {
+    if (e.gain >= 0) gains += e.gain;
+    else losses += -e.gain;
+  }
+  return { gains, losses, net: gains - losses };
+}
+function crossOffset(netShort, netLong) {
+  if (netShort >= 0 && netLong >= 0) {
+    return { taxableShort: netShort, taxableLong: netLong, ordinaryOffset: 0, carryForward: 0 };
+  }
+  if (netShort < 0 && netLong < 0) {
+    const totalLoss = -(netShort + netLong);
+    const ordinaryOffset2 = Math.min(ORDINARY_OFFSET_CAP, totalLoss);
+    return { taxableShort: 0, taxableLong: 0, ordinaryOffset: ordinaryOffset2, carryForward: totalLoss - ordinaryOffset2 };
+  }
+  const combined = netShort + netLong;
+  if (combined >= 0) {
+    const taxableShort = netShort > 0 ? combined : 0;
+    const taxableLong = netLong > 0 ? combined : 0;
+    return { taxableShort, taxableLong, ordinaryOffset: 0, carryForward: 0 };
+  }
+  const loss = -combined;
+  const ordinaryOffset = Math.min(ORDINARY_OFFSET_CAP, loss);
+  return { taxableShort: 0, taxableLong: 0, ordinaryOffset, carryForward: loss - ordinaryOffset };
+}
+function aggregateByYear(events) {
+  const out = /* @__PURE__ */ new Map();
+  const blank = () => ({
+    shortTermGains: 0,
+    shortTermLosses: 0,
+    longTermGains: 0,
+    longTermLosses: 0,
+    qualifiedDividends: 0,
+    ordinaryDividends: 0,
+    interestIncome: 0
+  });
+  for (const e of events) {
+    const year = e.closeDate.getUTCFullYear();
+    const acc = out.get(year) ?? blank();
+    switch (e.incomeKind) {
+      case "capital-gain":
+        if (e.termType === "long") {
+          if (e.gain >= 0) acc.longTermGains += e.gain;
+          else acc.longTermLosses += -e.gain;
+        } else {
+          if (e.gain >= 0) acc.shortTermGains += e.gain;
+          else acc.shortTermLosses += -e.gain;
+        }
+        break;
+      case "qualified-dividend":
+        acc.qualifiedDividends += e.proceeds;
+        break;
+      case "ordinary-dividend":
+        acc.ordinaryDividends += e.proceeds;
+        break;
+      case "interest":
+        acc.interestIncome += e.proceeds;
+        break;
+    }
+    out.set(year, acc);
+  }
+  return out;
+}
+function computeTaxBill(income, rates) {
+  const netShort = income.shortTermGains - income.shortTermLosses;
+  const netLong = income.longTermGains - income.longTermLosses;
+  const off = crossOffset(netShort, netLong);
+  const ordinaryPortion = (off.taxableShort + income.ordinaryDividends + income.interestIncome) * rates.shortTerm;
+  const ltPortion = (off.taxableLong + income.qualifiedDividends) * rates.longTerm;
+  const total = ordinaryPortion + ltPortion;
+  return { total, breakdown: { ordinaryPortion, ltPortion, carryForward: off.carryForward } };
+}
+
 // src/portfolio/derived.ts
 function positionsByAsset(portfolio) {
   const byId = /* @__PURE__ */ new Map();
@@ -3078,16 +3264,21 @@ export {
   LSEExchangeCalendar,
   MemoryFeatureCache,
   NYSEExchangeCalendar,
+  ORDINARY_OFFSET_CAP,
   RoutingDataFeed,
   RoutingDataFeedError,
   RoutingQuoteFeed,
   RoutingQuoteFeedError,
   RoutingStreamingDataFeed,
   RoutingStreamingDataFeedError,
+  aggregateByYear,
   applyFills,
   applyOrders,
   barsToSeries,
+  bucketByTerm,
   collectBars,
+  computeTaxBill,
+  crossOffset,
   defineFeature,
   drawdown,
   ema,
@@ -3097,19 +3288,28 @@ export {
   fromSpec,
   getCalendar,
   getFeatureCompute,
+  holdingPeriodDays,
+  isLongTerm,
   isRebalanceDay,
+  netWithinBucket,
   paramsHash,
   periodKey,
   pollingStreamFromHistorical,
   positionsByAsset,
+  realize,
   reconcile,
   returnSeries,
   rsi,
   runBacktest,
   runLive,
+  selectFIFO,
+  selectHIFO,
+  selectLIFO,
+  selectMinTax,
   seriesAt,
   sma,
   tactical_exports as tactical,
+  tax_exports as tax,
   volatility,
   withStreamingSynthetics,
   withSynthetics