sentisense 0.65.0 → 0.66.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
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.66.0";
1360
1413
 
1361
1414
  // src/resources/analyst.ts
1362
1415
  var Analyst = class {
@@ -2708,11 +2761,11 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
2708
2761
  var MAX_DEEP_HISTORY_WAIT_S = 30;
2709
2762
  var MAX_RATE_LIMIT_WAIT_S = 120;
2710
2763
  var RATE_LIMIT_FALLBACK_WAIT_S = 60;
2711
- var QUOTA_EXCEEDED_CODE = "quota_exceeded";
2712
- async function isQuotaExceeded(response) {
2764
+ var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["quota_exceeded", "key_limit_reached"]);
2765
+ async function isAllowanceExhausted(response) {
2713
2766
  try {
2714
2767
  const body = await response.clone().json();
2715
- return body?.error === QUOTA_EXCEEDED_CODE;
2768
+ return typeof body?.error === "string" && NON_RETRYABLE_429_CODES.has(body.error);
2716
2769
  } catch {
2717
2770
  return false;
2718
2771
  }
@@ -2802,7 +2855,7 @@ var SentiSense = class {
2802
2855
  );
2803
2856
  }
2804
2857
  if (!response.ok) {
2805
- if (response.status === 429 && await isQuotaExceeded(response)) {
2858
+ if (response.status === 429 && await isAllowanceExhausted(response)) {
2806
2859
  await this.handleErrorResponse(response);
2807
2860
  }
2808
2861
  const isRetryable = response.status === 429 || response.status >= 500;
@@ -2851,9 +2904,10 @@ var SentiSense = class {
2851
2904
  throw new SentiSenseError("All retries exhausted");
2852
2905
  }
2853
2906
  /** @internal */
2854
- async post(path, body) {
2907
+ async post(path, body, extraHeaders) {
2855
2908
  const url = this.buildUrl(path);
2856
2909
  const headers = {
2910
+ ...extraHeaders,
2857
2911
  "Accept": "application/json",
2858
2912
  "Content-Type": "application/json"
2859
2913
  };
@@ -3207,6 +3261,152 @@ var healthCommand = {
3207
3261
  }
3208
3262
  };
3209
3263
 
3264
+ // src/cli/commands/init.ts
3265
+ var ENV_VAR = "SENTISENSE_API_KEY";
3266
+ var KEY_PATTERN = /^[A-Za-z0-9_-]{8,128}$/;
3267
+ var PROVISION_PATH = "/api/v1/keys/provision";
3268
+ var CLIENT_ID_HEADER = "X-SentiSense-Client-Id";
3269
+ var LLMS_URL = "https://sentisense.ai/llms.txt";
3270
+ var SKILL_URL = "https://sentisense.ai/skill.md";
3271
+ var SOURCE_TEXT = {
3272
+ config: 'your own key saved with "sentisense auth"',
3273
+ flag: "the key passed with --api-key",
3274
+ env: "the key in your SENTISENSE_API_KEY environment variable"
3275
+ };
3276
+ var BY_HAND = `get a free key at ${KEY_URL}.`;
3277
+ function formatUtc(epochSeconds) {
3278
+ return `${new Date(epochSeconds * 1e3).toISOString().slice(0, 16).replace("T", " ")} UTC`;
3279
+ }
3280
+ function isProvisionedKey(value) {
3281
+ if (!value || typeof value !== "object") return false;
3282
+ const body = value;
3283
+ 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);
3284
+ }
3285
+ async function mintKey(context) {
3286
+ const client = createClient(context, { anonymous: true });
3287
+ const installId = readOrCreateInstallId(context.configDir);
3288
+ let answer;
3289
+ try {
3290
+ answer = await client.post(PROVISION_PATH, {}, installId ? { [CLIENT_ID_HEADER]: installId } : void 0);
3291
+ } catch (error) {
3292
+ if (error instanceof NotFoundError || error instanceof AuthenticationError && error.status === 401) {
3293
+ throw new CliCommandError("this SentiSense server does not hand out keys from the command line.", BY_HAND, EXIT.AUTH);
3294
+ }
3295
+ if (error instanceof RateLimitError && error.code === "keep_existing_key") {
3296
+ throw new CliCommandError(
3297
+ error.message,
3298
+ `open the keep link that came with the key init gave you before and sign in, or ${BY_HAND}`,
3299
+ EXIT.RATE_LIMIT
3300
+ );
3301
+ }
3302
+ if (error instanceof RateLimitError) {
3303
+ throw new CliCommandError(error.message, BY_HAND, EXIT.RATE_LIMIT);
3304
+ }
3305
+ if (error instanceof SentiSenseError && error.code === "provision_paused") {
3306
+ throw new CliCommandError(error.message, `try again after 00:00 UTC, or ${BY_HAND}`, EXIT.RATE_LIMIT);
3307
+ }
3308
+ if (error instanceof AuthenticationError) {
3309
+ throw new CliCommandError(error.message, BY_HAND, EXIT.AUTH);
3310
+ }
3311
+ if (error instanceof SentiSenseError && error.status !== void 0 && error.status >= 500) {
3312
+ throw new CliCommandError(error.message, `try again in a few minutes, or ${BY_HAND}`, EXIT.ERROR);
3313
+ }
3314
+ throw error;
3315
+ }
3316
+ if (!isProvisionedKey(answer)) {
3317
+ throw new CliCommandError("the server's answer did not contain a usable key.", BY_HAND, EXIT.ERROR);
3318
+ }
3319
+ return answer;
3320
+ }
3321
+ function limitsText(limits) {
3322
+ if (!limits) return "";
3323
+ const parts = [];
3324
+ if (limits.requestsPerDay) parts.push(`${limits.requestsPerDay.toLocaleString("en-US")} a day`);
3325
+ if (limits.requestsPerMinute) parts.push(`${limits.requestsPerMinute} a minute`);
3326
+ if (limits.requestsTotal) {
3327
+ const pace = parts.length ? ` (at most ${parts.join(", ")})` : "";
3328
+ return ` Until it is kept, the key has ${limits.requestsTotal.toLocaleString("en-US")} requests in all${pace}.`;
3329
+ }
3330
+ return parts.length ? ` Until it is kept, the key allows ${parts.join(" and ")}.` : "";
3331
+ }
3332
+ var initCommand = {
3333
+ name: "init",
3334
+ summary: "Get an API key with no signup and print it, with a link to keep it",
3335
+ usage: "sentisense init [--new]",
3336
+ examples: ["npx sentisense init", "npx sentisense init --json", "npx sentisense init --new"],
3337
+ notes: [
3338
+ "Runs without prompts, so a coding agent can run it. It writes nothing into your project:",
3339
+ "it prints SENTISENSE_API_KEY=<key> and a keep link. Store the key the way the project",
3340
+ "already stores secrets (an environment variable, a .env file kept out of git, a secret",
3341
+ "manager). The SDK and every sentisense command read SENTISENSE_API_KEY from the environment.",
3342
+ "The key is temporary until kept: open the link, sign in or create a free account, and the",
3343
+ "same key stays on your account. Until then it stops working after a few days and has request",
3344
+ "limits; the link keeps it for about two weeks, even after it stops working.",
3345
+ "When a key is already configured (--api-key, the environment, or sentisense auth), init says",
3346
+ "so and makes no new one; --new asks for a fresh temporary key anyway.",
3347
+ "Exits 3 when no key could be obtained, 5 when today's temporary keys for this network are",
3348
+ "used up."
3349
+ ],
3350
+ flags: {
3351
+ new: { type: "boolean", describe: "Ask for a fresh temporary key even when one is already configured" }
3352
+ },
3353
+ async run({ args, context }) {
3354
+ if (args.positionals.length > 0) {
3355
+ throw new CliUsageError(`init takes no arguments, got "${args.positionals[0]}".`, "run it as: sentisense init");
3356
+ }
3357
+ if (context.apiKey && args.flags.new !== true) {
3358
+ const source = context.apiKeySource === "default" ? "config" : context.apiKeySource;
3359
+ return {
3360
+ json: {
3361
+ apiKey: null,
3362
+ configured: { source, masked: maskKey(context.apiKey) },
3363
+ temporary: false,
3364
+ envVar: ENV_VAR,
3365
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3366
+ },
3367
+ doc: doc(
3368
+ { kind: "text", text: `A key is already configured: ${SOURCE_TEXT[source]} (${maskKey(context.apiKey)}).` },
3369
+ { kind: "text", text: 'No new key was made. Run "sentisense init --new" for a fresh temporary key.', tone: "dim" }
3370
+ )
3371
+ };
3372
+ }
3373
+ const minted = await mintKey(context);
3374
+ const keepWindow = minted.keepUntil ? `; it works until ${formatUtc(minted.keepUntil)}, even after the key stops` : "";
3375
+ return {
3376
+ json: {
3377
+ apiKey: minted.apiKey,
3378
+ envVar: ENV_VAR,
3379
+ temporary: true,
3380
+ expiresAt: minted.expiresAt,
3381
+ keepUntil: minted.keepUntil ?? null,
3382
+ keepUrl: minted.keepUrl,
3383
+ limits: minted.limits ?? null,
3384
+ docs: { llms: LLMS_URL, skill: SKILL_URL }
3385
+ },
3386
+ doc: doc(
3387
+ { kind: "text", text: `${ENV_VAR}=${minted.apiKey}` },
3388
+ { kind: "blank" },
3389
+ {
3390
+ kind: "text",
3391
+ 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.`
3392
+ },
3393
+ { kind: "blank" },
3394
+ {
3395
+ kind: "text",
3396
+ 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."
3397
+ },
3398
+ { kind: "text", text: minted.keepUrl, tone: "accent" },
3399
+ {
3400
+ kind: "text",
3401
+ text: `Save the link with the key${keepWindow}.${limitsText(minted.limits)}`,
3402
+ tone: "dim"
3403
+ },
3404
+ { kind: "text", text: `API reference for agents: ${LLMS_URL}`, tone: "dim" }
3405
+ )
3406
+ };
3407
+ }
3408
+ };
3409
+
3210
3410
  // src/cli/commands/insiders.ts
3211
3411
  var insidersCommand = {
3212
3412
  name: "insiders",
@@ -4510,6 +4710,7 @@ var sentimentCommand = {
4510
4710
  // src/cli/commands/index.ts
4511
4711
  var COMMANDS = [
4512
4712
  authCommand,
4713
+ initCommand,
4513
4714
  healthCommand,
4514
4715
  quoteCommand,
4515
4716
  sentimentCommand,
@@ -4535,6 +4736,7 @@ var OFFLINE_COMMANDS = /* @__PURE__ */ new Set(["auth"]);
4535
4736
  // src/cli/help.ts
4536
4737
  var EXAMPLE = {
4537
4738
  auth: "sentisense auth $SENTISENSE_API_KEY",
4739
+ init: "npx sentisense init",
4538
4740
  health: "sentisense health",
4539
4741
  quote: "sentisense quote NVDA AAPL",
4540
4742
  sentiment: "sentisense sentiment NVDA --days 30",
@@ -4583,6 +4785,7 @@ function mainHelp() {
4583
4785
  " --full widens a command, --plain and --no-color force text, --debug shows stack traces.",
4584
4786
  "",
4585
4787
  "Setup:",
4788
+ " sentisense init print a temporary key with no signup, and a link to keep it",
4586
4789
  ` sentisense auth <key> store a key at ~/.config/sentisense/config.json (0600)`,
4587
4790
  " SENTISENSE_API_KEY=<key> or pass it in the environment",
4588
4791
  ` Get a key at ${KEY_URL}`,
package/dist/index.cjs CHANGED
@@ -1423,7 +1423,7 @@ var Trackers = class {
1423
1423
  };
1424
1424
 
1425
1425
  // src/version.ts
1426
- var VERSION = "0.65.0";
1426
+ var VERSION = "0.66.0";
1427
1427
 
1428
1428
  // src/client.ts
1429
1429
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -1435,11 +1435,11 @@ var DEEP_HISTORY_FALLBACK_WAIT_S = 3;
1435
1435
  var MAX_DEEP_HISTORY_WAIT_S = 30;
1436
1436
  var MAX_RATE_LIMIT_WAIT_S = 120;
1437
1437
  var RATE_LIMIT_FALLBACK_WAIT_S = 60;
1438
- var QUOTA_EXCEEDED_CODE = "quota_exceeded";
1439
- async function isQuotaExceeded(response) {
1438
+ var NON_RETRYABLE_429_CODES = /* @__PURE__ */ new Set(["quota_exceeded", "key_limit_reached"]);
1439
+ async function isAllowanceExhausted(response) {
1440
1440
  try {
1441
1441
  const body = await response.clone().json();
1442
- return body?.error === QUOTA_EXCEEDED_CODE;
1442
+ return typeof body?.error === "string" && NON_RETRYABLE_429_CODES.has(body.error);
1443
1443
  } catch {
1444
1444
  return false;
1445
1445
  }
@@ -1529,7 +1529,7 @@ var SentiSense = class {
1529
1529
  );
1530
1530
  }
1531
1531
  if (!response.ok) {
1532
- if (response.status === 429 && await isQuotaExceeded(response)) {
1532
+ if (response.status === 429 && await isAllowanceExhausted(response)) {
1533
1533
  await this.handleErrorResponse(response);
1534
1534
  }
1535
1535
  const isRetryable = response.status === 429 || response.status >= 500;
@@ -1578,9 +1578,10 @@ var SentiSense = class {
1578
1578
  throw new SentiSenseError("All retries exhausted");
1579
1579
  }
1580
1580
  /** @internal */
1581
- async post(path, body) {
1581
+ async post(path, body, extraHeaders) {
1582
1582
  const url = this.buildUrl(path);
1583
1583
  const headers = {
1584
+ ...extraHeaders,
1584
1585
  "Accept": "application/json",
1585
1586
  "Content-Type": "application/json"
1586
1587
  };