@spec2tools/core 0.1.1 → 0.1.2

package/dist/openapi-parser.js

@@ -109,10 +109,39 @@ function parseSecurityScheme(scheme, scopes) {
     }
     return { type: 'none' };
 }
+/**
+ * Resolve a $ref to its actual schema object
+ */
+function resolveRef(ref, spec, visited = new Set()) {
+    // Detect circular references
+    if (visited.has(ref)) {
+        throw new UnsupportedSchemaError(ref, 'Circular $ref detected');
+    }
+    visited.add(ref);
+    // Only support #/components/schemas/ references
+    if (!ref.startsWith('#/components/schemas/')) {
+        throw new UnsupportedSchemaError(ref, 'Only #/components/schemas/ $refs are supported');
+    }
+    const schemaName = ref.replace('#/components/schemas/', '');
+    const schema = spec.components?.schemas?.[schemaName];
+    if (!schema) {
+        throw new UnsupportedSchemaError(ref, `Schema "${schemaName}" not found in components`);
+    }
+    // If the resolved schema has a $ref, resolve it recursively
+    if (schema.$ref) {
+        return resolveRef(schema.$ref, spec, visited);
+    }
+    return schema;
+}
 /**
  * Convert an OpenAPI schema to a Zod schema
  */
-function schemaToZod(schema, path, depth = 0) {
+function schemaToZod(schema, path, spec, depth = 0, visited = new Set()) {
+    // Resolve $ref if present
+    if (schema.$ref) {
+        const resolvedSchema = resolveRef(schema.$ref, spec, new Set(visited));
+        return schemaToZod(resolvedSchema, path, spec, depth, visited);
+    }
     // Check for unsupported features
     if (schema.anyOf) {
         throw new UnsupportedSchemaError(path, 'anyOf is not supported');
@@ -123,9 +152,6 @@ function schemaToZod(schema, path, depth = 0) {
     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) {
@@ -134,7 +160,7 @@ function schemaToZod(schema, path, depth = 0) {
         if (schema.items.type === 'object') {
             throw new UnsupportedSchemaError(path, 'Arrays of objects are not supported');
         }
-        const itemSchema = schemaToZod(schema.items, `${path}.items`, depth);
+        const itemSchema = schemaToZod(schema.items, `${path}.items`, spec, depth, visited);
         let arraySchema = z.array(itemSchema);
         if (schema.description) {
             arraySchema = arraySchema.describe(schema.description);
@@ -150,7 +176,7 @@ function schemaToZod(schema, path, depth = 0) {
         const required = schema.required || [];
         const shape = {};
         for (const [propName, propSchema] of Object.entries(properties)) {
-            let zodProp = schemaToZod(propSchema, `${path}.${propName}`, depth + 1);
+            let zodProp = schemaToZod(propSchema, `${path}.${propName}`, spec, depth + 1, visited);
             if (!required.includes(propName)) {
                 zodProp = zodProp.optional();
             }
@@ -197,15 +223,17 @@ function schemaToZod(schema, path, depth = 0) {
 /**
  * Build parameters schema from path and query parameters
  */
-function buildParametersSchema(parameters, operationId) {
+function buildParametersSchema(parameters, operationId, spec) {
     const shape = {};
+    const pathParams = new Set();
+    const queryParams = new Set();
     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);
+            paramSchema = schemaToZod(param.schema, `${operationId}.parameters.${param.name}`, spec, 0);
         }
         else {
             paramSchema = z.string();
@@ -217,45 +245,58 @@ function buildParametersSchema(parameters, operationId) {
             paramSchema = paramSchema.optional();
         }
         shape[param.name] = paramSchema;
+        // Track which set this parameter belongs to
+        if (param.in === 'path') {
+            pathParams.add(param.name);
+        }
+        else if (param.in === 'query') {
+            queryParams.add(param.name);
+        }
     }
-    return shape;
+    return { shape, pathParams, queryParams };
 }
 /**
  * Build request body schema
  */
-function buildRequestBodySchema(operation, operationId) {
+function buildRequestBodySchema(operation, operationId, spec) {
+    const shape = {};
+    const bodyParams = new Set();
     if (!operation.requestBody?.content) {
-        return {};
+        return { shape, bodyParams };
     }
     const jsonContent = operation.requestBody.content['application/json'];
     if (!jsonContent?.schema) {
-        return {};
+        return { shape, bodyParams };
     }
     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');
     }
+    // Resolve $ref if present
+    let resolvedSchema = schema;
+    if (schema.$ref) {
+        resolvedSchema = resolveRef(schema.$ref, spec);
+    }
     // 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 = {};
+    if (resolvedSchema.type === 'object' || resolvedSchema.properties) {
+        const properties = resolvedSchema.properties || {};
+        const required = resolvedSchema.required || [];
         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);
+            let zodProp = schemaToZod(propSchema, `${operationId}.requestBody.${propName}`, spec, 1);
             if (!required.includes(propName)) {
                 zodProp = zodProp.optional();
             }
             shape[propName] = zodProp;
+            bodyParams.add(propName); // Track that this is a body parameter
         }
-        return shape;
     }
-    return {};
+    return { shape, bodyParams };
 }
 /**
  * Generate tool name from operation
@@ -292,9 +333,9 @@ export function parseOperations(spec) {
                 ...(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 parametersResult = buildParametersSchema(allParameters, operationId, spec);
+            const bodyResult = buildRequestBodySchema(operation, operationId, spec);
+            const combinedShape = { ...parametersResult.shape, ...bodyResult.shape };
             const parameters = z.object(combinedShape);
             // Extract operation-specific auth config
             const authConfig = extractOperationAuthConfig(spec, operation);
@@ -305,6 +346,11 @@ export function parseOperations(spec) {
                 httpMethod: method,
                 path,
                 authConfig,
+                parameterMetadata: {
+                    pathParams: parametersResult.pathParams,
+                    queryParams: parametersResult.queryParams,
+                    bodyParams: bodyResult.bodyParams,
+                },
             });
         }
     }

package/dist/tool-executor.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Tool, HttpMethod, AuthConfig } from './types.js';
+import { Tool, HttpMethod, AuthConfig, ParameterMetadata } from './types.js';
 import { AuthManager } from './auth-manager.js';
 interface ToolDefinition {
     name: string;
@@ -8,6 +8,7 @@ interface ToolDefinition {
     httpMethod: HttpMethod;
     path: string;
     authConfig?: AuthConfig;
+    parameterMetadata?: ParameterMetadata;
 }
 /**
  * Create executable tools from tool definitions

package/dist/tool-executor.js

@@ -19,8 +19,8 @@ function createExecutor(tool, baseUrl, authManager) {
             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);
+            // Separate path, query, and body parameters using metadata
+            const { queryParams, bodyParams } = separateParams(validatedParams, tool.parameterMetadata);
             // Add query parameters
             const urlObj = new URL(url);
             for (const [key, value] of Object.entries(queryParams)) {
@@ -122,39 +122,55 @@ function buildUrl(baseUrl, path, params) {
     return `${baseUrl}${finalPath}`;
 }
 /**
- * Separate parameters into path, query, and body params
+ * Separate parameters into path, query, and body params using metadata
  */
-function separateParams(params, path) {
+function separateParams(params, metadata) {
     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;
+    // If we have metadata, use it to categorize parameters
+    if (metadata) {
+        for (const [key, value] of Object.entries(params)) {
+            if (metadata.pathParams.has(key)) {
+                pathParams[key] = value;
+            }
+            else if (metadata.queryParams.has(key)) {
+                queryParams[key] = value;
+            }
+            else if (metadata.bodyParams.has(key)) {
+                bodyParams[key] = value;
+            }
+            else {
+                // Fallback: if not in metadata, treat as body param
+                bodyParams[key] = value;
+            }
         }
-        else {
-            // Complex values go to body
-            bodyParams[key] = value;
+    }
+    else {
+        // Fallback to old behavior if no metadata (shouldn't happen with new parser)
+        // This keeps backward compatibility
+        const pathParamNames = extractPathParamNames(params);
+        for (const [key, value] of Object.entries(params)) {
+            if (pathParamNames.has(key)) {
+                pathParams[key] = value;
+            }
+            else if (isPrimitive(value)) {
+                queryParams[key] = value;
+            }
+            else {
+                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 };
 }
+/**
+ * Extract path parameter names from params (fallback)
+ */
+function extractPathParamNames(params) {
+    // This is a fallback - in practice, metadata should always be provided
+    return new Set();
+}
 /**
  * Check if value is a primitive type
  */

package/dist/types.d.ts

@@ -1,5 +1,13 @@
 import { z } from 'zod';
 export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+export interface ParameterMetadata {
+    /** Parameters that come from path (e.g., {id} in /users/{id}) */
+    pathParams: Set<string>;
+    /** Parameters that come from query string */
+    queryParams: Set<string>;
+    /** Parameters that come from request body */
+    bodyParams: Set<string>;
+}
 export interface Tool {
     name: string;
     description: string;
@@ -8,6 +16,7 @@ export interface Tool {
     httpMethod: HttpMethod;
     path: string;
     authConfig?: AuthConfig;
+    parameterMetadata?: ParameterMetadata;
 }
 export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'basic' | 'none';
 export interface AuthConfig {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/core",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Core utilities for OpenAPI parsing and authentication",
   "type": "module",
   "main": "dist/index.js",