@redocly/cli 2.47.0 → 2.49.0

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

@@ -0,0 +1,232 @@
+// Ejected from @redocly/client-generator@0.4.1 — 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`.
+// The `operations` stage: one typed request method per operation, plus the
+// argument planning and request prologue it shares with the pagination wrappers.
+
+import {
+  type ApiModel,
+  type DateType,
+  isMultipartBody,
+  jsonSuccessSchema,
+  type OperationModel,
+  sseResponse,
+  uniqueIdentifiers,
+} from '@redocly/client-generator';
+import type { PhpPrinter } from '@redocly/client-generator/printers/php';
+
+import { envelopeHeaderSpecs } from './descriptor.ts';
+import { hydration, serialization } from './models.ts';
+import { PHP, phpString } from './naming.ts';
+import { phpElementType, phpNullable, phpType } from './types.ts';
+
+const MUTATING = new Set(['post', 'put', 'patch']);
+
+type MethodArgs = {
+  pathArgs: Array<{ php: string; wire: string; type: string }>;
+  /** `value` is the expression to send: a date object formats itself, everything else is the variable. */
+  queryArgs: Array<{ php: string; wire: string; type: string; value: string }>;
+  signature: string[];
+};
+
+/**
+ * The argument names a request method declares beside its parameters. A parameter named
+ * after one of them takes a suffixed variable instead, so the slot keeps its meaning.
+ */
+const SIGNATURE_ARG_SLOTS = ['body', 'headers', 'idempotencyKey'];
+
+export function methodArgs(
+  op: OperationModel,
+  model: ApiModel,
+  includeBody: boolean,
+  dateType: DateType
+): MethodArgs {
+  // Each parameter is its own argument, so path and query names share one namespace with
+  // the slots this signature declares itself (`$body`, `$headers`, `$idempotencyKey`).
+  // A repeat moves aside (`$id`, `$id_2`): PHP rejects a redefined parameter outright, and
+  // a description may legally use one name in two locations.
+  const names = uniqueIdentifiers(
+    [...op.pathParams, ...op.queryParams].map((param) => param.name),
+    { style: 'camel', reserved: PHP, taken: SIGNATURE_ARG_SLOTS }
+  );
+  const pathArgs = op.pathParams.map((param, index) => ({
+    php: names[index],
+    wire: param.name,
+    type: phpType(param.schema, model, dateType),
+  }));
+  const queryArgs = op.queryParams.map((param, index) => {
+    const php = names[op.pathParams.length + index];
+    return {
+      php,
+      wire: param.name,
+      type: phpType(param.schema, model, dateType),
+      value: serialization(param.schema, `${'$'}${php}`, model, dateType) ?? `${'$'}${php}`,
+    };
+  });
+  const signature = [
+    ...pathArgs.map(({ php, type }) => `${type} ${'$'}${php}`),
+    ...(includeBody && op.requestBody
+      ? [
+          `${isMultipartBody(op) ? 'array' : phpType(op.requestBody.schema, model, dateType)} ${'$'}body`,
+        ]
+      : []),
+    ...queryArgs.map(({ php, type }) => {
+      const nullable = phpNullable(type);
+      return `${nullable} ${'$'}${php} = null`;
+    }),
+    '?array $headers = null',
+    ...(includeBody && MUTATING.has(op.method.toLowerCase())
+      ? ['?string $idempotencyKey = null']
+      : []),
+  ];
+  return { pathArgs, queryArgs, signature };
+}
+
+/** The shared prologue: resolve auth, build query/url, merge headers. */
+function writeRequestSetup(printer: PhpPrinter, op: OperationModel, args: MethodArgs): void {
+  printer.line(`$op = OPERATIONS[${phpString(op.specName ?? op.name)}];`);
+  printer.line(
+    "[$authHeaders, $query, $cookies] = resolveAuth($op['security'] ?? [], $this->config->auth);"
+  );
+  for (const { php, wire, value } of args.queryArgs) {
+    printer.block(
+      `if (${'$'}${php} !== null) {`,
+      () => {
+        printer.line(`$query[${phpString(wire)}] = ${value};`);
+      },
+      '}'
+    );
+  }
+  const pathDict = args.pathArgs
+    .map(({ php, wire }) => `${phpString(wire)} => ${'$'}${php}`)
+    .join(', ');
+  printer.line(`$url = buildUrl($this->config->serverUrl, $op['path'], [${pathDict}]);`);
+  printer.line('$requestHeaders = array_merge($authHeaders, $headers ?? []);');
+  printer.block(
+    'if ($cookies !== []) {',
+    () => {
+      printer.line("$requestHeaders['Cookie'] = implode('; ', $cookies);");
+    },
+    '}'
+  );
+}
+
+export function writePhpMethod(
+  printer: PhpPrinter,
+  op: OperationModel,
+  ident: string,
+  model: ApiModel,
+  dateType: DateType,
+  envelope = false
+): void {
+  const args = methodArgs(op, model, true, dateType);
+  const sse = sseResponse(op);
+  const success = jsonSuccessSchema(op);
+  // Non-JSON success bodies (PDFs, images, octet streams) return the raw body string.
+  const rawBody =
+    sse === undefined &&
+    success === undefined &&
+    op.successResponses.some((response) => response.contentType !== '');
+  const returnType = envelope
+    ? 'Envelope'
+    : sse !== undefined
+      ? '\\Generator'
+      : success !== undefined
+        ? phpType(success, model, dateType)
+        : rawBody
+          ? 'string'
+          : 'void';
+  const name = envelope ? `${ident}WithHeaders` : ident;
+  const element = envelope ? undefined : phpElementType(success, model, dateType);
+  printer.doc(
+    name,
+    envelope
+      ? `Like ${ident}(), returning an Envelope with the declared response headers.`
+      : (op.summary ?? `${op.method.toUpperCase()} ${op.path}`),
+    element === undefined ? [] : [`@return ${element}[]`]
+  );
+  printer.line(`public function ${name}(${args.signature.join(', ')}): ${returnType}`);
+  printer.block(
+    '{',
+    () => {
+      writeRequestSetup(printer, op, args);
+      if (sse !== undefined) {
+        const jsonData = sse.schema !== undefined && sse.schema.kind !== 'unknown';
+        printer.line('$url = appendQuery($url, $query);');
+        printer.block(
+          '$open = function (array $extraHeaders) use ($url, $requestHeaders): \\CurlHandle {',
+          () => {
+            printer.line('$handle = curl_init($url);');
+            printer.line('$lines = [];');
+            printer.block(
+              'foreach (array_merge($requestHeaders, $extraHeaders) as $name => $value) {',
+              () => {
+                printer.line("$lines[] = $name . ': ' . $value;");
+              },
+              '}'
+            );
+            printer.line('curl_setopt($handle, CURLOPT_HTTPHEADER, $lines);');
+            printer.line('return $handle;');
+          },
+          '};'
+        );
+        printer.line(`yield from iterSse($open, ${jsonData ? 'true' : 'false'});`);
+        return;
+      }
+      const request = [
+        `'operationId' => $op['id']`,
+        `'method' => $op['method']`,
+        `'url' => $url`,
+        `'headers' => $requestHeaders`,
+        `'query' => $query`,
+      ];
+      if (op.requestBody && isMultipartBody(op)) {
+        printer.line('[$contentType, $encoded] = toMultipart($body);');
+        request.push(`'body' => $encoded`, `'contentType' => $contentType`);
+      } else if (op.requestBody) {
+        const wire = serialization(op.requestBody.schema, '$body', model, dateType) ?? '$body';
+        printer.line(`$payload = json_encode(${wire});`);
+        request.push(
+          `'body' => $payload`,
+          `'contentType' => ${phpString(op.requestBody.contentType)}`
+        );
+      }
+      if (MUTATING.has(op.method.toLowerCase()) && op.requestBody) {
+        request.push(`'idempotencyKey' => $idempotencyKey`);
+      }
+      printer.line(`$response = send($this->config, [${request.join(', ')}]);`);
+      printer.block(
+        "if ($response['status'] >= 400) {",
+        () => {
+          printer.line('throw apiErrorFrom($response);');
+        },
+        '}'
+      );
+      const decoded = rawBody
+        ? "$response['body']"
+        : ((success === undefined
+            ? undefined
+            : hydration(success, 'decodeJson($response)', model, dateType)) ??
+          'decodeJson($response)');
+      if (envelope) {
+        printer.line(`$data = ${decoded};`);
+        printer.line(
+          `return new Envelope(data: $data, headers: readEnvelopeHeaders($response, ${envelopeHeaderSpecs(op, model)}), status: $response['status']);`
+        );
+        return;
+      }
+      if (rawBody) {
+        printer.line("return $response['body'];");
+        return;
+      }
+      if (returnType === 'void') {
+        printer.line('decodeJson($response);');
+        return;
+      }
+      printer.line(`return ${decoded};`);
+    },
+    '}'
+  );
+  printer.blank();
+}

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

@@ -0,0 +1,133 @@
+// Ejected from @redocly/client-generator@0.4.1 — 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`.
+// The `pagination` stage: the `<op>Pages()` / `<op>Items()` generator methods
+// over the runtime's iterPages.
+
+import {
+  type ApiModel,
+  type DateType,
+  jsonSuccessSchema,
+  type OperationModel,
+} from '@redocly/client-generator';
+import type { PhpPrinter } from '@redocly/client-generator/printers/php';
+
+import { phpString } from './naming.ts';
+import { methodArgs } from './operations.ts';
+import { phpType } from './types.ts';
+
+/** `<op>Pages()` / `<op>Items()` generators over the runtime's iterPages. */
+export function writePhpPaginationWrappers(
+  printer: PhpPrinter,
+  op: OperationModel,
+  ident: string,
+  model: ApiModel,
+  dateType: DateType,
+  pageHydration: string | undefined,
+  itemHydration: string | undefined,
+  itemsPointer: string | undefined,
+  itemYield: string
+): void {
+  const args = methodArgs(op, model, false, dateType);
+  const name = ident;
+
+  const writeCall = () => {
+    printer.line(`$op = OPERATIONS[${phpString(op.specName ?? op.name)}];`);
+    printer.line('$base = [];');
+    for (const { php, wire, value } of args.queryArgs) {
+      printer.block(
+        `if (${'$'}${php} !== null) {`,
+        () => {
+          printer.line(`$base[${phpString(wire)}] = ${value};`);
+        },
+        '}'
+      );
+    }
+    const pathDict = args.pathArgs
+      .map(({ php, wire }) => `${phpString(wire)} => ${'$'}${php}`)
+      .join(', ');
+    printer.block(
+      '$call = function (array $params) use ($op, $headers): array {',
+      () => {
+        printer.line(
+          "[$authHeaders, $authQuery, $cookies] = resolveAuth($op['security'] ?? [], $this->config->auth);"
+        );
+        printer.line(`$url = buildUrl($this->config->serverUrl, $op['path'], [${pathDict}]);`);
+        printer.line('$requestHeaders = array_merge($authHeaders, $headers ?? []);');
+        printer.block(
+          'if ($cookies !== []) {',
+          () => {
+            printer.line("$requestHeaders['Cookie'] = implode('; ', $cookies);");
+          },
+          '}'
+        );
+        printer.line(
+          "$response = send($this->config, ['operationId' => $op['id'], 'method' => $op['method'], 'url' => $url, 'headers' => $requestHeaders, 'query' => array_merge($params, $authQuery)]);"
+        );
+        printer.block(
+          "if ($response['status'] >= 400) {",
+          () => {
+            printer.line('throw apiErrorFrom($response);');
+          },
+          '}'
+        );
+        printer.line('return [decodeJson($response), $response];');
+      },
+      '};'
+    );
+  };
+
+  const pageType = phpType(jsonSuccessSchema(op) ?? { kind: 'unknown' }, model, dateType);
+  const pageYield = pageType === 'mixed' ? 'mixed' : pageType;
+  printer.line('/**');
+  printer.line(` * ${name} response pages, following the pagination rule automatically.`);
+  printer.line(' *');
+  printer.line(` * @return \\Generator<int, ${pageYield}>`);
+  printer.line(' */');
+  printer.line(`public function ${name}Pages(${args.signature.join(', ')}): \\Generator`);
+  printer.block(
+    '{',
+    () => {
+      writeCall();
+      printer.block(
+        "foreach (iterPages($call, $op['pagination'], $base) as $page) {",
+        () => {
+          printer.line(`yield ${pageHydration ?? '$page'};`);
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+
+  printer.line('/**');
+  printer.line(` * The items of every ${name} page.`);
+  printer.line(' *');
+  printer.line(` * @return \\Generator<int, ${itemYield}>`);
+  printer.line(' */');
+  printer.line(`public function ${name}Items(${args.signature.join(', ')}): \\Generator`);
+  printer.block(
+    '{',
+    () => {
+      writeCall();
+      printer.block(
+        "foreach (iterPages($call, $op['pagination'], $base) as $page) {",
+        () => {
+          printer.line(`$items = resolvePointer($page, ${phpString(itemsPointer ?? '')});`);
+          printer.block(
+            'foreach (is_array($items) ? $items : [] as $item) {',
+            () => {
+              printer.line(`yield ${itemHydration ?? '$item'};`);
+            },
+            '}'
+          );
+        },
+        '}'
+      );
+    },
+    '}'
+  );
+  printer.blank();
+}

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

@@ -0,0 +1,148 @@
+// Ejected from @redocly/client-generator@0.4.1 — 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`.
+// The `types` stage: the PHP type declaration for a schema, its nullable and
+// union forms, and the element type PHP's own syntax erases.
+
+import {
+  type ApiModel,
+  type DateType,
+  deref,
+  enumValues,
+  flattenAllOf,
+  isNullable,
+  type SchemaModel,
+  unwrapNullable,
+} from '@redocly/client-generator';
+
+import { className } from './naming.ts';
+
+/** What a named schema renders as: a class, a native enum, or nothing (alias). */
+export function classify(name: string, model: ApiModel): 'class' | 'enum' | 'other' {
+  const named = model.schemas.find((candidate) => candidate.name === name);
+  if (named === undefined) return 'other';
+  const schema = named.schema;
+  const asEnum = enumValues(schema);
+  if (asEnum !== undefined && (asEnum.scalar === 'string' || asEnum.scalar === 'integer')) {
+    return 'enum';
+  }
+  if (
+    (schema.kind === 'object' || schema.kind === 'intersection') &&
+    flattenAllOf(schema, model) !== undefined
+  ) {
+    return 'class';
+  }
+  return 'other';
+}
+
+/** The PHP type declaration for a schema (arrays and unions widen to array/mixed). */
+export function phpType(
+  schema: SchemaModel,
+  model: ApiModel,
+  dateType: DateType = 'string'
+): string {
+  if (isNullable(schema)) {
+    const inner = phpType(unwrapNullable(schema), model, dateType);
+    return phpNullable(inner);
+  }
+  switch (schema.kind) {
+    case 'scalar':
+      // Under `dateType: Date`, date and date-time become DateTimeImmutable — PHP's
+      // immutable date object parses and formats both wire shapes.
+      if (dateType === 'Date' && schema.scalar === 'string' && isDateFormat(schema)) {
+        return '\\DateTimeImmutable';
+      }
+      return { string: 'string', integer: 'int', number: 'float', boolean: 'bool' }[schema.scalar];
+    case 'array':
+    case 'record':
+      return 'array';
+    case 'ref': {
+      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);
+    }
+    case 'enum':
+      // Anonymous (inline) enums keep the wire scalar; only NAMED enums get types.
+      return { string: 'string', integer: 'int', number: 'float', boolean: 'bool' }[schema.scalar];
+    case 'literal':
+      return typeof schema.value === 'string'
+        ? 'string'
+        : typeof schema.value === 'boolean'
+          ? 'bool'
+          : 'float';
+    case 'omit':
+      // PHP has no Omit; the base class is the honest annotation.
+      return className(schema.base);
+    case 'union':
+      return phpUnionType(schema.members, model, dateType);
+    case 'null':
+    case 'object':
+    case 'intersection':
+    case 'unknown':
+      return 'mixed';
+  }
+}
+
+/** `date` or `date-time` — the two formats `dateType: Date` turns into objects. */
+export function isDateFormat(schema: SchemaModel): boolean {
+  const format = schema.metadata?.format;
+  return format === 'date' || format === 'date-time';
+}
+
+/**
+ * The nullable form of a PHP type. `?T` for a single type, `A|B|null` for a union — PHP
+ * forbids mixing `?` with `|`, and `mixed` already includes null.
+ */
+export function phpNullable(type: string): string {
+  if (type === 'mixed' || type.startsWith('?') || type.endsWith('|null')) return type;
+  return type.includes('|') ? `${type}|null` : `?${type}`;
+}
+
+/**
+ * A union as a native PHP 8.1 union type (`int|string`, `PromotionType|array`). Rich list
+ * filters are usually unions, and collapsing them to `mixed` throws away the typing that
+ * makes the SDK worth generating. `mixed` cannot be a union member, so a member without a
+ * PHP type of its own (inline object, intersection, unknown) forces the whole union to
+ * `mixed`. Members that map to the same PHP type collapse to one.
+ */
+export function phpUnionType(members: SchemaModel[], model: ApiModel, dateType: DateType): string {
+  const rendered: string[] = [];
+  for (const member of members) {
+    // `null` is handled by the caller's nullability check, never as a member here.
+    if (member.kind === 'null') continue;
+    const type = phpType(member, model, dateType);
+    if (type === 'mixed') return 'mixed';
+    // A nullable member inside a union contributes its bare type plus null.
+    const bare = type.startsWith('?') ? type.slice(1) : type;
+    if (!rendered.includes(bare)) rendered.push(bare);
+    if (type.startsWith('?') && !rendered.includes('null')) rendered.push('null');
+  }
+  if (rendered.length === 0) return 'mixed';
+  return rendered.join('|');
+}
+
+/**
+ * The element type behind a PHP type that erases it. `array` and `\Generator` are as
+ * specific as PHP's syntax gets, so the docblock carries what they hold — that is what
+ * static analysis and readers actually go by.
+ */
+export function phpElementType(
+  schema: SchemaModel | undefined,
+  model: ApiModel,
+  dateType: DateType
+): string | undefined {
+  if (schema === undefined) return undefined;
+  const bare = unwrapNullable(schema);
+  if (bare.kind === 'ref') {
+    const target = deref(bare, model);
+    // A named schema that IS an array (a collection alias) keeps its element type.
+    return classify(bare.name, model) === 'other'
+      ? phpElementType(target, model, dateType)
+      : undefined;
+  }
+  if (bare.kind !== 'array') return undefined;
+  const element = phpType(bare.items, model, dateType);
+  return element === 'mixed' ? undefined : element;
+}

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

@@ -0,0 +1,123 @@
+// Ejected from @redocly/client-generator@0.4.1 — 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`.
+// The `client` stage: the `Servers` helper class and the `Client`/`AsyncClient`
+// classes that assemble the per-operation methods.
+
+import {
+  type ApiModel,
+  type DateType,
+  identifierFor,
+  jsonSuccessSchema,
+  paginationItemSchema,
+  type ServerModel,
+  serverUrlParts,
+  sseResponse,
+} from '@redocly/client-generator';
+import type { PythonPrinter } from '@redocly/client-generator/printers/python';
+
+import { fieldName, naming, operationIdents, PY } from './naming.ts';
+import { writeMethod } from './operations.ts';
+import { writePaginationWrappers } from './pagination.ts';
+import { pythonType } from './types.ts';
+
+/** The server URL as a Python expression: literals concatenated with declared-variable args. */
+function serverUrlExpression(server: ServerModel): string {
+  const parts = serverUrlParts(server).map((part) =>
+    part.kind === 'literal' ? naming.string(part.value) : fieldName(part.name).python
+  );
+  return parts.join(' + ');
+}
+
+/** One static method per declared server; server variables become keyword arguments. */
+export function writePythonServers(printer: PythonPrinter, model: ApiModel): void {
+  const servers = model.servers ?? [];
+  if (servers.length === 0) return;
+  const usedNames = new Set<string>();
+  printer.block('class Servers:', () => {
+    printer.line(
+      '"""The declared servers; variables default to the values from the description."""'
+    );
+    printer.blank();
+    servers.forEach((server, index) => {
+      let name = identifierFor(server.description ?? `server${index + 1}`, {
+        style: 'snake',
+        reserved: PY,
+      });
+      if (usedNames.has(name)) name = `${name}_${index + 1}`;
+      usedNames.add(name);
+      const params = server.variables.map(
+        (variable) => `${fieldName(variable.name).python}: str = ${naming.string(variable.default)}`
+      );
+      if (index > 0) printer.blank();
+      printer.line('@staticmethod');
+      printer.block(`def ${name}(${params.join(', ')}) -> str:`, () => {
+        printer.line(`return ${serverUrlExpression(server)}`);
+      });
+    });
+  });
+  printer.blank();
+}
+
+export function writeClientClass(
+  printer: PythonPrinter,
+  model: ApiModel,
+  errorMode: 'throw' | 'result',
+  isAsync: boolean,
+  paginationSpecs: Map<string, Record<string, unknown> | undefined>,
+  serverUrl: string,
+  dateType: DateType
+): void {
+  const name = isAsync ? 'AsyncClient' : 'Client';
+  const httpType = isAsync ? 'httpx.AsyncClient' : 'httpx.Client';
+  printer.block(`class ${name}:`, () => {
+    printer.doc(`${isAsync ? 'Async ' : ''}client for ${model.title} (${model.version}).`);
+    printer.block(
+      `def __init__(self, server_url: str = ${naming.string(serverUrl)}, *, ` +
+        'auth: Optional[Dict[str, Any]] = None, headers: Optional[Dict[str, str]] = None, ' +
+        'timeout: Optional[float] = None, retry: Optional[Dict[str, Any]] = None, ' +
+        'middleware: Optional[List[Any]] = None, idempotency_key: Any = None, ' +
+        `http_client: Optional[${httpType}] = None) -> None:`,
+      () => {
+        printer.line('self._server_url = server_url');
+        printer.line('self._auth = auth or {}');
+        printer.line('self._config: Dict[str, Any] = {');
+        printer.indent(() => {
+          printer.line('"headers": headers or {},');
+          printer.line('"timeout": timeout,');
+          printer.line('"retry": retry or {},');
+          printer.line('"middleware": middleware or [],');
+          printer.line('"idempotency_key": idempotency_key,');
+        });
+        printer.line('}');
+        printer.line(`self._http = http_client or ${httpType}()`);
+      }
+    );
+    printer.blank();
+    for (const { op, ident } of operationIdents(model)) {
+      writeMethod(printer, op, ident, errorMode, isAsync, dateType);
+      if (sseResponse(op) === undefined && (op.successResponseHeaders?.length ?? 0) > 0) {
+        writeMethod(printer, op, ident, errorMode, isAsync, dateType, model, true);
+      }
+      const spec = paginationSpecs.get(ident);
+      if (spec !== undefined) {
+        const success = jsonSuccessSchema(op);
+        const element = paginationItemSchema(
+          success,
+          typeof spec.items === 'string' ? spec.items : undefined,
+          model
+        );
+        writePaginationWrappers(
+          printer,
+          op,
+          ident,
+          isAsync,
+          element === undefined ? 'Any' : pythonType(element, dateType),
+          dateType
+        );
+      }
+    }
+  });
+  printer.blank();
+}

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

@@ -0,0 +1,52 @@
+// Ejected from @redocly/client-generator@0.4.1 — 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`.
+// The `descriptor` stage: the wire-shape literals the embedded runtime routes by —
+// pagination specs, envelope-header coerce specs, and Python data literals.
+
+import {
+  type ApiModel,
+  headerCoerceType,
+  identifierFor,
+  type NeutralPaginationRule,
+  type OperationModel,
+} from '@redocly/client-generator';
+
+import { naming, PY } from './naming.ts';
+
+/** JSON → Python literal (dicts/lists/strings/numbers/bools/None). */
+export function pythonLiteral(value: unknown): string {
+  return naming.literal(value);
+}
+
+/** The resolved pagination rule mapped to the snake_case spec dict the embedded
+ * Python runtime consumes. */
+export function paginationSpec(
+  rule: NeutralPaginationRule | undefined
+): Record<string, unknown> | undefined {
+  if (rule === undefined) return undefined;
+  return {
+    style: rule.style,
+    ...(rule.param !== undefined ? { param: rule.param } : {}),
+    ...(rule.nextCursor !== undefined ? { next_cursor: rule.nextCursor } : {}),
+    ...(rule.hasMore !== undefined ? { has_more: rule.hasMore } : {}),
+    ...(rule.limitParam !== undefined ? { limit_param: rule.limitParam } : {}),
+    ...(rule.items !== undefined ? { items: rule.items } : {}),
+  };
+}
+
+/** Declared response headers as runtime coerce specs: `("wire-name", "snake_key", "type")`. */
+export function envelopeHeaderSpecs(op: OperationModel, model: ApiModel): string {
+  const used = new Set<string>();
+  const specs = (op.successResponseHeaders ?? []).map((header) => {
+    const base = identifierFor(header.name, { style: 'snake', reserved: PY });
+    let key = base;
+    let suffix = 2;
+    while (used.has(key)) key = `${base}_${suffix++}`;
+    used.add(key);
+    const type = headerCoerceType(header.schema, model);
+    return `(${naming.string(header.name)}, ${naming.string(key)}, ${naming.string(type)})`;
+  });
+  return `[${specs.join(', ')}]`;
+}