@schemavaults/openapi-operations 0.1.4

package/dist/openapi/build-openapi-document.js

@@ -0,0 +1,124 @@
+import { OpenAPIRegistry, OpenApiGeneratorV31, } from "@asteasolutions/zod-to-openapi";
+import { assertUniqueOperations } from "../operation";
+import { SCHEMAVAULTS_AUTH_EXTENSION, SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION, SCHEMAVAULTS_SCHEME_TITLE_EXTENSION, toSchemaVaultsAuthExtension, } from "./extensions";
+/** Every distinct auth scheme referenced by the operations (first definition wins per name). */
+export function collectAuthSchemes(operations, additional = []) {
+    const byName = new Map();
+    const add = (scheme) => {
+        const existing = byName.get(scheme.name);
+        if (existing && existing !== scheme) {
+            const same = JSON.stringify(existing.securityScheme) === JSON.stringify(scheme.securityScheme);
+            if (!same) {
+                throw new TypeError(`Auth scheme "${scheme.name}" is defined twice with different security scheme objects`);
+            }
+            return;
+        }
+        byName.set(scheme.name, scheme);
+    };
+    for (const scheme of additional)
+        add(scheme);
+    for (const operation of operations) {
+        if (operation.auth.type === "required") {
+            for (const scheme of operation.auth.schemes)
+                add(scheme);
+        }
+    }
+    return [...byName.values()];
+}
+export function toSecuritySchemeComponent(scheme) {
+    return {
+        ...scheme.securityScheme,
+        description: scheme.securityScheme.description ?? scheme.description,
+        [SCHEMAVAULTS_SCHEME_TITLE_EXTENSION]: scheme.title,
+        ...(scheme.challenge !== undefined
+            ? { [SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION]: scheme.challenge }
+            : {}),
+    };
+}
+function toSecurityRequirements(operation) {
+    if (operation.auth.type === "public")
+        return [];
+    const scopes = [...(operation.auth.requiredScopes ?? [])];
+    return operation.auth.schemes.map((scheme) => ({ [scheme.name]: scopes }));
+}
+/** zod-to-openapi route config for one operation (also usable with `@hono/zod-openapi`). */
+export function toRouteConfig(operation) {
+    const responses = {};
+    for (const [status, response] of Object.entries(operation.responses)) {
+        responses[status] = {
+            description: response.description,
+            ...(response.headers ? { headers: response.headers } : {}),
+            ...(response.schema
+                ? {
+                    content: {
+                        [response.contentType ?? "application/json"]: { schema: response.schema },
+                    },
+                }
+                : {}),
+        };
+    }
+    const { params, query, headers, body } = operation.request;
+    return {
+        method: operation.method,
+        path: operation.path,
+        operationId: operation.operationId,
+        summary: operation.summary,
+        ...(operation.description !== undefined ? { description: operation.description } : {}),
+        tags: [...operation.tags],
+        ...(operation.deprecated ? { deprecated: true } : {}),
+        security: toSecurityRequirements(operation),
+        request: {
+            ...(params ? { params } : {}),
+            ...(query ? { query } : {}),
+            ...(headers ? { headers } : {}),
+            ...(body
+                ? {
+                    body: {
+                        required: body.required ?? true,
+                        ...(body.description !== undefined ? { description: body.description } : {}),
+                        content: {
+                            [body.contentType ?? "application/json"]: { schema: body.schema },
+                        },
+                    },
+                }
+                : {}),
+        },
+        responses,
+        [SCHEMAVAULTS_AUTH_EXTENSION]: toSchemaVaultsAuthExtension(operation.auth),
+        ...(operation.extensions ?? {}),
+    };
+}
+/**
+ * Builds an OpenAPI 3.1 document from operation definitions using
+ * `@asteasolutions/zod-to-openapi`. Zod schemas registered with
+ * `.openapi("RefId")` are emitted under `components.schemas`.
+ */
+export function buildOpenApiDocument(options) {
+    assertUniqueOperations(options.operations);
+    const registry = new OpenAPIRegistry();
+    for (const scheme of collectAuthSchemes(options.operations, options.additionalAuthSchemes)) {
+        registry.registerComponent("securitySchemes", scheme.name, toSecuritySchemeComponent(scheme));
+    }
+    for (const operation of options.operations) {
+        registry.registerPath(toRouteConfig(operation));
+    }
+    const declaredTags = new Map();
+    for (const tag of options.tags ?? [])
+        declaredTags.set(tag.name, tag);
+    for (const operation of options.operations) {
+        for (const tag of operation.tags) {
+            if (!declaredTags.has(tag))
+                declaredTags.set(tag, { name: tag });
+        }
+    }
+    const generator = new OpenApiGeneratorV31(registry.definitions);
+    return generator.generateDocument({
+        openapi: "3.1.0",
+        info: options.info,
+        ...(options.servers ? { servers: [...options.servers] } : {}),
+        ...(declaredTags.size > 0 ? { tags: [...declaredTags.values()] } : {}),
+        ...(options.externalDocs ? { externalDocs: options.externalDocs } : {}),
+        ...(options.extensions ?? {}),
+    });
+}
+//# sourceMappingURL=build-openapi-document.js.map

package/dist/openapi/build-openapi-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-openapi-document.js","sourceRoot":"","sources":["../../src/openapi/build-openapi-document.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,mBAAmB,GAGpB,MAAM,gCAAgC,CAAC;AAYxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,OAAO,EACL,2BAA2B,EAC3B,uCAAuC,EACvC,mCAAmC,EACnC,2BAA2B,GAC5B,MAAM,cAAc,CAAC;AAetB,gGAAgG;AAChG,MAAM,UAAU,kBAAkB,CAChC,UAA6C,EAC7C,aAA8C,EAAE;IAEhD,MAAM,MAAM,GAAG,IAAI,GAAG,EAAgC,CAAC;IACvD,MAAM,GAAG,GAAG,CAAC,MAA4B,EAAQ,EAAE;QACjD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,QAAQ,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;YACpC,MAAM,IAAI,GACR,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;YACpF,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,MAAM,IAAI,SAAS,CACjB,gBAAgB,MAAM,CAAC,IAAI,2DAA2D,CACvF,CAAC;YACJ,CAAC;YACD,OAAO;QACT,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAClC,CAAC,CAAC;IACF,KAAK,MAAM,MAAM,IAAI,UAAU;QAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvC,KAAK,MAAM,MAAM,IAAI,SAAS,CAAC,IAAI,CAAC,OAAO;gBAAE,GAAG,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,MAA4B;IACpE,OAAO;QACL,GAAG,MAAM,CAAC,cAAc;QACxB,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW;QACpE,CAAC,mCAAmC,CAAC,EAAE,MAAM,CAAC,KAAK;QACnD,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS;YAChC,CAAC,CAAC,EAAE,CAAC,uCAAuC,CAAC,EAAE,MAAM,CAAC,SAAS,EAAE;YACjE,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;AACJ,CAAC;AAED,SAAS,sBAAsB,CAAC,SAAiC;IAC/D,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1D,OAAO,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,aAAa,CAAC,SAAiC;IAC7D,MAAM,SAAS,GAAmC,EAAE,CAAC;IACrD,KAAK,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QACrE,SAAS,CAAC,MAAM,CAAC,GAAG;YAClB,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1D,GAAG,CAAC,QAAQ,CAAC,MAAM;gBACjB,CAAC,CAAC;oBACE,OAAO,EAAE;wBACP,CAAC,QAAQ,CAAC,WAAW,IAAI,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE;qBAC1E;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,SAAS,CAAC,OAAO,CAAC;IAC3D,OAAO;QACL,MAAM,EAAE,SAAS,CAAC,MAAM;QACxB,IAAI,EAAE,SAAS,CAAC,IAAI;QACpB,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,OAAO,EAAE,SAAS,CAAC,OAAO;QAC1B,GAAG,CAAC,SAAS,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtF,IAAI,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC;QACzB,GAAG,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrD,QAAQ,EAAE,sBAAsB,CAAC,SAAS,CAAC;QAC3C,OAAO,EAAE;YACP,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3B,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/B,GAAG,CAAC,IAAI;gBACN,CAAC,CAAC;oBACE,IAAI,EAAE;wBACJ,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI;wBAC/B,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;wBAC5E,OAAO,EAAE;4BACP,CAAC,IAAI,CAAC,WAAW,IAAI,kBAAkB,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE;yBAClE;qBACF;iBACF;gBACH,CAAC,CAAC,EAAE,CAAC;SACR;QACD,SAAS;QACT,CAAC,2BAA2B,CAAC,EAAE,2BAA2B,CAAC,SAAS,CAAC,IAAI,CAAC;QAC1E,GAAG,CAAC,SAAS,CAAC,UAAU,IAAI,EAAE,CAAC;KAChC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAoC;IACvE,sBAAsB,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,eAAe,EAAE,CAAC;IAEvC,KAAK,MAAM,MAAM,IAAI,kBAAkB,CAAC,OAAO,CAAC,UAAU,EAAE,OAAO,CAAC,qBAAqB,CAAC,EAAE,CAAC;QAC3F,QAAQ,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,EAAE,yBAAyB,CAAC,MAAM,CAAC,CAAC,CAAC;IAChG,CAAC;IACD,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,QAAQ,CAAC,YAAY,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC;IAClD,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,EAAqB,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,IAAI,EAAE;QAAE,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtE,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;QAC3C,KAAK,MAAM,GAAG,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;YACjC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;QACnE,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,IAAI,mBAAmB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;IAChE,OAAO,SAAS,CAAC,gBAAgB,CAAC;QAChC,OAAO,EAAE,OAAO;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,YAAY,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;KAC9B,CAAC,CAAC;AACL,CAAC"}

package/dist/openapi/extensions.d.ts

@@ -0,0 +1,26 @@
+import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/organizations";
+import type { OperationAuth, RouteGuardType } from "../auth-scheme";
+/**
+ * Vendor extension attached to every operation object so API docs can show
+ * the SchemaVaults authorization requirements that plain OpenAPI `security`
+ * requirements cannot express (route guard level, organization role).
+ */
+export declare const SCHEMAVAULTS_AUTH_EXTENSION: "x-schemavaults-auth";
+/** Extra keys on `components.securitySchemes[name]` describing the scheme for docs. */
+export declare const SCHEMAVAULTS_SCHEME_TITLE_EXTENSION: "x-schemavaults-title";
+export declare const SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION: "x-schemavaults-challenge";
+export interface SchemaVaultsAuthExtension {
+    readonly public: boolean;
+    /** Names of the accepted security schemes (any one satisfies the operation). */
+    readonly schemes: readonly string[];
+    readonly routeGuard: RouteGuardType | null;
+    readonly requiredScopes: readonly string[];
+    readonly organization: {
+        readonly parameter: string;
+        readonly roles: readonly OrganizationMembershipRoleType[];
+        readonly adminBypass: boolean;
+    } | null;
+    readonly notes?: string;
+}
+export declare function toSchemaVaultsAuthExtension(auth: OperationAuth): SchemaVaultsAuthExtension;
+export declare function isSchemaVaultsAuthExtension(value: unknown): value is SchemaVaultsAuthExtension;

package/dist/openapi/extensions.js

@@ -0,0 +1,47 @@
+/**
+ * Vendor extension attached to every operation object so API docs can show
+ * the SchemaVaults authorization requirements that plain OpenAPI `security`
+ * requirements cannot express (route guard level, organization role).
+ */
+export const SCHEMAVAULTS_AUTH_EXTENSION = "x-schemavaults-auth";
+/** Extra keys on `components.securitySchemes[name]` describing the scheme for docs. */
+export const SCHEMAVAULTS_SCHEME_TITLE_EXTENSION = "x-schemavaults-title";
+export const SCHEMAVAULTS_SCHEME_CHALLENGE_EXTENSION = "x-schemavaults-challenge";
+export function toSchemaVaultsAuthExtension(auth) {
+    if (auth.type === "public") {
+        return {
+            public: true,
+            schemes: [],
+            routeGuard: null,
+            requiredScopes: [],
+            organization: null,
+            ...(auth.notes !== undefined ? { notes: auth.notes } : {}),
+        };
+    }
+    return {
+        public: false,
+        schemes: auth.schemes.map((scheme) => scheme.name),
+        routeGuard: auth.routeGuard ?? "authenticated",
+        requiredScopes: [...(auth.requiredScopes ?? [])],
+        organization: auth.organization
+            ? {
+                parameter: auth.organization.parameter,
+                roles: [...auth.organization.roles],
+                adminBypass: auth.organization.adminBypass ?? true,
+            }
+            : null,
+        ...(auth.notes !== undefined ? { notes: auth.notes } : {}),
+    };
+}
+export function isSchemaVaultsAuthExtension(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    return (typeof record.public === "boolean" &&
+        Array.isArray(record.schemes) &&
+        Array.isArray(record.requiredScopes) &&
+        (record.routeGuard === null ||
+            record.routeGuard === "authenticated" ||
+            record.routeGuard === "admin"));
+}
+//# sourceMappingURL=extensions.js.map

package/dist/openapi/extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extensions.js","sourceRoot":"","sources":["../../src/openapi/extensions.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,qBAA8B,CAAC;AAE1E,uFAAuF;AACvF,MAAM,CAAC,MAAM,mCAAmC,GAAG,sBAA+B,CAAC;AACnF,MAAM,CAAC,MAAM,uCAAuC,GAAG,0BAAmC,CAAC;AAgB3F,MAAM,UAAU,2BAA2B,CAAC,IAAmB;IAC7D,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,OAAO;YACL,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,EAAE;YACX,UAAU,EAAE,IAAI;YAChB,cAAc,EAAE,EAAE;YAClB,YAAY,EAAE,IAAI;YAClB,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3D,CAAC;IACJ,CAAC;IACD,OAAO;QACL,MAAM,EAAE,KAAK;QACb,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC;QAClD,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,eAAe;QAC9C,cAAc,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,CAAC,CAAC;QAChD,YAAY,EAAE,IAAI,CAAC,YAAY;YAC7B,CAAC,CAAC;gBACE,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,SAAS;gBACtC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC;gBACnC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,WAAW,IAAI,IAAI;aACnD;YACH,CAAC,CAAC,IAAI;QACR,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,KAAc;IACxD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC9D,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,OAAO,CACL,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS;QAClC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;QAC7B,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC;QACpC,CAAC,MAAM,CAAC,UAAU,KAAK,IAAI;YACzB,MAAM,CAAC,UAAU,KAAK,eAAe;YACrC,MAAM,CAAC,UAAU,KAAK,OAAO,CAAC,CACjC,CAAC;AACJ,CAAC"}

package/dist/openapi/path-format.d.ts

@@ -0,0 +1,7 @@
+export declare function isOpenApiPath(path: string): boolean;
+/** Names of the `{placeholders}` in an OpenAPI path, in order. */
+export declare function extractPathParameterNames(path: string): string[];
+/** `/api/apps/{app_id}` → `/api/apps/:app_id` (Hono / Express style). */
+export declare function openApiPathToHonoPath(path: string): string;
+/** `/api/apps/:app_id` → `/api/apps/{app_id}`. */
+export declare function honoPathToOpenApiPath(path: string): string;

package/dist/openapi/path-format.js

@@ -0,0 +1,26 @@
+const OPENAPI_PATH_PARAM_REGEX = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+export function isOpenApiPath(path) {
+    return (typeof path === "string" &&
+        path.startsWith("/") &&
+        !path.includes(":") &&
+        !/\{[^}]*[^A-Za-z0-9_}][^}]*\}/.test(path));
+}
+/** Names of the `{placeholders}` in an OpenAPI path, in order. */
+export function extractPathParameterNames(path) {
+    const names = [];
+    for (const match of path.matchAll(OPENAPI_PATH_PARAM_REGEX)) {
+        const name = match[1];
+        if (typeof name === "string")
+            names.push(name);
+    }
+    return names;
+}
+/** `/api/apps/{app_id}` → `/api/apps/:app_id` (Hono / Express style). */
+export function openApiPathToHonoPath(path) {
+    return path.replace(OPENAPI_PATH_PARAM_REGEX, ":$1");
+}
+/** `/api/apps/:app_id` → `/api/apps/{app_id}`. */
+export function honoPathToOpenApiPath(path) {
+    return path.replace(/:([A-Za-z_][A-Za-z0-9_]*)/g, "{$1}");
+}
+//# sourceMappingURL=path-format.js.map

package/dist/openapi/path-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-format.js","sourceRoot":"","sources":["../../src/openapi/path-format.ts"],"names":[],"mappings":"AAAA,MAAM,wBAAwB,GAAG,+BAA+B,CAAC;AAEjE,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,OAAO,CACL,OAAO,IAAI,KAAK,QAAQ;QACxB,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QACpB,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC;QACnB,CAAC,8BAA8B,CAAC,IAAI,CAAC,IAAI,CAAC,CAC3C,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,wBAAwB,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,IAAI,CAAC,OAAO,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,IAAI,CAAC,OAAO,CAAC,4BAA4B,EAAE,MAAM,CAAC,CAAC;AAC5D,CAAC"}

package/dist/operation.d.ts

@@ -0,0 +1,168 @@
+import type { z, ZodObject, ZodType } from "zod";
+import type { OrganizationMembershipRoleType } from "@schemavaults/auth-common/organizations";
+import { type HttpMethod } from "./http-method";
+import type { OperationAuth, PublicOperationAuth } from "./auth-scheme";
+export type RequestBodyContentType = "application/json" | "application/x-www-form-urlencoded" | "multipart/form-data" | "text/plain" | (string & {});
+export interface RequestBodyDefinition<TSchema extends ZodType = ZodType> {
+    /** Media type the body is parsed as (default `application/json`). */
+    readonly contentType?: RequestBodyContentType;
+    readonly schema: TSchema;
+    readonly description?: string;
+    /** Default true. */
+    readonly required?: boolean;
+}
+export interface ResponseDefinition<TSchema extends ZodType | undefined = ZodType | undefined> {
+    readonly description: string;
+    /** Omit for empty responses (204, 304, redirects, ...). */
+    readonly schema?: TSchema;
+    /** Media type of the response body (default `application/json`). */
+    readonly contentType?: string;
+    /** Documented response headers. */
+    readonly headers?: ZodObject;
+}
+export type ResponsesDefinition = Readonly<Record<number, ResponseDefinition>>;
+export interface OperationRequestDefinition<TParams extends ZodObject | undefined = ZodObject | undefined, TQuery extends ZodObject | undefined = ZodObject | undefined, THeaders extends ZodObject | undefined = ZodObject | undefined, TBody extends RequestBodyDefinition | undefined = RequestBodyDefinition | undefined> {
+    /** Path parameters; keys must match the `{placeholders}` in `path`. */
+    readonly params?: TParams;
+    /** Query string parameters (repeated keys arrive as `string[]`). */
+    readonly query?: TQuery;
+    /** Request headers (lower-case keys). */
+    readonly headers?: THeaders;
+    readonly body?: TBody;
+}
+export type InferParsed<T> = T extends ZodType ? z.output<T> : Readonly<Record<string, never>>;
+export type InferBody<T> = T extends RequestBodyDefinition<infer S> ? S extends ZodType ? z.output<S> : undefined : undefined;
+export type ResponseStatusOf<TResponses extends ResponsesDefinition> = Extract<keyof TResponses, number>;
+export type ResponseBodyOf<TResponses extends ResponsesDefinition, S extends keyof TResponses> = TResponses[S] extends {
+    readonly schema: infer TSchema;
+} ? TSchema extends ZodType ? z.output<TSchema> : undefined : undefined;
+export type EmptyResponseStatusOf<TResponses extends ResponsesDefinition> = {
+    [S in ResponseStatusOf<TResponses>]: TResponses[S] extends {
+        readonly schema: ZodType;
+    } ? never : S;
+}[ResponseStatusOf<TResponses>];
+/**
+ * Result of a successful credential resolution for one auth scheme. Built
+ * by the {@link AuthResolver} registered for the scheme, so its `user` type
+ * is whatever the host application resolves (e.g. `UserData` from
+ * `@schemavaults/auth-common` on the auth server).
+ */
+export interface AuthPrincipal<TUser = unknown> {
+    /** Name of the auth scheme whose resolver produced this principal. */
+    readonly scheme: string;
+    /** Resolved user, or null for non-user principals (client credentials, api keys). */
+    readonly user: TUser | null;
+    /** Platform administrator flag, used for the "admin" route guard and org bypass. */
+    readonly isAdmin: boolean;
+    /**
+     * Space separated scope string granted to the presented token (RFC 6749
+     * §3.3), or null when the credential carries no scope claim.
+     */
+    readonly scope: string | null;
+    /** OAuth client id for client-credential style principals. */
+    readonly clientId?: string;
+    /**
+     * Resolves the principal's membership role in an organization, used for
+     * {@link OrganizationRoleRequirement}. Absent means "cannot be a member".
+     */
+    readonly getOrganizationRole?: (organizationId: string) => Promise<OrganizationMembershipRoleType | false>;
+}
+export interface ResponseInit_ {
+    readonly headers?: HeadersInit;
+}
+export interface OperationHandlerContext<TParams, TQuery, THeaders, TBody, TResponses extends ResponsesDefinition, TContext, TAuth> {
+    readonly params: TParams;
+    readonly query: TQuery;
+    readonly headers: THeaders;
+    readonly body: TBody;
+    /** Resolved principal, or null on public operations. */
+    readonly auth: TAuth;
+    /** Host-provided per-request context (database handle, environment, ...). */
+    readonly context: TContext;
+    readonly request: Request;
+    readonly url: URL;
+    /** Type-checked JSON response for one of the declared status codes. */
+    json<S extends ResponseStatusOf<TResponses>>(status: S, body: ResponseBodyOf<TResponses, S>, init?: ResponseInit_): Response;
+    /** Body-less response for a declared status code without a schema. */
+    empty(status: EmptyResponseStatusOf<TResponses>, init?: ResponseInit_): Response;
+    redirect(location: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+}
+export type OperationHandlerResult = Response | Promise<Response>;
+export interface OperationDefinition<TParams extends ZodObject | undefined = ZodObject | undefined, TQuery extends ZodObject | undefined = ZodObject | undefined, THeaders extends ZodObject | undefined = ZodObject | undefined, TBody extends RequestBodyDefinition | undefined = RequestBodyDefinition | undefined, TResponses extends ResponsesDefinition = ResponsesDefinition, TContext = unknown, TUser = unknown, TAuth extends OperationAuth = OperationAuth> {
+    readonly method: HttpMethod;
+    /** OpenAPI style path with `{param}` placeholders, e.g. `/api/apps/{app_id}`. */
+    readonly path: string;
+    /** Unique id; defaults to `<method>_<path>` slug. */
+    readonly operationId: string;
+    readonly summary: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly deprecated?: boolean;
+    readonly auth: TAuth;
+    readonly request: OperationRequestDefinition<TParams, TQuery, THeaders, TBody>;
+    readonly responses: TResponses;
+    /** Extra OpenAPI vendor extensions merged into the operation object. */
+    readonly extensions?: Readonly<Record<`x-${string}`, unknown>>;
+    handler(ctx: OperationHandlerContext<InferParsed<TParams>, InferParsed<TQuery>, InferParsed<THeaders>, InferBody<TBody>, TResponses, TContext, TAuth extends PublicOperationAuth ? null : AuthPrincipal<TUser>>): OperationHandlerResult;
+}
+/**
+ * Structural, type-erased view of any operation definition. Every
+ * `OperationDefinition<...>` is assignable to it, so heterogeneous
+ * operation lists can be passed to `buildOpenApiDocument` and
+ * `createOperationsApp`.
+ */
+export interface AnyOperationDefinition {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly operationId: string;
+    readonly summary: string;
+    readonly description?: string;
+    readonly tags: readonly string[];
+    readonly deprecated?: boolean;
+    readonly auth: OperationAuth;
+    readonly request: OperationRequestDefinition;
+    readonly responses: ResponsesDefinition;
+    readonly extensions?: Readonly<Record<`x-${string}`, unknown>>;
+    handler(ctx: any): OperationHandlerResult;
+}
+export interface OperationInput<TParams extends ZodObject | undefined, TQuery extends ZodObject | undefined, THeaders extends ZodObject | undefined, TBody extends RequestBodyDefinition | undefined, TResponses extends ResponsesDefinition, TContext, TUser, TAuth extends OperationAuth> {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly operationId?: string;
+    readonly summary: string;
+    readonly description?: string;
+    readonly tags?: readonly string[];
+    readonly deprecated?: boolean;
+    readonly auth: TAuth;
+    readonly request?: OperationRequestDefinition<TParams, TQuery, THeaders, TBody>;
+    readonly responses: TResponses;
+    readonly extensions?: Readonly<Record<`x-${string}`, unknown>>;
+    readonly handler: OperationDefinition<TParams, TQuery, THeaders, TBody, TResponses, TContext, TUser, TAuth>["handler"];
+}
+export type OperationDefiner<TContext, TUser> = <const TParams extends ZodObject | undefined = undefined, const TQuery extends ZodObject | undefined = undefined, const THeaders extends ZodObject | undefined = undefined, const TBody extends RequestBodyDefinition | undefined = undefined, const TResponses extends ResponsesDefinition = ResponsesDefinition, const TAuth extends OperationAuth = OperationAuth>(input: OperationInput<TParams, TQuery, THeaders, TBody, TResponses, TContext, TUser, TAuth>) => OperationDefinition<TParams, TQuery, THeaders, TBody, TResponses, TContext, TUser, TAuth>;
+export declare function defaultOperationId(method: HttpMethod, path: string): string;
+/**
+ * Creates a `defineOperation` bound to the host application's per-request
+ * context and resolved user types:
+ *
+ * ```ts
+ * const defineOperation = createOperationDefiner<{ dbh: Kysely<AuthDatabase> }, UserData>();
+ * ```
+ */
+export declare function createOperationDefiner<TContext = unknown, TUser = unknown>(): OperationDefiner<TContext, TUser>;
+/** Untyped-context `defineOperation`; prefer {@link createOperationDefiner} in apps. */
+export declare const defineOperation: OperationDefiner<unknown, unknown>;
+export interface OperationGroup {
+    /** Tags applied to every operation (prepended to the operation's own). */
+    readonly tags?: readonly string[];
+    /** Path prefix (OpenAPI style) prepended to every operation path. */
+    readonly pathPrefix?: string;
+    readonly operations: readonly AnyOperationDefinition[];
+}
+/**
+ * Flattens a group into standalone operations, applying the shared tags and
+ * path prefix. The result can be passed to `buildOpenApiDocument` and
+ * `createOperationsApp` like any other operation list.
+ */
+export declare function defineOperationGroup(group: OperationGroup): AnyOperationDefinition[];
+export declare function assertUniqueOperations(operations: readonly AnyOperationDefinition[]): void;

package/dist/operation.js

@@ -0,0 +1,111 @@
+import { HTTP_METHODS_WITH_REQUEST_BODY, isHttpMethod } from "./http-method";
+import { extractPathParameterNames, isOpenApiPath } from "./openapi/path-format";
+export function defaultOperationId(method, path) {
+    const slug = path
+        .replace(/[{}]/g, "")
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .join("_")
+        .replace(/[^A-Za-z0-9_]+/g, "_");
+    return slug.length > 0 ? `${method}_${slug}` : method;
+}
+function validateOperationInput(input) {
+    if (!isHttpMethod(input.method)) {
+        throw new TypeError(`Unsupported HTTP method "${String(input.method)}"`);
+    }
+    if (!isOpenApiPath(input.path)) {
+        throw new TypeError(`Operation path "${input.path}" must start with "/" and use {param} placeholders`);
+    }
+    if (typeof input.summary !== "string" || input.summary.trim().length === 0) {
+        throw new TypeError(`Operation ${input.method.toUpperCase()} ${input.path} needs a summary`);
+    }
+    const placeholders = extractPathParameterNames(input.path);
+    const declared = input.request?.params
+        ? Object.keys(input.request.params.shape)
+        : [];
+    for (const name of placeholders) {
+        if (!declared.includes(name)) {
+            throw new TypeError(`Path parameter {${name}} of ${input.path} is not declared in request.params`);
+        }
+    }
+    for (const name of declared) {
+        if (!placeholders.includes(name)) {
+            throw new TypeError(`request.params declares "${name}" but ${input.path} has no {${name}} placeholder`);
+        }
+    }
+    if (input.request?.body && !HTTP_METHODS_WITH_REQUEST_BODY.has(input.method)) {
+        throw new TypeError(`${input.method.toUpperCase()} ${input.path} declares a request body, which is not allowed for that method`);
+    }
+    const statuses = Object.keys(input.responses);
+    if (statuses.length === 0) {
+        throw new TypeError(`${input.method.toUpperCase()} ${input.path} declares no responses`);
+    }
+    for (const status of statuses) {
+        const code = Number(status);
+        if (!Number.isInteger(code) || code < 100 || code > 599) {
+            throw new TypeError(`Invalid response status "${status}" on ${input.path}`);
+        }
+    }
+}
+/**
+ * Creates a `defineOperation` bound to the host application's per-request
+ * context and resolved user types:
+ *
+ * ```ts
+ * const defineOperation = createOperationDefiner<{ dbh: Kysely<AuthDatabase> }, UserData>();
+ * ```
+ */
+export function createOperationDefiner() {
+    return function defineOperationForContext(input) {
+        validateOperationInput(input);
+        const operation = {
+            method: input.method,
+            path: input.path,
+            operationId: input.operationId ?? defaultOperationId(input.method, input.path),
+            summary: input.summary,
+            description: input.description,
+            tags: Object.freeze([...(input.tags ?? [])]),
+            deprecated: input.deprecated,
+            auth: input.auth,
+            request: input.request ?? {},
+            responses: input.responses,
+            extensions: input.extensions,
+            handler: input.handler,
+        };
+        return Object.freeze(operation);
+    };
+}
+/** Untyped-context `defineOperation`; prefer {@link createOperationDefiner} in apps. */
+export const defineOperation = createOperationDefiner();
+/**
+ * Flattens a group into standalone operations, applying the shared tags and
+ * path prefix. The result can be passed to `buildOpenApiDocument` and
+ * `createOperationsApp` like any other operation list.
+ */
+export function defineOperationGroup(group) {
+    const prefix = group.pathPrefix ?? "";
+    if (prefix.length > 0 && !isOpenApiPath(prefix)) {
+        throw new TypeError(`Group pathPrefix "${prefix}" must start with "/"`);
+    }
+    return group.operations.map((operation) => {
+        const path = prefix.length > 0 ? `${prefix.replace(/\/+$/, "")}${operation.path}` : operation.path;
+        const tags = Array.from(new Set([...(group.tags ?? []), ...operation.tags]));
+        return Object.freeze({ ...operation, path, tags });
+    });
+}
+export function assertUniqueOperations(operations) {
+    const ids = new Set();
+    const routes = new Set();
+    for (const operation of operations) {
+        if (ids.has(operation.operationId)) {
+            throw new TypeError(`Duplicate operationId "${operation.operationId}"`);
+        }
+        ids.add(operation.operationId);
+        const route = `${operation.method} ${operation.path}`;
+        if (routes.has(route)) {
+            throw new TypeError(`Duplicate route ${route.toUpperCase()}`);
+        }
+        routes.add(route);
+    }
+}
+//# sourceMappingURL=operation.js.map

package/dist/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../src/operation.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,8BAA8B,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9F,OAAO,EAAE,yBAAyB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA+RjF,MAAM,UAAU,kBAAkB,CAAC,MAAkB,EAAE,IAAY;IACjE,MAAM,IAAI,GAAG,IAAI;SACd,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;SACvC,IAAI,CAAC,GAAG,CAAC;SACT,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AACxD,CAAC;AAED,SAAS,sBAAsB,CAAC,KAM/B;IACC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,SAAS,CAAC,4BAA4B,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC3E,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,SAAS,CACjB,mBAAmB,KAAK,CAAC,IAAI,oDAAoD,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,SAAS,CAAC,aAAa,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,kBAAkB,CAAC,CAAC;IAC/F,CAAC;IACD,MAAM,YAAY,GAAG,yBAAyB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAa,KAAK,CAAC,OAAO,EAAE,MAAM;QAC9C,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC;QACzC,CAAC,CAAC,EAAE,CAAC;IACP,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;QAChC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7B,MAAM,IAAI,SAAS,CACjB,mBAAmB,IAAI,QAAQ,KAAK,CAAC,IAAI,oCAAoC,CAC9E,CAAC;QACJ,CAAC;IACH,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,IAAI,SAAS,CACjB,4BAA4B,IAAI,SAAS,KAAK,CAAC,IAAI,YAAY,IAAI,eAAe,CACnF,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,EAAE,IAAI,IAAI,CAAC,8BAA8B,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7E,MAAM,IAAI,SAAS,CACjB,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,gEAAgE,CAC5G,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,SAAS,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC,WAAW,EAAE,IAAI,KAAK,CAAC,IAAI,wBAAwB,CAAC,CAAC;IAC3F,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,GAAG,IAAI,IAAI,GAAG,GAAG,EAAE,CAAC;YACxD,MAAM,IAAI,SAAS,CAAC,4BAA4B,MAAM,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9E,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB;IAIpC,OAAO,SAAS,yBAAyB,CAAC,KAAK;QAC7C,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC9B,MAAM,SAAS,GAAG;YAChB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,kBAAkB,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,IAAI,CAAC;YAC9E,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;YAC5C,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,SAAS,EAAE,KAAK,CAAC,SAAS;YAC1B,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;QACF,OAAO,MAAM,CAAC,MAAM,CAAC,SAAS,CAAkD,CAAC;IACnF,CAAsC,CAAC;AACzC,CAAC;AAED,wFAAwF;AACxF,MAAM,CAAC,MAAM,eAAe,GAC1B,sBAAsB,EAAoB,CAAC;AAc7C;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,KAAqB;IACxD,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC;IACtC,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,SAAS,CAAC,qBAAqB,MAAM,uBAAuB,CAAC,CAAC;IAC1E,CAAC;IACD,OAAO,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,SAAS,EAA0B,EAAE;QAChE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC;QACnG,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7E,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,UAA6C;IAClF,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,CAAC;YACnC,MAAM,IAAI,SAAS,CAAC,0BAA0B,SAAS,CAAC,WAAW,GAAG,CAAC,CAAC;QAC1E,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,WAAW,CAAC,CAAC;QAC/B,MAAM,KAAK,GAAG,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC;QACtD,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,IAAI,SAAS,CAAC,mBAAmB,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QAChE,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACpB,CAAC;AACH,CAAC"}

package/dist/runtime/create-operations-app.d.ts

@@ -0,0 +1,40 @@
+import { Hono, type Context } from "hono";
+import type { OpenAPIObject } from "openapi3-ts/oas31";
+import type { AnyOperationDefinition } from "../operation";
+import { type AuthResolvers } from "./resolve-auth";
+export interface OpenApiDocumentRouteOptions {
+    /** Path (relative to `basePath`) serving the JSON document. Default `/openapi.json`. */
+    readonly path?: string;
+    /**
+     * The document, or a function producing it per request. The function
+     * receives the Hono context so hosts can derive request-dependent parts
+     * such as `servers` from the incoming Host / X-Forwarded-* headers.
+     */
+    readonly document: OpenAPIObject | ((c: Context) => OpenAPIObject | Promise<OpenAPIObject>);
+}
+export interface CreateOperationsAppOptions<TContext = unknown, TUser = unknown> {
+    readonly operations: readonly AnyOperationDefinition[];
+    /**
+     * Prefix stripped by the deployment before routing (e.g. `/api` when the
+     * app is mounted from `app/api/[[...route]]/route.ts`). Operation paths
+     * stay absolute in the OpenAPI document; leave unset to route on them
+     * verbatim.
+     */
+    readonly basePath?: string;
+    /** Credential resolvers keyed by auth scheme name. */
+    readonly authResolvers?: AuthResolvers<TUser>;
+    /** Builds the per-request context handed to handlers as `ctx.context`. */
+    readonly context?: (c: Context) => Promise<TContext> | TContext;
+    /** Serve the OpenAPI document from the app; omit to not expose it. */
+    readonly openapi?: OpenApiDocumentRouteOptions;
+    /** Called for unexpected (non-OperationError) failures before the 500 is sent. */
+    readonly onError?: (error: unknown, c: Context) => void | Promise<void>;
+    /** Extra middleware / routes registered before the operations (CORS, logging, ...). */
+    readonly configure?: (app: Hono) => void;
+}
+/**
+ * Builds a Hono app that routes, validates, authenticates and dispatches
+ * the given operations. Mount it on Vercel functions with
+ * `toVercelHandler()` or Next.js route handlers with `toNextRouteHandlers()`.
+ */
+export declare function createOperationsApp<TContext = unknown, TUser = unknown>(options: CreateOperationsAppOptions<TContext, TUser>): Hono;