sentisense 0.61.0 → 0.62.0

package/README.md

@@ -68,7 +68,7 @@ npx -y sentisense@latest health
 |---------|--------------|
 | `auth [key]` | Store a key, show what is configured, or `--remove` it |
 | `health` | Reachability, key validity, latency, and the resolved base URL |
-| `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker |
+| `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker; ETFs show AUM, expense ratio and NAV |
 | `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. `--coverage` for who covers it, by firm |
@@ -238,7 +238,10 @@ client.stocks.getProfile("AAPL")                        // Company profile
 client.stocks.getChart("AAPL", { timeframe: "6M" })     // OHLCV chart data
 client.stocks.getMarketStatus()                         // Market open/closed
 client.stocks.getFundamentals("AAPL")                   // Financial data
-client.stocks.getShortInterest("GME")                   // Short interest
+client.stocks.getShortInterest("GME", { limit: 12 })    // Short interest by settlement date
+client.stocks.getShortVolume("GME")                     // Daily short volume
+client.stocks.getFloat("GME")                           // Free float
+client.stocks.getGraph("AAPL", { depth: 1 })            // Company knowledge graph: people, products, peers
 client.stocks.getOptionsSummary("NVDA")                 // End-of-day options dossier
 client.stocks.getOptionsHistory("NVDA", { window: "2y" })  // Daily options aggregates over time
 client.stocks.getRating("AAPL")                         // SentiSense Rating: score, letter, percentile, dimensions
@@ -247,6 +250,8 @@ client.stocks.getAISummary("AAPL", { depth: "deep" })   // AI report (PRO)
 
 Price fields carry `priceAsOf` (Unix milliseconds) for the age of the market data; read that for freshness rather than `timestamp`, which is when the response was served.
 
+Short interest and short volume come back newest first, and an unknown ticker returns an empty `dataPoints` array rather than an error. Every identifier in `getGraph` is a slug, the same handle the metric and document endpoints take. An ETF symbol is refused by `getQuote` with an `APIError` whose `code` is `"ticker_is_etf"`; use `etfs.quote()` for funds.
+
 ### Documents & news
 
 ```typescript
@@ -459,6 +464,7 @@ Composition data is public; the holdings-weighted aggregate views follow the sam
 
 ```typescript
 client.etfs.list()                                              // Every ETF tracked
+client.etfs.quote("SPY")                                        // Price, ranges, AUM, expense ratio, NAV
 client.etfs.holdings("QQQ")                                     // Full composition + freshness metadata
 client.etfs.analystAggregate("QQQ")                             // Holdings-weighted analyst consensus
 client.etfs.insiderAggregate("ARKK", { lookbackDays: 90 })      // Holdings-weighted Form 4 net flow

package/dist/cli.cjs

@@ -502,10 +502,22 @@ async function verifyTickerOnEmpty(api, ticker) {
     await api.stocks.getQuote(ticker);
     return void 0;
   } catch (error) {
+    if (isEtfRedirect(error)) return void 0;
     if (error instanceof NotFoundError) throw new UnknownTickerError(ticker);
     return `could not verify ${ticker}, so the empty result is unconfirmed`;
   }
 }
+function isEtfRedirect(error) {
+  return error instanceof APIError && error.code === "ticker_is_etf";
+}
+async function quoteAnyTicker(api, ticker) {
+  try {
+    return { kind: "stock", quote: await api.stocks.getQuote(ticker) };
+  } catch (error) {
+    if (!isEtfRedirect(error)) throw error;
+    return { kind: "etf", quote: await api.etfs.quote(ticker) };
+  }
+}
 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.";
 
@@ -518,11 +530,13 @@ function actionTone(actionType) {
   return void 0;
 }
 function primaryAnalyst(row) {
-  const named = row.latestNote?.analyst;
-  const match = (named ? row.analysts.find((analyst) => analyst.name === named) : void 0) ?? row.analysts[0];
-  const name = match?.name ?? named ?? "";
+  const named = row.latestNote?.analyst ?? null;
+  const match = (named ? row.analysts.find(
+    (analyst) => named.slug !== null && analyst.slug === named.slug || analyst.name === named.name
+  ) : void 0) ?? row.analysts[0];
+  const name = match?.name ?? named?.name ?? "";
   const extra = row.analysts.length > 1 ? ` +${row.analysts.length - 1}` : "";
-  return { name: name ? `${name}${extra}` : "", slug: match?.slug ?? "" };
+  return { name: name ? `${name}${extra}` : "", slug: match?.slug ?? named?.slug ?? "" };
 }
 var analystsCommand = {
   name: "analysts",
@@ -1331,7 +1345,7 @@ var flowsCommand = {
 };
 
 // src/version.ts
-var VERSION = "0.61.0";
+var VERSION = "0.62.0";
 
 // src/resources/analyst.ts
 var Analyst = class {
@@ -1726,6 +1740,19 @@ var Etfs = class {
   async list() {
     return this.client.get("/api/v1/etfs");
   }
+  /**
+   * Get the quote snapshot for an ETF: price, day and 52-week range, volume, dividend
+   * yield, AUM, expense ratio, NAV and inception date.
+   *
+   * Fails with a 400 `APIError` whose `code` is `"ticker_is_not_etf"` when the symbol is a
+   * stock (use `stocks.getQuote()` for those), and a `NotFoundError` when there is no
+   * price data for the fund.
+   */
+  async quote(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/quote`
+    );
+  }
   /**
    * Get the full holdings composition for an ETF, including per-holding weights
    * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
@@ -2320,6 +2347,21 @@ var Stocks = class {
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
   }
+  /**
+   * Get the company knowledge graph around a stock: the people, products, peers and other
+   * entities linked to the company, and the typed relationships between them.
+   *
+   * Every identifier in the response is a slug, the same handle the metric and document
+   * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
+   * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
+   * with a 400. A ticker with no graph returns a `NotFoundError`.
+   */
+  async getGraph(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/graph`,
+      options
+    );
+  }
   /**
    * Get AI-generated stock analysis report. Requires PRO tier.
    *
@@ -2382,17 +2424,23 @@ var Stocks = class {
   async getHistoricalRevenue(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/historical/revenue", { ticker });
   }
-  /** Get short interest metrics (FINRA). */
-  async getShortInterest(ticker) {
-    return this.client.get("/api/v1/stocks/short-interest", { ticker });
+  /**
+   * Get short interest history (FINRA), newest first: shares short, days to cover and
+   * average daily volume per settlement date. `limit` defaults to 24 settlement dates.
+   */
+  async getShortInterest(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-interest", { ticker, ...options });
   }
   /** Get float information. */
   async getFloat(ticker) {
     return this.client.get("/api/v1/stocks/float", { ticker });
   }
-  /** Get short volume trading data. */
-  async getShortVolume(ticker) {
-    return this.client.get("/api/v1/stocks/short-volume", { ticker });
+  /**
+   * Get daily short volume, newest first: shares sold short against total volume on the
+   * reporting venues. `limit` defaults to 90 trading days.
+   */
+  async getShortVolume(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-volume", { ticker, ...options });
   }
   /**
    * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
@@ -3641,6 +3689,37 @@ var optionsCommand = {
 };
 
 // src/cli/commands/quote.ts
+function valuation(row) {
+  if (row.kind === "etf") {
+    const etf = row.quote;
+    return {
+      kind: "facts",
+      items: fields(
+        field("AUM", humanize(etf.aum)),
+        // Both ratios, like `dividendYield` on the stock quote.
+        field("Expense ratio", ratioPercent(etf.expenseRatio)),
+        field("NAV", fixed(etf.nav)),
+        field("Div yield", ratioPercent(etf.dividendYield)),
+        field("52w", `${fixed(etf.week52Low)} to ${fixed(etf.week52High)}`)
+      )
+    };
+  }
+  const quote = row.quote;
+  return {
+    kind: "facts",
+    items: fields(
+      field("Mkt cap", humanize(quote.marketCap)),
+      field("P/E", fixed(quote.peRatio)),
+      field("EPS TTM", fixed(quote.epsTTM)),
+      // 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)}`
+      )
+    )
+  };
+}
 function single(row, full) {
   const { quote, profile } = row;
   const tone = direction(quote.changePercent);
@@ -3668,20 +3747,7 @@ function single(row, full) {
         field("Prev close", fixed(quote.previousClose))
       )
     },
-    {
-      kind: "facts",
-      items: fields(
-        field("Mkt cap", humanize(quote.marketCap)),
-        field("P/E", fixed(quote.peRatio)),
-        field("EPS TTM", fixed(quote.epsTTM)),
-        // 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)}`
-        )
-      )
-    }
+    valuation(row)
   ];
   if (quote.extendedHours) {
     const ext = quote.extendedHours;
@@ -3700,25 +3766,33 @@ function single(row, full) {
       )
     });
   }
-  if (full) {
+  if (full && row.kind === "etf") {
+    blocks.push({
+      kind: "kv",
+      items: fields(
+        row.quote.inceptionDate ? field("inception", row.quote.inceptionDate) : void 0
+      )
+    });
+  } else if (full && row.kind === "stock") {
     blocks.push({
       kind: "kv",
       items: fields(
-        field("200d average", fixed(quote.movingAverage200Day)),
-        quote.reportedCurrency ? field("reported currency", quote.reportedCurrency) : void 0,
+        field("200d average", fixed(row.quote.movingAverage200Day)),
+        row.quote.reportedCurrency ? field("reported currency", row.quote.reportedCurrency) : void 0,
         profile?.sector ? field("sector", String(profile.sector)) : void 0,
         profile?.industry ? field("industry", String(profile.industry)) : void 0,
         profile?.ceo ? field("ceo", String(profile.ceo)) : void 0
       )
     });
   }
-  if (quote.listingStatus === "DELISTED") {
+  const listingStatus = row.kind === "stock" ? row.quote.listingStatus : void 0;
+  if (row.kind === "stock" && listingStatus === "DELISTED") {
     blocks.push({
       kind: "text",
-      text: `Delisted on ${quote.delistedDate ?? "an unrecorded date"}. Every figure above is frozen at the last trade, not a live market move.`,
+      text: `Delisted on ${row.quote.delistedDate ?? "an unrecorded date"}. Every figure above is frozen at the last trade, not a live market move.`,
       tone: "down"
     });
-  } else if (quote.listingStatus === "PENDING_DELISTING") {
+  } else if (listingStatus === "PENDING_DELISTING") {
     blocks.push({
       kind: "text",
       text: "A merger or take-private is scheduled. The stock still trades, so these figures are current.",
@@ -3745,7 +3819,8 @@ function table(rows, full) {
         cell(signed(row.quote.change), tone),
         cell(signedPercent(row.quote.changePercent), tone),
         cell(humanize(row.quote.volume, 1)),
-        cell(humanize(row.quote.marketCap))
+        // An ETF has no market cap; its AUM is a different number and stays out of this column.
+        cell(humanize(row.kind === "stock" ? row.quote.marketCap : void 0))
       ];
       return full ? [cell(row.ticker), cell(row.profile?.name ?? ""), ...tail] : [cell(row.ticker), ...tail];
     })
@@ -3767,7 +3842,9 @@ var quoteCommand = {
     "Use canonical symbols, for example GOOGL rather than GOOG and BRK.B rather than BRK-B.",
     "One request per ticker. The company name costs a second request, so it is fetched only",
     "for the terminal layout: piped and --json output carry the quote alone.",
-    "JSON is the exact quote response for one ticker, and an object keyed by ticker for more."
+    "JSON is the exact quote response for one ticker, and an object keyed by ticker for more.",
+    "An ETF symbol answers with the ETF quote: AUM, expense ratio and NAV in place of market",
+    "cap, P/E and EPS. That costs one extra request per ETF symbol."
   ],
   flags: {},
   async run({ args, client, full, mode }) {
@@ -3779,12 +3856,12 @@ var quoteCommand = {
     const wantName = mode === "pretty";
     const rows = await Promise.all(
       tickers.map(async (ticker) => {
-        const [quote, profile] = await Promise.all([
-          api.stocks.getQuote(ticker),
+        const [answer, profile] = await Promise.all([
+          quoteAnyTicker(api, ticker),
           // A name is a nicety, not the answer. A ticker with no profile still gets a quote.
           wantName ? api.stocks.getProfile(ticker).catch(() => null) : Promise.resolve(null)
         ]);
-        return { ticker, quote, profile };
+        return { ...answer, ticker, profile };
       })
     );
     if (rows.length === 1) {

package/dist/index.cjs

@@ -475,6 +475,19 @@ var Etfs = class {
   async list() {
     return this.client.get("/api/v1/etfs");
   }
+  /**
+   * Get the quote snapshot for an ETF: price, day and 52-week range, volume, dividend
+   * yield, AUM, expense ratio, NAV and inception date.
+   *
+   * Fails with a 400 `APIError` whose `code` is `"ticker_is_not_etf"` when the symbol is a
+   * stock (use `stocks.getQuote()` for those), and a `NotFoundError` when there is no
+   * price data for the fund.
+   */
+  async quote(ticker) {
+    return this.client.get(
+      `/api/v1/etfs/${encodeURIComponent(ticker.toUpperCase())}/quote`
+    );
+  }
   /**
    * Get the full holdings composition for an ETF, including per-holding weights
    * and freshness metadata. Returns 404 for unknown ETFs or commodity-only funds.
@@ -1069,6 +1082,21 @@ var Stocks = class {
   async getEntities(ticker) {
     return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/entities`);
   }
+  /**
+   * Get the company knowledge graph around a stock: the people, products, peers and other
+   * entities linked to the company, and the typed relationships between them.
+   *
+   * Every identifier in the response is a slug, the same handle the metric and document
+   * endpoints take, so a node can be passed straight to them. `depth` is 1 (default) or 2,
+   * `cap` limits the node count (1 to 200, default 75); out-of-range values are rejected
+   * with a 400. A ticker with no graph returns a `NotFoundError`.
+   */
+  async getGraph(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/graph`,
+      options
+    );
+  }
   /**
    * Get AI-generated stock analysis report. Requires PRO tier.
    *
@@ -1131,17 +1159,23 @@ var Stocks = class {
   async getHistoricalRevenue(ticker) {
     return this.client.get("/api/v1/stocks/fundamentals/historical/revenue", { ticker });
   }
-  /** Get short interest metrics (FINRA). */
-  async getShortInterest(ticker) {
-    return this.client.get("/api/v1/stocks/short-interest", { ticker });
+  /**
+   * Get short interest history (FINRA), newest first: shares short, days to cover and
+   * average daily volume per settlement date. `limit` defaults to 24 settlement dates.
+   */
+  async getShortInterest(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-interest", { ticker, ...options });
   }
   /** Get float information. */
   async getFloat(ticker) {
     return this.client.get("/api/v1/stocks/float", { ticker });
   }
-  /** Get short volume trading data. */
-  async getShortVolume(ticker) {
-    return this.client.get("/api/v1/stocks/short-volume", { ticker });
+  /**
+   * Get daily short volume, newest first: shares sold short against total volume on the
+   * reporting venues. `limit` defaults to 90 trading days.
+   */
+  async getShortVolume(ticker, options) {
+    return this.client.get("/api/v1/stocks/short-volume", { ticker, ...options });
   }
   /**
    * Get company-specific KPI time-series for a ticker. Returns curated GAAP and
@@ -1353,7 +1387,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.61.0";
+var VERSION = "0.62.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";