sentisense 0.43.0 → 0.45.0

package/README.md

@@ -88,6 +88,25 @@ something supplementary does not come back, such as the Score history behind a s
 command still prints its answer and exits 0 with a `note:` line on stderr, so stdout stays
 clean for a pipe and the gap is never silent.
 
+### Saying who is calling
+
+If you set `SENTISENSE_AGENT_NAME` (what your agent is called) and `SENTISENSE_SKILL` (the
+slug of the skill driving it), requests carry that identity, so usage can be understood and
+the tools improved. Both are optional, never required, and nothing is inferred when they are
+absent.
+
+```bash
+export SENTISENSE_AGENT_NAME=research-desk
+export SENTISENSE_SKILL=stock-analysis
+npx -y sentisense@latest quote NVDA
+# User-Agent: sentisense-node/0.44.0 sentisense-cli/0.44.0 (stock-analysis; agent/research-desk)
+```
+
+Either can also be a flag (`--agent`, `--skill`) or a stored setting
+(`sentisense auth --agent research-desk --skill stock-analysis`), resolved flag first, then
+environment, then config. Values are reduced to letters, digits, dot, underscore and hyphen,
+and capped at 32 characters, so nothing you set can reshape the header.
+
 ### Exit codes
 
 Failures print two lines to stderr, what went wrong and what to do about it, and exit with a

package/dist/cli.cjs

@@ -55,8 +55,8 @@ var EXIT = {
 };
 var EXIT_TABLE = [
   [EXIT.OK, "success"],
-  [EXIT.ERROR, "API error or unexpected failure"],
-  [EXIT.USAGE, "bad usage: unknown command, flag, or missing argument"],
+  [EXIT.ERROR, "API error, including a request the API rejected as invalid"],
+  [EXIT.USAGE, "bad usage, caught before any request was sent"],
   [EXIT.AUTH, "missing or rejected API key"],
   [EXIT.NOT_FOUND, "no data for that symbol or identifier"],
   [EXIT.RATE_LIMIT, "rate limited"],
@@ -83,14 +83,14 @@ var MissingKeyError = class extends Error {
     this.name = "MissingKeyError";
   }
 };
-function describeError(error, debug) {
-  const report = classify(error);
+function describeError(error, debug, command) {
+  const report = classify(error, command);
   if (debug && error instanceof Error && error.stack) {
     report.lines.push(error.stack);
   }
   return report;
 }
-function classify(error) {
+function classify(error, command) {
   if (error instanceof MissingKeyError) {
     return {
       exitCode: EXIT.AUTH,
@@ -156,6 +156,16 @@ function classify(error) {
         ]
       };
     }
+    if (error.status !== void 0 && error.status >= 400 && error.status < 500) {
+      const help = command ? `sentisense help ${command}` : "sentisense --help";
+      return {
+        exitCode: EXIT.ERROR,
+        lines: [
+          `error: the API rejected the request (${error.status}): ${error.message}`,
+          `next: check the flags and values you passed. Run "${help}" for the accepted fields and examples.`
+        ]
+      };
+    }
     return {
       exitCode: EXIT.ERROR,
       lines: [
@@ -268,6 +278,16 @@ function signedPercent(value, decimals = 2) {
 function percent(value, decimals = 1) {
   return isNum(value) ? `${value.toFixed(decimals)}%` : ABSENT;
 }
+var MAX_RATIO_DECIMALS = 6;
+function ratioPercent(value, decimals = 2) {
+  if (!isNum(value)) return ABSENT;
+  const scaled = value * 100;
+  let places = decimals;
+  while (scaled !== 0 && places < MAX_RATIO_DECIMALS && Number(scaled.toFixed(places)) === 0) {
+    places += 1;
+  }
+  return `${scaled.toFixed(places)}%`;
+}
 function money(value, decimals = 2) {
   return isNum(value) ? `$${value.toFixed(decimals)}` : ABSENT;
 }
@@ -435,6 +455,7 @@ function readConfig(dir) {
     const config = {};
     if (typeof raw.apiKey === "string") config.apiKey = raw.apiKey;
     if (typeof raw.agentName === "string") config.agentName = raw.agentName;
+    if (typeof raw.skill === "string") config.skill = raw.skill;
     if (typeof raw.baseUrl === "string") config.baseUrl = raw.baseUrl;
     return config;
   } catch {
@@ -464,10 +485,11 @@ function maskKey(key) {
 var authCommand = {
   name: "auth",
   summary: "Store an API key, show what is configured, or remove it",
-  usage: "sentisense auth [<key>] [--agent <name>] [--remove]",
+  usage: "sentisense auth [<key>] [--agent <name>] [--skill <slug>] [--remove]",
   examples: [
     "sentisense auth $SENTISENSE_API_KEY",
     "sentisense auth --agent research-desk",
+    "sentisense auth --skill stock-analysis --agent research-desk",
     "sentisense auth",
     "sentisense auth --remove"
   ],
@@ -475,8 +497,10 @@ var authCommand = {
     "Settings live in config.json under $SENTISENSE_CONFIG_DIR, $XDG_CONFIG_HOME/sentisense,",
     "or ~/.config/sentisense, written owner-readable only (0600).",
     "The key is never printed back in full, and never has to be pasted into a command again.",
-    "An agent name is optional. When set, it rides along in the User-Agent so your own",
-    "traffic is easy to tell apart from everything else calling the API."
+    "Two optional labels say who is calling: --agent is what your agent calls itself, and",
+    "--skill is the slug of the skill driving it. When set, they ride along in the",
+    "User-Agent, so usage can be understood and the tools improved. Both are voluntary and",
+    "nothing needs them to work."
   ],
   flags: {
     remove: { type: "boolean", describe: "Delete the stored settings" }
@@ -495,13 +519,15 @@ var authCommand = {
     }
     const key = args.positionals[0];
     const agent = typeof args.flags.agent === "string" ? args.flags.agent : void 0;
+    const skill = typeof args.flags.skill === "string" ? args.flags.skill : void 0;
     const baseUrl = typeof args.flags["base-url"] === "string" ? args.flags["base-url"] : void 0;
-    if (key || agent || baseUrl) {
+    if (key || agent || skill || baseUrl) {
       const stored2 = readConfig(dir);
       const next = {
         ...stored2,
         ...key ? { apiKey: key } : {},
         ...agent ? { agentName: agent } : {},
+        ...skill ? { skill } : {},
         ...baseUrl ? { baseUrl } : {}
       };
       writeConfig(dir, next);
@@ -510,6 +536,7 @@ var authCommand = {
           path,
           apiKey: next.apiKey ? maskKey(next.apiKey) : null,
           agentName: next.agentName ?? null,
+          skill: next.skill ?? null,
           baseUrl: next.baseUrl ?? null
         },
         doc: doc(
@@ -519,6 +546,7 @@ var authCommand = {
             items: fields(
               next.apiKey ? field("api key", maskKey(next.apiKey)) : void 0,
               next.agentName ? field("agent", next.agentName) : void 0,
+              next.skill ? field("skill", next.skill) : void 0,
               next.baseUrl ? field("base url", next.baseUrl) : void 0
             )
           }
@@ -534,6 +562,7 @@ var authCommand = {
         apiKey: resolved ? maskKey(resolved) : null,
         apiKeySource: context.apiKeySource,
         agentName: context.agentName ?? null,
+        skill: context.skill ?? null,
         baseUrl: context.baseUrl ?? null
       },
       doc: doc(
@@ -544,6 +573,7 @@ var authCommand = {
             field("source", resolved ? context.apiKeySource : "none"),
             field("config", path),
             context.agentName ? field("agent", context.agentName) : void 0,
+            context.skill ? field("skill", context.skill) : void 0,
             context.baseUrl ? field("base url", context.baseUrl) : void 0
           )
         },
@@ -1008,7 +1038,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.43.0";
+var VERSION = "0.45.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2190,7 +2220,12 @@ var GLOBAL_FLAGS = {
   agent: {
     type: "string",
     placeholder: "name",
-    describe: "Label this call in the User-Agent"
+    describe: "Name your agent in the User-Agent, if you want to"
+  },
+  skill: {
+    type: "string",
+    placeholder: "slug",
+    describe: "Name the skill driving this call, if you want to"
   }
 };
 var SHORT_FLAGS = {
@@ -2325,6 +2360,7 @@ function resolveContext({ flags, env, configDir }) {
   const key = pick(flagString(flags, "api-key"), env.SENTISENSE_API_KEY, stored.apiKey);
   const base = pick(flagString(flags, "base-url"), env.SENTISENSE_BASE_URL, stored.baseUrl);
   const agent = pick(flagString(flags, "agent"), env.SENTISENSE_AGENT_NAME, stored.agentName);
+  const skill = pick(flagString(flags, "skill"), env.SENTISENSE_SKILL, stored.skill);
   return {
     configDir: dir,
     apiKey: key.value,
@@ -2332,21 +2368,27 @@ function resolveContext({ flags, env, configDir }) {
     baseUrl: base.value,
     baseUrlSource: base.source,
     agentName: agent.value,
-    agentSource: agent.source
+    agentSource: agent.source,
+    skill: skill.value,
+    skillSource: skill.source
   };
 }
 var DEFAULT_BASE_URL2 = "https://app.sentisense.ai";
 function effectiveBaseUrl(context) {
   return context.baseUrl ?? DEFAULT_BASE_URL2;
 }
-function sanitizeAgent(name) {
-  return name.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "");
+var MAX_IDENTITY = 32;
+function sanitizeIdentity(value) {
+  return value.trim().replace(/\s+/g, "-").replace(/[^A-Za-z0-9._-]/g, "").replace(/-{2,}/g, "-").slice(0, MAX_IDENTITY).replace(/^-+|-+$/g, "");
 }
 function userAgentSuffix(context) {
-  const parts = [`sentisense-cli/${VERSION}`];
-  const agent = context.agentName ? sanitizeAgent(context.agentName) : "";
-  if (agent) parts.push(`agent/${agent}`);
-  return parts.join(" ");
+  const product = `sentisense-cli/${VERSION}`;
+  const slug = sanitizeIdentity(context.skill ?? "");
+  const agent = sanitizeIdentity(context.agentName ?? "");
+  const comment = [];
+  if (slug) comment.push(slug);
+  if (agent) comment.push(`agent/${agent}`);
+  return comment.length === 0 ? product : `${product} (${comment.join("; ")})`;
 }
 function createClient(context, options = {}) {
   if (!options.anonymous && !context.apiKey) throw new MissingKeyError();
@@ -2752,13 +2794,20 @@ var newsCommand = {
     "A story is a cluster of articles covering the same event, not a single headline, so",
     "the size column is how many sources picked it up and impact ranks how much it moved.",
     "Tone is the average sentiment across the cluster, between -1 and 1.",
-    "--days only applies to the market-wide feed.",
+    "--days only applies to the market-wide feed, and counts from when a story STARTED",
+    "breaking, not from its latest article. A running story with fresh coverage but an",
+    "older start falls out of short windows, so an empty window can be correct. It also",
+    "switches ordering to curation score instead of the day-bucketed default.",
     EMPTY_VERIFY_NOTE,
     EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     limit: { type: "number", placeholder: "N", describe: `Stories to return (default ${DEFAULT_LIMIT})` },
-    days: { type: "number", placeholder: "N", describe: "Look-back window, market-wide feed only" }
+    days: {
+      type: "number",
+      placeholder: "N",
+      describe: "Look-back window in days, market-wide feed only"
+    }
   },
   async run({ args, client, full }) {
     const api = client();
@@ -2766,7 +2815,10 @@ var newsCommand = {
     const notes = [];
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_LIMIT;
     const days = typeof args.flags.days === "number" ? args.flags.days : void 0;
-    const stories = ticker ? await api.documents.getStoriesByTicker(ticker, { limit }) : await api.documents.getStories({ limit, ...days === void 0 ? {} : { days } });
+    const stories = ticker ? await api.documents.getStoriesByTicker(ticker, { limit }) : await api.documents.getStories({
+      limit,
+      ...days === void 0 ? {} : { filterHours: days * 24 }
+    });
     if (ticker && stories.length === 0) {
       const note = await verifyTickerOnEmpty(api, ticker);
       if (note) notes.push(note);
@@ -3000,7 +3052,8 @@ function single(row, full) {
         field("Mkt cap", humanize(quote.marketCap)),
         field("P/E", fixed(quote.peRatio)),
         field("EPS TTM", fixed(quote.epsTTM)),
-        field("Div yield", percent(quote.dividendYield, 2)),
+        // A ratio, unlike `changePercent` and the other percentages in the same payload.
+        field("Div yield", ratioPercent(quote.dividendYield)),
         field(
           "52w",
           `${fixed(quote.week52Low)} to ${fixed(quote.week52High)}`
@@ -3604,6 +3657,12 @@ function mainHelp() {
     "",
     'Run "sentisense help <command>" for flags, examples, and exit codes.',
     "",
+    "Saying who is calling (optional):",
+    "  SENTISENSE_AGENT_NAME=<name>   what your agent calls itself",
+    "  SENTISENSE_SKILL=<slug>        the skill driving it",
+    "  Set either and requests carry that identity, so usage can be understood and the",
+    "  tools improved. Nothing needs them, and nothing is inferred when they are absent.",
+    "",
     "Research data, not investment advice."
   ];
   return `${lines.join("\n")}
@@ -3872,7 +3931,7 @@ async function runCli(argv, io) {
     return result.exitCode ?? EXIT.OK;
   } catch (error) {
     const debug = argv.includes("--debug");
-    const report = describeError(error, debug);
+    const report = describeError(error, debug, name);
     for (const line of report.lines) io.stderr(`${line}
 `);
     return report.exitCode;

package/dist/index.cjs

@@ -1036,7 +1036,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.43.0";
+var VERSION = "0.45.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";