@spec2tools/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026
+
+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/README.md

@@ -0,0 +1,117 @@
+# @spec2tools/core
+
+Core utilities for OpenAPI parsing and authentication.
+
+## Installation
+
+```bash
+npm install @spec2tools/core
+```
+
+## API
+
+### OpenAPI Parsing
+
+```ts
+import {
+  loadOpenAPISpec,
+  extractBaseUrl,
+  extractAuthConfig,
+  parseOperations,
+  formatToolSchema,
+  formatToolSignature,
+} from '@spec2tools/core';
+
+// Load an OpenAPI specification from file or URL
+const spec = await loadOpenAPISpec('./openapi.yaml');
+
+// Extract the base URL
+const baseUrl = extractBaseUrl(spec);
+
+// Extract authentication configuration
+const authConfig = extractAuthConfig(spec);
+
+// Parse operations into tool definitions
+const tools = parseOperations(spec);
+```
+
+### Authentication Manager
+
+```ts
+import { AuthManager } from '@spec2tools/core';
+
+const authManager = new AuthManager(authConfig);
+
+// Check if auth is required
+if (authManager.requiresAuth()) {
+  // Perform authentication (OAuth2, API Key, or Bearer token)
+  await authManager.authenticate();
+}
+
+// Get auth headers for requests
+const headers = authManager.getAuthHeaders();
+```
+
+### Tool Execution
+
+```ts
+import { createExecutableTools, executeToolByName } from '@spec2tools/core';
+
+// Create executable tools from tool definitions
+const tools = createExecutableTools(toolDefs, baseUrl, authManager);
+
+// Execute a tool by name
+const result = await executeToolByName(tools, 'getUser', { id: '123' });
+```
+
+### Error Classes
+
+```ts
+import {
+  UnsupportedSchemaError,
+  AuthenticationError,
+  ToolExecutionError,
+  SpecLoadError,
+} from '@spec2tools/core';
+```
+
+### Types
+
+```ts
+import type {
+  HttpMethod,
+  Tool,
+  AuthType,
+  AuthConfig,
+  Session,
+  OpenAPISpec,
+  PathItem,
+  Operation,
+  Parameter,
+  RequestBody,
+  MediaType,
+  Response,
+  SchemaObject,
+  SecurityScheme,
+} from '@spec2tools/core';
+```
+
+## Supported OpenAPI Features
+
+### Supported
+- `GET`, `POST`, `PUT`, `PATCH`, `DELETE` operations
+- Path parameters (string, number, boolean)
+- Query parameters (string, number, boolean)
+- Request body with simple JSON schemas (primitives, flat objects)
+- Security schemes: OAuth2 (authorization code with PKCE), API Key, Bearer token
+
+### Not Supported (throws error)
+- Nested objects beyond 1 level
+- Arrays of objects
+- `anyOf`, `oneOf`, `allOf` schemas
+- File uploads
+- `$ref` references
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,38 @@
+import { Tool } from './types.js';
+interface AgentConfig {
+    tools: Tool[];
+    model?: string;
+    maxSteps?: number;
+}
+/**
+ * AI Agent that uses OpenAPI tools
+ */
+export declare class Agent {
+    private tools;
+    private model;
+    private maxSteps;
+    private conversationHistory;
+    constructor(config: AgentConfig);
+    /**
+     * Get available tools description for the agent
+     */
+    getToolsDescription(): string;
+    /**
+     * Process a user message and return the response
+     */
+    chat(userMessage: string): Promise<string>;
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Get the list of tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name: string): Tool | undefined;
+}
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,126 @@
+import { generateText, tool, stepCountIs } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { ToolExecutionError } from './errors.js';
+import chalk from 'chalk';
+const MAX_OUTPUT_LENGTH = 500;
+/**
+ * Trim a string if it exceeds the maximum length
+ */
+function trimOutput(value) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    if (str.length > MAX_OUTPUT_LENGTH) {
+        return str.substring(0, MAX_OUTPUT_LENGTH) + '...';
+    }
+    return str;
+}
+/**
+ * AI Agent that uses OpenAPI tools
+ */
+export class Agent {
+    tools;
+    model;
+    maxSteps;
+    conversationHistory;
+    constructor(config) {
+        this.tools = config.tools;
+        this.model = config.model || 'gpt-5.1-chat-latest';
+        this.maxSteps = config.maxSteps || 10;
+        this.conversationHistory = [];
+    }
+    /**
+     * Get available tools description for the agent
+     */
+    getToolsDescription() {
+        if (this.tools.length === 0) {
+            return 'No tools available.';
+        }
+        const toolDescriptions = this.tools.map((tool) => {
+            return `- ${tool.name}: ${tool.description}`;
+        });
+        return `I have access to the following tools:\n${toolDescriptions.join('\n')}`;
+    }
+    /**
+     * Process a user message and return the response
+     */
+    async chat(userMessage) {
+        // Add user message to history
+        this.conversationHistory.push({
+            role: 'user',
+            content: userMessage,
+        });
+        try {
+            // Build AI SDK tools from our tool definitions
+            const aiTools = {};
+            for (const t of this.tools) {
+                const toolExecute = t.execute;
+                const toolName = t.name;
+                aiTools[t.name] = tool({
+                    description: t.description,
+                    inputSchema: t.parameters,
+                    execute: async (params) => {
+                        console.log(chalk.dim(`\n[Calling ${toolName} with ${JSON.stringify(params)}]`));
+                        try {
+                            const result = await toolExecute(params);
+                            console.log(chalk.dim(`[${toolName} returned: ${trimOutput(result)}]\n`));
+                            return result;
+                        }
+                        catch (error) {
+                            if (error instanceof ToolExecutionError) {
+                                console.log(chalk.red(`[${toolName} failed: ${error.message}]\n`));
+                                throw error;
+                            }
+                            throw error;
+                        }
+                    },
+                });
+            }
+            // Build system prompt
+            const systemPrompt = `You are a helpful AI assistant with access to various API tools.
+When the user asks you to perform actions, use the available tools to help them.
+Always explain what you're doing and present results in a clear, readable format.
+If a tool call fails, explain the error to the user.`;
+            // Generate response with tool use
+            const result = await generateText({
+                model: openai(this.model),
+                system: systemPrompt,
+                messages: this.conversationHistory,
+                tools: aiTools,
+                stopWhen: stepCountIs(this.maxSteps),
+            });
+            // Add assistant response to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: result.text,
+            });
+            return result.text;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Add error response to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: `I encountered an error: ${errorMessage}`,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Clear conversation history
+     */
+    clearHistory() {
+        this.conversationHistory = [];
+    }
+    /**
+     * Get the list of tool names
+     */
+    getToolNames() {
+        return this.tools.map((t) => t.name);
+    }
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name) {
+        return this.tools.find((t) => t.name === name);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/auth-manager.d.ts

@@ -0,0 +1,67 @@
+import { AuthConfig } from './types.js';
+export declare class AuthManager {
+    private authConfig;
+    private accessToken?;
+    private refreshToken?;
+    private clientId?;
+    private clientSecret?;
+    private codeVerifier?;
+    constructor(authConfig: AuthConfig);
+    /**
+     * Check if authentication is required
+     */
+    requiresAuth(): boolean;
+    /**
+     * Get the current access token
+     */
+    getAccessToken(): string | undefined;
+    /**
+     * Get authorization headers for requests
+     */
+    getAuthHeaders(): Record<string, string>;
+    /**
+     * Get query parameters for API key auth
+     */
+    getAuthQueryParams(): Record<string, string>;
+    /**
+     * Perform authentication based on config type
+     */
+    authenticate(): Promise<void>;
+    /**
+     * Prompt user for API key
+     */
+    private promptForApiKey;
+    /**
+     * Prompt user for bearer token
+     */
+    private promptForBearerToken;
+    /**
+     * Perform OAuth2 authorization code flow
+     */
+    private performOAuth2Flow;
+    /**
+     * Register OAuth2 client dynamically
+     */
+    private registerClient;
+    /**
+     * Start local callback server and initiate authorization
+     */
+    private startCallbackServerAndAuthorize;
+    /**
+     * Generate PKCE code verifier and challenge
+     */
+    private generatePKCE;
+    /**
+     * Build the OAuth2 authorization URL
+     */
+    private buildAuthorizationUrl;
+    /**
+     * Exchange authorization code for access token
+     */
+    private exchangeCodeForToken;
+    /**
+     * Set access token directly (for testing or manual token entry)
+     */
+    setAccessToken(token: string): void;
+}
+//# sourceMappingURL=auth-manager.d.ts.map

package/dist/auth-manager.js

@@ -0,0 +1,308 @@
+import express from 'express';
+import open from 'open';
+import crypto from 'crypto';
+import { createServer } from 'http';
+import { AuthenticationError } from './errors.js';
+import * as readline from 'readline';
+const CALLBACK_PORT = 54321;
+const CALLBACK_PATH = '/callback';
+export class AuthManager {
+    authConfig;
+    accessToken;
+    refreshToken;
+    clientId;
+    clientSecret;
+    codeVerifier;
+    constructor(authConfig) {
+        this.authConfig = authConfig;
+    }
+    /**
+     * Check if authentication is required
+     */
+    requiresAuth() {
+        return this.authConfig.type !== 'none';
+    }
+    /**
+     * Get the current access token
+     */
+    getAccessToken() {
+        return this.accessToken;
+    }
+    /**
+     * Get authorization headers for requests
+     */
+    getAuthHeaders() {
+        if (!this.accessToken) {
+            return {};
+        }
+        switch (this.authConfig.type) {
+            case 'oauth2':
+            case 'bearer':
+                return { Authorization: `Bearer ${this.accessToken}` };
+            case 'apiKey':
+                if (this.authConfig.apiKeyIn === 'header' && this.authConfig.apiKeyHeader) {
+                    return { [this.authConfig.apiKeyHeader]: this.accessToken };
+                }
+                return {};
+            default:
+                return {};
+        }
+    }
+    /**
+     * Get query parameters for API key auth
+     */
+    getAuthQueryParams() {
+        if (this.authConfig.type === 'apiKey' &&
+            this.authConfig.apiKeyIn === 'query' &&
+            this.authConfig.apiKeyHeader &&
+            this.accessToken) {
+            return { [this.authConfig.apiKeyHeader]: this.accessToken };
+        }
+        return {};
+    }
+    /**
+     * Perform authentication based on config type
+     */
+    async authenticate() {
+        switch (this.authConfig.type) {
+            case 'oauth2':
+                await this.performOAuth2Flow();
+                break;
+            case 'apiKey':
+                await this.promptForApiKey();
+                break;
+            case 'bearer':
+                await this.promptForBearerToken();
+                break;
+            case 'none':
+                // No authentication needed
+                break;
+        }
+    }
+    /**
+     * Prompt user for API key
+     */
+    async promptForApiKey() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const headerName = this.authConfig.apiKeyHeader || 'API-Key';
+        this.accessToken = await new Promise((resolve) => {
+            rl.question(`Enter your API key (${headerName}): `, (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        });
+        if (!this.accessToken) {
+            throw new AuthenticationError('API key is required');
+        }
+    }
+    /**
+     * Prompt user for bearer token
+     */
+    async promptForBearerToken() {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        this.accessToken = await new Promise((resolve) => {
+            rl.question('Enter your Bearer token: ', (answer) => {
+                rl.close();
+                resolve(answer.trim());
+            });
+        });
+        if (!this.accessToken) {
+            throw new AuthenticationError('Bearer token is required');
+        }
+    }
+    /**
+     * Perform OAuth2 authorization code flow
+     */
+    async performOAuth2Flow() {
+        if (!this.authConfig.authorizationUrl || !this.authConfig.tokenUrl) {
+            throw new AuthenticationError('OAuth2 requires authorizationUrl and tokenUrl');
+        }
+        // Register client dynamically
+        await this.registerClient();
+        // Start local callback server
+        const authCode = await this.startCallbackServerAndAuthorize();
+        // Exchange code for token
+        await this.exchangeCodeForToken(authCode);
+    }
+    /**
+     * Register OAuth2 client dynamically
+     */
+    async registerClient() {
+        // Derive registration URL from token URL (replace /token with /register)
+        const registrationUrl = this.authConfig.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, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                client_name: 'OpenAPI Agent CLI',
+                redirect_uris: [redirectUri],
+                grant_types: ['authorization_code'],
+                token_endpoint_auth_method: 'none',
+            }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new AuthenticationError(`Client registration failed: ${response.status} ${errorText}`);
+        }
+        const registration = (await response.json());
+        this.clientId = registration.client_id;
+        this.clientSecret = registration.client_secret;
+        console.log('Client registered successfully.');
+    }
+    /**
+     * Start local callback server and initiate authorization
+     */
+    async startCallbackServerAndAuthorize() {
+        return new Promise((resolve, reject) => {
+            const app = express();
+            let server;
+            app.get(CALLBACK_PATH, (req, res) => {
+                const code = req.query.code;
+                const error = req.query.error;
+                if (error) {
+                    res.send(`
+            <html>
+              <body>
+                <h1>Authentication Failed</h1>
+                <p>Error: ${error}</p>
+                <p>You can close this window.</p>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    reject(new AuthenticationError(error));
+                    return;
+                }
+                if (!code) {
+                    res.send(`
+            <html>
+              <body>
+                <h1>Authentication Failed</h1>
+                <p>No authorization code received.</p>
+                <p>You can close this window.</p>
+              </body>
+            </html>
+          `);
+                    server.close();
+                    reject(new AuthenticationError('No authorization code received'));
+                    return;
+                }
+                res.send(`
+          <html>
+            <body>
+              <h1>Authentication Successful!</h1>
+              <p>You can close this window and return to the CLI.</p>
+            </body>
+          </html>
+        `);
+                server.close();
+                resolve(code);
+            });
+            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);
+                console.log('\nAuthentication required. Opening browser...');
+                console.log(`If browser doesn't open, visit: ${authUrl}\n`);
+                open(authUrl).catch(() => {
+                    console.log('Could not open browser automatically.');
+                });
+            });
+            server.on('error', (err) => {
+                if (err.code === 'EADDRINUSE') {
+                    reject(new AuthenticationError(`Port ${CALLBACK_PORT} is already in use. Please free the port and try again.`));
+                }
+                else {
+                    reject(new AuthenticationError(err.message));
+                }
+            });
+            // Timeout after 5 minutes
+            setTimeout(() => {
+                server.close();
+                reject(new AuthenticationError('Authentication timed out'));
+            }, 5 * 60 * 1000);
+        });
+    }
+    /**
+     * Generate PKCE code verifier and challenge
+     */
+    generatePKCE() {
+        // Generate random code verifier (43-128 characters)
+        const verifier = crypto.randomBytes(32).toString('base64url');
+        // Create code challenge using SHA-256
+        const challenge = crypto
+            .createHash('sha256')
+            .update(verifier)
+            .digest('base64url');
+        return { verifier, challenge };
+    }
+    /**
+     * Build the OAuth2 authorization URL
+     */
+    buildAuthorizationUrl(redirectUri) {
+        const url = new URL(this.authConfig.authorizationUrl);
+        // Generate PKCE
+        const pkce = this.generatePKCE();
+        this.codeVerifier = pkce.verifier;
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', this.clientId);
+        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(' '));
+        }
+        // Generate state for CSRF protection
+        const state = crypto.randomBytes(16).toString('base64url');
+        url.searchParams.set('state', state);
+        return url.toString();
+    }
+    /**
+     * Exchange authorization code for access token
+     */
+    async exchangeCodeForToken(code) {
+        const redirectUri = `http://127.0.0.1:${CALLBACK_PORT}${CALLBACK_PATH}`;
+        const params = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            client_id: this.clientId,
+            code_verifier: this.codeVerifier,
+        });
+        // Only include client_secret if set (public clients don't have one)
+        if (this.clientSecret) {
+            params.set('client_secret', this.clientSecret);
+        }
+        const response = await fetch(this.authConfig.tokenUrl, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new AuthenticationError(`Token exchange failed: ${response.status} ${errorText}`);
+        }
+        const tokenResponse = (await response.json());
+        this.accessToken = tokenResponse.access_token;
+        this.refreshToken = tokenResponse.refresh_token;
+    }
+    /**
+     * Set access token directly (for testing or manual token entry)
+     */
+    setAccessToken(token) {
+        this.accessToken = token;
+    }
+}
+//# sourceMappingURL=auth-manager.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createCLI(): Command;
+//# sourceMappingURL=cli.d.ts.map