@livefolio/sdk 0.2.0 → 0.2.3

package/README.md

@@ -8,9 +8,7 @@ TypeScript SDK for market data, strategy evaluation, and portfolio management.
 npm install @livefolio/sdk
 ```
 
-## Getting Started
-
-All modules are created from a single Supabase client:
+## Quick Start
 
 ```ts
 import { createLivefolioClient } from '@livefolio/sdk';
@@ -20,171 +18,47 @@ const supabase = createClient(SUPABASE_URL, SUPABASE_ANON_KEY);
 const livefolio = createLivefolioClient(supabase);
 ```
 
-Individual modules can also be imported directly:
-
-```ts
-import { createMarket } from '@livefolio/sdk/market';
-import { createAuth } from '@livefolio/sdk/auth';
-import { createStrategy } from '@livefolio/sdk/strategy';
-```
-
----
-
-## Auth
-
-Wraps Supabase Auth with a simplified interface.
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `getUser()` | `User \| null` | Get the current authenticated user, or `null` if not signed in |
-| `getSession()` | `Session \| null` | Get the current session |
-| `requireUser()` | `User` | Get the current user or throw if not authenticated |
-| `onAuthStateChange(callback)` | `Subscription` | Subscribe to auth state changes (sign in, sign out, token refresh) |
-| `signOut()` | `void` | Sign out the current user |
-
-```ts
-const user = await livefolio.auth.getUser();
-
-const subscription = livefolio.auth.onAuthStateChange((event, session) => {
-  console.log(event, session);
-});
-```
-
----
-
-## Market
-
-Provides historical price series, real-time quotes, and the trading calendar. Series and quotes are served through Supabase Edge Functions with transparent cache-through behavior — the SDK requests data and caching is handled server-side.
-
-### Series
-
-Retrieve historical daily observations for one or more symbols. Each observation has an ISO 8601 `timestamp` (market close) and a `value` (closing price).
-
-```ts
-const spy = await livefolio.market.getSeries('SPY');
-// spy: Observation[] — [{ timestamp: '2025-01-10T21:00:00Z', value: 590.25 }, ...]
-
-const batch = await livefolio.market.getBatchSeries(['SPY', 'QQQ', 'TLT']);
-// batch: Record<string, Observation[]> — { SPY: [...], QQQ: [...], TLT: [...] }
-```
-
-### Quotes
+## Modules
 
-Retrieve the latest real-time quote for one or more symbols.
-
-```ts
-const quote = await livefolio.market.getQuote('SPY');
-// quote: Observation — { timestamp: '2025-03-02T21:00:00Z', value: 592.10 }
-
-const quotes = await livefolio.market.getBatchQuotes(['SPY', 'QQQ']);
-// quotes: Record<string, Observation>
-```
-
-### Trading Calendar
-
-Query the trading calendar for market open/close times. Dates are `YYYY-MM-DD` strings.
-
-```ts
-const days = await livefolio.market.getTradingDays('2025-01-01', '2025-12-31');
-// days: TradingDay[] — [{ date, open, close, extended_open, extended_close }, ...]
-
-const today = await livefolio.market.getTradingDay('2025-03-02');
-// today: TradingDay | null
-```
-
----
-
-## Strategy
-
-Handles strategy retrieval, evaluation, and result caching. The module exposes two evaluation paths:
-
-- **`evaluate()`** (async) — the primary API. Checks the DB cache for a prior result, returns it on hit, or runs a fresh evaluation and stores the result on miss. Consumers never need to manage caching manually.
-- **Pure functions** (sync) — `evaluateIndicator`, `evaluateSignal`, `evaluateAllocation` for direct computation without DB interaction. Useful for testing, debugging, or custom pipelines.
-
-### Retrieving Strategies
-
-Fetch a fully-resolved strategy by its link ID. The `get()` method calls the `strategy` edge function, which looks up the strategy in the database and auto-imports from testfol.io if not found. The returned `Strategy` object contains all named signals, indicators, condition trees, and allocations ready for evaluation.
-
-```ts
-const strategy = await livefolio.strategy.get('abc-123');
-// strategy: Strategy | null
-
-const strategies = await livefolio.strategy.getMany(['abc-123', 'def-456']);
-// strategies: Record<string, Strategy>
-```
-
-### Evaluating a Strategy
-
-The `evaluate` method is the standard way to run a strategy. Pass a strategy and a date — everything else is handled internally:
-
-1. Fetches historical series for all symbols used by the strategy
-2. Computes the evaluation date
-3. Checks the DB cache for a prior result on that trading day
-4. On cache miss: fetches prior signal states (for hysteresis) and indicator metadata (for incremental EMA/RSI), runs the evaluation, and stores the result
-5. On cache hit: returns the cached allocation and signal states
+| Module | Description |
+|--------|-------------|
+| `livefolio.auth` | Authentication (user, session, sign-out) |
+| `livefolio.market` | Historical series, real-time quotes, trading calendar |
+| `livefolio.strategy` | Strategy retrieval, cached evaluation, live streaming |
+| `livefolio.portfolio` | Brokerage account aggregation (stub) |
 
 ```ts
+// Fetch and evaluate a strategy
 const strategy = await livefolio.strategy.get('abc-123');
 if (strategy) {
   const result = await livefolio.strategy.evaluate(strategy, new Date());
-
-  result.allocation;   // the winning allocation (name, holdings)
-  result.asOf;         // Date the evaluation corresponds to (trading day market close)
-  result.signals;      // Record<string, boolean> — all signal states
-  result.indicators;   // Record<string, IndicatorEvaluation> — all indicator values
+  console.log(result.allocation.name, result.allocation.holdings);
 }
-```
 
-### Utilities
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `extractSymbols(strategy)` | `string[]` | Collect all ticker symbols needed to evaluate a strategy (from signals + holdings) |
-| `getEvaluationDate(trading, options)` | `Date`            | Compute the evaluation date — requires `EvaluationOptions` with series data |
-
-### Pure Evaluation Functions
+// Market data
+const series = await livefolio.market.getBatchSeries(['SPY', 'BND']);
+const quote = await livefolio.market.getQuote('SPY');
+```
 
-For advanced use cases (testing, backtesting, custom pipelines), the pure evaluation functions operate synchronously without any DB interaction. They accept `EvaluationOptions` with `batchSeries` and optionally `previousSignalStates` and `previousIndicatorMetadata`.
+Modules can also be imported individually:
 
 ```ts
-import { evaluate, evaluateIndicator, evaluateSignal } from '@livefolio/sdk/strategy';
-
-// Evaluate a single indicator
-const smaResult = livefolio.strategy.evaluateIndicator(indicator, options);
-
-// Evaluate a signal (comparison of two indicators)
-const isAbove = livefolio.strategy.evaluateSignal(signal, options);
-
-// Evaluate a full allocation condition tree
-const matches = livefolio.strategy.evaluateAllocation(allocation, options);
+import { createMarket } from '@livefolio/sdk/market';
+import { createStrategy } from '@livefolio/sdk/strategy';
 ```
 
----
-
-## Portfolio
+## Documentation
 
-Brokerage account aggregation and trade order management. This module is planned but not yet implemented.
-
----
+Full method reference, arguments, return types, and usage examples: **[docs/](./docs/)**
 
 ## Development
 
 ```bash
-npm install
 npm run build    # compile TypeScript → dist/
 npm test         # run tests
 ```
 
-## CI/CD
-
-- PRs to `main` run build + tests and enforce a version bump
-- Merges to `main` auto-publish to npm and create a GitHub release
-
-Before merging, bump the version:
-
-```bash
-npm version patch
-```
+PRs to `main` run build + tests and enforce a version bump. Merges auto-publish to npm.
 
 ## License
 

package/dist/portfolio/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/portfolio/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAE7E"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/portfolio/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,eAAe,CAM7E"}

package/dist/portfolio/client.js

@@ -1,7 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createPortfolio = createPortfolio;
+const rebalance_1 = require("./rebalance");
+const symbols_1 = require("./symbols");
 function createPortfolio(_client) {
-    return {};
+    return {
+        buildRebalancePlan: rebalance_1.buildRebalancePlan,
+        computePortfolioDriftPercentPoints: rebalance_1.computePortfolioDriftPercentPoints,
+        mapTickerToTradable: symbols_1.mapTickerToTradable,
+    };
 }
 //# sourceMappingURL=client.js.map

package/dist/portfolio/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/portfolio/client.ts"],"names":[],"mappings":";;AAGA,0CAEC;AAFD,SAAgB,eAAe,CAAC,OAA4B;IAC1D,OAAO,EAAE,CAAC;AACZ,CAAC"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/portfolio/client.ts"],"names":[],"mappings":";;AAKA,0CAMC;AATD,2CAAqF;AACrF,uCAAgD;AAEhD,SAAgB,eAAe,CAAC,OAA4B;IAC1D,OAAO;QACL,kBAAkB,EAAlB,8BAAkB;QAClB,kCAAkC,EAAlC,8CAAkC;QAClC,mBAAmB,EAAnB,6BAAmB;KACpB,CAAC;AACJ,CAAC"}

package/dist/portfolio/index.d.ts

@@ -1,3 +1,5 @@
 export type { PortfolioModule } from './types';
 export { createPortfolio } from './client';
+export { buildRebalancePlan, computePortfolioDriftPercentPoints, type TradeOrder, type RebalancePlanInput, type RebalancePlan, PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS, REBALANCE_MIN_TRADE_VALUE, REBALANCE_QUANTITY_PRECISION, REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION, REBALANCE_EPSILON, REBALANCE_CASH_RESERVE_PERCENT, REBALANCE_MIN_CASH_RESERVE_VALUE, REBALANCE_BUY_SLIPPAGE_BPS, REBALANCE_SELL_SLIPPAGE_BPS, REBALANCE_PER_ORDER_FEE, REBALANCE_CASH_SYMBOL, REBALANCE_CASH_SOURCE_SYMBOL, } from './rebalance';
+export { mapTickerToTradable, FRED_TRADABLE_MAP, BASE_TICKER_ALIASES, ETF_LEVERAGE_MAP, } from './symbols';
 //# sourceMappingURL=index.d.ts.map

package/dist/portfolio/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/portfolio/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/portfolio/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EACL,kBAAkB,EAClB,kCAAkC,EAClC,KAAK,UAAU,EACf,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,wCAAwC,EACxC,yBAAyB,EACzB,4BAA4B,EAC5B,wCAAwC,EACxC,iBAAiB,EACjB,8BAA8B,EAC9B,gCAAgC,EAChC,0BAA0B,EAC1B,2BAA2B,EAC3B,uBAAuB,EACvB,qBAAqB,EACrB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,WAAW,CAAC"}

package/dist/portfolio/index.js

@@ -1,6 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createPortfolio = void 0;
+exports.ETF_LEVERAGE_MAP = exports.BASE_TICKER_ALIASES = exports.FRED_TRADABLE_MAP = exports.mapTickerToTradable = exports.REBALANCE_CASH_SOURCE_SYMBOL = exports.REBALANCE_CASH_SYMBOL = exports.REBALANCE_PER_ORDER_FEE = exports.REBALANCE_SELL_SLIPPAGE_BPS = exports.REBALANCE_BUY_SLIPPAGE_BPS = exports.REBALANCE_MIN_CASH_RESERVE_VALUE = exports.REBALANCE_CASH_RESERVE_PERCENT = exports.REBALANCE_EPSILON = exports.REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION = exports.REBALANCE_QUANTITY_PRECISION = exports.REBALANCE_MIN_TRADE_VALUE = exports.PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS = exports.computePortfolioDriftPercentPoints = exports.buildRebalancePlan = exports.createPortfolio = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "createPortfolio", { enumerable: true, get: function () { return client_1.createPortfolio; } });
+var rebalance_1 = require("./rebalance");
+Object.defineProperty(exports, "buildRebalancePlan", { enumerable: true, get: function () { return rebalance_1.buildRebalancePlan; } });
+Object.defineProperty(exports, "computePortfolioDriftPercentPoints", { enumerable: true, get: function () { return rebalance_1.computePortfolioDriftPercentPoints; } });
+Object.defineProperty(exports, "PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS", { enumerable: true, get: function () { return rebalance_1.PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS; } });
+Object.defineProperty(exports, "REBALANCE_MIN_TRADE_VALUE", { enumerable: true, get: function () { return rebalance_1.REBALANCE_MIN_TRADE_VALUE; } });
+Object.defineProperty(exports, "REBALANCE_QUANTITY_PRECISION", { enumerable: true, get: function () { return rebalance_1.REBALANCE_QUANTITY_PRECISION; } });
+Object.defineProperty(exports, "REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION", { enumerable: true, get: function () { return rebalance_1.REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION; } });
+Object.defineProperty(exports, "REBALANCE_EPSILON", { enumerable: true, get: function () { return rebalance_1.REBALANCE_EPSILON; } });
+Object.defineProperty(exports, "REBALANCE_CASH_RESERVE_PERCENT", { enumerable: true, get: function () { return rebalance_1.REBALANCE_CASH_RESERVE_PERCENT; } });
+Object.defineProperty(exports, "REBALANCE_MIN_CASH_RESERVE_VALUE", { enumerable: true, get: function () { return rebalance_1.REBALANCE_MIN_CASH_RESERVE_VALUE; } });
+Object.defineProperty(exports, "REBALANCE_BUY_SLIPPAGE_BPS", { enumerable: true, get: function () { return rebalance_1.REBALANCE_BUY_SLIPPAGE_BPS; } });
+Object.defineProperty(exports, "REBALANCE_SELL_SLIPPAGE_BPS", { enumerable: true, get: function () { return rebalance_1.REBALANCE_SELL_SLIPPAGE_BPS; } });
+Object.defineProperty(exports, "REBALANCE_PER_ORDER_FEE", { enumerable: true, get: function () { return rebalance_1.REBALANCE_PER_ORDER_FEE; } });
+Object.defineProperty(exports, "REBALANCE_CASH_SYMBOL", { enumerable: true, get: function () { return rebalance_1.REBALANCE_CASH_SYMBOL; } });
+Object.defineProperty(exports, "REBALANCE_CASH_SOURCE_SYMBOL", { enumerable: true, get: function () { return rebalance_1.REBALANCE_CASH_SOURCE_SYMBOL; } });
+var symbols_1 = require("./symbols");
+Object.defineProperty(exports, "mapTickerToTradable", { enumerable: true, get: function () { return symbols_1.mapTickerToTradable; } });
+Object.defineProperty(exports, "FRED_TRADABLE_MAP", { enumerable: true, get: function () { return symbols_1.FRED_TRADABLE_MAP; } });
+Object.defineProperty(exports, "BASE_TICKER_ALIASES", { enumerable: true, get: function () { return symbols_1.BASE_TICKER_ALIASES; } });
+Object.defineProperty(exports, "ETF_LEVERAGE_MAP", { enumerable: true, get: function () { return symbols_1.ETF_LEVERAGE_MAP; } });
 //# sourceMappingURL=index.js.map

package/dist/portfolio/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/portfolio/index.ts"],"names":[],"mappings":";;;AACA,mCAA2C;AAAlC,yGAAA,eAAe,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/portfolio/index.ts"],"names":[],"mappings":";;;AACA,mCAA2C;AAAlC,yGAAA,eAAe,OAAA;AACxB,yCAkBqB;AAjBnB,+GAAA,kBAAkB,OAAA;AAClB,+HAAA,kCAAkC,OAAA;AAIlC,qIAAA,wCAAwC,OAAA;AACxC,sHAAA,yBAAyB,OAAA;AACzB,yHAAA,4BAA4B,OAAA;AAC5B,qIAAA,wCAAwC,OAAA;AACxC,8GAAA,iBAAiB,OAAA;AACjB,2HAAA,8BAA8B,OAAA;AAC9B,6HAAA,gCAAgC,OAAA;AAChC,uHAAA,0BAA0B,OAAA;AAC1B,wHAAA,2BAA2B,OAAA;AAC3B,oHAAA,uBAAuB,OAAA;AACvB,kHAAA,qBAAqB,OAAA;AACrB,yHAAA,4BAA4B,OAAA;AAE9B,qCAKmB;AAJjB,8GAAA,mBAAmB,OAAA;AACnB,4GAAA,iBAAiB,OAAA;AACjB,8GAAA,mBAAmB,OAAA;AACnB,2GAAA,gBAAgB,OAAA"}

package/dist/portfolio/rebalance.d.ts

@@ -0,0 +1,62 @@
+export interface TradeOrder {
+    action: 'BUY' | 'SELL';
+    symbol: string;
+    quantity: number;
+    estimatedPrice: number;
+    estimatedValue: number;
+}
+export interface RebalancePlanInput {
+    targetWeights: Record<string, number>;
+    currentValues: Record<string, number>;
+    prices: Record<string, number>;
+    quantityPrecisionBySymbol?: Record<string, number>;
+    cashValue: number;
+    totalValue: number;
+    portfolioDriftThresholdPercentPoints?: number;
+    minTradeValue?: number;
+    cashReservePercent?: number;
+    minCashReserveValue?: number;
+    buySlippageBps?: number;
+    sellSlippageBps?: number;
+    perOrderFee?: number;
+    /** When set, this symbol is treated as cash: no orders, no price required. */
+    cashSymbol?: string;
+}
+export interface RebalancePlan {
+    triggered: boolean;
+    portfolioDriftPercentPoints: number;
+    reason: 'below_threshold' | 'ok' | 'no_orders';
+    orders: TradeOrder[];
+}
+/** Minimum portfolio drift (in percentage points) required before rebalancing is triggered. */
+export declare const PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS = 25;
+/** Ignore tiny deltas below this notional value to avoid dust trades. */
+export declare const REBALANCE_MIN_TRADE_VALUE = 1;
+/** Default quantity precision for fractionable symbols (100 = 2 decimal places). */
+export declare const REBALANCE_QUANTITY_PRECISION = 100;
+/** Quantity precision for whole-share-only symbols (1 = integer shares only). */
+export declare const REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION = 1;
+/** Numeric tolerance for floating-point comparisons. */
+export declare const REBALANCE_EPSILON = 1e-9;
+/** Keep this % of cash unallocated as a safety reserve. */
+export declare const REBALANCE_CASH_RESERVE_PERCENT = 1;
+/** Absolute minimum dollar reserve kept as cash. */
+export declare const REBALANCE_MIN_CASH_RESERVE_VALUE = 10;
+/** Inflate buy pricing by this many basis points when sizing orders. */
+export declare const REBALANCE_BUY_SLIPPAGE_BPS = 30;
+/** Haircut expected sell proceeds by this many basis points when funding buys. */
+export declare const REBALANCE_SELL_SLIPPAGE_BPS = 20;
+/** Flat per-order fee assumption used in funding math. */
+export declare const REBALANCE_PER_ORDER_FEE = 0;
+/** Canonical symbol used in targetWeights when strategy holds cash. */
+export declare const REBALANCE_CASH_SYMBOL = "CASH";
+/** Strategy ticker that means "hold as cash". */
+export declare const REBALANCE_CASH_SOURCE_SYMBOL = "DTB3";
+export declare function computePortfolioDriftPercentPoints(input: {
+    targetWeights: Record<string, number>;
+    currentValues: Record<string, number>;
+    cashValue: number;
+    totalValue: number;
+}): number;
+export declare function buildRebalancePlan(input: RebalancePlanInput): RebalancePlan;
+//# sourceMappingURL=rebalance.d.ts.map

package/dist/portfolio/rebalance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebalance.d.ts","sourceRoot":"","sources":["../../src/portfolio/rebalance.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,yBAAyB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,oCAAoC,CAAC,EAAE,MAAM,CAAC;IAC9C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,2BAA2B,EAAE,MAAM,CAAC;IACpC,MAAM,EAAE,iBAAiB,GAAG,IAAI,GAAG,WAAW,CAAC;IAC/C,MAAM,EAAE,UAAU,EAAE,CAAC;CACtB;AAMD,+FAA+F;AAC/F,eAAO,MAAM,wCAAwC,KAAK,CAAC;AAC3D,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAC3C,oFAAoF;AACpF,eAAO,MAAM,4BAA4B,MAAM,CAAC;AAChD,iFAAiF;AACjF,eAAO,MAAM,wCAAwC,IAAI,CAAC;AAC1D,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,2DAA2D;AAC3D,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,oDAAoD;AACpD,eAAO,MAAM,gCAAgC,KAAK,CAAC;AACnD,wEAAwE;AACxE,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAC7C,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,KAAK,CAAC;AAC9C,0DAA0D;AAC1D,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,uEAAuE;AACvE,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAC5C,iDAAiD;AACjD,eAAO,MAAM,4BAA4B,SAAS,CAAC;AAsCnD,wBAAgB,kCAAkC,CAAC,KAAK,EAAE;IACxD,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,MAAM,CAiCT;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,GAAG,aAAa,CAoI3E"}

package/dist/portfolio/rebalance.js

@@ -0,0 +1,205 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REBALANCE_CASH_SOURCE_SYMBOL = exports.REBALANCE_CASH_SYMBOL = exports.REBALANCE_PER_ORDER_FEE = exports.REBALANCE_SELL_SLIPPAGE_BPS = exports.REBALANCE_BUY_SLIPPAGE_BPS = exports.REBALANCE_MIN_CASH_RESERVE_VALUE = exports.REBALANCE_CASH_RESERVE_PERCENT = exports.REBALANCE_EPSILON = exports.REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION = exports.REBALANCE_QUANTITY_PRECISION = exports.REBALANCE_MIN_TRADE_VALUE = exports.PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS = void 0;
+exports.computePortfolioDriftPercentPoints = computePortfolioDriftPercentPoints;
+exports.buildRebalancePlan = buildRebalancePlan;
+// ---------------------------------------------------------------------------
+// Constants (exported so consumers can import defaults)
+// ---------------------------------------------------------------------------
+/** Minimum portfolio drift (in percentage points) required before rebalancing is triggered. */
+exports.PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS = 25;
+/** Ignore tiny deltas below this notional value to avoid dust trades. */
+exports.REBALANCE_MIN_TRADE_VALUE = 1;
+/** Default quantity precision for fractionable symbols (100 = 2 decimal places). */
+exports.REBALANCE_QUANTITY_PRECISION = 100;
+/** Quantity precision for whole-share-only symbols (1 = integer shares only). */
+exports.REBALANCE_WHOLE_SHARE_QUANTITY_PRECISION = 1;
+/** Numeric tolerance for floating-point comparisons. */
+exports.REBALANCE_EPSILON = 1e-9;
+/** Keep this % of cash unallocated as a safety reserve. */
+exports.REBALANCE_CASH_RESERVE_PERCENT = 1;
+/** Absolute minimum dollar reserve kept as cash. */
+exports.REBALANCE_MIN_CASH_RESERVE_VALUE = 10;
+/** Inflate buy pricing by this many basis points when sizing orders. */
+exports.REBALANCE_BUY_SLIPPAGE_BPS = 30;
+/** Haircut expected sell proceeds by this many basis points when funding buys. */
+exports.REBALANCE_SELL_SLIPPAGE_BPS = 20;
+/** Flat per-order fee assumption used in funding math. */
+exports.REBALANCE_PER_ORDER_FEE = 0;
+/** Canonical symbol used in targetWeights when strategy holds cash. */
+exports.REBALANCE_CASH_SYMBOL = 'CASH';
+/** Strategy ticker that means "hold as cash". */
+exports.REBALANCE_CASH_SOURCE_SYMBOL = 'DTB3';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function assertFiniteNumber(name, value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Invalid numeric value for ${name}`);
+    }
+}
+function assertNonNegative(name, value) {
+    assertFiniteNumber(name, value);
+    if (value < 0) {
+        throw new Error(`Invalid negative value for ${name}`);
+    }
+}
+function assertPositive(name, value) {
+    assertFiniteNumber(name, value);
+    if (value <= 0) {
+        throw new Error(`Invalid non-positive value for ${name}`);
+    }
+}
+function quantityFromNotional(notional, price, quantityPrecision) {
+    return Math.floor((notional / price) * quantityPrecision) / quantityPrecision;
+}
+function bpsToFraction(bps) {
+    return bps / 10_000;
+}
+// ---------------------------------------------------------------------------
+// Public functions
+// ---------------------------------------------------------------------------
+function computePortfolioDriftPercentPoints(input) {
+    const { targetWeights, currentValues, cashValue, totalValue } = input;
+    assertPositive('totalValue', totalValue);
+    assertNonNegative('cashValue', cashValue);
+    let targetWeightSum = 0;
+    for (const [symbol, weight] of Object.entries(targetWeights)) {
+        assertNonNegative(`targetWeight(${symbol})`, weight);
+        targetWeightSum += weight;
+    }
+    if (targetWeightSum > 100 + exports.REBALANCE_EPSILON) {
+        throw new Error(`Invalid target weights: sum exceeds 100 (${targetWeightSum.toFixed(4)})`);
+    }
+    const symbols = new Set([...Object.keys(targetWeights), ...Object.keys(currentValues)]);
+    let absSum = 0;
+    for (const symbol of symbols) {
+        const currentValue = currentValues[symbol] ?? 0;
+        assertNonNegative(`currentValue(${symbol})`, currentValue);
+        const currentWeight = (currentValue / totalValue) * 100;
+        const targetWeight = targetWeights[symbol] ?? 0;
+        absSum += Math.abs(targetWeight - currentWeight);
+    }
+    // Only add implicit cash when target weights don't sum to 100 (no explicit cash ticker).
+    if (targetWeightSum < 100) {
+        const targetCashWeight = 100 - targetWeightSum;
+        const currentCashWeight = (cashValue / totalValue) * 100;
+        absSum += Math.abs(targetCashWeight - currentCashWeight);
+    }
+    return absSum / 2;
+}
+function buildRebalancePlan(input) {
+    const { targetWeights, currentValues, prices, quantityPrecisionBySymbol, cashValue, totalValue, portfolioDriftThresholdPercentPoints = exports.PORTFOLIO_DRIFT_THRESHOLD_PERCENT_POINTS, minTradeValue = exports.REBALANCE_MIN_TRADE_VALUE, cashReservePercent = exports.REBALANCE_CASH_RESERVE_PERCENT, minCashReserveValue = exports.REBALANCE_MIN_CASH_RESERVE_VALUE, buySlippageBps = exports.REBALANCE_BUY_SLIPPAGE_BPS, sellSlippageBps = exports.REBALANCE_SELL_SLIPPAGE_BPS, perOrderFee = exports.REBALANCE_PER_ORDER_FEE, cashSymbol, } = input;
+    assertPositive('totalValue', totalValue);
+    assertNonNegative('cashValue', cashValue);
+    assertNonNegative('portfolioDriftThresholdPercentPoints', portfolioDriftThresholdPercentPoints);
+    assertNonNegative('minTradeValue', minTradeValue);
+    assertNonNegative('cashReservePercent', cashReservePercent);
+    assertNonNegative('minCashReserveValue', minCashReserveValue);
+    assertNonNegative('buySlippageBps', buySlippageBps);
+    assertNonNegative('sellSlippageBps', sellSlippageBps);
+    assertNonNegative('perOrderFee', perOrderFee);
+    for (const [symbol, precision] of Object.entries(quantityPrecisionBySymbol ?? {})) {
+        assertPositive(`quantityPrecisionBySymbol(${symbol})`, precision);
+    }
+    const portfolioDriftPercentPoints = computePortfolioDriftPercentPoints({
+        targetWeights,
+        currentValues,
+        cashValue,
+        totalValue,
+    });
+    if (portfolioDriftPercentPoints < portfolioDriftThresholdPercentPoints) {
+        return {
+            triggered: false,
+            portfolioDriftPercentPoints,
+            reason: 'below_threshold',
+            orders: [],
+        };
+    }
+    const symbols = new Set([...Object.keys(targetWeights), ...Object.keys(currentValues)]);
+    const sellCandidates = [];
+    const buyCandidates = [];
+    for (const symbol of symbols) {
+        if (cashSymbol != null && symbol === cashSymbol)
+            continue;
+        const currentValue = currentValues[symbol] ?? 0;
+        assertNonNegative(`currentValue(${symbol})`, currentValue);
+        const targetWeight = targetWeights[symbol] ?? 0;
+        const targetValue = (targetWeight / 100) * totalValue;
+        const delta = targetValue - currentValue;
+        if (Math.abs(delta) <= minTradeValue)
+            continue;
+        const price = prices[symbol];
+        assertPositive(`price(${symbol})`, price);
+        if (delta < 0) {
+            sellCandidates.push({ symbol, notional: Math.abs(delta), price });
+        }
+        else {
+            buyCandidates.push({ symbol, notional: delta, price });
+        }
+    }
+    sellCandidates.sort((a, b) => b.notional - a.notional);
+    buyCandidates.sort((a, b) => b.notional - a.notional);
+    const orders = [];
+    const reserveValue = Math.max(minCashReserveValue, cashValue * (cashReservePercent / 100));
+    let availableFunds = Math.max(0, cashValue - reserveValue);
+    const buySlippageMultiplier = 1 + bpsToFraction(buySlippageBps);
+    const sellSlippageMultiplier = 1 - bpsToFraction(sellSlippageBps);
+    for (const candidate of sellCandidates) {
+        const quantityPrecision = quantityPrecisionBySymbol?.[candidate.symbol] ?? exports.REBALANCE_QUANTITY_PRECISION;
+        const quantity = quantityFromNotional(candidate.notional, candidate.price, quantityPrecision);
+        if (quantity <= 0)
+            continue;
+        const estimatedValue = quantity * candidate.price;
+        if (estimatedValue <= minTradeValue)
+            continue;
+        orders.push({
+            action: 'SELL',
+            symbol: candidate.symbol,
+            quantity,
+            estimatedPrice: candidate.price,
+            estimatedValue,
+        });
+        const netProceeds = Math.max(0, estimatedValue * sellSlippageMultiplier - perOrderFee);
+        availableFunds += netProceeds;
+    }
+    for (const candidate of buyCandidates) {
+        if (availableFunds <= minTradeValue)
+            break;
+        const maxAffordableNotional = Math.max(0, availableFunds - perOrderFee);
+        const cappedNotional = Math.min(candidate.notional, maxAffordableNotional);
+        const effectiveBuyPrice = candidate.price * buySlippageMultiplier;
+        const quantityPrecision = quantityPrecisionBySymbol?.[candidate.symbol] ?? exports.REBALANCE_QUANTITY_PRECISION;
+        const quantity = quantityFromNotional(cappedNotional, effectiveBuyPrice, quantityPrecision);
+        if (quantity <= 0)
+            continue;
+        const estimatedValue = quantity * candidate.price;
+        if (estimatedValue <= minTradeValue)
+            continue;
+        const reservedCost = quantity * effectiveBuyPrice + perOrderFee;
+        if (reservedCost > availableFunds + exports.REBALANCE_EPSILON)
+            continue;
+        orders.push({
+            action: 'BUY',
+            symbol: candidate.symbol,
+            quantity,
+            estimatedPrice: candidate.price,
+            estimatedValue,
+        });
+        availableFunds = Math.max(0, availableFunds - reservedCost);
+    }
+    orders.sort((a, b) => {
+        if (a.action === 'SELL' && b.action === 'BUY')
+            return -1;
+        if (a.action === 'BUY' && b.action === 'SELL')
+            return 1;
+        return 0;
+    });
+    return {
+        triggered: true,
+        portfolioDriftPercentPoints,
+        reason: orders.length > 0 ? 'ok' : 'no_orders',
+        orders,
+    };
+}
+//# sourceMappingURL=rebalance.js.map

package/dist/portfolio/rebalance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rebalance.js","sourceRoot":"","sources":["../../src/portfolio/rebalance.ts"],"names":[],"mappings":"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"}

package/dist/portfolio/symbols.d.ts

@@ -0,0 +1,13 @@
+import type { Ticker } from '../strategy/types';
+/** Maps FRED rate symbols to tradable equivalents. `null` = hold as cash. */
+export declare const FRED_TRADABLE_MAP: Record<string, string | null>;
+/** Normalizes equivalent base tickers to a canonical symbol for leverage lookups. */
+export declare const BASE_TICKER_ALIASES: Record<string, string>;
+/** Maps "SYMBOL:LEVERAGE" to the actual leveraged/inverse ETF ticker. Covers bull (2x/3x) and inverse (-1x/-2x/-3x). */
+export declare const ETF_LEVERAGE_MAP: Record<string, string>;
+/**
+ * Maps a strategy ticker to its tradable symbol.
+ * Pipeline: FRED mapping -> leveraged/inverse ETF lookup (with alias normalization) -> passthrough.
+ */
+export declare function mapTickerToTradable(ticker: Ticker): string | null;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/portfolio/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../../src/portfolio/symbols.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAEhD,6EAA6E;AAC7E,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAG3D,CAAC;AAEF,qFAAqF;AACrF,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGtD,CAAC;AAEF,wHAAwH;AACxH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAoFnD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkBjE"}