feat(http): validate API responses at runtime with valibot instead of blind casts

[Andy00L]

Validate API responses on the run paths against valibot schemas at the HTTP client, instead of blind as T casts.

• New src/lib/response-schemas.ts: looseObject schemas for the run-path payloads (trigger, rerun, batch rerun, batch fresh, get run, list runs); unknown extra keys are preserved so additive server changes stay non-breaking.
• RequestOptions gains an optional schema field; when present, requestWithMeta runs v.safeParse on the OK-path JSON. Shape drift now surfaces as a typed INTERNAL envelope naming the request path and the first mismatched field paths (never echoing the body), instead of undefined output or an opaque crash downstream.
• Wired by the typed run helpers only (triggerRun, triggerRunWithMeta, triggerRerun, triggerBatchRerun, triggerBatchRunFresh, getRun, listTestRuns); generic get/post/... callers are unchanged and stay opt-in.
• Uses the valibot dependency already present in the project; no new dependency.
• Verified against current main: typecheck, build, full suite, lint and prettier clean.

Closes #102

Discord: interferon0

Summary by CodeRabbit

• New Features

  • Added response validation for run-related API requests.
  • Supports typed schemas for HTTP requests and responses.
  • Preserves additional fields returned by the server for forward compatibility.
  • Provides detailed validation errors when response data does not match expectations.

• Bug Fixes

  • Prevents malformed API responses from being silently accepted as valid data.
  • Added coverage for schema validation, compatible response changes, and unvalidated requests.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Valibot schemas for run-related HTTP responses, validates selected successful responses in HttpClient, reports schema drift through capped INTERNAL ApiError details, and adds tests for valid, invalid, additive, and schemaless response handling.

Changes

Runtime response validation

Layer / File(s)	Summary
Run response schema contracts src/lib/response-schemas.ts	Adds loose Valibot schemas for run, trigger, rerun, batch, list, and identity response envelopes with nullable and optional wire fields.
HTTP client schema validation and endpoint wiring src/lib/http.ts	Makes request options generic, validates configured successful JSON responses with Valibot, caps reported issues, raises INTERNAL envelopes on mismatches, and wires schemas into run-related endpoints.
Schema and HTTP boundary coverage src/lib/response-schemas.test.ts	Tests additive fields, required-field failures, typed validation errors, schemaless responses, and queued trigger responses.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant HttpClient
  participant Valibot
  participant ApiError
  HttpClient->>Valibot: Validate successful JSON body
  Valibot-->>HttpClient: Parsed output or issues
  HttpClient->>ApiError: Return INTERNAL envelope on mismatch

Loading

Possibly related PRs

• TestSprite/testsprite-cli#166: Both changes update successful-response handling in src/lib/http.ts to return typed errors for response-body failures.

Suggested reviewers: ruili-testsprite, zeshi-du

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: runtime API response validation with Valibot replacing blind casts.
Linked Issues check	✅ Passed	The PR adds runtime Valibot schemas, wires them into run-related HTTP requests, preserves unknown fields, and tests valid and drifted responses as requested.
Out of Scope Changes check	✅ Passed	The changes stay focused on HTTP response validation, schema definitions, and tests, with no obvious unrelated additions.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

src/lib/response-schemas.test.ts (1)

93-104: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Extend schema tests to the remaining wired schemas.

Only RUN_RESPONSE_SCHEMA (positive+negative) and TRIGGER_RUN_RESPONSE_SCHEMA (positive-only) are directly tested here. RERUN_RESPONSE_SCHEMA, BATCH_RERUN_RESPONSE_SCHEMA, BATCH_RUN_FRESH_RESPONSE_SCHEMA, and LIST_RUNS_RESPONSE_SCHEMA are all wired into HttpClient in this PR but have no direct parse test, so a regression in any of those four schemas would only surface indirectly. Mirroring the existing RUN_RESPONSE_SCHEMA pattern (valid payload + one missing-required-field case) for each would be low effort and directly serves the issue's stated goal of testing valid/drifted responses for the run-related wire types.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/lib/response-schemas.test.ts` around lines 93 - 104, The response-schema
tests currently omit direct coverage for four schemas. Extend the test suite
with valid parse cases and missing-required-field negative cases for
RERUN_RESPONSE_SCHEMA, BATCH_RERUN_RESPONSE_SCHEMA,
BATCH_RUN_FRESH_RESPONSE_SCHEMA, and LIST_RUNS_RESPONSE_SCHEMA, mirroring the
existing RUN_RESPONSE_SCHEMA test pattern while retaining the current
TRIGGER_RUN_RESPONSE_SCHEMA coverage.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/lib/response-schemas.test.ts`:
- Around line 93-104: The response-schema tests currently omit direct coverage
for four schemas. Extend the test suite with valid parse cases and
missing-required-field negative cases for RERUN_RESPONSE_SCHEMA,
BATCH_RERUN_RESPONSE_SCHEMA, BATCH_RUN_FRESH_RESPONSE_SCHEMA, and
LIST_RUNS_RESPONSE_SCHEMA, mirroring the existing RUN_RESPONSE_SCHEMA test
pattern while retaining the current TRIGGER_RUN_RESPONSE_SCHEMA coverage.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 06983a61-e073-4900-aba6-05930bce5a38

📥 Commits

Reviewing files that changed from the base of the PR and between 2708a40 and 21ceb10.

📒 Files selected for processing (3)

• src/lib/http.ts
• src/lib/response-schemas.test.ts
• src/lib/response-schemas.ts