sentisense 0.72.1 → 0.74.0
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 +32 -1
- package/dist/cli.cjs +338 -6
- package/dist/index.cjs +64 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +233 -4
- package/dist/index.d.ts +233 -4
- package/dist/index.mjs +64 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -75,6 +75,7 @@ npx -y sentisense@latest health
|
|
|
75
75
|
| `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades. `--coverage` for who covers it, by firm |
|
|
76
76
|
| `analyst <slug>` | One analyst: their firms, their coverage book, and `--calls` for their price target notes |
|
|
77
77
|
| `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one (`earnings AAPL`) |
|
|
78
|
+
| `kpis <ticker>` | Company KPIs from earnings filings: latest value and year-over-year change per series, `--series ID` for one series' history, `--types` for the series list, `--coverage` for the covered tickers |
|
|
78
79
|
| `insiders <ticker>` | Filed Form 4 transactions, including whether they were pre-planned |
|
|
79
80
|
| `insights <ticker>` | Generated signals, filterable by `--urgency` and `--type` |
|
|
80
81
|
| `congress [ticker]` | Congressional disclosures, market-wide or for one symbol |
|
|
@@ -192,7 +193,7 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
|
|
|
192
193
|
| `etfs` | `analystAggregate` `insiderAggregate` `sentimentAggregate` |
|
|
193
194
|
| `insider` | `getActivity` `getTrades` `getClusterBuys` |
|
|
194
195
|
| `insights` | `stock` `stockRange` `market` `latest` `user` |
|
|
195
|
-
| `institutional` | `getFlows` `getHolders` `getHoldersHistory` `getActivists` |
|
|
196
|
+
| `institutional` | `getFlows` `getHolders` `getHoldersHistory` `getInstitutionHistory` `getActivists` |
|
|
196
197
|
| `options` | `getOverview` |
|
|
197
198
|
| `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
|
|
198
199
|
| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` `getOptionsIntradayHistory` |
|
|
@@ -306,6 +307,8 @@ client.institutional.getFlows("2025-02-14", { limit: 20 })
|
|
|
306
307
|
client.institutional.getHolders("AAPL", "2025-02-14")
|
|
307
308
|
client.institutional.getHolders("AAPL") // no date: the ticker's latest settled quarter
|
|
308
309
|
client.institutional.getHoldersHistory("AAPL", { quarters: 8 })
|
|
310
|
+
client.institutional.getInstitutionDetail("Berkshire-Hathaway", { limit: 10, sortBy: "estimatedFlowUsd" })
|
|
311
|
+
client.institutional.getInstitutionHistory("Renaissance-Technologies", { quarters: 8, tickers: ["NVDA"] })
|
|
309
312
|
client.institutional.getActivists("2025-02-14")
|
|
310
313
|
```
|
|
311
314
|
|
|
@@ -347,6 +350,34 @@ const detail = await client.institutional.getInstitutionDetail("1067983") as Pre
|
|
|
347
350
|
console.log(detail.data.positionsHeld); // undefined when an older response omits it
|
|
348
351
|
```
|
|
349
352
|
|
|
353
|
+
Institution detail compares each filing with the quarter before it. When `comparisonStatus` is `AVAILABLE`, the payload carries `priorTotalValueUsd` and `priorPositionsHeld`, and each holding carries `priorValueUsd`, `priorPortfolioWeight` and `estimatedFlowUsd` (dollars bought, positive, or sold, negative, estimated from two quarter-end snapshots rather than a reported trade). Every one of these is absent when it does not apply. Pass `limit` to get a sorted page of holdings, with `sortBy`, `sortDir`, `changeType` (a value or an array; `"HELD"` keeps every position still held, whatever its change), `q` and `minWeight` to sort and filter it; those only take effect together with `limit`. When a filter is set, `data.matchTotals` sums every matching holding, not just the page:
|
|
354
|
+
|
|
355
|
+
```typescript
|
|
356
|
+
// The ten biggest estimated buys of the latest quarter
|
|
357
|
+
const page = await client.institutional.getInstitutionDetail("Berkshire-Hathaway", {
|
|
358
|
+
limit: 10,
|
|
359
|
+
sortBy: "estimatedFlowUsd",
|
|
360
|
+
changeType: ["NEW", "INCREASED"],
|
|
361
|
+
}) as PreviewResponse<InstitutionDetail>;
|
|
362
|
+
for (const h of page.data.holdings ?? []) console.log(h.ticker, h.estimatedFlowUsd);
|
|
363
|
+
console.log(page.data.matchTotals?.estimatedFlowUsd); // every matching holding, not only these ten
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
**Institution history.** `getInstitutionHistory()` returns one row per filing, newest first (`quarters` up to 40, 12 by default). Free keys see the newest four, with `totalCount` naming the window. The comparison fields (`newPositions`, `boughtUsd`, `netFlowUsd` and the rest) are absent unless that filing's `comparisonStatus` is `AVAILABLE`, never zero. Pass `tickers` (up to 100) to also get `positions`: each ticker's shares and value per filing, newest first, with filings where the institution did not hold it left out. Free keys receive `positions` only for the institution's ten largest holdings. `priceEffectUsd` is the remainder after `netFlowUsd`, mostly price moves; it also absorbs rounding, the different price bases of exits and trades, and positions whose change could not be restated:
|
|
367
|
+
|
|
368
|
+
```typescript
|
|
369
|
+
const { data } = await client.institutional.getInstitutionHistory("Renaissance-Technologies", {
|
|
370
|
+
quarters: 8,
|
|
371
|
+
tickers: ["NVDA", "META"],
|
|
372
|
+
});
|
|
373
|
+
for (const q of data.quarters) {
|
|
374
|
+
console.log(q.label, q.totalValueUsd, q.netFlowUsd, q.priceEffectUsd);
|
|
375
|
+
}
|
|
376
|
+
for (const point of data.positions?.NVDA ?? []) {
|
|
377
|
+
console.log(point.reportDate, point.shares, point.valueUsd);
|
|
378
|
+
}
|
|
379
|
+
```
|
|
380
|
+
|
|
350
381
|
**Paging the holder list.** A widely held ticker returns thousands of rows: a megacap quarter is roughly 6,000 holders and 1.5 MB on the wire. Pass `limit` unless you really want the whole list; omitting the options object sends the original unbounded request, so existing code keeps working.
|
|
351
382
|
|
|
352
383
|
| Option | Values |
|
package/dist/cli.cjs
CHANGED
|
@@ -1264,9 +1264,9 @@ function latestSettledQuarter(quarters) {
|
|
|
1264
1264
|
const dated = quarters.filter(
|
|
1265
1265
|
(q) => typeof q.reportDate === "string"
|
|
1266
1266
|
);
|
|
1267
|
-
const
|
|
1268
|
-
const settled =
|
|
1269
|
-
return (settled ??
|
|
1267
|
+
const newestFirst2 = [...dated].sort((a, b) => b.reportDate.localeCompare(a.reportDate));
|
|
1268
|
+
const settled = newestFirst2.find((q) => q.pending !== true);
|
|
1269
|
+
return (settled ?? newestFirst2[0])?.reportDate;
|
|
1270
1270
|
}
|
|
1271
1271
|
var flowsCommand = {
|
|
1272
1272
|
name: "flows",
|
|
@@ -1432,7 +1432,7 @@ var flowsCommand = {
|
|
|
1432
1432
|
};
|
|
1433
1433
|
|
|
1434
1434
|
// src/version.ts
|
|
1435
|
-
var VERSION = "0.
|
|
1435
|
+
var VERSION = "0.74.0";
|
|
1436
1436
|
|
|
1437
1437
|
// src/resources/analyst.ts
|
|
1438
1438
|
var Analyst = class {
|
|
@@ -2226,10 +2226,71 @@ var Institutional = class {
|
|
|
2226
2226
|
* The signature remains unknown for compatibility. Opt in to the exported
|
|
2227
2227
|
* PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
|
|
2228
2228
|
* portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
|
|
2229
|
+
*
|
|
2230
|
+
* When the filing compares with the preceding quarter (`comparisonStatus` is `AVAILABLE`),
|
|
2231
|
+
* the payload also carries `priorTotalValueUsd` and `priorPositionsHeld`, and each holding
|
|
2232
|
+
* carries `priorValueUsd`, `priorPortfolioWeight` and `estimatedFlowUsd` (an estimate from
|
|
2233
|
+
* two quarter-end snapshots, not a reported trade). Each is absent when it does not apply.
|
|
2234
|
+
*
|
|
2235
|
+
* `options.limit` returns a sorted page of holdings and adds `returnedCount` and `offset` to
|
|
2236
|
+
* `data` and `totalCount` to the envelope; `sortBy`, `sortDir`, `changeType`, `q` and
|
|
2237
|
+
* `minWeight` only take effect together with it (PRO only). `changeType` also accepts `"HELD"`,
|
|
2238
|
+
* every position still held whatever its change; values combine as a union. With a filter set, `data.matchTotals`
|
|
2239
|
+
* sums every matching holding, not just the page. Calling without `options` is unchanged.
|
|
2240
|
+
*
|
|
2241
|
+
* @example
|
|
2242
|
+
* const page = await client.institutional.getInstitutionDetail("Berkshire-Hathaway", {
|
|
2243
|
+
* limit: 10,
|
|
2244
|
+
* sortBy: "estimatedFlowUsd",
|
|
2245
|
+
* changeType: ["NEW", "INCREASED"],
|
|
2246
|
+
* }) as PreviewResponse<InstitutionDetail>;
|
|
2247
|
+
*/
|
|
2248
|
+
async getInstitutionDetail(slugOrCik, options) {
|
|
2249
|
+
const { changeType, ...rest } = options ?? {};
|
|
2250
|
+
return this.client.get(
|
|
2251
|
+
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}`,
|
|
2252
|
+
{
|
|
2253
|
+
...rest,
|
|
2254
|
+
changeType: typeof changeType === "string" ? changeType : changeType?.join(",") || void 0
|
|
2255
|
+
}
|
|
2256
|
+
);
|
|
2257
|
+
}
|
|
2258
|
+
/**
|
|
2259
|
+
* Get an institution's 13F book filing by filing, newest first.
|
|
2260
|
+
*
|
|
2261
|
+
* Returns the preview envelope wrapping an {@link InstitutionHistory}, so the rows are two
|
|
2262
|
+
* levels down: `(await getInstitutionHistory(s)).data.quarters`. Each row carries the
|
|
2263
|
+
* filing's reported value, positions held and top-10 concentration, and, when it compares
|
|
2264
|
+
* with the quarter before (`comparisonStatus: "AVAILABLE"`), the position counts and the
|
|
2265
|
+
* estimated dollars bought, trimmed and exited. Those comparison fields are absent
|
|
2266
|
+
* otherwise, never zero. The flows are estimates from two quarter-end snapshots, not
|
|
2267
|
+
* reported cash flow. A 13F covers long US-listed equity only.
|
|
2268
|
+
*
|
|
2269
|
+
* Pass `tickers` to also get `data.positions`: each ticker maps to its shares and value per
|
|
2270
|
+
* filing, newest first. A filing in which the institution did not hold the ticker is absent
|
|
2271
|
+
* from its list. Free keys receive positions only for the institution's ten largest
|
|
2272
|
+
* holdings; other tickers are left out.
|
|
2273
|
+
*
|
|
2274
|
+
* Free keys receive the newest four filings with `isPreview: true` and `totalCount` holding
|
|
2275
|
+
* the number of filings in the requested window. The first request for a large multi-filer
|
|
2276
|
+
* institution can take a few seconds; when too many such computations run at once the API
|
|
2277
|
+
* answers 503 with a `Retry-After` header.
|
|
2278
|
+
*
|
|
2279
|
+
* @example
|
|
2280
|
+
* const { data } = await client.institutional.getInstitutionHistory("Renaissance-Technologies", {
|
|
2281
|
+
* quarters: 8,
|
|
2282
|
+
* tickers: ["NVDA", "META"],
|
|
2283
|
+
* });
|
|
2284
|
+
* for (const q of data.quarters) console.log(q.label, q.totalValueUsd, q.netFlowUsd);
|
|
2229
2285
|
*/
|
|
2230
|
-
async
|
|
2286
|
+
async getInstitutionHistory(slugOrCik, options) {
|
|
2287
|
+
const { tickers, ...rest } = options ?? {};
|
|
2231
2288
|
return this.client.get(
|
|
2232
|
-
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}
|
|
2289
|
+
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}/history`,
|
|
2290
|
+
{
|
|
2291
|
+
...rest,
|
|
2292
|
+
tickers: typeof tickers === "string" ? tickers : tickers?.join(",") || void 0
|
|
2293
|
+
}
|
|
2233
2294
|
);
|
|
2234
2295
|
}
|
|
2235
2296
|
};
|
|
@@ -3706,6 +3767,275 @@ var insightsCommand = {
|
|
|
3706
3767
|
}
|
|
3707
3768
|
};
|
|
3708
3769
|
|
|
3770
|
+
// src/cli/commands/kpis.ts
|
|
3771
|
+
var DEFAULT_PERIODS = 12;
|
|
3772
|
+
var DEFAULT_COVERAGE_ROWS2 = 20;
|
|
3773
|
+
function newestFirst(values) {
|
|
3774
|
+
return [...values].sort((a, b) => a.date < b.date ? 1 : a.date > b.date ? -1 : 0);
|
|
3775
|
+
}
|
|
3776
|
+
function yearAgoLabel(period) {
|
|
3777
|
+
const match = /(\d{4})/.exec(period);
|
|
3778
|
+
if (!match) return void 0;
|
|
3779
|
+
const year = Number(match[1]);
|
|
3780
|
+
return `${period.slice(0, match.index)}${year - 1}${period.slice(match.index + 4)}`;
|
|
3781
|
+
}
|
|
3782
|
+
function yearOverYear(series, point) {
|
|
3783
|
+
const label = yearAgoLabel(point.period);
|
|
3784
|
+
const prior = label === void 0 ? void 0 : series.values.find((value) => value.period === label);
|
|
3785
|
+
if (!prior || !Number.isFinite(prior.value) || !Number.isFinite(point.value)) return cell(ABSENT);
|
|
3786
|
+
if (series.unit === "percent") {
|
|
3787
|
+
const diff = point.value - prior.value;
|
|
3788
|
+
return cell(`${signed(diff, 1)} pts`, direction(diff));
|
|
3789
|
+
}
|
|
3790
|
+
if (prior.value <= 0) return cell(ABSENT);
|
|
3791
|
+
const change = (point.value - prior.value) / prior.value * 100;
|
|
3792
|
+
return cell(signedPercent(change, 1), direction(change));
|
|
3793
|
+
}
|
|
3794
|
+
function formatKpiValue(value, series) {
|
|
3795
|
+
if (!Number.isFinite(value)) return ABSENT;
|
|
3796
|
+
const { unit, displayFormat } = series;
|
|
3797
|
+
if (unit === "percent") return percent(value, 1);
|
|
3798
|
+
if (unit === "USD") return displayFormat === "currency" ? money(value) : `$${humanize(value)}`;
|
|
3799
|
+
if (/^[A-Z]{3}$/.test(unit)) {
|
|
3800
|
+
return displayFormat === "currency" ? `${value.toFixed(2)} ${unit}` : `${humanize(value)} ${unit}`;
|
|
3801
|
+
}
|
|
3802
|
+
return unit ? `${humanize(value)} ${unit}` : humanize(value);
|
|
3803
|
+
}
|
|
3804
|
+
async function noCoverage(api, ticker) {
|
|
3805
|
+
await verifyTickerOnEmpty(api, ticker);
|
|
3806
|
+
throw new CliCommandError(
|
|
3807
|
+
`${ticker} has no curated KPI coverage yet.`,
|
|
3808
|
+
'run "sentisense kpis --coverage" for the tickers that have it.',
|
|
3809
|
+
EXIT.NOT_FOUND
|
|
3810
|
+
);
|
|
3811
|
+
}
|
|
3812
|
+
async function orNoCoverage(api, ticker, request) {
|
|
3813
|
+
try {
|
|
3814
|
+
return await request;
|
|
3815
|
+
} catch (error) {
|
|
3816
|
+
if (error instanceof NotFoundError) return noCoverage(api, ticker);
|
|
3817
|
+
throw error;
|
|
3818
|
+
}
|
|
3819
|
+
}
|
|
3820
|
+
var kpisCommand = {
|
|
3821
|
+
name: "kpis",
|
|
3822
|
+
summary: "Company KPIs from earnings filings: segment revenue, deliveries, subscribers",
|
|
3823
|
+
usage: "sentisense kpis <ticker> [--series ID | --types] | sentisense kpis --coverage",
|
|
3824
|
+
examples: [
|
|
3825
|
+
"sentisense kpis TSLA",
|
|
3826
|
+
"sentisense kpis TSLA --series vehicle_deliveries",
|
|
3827
|
+
"sentisense kpis TSLA --types",
|
|
3828
|
+
"sentisense kpis --coverage --full",
|
|
3829
|
+
"sentisense kpis TSLA --json"
|
|
3830
|
+
],
|
|
3831
|
+
notes: [
|
|
3832
|
+
"One row per series: its latest reported period and value, and the change from the same",
|
|
3833
|
+
"period a year earlier, computed only from that series' own values. A percent series",
|
|
3834
|
+
"changes in points. Discontinued series are hidden unless --full.",
|
|
3835
|
+
"--series ID prints that series' periods, newest first. The ids are in the first column.",
|
|
3836
|
+
"--types lists the series without their values, on any key and at no quota cost.",
|
|
3837
|
+
"--coverage lists every covered ticker and marks the sample companies, whose full KPI",
|
|
3838
|
+
"series a free key can read. Other companies return the series list only on a free key;",
|
|
3839
|
+
"PRO returns every series in full.",
|
|
3840
|
+
"A ticker without KPI coverage exits 4 and says so; an unknown symbol exits 4 as a typo.",
|
|
3841
|
+
EMPTY_VERIFY_NOTE,
|
|
3842
|
+
EMPTY_VERIFY_NOTE_2
|
|
3843
|
+
],
|
|
3844
|
+
flags: {
|
|
3845
|
+
series: { type: "string", placeholder: "ID", describe: "Print one series' periods, newest first" },
|
|
3846
|
+
types: { type: "boolean", describe: "List the series without their values (free on any key)" },
|
|
3847
|
+
coverage: { type: "boolean", describe: "List every ticker with KPI coverage" }
|
|
3848
|
+
},
|
|
3849
|
+
async run({ args, client, full }) {
|
|
3850
|
+
if (args.flags.coverage === true) {
|
|
3851
|
+
rejectPositionals(args, "kpis --coverage");
|
|
3852
|
+
return coverageRun2(client(), full);
|
|
3853
|
+
}
|
|
3854
|
+
const ticker = oneTicker(args, "kpis");
|
|
3855
|
+
const series = typeof args.flags.series === "string" ? args.flags.series : void 0;
|
|
3856
|
+
if (series !== void 0 && args.flags.types === true) {
|
|
3857
|
+
throw new CliUsageError("--series and --types do not go together.", "pass one or the other.");
|
|
3858
|
+
}
|
|
3859
|
+
const api = client();
|
|
3860
|
+
if (args.flags.types === true) return typesRun(api, ticker);
|
|
3861
|
+
const envelope = await orNoCoverage(api, ticker, api.stocks.getKpis(ticker));
|
|
3862
|
+
return series === void 0 ? summaryRun(envelope, ticker, full) : seriesRun(envelope, ticker, series, full);
|
|
3863
|
+
}
|
|
3864
|
+
};
|
|
3865
|
+
function headBlock(ticker, data, right) {
|
|
3866
|
+
return {
|
|
3867
|
+
kind: "head",
|
|
3868
|
+
title: field("ticker", ticker),
|
|
3869
|
+
subtitle: data?.companyName ? field("company", data.companyName) : void 0,
|
|
3870
|
+
right: fields(...right)
|
|
3871
|
+
};
|
|
3872
|
+
}
|
|
3873
|
+
function lockedBlocks(envelope, ticker) {
|
|
3874
|
+
if (!envelope.isPreview) return [];
|
|
3875
|
+
return [
|
|
3876
|
+
{
|
|
3877
|
+
kind: "text",
|
|
3878
|
+
text: "Preview response: KPI values for this company are PRO. A free key gets the full series for the sample companies.",
|
|
3879
|
+
tone: "dim"
|
|
3880
|
+
},
|
|
3881
|
+
{ kind: "text", text: `Run "sentisense kpis ${ticker} --types" for the series this company reports.`, tone: "dim" }
|
|
3882
|
+
];
|
|
3883
|
+
}
|
|
3884
|
+
function summaryRun(envelope, ticker, full) {
|
|
3885
|
+
const data = envelope.data;
|
|
3886
|
+
const all = data?.kpis ?? [];
|
|
3887
|
+
const discontinued = all.filter((series) => series.discontinued === true);
|
|
3888
|
+
const shown = full ? all : all.filter((series) => series.discontinued !== true);
|
|
3889
|
+
const blocks = [
|
|
3890
|
+
headBlock(ticker, data, [
|
|
3891
|
+
// A preview's empty list is a gate, not a count, so it prints no "series: 0".
|
|
3892
|
+
envelope.isPreview && all.length === 0 ? void 0 : field("series", String(all.length)),
|
|
3893
|
+
data?.lastUpdated ? field("updated", data.lastUpdated.slice(0, 10)) : void 0
|
|
3894
|
+
])
|
|
3895
|
+
];
|
|
3896
|
+
if (shown.length > 0) {
|
|
3897
|
+
blocks.push({
|
|
3898
|
+
kind: "table",
|
|
3899
|
+
head: ["ID", "SERIES", "PERIOD", "VALUE", "YOY"],
|
|
3900
|
+
align: ["left", "left", "left", "right", "right"],
|
|
3901
|
+
rows: shown.map((series) => {
|
|
3902
|
+
const latest = newestFirst(series.values)[0];
|
|
3903
|
+
const name = `${series.name}${series.discontinued ? " (discontinued)" : ""}`;
|
|
3904
|
+
return [
|
|
3905
|
+
// Never truncated: the id is what --series takes, so it has to copy and paste whole.
|
|
3906
|
+
cell(series.id),
|
|
3907
|
+
cell(truncate(name, full ? 60 : 32), series.discontinued ? "dim" : void 0),
|
|
3908
|
+
cell(latest ? `${latest.period}${latest.isEstimate ? " (prelim)" : ""}` : ABSENT),
|
|
3909
|
+
cell(latest ? formatKpiValue(latest.value, series) : ABSENT),
|
|
3910
|
+
latest ? yearOverYear(series, latest) : cell(ABSENT)
|
|
3911
|
+
];
|
|
3912
|
+
})
|
|
3913
|
+
});
|
|
3914
|
+
if (!full && discontinued.length > 0) {
|
|
3915
|
+
blocks.push({
|
|
3916
|
+
kind: "text",
|
|
3917
|
+
text: `${discontinued.length} discontinued series hidden. Add --full to show them.`,
|
|
3918
|
+
tone: "dim"
|
|
3919
|
+
});
|
|
3920
|
+
}
|
|
3921
|
+
} else if (!envelope.isPreview) {
|
|
3922
|
+
blocks.push({ kind: "text", text: "No KPI series reported for this company." });
|
|
3923
|
+
}
|
|
3924
|
+
blocks.push(...lockedBlocks(envelope, ticker));
|
|
3925
|
+
return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
|
|
3926
|
+
}
|
|
3927
|
+
function seriesRun(envelope, ticker, id, full) {
|
|
3928
|
+
const data = envelope.data;
|
|
3929
|
+
if (envelope.isPreview && (data?.kpis ?? []).length === 0) {
|
|
3930
|
+
const blocks2 = [headBlock(ticker, data, [field("series", id)]), ...lockedBlocks(envelope, ticker)];
|
|
3931
|
+
return { json: envelope, doc: doc(...blocks2, sampleNote(envelope, ticker)) };
|
|
3932
|
+
}
|
|
3933
|
+
const series = (data?.kpis ?? []).find((candidate) => candidate.id === id);
|
|
3934
|
+
if (!series) {
|
|
3935
|
+
throw new CliCommandError(
|
|
3936
|
+
`${ticker} has no KPI series "${id}".`,
|
|
3937
|
+
`run "sentisense kpis ${ticker} --types" for its series ids.`,
|
|
3938
|
+
EXIT.NOT_FOUND
|
|
3939
|
+
);
|
|
3940
|
+
}
|
|
3941
|
+
const values = newestFirst(series.values);
|
|
3942
|
+
const shown = full ? values : values.slice(0, DEFAULT_PERIODS);
|
|
3943
|
+
const blocks = [
|
|
3944
|
+
headBlock(ticker, data, [field("series", series.name), field("periods", String(values.length))])
|
|
3945
|
+
];
|
|
3946
|
+
if (series.discontinued) {
|
|
3947
|
+
blocks.push({
|
|
3948
|
+
kind: "text",
|
|
3949
|
+
text: `Discontinued${series.discontinuedNote ? `: ${series.discontinuedNote}` : "."}`,
|
|
3950
|
+
tone: "dim"
|
|
3951
|
+
});
|
|
3952
|
+
}
|
|
3953
|
+
if (shown.length === 0) {
|
|
3954
|
+
blocks.push({ kind: "text", text: "No reported periods in this series." });
|
|
3955
|
+
} else {
|
|
3956
|
+
blocks.push({
|
|
3957
|
+
kind: "table",
|
|
3958
|
+
head: ["PERIOD", "DATE", "VALUE", "YOY", ""],
|
|
3959
|
+
align: ["left", "left", "right", "right", "left"],
|
|
3960
|
+
rows: shown.map((point) => [
|
|
3961
|
+
cell(point.period),
|
|
3962
|
+
cell(point.date),
|
|
3963
|
+
cell(formatKpiValue(point.value, series)),
|
|
3964
|
+
yearOverYear(series, point),
|
|
3965
|
+
cell(point.isEstimate ? "prelim" : "")
|
|
3966
|
+
])
|
|
3967
|
+
});
|
|
3968
|
+
if (shown.length < values.length) {
|
|
3969
|
+
blocks.push({
|
|
3970
|
+
kind: "text",
|
|
3971
|
+
text: `Showing ${shown.length} of ${values.length} periods. Add --full for the rest.`,
|
|
3972
|
+
tone: "dim"
|
|
3973
|
+
});
|
|
3974
|
+
}
|
|
3975
|
+
}
|
|
3976
|
+
if (series.sourceRef) blocks.push({ kind: "text", text: `Source: ${series.sourceRef}`, tone: "dim" });
|
|
3977
|
+
return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
|
|
3978
|
+
}
|
|
3979
|
+
async function typesRun(api, ticker) {
|
|
3980
|
+
const types = await orNoCoverage(api, ticker, api.stocks.getKpiTypes(ticker));
|
|
3981
|
+
const blocks = [{ kind: "head", title: field("ticker", ticker), right: [field("series", String(types.length))] }];
|
|
3982
|
+
if (types.length === 0) {
|
|
3983
|
+
blocks.push({ kind: "text", text: "No KPI series listed for this company." });
|
|
3984
|
+
} else {
|
|
3985
|
+
blocks.push({
|
|
3986
|
+
kind: "table",
|
|
3987
|
+
head: ["ID", "SERIES", "CATEGORY"],
|
|
3988
|
+
rows: types.map((entry) => [cell(entry.id), cell(entry.name), cell(entry.category)])
|
|
3989
|
+
});
|
|
3990
|
+
}
|
|
3991
|
+
return { json: types, doc: doc(...blocks) };
|
|
3992
|
+
}
|
|
3993
|
+
async function coverageRun2(api, full) {
|
|
3994
|
+
const response = await api.stocks.listKpiCoverage();
|
|
3995
|
+
const rows = response.tickers ?? [];
|
|
3996
|
+
const samples = rows.filter((row) => row.sampleCompany === true);
|
|
3997
|
+
const count = response.count ?? rows.length;
|
|
3998
|
+
const shown = full ? rows : samples.length > 0 ? samples : rows.slice(0, DEFAULT_COVERAGE_ROWS2);
|
|
3999
|
+
const blocks = [
|
|
4000
|
+
{
|
|
4001
|
+
kind: "head",
|
|
4002
|
+
title: field("kpi coverage", `${count} tickers`),
|
|
4003
|
+
right: fields(samples.length > 0 ? field("sample companies", String(samples.length)) : void 0)
|
|
4004
|
+
}
|
|
4005
|
+
];
|
|
4006
|
+
if (shown.length === 0) {
|
|
4007
|
+
blocks.push({ kind: "text", text: "No tickers listed with KPI coverage." });
|
|
4008
|
+
} else {
|
|
4009
|
+
blocks.push({
|
|
4010
|
+
kind: "table",
|
|
4011
|
+
head: ["TICKER", "COMPANY", "SERIES", "UPDATED", "SAMPLE"],
|
|
4012
|
+
align: ["left", "left", "right", "left", "left"],
|
|
4013
|
+
rows: shown.map((row) => [
|
|
4014
|
+
cell(row.ticker),
|
|
4015
|
+
cell(truncate(row.companyName ?? "", full ? 48 : 32)),
|
|
4016
|
+
cell(String(row.kpiCount)),
|
|
4017
|
+
cell((row.lastUpdated ?? "").slice(0, 10)),
|
|
4018
|
+
cell(row.sampleCompany ? "sample" : "", row.sampleCompany ? "accent" : void 0)
|
|
4019
|
+
])
|
|
4020
|
+
});
|
|
4021
|
+
}
|
|
4022
|
+
if (samples.length > 0) {
|
|
4023
|
+
blocks.push({
|
|
4024
|
+
kind: "text",
|
|
4025
|
+
text: `Full KPI data on ${samples.length} sample companies, free; a preview for every other company. PRO unlocks them all.`,
|
|
4026
|
+
tone: "dim"
|
|
4027
|
+
});
|
|
4028
|
+
}
|
|
4029
|
+
if (shown.length < rows.length) {
|
|
4030
|
+
blocks.push({
|
|
4031
|
+
kind: "text",
|
|
4032
|
+
text: samples.length > 0 && !full ? `Showing the ${shown.length} sample companies of ${rows.length} covered tickers. Add --full for all of them.` : `Showing ${shown.length} of ${rows.length} covered tickers. Add --full for all of them.`,
|
|
4033
|
+
tone: "dim"
|
|
4034
|
+
});
|
|
4035
|
+
}
|
|
4036
|
+
return { json: response, doc: doc(...blocks) };
|
|
4037
|
+
}
|
|
4038
|
+
|
|
3709
4039
|
// src/cli/commands/mood.ts
|
|
3710
4040
|
function readMarket(payload) {
|
|
3711
4041
|
if (!payload || typeof payload !== "object") return {};
|
|
@@ -4814,6 +5144,7 @@ var COMMANDS = [
|
|
|
4814
5144
|
analystsCommand,
|
|
4815
5145
|
analystCommand,
|
|
4816
5146
|
earningsCommand,
|
|
5147
|
+
kpisCommand,
|
|
4817
5148
|
insidersCommand,
|
|
4818
5149
|
insightsCommand,
|
|
4819
5150
|
congressCommand,
|
|
@@ -4840,6 +5171,7 @@ var EXAMPLE = {
|
|
|
4840
5171
|
analysts: "sentisense analysts NVDA --coverage",
|
|
4841
5172
|
analyst: "sentisense analyst dan-ives --calls",
|
|
4842
5173
|
earnings: "sentisense earnings --week next",
|
|
5174
|
+
kpis: "sentisense kpis TSLA",
|
|
4843
5175
|
insiders: "sentisense insiders NVDA",
|
|
4844
5176
|
insights: "sentisense insights NVDA",
|
|
4845
5177
|
congress: "sentisense congress NVDA",
|
package/dist/index.cjs
CHANGED
|
@@ -874,10 +874,71 @@ var Institutional = class {
|
|
|
874
874
|
* The signature remains unknown for compatibility. Opt in to the exported
|
|
875
875
|
* PreviewResponse<InstitutionDetail> type to read data.positionsHeld, the full
|
|
876
876
|
* portfolio count excluding SOLD_OUT rows, even on a truncated holdings list.
|
|
877
|
+
*
|
|
878
|
+
* When the filing compares with the preceding quarter (`comparisonStatus` is `AVAILABLE`),
|
|
879
|
+
* the payload also carries `priorTotalValueUsd` and `priorPositionsHeld`, and each holding
|
|
880
|
+
* carries `priorValueUsd`, `priorPortfolioWeight` and `estimatedFlowUsd` (an estimate from
|
|
881
|
+
* two quarter-end snapshots, not a reported trade). Each is absent when it does not apply.
|
|
882
|
+
*
|
|
883
|
+
* `options.limit` returns a sorted page of holdings and adds `returnedCount` and `offset` to
|
|
884
|
+
* `data` and `totalCount` to the envelope; `sortBy`, `sortDir`, `changeType`, `q` and
|
|
885
|
+
* `minWeight` only take effect together with it (PRO only). `changeType` also accepts `"HELD"`,
|
|
886
|
+
* every position still held whatever its change; values combine as a union. With a filter set, `data.matchTotals`
|
|
887
|
+
* sums every matching holding, not just the page. Calling without `options` is unchanged.
|
|
888
|
+
*
|
|
889
|
+
* @example
|
|
890
|
+
* const page = await client.institutional.getInstitutionDetail("Berkshire-Hathaway", {
|
|
891
|
+
* limit: 10,
|
|
892
|
+
* sortBy: "estimatedFlowUsd",
|
|
893
|
+
* changeType: ["NEW", "INCREASED"],
|
|
894
|
+
* }) as PreviewResponse<InstitutionDetail>;
|
|
895
|
+
*/
|
|
896
|
+
async getInstitutionDetail(slugOrCik, options) {
|
|
897
|
+
const { changeType, ...rest } = options ?? {};
|
|
898
|
+
return this.client.get(
|
|
899
|
+
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}`,
|
|
900
|
+
{
|
|
901
|
+
...rest,
|
|
902
|
+
changeType: typeof changeType === "string" ? changeType : changeType?.join(",") || void 0
|
|
903
|
+
}
|
|
904
|
+
);
|
|
905
|
+
}
|
|
906
|
+
/**
|
|
907
|
+
* Get an institution's 13F book filing by filing, newest first.
|
|
908
|
+
*
|
|
909
|
+
* Returns the preview envelope wrapping an {@link InstitutionHistory}, so the rows are two
|
|
910
|
+
* levels down: `(await getInstitutionHistory(s)).data.quarters`. Each row carries the
|
|
911
|
+
* filing's reported value, positions held and top-10 concentration, and, when it compares
|
|
912
|
+
* with the quarter before (`comparisonStatus: "AVAILABLE"`), the position counts and the
|
|
913
|
+
* estimated dollars bought, trimmed and exited. Those comparison fields are absent
|
|
914
|
+
* otherwise, never zero. The flows are estimates from two quarter-end snapshots, not
|
|
915
|
+
* reported cash flow. A 13F covers long US-listed equity only.
|
|
916
|
+
*
|
|
917
|
+
* Pass `tickers` to also get `data.positions`: each ticker maps to its shares and value per
|
|
918
|
+
* filing, newest first. A filing in which the institution did not hold the ticker is absent
|
|
919
|
+
* from its list. Free keys receive positions only for the institution's ten largest
|
|
920
|
+
* holdings; other tickers are left out.
|
|
921
|
+
*
|
|
922
|
+
* Free keys receive the newest four filings with `isPreview: true` and `totalCount` holding
|
|
923
|
+
* the number of filings in the requested window. The first request for a large multi-filer
|
|
924
|
+
* institution can take a few seconds; when too many such computations run at once the API
|
|
925
|
+
* answers 503 with a `Retry-After` header.
|
|
926
|
+
*
|
|
927
|
+
* @example
|
|
928
|
+
* const { data } = await client.institutional.getInstitutionHistory("Renaissance-Technologies", {
|
|
929
|
+
* quarters: 8,
|
|
930
|
+
* tickers: ["NVDA", "META"],
|
|
931
|
+
* });
|
|
932
|
+
* for (const q of data.quarters) console.log(q.label, q.totalValueUsd, q.netFlowUsd);
|
|
877
933
|
*/
|
|
878
|
-
async
|
|
934
|
+
async getInstitutionHistory(slugOrCik, options) {
|
|
935
|
+
const { tickers, ...rest } = options ?? {};
|
|
879
936
|
return this.client.get(
|
|
880
|
-
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}
|
|
937
|
+
`/api/v1/institutional/institution/${encodeURIComponent(slugOrCik)}/history`,
|
|
938
|
+
{
|
|
939
|
+
...rest,
|
|
940
|
+
tickers: typeof tickers === "string" ? tickers : tickers?.join(",") || void 0
|
|
941
|
+
}
|
|
881
942
|
);
|
|
882
943
|
}
|
|
883
944
|
};
|
|
@@ -1475,7 +1536,7 @@ var Trackers = class {
|
|
|
1475
1536
|
};
|
|
1476
1537
|
|
|
1477
1538
|
// src/version.ts
|
|
1478
|
-
var VERSION = "0.
|
|
1539
|
+
var VERSION = "0.74.0";
|
|
1479
1540
|
|
|
1480
1541
|
// src/client.ts
|
|
1481
1542
|
var DEFAULT_BASE_URL = "https://app.sentisense.ai";
|