sentisense 0.74.0 → 0.76.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,7 +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
+ | `init` | A temporary key with no signup, printed as `SENTISENSE_API_KEY=...`, plus a command to try it and a link to keep it |
71
71
  | `health` | Reachability, key validity, latency, and the resolved base URL |
72
72
  | `quote <ticker>...` | Price, day range, 52-week range, market cap, P/E. One request per ticker; ETFs show AUM, expense ratio and NAV |
73
73
  | `sentiment <ticker>` | SentiSense Score, tone, attention, per-source breakdown, `--days N` history |
@@ -92,10 +92,18 @@ Run `sentisense help <command>` for its flags and examples.
92
92
  `init` is built for coding agents: it asks nothing and writes nothing into your project.
93
93
 
94
94
  ```bash
95
- npx -y sentisense@latest init # prints SENTISENSE_API_KEY=<key> and a keep link
95
+ npx -y sentisense@latest init # prints SENTISENSE_API_KEY=<key>, a command to try, and a keep link
96
96
  npx -y sentisense@latest init --json # the same, as JSON
97
97
  ```
98
98
 
99
+ Right after the key, `init` prints one command to run next:
100
+
101
+ ```bash
102
+ npx sentisense sentiment TSLA --api-key <key>
103
+ ```
104
+
105
+ Tesla is a sample company, so the temporary key gets its full sentiment reading. `--api-key` applies to that one call, so it works before the key is stored anywhere. With `--json`, the same line is in `starterCommand`.
106
+
99
107
  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.
100
108
 
101
109
  Three of these chain into each other. Start from a name, land on a person:
@@ -255,6 +263,7 @@ client.stocks.getShortInterest("GME", { limit: 12 }) // Short interest by set
255
263
  client.stocks.getShortVolume("GME") // Daily short volume
256
264
  client.stocks.getFloat("GME") // Free float
257
265
  client.stocks.getGraph("AAPL", { depth: 1 }) // Company knowledge graph: people, products, peers
266
+ client.stocks.getEtfs("NVDA", { limit: 5 }) // ETFs that hold the stock, heaviest weight first
258
267
  client.stocks.getOptionsSummary("NVDA") // End-of-day options dossier
259
268
  client.stocks.getOptionsHistory("NVDA", { window: "2y" }) // Daily options aggregates over time
260
269
  client.stocks.getOptionsIntradayHistory("NVDA") // One session's intraday options series (PRO)
@@ -264,6 +273,8 @@ client.stocks.getAISummary("AAPL", { depth: "deep" }) // AI report (PRO)
264
273
 
265
274
  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.
266
275
 
276
+ `stocks.getEtfs` resolves to a bare array (no preview envelope) on every tier. Each row has `etfTicker`, `etfName`, `weightPct` (the stock's weight in the fund as a percentage from 0 to 100, combined across share classes for a company with several) and `asOfDate` (that fund's own holdings date, so it can differ between rows; may be absent). It searches only the funds SentiSense tracks with a holdings file, some of which are partial, so it is not every fund in the market. A ticker no tracked fund holds resolves to `[]`. See the [API reference](https://sentisense.ai/docs/api/stocks/#get-stock-etfs).
277
+
267
278
  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.
268
279
 
269
280
  Product nodes (`type === "PRODUCT_OR_SERVICE"`) in `stocks.getGraph` now carry optional `category` when known. Other nodes and products without a category omit it.
@@ -675,6 +686,24 @@ const symbol = hits.find((hit) => hit.ticker)?.ticker; // "TSLA"
675
686
 
676
687
  An empty array is the normal answer for a query that matches nothing, so branch on `length` rather than catching.
677
688
 
689
+ ### Trackers
690
+
691
+ Every tracker returns the same snapshot envelope, so one renderer per `viewType` covers them all. `trackers.list()` says which trackers exist and, on those that have them, the `filters` each accepts (`{ key, values }`, with `values` the complete list).
692
+
693
+ ```typescript
694
+ const { trackers } = await client.trackers.list();
695
+ const heatmap = await client.trackers.get("market-heatmap", { scope: "nasdaq100" });
696
+
697
+ // Narrow a tracker that lists filters, as an object or the wire string "state:TX".
698
+ const tx = await client.trackers.get("data-center-moratoriums", { filter: { state: "TX" } });
699
+ console.log(tx.totalCount, "Texas records");
700
+ for (const row of tx.data.rows ?? []) {
701
+ console.log(row.rowId, row.name, row.ticker, row.endsDate, row.statesNamed);
702
+ }
703
+ ```
704
+
705
+ Rows carry `ticker`, `url`, `endsDate` (ISO date) and `statesNamed` when a row has them, and absent otherwise. Other named cells, such as the `market-heatmap` columns, are on the row too (`row.marketCap`, typed `unknown`). Combine filters with commas: `{ state: "TX", category: "local" }` sends `filter=state:TX,category:local`. An unknown filter key or value throws `APIError` with `status: 400` and `code: "invalid_filter"`, the same way a bad `scope` throws `code: "invalid_scope"`, so a call never comes back unfiltered by accident.
706
+
678
707
  ### Screener
679
708
 
680
709
  Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals, price and end-of-day options readings in one query. Screening on analyst ratings alone is something a dozen free tools do; screening on analyst ratings *where the Score disagrees* is not.
package/dist/cli.cjs CHANGED
@@ -1432,7 +1432,7 @@ var flowsCommand = {
1432
1432
  };
1433
1433
 
1434
1434
  // src/version.ts
1435
- var VERSION = "0.74.0";
1435
+ var VERSION = "0.76.0";
1436
1436
 
1437
1437
  // src/resources/analyst.ts
1438
1438
  var Analyst = class {
@@ -2529,6 +2529,19 @@ var Stocks = class {
2529
2529
  async getSimilar(ticker, options) {
2530
2530
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/similar`, options);
2531
2531
  }
2532
+ /**
2533
+ * List the ETFs that hold a stock, heaviest weight first.
2534
+ *
2535
+ * Resolves to a bare array (no preview envelope) on every tier, sorted by `weightPct`
2536
+ * descending, then `etfTicker` ascending. A ticker no tracked fund holds, or an unknown
2537
+ * ticker, resolves to `[]` rather than throwing. Only funds SentiSense tracks with a
2538
+ * holdings file are searched, and some funds' holdings are partial, so the list is not
2539
+ * every fund in the market. `ticker` is case-insensitive. Counts against the monthly
2540
+ * quota like other data endpoints.
2541
+ */
2542
+ async getEtfs(ticker, options) {
2543
+ return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/etfs`, options);
2544
+ }
2532
2545
  /** Get company profile (CEO, sector, industry, market data). */
2533
2546
  async getProfile(ticker, options) {
2534
2547
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/profile`, options);
@@ -2879,13 +2892,27 @@ var Trackers = class {
2879
2892
  * in your renderer.
2880
2893
  *
2881
2894
  * @param trackerId slug from {@link list}, e.g. `"institution-concentration"`.
2882
- * @param params provider-specific query params (e.g. `{ scope: "us" }` for
2883
- * geographically-scoped trackers like hantavirus). Unknown keys are ignored.
2895
+ * @param params provider-specific query params, e.g. `{ scope: "nasdaq100" }` for
2896
+ * `market-heatmap`, or `{ filter: { state: "TX" } }` for a tracker that lists
2897
+ * `filters`. A bad `filter` throws `APIError` with `code: "invalid_filter"`.
2884
2898
  */
2885
2899
  async get(trackerId, params) {
2886
- return this.client.get(`/api/v1/trackers/${trackerId}`, params);
2900
+ return this.client.get(`/api/v1/trackers/${trackerId}`, serializeTrackerParams(params));
2887
2901
  }
2888
2902
  };
2903
+ function serializeTrackerFilter(filter) {
2904
+ if (typeof filter === "string") return filter;
2905
+ return Object.entries(filter).map(([key, value]) => `${key}:${value}`).join(",");
2906
+ }
2907
+ function serializeTrackerParams(params) {
2908
+ if (!params) return void 0;
2909
+ const out = {};
2910
+ for (const [key, value] of Object.entries(params)) {
2911
+ if (value === void 0 || value === null) continue;
2912
+ out[key] = key === "filter" ? serializeTrackerFilter(value) : value;
2913
+ }
2914
+ return out;
2915
+ }
2889
2916
 
2890
2917
  // src/client.ts
2891
2918
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -3422,6 +3449,10 @@ var PROVISION_PATH = "/api/v1/keys/provision";
3422
3449
  var CLIENT_ID_HEADER = "X-SentiSense-Client-Id";
3423
3450
  var LLMS_URL = "https://sentisense.ai/llms.txt";
3424
3451
  var SKILL_URL = "https://sentisense.ai/skill.md";
3452
+ var STARTER_ARGS = "sentiment TSLA";
3453
+ function starterCommand(apiKey) {
3454
+ return `npx sentisense ${STARTER_ARGS} --api-key ${apiKey}`;
3455
+ }
3425
3456
  var SOURCE_TEXT = {
3426
3457
  config: 'your own key saved with "sentisense auth"',
3427
3458
  flag: "the key passed with --api-key",
@@ -3493,6 +3524,7 @@ var initCommand = {
3493
3524
  "it prints SENTISENSE_API_KEY=<key> and a keep link. Store the key the way the project",
3494
3525
  "already stores secrets (an environment variable, a .env file kept out of git, a secret",
3495
3526
  "manager). The SDK and every sentisense command read SENTISENSE_API_KEY from the environment.",
3527
+ "After the key it prints one command to try next (Tesla's sentiment, a sample company).",
3496
3528
  "The key is temporary until kept: open the link, sign in or create a free account, and the",
3497
3529
  "same key stays on your account. Until then it stops working after a few days and has request",
3498
3530
  "limits; the link keeps it for about two weeks, even after it stops working.",
@@ -3526,6 +3558,7 @@ var initCommand = {
3526
3558
  }
3527
3559
  const minted = await mintKey(context);
3528
3560
  const keepWindow = minted.keepUntil ? `; it works until ${formatUtc(minted.keepUntil)}, even after the key stops` : "";
3561
+ const starter = starterCommand(minted.apiKey);
3529
3562
  return {
3530
3563
  json: {
3531
3564
  apiKey: minted.apiKey,
@@ -3535,6 +3568,7 @@ var initCommand = {
3535
3568
  keepUntil: minted.keepUntil ?? null,
3536
3569
  keepUrl: minted.keepUrl,
3537
3570
  limits: minted.limits ?? null,
3571
+ starterCommand: starter,
3538
3572
  docs: { llms: LLMS_URL, skill: SKILL_URL }
3539
3573
  },
3540
3574
  doc: doc(
@@ -3545,6 +3579,9 @@ var initCommand = {
3545
3579
  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.`
3546
3580
  },
3547
3581
  { kind: "blank" },
3582
+ { kind: "text", text: "Run this next. Tesla is a sample company, so this key gets its full sentiment reading:" },
3583
+ { kind: "text", text: starter, tone: "accent" },
3584
+ { kind: "blank" },
3548
3585
  {
3549
3586
  kind: "text",
3550
3587
  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."
package/dist/index.cjs CHANGED
@@ -1177,6 +1177,19 @@ var Stocks = class {
1177
1177
  async getSimilar(ticker, options) {
1178
1178
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/similar`, options);
1179
1179
  }
1180
+ /**
1181
+ * List the ETFs that hold a stock, heaviest weight first.
1182
+ *
1183
+ * Resolves to a bare array (no preview envelope) on every tier, sorted by `weightPct`
1184
+ * descending, then `etfTicker` ascending. A ticker no tracked fund holds, or an unknown
1185
+ * ticker, resolves to `[]` rather than throwing. Only funds SentiSense tracks with a
1186
+ * holdings file are searched, and some funds' holdings are partial, so the list is not
1187
+ * every fund in the market. `ticker` is case-insensitive. Counts against the monthly
1188
+ * quota like other data endpoints.
1189
+ */
1190
+ async getEtfs(ticker, options) {
1191
+ return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/etfs`, options);
1192
+ }
1180
1193
  /** Get company profile (CEO, sector, industry, market data). */
1181
1194
  async getProfile(ticker, options) {
1182
1195
  return this.client.get(`/api/v1/stocks/${encodeURIComponent(ticker)}/profile`, options);
@@ -1527,16 +1540,30 @@ var Trackers = class {
1527
1540
  * in your renderer.
1528
1541
  *
1529
1542
  * @param trackerId slug from {@link list}, e.g. `"institution-concentration"`.
1530
- * @param params provider-specific query params (e.g. `{ scope: "us" }` for
1531
- * geographically-scoped trackers like hantavirus). Unknown keys are ignored.
1543
+ * @param params provider-specific query params, e.g. `{ scope: "nasdaq100" }` for
1544
+ * `market-heatmap`, or `{ filter: { state: "TX" } }` for a tracker that lists
1545
+ * `filters`. A bad `filter` throws `APIError` with `code: "invalid_filter"`.
1532
1546
  */
1533
1547
  async get(trackerId, params) {
1534
- return this.client.get(`/api/v1/trackers/${trackerId}`, params);
1548
+ return this.client.get(`/api/v1/trackers/${trackerId}`, serializeTrackerParams(params));
1535
1549
  }
1536
1550
  };
1551
+ function serializeTrackerFilter(filter) {
1552
+ if (typeof filter === "string") return filter;
1553
+ return Object.entries(filter).map(([key, value]) => `${key}:${value}`).join(",");
1554
+ }
1555
+ function serializeTrackerParams(params) {
1556
+ if (!params) return void 0;
1557
+ const out = {};
1558
+ for (const [key, value] of Object.entries(params)) {
1559
+ if (value === void 0 || value === null) continue;
1560
+ out[key] = key === "filter" ? serializeTrackerFilter(value) : value;
1561
+ }
1562
+ return out;
1563
+ }
1537
1564
 
1538
1565
  // src/version.ts
1539
- var VERSION = "0.74.0";
1566
+ var VERSION = "0.76.0";
1540
1567
 
1541
1568
  // src/client.ts
1542
1569
  var DEFAULT_BASE_URL = "https://app.sentisense.ai";