sentisense 0.67.0 → 0.69.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 +20 -4
- package/dist/cli.cjs +53 -4
- package/dist/index.cjs +51 -3
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +164 -4
- package/dist/index.d.ts +164 -4
- package/dist/index.mjs +51 -3
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -34,7 +34,7 @@ npm install sentisense
|
|
|
34
34
|
```typescript
|
|
35
35
|
import SentiSense from "sentisense";
|
|
36
36
|
|
|
37
|
-
const client = new SentiSense({ apiKey
|
|
37
|
+
const client = new SentiSense(); // reads SENTISENSE_API_KEY, or pass { apiKey }
|
|
38
38
|
|
|
39
39
|
const price = await client.stocks.getPrice("AAPL");
|
|
40
40
|
console.log(price.currentPrice);
|
|
@@ -166,7 +166,7 @@ const client = new SentiSense({
|
|
|
166
166
|
|
|
167
167
|
| Option | Default | What it does |
|
|
168
168
|
|--------|---------|--------------|
|
|
169
|
-
| `apiKey` |
|
|
169
|
+
| `apiKey` | `SENTISENSE_API_KEY` env var | Sent as `X-SentiSense-API-Key`. Required by every endpoint. An explicit value wins over the environment. |
|
|
170
170
|
| `baseUrl` | `https://app.sentisense.ai` | Override for a non-production host. |
|
|
171
171
|
| `timeout` | `30000` | Per-request timeout in milliseconds. |
|
|
172
172
|
| `maxRetries` | `3` | Retries the per-minute 429 and 5xx, honouring `Retry-After`. The monthly-allowance 429 is never retried. Set `0` to fail fast. |
|
|
@@ -192,7 +192,7 @@ Affected: every method whose declared return type is `PreviewResponse<T>`. A tes
|
|
|
192
192
|
| `etfs` | `analystAggregate` `insiderAggregate` `sentimentAggregate` |
|
|
193
193
|
| `insider` | `getActivity` `getTrades` `getClusterBuys` |
|
|
194
194
|
| `insights` | `stock` `stockRange` `market` `latest` `user` |
|
|
195
|
-
| `institutional` | `getFlows` `getHolders` `getActivists` |
|
|
195
|
+
| `institutional` | `getFlows` `getHolders` `getHoldersHistory` `getActivists` |
|
|
196
196
|
| `options` | `getOverview` |
|
|
197
197
|
| `politicians` | `getActivity` `getFilings` `getMembers` `getMember` |
|
|
198
198
|
| `stocks` | `getSentiment` `getKpis` `getOptionsSummary` `getOptionsHistory` `getOptionsIntradayHistory` |
|
|
@@ -305,6 +305,7 @@ client.institutional.getQuarters()
|
|
|
305
305
|
client.institutional.getFlows("2025-02-14", { limit: 20 })
|
|
306
306
|
client.institutional.getHolders("AAPL", "2025-02-14")
|
|
307
307
|
client.institutional.getHolders("AAPL") // no date: the ticker's latest settled quarter
|
|
308
|
+
client.institutional.getHoldersHistory("AAPL", { quarters: 8 })
|
|
308
309
|
client.institutional.getActivists("2025-02-14")
|
|
309
310
|
```
|
|
310
311
|
|
|
@@ -321,6 +322,19 @@ if (latest) {
|
|
|
321
322
|
|
|
322
323
|
The holders payload also says how its quarter was chosen (`selection`), reports a newer still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known institutions matched against the full roster (`notableHolders`), and summarizes the quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each holder row carries its own `comparisonStatus`; only `AVAILABLE` on that row supports its change figures.
|
|
323
324
|
|
|
325
|
+
**Ownership history.** `getHoldersHistory()` returns one row per quarter for a stock, newest
|
|
326
|
+
first, covering the 12 newest quarters by default (`quarters` up to 20). Free keys see the
|
|
327
|
+
newest four. The newest row can still be filing (`status: "filing"`), in which case it covers
|
|
328
|
+
only the institutions that have filed so far. `sharesOutstanding`, `institutionalOwnershipPct`,
|
|
329
|
+
`avgClosePrice` and `dollarFlowUsd` are absent when they cannot be computed, never zero:
|
|
330
|
+
|
|
331
|
+
```typescript
|
|
332
|
+
const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
|
|
333
|
+
for (const q of data.quarters) {
|
|
334
|
+
console.log(q.label, q.status, q.holderCount, q.institutionalOwnershipPct, q.netSharesChange);
|
|
335
|
+
}
|
|
336
|
+
```
|
|
337
|
+
|
|
324
338
|
`positionsHeld` on an institution detail counts the full portfolio's held positions:
|
|
325
339
|
`max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
|
|
326
340
|
`getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
|
|
@@ -414,7 +428,7 @@ client.analyst.consensus("AAPL") // Price target cone + c
|
|
|
414
428
|
client.analyst.consensusHistory("AAPL", { limit: 90 }) // Daily history. Free: last 30 days; distribution fields null.
|
|
415
429
|
client.analyst.calledIt("AAPL", { limit: 10 }) // Recorded calls for 20% moves over five sessions. Free: newest move, up to 5 calls, move counts intact.
|
|
416
430
|
client.analyst.actions("AAPL", { lookbackDays: 30 }) // Upgrade/downgrade feed. Free: 3 most recent.
|
|
417
|
-
client.analyst.estimates("AAPL") // Forward EPS + surprises. Free: 1 quarter.
|
|
431
|
+
client.analyst.estimates("AAPL") // Forward EPS + surprises. Free: 1 quarter. data.ticker: the listing per-share figures are for (BRK-A answers BRK.B).
|
|
418
432
|
client.analyst.marketActivity({ lookbackDays: 7 }) // Market-wide analyst actions (PRO).
|
|
419
433
|
```
|
|
420
434
|
|
|
@@ -496,6 +510,8 @@ The forward-looking half of the family is `client.calendar.getEarnings()`, which
|
|
|
496
510
|
|
|
497
511
|
`earnings.getSummaries` exposes optional `totalCount` on the envelope on both PRO and FREE. It counts indexed quarters; returned rows can be fewer because of `limit` or an unavailable body. Older responses without the count still read as `undefined`.
|
|
498
512
|
|
|
513
|
+
The envelope `ticker` names the listing the quarters' per-share figures are quoted for: `BRK-A` answers `BRK.B` and `GOOG` answers `GOOGL`. It reads `undefined` on older responses.
|
|
514
|
+
|
|
499
515
|
### Company KPIs (PRO)
|
|
500
516
|
|
|
501
517
|
```typescript
|
package/dist/cli.cjs
CHANGED
|
@@ -1409,7 +1409,7 @@ var flowsCommand = {
|
|
|
1409
1409
|
};
|
|
1410
1410
|
|
|
1411
1411
|
// src/version.ts
|
|
1412
|
-
var VERSION = "0.
|
|
1412
|
+
var VERSION = "0.69.0";
|
|
1413
1413
|
|
|
1414
1414
|
// src/resources/analyst.ts
|
|
1415
1415
|
var Analyst = class {
|
|
@@ -1680,6 +1680,9 @@ var Earnings = class {
|
|
|
1680
1680
|
* assuming a fixed lag. A ticker with no stored quarter answers with an empty
|
|
1681
1681
|
* `data` array, not a 404.
|
|
1682
1682
|
*
|
|
1683
|
+
* The envelope `ticker` names the listing the per-share figures are quoted
|
|
1684
|
+
* for: `"BRK.B"` for `BRK-A`, `"GOOGL"` for `GOOG`.
|
|
1685
|
+
*
|
|
1683
1686
|
* Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
|
|
1684
1687
|
*/
|
|
1685
1688
|
async getSummaries(ticker, options) {
|
|
@@ -2132,6 +2135,34 @@ var Institutional = class {
|
|
|
2132
2135
|
{ reportDate, ...options }
|
|
2133
2136
|
);
|
|
2134
2137
|
}
|
|
2138
|
+
/**
|
|
2139
|
+
* Get a stock's institutional ownership quarter by quarter, newest first.
|
|
2140
|
+
*
|
|
2141
|
+
* Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
|
|
2142
|
+
* two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
|
|
2143
|
+
* holder count, the share of the class institutions held (`institutionalOwnershipPct`),
|
|
2144
|
+
* and the quarter's net shares bought or sold, dollar flow and position counts.
|
|
2145
|
+
*
|
|
2146
|
+
* The newest quarter can still be filing (`status: "filing"`), in which case its figures
|
|
2147
|
+
* cover only the institutions that have filed so far. Quarters in which the security had
|
|
2148
|
+
* no holdings are omitted.
|
|
2149
|
+
*
|
|
2150
|
+
* Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
|
|
2151
|
+
* holding the number of quarters in the full window. PRO receives the whole window
|
|
2152
|
+
* without `totalCount`.
|
|
2153
|
+
*
|
|
2154
|
+
* Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
|
|
2155
|
+
*
|
|
2156
|
+
* @example
|
|
2157
|
+
* const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
|
|
2158
|
+
* for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
|
|
2159
|
+
*/
|
|
2160
|
+
async getHoldersHistory(ticker, options) {
|
|
2161
|
+
return this.client.get(
|
|
2162
|
+
`/api/v1/institutional/holders/${encodeURIComponent(ticker)}/history`,
|
|
2163
|
+
{ ...options }
|
|
2164
|
+
);
|
|
2165
|
+
}
|
|
2135
2166
|
/**
|
|
2136
2167
|
* Get activist investor positions (NEW or INCREASED).
|
|
2137
2168
|
*
|
|
@@ -2800,9 +2831,22 @@ function retryAfterSeconds(raw, defaultS, maxWaitS) {
|
|
|
2800
2831
|
function sleep(ms) {
|
|
2801
2832
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
2802
2833
|
}
|
|
2834
|
+
var MISSING_KEY_HINT = "(No API key was sent. Set the SENTISENSE_API_KEY environment variable or pass apiKey; get a free key at https://app.sentisense.ai/get-api-key)";
|
|
2835
|
+
function resolveApiKey(explicit) {
|
|
2836
|
+
if (explicit === null) return void 0;
|
|
2837
|
+
if (explicit) return explicit;
|
|
2838
|
+
try {
|
|
2839
|
+
if (typeof process !== "undefined" && process.env) {
|
|
2840
|
+
const fromEnv = process.env.SENTISENSE_API_KEY?.trim();
|
|
2841
|
+
if (fromEnv) return fromEnv;
|
|
2842
|
+
}
|
|
2843
|
+
} catch {
|
|
2844
|
+
}
|
|
2845
|
+
return void 0;
|
|
2846
|
+
}
|
|
2803
2847
|
var SentiSense = class {
|
|
2804
2848
|
constructor(options = {}) {
|
|
2805
|
-
this.apiKey = options.apiKey;
|
|
2849
|
+
this.apiKey = resolveApiKey(options.apiKey);
|
|
2806
2850
|
this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
2807
2851
|
this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
|
|
2808
2852
|
this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
|
|
@@ -2982,7 +3026,11 @@ var SentiSense = class {
|
|
|
2982
3026
|
switch (response.status) {
|
|
2983
3027
|
case 401:
|
|
2984
3028
|
case 403:
|
|
2985
|
-
throw new AuthenticationError(
|
|
3029
|
+
throw new AuthenticationError(
|
|
3030
|
+
this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
|
|
3031
|
+
response.status,
|
|
3032
|
+
code
|
|
3033
|
+
);
|
|
2986
3034
|
case 404:
|
|
2987
3035
|
throw new NotFoundError(message, code);
|
|
2988
3036
|
case 429: {
|
|
@@ -3186,7 +3234,8 @@ function userAgentSuffix(context) {
|
|
|
3186
3234
|
function createClient(context, options = {}) {
|
|
3187
3235
|
if (!options.anonymous && !context.apiKey) throw new MissingKeyError();
|
|
3188
3236
|
return new SentiSense({
|
|
3189
|
-
|
|
3237
|
+
// null, not undefined: an anonymous probe must not pick up SENTISENSE_API_KEY from the library fallback.
|
|
3238
|
+
apiKey: options.anonymous ? null : context.apiKey,
|
|
3190
3239
|
baseUrl: context.baseUrl,
|
|
3191
3240
|
maxRetries: 0,
|
|
3192
3241
|
userAgentSuffix: userAgentSuffix(context)
|
package/dist/index.cjs
CHANGED
|
@@ -351,6 +351,9 @@ var Earnings = class {
|
|
|
351
351
|
* assuming a fixed lag. A ticker with no stored quarter answers with an empty
|
|
352
352
|
* `data` array, not a 404.
|
|
353
353
|
*
|
|
354
|
+
* The envelope `ticker` names the listing the per-share figures are quoted
|
|
355
|
+
* for: `"BRK.B"` for `BRK-A`, `"GOOGL"` for `GOOG`.
|
|
356
|
+
*
|
|
354
357
|
* Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
|
|
355
358
|
*/
|
|
356
359
|
async getSummaries(ticker, options) {
|
|
@@ -803,6 +806,34 @@ var Institutional = class {
|
|
|
803
806
|
{ reportDate, ...options }
|
|
804
807
|
);
|
|
805
808
|
}
|
|
809
|
+
/**
|
|
810
|
+
* Get a stock's institutional ownership quarter by quarter, newest first.
|
|
811
|
+
*
|
|
812
|
+
* Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
|
|
813
|
+
* two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
|
|
814
|
+
* holder count, the share of the class institutions held (`institutionalOwnershipPct`),
|
|
815
|
+
* and the quarter's net shares bought or sold, dollar flow and position counts.
|
|
816
|
+
*
|
|
817
|
+
* The newest quarter can still be filing (`status: "filing"`), in which case its figures
|
|
818
|
+
* cover only the institutions that have filed so far. Quarters in which the security had
|
|
819
|
+
* no holdings are omitted.
|
|
820
|
+
*
|
|
821
|
+
* Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
|
|
822
|
+
* holding the number of quarters in the full window. PRO receives the whole window
|
|
823
|
+
* without `totalCount`.
|
|
824
|
+
*
|
|
825
|
+
* Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
|
|
826
|
+
*
|
|
827
|
+
* @example
|
|
828
|
+
* const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
|
|
829
|
+
* for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
|
|
830
|
+
*/
|
|
831
|
+
async getHoldersHistory(ticker, options) {
|
|
832
|
+
return this.client.get(
|
|
833
|
+
`/api/v1/institutional/holders/${encodeURIComponent(ticker)}/history`,
|
|
834
|
+
{ ...options }
|
|
835
|
+
);
|
|
836
|
+
}
|
|
806
837
|
/**
|
|
807
838
|
* Get activist investor positions (NEW or INCREASED).
|
|
808
839
|
*
|
|
@@ -1441,7 +1472,7 @@ var Trackers = class {
|
|
|
1441
1472
|
};
|
|
1442
1473
|
|
|
1443
1474
|
// src/version.ts
|
|
1444
|
-
var VERSION = "0.
|
|
1475
|
+
var VERSION = "0.69.0";
|
|
1445
1476
|
|
|
1446
1477
|
// src/client.ts
|
|
1447
1478
|
var DEFAULT_BASE_URL = "https://app.sentisense.ai";
|
|
@@ -1474,9 +1505,22 @@ function retryAfterSeconds(raw, defaultS, maxWaitS) {
|
|
|
1474
1505
|
function sleep(ms) {
|
|
1475
1506
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
1476
1507
|
}
|
|
1508
|
+
var MISSING_KEY_HINT = "(No API key was sent. Set the SENTISENSE_API_KEY environment variable or pass apiKey; get a free key at https://app.sentisense.ai/get-api-key)";
|
|
1509
|
+
function resolveApiKey(explicit) {
|
|
1510
|
+
if (explicit === null) return void 0;
|
|
1511
|
+
if (explicit) return explicit;
|
|
1512
|
+
try {
|
|
1513
|
+
if (typeof process !== "undefined" && process.env) {
|
|
1514
|
+
const fromEnv = process.env.SENTISENSE_API_KEY?.trim();
|
|
1515
|
+
if (fromEnv) return fromEnv;
|
|
1516
|
+
}
|
|
1517
|
+
} catch {
|
|
1518
|
+
}
|
|
1519
|
+
return void 0;
|
|
1520
|
+
}
|
|
1477
1521
|
var SentiSense = class {
|
|
1478
1522
|
constructor(options = {}) {
|
|
1479
|
-
this.apiKey = options.apiKey;
|
|
1523
|
+
this.apiKey = resolveApiKey(options.apiKey);
|
|
1480
1524
|
this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
1481
1525
|
this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
|
|
1482
1526
|
this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
|
|
@@ -1656,7 +1700,11 @@ var SentiSense = class {
|
|
|
1656
1700
|
switch (response.status) {
|
|
1657
1701
|
case 401:
|
|
1658
1702
|
case 403:
|
|
1659
|
-
throw new AuthenticationError(
|
|
1703
|
+
throw new AuthenticationError(
|
|
1704
|
+
this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
|
|
1705
|
+
response.status,
|
|
1706
|
+
code
|
|
1707
|
+
);
|
|
1660
1708
|
case 404:
|
|
1661
1709
|
throw new NotFoundError(message, code);
|
|
1662
1710
|
case 429: {
|