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 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: process.env.SENTISENSE_API_KEY });
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` | none | Sent as `X-SentiSense-API-Key`. Required by every endpoint. |
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.67.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(message, response.status, code);
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
- apiKey: options.anonymous ? void 0 : context.apiKey,
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.67.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(message, response.status, code);
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: {