@ts-pf/openapi 0.1.0-beta.0

package/README.md

@@ -0,0 +1,44 @@
+# @ts-pf/openapi
+
+Project a `@ts-pf/docs` `catalog()` into an **OpenAPI 3.1** document that describes the existing POST JSON RPC.
+
+Agent skill: [`skills/ts-pf-openapi/`](skills/ts-pf-openapi/). Sync with `npx skills experimental_sync -y`.
+
+The catalog is the portable spec. This package is the **polyglot** export. For a TypeScript client in another repo, use [`@ts-pf/codegen`](../codegen) (`emit` → `createClient<Contract>`), not OpenAPI-TS.
+
+This package does **not** serve HTTP, embed Scalar/Swagger, invent REST paths, or change `FetchHandler`. Path params, GET/PUT, and flattened bodies are out.
+
+```ts
+import { catalog, docs } from '@ts-pf/docs'
+import { openapi } from '@ts-pf/openapi'
+
+procedure.meta(docs({ description: 'Find a planet by id' }))
+
+const spec = openapi(catalog(contract, { prefix: '/rpc' }), {
+  info: { title: 'Planet API', version: '1.0.0' },
+  servers: [{ url: 'https://api.example.com' }],
+})
+```
+
+Every path is `POST {prefix}/{router keys}` with body `{ "input": … }` and `{ "ok": true, "output": … }` / `{ "ok": false, "error": { "code", "message", "data?" } }`. The protocol header comes from `catalog.protocol`.
+
+Serve the JSON in userland, **outside** the RPC prefix (`GET /rpc/...` is not a spec):
+
+```ts
+if (url.pathname === '/openapi.json') {
+  return Response.json(spec)
+}
+const result = await handler.handle(req, { prefix: '/rpc', context })
+```
+
+Point Scalar or Swagger UI at that URL. Do not put those UIs in this package.
+
+`openapi()` is a dumb projection of the catalog. Filter/hide procedures with `catalog(..., { filter })`. Mutate the returned object for `security`, extra `components`, or operation overrides.
+
+Stream procedures advertise `application/jsonl` (item schema from the catalog). Pass `sse: true` to also list `text/event-stream`. Pass `multipart: true` to also list `multipart/form-data` on unary requests. Default is JSON (and JSONL for streams).
+
+`$ref` values inside converted JSON Schema (`#/$defs/…`) are rewritten to the component they live under. `$anchor` / `$dynamicAnchor` across schemas are not rewritten.
+
+Message transports (WebSocket, stdio, MessagePort) are not HTTP and are not in this document.
+
+Typed split-repo clients: [`@ts-pf/codegen`](../codegen).

package/dist/envelope.d.ts

@@ -0,0 +1,6 @@
+import type { CatalogSchema, JsonSchema } from '@ts-pf/docs';
+export declare function innerFromCatalog(schema: CatalogSchema | undefined): JsonSchema | undefined;
+export declare function requestEnvelope(input?: JsonSchema): JsonSchema;
+export declare function successEnvelope(output?: JsonSchema): JsonSchema;
+export declare function failureEnvelope(code: string, data?: JsonSchema): JsonSchema;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE5D,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,UAAU,GAAG,SAAS,CAcxB;AAED,wBAAgB,eAAe,CAAC,KAAK,CAAC,EAAE,UAAU,GAAG,UAAU,CAkB9D;AAED,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,UAAU,CAe/D;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,UAAU,CAwB3E"}

package/dist/envelope.js

@@ -0,0 +1,76 @@
+export function innerFromCatalog(schema) {
+    if (schema === undefined) {
+        return undefined;
+    }
+    if (schema.kind === 'json') {
+        return schema.jsonSchema;
+    }
+    if (schema.kind === 'unavailable') {
+        return { description: `Schema unavailable: ${schema.reason}` };
+    }
+    if (schema.kind === 'stream') {
+        return innerFromCatalog(schema.item) ?? {};
+    }
+    return undefined;
+}
+export function requestEnvelope(input) {
+    if (input === undefined) {
+        return {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                input: { type: 'null' },
+            },
+        };
+    }
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['input'],
+        properties: {
+            input,
+        },
+    };
+}
+export function successEnvelope(output) {
+    const properties = {
+        ok: { const: true },
+    };
+    const required = ['ok'];
+    if (output !== undefined) {
+        properties.output = output;
+        required.push('output');
+    }
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required,
+        properties,
+    };
+}
+export function failureEnvelope(code, data) {
+    const properties = {
+        code: { const: code },
+        message: { type: 'string' },
+    };
+    const required = ['code', 'message'];
+    if (data !== undefined) {
+        properties.data = data;
+        required.push('data');
+    }
+    return {
+        type: 'object',
+        additionalProperties: false,
+        required: ['ok', 'error'],
+        properties: {
+            ok: { const: false },
+            error: {
+                type: 'object',
+                additionalProperties: false,
+                required,
+                properties,
+            },
+        },
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,gBAAgB,CAC9B,MAAiC;IAEjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3B,OAAO,MAAM,CAAC,UAAU,CAAA;IAC1B,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;QAClC,OAAO,EAAE,WAAW,EAAE,uBAAuB,MAAM,CAAC,MAAM,EAAE,EAAE,CAAA;IAChE,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,CAAA;IAC5C,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,oBAAoB,EAAE,KAAK;YAC3B,UAAU,EAAE;gBACV,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;aACxB;SACF,CAAA;IACH,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,QAAQ,EAAE,CAAC,OAAO,CAAC;QACnB,UAAU,EAAE;YACV,KAAK;SACN;KACF,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,MAAmB;IACjD,MAAM,UAAU,GAA4B;QAC1C,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;KACpB,CAAA;IACD,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAA;IACvB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,UAAU,CAAC,MAAM,GAAG,MAAM,CAAA;QAC1B,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACzB,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,QAAQ;QACR,UAAU;KACX,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,IAAiB;IAC7D,MAAM,UAAU,GAA4B;QAC1C,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE;QACrB,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;KAC5B,CAAA;IACD,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACpC,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,UAAU,CAAC,IAAI,GAAG,IAAI,CAAA;QACtB,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IACvB,CAAC;IACD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,oBAAoB,EAAE,KAAK;QAC3B,QAAQ,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;QACzB,UAAU,EAAE;YACV,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;YACpB,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,oBAAoB,EAAE,KAAK;gBAC3B,QAAQ;gBACR,UAAU;aACX;SACF;KACF,CAAA;AACH,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,16 @@
+import type { CatalogProcedure, JsonSchema, ProcedureCatalog } from '@ts-pf/docs';
+export declare function protocolErrorRefs(catalog: ProcedureCatalog, schemas: Record<string, JsonSchema>): Map<string, JsonSchema>;
+export declare function operationErrorResponses(proc: CatalogProcedure, options: {
+    includeProtocolErrors: boolean;
+    catalog: ProcedureCatalog;
+    schemas: Record<string, JsonSchema>;
+    protocolRefs: Map<string, JsonSchema>;
+}): Record<string, {
+    description: string;
+    content: {
+        'application/json': {
+            schema: JsonSchema;
+        };
+    };
+}>;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,gBAAgB,EACjB,MAAM,aAAa,CAAA;AAapB,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,GAClC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAWzB;AAED,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;IACP,qBAAqB,EAAE,OAAO,CAAA;IAC9B,OAAO,EAAE,gBAAgB,CAAA;IACzB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACnC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CACtC,GACA,MAAM,CACP,MAAM,EACN;IACE,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE;QAAE,kBAAkB,EAAE;YAAE,MAAM,EAAE,UAAU,CAAA;SAAE,CAAA;KAAE,CAAA;CACxD,CACF,CA4EA"}

package/dist/errors.js

@@ -0,0 +1,79 @@
+import { failureEnvelope, innerFromCatalog } from './envelope.js';
+import { protocolErrorSchemaName, schemaName } from './names.js';
+import { putSchema } from './refs.js';
+const SKIP_PROTOCOL = new Set(['METHOD_NOT_ALLOWED', 'NOT_FOUND']);
+export function protocolErrorRefs(catalog, schemas) {
+    const refs = new Map();
+    for (const err of catalog.protocolErrors) {
+        const name = protocolErrorSchemaName(err.code);
+        const data = innerFromCatalog(err.data);
+        refs.set(err.code, putSchema(schemas, name, failureEnvelope(err.code, data)));
+    }
+    return refs;
+}
+export function operationErrorResponses(proc, options) {
+    const groups = new Map();
+    const add = (status, entry) => {
+        const list = groups.get(status) ?? [];
+        if (list.some((existing) => existing.code === entry.code)) {
+            return;
+        }
+        list.push(entry);
+        groups.set(status, list);
+    };
+    for (const err of proc.errors) {
+        const status = err.status ?? 400;
+        const name = schemaName(proc.path, `Error.${err.code}`);
+        const data = innerFromCatalog(err.data);
+        add(status, {
+            code: err.code,
+            description: err.message ?? err.code,
+            schema: putSchema(options.schemas, name, failureEnvelope(err.code, data)),
+        });
+    }
+    if (options.includeProtocolErrors) {
+        for (const err of options.catalog.protocolErrors) {
+            if (SKIP_PROTOCOL.has(err.code)) {
+                continue;
+            }
+            if (err.code === 'VALIDATION' && proc.input === undefined) {
+                continue;
+            }
+            const schema = options.protocolRefs.get(err.code);
+            if (schema === undefined) {
+                continue;
+            }
+            add(err.status, {
+                code: err.code,
+                description: err.code,
+                schema,
+            });
+        }
+    }
+    const responses = {};
+    const statuses = [...groups.keys()].sort((a, b) => a - b);
+    for (const status of statuses) {
+        const entries = groups.get(status);
+        if (entries === undefined || entries.length === 0) {
+            continue;
+        }
+        const first = entries[0];
+        if (first === undefined) {
+            continue;
+        }
+        const schema = entries.length === 1
+            ? first.schema
+            : { oneOf: entries.map((entry) => entry.schema) };
+        const description = entries.length === 1
+            ? first.description
+            : entries.map((entry) => entry.code).join(', ');
+        responses[String(status)] = {
+            description,
+            content: {
+                'application/json': { schema },
+            },
+        };
+    }
+    return responses;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { openapi } from './openapi.js';
+export type { OpenAPIDocument, OpenAPIOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { openapi } from './openapi.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/dist/names.d.ts

@@ -0,0 +1,6 @@
+export declare function sanitizeSegment(value: string): string;
+export declare function operationId(path: readonly string[]): string;
+export declare function schemaName(path: readonly string[], suffix: string): string;
+export declare function protocolErrorSchemaName(code: string): string;
+export declare function operationPath(href: string | undefined, key: string): string;
+//# sourceMappingURL=names.d.ts.map

package/dist/names.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.d.ts","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAEA,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGrD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK3D;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAG1E;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAG3E"}

package/dist/names.js

@@ -0,0 +1,23 @@
+const UNSAFE = /[^A-Za-z0-9._-]/g;
+export function sanitizeSegment(value) {
+    const next = value.replace(UNSAFE, '_');
+    return next.length > 0 ? next : '_';
+}
+export function operationId(path) {
+    if (path.length === 0) {
+        return '_';
+    }
+    return path.map(sanitizeSegment).join('.');
+}
+export function schemaName(path, suffix) {
+    const safeSuffix = suffix.split('.').map(sanitizeSegment).join('.');
+    return `${operationId(path)}.${safeSuffix}`;
+}
+export function protocolErrorSchemaName(code) {
+    return `TsPf.Error.${sanitizeSegment(code)}`;
+}
+export function operationPath(href, key) {
+    const raw = href ?? (key === '' ? '/' : `/${key}`);
+    return raw.startsWith('/') ? raw : `/${raw}`;
+}
+//# sourceMappingURL=names.js.map

package/dist/names.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"names.js","sourceRoot":"","sources":["../src/names.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,GAAG,kBAAkB,CAAA;AAEjC,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;IACvC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAuB;IACjD,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AAC5C,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAuB,EAAE,MAAc;IAChE,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IACnE,OAAO,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,UAAU,EAAE,CAAA;AAC7C,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,IAAY;IAClD,OAAO,cAAc,eAAe,CAAC,IAAI,CAAC,EAAE,CAAA;AAC9C,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAwB,EAAE,GAAW;IACjE,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAA;IAClD,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,EAAE,CAAA;AAC9C,CAAC"}

package/dist/openapi.d.ts

@@ -0,0 +1,4 @@
+import type { ProcedureCatalog } from '@ts-pf/docs';
+import type { OpenAPIDocument, OpenAPIOptions } from './types.js';
+export declare function openapi(catalog: ProcedureCatalog, options: OpenAPIOptions): OpenAPIDocument;
+//# sourceMappingURL=openapi.d.ts.map

package/dist/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAG/D,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAEf,MAAM,YAAY,CAAA;AAKnB,wBAAgB,OAAO,CACrB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,cAAc,GACtB,eAAe,CAqEjB"}

package/dist/openapi.js

@@ -0,0 +1,90 @@
+import { protocolErrorRefs } from './errors.js';
+import { toPathEntry } from './operation.js';
+const JSON_SCHEMA_DIALECT = 'https://json-schema.org/draft/2020-12/schema';
+export function openapi(catalog, options) {
+    if (catalog.catalogVersion !== 1) {
+        throw new Error(`Unsupported catalogVersion: ${String(catalog.catalogVersion)}`);
+    }
+    if (!Array.isArray(catalog.procedures)) {
+        throw new Error('catalog.procedures must be an array');
+    }
+    if (options.info.title.trim() === '' || options.info.version.trim() === '') {
+        throw new Error('info.title and info.version are required');
+    }
+    const schemas = {};
+    const includeProtocolErrors = options.protocolErrors !== false;
+    const protocolRefs = includeProtocolErrors
+        ? protocolErrorRefs(catalog, schemas)
+        : new Map();
+    const paths = {};
+    const tags = [];
+    const seenTags = new Set();
+    for (const proc of catalog.procedures) {
+        const entry = toPathEntry(proc, {
+            catalog,
+            openapi: options,
+            schemas,
+            protocolRefs,
+            includeProtocolErrors,
+        });
+        paths[entry.path] = entry.item;
+        if (entry.tags !== undefined) {
+            for (const tag of entry.tags) {
+                if (!seenTags.has(tag)) {
+                    seenTags.add(tag);
+                    tags.push(tag);
+                }
+            }
+        }
+    }
+    const document = {
+        openapi: '3.1.0',
+        info: copyInfo(options.info),
+        jsonSchemaDialect: JSON_SCHEMA_DIALECT,
+        paths,
+        components: {
+            schemas,
+            parameters: {
+                TsPfProtocol: {
+                    name: catalog.protocol.header.name,
+                    in: 'header',
+                    required: true,
+                    schema: {
+                        type: 'string',
+                        const: catalog.protocol.header.value,
+                    },
+                },
+            },
+        },
+    };
+    if (options.servers !== undefined) {
+        document.servers = options.servers;
+    }
+    if (tags.length > 0) {
+        document.tags = tags.map((name) => ({ name }));
+    }
+    return document;
+}
+function copyInfo(info) {
+    const out = {
+        title: info.title,
+        version: info.version,
+    };
+    if (info.summary !== undefined) {
+        out.summary = info.summary;
+    }
+    if (info.description !== undefined) {
+        out.description = info.description;
+    }
+    if (info.termsOfService !== undefined) {
+        out.termsOfService = info.termsOfService;
+    }
+    if (info.contact !== undefined) {
+        out.contact = info.contact;
+    }
+    if (info.license !== undefined) {
+        out.license = info.license;
+    }
+    return out;
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAQ5C,MAAM,mBAAmB,GACvB,8CAAuD,CAAA;AAEzD,MAAM,UAAU,OAAO,CACrB,OAAyB,EACzB,OAAuB;IAEvB,IAAI,OAAO,CAAC,cAAc,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,IAAI,KAAK,CACb,+BAA+B,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAChE,CAAA;IACH,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;IACxD,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC3E,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAA;IAC7D,CAAC;IAED,MAAM,OAAO,GAA+B,EAAE,CAAA;IAC9C,MAAM,qBAAqB,GAAG,OAAO,CAAC,cAAc,KAAK,KAAK,CAAA;IAC9D,MAAM,YAAY,GAAG,qBAAqB;QACxC,CAAC,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,CAAC;QACrC,CAAC,CAAC,IAAI,GAAG,EAAsB,CAAA;IAEjC,MAAM,KAAK,GAA6B,EAAE,CAAA;IAC1C,MAAM,IAAI,GAAa,EAAE,CAAA;IACzB,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAA;IAElC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QACtC,MAAM,KAAK,GAAG,WAAW,CAAC,IAAI,EAAE;YAC9B,OAAO;YACP,OAAO,EAAE,OAAO;YAChB,OAAO;YACP,YAAY;YACZ,qBAAqB;SACtB,CAAC,CAAA;QACF,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAA;QAC9B,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC7B,KAAK,MAAM,GAAG,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;gBAC7B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACvB,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;oBACjB,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;gBAChB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,QAAQ,GAAoB;QAChC,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC;QAC5B,iBAAiB,EAAE,mBAAmB;QACtC,KAAK;QACL,UAAU,EAAE;YACV,OAAO;YACP,UAAU,EAAE;gBACV,YAAY,EAAE;oBACZ,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI;oBAClC,EAAE,EAAE,QAAQ;oBACZ,QAAQ,EAAE,IAAI;oBACd,MAAM,EAAE;wBACN,IAAI,EAAE,QAAQ;wBACd,KAAK,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK;qBACrC;iBACF;aACF;SACF;KACF,CAAA;IACD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAClC,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpB,QAAQ,CAAC,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAA;IAChD,CAAC;IACD,OAAO,QAAQ,CAAA;AACjB,CAAC;AAED,SAAS,QAAQ,CAAC,IAAiB;IACjC,MAAM,GAAG,GAAgB;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,OAAO,EAAE,IAAI,CAAC,OAAO;KACtB,CAAA;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;IAC5B,CAAC;IACD,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;QACnC,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;IACpC,CAAC;IACD,IAAI,IAAI,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACtC,GAAG,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAA;IAC1C,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;IAC5B,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAA;IAC5B,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/operation.d.ts

@@ -0,0 +1,14 @@
+import type { CatalogProcedure, JsonSchema, ProcedureCatalog } from '@ts-pf/docs';
+import type { OpenAPIOptions, PathItem } from './types.js';
+export declare function toPathEntry(proc: CatalogProcedure, options: {
+    catalog: ProcedureCatalog;
+    openapi: OpenAPIOptions;
+    schemas: Record<string, JsonSchema>;
+    protocolRefs: Map<string, JsonSchema>;
+    includeProtocolErrors: boolean;
+}): {
+    path: string;
+    item: PathItem;
+    tags?: string[];
+};
+//# sourceMappingURL=operation.d.ts.map

package/dist/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,UAAU,EACV,gBAAgB,EACjB,MAAM,aAAa,CAAA;AAapB,OAAO,KAAK,EAEV,cAAc,EAGd,QAAQ,EACT,MAAM,YAAY,CAAA;AAEnB,wBAAgB,WAAW,CACzB,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE;IACP,OAAO,EAAE,gBAAgB,CAAA;IACzB,OAAO,EAAE,cAAc,CAAA;IACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACnC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACrC,qBAAqB,EAAE,OAAO,CAAA;CAC/B,GACA;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAWnD"}

package/dist/operation.js

@@ -0,0 +1,130 @@
+import { innerFromCatalog, requestEnvelope, successEnvelope, } from './envelope.js';
+import { operationErrorResponses } from './errors.js';
+import { operationId as makeOperationId, operationPath, schemaName, } from './names.js';
+import { putSchema } from './refs.js';
+export function toPathEntry(proc, options) {
+    const operation = toOperation(proc, options);
+    const item = { post: operation };
+    const result = {
+        path: operationPath(proc.href, proc.key),
+        item,
+    };
+    if (operation.tags !== undefined) {
+        result.tags = operation.tags;
+    }
+    return result;
+}
+function toOperation(proc, options) {
+    const requestName = schemaName(proc.path, 'Request');
+    const successName = schemaName(proc.path, 'Success');
+    const requestInner = innerFromCatalog(proc.input);
+    const successInner = innerFromCatalog(proc.output);
+    const requestSchema = putSchema(options.schemas, requestName, requestEnvelope(hasInput(proc) ? requestInner : undefined));
+    const successSchema = putSchema(options.schemas, successName, successEnvelope(hasOutput(proc) ? successInner : undefined));
+    const operation = {
+        operationId: makeOperationId(proc.path),
+        parameters: [{ $ref: '#/components/parameters/TsPfProtocol' }],
+        requestBody: requestBody(proc, requestSchema, options.openapi),
+        responses: {
+            '200': successResponse(proc, successSchema, options),
+            ...operationErrorResponses(proc, options),
+        },
+    };
+    if (proc.docs?.summary !== undefined) {
+        operation.summary = proc.docs.summary;
+    }
+    if (proc.docs?.description !== undefined) {
+        operation.description = proc.docs.description;
+    }
+    if (proc.docs?.deprecated === true) {
+        operation.deprecated = true;
+    }
+    const tags = tagsFor(proc);
+    if (tags !== undefined) {
+        operation.tags = tags;
+    }
+    return operation;
+}
+function requestBody(proc, requestSchema, options) {
+    const content = {};
+    if (isStream(proc.input)) {
+        content['application/jsonl'] = { schema: requestSchema };
+    }
+    else {
+        content['application/json'] = { schema: requestSchema };
+        if (options.multipart === true) {
+            content['multipart/form-data'] = {
+                schema: {
+                    type: 'object',
+                    required: ['rpc'],
+                    properties: { rpc: requestSchema },
+                    additionalProperties: {
+                        type: 'string',
+                        contentMediaType: 'application/octet-stream',
+                    },
+                },
+            };
+        }
+    }
+    const body = { content };
+    if (hasInput(proc)) {
+        body.required = true;
+    }
+    if (options.multipart === true && !isStream(proc.input)) {
+        body.description =
+            'JSON RPC envelope, or multipart with JSON part `rpc` plus numbered file parts (see ts-pf PROTOCOL.md).';
+    }
+    return body;
+}
+function successResponse(proc, successSchema, options) {
+    const headerName = options.catalog.protocol.header.name;
+    const headerValue = options.catalog.protocol.header.value;
+    const headers = {
+        [headerName]: {
+            required: true,
+            schema: { type: 'string', const: headerValue },
+        },
+    };
+    if (isStream(proc.output)) {
+        const content = {
+            'application/jsonl': { schema: successSchema },
+        };
+        const response = {
+            description: 'RPC success stream. HTTP status stays 200 after the stream starts; in-band `{ ok: false, error }` lines are failures; EOF ends the stream.',
+            headers,
+            content,
+        };
+        if (options.openapi.sse === true) {
+            content['text/event-stream'] = { schema: successSchema };
+            response.description = `${response.description} SSE framing uses event: message / error / close; data: is the same JSONL line.`;
+        }
+        return response;
+    }
+    return {
+        description: 'RPC success',
+        headers,
+        content: {
+            'application/json': { schema: successSchema },
+        },
+    };
+}
+function tagsFor(proc) {
+    if (proc.docs?.tags !== undefined && proc.docs.tags.length > 0) {
+        return [...proc.docs.tags];
+    }
+    const first = proc.path[0];
+    if (proc.path.length > 1 && first !== undefined) {
+        return [first];
+    }
+    return undefined;
+}
+function isStream(schema) {
+    return schema?.kind === 'stream';
+}
+function hasInput(proc) {
+    return proc.input !== undefined;
+}
+function hasOutput(proc) {
+    return proc.output !== undefined;
+}
+//# sourceMappingURL=operation.js.map

package/dist/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"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"}

package/dist/refs.d.ts

@@ -0,0 +1,4 @@
+import type { JsonSchema } from '@ts-pf/docs';
+export declare function relocateRefs(schema: JsonSchema, componentName: string): JsonSchema;
+export declare function putSchema(schemas: Record<string, JsonSchema>, name: string, schema: JsonSchema): JsonSchema;
+//# sourceMappingURL=refs.d.ts.map

package/dist/refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.d.ts","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C,wBAAgB,YAAY,CAC1B,MAAM,EAAE,UAAU,EAClB,aAAa,EAAE,MAAM,GACpB,UAAU,CAGZ;AAsCD,wBAAgB,SAAS,CACvB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,UAAU,GACjB,UAAU,CAGZ"}

package/dist/refs.js

@@ -0,0 +1,42 @@
+export function relocateRefs(schema, componentName) {
+    const prefix = `#/components/schemas/${componentName}`;
+    return walk(schema, prefix);
+}
+function walk(value, prefix) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => walk(entry, prefix));
+    }
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const obj = value;
+    const out = {};
+    for (const [key, child] of Object.entries(obj)) {
+        if ((key === '$ref' || key === '$dynamicRef') &&
+            typeof child === 'string' &&
+            child.startsWith('#')) {
+            out[key] = rewriteRef(child, prefix);
+        }
+        else {
+            out[key] = walk(child, prefix);
+        }
+    }
+    return out;
+}
+function rewriteRef(ref, prefix) {
+    if (ref.startsWith('#/components/')) {
+        return ref;
+    }
+    if (ref === '#') {
+        return prefix;
+    }
+    if (ref.startsWith('#/')) {
+        return `${prefix}${ref.slice(1)}`;
+    }
+    return ref;
+}
+export function putSchema(schemas, name, schema) {
+    schemas[name] = relocateRefs(schema, name);
+    return { $ref: `#/components/schemas/${name}` };
+}
+//# sourceMappingURL=refs.js.map

package/dist/refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refs.js","sourceRoot":"","sources":["../src/refs.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAC1B,MAAkB,EAClB,aAAqB;IAErB,MAAM,MAAM,GAAG,wBAAwB,aAAa,EAAE,CAAA;IACtD,OAAO,IAAI,CAAC,MAAM,EAAE,MAAM,CAAe,CAAA;AAC3C,CAAC;AAED,SAAS,IAAI,CAAC,KAAc,EAAE,MAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IACD,MAAM,GAAG,GAAG,KAAgC,CAAA;IAC5C,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/C,IACE,CAAC,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,aAAa,CAAC;YACzC,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EACrB,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QACtC,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,SAAS,UAAU,CAAC,GAAW,EAAE,MAAc;IAC7C,IAAI,GAAG,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;QACpC,OAAO,GAAG,CAAA;IACZ,CAAC;IACD,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,MAAM,CAAA;IACf,CAAC;IACD,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,OAAmC,EACnC,IAAY,EACZ,MAAkB;IAElB,OAAO,CAAC,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAC1C,OAAO,EAAE,IAAI,EAAE,wBAAwB,IAAI,EAAE,EAAE,CAAA;AACjD,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,92 @@
+import type { JsonSchema } from '@ts-pf/docs';
+export type OpenAPIInfo = {
+    title: string;
+    version: string;
+    summary?: string;
+    description?: string;
+    termsOfService?: string;
+    contact?: {
+        name?: string;
+        url?: string;
+        email?: string;
+    };
+    license?: {
+        name: string;
+        url?: string;
+    };
+};
+export type OpenAPIServer = {
+    url: string;
+    description?: string;
+};
+export type OpenAPIOptions = {
+    info: OpenAPIInfo;
+    servers?: ReadonlyArray<OpenAPIServer>;
+    /** Default true. Attach protocol errors that can occur on a matched POST. */
+    protocolErrors?: boolean;
+    /**
+     * For `kind: 'stream'` outputs, also advertise `text/event-stream`.
+     * Default false — catalog does not know the codec.
+     */
+    sse?: boolean;
+    /**
+     * Also advertise `multipart/form-data` request bodies (approximate).
+     * Default false — files are a codec, not in the catalog.
+     */
+    multipart?: boolean;
+};
+export type OpenAPIMediaType = {
+    schema?: JsonSchema;
+};
+export type OpenAPIRequestBody = {
+    required?: boolean;
+    description?: string;
+    content: Record<string, OpenAPIMediaType>;
+};
+export type OpenAPIResponseHeader = {
+    schema?: JsonSchema;
+    required?: boolean;
+    description?: string;
+};
+export type OpenAPIResponse = {
+    description: string;
+    headers?: Record<string, OpenAPIResponseHeader>;
+    content?: Record<string, OpenAPIMediaType>;
+};
+export type OpenAPIParameter = {
+    name: string;
+    in: 'header' | 'query' | 'path' | 'cookie';
+    required?: boolean;
+    schema?: JsonSchema;
+};
+export type OpenAPIRef = {
+    $ref: string;
+};
+export type OpenAPIOperation = {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    deprecated?: boolean;
+    parameters?: Array<OpenAPIParameter | OpenAPIRef>;
+    requestBody?: OpenAPIRequestBody;
+    responses: Record<string, OpenAPIResponse>;
+};
+export type PathItem = {
+    post?: OpenAPIOperation;
+};
+export type OpenAPIDocument = {
+    openapi: '3.1.0';
+    info: OpenAPIInfo;
+    jsonSchemaDialect?: string;
+    servers?: ReadonlyArray<OpenAPIServer>;
+    tags?: Array<{
+        name: string;
+    }>;
+    paths: Record<string, PathItem>;
+    components: {
+        schemas: Record<string, JsonSchema>;
+        parameters?: Record<string, OpenAPIParameter>;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@ts-pf/openapi",
+  "version": "0.1.0-beta.0",
+  "description": "Opt-in OpenAPI 3.1 document from catalog() (POST JSON RPC)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crobinson42/ts-pf.git",
+    "directory": "packages/openapi"
+  },
+  "homepage": "https://github.com/crobinson42/ts-pf/tree/main/packages/openapi#readme",
+  "bugs": {
+    "url": "https://github.com/crobinson42/ts-pf/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit",
+    "lint": "biome check src tests"
+  },
+  "dependencies": {
+    "@ts-pf/docs": "0.1.0-beta.0"
+  },
+  "devDependencies": {
+    "@ts-pf/contract": "0.1.0-beta.0",
+    "@ts-pf/stream": "0.1.0-beta.0",
+    "typebox": "^1.3.24",
+    "zod": "^4.0.0"
+  }
+}

package/skills/ts-pf-openapi/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: ts-pf-openapi
+description: Use when projecting a ts-pf catalog() to OpenAPI 3.1 with openapi(). Triggers: @ts-pf/openapi, openapi(), OpenAPI 3.1, POST JSON RPC spec.
+---
+
+# @ts-pf/openapi
+
+OpenAPI 3.1 projection of `catalog()`. POST JSON RPC only. Not a runtime.
+
+Install: `npm i @ts-pf/openapi@beta`
+
+Link for agents: `npx skills experimental_sync -y`
+
+## Do
+
+```ts
+import { catalog, docs } from '@ts-pf/docs'
+import { openapi } from '@ts-pf/openapi'
+
+procedure.meta(docs({ description: 'Find a planet by id' }))
+
+const spec = openapi(catalog(contract, { prefix: '/rpc' }), {
+  info: { title: 'Planet API', version: '1.0.0' },
+})
+```
+
+Every path is `POST {prefix}/{router keys}`. Serve JSON in userland (`GET /openapi.json`), not from `FetchHandler`. Point Scalar/Swagger at that URL — do not embed those UIs here.
+
+Typed split-repo clients: `ts-pf-codegen`, not OpenAPI-TS.
+
+## API
+
+- `openapi`
+- `OpenAPIOptions` (`sse: true` / `multipart: true` advertise those content types), `OpenAPIDocument`
+
+## Pair with
+
+- Catalog: `ts-pf-docs`
+- Typed client `.d.ts`: `ts-pf-codegen`
+
+## Don't
+
+- GET/PUT/path params or flattened REST bodies.
+- Serve the spec from `FetchHandler`.
+- Message transports (not HTTP) in this document.