docs: document watchOrderBook limit examples

[999axel999]

Summary

• Document the optional limit argument for watchOrderBook and watchOrderBooks.
• Update Python, JavaScript, and WebSocket examples to pass the depth limit through the existing API shape.
• Correct TypeScript API reference examples to use the numeric limit argument and an array for watchOrderBooks.

Closes #163

Tests

• git diff --check
• Select-String verification for updated limit parameter rows and corrected examples

Prepared with local automation assistance; final submission remains human-approved.

[realfishsam]

PR Review: PASS (NOT VERIFIED)

What This Does

Adds the missing limit parameter row to the watchOrderBook and watchOrderBooks API reference tables, updates basic usage examples in both MDX docs to demonstrate limit, and fixes two broken TypeScript examples in sdks/typescript/API_REFERENCE.md that were passing incorrect argument types.

Blast Radius

Documentation only — three files changed, zero code changes. No exchange logic, no SDK behavior, no generated files, no OpenAPI schema, no server routes touched.

Consumer Verification

Before (base branch — sdks/typescript/API_REFERENCE.md):

// watchOrderBook — object literal passed as limit (wrong type)
await exchange.watchOrderBook("12345", { limit: 10 })

// watchOrderBooks — string passed as ids (wrong type), object as limit (wrong type)
await exchange.watchOrderBooks("12345", { limit: 10 })

After (PR branch):

await exchange.watchOrderBook("12345", 10)
await exchange.watchOrderBooks(["12345"], 10)

Server could not be started in this environment due to a pre-existing build failure (tsconfig.json missing rootDir, unrelated to this PR — the error is present on main before any PR changes). Consumer verification via live HTTP calls was therefore skipped. Correctness was established by static analysis against the implementation.

Test Results

• Build: FAIL (pre-existing tsconfig.json error on main, unrelated to this PR)
• Unit tests: NOT RUN (build prerequisite)
• Server starts: NOT RUN
• E2E smoke: NOT RUN

Findings

1. All three example corrections are verified correct against the implementation.

   • watch-order-book.mdx Python example: watch_order_book("OUTCOME_ID", limit=10) matches client.py:1736 signature def watch_order_book(self, outcome_id, limit: Optional[int] = None). ✓
   • watch-order-book.mdx JS example: watchOrderBook("OUTCOME_ID", 10) matches client.ts:1465 signature async watchOrderBook(outcomeId: string | MarketOutcome, limit?: number). ✓
   • watch-order-books.mdx Python example: watch_order_books(ids, limit=10) matches client.py:1832 signature def watch_order_books(self, outcome_ids, limit: Optional[int] = None). ✓
   • watch-order-books.mdx JS example: watchOrderBooks(ids, 10) matches client.ts:1527 signature async watchOrderBooks(outcomeIds: (string | MarketOutcome)[], limit?: number). ✓
   • WebSocket "args": ["OUTCOME_ID", 10] for watchOrderBook: ws-handler.ts:117 extracts args[0] as symbol, then exchange[method](...args) spreads all args including args[1] as the limit. ✓
   • WebSocket "args": [["OUTCOME_ID_1", ...], 10] for watchOrderBooks: ws-handler.ts:160 extracts args[0] as the ids array, then exchange[method](...args) spreads. ✓

2. Pre-existing doc defect, not introduced by this PR (informational): Both WebSocket examples (watch-order-book.mdx and watch-order-books.mdx) omit the required exchange field from the subscribe message. ws-handler.ts:259 returns "Missing required fields: id, action, exchange" if this field is absent, so the raw WebSocket examples as documented would fail. The PR does not make this worse and does not need to fix it in scope, but it is a latent inaccuracy worth a follow-up.

PMXT Pipeline Check

• Field propagation (3-layer): N/A (no new fields)
• OpenAPI sync: N/A (no interface changes)
• Financial precision: N/A
• Type safety: N/A (docs only)
• Auth safety: N/A

Semver Impact

patch — documentation corrections only, no API surface change.

Risk

Minimal. Both MDX docs still show watchOrderBook and watchOrderBooks examples elsewhere in the "Use cases" sections without limit, which is fine since it is optional. The only residual inaccuracy is the pre-existing missing exchange field in the raw WebSocket JSON examples, which exists on both sides of this diff.

---

Generated by Claude Code