@aura-labs-ai/scout 0.2.0

package/src/tests/mcp-client.test.js

@@ -0,0 +1,224 @@
+/**
+ * MCP Client Tests
+ *
+ * Tests for Model Context Protocol client implementation.
+ *
+ * Run:
+ *   node --test src/tests/mcp-client.test.js
+ */
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { MCPClient } from '../mcp/client.js';
+
+// =============================================================================
+// Client Initialization Tests
+// =============================================================================
+
+describe('MCP Client Initialization', () => {
+  test('creates client with default config', () => {
+    const client = new MCPClient();
+
+    assert.ok(client);
+    assert.strictEqual(client.isConnected, false);
+  });
+
+  test('creates client with custom config', () => {
+    const client = new MCPClient({
+      clientInfo: {
+        name: 'test-client',
+        version: '2.0.0',
+      },
+    });
+
+    assert.ok(client);
+    assert.strictEqual(client.clientInfo.name, 'test-client');
+    assert.strictEqual(client.clientInfo.version, '2.0.0');
+  });
+
+  test('uses default client info when not provided', () => {
+    const client = new MCPClient({});
+
+    assert.strictEqual(client.clientInfo.name, 'aura-scout');
+    assert.strictEqual(client.clientInfo.version, '1.0.0');
+  });
+});
+
+// =============================================================================
+// Connection State Tests
+// =============================================================================
+
+describe('MCP Client Connection State', () => {
+  test('starts disconnected', () => {
+    const client = new MCPClient();
+    assert.strictEqual(client.isConnected, false);
+  });
+
+  test('returns empty tools list when not connected', async () => {
+    const client = new MCPClient();
+    const tools = await client.listAllTools();
+
+    assert.deepStrictEqual(tools, []);
+  });
+
+  test('returns empty context when not connected', async () => {
+    const client = new MCPClient();
+    const context = await client.aggregateContext({ query: 'test' });
+
+    assert.deepStrictEqual(context.tools, []);
+    assert.deepStrictEqual(context.resources, []);
+  });
+});
+
+// =============================================================================
+// Event Emitter Tests
+// =============================================================================
+
+describe('MCP Client Events', () => {
+  test('emits events as EventEmitter', () => {
+    const client = new MCPClient();
+    let eventReceived = false;
+
+    client.on('test-event', () => {
+      eventReceived = true;
+    });
+
+    client.emit('test-event');
+    assert.strictEqual(eventReceived, true);
+  });
+
+  test('supports multiple event listeners', () => {
+    const client = new MCPClient();
+    const calls = [];
+
+    client.on('multi-event', () => calls.push(1));
+    client.on('multi-event', () => calls.push(2));
+
+    client.emit('multi-event');
+    assert.deepStrictEqual(calls, [1, 2]);
+  });
+});
+
+// =============================================================================
+// Tool Listing Tests
+// =============================================================================
+
+describe('MCP Client Tool Listing', () => {
+  test('listAllTools returns array', async () => {
+    const client = new MCPClient();
+    const tools = await client.listAllTools();
+
+    assert.ok(Array.isArray(tools));
+  });
+
+  test('listAllTools returns empty array with no servers', async () => {
+    const client = new MCPClient();
+    const tools = await client.listAllTools();
+
+    assert.strictEqual(tools.length, 0);
+  });
+});
+
+// =============================================================================
+// Context Aggregation Tests
+// =============================================================================
+
+describe('MCP Client Context Aggregation', () => {
+  test('aggregateContext returns context structure', async () => {
+    const client = new MCPClient();
+    const context = await client.aggregateContext({});
+
+    assert.ok('tools' in context);
+    assert.ok('resources' in context);
+    assert.ok('data' in context);
+  });
+
+  test('aggregateContext accepts query parameter', async () => {
+    const client = new MCPClient();
+    const context = await client.aggregateContext({
+      query: 'test query',
+      includeResources: true,
+    });
+
+    // Should return empty context (no servers connected)
+    assert.deepStrictEqual(context.tools, []);
+    assert.deepStrictEqual(context.resources, []);
+  });
+});
+
+// =============================================================================
+// Tool Call Tests (Mock/Offline)
+// =============================================================================
+
+describe('MCP Client Tool Calls', () => {
+  test('callTool throws when server not found', async () => {
+    const client = new MCPClient();
+
+    await assert.rejects(
+      async () => {
+        await client.callTool('unknown-server', 'test-tool', {});
+      },
+      { message: /not connected/i }
+    );
+  });
+});
+
+// =============================================================================
+// Server Management Tests
+// =============================================================================
+
+describe('MCP Client Server Management', () => {
+  test('disconnect returns immediately when not connected', async () => {
+    const client = new MCPClient();
+
+    // Should not throw
+    await client.disconnect('some-server');
+    assert.strictEqual(client.isConnected, false);
+  });
+
+  test('disconnectAll works with no servers', async () => {
+    const client = new MCPClient();
+
+    // Should not throw
+    await client.disconnectAll();
+    assert.strictEqual(client.isConnected, false);
+  });
+});
+
+// =============================================================================
+// Protocol Version Tests
+// =============================================================================
+
+describe('MCP Client Protocol', () => {
+  test('uses correct protocol version', () => {
+    const client = new MCPClient();
+    assert.strictEqual(client.protocolVersion, '2024-11-05');
+  });
+
+  test('supports required capabilities', () => {
+    const client = new MCPClient();
+    const capabilities = client.capabilities;
+
+    assert.ok(capabilities.tools);
+    assert.ok(capabilities.resources);
+    assert.ok(capabilities.prompts);
+    assert.ok(capabilities.sampling);
+  });
+});
+
+// =============================================================================
+// Error Handling Tests
+// =============================================================================
+
+describe('MCP Client Error Handling', () => {
+  test('handles connection errors gracefully', async () => {
+    const client = new MCPClient();
+
+    // Attempting to connect to invalid URL should reject
+    await assert.rejects(
+      async () => {
+        await client.connect({ uri: 'https://invalid.example.com/mcp', name: 'invalid' });
+      }
+    );
+  });
+});

package/src/tests/ping.test.js

@@ -0,0 +1,282 @@
+/**
+ * Scout SDK ping() unit tests
+ *
+ * Tests the read-only healthcheck method that wraps Core's GET /health/ready.
+ * Verifies: response mapping (ok/degraded/error), no auth headers,
+ * activity event recording, timeout handling, and independence from ready().
+ */
+
+import { describe, it, beforeEach, afterEach, mock } from 'node:test';
+import assert from 'node:assert/strict';
+import { createScout } from '../index.js';
+
+// --- Test helpers ---
+
+/**
+ * Create a mock fetch that returns the given response
+ */
+function mockFetch(status, body, { delay = 0, shouldThrow = false, throwError = null } = {}) {
+  return mock.fn(async (url, opts) => {
+    if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+    if (shouldThrow) throw throwError || new TypeError('fetch failed');
+    return {
+      ok: status >= 200 && status < 300,
+      status,
+      json: async () => body,
+    };
+  });
+}
+
+const HEALTHY_RESPONSE = {
+  status: 'ready',
+  checks: {
+    database: {
+      status: 'healthy',
+      latency_ms: 5,
+      pool: { total: 10, idle: 8, waiting: 0 },
+    },
+    redis: { status: 'unconfigured' },
+  },
+  timestamp: '2026-03-11T14:30:00.000Z',
+};
+
+const DEGRADED_RESPONSE = {
+  status: 'not_ready',
+  checks: {
+    database: {
+      status: 'unhealthy',
+      latency_ms: 100,
+      error: 'Database check failed',
+    },
+    redis: { status: 'healthy', latency_ms: 3 },
+  },
+  timestamp: '2026-03-11T14:30:00.000Z',
+};
+
+describe('Scout ping()', () => {
+  let originalFetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  describe('Core healthy (200)', () => {
+    it('returns status ok with core checks', async () => {
+      globalThis.fetch = mockFetch(200, HEALTHY_RESPONSE);
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'ok');
+      assert.equal(result.core.status, 'ready');
+      assert.equal(result.core.checks.database.status, 'healthy');
+      assert.equal(result.core.checks.database.pool.total, 10);
+      assert.equal(result.core.checks.redis.status, 'unconfigured');
+      assert.equal(typeof result.latency_ms, 'number');
+      assert.ok(result.latency_ms >= 0);
+      assert.equal(typeof result.timestamp, 'string');
+      // Verify ISO 8601 format
+      assert.ok(!isNaN(Date.parse(result.timestamp)));
+    });
+
+    it('records PING_SUCCESS activity event', async () => {
+      globalThis.fetch = mockFetch(200, HEALTHY_RESPONSE);
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      await scout.ping();
+
+      const events = scout.activity.getEvents({ type: 'ping.success' });
+      assert.equal(events.length, 1);
+      assert.equal(events[0].metadata.coreStatus, 'ready');
+      assert.equal(typeof events[0].metadata.latency_ms, 'number');
+    });
+
+    it('increments ping summary counters', async () => {
+      globalThis.fetch = mockFetch(200, HEALTHY_RESPONSE);
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      await scout.ping();
+      await scout.ping();
+
+      const summary = scout.activity.getSummary();
+      assert.equal(summary.ping.total, 2);
+      assert.equal(summary.ping.successful, 2);
+      assert.equal(summary.ping.failed, 0);
+    });
+  });
+
+  describe('Core degraded (503)', () => {
+    it('returns status degraded with unhealthy checks', async () => {
+      globalThis.fetch = mockFetch(503, DEGRADED_RESPONSE);
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'degraded');
+      assert.equal(result.core.status, 'not_ready');
+      assert.equal(result.core.checks.database.status, 'unhealthy');
+      assert.equal(result.core.checks.database.error, 'Database check failed');
+    });
+
+    it('records PING_SUCCESS event (Core responded, just unhealthy)', async () => {
+      globalThis.fetch = mockFetch(503, DEGRADED_RESPONSE);
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      await scout.ping();
+
+      const events = scout.activity.getEvents({ type: 'ping.success' });
+      assert.equal(events.length, 1);
+      assert.equal(events[0].metadata.coreStatus, 'not_ready');
+    });
+  });
+
+  describe('Core unreachable', () => {
+    it('returns status error with CORE_UNREACHABLE code', async () => {
+      globalThis.fetch = mockFetch(0, null, {
+        shouldThrow: true,
+        throwError: new TypeError('fetch failed'),
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:9999' });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'error');
+      assert.equal(result.code, 'CORE_UNREACHABLE');
+      assert.ok(result.message.includes('http://localhost:9999'));
+      assert.equal(typeof result.latency_ms, 'number');
+    });
+
+    it('records PING_FAILED activity event', async () => {
+      globalThis.fetch = mockFetch(0, null, {
+        shouldThrow: true,
+        throwError: new TypeError('fetch failed'),
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:9999' });
+
+      await scout.ping();
+
+      const events = scout.activity.getEvents({ type: 'ping.failed' });
+      assert.equal(events.length, 1);
+      assert.equal(events[0].metadata.code, 'CORE_UNREACHABLE');
+      assert.equal(typeof events[0].metadata.error, 'string');
+    });
+
+    it('increments failed ping counter', async () => {
+      globalThis.fetch = mockFetch(0, null, { shouldThrow: true });
+      const scout = createScout({ coreUrl: 'http://localhost:9999' });
+
+      await scout.ping();
+
+      const summary = scout.activity.getSummary();
+      assert.equal(summary.ping.total, 1);
+      assert.equal(summary.ping.successful, 0);
+      assert.equal(summary.ping.failed, 1);
+    });
+  });
+
+  describe('Timeout', () => {
+    it('returns status error with CORE_TIMEOUT code on AbortError', async () => {
+      const abortError = new DOMException('The operation was aborted', 'AbortError');
+      globalThis.fetch = mockFetch(0, null, {
+        shouldThrow: true,
+        throwError: abortError,
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:3000', timeout: 100 });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'error');
+      assert.equal(result.code, 'CORE_TIMEOUT');
+      assert.ok(result.message.includes('http://localhost:3000'));
+    });
+
+    it('returns CORE_TIMEOUT on TimeoutError', async () => {
+      const timeoutError = new DOMException('signal timed out', 'TimeoutError');
+      globalThis.fetch = mockFetch(0, null, {
+        shouldThrow: true,
+        throwError: timeoutError,
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:3000', timeout: 100 });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'error');
+      assert.equal(result.code, 'CORE_TIMEOUT');
+    });
+  });
+
+  describe('No prior initialisation', () => {
+    it('works without calling ready() first', async () => {
+      globalThis.fetch = mockFetch(200, HEALTHY_RESPONSE);
+      // Create scout but do NOT call ready()
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      const result = await scout.ping();
+
+      assert.equal(result.status, 'ok');
+      assert.equal(result.core.status, 'ready');
+    });
+  });
+
+  describe('No auth headers', () => {
+    it('does not send authentication headers', async () => {
+      let capturedHeaders = {};
+      globalThis.fetch = mock.fn(async (url, opts) => {
+        capturedHeaders = opts.headers || {};
+        return {
+          ok: true,
+          status: 200,
+          json: async () => HEALTHY_RESPONSE,
+        };
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      await scout.ping();
+
+      // Must NOT have auth headers
+      assert.equal(capturedHeaders['X-Agent-Id'], undefined);
+      assert.equal(capturedHeaders['X-Agent-Signature'], undefined);
+      assert.equal(capturedHeaders['X-Agent-Timestamp'], undefined);
+      assert.equal(capturedHeaders['Authorization'], undefined);
+
+      // MUST have correlation and SDK headers
+      assert.ok(capturedHeaders['X-Request-ID']);
+      assert.ok(capturedHeaders['X-Scout-SDK']);
+    });
+
+    it('calls the correct URL (coreUrl + /health/ready)', async () => {
+      let capturedUrl;
+      globalThis.fetch = mock.fn(async (url, opts) => {
+        capturedUrl = url;
+        return { ok: true, status: 200, json: async () => HEALTHY_RESPONSE };
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      await scout.ping();
+
+      assert.equal(capturedUrl, 'http://localhost:3000/health/ready');
+    });
+  });
+
+  describe('Concurrent calls', () => {
+    it('two concurrent ping() calls resolve independently', async () => {
+      let callCount = 0;
+      globalThis.fetch = mock.fn(async () => {
+        callCount++;
+        return { ok: true, status: 200, json: async () => HEALTHY_RESPONSE };
+      });
+      const scout = createScout({ coreUrl: 'http://localhost:3000' });
+
+      const [r1, r2] = await Promise.all([scout.ping(), scout.ping()]);
+
+      assert.equal(r1.status, 'ok');
+      assert.equal(r2.status, 'ok');
+      // Both should make their own fetch call (no deduplication)
+      assert.equal(callCount, 2);
+    });
+  });
+});

package/src/tests/run-protocol-tests.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+/**
+ * Protocol Test Runner
+ *
+ * Runs all protocol implementation tests:
+ * - MCP Client
+ * - AP2 Mandates
+ * - Visa TAP
+ *
+ * Usage:
+ *   node src/tests/run-protocol-tests.js
+ *
+ * Or with Node's test runner directly:
+ *   node --test src/tests/mcp-client.test.js src/tests/ap2-mandates.test.js src/tests/visa-tap.test.js
+ */
+
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const testFiles = [
+  'mcp-client.test.js',
+  'ap2-mandates.test.js',
+  'visa-tap.test.js',
+];
+
+console.log('\n' + '═'.repeat(70));
+console.log('  AURA Scout SDK - Protocol Tests');
+console.log('═'.repeat(70) + '\n');
+
+console.log('Running tests for:');
+console.log('  • MCP Client (Model Context Protocol)');
+console.log('  • AP2 Mandates (Agent Payments Protocol)');
+console.log('  • Visa TAP (Trusted Agent Protocol)');
+console.log('');
+
+const testPaths = testFiles.map(f => join(__dirname, f));
+
+const child = spawn('node', ['--test', ...testPaths], {
+  stdio: 'inherit',
+  cwd: join(__dirname, '../..'),
+});
+
+child.on('exit', (code) => {
+  console.log('\n' + '═'.repeat(70));
+  if (code === 0) {
+    console.log('  ✅ All protocol tests passed!');
+  } else {
+    console.log('  ❌ Some tests failed');
+  }
+  console.log('═'.repeat(70) + '\n');
+  process.exit(code);
+});