@smithers-orchestrator/openapi 0.16.0

package/src/index.d.ts

@@ -0,0 +1,287 @@
+import * as effect from 'effect';
+import { Effect } from 'effect';
+import { z } from 'zod';
+import { Tool } from 'ai';
+import * as effect_MetricState from 'effect/MetricState';
+import * as effect_MetricKeyType from 'effect/MetricKeyType';
+
+type HttpMethod = "get" | "post" | "put" | "delete" | "patch";
+
+type RefObject$1 = {
+    $ref: string;
+};
+
+type SchemaObject$1 = {
+    type?: string;
+    format?: string;
+    description?: string;
+    properties?: Record<string, SchemaObject$1 | RefObject$1>;
+    required?: string[];
+    items?: SchemaObject$1 | RefObject$1;
+    enum?: unknown[];
+    default?: unknown;
+    nullable?: boolean;
+    oneOf?: Array<SchemaObject$1 | RefObject$1>;
+    anyOf?: Array<SchemaObject$1 | RefObject$1>;
+    allOf?: Array<SchemaObject$1 | RefObject$1>;
+    additionalProperties?: boolean | SchemaObject$1 | RefObject$1;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    $ref?: string;
+};
+
+type ParameterObject$1 = {
+    name: string;
+    in: "query" | "header" | "path" | "cookie";
+    description?: string;
+    required?: boolean;
+    schema?: SchemaObject$1 | RefObject$1;
+    deprecated?: boolean;
+};
+
+type MediaTypeObject = {
+    schema?: SchemaObject$1 | RefObject$1;
+};
+
+type RequestBodyObject$1 = {
+    description?: string;
+    required?: boolean;
+    content: Record<string, MediaTypeObject>;
+};
+
+type ParsedOperation$2 = {
+    operationId: string;
+    method: HttpMethod;
+    path: string;
+    summary: string;
+    description: string;
+    parameters: ParameterObject$1[];
+    requestBody?: RequestBodyObject$1;
+    deprecated: boolean;
+};
+
+type OpenApiAuth$1 = {
+    type: "bearer";
+    token: string;
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+} | {
+    type: "apiKey";
+    name: string;
+    value: string;
+    in: "header" | "query";
+};
+
+type OpenApiToolsOptions$5 = {
+    baseUrl?: string;
+    headers?: Record<string, string>;
+    auth?: OpenApiAuth$1;
+    include?: string[];
+    exclude?: string[];
+    namePrefix?: string;
+};
+
+type OperationObject = {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: Array<ParameterObject$1 | RefObject$1>;
+    requestBody?: RequestBodyObject$1 | RefObject$1;
+    responses?: Record<string, unknown>;
+    tags?: string[];
+    deprecated?: boolean;
+};
+
+type PathItem = {
+    get?: OperationObject;
+    post?: OperationObject;
+    put?: OperationObject;
+    delete?: OperationObject;
+    patch?: OperationObject;
+    parameters?: Array<ParameterObject$1 | RefObject$1>;
+};
+
+type OpenApiSpec$b = {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+        description?: string;
+    };
+    servers?: Array<{
+        url: string;
+        description?: string;
+    }>;
+    paths: Record<string, PathItem>;
+    components?: {
+        schemas?: Record<string, SchemaObject$1>;
+        parameters?: Record<string, ParameterObject$1>;
+        requestBodies?: Record<string, RequestBodyObject$1>;
+    };
+};
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./ParsedOperation.ts").ParsedOperation} ParsedOperation */
+/**
+ * Extract all operations from an OpenAPI spec.
+ *
+ * @param {OpenApiSpec} spec
+ * @returns {ParsedOperation[]}
+ */
+declare function extractOperations(spec: OpenApiSpec$a): ParsedOperation$1[];
+type OpenApiSpec$a = OpenApiSpec$b;
+type ParsedOperation$1 = ParsedOperation$2;
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/**
+ * Load an OpenAPI spec from a JSON/YAML string, URL, file path, or object.
+ *
+ * @param {string | OpenApiSpec} input
+ * @returns {Effect.Effect<OpenApiSpec, unknown>}
+ */
+declare function loadSpecEffect(input: string | OpenApiSpec$9): Effect.Effect<OpenApiSpec$9, unknown>;
+type OpenApiSpec$9 = OpenApiSpec$b;
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/**
+ * Synchronous version for simpler call sites.
+ *
+ * @param {string | OpenApiSpec} input
+ * @returns {OpenApiSpec}
+ */
+declare function loadSpecSync(input: string | OpenApiSpec$8): OpenApiSpec$8;
+type OpenApiSpec$8 = OpenApiSpec$b;
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./RefObject.ts").RefObject} RefObject */
+/** @typedef {import("./SchemaObject.ts").SchemaObject} SchemaObject */
+/**
+ * Convert an OpenAPI JSON Schema object to a Zod schema.
+ * Falls back to z.any() for schemas that cannot be cleanly represented.
+ *
+ * @param {SchemaObject | RefObject | undefined} schema
+ * @param {OpenApiSpec} spec
+ * @param {Set<string>} [visited]
+ * @returns {z.ZodType}
+ */
+declare function jsonSchemaToZod(schema: SchemaObject | RefObject | undefined, spec: OpenApiSpec$7, visited?: Set<string>): z.ZodType;
+type OpenApiSpec$7 = OpenApiSpec$b;
+type RefObject = RefObject$1;
+type SchemaObject = SchemaObject$1;
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./ParameterObject.ts").ParameterObject} ParameterObject */
+/** @typedef {import("./RequestBodyObject.ts").RequestBodyObject} RequestBodyObject */
+/**
+ * Build a single Zod object schema for an operation's input, combining:
+ * - path parameters
+ * - query parameters
+ * - header parameters
+ * - request body fields
+ *
+ * @param {ParameterObject[]} parameters
+ * @param {RequestBodyObject | undefined} requestBody
+ * @param {OpenApiSpec} spec
+ * @returns {z.ZodType}
+ */
+declare function buildOperationSchema(parameters: ParameterObject[], requestBody: RequestBodyObject | undefined, spec: OpenApiSpec$6): z.ZodType;
+type OpenApiSpec$6 = OpenApiSpec$b;
+type ParameterObject = ParameterObject$1;
+type RequestBodyObject = RequestBodyObject$1;
+
+/** @typedef {import("../OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("../OpenApiToolsOptions.ts").OpenApiToolsOptions} OpenApiToolsOptions */
+/**
+ * Create AI SDK tools from all operations in an OpenAPI spec.
+ *
+ * @param {string | OpenApiSpec} input - OpenAPI spec as JSON object, file path, URL, or raw text
+ * @param {OpenApiToolsOptions} [options] - Configuration for auth, filtering, base URL, etc.
+ * @returns {Promise<Record<string, any>>} Record of operationId → AI SDK tool
+ */
+declare function createOpenApiTools(input: string | OpenApiSpec$5, options?: OpenApiToolsOptions$4): Promise<Record<string, any>>;
+type OpenApiSpec$5 = OpenApiSpec$b;
+type OpenApiToolsOptions$4 = OpenApiToolsOptions$5;
+
+/** @typedef {import("../OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("../OpenApiToolsOptions.ts").OpenApiToolsOptions} OpenApiToolsOptions */
+/**
+ * Synchronous version — only works with specs that are objects or local files.
+ *
+ * @param {string | OpenApiSpec} input
+ * @param {OpenApiToolsOptions} [options]
+ * @returns {Record<string, any>}
+ */
+declare function createOpenApiToolsSync(input: string | OpenApiSpec$4, options?: OpenApiToolsOptions$3): Record<string, any>;
+type OpenApiSpec$4 = OpenApiSpec$b;
+type OpenApiToolsOptions$3 = OpenApiToolsOptions$5;
+
+/** @typedef {import("../OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("../OpenApiToolsOptions.ts").OpenApiToolsOptions} OpenApiToolsOptions */
+/**
+ * Create a single AI SDK tool from an OpenAPI spec by operationId.
+ *
+ * @param {string | OpenApiSpec} input - OpenAPI spec as JSON object, file path, URL, or raw text
+ * @param {string} operationId - The operationId of the operation to create a tool for
+ * @param {OpenApiToolsOptions} [options] - Configuration for auth, base URL, etc.
+ * @returns {Promise<any>} A single AI SDK tool
+ */
+declare function createOpenApiTool(input: string | OpenApiSpec$3, operationId: string, options?: OpenApiToolsOptions$2): Promise<any>;
+type OpenApiSpec$3 = OpenApiSpec$b;
+type OpenApiToolsOptions$2 = OpenApiToolsOptions$5;
+
+/**
+ * Type alias for an AI SDK tool produced from an OpenAPI operation.
+ * Re-exported here so JSDoc files can reference a stable name without
+ * reaching into the `ai` package directly.
+ */
+type OpenApiTool$1 = Tool;
+
+/** @typedef {import("../OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("../OpenApiTool.ts").OpenApiTool} OpenApiTool */
+/** @typedef {import("../OpenApiToolsOptions.ts").OpenApiToolsOptions} OpenApiToolsOptions */
+/**
+ * Synchronous version — only works with specs that are objects or local files.
+ *
+ * @param {string | OpenApiSpec} input
+ * @param {string} operationId
+ * @param {OpenApiToolsOptions} [options]
+ * @returns {OpenApiTool}
+ */
+declare function createOpenApiToolSync(input: string | OpenApiSpec$2, operationId: string, options?: OpenApiToolsOptions$1): OpenApiTool;
+type OpenApiSpec$2 = OpenApiSpec$b;
+type OpenApiTool = OpenApiTool$1;
+type OpenApiToolsOptions$1 = OpenApiToolsOptions$5;
+
+/** @typedef {import("../OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/**
+ * List all operations from a spec (for CLI preview).
+ *
+ * @param {string | OpenApiSpec} input
+ * @returns {Array<{ operationId: string; method: string; path: string; summary: string }>}
+ */
+declare function listOperations(input: string | OpenApiSpec$1): Array<{
+    operationId: string;
+    method: string;
+    path: string;
+    summary: string;
+}>;
+type OpenApiSpec$1 = OpenApiSpec$b;
+
+/** @type {import("effect").Metric.Metric.Counter<number>} */
+declare const openApiToolCallsTotal: effect.Metric.Metric.Counter<number>;
+/** @type {import("effect").Metric.Metric.Counter<number>} */
+declare const openApiToolCallErrorsTotal: effect.Metric.Metric.Counter<number>;
+/** @type {import("effect").Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>} */
+declare const openApiToolDuration: effect.Metric.Metric<effect_MetricKeyType.MetricKeyType.Histogram, number, effect_MetricState.MetricState.Histogram>;
+
+type OpenApiAuth = OpenApiAuth$1;
+type OpenApiSpec = OpenApiSpec$b;
+type OpenApiToolsOptions = OpenApiToolsOptions$5;
+type ParsedOperation = ParsedOperation$2;
+
+export { type OpenApiAuth, type OpenApiSpec, type OpenApiToolsOptions, type ParsedOperation, buildOperationSchema, createOpenApiTool, createOpenApiToolSync, createOpenApiTools, createOpenApiToolsSync, extractOperations, jsonSchemaToZod, listOperations, loadSpecEffect, loadSpecSync, openApiToolCallErrorsTotal, openApiToolCallsTotal, openApiToolDuration };

package/src/index.js

@@ -0,0 +1,17 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./OpenApiAuth.ts").OpenApiAuth} OpenApiAuth */
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./OpenApiToolsOptions.ts").OpenApiToolsOptions} OpenApiToolsOptions */
+/** @typedef {import("./ParsedOperation.ts").ParsedOperation} ParsedOperation */
+// @smithers-type-exports-end
+
+// ---------------------------------------------------------------------------
+// OpenAPI tool factory — public API
+// ---------------------------------------------------------------------------
+export { createOpenApiTools, createOpenApiToolsSync, createOpenApiTool, createOpenApiToolSync, listOperations, } from "./tool-factory/index.js";
+export { openApiToolCallsTotal, openApiToolCallErrorsTotal, openApiToolDuration, } from "./metrics.js";
+export { extractOperations } from "./extractOperations.js";
+export { loadSpecEffect } from "./loadSpecEffect.js";
+export { loadSpecSync } from "./loadSpecSync.js";
+export { jsonSchemaToZod } from "./jsonSchemaToZod.js";
+export { buildOperationSchema } from "./buildOperationSchema.js";

package/src/jsonSchemaToZod.js

@@ -0,0 +1,197 @@
+// ---------------------------------------------------------------------------
+// OpenAPI JSON Schema → Zod schema conversion
+// ---------------------------------------------------------------------------
+import { z } from "zod";
+import { isRef, resolveRef } from "./ref-resolver.js";
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./RefObject.ts").RefObject} RefObject */
+/** @typedef {import("./SchemaObject.ts").SchemaObject} SchemaObject */
+
+/**
+ * Convert an OpenAPI JSON Schema object to a Zod schema.
+ * Falls back to z.any() for schemas that cannot be cleanly represented.
+ *
+ * @param {SchemaObject | RefObject | undefined} schema
+ * @param {OpenApiSpec} spec
+ * @param {Set<string>} [visited]
+ * @returns {z.ZodType}
+ */
+export function jsonSchemaToZod(schema, spec, visited = new Set()) {
+    if (!schema)
+        return z.any();
+    // Resolve $ref
+    if (isRef(schema)) {
+        const ref = schema.$ref;
+        if (visited.has(ref)) {
+            // Circular reference — bail to z.any()
+            return z.any().describe(`Circular reference: ${ref}`);
+        }
+        visited.add(ref);
+        const resolved = resolveRef(spec, ref);
+        const result = jsonSchemaToZod(resolved, spec, visited);
+        visited.delete(ref);
+        return result;
+    }
+    const s = schema;
+    // allOf — merge into a single object
+    if (s.allOf && s.allOf.length > 0) {
+        // Build a combined object from all allOf entries
+        const schemas = s.allOf.map((sub) => jsonSchemaToZod(sub, spec, visited));
+        if (schemas.length === 1)
+            return maybeDescribe(schemas[0], s);
+        // For multiple schemas, try to intersect them
+        let result = schemas[0];
+        for (let i = 1; i < schemas.length; i++) {
+            result = z.intersection(result, schemas[i]);
+        }
+        return maybeDescribe(result, s);
+    }
+    // oneOf / anyOf — union
+    if (s.oneOf && s.oneOf.length > 0) {
+        return buildUnion(s.oneOf, spec, visited, s);
+    }
+    if (s.anyOf && s.anyOf.length > 0) {
+        return buildUnion(s.anyOf, spec, visited, s);
+    }
+    const type = s.type;
+    if (type === "string") {
+        return buildString(s);
+    }
+    if (type === "number" || type === "integer") {
+        return buildNumber(s);
+    }
+    if (type === "boolean") {
+        return maybeDescribe(z.boolean(), s);
+    }
+    if (type === "array") {
+        const items = jsonSchemaToZod(s.items, spec, visited);
+        return maybeDescribe(z.array(items), s);
+    }
+    if (type === "object" || s.properties) {
+        return buildObject(s, spec, visited);
+    }
+    // null type
+    if (type === "null") {
+        return maybeDescribe(z.null(), s);
+    }
+    // Fallback
+    const desc = s.description ? `${s.description} (untyped)` : "untyped schema";
+    return z.any().describe(desc);
+}
+// ---------------------------------------------------------------------------
+// Type-specific builders
+// ---------------------------------------------------------------------------
+/**
+ * @param {SchemaObject} s
+ * @returns {z.ZodType}
+ */
+function buildString(s) {
+    let schema;
+    if (s.enum && s.enum.length > 0) {
+        const values = s.enum;
+        schema = z.enum(values);
+    }
+    else {
+        let str = z.string();
+        if (s.minLength !== undefined)
+            str = str.min(s.minLength);
+        if (s.maxLength !== undefined)
+            str = str.max(s.maxLength);
+        if (s.pattern)
+            str = str.regex(new RegExp(s.pattern));
+        if (s.format === "email")
+            str = str.email();
+        if (s.format === "url" || s.format === "uri")
+            str = str.url();
+        schema = str;
+    }
+    return maybeDescribe(maybeNullable(maybeDefault(schema, s), s), s);
+}
+/**
+ * @param {SchemaObject} s
+ * @returns {z.ZodType}
+ */
+function buildNumber(s) {
+    let num = z.number();
+    if (s.type === "integer")
+        num = num.int();
+    if (s.minimum !== undefined)
+        num = num.min(s.minimum);
+    if (s.maximum !== undefined)
+        num = num.max(s.maximum);
+    return maybeDescribe(maybeNullable(maybeDefault(num, s), s), s);
+}
+/**
+ * @param {SchemaObject} s
+ * @param {OpenApiSpec} spec
+ * @param {Set<string>} visited
+ * @returns {z.ZodType}
+ */
+function buildObject(s, spec, visited) {
+    const props = {};
+    const required = new Set(s.required ?? []);
+    for (const [key, propSchema] of Object.entries(s.properties ?? {})) {
+        let zodProp = jsonSchemaToZod(propSchema, spec, visited);
+        if (!required.has(key)) {
+            zodProp = zodProp.optional();
+        }
+        props[key] = zodProp;
+    }
+    let obj = z.object(props);
+    if (s.additionalProperties === true || s.additionalProperties === undefined) {
+        // Allow additional properties — use catchall for objects with props
+        if (Object.keys(props).length > 0) {
+            obj = obj.catchall(z.unknown());
+        }
+    }
+    return maybeDescribe(maybeNullable(obj, s), s);
+}
+/**
+ * @param {Array<SchemaObject | RefObject>} variants
+ * @param {OpenApiSpec} spec
+ * @param {Set<string>} visited
+ * @param {SchemaObject} parent
+ * @returns {z.ZodType}
+ */
+function buildUnion(variants, spec, visited, parent) {
+    const schemas = variants.map((v) => jsonSchemaToZod(v, spec, visited));
+    if (schemas.length === 0)
+        return z.any();
+    if (schemas.length === 1)
+        return maybeDescribe(schemas[0], parent);
+    return maybeDescribe(z.union(schemas), parent);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * @param {z.ZodType} schema
+ * @param {SchemaObject} s
+ * @returns {z.ZodType}
+ */
+function maybeDescribe(schema, s) {
+    if (s.description)
+        return schema.describe(s.description);
+    return schema;
+}
+/**
+ * @param {z.ZodType} schema
+ * @param {SchemaObject} s
+ * @returns {z.ZodType}
+ */
+function maybeNullable(schema, s) {
+    if (s.nullable)
+        return schema.nullable();
+    return schema;
+}
+/**
+ * @param {z.ZodType} schema
+ * @param {SchemaObject} s
+ * @returns {z.ZodType}
+ */
+function maybeDefault(schema, s) {
+    if (s.default !== undefined)
+        return schema.default(s.default);
+    return schema;
+}

package/src/loadSpecEffect.js

@@ -0,0 +1,51 @@
+// ---------------------------------------------------------------------------
+// loadSpecEffect — Effect-based OpenAPI spec loader
+// ---------------------------------------------------------------------------
+import { readFileSync } from "node:fs";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { parseSpecText } from "./_specHelpers.js";
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+
+/**
+ * Load an OpenAPI spec from a JSON/YAML string, URL, file path, or object.
+ *
+ * @param {string | OpenApiSpec} input
+ * @returns {Effect.Effect<OpenApiSpec, unknown>}
+ */
+export function loadSpecEffect(input) {
+    if (typeof input === "object" && input !== null && "openapi" in input) {
+        return Effect.succeed(input);
+    }
+    const str = input;
+    // URL
+    if (str.startsWith("http://") || str.startsWith("https://")) {
+        return Effect.tryPromise({
+            try: async () => {
+                const res = await fetch(str);
+                if (!res.ok) {
+                    throw new Error(`Failed to fetch OpenAPI spec: ${res.status} ${res.statusText}`);
+                }
+                const text = await res.text();
+                return parseSpecText(text);
+            },
+            catch: (cause) => toSmithersError(cause, "openapi fetch spec"),
+        });
+    }
+    // File path or raw JSON/YAML string
+    return Effect.try({
+        try: () => {
+            // Try reading as file first
+            try {
+                const content = readFileSync(str, "utf8");
+                return parseSpecText(content);
+            }
+            catch {
+                // Not a file — try parsing as raw text
+                return parseSpecText(str);
+            }
+        },
+        catch: (cause) => toSmithersError(cause, "openapi load spec"),
+    });
+}

package/src/loadSpecSync.js

@@ -0,0 +1,27 @@
+// ---------------------------------------------------------------------------
+// loadSpecSync — synchronous OpenAPI spec loader
+// ---------------------------------------------------------------------------
+import { readFileSync } from "node:fs";
+import { parseSpecText } from "./_specHelpers.js";
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+
+/**
+ * Synchronous version for simpler call sites.
+ *
+ * @param {string | OpenApiSpec} input
+ * @returns {OpenApiSpec}
+ */
+export function loadSpecSync(input) {
+    if (typeof input === "object" && input !== null && "openapi" in input) {
+        return input;
+    }
+    const str = input;
+    try {
+        const content = readFileSync(str, "utf8");
+        return parseSpecText(content);
+    }
+    catch {
+        return parseSpecText(str);
+    }
+}

package/src/metrics.js

@@ -0,0 +1,19 @@
+// ---------------------------------------------------------------------------
+// OpenAPI tool metrics
+// ---------------------------------------------------------------------------
+import { Metric, MetricBoundaries } from "effect";
+
+/** @type {import("effect").Metric.Metric.Counter<number>} */
+export const openApiToolCallsTotal = Metric.counter("smithers.openapi.tool_calls");
+
+/** @type {import("effect").Metric.Metric.Counter<number>} */
+export const openApiToolCallErrorsTotal = Metric.counter("smithers.openapi.tool_call_errors");
+
+const toolBuckets = MetricBoundaries.exponential({
+    start: 10,
+    factor: 2,
+    count: 14,
+}); // ~10ms to ~80s
+
+/** @type {import("effect").Metric.Metric<import("effect/MetricKeyType").MetricKeyType.Histogram, number, import("effect/MetricState").MetricState.Histogram>} */
+export const openApiToolDuration = Metric.histogram("smithers.openapi.tool_duration_ms", toolBuckets);

package/src/ref-resolver.js

@@ -0,0 +1,58 @@
+// ---------------------------------------------------------------------------
+// $ref resolution within an OpenAPI spec
+// ---------------------------------------------------------------------------
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./RefObject.ts").RefObject} RefObject */
+
+/**
+ * @param {unknown} obj
+ * @returns {obj is RefObject}
+ */
+export function isRef(obj) {
+    return (typeof obj === "object" &&
+        obj !== null &&
+        "$ref" in obj &&
+        typeof obj.$ref === "string");
+}
+/**
+ * Resolve a local JSON pointer ($ref) anywhere within the OpenAPI spec.
+ *
+ * @template [T=unknown]
+ * @param {OpenApiSpec} spec
+ * @param {string} ref
+ * @returns {T}
+ */
+export function resolveRef(spec, ref) {
+    if (!ref.startsWith("#/")) {
+        throw new Error(`Unsupported $ref format: ${ref}`);
+    }
+    const parts = ref.slice(2).split("/");
+    /** @type {unknown} */
+    let current = spec;
+    for (const part of parts) {
+        const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (current === null || typeof current !== "object") {
+            throw new Error(`Could not resolve $ref: ${ref}`);
+        }
+        current = /** @type {Record<string, unknown>} */ (current)[decoded];
+        if (current === undefined) {
+            throw new Error(`Could not resolve $ref: ${ref}`);
+        }
+    }
+    return /** @type {T} */ (current);
+}
+/**
+ * If the value is a $ref, resolve it. Otherwise return as-is.
+ * Handles one level of indirection (resolved value is not recursively resolved).
+ *
+ * @template [T=unknown]
+ * @param {OpenApiSpec} spec
+ * @param {T | RefObject} value
+ * @returns {T}
+ */
+export function deref(spec, value) {
+    if (isRef(value)) {
+        return resolveRef(spec, value.$ref);
+    }
+    return value;
+}

package/src/schema-converter.js

@@ -0,0 +1,2 @@
+export { jsonSchemaToZod } from "./jsonSchemaToZod.js";
+export { buildOperationSchema } from "./buildOperationSchema.js";

package/src/spec-parser.js

@@ -0,0 +1,3 @@
+export { loadSpecEffect } from "./loadSpecEffect.js";
+export { loadSpecSync } from "./loadSpecSync.js";
+export { extractOperations } from "./extractOperations.js";