@redocly/cli 2.60.0 → 2.62.0

package/lib/eject-assets/skills/client-generators/SKILL.md

@@ -96,29 +96,30 @@ discriminated union on `kind`: `scalar`, `array`, `object`, `record`, `ref`,
 
 ## Helpers (import from '@redocly/client-generator')
 
-| Helper                                                  | Use                                                                                                                              |
-| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `flattenAllOf(schema, model)`                           | The merged property view of allOf compositions — languages without intersection types render this.                               |
-| `deref(schema, model)`                                  | Follow a `ref` chain to the schema it names (cycle-guarded).                                                                     |
-| `jsonSuccessSchema(op)` / `sseResponse(op)`             | The primary JSON success schema; the `text/event-stream` response when the operation streams.                                    |
-| `isMultipartBody(op)`                                   | Whether the request body is multipart.                                                                                           |
-| `isBinaryContentType(contentType)`                      | Whether a body of this content type is bytes (archives, PDF, images, media) — decode it as a Blob, not JSON or text.             |
-| `serverUrlParts(server)`                                | A server-URL template as literal/variable parts, ready for any concatenation syntax.                                             |
-| `securityRequirements(op, model)`                       | The operation's security as OR-alternatives of AND-sets, denormalized against the declared schemes.                              |
-| `paginationItemSchema(pageSchema, itemsPointer, model)` | The raw element schema behind a pagination rule's `items` pointer — a `ref` element keeps its name.                              |
-| `discriminatorCases(schema, model)`                     | `{ property, cases }` dispatch table for discriminated unions.                                                                   |
-| `isNullable(schema)` / `unwrapNullable(schema)`         | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                    |
-| `enumValues(schema)`                                    | Values plus SCREAMING_SNAKE member-name suggestions.                                                                             |
-| `headerCoerceType(schema, model)`                       | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                 |
-| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                          |
-| `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter. |
-| `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                               |
-| `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                             |
-| `schemaAtPointer(schema, pointer, model)`               | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type. |
-| `paginationRuleFor(op, config)`                         | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                   |
-| `renderReferencePage(model, options)`                   | The Markdown reference page a generator's `docs` hook returns — your `sample` hook supplies its call snippets.                   |
-| `NotSupportedError`                                     | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                |
-| `AUTHORING_HELPER_NAMES`                                | The list of the above (introspection).                                                                                           |
+| Helper                                                  | Use                                                                                                                                  |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `flattenAllOf(schema, model)`                           | The merged property view of allOf compositions — languages without intersection types render this.                                   |
+| `deref(schema, model)`                                  | Follow a `ref` chain to the schema it names (cycle-guarded).                                                                         |
+| `jsonSuccessSchema(op)` / `sseResponse(op)`             | The primary JSON success schema; the `text/event-stream` response when the operation streams.                                        |
+| `isMultipartBody(op)`                                   | Whether the request body is multipart.                                                                                               |
+| `isUntypedMultipartBody(op)`                            | Whether the request body is multipart with a schema that is neither an object nor a `$ref`, so the caller supplies the encoded body. |
+| `isBinaryContentType(contentType)`                      | Whether a body of this content type is bytes (archives, PDF, images, media) — decode it as a Blob, not JSON or text.                 |
+| `serverUrlParts(server)`                                | A server-URL template as literal/variable parts, ready for any concatenation syntax.                                                 |
+| `securityRequirements(op, model)`                       | The operation's security as OR-alternatives of AND-sets, denormalized against the declared schemes.                                  |
+| `paginationItemSchema(pageSchema, itemsPointer, model)` | The raw element schema behind a pagination rule's `items` pointer — a `ref` element keeps its name.                                  |
+| `discriminatorCases(schema, model)`                     | `{ property, cases }` dispatch table for discriminated unions.                                                                       |
+| `isNullable(schema)` / `unwrapNullable(schema)`         | Detect and strip `null` union members (`Optional[T]`, pointers, `Option<T>`).                                                        |
+| `enumValues(schema)`                                    | Values plus SCREAMING_SNAKE member-name suggestions.                                                                                 |
+| `headerCoerceType(schema, model)`                       | Response-header coerce hint (`integer`/`number`/`boolean`/`string`) through refs, nullables, and allOf wrappers.                     |
+| `casing` / `identifierFor(name, { style, reserved })`   | camel/pascal/snake/screaming; keyword-safe identifiers (`RESERVED_WORDS.python/go/typescript` shipped).                              |
+| `uniqueIdentifiers(names, { style, reserved, taken })`  | The same, made unique among themselves and among names you already took — for a signature that takes one argument per parameter.     |
+| `Printer`                                               | Indentation-aware text builder — no manual whitespace bookkeeping.                                                                   |
+| `docText(description)`                                  | Description as trimmed lines for any comment syntax.                                                                                 |
+| `schemaAtPointer(schema, pointer, model)`               | Resolve an RFC 6901 JSON pointer over a schema (through refs and allOf) — e.g. a pagination `items` pointer to its element type.     |
+| `paginationRuleFor(op, config)`                         | The pagination rule that applies to an operation (per-op config > extension > fitting convention), normalized.                       |
+| `renderReferencePage(model, options)`                   | The Markdown reference page a generator's `docs` hook returns — your `sample` hook supplies its call snippets.                       |
+| `NotSupportedError`                                     | Throw it to reject an option the generator can't honor — the CLI prints the message as a user error, not a crash.                    |
+| `AUTHORING_HELPER_NAMES`                                | The list of the above (introspection).                                                                                               |
 
 Worked example: the built-in `python` generator
 (`packages/client-generator/src/generators/python/index.ts` in the Redocly CLI repo) is

package/lib/eject-assets/skills/go-generator/SKILL.md

@@ -55,6 +55,17 @@ runtime. Go ≥ 1.21, standard library only — zero dependencies.
   parameters (Go has no defaults — the doc comment states the spec default), so templated
   base URLs need no manual string building. The client's baked default stays `servers[0]`
   with variable defaults substituted.
+- **Stream bodies pass through.** For an untyped `multipart/form-data` operation
+  (`isUntypedMultipartBody` from the toolkit: a schema that is neither an object nor a
+  `$ref`) or a binary operation (`isBinaryContentType`), the body argument is `any` and
+  the runtime sorts it out (`multipartBody` / `binaryBody`): an `io.Reader` is the
+  request body as is, with no `io.ReadAll` and exactly one attempt (a consumed reader
+  cannot be replayed, whatever the retry policy says); a `[]byte` or a `string` is sent as
+  bytes, not JSON-marshalled, and stays replayable, so retries stay; a map or struct body
+  of an untyped multipart operation keeps the `toMultipart` path. The description's (or
+  the multipart boundary's) `Content-Type` is applied only when the caller set none, so a
+  forwarded boundary survives; that rule holds for every operation. The per-attempt
+  timeout still applies. Typed multipart bodies are unaffected.
 - **Parity surface:** auth, retries with `Retry-After` + jittered backoff, per-attempt
   `context.WithTimeout`, idempotency keys, middleware, pagination (`<Op>Pages`/`<Op>Items`
   as `func(yield func(T, error) bool)` — `range`-over-func needs Go ≥ 1.23; 1.21 calls

package/lib/eject-assets/skills/php-generator/SKILL.md

@@ -76,6 +76,22 @@ extension — zero Composer dependencies. The namespace derives from the API tit
   to the spec's defaults (`Servers::production(organizationId: 'org_x')`), so templated
   base URLs need no manual string building. The client's baked default stays `servers[0]`
   with variable defaults substituted.
+- **Stream bodies pass through.** For an untyped `multipart/form-data` operation
+  (`isUntypedMultipartBody` from the toolkit: a schema that is neither an object nor a
+  `$ref`) or a binary operation (`isBinaryContentType`), the body is `mixed` and the
+  runtime sorts it out (`multipartBody` / `binaryBody`): a stream `resource` is uploaded
+  by curl in chunks (`CURLOPT_UPLOAD` + `CURLOPT_INFILE`, the method kept by
+  `CURLOPT_CUSTOMREQUEST`), never read into a string, in exactly one attempt, whatever
+  the retry policy says (the default is three attempts for any method), because a
+  consumed stream cannot be replayed. `CURLOPT_INFILESIZE` is set only when the stream is
+  seekable AND `fstat` returns an array (the bytes left from the current position);
+  `php://input`, pipes, and wrappers without `stream_stat` go chunked. A `string` body of
+  either operation is sent raw, not `json_encode`d; any other binary-operation value is
+  still `json_encode`d; an `array` body of an untyped multipart operation keeps the
+  `toMultipart` path. The caller's `Content-Type` wins over the description's or the
+  multipart boundary's, matched case-insensitively in `send` so the header is never sent
+  twice; that rule holds for every operation. The whole-request curl timeout still
+  applies (`timeout: null` disables it). Typed multipart bodies are unaffected.
 - **Parity surface:** auth, retries with `Retry-After` + jittered backoff, per-attempt
   curl timeouts, middleware callables, pagination (`<op>Pages()` / `<op>Items()` as
   `\Generator`s), SSE (`iterSse` over a curl_multi pump), multipart.

package/lib/eject-assets/skills/python-generator/SKILL.md

@@ -82,6 +82,19 @@ One self-contained `<stem>.py`: typed dataclass models, a sync `Client` and an a
   the spec's defaults (`Servers.production(organization_id="org_x")`), so templated base
   URLs need no manual string building. The client's baked default stays `servers[0]`
   with variable defaults substituted.
+- **Stream bodies pass through.** For an untyped `multipart/form-data` operation
+  (`isUntypedMultipartBody`) or a binary operation (`isBinaryContentType`), the body
+  argument is `Any`, and a body that is `bytes`/`bytearray`, a `str`, a
+  file-like object (a callable `.read`), or an iterator/async iterator of bytes goes to httpx
+  `content=`, never through `json=` or `to_multipart`; a `dict` body of an untyped
+  multipart operation keeps the `to_multipart` path. The runtime sets the operation's
+  declared content type only when the caller set none (matched case-insensitively), and
+  never for a multipart body, whose boundary is the caller's. A body that cannot be
+  replayed (a file-like object or iterator, as opposed to `bytes` or `str`) is sent in
+  exactly one attempt, whatever the retry policy says. The per-attempt `timeout` still
+  applies. Both the sync and the async `send` behave the same. Typed multipart bodies
+  are unaffected: they go straight to `to_multipart` and never through stream detection,
+  so a model field named `read` cannot turn one into a raw upload.
 - **Parity surface:** auth (bearer/basic/apiKey), retries with `Retry-After` + jittered
   backoff, timeouts, idempotency keys, middleware, pagination (`<op>_pages()` /
   `<op>_items()` + `aiter` mirrors), SSE (`iter_sse`/`aiter_sse`), multipart.

package/lib/eject-assets/skills/typescript-generator/SKILL.md

@@ -40,6 +40,22 @@ relatively (`runtime: module`).
   layer — `path`, `query`, `headers`, `cookies`, `body` — and `flat` merges them into one
   object, which the runtime converts back using the descriptor's own parameter list. An
   operation whose merged names would collide keeps the grouped shape.
+- **Stream bodies pass through.** A request body that is a `ReadableStream`, or any
+  async iterable of bytes (a Node `Readable`), is a pass-through upload: `send()` hands it
+  to `fetch` untouched with `duplex: 'half'` and makes exactly one attempt, because a
+  consumed stream cannot be replayed, whatever the retry policy says. The whole-attempt
+  `timeout` still applies; callers pass `timeout: 0` or a budget that fits the upload per
+  call. The body type of an untyped `multipart/form-data` operation is
+  `FormData | ReadableStream`, and of a binary operation (`isBinaryContentType`:
+  `application/octet-stream`, `application/pdf`, images, audio, video, fonts, zip)
+  `Blob | ArrayBuffer | ReadableStream`. The client stays free of Node types: a Node
+  request becomes a web stream with `Readable.toWeb(request)`. Typed multipart objects
+  are unaffected.
+- **The caller's `Content-Type` wins; the description's fills the gap.** For a
+  pass-through body other than `FormData` or `URLSearchParams` (whose type `fetch`
+  derives, boundary included), `send()` sets the operation's declared content type only
+  when the caller set none, the same rule the JSON branch already follows. A forwarded
+  multipart boundary therefore survives, and a binary upload is never sent untyped.
 - **Throw mode returns the body**; `{ envelope: true }` opts into
   `{ data, headers, response }` with typed declared headers. Result mode returns
   `{ data, error, response }` and ignores `envelope`.