@openapi-press/spec

Typed interactions with a generated OpenAPI paths type.

The spec model

openapi-press clients are built from types generated by openapi-typescript: a paths interface describing every path, method, parameter, body, and response an API declares. This package is the layer that reads those types. Everything it exports is derivable from a user's spec — it knows nothing about transport, configuration, or how a client is assembled.

It works in two planes. Type-level utilities derive call-signature material from the spec: positional path-param tuples parsed from {param} templates, query/body input shapes with their optionality rules, and success payload types. At runtime it provides operation descriptors — branded op(method, path) references into the spec that client layers compose into namespace trees — plus the parser that binds positional arguments back to named path params.

Usage

import { defineSpec } from "@openapi-press/spec";
import type { paths } from "./schema.gen";

const { op } = defineSpec<paths>();

// Descriptors are checked against the spec: the path must exist and carry
// the method.
export const users = {
  list: op("get", "/users"),
  get: op("get", "/users/{user_id}"),
  accounts: {
    unlink: op("delete", "/users/{user_id}/accounts/{account_id}"),
  },
};

API

• defineSpec<Paths>() — binds a generated paths type; returns a SpecBuilder whose op(method, path) produces spec-checked descriptors.
• makeOp(method, path) — creates a branded descriptor without spec checking; the machine-facing counterpart to defineSpec.
• isOp(value) — whether a value is a branded descriptor (a leaf, as opposed to a namespace branch).
• extractParams(path) — {param} names of a path template, in order.
• Operation<Paths, M, P> — the operation object for a (method, path) pair.
• PathParamNames<P> / PathParamObject<Op> / PathArgs<Names, PP> — the {param} grammar at the type level: template names, their declared types, and the positional tuple they form.
• QueryOption<Op> / BodyOption<Op> / OpOptions<Op> — the input an operation admits beyond path params, with optionality derived from the spec.
• OpData<Op> — the success (2xx) JSON payload an operation resolves to.