sentisense 0.42.0 → 0.43.0

package/README.md

@@ -56,7 +56,7 @@ Get a key at [app.sentisense.ai/get-api-key](https://app.sentisense.ai/get-api-k
 | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
 | `mood` | Composite market sentiment, the signals behind it, and the sector map |
 | `analysts <ticker>` | Consensus, price target band, recent upgrades and downgrades |
-| `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one |
+| `earnings [ticker]` | Forward calendar with no ticker, per-quarter analysis with one (`earnings AAPL`) |
 | `insiders <ticker>` | Filed Form 4 transactions, including whether they were pre-planned |
 | `insights <ticker>` | Generated signals, filterable by `--urgency` and `--type` |
 | `congress [ticker]` | Congressional disclosures, market-wide or for one symbol |

package/dist/cli.cjs

@@ -70,6 +70,13 @@ var CliUsageError = class extends Error {
     this.hint = hint;
   }
 };
+var UnknownTickerError = class extends Error {
+  constructor(ticker) {
+    super(`unknown ticker "${ticker}".`);
+    this.name = "UnknownTickerError";
+    this.ticker = ticker;
+  }
+};
 var MissingKeyError = class extends Error {
   constructor() {
     super("no API key configured.");
@@ -93,6 +100,15 @@ function classify(error) {
       ]
     };
   }
+  if (error instanceof UnknownTickerError) {
+    return {
+      exitCode: EXIT.NOT_FOUND,
+      lines: [
+        `error: ${error.message}`,
+        "next: check the symbol. Use canonical tickers, for example GOOGL rather than GOOG and BRK.B rather than BRK-B."
+      ]
+    };
+  }
   if (error instanceof CliUsageError) {
     return {
       exitCode: EXIT.USAGE,
@@ -158,6 +174,48 @@ function classify(error) {
   };
 }
 
+// src/cli/ticker.ts
+function rejectSurplus(args, name, allowed) {
+  if (args.positionals.length <= allowed) return;
+  throw new CliUsageError(
+    `${name} takes one ticker, and got ${args.positionals.length}.`,
+    "run it once per ticker. Only quote accepts more than one."
+  );
+}
+function oneTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  const ticker = args.positionals[0];
+  if (!ticker) {
+    throw new CliUsageError(
+      `${name} needs a ticker.`,
+      `for example: sentisense ${name} NVDA`
+    );
+  }
+  return ticker.toUpperCase();
+}
+function optionalTicker(args, name) {
+  rejectSurplus(args, name, 1);
+  return args.positionals[0]?.toUpperCase();
+}
+function rejectPositionals(args, name) {
+  if (args.positionals.length === 0) return;
+  throw new CliUsageError(
+    `${name} takes no ticker, and got ${args.positionals.length}.`,
+    `run "sentisense help ${name}" for what it accepts.`
+  );
+}
+async function verifyTickerOnEmpty(api, ticker) {
+  try {
+    await api.stocks.getQuote(ticker);
+    return void 0;
+  } catch (error) {
+    if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
+    return `could not verify ${ticker}, so the empty result is unconfirmed`;
+  }
+}
+var EMPTY_VERIFY_NOTE = "An empty result verifies the ticker before reporting no data, so a typo exits 4 rather";
+var EMPTY_VERIFY_NOTE_2 = "than looking like a company with nothing to report.";
+
 // src/cli/render/doc.ts
 function cell(text, tone) {
   return tone ? { text, tone } : { text };
@@ -269,13 +327,7 @@ var analystsCommand = {
     days: { type: "number", placeholder: "N", describe: "Days of rating history (default 90)" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "analysts needs a ticker.",
-        "for example: sentisense analysts NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "analysts");
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const api = client();
     const notes = [];
@@ -519,7 +571,9 @@ var congressCommand = {
     "Disclosures are filed after the fact, so the gap between the trade date and the",
     "disclosure date is part of the picture. The delay column carries it in days.",
     "Amounts are the filed ranges, never exact figures: that is how the filings work.",
-    "A free key sees a short preview of either feed."
+    "A free key sees a short preview of either feed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" },
@@ -527,7 +581,8 @@ var congressCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "congress");
+    const notes = [];
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
     let envelope;
@@ -546,6 +601,10 @@ var congressCommand = {
       );
     }
     const trades = envelope.data ?? [];
+    if (ticker && trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? trades : trades.slice(0, 20);
     const blocks = [
       {
@@ -594,7 +653,7 @@ var congressCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -612,14 +671,18 @@ var earningsCommand = {
   examples: [
     "sentisense earnings",
     "sentisense earnings --week next",
-    "sentisense earnings NVDA",
-    "sentisense earnings NVDA --limit 4 --full"
+    "sentisense earnings AAPL",
+    "sentisense earnings AAPL --limit 4 --full"
   ],
   notes: [
     "With no ticker this is the forward calendar: who reports, when, and the consensus EPS.",
     "With a ticker it is the backward-looking analysis: one entry per reported quarter with",
     "the editorial headline, and on a PRO key the written summary and guidance language.",
-    "A free key sees the current week of the calendar and the latest quarter of the analysis."
+    "A free key sees the current week of the calendar and the latest quarter of the analysis.",
+    "Coverage of the per-ticker analysis is not the whole market, so a tracked company can",
+    "have no stored quarter yet.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     week: { type: "string", placeholder: "this|next", describe: "Calendar window shorthand" },
@@ -630,7 +693,8 @@ var earningsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "earnings");
+    const notes = [];
     if (ticker) {
       const limit = typeof args.flags.limit === "number" ? args.flags.limit : void 0;
       const envelope2 = await api.earnings.getSummaries(
@@ -638,6 +702,10 @@ var earningsCommand = {
         limit === void 0 ? void 0 : { limit }
       );
       const quarters = envelope2.data ?? [];
+      if (quarters.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
       const blocks2 = [
         {
           kind: "head",
@@ -699,7 +767,7 @@ var earningsCommand = {
           tone: "dim"
         });
       }
-      return { json: envelope2, doc: doc(...blocks2) };
+      return { json: envelope2, doc: doc(...blocks2), notes };
     }
     const week = typeof args.flags.week === "string" ? args.flags.week : void 0;
     if (week && week !== "this" && week !== "next") {
@@ -791,7 +859,9 @@ var flowsCommand = {
     "market. With a ticker it is that stock's institutional ownership and the quarter's",
     "notable position changes, since flows are only published market-wide.",
     "13F filings land up to 45 days after quarter end, so a still-open quarter shows only",
-    "early filers and says so."
+    "early filers and says so, and a ticker reads the newest quarter that has closed.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     limit: { type: "number", placeholder: "N", describe: `Rows per side (default ${DEFAULT_ROWS})` },
@@ -799,7 +869,8 @@ var flowsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "flows");
+    const notes = [];
     const limit = typeof args.flags.limit === "number" ? args.flags.limit : DEFAULT_ROWS;
     const quarter = typeof args.flags.quarter === "string" ? args.flags.quarter : void 0;
     if (ticker) {
@@ -820,6 +891,10 @@ var flowsCommand = {
       });
       const data2 = envelope2.data;
       const holders = data2?.holders ?? [];
+      if (holders.length === 0) {
+        const note = await verifyTickerOnEmpty(api, ticker);
+        if (note) notes.push(note);
+      }
       const blocks2 = [
         {
           kind: "head",
@@ -878,7 +953,7 @@ var flowsCommand = {
           tone: "dim"
         });
       }
-      return { json: envelope2, doc: doc(...blocks2) };
+      return { json: envelope2, doc: doc(...blocks2), notes };
     }
     const envelope = await api.institutional.getFlows(quarter, { limit });
     const data = envelope.data;
@@ -933,7 +1008,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.42.0";
+var VERSION = "0.43.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -2312,7 +2387,8 @@ var healthCommand = {
     "Exits 3 when the key is missing or rejected, 6 when the host cannot be reached."
   ],
   flags: {},
-  async run({ context }) {
+  async run({ args, context }) {
+    rejectPositionals(args, "health");
     const baseUrl = effectiveBaseUrl(context);
     const anonymous = createClient(context, { anonymous: true });
     const reach = await probe(() => anonymous.stocks.getMarketStatus());
@@ -2382,25 +2458,27 @@ var insidersCommand = {
     "Rows are individual filed transactions, newest first, not a net total.",
     "The plan column says whether the trade was under a confirmed pre-arranged 10b5-1 plan,",
     "which is the difference between a scheduled sale and a discretionary one.",
-    "A free key sees the top few transactions; a PRO key sees the window you asked for."
+    "A free key sees the top few transactions; a PRO key sees the window you asked for.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     days: { type: "number", placeholder: "N", describe: "Look-back window, 1 to 365 (default 90)" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "insiders needs a ticker.",
-        "for example: sentisense insiders NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "insiders");
     const lookbackDays = typeof args.flags.days === "number" ? args.flags.days : void 0;
-    const envelope = await client().insider.getTrades(
+    const api = client();
+    const notes = [];
+    const envelope = await api.insider.getTrades(
       ticker,
       lookbackDays === void 0 ? void 0 : { lookbackDays }
     );
     const trades = envelope.data ?? [];
+    if (trades.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? trades : trades.slice(0, 15);
     const buys = trades.filter((trade) => trade.transactionType === "BUY");
     const sells = trades.filter((trade) => trade.transactionType === "SELL");
@@ -2451,7 +2529,7 @@ var insidersCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -2468,25 +2546,23 @@ var insightsCommand = {
   examples: [
     "sentisense insights NVDA",
     "sentisense insights NVDA --urgency high",
-    "sentisense insights NVDA --type insider_buy_signal --full"
+    "sentisense insights NVDA --type institutional_position_change --full"
   ],
   notes: [
     "Signals are generated observations about filings, flows, and attention, ordered by",
     "urgency then confidence. They describe what the data shows, not what to do about it.",
-    "A free key sees the top three; a PRO key sees the whole list."
+    "A free key sees the top three; a PRO key sees the whole list.",
+    "Signal types vary by ticker and over time, so take --type from what a plain run reports",
+    "rather than guessing a name.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     urgency: { type: "string", placeholder: "level", describe: "Filter to low, medium, or high" },
     type: { type: "string", placeholder: "name", describe: "Filter to one signal type" }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "insights needs a ticker.",
-        "for example: sentisense insights NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "insights");
     const urgency = typeof args.flags.urgency === "string" ? args.flags.urgency : void 0;
     if (urgency && !["low", "medium", "high"].includes(urgency)) {
       throw new CliUsageError(
@@ -2498,11 +2574,17 @@ var insightsCommand = {
       ...urgency ? { urgency } : {},
       ...typeof args.flags.type === "string" ? { insightType: args.flags.type } : {}
     };
-    const envelope = await client().insights.stock(
+    const api = client();
+    const notes = [];
+    const envelope = await api.insights.stock(
       ticker,
       Object.keys(options).length > 0 ? options : void 0
     );
     const insights = envelope.data ?? [];
+    if (insights.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const shown = full ? insights : insights.slice(0, 8);
     const blocks = [
       {
@@ -2555,7 +2637,7 @@ var insightsCommand = {
         tone: "dim"
       });
     }
-    return { json: envelope, doc: doc(...blocks) };
+    return { json: envelope, doc: doc(...blocks), notes };
   }
 };
 
@@ -2584,7 +2666,8 @@ var moodCommand = {
     "46-55 neutral, 56-70 optimism, 71-85 greed, 86-100 extreme greed."
   ],
   flags: {},
-  async run({ client, full }) {
+  async run({ args, client, full }) {
+    rejectPositionals(args, "mood");
     const payload = await client().marketMood.get();
     const market = readMarket(payload);
     const sectors = readSectors(payload);
@@ -2669,7 +2752,9 @@ 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.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2
   ],
   flags: {
     limit: { type: "number", placeholder: "N", describe: `Stories to return (default ${DEFAULT_LIMIT})` },
@@ -2677,10 +2762,15 @@ var newsCommand = {
   },
   async run({ args, client, full }) {
     const api = client();
-    const ticker = args.positionals[0]?.toUpperCase();
+    const ticker = optionalTicker(args, "news");
+    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 } });
+    if (ticker && stories.length === 0) {
+      const note = await verifyTickerOnEmpty(api, ticker);
+      if (note) notes.push(note);
+    }
     const blocks = [
       {
         kind: "head",
@@ -2738,7 +2828,7 @@ var newsCommand = {
         tone: "dim"
       });
     }
-    return { json: stories, doc: doc(...blocks) };
+    return { json: stories, doc: doc(...blocks), notes };
   }
 };
 
@@ -2766,23 +2856,25 @@ var optionsCommand = {
     "End of day, not live: readings describe the latest completed session and refresh the",
     "following morning. Percentiles are against that ticker's own trailing history, so they",
     "compare a stock to its past self, never to another stock.",
-    "Coverage is the most actively optioned names plus the tracked ETFs. A ticker outside",
-    "that set reports no coverage and exits 0, the same as any other empty result.",
+    "Coverage is the most actively optioned names plus the tracked ETFs. A real ticker",
+    "outside that set reports no coverage and exits 0, the same as any other empty result.",
+    EMPTY_VERIFY_NOTE,
+    EMPTY_VERIFY_NOTE_2,
     "A free key gets the full dossier for the first ten calls each month, then a headline",
     "preview. Calls that return no dossier do not count against that."
   ],
   flags: {},
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError("options needs a ticker.", "for example: sentisense options NVDA");
-    }
-    const envelope = await client().stocks.getOptionsSummary(ticker);
+    const ticker = oneTicker(args, "options");
+    const api = client();
+    const envelope = await api.stocks.getOptionsSummary(ticker);
     const data = envelope.data;
     if (!data) {
+      const note = await verifyTickerOnEmpty(api, ticker);
       return {
         json: envelope,
-        doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` })
+        doc: doc({ kind: "text", text: `No options coverage for ${ticker}.` }),
+        notes: note ? [note] : void 0
       };
     }
     const latest = data.latest ?? {};
@@ -3109,6 +3201,7 @@ var screenCommand = {
     etf: { type: "boolean", describe: "Screen the ETF universe" }
   },
   async run({ args, client, full }) {
+    rejectPositionals(args, "screen");
     const api = client();
     const etf = args.flags.etf === true;
     if (args.flags.fields === true) {
@@ -3314,13 +3407,7 @@ var sentimentCommand = {
     days: { type: "number", placeholder: "N", describe: `Days of Score history (default ${DEFAULT_DAYS})` }
   },
   async run({ args, client, full }) {
-    const ticker = args.positionals[0]?.toUpperCase();
-    if (!ticker) {
-      throw new CliUsageError(
-        "sentiment needs a ticker.",
-        "for example: sentisense sentiment NVDA"
-      );
-    }
+    const ticker = oneTicker(args, "sentiment");
     const days = typeof args.flags.days === "number" ? args.flags.days : DEFAULT_DAYS;
     if (days < 1) {
       throw new CliUsageError("--days must be at least 1.", "for example: --days 30");

package/dist/index.cjs

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