feat: corporate actions from the Stockbit session (stocks actions, stocks calendar)

`idx stocks actions SYM [--kind ...]`: one stock's cash and stock dividends, bonus shares, rights, warrants, splits and reverse splits, meetings, public exposes and tender offers (`--kind ipo` adds its IPO), newest first. `idx stocks calendar [--from] [--to] [--kind ...]`: the market's actions dated in the range (default today and 30 days ahead), oldest first. MCP: get_corporate_actions, get_corporate_calendar. Stockbit's `/corpaction/{type}` serves one kind per request; each type has its own field prefix and list key, so entitlements are read by field suffix. An action's `date` is the cum date for entitlements, else the event's first day. Dividends keep their decimals. One request per kind, cached 6 hours. AUTHERROR without a session. Fixtures are the 2026-11-03 recordings (market-wide ones trimmed to October-December). Goldens added; help-stocks and completions-bash gain the two subcommands, MCP tools.json the two tools (regenerated with UPDATE_GOLDEN=1). The MCP docs counted 17 tools without stockbit_login; now 20. Claude-Session: https://claude.ai/code/session_01RqPPVeVDrnLoP7NUZmLRxY
2026-11-07 01:35:36 +00:00 · 2026-11-03 14:35:20 +07:00 · 2026-11-03 14:35:20 +07:00 · 43ff4aa433
commit 43ff4aa433
parent 8a1b29043c
55 changed files with 2026 additions and 34 deletions
--- a/web/src/content/docs/cli/reference.md
+++ b/web/src/content/docs/cli/reference.md
@ -68,6 +68,8 @@ Commands:
  quote        Get real-time stock quotes
  intraday     Today's session price by the minute (Stockbit)
  orderbook    Order book depth and foreign flow (Stockbit login)
+  actions      Dividends, rights, splits and other corporate actions of a stock (Stockbit login)
+  calendar     Upcoming and recent corporate actions across the market (Stockbit login)
  history      Get historical OHLC data
  technical    Run technical analysis on a stock
  growth       Run growth analysis on a stock
@ -223,6 +225,132 @@ Examples:
  idx -o json stocks orderbook TLKM | jq '.offers[0]'
 ```

+### `idx stocks actions`
+
+```text
+One IDX stock's corporate actions from your own Stockbit session (`idx stockbit login`), newest first: cash and stock dividends, bonus shares, rights issues, warrants, splits and reverse splits, shareholders' meetings, public exposes and tender offers (`--kind ipo` adds its IPO). Stockbit serves one kind per request, 1 s apart, so the first call takes about a second per kind; answers are cached for 6 hours.
+
+Usage: idx stocks actions [OPTIONS] <SYMBOL>
+
+Arguments:
+  <SYMBOL>
+          Single ticker symbol (e.g. BBCA)
+
+Options:
+      --kind <KINDS>...
+          Kinds to list (default: all but ipo)
+
+          Possible values:
+          - dividend:       Cash dividend
+          - stock-dividend
+          - bonus:          Bonus shares
+          - rights:         Rights issue (HMETD)
+          - warrant
+          - split:          Stock split
+          - reverse-split
+          - meeting:        Shareholders' meeting (RUPS)
+          - expose:         Public expose
+          - ipo
+          - tender
+
+  -o, --output <OUTPUT>
+          Output format [default: auto = table on a terminal, json when piped]
+
+          [possible values: auto, table, json, jsonl]
+
+      --no-color
+          Disable colored output
+
+  -q, --quiet
+          Suppress non-essential output
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --provider <PROVIDER>
+          Market data provider [default: general.provider, else msn]
+
+          [possible values: yahoo, msn, stockbit]
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+  idx stocks actions BBCA
+  idx stocks actions TLKM --kind dividend
+  idx -o json stocks actions BBRI --kind dividend,split | jq '.[0]'
+```
+
+### `idx stocks calendar`
+
+```text
+Corporate actions across IDX from your own Stockbit session (`idx stockbit login`), oldest first, dated within --from and --to (default: today and the next 30 days). An action's date is its cum date for dividends, bonuses, rights and splits, else the event's first day. Stockbit lists about a year back and what is announced ahead. One request per kind, 1 s apart; answers are cached for 6 hours.
+
+Usage: idx stocks calendar [OPTIONS]
+
+Options:
+      --from <FROM>
+          First day, YYYY-MM-DD. Default: today
+
+  -o, --output <OUTPUT>
+          Output format [default: auto = table on a terminal, json when piped]
+
+          [possible values: auto, table, json, jsonl]
+
+      --no-color
+          Disable colored output
+
+      --to <TO>
+          Last day, YYYY-MM-DD. Default: 30 days after --from (at most 366)
+
+      --kind <KINDS>...
+          Kinds to list (default: all)
+
+          Possible values:
+          - dividend:       Cash dividend
+          - stock-dividend
+          - bonus:          Bonus shares
+          - rights:         Rights issue (HMETD)
+          - warrant
+          - split:          Stock split
+          - reverse-split
+          - meeting:        Shareholders' meeting (RUPS)
+          - expose:         Public expose
+          - ipo
+          - tender
+
+  -q, --quiet
+          Suppress non-essential output
+
+  -v, --verbose...
+          Increase verbosity (-v, -vv)
+
+      --provider <PROVIDER>
+          Market data provider [default: general.provider, else msn]
+
+          [possible values: yahoo, msn, stockbit]
+
+      --offline
+          Run without network requests
+
+      --no-cache
+          Bypass local cache
+
+  -h, --help
+          Print help (see a summary with '-h')
+
+Examples:
+  idx stocks calendar
+  idx stocks calendar --kind dividend,rights
+  idx stocks calendar --from 2026-12-01 --to 2026-12-31 --kind meeting
+```
+
 ### `idx stocks history`

 ```text
--- a/web/src/content/docs/cli/stockbit.md
+++ b/web/src/content/docs/cli/stockbit.md
@ -75,6 +75,8 @@ idx stockbit login                    # paste the credentialStorage cookie
 idx stockbit status                   # logged in? when do the tokens expire?
 idx stocks orderbook BBCA             # depth, queued orders, foreign flow
 idx stocks orderbook BBRI --depth 5
+idx stocks actions BBCA               # dividends, splits, meetings, ...
+idx stocks calendar --kind dividend   # cum dates in the next 30 days
 idx --provider stockbit stocks quote BBCA                    # live, not delayed
 idx --provider stockbit stocks history BBCA --period 1y      # Stockbit's daily candles
 idx stockbit logout
@ -198,6 +200,7 @@ What the login adds:
 | `stocks orderbook` | `AUTHERROR` | every level with lots and queued orders, OHLC, value, trades; foreign buy/sell/net once Stockbit marks them current |
 | `stocks history` under `--provider stockbit` | Yahoo | Stockbit's daily candles for `5d` to `1y`; Yahoo for other windows |
 | `stocks intraday` | public page | public page |
+| `stocks actions`, `stocks calendar` | `AUTHERROR` | corporate actions: one stock's history, or the market's calendar |

 The order book is what Stockbit's own app shows. Outside trading it is the
 book as the market left it, and the output says so. Foreign buy, sell and net
@ -218,7 +221,7 @@ Stockbit. Use this for looking at a stock now and then, not for crawling the
 market or republishing prices. With your login, automated use is tied to your
 account: keep it human-paced.

-Over MCP, the same data comes from `get_intraday`, `get_orderbook` and
-`stockbit_status`, and from `get_quotes` and `get_price_history` when the
+Over MCP, the same data comes from `get_intraday`, `get_orderbook`,
+`get_corporate_actions`, `get_corporate_calendar` and `stockbit_status`, and from `get_quotes` and `get_price_history` when the
 server runs with `IDX_PROVIDER=stockbit`. The server never logs in; run
 `idx stockbit login` in a terminal.
--- a/web/src/content/docs/cli/stocks.md
+++ b/web/src/content/docs/cli/stocks.md
@ -46,6 +46,28 @@ value and trades, and foreign buy, sell and net once Stockbit marks them
 current (not during trading, when they lag a day). Without one it answers
 `AUTHERROR`. See [Stockbit](/cli/stockbit/#with-your-stockbit-login).

+## Corporate actions (Stockbit login)
+
+```bash
+idx stocks actions BBCA                       # newest first
+idx stocks actions TLKM --kind dividend
+idx stocks calendar                           # today and the next 30 days
+idx stocks calendar --kind dividend,rights --to 2026-12-31
+```
+
+`actions` lists one stock's cash and stock dividends, bonus shares, rights
+issues, warrants, splits and reverse splits, shareholders' meetings, public
+exposes and tender offers (`--kind ipo` adds its IPO). `calendar` lists them
+across the market between `--from` and `--to` (at most 366 days), including
+what is announced ahead. An action's date is its cum date for dividends,
+bonuses, rights and splits: buy by then to be entitled. For the others it is
+the event's first day. Dividends per share keep their decimals (`Rp 3.8`).
+
+Both need your Stockbit session and answer `AUTHERROR` without one. Stockbit
+serves one kind per request, 1 s apart, so a first call with every kind takes
+about ten seconds; answers are then cached for 6 hours. `--kind` asks for
+less.
+
 ## Company data

 | Command | What it shows |
--- a/web/src/content/docs/mcp/index.md
+++ b/web/src/content/docs/mcp/index.md
@ -5,9 +5,9 @@ description: idx-mcp serves idx's stock and ownership data to AI agents over MCP

 `idx-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io)
 server over stdio. It gives an agent the same data as the `idx` CLI, as
-[17 tools](/mcp/tools/) (plus an opt-in `ownership_sync`): quotes, today's
-session by the minute, the order book (with a Stockbit login), price
-history, screening, company data, analysis, comparison, broker summaries,
+[20 tools](/mcp/tools/) (plus an opt-in `ownership_sync`): quotes, today's
+session by the minute, the order book and corporate actions (with a Stockbit
+login), price history, screening, company data, analysis, comparison, broker summaries,
 bandarmology, foreign flow, and the KSEI ownership queries.

 It shares idx's [config, cache and ownership database](/start/config/#files-idx-keeps),
--- a/web/src/content/docs/mcp/tools.md
+++ b/web/src/content/docs/mcp/tools.md
@ -63,6 +63,25 @@ Company data for one IDX ticker: profile, financial statements, earnings, analys
 | `sections` | array of `profile` / `financials` / `earnings` / `sentiment` / `insights` / `news` | no | Sections to fetch (default: all). |
 | `symbol` | string | yes | IDX ticker, e.g. "BBCA". |

+## `get_corporate_actions`
+
+Corporate actions of one IDX stock from the user's own Stockbit session, newest first: `kind` (dividend, stock-dividend, bonus, rights, warrant, split, reverse-split, meeting, expose, ipo, tender), `date` (the cum date for dividends, bonuses, rights and splits, i.e. the last day to buy and be entitled; else the event's first day), `ex_date`, `record_date`, `pay_date`, and per kind `cash_per_share` (IDR, may have decimals), `ratio` {old, new} (1:5 split = 1 share becomes 5; 655:104 rights = 104 rights per 655 held), `factor` (price adjustment), `price` (rights, warrant exercise, tender or IPO price, IDR), `period` and `exercise` {start, end}, `shares`, `percentage_bps`, `time`, `venue`. Absent fields are omitted. One Stockbit request per kind (about 1 s each on a cold cache, then cached 6 hours). AUTHERROR means there is no session: call stockbit_status, then stockbit_login.
+
+| Input | Type | Required | Description |
+| --- | --- | --- | --- |
+| `kinds` | array of `dividend` / `stock-dividend` / `bonus` / `rights` / `warrant` / `split` / `reverse-split` / `meeting` / `expose` / `ipo` / `tender` | no | Kinds to list (default: every kind but "ipo"). Each kind is one request to Stockbit. |
+| `symbol` | string | yes | IDX ticker, e.g. "BBCA". |
+
+## `get_corporate_calendar`
+
+Corporate actions across IDX from the user's own Stockbit session, oldest first, dated from `from` to `to` (default today and the next 30 days): upcoming cum dates, meetings, exposes, rights, warrants, IPOs and tender offers, and the past year. Each item has the same fields as get_corporate_actions, with `symbol`. One Stockbit request per kind (about 1 s each on a cold cache, then cached 6 hours); pass `kinds` to ask for less. AUTHERROR means there is no session: call stockbit_status, then stockbit_login.
+
+| Input | Type | Required | Description |
+| --- | --- | --- | --- |
+| `from` | string | no | First day, YYYY-MM-DD (default today). |
+| `kinds` | array of `dividend` / `stock-dividend` / `bonus` / `rights` / `warrant` / `split` / `reverse-split` / `meeting` / `expose` / `ipo` / `tender` | no | Kinds to list (default: every kind). Each kind is one request to Stockbit. |
+| `to` | string | no | Last day, YYYY-MM-DD (default 30 days after `from`; at most 366 days). |
+
 ## `get_foreign_flow`

 Foreign investors' buying and selling of one IDX ticker, session by session (oldest first), with range totals; end of day. With `source` "ipot" (default): `foreign_buy_value`, `foreign_sell_value` and `foreign_net_value` in IDR across all boards, `value` traded, and `foreign_share_bps` (foreign share of trading); share counts, close and `non_regular_bps` are null, and `rounded` = true means one decimal of precision. With "idx": exact foreign share counts on the regular board, values estimated at the session's average price, the close, `change_bps` and `non_regular_bps`.