fix(api): correct openapi.yaml drift from actual v17 responses [BUG-112]

[Morenikeoa]

Bug

openapi.yaml has drifted from the actual route implementations in four ways:

1. Missing path: /candles/{slab} (src/routes/candles.ts) is a live route with no entry in the spec at all.
2. Wrong types in MarketWithStats/MarketStats: lastPrice/markPrice/indexPrice/fundingRate/lastCrankSlot (and snake_case equivalents) are documented as string, but markets.ts returns them as raw numeric Postgres columns — confirmed as JS numbers via the existing mocks in tests/routes/markets.test.ts (e.g. last_price: 50000, not "50000").
3. Wrong types in FundingHistoryEntry: slot/priceE6 documented as string, but funding.ts passes through h.slot/h.price_e6 unmodified — same numeric-column pattern, confirmed via tests/routes/funding.test.ts mocks (e.g. slot: 123456789, price_e6: 50000000000).
4. Wrong nullability in MarketDetails.engine: documented as a non-nullable object, but markets.ts explicitly returns engine: null for v17 market-group accounts (v17 engine state moved to per-portfolio storage, queried via /markets/{slab}/stats instead) — a null here is invalid against a non-nullable object schema for any strict validator or generated client.

Fields that are genuinely large/precision-sensitive on-chain values stored as Postgres numeric (totalOpenInterest, netLpPos, lpSumAbs, etc.) were left as string — those really do come back as strings to avoid float precision loss, and were already documented correctly.

Fix

• Added the /candles/{slab} path with a new CandlesResponse schema matching the route's actual TradingView-UDF-style response shape, and a Candles tag.
• Changed the 5 mistyped numeric fields in MarketWithStats and MarketStats from string to number/integer (with nullable: true where the route can return null).
• Changed FundingHistoryEntry.slot to integer and .priceE6 to number.
• Added nullable: true + an explanatory description to MarketDetails.engine.

Test plan

This is a documentation-only change to a static YAML file served as-is by docs.ts — there's no associated runtime logic or existing test suite to update/revert-and-confirm against. Verified instead via:

• npx js-yaml openapi.yaml — parses cleanly, no syntax errors.
• Wrote a one-off script to walk every $ref in the parsed document and confirm it resolves — all 81 refs (including the new ones added here) resolve correctly.
• Cross-checked every changed field's actual runtime type against the corresponding route source and its existing test mocks (markets.test.ts, funding.test.ts) before changing its documented type.
• Full test suite still passes (294/295 — the 1 pre-existing failure is unrelated to this change, in adl.test.ts); tsc --noEmit clean (expected, since this PR touches no .ts files).

[vercel]

@Princessdada is attempting to deploy a commit to the Khubair Nasir's projects Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Warning

Review limit reached

@Morenikeoa, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 47 minutes and 24 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6e4b61c3-6c80-419c-8ae7-bda7832521b9

📥 Commits

Reviewing files that changed from the base of the PR and between b2751f4 and efc32fd.

📒 Files selected for processing (1)

• openapi.yaml

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dcccrypto]

Independent verification — not an approval (QA/Security own that). I checked the corrected spec against the actual route rather than taking it on trust. It's accurate.

A spec-only PR can't be mutation-tested, so I verified the claims directly against src/routes/candles.ts:

spec says	route does	✓
enum: ["1","5","15","60","240","1D"]	RES_TO_SECONDS keys are exactly those six	✓
default: "1"	c.req.query("resolution") ?? "1"	✓
"1D" buckets into whole days	"1D": 24 * 60 * 60	✓
s: enum [ok, no_data, error]	UdfResponse.s: "ok" | "no_data" | "error"	✓
errmsg present only when s: "error"	{ s: "error", errmsg } on the 400 path	✓
400 documented	return c.json({s:"error",...}, 400) for unsupported resolution	✓
parallel arrays t/o/h/l/c/v, Unix seconds	emptyResponse / bucketCandles build exactly that	✓

No residual drift found. The no_data case in particular is documented with an accurate description ("for an empty range"), which is the response a brand-new market returns most often — easy to omit, and it isn't omitted.

(Method note on myself: my first pass grepped only the /candles/{slab} path block and I saw no no_data, which looked like a gap. It's in components/schemas/CandlesResponse. Checked before reporting — a partial grep is not a finding.)

The one real gap: nothing stops it re-drifting

openapi.yaml is hand-maintained, and this PR fixes the current drift without adding anything that would catch the next one. BUG-112 is a recurrence-shaped bug: it will come back the next time someone edits a route and not the spec, and it'll be invisible until a consumer breaks.

Cheapest guard that would actually bind — a test asserting the spec and the code agree on the enum:

import { load } from "js-yaml";
const spec = load(readFileSync("openapi.yaml", "utf8")) as any;
const specEnum = spec.paths["/candles/{slab}"].get.parameters
  .find((p: any) => p.name === "resolution").schema.enum;
expect(specEnum.sort()).toEqual(Object.keys(RES_TO_SECONDS).sort());

That pins the one field most likely to drift (adding a resolution to RES_TO_SECONDS and forgetting the spec) and fails loudly when it does.

Not blocking — the correction itself is right, and I'd take it as-is. Flagging because a spec fix without a drift guard tends to be the same fix again in three months.