sentisense 0.66.0 → 0.68.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 +16 -2
- package/dist/cli.cjs +41 -5
- package/dist/index.cjs +39 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.mts +172 -7
- package/dist/index.d.ts +172 -7
- package/dist/index.mjs +39 -4
- 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. |
|
|
@@ -304,9 +304,23 @@ for (const update of detail.timeline) {
|
|
|
304
304
|
client.institutional.getQuarters()
|
|
305
305
|
client.institutional.getFlows("2025-02-14", { limit: 20 })
|
|
306
306
|
client.institutional.getHolders("AAPL", "2025-02-14")
|
|
307
|
+
client.institutional.getHolders("AAPL") // no date: the ticker's latest settled quarter
|
|
307
308
|
client.institutional.getActivists("2025-02-14")
|
|
308
309
|
```
|
|
309
310
|
|
|
311
|
+
**Pick a filed quarter by its flag.** `getQuarters()` is newest first, and its first entry is usually still filing. Each `Quarter` carries `pending`, `ownershipEligible` and `ownershipEligibleAt`, so select on the flag rather than by position:
|
|
312
|
+
|
|
313
|
+
```typescript
|
|
314
|
+
const quarters = await client.institutional.getQuarters();
|
|
315
|
+
const latest = quarters.find((q) => !q.pending)?.reportDate;
|
|
316
|
+
if (latest) {
|
|
317
|
+
const holders = await client.institutional.getHolders("AAPL", latest, { limit: 25 });
|
|
318
|
+
console.log(holders.data.selection?.status, holders.data.earlyFilers?.reportDate);
|
|
319
|
+
}
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
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
|
+
|
|
310
324
|
`positionsHeld` on an institution detail counts the full portfolio's held positions:
|
|
311
325
|
`max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
|
|
312
326
|
`getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
|
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.68.0";
|
|
1413
1413
|
|
|
1414
1414
|
// src/resources/analyst.ts
|
|
1415
1415
|
var Analyst = class {
|
|
@@ -2071,7 +2071,13 @@ var Institutional = class {
|
|
|
2071
2071
|
constructor(client) {
|
|
2072
2072
|
this.client = client;
|
|
2073
2073
|
}
|
|
2074
|
-
/**
|
|
2074
|
+
/**
|
|
2075
|
+
* Get available 13F reporting quarters, newest first.
|
|
2076
|
+
*
|
|
2077
|
+
* The first entry is usually the quarter that is still filing, so pick by the flag rather
|
|
2078
|
+
* than by position: `quarters.find((q) => !q.pending)?.reportDate`. Each row also carries
|
|
2079
|
+
* `ownershipEligible` and `ownershipEligibleAt`.
|
|
2080
|
+
*/
|
|
2075
2081
|
async getQuarters() {
|
|
2076
2082
|
return this.client.get("/api/v1/institutional/quarters");
|
|
2077
2083
|
}
|
|
@@ -2094,6 +2100,11 @@ var Institutional = class {
|
|
|
2094
2100
|
/**
|
|
2095
2101
|
* Get institutional holders for a specific stock.
|
|
2096
2102
|
*
|
|
2103
|
+
* `reportDate` is optional: omit it (or pass `undefined` ahead of `options`) and the
|
|
2104
|
+
* request carries no date, so the server serves this ticker's latest settled quarter,
|
|
2105
|
+
* echoes it in `data.reportDate` with `data.selection.mode` set to `DEFAULT`, and reports
|
|
2106
|
+
* any newer still-filing quarter separately in `data.earlyFilers`.
|
|
2107
|
+
*
|
|
2097
2108
|
* Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
|
|
2098
2109
|
* are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
|
|
2099
2110
|
* totals like `holderCount`. Free callers get a truncated `holders` array with
|
|
@@ -2107,6 +2118,13 @@ var Institutional = class {
|
|
|
2107
2118
|
* `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
|
|
2108
2119
|
* without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
|
|
2109
2120
|
* server and you get the full unsorted list back with a 200.
|
|
2121
|
+
*
|
|
2122
|
+
* The payload also says how its quarter was chosen (`selection`), reports a newer
|
|
2123
|
+
* still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known
|
|
2124
|
+
* institutions matched against the full roster (`notableHolders`), and summarizes the
|
|
2125
|
+
* quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each
|
|
2126
|
+
* holder row has its own `comparisonStatus`; only `AVAILABLE` on that row supports its
|
|
2127
|
+
* change figures.
|
|
2110
2128
|
*/
|
|
2111
2129
|
async getHolders(ticker, reportDate, options) {
|
|
2112
2130
|
return this.client.get(
|
|
@@ -2782,9 +2800,22 @@ function retryAfterSeconds(raw, defaultS, maxWaitS) {
|
|
|
2782
2800
|
function sleep(ms) {
|
|
2783
2801
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
2784
2802
|
}
|
|
2803
|
+
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)";
|
|
2804
|
+
function resolveApiKey(explicit) {
|
|
2805
|
+
if (explicit === null) return void 0;
|
|
2806
|
+
if (explicit) return explicit;
|
|
2807
|
+
try {
|
|
2808
|
+
if (typeof process !== "undefined" && process.env) {
|
|
2809
|
+
const fromEnv = process.env.SENTISENSE_API_KEY?.trim();
|
|
2810
|
+
if (fromEnv) return fromEnv;
|
|
2811
|
+
}
|
|
2812
|
+
} catch {
|
|
2813
|
+
}
|
|
2814
|
+
return void 0;
|
|
2815
|
+
}
|
|
2785
2816
|
var SentiSense = class {
|
|
2786
2817
|
constructor(options = {}) {
|
|
2787
|
-
this.apiKey = options.apiKey;
|
|
2818
|
+
this.apiKey = resolveApiKey(options.apiKey);
|
|
2788
2819
|
this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
2789
2820
|
this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
|
|
2790
2821
|
this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
|
|
@@ -2964,7 +2995,11 @@ var SentiSense = class {
|
|
|
2964
2995
|
switch (response.status) {
|
|
2965
2996
|
case 401:
|
|
2966
2997
|
case 403:
|
|
2967
|
-
throw new AuthenticationError(
|
|
2998
|
+
throw new AuthenticationError(
|
|
2999
|
+
this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
|
|
3000
|
+
response.status,
|
|
3001
|
+
code
|
|
3002
|
+
);
|
|
2968
3003
|
case 404:
|
|
2969
3004
|
throw new NotFoundError(message, code);
|
|
2970
3005
|
case 429: {
|
|
@@ -3168,7 +3203,8 @@ function userAgentSuffix(context) {
|
|
|
3168
3203
|
function createClient(context, options = {}) {
|
|
3169
3204
|
if (!options.anonymous && !context.apiKey) throw new MissingKeyError();
|
|
3170
3205
|
return new SentiSense({
|
|
3171
|
-
|
|
3206
|
+
// null, not undefined: an anonymous probe must not pick up SENTISENSE_API_KEY from the library fallback.
|
|
3207
|
+
apiKey: options.anonymous ? null : context.apiKey,
|
|
3172
3208
|
baseUrl: context.baseUrl,
|
|
3173
3209
|
maxRetries: 0,
|
|
3174
3210
|
userAgentSuffix: userAgentSuffix(context)
|
package/dist/index.cjs
CHANGED
|
@@ -742,7 +742,13 @@ var Institutional = class {
|
|
|
742
742
|
constructor(client) {
|
|
743
743
|
this.client = client;
|
|
744
744
|
}
|
|
745
|
-
/**
|
|
745
|
+
/**
|
|
746
|
+
* Get available 13F reporting quarters, newest first.
|
|
747
|
+
*
|
|
748
|
+
* The first entry is usually the quarter that is still filing, so pick by the flag rather
|
|
749
|
+
* than by position: `quarters.find((q) => !q.pending)?.reportDate`. Each row also carries
|
|
750
|
+
* `ownershipEligible` and `ownershipEligibleAt`.
|
|
751
|
+
*/
|
|
746
752
|
async getQuarters() {
|
|
747
753
|
return this.client.get("/api/v1/institutional/quarters");
|
|
748
754
|
}
|
|
@@ -765,6 +771,11 @@ var Institutional = class {
|
|
|
765
771
|
/**
|
|
766
772
|
* Get institutional holders for a specific stock.
|
|
767
773
|
*
|
|
774
|
+
* `reportDate` is optional: omit it (or pass `undefined` ahead of `options`) and the
|
|
775
|
+
* request carries no date, so the server serves this ticker's latest settled quarter,
|
|
776
|
+
* echoes it in `data.reportDate` with `data.selection.mode` set to `DEFAULT`, and reports
|
|
777
|
+
* any newer still-filing quarter separately in `data.earlyFilers`.
|
|
778
|
+
*
|
|
768
779
|
* Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
|
|
769
780
|
* are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
|
|
770
781
|
* totals like `holderCount`. Free callers get a truncated `holders` array with
|
|
@@ -778,6 +789,13 @@ var Institutional = class {
|
|
|
778
789
|
* `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
|
|
779
790
|
* without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
|
|
780
791
|
* server and you get the full unsorted list back with a 200.
|
|
792
|
+
*
|
|
793
|
+
* The payload also says how its quarter was chosen (`selection`), reports a newer
|
|
794
|
+
* still-filing quarter separately (`earlyFilersStatus`, `earlyFilers`), lists well-known
|
|
795
|
+
* institutions matched against the full roster (`notableHolders`), and summarizes the
|
|
796
|
+
* quarter-over-quarter comparison (`comparisonReportDate`, `comparisonStatus`). Each
|
|
797
|
+
* holder row has its own `comparisonStatus`; only `AVAILABLE` on that row supports its
|
|
798
|
+
* change figures.
|
|
781
799
|
*/
|
|
782
800
|
async getHolders(ticker, reportDate, options) {
|
|
783
801
|
return this.client.get(
|
|
@@ -1423,7 +1441,7 @@ var Trackers = class {
|
|
|
1423
1441
|
};
|
|
1424
1442
|
|
|
1425
1443
|
// src/version.ts
|
|
1426
|
-
var VERSION = "0.
|
|
1444
|
+
var VERSION = "0.68.0";
|
|
1427
1445
|
|
|
1428
1446
|
// src/client.ts
|
|
1429
1447
|
var DEFAULT_BASE_URL = "https://app.sentisense.ai";
|
|
@@ -1456,9 +1474,22 @@ function retryAfterSeconds(raw, defaultS, maxWaitS) {
|
|
|
1456
1474
|
function sleep(ms) {
|
|
1457
1475
|
return new Promise((resolve) => setTimeout(resolve, ms));
|
|
1458
1476
|
}
|
|
1477
|
+
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)";
|
|
1478
|
+
function resolveApiKey(explicit) {
|
|
1479
|
+
if (explicit === null) return void 0;
|
|
1480
|
+
if (explicit) return explicit;
|
|
1481
|
+
try {
|
|
1482
|
+
if (typeof process !== "undefined" && process.env) {
|
|
1483
|
+
const fromEnv = process.env.SENTISENSE_API_KEY?.trim();
|
|
1484
|
+
if (fromEnv) return fromEnv;
|
|
1485
|
+
}
|
|
1486
|
+
} catch {
|
|
1487
|
+
}
|
|
1488
|
+
return void 0;
|
|
1489
|
+
}
|
|
1459
1490
|
var SentiSense = class {
|
|
1460
1491
|
constructor(options = {}) {
|
|
1461
|
-
this.apiKey = options.apiKey;
|
|
1492
|
+
this.apiKey = resolveApiKey(options.apiKey);
|
|
1462
1493
|
this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
|
|
1463
1494
|
this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
|
|
1464
1495
|
this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
|
|
@@ -1638,7 +1669,11 @@ var SentiSense = class {
|
|
|
1638
1669
|
switch (response.status) {
|
|
1639
1670
|
case 401:
|
|
1640
1671
|
case 403:
|
|
1641
|
-
throw new AuthenticationError(
|
|
1672
|
+
throw new AuthenticationError(
|
|
1673
|
+
this.apiKey ? message : `${message} ${MISSING_KEY_HINT}`,
|
|
1674
|
+
response.status,
|
|
1675
|
+
code
|
|
1676
|
+
);
|
|
1642
1677
|
case 404:
|
|
1643
1678
|
throw new NotFoundError(message, code);
|
|
1644
1679
|
case 429: {
|