@labelbox/rl-sdk 0.0.0

package/dist/reference/resources-schema.d.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod';
+export declare const ResourceFieldSchema: z.ZodObject<{
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    format: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>>;
+    items: z.ZodOptional<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>;
+    variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>>;
+    name: z.ZodString;
+    required: z.ZodBoolean;
+}, z.core.$strict>;
+export type ResourceField = z.infer<typeof ResourceFieldSchema>;
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export declare const JsonValueSchema: z.ZodType<JsonValue>;
+export declare const ResourceRelationshipSchema: z.ZodObject<{
+    field: z.ZodString;
+    targetResource: z.ZodString;
+}, z.core.$strict>;
+export type ResourceRelationship = z.infer<typeof ResourceRelationshipSchema>;
+export declare const ResourceReferenceEntrySchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    parent: z.ZodOptional<z.ZodString>;
+    order: z.ZodNumber;
+    domain: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    object: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        fields: z.ZodArray<z.ZodObject<{
+            type: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+            enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            format: z.ZodOptional<z.ZodString>;
+            example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            nullable: z.ZodOptional<z.ZodBoolean>;
+            minimum: z.ZodOptional<z.ZodNumber>;
+            maximum: z.ZodOptional<z.ZodNumber>;
+            exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+            exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+            minLength: z.ZodOptional<z.ZodNumber>;
+            maxLength: z.ZodOptional<z.ZodNumber>;
+            minItems: z.ZodOptional<z.ZodNumber>;
+            maxItems: z.ZodOptional<z.ZodNumber>;
+            pattern: z.ZodOptional<z.ZodString>;
+            fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>>;
+            items: z.ZodOptional<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>;
+            variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<import("./schema.js").ShapeNode, unknown, z.core.$ZodTypeInternals<import("./schema.js").ShapeNode, unknown>>>>>;
+            name: z.ZodString;
+            required: z.ZodBoolean;
+        }, z.core.$strict>>;
+        sample: z.ZodOptional<z.ZodType<JsonValue, unknown, z.core.$ZodTypeInternals<JsonValue, unknown>>>;
+    }, z.core.$strict>>;
+    operationIds: z.ZodArray<z.ZodString>;
+    relationships: z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        targetResource: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ResourceReferenceEntry = z.infer<typeof ResourceReferenceEntrySchema>;

package/dist/reference/resources-schema.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { NamedShapeNodeSchema } from './schema.js';
+// One Explanation-layer "resource hub", keyed by resource id, produced from the
+// backend OpenAPI spec by `yarn dx resources:generate` and rendered on the in-app
+// Resources docs pages. A tag becomes a live resource by carrying `x-docs-resource`
+// metadata (see `apps/recursion/api/src/openapi-config.ts`). Guardrail: every field here is
+// either a checked reference into the spec or bounded editorial prose — never
+// free-floating text — so the freshness check can prove it matches the spec.
+// A field of a resource's detail-DTO object shape. A named shape node (no `in`
+// location — object fields have no path/query/body site), so it carries the same
+// recursive shape + constraint metadata as an SDK param or response field.
+export const ResourceFieldSchema = NamedShapeNodeSchema;
+export const JsonValueSchema = z.lazy(() => z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(JsonValueSchema),
+    z.record(z.string(), JsonValueSchema),
+]));
+// A foreign-key edge from this resource's object to another live resource, derived
+// from a `<base>Id` field whose `<base>` resolves to a resource's object DTO.
+export const ResourceRelationshipSchema = z
+    .object({
+    // The `<base>Id` field on this resource's object that points to the target.
+    field: z.string(),
+    // The resource id (tag name) the edge points to.
+    targetResource: z.string(),
+})
+    .strict();
+export const ResourceReferenceEntrySchema = z
+    .object({
+    // Resource id — the OpenAPI tag name that carries `x-docs-resource`.
+    id: z.string(),
+    // Display title — the `title` override, else a title-cased id.
+    title: z.string(),
+    // Parent resource id for nav nesting (e.g. `problems` → `environments`).
+    parent: z.string().optional(),
+    // Sort order within the resource's nav level (ascending).
+    order: z.number(),
+    // Canonical product domain (a `DomainId` — see `./domains.ts`) this resource
+    // anchors. Optional: only curated resources carry one. Kept a plain string
+    // here; membership in `DOMAINS` is enforced fail-fast by `resources:generate`.
+    // Powers P2's cross-type domain hubs.
+    domain: z.string().optional(),
+    // One-line terse summary (tag `x-docs-resource.summary`) — nav label / CLI group help.
+    summary: z.string().optional(),
+    // The rich markdown intro — the tag `description`, promoted from the authored
+    // `apps/recursion/api/src/resource-intros/<id>.md` at spec-build time. Rendered as the hub intro.
+    description: z.string().optional(),
+    // The detail DTO (the `GET /:id` response) and its field shape. Absent for
+    // resources with no addressable detail DTO (sub-resources reached only via a
+    // collection or singleton endpoint) — their hub renders object-less.
+    object: z
+        .object({
+        // The DTO component name, e.g. `EnvironmentDto`.
+        name: z.string(),
+        fields: z.array(ResourceFieldSchema),
+        // The DTO's authored example — the whole-object `example` on its Zod schema
+        // (`.meta({ example })`), read straight off the spec at codegen time and
+        // rendered above Fields as a real, coherent copy-paste starting point.
+        sample: JsonValueSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    // operationIds of the @SdkRoute operations tagged with this resource.
+    operationIds: z.array(z.string()),
+    // Foreign-key edges to other live resources.
+    relationships: z.array(ResourceRelationshipSchema),
+})
+    .strict();

package/dist/reference/schema.d.ts

@@ -0,0 +1,153 @@
+import { z } from 'zod';
+export interface ShapeNode {
+    name?: string | undefined;
+    type: string;
+    required?: boolean | undefined;
+    description?: string | undefined;
+    enum?: string[] | undefined;
+    itemEnum?: string[] | undefined;
+    default?: string | number | boolean | undefined;
+    format?: string | undefined;
+    example?: string | number | boolean | undefined;
+    nullable?: boolean | undefined;
+    minimum?: number | undefined;
+    maximum?: number | undefined;
+    exclusiveMinimum?: number | undefined;
+    exclusiveMaximum?: number | undefined;
+    minLength?: number | undefined;
+    maxLength?: number | undefined;
+    minItems?: number | undefined;
+    maxItems?: number | undefined;
+    pattern?: string | undefined;
+    fields?: ShapeNode[] | undefined;
+    items?: ShapeNode | undefined;
+    variants?: ShapeNode[] | undefined;
+}
+export declare const ShapeNodeSchema: z.ZodType<ShapeNode>;
+/**
+ * The metadata / constraint keys a `ShapeNode` carries beyond its structural
+ * identity (`name`/`type`/`required`), its `description`, and its sub-shape
+ * (`fields`/`items`/`variants`). Derived from `ShapeNode`, so adding a constraint
+ * field to the interface automatically widens this union. The in-app docs
+ * renderer uses the union to require a label for every metadata key.
+ */
+export type ShapeMetaKey = Exclude<keyof ShapeNode, 'name' | 'type' | 'required' | 'description' | 'fields' | 'items' | 'variants'>;
+/**
+ * A node's present metadata as ordered `[key, value]` pairs for the in-app docs
+ * renderer. Value normalization lives here: `enum`/`itemEnum` stay arrays for the
+ * consumer to join, the exclusive bounds carry their `>`/`<` prefix, `nullable`
+ * is the bare flag, and every other present key is its raw scalar. Absent keys
+ * (and a `false` `nullable`) are omitted.
+ */
+export declare function shapeMetaEntries(node: ShapeNode): Array<readonly [ShapeMetaKey, string | number | boolean | readonly string[]]>;
+export declare const NamedShapeNodeSchema: z.ZodObject<{
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    format: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+    variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    name: z.ZodString;
+    required: z.ZodBoolean;
+}, z.core.$strict>;
+export type NamedShapeNode = z.infer<typeof NamedShapeNodeSchema>;
+export declare const SdkParamSchema: z.ZodObject<{
+    type: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    format: z.ZodOptional<z.ZodString>;
+    example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    nullable: z.ZodOptional<z.ZodBoolean>;
+    minimum: z.ZodOptional<z.ZodNumber>;
+    maximum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+    exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+    minLength: z.ZodOptional<z.ZodNumber>;
+    maxLength: z.ZodOptional<z.ZodNumber>;
+    minItems: z.ZodOptional<z.ZodNumber>;
+    maxItems: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+    variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+    name: z.ZodString;
+    required: z.ZodBoolean;
+    in: z.ZodEnum<{
+        query: "query";
+        body: "body";
+        path: "path";
+    }>;
+}, z.core.$strict>;
+export type SdkParam = z.infer<typeof SdkParamSchema>;
+export declare const SdkReferenceEntrySchema: z.ZodObject<{
+    operationId: z.ZodString;
+    tag: z.ZodString;
+    callPath: z.ZodArray<z.ZodString>;
+    namespace: z.ZodString;
+    method: z.ZodString;
+    bodyKey: z.ZodOptional<z.ZodString>;
+    signature: z.ZodString;
+    example: z.ZodString;
+    cliInvocation: z.ZodString;
+    cliExample: z.ZodString;
+    curlExample: z.ZodString;
+    summary: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    httpMethod: z.ZodEnum<{
+        delete: "delete";
+        get: "get";
+        patch: "patch";
+        post: "post";
+        put: "put";
+    }>;
+    path: z.ZodString;
+    requiredPermissions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    params: z.ZodArray<z.ZodObject<{
+        type: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        enum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        itemEnum: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        format: z.ZodOptional<z.ZodString>;
+        example: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        nullable: z.ZodOptional<z.ZodBoolean>;
+        minimum: z.ZodOptional<z.ZodNumber>;
+        maximum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMinimum: z.ZodOptional<z.ZodNumber>;
+        exclusiveMaximum: z.ZodOptional<z.ZodNumber>;
+        minLength: z.ZodOptional<z.ZodNumber>;
+        maxLength: z.ZodOptional<z.ZodNumber>;
+        minItems: z.ZodOptional<z.ZodNumber>;
+        maxItems: z.ZodOptional<z.ZodNumber>;
+        pattern: z.ZodOptional<z.ZodString>;
+        fields: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+        items: z.ZodOptional<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>;
+        variants: z.ZodOptional<z.ZodArray<z.ZodLazy<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>>>;
+        name: z.ZodString;
+        required: z.ZodBoolean;
+        in: z.ZodEnum<{
+            query: "query";
+            body: "body";
+            path: "path";
+        }>;
+    }, z.core.$strict>>;
+    response: z.ZodOptional<z.ZodType<ShapeNode, unknown, z.core.$ZodTypeInternals<ShapeNode, unknown>>>;
+    responseMediaType: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type SdkReferenceEntry = z.infer<typeof SdkReferenceEntrySchema>;

package/dist/reference/schema.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+// A scalar leaf value — the type of an authored `default` / `example`.
+const ScalarValueSchema = z.union([z.string(), z.number(), z.boolean()]);
+// The recursive object schema. Recursive fields use `z.lazy` to defer to the
+// exported alias below; `.strict()` rejects unknown keys at every level.
+const ShapeNodeObjectSchema = z
+    .object({
+    name: z.string().optional(),
+    type: z.string(),
+    required: z.boolean().optional(),
+    description: z.string().optional(),
+    enum: z.array(z.string()).optional(),
+    itemEnum: z.array(z.string()).optional(),
+    default: ScalarValueSchema.optional(),
+    format: z.string().optional(),
+    example: ScalarValueSchema.optional(),
+    nullable: z.boolean().optional(),
+    minimum: z.number().optional(),
+    maximum: z.number().optional(),
+    exclusiveMinimum: z.number().optional(),
+    exclusiveMaximum: z.number().optional(),
+    minLength: z.number().optional(),
+    maxLength: z.number().optional(),
+    minItems: z.number().optional(),
+    maxItems: z.number().optional(),
+    pattern: z.string().optional(),
+    fields: z.array(z.lazy(() => ShapeNodeSchema)).optional(),
+    items: z.lazy(() => ShapeNodeSchema).optional(),
+    variants: z.array(z.lazy(() => ShapeNodeSchema)).optional(),
+})
+    .strict();
+export const ShapeNodeSchema = ShapeNodeObjectSchema;
+function shapeMetaKeys(values) {
+    return values;
+}
+// Canonical render order for SDK reference metadata consumed by the in-app docs.
+// The helper requires every ShapeMetaKey exactly once and rejects extra keys, so
+// adding metadata fails here until it is deliberately placed in the order.
+const SHAPE_META_KEYS = shapeMetaKeys([
+    'enum',
+    'itemEnum',
+    'default',
+    'format',
+    'example',
+    'minimum',
+    'exclusiveMinimum',
+    'maximum',
+    'exclusiveMaximum',
+    'minLength',
+    'maxLength',
+    'minItems',
+    'maxItems',
+    'pattern',
+    'nullable',
+]);
+/**
+ * A node's present metadata as ordered `[key, value]` pairs for the in-app docs
+ * renderer. Value normalization lives here: `enum`/`itemEnum` stay arrays for the
+ * consumer to join, the exclusive bounds carry their `>`/`<` prefix, `nullable`
+ * is the bare flag, and every other present key is its raw scalar. Absent keys
+ * (and a `false` `nullable`) are omitted.
+ */
+export function shapeMetaEntries(node) {
+    const entries = [];
+    for (const key of SHAPE_META_KEYS) {
+        const value = node[key];
+        if (value === undefined)
+            continue;
+        if (key === 'enum' || key === 'itemEnum') {
+            if (Array.isArray(value) && value.length > 0)
+                entries.push([key, value]);
+        }
+        else if (key === 'nullable') {
+            if (value === true)
+                entries.push([key, true]);
+        }
+        else if (key === 'exclusiveMinimum') {
+            entries.push([key, `>${value}`]);
+        }
+        else if (key === 'exclusiveMaximum') {
+            entries.push([key, `<${value}`]);
+        }
+        else {
+            entries.push([key, value]);
+        }
+    }
+    return entries;
+}
+// A named shape node: a field/param guaranteed to carry a `name` + `required`
+// flag. The top-level params, response fields, and resource object fields are
+// all named; only nested array items / union variants are anonymous.
+export const NamedShapeNodeSchema = ShapeNodeObjectSchema.extend({
+    name: z.string(),
+    required: z.boolean(),
+});
+// One method-parameter in the generated TypeScript SDK reference, keyed by
+// operationId. Produced from the backend OpenAPI spec by `yarn dx sdk:generate`
+// and rendered on the in-app API docs pages. The namespace + method match the
+// real generated surface (`rl.<namespace>.<method>(...)`). A named shape node
+// plus its HTTP location.
+export const SdkParamSchema = NamedShapeNodeSchema.extend({
+    in: z.enum(['path', 'query', 'body']),
+});
+export const SdkReferenceEntrySchema = z
+    .object({
+    operationId: z.string(),
+    // OpenAPI tag — groups the operation in the API docs nav and deep-links it
+    // into the Swagger reference (`#/<tag>/<operationId>`).
+    tag: z.string(),
+    // Canonical call path — the segments of `rl.<…>.<leaf>(...)`. The TS SDK
+    // joins it with dots, the CLI with spaces. `namespace`/`method` are the
+    // first/last segments, kept for the docs renderer.
+    callPath: z.array(z.string()).min(1),
+    namespace: z.string(),
+    method: z.string(),
+    // The flat-call key the request body is passed under (`body`); absent for
+    // operations with no body.
+    bodyKey: z.string().optional(),
+    // TypeScript SDK: the call signature + a runnable example.
+    signature: z.string(),
+    example: z.string(),
+    // CLI: the `rl <noun> <verb>` invocation + a runnable example command.
+    cliInvocation: z.string(),
+    cliExample: z.string(),
+    // cURL: a runnable request against the public API.
+    curlExample: z.string(),
+    summary: z.string(),
+    description: z.string().optional(),
+    httpMethod: z.enum(['get', 'post', 'put', 'patch', 'delete']),
+    path: z.string(),
+    // The permissions the caller must hold to invoke this operation, lifted from
+    // the handler's `@RequirePermissions(...)` via the `x-required-permissions`
+    // spec extension. Absent for operations with no permission requirement (which
+    // are therefore never gated). The live CLI uses these to mark commands the
+    // caller can't run against their `/me/permissions` set.
+    requiredPermissions: z.array(z.string()).optional(),
+    params: z.array(SdkParamSchema),
+    // The full success (2xx) JSON response shape — an object (its `fields`), an
+    // array (its `items`), a scalar, or a union — carrying the same recursive
+    // metadata as the request params. Absent for void responses (no documented
+    // 2xx body). Rendered as the docs/CLI "Response" section, and the recipe
+    // composition validator reads `response.fields` to check a step can only
+    // capture a field the producing operation actually returns.
+    response: ShapeNodeSchema.optional(),
+    // The success body's media type when it is NOT application/json (e.g.
+    // 'text/plain' for the transcript download). Absent for JSON and void
+    // responses. The shell composer reads it to capture the raw body instead
+    // of piping non-JSON through jq.
+    responseMediaType: z.string().optional(),
+})
+    .strict();

package/dist/reference/sdk-reference.generated.d.ts

@@ -0,0 +1,10 @@
+/**
+ * AUTO-GENERATED by 'yarn dx sdk:generate'.
+ * Do not edit manually — changes will be overwritten.
+ *
+ * TypeScript SDK reference, keyed by operationId. Derived from the backend
+ * OpenAPI spec: only operations opted in via @SdkRoute are included, each
+ * placed at its declared x-sdk-path so the docs match the generated client.
+ */
+import type { SdkReferenceEntry } from './schema.js';
+export declare const SDK_REFERENCE: Record<string, SdkReferenceEntry>;