@livefolio/sdk 0.2.7 → 0.2.8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +74 -1
- package/dist/market/client.d.ts.map +1 -1
- package/dist/market/client.js +12 -1
- package/dist/market/client.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @livefolio/sdk
|
|
2
2
|
|
|
3
|
-
TypeScript SDK for market data, strategy evaluation, and portfolio
|
|
3
|
+
Open-source TypeScript SDK for market data, deterministic strategy evaluation and backtesting, live signal streaming, and portfolio rebalance planning.
|
|
4
4
|
|
|
5
5
|
## Install
|
|
6
6
|
|
|
@@ -51,9 +51,35 @@ import { createStrategy } from '@livefolio/sdk/strategy';
|
|
|
51
51
|
|
|
52
52
|
Full method reference, arguments, return types, and usage examples: **[docs/](./docs/)**
|
|
53
53
|
|
|
54
|
+
## What The SDK Supports Today
|
|
55
|
+
|
|
56
|
+
The current public surface is strongest in four areas:
|
|
57
|
+
|
|
58
|
+
- Market data: historical daily series, quotes, trading-day lookups, and tracked ticker helpers
|
|
59
|
+
- Strategy engine: strategy retrieval, deterministic evaluation, pure evaluation helpers, live streaming updates, and rules compilation
|
|
60
|
+
- Backtesting: DB-backed historical backtests plus performance metric helpers
|
|
61
|
+
- Portfolio tooling: drift calculations, rebalance planning, and ticker-to-tradable mapping
|
|
62
|
+
|
|
63
|
+
`livefolio.auth` is intentionally lightweight, and `livefolio.portfolio` is best described today as portfolio tooling rather than a full brokerage integration layer.
|
|
64
|
+
|
|
65
|
+
## Community Contribution Areas
|
|
66
|
+
|
|
67
|
+
Good areas for community contributions:
|
|
68
|
+
|
|
69
|
+
- New indicator types and strategy primitives
|
|
70
|
+
- Additional market data adapters and quote providers
|
|
71
|
+
- Backtest realism improvements such as fees, slippage, taxes, and execution assumptions
|
|
72
|
+
- Portfolio and rebalancing logic, including tradable mappings and execution planning
|
|
73
|
+
- Broker and custodian adapters
|
|
74
|
+
- Examples, docs, notebooks, and app integrations
|
|
75
|
+
- Performance, caching, and test coverage improvements
|
|
76
|
+
|
|
77
|
+
If you are evaluating where to contribute first, the highest-leverage work is usually in `market/`, `strategy/`, `portfolio/rebalance`, and the docs/examples around those modules.
|
|
78
|
+
|
|
54
79
|
## Development
|
|
55
80
|
|
|
56
81
|
```bash
|
|
82
|
+
npm install
|
|
57
83
|
npm run build # compile TypeScript → dist/
|
|
58
84
|
npm test # run tests
|
|
59
85
|
npm run ingest:init # backfill price_observations from Yahoo
|
|
@@ -61,6 +87,53 @@ npm run ingest:daily # refresh latest daily bars
|
|
|
61
87
|
npm run backtest:smoke -- --linkId <strategy-link-id>
|
|
62
88
|
```
|
|
63
89
|
|
|
90
|
+
## Contributing Locally
|
|
91
|
+
|
|
92
|
+
Most contributors only need the default local workflow:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
git clone https://github.com/livefolio/sdk.git
|
|
96
|
+
cd sdk
|
|
97
|
+
npm install
|
|
98
|
+
npm run build
|
|
99
|
+
npm test
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
The test suite mocks Supabase at the boundary, so most SDK work does not require a running backend.
|
|
103
|
+
|
|
104
|
+
If you are working on market ingestion, DB-backed backtests, or cache-through evaluation flows, set local Supabase credentials first:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
export SUPABASE_URL=http://127.0.0.1:54321
|
|
108
|
+
export SUPABASE_ANON_KEY=<local-anon-key>
|
|
109
|
+
export SUPABASE_SERVICE_ROLE_KEY=<local-service-role-key>
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Then you can run the data-backed workflows:
|
|
113
|
+
|
|
114
|
+
```bash
|
|
115
|
+
npm run ingest:init
|
|
116
|
+
npm run ingest:daily
|
|
117
|
+
npm run backtest:smoke -- --linkId <strategy-link-id>
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Contributor expectations:
|
|
121
|
+
|
|
122
|
+
- Run `npm run build` and `npm test` before opening a PR
|
|
123
|
+
- Add unit tests for new exported behavior
|
|
124
|
+
- Update `docs/` when adding or changing public module methods
|
|
125
|
+
- Prefer narrow deterministic tests over large integration-only coverage
|
|
126
|
+
|
|
127
|
+
## Open Source Scope
|
|
128
|
+
|
|
129
|
+
The SDK is intended for developers building transparent, rules-based investing software. Community maintainers can use it to:
|
|
130
|
+
|
|
131
|
+
- Fetch market data and trading calendars
|
|
132
|
+
- Define, compile, evaluate, and stream rule-based strategies
|
|
133
|
+
- Run deterministic backtests over historical data
|
|
134
|
+
- Compute portfolio drift and generate rebalance plans
|
|
135
|
+
- Integrate Livefolio-compatible strategy definitions into custom apps and research workflows
|
|
136
|
+
|
|
64
137
|
PRs to `main` run build + tests and enforce a version bump. Merges auto-publish to npm.
|
|
65
138
|
|
|
66
139
|
## License
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/market/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,SAAS,CAAC;
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/market/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AACpD,OAAO,KAAK,EAA2B,YAAY,EAAE,MAAM,SAAS,CAAC;AAsBrE,wBAAgB,YAAY,CAAC,MAAM,EAAE,mBAAmB,GAAG,YAAY,CA+FtE"}
|
package/dist/market/client.js
CHANGED
|
@@ -1,6 +1,17 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.createMarket = createMarket;
|
|
4
|
+
function requireMarketCloseTimestamp(row) {
|
|
5
|
+
const raw = row.timestamp_400pm_et;
|
|
6
|
+
if (typeof raw !== 'string' || raw.length === 0) {
|
|
7
|
+
throw new Error(`Missing timestamp_400pm_et for ${row.symbol} on ${row.date}. ` +
|
|
8
|
+
'Price rows without a market-close timestamp cannot be evaluated safely.');
|
|
9
|
+
}
|
|
10
|
+
if (!Number.isFinite(new Date(raw).getTime())) {
|
|
11
|
+
throw new Error(`Invalid timestamp_400pm_et for ${row.symbol} on ${row.date}: ${raw}`);
|
|
12
|
+
}
|
|
13
|
+
return raw;
|
|
14
|
+
}
|
|
4
15
|
function createMarket(client) {
|
|
5
16
|
return {
|
|
6
17
|
async getBatchSeries(symbols) {
|
|
@@ -31,7 +42,7 @@ function createMarket(client) {
|
|
|
31
42
|
if (!out[symbol])
|
|
32
43
|
out[symbol] = [];
|
|
33
44
|
out[symbol].push({
|
|
34
|
-
timestamp: row
|
|
45
|
+
timestamp: requireMarketCloseTimestamp(row),
|
|
35
46
|
value: row.price_400pm_et,
|
|
36
47
|
});
|
|
37
48
|
}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/market/client.ts"],"names":[],"mappings":";;
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/market/client.ts"],"names":[],"mappings":"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"}
|