sentisense 0.76.0 → 0.78.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/dist/cli.cjs CHANGED
@@ -3,22 +3,23 @@
3
3
 
4
4
  // src/errors.ts
5
5
  var SentiSenseError = class extends Error {
6
- constructor(message, status, code) {
6
+ constructor(message, status, code, body) {
7
7
  super(message);
8
8
  this.name = "SentiSenseError";
9
9
  this.status = status;
10
10
  this.code = code;
11
+ this.body = body;
11
12
  }
12
13
  };
13
14
  var AuthenticationError = class extends SentiSenseError {
14
- constructor(message, status, code) {
15
- super(message, status, code);
15
+ constructor(message, status, code, body) {
16
+ super(message, status, code, body);
16
17
  this.name = "AuthenticationError";
17
18
  }
18
19
  };
19
20
  var NotFoundError = class extends SentiSenseError {
20
- constructor(message, code) {
21
- super(message, 404, code);
21
+ constructor(message, code, body) {
22
+ super(message, 404, code, body);
22
23
  this.name = "NotFoundError";
23
24
  }
24
25
  };
@@ -30,22 +31,22 @@ var DeepHistoryUnavailableError = class extends SentiSenseError {
30
31
  }
31
32
  };
32
33
  var RateLimitError = class extends SentiSenseError {
33
- constructor(message, code, retryAfter) {
34
- super(message, 429, code);
34
+ constructor(message, code, retryAfter, body) {
35
+ super(message, 429, code, body);
35
36
  this.name = "RateLimitError";
36
37
  this.retryAfter = retryAfter;
37
38
  }
38
39
  };
39
40
  var TemporarilyUnavailableError = class extends SentiSenseError {
40
- constructor(message, retryAfter, code) {
41
- super(message, 503, code);
41
+ constructor(message, retryAfter, code, body) {
42
+ super(message, 503, code, body);
42
43
  this.name = "TemporarilyUnavailableError";
43
44
  this.retryAfter = retryAfter;
44
45
  }
45
46
  };
46
47
  var APIError = class extends SentiSenseError {
47
- constructor(message, status, code) {
48
- super(message, status, code);
48
+ constructor(message, status, code, body) {
49
+ super(message, status, code, body);
49
50
  this.name = "APIError";
50
51
  }
51
52
  };
@@ -388,8 +389,11 @@ var analystCommand = {
388
389
  "firstSeen and lastSeen bound the notes on record, not employment: the most recent firm",
389
390
  "is where they last published, not necessarily where they work today.",
390
391
  NOT_A_SCORECARD,
391
- "A slug that matches no analyst exits 4."
392
+ "A slug that matches no analyst exits 4.",
393
+ "--json prints the profile response. With --calls it is one object combining two responses,",
394
+ '"profile" and "calls", each the API response with its envelope.'
392
395
  ],
396
+ jsonShape: 'Print the profile response as JSON; with --calls, {"profile": ..., "calls": ...}',
393
397
  flags: {
394
398
  calls: { type: "boolean", describe: "Append their price target notes, newest first" },
395
399
  limit: { type: "number", placeholder: "N", describe: `Calls to request, 1 to 200 (default ${DEFAULT_CALLS})` }
@@ -575,13 +579,45 @@ async function verifyTickerOnEmpty(api, ticker) {
575
579
  function isEtfRedirect(error) {
576
580
  return error instanceof APIError && error.code === "ticker_is_etf";
577
581
  }
582
+ var ETF_QUOTE_PATH = /^\/api\/v1\/etfs\/([^/?#]+)\/quote$/i;
583
+ function etfQuoteSymbol(quote, ticker) {
584
+ if (!Array.isArray(quote.seeInstead)) return void 0;
585
+ const own = /* @__PURE__ */ new Set([ticker.toUpperCase()]);
586
+ if (typeof quote.ticker === "string") own.add(quote.ticker.toUpperCase());
587
+ for (const path of quote.seeInstead) {
588
+ if (typeof path !== "string") continue;
589
+ const match = ETF_QUOTE_PATH.exec(path);
590
+ if (!match) continue;
591
+ let symbol;
592
+ try {
593
+ symbol = decodeURIComponent(match[1]);
594
+ } catch {
595
+ continue;
596
+ }
597
+ if (own.has(symbol.toUpperCase())) return symbol;
598
+ }
599
+ return void 0;
600
+ }
578
601
  async function quoteAnyTicker(api, ticker) {
602
+ let quote;
579
603
  try {
580
- return { kind: "stock", quote: await api.stocks.getQuote(ticker) };
604
+ quote = await api.stocks.getQuote(ticker);
581
605
  } catch (error) {
582
606
  if (!isEtfRedirect(error)) throw error;
583
607
  return { kind: "etf", quote: await api.etfs.quote(ticker) };
584
608
  }
609
+ const fund = etfQuoteSymbol(quote, ticker);
610
+ if (fund === void 0) return { kind: "stock", quote };
611
+ try {
612
+ return { kind: "etf", quote: await api.etfs.quote(fund) };
613
+ } catch (error) {
614
+ const reason = error instanceof Error ? error.message : String(error);
615
+ return {
616
+ kind: "stock",
617
+ quote,
618
+ note: `${ticker}: the fund quote failed (${reason}), so AUM, expense ratio and NAV are missing`
619
+ };
620
+ }
585
621
  }
586
622
  var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
587
623
  var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
@@ -594,6 +630,19 @@ function actionTone(actionType) {
594
630
  if (actionType === "DOWNGRADE") return "down";
595
631
  return void 0;
596
632
  }
633
+ function isTarget(value) {
634
+ return typeof value === "number" && Number.isFinite(value);
635
+ }
636
+ function targetText(value) {
637
+ return Number.isInteger(value) ? `$${value}` : money(value);
638
+ }
639
+ function targetMove(action) {
640
+ const target = action.priceTarget;
641
+ if (!isTarget(target)) return cell("");
642
+ const prior = action.priorPriceTarget;
643
+ if (!isTarget(prior)) return cell(targetText(target));
644
+ return cell(`${targetText(prior)} to ${targetText(target)}`, direction(target - prior));
645
+ }
597
646
  function primaryAnalyst(row) {
598
647
  const named = row.latestNote?.analyst ?? null;
599
648
  const match = (named ? row.analysts.find(
@@ -624,9 +673,16 @@ var analystsCommand = {
624
673
  'on a row is what "sentisense analyst <slug>" takes.',
625
674
  "A firm can cover a ticker on a rating action alone, so a blank target is a real reading",
626
675
  "rather than missing data, and a blank analyst means the note named nobody.",
676
+ "TARGET on a rating change is the price target the firm stated with it, shown as",
677
+ '"$400 to $200" when it moved from a prior target. It is blank when the firm stated',
678
+ "none, and blank on a free key outside the sample companies.",
627
679
  "--limit trims the rows printed under --coverage; the API returns the whole book either",
628
- "way, and --full prints all of it."
680
+ "way, and --full prints all of it.",
681
+ '--json prints one object combining two responses: "consensus" and "actions", each the API',
682
+ 'response with its envelope ("actions" is null if that call failed). With --coverage it is',
683
+ "the coverage response alone."
629
684
  ],
685
+ jsonShape: 'Print {"consensus": ..., "actions": ...} as JSON; with --coverage, the coverage response',
630
686
  flags: {
631
687
  coverage: { type: "boolean", describe: "Show who covers the ticker, one row per firm" },
632
688
  days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" },
@@ -690,13 +746,14 @@ var analystsCommand = {
690
746
  blocks.push({ kind: "blank" });
691
747
  blocks.push({
692
748
  kind: "table",
693
- head: ["DATE", "FIRM", "ACTION", "FROM", "TO"],
749
+ head: ["DATE", "FIRM", "ACTION", "FROM", "TO", "TARGET"],
694
750
  rows: shown.map((action) => [
695
751
  cell(action.actionDate),
696
752
  cell(action.firm),
697
753
  cell(action.actionType, actionTone(action.actionType)),
698
754
  cell(action.fromGrade ?? ""),
699
- cell(action.toGrade ?? "")
755
+ cell(action.toGrade ?? ""),
756
+ targetMove(action)
700
757
  ])
701
758
  });
702
759
  if (!full && rows.length > shown.length) {
@@ -1432,7 +1489,7 @@ var flowsCommand = {
1432
1489
  };
1433
1490
 
1434
1491
  // src/version.ts
1435
- var VERSION = "0.76.0";
1492
+ var VERSION = "0.78.0";
1436
1493
 
1437
1494
  // src/resources/analyst.ts
1438
1495
  var Analyst = class {
@@ -1483,6 +1540,10 @@ var Analyst = class {
1483
1540
  /**
1484
1541
  * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
1485
1542
  * Free users receive the 3 most recent.
1543
+ *
1544
+ * Each row carries `priceTarget`, the target the firm stated with the action, and
1545
+ * `priorPriceTarget`, the target it moved from (PRO; `null` on free preview rows,
1546
+ * `null` when the firm stated none or kept its target unchanged).
1486
1547
  */
1487
1548
  async actions(ticker, options) {
1488
1549
  return this.client.get(
@@ -1502,6 +1563,10 @@ var Analyst = class {
1502
1563
  /**
1503
1564
  * Get market-wide recent analyst actions across all covered tickers, newest first.
1504
1565
  * Free users receive the 5 most recent.
1566
+ *
1567
+ * Rows carry the same `priceTarget` and `priorPriceTarget` as {@link actions} (PRO;
1568
+ * `null` on free preview rows). This feed does not check for stock splits, so for a
1569
+ * stock that split inside the window, read its targets from {@link actions}.
1505
1570
  */
1506
1571
  async marketActivity(options) {
1507
1572
  return this.client.get("/api/v1/analyst/activity", options);
@@ -1813,13 +1878,18 @@ var EntityMetrics = class {
1813
1878
  *
1814
1879
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug.
1815
1880
  * @param metricType The metric to break down (e.g. "mentions" or "sentiment").
1816
- * @param options Optional dimension parameter.
1881
+ * @param options Optional dimension, and an optional window as `startTime` / `endTime` in
1882
+ * epoch milliseconds. Without a window the API uses the last 7 days.
1817
1883
  */
1818
1884
  async getDistribution(symbol, metricType, options = {}) {
1819
- const { dimension = "source" } = options;
1885
+ const { dimension = "source", startTime, endTime } = options;
1820
1886
  return this.client.get(
1821
1887
  `/api/v2/metrics/entity/${encodeURIComponent(symbol)}/distribution/${encodeURIComponent(metricType)}`,
1822
- { dimension }
1888
+ {
1889
+ dimension,
1890
+ ...startTime !== void 0 && { startTime },
1891
+ ...endTime !== void 0 && { endTime }
1892
+ }
1823
1893
  );
1824
1894
  }
1825
1895
  };
@@ -2501,6 +2571,9 @@ var Stocks = class {
2501
2571
  * Get aggregate quote snapshot: live price, today OHLC, 52-week range,
2502
2572
  * market cap, P/E, EPS TTM, and dividend yield in a single call.
2503
2573
  * All fields except `ticker` may be null when upstream data is unavailable.
2574
+ *
2575
+ * A fund ticker gets a normal quote without AUM or NAV, plus `seeInstead` pointing at the
2576
+ * fund quote when that covers it: call `etfs.quote()` for those fields.
2504
2577
  */
2505
2578
  async getQuote(ticker) {
2506
2579
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/quote`);
@@ -2629,6 +2702,18 @@ var Stocks = class {
2629
2702
  async getFundamentals(ticker, options) {
2630
2703
  return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
2631
2704
  }
2705
+ /**
2706
+ * Get up to 40 quarters or 20 years of full financial statements, newest first: the same
2707
+ * period object as `getFundamentals()`, with the trailing-twelve-month, price-ratio and market
2708
+ * fields null on every row. A ticker with no statements resolves with an empty `periods` and a
2709
+ * `reason` rather than throwing.
2710
+ *
2711
+ * Periods served from an SEC-backed record carry the optional provenance fields `source`,
2712
+ * `sourceRef`, `secFiled` and `lineSources`; see {@link Fundamentals}.
2713
+ */
2714
+ async getFundamentalsHistory(ticker, options) {
2715
+ return this.client.get("/api/v1/stocks/fundamentals/history", { ticker, ...options });
2716
+ }
2632
2717
  /** Get available fiscal periods. The periods are in `periods`. */
2633
2718
  async getFundamentalsPeriods(ticker) {
2634
2719
  return this.client.get("/api/v1/stocks/fundamentals/periods", { ticker });
@@ -2942,6 +3027,14 @@ function clampRetryAfter(raw, maxWaitS) {
2942
3027
  function retryAfterSeconds(raw, defaultS, maxWaitS) {
2943
3028
  return clampRetryAfter(raw, maxWaitS) ?? defaultS;
2944
3029
  }
3030
+ async function readErrorBody(response) {
3031
+ try {
3032
+ const parsed = await response.json();
3033
+ return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
3034
+ } catch {
3035
+ return void 0;
3036
+ }
3037
+ }
2945
3038
  function sleep(ms) {
2946
3039
  return new Promise((resolve) => setTimeout(resolve, ms));
2947
3040
  }
@@ -3043,13 +3136,12 @@ var SentiSense = class {
3043
3136
  Number.POSITIVE_INFINITY
3044
3137
  );
3045
3138
  if (requestedS > MAX_RATE_LIMIT_WAIT_S) {
3046
- try {
3047
- await response.body?.cancel();
3048
- } catch {
3049
- }
3139
+ const body = await readErrorBody(response);
3050
3140
  throw new TemporarilyUnavailableError(
3051
3141
  `Server asked for a ${Math.round(requestedS)}s wait, longer than this client's ${MAX_RATE_LIMIT_WAIT_S}s budget`,
3052
- requestedS
3142
+ requestedS,
3143
+ void 0,
3144
+ body
3053
3145
  );
3054
3146
  }
3055
3147
  delayMs = requestedS * 1e3;
@@ -3130,32 +3222,29 @@ var SentiSense = class {
3130
3222
  return url.toString();
3131
3223
  }
3132
3224
  async handleErrorResponse(response) {
3133
- let body = {};
3134
- try {
3135
- body = await response.json();
3136
- } catch {
3137
- }
3138
- const message = body.message ?? response.statusText ?? "API request failed";
3139
- const code = body.error;
3225
+ const body = await readErrorBody(response);
3226
+ const message = body?.message ?? response.statusText ?? "API request failed";
3227
+ const code = body?.error;
3140
3228
  switch (response.status) {
3141
3229
  case 401:
3142
3230
  case 403:
3143
3231
  throw new AuthenticationError(
3144
3232
  this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
3145
3233
  response.status,
3146
- code
3234
+ code,
3235
+ body
3147
3236
  );
3148
3237
  case 404:
3149
- throw new NotFoundError(message, code);
3238
+ throw new NotFoundError(message, code, body);
3150
3239
  case 429: {
3151
3240
  const retryAfter = clampRetryAfter(
3152
3241
  response.headers.get("Retry-After"),
3153
3242
  MAX_RATE_LIMIT_WAIT_S
3154
3243
  );
3155
- throw new RateLimitError(message, code, retryAfter);
3244
+ throw new RateLimitError(message, code, retryAfter, body);
3156
3245
  }
3157
3246
  default:
3158
- throw new APIError(message, response.status, code);
3247
+ throw new APIError(message, response.status, code, body);
3159
3248
  }
3160
3249
  }
3161
3250
  };
@@ -4652,8 +4741,12 @@ var quoteCommand = {
4652
4741
  "for the terminal layout: piped and --json output carry the quote alone.",
4653
4742
  "JSON is the exact quote response for one ticker, and an object keyed by ticker for more.",
4654
4743
  "An ETF symbol answers with the ETF quote: AUM, expense ratio and NAV in place of market",
4655
- "cap, P/E and EPS. That costs one extra request per ETF symbol."
4744
+ "cap, P/E and EPS. That costs one extra request per ETF symbol.",
4745
+ "With several tickers, one that fails does not lose the rest: the others print, each failed",
4746
+ "symbol is named on stderr, and the exit code is that failure's (4 for an unknown symbol).",
4747
+ "Under --json a failed symbol is left out of the object rather than given a null."
4656
4748
  ],
4749
+ jsonShape: "Print the quote response as JSON; for several tickers, an object keyed by ticker",
4657
4750
  flags: {},
4658
4751
  async run({ args, client, full, mode }) {
4659
4752
  const tickers = args.positionals.map((t) => t.toUpperCase());
@@ -4662,7 +4755,7 @@ var quoteCommand = {
4662
4755
  }
4663
4756
  const api = client();
4664
4757
  const wantName = mode === "pretty";
4665
- const rows = await Promise.all(
4758
+ const settled = await Promise.allSettled(
4666
4759
  tickers.map(async (ticker) => {
4667
4760
  const [answer, profile] = await Promise.all([
4668
4761
  quoteAnyTicker(api, ticker),
@@ -4672,14 +4765,37 @@ var quoteCommand = {
4672
4765
  return { ...answer, ticker, profile };
4673
4766
  })
4674
4767
  );
4675
- if (rows.length === 1) {
4676
- return { json: rows[0].quote, doc: doc(...single(rows[0], full)) };
4768
+ const rows = [];
4769
+ const failed = [];
4770
+ settled.forEach((outcome, index) => {
4771
+ if (outcome.status === "fulfilled") rows.push(outcome.value);
4772
+ else failed.push({ ticker: tickers[index], error: outcome.reason });
4773
+ });
4774
+ if (rows.length === 0) throw failed[0].error;
4775
+ const notes = rows.flatMap((row) => row.note ? [row.note] : []);
4776
+ if (tickers.length === 1) {
4777
+ return { json: rows[0].quote, doc: doc(...single(rows[0], full)), notes };
4677
4778
  }
4678
4779
  const json = {};
4679
4780
  for (const row of rows) json[row.ticker] = row.quote;
4680
- return { json, doc: doc(table(rows, full)) };
4781
+ const result = { json, doc: doc(table(rows, full)), notes };
4782
+ if (failed.length > 0) Object.assign(result, partialFailure(failed, args.flags.debug === true));
4783
+ return result;
4681
4784
  }
4682
4785
  };
4786
+ function partialFailure(failed, debug) {
4787
+ const errors = [];
4788
+ const advice = /* @__PURE__ */ new Set();
4789
+ let exitCode;
4790
+ for (const { ticker, error } of failed) {
4791
+ const report = describeError(error, debug, "quote");
4792
+ if (exitCode === void 0) exitCode = report.exitCode;
4793
+ const [first, ...rest] = report.lines;
4794
+ errors.push(first.replace(/^error: /, `error: ${ticker}: `));
4795
+ for (const line of rest) advice.add(line);
4796
+ }
4797
+ return { errors: [...errors, ...advice], exitCode };
4798
+ }
4683
4799
 
4684
4800
  // src/cli/commands/screen.ts
4685
4801
  var OPS = ["GTE", "LTE", "GT", "LT", "EQ", "NEQ", "IN", "NOT_IN"];
@@ -5045,8 +5161,12 @@ var sentimentCommand = {
5045
5161
  "polarity: it is unbounded, and the bands sit at 5, 13, and 23 either side of zero.",
5046
5162
  "Tone per source is the separate polarity reading, always between -1 and 1, and it is",
5047
5163
  "reported per source rather than blended into one number.",
5048
- "--days sets the Score history window used for the sparkline. Default is 30."
5164
+ "--days sets the Score history window used for the sparkline. Default is 30.",
5165
+ '--json prints one object combining two responses: "sentiment" is the sentiment response,',
5166
+ 'envelope included, and "series" the Score history points (null if that call failed). So',
5167
+ "the Score is at .sentiment.data.sentisenseScore, not .data.sentisenseScore."
5049
5168
  ],
5169
+ jsonShape: 'Print {"sentiment": <sentiment response>, "series": <Score history>} as JSON',
5050
5170
  flags: {
5051
5171
  days: { type: "number", placeholder: "N", describe: `Days of Score history (default ${DEFAULT_DAYS})` }
5052
5172
  },
@@ -5221,12 +5341,12 @@ var EXAMPLE = {
5221
5341
  function pad(text, width) {
5222
5342
  return text.length >= width ? text : text + " ".repeat(width - text.length);
5223
5343
  }
5224
- function flagLines(specs) {
5344
+ function flagLines(specs, overrides = {}) {
5225
5345
  const entries = Object.entries(specs);
5226
5346
  if (entries.length === 0) return [];
5227
5347
  const rendered = entries.map(([name, spec]) => ({
5228
5348
  left: spec.type === "boolean" ? `--${name}` : `--${name} <${spec.placeholder ?? "value"}>`,
5229
- describe: spec.describe
5349
+ describe: overrides[name] ?? spec.describe
5230
5350
  }));
5231
5351
  const width = Math.max(...rendered.map((entry) => entry.left.length));
5232
5352
  return rendered.map((entry) => ` ${pad(entry.left, width)} ${entry.describe}`);
@@ -5246,7 +5366,8 @@ function mainHelp() {
5246
5366
  ),
5247
5367
  "",
5248
5368
  "Output:",
5249
- " Pretty in a terminal, plain text when piped, exact API JSON with --json.",
5369
+ " Pretty in a terminal, plain text when piped, the API's JSON with --json. Where a command",
5370
+ " combines two responses into one object, its help names the keys.",
5250
5371
  " --full widens a command, --plain and --no-color force text, --debug shows stack traces.",
5251
5372
  "",
5252
5373
  "Setup:",
@@ -5279,7 +5400,11 @@ function commandHelp(command) {
5279
5400
  }
5280
5401
  const own = flagLines(command.flags);
5281
5402
  if (own.length > 0) lines.push("", "Flags:", ...own);
5282
- lines.push("", "Common flags:", ...flagLines(GLOBAL_FLAGS));
5403
+ lines.push(
5404
+ "",
5405
+ "Common flags:",
5406
+ ...flagLines(GLOBAL_FLAGS, command.jsonShape ? { json: command.jsonShape } : {})
5407
+ );
5283
5408
  lines.push("", "Examples:", ...command.examples.map((example) => ` ${example}`));
5284
5409
  lines.push(
5285
5410
  "",
@@ -5528,6 +5653,8 @@ async function runCli(argv, io) {
5528
5653
  } else {
5529
5654
  io.stdout(renderPlain(result.doc));
5530
5655
  }
5656
+ for (const line of result.errors ?? []) io.stderr(`${line}
5657
+ `);
5531
5658
  return result.exitCode ?? EXIT.OK;
5532
5659
  } catch (error) {
5533
5660
  const debug = argv.includes("--debug");
package/dist/index.cjs CHANGED
@@ -35,22 +35,23 @@ module.exports = __toCommonJS(index_exports);
35
35
 
36
36
  // src/errors.ts
37
37
  var SentiSenseError = class extends Error {
38
- constructor(message, status, code) {
38
+ constructor(message, status, code, body) {
39
39
  super(message);
40
40
  this.name = "SentiSenseError";
41
41
  this.status = status;
42
42
  this.code = code;
43
+ this.body = body;
43
44
  }
44
45
  };
45
46
  var AuthenticationError = class extends SentiSenseError {
46
- constructor(message, status, code) {
47
- super(message, status, code);
47
+ constructor(message, status, code, body) {
48
+ super(message, status, code, body);
48
49
  this.name = "AuthenticationError";
49
50
  }
50
51
  };
51
52
  var NotFoundError = class extends SentiSenseError {
52
- constructor(message, code) {
53
- super(message, 404, code);
53
+ constructor(message, code, body) {
54
+ super(message, 404, code, body);
54
55
  this.name = "NotFoundError";
55
56
  }
56
57
  };
@@ -62,22 +63,22 @@ var DeepHistoryUnavailableError = class extends SentiSenseError {
62
63
  }
63
64
  };
64
65
  var RateLimitError = class extends SentiSenseError {
65
- constructor(message, code, retryAfter) {
66
- super(message, 429, code);
66
+ constructor(message, code, retryAfter, body) {
67
+ super(message, 429, code, body);
67
68
  this.name = "RateLimitError";
68
69
  this.retryAfter = retryAfter;
69
70
  }
70
71
  };
71
72
  var TemporarilyUnavailableError = class extends SentiSenseError {
72
- constructor(message, retryAfter, code) {
73
- super(message, 503, code);
73
+ constructor(message, retryAfter, code, body) {
74
+ super(message, 503, code, body);
74
75
  this.name = "TemporarilyUnavailableError";
75
76
  this.retryAfter = retryAfter;
76
77
  }
77
78
  };
78
79
  var APIError = class extends SentiSenseError {
79
- constructor(message, status, code) {
80
- super(message, status, code);
80
+ constructor(message, status, code, body) {
81
+ super(message, status, code, body);
81
82
  this.name = "APIError";
82
83
  }
83
84
  };
@@ -131,6 +132,10 @@ var Analyst = class {
131
132
  /**
132
133
  * Get recent analyst upgrade/downgrade actions for a ticker, newest first.
133
134
  * Free users receive the 3 most recent.
135
+ *
136
+ * Each row carries `priceTarget`, the target the firm stated with the action, and
137
+ * `priorPriceTarget`, the target it moved from (PRO; `null` on free preview rows,
138
+ * `null` when the firm stated none or kept its target unchanged).
134
139
  */
135
140
  async actions(ticker, options) {
136
141
  return this.client.get(
@@ -150,6 +155,10 @@ var Analyst = class {
150
155
  /**
151
156
  * Get market-wide recent analyst actions across all covered tickers, newest first.
152
157
  * Free users receive the 5 most recent.
158
+ *
159
+ * Rows carry the same `priceTarget` and `priorPriceTarget` as {@link actions} (PRO;
160
+ * `null` on free preview rows). This feed does not check for stock splits, so for a
161
+ * stock that split inside the window, read its targets from {@link actions}.
153
162
  */
154
163
  async marketActivity(options) {
155
164
  return this.client.get("/api/v1/analyst/activity", options);
@@ -461,13 +470,18 @@ var EntityMetrics = class {
461
470
  *
462
471
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug.
463
472
  * @param metricType The metric to break down (e.g. "mentions" or "sentiment").
464
- * @param options Optional dimension parameter.
473
+ * @param options Optional dimension, and an optional window as `startTime` / `endTime` in
474
+ * epoch milliseconds. Without a window the API uses the last 7 days.
465
475
  */
466
476
  async getDistribution(symbol, metricType, options = {}) {
467
- const { dimension = "source" } = options;
477
+ const { dimension = "source", startTime, endTime } = options;
468
478
  return this.client.get(
469
479
  `/api/v2/metrics/entity/${encodeURIComponent(symbol)}/distribution/${encodeURIComponent(metricType)}`,
470
- { dimension }
480
+ {
481
+ dimension,
482
+ ...startTime !== void 0 && { startTime },
483
+ ...endTime !== void 0 && { endTime }
484
+ }
471
485
  );
472
486
  }
473
487
  };
@@ -1149,6 +1163,9 @@ var Stocks = class {
1149
1163
  * Get aggregate quote snapshot: live price, today OHLC, 52-week range,
1150
1164
  * market cap, P/E, EPS TTM, and dividend yield in a single call.
1151
1165
  * All fields except `ticker` may be null when upstream data is unavailable.
1166
+ *
1167
+ * A fund ticker gets a normal quote without AUM or NAV, plus `seeInstead` pointing at the
1168
+ * fund quote when that covers it: call `etfs.quote()` for those fields.
1152
1169
  */
1153
1170
  async getQuote(ticker) {
1154
1171
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/quote`);
@@ -1277,6 +1294,18 @@ var Stocks = class {
1277
1294
  async getFundamentals(ticker, options) {
1278
1295
  return this.client.get("/api/v1/stocks/fundamentals", { ticker, ...options });
1279
1296
  }
1297
+ /**
1298
+ * Get up to 40 quarters or 20 years of full financial statements, newest first: the same
1299
+ * period object as `getFundamentals()`, with the trailing-twelve-month, price-ratio and market
1300
+ * fields null on every row. A ticker with no statements resolves with an empty `periods` and a
1301
+ * `reason` rather than throwing.
1302
+ *
1303
+ * Periods served from an SEC-backed record carry the optional provenance fields `source`,
1304
+ * `sourceRef`, `secFiled` and `lineSources`; see {@link Fundamentals}.
1305
+ */
1306
+ async getFundamentalsHistory(ticker, options) {
1307
+ return this.client.get("/api/v1/stocks/fundamentals/history", { ticker, ...options });
1308
+ }
1280
1309
  /** Get available fiscal periods. The periods are in `periods`. */
1281
1310
  async getFundamentalsPeriods(ticker) {
1282
1311
  return this.client.get("/api/v1/stocks/fundamentals/periods", { ticker });
@@ -1563,7 +1592,7 @@ function serializeTrackerParams(params) {
1563
1592
  }
1564
1593
 
1565
1594
  // src/version.ts
1566
- var VERSION = "0.76.0";
1595
+ var VERSION = "0.78.0";
1567
1596
 
1568
1597
  // src/client.ts
1569
1598
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1593,6 +1622,14 @@ function clampRetryAfter(raw, maxWaitS) {
1593
1622
  function retryAfterSeconds(raw, defaultS, maxWaitS) {
1594
1623
  return clampRetryAfter(raw, maxWaitS) ?? defaultS;
1595
1624
  }
1625
+ async function readErrorBody(response) {
1626
+ try {
1627
+ const parsed = await response.json();
1628
+ return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : void 0;
1629
+ } catch {
1630
+ return void 0;
1631
+ }
1632
+ }
1596
1633
  function sleep(ms) {
1597
1634
  return new Promise((resolve) => setTimeout(resolve, ms));
1598
1635
  }
@@ -1694,13 +1731,12 @@ var SentiSense = class {
1694
1731
  Number.POSITIVE_INFINITY
1695
1732
  );
1696
1733
  if (requestedS > MAX_RATE_LIMIT_WAIT_S) {
1697
- try {
1698
- await response.body?.cancel();
1699
- } catch {
1700
- }
1734
+ const body = await readErrorBody(response);
1701
1735
  throw new TemporarilyUnavailableError(
1702
1736
  `Server asked for a ${Math.round(requestedS)}s wait, longer than this client's ${MAX_RATE_LIMIT_WAIT_S}s budget`,
1703
- requestedS
1737
+ requestedS,
1738
+ void 0,
1739
+ body
1704
1740
  );
1705
1741
  }
1706
1742
  delayMs = requestedS * 1e3;
@@ -1781,32 +1817,29 @@ var SentiSense = class {
1781
1817
  return url.toString();
1782
1818
  }
1783
1819
  async handleErrorResponse(response) {
1784
- let body = {};
1785
- try {
1786
- body = await response.json();
1787
- } catch {
1788
- }
1789
- const message = body.message ?? response.statusText ?? "API request failed";
1790
- const code = body.error;
1820
+ const body = await readErrorBody(response);
1821
+ const message = body?.message ?? response.statusText ?? "API request failed";
1822
+ const code = body?.error;
1791
1823
  switch (response.status) {
1792
1824
  case 401:
1793
1825
  case 403:
1794
1826
  throw new AuthenticationError(
1795
1827
  this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
1796
1828
  response.status,
1797
- code
1829
+ code,
1830
+ body
1798
1831
  );
1799
1832
  case 404:
1800
- throw new NotFoundError(message, code);
1833
+ throw new NotFoundError(message, code, body);
1801
1834
  case 429: {
1802
1835
  const retryAfter = clampRetryAfter(
1803
1836
  response.headers.get("Retry-After"),
1804
1837
  MAX_RATE_LIMIT_WAIT_S
1805
1838
  );
1806
- throw new RateLimitError(message, code, retryAfter);
1839
+ throw new RateLimitError(message, code, retryAfter, body);
1807
1840
  }
1808
1841
  default:
1809
- throw new APIError(message, response.status, code);
1842
+ throw new APIError(message, response.status, code, body);
1810
1843
  }
1811
1844
  }
1812
1845
  };