docs: document OrderBook bids/asks sort convention

[Nexory]

The OrderBookSchema in packages/bindings/src/clob/order-book.ts:18-19 defines bids and asks as z.array(OrderBookLevelSchema) without documenting the sort order the CLOB API returns.

The convention is non-obvious — calculateBuyMarketPrice in packages/client/src/actions/orders/estimate.ts:191 walks positions from the end (positions.length - 1 down to 0) to start from the cheapest level, which implies asks are returned highest-price-first. The analogous calculateSellMarketPrice does the same on bids, implying bids are returned lowest-price-first.

This is non-obvious for users writing custom orderbook-walking logic outside the provided calculateMarketPrice helper, and easy to get wrong silently.

Suggested fix

Mirror the py-sdk fix from #42 (resolved by Polymarket/py-sdk#45). Either Zod-level descriptions via .describe():

export const OrderBookSchema = z
  .object({
    // ...
    bids: z.array(OrderBookLevelSchema)
      .describe('Bid levels in ascending price order, lowest bid first.'),
    asks: z.array(OrderBookLevelSchema)
      .describe('Ask levels in descending price order, highest ask first.'),
    // ...
  })

…or JSDoc-style comments on the inferred OrderBook type for IDE hover support. JSDoc precedent already exists in packages/bindings/src/clob/signature-type.ts.

Happy to send a small PR once external PRs are accepted.

[cesarenaldi]

#72