sentisense 0.68.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
@@ -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.68.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
  *
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.68.0";
1475
+ var VERSION = "0.69.0";
1445
1476
 
1446
1477
  // src/client.ts
1447
1478
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";