@spec2tools/core 0.1.0 → 0.1.2

package/dist/auth-manager.d.ts

@@ -1,32 +1,35 @@
 import { AuthConfig } from './types.js';
 export declare class AuthManager {
-    private authConfig;
+    private globalAuthConfig;
     private accessToken?;
     private refreshToken?;
     private clientId?;
     private clientSecret?;
     private codeVerifier?;
-    constructor(authConfig: AuthConfig);
+    constructor(globalAuthConfig: AuthConfig);
     /**
      * Check if authentication is required
      */
-    requiresAuth(): boolean;
+    requiresAuth(authConfig?: AuthConfig): boolean;
     /**
      * Get the current access token
      */
     getAccessToken(): string | undefined;
     /**
      * Get authorization headers for requests
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthHeaders(): Record<string, string>;
+    getAuthHeaders(authConfig?: AuthConfig): Record<string, string>;
     /**
      * Get query parameters for API key auth
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthQueryParams(): Record<string, string>;
+    getAuthQueryParams(authConfig?: AuthConfig): Record<string, string>;
     /**
      * Perform authentication based on config type
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    authenticate(): Promise<void>;
+    authenticate(authConfig?: AuthConfig): Promise<void>;
     /**
      * Prompt user for API key
      */
@@ -35,6 +38,10 @@ export declare class AuthManager {
      * Prompt user for bearer token
      */
     private promptForBearerToken;
+    /**
+     * Prompt user for basic auth credentials
+     */
+    private promptForBasicAuth;
     /**
      * Perform OAuth2 authorization code flow
      */

package/dist/auth-manager.js

@@ -7,20 +7,21 @@ import * as readline from 'readline';
 const CALLBACK_PORT = 54321;
 const CALLBACK_PATH = '/callback';
 export class AuthManager {
-    authConfig;
+    globalAuthConfig;
     accessToken;
     refreshToken;
     clientId;
     clientSecret;
     codeVerifier;
-    constructor(authConfig) {
-        this.authConfig = authConfig;
+    constructor(globalAuthConfig) {
+        this.globalAuthConfig = globalAuthConfig;
     }
     /**
      * Check if authentication is required
      */
-    requiresAuth() {
-        return this.authConfig.type !== 'none';
+    requiresAuth(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        return config.type !== 'none';
     }
     /**
      * Get the current access token
@@ -30,18 +31,22 @@ export class AuthManager {
     }
     /**
      * Get authorization headers for requests
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthHeaders() {
+    getAuthHeaders(authConfig) {
         if (!this.accessToken) {
             return {};
         }
-        switch (this.authConfig.type) {
+        const config = authConfig ?? this.globalAuthConfig;
+        switch (config.type) {
             case 'oauth2':
             case 'bearer':
                 return { Authorization: `Bearer ${this.accessToken}` };
+            case 'basic':
+                return { Authorization: `Basic ${this.accessToken}` };
             case 'apiKey':
-                if (this.authConfig.apiKeyIn === 'header' && this.authConfig.apiKeyHeader) {
-                    return { [this.authConfig.apiKeyHeader]: this.accessToken };
+                if (config.apiKeyIn === 'header' && config.apiKeyHeader) {
+                    return { [config.apiKeyHeader]: this.accessToken };
                 }
                 return {};
             default:
@@ -50,30 +55,37 @@ export class AuthManager {
     }
     /**
      * Get query parameters for API key auth
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    getAuthQueryParams() {
-        if (this.authConfig.type === 'apiKey' &&
-            this.authConfig.apiKeyIn === 'query' &&
-            this.authConfig.apiKeyHeader &&
+    getAuthQueryParams(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        if (config.type === 'apiKey' &&
+            config.apiKeyIn === 'query' &&
+            config.apiKeyHeader &&
             this.accessToken) {
-            return { [this.authConfig.apiKeyHeader]: this.accessToken };
+            return { [config.apiKeyHeader]: this.accessToken };
         }
         return {};
     }
     /**
      * Perform authentication based on config type
+     * @param authConfig Optional tool-specific auth config that overrides the global config
      */
-    async authenticate() {
-        switch (this.authConfig.type) {
+    async authenticate(authConfig) {
+        const config = authConfig ?? this.globalAuthConfig;
+        switch (config.type) {
             case 'oauth2':
-                await this.performOAuth2Flow();
+                await this.performOAuth2Flow(config);
                 break;
             case 'apiKey':
-                await this.promptForApiKey();
+                await this.promptForApiKey(config);
                 break;
             case 'bearer':
                 await this.promptForBearerToken();
                 break;
+            case 'basic':
+                await this.promptForBasicAuth();
+                break;
             case 'none':
                 // No authentication needed
                 break;
@@ -82,12 +94,12 @@ export class AuthManager {
     /**
      * Prompt user for API key
      */
-    async promptForApiKey() {
+    async promptForApiKey(config) {
         const rl = readline.createInterface({
             input: process.stdin,
             output: process.stdout,
         });
-        const headerName = this.authConfig.apiKeyHeader || 'API-Key';
+        const headerName = config.apiKeyHeader || 'API-Key';
         this.accessToken = await new Promise((resolve) => {
             rl.question(`Enter your API key (${headerName}): `, (answer) => {
                 rl.close();
@@ -116,26 +128,50 @@ export class AuthManager {
             throw new AuthenticationError('Bearer token is required');
         }
     }
+    /**
+     * Prompt user for basic auth credentials
+     */
+    async promptForBasicAuth() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const question = (prompt) => {
+            return new Promise((resolve) => {
+                rl.question(prompt, (answer) => {
+                    resolve(answer.trim());
+                });
+            });
+        };
+        const username = await question('Enter username: ');
+        const password = await question('Enter password: ');
+        rl.close();
+        if (!username || !password) {
+            throw new AuthenticationError('Username and password are required for Basic auth');
+        }
+        // Base64 encode the credentials
+        this.accessToken = Buffer.from(`${username}:${password}`).toString('base64');
+    }
     /**
      * Perform OAuth2 authorization code flow
      */
-    async performOAuth2Flow() {
-        if (!this.authConfig.authorizationUrl || !this.authConfig.tokenUrl) {
+    async performOAuth2Flow(config) {
+        if (!config.authorizationUrl || !config.tokenUrl) {
             throw new AuthenticationError('OAuth2 requires authorizationUrl and tokenUrl');
         }
         // Register client dynamically
-        await this.registerClient();
+        await this.registerClient(config);
         // Start local callback server
-        const authCode = await this.startCallbackServerAndAuthorize();
+        const authCode = await this.startCallbackServerAndAuthorize(config);
         // Exchange code for token
-        await this.exchangeCodeForToken(authCode);
+        await this.exchangeCodeForToken(authCode, config);
     }
     /**
      * Register OAuth2 client dynamically
      */
-    async registerClient() {
+    async registerClient(config) {
         // Derive registration URL from token URL (replace /token with /register)
-        const registrationUrl = this.authConfig.tokenUrl.replace(/\/token$/, '/register');
+        const registrationUrl = config.tokenUrl.replace(/\/token$/, '/register');
         const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
         console.log('Registering OAuth2 client...');
         const response = await fetch(registrationUrl, {
@@ -162,7 +198,7 @@ export class AuthManager {
     /**
      * Start local callback server and initiate authorization
      */
-    async startCallbackServerAndAuthorize() {
+    async startCallbackServerAndAuthorize(config) {
         return new Promise((resolve, reject) => {
             const app = express();
             let server;
@@ -211,7 +247,7 @@ export class AuthManager {
             server = createServer(app);
             server.listen(CALLBACK_PORT, '127.0.0.1', () => {
                 const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
-                const authUrl = this.buildAuthorizationUrl(redirectUri);
+                const authUrl = this.buildAuthorizationUrl(redirectUri, config);
                 console.log('\nAuthentication required. Opening browser...');
                 console.log(`If browser doesn't open, visit: ${authUrl}\n`);
                 open(authUrl).catch(() => {
@@ -249,8 +285,8 @@ export class AuthManager {
     /**
      * Build the OAuth2 authorization URL
      */
-    buildAuthorizationUrl(redirectUri) {
-        const url = new URL(this.authConfig.authorizationUrl);
+    buildAuthorizationUrl(redirectUri, config) {
+        const url = new URL(config.authorizationUrl);
         // Generate PKCE
         const pkce = this.generatePKCE();
         this.codeVerifier = pkce.verifier;
@@ -259,8 +295,8 @@ export class AuthManager {
         url.searchParams.set('redirect_uri', redirectUri);
         url.searchParams.set('code_challenge', pkce.challenge);
         url.searchParams.set('code_challenge_method', 'S256');
-        if (this.authConfig.scopes && this.authConfig.scopes.length > 0) {
-            url.searchParams.set('scope', this.authConfig.scopes.join(' '));
+        if (config.scopes && config.scopes.length > 0) {
+            url.searchParams.set('scope', config.scopes.join(' '));
         }
         // Generate state for CSRF protection
         const state = crypto.randomBytes(16).toString('base64url');
@@ -270,7 +306,7 @@ export class AuthManager {
     /**
      * Exchange authorization code for access token
      */
-    async exchangeCodeForToken(code) {
+    async exchangeCodeForToken(code, config) {
         const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
         const params = new URLSearchParams({
             grant_type: 'authorization_code',
@@ -283,7 +319,7 @@ export class AuthManager {
         if (this.clientSecret) {
             params.set('client_secret', this.clientSecret);
         }
-        const response = await fetch(this.authConfig.tokenUrl, {
+        const response = await fetch(config.tokenUrl, {
             method: 'POST',
             headers: {
                 'Content-Type': 'application/x-www-form-urlencoded',

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
 export type { HttpMethod, Tool, AuthType, AuthConfig, Session, OpenAPISpec, PathItem, Operation, Parameter, RequestBody, MediaType, Response, SchemaObject, SecurityScheme, } from './types.js';
-export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
 export { AuthManager } from './auth-manager.js';
 export { createExecutableTools, executeToolByName } from './tool-executor.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,7 +1,7 @@
 // Error classes
 export { UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from './errors.js';
 // OpenAPI Parser
-export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
+export { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, extractOperationAuthConfig, parseOperations, formatToolSchema, formatToolSignature, } from './openapi-parser.js';
 // Auth Manager
 export { AuthManager } from './auth-manager.js';
 // Tool Executor

package/dist/openapi-parser.d.ts

@@ -1,4 +1,4 @@
-import { OpenAPISpec, Tool, AuthConfig } from './types.js';
+import { OpenAPISpec, Operation, Tool, AuthConfig } from './types.js';
 /**
  * Fetch and parse an OpenAPI specification from URL or file path
  */
@@ -11,6 +11,11 @@ export declare function extractBaseUrl(spec: OpenAPISpec): string;
  * Extract authentication configuration from security schemes
  */
 export declare function extractAuthConfig(spec: OpenAPISpec): AuthConfig;
+/**
+ * Extract authentication configuration for a specific operation
+ * Uses operation-level security if defined, otherwise falls back to global security
+ */
+export declare function extractOperationAuthConfig(spec: OpenAPISpec, operation: Operation): AuthConfig;
 /**
  * Parse all operations from the OpenAPI spec and generate tool definitions
  */

package/dist/openapi-parser.js

@@ -47,13 +47,33 @@ export function extractBaseUrl(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 extractAuthConfigFromSecurity(spec.security, spec.components?.securitySchemes);
+}
+/**
+ * Extract authentication configuration for a specific operation
+ * Uses operation-level security if defined, otherwise falls back to global security
+ */
+export function extractOperationAuthConfig(spec, operation) {
+    // If operation has its own security field, use it (even if empty array = no auth)
+    if (operation.security !== undefined) {
+        return extractAuthConfigFromSecurity(operation.security, spec.components?.securitySchemes);
+    }
+    // Fall back to global security
+    return extractAuthConfig(spec);
+}
+/**
+ * Extract auth config from a security requirement array
+ */
+function extractAuthConfigFromSecurity(security, securitySchemes) {
+    // Empty security array means explicitly no auth required
+    if (security !== undefined && security.length === 0) {
+        return { type: 'none' };
+    }
+    if (!securitySchemes || !security || security.length === 0) {
         return { type: 'none' };
     }
     // Get the first security requirement
-    const securityReq = globalSecurity[0];
+    const securityReq = security[0];
     const schemeName = Object.keys(securityReq)[0];
     const scheme = securitySchemes[schemeName];
     if (!scheme) {
@@ -84,12 +104,44 @@ function parseSecurityScheme(scheme, scopes) {
     if (scheme.type === 'http' && scheme.scheme === 'bearer') {
         return { type: 'bearer' };
     }
+    if (scheme.type === 'http' && scheme.scheme === 'basic') {
+        return { type: 'basic' };
+    }
     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');
@@ -100,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) {
@@ -111,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);
@@ -127,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();
             }
@@ -174,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();
@@ -194,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
@@ -269,16 +333,24 @@ 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);
             tools.push({
                 name: operationId,
                 description: operation.summary || operation.description || `${method} ${path}`,
                 parameters,
                 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 } from './types.js';
+import { Tool, HttpMethod, AuthConfig, ParameterMetadata } from './types.js';
 import { AuthManager } from './auth-manager.js';
 interface ToolDefinition {
     name: string;
@@ -7,6 +7,8 @@ interface ToolDefinition {
     parameters: z.ZodObject<z.ZodRawShape>;
     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)) {
@@ -28,15 +28,20 @@ function createExecutor(tool, baseUrl, authManager) {
                     urlObj.searchParams.set(key, String(value));
                 }
             }
+            // Check if this tool requires auth (respects operation-level security)
+            // Tool-level authConfig overrides the global authConfig
+            const toolRequiresAuth = authManager.requiresAuth(tool.authConfig);
             // Add auth query params if needed
-            const authQueryParams = authManager.getAuthQueryParams();
-            for (const [key, value] of Object.entries(authQueryParams)) {
-                urlObj.searchParams.set(key, value);
+            if (toolRequiresAuth) {
+                const authQueryParams = authManager.getAuthQueryParams(tool.authConfig);
+                for (const [key, value] of Object.entries(authQueryParams)) {
+                    urlObj.searchParams.set(key, value);
+                }
             }
             url = urlObj.toString();
             // Build request options
             const headers = {
-                ...authManager.getAuthHeaders(),
+                ...(toolRequiresAuth ? authManager.getAuthHeaders(tool.authConfig) : {}),
             };
             const fetchOptions = {
                 method: tool.httpMethod,
@@ -62,7 +67,29 @@ function createExecutor(tool, baseUrl, authManager) {
                 responseData = await response.text();
             }
             if (!response.ok) {
-                throw new Error(`HTTP ${response.status}: ${JSON.stringify(responseData)}`);
+                // Build detailed error message
+                const errorDetails = [
+                    `HTTP ${response.status} ${response.statusText}`,
+                    `URL: ${tool.httpMethod} ${url}`,
+                    `Response: ${typeof responseData === 'string' ? responseData : JSON.stringify(responseData, null, 2)}`
+                ];
+                // Add helpful context for common errors
+                if (response.status === 401) {
+                    errorDetails.push('Authentication failed. Check your API key/token.');
+                }
+                else if (response.status === 403) {
+                    errorDetails.push('Access forbidden. Verify your permissions.');
+                }
+                else if (response.status === 404) {
+                    errorDetails.push('Resource not found.');
+                }
+                else if (response.status === 429) {
+                    errorDetails.push('Rate limit exceeded. Try again later.');
+                }
+                else if (response.status >= 500) {
+                    errorDetails.push('Server error. The API service may be experiencing issues.');
+                }
+                throw new Error(errorDetails.join('\n'));
             }
             return responseData;
         }
@@ -95,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;
@@ -7,8 +15,10 @@ export interface Tool {
     execute: (params: unknown) => Promise<unknown>;
     httpMethod: HttpMethod;
     path: string;
+    authConfig?: AuthConfig;
+    parameterMetadata?: ParameterMetadata;
 }
-export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'none';
+export type AuthType = 'oauth2' | 'apiKey' | 'bearer' | 'basic' | 'none';
 export interface AuthConfig {
     type: AuthType;
     authorizationUrl?: string;

package/package.json

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