sentisense 0.35.0 → 0.38.0

package/README.md

@@ -263,6 +263,41 @@ client.stocks.getKpis("AAPL")       // Product metrics and segment revenue time-
 client.stocks.listKpiCoverage()     // All tickers with curated KPI data (free, no quota cost)
 ```
 
+### Earnings
+
+The earnings analysis report is the assembled version of a quarter: one object per fiscal period carrying the editorial headline, the KPI cards with year-over-year deltas, the guidance language as management phrased it, and a summary of the earnings call. Pair it with the recent-reporters feed to drive a post-earnings sweep. Both return the preview envelope.
+
+```typescript
+client.earnings.getSummaries("AAPL", { limit: 4 })   // Per-quarter analysis report, newest first. FREE: latest quarter, shaped. PRO: every hydrated quarter in full.
+client.earnings.getRecent({ days: 7, limit: 25 })    // Who reported in the last N days. Full window on every key.
+```
+
+```typescript
+import SentiSense from "sentisense";
+
+const client = new SentiSense({ apiKey: process.env.SENTISENSE_API_KEY });
+
+const res = await client.earnings.getSummaries("AAPL", { limit: 1 });
+const quarter = res.data[0];
+
+if (quarter) {
+  console.log(quarter.fiscalPeriod, quarter.reportDate);
+  console.log(quarter.headline);
+  for (const kpi of quarter.kpiHighlights ?? []) {
+    console.log(`  ${kpi.label}: ${kpi.value} (${kpi.yoy ?? "no YoY"})`);
+  }
+
+  if (res.isPreview) {
+    // Free key: section titles stand in for the bodies.
+    console.log("Summary covers:", quarter.summaryTopics?.join(", "));
+  } else {
+    console.log(quarter.summaryMd);
+  }
+}
+```
+
+The forward-looking half of the family is `client.calendar.getEarnings()`, which covers scheduled dates and consensus EPS rather than results.
+
 ### ETFs (beta)
 
 Composition data is public; the holdings-weighted aggregate views follow the same PRO-with-preview pattern as Analyst/Insider. Aggregates synthesize fund-level views from each constituent's per-stock data, weighted by allocation, with a `coverage` block on every response.
@@ -281,6 +316,55 @@ client.etfs.sentimentAggregate("QQQ")                           // SentiSense re
 client.marketMood.get()
 ```
 
+### Screener
+
+Filter the tracked universe on the SentiSense Score, attention, analyst consensus, technicals and price 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.
+
+```typescript
+client.screener.fields()                      // Every filterable field, both universes, with units + operators
+client.screener.screens()                     // The curated screens shipped in the product, each with a runnable plan
+client.screener.run({ plan, tickers, limit }) // Run a screen against the stock universe
+client.screener.runEtfs({ plan, limit })      // Run a screen against the ETF universe
+```
+
+```typescript
+// Run a curated screen as-is
+const { screens } = await client.screener.screens();
+const crowdVsStreet = screens.find((s) => s.id === "crowd-vs-street")!;
+const curated = await client.screener.run({ plan: crowdVsStreet.plan, limit: 25 });
+console.log(`${curated.matched} matched, showing ${curated.results.length}`);
+
+// Or build your own: bullish Score, thin analyst enthusiasm
+const res = await client.screener.run({
+  plan: {
+    filters: [
+      { fieldName: "SENTI_SCORE_7D", op: "GTE", value: 13 },
+      { fieldName: "ANALYST_BUY_RATIO_PCT", op: "LTE", value: 30 },
+      { fieldName: "ANALYST_COUNT", op: "GTE", value: 5 },
+    ],
+    sort: { fieldName: "SENTI_SCORE_7D", dir: "DESC" },
+  },
+  limit: 25,
+});
+for (const row of res.results) {
+  console.log(row.ticker, row.sentiSenseScore7D, row.analystBuyRatioPct);
+}
+```
+
+`limit` rides next to the plan rather than inside it, because a plan is a stored object and paging is a transport concern. It defaults to 100 and caps at 500. `matched` is the count before `limit` was applied, so truncation is visible. `tickers` is optional: omit it to screen the whole tracked universe, pass a list to screen a watchlist.
+
+Three field semantics are worth stating outright, because guessing them wrong produces a screen that looks fine and means nothing:
+
+- **`ANALYST_RATING_MEAN` is inverted.** It is the vendor's 1-to-5 scale where **1.0 is strong buy**, so bullish is `LTE 2.5`. Prefer `ANALYST_BUY_RATIO_PCT`, which runs the intuitive direction.
+- **`MA_CROSS_STATE` is ordinal**, not a percentage: `1` golden cross, `-1` death cross, `0` neither. Use `EQ`.
+- **`SENTIMENT_DIRECTION` is the sign of the 7-day SentiSense Score** (`1` / `0` / `-1`) with a neutral band of plus-or-minus 5. Despite the name it is not sentiment polarity, and `0` matches only an exact zero.
+
+The Score fields (`SENTI_SCORE_7D`, `SENTI_SCORE_1M`, `SCORE_CHANGE_7D`) are the SentiSense Score, not polarity: unbounded, banded at 5 / 13 / 23 either side of zero. Filter on those band edges, not on values like `0.5`, which behave as "any positive score". Nulls never match in either direction, so `RETURN_1Y >= 0` and `RETURN_1Y < 0` do not partition the universe: a stock listed four months ago is in neither result. If a screen returns fewer rows than you expect, check coverage before you check your thresholds.
+
+On the ETF side, `CONSTITUENTS_WEIGHTED_SENTISENSE` is the holdings-weighted Score across what the fund owns and is usually the one you want; `DIRECT_SENTISENSE` is the Score from chatter about the fund ticker itself. `WEIGHT_COVERED_PCT` tells you how much of the fund's weight had constituent data behind the weighted number.
+
+Screens read a snapshot that refreshes every 20 minutes, so this is not a quote feed. Use `client.stocks.getQuote()` for live prices.
+
 ## Error Handling
 
 ```typescript

package/dist/index.cjs

@@ -185,6 +185,53 @@ var Documents = class {
   }
 };
 
+// src/resources/earnings.ts
+var Earnings = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Per-quarter earnings analysis report for one ticker, newest first.
+   *
+   * Each quarter carries the editorial headline, the KPI cards that matter for
+   * that company with year-over-year deltas, the guidance language as
+   * management phrased it, and a summary of the earnings call.
+   *
+   * Branch on `isPreview`: a PRO key receives every hydrated quarter in full, a
+   * FREE key receives the latest quarter shaped rather than truncated, plus
+   * `totalCount`. {@link EarningsQuarter} documents which fields each tier
+   * carries.
+   *
+   * A quarter typically appears within 48 hours of the company reporting, and
+   * the call summary can arrive after the press-release content for the same
+   * quarter, so read `generatedAt` and `transcriptGeneratedAt` rather than
+   * assuming a fixed lag. A ticker with no stored quarter answers with an empty
+   * `data` array, not a 404.
+   *
+   * Use canonical ticker symbols: `GOOGL` (not `GOOG`), `BRK.B` (not `BRK-B`).
+   */
+  async getSummaries(ticker, options) {
+    return this.client.get(
+      `/api/v1/stocks/${encodeURIComponent(ticker.toUpperCase())}/earnings-summaries`,
+      options
+    );
+  }
+  /**
+   * Which covered companies reported on or after `today - days`, newest first.
+   *
+   * Every API key receives the full window it asks for, so `isPreview` is
+   * always `false` here. The window is bounded by `reportDate`, so a quarter
+   * reported inside it appears even when its call summary lands later, and an
+   * empty `data` array means nobody in the covered set reported in that window.
+   *
+   * This is the backward-looking feed; `client.calendar.getEarnings()` is the
+   * forward-looking one.
+   */
+  async getRecent(options) {
+    return this.client.get("/api/v1/earnings/recent", options);
+  }
+};
+
 // src/resources/entityMetrics.ts
 var EntityMetrics = class {
   constructor(client) {
@@ -285,7 +332,7 @@ var Insider = class {
   /**
    * Get market-wide insider activity: top buys and sells aggregated by ticker.
    *
-   * PRO-gated. Free/unauthenticated users receive a preview (top 5 per direction)
+   * PRO-gated. Free-tier users receive a preview (top 5 per direction)
    * with `isPreview: true` in the response.
    */
   async getActivity(options) {
@@ -320,7 +367,7 @@ var Politicians = class {
   /**
    * Get recent congressional STOCK Act trading activity across all politicians.
    *
-   * PRO-gated. Free/unauthenticated users receive a preview (top 5 trades)
+   * PRO-gated. Free-tier users receive a preview (top 5 trades)
    * with `isPreview: true` in the response.
    *
    * The feed is longer than one response: a default 90-day window is routinely well over a
@@ -432,7 +479,7 @@ var Insights = class {
   }
   /**
    * Get available insight types for a specific stock.
-   * No authentication required.
+   * API key required.
    *
    * Returns an array of insight type strings (e.g., `["sentiment_shift", "options_activity"]`).
    */
@@ -571,6 +618,86 @@ var MarketSummaryResource = class {
   }
 };
 
+// src/resources/screener.ts
+var Screener = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Every filterable field, with its unit, operators and description, for both
+   * universes.
+   *
+   * Build a filter UI from this rather than hardcoding the list and you inherit
+   * new fields as they ship. The ETF `STRING` fields (`ISSUER`, `ASSET_CLASS`,
+   * `TRACKED_INDEX`) come back with their `values` populated from the live
+   * universe, so pickers stay current without a redeploy.
+   */
+  async fields() {
+    return this.client.get("/api/v1/screener/fields");
+  }
+  /**
+   * The curated screens shipped in the product, each with a runnable plan.
+   *
+   * Each `plan` round-trips straight into {@link run} (or {@link runEtfs} when
+   * `plan.universe === "ETF"`) with nothing to rebuild.
+   *
+   * Their filters identify the field with `field` rather than `fieldName`.
+   * Both keys are accepted on the way in, so read either when inspecting a plan
+   * you did not build yourself.
+   */
+  async screens() {
+    return this.client.get("/api/v1/screener/screens");
+  }
+  /**
+   * Run a screen against the stock universe.
+   *
+   * `tickers` is optional: omit it to screen the whole tracked universe, pass a
+   * list to screen a watchlist. `limit` sits next to the plan rather than
+   * inside it, because a plan is a stored object and paging is a transport
+   * concern; it defaults to 100 and caps at 500.
+   *
+   * Read `matched` before you read `results`: it is the count before `limit`
+   * was applied, so a `matched` above your `limit` means you are holding the
+   * top slice under the plan's sort, not the whole answer.
+   *
+   * @example
+   * ```ts
+   * const res = await client.screener.run({
+   *   plan: {
+   *     filters: [
+   *       { fieldName: "SENTI_SCORE_7D", op: "GTE", value: 13 },
+   *       { fieldName: "ANALYST_BUY_RATIO_PCT", op: "LTE", value: 30 },
+   *       { fieldName: "ANALYST_COUNT", op: "GTE", value: 5 },
+   *     ],
+   *     sort: { fieldName: "SENTI_SCORE_7D", dir: "DESC" },
+   *   },
+   *   limit: 25,
+   * });
+   * ```
+   */
+  async run(options) {
+    return this.client.post("/api/v1/screener/execute", options);
+  }
+  /**
+   * Run a screen against the ETF universe.
+   *
+   * Same request shape as {@link run}, against a different field vocabulary:
+   * take the ETF names from `fields().etf`. `IN` / `NOT_IN` take a `values`
+   * array instead of `value` and are the operators for the string fields
+   * (`ISSUER`, `ASSET_CLASS`, `TRACKED_INDEX`).
+   *
+   * `CONSTITUENTS_WEIGHTED_SENTISENSE` is the holdings-weighted SentiSense
+   * Score across what the fund owns and is usually the one you want;
+   * `DIRECT_SENTISENSE` is the Score from chatter about the fund ticker itself,
+   * which on a broad index fund is mostly macro noise. `WEIGHT_COVERED_PCT`
+   * tells you how much of the fund's weight had constituent data behind the
+   * weighted number.
+   */
+  async runEtfs(options) {
+    return this.client.post("/api/v1/screener/etfs/execute", options);
+  }
+};
+
 // src/resources/stocks.ts
 var Stocks = class {
   constructor(client) {
@@ -844,7 +971,7 @@ var Trackers = class {
 };
 
 // src/version.ts
-var VERSION = "0.35.0";
+var VERSION = "0.38.0";
 
 // src/client.ts
 var DEFAULT_BASE_URL = "https://app.sentisense.ai";
@@ -889,6 +1016,8 @@ var SentiSense = class {
     this.indexes = new Indexes(this);
     this.trackers = new Trackers(this);
     this.calendar = new Calendar(this);
+    this.earnings = new Earnings(this);
+    this.screener = new Screener(this);
   }
   /** @internal */
   async get(path, params) {