sentisense 0.72.1 → 0.73.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 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 |
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 newestFirst = [...dated].sort((a, b) => b.reportDate.localeCompare(a.reportDate));
1268
- const settled = newestFirst.find((q) => q.pending !== true);
1269
- return (settled ?? newestFirst[0])?.reportDate;
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.72.1";
1435
+ var VERSION = "0.73.0";
1436
1436
 
1437
1437
  // src/resources/analyst.ts
1438
1438
  var Analyst = class {
@@ -3706,6 +3706,275 @@ var insightsCommand = {
3706
3706
  }
3707
3707
  };
3708
3708
 
3709
+ // src/cli/commands/kpis.ts
3710
+ var DEFAULT_PERIODS = 12;
3711
+ var DEFAULT_COVERAGE_ROWS2 = 20;
3712
+ function newestFirst(values) {
3713
+ return [...values].sort((a, b) => a.date < b.date ? 1 : a.date > b.date ? -1 : 0);
3714
+ }
3715
+ function yearAgoLabel(period) {
3716
+ const match = /(\d{4})/.exec(period);
3717
+ if (!match) return void 0;
3718
+ const year = Number(match[1]);
3719
+ return `${period.slice(0, match.index)}${year - 1}${period.slice(match.index + 4)}`;
3720
+ }
3721
+ function yearOverYear(series, point) {
3722
+ const label = yearAgoLabel(point.period);
3723
+ const prior = label === void 0 ? void 0 : series.values.find((value) => value.period === label);
3724
+ if (!prior || !Number.isFinite(prior.value) || !Number.isFinite(point.value)) return cell(ABSENT);
3725
+ if (series.unit === "percent") {
3726
+ const diff = point.value - prior.value;
3727
+ return cell(`${signed(diff, 1)} pts`, direction(diff));
3728
+ }
3729
+ if (prior.value <= 0) return cell(ABSENT);
3730
+ const change = (point.value - prior.value) / prior.value * 100;
3731
+ return cell(signedPercent(change, 1), direction(change));
3732
+ }
3733
+ function formatKpiValue(value, series) {
3734
+ if (!Number.isFinite(value)) return ABSENT;
3735
+ const { unit, displayFormat } = series;
3736
+ if (unit === "percent") return percent(value, 1);
3737
+ if (unit === "USD") return displayFormat === "currency" ? money(value) : `$${humanize(value)}`;
3738
+ if (/^[A-Z]{3}$/.test(unit)) {
3739
+ return displayFormat === "currency" ? `${value.toFixed(2)} ${unit}` : `${humanize(value)} ${unit}`;
3740
+ }
3741
+ return unit ? `${humanize(value)} ${unit}` : humanize(value);
3742
+ }
3743
+ async function noCoverage(api, ticker) {
3744
+ await verifyTickerOnEmpty(api, ticker);
3745
+ throw new CliCommandError(
3746
+ `${ticker} has no curated KPI coverage yet.`,
3747
+ 'run "sentisense kpis --coverage" for the tickers that have it.',
3748
+ EXIT.NOT_FOUND
3749
+ );
3750
+ }
3751
+ async function orNoCoverage(api, ticker, request) {
3752
+ try {
3753
+ return await request;
3754
+ } catch (error) {
3755
+ if (error instanceof NotFoundError) return noCoverage(api, ticker);
3756
+ throw error;
3757
+ }
3758
+ }
3759
+ var kpisCommand = {
3760
+ name: "kpis",
3761
+ summary: "Company KPIs from earnings filings: segment revenue, deliveries, subscribers",
3762
+ usage: "sentisense kpis <ticker> [--series ID | --types] | sentisense kpis --coverage",
3763
+ examples: [
3764
+ "sentisense kpis TSLA",
3765
+ "sentisense kpis TSLA --series vehicle_deliveries",
3766
+ "sentisense kpis TSLA --types",
3767
+ "sentisense kpis --coverage --full",
3768
+ "sentisense kpis TSLA --json"
3769
+ ],
3770
+ notes: [
3771
+ "One row per series: its latest reported period and value, and the change from the same",
3772
+ "period a year earlier, computed only from that series' own values. A percent series",
3773
+ "changes in points. Discontinued series are hidden unless --full.",
3774
+ "--series ID prints that series' periods, newest first. The ids are in the first column.",
3775
+ "--types lists the series without their values, on any key and at no quota cost.",
3776
+ "--coverage lists every covered ticker and marks the sample companies, whose full KPI",
3777
+ "series a free key can read. Other companies return the series list only on a free key;",
3778
+ "PRO returns every series in full.",
3779
+ "A ticker without KPI coverage exits 4 and says so; an unknown symbol exits 4 as a typo.",
3780
+ EMPTY_VERIFY_NOTE,
3781
+ EMPTY_VERIFY_NOTE_2
3782
+ ],
3783
+ flags: {
3784
+ series: { type: "string", placeholder: "ID", describe: "Print one series' periods, newest first" },
3785
+ types: { type: "boolean", describe: "List the series without their values (free on any key)" },
3786
+ coverage: { type: "boolean", describe: "List every ticker with KPI coverage" }
3787
+ },
3788
+ async run({ args, client, full }) {
3789
+ if (args.flags.coverage === true) {
3790
+ rejectPositionals(args, "kpis --coverage");
3791
+ return coverageRun2(client(), full);
3792
+ }
3793
+ const ticker = oneTicker(args, "kpis");
3794
+ const series = typeof args.flags.series === "string" ? args.flags.series : void 0;
3795
+ if (series !== void 0 && args.flags.types === true) {
3796
+ throw new CliUsageError("--series and --types do not go together.", "pass one or the other.");
3797
+ }
3798
+ const api = client();
3799
+ if (args.flags.types === true) return typesRun(api, ticker);
3800
+ const envelope = await orNoCoverage(api, ticker, api.stocks.getKpis(ticker));
3801
+ return series === void 0 ? summaryRun(envelope, ticker, full) : seriesRun(envelope, ticker, series, full);
3802
+ }
3803
+ };
3804
+ function headBlock(ticker, data, right) {
3805
+ return {
3806
+ kind: "head",
3807
+ title: field("ticker", ticker),
3808
+ subtitle: data?.companyName ? field("company", data.companyName) : void 0,
3809
+ right: fields(...right)
3810
+ };
3811
+ }
3812
+ function lockedBlocks(envelope, ticker) {
3813
+ if (!envelope.isPreview) return [];
3814
+ return [
3815
+ {
3816
+ kind: "text",
3817
+ text: "Preview response: KPI values for this company are PRO. A free key gets the full series for the sample companies.",
3818
+ tone: "dim"
3819
+ },
3820
+ { kind: "text", text: `Run "sentisense kpis ${ticker} --types" for the series this company reports.`, tone: "dim" }
3821
+ ];
3822
+ }
3823
+ function summaryRun(envelope, ticker, full) {
3824
+ const data = envelope.data;
3825
+ const all = data?.kpis ?? [];
3826
+ const discontinued = all.filter((series) => series.discontinued === true);
3827
+ const shown = full ? all : all.filter((series) => series.discontinued !== true);
3828
+ const blocks = [
3829
+ headBlock(ticker, data, [
3830
+ // A preview's empty list is a gate, not a count, so it prints no "series: 0".
3831
+ envelope.isPreview && all.length === 0 ? void 0 : field("series", String(all.length)),
3832
+ data?.lastUpdated ? field("updated", data.lastUpdated.slice(0, 10)) : void 0
3833
+ ])
3834
+ ];
3835
+ if (shown.length > 0) {
3836
+ blocks.push({
3837
+ kind: "table",
3838
+ head: ["ID", "SERIES", "PERIOD", "VALUE", "YOY"],
3839
+ align: ["left", "left", "left", "right", "right"],
3840
+ rows: shown.map((series) => {
3841
+ const latest = newestFirst(series.values)[0];
3842
+ const name = `${series.name}${series.discontinued ? " (discontinued)" : ""}`;
3843
+ return [
3844
+ // Never truncated: the id is what --series takes, so it has to copy and paste whole.
3845
+ cell(series.id),
3846
+ cell(truncate(name, full ? 60 : 32), series.discontinued ? "dim" : void 0),
3847
+ cell(latest ? `${latest.period}${latest.isEstimate ? " (prelim)" : ""}` : ABSENT),
3848
+ cell(latest ? formatKpiValue(latest.value, series) : ABSENT),
3849
+ latest ? yearOverYear(series, latest) : cell(ABSENT)
3850
+ ];
3851
+ })
3852
+ });
3853
+ if (!full && discontinued.length > 0) {
3854
+ blocks.push({
3855
+ kind: "text",
3856
+ text: `${discontinued.length} discontinued series hidden. Add --full to show them.`,
3857
+ tone: "dim"
3858
+ });
3859
+ }
3860
+ } else if (!envelope.isPreview) {
3861
+ blocks.push({ kind: "text", text: "No KPI series reported for this company." });
3862
+ }
3863
+ blocks.push(...lockedBlocks(envelope, ticker));
3864
+ return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
3865
+ }
3866
+ function seriesRun(envelope, ticker, id, full) {
3867
+ const data = envelope.data;
3868
+ if (envelope.isPreview && (data?.kpis ?? []).length === 0) {
3869
+ const blocks2 = [headBlock(ticker, data, [field("series", id)]), ...lockedBlocks(envelope, ticker)];
3870
+ return { json: envelope, doc: doc(...blocks2, sampleNote(envelope, ticker)) };
3871
+ }
3872
+ const series = (data?.kpis ?? []).find((candidate) => candidate.id === id);
3873
+ if (!series) {
3874
+ throw new CliCommandError(
3875
+ `${ticker} has no KPI series "${id}".`,
3876
+ `run "sentisense kpis ${ticker} --types" for its series ids.`,
3877
+ EXIT.NOT_FOUND
3878
+ );
3879
+ }
3880
+ const values = newestFirst(series.values);
3881
+ const shown = full ? values : values.slice(0, DEFAULT_PERIODS);
3882
+ const blocks = [
3883
+ headBlock(ticker, data, [field("series", series.name), field("periods", String(values.length))])
3884
+ ];
3885
+ if (series.discontinued) {
3886
+ blocks.push({
3887
+ kind: "text",
3888
+ text: `Discontinued${series.discontinuedNote ? `: ${series.discontinuedNote}` : "."}`,
3889
+ tone: "dim"
3890
+ });
3891
+ }
3892
+ if (shown.length === 0) {
3893
+ blocks.push({ kind: "text", text: "No reported periods in this series." });
3894
+ } else {
3895
+ blocks.push({
3896
+ kind: "table",
3897
+ head: ["PERIOD", "DATE", "VALUE", "YOY", ""],
3898
+ align: ["left", "left", "right", "right", "left"],
3899
+ rows: shown.map((point) => [
3900
+ cell(point.period),
3901
+ cell(point.date),
3902
+ cell(formatKpiValue(point.value, series)),
3903
+ yearOverYear(series, point),
3904
+ cell(point.isEstimate ? "prelim" : "")
3905
+ ])
3906
+ });
3907
+ if (shown.length < values.length) {
3908
+ blocks.push({
3909
+ kind: "text",
3910
+ text: `Showing ${shown.length} of ${values.length} periods. Add --full for the rest.`,
3911
+ tone: "dim"
3912
+ });
3913
+ }
3914
+ }
3915
+ if (series.sourceRef) blocks.push({ kind: "text", text: `Source: ${series.sourceRef}`, tone: "dim" });
3916
+ return { json: envelope, doc: doc(...blocks, sampleNote(envelope, ticker)) };
3917
+ }
3918
+ async function typesRun(api, ticker) {
3919
+ const types = await orNoCoverage(api, ticker, api.stocks.getKpiTypes(ticker));
3920
+ const blocks = [{ kind: "head", title: field("ticker", ticker), right: [field("series", String(types.length))] }];
3921
+ if (types.length === 0) {
3922
+ blocks.push({ kind: "text", text: "No KPI series listed for this company." });
3923
+ } else {
3924
+ blocks.push({
3925
+ kind: "table",
3926
+ head: ["ID", "SERIES", "CATEGORY"],
3927
+ rows: types.map((entry) => [cell(entry.id), cell(entry.name), cell(entry.category)])
3928
+ });
3929
+ }
3930
+ return { json: types, doc: doc(...blocks) };
3931
+ }
3932
+ async function coverageRun2(api, full) {
3933
+ const response = await api.stocks.listKpiCoverage();
3934
+ const rows = response.tickers ?? [];
3935
+ const samples = rows.filter((row) => row.sampleCompany === true);
3936
+ const count = response.count ?? rows.length;
3937
+ const shown = full ? rows : samples.length > 0 ? samples : rows.slice(0, DEFAULT_COVERAGE_ROWS2);
3938
+ const blocks = [
3939
+ {
3940
+ kind: "head",
3941
+ title: field("kpi coverage", `${count} tickers`),
3942
+ right: fields(samples.length > 0 ? field("sample companies", String(samples.length)) : void 0)
3943
+ }
3944
+ ];
3945
+ if (shown.length === 0) {
3946
+ blocks.push({ kind: "text", text: "No tickers listed with KPI coverage." });
3947
+ } else {
3948
+ blocks.push({
3949
+ kind: "table",
3950
+ head: ["TICKER", "COMPANY", "SERIES", "UPDATED", "SAMPLE"],
3951
+ align: ["left", "left", "right", "left", "left"],
3952
+ rows: shown.map((row) => [
3953
+ cell(row.ticker),
3954
+ cell(truncate(row.companyName ?? "", full ? 48 : 32)),
3955
+ cell(String(row.kpiCount)),
3956
+ cell((row.lastUpdated ?? "").slice(0, 10)),
3957
+ cell(row.sampleCompany ? "sample" : "", row.sampleCompany ? "accent" : void 0)
3958
+ ])
3959
+ });
3960
+ }
3961
+ if (samples.length > 0) {
3962
+ blocks.push({
3963
+ kind: "text",
3964
+ text: `Full KPI data on ${samples.length} sample companies, free; a preview for every other company. PRO unlocks them all.`,
3965
+ tone: "dim"
3966
+ });
3967
+ }
3968
+ if (shown.length < rows.length) {
3969
+ blocks.push({
3970
+ kind: "text",
3971
+ 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.`,
3972
+ tone: "dim"
3973
+ });
3974
+ }
3975
+ return { json: response, doc: doc(...blocks) };
3976
+ }
3977
+
3709
3978
  // src/cli/commands/mood.ts
3710
3979
  function readMarket(payload) {
3711
3980
  if (!payload || typeof payload !== "object") return {};
@@ -4814,6 +5083,7 @@ var COMMANDS = [
4814
5083
  analystsCommand,
4815
5084
  analystCommand,
4816
5085
  earningsCommand,
5086
+ kpisCommand,
4817
5087
  insidersCommand,
4818
5088
  insightsCommand,
4819
5089
  congressCommand,
@@ -4840,6 +5110,7 @@ var EXAMPLE = {
4840
5110
  analysts: "sentisense analysts NVDA --coverage",
4841
5111
  analyst: "sentisense analyst dan-ives --calls",
4842
5112
  earnings: "sentisense earnings --week next",
5113
+ kpis: "sentisense kpis TSLA",
4843
5114
  insiders: "sentisense insiders NVDA",
4844
5115
  insights: "sentisense insights NVDA",
4845
5116
  congress: "sentisense congress NVDA",
package/dist/index.cjs CHANGED
@@ -1475,7 +1475,7 @@ var Trackers = class {
1475
1475
  };
1476
1476
 
1477
1477
  // src/version.ts
1478
- var VERSION = "0.72.1";
1478
+ var VERSION = "0.73.0";
1479
1479
 
1480
1480
  // src/client.ts
1481
1481
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";