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 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. |
@@ -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.66.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
- /** Get available 13F reporting quarters. */
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(message, response.status, code);
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
- apiKey: options.anonymous ? void 0 : context.apiKey,
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
- /** Get available 13F reporting quarters. */
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.66.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(message, response.status, code);
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: {