feat(client-generator): expose response headers via opt-in throw-mode envelope - #3002
Merged
Merged
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: cb58bfc 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
oxfmt requires continuation lines under a bullet to be indented; the tech-writer rewrite left two of them flush left. Co-authored-by: Cursor <cursoragent@cursor.com>
RomanHotsiy
reviewed
Aug 3, 2026
Shorten the changeset, coerce boolean response headers case-insensitively, and unwrap nullable header schemas so boolean|null / integer|null keep the inner coerce type instead of falling back to string. Co-authored-by: Cursor <cursoragent@cursor.com>
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
…esult Package-mode flat sugar generated before envelope typed every init parameter as RequestOptions. Treating that as an unknowable flag widened every call site to body|envelope after a runtime upgrade without regenerating. Co-authored-by: Cursor <cursoragent@cursor.com>
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit d2e2fdb. Configure here.
… coerce types
allOf: [{ $ref }] and $ref-to-allOf header schemas stayed as kind: ref in the
IR, so headerParseType fell through to string and skipped number/boolean
coercion. Resolve named schemas and peel metadata-only intersections when
planning envelope header types.
Co-authored-by: Cursor <cursoragent@cursor.com>
…methods expectTypeOf(...).toBeCallableWith resolves Parameters to never for ThrowMethod intersected with operationId, which broke tsc --noEmit in CI. Assert those call sites through real calls instead. Co-authored-by: Cursor <cursoragent@cursor.com>
DmitryAnansky
approved these changes
Aug 4, 2026
7 tasks
Marshevskyy
added a commit
that referenced
this pull request
Aug 6, 2026
…t emitters Carries PR #3002's throw-mode `{ envelope: true }` support over to the text template emitters, replacing the AST helpers the toolkit removal dropped.
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
5 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