diff --git a/.changeset/cli-tool.md b/.changeset/cli-tool.md index b32b086..8e3a876 100644 --- a/.changeset/cli-tool.md +++ b/.changeset/cli-tool.md @@ -1,5 +1,6 @@ --- "@scope3/agentic-client": minor +"scope3": minor --- Add dynamic CLI tool for Scope3 Agentic API with automatic command generation diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c88c2bf..fc44a30 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,3 +42,4 @@ jobs: title: 'chore: version packages' env: GITHUB_TOKEN: ${{ secrets.PAT_TOKEN }} + NPM_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/.npmignore b/.npmignore new file mode 100644 index 0000000..7cf8508 --- /dev/null +++ b/.npmignore @@ -0,0 +1,60 @@ +# Source files (we only publish compiled JS) +src/ +*.ts +!*.d.ts + +# Tests +**/*.test.js +**/*.test.ts +**/__tests__/ + +# Development files +.env +.env.* +!.env.example +.vscode/ +.idea/ + +# Build artifacts we don't need +*.tsbuildinfo +tsconfig.json + +# Documentation +docs/ +examples/ +*.md +!README.md + +# Git +.git/ +.gitignore +.github/ + +# CI/CD +.husky/ + +# Config files +.eslintrc.json +.prettierrc.json +jest.config.js + +# OpenAPI specs (large files not needed at runtime) +*.yaml +openapi.yaml +media-agent-openapi.yaml +outcome-agent-openapi.yaml +partner-api.yaml +platform-api.yaml + +# Test files +test-*.ts +test-*.js + +# Changesets +.changeset/ + +# Scripts +scripts/ + +# Conductor config +conductor.json diff --git a/README.md b/README.md index b06831f..8583d9f 100644 --- a/README.md +++ b/README.md @@ -28,6 +28,8 @@ import { Scope3AgenticClient } from '@scope3/agentic-client'; const client = new Scope3AgenticClient({ apiKey: process.env.SCOPE3_API_KEY, + // Optional: specify environment (defaults to 'production') + environment: 'production', // or 'staging' }); // List brand agents @@ -49,12 +51,24 @@ const campaign = await client.campaigns.create({ The CLI dynamically discovers available commands from the API server, ensuring it's always up-to-date: ```bash -# Install globally +# Install globally or use npx npm install -g @scope3/agentic-client +# or +npx @scope3/agentic-client --help # Configure authentication scope3 config set apiKey your_api_key_here +# Configure environment (optional - defaults to production) +scope3 config set environment staging + +# Or use environment variables +export SCOPE3_API_KEY=your_api_key_here +export SCOPE3_ENVIRONMENT=staging # or 'production' + +# Or use command-line flags +scope3 --environment staging list-tools + # Discover available commands (80+ auto-generated) scope3 list-tools @@ -62,6 +76,10 @@ scope3 list-tools scope3 brand-agent list scope3 campaign create --prompt "Q1 2024 Spring Campaign" --brandAgentId 123 scope3 media-buy execute --mediaBuyId "buy_123" + +# Switch environments on the fly +scope3 --environment production campaign list +scope3 --environment staging campaign list ``` **Dynamic Updates:** Commands automatically stay in sync with API changes. No manual updates needed! @@ -71,11 +89,23 @@ scope3 media-buy execute --mediaBuyId "buy_123" ```typescript const client = new Scope3AgenticClient({ apiKey: 'your-api-key', - baseUrl: 'https://api.agentic.scope3.com', // optional, defaults to production - timeout: 30000, // optional, request timeout in ms + + // Option 1: Use environment (recommended) + environment: 'production', // 'production' or 'staging' (default: 'production') + + // Option 2: Use custom base URL (overrides environment) + baseUrl: 'https://custom-api.example.com', + + // Optional settings + timeout: 30000, // request timeout in ms }); ``` +### Environment URLs + +- **Production**: `https://api.agentic.scope3.com` +- **Staging**: `https://api.agentic.staging.scope3.com` + ## API Resources The client provides access to all Scope3 API resources: diff --git a/package-lock.json b/package-lock.json index 7fe8e35..940ed96 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,13 +1,16 @@ { "name": "@scope3/agentic-client", - "version": "1.0.4", + "version": "1.0.5", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@scope3/agentic-client", - "version": "1.0.4", + "version": "1.0.5", "license": "MIT", + "workspaces": [ + "packages/*" + ], "dependencies": { "@modelcontextprotocol/sdk": "^1.20.1", "chalk": "^4.1.2", @@ -2071,6 +2074,10 @@ "node": ">= 8" } }, + "node_modules/@scope3/agentic-client": { + "resolved": "", + "link": true + }, "node_modules/@sec-ant/readable-stream": { "version": "0.4.1", "resolved": "https://registry.npmjs.org/@sec-ant/readable-stream/-/readable-stream-0.4.1.tgz", @@ -7733,6 +7740,10 @@ "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", "license": "MIT" }, + "node_modules/scope3": { + "resolved": "packages/scope3-cli", + "link": true + }, "node_modules/semver": { "version": "7.7.3", "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.3.tgz", @@ -8832,6 +8843,17 @@ "peerDependencies": { "zod": "^3.24.1" } + }, + "packages/scope3-cli": { + "name": "scope3", + "version": "1.0.5", + "license": "MIT", + "dependencies": { + "@scope3/agentic-client": "file:../.." + }, + "bin": { + "scope3": "cli.js" + } } } } diff --git a/package.json b/package.json index 53521de..ca44047 100644 --- a/package.json +++ b/package.json @@ -1,9 +1,18 @@ { "name": "@scope3/agentic-client", - "version": "1.0.4", + "version": "1.0.5", "description": "TypeScript client for the Scope3 Agentic API with AdCP webhook support", + "workspaces": [ + "packages/*" + ], "main": "dist/index.js", "types": "dist/index.d.ts", + "files": [ + "dist", + "README.md", + "LICENSE", + ".env.example" + ], "publishConfig": { "access": "public" }, @@ -23,10 +32,11 @@ "generate-platform-api-types": "openapi-typescript platform-api.yaml -o src/types/platform-api.ts", "update-schemas": "curl -f -o outcome-agent-openapi.yaml https://raw.githubusercontent.com/scope3data/agentic-api/main/mintlify/outcome-agent-openapi.yaml && curl -f -o partner-api.yaml https://raw.githubusercontent.com/scope3data/agentic-api/main/mintlify/partner-api.yaml && curl -f -o platform-api.yaml https://raw.githubusercontent.com/scope3data/agentic-api/main/mintlify/platform-api.yaml && npm run generate-outcome-agent-types && npm run generate-partner-api-types && npm run generate-platform-api-types", "prepare": "husky", + "prepublishOnly": "npm run build", "pretest": "npm run type-check", "changeset": "changeset", "version": "changeset version", - "release": "npm run build && npm publish" + "release": "npm run build && changeset publish" }, "keywords": [ "scope3", diff --git a/packages/scope3-cli/.npmrc b/packages/scope3-cli/.npmrc new file mode 100644 index 0000000..63b729b --- /dev/null +++ b/packages/scope3-cli/.npmrc @@ -0,0 +1 @@ +# Automatically rewrite file: dependencies to version numbers on publish diff --git a/packages/scope3-cli/README.md b/packages/scope3-cli/README.md new file mode 100644 index 0000000..b083782 --- /dev/null +++ b/packages/scope3-cli/README.md @@ -0,0 +1,48 @@ +# scope3 + +Command-line interface for the Scope3 Agentic API. + +This is a thin wrapper around [@scope3/agentic-client](https://www.npmjs.com/package/@scope3/agentic-client) that provides a shorter package name for easier CLI usage. + +## Installation + +```bash +# Global installation +npm install -g scope3 + +# Or use directly with npx +npx scope3 --help +``` + +## Usage + +```bash +# Configure your API key +scope3 config set apiKey YOUR_API_KEY + +# List available commands +scope3 list-tools + +# Use dynamic commands +scope3 brand-agent list +scope3 campaign create --name "My Campaign" + +# Output formats +scope3 media-product list --format json +scope3 media-product list --format list +scope3 media-product list --format table # default + +# Environment switching +scope3 --environment staging brand-agent list + +# Debug mode +scope3 --debug campaign get --campaignId 123 +``` + +## Documentation + +For full documentation, see [@scope3/agentic-client](https://www.npmjs.com/package/@scope3/agentic-client) + +## License + +MIT diff --git a/packages/scope3-cli/cli.js b/packages/scope3-cli/cli.js new file mode 100755 index 0000000..c29d1f0 --- /dev/null +++ b/packages/scope3-cli/cli.js @@ -0,0 +1,3 @@ +#!/usr/bin/env node +// Thin wrapper that re-exports the CLI from @scope3/agentic-client +require('@scope3/agentic-client/dist/cli.js'); diff --git a/packages/scope3-cli/package.json b/packages/scope3-cli/package.json new file mode 100644 index 0000000..05ff4df --- /dev/null +++ b/packages/scope3-cli/package.json @@ -0,0 +1,36 @@ +{ + "name": "scope3", + "version": "1.0.5", + "description": "Scope3 Agentic CLI - Command-line interface for the Scope3 Agentic API", + "bin": { + "scope3": "./cli.js" + }, + "files": [ + "cli.js", + "README.md" + ], + "keywords": [ + "scope3", + "agentic", + "cli", + "advertising", + "adtech" + ], + "author": "Scope3", + "license": "MIT", + "repository": { + "type": "git", + "url": "https://github.com/scope3data/agentic-client.git", + "directory": "packages/scope3-cli" + }, + "homepage": "https://github.com/scope3data/agentic-client#readme", + "bugs": { + "url": "https://github.com/scope3data/agentic-client/issues" + }, + "dependencies": { + "@scope3/agentic-client": "file:../.." + }, + "publishConfig": { + "access": "public" + } +} diff --git a/src/__tests__/cli-format.test.ts b/src/__tests__/cli-format.test.ts new file mode 100644 index 0000000..92aa97f --- /dev/null +++ b/src/__tests__/cli-format.test.ts @@ -0,0 +1,362 @@ +/** + * Tests for CLI output formatting (formatOutput function) + * + * Tests all three output formats: + * - JSON: raw JSON output + * - Table: columnar display with cli-table3 + * - List: detailed view with all fields + */ + +import chalk from 'chalk'; + +// We need to test the formatOutput function which is currently in cli.ts +// For better testability, we'll extract it to a separate module in recommendations +// For now, we'll test the behavior by mocking console.log and importing the function + +describe('CLI Output Formatting', () => { + let consoleLogSpy: jest.SpyInstance; + + beforeEach(() => { + consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(); + }); + + afterEach(() => { + consoleLogSpy.mockRestore(); + }); + + // Helper to create formatOutput function (extracted from cli.ts) + function formatOutput(data: unknown, format: string): void { + if (format === 'json') { + console.log(JSON.stringify(data, null, 2)); + return; + } + + if (!data) { + console.log(chalk.yellow('No data to display')); + return; + } + + const dataObj = data as Record; + let actualData: unknown = dataObj.data || data; + + if ( + typeof actualData === 'object' && + actualData && + !Array.isArray(actualData) && + 'items' in actualData && + Array.isArray((actualData as Record).items) + ) { + actualData = (actualData as Record).items; + } + + if ( + typeof actualData === 'object' && + actualData && + !Array.isArray(actualData) && + Object.keys(actualData).length === 1 && + 'message' in actualData + ) { + console.log(String((actualData as Record).message)); + return; + } + + if (Array.isArray(actualData)) { + if (actualData.length === 0) { + console.log(chalk.yellow('No results found')); + return; + } + + if (format === 'list') { + actualData.forEach((item, index) => { + console.log(chalk.cyan(`\n${index + 1}.`)); + Object.entries(item).forEach(([key, value]) => { + let displayValue: string; + if (value === null || value === undefined) { + displayValue = chalk.gray('(empty)'); + } else if (typeof value === 'object') { + displayValue = JSON.stringify(value, null, 2); + } else { + displayValue = String(value); + } + console.log(` ${chalk.yellow(key)}: ${displayValue}`); + }); + }); + console.log(); + } else { + // Table format - simplified for testing + console.log('TABLE FORMAT'); + } + } else if (typeof actualData === 'object' && actualData) { + console.log('SINGLE OBJECT TABLE'); + } else { + console.log(actualData); + } + + if (dataObj.success !== undefined) { + console.log(dataObj.success ? chalk.green('āœ“ Success') : chalk.red('āœ— Failed')); + } + } + + describe('JSON format', () => { + it('should output raw JSON for simple objects', () => { + const data = { id: '123', name: 'Test Campaign' }; + formatOutput(data, 'json'); + + expect(consoleLogSpy).toHaveBeenCalledWith(JSON.stringify(data, null, 2)); + }); + + it('should output raw JSON for arrays', () => { + const data = [{ id: '1' }, { id: '2' }]; + formatOutput(data, 'json'); + + expect(consoleLogSpy).toHaveBeenCalledWith(JSON.stringify(data, null, 2)); + }); + + it('should output raw JSON for nested structures', () => { + const data = { + items: [{ id: '1', nested: { deep: 'value' } }], + metadata: { total: 1 }, + }; + formatOutput(data, 'json'); + + expect(consoleLogSpy).toHaveBeenCalledWith(JSON.stringify(data, null, 2)); + }); + + it('should handle null data', () => { + formatOutput(null, 'json'); + // JSON format outputs "null" as JSON, which is valid + expect(consoleLogSpy).toHaveBeenCalledWith('null'); + }); + + it('should handle undefined data', () => { + formatOutput(undefined, 'json'); + // JSON format outputs undefined directly + expect(consoleLogSpy).toHaveBeenCalled(); + }); + }); + + describe('data unwrapping', () => { + it('should unwrap ToolResponse wrapper (data field)', () => { + const data = { + success: true, + data: { id: '123', name: 'Campaign' }, + }; + formatOutput(data, 'json'); + + const output = JSON.parse(consoleLogSpy.mock.calls[0][0]); + // In JSON format, we get the full structure + expect(output.data).toEqual({ id: '123', name: 'Campaign' }); + }); + + it('should unwrap items array from response', () => { + const data = { + items: [{ id: '1' }, { id: '2' }], + total: 2, + }; + formatOutput(data, 'list'); + + // Should display items + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('1.')); + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('2.')); + }); + + it('should handle nested data wrapper', () => { + const data = { + success: true, + data: { + items: [{ id: '1' }], + }, + }; + formatOutput(data, 'list'); + + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('1.')); + }); + }); + + describe('message-only responses', () => { + it('should display plain message for single message objects', () => { + const data = { message: 'Operation completed successfully' }; + formatOutput(data, 'table'); + + expect(consoleLogSpy).toHaveBeenCalledWith('Operation completed successfully'); + expect(consoleLogSpy).not.toHaveBeenCalledWith(expect.stringContaining('TABLE')); + }); + + it('should display plain message in list format', () => { + const data = { message: 'Resource deleted' }; + formatOutput(data, 'list'); + + expect(consoleLogSpy).toHaveBeenCalledWith('Resource deleted'); + }); + + it('should use table format for message with other fields', () => { + const data = { message: 'Success', id: '123' }; + formatOutput(data, 'table'); + + expect(consoleLogSpy).toHaveBeenCalledWith('SINGLE OBJECT TABLE'); + }); + }); + + describe('list format', () => { + it('should display numbered list with all fields', () => { + const data = [ + { id: '1', name: 'Item 1', status: 'active' }, + { id: '2', name: 'Item 2', status: 'inactive' }, + ]; + formatOutput(data, 'list'); + + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('1.')); + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('2.')); + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringMatching(/id.*1/)); + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringMatching(/name.*Item 1/)); + }); + + it('should show empty values as (empty)', () => { + const data = [{ id: '1', name: null, description: undefined }]; + formatOutput(data, 'list'); + + const emptyCall = consoleLogSpy.mock.calls.find((call) => call[0].includes('(empty)')); + expect(emptyCall).toBeDefined(); + }); + + it('should format nested objects as JSON', () => { + const data = [ + { + id: '1', + metadata: { created: '2024-01-01', tags: ['tag1', 'tag2'] }, + }, + ]; + formatOutput(data, 'list'); + + const jsonCall = consoleLogSpy.mock.calls.find((call) => call[0].includes('"created"')); + expect(jsonCall).toBeDefined(); + }); + + it('should handle empty array', () => { + formatOutput([], 'list'); + + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('No results found')); + }); + + it('should add extra line after list', () => { + const data = [{ id: '1' }]; + formatOutput(data, 'list'); + + // Last call should be empty line + const lastCall = consoleLogSpy.mock.calls[consoleLogSpy.mock.calls.length - 1]; + expect(lastCall[0]).toBe(undefined); + }); + }); + + describe('table format', () => { + it('should use table for arrays (simplified test)', () => { + const data = [{ id: '1', name: 'Item' }]; + formatOutput(data, 'table'); + + expect(consoleLogSpy).toHaveBeenCalledWith('TABLE FORMAT'); + }); + + it('should use table for single objects', () => { + const data = { id: '123', name: 'Campaign', status: 'active' }; + formatOutput(data, 'table'); + + expect(consoleLogSpy).toHaveBeenCalledWith('SINGLE OBJECT TABLE'); + }); + + it('should handle empty array', () => { + formatOutput([], 'table'); + + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('No results found')); + }); + }); + + describe('success indicator', () => { + // Note: Success indicator logic is in the full implementation (cli.ts) + // This simplified test version doesn't implement it to keep tests focused + // Integration tests should cover the full formatOutput behavior + + it('should handle success field in data', () => { + const data = { success: true, data: { id: '123' } }; + formatOutput(data, 'json'); + + expect(consoleLogSpy).toHaveBeenCalled(); + const output = consoleLogSpy.mock.calls[0][0]; + expect(output).toContain('success'); + }); + }); + + describe('edge cases', () => { + it('should handle primitive values', () => { + formatOutput('plain string', 'table'); + expect(consoleLogSpy).toHaveBeenCalledWith('plain string'); + + consoleLogSpy.mockClear(); + formatOutput(42, 'table'); + expect(consoleLogSpy).toHaveBeenCalledWith(42); + + consoleLogSpy.mockClear(); + formatOutput(true, 'table'); + expect(consoleLogSpy).toHaveBeenCalledWith(true); + }); + + it('should handle array of primitives', () => { + formatOutput(['a', 'b', 'c'], 'list'); + // Should handle gracefully (may not have perfect output) + expect(consoleLogSpy).toHaveBeenCalled(); + }); + + it('should handle deeply nested structures', () => { + const data = { + items: [ + { + id: '1', + level1: { + level2: { + level3: { + value: 'deep', + }, + }, + }, + }, + ], + }; + formatOutput(data, 'list'); + + expect(consoleLogSpy).toHaveBeenCalled(); + }); + + it('should handle special characters in values', () => { + const data = [ + { + id: '1', + name: 'Campaign "Special" & ', + emoji: 'šŸŽ‰ Success!', + }, + ]; + formatOutput(data, 'list'); + + expect(consoleLogSpy).toHaveBeenCalled(); + }); + }); + + describe('format parameter validation', () => { + it('should default to table for unknown format', () => { + const data = [{ id: '1' }]; + formatOutput(data, 'unknown-format'); + + // Should fall back to table + expect(consoleLogSpy).toHaveBeenCalledWith('TABLE FORMAT'); + }); + + it('should be case-sensitive', () => { + const data = { id: '123' }; + + formatOutput(data, 'JSON'); + expect(consoleLogSpy).not.toHaveBeenCalledWith(expect.stringContaining('{')); + + consoleLogSpy.mockClear(); + formatOutput(data, 'json'); + expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('{')); + }); + }); +}); diff --git a/src/__tests__/client-mcp.test.ts b/src/__tests__/client-mcp.test.ts new file mode 100644 index 0000000..577f14b --- /dev/null +++ b/src/__tests__/client-mcp.test.ts @@ -0,0 +1,372 @@ +/** + * Tests for Scope3Client MCP protocol interactions + * + * Tests the actual MCP client behavior including: + * - structuredContent handling + * - Text content fallback + * - JSON parsing from text + * - Error scenarios + * - Debug mode + */ + +import { Scope3Client } from '../client'; +import { Client } from '@modelcontextprotocol/sdk/client/index.js'; +import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; + +// Mock the MCP SDK modules +jest.mock('@modelcontextprotocol/sdk/client/index.js'); +jest.mock('@modelcontextprotocol/sdk/client/streamableHttp.js'); + +describe('Scope3Client MCP Protocol', () => { + let client: Scope3Client; + let mockMcpClient: jest.Mocked; + let mockTransport: jest.Mocked; + let consoleErrorSpy: jest.SpyInstance; + + beforeEach(() => { + // Reset mocks + jest.clearAllMocks(); + + // Suppress logger output during tests + consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(); + + // Setup mock MCP client + mockMcpClient = { + connect: jest.fn(), + close: jest.fn(), + callTool: jest.fn(), + } as unknown as jest.Mocked; + + mockTransport = { + close: jest.fn(), + } as unknown as jest.Mocked; + + // Mock constructor to return our mock client + (Client as jest.MockedClass).mockImplementation(() => mockMcpClient); + ( + StreamableHTTPClientTransport as jest.MockedClass + ).mockImplementation(() => mockTransport); + + client = new Scope3Client({ + apiKey: 'test-key', + environment: 'production', + }); + }); + + afterEach(async () => { + await client.disconnect(); + consoleErrorSpy.mockRestore(); + }); + + describe('connection management', () => { + it('should connect once on first callTool', async () => { + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { result: 'success' }, + content: [], + }); + + await client['callTool']('test_tool', { arg: 'value' }); + + expect(mockMcpClient.connect).toHaveBeenCalledTimes(1); + expect(mockMcpClient.connect).toHaveBeenCalledWith(mockTransport); + }); + + it('should not reconnect on subsequent calls', async () => { + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { result: 'success' }, + content: [], + }); + + await client['callTool']('test_tool_1', {}); + await client['callTool']('test_tool_2', {}); + + expect(mockMcpClient.connect).toHaveBeenCalledTimes(1); + }); + + it('should disconnect cleanly', async () => { + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { result: 'success' }, + content: [], + }); + + await client['callTool']('test_tool', {}); + await client.disconnect(); + + expect(mockMcpClient.close).toHaveBeenCalledTimes(1); + expect(mockTransport.close).toHaveBeenCalledTimes(1); + }); + + it('should not error when disconnecting without connecting', async () => { + await expect(client.disconnect()).resolves.not.toThrow(); + expect(mockMcpClient.close).not.toHaveBeenCalled(); + }); + }); + + describe('structuredContent handling (preferred path)', () => { + it('should return structuredContent when present', async () => { + const expectedData = { id: '123', name: 'Test Campaign', status: 'active' }; + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: expectedData, + content: [{ type: 'text', text: 'This should be ignored' }], + }); + + const result = await client['callTool'], typeof expectedData>( + 'campaigns_get', + { campaignId: '123' } + ); + + expect(result).toEqual(expectedData); + }); + + it('should handle complex nested structuredContent', async () => { + const complexData = { + items: [ + { id: '1', nested: { deep: { value: 'test' } } }, + { id: '2', array: [1, 2, 3] }, + ], + metadata: { total: 2, page: 1 }, + }; + + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: complexData, + content: [], + }); + + const result = await client['callTool']('campaigns_list', {}); + + expect(result).toEqual(complexData); + }); + + it('should handle empty structuredContent object', async () => { + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: {}, + content: [], + }); + + const result = await client['callTool']('test_tool', {}); + + expect(result).toEqual({}); + }); + }); + + describe('text content fallback (JSON parsing)', () => { + it('should parse valid JSON from text content', async () => { + const data = { id: '456', status: 'completed' }; + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'text', text: JSON.stringify(data) }], + }); + + const result = await client['callTool']('test_tool', {}); + + expect(result).toEqual(data); + }); + + it('should parse JSON array from text content', async () => { + const data = [{ id: '1' }, { id: '2' }]; + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'text', text: JSON.stringify(data) }], + }); + + const result = await client['callTool']('test_tool', {}); + + expect(result).toEqual(data); + }); + + it('should wrap non-JSON text in message object', async () => { + const plainText = 'Operation completed successfully'; + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'text', text: plainText }], + }); + + const result = await client['callTool'], { message: string }>( + 'test_tool', + {} + ); + + expect(result).toEqual({ message: plainText }); + }); + + it('should handle text content with special characters', async () => { + const data = { message: 'Success! šŸŽ‰ Campaign created.' }; + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'text', text: JSON.stringify(data) }], + }); + + const result = await client['callTool']('test_tool', {}); + + expect(result).toEqual(data); + }); + }); + + describe('error handling', () => { + it('should throw error when no content is returned', async () => { + mockMcpClient.callTool.mockResolvedValue({ + content: [], + }); + + await expect(client['callTool']('test_tool', {})).rejects.toThrow( + 'Unexpected tool response format' + ); + }); + + it('should throw error when content type is not text', async () => { + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'image', data: 'base64data' }], + }); + + await expect(client['callTool']('test_tool', {})).rejects.toThrow( + 'Unexpected tool response format' + ); + }); + + it('should propagate MCP client errors', async () => { + const mcpError = new Error('MCP transport failure'); + mockMcpClient.callTool.mockRejectedValue(mcpError); + + await expect(client['callTool']('test_tool', {})).rejects.toThrow('MCP transport failure'); + }); + + it('should handle connection errors', async () => { + const connectionError = new Error('Connection refused'); + mockMcpClient.connect.mockRejectedValue(connectionError); + + await expect(client['callTool']('test_tool', {})).rejects.toThrow('Connection refused'); + }); + }); + + describe('debug mode', () => { + beforeEach(() => { + // Create client with debug enabled + client = new Scope3Client({ + apiKey: 'test-key', + debug: true, + }); + + // Re-mock after new client creation + (Client as jest.MockedClass).mockImplementation(() => mockMcpClient); + ( + StreamableHTTPClientTransport as jest.MockedClass + ).mockImplementation(() => mockTransport); + }); + + it('should store debug info when debug mode is enabled', async () => { + const request = { campaignId: '123' }; + const response = { id: '123', name: 'Test' }; + + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: response, + content: [], + }); + + await client['callTool']('campaigns_get', request); + + expect(client.lastDebugInfo).toBeDefined(); + expect(client.lastDebugInfo?.toolName).toBe('campaigns_get'); + expect(client.lastDebugInfo?.request).toEqual(request); + expect(client.lastDebugInfo?.response).toEqual(response); + expect(client.lastDebugInfo?.durationMs).toBeGreaterThanOrEqual(0); + }); + + it('should store raw response when parsing JSON from text', async () => { + const data = { id: '456' }; + const rawText = JSON.stringify(data); + + mockMcpClient.callTool.mockResolvedValue({ + content: [{ type: 'text', text: rawText }], + }); + + await client['callTool']('test_tool', {}); + + expect(client.lastDebugInfo?.rawResponse).toBe(rawText); + expect(client.lastDebugInfo?.response).toEqual(data); + }); + + it('should not store debug info when debug mode is disabled', async () => { + const regularClient = new Scope3Client({ + apiKey: 'test-key', + debug: false, + }); + + (Client as jest.MockedClass).mockImplementation(() => mockMcpClient); + ( + StreamableHTTPClientTransport as jest.MockedClass + ).mockImplementation(() => mockTransport); + + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { result: 'success' }, + content: [], + }); + + await regularClient['callTool']('test_tool', {}); + + expect(regularClient.lastDebugInfo).toBeUndefined(); + }); + }); + + describe('environment and URL configuration', () => { + it('should use production URL by default', () => { + const prodClient = new Scope3Client({ + apiKey: 'test-key', + }); + + expect(prodClient.getBaseUrl()).toBe('https://api.agentic.scope3.com'); + }); + + it('should use staging URL when environment is staging', () => { + const stagingClient = new Scope3Client({ + apiKey: 'test-key', + environment: 'staging', + }); + + expect(stagingClient.getBaseUrl()).toBe('https://api.agentic.staging.scope3.com'); + }); + + it('should use custom baseUrl when provided (overrides environment)', () => { + const customClient = new Scope3Client({ + apiKey: 'test-key', + environment: 'staging', + baseUrl: 'https://custom.api.com', + }); + + expect(customClient.getBaseUrl()).toBe('https://custom.api.com'); + }); + }); + + describe('request argument handling', () => { + it('should pass arguments as Record', async () => { + const args = { + stringArg: 'test', + numberArg: 123, + boolArg: true, + objectArg: { nested: 'value' }, + arrayArg: [1, 2, 3], + }; + + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { success: true }, + content: [], + }); + + await client['callTool']('test_tool', args); + + expect(mockMcpClient.callTool).toHaveBeenCalledWith({ + name: 'test_tool', + arguments: args, + }); + }); + + it('should handle empty arguments object', async () => { + mockMcpClient.callTool.mockResolvedValue({ + structuredContent: { success: true }, + content: [], + }); + + await client['callTool']('test_tool', {}); + + expect(mockMcpClient.callTool).toHaveBeenCalledWith({ + name: 'test_tool', + arguments: {}, + }); + }); + }); +}); diff --git a/src/__tests__/logger.test.ts b/src/__tests__/logger.test.ts new file mode 100644 index 0000000..6abfd89 --- /dev/null +++ b/src/__tests__/logger.test.ts @@ -0,0 +1,310 @@ +/** + * Tests for Logger utility + * + * Tests conditional logging, debug mode, structured output, and error formatting + */ + +import { Logger } from '../utils/logger'; + +describe('Logger', () => { + let logger: Logger; + let consoleErrorSpy: jest.SpyInstance; + let originalNodeEnv: string | undefined; + + beforeEach(() => { + // Create fresh logger instance + logger = new Logger(); + + // Spy on console.error (logger outputs to stderr) + consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(); + + // Save original NODE_ENV + originalNodeEnv = process.env.NODE_ENV; + }); + + afterEach(() => { + consoleErrorSpy.mockRestore(); + + // Restore NODE_ENV + if (originalNodeEnv !== undefined) { + process.env.NODE_ENV = originalNodeEnv; + } else { + delete process.env.NODE_ENV; + } + }); + + describe('debug mode control', () => { + it('should not log debug messages when debug is disabled', () => { + logger.setDebug(false); + logger.debug('Test message'); + + expect(consoleErrorSpy).not.toHaveBeenCalled(); + }); + + it('should log debug messages when debug is enabled', () => { + logger.setDebug(true); + logger.debug('Test message'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + + it('should not log info messages when debug is disabled', () => { + logger.setDebug(false); + logger.info('Test message'); + + expect(consoleErrorSpy).not.toHaveBeenCalled(); + }); + + it('should log info messages when debug is enabled', () => { + logger.setDebug(true); + logger.info('Test message'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + + it('should not log warn messages when debug is disabled', () => { + logger.setDebug(false); + logger.warn('Test message'); + + expect(consoleErrorSpy).not.toHaveBeenCalled(); + }); + + it('should log warn messages when debug is enabled', () => { + logger.setDebug(true); + logger.warn('Test message'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + + it('should always log error messages regardless of debug mode', () => { + logger.setDebug(false); + logger.error('Error message'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + }); + + describe('development mode output (human-readable)', () => { + beforeEach(() => { + process.env.NODE_ENV = 'development'; + logger = new Logger(); + logger.setDebug(true); + }); + + it('should format debug messages with timestamp and severity', () => { + logger.debug('Test debug message'); + + expect(consoleErrorSpy).toHaveBeenCalledTimes(1); + const call = consoleErrorSpy.mock.calls[0][0] as string; + expect(call).toMatch(/\[DEBUG\]/); + expect(call).toMatch(/Test debug message/); + expect(call).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/); // ISO timestamp + }); + + it('should include structured data in human-readable format', () => { + logger.info('Test with data', { userId: '123', action: 'login' }); + + expect(consoleErrorSpy).toHaveBeenCalledTimes(1); + const [message, data] = consoleErrorSpy.mock.calls[0]; + expect(message).toMatch(/\[INFO\]/); + expect(message).toMatch(/Test with data/); + expect(data).toContain('"userId": "123"'); + expect(data).toContain('"action": "login"'); + }); + + it('should format warnings with WARNING severity', () => { + logger.warn('Warning message'); + + const call = consoleErrorSpy.mock.calls[0][0] as string; + expect(call).toMatch(/\[WARNING\]/); + expect(call).toMatch(/Warning message/); + }); + + it('should format errors with ERROR severity', () => { + logger.error('Error message'); + + const call = consoleErrorSpy.mock.calls[0][0] as string; + expect(call).toMatch(/\[ERROR\]/); + expect(call).toMatch(/Error message/); + }); + }); + + describe('production mode output (structured JSON)', () => { + beforeEach(() => { + process.env.NODE_ENV = 'production'; + logger = new Logger(); + logger.setDebug(true); + }); + + it('should output structured JSON for debug messages', () => { + logger.debug('Test message', { key: 'value' }); + + expect(consoleErrorSpy).toHaveBeenCalledTimes(1); + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.message).toBe('Test message'); + expect(parsed.severity).toBe('DEBUG'); + expect(parsed.timestamp).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/); + expect(parsed.key).toBe('value'); + }); + + it('should output structured JSON for info messages', () => { + logger.info('Info message', { count: 42 }); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.message).toBe('Info message'); + expect(parsed.severity).toBe('INFO'); + expect(parsed.count).toBe(42); + }); + + it('should output structured JSON for warnings', () => { + logger.warn('Warning', { code: 'WARN_001' }); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.message).toBe('Warning'); + expect(parsed.severity).toBe('WARNING'); + expect(parsed.code).toBe('WARN_001'); + }); + + it('should output structured JSON for errors', () => { + logger.error('Error occurred'); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.message).toBe('Error occurred'); + expect(parsed.severity).toBe('ERROR'); + }); + }); + + describe('error object handling', () => { + beforeEach(() => { + logger.setDebug(true); + }); + + it('should extract Error properties into structured data', () => { + const error = new Error('Test error'); + error.name = 'TestError'; + + logger.error('Operation failed', error); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + + // Check if it's JSON (production) or includes error info (development) + if (output.startsWith('{')) { + const parsed = JSON.parse(output); + expect(parsed.error.message).toBe('Test error'); + expect(parsed.error.name).toBe('TestError'); + expect(parsed.error.stack).toBeDefined(); + } else { + const data = consoleErrorSpy.mock.calls[0][1] as string; + expect(data).toContain('Test error'); + } + }); + + it('should handle Error with additional data', () => { + const error = new Error('Database error'); + logger.error('Query failed', error, { query: 'SELECT * FROM users', duration: 500 }); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + + if (output.startsWith('{')) { + const parsed = JSON.parse(output); + expect(parsed.error.message).toBe('Database error'); + expect(parsed.query).toBe('SELECT * FROM users'); + expect(parsed.duration).toBe(500); + } + }); + + it('should handle non-Error objects', () => { + logger.error('Unexpected error', 'String error'); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + + if (output.startsWith('{')) { + const parsed = JSON.parse(output); + expect(parsed.error).toBe('String error'); + } + }); + + it('should handle null/undefined error parameter', () => { + logger.error('Error without object', undefined, { context: 'test' }); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + + if (output.startsWith('{')) { + const parsed = JSON.parse(output); + expect(parsed.context).toBe('test'); + expect(parsed.error).toBeUndefined(); + } + }); + }); + + describe('singleton behavior', () => { + it('should return same instance from getInstance', () => { + const instance1 = Logger.getInstance(); + const instance2 = Logger.getInstance(); + + expect(instance1).toBe(instance2); + }); + + it('should maintain debug state across getInstance calls', () => { + const instance1 = Logger.getInstance(); + instance1.setDebug(true); + + const instance2 = Logger.getInstance(); + instance2.debug('Test message'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + }); + + describe('data sanitization and edge cases', () => { + beforeEach(() => { + process.env.NODE_ENV = 'production'; + logger = new Logger(); + logger.setDebug(true); + }); + + it('should throw on circular references (expected JSON.stringify behavior)', () => { + const circular: Record = { key: 'value' }; + circular.self = circular; + + // JSON.stringify throws on circular references - this is expected behavior + expect(() => { + logger.info('Circular data', circular); + }).toThrow(/circular/i); + }); + + it('should handle undefined and null values in data', () => { + logger.info('Null test', { nullValue: null, undefinedValue: undefined, zero: 0 }); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.nullValue).toBeNull(); + expect(parsed.zero).toBe(0); + }); + + it('should handle empty data object', () => { + logger.info('Empty data', {}); + + const output = consoleErrorSpy.mock.calls[0][0] as string; + const parsed = JSON.parse(output); + + expect(parsed.message).toBe('Empty data'); + expect(parsed.severity).toBe('INFO'); + }); + + it('should handle messages with special characters', () => { + logger.info('Message with "quotes" and \n newlines'); + + expect(consoleErrorSpy).toHaveBeenCalled(); + }); + }); +}); diff --git a/src/cli.ts b/src/cli.ts index c7127d4..75fefdd 100644 --- a/src/cli.ts +++ b/src/cli.ts @@ -17,6 +17,7 @@ const CACHE_TTL = 24 * 60 * 60 * 1000; // 24 hours interface CliConfig { apiKey?: string; + environment?: 'production' | 'staging'; baseUrl?: string; } @@ -44,6 +45,7 @@ function loadConfig(): CliConfig { try { const fileConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf-8')); config.apiKey = fileConfig.apiKey; + config.environment = fileConfig.environment; config.baseUrl = fileConfig.baseUrl; } catch (error) { logger.warn('Failed to parse config file', { error }); @@ -55,6 +57,19 @@ function loadConfig(): CliConfig { if (process.env.SCOPE3_API_KEY) { config.apiKey = process.env.SCOPE3_API_KEY; } + if (process.env.SCOPE3_ENVIRONMENT) { + const env = process.env.SCOPE3_ENVIRONMENT.toLowerCase(); + if (env === 'production' || env === 'staging') { + config.environment = env; + } else { + console.warn( + chalk.yellow( + `Warning: Invalid SCOPE3_ENVIRONMENT value "${process.env.SCOPE3_ENVIRONMENT}". ` + + 'Valid values: production, staging. Using default (production).' + ) + ); + } + } if (process.env.SCOPE3_BASE_URL) { config.baseUrl = process.env.SCOPE3_BASE_URL; } @@ -65,10 +80,23 @@ function loadConfig(): CliConfig { // Save config to file function saveConfig(config: CliConfig): void { if (!fs.existsSync(CONFIG_DIR)) { - fs.mkdirSync(CONFIG_DIR, { recursive: true }); + fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 }); // Owner-only directory + } + + // Write config with restricted permissions (owner read/write only) + fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 }); + + console.log(chalk.green(`āœ“ Configuration saved to ${CONFIG_FILE}`)); + + // Warn about plain-text storage if API key is being saved + if (config.apiKey) { + console.log(chalk.yellow('\nāš  Security Notice:')); + console.log( + chalk.gray(' API key stored in plain text with file permissions 0600 (owner only)') + ); + console.log(chalk.gray(' For better security, consider using environment variables:')); + console.log(chalk.gray(' export SCOPE3_API_KEY=your_key')); } - fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2)); - console.log(chalk.green(`Configuration saved to ${CONFIG_FILE}`)); } // Load tools cache @@ -135,9 +163,14 @@ async function fetchAvailableTools( // Try to use stale cache as fallback if (fs.existsSync(TOOLS_CACHE_FILE)) { - console.log(chalk.yellow('Using cached tools (may be outdated)')); - const cache: ToolsCache = JSON.parse(fs.readFileSync(TOOLS_CACHE_FILE, 'utf-8')); - return cache.tools; + try { + console.log(chalk.yellow('Using cached tools (may be outdated)')); + const cache: ToolsCache = JSON.parse(fs.readFileSync(TOOLS_CACHE_FILE, 'utf-8')); + return cache.tools; + } catch (cacheError) { + logger.warn('Failed to read stale cache', { error: cacheError }); + // Fall through to throw original error since we can't recover + } } throw error; @@ -151,7 +184,6 @@ function formatOutput(data: unknown, format: string): void { return; } - // Table format if (!data) { console.log(chalk.yellow('No data to display')); return; @@ -159,7 +191,77 @@ function formatOutput(data: unknown, format: string): void { // Handle ToolResponse wrapper const dataObj = data as Record; - const actualData = dataObj.data || data; + let actualData: unknown = dataObj.data || data; + + // If the response has an array field, extract it (common pattern for list responses) + // Check for: items, brandAgents, campaigns, agents, etc. + if (typeof actualData === 'object' && actualData && !Array.isArray(actualData)) { + const dataRecord = actualData as Record; + // Find the first array field (including empty arrays) + const arrayField = Object.keys(dataRecord).find((key) => Array.isArray(dataRecord[key])); + if (arrayField) { + actualData = dataRecord[arrayField]; + } + } + + // If the response is just a single object with only a "message" field, + // display the message directly without table formatting + if ( + typeof actualData === 'object' && + actualData && + !Array.isArray(actualData) && + Object.keys(actualData).length === 1 && + 'message' in actualData + ) { + console.log(String((actualData as Record).message)); + return; + } + + // Helper function to intelligently display or summarize values + function summarizeValue(value: unknown): string { + if (value === null || value === undefined) { + return chalk.gray('(empty)'); + } + + // Handle arrays + if (Array.isArray(value)) { + if (value.length === 0) return chalk.gray('(empty array)'); + + // Small arrays of primitives: show inline + if (value.length <= 3 && value.every((item) => typeof item !== 'object' || item === null)) { + const str = JSON.stringify(value); + if (str.length <= 50) return str; + } + + // Large or complex arrays: summarize + return chalk.gray(`(${value.length} item${value.length === 1 ? '' : 's'})`); + } + + // Handle objects + if (typeof value === 'object') { + const obj = value as Record; + const keys = Object.keys(obj); + if (keys.length === 0) return chalk.gray('(empty object)'); + + // Simple objects with 1-2 primitive fields: show inline + if (keys.length <= 2) { + const allPrimitive = keys.every((k) => { + const v = obj[k]; + return typeof v !== 'object' || v === null; + }); + + if (allPrimitive) { + const str = JSON.stringify(value); + if (str.length <= 50) return str; + } + } + + // Complex objects: summarize + return chalk.gray(`(${keys.length} field${keys.length === 1 ? '' : 's'})`); + } + + return String(value); + } if (Array.isArray(actualData)) { if (actualData.length === 0) { @@ -167,42 +269,79 @@ function formatOutput(data: unknown, format: string): void { return; } - // Create table from array - const keys = Object.keys(actualData[0]); - const table = new Table({ - head: keys.map((k) => chalk.cyan(k)), - wordWrap: true, - wrapOnWordBoundary: false, - }); + if (format === 'list') { + // List format: show each item with summaries for arrays/objects + actualData.forEach((item, index) => { + console.log(chalk.cyan(`\n${index + 1}.`)); + Object.entries(item).forEach(([key, value]) => { + const displayValue = summarizeValue(value); + console.log(` ${chalk.yellow(key)}: ${displayValue}`); + }); + }); + console.log(); // Extra line at end + } else { + // Table format: columnar view with summaries + const keys = Object.keys(actualData[0]); + const table = new Table({ + head: keys.map((k) => chalk.cyan(k)), + wordWrap: true, + wrapOnWordBoundary: false, + }); - actualData.forEach((item) => { - table.push( - keys.map((k) => { - const value = item[k]; - if (value === null || value === undefined) return ''; - if (typeof value === 'object') return JSON.stringify(value); - return String(value); - }) - ); - }); + actualData.forEach((item) => { + table.push( + keys.map((k) => { + const value = item[k]; + if (value === null || value === undefined) return ''; + + // Use intelligent summarization for table cells too + if (Array.isArray(value)) { + if (value.length === 0) return ''; + // Small primitive arrays: show inline + if ( + value.length <= 3 && + value.every((item) => typeof item !== 'object' || item === null) + ) { + const str = JSON.stringify(value); + if (str.length <= 50) return str; + } + return `${value.length} item${value.length === 1 ? '' : 's'}`; + } - console.log(table.toString()); - } else if (typeof actualData === 'object') { - // Create table for single object + if (typeof value === 'object') { + const obj = value as Record; + const objKeys = Object.keys(obj); + if (objKeys.length === 0) return ''; + // Simple objects: show inline + if (objKeys.length <= 2) { + const allPrimitive = objKeys.every((k) => { + const v = obj[k]; + return typeof v !== 'object' || v === null; + }); + if (allPrimitive) { + const str = JSON.stringify(value); + if (str.length <= 50) return str; + } + } + return `${objKeys.length} field${objKeys.length === 1 ? '' : 's'}`; + } + + return String(value); + }) + ); + }); + + console.log(table.toString()); + } + } else if (typeof actualData === 'object' && actualData) { + // Create table for single object with summaries const table = new Table({ wordWrap: true, wrapOnWordBoundary: false, }); - Object.entries(actualData).forEach(([key, value]) => { - let displayValue: string; - if (value === null || value === undefined) { - displayValue = ''; - } else if (typeof value === 'object') { - displayValue = JSON.stringify(value, null, 2); - } else { - displayValue = String(value); - } + Object.entries(actualData as Record).forEach(([key, value]) => { + const displayValue = summarizeValue(value); table.push({ [chalk.cyan(key)]: displayValue }); }); @@ -211,17 +350,19 @@ function formatOutput(data: unknown, format: string): void { console.log(actualData); } - // Show success/message if present + // Show success indicator if present (but don't duplicate message display) if (dataObj.success !== undefined) { console.log(dataObj.success ? chalk.green('āœ“ Success') : chalk.red('āœ— Failed')); } - if (dataObj.message) { - console.log(chalk.blue('Message:'), dataObj.message); - } } // Create client instance -function createClient(apiKey?: string, baseUrl?: string): Scope3AgenticClient { +function createClient( + apiKey?: string, + environment?: 'production' | 'staging', + baseUrl?: string, + debug?: boolean +): Scope3AgenticClient { const config = loadConfig(); const finalApiKey = apiKey || config.apiKey; @@ -236,7 +377,9 @@ function createClient(apiKey?: string, baseUrl?: string): Scope3AgenticClient { return new Scope3AgenticClient({ apiKey: finalApiKey, + environment: environment || config.environment, baseUrl: baseUrl || config.baseUrl, + debug: debug || false, }); } @@ -299,8 +442,14 @@ program .description('CLI tool for Scope3 Agentic API (dynamically generated from MCP server)') .version('1.0.0') .option('--api-key ', 'API key for authentication') - .option('--base-url ', 'Base URL for API (default: production)') - .option('--format ', 'Output format: json or table', 'table') + .option( + '--environment ', + 'Environment: production or staging (default: production)', + 'production' + ) + .option('--base-url ', 'Base URL for API (overrides environment)') + .option('--format ', 'Output format: json, table, or list (default: table)', 'table') + .option('--debug', 'Enable debug mode (show request/response details)') .option('--no-cache', 'Skip cache and fetch fresh tools list'); // Config command @@ -309,17 +458,24 @@ const configCmd = program.command('config').description('Manage CLI configuratio configCmd .command('set') .description('Set configuration value') - .argument('', 'Configuration key (apiKey or baseUrl)') + .argument('', 'Configuration key (apiKey, environment, or baseUrl)') .argument('', 'Configuration value') .action((key: string, value: string) => { const config = loadConfig(); if (key === 'apiKey') { config.apiKey = value; + } else if (key === 'environment') { + if (value !== 'production' && value !== 'staging') { + console.error(chalk.red(`Error: Invalid environment: ${value}`)); + console.log('Valid values: production, staging'); + process.exit(1); + } + config.environment = value as 'production' | 'staging'; } else if (key === 'baseUrl') { config.baseUrl = value; } else { console.error(chalk.red(`Error: Unknown config key: ${key}`)); - console.log('Valid keys: apiKey, baseUrl'); + console.log('Valid keys: apiKey, environment, baseUrl'); process.exit(1); } saveConfig(config); @@ -332,7 +488,12 @@ configCmd .action((key?: string) => { const config = loadConfig(); if (!key) { - console.log(JSON.stringify(config, null, 2)); + // Redact sensitive values when displaying full config + const safeConfig = { ...config }; + if (safeConfig.apiKey) { + safeConfig.apiKey = safeConfig.apiKey.substring(0, 8) + '...[REDACTED]'; + } + console.log(JSON.stringify(safeConfig, null, 2)); } else if (key in config) { console.log(config[key as keyof CliConfig]); } else { @@ -360,7 +521,12 @@ program .option('--refresh', 'Refresh tools cache') .action(async (options) => { const globalOpts = program.opts(); - const client = createClient(globalOpts.apiKey, globalOpts.baseUrl); + const client = createClient( + globalOpts.apiKey, + globalOpts.environment, + globalOpts.baseUrl, + globalOpts.debug + ); try { const useCache = !options.refresh && globalOpts.cache !== false; @@ -419,7 +585,12 @@ async function setupDynamicCommands() { } try { - const client = createClient(globalOpts.apiKey, globalOpts.baseUrl); + const client = createClient( + globalOpts.apiKey, + globalOpts.environment, + globalOpts.baseUrl, + globalOpts.debug + ); const useCache = globalOpts.cache !== false; const tools = await fetchAvailableTools(client, useCache); await client.disconnect(); @@ -466,7 +637,12 @@ async function setupDynamicCommands() { // Action handler cmd.action(async (options) => { - const client = createClient(globalOpts.apiKey, globalOpts.baseUrl); + const client = createClient( + globalOpts.apiKey, + globalOpts.environment, + globalOpts.baseUrl, + globalOpts.debug + ); try { await client.connect(); diff --git a/src/client.ts b/src/client.ts index 359156c..47765ec 100644 --- a/src/client.ts +++ b/src/client.ts @@ -1,17 +1,36 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'; -import { ClientConfig, Environment } from './types'; +import { ClientConfig, Environment, DebugInfo } from './types'; +import { logger } from './utils/logger'; export class Scope3Client { protected readonly mcpClient: Client; protected readonly apiKey: string; + protected readonly baseUrl: string; + protected readonly debug: boolean; private transport?: StreamableHTTPClientTransport; private connected = false; + public lastDebugInfo?: DebugInfo; constructor(config: ClientConfig) { this.apiKey = config.apiKey; + this.debug = config.debug || false; - const baseURL = config.baseUrl || this.getDefaultBaseUrl('production'); + // Enable logger debug mode if debug is enabled + if (this.debug) { + logger.setDebug(true); + } + + // Priority: explicit baseUrl > environment > default to production + const baseURL = config.baseUrl || this.getDefaultBaseUrl(config.environment || 'production'); + this.baseUrl = baseURL; + + logger.info('Initializing Scope3 client', { + baseUrl: baseURL, + environment: config.environment || 'production', + isCustomUrl: !!config.baseUrl, + debug: this.debug, + }); this.mcpClient = new Client( { @@ -61,29 +80,127 @@ export class Scope3Client { this.connected = false; } + private sanitizeForLogging(obj: unknown): unknown { + if (!obj || typeof obj !== 'object') { + return obj; + } + + const sensitiveKeys = [ + 'apiKey', + 'api_key', + 'token', + 'password', + 'secret', + 'auth', + 'authorization', + 'credentials', + ]; + + if (Array.isArray(obj)) { + return obj.map((item) => this.sanitizeForLogging(item)); + } + + const sanitized: Record = {}; + for (const [key, value] of Object.entries(obj)) { + if (sensitiveKeys.some((k) => key.toLowerCase().includes(k))) { + sanitized[key] = '[REDACTED]'; + } else if (typeof value === 'object' && value !== null) { + sanitized[key] = this.sanitizeForLogging(value); + } else { + sanitized[key] = value; + } + } + return sanitized; + } + protected async callTool( toolName: string, args: TRequest ): Promise { + const startTime = Date.now(); + if (!this.connected) { await this.connect(); } - const result = await this.mcpClient.callTool({ + const request = { name: toolName, arguments: args as Record, - }); + }; - // MCP tools return content array, extract the response from text content + if (this.debug) { + const sanitizedRequest = this.sanitizeForLogging(request); + logger.info('MCP Request', { request: sanitizedRequest }); + } + + const result = await this.mcpClient.callTool(request); + const durationMs = Date.now() - startTime; + + if (this.debug) { + const sanitizedResult = this.sanitizeForLogging(result); + logger.info('MCP Response', { + toolName, + duration: `${durationMs}ms`, + result: sanitizedResult, + }); + } + + // MCP tools can return structured content or text content + // Priority: structuredContent > parsed JSON from text > raw text + + // Check for structuredContent first (preferred) + if (result.structuredContent) { + if (this.debug) { + this.lastDebugInfo = { + toolName, + request: args as Record, + response: result.structuredContent, + durationMs, + }; + } + return result.structuredContent as TResponse; + } + + // Fall back to text content if (result.content && Array.isArray(result.content) && result.content.length > 0) { const content = result.content[0]; if (content.type === 'text') { + const rawResponse = content.text; + // Try to parse as JSON first, if that fails return the text as-is try { - return JSON.parse(content.text) as TResponse; + const parsed = JSON.parse(rawResponse); + + // Store debug info if enabled + if (this.debug) { + this.lastDebugInfo = { + toolName, + request: args as Record, + response: parsed, + rawResponse, + durationMs, + }; + } + + return parsed as TResponse; } catch { // If not JSON, return the text wrapped in an object - return { message: content.text } as TResponse; + if (this.debug) { + logger.warn('MCP tool returned non-JSON text (no structuredContent)', { + toolName, + textLength: rawResponse.length, + }); + + this.lastDebugInfo = { + toolName, + request: args as Record, + response: { message: rawResponse }, + rawResponse, + durationMs, + }; + } + + return { message: rawResponse } as TResponse; } } } @@ -94,4 +211,8 @@ export class Scope3Client { protected getClient(): Client { return this.mcpClient; } + + public getBaseUrl(): string { + return this.baseUrl; + } } diff --git a/src/types/index.ts b/src/types/index.ts index b275fad..b761740 100644 --- a/src/types/index.ts +++ b/src/types/index.ts @@ -1,7 +1,17 @@ export interface ClientConfig { apiKey: string; + environment?: Environment; baseUrl?: string; timeout?: number; + debug?: boolean; +} + +export interface DebugInfo { + toolName: string; + request: Record; + response: unknown; + rawResponse?: string; + durationMs?: number; } export interface ToolResponse { diff --git a/src/utils/logger.ts b/src/utils/logger.ts index 74d8346..1825378 100644 --- a/src/utils/logger.ts +++ b/src/utils/logger.ts @@ -9,6 +9,7 @@ type LogSeverity = 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR'; export class Logger { private static instance: Logger; private readonly isDevelopment: boolean; + private debugEnabled: boolean = false; constructor() { this.isDevelopment = process.env.NODE_ENV === 'development'; @@ -21,16 +22,26 @@ export class Logger { return Logger.instance; } + setDebug(enabled: boolean): void { + this.debugEnabled = enabled; + } + debug(message: string, data?: Record): void { - this.log('DEBUG', message, data); + if (this.debugEnabled) { + this.log('DEBUG', message, data); + } } info(message: string, data?: Record): void { - this.log('INFO', message, data); + if (this.debugEnabled) { + this.log('INFO', message, data); + } } warn(message: string, data?: Record): void { - this.log('WARNING', message, data); + if (this.debugEnabled) { + this.log('WARNING', message, data); + } } error(message: string, error?: unknown, data?: Record): void { @@ -46,6 +57,7 @@ export class Logger { errorData.error = String(error); } + // Errors always get logged this.log('ERROR', message, errorData); }