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/README.md +231 -594
- package/dist/cli.cjs +173 -46
- package/dist/index.cjs +64 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +247 -10
- package/dist/index.d.ts +247 -10
- package/dist/index.mjs +64 -31
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
{
|
|
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
|
-
|
|
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
|
-
|
|
3134
|
-
|
|
3135
|
-
|
|
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
|
|
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
|
-
|
|
4676
|
-
|
|
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
|
-
|
|
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,
|
|
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(
|
|
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
|
|
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
|
-
{
|
|
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.
|
|
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
|
-
|
|
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
|
-
|
|
1785
|
-
|
|
1786
|
-
|
|
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
|
};
|