feat(client-generator): expose response headers via opt-in throw-mode envelope - #3002
Open
adamaltman wants to merge 2 commits into
Open
feat(client-generator): expose response headers via opt-in throw-mode envelope#3002adamaltman wants to merge 2 commits into
adamaltman wants to merge 2 commits into
Conversation
… envelope
Throw-mode calls return only the parsed body, so declared response
headers (Pagination-Total, rate limits, Location) were unreachable
without switching to --error-mode result. Passing { envelope: true }
on a call now returns { data, headers, response }: headers is a typed
camelCase object built from the operation's declared success-response
headers with number/boolean coercion, and response is the raw Response
for anything undocumented.
Default call sites stay body-only via the EnvelopeResult conditional
type, pagination iterators and the TanStack Query/SWR wrappers exclude
and strip the option so cached data is always the plain body.
Co-authored-by: Cursor <cursoragent@cursor.com>
🦋 Changeset detectedLatest commit: 5b330c2 The changes in this PR will be included in the next version bump. This PR includes changesets to release 1 package
Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
Contributor
Contributor
Performance Benchmark (Lower is Faster)
|
JLekawa
reviewed
Aug 1, 2026
JLekawa
reviewed
Aug 1, 2026
Co-authored-by: Jacek Łękawa <164185257+JLekawa@users.noreply.github.com>
JLekawa
approved these changes
Aug 1, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What/Why/How?
What: Generated throw-mode clients can now return declared response headers. Passing
{ envelope: true }on a call returns{ data, headers, response }instead of the parsed body alone.Why: Throw mode (the default) returns only the body, so OpenAPI-declared success-response headers —
Pagination-Total, rate limits,Location— were unreachable without switching the whole client to--error-mode result.How:
successResponseHeadersbuilt from the selected success response (including bodyless responses like201+Location); referenced scalar header schemas are dereferenced.executereturns the envelope whenenvelope === true; header values are coerced tonumber/booleanper schema (blank/unparsable values are omitted, never0). Pagination iterators strip the flag so page pointers keep resolving against the body.EnvelopeResultconditional type keeps default call sites body-only (non-breaking) and narrows toEnvelope<…>only for a literalenvelope: true; a statically unknowable flag widens to the union. Result-mode clients ignore the option (they already returnresponse).Pagination-Total→paginationTotal,3D-Secure→_3dSecure) with deterministic collision suffixes;<Op>ResponseHeadersaliases are emitted; required headers are required properties (the type trusts the description, like body types).Omit<RequestOptions, 'envelope'>and the forwarded calls strip the flag at runtime, so cached data is always the plain body. This also fixes a latent bug where grouped-style no-input SWR hooks passedinitin the args slot.Reference
Closes #3001
Testing
EnvelopeResulttyping (993 client-generator tests).envelope.test.ts) generates a client from a response-headers fixture and strict-tsc-checks envelope and default call sites; the TanStack e2e pinsuseQuery(...).datato the plain body type.generator-contracte2e failure in the local environment only; passes on CI from main).Check yourself
Security
Made with Cursor