@invinite-org/invinite-data-cli 0.1.22 → 0.2.1

package/README.md

@@ -120,10 +120,10 @@ npx @invinite-org/invinite-data-cli@latest plugin uninstall --all --global
 
 | Runtime | Skill | Agent | Command |
 |---------|-------|-------|---------|
-| **Claude Code** | `skills/invinite-data-cli/SKILL.md` | `agents/invinite-data.md` | `commands/financial-research.md` |
-| **OpenCode** | `command/invinite-data-cli.md` | `agents/invinite-data.md` | — |
-| **Codex** | `skills/invinite-data-cli/SKILL.md` | — | `skills/invinite-financial-research/SKILL.md` |
-| **Copilot** | `skills/invinite-data-cli/SKILL.md` | — | `skills/invinite-financial-research/SKILL.md` |
+| **Claude Code** | `skills/invinite-data-cli/SKILL.md` | `agents/invinite-data.md` | `commands/financial-research.md`, `commands/analyze-earnings-call.md` |
+| **OpenCode** | `command/invinite-data-cli.md` | `agents/invinite-data.md` | `command/analyze-earnings-call.md` |
+| **Codex** | `skills/invinite-data-cli/SKILL.md` | — | `skills/invinite-financial-research/SKILL.md`, `skills/invinite-analyze-earnings-call/SKILL.md` |
+| **Copilot** | `skills/invinite-data-cli/SKILL.md` | — | `skills/invinite-financial-research/SKILL.md`, `skills/invinite-analyze-earnings-call/SKILL.md` |
 
 ### Alternative: Claude Code plugin directory
 
@@ -143,6 +143,13 @@ Use `/financial-research` for multi-step analysis:
 /financial-research Analyze risk factors from NVDA's latest 10-K filing
 ```
 
+Use `/analyze-earnings-call` for one call — results vs guidance, raised / lowered guidance, analyst focus and tone change vs the prior call, cited with `[m:ss]` timestamps:
+
+```
+/analyze-earnings-call NVDA
+/analyze-earnings-call AAPL 2026 Q4
+```
+
 Or ask questions directly — the AI will auto-trigger the skill and delegate to the data agent as needed.
 
 > **Note:** The CLI must be installed and authenticated (see [Authentication](#authentication)) for the plugin to work.
@@ -167,12 +174,14 @@ These options are available on all data commands:
 - [metrics](#metrics) — Financial metrics, ratios, and growth
 - [segments](#segments) — Segmented financials
 - [filings](#filings) — SEC filings
+- [earnings](#earnings) — Earnings calls: calendar, transcripts, Q&A, guidance, audio, slides, documents, search
 - [ownership](#ownership) — Institutional ownership
 - [insider-trades](#insider-trades) — Insider trading data
 - [ipos](#ipos) — IPO listings
 - [market](#market) — Market data
 - [metadata](#metadata) — API metadata
-- [ws](#ws) — WebSocket streaming
+- [webhooks](#webhooks) — Earnings-call webhook subscriptions
+- [ws](#ws) — WebSocket streaming (`ws listen --earnings` for live call transcripts, `--keywords` / `--all-live` for keyword alerts)
 
 ---
 
@@ -501,6 +510,255 @@ invd filings form-types -i AAPL
 
 ---
 
+### earnings
+
+Earnings calls: calendar, transcripts, Q&A, guidance and KPIs, audio, slides, documents, search. The live transcript (`ws listen --earnings`), audio, slides, the live stream and webhooks need the **PRO** plan (calendar, events and `live` need LITE, the other reads STANDARD); a `403` names the plan a route needs.
+
+**Selecting a call.** Commands about one call (marked *selector* below) take either `--event <event_id>` (a UUID from `earnings events` / `earnings calendar`; wins over the rest), or `-i, --identifier <ticker|cik>` with `--year <n>` + `--quarter <n>` (the company's fiscal quarter) or `--date <YYYY-MM-DD>` (the New York call day).
+
+**Saving files.** `--output <file>` saves a transcript, press release, recording or deck (`documents --output <dir>` saves every document); an existing file is only replaced with `--force`. Without `--output` the media commands print **presigned URLs that expire after 15 minutes**.
+
+#### `earnings calendar`
+
+Upcoming and recent calls across companies.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--from <date>` / `--to <date>` | New York days (at most 92 days) | today / from + 14 days |
+| `--status <list>` | `estimated`, `unconfirmed`, `confirmed`, `postponed`, `cancelled` (comma-separated) | — |
+| `--session <session>` | `bmo`, `amc`, `intraday` | — |
+| `--exchange <exchange>` | Exchange | — |
+| `--event-type <type>` | `earnings_call`, `investor_day`, `conference`, `agm`, `other`, or `all` (every type) | `earnings_call` |
+| `-s, --sort` / `-l, --limit` / `--offset` | Sort, page size (1–500), offset | — |
+
+```bash
+invd earnings calendar --from 2026-10-26 --to 2026-10-30 --status confirmed
+```
+
+#### `earnings events`
+
+A company's calls.
+
+| Option | Description |
+|--------|-------------|
+| `-i, --identifier <ticker>` | Ticker or CIK **(required)** |
+| `--from <date>` / `--to <date>` | Call day range |
+| `--event-type <type>` | `earnings_call`, `investor_day`, `conference`, `agm`, `other`, or `all` (default: every type) |
+| `--observations` | Include the date / time observations per call |
+| `-s, --sort` / `-l, --limit` / `--offset` | Sort, page size (1–200), offset |
+
+```bash
+invd earnings events -i AAPL -s desc -l 4
+```
+
+#### `earnings live`
+
+Calls being captured right now (`live_audio` = a live stream exists).
+
+```bash
+invd earnings live
+```
+
+#### `earnings event`
+
+One call with its date / time observations: `invd earnings event <event_id>`.
+
+```bash
+invd earnings event 0b9d6f43-6b1e-4c39-9d3a-2f6a3c1e8b11
+```
+
+#### `earnings transcript` *(selector)*
+
+| Option | Description |
+|--------|-------------|
+| `--format <format>` | `speakers` (default), `text`, `words`, `sections`, `cleaned` |
+| `--transcript-version <n>` | A published version (`earnings versions`); not `--version`, which prints the CLI version |
+| `--as-of <iso>` | The version current at that instant |
+| `-o, --output <file>` / `--force` | Save the transcript as text |
+
+The header shows where the Q&A begins ("Q&A starts at 41:07") when the call has one; `--json` carries it as `qa_start_ms` (milliseconds, `null` without a Q&A).
+
+```bash
+invd earnings transcript -i AAPL --year 2026 --quarter 4 --output aapl-q4.txt
+```
+
+#### `earnings versions` *(selector)*
+
+Published transcript versions (final, corrected, …).
+
+```bash
+invd earnings versions -i AAPL --date 2026-10-30
+```
+
+#### `earnings transcript-diff` *(selector)*
+
+| Option | Description |
+|--------|-------------|
+| `--from <n>` | Older version **(required)** |
+| `--to <n>` | Newer version (default: the current one) |
+
+```bash
+invd earnings transcript-diff --event <event_id> --from 1
+```
+
+#### `earnings qa` *(selector)*
+
+Question / answer pairs with the analyst and the answering executives (`-l, --limit` 1–200, `--offset`).
+
+```bash
+invd earnings qa -i NVDA --year 2027 --quarter 2
+```
+
+#### `earnings participants` *(selector)*
+
+Speakers of the call (`--evidence` adds the quotes each name was resolved from).
+
+```bash
+invd earnings participants --event <event_id> --evidence
+```
+
+#### `earnings analysts`
+
+Analysts on a company's calls (`-i` **required**, `-l, --limit` 1–100, `--offset`).
+
+```bash
+invd earnings analysts -i MSFT
+```
+
+#### `earnings person`
+
+One person's call appearances: `invd earnings person <person_id>` (`-l, --limit` 1–200, `--offset`).
+
+```bash
+invd earnings person <person_id>
+```
+
+#### `earnings press-release` *(selector)*
+
+| Option | Description |
+|--------|-------------|
+| `--body` | Include the release text |
+| `-o, --output <file>` / `--force` | Save the release text |
+
+```bash
+invd earnings press-release -i AAPL --year 2026 --quarter 4 --body
+```
+
+#### `earnings extractions` *(selector)*
+
+| Option | Description |
+|--------|-------------|
+| `--kind <kind>` | `guidance` (default) or `kpi` |
+| `--review <filter>` | Guidance review filter: `approved`, `auto`, `all` |
+| `-l, --limit` / `--offset` | Page size (1–500), offset |
+
+```bash
+invd earnings extractions --event <event_id> --kind kpi
+```
+
+#### `earnings guidance-history`
+
+A company's guidance for one metric across calls.
+
+| Option | Description |
+|--------|-------------|
+| `-i, --identifier <ticker>` | Ticker or CIK **(required)** |
+| `--metric <metric>` | Normalized metric, e.g. `revenue`, `eps_non_gaap`, `segment:iphone` **(required)** |
+| `--period-kind <kind>` | `quarter`, `fiscal_year`, `half`, `other` |
+| `--basis <basis>` | `gaap`, `non_gaap`, `unknown` |
+| `-l, --limit <n>` | Series entries (1–40) |
+
+```bash
+invd earnings guidance-history -i AAPL --metric revenue --period-kind quarter
+```
+
+#### `earnings diff` *(selector)*
+
+What changed against the prior call: similarity, tone, hedging, new / dropped topics, slide changes (`--vs prior`, the only base).
+
+```bash
+invd earnings diff -i AAPL --year 2026 --quarter 4
+```
+
+#### `earnings metrics` *(selector)*
+
+Call structure metrics (length, Q&A share, question count, …).
+
+```bash
+invd earnings metrics --event <event_id>
+```
+
+#### `earnings prosody` *(selector)*
+
+Speech timing, pitch and energy per speaker (`--section all|prepared|qa`).
+
+```bash
+invd earnings prosody --event <event_id> --section qa
+```
+
+#### `earnings audio` *(selector)*
+
+The recording as a presigned URL, or `-o, --output <file>` (+ `--force`) to save it.
+
+```bash
+invd earnings audio --event <event_id> --output call.mp3
+```
+
+#### `earnings slides` *(selector)*
+
+| Option | Description |
+|--------|-------------|
+| `--markdown` | Include each page's extracted text |
+| `--pages <range>` | Page or range, e.g. `3` or `1-5` |
+| `-o, --output <file>` / `--force` | Save the deck PDF |
+
+```bash
+invd earnings slides -i AAPL --year 2026 --quarter 4 --output deck.pdf
+```
+
+#### `earnings documents` *(selector)*
+
+Investor documents of the call (CFO commentary, data sheets, letters, filings).
+
+| Option | Description |
+|--------|-------------|
+| `--kind <list>` | `cfo_commentary`, `financial_data`, `shareholder_letter`, `fact_sheet`, `company_transcript`, `sec_filing`, `infographic`, `other` |
+| `--body` | Include the extracted text |
+| `-l, --limit` / `--offset` | Page size (1–100), offset |
+| `-o, --output <dir>` / `--force` | Save every document as `<kind>-<document_id>.<ext>` |
+
+With `--output`, a document without a download URL (a link-only `sec_filing`, or a file the API could not fetch — use its `source_url`) is never skipped silently: each gets a warning on stderr, followed by a count (`2 of 3 documents saved; 1 skipped`). The exit code is 0 when at least one document was saved (or the list was empty) and 1 when documents were listed but none could be saved. An interrupted download (Ctrl-C) never leaves a partial file behind.
+
+```bash
+invd earnings documents --event <event_id> --output ./docs
+```
+
+#### `earnings search`
+
+Semantic search over call transcripts and slides.
+
+| Option | Description |
+|--------|-------------|
+| `-q, --query <text>` | Search text **(required)** |
+| `--event <event_id>` / `-i, --identifier <ticker>` | Only this call / company |
+| `--from <date>` / `--to <date>` | Call day range |
+| `--type <type>` | `transcript`, `qa`, `preparedRemarks`, `presentation` |
+| `-l, --limit <n>` | Passages (1–8) |
+
+```bash
+invd earnings search -q "data center demand" -i NVDA
+```
+
+#### `earnings stream` *(selector)*
+
+The live HLS audio URL of a call in progress (PRO; `status` = `available`, `not_started`, `ended` or `disabled`). Play it with `ffplay` or VLC; the URL expires (`expires_at`).
+
+```bash
+invd earnings stream --event <event_id>
+```
+
+---
+
 ### ownership
 
 Institutional ownership data.
@@ -661,13 +919,50 @@ invd metadata section-ids
 
 ---
 
+### webhooks
+
+Earnings-call webhook subscriptions (PRO): signed, retried `POST`s of the call lifecycle to your HTTPS endpoint. Events: `earnings_call.scheduled`, `.rescheduled`, `.started`, `.ended`, `.transcript_provisional`, `.transcript_ready`, `.transcript_corrected`, `.assets_ready`, `.keyword_hit` (one delivery per mention of one of the subscription's `--keywords` on a live call, with the speaker, `start_ms` and the sentence), `.guidance_flash` (a guidance number spoken live, before the final transcript), and `ping`. Deliveries carry `X-Invinite-Signature: t=…,v1=…` (HMAC-SHA256 of `<t>.<raw body>` with the secret) and are retried after 1 min, 5 min, 30 min, 2 h, 6 h, 12 h and 24 h.
+
+| Command | Description |
+|---------|-------------|
+| `webhooks list` | Your team's subscriptions (never the secret, only `secret_hint`) |
+| `webhooks create --url <url> --events <list> [--ciks <list>] [--keywords <list>]` | Create one (max 10 per team; `--ciks` max 10, default every company; `--keywords` max 20 of 2–64 chars, matched on every live call for `.keyword_hit`). **Prints the signing secret once** |
+| `webhooks update <id> [--keywords <list>] [--ciks <list>] [--events <list>] [--active true\|false]` | Change a subscription (`PATCH`; at least one option; an empty `--keywords ""` / `--ciks ""` clears the list; `--active false` pauses it, `true` resumes it and resets the failure counters) |
+| `webhooks delete <id>` | Delete a subscription |
+| `webhooks rotate-secret <id>` | New secret (printed once); the old one stays valid until `previous_secret_expires_at` (5 min) |
+| `webhooks test <id>` | Queue a signed `ping` delivery |
+| `webhooks deliveries <id>` | The last 100 attempts: `delivery_id`, `event`, `attempt`, `status`, `response_status`, `duration_ms`, `at`, `next_attempt_at` |
+
+```bash
+invd webhooks create --url https://hooks.example.com/invinite --events earnings_call.transcript_ready,earnings_call.started --ciks 320193
+invd webhooks create --url https://hooks.example.com/alerts --events earnings_call.keyword_hit --keywords tariffs,buyback   # every company
+invd webhooks update <id> --keywords tariffs,china,buyback
+invd webhooks update <id> --active false
+invd webhooks test <id>
+invd webhooks deliveries <id>
+```
+
+---
+
 ### ws
 
 Real-time WebSocket streaming.
 
 #### `ws listen`
 
-Listen to real-time SEC filing notifications. Automatically reconnects on disconnection with exponential backoff.
+Listen to real-time SEC filing notifications, or with `--earnings` follow one earnings call's live transcript (PRO), or with `--all-live --keywords` get keyword alerts across every live call. Automatically reconnects on disconnection with exponential backoff.
+
+| Option | Description |
+|--------|-------------|
+| `--earnings <event_id\|cik>` | Follow a live call: event ID (UUID) or CIK |
+| `--all-live` | Keyword alerts across every live call at once (needs `--keywords`; no transcript, replay or partials) |
+| `--since-seq <n>` | Replay the finals after this seq (default `-1` = the whole call so far) |
+| `--partials` | Show interim segments, overwritten in place (terminal only; `--json` emits them) |
+| `--names` | Print each speaker-name snapshot |
+| `--keywords <list>` | Comma-separated keywords (max 20, 2–64 chars each): one highlighted `keyword_hit` line per mention |
+| `--keyword-match exact\|stem` | `exact` (default) matches the word; `stem` also its inflections (`tariff` hits "tariffs") |
+| `--speaker-roles <list>` | Only hits by these speakers: `executive`, `ir_host`, `analyst`, `operator` |
+| `--min-rank <n>` | With `--all-live`: only companies ranked ≤ n by market cap |
 
 ```bash
 invd ws listen
@@ -675,6 +970,26 @@ invd ws listen
 
 Press `Ctrl+C` to disconnect.
 
+**Live transcripts.** Find a call in progress, then follow it:
+
+```bash
+invd earnings live
+invd ws listen --earnings 0b9d6f43-6b1e-4c39-9d3a-2f6a3c1e8b11 --partials
+# AAPL 2026-10-30T21:00:00.000Z · capturing · from seq 0 (latest 41)
+# [0:12] Operator: Good afternoon and welcome to the Apple Q4 fiscal year 2026 earnings call.
+# [1:05] Tim Cook: Thank you, everyone, for joining us.
+```
+
+**Keyword and guidance alerts.** With `--keywords` the same subscription also delivers a `keyword_hit` frame for every mention (one highlighted line: `[m:ss] keyword "tariffs" · Tim Cook (executive): …`, the speaker from the API's live naming) and a `guidance_flash` frame for every guidance number spoken live (`[m:ss] guidance flash · Revenue Q1 FY2027: USD 4.1–4.3 billion — "…"`), both before the final transcript. `--all-live --keywords <list>` subscribes to every live call at once (`scope: "all_live"`; each line starts with the symbol; the API refuses it without keywords, and so does the CLI); a `warning` frame (`global_scope_degraded`: some calls may be missing from the alerts) is printed and never fatal. With `--json` both frames are emitted as they arrive.
+
+```bash
+invd ws listen --earnings 320193 --keywords tariffs,china --keyword-match stem --speaker-roles executive
+invd ws listen --all-live --keywords tariffs --min-rank 500
+invd ws listen --all-live --keywords tariffs --json | jq -r 'select(.type=="keyword_hit") | "\(.symbol) \(.speaker_name): \(.text)"'
+```
+
+Finals are named from the newest speaker-name snapshot (`Speaker A` until a name is known). A `gap` line marks a seq range with no final yet (a late final may still follow on the same subscription, so finals can print slightly out of order); `resume_unavailable` means missed finals cannot be replayed right now — live delivery continues and the API back-fills them once it can. Neither needs a re-subscribe. After a reconnect the listener resumes after the last final it printed; it exits once the final transcript is ready (`invd earnings transcript --event <id>`). With `--json` every frame is one JSON line (NDJSON), e.g. `invd ws listen --earnings 320193 --json | jq -r 'select(.type=="transcript_segment") | .text'`.
+
 ---
 
 ## Output Formats

package/claude-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "invinite-financial-data",
-  "description": "Fetch and analyze financial data using the Invinite Data API — company fundamentals, financial statements, SEC filings, institutional ownership, insider trades, and more.",
-  "version": "0.3.0",
+  "description": "Fetch and analyze financial data using the Invinite Data API — company fundamentals, financial statements, SEC filings, earnings calls (transcripts, guidance, Q&A, live calls), institutional ownership, insider trades, and more.",
+  "version": "0.4.0",
   "author": {
     "name": "Invinite"
   },

package/claude-plugin/agents/invinite-data.md

@@ -1,6 +1,6 @@
 ---
 name: invinite-data
-description: Fetches financial data from the Invinite Data API for analysis. Use this agent whenever you need company financials, SEC filings, institutional ownership, insider trades, financial ratios, growth metrics, or any stock/company data. Delegate to this agent when the user asks for financial data retrieval, company research, or comparative financial analysis — even if they don't mention "Invinite" explicitly. This agent knows how to efficiently query the right endpoints, combine data from multiple sources, and return structured results ready for analysis.
+description: Fetches financial data from the Invinite Data API for analysis. Use this agent whenever you need company financials, SEC filings, institutional ownership, insider trades, financial ratios, growth metrics, earnings calls (calendar, transcripts, guidance and KPIs, Q&A, press releases, slides), or any stock/company data. Delegate to this agent when the user asks for financial data retrieval, company research, or comparative financial analysis — even if they don't mention "Invinite" explicitly. This agent knows how to efficiently query the right endpoints, combine data from multiple sources, and return structured results ready for analysis.
 tools: Bash(invd *), Read, Glob, Grep
 skills:
   - invinite-data-cli
@@ -29,6 +29,8 @@ You are a financial data retrieval specialist. Your job is to fetch the requeste
 - When fetching financial statements, default to `annual` period unless the request specifies otherwise
 - Use `--limit` appropriately — don't fetch more data than needed, but don't under-fetch either
 - For large datasets, use `--all` only when specifically needed
+- For earnings calls, resolve the call's `event_id` first (`invd earnings events -i <TICKER> -s desc -l 4 --json`) and pass `--event <event_id>` to every per-call command; keep `start_ms` values in the results so the caller can cite `[m:ss]` timestamps
+- Never pass `--output` (file downloads) unless the caller asked for a file
 
 ## Query planning
 
@@ -40,6 +42,8 @@ Common multi-step patterns:
 - **Ownership analysis**: holdings-by-company + ownership transactions
 - **Filing deep-dive**: metadata section-ids (first) + filings list → then filings sections for full text
 - **Comparative analysis**: metadata metrics (first) + financials snapshot with multiple tickers + metrics ratios for each
+- **Earnings call review**: earnings events (first, for the `event_id`) → then in parallel press-release + extractions `--kind guidance` + extractions `--kind kpi` + qa + diff
+- **Guidance tracking**: earnings guidance-history `--metric <metric>` across calls + extractions of the latest call
 
 ## Output format
 

package/claude-plugin/commands/analyze-earnings-call.md

@@ -0,0 +1,24 @@
+---
+name: analyze-earnings-call
+description: Analyze a company's latest (or a given quarter's) earnings call — results vs guidance, raised or lowered guidance, analyst focus, tone change against the prior call — with timestamped evidence.
+argument-hint: <ticker> [fiscal year + quarter, e.g. 2026 Q3]
+---
+
+# Analyze Earnings Call
+
+Analyze the earnings call requested in `$ARGUMENTS` using Invinite Data. Prefer the MCP tools (`earnings_call_*`) when connected; otherwise use the `invd earnings` commands below with `--json`.
+
+1. **Find the call.** Without a quarter, take the latest call that already happened: `invd earnings events -i <TICKER> --to <today> -s desc -l 1 --json` (MCP `earnings_call_events`). With a quarter, select it directly with `-i <TICKER> --year <YYYY> --quarter <Q>`. Use the call's `event_id` for every later step (`--event <event_id>`). If the call has no transcript yet, say so and stop.
+2. **Fetch in parallel** (all with `--event <event_id> --json`):
+   - press release: `invd earnings press-release` (`earnings_call_press_release`)
+   - guidance: `invd earnings extractions --kind guidance` and KPIs: `invd earnings extractions --kind kpi` (`earnings_call_guidance`)
+   - Q&A: `invd earnings qa` (`earnings_call_qa`) and participants: `invd earnings participants` (`earnings_call_participants`)
+   - diff vs the prior call: `invd earnings diff` (`earnings_call_diff`)
+   - only when a claim needs the exact wording: `invd earnings transcript` (`earnings_call_transcript`) or `invd earnings search -q "<topic>" --event <event_id>` (`earnings_call_search`)
+3. **Summarise**:
+   - **Results vs guidance** — reported figures from the press release against the guidance given on the prior call (`invd earnings guidance-history -i <TICKER> --metric <metric>` for a metric's series).
+   - **Guidance changes** — each item raised, lowered, maintained, introduced or withdrawn (`direction`), with the period and basis (GAAP / non-GAAP).
+   - **Analyst focus** — the recurring Q&A themes, who asked (firm), and where management deflected.
+   - **Tone change** — the diff's tone shift, hedging / uncertainty changes and new or dropped topics.
+4. **Cite evidence** — every quote or claim carries its `[m:ss]` timestamp (from `start_ms`) and the speaker; separate what was said from your interpretation.
+5. Flag what is missing (no press release, no guidance extracted, prior call not covered) instead of inferring it.

package/claude-plugin/commands/financial-research.md

@@ -1,6 +1,6 @@
 ---
 name: financial-research
-description: Perform AI-powered financial research and analysis. Use when the user asks to research companies, compare financials, analyze ownership patterns, review SEC filings, evaluate growth trends, or any multi-faceted financial question. This command orchestrates parallel data fetching and then synthesizes the results into a coherent analysis.
+description: Perform AI-powered financial research and analysis. Use when the user asks to research companies, compare financials, analyze ownership patterns, review SEC filings or earnings calls, evaluate growth trends, or any multi-faceted financial question. This command orchestrates parallel data fetching and then synthesizes the results into a coherent analysis.
 argument-hint: [question or research topic]
 ---
 
@@ -17,6 +17,7 @@ Break the user's request into independent data retrieval tasks. Think about what
 - **Statements**: income statements, balance sheets, cash flows (for trend analysis)
 - **Ownership**: institutional holders, ownership transactions, insider trades
 - **Filings**: SEC filing sections (risk factors, MD&A, business descriptions)
+- **Earnings calls**: call calendar, transcripts, management guidance and KPIs, Q&A with analysts, press releases, the diff vs the prior call
 - **Context**: dividends, stock splits, fiscal periods, segments
 
 Each independent data need becomes a separate subagent task.

package/claude-plugin/skills/invinite-data-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: invinite-financial-data
-description: Fetch financial data through the Invinite Data API MCP connector or invd CLI. Use whenever the user wants company information, financial statements, SEC filings, institutional ownership, insider trades, IPO data, market holidays, financial metrics, or other stock/company data, including requests mentioning tickers, CIKs, balance sheets, income statements, cash flows, 10-K, 10-Q, ratios, CAGR, growth rates, dividends, stock splits, or institutional holdings.
+description: Fetch financial data through the Invinite Data API MCP connector or invd CLI. Use whenever the user wants company information, financial statements, SEC filings, institutional ownership, insider trades, IPO data, market holidays, financial metrics, earnings calls, or other stock/company data, including requests mentioning tickers, CIKs, balance sheets, income statements, cash flows, 10-K, 10-Q, ratios, CAGR, growth rates, dividends, stock splits, institutional holdings, call transcripts, earnings guidance, KPIs, Q&A, analysts, live calls, slides, or press releases.
 allowed-tools: Bash(invd *)
 ---
 
@@ -28,6 +28,12 @@ Use the connected Invinite Data API MCP tools when available. Fall back to the `
 | Filing and metric discovery | `sec_available_form_types`, `list_available_section_ids`, `list_available_metrics` | `invd filings form-types`, `invd metadata ...` |
 | Institutional ownership | `holdings_by_company`, `holdings_by_investor`, `institutional_investors`, `institutional_transactions` | `invd ownership ...` |
 | Insider trades/IPOs/holidays | `insider_trades`, `ipos`, `market_holidays` | `invd insider-trades`, `invd ipos`, `invd market ...` |
+| Earnings call calendar/events/live | `earnings_call_calendar`, `earnings_call_events`, `earnings_call_live` | `invd earnings calendar\|events\|live` |
+| Call transcript/Q&A/participants | `earnings_call_transcript`, `earnings_call_qa`, `earnings_call_participants` | `invd earnings transcript\|qa\|participants` |
+| Call guidance/KPIs, diff vs prior call | `earnings_call_guidance`, `earnings_call_diff` | `invd earnings extractions\|guidance-history\|diff` |
+| Call documents/press release | `earnings_call_documents`, `earnings_call_press_release` | `invd earnings documents\|press-release` |
+| Search across calls | `earnings_call_search` | `invd earnings search` |
+| Keyword / guidance alerts | `earnings_call_alert_create\|list\|update\|delete\|test\|deliveries` | `invd webhooks …` |
 
 The discovery rules below apply to both transports: call `list_available_metrics` before ratios, growth, CAGR, or financial-statement analysis, and call `list_available_section_ids` before requesting filing sections.
 
@@ -227,6 +233,79 @@ invd metadata metrics --json
 invd metadata section-ids --json
 ```
 
+### Earnings Calls
+
+Commands about one call take a selector: `--event <event_id>` (from `events` / `calendar`), or `-i <ticker>` with `--year` + `--quarter` (fiscal) or `--date YYYY-MM-DD` (New York call day).
+
+```bash
+# Calendar across companies, a company's calls, calls being captured right now
+# --event-type: earnings_call (calendar default), investor_day, conference, agm, other, all (events default)
+invd earnings calendar --from 2026-10-20 --to 2026-10-31 --json
+invd earnings calendar --event-type all --json   # investor days, conferences, AGMs too
+invd earnings events -i AAPL -s desc -l 4 --json
+invd earnings live --json
+invd earnings event <event_id> --json
+
+# Transcript (formats: speakers, text, words, sections, cleaned), versions, word diff between versions
+# qa_start_ms = where the Q&A begins (ms into the call, null without one)
+invd earnings transcript -i AAPL --year 2026 --quarter 4 --format speakers --json
+invd earnings versions --event <event_id> --json
+invd earnings transcript-diff --event <event_id> --from 1 --json
+
+# Q&A pairs, speakers, analysts of a company, one person's appearances
+invd earnings qa --event <event_id> --json
+invd earnings participants --event <event_id> --json
+invd earnings analysts -i AAPL --json
+invd earnings person <person_id> --json
+
+# Press release, guidance / KPI extractions, a metric's guidance across calls
+invd earnings press-release --event <event_id> --body --json
+invd earnings extractions --event <event_id> --kind guidance --json
+invd earnings extractions --event <event_id> --kind kpi --json
+invd earnings guidance-history -i AAPL --metric revenue --json
+
+# Derived: diff vs the prior call, call metrics, prosody
+invd earnings diff --event <event_id> --json
+invd earnings metrics --event <event_id> --json
+invd earnings prosody --event <event_id> --section qa --json
+
+# Media (signed URLs expire after 15 min; --output saves the file)
+invd earnings audio --event <event_id> --output call.mp3
+invd earnings slides --event <event_id> --markdown --json
+invd earnings documents --event <event_id> --kind cfo_commentary --json
+invd earnings documents --event <event_id> --output ./docs   # a row without url (link-only sec_filing) is warned on stderr; use its source_url
+invd earnings stream --event <event_id> --json   # live HLS URL of a call in progress (PRO)
+
+# Semantic search over transcripts and slides
+invd earnings search -q "data center demand" -i NVDA --json
+```
+
+- `--transcript-version N` (not `--version`) selects a published transcript version; `--as-of <iso>` the version current at that instant.
+- `extractions --review approved|auto|all` filters guidance by review status; `diff --vs prior` is the only comparison base.
+- Every `*_ms` field is milliseconds from the call's start: cite it as `[m:ss]`.
+- The live transcript (`ws listen --earnings`), audio, slides, the live stream and webhooks need the PRO plan (calendar, events and `live` need LITE, the other reads STANDARD); a `403` names the plan a route needs.
+
+### Live transcripts and webhooks
+
+```bash
+# Follow a live call over the WebSocket (event ID or CIK; NDJSON with --json)
+invd ws listen --earnings <event_id> --json
+invd ws listen --earnings 320193 --names
+
+# Keyword alerts on a live call, or across every live call (--all-live needs --keywords)
+invd ws listen --earnings 320193 --keywords tariffs,china --keyword-match stem --json
+invd ws listen --all-live --keywords tariffs --json
+
+# Earnings-call webhook subscriptions (the secret is printed once)
+invd webhooks list --json
+invd webhooks create --url https://hooks.example.com/invinite --events earnings_call.transcript_ready --ciks 320193
+invd webhooks create --url https://hooks.example.com/alerts --events earnings_call.keyword_hit --keywords tariffs   # every company
+invd webhooks update <id> --keywords tariffs,buyback --json
+invd webhooks deliveries <id> --json
+```
+
+Keyword / guidance alerts (PRO) are webhook subscriptions: `earnings_call.keyword_hit` delivers one POST per mention of a keyword on any live call (speaker, `start_ms`, sentence), `earnings_call.guidance_flash` one per guidance number spoken live. "Alert me when any call mentions 'tariffs'" → `earnings_call_alert_create` with `keywords: ["tariffs"]`, `events: ["earnings_call.keyword_hit"]`, the user's HTTPS endpoint and no `ciks` (every company); later changes go through `earnings_call_alert_update` (keywords, ciks, events, active). CLI: `invd webhooks create --url <url> --events earnings_call.keyword_hit --keywords tariffs`.
+
 ### Health Check
 
 ```bash
@@ -264,6 +343,15 @@ invd ownership holdings-by-company -i AAPL --min-value 10000000 --json
 invd filings search -r "artificial intelligence strategy" -i MSFT --json
 ```
 
+### Reading an earnings call
+Find the call, then read it from the cheapest source to the most detailed:
+```bash
+invd earnings events -i NVDA -s desc -l 4 --json            # pick the event_id
+invd earnings transcript --event <event_id> --format sections --json
+invd earnings extractions --event <event_id> --kind guidance --json
+invd earnings search -q "gross margin outlook" --event <event_id> --json
+```
+
 ### Reading specific filing sections
 First find section IDs, then fetch the section:
 ```bash
@@ -279,3 +367,5 @@ invd filings sections -i AAPL --form-type 10-K --section-id risk_factors --json
 - For financial statements, `annual` gives the full year, `quarterly` gives each quarter, `ttm` gives trailing twelve months, `ytd` gives year-to-date
 - The `snapshot` command is the most efficient way to get complete financials for one or more companies at once
 - Filing sections return full text — great for detailed analysis of risk factors, MD&A, business descriptions, etc.
+- Following a live call: `invd earnings live --json` lists the calls in progress; `invd ws listen --earnings <event_id>` streams the transcript (PRO) and exits once the final transcript is ready
+- Earnings-call identifiers: `event_id` (UUID) from `invd earnings events` / `calendar` is the most precise selector; ticker + `--year` + `--quarter` uses the company's fiscal quarter

package/dist/src/cli.d.ts

@@ -1,2 +1,4 @@
 import { Command } from 'commander';
+/** `package.json` sits one level up under tsx (`src/cli.ts`), two in the build (`dist/src/cli.js`). */
+export declare function packageVersion(): string;
 export declare function createProgram(): Command;

package/dist/src/cli.js

@@ -1,3 +1,4 @@
+import { createRequire } from 'node:module';
 import { Command } from 'commander';
 import { setJsonMode } from './shared/spinner.js';
 import { registerConfigCommands } from './commands/config.js';
@@ -10,17 +11,35 @@ import { registerIposCommands } from './commands/ipos.js';
 import { registerOwnershipCommands } from './commands/ownership.js';
 import { registerInsiderTradesCommands } from './commands/insider-trades.js';
 import { registerFilingsCommands } from './commands/filings.js';
+import { registerEarningsCommands } from './commands/earnings.js';
 import { registerMarketCommands } from './commands/market.js';
 import { registerMetadataCommands } from './commands/metadata.js';
+import { registerWebhooksCommands } from './commands/webhooks.js';
 import { registerWsCommands } from './commands/ws.js';
 import { registerPluginCommands } from './commands/plugin.js';
 import { registerLoginCommands } from './commands/login.js';
+const PACKAGE_NAME = '@invinite-org/invinite-data-cli';
+/** `package.json` sits one level up under tsx (`src/cli.ts`), two in the build (`dist/src/cli.js`). */
+export function packageVersion() {
+    const requireJson = createRequire(import.meta.url);
+    for (const candidate of ['../package.json', '../../package.json']) {
+        try {
+            const pkg = requireJson(candidate);
+            if (pkg.name === PACKAGE_NAME && pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // not at this level
+        }
+    }
+    return '0.0.0';
+}
 export function createProgram() {
     const program = new Command();
     program
         .name('invd')
         .description('CLI for the Invinite financial data API')
-        .version('0.1.0')
+        .version(packageVersion())
         .option('--json', 'Output raw JSON (pipe-friendly)')
         .option('--all', 'Auto-paginate through all results')
         .hook('preAction', (thisCommand) => {
@@ -39,8 +58,10 @@ export function createProgram() {
     registerOwnershipCommands(program);
     registerInsiderTradesCommands(program);
     registerFilingsCommands(program);
+    registerEarningsCommands(program);
     registerMarketCommands(program);
     registerMetadataCommands(program);
+    registerWebhooksCommands(program);
     registerWsCommands(program);
     registerPluginCommands(program);
     registerLoginCommands(program);

package/dist/src/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,6BAA6B,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,wBAAwB,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAE5D,MAAM,UAAU,aAAa;IAC3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAE9B,OAAO;SACJ,IAAI,CAAC,MAAM,CAAC;SACZ,WAAW,CAAC,yCAAyC,CAAC;SACtD,OAAO,CAAC,OAAO,CAAC;SAChB,MAAM,CAAC,QAAQ,EAAE,iCAAiC,CAAC;SACnD,MAAM,CAAC,OAAO,EAAE,mCAAmC,CAAC;SACpD,IAAI,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;QACjC,MAAM,IAAI,GAAG,WAAW,CAAC,IAAI,EAAE,CAAC;QAChC,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACd,WAAW,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,CAAC,CAAC;IAEL,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAC/B,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,0BAA0B,CAAC,OAAO,CAAC,CAAC;IACpC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC9B,yBAAyB,CAAC,OAAO,CAAC,CAAC;IACnC,6BAA6B,CAAC,OAAO,CAAC,CAAC;IACvC,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACjC,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC5B,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAChC,qBAAqB,CAAC,OAAO,CAAC,CAAC;IAE/B,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}