sentisense 0.65.0 → 0.67.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
@@ -67,6 +67,7 @@ npx -y sentisense@latest health
67
67
  | Command | What you get |
68
68
  |---------|--------------|
69
69
  | `auth [key]` | Store a key, show what is configured, or `--remove` it |
70
+ | `init` | A temporary key with no signup, printed as `SENTISENSE_API_KEY=...`, plus a link to keep it |
70
71
  | `health` | Reachability, key validity, latency, and the resolved base URL |
71
72
  | `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker; ETFs show AUM, expense ratio and NAV |
72
73
  | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
@@ -85,6 +86,17 @@ npx -y sentisense@latest health
85
86
 
86
87
  Run `sentisense help <command>` for its flags and examples.
87
88
 
89
+ ### Getting a key with no signup
90
+
91
+ `init` is built for coding agents: it asks nothing and writes nothing into your project.
92
+
93
+ ```bash
94
+ npx -y sentisense@latest init # prints SENTISENSE_API_KEY=<key> and a keep link
95
+ npx -y sentisense@latest init --json # the same, as JSON
96
+ ```
97
+
98
+ It prints a temporary free key as `SENTISENSE_API_KEY=<key>`. Store it the way your project already stores secrets; the SDK and every command read `SENTISENSE_API_KEY` from the environment. To keep the key, open the link it prints, sign in or create a free account, and the same key stays on your account with nothing else to change. Until it is kept, the key stops working after a few days and has request limits; the link still keeps it for about two weeks. When a key is already configured, `init` says so and makes no new one; `--new` asks for a fresh temporary key anyway. To tell machines that share a network apart, the request carries a random per-install id, stored as `install-id` in the CLI's config directory; it identifies nothing about you.
99
+
88
100
  Three of these chain into each other. Start from a name, land on a person:
89
101
 
90
102
  ```bash
@@ -292,9 +304,23 @@ for (const update of detail.timeline) {
292
304
  client.institutional.getQuarters()
293
305
  client.institutional.getFlows("2025-02-14", { limit: 20 })
294
306
  client.institutional.getHolders("AAPL", "2025-02-14")
307
+ client.institutional.getHolders("AAPL") // no date: the ticker's latest settled quarter
295
308
  client.institutional.getActivists("2025-02-14")
296
309
  ```
297
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
+
298
324
  `positionsHeld` on an institution detail counts the full portfolio's held positions:
299
325
  `max(0, holdingsCount - soldOutPositions)`, even when the holdings list is truncated.
300
326
  `getInstitutionDetail` keeps its `Promise<unknown>` signature. The exported all-optional
package/dist/cli.cjs CHANGED
@@ -72,6 +72,10 @@ var EXIT_TABLE = [
72
72
  var KEY_URL = "https://app.sentisense.ai/get-api-key";
73
73
  var PRICING_URL = "https://app.sentisense.ai/pricing";
74
74
  var QUOTA_EXCEEDED = "quota_exceeded";
75
+ var KEY_LIMIT_REACHED = "key_limit_reached";
76
+ var KEY_EXPIRED = "key_expired";
77
+ var KEY_NOT_KEPT = "key_not_kept";
78
+ var KEEP_HINT = "keep the key with the keep link (in the message above, or the one sentisense init printed with the key), then run it again.";
75
79
  var CliUsageError = class extends Error {
76
80
  constructor(message, hint) {
77
81
  super(message);
@@ -94,6 +98,14 @@ var NoMatchError = class extends Error {
94
98
  this.hint = hint;
95
99
  }
96
100
  };
101
+ var CliCommandError = class extends Error {
102
+ constructor(message, hint, exitCode = EXIT.ERROR) {
103
+ super(message);
104
+ this.name = "CliCommandError";
105
+ this.hint = hint;
106
+ this.exitCode = exitCode;
107
+ }
108
+ };
97
109
  var MissingKeyError = class extends Error {
98
110
  constructor() {
99
111
  super("no API key configured.");
@@ -132,6 +144,12 @@ function classify(error, command) {
132
144
  lines: [`error: ${error.message}`, `next: ${error.hint}`]
133
145
  };
134
146
  }
147
+ if (error instanceof CliCommandError) {
148
+ return {
149
+ exitCode: error.exitCode,
150
+ lines: [`error: ${error.message}`, `next: ${error.hint}`]
151
+ };
152
+ }
135
153
  if (error instanceof CliUsageError) {
136
154
  return {
137
155
  exitCode: EXIT.USAGE,
@@ -141,6 +159,19 @@ function classify(error, command) {
141
159
  ]
142
160
  };
143
161
  }
162
+ if (error instanceof AuthenticationError && error.code === KEY_EXPIRED) {
163
+ const keepable = /\/keep-key\b/.test(error.message);
164
+ return {
165
+ exitCode: EXIT.AUTH,
166
+ lines: [
167
+ `error: ${error.message}`,
168
+ keepable ? "next: open the keep link above and sign in; the same key works again with nothing in the project to change." : `next: run "sentisense init --new" for a new key, or get one at ${KEY_URL}`
169
+ ]
170
+ };
171
+ }
172
+ if (error instanceof AuthenticationError && error.code === KEY_NOT_KEPT) {
173
+ return { exitCode: EXIT.AUTH, lines: [`error: ${error.message}`, `next: ${KEEP_HINT}`] };
174
+ }
144
175
  if (error instanceof AuthenticationError) {
145
176
  return {
146
177
  exitCode: EXIT.AUTH,
@@ -159,6 +190,9 @@ function classify(error, command) {
159
190
  ]
160
191
  };
161
192
  }
193
+ if (error instanceof RateLimitError && error.code === KEY_LIMIT_REACHED) {
194
+ return { exitCode: EXIT.RATE_LIMIT, lines: [`error: ${error.message}`, `next: ${KEEP_HINT}`] };
195
+ }
162
196
  if (error instanceof RateLimitError) {
163
197
  if (error.code === QUOTA_EXCEEDED) {
164
198
  return {
@@ -749,10 +783,13 @@ async function coverageRun({ api, ticker, lookbackDays, full, args }) {
749
783
  }
750
784
 
751
785
  // src/cli/config.ts
786
+ var import_node_crypto = require("crypto");
752
787
  var import_node_fs = require("fs");
753
788
  var import_node_os = require("os");
754
789
  var import_node_path = require("path");
755
790
  var CONFIG_FILE = "config.json";
791
+ var INSTALL_ID_FILE = "install-id";
792
+ var UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
756
793
  function resolveConfigDir(env, override) {
757
794
  if (override) return override;
758
795
  const explicit = env.SENTISENSE_CONFIG_DIR?.trim();
@@ -789,6 +826,22 @@ function writeConfig(dir, config) {
789
826
  (0, import_node_fs.chmodSync)(path, 384);
790
827
  return path;
791
828
  }
829
+ function readOrCreateInstallId(dir) {
830
+ const path = (0, import_node_path.join)(dir, INSTALL_ID_FILE);
831
+ try {
832
+ if ((0, import_node_fs.existsSync)(path)) {
833
+ const stored = (0, import_node_fs.readFileSync)(path, "utf8").trim().toLowerCase();
834
+ if (UUID_PATTERN.test(stored)) return stored;
835
+ }
836
+ const id = (0, import_node_crypto.randomUUID)();
837
+ (0, import_node_fs.mkdirSync)(dir, { recursive: true, mode: 448 });
838
+ (0, import_node_fs.writeFileSync)(path, `${id}
839
+ `, { mode: 384 });
840
+ return (0, import_node_fs.readFileSync)(path, "utf8").trim() === id ? id : null;
841
+ } catch {
842
+ return null;
843
+ }
844
+ }
792
845
  function clearConfig(dir) {
793
846
  const path = configPath(dir);
794
847
  if (!(0, import_node_fs.existsSync)(path)) return false;
@@ -1356,7 +1409,7 @@ var flowsCommand = {
1356
1409
  };
1357
1410
 
1358
1411
  // src/version.ts
1359
- var VERSION = "0.65.0";
1412
+ var VERSION = "0.67.0";
1360
1413
 
1361
1414
  // src/resources/analyst.ts
1362
1415
  var Analyst = class {
@@ -2018,7 +2071,13 @@ var Institutional = class {
2018
2071
  constructor(client) {
2019
2072
  this.client = client;
2020
2073
  }
2021
- /** 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
+ */
2022
2081
  async getQuarters() {
2023
2082
  return this.client.get("/api/v1/institutional/quarters");
2024
2083
  }
@@ -2041,6 +2100,11 @@ var Institutional = class {
2041
2100
  /**
2042
2101
  * Get institutional holders for a specific stock.
2043
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
+ *
2044
2108
  * Returns the preview envelope wrapping a {@link TickerHolders} object, so the rows
2045
2109
  * are two levels down: `(await getHolders(t, d)).data.holders`, alongside ticker-level
2046
2110
  * totals like `holderCount`. Free callers get a truncated `holders` array with
@@ -2054,6 +2118,13 @@ var Institutional = class {
2054
2118
  * `returnedCount`, `offset`, and a `notableChanges` summary, so you can walk the list
2055
2119
  * without re-counting it. Without it, `offset` / `sortBy` / `sortDir` are ignored by the
2056
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.
2057
2128
  */
2058
2129
  async getHolders(ticker, reportDate, options) {
2059
2130
  return this.client.get(
@@ -2708,11 +2779,11 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
2708
2779
  var MAX_DEEP_HISTORY_WAIT_S = 30;
2709
2780
  var MAX_RATE_LIMIT_WAIT_S = 120;
2710
2781
  var RATE_LIMIT_FALLBACK_WAIT_S = 60;
2711
- var QUOTA_EXCEEDED_CODE = "quota_exceeded";
2712
- async function isQuotaExceeded(response) {
2782
+ var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["quota_exceeded", "key_limit_reached"]);
2783
+ async function isAllowanceExhausted(response) {
2713
2784
  try {
2714
2785
  const body = await response.clone().json();
2715
- return body?.error === QUOTA_EXCEEDED_CODE;
2786
+ return typeof body?.error === "string" && NON_RETRYABLE_429_CODES.has(body.error);
2716
2787
  } catch {
2717
2788
  return false;
2718
2789
  }
@@ -2802,7 +2873,7 @@ var SentiSense = class {
2802
2873
  );
2803
2874
  }
2804
2875
  if (!response.ok) {
2805
- if (response.status === 429 && await isQuotaExceeded(response)) {
2876
+ if (response.status === 429 && await isAllowanceExhausted(response)) {
2806
2877
  await this.handleErrorResponse(response);
2807
2878
  }
2808
2879
  const isRetryable = response.status === 429 || response.status >= 500;
@@ -2851,9 +2922,10 @@ var SentiSense = class {
2851
2922
  throw new SentiSenseError("All retries exhausted");
2852
2923
  }
2853
2924
  /** @internal */
2854
- async post(path, body) {
2925
+ async post(path, body, extraHeaders) {
2855
2926
  const url = this.buildUrl(path);
2856
2927
  const headers = {
2928
+ ...extraHeaders,
2857
2929
  "Accept": "application/json",
2858
2930
  "Content-Type": "application/json"
2859
2931
  };
@@ -3207,6 +3279,152 @@ var healthCommand = {
3207
3279
  }
3208
3280
  };
3209
3281
 
3282
+ // src/cli/commands/init.ts
3283
+ var ENV_VAR = "SENTISENSE_API_KEY";
3284
+ var KEY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
3285
+ var PROVISION_PATH = "/api/v1/keys/provision";
3286
+ var CLIENT_ID_HEADER = "X-SentiSense-Client-Id";
3287
+ var LLMS_URL = "https://sentisense.ai/llms.txt";
3288
+ var SKILL_URL = "https://sentisense.ai/skill.md";
3289
+ var SOURCE_TEXT = {
3290
+ config: 'your own key saved with "sentisense auth"',
3291
+ flag: "the key passed with --api-key",
3292
+ env: "the key in your SENTISENSE_API_KEY environment variable"
3293
+ };
3294
+ var BY_HAND = `get a free key at ${KEY_URL}.`;
3295
+ function formatUtc(epochSeconds) {
3296
+ return `${new Date(epochSeconds * 1e3).toISOString().slice(0, 16).replace("T", " ")} UTC`;
3297
+ }
3298
+ function isProvisionedKey(value) {
3299
+ if (!value || typeof value !== "object") return false;
3300
+ const body = value;
3301
+ return typeof body.apiKey === "string" && KEY_PATTERN.test(body.apiKey) && typeof body.expiresAt === "number" && Number.isFinite(body.expiresAt) && typeof body.keepUrl === "string" && /^https?:\/\/\S+$/.test(body.keepUrl);
3302
+ }
3303
+ async function mintKey(context) {
3304
+ const client = createClient(context, { anonymous: true });
3305
+ const installId = readOrCreateInstallId(context.configDir);
3306
+ let answer;
3307
+ try {
3308
+ answer = await client.post(PROVISION_PATH, {}, installId ? { [CLIENT_ID_HEADER]: installId } : void 0);
3309
+ } catch (error) {
3310
+ if (error instanceof NotFoundError || error instanceof AuthenticationError && error.status === 401) {
3311
+ throw new CliCommandError("this SentiSense server does not hand out keys from the command line.", BY_HAND, EXIT.AUTH);
3312
+ }
3313
+ if (error instanceof RateLimitError && error.code === "keep_existing_key") {
3314
+ throw new CliCommandError(
3315
+ error.message,
3316
+ `open the keep link that came with the key init gave you before and sign in, or ${BY_HAND}`,
3317
+ EXIT.RATE_LIMIT
3318
+ );
3319
+ }
3320
+ if (error instanceof RateLimitError) {
3321
+ throw new CliCommandError(error.message, BY_HAND, EXIT.RATE_LIMIT);
3322
+ }
3323
+ if (error instanceof SentiSenseError && error.code === "provision_paused") {
3324
+ throw new CliCommandError(error.message, `try again after 00:00 UTC, or ${BY_HAND}`, EXIT.RATE_LIMIT);
3325
+ }
3326
+ if (error instanceof AuthenticationError) {
3327
+ throw new CliCommandError(error.message, BY_HAND, EXIT.AUTH);
3328
+ }
3329
+ if (error instanceof SentiSenseError && error.status !== void 0 && error.status >= 500) {
3330
+ throw new CliCommandError(error.message, `try again in a few minutes, or ${BY_HAND}`, EXIT.ERROR);
3331
+ }
3332
+ throw error;
3333
+ }
3334
+ if (!isProvisionedKey(answer)) {
3335
+ throw new CliCommandError("the server's answer did not contain a usable key.", BY_HAND, EXIT.ERROR);
3336
+ }
3337
+ return answer;
3338
+ }
3339
+ function limitsText(limits) {
3340
+ if (!limits) return "";
3341
+ const parts = [];
3342
+ if (limits.requestsPerDay) parts.push(`${limits.requestsPerDay.toLocaleString("en-US")} a day`);
3343
+ if (limits.requestsPerMinute) parts.push(`${limits.requestsPerMinute} a minute`);
3344
+ if (limits.requestsTotal) {
3345
+ const pace = parts.length ? ` (at most ${parts.join(", ")})` : "";
3346
+ return ` Until it is kept, the key has ${limits.requestsTotal.toLocaleString("en-US")} requests in all${pace}.`;
3347
+ }
3348
+ return parts.length ? ` Until it is kept, the key allows ${parts.join(" and ")}.` : "";
3349
+ }
3350
+ var initCommand = {
3351
+ name: "init",
3352
+ summary: "Get an API key with no signup and print it, with a link to keep it",
3353
+ usage: "sentisense init [--new]",
3354
+ examples: ["npx sentisense init", "npx sentisense init --json", "npx sentisense init --new"],
3355
+ notes: [
3356
+ "Runs without prompts, so a coding agent can run it. It writes nothing into your project:",
3357
+ "it prints SENTISENSE_API_KEY=<key> and a keep link. Store the key the way the project",
3358
+ "already stores secrets (an environment variable, a .env file kept out of git, a secret",
3359
+ "manager). The SDK and every sentisense command read SENTISENSE_API_KEY from the environment.",
3360
+ "The key is temporary until kept: open the link, sign in or create a free account, and the",
3361
+ "same key stays on your account. Until then it stops working after a few days and has request",
3362
+ "limits; the link keeps it for about two weeks, even after it stops working.",
3363
+ "When a key is already configured (--api-key, the environment, or sentisense auth), init says",
3364
+ "so and makes no new one; --new asks for a fresh temporary key anyway.",
3365
+ "Exits 3 when no key could be obtained, 5 when today's temporary keys for this network are",
3366
+ "used up."
3367
+ ],
3368
+ flags: {
3369
+ new: { type: "boolean", describe: "Ask for a fresh temporary key even when one is already configured" }
3370
+ },
3371
+ async run({ args, context }) {
3372
+ if (args.positionals.length > 0) {
3373
+ throw new CliUsageError(`init takes no arguments, got "${args.positionals[0]}".`, "run it as: sentisense init");
3374
+ }
3375
+ if (context.apiKey && args.flags.new !== true) {
3376
+ const source = context.apiKeySource === "default" ? "config" : context.apiKeySource;
3377
+ return {
3378
+ json: {
3379
+ apiKey: null,
3380
+ configured: { source, masked: maskKey(context.apiKey) },
3381
+ temporary: false,
3382
+ envVar: ENV_VAR,
3383
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3384
+ },
3385
+ doc: doc(
3386
+ { kind: "text", text: `A key is already configured: ${SOURCE_TEXT[source]} (${maskKey(context.apiKey)}).` },
3387
+ { kind: "text", text: 'No new key was made. Run "sentisense init --new" for a fresh temporary key.', tone: "dim" }
3388
+ )
3389
+ };
3390
+ }
3391
+ const minted = await mintKey(context);
3392
+ const keepWindow = minted.keepUntil ? `; it works until ${formatUtc(minted.keepUntil)}, even after the key stops` : "";
3393
+ return {
3394
+ json: {
3395
+ apiKey: minted.apiKey,
3396
+ envVar: ENV_VAR,
3397
+ temporary: true,
3398
+ expiresAt: minted.expiresAt,
3399
+ keepUntil: minted.keepUntil ?? null,
3400
+ keepUrl: minted.keepUrl,
3401
+ limits: minted.limits ?? null,
3402
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3403
+ },
3404
+ doc: doc(
3405
+ { kind: "text", text: `${ENV_VAR}=${minted.apiKey}` },
3406
+ { kind: "blank" },
3407
+ {
3408
+ kind: "text",
3409
+ text: `A temporary key, working until ${formatUtc(minted.expiresAt)} unless kept. Set it as the ${ENV_VAR} environment variable wherever this project keeps its secrets; the SDK and the sentisense commands read it from there.`
3410
+ },
3411
+ { kind: "blank" },
3412
+ {
3413
+ kind: "text",
3414
+ text: "Keep this key: open this link and sign in (or create a free account), and the same key stays on your account for good. Nothing else changes."
3415
+ },
3416
+ { kind: "text", text: minted.keepUrl, tone: "accent" },
3417
+ {
3418
+ kind: "text",
3419
+ text: `Save the link with the key${keepWindow}.${limitsText(minted.limits)}`,
3420
+ tone: "dim"
3421
+ },
3422
+ { kind: "text", text: `API reference for agents: ${LLMS_URL}`, tone: "dim" }
3423
+ )
3424
+ };
3425
+ }
3426
+ };
3427
+
3210
3428
  // src/cli/commands/insiders.ts
3211
3429
  var insidersCommand = {
3212
3430
  name: "insiders",
@@ -4510,6 +4728,7 @@ var sentimentCommand = {
4510
4728
  // src/cli/commands/index.ts
4511
4729
  var COMMANDS = [
4512
4730
  authCommand,
4731
+ initCommand,
4513
4732
  healthCommand,
4514
4733
  quoteCommand,
4515
4734
  sentimentCommand,
@@ -4535,6 +4754,7 @@ var OFFLINE_COMMANDS = /* @__PURE__ */ new Set(["auth"]);
4535
4754
  // src/cli/help.ts
4536
4755
  var EXAMPLE = {
4537
4756
  auth: "sentisense auth $SENTISENSE_API_KEY",
4757
+ init: "npx sentisense init",
4538
4758
  health: "sentisense health",
4539
4759
  quote: "sentisense quote NVDA AAPL",
4540
4760
  sentiment: "sentisense sentiment NVDA --days 30",
@@ -4583,6 +4803,7 @@ function mainHelp() {
4583
4803
  " --full widens a command, --plain and --no-color force text, --debug shows stack traces.",
4584
4804
  "",
4585
4805
  "Setup:",
4806
+ " sentisense init print a temporary key with no signup, and a link to keep it",
4586
4807
  ` sentisense auth <key> store a key at ~/.config/sentisense/config.json (0600)`,
4587
4808
  " SENTISENSE_API_KEY=<key> or pass it in the environment",
4588
4809
  ` Get a key at ${KEY_URL}`,
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.65.0";
1444
+ var VERSION = "0.67.0";
1427
1445
 
1428
1446
  // src/client.ts
1429
1447
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1435,11 +1453,11 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
1435
1453
  var MAX_DEEP_HISTORY_WAIT_S = 30;
1436
1454
  var MAX_RATE_LIMIT_WAIT_S = 120;
1437
1455
  var RATE_LIMIT_FALLBACK_WAIT_S = 60;
1438
- var QUOTA_EXCEEDED_CODE = "quota_exceeded";
1439
- async function isQuotaExceeded(response) {
1456
+ var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["quota_exceeded", "key_limit_reached"]);
1457
+ async function isAllowanceExhausted(response) {
1440
1458
  try {
1441
1459
  const body = await response.clone().json();
1442
- return body?.error === QUOTA_EXCEEDED_CODE;
1460
+ return typeof body?.error === "string" && NON_RETRYABLE_429_CODES.has(body.error);
1443
1461
  } catch {
1444
1462
  return false;
1445
1463
  }
@@ -1529,7 +1547,7 @@ var SentiSense = class {
1529
1547
  );
1530
1548
  }
1531
1549
  if (!response.ok) {
1532
- if (response.status === 429 && await isQuotaExceeded(response)) {
1550
+ if (response.status === 429 && await isAllowanceExhausted(response)) {
1533
1551
  await this.handleErrorResponse(response);
1534
1552
  }
1535
1553
  const isRetryable = response.status === 429 || response.status >= 500;
@@ -1578,9 +1596,10 @@ var SentiSense = class {
1578
1596
  throw new SentiSenseError("All retries exhausted");
1579
1597
  }
1580
1598
  /** @internal */
1581
- async post(path, body) {
1599
+ async post(path, body, extraHeaders) {
1582
1600
  const url = this.buildUrl(path);
1583
1601
  const headers = {
1602
+ ...extraHeaders,
1584
1603
  "Accept": "application/json",
1585
1604
  "Content-Type": "application/json"
1586
1605
  };