sentisense 0.68.0 → 0.70.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
@@ -528,6 +544,9 @@ client.entityMetrics.getMetrics("AAPL", {
528
544
  maxDataPoints: 100,
529
545
  })
530
546
 
547
+ // Daily App Store ratings for a product entity with an app (an entity slug, not a ticker)
548
+ client.entityMetrics.getMetrics("Instagram", { metricType: "app_all_ratings_count" })
549
+
531
550
  // Share of mentions by source (valueType "SHARE_PERCENT")
532
551
  client.entityMetrics.getDistribution("AAPL", "mentions")
533
552
  client.entityMetrics.getDistribution("AAPL", "mentions", { dimension: "source" })
@@ -538,7 +557,9 @@ client.entityMetrics.getDistribution("AAPL", "sentiment")
538
557
 
539
558
  In a distribution, `valueType` says what each number is. For a count metric such as `mentions` or `creators` it is `"SHARE_PERCENT"`: each value is that source's percentage share of the total, summing to about 100. For `sentiment` it is `"MEAN"`: each value is that source's mean polarity over the window, in [-1, 1], the same numbers as `GET /api/v2/metrics/entity/{symbol}/metric/sentiment/mean-by/source` in the [API reference](https://sentisense.ai/docs/api/metrics/). `sentisense_score` has no per-source split and answers with an empty distribution.
540
559
 
541
- Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`. `sentisense` is an alias for `sentisense_score`; either spelling returns the same series, and keys are case-insensitive. Responses always name the canonical type, so a `sentisense` request answers with `SENTISENSE_SCORE`. `sentisense_rating` is the SentiSense Rating score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
560
+ Available metric types: `mentions`, `sentiment`, `sentisense_score`, `sentisense_rating`, `social_dominance`, `creators`, `app_review_count`, `app_rating`, `app_all_ratings_count`, `app_all_ratings_avg`. `sentisense` is an alias for `sentisense_score`; either spelling returns the same series, and keys are case-insensitive. Responses always name the canonical type, so a `sentisense` request answers with `SENTISENSE_SCORE`. `sentisense_rating` is the SentiSense Rating score and is a time series only: it has no source breakdown, so `getDistribution` answers with an empty distribution for it.
561
+
562
+ The four `app_` metrics are daily Apple App Store series for product entities that have an app, so pass an entity slug such as `"Instagram"` rather than a ticker. `app_review_count` and `app_rating` cover the written reviews published that day, a small share of all ratings whose stars skew lower; `app_all_ratings_count` and `app_all_ratings_avg` cover every new rating, star-only and written together, and have no point on a day with no net new ratings or when the store's totals fell. Over a range, weight each day's `app_all_ratings_avg` by `app_all_ratings_count` for the period average. Each point's flat `value` is the count or the average stars.
542
563
 
543
564
  ### Options
544
565
 
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.70.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) {
@@ -1760,7 +1763,10 @@ var EntityMetrics = class {
1760
1763
  *
1761
1764
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
1762
1765
  * case-insensitive; discover slugs via stocks.getEntities()).
1763
- * @param options Metric type and optional time range / resolution.
1766
+ * @param options Metric type and optional time range / resolution. The App Store metrics
1767
+ * (`app_review_count`, `app_rating`, `app_all_ratings_count`,
1768
+ * `app_all_ratings_avg`) apply to product entities with a tracked app, so pass
1769
+ * an entity slug such as "Instagram", not a ticker.
1764
1770
  */
1765
1771
  async getMetrics(symbol, options = {}) {
1766
1772
  const { metricType = "sentiment", startTime, endTime, maxDataPoints } = options;
@@ -2132,6 +2138,34 @@ var Institutional = class {
2132
2138
  { reportDate, ...options }
2133
2139
  );
2134
2140
  }
2141
+ /**
2142
+ * Get a stock's institutional ownership quarter by quarter, newest first.
2143
+ *
2144
+ * Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
2145
+ * two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
2146
+ * holder count, the share of the class institutions held (`institutionalOwnershipPct`),
2147
+ * and the quarter's net shares bought or sold, dollar flow and position counts.
2148
+ *
2149
+ * The newest quarter can still be filing (`status: "filing"`), in which case its figures
2150
+ * cover only the institutions that have filed so far. Quarters in which the security had
2151
+ * no holdings are omitted.
2152
+ *
2153
+ * Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
2154
+ * holding the number of quarters in the full window. PRO receives the whole window
2155
+ * without `totalCount`.
2156
+ *
2157
+ * Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
2158
+ *
2159
+ * @example
2160
+ * const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
2161
+ * for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
2162
+ */
2163
+ async getHoldersHistory(ticker, options) {
2164
+ return this.client.get(
2165
+ `/api/v1/institutional/holders/${encodeURIComponent(ticker)}/history`,
2166
+ { ...options }
2167
+ );
2168
+ }
2135
2169
  /**
2136
2170
  * Get activist investor positions (NEW or INCREASED).
2137
2171
  *
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) {
@@ -431,7 +434,10 @@ var EntityMetrics = class {
431
434
  *
432
435
  * @param symbol Ticker symbol (e.g. "AAPL") or entity urlSlug (e.g. "Nancy-Pelosi",
433
436
  * case-insensitive; discover slugs via stocks.getEntities()).
434
- * @param options Metric type and optional time range / resolution.
437
+ * @param options Metric type and optional time range / resolution. The App Store metrics
438
+ * (`app_review_count`, `app_rating`, `app_all_ratings_count`,
439
+ * `app_all_ratings_avg`) apply to product entities with a tracked app, so pass
440
+ * an entity slug such as "Instagram", not a ticker.
435
441
  */
436
442
  async getMetrics(symbol, options = {}) {
437
443
  const { metricType = "sentiment", startTime, endTime, maxDataPoints } = options;
@@ -803,6 +809,34 @@ var Institutional = class {
803
809
  { reportDate, ...options }
804
810
  );
805
811
  }
812
+ /**
813
+ * Get a stock's institutional ownership quarter by quarter, newest first.
814
+ *
815
+ * Returns the preview envelope wrapping a {@link HoldersHistory} object, so the rows are
816
+ * two levels down: `(await getHoldersHistory(t)).data.quarters`. Each row carries the
817
+ * holder count, the share of the class institutions held (`institutionalOwnershipPct`),
818
+ * and the quarter's net shares bought or sold, dollar flow and position counts.
819
+ *
820
+ * The newest quarter can still be filing (`status: "filing"`), in which case its figures
821
+ * cover only the institutions that have filed so far. Quarters in which the security had
822
+ * no holdings are omitted.
823
+ *
824
+ * Free keys receive the newest four quarters with `isPreview: true` and `totalCount`
825
+ * holding the number of quarters in the full window. PRO receives the whole window
826
+ * without `totalCount`.
827
+ *
828
+ * Share classes are answered separately (`GOOG` and `GOOGL`, `BRK.A` and `BRK.B`).
829
+ *
830
+ * @example
831
+ * const { data } = await client.institutional.getHoldersHistory("AAPL", { quarters: 8 });
832
+ * for (const q of data.quarters) console.log(q.label, q.status, q.institutionalOwnershipPct);
833
+ */
834
+ async getHoldersHistory(ticker, options) {
835
+ return this.client.get(
836
+ `/api/v1/institutional/holders/${encodeURIComponent(ticker)}/history`,
837
+ { ...options }
838
+ );
839
+ }
806
840
  /**
807
841
  * Get activist investor positions (NEW or INCREASED).
808
842
  *
@@ -1441,7 +1475,7 @@ var Trackers = class {
1441
1475
  };
1442
1476
 
1443
1477
  // src/version.ts
1444
- var VERSION = "0.68.0";
1478
+ var VERSION = "0.70.0";
1445
1479
 
1446
1480
  // src/client.ts
1447
1481
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";