@redocly/cli 2.71.0 → 2.71.1

package/lib/eject-assets/generators/mock/render.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "mock" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "mock" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator mock --update`.
@@ -13,9 +13,13 @@ import {
   allOperations,
   type ApiModel,
   type DateType,
+  flattenAllOf,
+  isNullable,
+  type ModelPagination,
   type NamedSchemaModel,
   type OperationModel,
   type ResponseBodyModel,
+  schemaAtPointer,
   type SchemaModel,
 } from '@redocly/client-generator';
 import {
@@ -30,6 +34,7 @@ import { sampleValue, SampleExpression } from './sample.ts';
 import {
   expr,
   isObjectValue,
+  type MockEntry,
   type MockValue,
   objectValue,
   renderMockValue,
@@ -54,6 +59,8 @@ export type MockOptions = {
   mockData?: 'static' | 'faker';
   /** When set in `'faker'` mode, emit a top-level `faker.seed(<n>);` so runs reproduce. */
   mockSeed?: number;
+  /** The run's resolved pagination: a paginated handler serves the last page. */
+  pagination?: ModelPagination;
 };
 
 /** The body value for `schema` under the active data mode: a static literal tree
@@ -150,7 +157,7 @@ function codeIdent(value: string): string {
 function handlerFor(op: OperationModel, model: ApiModel, opts: MockOptions): string {
   const override = overrideParam(op, model, opts);
   const params = override ?? '';
-  const call = `http.${codeIdent(op.method)}(${JSON.stringify(mswPath(op.path))}, () => ${responseExpression(op, model, opts)})`;
+  const call = `http.${codeIdent(op.method)}(${JSON.stringify(mswPath(op.path))}, ${resolverFor(op, model, opts)})`;
   return `export const ${codeIdent(op.name)}Handler = (${params}) => ${call};`;
 }
 
@@ -212,8 +219,8 @@ function errorBodyType(op: OperationModel): string {
  * A `ref` success body forwards `override` to `create<Schema>(override)`, so its type
  * mirrors the factory's parameter (`Partial<Schema>`, or the full type when the factory
  * replaces wholesale — see `factoryFor`). An inline object body spreads `override`, typed
- * `Record<string, unknown>`. A body-less or non-object inline response has nothing to
- * override, so the handler takes no parameter.
+ * `Record<string, unknown>`, or `Partial<Omit<Schema, …>>` for an `omit` body. A body-less
+ * or non-object inline response has nothing to override, so the handler takes no parameter.
  */
 function overrideParam(op: OperationModel, model: ApiModel, opts: MockOptions): string | undefined {
   const success = op.successResponses[0];
@@ -226,16 +233,128 @@ function overrideParam(op: OperationModel, model: ApiModel, opts: MockOptions):
     return `override?: ${type}`;
   }
   if (!isObjectValue(bodyValue(success.schema, model, opts))) return undefined;
+  if (success.schema.kind === 'omit') {
+    const keys = success.schema.keys.map((key) => JSON.stringify(key)).join(' | ');
+    return `override?: Partial<Omit<${success.schema.base}, ${keys}>>`;
+  }
   return 'override?: Record<string, unknown>';
 }
 
+/**
+ * The handler's resolver. A paginated operation serves the LAST page, so `.pages()` over
+ * the default handlers ends after one page: a cursor page carries no next cursor (and a
+ * `false` "has more" flag), and a `body-link` page no next link; an offset or page-number
+ * page answers any position past the first with an empty item list, because those styles
+ * stop only on an empty page.
+ */
+function resolverFor(op: OperationModel, model: ApiModel, opts: MockOptions): string {
+  const spec = opts.pagination?.get(op.name)?.spec;
+  const success = op.successResponses[0];
+  if (!spec || spec.style === 'link' || !success)
+    return `() => ${responseExpression(op, model, opts)}`;
+  const page = bodyValue(success.schema, model, opts);
+  const status = statusCode(success.status);
+  // An object page spreads `override` in; a page that is the item array is replaced by it.
+  const takesOverride = overrideParam(op, model, opts) !== undefined;
+  const withOverride = (value: MockValue): MockValue => {
+    if (isObjectValue(value)) return spreadInto(value, 'override');
+    return takesOverride ? { kind: 'wrap', before: 'override ?? ', value, after: '' } : value;
+  };
+  const json = (value: MockValue): string => {
+    const data = renderMockValue(value, '');
+    return status === 200
+      ? `HttpResponse.json(${data})`
+      : `HttpResponse.json(${data}, { status: ${status} })`;
+  };
+  if (spec.style === 'cursor' || spec.style === 'body-link') {
+    const next = spec.style === 'cursor' ? spec.nextCursor : spec.nextLink;
+    let last = withPointer(page, pointerKeys(next), cursorStop(success.schema, next, model));
+    if (spec.style === 'cursor' && spec.hasMore !== undefined)
+      last = withPointer(last, pointerKeys(spec.hasMore), expr('false'));
+    return `() => ${json(withOverride(last))}`;
+  }
+  const first = spec.style === 'page' ? 1 : 0;
+  const position = `Number(new URL(request.url).searchParams.get(${codeLiteral(spec.param)}) ?? ${first})`;
+  const empty = emptyPage(page, pointerKeys(spec.items));
+  return `({ request }) => ${position} > ${first} ? ${json(empty)} : ${json(withOverride(page))}`;
+}
+
+/**
+ * The page past the last one: the page with `override` spread in, and the items at `keys`
+ * set AFTER the spread, so an override that sets the items cannot refill the empty page.
+ * The top-level property that holds the items is written out from the sample.
+ */
+function emptyPage(page: MockValue, keys: string[]): MockValue {
+  if (keys.length === 0 || !isObjectValue(page)) return withPointer(page, keys, expr('[]'));
+  const [key, ...rest] = keys;
+  const isKey = (entry: MockEntry) => !('spread' in entry) && entry.key === key;
+  const holder = page.entries.find(isKey);
+  const inner = holder && !('spread' in holder) ? holder.value : objectValue([]);
+  return objectValue([
+    ...page.entries.filter((entry) => !isKey(entry)),
+    { spread: 'override' },
+    { key, value: withPointer(inner, rest, expr('[]')) },
+  ]);
+}
+
+/**
+ * What ends a cursor or `body-link` walk at `pointer`: `null` when the value is nullable,
+ * nothing (the property is left out) when it is optional, and an empty string otherwise.
+ */
+function cursorStop(schema: SchemaModel, pointer: string, model: ApiModel): MockValue | undefined {
+  const cursor = schemaAtPointer(schema, pointer, model);
+  if (cursor?.kind === 'null' || (cursor && isNullable(cursor))) return expr('null');
+  const keys = pointerKeys(pointer);
+  const parent = schemaAtPointer(schema, pointer.slice(0, pointer.lastIndexOf('/')), model);
+  const property =
+    parent &&
+    flattenAllOf(parent, model)?.properties.find((candidate) => candidate.name === keys.at(-1));
+  return property?.required === false ? undefined : expr('""');
+}
+
+/** RFC 6901 pointer tokens (`~1` → `/`, `~0` → `~`); none for `''`, the whole value. */
+function pointerKeys(pointer: string): string[] {
+  if (pointer === '') return [];
+  return pointer
+    .slice(1)
+    .split('/')
+    .map((token) => token.replaceAll('~1', '/').replaceAll('~0', '~'));
+}
+
+/**
+ * `value` with the property at the `keys` path replaced (added when missing), or removed
+ * when `replacement` is `undefined`. An empty path replaces the whole value (a page that
+ * is the item array itself). Steps only through objects: a path that reaches into
+ * anything else leaves the value unchanged.
+ */
+function withPointer(
+  value: MockValue,
+  keys: string[],
+  replacement: MockValue | undefined
+): MockValue {
+  if (keys.length === 0) return replacement ?? value;
+  if (!isObjectValue(value)) return value;
+  const [key, ...rest] = keys;
+  const found = value.entries.some((entry) => !('spread' in entry) && entry.key === key);
+  const entries = value.entries.flatMap((entry) => {
+    if ('spread' in entry || entry.key !== key) return [entry];
+    if (rest.length > 0) return [{ key, value: withPointer(entry.value, rest, replacement) }];
+    return replacement === undefined ? [] : [{ key, value: replacement }];
+  });
+  if (!found && rest.length === 0 && replacement !== undefined) {
+    entries.push({ key, value: replacement });
+  }
+  return objectValue(entries);
+}
+
 /**
  * The handler's response. A primary success body becomes `HttpResponse.json(…)`:
- * a `ref` body calls its named `create<Schema>(override)` factory; an inline body
- * is sampled and printed in place with `...override` spread in. A success with no
- * usable body (an `unknown` schema, or no success response at all) becomes a
- * body-less `new HttpResponse(null, { status })`. The status is the success
- * response's declared code, or 200 when it's `default`/absent.
+ * a `ref` body calls its named `create<Schema>(override)` factory; an inline body is
+ * sampled and printed in place with `...override` spread in. An `omit` body (a named
+ * schema without its `writeOnly` keys) is inline too, because the factory keeps the
+ * required ones. A success with no usable body (an `unknown` schema, or no success
+ * response at all) becomes a body-less `new HttpResponse(null, { status })`. The status
+ * is the success response's declared code, or 200 when it's `default`/absent.
  */
 function responseExpression(op: OperationModel, model: ApiModel, opts: MockOptions): string {
   const success = op.successResponses[0];

package/lib/eject-assets/generators/mock/sample.ts

@@ -1,10 +1,11 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "mock" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "mock" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator mock --update`.
 import {
   type DateType,
   type NamedSchemaModel,
+  type PropertyModel,
   type ScalarKind,
   type SchemaMetadata,
   type SchemaModel,
@@ -97,7 +98,10 @@ export function splitIntersection(
   members: SchemaModel[],
   byName: Map<string, SchemaModel>
 ): { merged: SchemaModel | undefined; rest: SchemaModel[] } {
-  const properties = new Map<string, { schema: SchemaModel; required: boolean; rank: number }>();
+  const properties = new Map<
+    string,
+    { schema: SchemaModel; required: boolean; writeOnly: boolean; rank: number }
+  >();
   const rest: SchemaModel[] = [];
   let sawObject = false;
   for (const member of members) {
@@ -116,6 +120,7 @@ export function splitIntersection(
         properties.set(property.name, {
           schema: property.schema,
           required: property.required || (existing?.required ?? false),
+          writeOnly: property.writeOnly === true || (existing?.writeOnly ?? false),
           rank,
         });
       }
@@ -129,6 +134,7 @@ export function splitIntersection(
         name,
         schema: p.schema,
         required: p.required,
+        ...(p.writeOnly ? { writeOnly: true } : {}),
       })),
     },
     rest,
@@ -195,7 +201,9 @@ function walk(
   const meta = schema.metadata;
   // An example/default is honored only when it inhabits the generated type — real specs
   // carry `example: null` on non-nullable fields and defaults outside a narrowed enum
-  // (`enum: [cram-md5], default: none`); baking those would not type-check.
+  // (`enum: [cram-md5], default: none`); baking those would not type-check. A number
+  // outside its bounds or off its `multipleOf` step would fail the zod schema, so it is
+  // skipped too.
   const inhabits = (value: unknown): boolean => {
     if (value === null) {
       return (
@@ -205,6 +213,16 @@ function walk(
     }
     if (schema.kind === 'enum') return (schema.values as unknown[]).includes(value);
     if (schema.kind === 'literal') return value === schema.value;
+    if (
+      schema.kind === 'scalar' &&
+      (schema.scalar === 'integer' || schema.scalar === 'number') &&
+      typeof value === 'number'
+    ) {
+      const { min, max, step } = numericRange(schema.scalar, meta);
+      // `toPrecision` drops float noise, so `0.3` counts as a multiple of `0.1`.
+      const onStep = step === undefined || Number.isInteger(Number((value / step).toPrecision(12)));
+      return onStep && (min === undefined || value >= min) && (max === undefined || value <= max);
+    }
     return true;
   };
   if (meta?.example !== undefined && inhabits(meta.example)) return meta.example;
@@ -221,6 +239,7 @@ function walk(
     case 'object':
       return Object.fromEntries(
         schema.properties.flatMap((p) => {
+          if (omitsFromResponse(p)) return [];
           const value = walk(p.schema, byName, visiting, dateType);
           // A cyclic optional property is omitted (a null would not satisfy `T | undefined`);
           // a cyclic required property is uninhabitable, so null is the only stand-in.
@@ -292,9 +311,73 @@ function walk(
   }
 }
 
+/**
+ * Whether a mock leaves a property out. Mocks are response data, and a response never
+ * carries a `writeOnly` property. A required one stays, because the named type still
+ * demands it; a handler whose response omits it samples that `omit` shape instead.
+ */
+export function omitsFromResponse(property: PropertyModel): boolean {
+  return property.writeOnly === true && !property.required;
+}
+
+/**
+ * The inclusive range a numeric schema allows. `minimum`/`maximum` and the exclusive
+ * bounds narrow it, aligned to `multipleOf` (an integer steps by 1 without one). An
+ * exclusive bound on a number without a step moves in by 1, or to the middle of the
+ * range when the range is narrower than that. An unbounded side is `undefined`.
+ */
+export function numericRange(
+  scalar: 'integer' | 'number',
+  meta: SchemaMetadata | undefined
+): { min?: number; max?: number; step?: number } {
+  const step = meta?.multipleOf ?? (scalar === 'integer' ? 1 : undefined);
+  // The multiple of `step` that `round` picks for `bound`; `toPrecision` drops float noise.
+  const onStep = (bound: number, size: number, round: (steps: number) => number): number =>
+    Number((round(bound / size) * size).toPrecision(15));
+  const lows: number[] = [];
+  const highs: number[] = [];
+  if (meta?.minimum !== undefined) {
+    const bound = meta.minimum;
+    lows.push(step === undefined ? bound : onStep(bound, step, Math.ceil));
+  }
+  if (meta?.exclusiveMinimum !== undefined) {
+    const bound = meta.exclusiveMinimum;
+    lows.push(
+      step === undefined ? bound + 1 : onStep(bound, step, (steps) => Math.floor(steps) + 1)
+    );
+  }
+  if (meta?.maximum !== undefined) {
+    const bound = meta.maximum;
+    highs.push(step === undefined ? bound : onStep(bound, step, Math.floor));
+  }
+  if (meta?.exclusiveMaximum !== undefined) {
+    const bound = meta.exclusiveMaximum;
+    highs.push(
+      step === undefined ? bound - 1 : onStep(bound, step, (steps) => Math.ceil(steps) - 1)
+    );
+  }
+  const min = lows.length > 0 ? Math.max(...lows) : undefined;
+  const max = highs.length > 0 ? Math.min(...highs) : undefined;
+  if (step === undefined && min !== undefined && max !== undefined && min > max) {
+    const low = Math.max(meta?.minimum ?? -Infinity, meta?.exclusiveMinimum ?? -Infinity);
+    const high = Math.min(meta?.maximum ?? Infinity, meta?.exclusiveMaximum ?? Infinity);
+    const middle = (low + high) / 2;
+    return { min: middle, max: middle };
+  }
+  return { min, max, step };
+}
+
+/** `0` when the range allows it, else the end of the range nearest to `0`. */
+function numberSample(scalar: 'integer' | 'number', meta: SchemaMetadata | undefined): number {
+  const { min, max } = numericRange(scalar, meta);
+  if (min !== undefined && min > 0) return min;
+  if (max !== undefined && max < 0) return max;
+  return 0;
+}
+
 function scalarSample(scalar: ScalarKind, meta: SchemaMetadata | undefined): unknown {
   if (scalar === 'boolean') return true;
-  if (scalar === 'integer' || scalar === 'number') return 0;
+  if (scalar === 'integer' || scalar === 'number') return numberSample(scalar, meta);
   // Type-demanding formats (binary, and date/date-time under `dateType: 'Date'`) are
   // handled earlier in `walk` via `typeDemandedExpression`; here the date formats fall
   // through to the ISO-string path (the `dateType: 'string'` types them as `string`).

package/lib/eject-assets/generators/mock/values.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "mock" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "mock" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator mock --update`.

package/lib/eject-assets/generators/php/client.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.

package/lib/eject-assets/generators/php/descriptor.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -30,6 +30,15 @@ export function phpSecurityLiteral(op: OperationModel, model: ApiModel): string
   return `[${alternatives.join(', ')}]`;
 }
 
+/**
+ * The `resolveAuth` argument: the table's `security` entry, or `[]` for an operation the
+ * table gives none. Reading an absent key with `?? []` reads as dead code to PHPStan,
+ * which knows the table's exact shape.
+ */
+export function phpSecurityArg(op: OperationModel, model: ApiModel): string {
+  return phpSecurityLiteral(op, model) === undefined ? '[]' : "$op['security']";
+}
+
 export function phpPaginationLiteral(rule: NeutralPaginationRule): string {
   const fields = [
     `'style' => ${phpString(rule.style)}`,

package/lib/eject-assets/generators/php/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -234,5 +234,5 @@ export default {
     "argsStyle": "inputs follow the target language's own idiom",
     "importExt": "the generated file has no relative imports"
   },
-  requiresGenerator: '^0.7.11',
+  requiresGenerator: '^0.7.12',
 };

package/lib/eject-assets/generators/php/models.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -111,10 +111,15 @@ function writeClass(
   dateType: DateType,
   description?: string
 ): void {
+  // A response never carries a `writeOnly` property, and responses decode into this same
+  // class, so the property is optional even when the description requires it.
+  const fields = properties.map((property) =>
+    property.writeOnly ? { ...property, required: false } : property
+  );
   // PHP requires defaulted parameters after required ones.
   const ordered = [
-    ...properties.filter((property) => property.required),
-    ...properties.filter((property) => !property.required),
+    ...fields.filter((property) => property.required),
+    ...fields.filter((property) => !property.required),
   ];
   printer.doc(className(name), description);
   printer.line(`final class ${className(name)}`);

package/lib/eject-assets/generators/php/naming.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.

package/lib/eject-assets/generators/php/operations.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -18,7 +18,7 @@ import {
 } from '@redocly/client-generator';
 import type { PhpPrinter } from '@redocly/client-generator/printers/php';
 
-import { envelopeHeaderSpecs } from './descriptor.ts';
+import { envelopeHeaderSpecs, phpSecurityArg } from './descriptor.ts';
 import { hydration, serialization } from './models.ts';
 import { PHP, phpString } from './naming.ts';
 import { phpElementType, phpNullable, phpType } from './types.ts';
@@ -94,10 +94,15 @@ export function methodArgs(
 }
 
 /** The shared prologue: resolve auth, build query/url, merge headers. */
-function writeRequestSetup(printer: PhpPrinter, op: OperationModel, args: MethodArgs): void {
+function writeRequestSetup(
+  printer: PhpPrinter,
+  op: OperationModel,
+  model: ApiModel,
+  args: MethodArgs
+): void {
   printer.line(`$op = self::OPERATIONS[${phpString(op.specName ?? op.name)}];`);
   printer.line(
-    "[$authHeaders, $query, $cookies] = resolveAuth($op['security'] ?? [], $this->config->auth);"
+    `[$authHeaders, $query, $cookies] = resolveAuth(${phpSecurityArg(op, model)}, $this->config->auth);`
   );
   for (const { php, wire, value } of args.queryArgs) {
     printer.block(
@@ -154,13 +159,13 @@ export function writePhpMethod(
     envelope
       ? `Like ${ident}(), returning an Envelope with the declared response headers.`
       : (op.summary ?? `${op.method.toUpperCase()} ${op.path}`),
-    element === undefined ? [] : [`@return ${element}[]`]
+    element === undefined ? [] : [`@return ${element.includes('|') ? `(${element})` : element}[]`]
   );
   printer.line(`public function ${name}(${args.signature.join(', ')}): ${returnType}`);
   printer.block(
     '{',
     () => {
-      writeRequestSetup(printer, op, args);
+      writeRequestSetup(printer, op, model, args);
       if (sse !== undefined) {
         const jsonData = sse.schema !== undefined && sse.schema.kind !== 'unknown';
         printer.line('$url = appendQuery($url, $query);');

package/lib/eject-assets/generators/php/pagination.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -13,6 +13,7 @@ import {
 } from '@redocly/client-generator';
 import type { PhpPrinter } from '@redocly/client-generator/printers/php';
 
+import { phpSecurityArg } from './descriptor.ts';
 import { phpString } from './naming.ts';
 import { methodArgs } from './operations.ts';
 import { phpType } from './types.ts';
@@ -51,7 +52,7 @@ export function writePhpPaginationWrappers(
       '$call = function (array $params) use ($op, $headers): array {',
       () => {
         printer.line(
-          "[$authHeaders, $authQuery, $cookies] = resolveAuth($op['security'] ?? [], $this->config->auth);"
+          `[$authHeaders, $authQuery, $cookies] = resolveAuth(${phpSecurityArg(op, model)}, $this->config->auth);`
         );
         printer.line(`$url = buildUrl($this->config->serverUrl, $op['path'], [${pathDict}]);`);
         printer.line('$requestHeaders = array_merge($authHeaders, $headers ?? []);');

package/lib/eject-assets/generators/php/types.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "php" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "php" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator php --update`.
@@ -9,6 +9,7 @@ import {
   type ApiModel,
   type DateType,
   deref,
+  discriminatorCases,
   enumValues,
   flattenAllOf,
   isNullable,
@@ -61,7 +62,16 @@ export function phpType(
       const kind = classify(schema.name, model);
       if (kind === 'class' || kind === 'enum') return className(schema.name);
       const target = deref(schema, model);
-      return target === undefined ? 'mixed' : phpType(target, model, dateType);
+      if (target === undefined) return 'mixed';
+      const type = phpType(target, model, dateType);
+      // A discriminated union hydrates through `unmarshalX`, which hands a value with an
+      // unknown discriminator back as the raw array.
+      // A nullable type drops its `?` first, because PHP forbids `?` inside a union.
+      const raw = discriminatorCases(target, model) !== undefined;
+      if (!raw || type === 'mixed' || type.split('|').includes('array')) return type;
+      const nullable = type.startsWith('?') || type.endsWith('|null');
+      const bare = type.startsWith('?') ? type.slice(1) : type.replace(/\|null$/, '');
+      return nullable ? phpNullable(`${bare}|array`) : `${bare}|array`;
     }
     case 'enum':
       // Anonymous (inline) enums keep the wire scalar; only NAMED enums get types.

package/lib/eject-assets/generators/python/client.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.

package/lib/eject-assets/generators/python/descriptor.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.

package/lib/eject-assets/generators/python/index.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.
@@ -138,7 +138,7 @@ export const pythonGenerator: Generator = ({
   for (const { op, ident } of operationIdents(model)) {
     paginationSpecs.set(ident, paginationSpec(pagination?.get(op.name)?.spec));
   }
-  printer.line('_OPERATIONS = {');
+  printer.line('_OPERATIONS: Dict[str, Dict[str, Any]] = {');
   printer.indent(() => {
     for (const { op, ident } of operationIdents(model)) {
       const descriptor = {
@@ -247,5 +247,5 @@ export default {
     "argsStyle": "inputs follow the target language's own idiom",
     "importExt": "the generated file has no relative imports"
   },
-  requiresGenerator: '^0.7.11',
+  requiresGenerator: '^0.7.12',
 };

package/lib/eject-assets/generators/python/models.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.
@@ -84,6 +84,11 @@ function writeDataclass(
   /** The discriminator value this class is mapped to, pinned as a `Literal` (pydantic). */
   pinned?: DiscriminatorPin
 ): void {
+  // A response never carries a `writeOnly` property, and responses decode into this same
+  // class, so the property is optional even when the description requires it.
+  const fields = properties.map((property) =>
+    property.writeOnly ? { ...property, required: false } : property
+  );
   const pydantic = models === 'pydantic';
   if (!pydantic) printer.line('@dataclass');
   const header = pydantic ? `class ${className(name)}(BaseModel):` : `class ${className(name)}:`;
@@ -97,8 +102,8 @@ function writeDataclass(
     }
     // Required fields first — a dataclass field without a default may not follow one with.
     const ordered = [
-      ...properties.filter((property) => property.required),
-      ...properties.filter((property) => !property.required),
+      ...fields.filter((property) => property.required),
+      ...fields.filter((property) => !property.required),
     ];
     const fieldMap: Array<[string, string]> = [];
     if (ordered.length === 0) printer.line('pass');
@@ -157,6 +162,7 @@ export function renderPythonModels(
     'Optional',
     'Tuple',
     'Union',
+    'cast',
   ];
   if (models === 'dataclass') typingNames.splice(2, 0, 'ClassVar');
   if (unions.size > 0) typingNames.unshift('Annotated');

package/lib/eject-assets/generators/python/naming.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.

package/lib/eject-assets/generators/python/operations.ts

@@ -1,4 +1,4 @@
-// Ejected from @redocly/client-generator@0.7.11 — the built-in "python" generator.
+// Ejected from @redocly/client-generator@0.7.12 — the built-in "python" generator.
 // This file is yours: edit freely; the generated client stays machine-owned and is
 // rebuilt by `redocly generate-client`. Newer generator versions merge in with
 // `redocly eject-generator python --update`.
@@ -72,7 +72,7 @@ export function writeMethod(
     : sse !== undefined
       ? `${isAsync ? 'AsyncIterator' : 'Iterator'}[ServerSentEvent]`
       : errorMode === 'result'
-        ? 'Result'
+        ? `Result[${success === undefined ? 'None' : pythonType(success, dateType)}, Any]`
         : success === undefined
           ? 'None'
           : pythonType(success, dateType);
@@ -103,7 +103,7 @@ export function writeMethod(
     printer.line(`url = build_url(self._server_url, op["path"], {${pathDict}})`);
     if (sse !== undefined) {
       const dataKind = sse.schema !== undefined && sse.schema.kind !== 'unknown' ? 'json' : 'text';
-      printer.block('def _open(extra_headers: Dict[str, str]):', () => {
+      printer.block('def _open(extra_headers: Dict[str, str]) -> Any:', () => {
         printer.line(
           'return self._http.stream(op["method"], url, ' +
             'headers={**auth_headers, **(headers or {}), **extra_headers}, params=params, timeout=timeout)'
@@ -129,10 +129,11 @@ export function writeMethod(
         `headers={**auth_headers, **(headers or {})}, params=params${bodyKw}, ` +
         'timeout=timeout, retry=retry, idempotency_key=idempotency_key)'
     );
+    const successType = success === undefined ? undefined : pythonType(success, dateType);
     const decoded =
-      success === undefined
+      successType === undefined
         ? 'None'
-        : `decode(${pythonType(success, dateType)}, _safe_json(response))`;
+        : `cast(${successType}, decode(${successType}, _safe_json(response)))`;
     if (envelope) {
       printer.block('if not response.is_success:', () => {
         printer.line(