feat(twse): add current cash-dividend calendar as a bounded roadmap slice

[luokerenx4]

Taiwan data callers can query prices and valuation metrics but cannot use the existing dividend calendar model with the TWSE provider. #406 contains a much larger roadmap. This Draft proposes one bounded slice: current TWSE listed-security cash-dividend announcements through the existing SDK and compatibility router.

flowchart LR
  A[Caller selects TWSE dividend calendar] --> B[Existing calendar SDK and router]
  B --> C[Before: provider has no calendar fetcher - blocked]
  B --> D[After: add fetcher to existing TWSE provider]
  D --> E[Official TWSE announcement snapshot]
  E --> F[Keep cash-dividend events and normalize ROC dates]
  F --> G[Existing dividend calendar rows]
  E --> H[Pure rights events excluded]

Loading

Reuses CalendarDividend, the existing provider registry/router, Taiwan symbol/date/number helpers and standard request transport. No provider framework, MCP bridge, new model, cache, AI tool set or board is added. The only new implementation is the missing provider adapter; discovery describes its bounded coverage.

Call the existing SDKEquityClient.getCalendarDividend({ provider: 'twse', start_date: '2026-10-01', end_date: '2026-10-31' }), or /api/market-data-v1/equity/calendar/dividend?provider=twse&start_date=2026-10-01&end_date=2026-10-31.

Source: official TWSE announcement data and official OpenAPI schema. Cash events (息) and combined events (權息) enter the existing dividend model. Pure rights issues (權) do not. The adapter normalizes .TW identities and ROC dates, applies inclusive date bounds, rejects invalid windows, omits unusable date/symbol records and leaves undisclosed cash amounts and unavailable payment/record dates null.

Tradeoff and deferred roadmap:

• This is the current announcement snapshot for TWSE-listed securities, including listed ETFs. It is not a historical series, guaranteed complete future calendar, or TPEx .TWO coverage. An empty historical window does not prove there were no dividends.
• The existing default TraderHub calendar board keeps its provider. This slice requires an explicit TWSE SDK/router request; a new Taiwan board or agent command is not introduced.
• Defer pure rights/stock distributions, TPEx calendar, monthly revenue, chip-flow, margin/SBL, notice/disposal lists, foreign ownership, TAIFEX/night-session data and ADR-derived metrics. Those require their own field/unit, timestamp or cross-market identity decisions. TWSE/TPEx vendor — high-value data gaps for AI trading (chip-flow, overnight leading indicators, derivatives) #406 remains a roadmap anchor; this PR does not claim to resolve it in full.

Validation:

• All six TWSE provider spec files passed: 16 tests, including six new calendar tests for mappings, inclusive bounds, bad dates/symbols, zero/null amounts, real router→executor registration with mocked transport, and upstream failure propagation.
• Root and opentypebb TypeScript checks passed; git diff --check passed.
• Live public read on 2026-10-02 through the actual executor: 52 dividend events, from 2026-10-05 through 2026-10-28; exact 2026-10-05 window returned three. The official raw snapshot had 57 events including rights-only entries. No key or user data was used.
• Direct Node transport initially returned ECONNREFUSED; repeating with the environment's proxy enabled succeeded. No product proxy settings changed.
• No UI change, trade, brokerage mutation, release or deployment was performed. Live availability beyond this observation remains provider-dependent.

Based on dev 4813c1b89d8c151a7853f717e31629f3ec1f3b4c, independent of the other issue PRs. No merge or issue closure requested. Includes four files: provider registration/description, adapter, tests and the existing owner guide.

Pushed head fc566cd5a342f366ad0f92fe3a4e7e5d56db582b verified against the remote branch; GitHub clean-build passed on this SHA.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
openalice-demo	Ready	Preview	Oct 2, 2026 10:43am UTC