Fix/relax schema validation

[subtleGradient]

This pull request focuses on improving the robustness and forward compatibility of the API response validation by relaxing the strictness of the zod schemas. The main change is the addition of .passthrough() to all relevant zod object schemas, allowing unexpected or extra fields in API responses to be accepted without causing validation errors. This ensures that the SDK will not break if the API introduces new fields in the future. The changes also update error handling and add new tests to verify the relaxed schema behavior.

Schema Relaxation and Forward Compatibility

• Added .passthrough() to all zod object schemas in src/chat/schemas.ts, src/completion/schemas.ts, src/schemas/error-response.ts, and src/schemas/image.ts to allow extra fields in API responses and prevent validation failures when the API returns unexpected fields. This affects chat, completion, error, and image response schemas. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

Error Handling Improvements

• Updated error handling in src/chat/index.ts and src/completion/index.ts to consistently extract error data from API responses and pass only the relevant fields to the APICallError, improving clarity and maintainability. [1] [2]

Testing and Validation

• Added new tests in src/chat/file-parser-schema.test.ts to verify that the relaxed schemas can parse real and extra fields in file annotations, ensuring the schemas work with current and future API responses.
• Updated error response tests in src/schemas/error-response.test.ts to include extra metadata fields, verifying that .passthrough() works as intended. [1] [2]

Documentation

• Added a changeset file .changeset/relax-schemas.md documenting the schema relaxation and its benefits for forward compatibility.

Plugin Configuration Example

• Updated an end-to-end test in e2e/pdf-blob/index.test.ts to show usage of the FileParser plugin with a specific OCR engine, demonstrating plugin extensibility.

[Copilot]

Pull Request Overview

This PR enhances the robustness and forward compatibility of API response validation by adding .passthrough() to all zod object schemas. This allows the SDK to accept extra fields from API responses that aren't explicitly defined in the schemas, preventing validation errors when the API evolves by adding new fields.

Key changes:

• Added .passthrough() to all zod object schemas across chat, completion, error, image, reasoning, and provider metadata schemas
• Updated error handling in chat and completion modules to properly extract and pass error data to APICallError
• Added comprehensive tests to verify the relaxed schema behavior handles both current and extra API fields

Reviewed Changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/schemas/reasoning-details.ts	Added .passthrough() to CommonReasoningDetailSchema for forward compatibility
src/schemas/provider-metadata.ts	Added .passthrough() to all nested objects in OpenRouterProviderMetadataSchema including usage details and cost objects
src/schemas/image.ts	Added .passthrough() to ImageResponseSchema and nested image_url object
src/schemas/error-response.ts	Added .passthrough() to OpenRouterErrorResponseSchema and nested error object
src/schemas/error-response.test.ts	Updated tests to verify extra fields like metadata and user_id are preserved through .passthrough()
src/completion/schemas.ts	Added .passthrough() to all nested objects in OpenRouterCompletionChunkSchema including choices, logprobs, and usage details
src/completion/index.ts	Improved error handling by extracting error data to a typed variable before passing to APICallError
src/chat/schemas.ts	Added .passthrough() to all nested objects in chat completion schemas including messages, tool calls, annotations, and logprobs
src/chat/index.ts	Improved error handling by extracting error data to a typed variable before passing to APICallError
src/chat/file-parser-schema.test.ts	Added new tests verifying the schemas correctly parse responses with extra API fields like native_finish_reason and refusal
e2e/pdf-blob/index.test.ts	Added plugin configuration example demonstrating the FileParser plugin with OCR engine specification
.changeset/relax-schemas.md	Added changeset documenting the schema relaxation changes

Comments suppressed due to low confidence (1)

src/schemas/reasoning-details.ts:24

• Using .extend() with .shape on a schema that has .passthrough() applied will lose the passthrough behavior. When you use .shape, it extracts only the defined fields and discards modifiers like .passthrough(). The resulting extended schemas (ReasoningDetailSummarySchema, ReasoningDetailEncryptedSchema, ReasoningDetailTextSchema) will not allow extra fields, defeating the purpose of this PR. Instead, use .merge() or reapply .passthrough() after extending.

export const ReasoningDetailSummarySchema = z
  .object({
    type: z.literal(ReasoningDetailType.Summary),
    summary: z.string(),
  })
  .extend(CommonReasoningDetailSchema.shape);

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.