@smithers-orchestrator/openapi 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 William Cory
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@smithers-orchestrator/openapi",
+  "version": "0.16.0",
+  "description": "OpenAPI parsing and AI SDK tool generation for Smithers",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./*": {
+      "types": "./src/index.d.ts",
+      "import": "./src/*.js",
+      "default": "./src/*.js"
+    }
+  },
+  "files": [
+    "src/"
+  ],
+  "dependencies": {
+    "ai": "^6.0.69",
+    "zod": "^4.3.6",
+    "@smithers-orchestrator/driver": "0.16.0",
+    "@smithers-orchestrator/observability": "0.16.0",
+    "@smithers-orchestrator/scheduler": "0.16.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "~5.9.3"
+  },
+  "scripts": {
+    "build": "tsup --dts-only",
+    "test": "bun test tests",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/src/HttpMethod.ts

@@ -0,0 +1 @@
+export type HttpMethod = "get" | "post" | "put" | "delete" | "patch";

package/src/MediaTypeObject.ts

@@ -0,0 +1,6 @@
+import type { RefObject } from "./RefObject.ts";
+import type { SchemaObject } from "./SchemaObject.ts";
+
+export type MediaTypeObject = {
+	schema?: SchemaObject | RefObject;
+};

package/src/OpenApiAuth.ts

@@ -0,0 +1,16 @@
+export type OpenApiAuth =
+	| {
+			type: "bearer";
+			token: string;
+	  }
+	| {
+			type: "basic";
+			username: string;
+			password: string;
+	  }
+	| {
+			type: "apiKey";
+			name: string;
+			value: string;
+			in: "header" | "query";
+	  };

package/src/OpenApiSpec.ts

@@ -0,0 +1,23 @@
+import type { ParameterObject } from "./ParameterObject.ts";
+import type { PathItem } from "./PathItem.ts";
+import type { RequestBodyObject } from "./RequestBodyObject.ts";
+import type { SchemaObject } from "./SchemaObject.ts";
+
+export type OpenApiSpec = {
+	openapi: string;
+	info: {
+		title: string;
+		version: string;
+		description?: string;
+	};
+	servers?: Array<{
+		url: string;
+		description?: string;
+	}>;
+	paths: Record<string, PathItem>;
+	components?: {
+		schemas?: Record<string, SchemaObject>;
+		parameters?: Record<string, ParameterObject>;
+		requestBodies?: Record<string, RequestBodyObject>;
+	};
+};

package/src/OpenApiTool.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "ai";
+
+/**
+ * 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.
+ */
+export type OpenApiTool = Tool;

package/src/OpenApiToolsOptions.ts

@@ -0,0 +1,10 @@
+import type { OpenApiAuth } from "./OpenApiAuth.ts";
+
+export type OpenApiToolsOptions = {
+	baseUrl?: string;
+	headers?: Record<string, string>;
+	auth?: OpenApiAuth;
+	include?: string[];
+	exclude?: string[];
+	namePrefix?: string;
+};

package/src/OperationObject.ts

@@ -0,0 +1,14 @@
+import type { ParameterObject } from "./ParameterObject.ts";
+import type { RefObject } from "./RefObject.ts";
+import type { RequestBodyObject } from "./RequestBodyObject.ts";
+
+export type OperationObject = {
+	operationId?: string;
+	summary?: string;
+	description?: string;
+	parameters?: Array<ParameterObject | RefObject>;
+	requestBody?: RequestBodyObject | RefObject;
+	responses?: Record<string, unknown>;
+	tags?: string[];
+	deprecated?: boolean;
+};

package/src/ParameterObject.ts

@@ -0,0 +1,11 @@
+import type { RefObject } from "./RefObject.ts";
+import type { SchemaObject } from "./SchemaObject.ts";
+
+export type ParameterObject = {
+	name: string;
+	in: "query" | "header" | "path" | "cookie";
+	description?: string;
+	required?: boolean;
+	schema?: SchemaObject | RefObject;
+	deprecated?: boolean;
+};

package/src/ParsedOperation.ts

@@ -0,0 +1,14 @@
+import type { HttpMethod } from "./HttpMethod.ts";
+import type { ParameterObject } from "./ParameterObject.ts";
+import type { RequestBodyObject } from "./RequestBodyObject.ts";
+
+export type ParsedOperation = {
+	operationId: string;
+	method: HttpMethod;
+	path: string;
+	summary: string;
+	description: string;
+	parameters: ParameterObject[];
+	requestBody?: RequestBodyObject;
+	deprecated: boolean;
+};

package/src/PathItem.ts

@@ -0,0 +1,12 @@
+import type { OperationObject } from "./OperationObject.ts";
+import type { ParameterObject } from "./ParameterObject.ts";
+import type { RefObject } from "./RefObject.ts";
+
+export type PathItem = {
+	get?: OperationObject;
+	post?: OperationObject;
+	put?: OperationObject;
+	delete?: OperationObject;
+	patch?: OperationObject;
+	parameters?: Array<ParameterObject | RefObject>;
+};

package/src/RefObject.ts

@@ -0,0 +1,3 @@
+export type RefObject = {
+	$ref: string;
+};

package/src/RequestBodyObject.ts

@@ -0,0 +1,7 @@
+import type { MediaTypeObject } from "./MediaTypeObject.ts";
+
+export type RequestBodyObject = {
+	description?: string;
+	required?: boolean;
+	content: Record<string, MediaTypeObject>;
+};

package/src/SchemaObject.ts

@@ -0,0 +1,23 @@
+import type { RefObject } from "./RefObject.ts";
+
+export type SchemaObject = {
+	type?: string;
+	format?: string;
+	description?: string;
+	properties?: Record<string, SchemaObject | RefObject>;
+	required?: string[];
+	items?: SchemaObject | RefObject;
+	enum?: unknown[];
+	default?: unknown;
+	nullable?: boolean;
+	oneOf?: Array<SchemaObject | RefObject>;
+	anyOf?: Array<SchemaObject | RefObject>;
+	allOf?: Array<SchemaObject | RefObject>;
+	additionalProperties?: boolean | SchemaObject | RefObject;
+	minimum?: number;
+	maximum?: number;
+	minLength?: number;
+	maxLength?: number;
+	pattern?: string;
+	$ref?: string;
+};

package/src/_specHelpers.js

@@ -0,0 +1,65 @@
+// ---------------------------------------------------------------------------
+// Shared private helpers for spec parsing
+// ---------------------------------------------------------------------------
+/** @typedef {import("./HttpMethod.ts").HttpMethod} HttpMethod */
+/** @typedef {import("./ParameterObject.ts").ParameterObject} ParameterObject */
+
+/**
+ * @param {string} text
+ * @returns {Record<string, unknown>}
+ */
+export function parseSpecText(text) {
+    /** @type {unknown} */
+    let parsed;
+    // Try JSON first
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        // Try YAML
+        try {
+            const yaml = require("yaml");
+            parsed = yaml.parse(text);
+        }
+        catch {
+            throw new Error("Failed to parse OpenAPI spec as JSON or YAML");
+        }
+    }
+    // Validate it looks like an OpenAPI spec
+    if (typeof parsed !== "object" ||
+        parsed === null ||
+        !("openapi" in parsed || "swagger" in parsed) ||
+        !("paths" in parsed || "info" in parsed)) {
+        throw new Error("Parsed content does not appear to be a valid OpenAPI spec (missing openapi/paths/info fields)");
+    }
+    return /** @type {Record<string, unknown>} */ (parsed);
+}
+/**
+ * Merge path-level and operation-level parameters. Operation-level wins
+ * when there is a name+in collision.
+ *
+ * @param {ParameterObject[]} pathLevel
+ * @param {ParameterObject[]} opLevel
+ * @returns {ParameterObject[]}
+ */
+export function mergeParameters(pathLevel, opLevel) {
+    const opKeys = new Set(opLevel.map((p) => `${p.in}:${p.name}`));
+    const fromPath = pathLevel.filter((p) => !opKeys.has(`${p.in}:${p.name}`));
+    return [...fromPath, ...opLevel];
+}
+/**
+ * Generate an operationId from method + path when one is not provided.
+ * e.g. GET /pets/{petId} → get_pets_petId
+ *
+ * @param {HttpMethod} method
+ * @param {string} path
+ * @returns {string}
+ */
+export function generateOperationId(method, path) {
+    const cleaned = path
+        .replace(/\{([^}]+)\}/g, "$1")
+        .replace(/[^a-zA-Z0-9]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_|_$/g, "");
+    return `${method}_${cleaned}`;
+}

package/src/buildOperationSchema.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// Build a combined Zod schema from operation parameters + requestBody
+// ---------------------------------------------------------------------------
+import { z } from "zod";
+import { isRef } from "./ref-resolver.js";
+import { jsonSchemaToZod } from "./jsonSchemaToZod.js";
+
+/** @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}
+ */
+export function buildOperationSchema(parameters, requestBody, spec) {
+    const props = {};
+    const requiredKeys = [];
+    // Parameters (path, query, header)
+    for (const param of parameters) {
+        if (param.in === "cookie")
+            continue; // skip cookies
+        let paramSchema = jsonSchemaToZod(param.schema, spec);
+        if (param.description && !(param.schema && !isRef(param.schema) && param.schema.description)) {
+            paramSchema = paramSchema.describe(param.description);
+        }
+        if (!param.required) {
+            paramSchema = paramSchema.optional();
+        }
+        else {
+            requiredKeys.push(param.name);
+        }
+        props[param.name] = paramSchema;
+    }
+    // Request body
+    if (requestBody) {
+        const jsonContent = requestBody.content?.["application/json"];
+        if (jsonContent?.schema) {
+            const bodySchema = jsonSchemaToZod(jsonContent.schema, spec);
+            // If the body schema is an object, merge its properties
+            // into the top-level props under a "body" key
+            if (requestBody.required) {
+                props.body = bodySchema;
+                requiredKeys.push("body");
+            }
+            else {
+                props.body = bodySchema.optional();
+            }
+        }
+    }
+    if (Object.keys(props).length === 0) {
+        return z.object({});
+    }
+    return z.object(props);
+}

package/src/extractOperations.js

@@ -0,0 +1,50 @@
+// ---------------------------------------------------------------------------
+// extractOperations — extract all operations from an OpenAPI spec
+// ---------------------------------------------------------------------------
+import { deref } from "./ref-resolver.js";
+import { HTTP_METHODS, } from "./types.js";
+import { mergeParameters, generateOperationId } from "./_specHelpers.js";
+
+/** @typedef {import("./OpenApiSpec.ts").OpenApiSpec} OpenApiSpec */
+/** @typedef {import("./ParsedOperation.ts").ParsedOperation} ParsedOperation */
+
+/**
+ * Extract all operations from an OpenAPI spec.
+ *
+ * @param {OpenApiSpec} spec
+ * @returns {ParsedOperation[]}
+ */
+export function extractOperations(spec) {
+    const operations = [];
+    const paths = spec.paths ?? {};
+    for (const [path, pathItem] of Object.entries(paths)) {
+        if (!pathItem)
+            continue;
+        // Path-level parameters (shared across all methods)
+        const pathParams = (pathItem.parameters ?? []).map((p) => deref(spec, p));
+        for (const method of HTTP_METHODS) {
+            const operation = pathItem[method];
+            if (!operation)
+                continue;
+            // Merge path-level and operation-level parameters.
+            // Operation-level takes precedence (matched by name+in).
+            const opParams = (operation.parameters ?? []).map((p) => deref(spec, p));
+            const mergedParams = mergeParameters(pathParams, opParams);
+            const requestBody = operation.requestBody
+                ? deref(spec, operation.requestBody)
+                : undefined;
+            const operationId = operation.operationId ?? generateOperationId(method, path);
+            operations.push({
+                operationId,
+                method,
+                path,
+                summary: operation.summary ?? "",
+                description: operation.description ?? operation.summary ?? "",
+                parameters: mergedParams,
+                requestBody,
+                deprecated: operation.deprecated ?? false,
+            });
+        }
+    }
+    return operations;
+}