@spec2tools/core 0.1.0

package/dist/openapi-parser.js

@@ -0,0 +1,368 @@
+import { z } from 'zod';
+import { readFile } from 'fs/promises';
+import { parse as parseYaml } from 'yaml';
+import { UnsupportedSchemaError, SpecLoadError } from './errors.js';
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+/**
+ * Fetch and parse an OpenAPI specification from URL or file path
+ */
+export async function loadOpenAPISpec(specPath) {
+    let content;
+    if (specPath.startsWith('http://') || specPath.startsWith('https://')) {
+        const response = await fetch(specPath);
+        if (!response.ok) {
+            throw new SpecLoadError(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        content = await response.text();
+    }
+    else {
+        try {
+            content = await readFile(specPath, 'utf-8');
+        }
+        catch (error) {
+            throw new SpecLoadError(`Cannot read file: ${specPath}`);
+        }
+    }
+    try {
+        // Try JSON first, then YAML
+        if (specPath.endsWith('.json') || content.trim().startsWith('{')) {
+            return JSON.parse(content);
+        }
+        return parseYaml(content);
+    }
+    catch (error) {
+        throw new SpecLoadError('Invalid JSON or YAML format');
+    }
+}
+/**
+ * Extract the base URL from the OpenAPI spec
+ */
+export function extractBaseUrl(spec) {
+    if (spec.servers && spec.servers.length > 0) {
+        return spec.servers[0].url.replace(/\/$/, ''); // Remove trailing slash
+    }
+    throw new SpecLoadError('No server URL defined in OpenAPI spec');
+}
+/**
+ * Extract authentication configuration from security schemes
+ */
+export function extractAuthConfig(spec) {
+    const securitySchemes = spec.components?.securitySchemes;
+    const globalSecurity = spec.security;
+    if (!securitySchemes || !globalSecurity || globalSecurity.length === 0) {
+        return { type: 'none' };
+    }
+    // Get the first security requirement
+    const securityReq = globalSecurity[0];
+    const schemeName = Object.keys(securityReq)[0];
+    const scheme = securitySchemes[schemeName];
+    if (!scheme) {
+        return { type: 'none' };
+    }
+    return parseSecurityScheme(scheme, securityReq[schemeName]);
+}
+function parseSecurityScheme(scheme, scopes) {
+    if (scheme.type === 'oauth2') {
+        const flow = scheme.flows?.authorizationCode;
+        if (!flow) {
+            throw new UnsupportedSchemaError('securitySchemes', 'Only OAuth2 authorization code flow is supported');
+        }
+        return {
+            type: 'oauth2',
+            authorizationUrl: flow.authorizationUrl,
+            tokenUrl: flow.tokenUrl,
+            scopes: scopes,
+        };
+    }
+    if (scheme.type === 'apiKey') {
+        return {
+            type: 'apiKey',
+            apiKeyHeader: scheme.name,
+            apiKeyIn: scheme.in,
+        };
+    }
+    if (scheme.type === 'http' && scheme.scheme === 'bearer') {
+        return { type: 'bearer' };
+    }
+    return { type: 'none' };
+}
+/**
+ * Convert an OpenAPI schema to a Zod schema
+ */
+function schemaToZod(schema, path, depth = 0) {
+    // Check for unsupported features
+    if (schema.anyOf) {
+        throw new UnsupportedSchemaError(path, 'anyOf is not supported');
+    }
+    if (schema.oneOf) {
+        throw new UnsupportedSchemaError(path, 'oneOf is not supported');
+    }
+    if (schema.allOf) {
+        throw new UnsupportedSchemaError(path, 'allOf is not supported');
+    }
+    if (schema.$ref) {
+        throw new UnsupportedSchemaError(path, '$ref is not supported');
+    }
+    // Handle array types
+    if (schema.type === 'array') {
+        if (!schema.items) {
+            throw new UnsupportedSchemaError(path, 'Array without items schema');
+        }
+        if (schema.items.type === 'object') {
+            throw new UnsupportedSchemaError(path, 'Arrays of objects are not supported');
+        }
+        const itemSchema = schemaToZod(schema.items, `${path}.items`, depth);
+        let arraySchema = z.array(itemSchema);
+        if (schema.description) {
+            arraySchema = arraySchema.describe(schema.description);
+        }
+        return arraySchema;
+    }
+    // Handle object types
+    if (schema.type === 'object' || schema.properties) {
+        if (depth > 1) {
+            throw new UnsupportedSchemaError(path, 'Nested objects beyond 1 level are not supported');
+        }
+        const properties = schema.properties || {};
+        const required = schema.required || [];
+        const shape = {};
+        for (const [propName, propSchema] of Object.entries(properties)) {
+            let zodProp = schemaToZod(propSchema, `${path}.${propName}`, depth + 1);
+            if (!required.includes(propName)) {
+                zodProp = zodProp.optional();
+            }
+            shape[propName] = zodProp;
+        }
+        let objSchema = z.object(shape);
+        if (schema.description) {
+            objSchema = objSchema.describe(schema.description);
+        }
+        return objSchema;
+    }
+    // Handle primitive types
+    switch (schema.type) {
+        case 'string': {
+            let strSchema = z.string();
+            if (schema.enum) {
+                strSchema = z.enum(schema.enum);
+            }
+            if (schema.description) {
+                strSchema = strSchema.describe(schema.description);
+            }
+            return strSchema;
+        }
+        case 'number':
+        case 'integer': {
+            let numSchema = z.number();
+            if (schema.description) {
+                numSchema = numSchema.describe(schema.description);
+            }
+            return numSchema;
+        }
+        case 'boolean': {
+            let boolSchema = z.boolean();
+            if (schema.description) {
+                boolSchema = boolSchema.describe(schema.description);
+            }
+            return boolSchema;
+        }
+        default:
+            // Default to string for unknown types
+            return z.string();
+    }
+}
+/**
+ * Build parameters schema from path and query parameters
+ */
+function buildParametersSchema(parameters, operationId) {
+    const shape = {};
+    for (const param of parameters) {
+        if (param.in !== 'path' && param.in !== 'query') {
+            continue; // Skip header and cookie parameters
+        }
+        let paramSchema;
+        if (param.schema) {
+            paramSchema = schemaToZod(param.schema, `${operationId}.parameters.${param.name}`, 0);
+        }
+        else {
+            paramSchema = z.string();
+        }
+        if (param.description) {
+            paramSchema = paramSchema.describe(param.description);
+        }
+        if (!param.required) {
+            paramSchema = paramSchema.optional();
+        }
+        shape[param.name] = paramSchema;
+    }
+    return shape;
+}
+/**
+ * Build request body schema
+ */
+function buildRequestBodySchema(operation, operationId) {
+    if (!operation.requestBody?.content) {
+        return {};
+    }
+    const jsonContent = operation.requestBody.content['application/json'];
+    if (!jsonContent?.schema) {
+        return {};
+    }
+    const schema = jsonContent.schema;
+    // Check for file uploads
+    if (schema.type === 'string' && schema.format === 'binary') {
+        throw new UnsupportedSchemaError(`${operationId}.requestBody`, 'File uploads are not supported');
+    }
+    // For object schemas, flatten properties into the parameter shape
+    if (schema.type === 'object' || schema.properties) {
+        const properties = schema.properties || {};
+        const required = schema.required || [];
+        const shape = {};
+        for (const [propName, propSchema] of Object.entries(properties)) {
+            // Check for file upload in properties
+            if (propSchema.type === 'string' &&
+                propSchema.format === 'binary') {
+                throw new UnsupportedSchemaError(`${operationId}.requestBody.${propName}`, 'File uploads are not supported');
+            }
+            let zodProp = schemaToZod(propSchema, `${operationId}.requestBody.${propName}`, 1);
+            if (!required.includes(propName)) {
+                zodProp = zodProp.optional();
+            }
+            shape[propName] = zodProp;
+        }
+        return shape;
+    }
+    return {};
+}
+/**
+ * Generate tool name from operation
+ */
+function generateToolName(operation, method, path) {
+    if (operation.operationId) {
+        return operation.operationId;
+    }
+    // Generate name from method and path
+    const cleanPath = path
+        .replace(/[{}]/g, '')
+        .replace(/\//g, '_')
+        .replace(/^_/, '');
+    return `${method.toLowerCase()}_${cleanPath}`;
+}
+/**
+ * Parse all operations from the OpenAPI spec and generate tool definitions
+ */
+export function parseOperations(spec) {
+    const tools = [];
+    for (const [path, pathItem] of Object.entries(spec.paths)) {
+        // Get path-level parameters
+        const pathParameters = pathItem.parameters || [];
+        for (const method of HTTP_METHODS) {
+            const methodKey = method.toLowerCase();
+            const operation = pathItem[methodKey];
+            if (!operation) {
+                continue;
+            }
+            const operationId = generateToolName(operation, method, path);
+            // Combine path-level and operation-level parameters
+            const allParameters = [
+                ...pathParameters,
+                ...(operation.parameters || []),
+            ];
+            // Build combined schema from parameters and request body
+            const parameterShape = buildParametersSchema(allParameters, operationId);
+            const bodyShape = buildRequestBodySchema(operation, operationId);
+            const combinedShape = { ...parameterShape, ...bodyShape };
+            const parameters = z.object(combinedShape);
+            tools.push({
+                name: operationId,
+                description: operation.summary || operation.description || `${method} ${path}`,
+                parameters,
+                httpMethod: method,
+                path,
+            });
+        }
+    }
+    return tools;
+}
+/**
+ * Format tool schema for display
+ */
+export function formatToolSchema(tool) {
+    const shape = tool.parameters.shape;
+    const lines = ['{'];
+    for (const [key, schema] of Object.entries(shape)) {
+        const zodSchema = schema;
+        const isOptional = zodSchema.isOptional();
+        const description = zodSchema.description;
+        let typeStr = getZodTypeString(zodSchema);
+        if (isOptional) {
+            typeStr += '.optional()';
+        }
+        if (description) {
+            typeStr += `.describe("${description}")`;
+        }
+        lines.push(`  ${key}: ${typeStr},`);
+    }
+    lines.push('}');
+    return lines.join('\n');
+}
+function getZodTypeString(schema) {
+    if (schema instanceof z.ZodOptional) {
+        return getZodTypeString(schema.unwrap());
+    }
+    if (schema instanceof z.ZodString) {
+        return 'z.string()';
+    }
+    if (schema instanceof z.ZodNumber) {
+        return 'z.number()';
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return 'z.boolean()';
+    }
+    if (schema instanceof z.ZodEnum) {
+        return `z.enum([${schema.options.map((o) => `"${o}"`).join(', ')}])`;
+    }
+    if (schema instanceof z.ZodArray) {
+        return `z.array(${getZodTypeString(schema.element)})`;
+    }
+    if (schema instanceof z.ZodObject) {
+        return 'z.object({...})';
+    }
+    return 'z.unknown()';
+}
+/**
+ * Format tool signature for display
+ */
+export function formatToolSignature(tool) {
+    const shape = tool.parameters.shape;
+    const params = [];
+    for (const [key, schema] of Object.entries(shape)) {
+        const zodSchema = schema;
+        const isOptional = zodSchema.isOptional();
+        const typeStr = getSimpleTypeString(zodSchema);
+        params.push(`${key}${isOptional ? '?' : ''}: ${typeStr}`);
+    }
+    return `${tool.name}(${params.join(', ')})`;
+}
+function getSimpleTypeString(schema) {
+    if (schema instanceof z.ZodOptional) {
+        return getSimpleTypeString(schema.unwrap());
+    }
+    if (schema instanceof z.ZodString || schema instanceof z.ZodEnum) {
+        return 'string';
+    }
+    if (schema instanceof z.ZodNumber) {
+        return 'number';
+    }
+    if (schema instanceof z.ZodBoolean) {
+        return 'boolean';
+    }
+    if (schema instanceof z.ZodArray) {
+        return `${getSimpleTypeString(schema.element)}[]`;
+    }
+    if (schema instanceof z.ZodObject) {
+        return 'object';
+    }
+    return 'unknown';
+}
+//# sourceMappingURL=openapi-parser.js.map

package/dist/tool-executor.d.ts

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+import { Tool, HttpMethod } from './types.js';
+import { AuthManager } from './auth-manager.js';
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<z.ZodRawShape>;
+    httpMethod: HttpMethod;
+    path: string;
+}
+/**
+ * Create executable tools from tool definitions
+ */
+export declare function createExecutableTools(toolDefs: ToolDefinition[], baseUrl: string, authManager: AuthManager): Tool[];
+/**
+ * Execute a tool directly by name
+ */
+export declare function executeToolByName(tools: Tool[], toolName: string, params: Record<string, unknown>): Promise<unknown>;
+export {};
+//# sourceMappingURL=tool-executor.d.ts.map

package/dist/tool-executor.js

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+import { ToolExecutionError } from './errors.js';
+/**
+ * Create executable tools from tool definitions
+ */
+export function createExecutableTools(toolDefs, baseUrl, authManager) {
+    return toolDefs.map((def) => ({
+        ...def,
+        execute: createExecutor(def, baseUrl, authManager),
+    }));
+}
+/**
+ * Create an executor function for a tool
+ */
+function createExecutor(tool, baseUrl, authManager) {
+    return async (params) => {
+        try {
+            // Validate parameters
+            const validatedParams = tool.parameters.parse(params);
+            // Build URL with path parameters replaced
+            let url = buildUrl(baseUrl, tool.path, validatedParams);
+            // Separate path, query, and body parameters
+            const { queryParams, bodyParams } = separateParams(validatedParams, tool.path);
+            // Add query parameters
+            const urlObj = new URL(url);
+            for (const [key, value] of Object.entries(queryParams)) {
+                if (value !== undefined) {
+                    urlObj.searchParams.set(key, String(value));
+                }
+            }
+            // Add auth query params if needed
+            const authQueryParams = authManager.getAuthQueryParams();
+            for (const [key, value] of Object.entries(authQueryParams)) {
+                urlObj.searchParams.set(key, value);
+            }
+            url = urlObj.toString();
+            // Build request options
+            const headers = {
+                ...authManager.getAuthHeaders(),
+            };
+            const fetchOptions = {
+                method: tool.httpMethod,
+                headers,
+            };
+            // Add body for methods that support it
+            if (['POST', 'PUT', 'PATCH'].includes(tool.httpMethod)) {
+                if (Object.keys(bodyParams).length > 0) {
+                    headers['Content-Type'] = 'application/json';
+                    fetchOptions.body = JSON.stringify(bodyParams);
+                }
+            }
+            fetchOptions.headers = headers;
+            // Execute request
+            const response = await fetch(url, fetchOptions);
+            // Parse response
+            const contentType = response.headers.get('content-type') || '';
+            let responseData;
+            if (contentType.includes('application/json')) {
+                responseData = await response.json();
+            }
+            else {
+                responseData = await response.text();
+            }
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${JSON.stringify(responseData)}`);
+            }
+            return responseData;
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new ToolExecutionError(tool.name, new Error(`Invalid parameters: ${error.message}`));
+            }
+            if (error instanceof ToolExecutionError) {
+                throw error;
+            }
+            throw new ToolExecutionError(tool.name, error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+}
+/**
+ * Build URL with path parameters replaced
+ */
+function buildUrl(baseUrl, path, params) {
+    let finalPath = path;
+    // Replace path parameters
+    const pathParamRegex = /\{(\w+)\}/g;
+    let match;
+    while ((match = pathParamRegex.exec(path)) !== null) {
+        const paramName = match[1];
+        const paramValue = params[paramName];
+        if (paramValue !== undefined) {
+            finalPath = finalPath.replace(`{${paramName}}`, encodeURIComponent(String(paramValue)));
+        }
+    }
+    return `${baseUrl}${finalPath}`;
+}
+/**
+ * Separate parameters into path, query, and body params
+ */
+function separateParams(params, path) {
+    const pathParams = {};
+    const queryParams = {};
+    const bodyParams = {};
+    // Extract path parameter names
+    const pathParamNames = new Set();
+    const pathParamRegex = /\{(\w+)\}/g;
+    let match;
+    while ((match = pathParamRegex.exec(path)) !== null) {
+        pathParamNames.add(match[1]);
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (pathParamNames.has(key)) {
+            pathParams[key] = value;
+        }
+        else if (isPrimitive(value)) {
+            // Primitive values go to query params
+            queryParams[key] = value;
+        }
+        else {
+            // Complex values go to body
+            bodyParams[key] = value;
+        }
+    }
+    // For simplicity, if there are non-path primitive params,
+    // we need to determine if they're query or body based on HTTP method
+    // Since we don't have that info here, we'll treat all non-path primitives
+    // as potential query params for GET/DELETE, and body params for POST/PUT/PATCH
+    // This is handled by the executor which knows the method
+    return { pathParams, queryParams, bodyParams };
+}
+/**
+ * Check if value is a primitive type
+ */
+function isPrimitive(value) {
+    return (typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean');
+}
+/**
+ * Execute a tool directly by name
+ */
+export async function executeToolByName(tools, toolName, params) {
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        throw new Error(`Tool not found: ${toolName}`);
+    }
+    return tool.execute(params);
+}
+//# sourceMappingURL=tool-executor.js.map

package/dist/types.d.ts

@@ -0,0 +1,117 @@
+import { z } from 'zod';
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface Tool {
+    name: string;
+    description: string;
+    parameters: z.ZodObject<z.ZodRawShape>;
+    execute: (params: unknown) => Promise<unknown>;
+    httpMethod: HttpMethod;
+    path: string;
+}
+export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'none';
+export interface AuthConfig {
+    type: AuthType;
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    scopes?: string[];
+    apiKeyHeader?: string;
+    apiKeyIn?: 'header' | 'query';
+}
+export interface Session {
+    baseUrl: string;
+    tools: Tool[];
+    authConfig: AuthConfig;
+    accessToken?: string;
+    refreshToken?: string;
+}
+export interface 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>;
+        securitySchemes?: Record<string, SecurityScheme>;
+    };
+    security?: Array<Record<string, string[]>>;
+}
+export interface PathItem {
+    get?: Operation;
+    post?: Operation;
+    put?: Operation;
+    patch?: Operation;
+    delete?: Operation;
+    parameters?: Parameter[];
+}
+export interface Operation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: Parameter[];
+    requestBody?: RequestBody;
+    responses?: Record<string, Response>;
+    security?: Array<Record<string, string[]>>;
+}
+export interface Parameter {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: SchemaObject;
+}
+export interface RequestBody {
+    required?: boolean;
+    content?: Record<string, MediaType>;
+    description?: string;
+}
+export interface MediaType {
+    schema?: SchemaObject;
+}
+export interface Response {
+    description: string;
+    content?: Record<string, MediaType>;
+}
+export interface SchemaObject {
+    type?: string;
+    format?: string;
+    description?: string;
+    required?: string[];
+    properties?: Record<string, SchemaObject>;
+    items?: SchemaObject;
+    enum?: unknown[];
+    default?: unknown;
+    anyOf?: SchemaObject[];
+    oneOf?: SchemaObject[];
+    allOf?: SchemaObject[];
+    $ref?: string;
+}
+export interface SecurityScheme {
+    type: 'oauth2' | 'apiKey' | 'http';
+    scheme?: string;
+    bearerFormat?: string;
+    name?: string;
+    in?: 'header' | 'query' | 'cookie';
+    flows?: {
+        authorizationCode?: {
+            authorizationUrl: string;
+            tokenUrl: string;
+            scopes?: Record<string, string>;
+        };
+        clientCredentials?: {
+            tokenUrl: string;
+            scopes?: Record<string, string>;
+        };
+        implicit?: {
+            authorizationUrl: string;
+            scopes?: Record<string, string>;
+        };
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

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