signalwire-agents 0.1.0

package/tests/AgentServer.test.ts

@@ -0,0 +1,102 @@
+import { describe, it, expect } from 'vitest';
+import { AgentServer } from '../src/AgentServer.js';
+import { AgentBase } from '../src/AgentBase.js';
+
+describe('AgentServer', () => {
+  it('registers agents', () => {
+    const server = new AgentServer();
+    const agent1 = new AgentBase({ name: 'support', route: '/support' });
+    const agent2 = new AgentBase({ name: 'sales', route: '/sales' });
+
+    server.register(agent1, '/support');
+    server.register(agent2, '/sales');
+
+    expect(server.getAgents().size).toBe(2);
+    expect(server.getAgent('/support')?.name).toBe('support');
+    expect(server.getAgent('/sales')?.name).toBe('sales');
+  });
+
+  it('throws on duplicate route', () => {
+    const server = new AgentServer();
+    const agent1 = new AgentBase({ name: 'a1', route: '/test' });
+    const agent2 = new AgentBase({ name: 'a2', route: '/test' });
+
+    server.register(agent1, '/test');
+    expect(() => server.register(agent2, '/test')).toThrow("Route '/test' is already in use");
+  });
+
+  it('unregisters agents', () => {
+    const server = new AgentServer();
+    const agent = new AgentBase({ name: 'test', route: '/test' });
+    server.register(agent, '/test');
+    server.unregister('/test');
+    expect(server.getAgents().size).toBe(0);
+  });
+
+  it('uses agent route if none provided', () => {
+    const server = new AgentServer();
+    const agent = new AgentBase({ name: 'myagent', route: '/myroute' });
+    server.register(agent);
+    expect(server.getAgent('/myroute')).toBeDefined();
+  });
+
+  it('getApp returns Hono instance', () => {
+    const server = new AgentServer();
+    const app = server.getApp();
+    expect(app).toBeDefined();
+    expect(typeof app.fetch).toBe('function');
+  });
+
+  it('health endpoint responds', async () => {
+    const server = new AgentServer();
+    const app = server.getApp();
+    const res = await app.request('/health');
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe('ok');
+  });
+
+  it('ready endpoint responds', async () => {
+    const server = new AgentServer();
+    const app = server.getApp();
+    const res = await app.request('/ready');
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.status).toBe('ready');
+  });
+
+  it('root listing when no agent at /', async () => {
+    const server = new AgentServer();
+    const agent = new AgentBase({ name: 'test', route: '/test' });
+    server.register(agent);
+    const app = server.getApp();
+    const res = await app.request('/');
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body.service).toBe('SignalWire AI Agents');
+    expect(body.agents.length).toBe(1);
+  });
+
+  it('includes security headers in responses', async () => {
+    const server = new AgentServer();
+    const app = server.getApp();
+    const res = await app.request('/health');
+    expect(res.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(res.headers.get('X-Frame-Options')).toBe('DENY');
+    expect(res.headers.get('X-XSS-Protection')).toBe('1; mode=block');
+    expect(res.headers.get('Referrer-Policy')).toBe('strict-origin-when-cross-origin');
+  });
+
+  it('responds to CORS preflight', async () => {
+    const server = new AgentServer();
+    const app = server.getApp();
+    const res = await app.request('/health', {
+      method: 'OPTIONS',
+      headers: {
+        'Origin': 'https://example.com',
+        'Access-Control-Request-Method': 'POST',
+      },
+    });
+    expect(res.headers.get('Access-Control-Allow-Origin')).toBe('*');
+  });
+});

package/tests/AuthHandler.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect } from 'vitest';
+import { AuthHandler } from '../src/AuthHandler.js';
+
+describe('AuthHandler', () => {
+  it('validates Bearer token', async () => {
+    const auth = new AuthHandler({ bearerToken: 'my-secret-token' });
+    const valid = await auth.validate({ authorization: 'Bearer my-secret-token' });
+    expect(valid).toBe(true);
+  });
+
+  it('rejects invalid Bearer token', async () => {
+    const auth = new AuthHandler({ bearerToken: 'my-secret-token' });
+    const valid = await auth.validate({ authorization: 'Bearer wrong-token' });
+    expect(valid).toBe(false);
+  });
+
+  it('validates API key', async () => {
+    const auth = new AuthHandler({ apiKey: 'my-api-key' });
+    const valid = await auth.validate({ 'x-api-key': 'my-api-key' });
+    expect(valid).toBe(true);
+  });
+
+  it('rejects invalid API key', async () => {
+    const auth = new AuthHandler({ apiKey: 'my-api-key' });
+    const valid = await auth.validate({ 'x-api-key': 'wrong-key' });
+    expect(valid).toBe(false);
+  });
+
+  it('validates Basic auth', async () => {
+    const auth = new AuthHandler({ basicAuth: ['admin', 'pass123'] });
+    const encoded = Buffer.from('admin:pass123').toString('base64');
+    const valid = await auth.validate({ authorization: `Basic ${encoded}` });
+    expect(valid).toBe(true);
+  });
+
+  it('rejects invalid Basic auth', async () => {
+    const auth = new AuthHandler({ basicAuth: ['admin', 'pass123'] });
+    const encoded = Buffer.from('admin:wrong').toString('base64');
+    const valid = await auth.validate({ authorization: `Basic ${encoded}` });
+    expect(valid).toBe(false);
+  });
+
+  it('validates custom validator', async () => {
+    const auth = new AuthHandler({
+      customValidator: (req) => req.headers['x-custom'] === 'valid',
+    });
+    const valid = await auth.validate({ 'x-custom': 'valid' });
+    expect(valid).toBe(true);
+  });
+
+  it('rejects with custom validator', async () => {
+    const auth = new AuthHandler({
+      customValidator: (req) => req.headers['x-custom'] === 'valid',
+    });
+    const valid = await auth.validate({ 'x-custom': 'invalid' });
+    expect(valid).toBe(false);
+  });
+
+  it('checks methods in priority order: Bearer > API Key > Basic', async () => {
+    const auth = new AuthHandler({
+      bearerToken: 'token',
+      apiKey: 'key',
+      basicAuth: ['u', 'p'],
+    });
+    // Bearer should pass even without API key or Basic
+    const valid = await auth.validate({ authorization: 'Bearer token' });
+    expect(valid).toBe(true);
+  });
+
+  it('allows all when no auth configured', async () => {
+    const auth = new AuthHandler({});
+    const valid = await auth.validate({});
+    expect(valid).toBe(true);
+  });
+
+  it('hasBearerAuth returns correct state', () => {
+    expect(new AuthHandler({ bearerToken: 'x' }).hasBearerAuth()).toBe(true);
+    expect(new AuthHandler({}).hasBearerAuth()).toBe(false);
+  });
+
+  it('hasApiKeyAuth returns correct state', () => {
+    expect(new AuthHandler({ apiKey: 'x' }).hasApiKeyAuth()).toBe(true);
+    expect(new AuthHandler({}).hasApiKeyAuth()).toBe(false);
+  });
+
+  it('hasBasicAuth returns correct state', () => {
+    expect(new AuthHandler({ basicAuth: ['u', 'p'] }).hasBasicAuth()).toBe(true);
+    expect(new AuthHandler({}).hasBasicAuth()).toBe(false);
+  });
+
+  it('async custom validator works', async () => {
+    const auth = new AuthHandler({
+      customValidator: async (req) => {
+        await new Promise((r) => setTimeout(r, 1));
+        return req.headers['x-token'] === 'async-valid';
+      },
+    });
+    expect(await auth.validate({ 'x-token': 'async-valid' })).toBe(true);
+    expect(await auth.validate({ 'x-token': 'nope' })).toBe(false);
+  });
+
+  it('middleware returns 401 for unauthorized request', async () => {
+    const auth = new AuthHandler({ bearerToken: 'secret' });
+    const mw = auth.middleware();
+    let nextCalled = false;
+
+    // Mock Hono context
+    const mockCtx = {
+      req: {
+        raw: {
+          headers: new Map([['authorization', 'Bearer wrong']]),
+        },
+      },
+      json: (body: unknown, status: number) => ({ body, status }),
+    };
+
+    const result = await mw(mockCtx, async () => { nextCalled = true; });
+    expect(nextCalled).toBe(false);
+    expect((result as any).status).toBe(401);
+  });
+});

package/tests/ConfigLoader.test.ts

@@ -0,0 +1,121 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { ConfigLoader } from '../src/ConfigLoader.js';
+import { writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+const TEST_DIR = join(process.cwd(), '__config_test_tmp__');
+
+describe('ConfigLoader', () => {
+  beforeAll(() => {
+    mkdirSync(TEST_DIR, { recursive: true });
+    writeFileSync(join(TEST_DIR, 'test.json'), JSON.stringify({
+      server: { host: '0.0.0.0', port: 3000 },
+      name: 'test-agent',
+      nested: { deep: { value: 42 } },
+    }));
+    writeFileSync(join(TEST_DIR, 'env-test.json'), JSON.stringify({
+      host: '${TEST_CONFIG_HOST|localhost}',
+      port: '${TEST_CONFIG_PORT|8080}',
+      secret: '${TEST_CONFIG_SECRET}',
+    }));
+  });
+
+  afterAll(() => {
+    rmSync(TEST_DIR, { recursive: true, force: true });
+  });
+
+  it('loads a JSON config file', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    expect(config.get('name')).toBe('test-agent');
+  });
+
+  it('dot-notation access for nested values', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    expect(config.get('server.host')).toBe('0.0.0.0');
+    expect(config.get('server.port')).toBe(3000);
+    expect(config.get('nested.deep.value')).toBe(42);
+  });
+
+  it('returns default value for missing path', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    expect(config.get('missing', 'fallback')).toBe('fallback');
+    expect(config.get('server.missing', 99)).toBe(99);
+  });
+
+  it('has() checks path existence', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    expect(config.has('name')).toBe(true);
+    expect(config.has('server.host')).toBe(true);
+    expect(config.has('nope')).toBe(false);
+    expect(config.has('server.nope')).toBe(false);
+  });
+
+  it('set() sets values with dot-notation', () => {
+    const config = new ConfigLoader();
+    config.loadFromObject({});
+    config.set('server.port', 5000);
+    config.set('name', 'new-agent');
+    expect(config.get('server.port')).toBe(5000);
+    expect(config.get('name')).toBe('new-agent');
+  });
+
+  it('getAll() returns all config data', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    const all = config.getAll();
+    expect(all.name).toBe('test-agent');
+    expect(all.server).toBeDefined();
+  });
+
+  it('interpolates env vars with defaults', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'env-test.json'));
+    expect(config.get('host')).toBe('localhost');
+    expect(config.get('port')).toBe('8080');
+    // secret has no default and no env var, so empty string
+    expect(config.get('secret')).toBe('');
+  });
+
+  it('interpolates env vars from environment', () => {
+    process.env['TEST_CONFIG_HOST'] = 'myhost.com';
+    try {
+      const config = new ConfigLoader(join(TEST_DIR, 'env-test.json'));
+      expect(config.get('host')).toBe('myhost.com');
+    } finally {
+      delete process.env['TEST_CONFIG_HOST'];
+    }
+  });
+
+  it('throws for missing file', () => {
+    expect(() => new ConfigLoader('/nonexistent/path.json')).toThrow('Config file not found');
+  });
+
+  it('loadFromObject works', () => {
+    const config = new ConfigLoader();
+    config.loadFromObject({ key: 'value', nested: { a: 1 } });
+    expect(config.get('key')).toBe('value');
+    expect(config.get('nested.a')).toBe(1);
+    expect(config.getFilePath()).toBeNull();
+  });
+
+  it('getFilePath returns the loaded file path', () => {
+    const config = new ConfigLoader(join(TEST_DIR, 'test.json'));
+    expect(config.getFilePath()).toContain('test.json');
+  });
+
+  it('load returns this for chaining', () => {
+    const config = new ConfigLoader();
+    const result = config.load(join(TEST_DIR, 'test.json'));
+    expect(result).toBe(config);
+  });
+
+  it('set creates intermediate objects', () => {
+    const config = new ConfigLoader();
+    config.loadFromObject({});
+    config.set('a.b.c', 'deep');
+    expect(config.get('a.b.c')).toBe('deep');
+  });
+
+  it('search returns null when file not found', () => {
+    const result = ConfigLoader.search('nonexistent-file-12345.json');
+    expect(result).toBeNull();
+  });
+});

package/tests/DataMap.test.ts

@@ -0,0 +1,286 @@
+import { describe, it, expect } from 'vitest';
+import { DataMap, createSimpleApiTool, createExpressionTool } from '../src/DataMap.js';
+import { SwaigFunctionResult } from '../src/SwaigFunctionResult.js';
+
+describe('DataMap', () => {
+  it('basic builder produces valid swaig function', () => {
+    const dm = new DataMap('get_weather')
+      .purpose('Get weather')
+      .parameter('location', 'string', 'City name', { required: true })
+      .webhook('GET', 'https://api.weather.com?q=${location}')
+      .output(new SwaigFunctionResult('Weather: ${response.temp}'));
+
+    const fn = dm.toSwaigFunction();
+    expect(fn['function']).toBe('get_weather');
+    expect(fn['description']).toBe('Get weather');
+    expect((fn['parameters'] as Record<string, unknown>)['required']).toEqual(['location']);
+    const dataMap = fn['data_map'] as Record<string, unknown>;
+    expect(dataMap['webhooks']).toBeDefined();
+  });
+
+  it('description is alias for purpose', () => {
+    const dm = new DataMap('fn').description('desc');
+    expect(dm.toSwaigFunction()['description']).toBe('desc');
+  });
+
+  it('default description when purpose not set', () => {
+    const dm = new DataMap('my_fn');
+    dm.webhook('GET', 'https://example.com').output(new SwaigFunctionResult('ok'));
+    expect(dm.toSwaigFunction()['description']).toBe('Execute my_fn');
+  });
+
+  it('parameter with enum', () => {
+    const dm = new DataMap('fn')
+      .parameter('color', 'string', 'A color', { enum: ['red', 'blue'] });
+    const params = dm.toSwaigFunction()['parameters'] as Record<string, unknown>;
+    const props = params['properties'] as Record<string, Record<string, unknown>>;
+    expect(props['color']['enum']).toEqual(['red', 'blue']);
+  });
+
+  it('expression-based tool', () => {
+    const dm = new DataMap('ctrl')
+      .purpose('Control playback')
+      .parameter('cmd', 'string', 'Command')
+      .expression('${args.cmd}', /start.*/, new SwaigFunctionResult('Starting'))
+      .expression('${args.cmd}', 'stop', new SwaigFunctionResult('Stopping'));
+
+    const fn = dm.toSwaigFunction();
+    const dataMap = fn['data_map'] as Record<string, unknown>;
+    const exprs = dataMap['expressions'] as Record<string, unknown>[];
+    expect(exprs.length).toBe(2);
+    expect(exprs[0]['pattern']).toBe('start.*');
+    expect(exprs[1]['pattern']).toBe('stop');
+  });
+
+  it('expression with nomatch output', () => {
+    const dm = new DataMap('fn')
+      .expression(
+        '${args.x}',
+        'yes',
+        new SwaigFunctionResult('matched'),
+        new SwaigFunctionResult('no match'),
+      );
+    const fn = dm.toSwaigFunction();
+    const exprs = (fn['data_map'] as Record<string, unknown>)['expressions'] as Record<string, unknown>[];
+    expect(exprs[0]['nomatch-output']).toEqual({ response: 'no match' });
+  });
+
+  it('webhook with body and headers', () => {
+    const dm = new DataMap('search')
+      .purpose('Search docs')
+      .webhook('POST', 'https://api.docs.com/search', {
+        headers: { Authorization: 'Bearer TOKEN' },
+      })
+      .body({ query: '${query}', limit: 3 })
+      .output(new SwaigFunctionResult('Found: ${response.title}'));
+
+    const fn = dm.toSwaigFunction();
+    const webhooks = (fn['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['method']).toBe('POST');
+    expect(webhooks[0]['headers']).toEqual({ Authorization: 'Bearer TOKEN' });
+    expect(webhooks[0]['body']).toEqual({ query: '${query}', limit: 3 });
+  });
+
+  it('webhook with params', () => {
+    const dm = new DataMap('fn')
+      .webhook('GET', 'https://example.com')
+      .params({ key: 'val' })
+      .output(new SwaigFunctionResult('ok'));
+    const webhooks = (dm.toSwaigFunction()['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['params']).toEqual({ key: 'val' });
+  });
+
+  it('foreach', () => {
+    const dm = new DataMap('fn')
+      .webhook('GET', 'https://example.com')
+      .foreach({ input_key: 'results', output_key: 'out', append: '${this.title}\n' })
+      .output(new SwaigFunctionResult('${out}'));
+    const webhooks = (dm.toSwaigFunction()['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['foreach']).toBeDefined();
+  });
+
+  it('multiple webhooks with fallback', () => {
+    const dm = new DataMap('multi')
+      .purpose('Search')
+      .webhook('GET', 'https://primary.com')
+      .output(new SwaigFunctionResult('Primary: ${response.title}'))
+      .webhook('GET', 'https://fallback.com')
+      .output(new SwaigFunctionResult('Fallback: ${response.title}'))
+      .fallbackOutput(new SwaigFunctionResult('All APIs failed'));
+
+    const fn = dm.toSwaigFunction();
+    const dataMap = fn['data_map'] as Record<string, unknown>;
+    expect((dataMap['webhooks'] as unknown[]).length).toBe(2);
+    expect(dataMap['output']).toEqual({ response: 'All APIs failed' });
+  });
+
+  it('error keys on webhook', () => {
+    const dm = new DataMap('fn')
+      .webhook('GET', 'https://example.com')
+      .errorKeys(['error', 'message'])
+      .output(new SwaigFunctionResult('ok'));
+    const webhooks = (dm.toSwaigFunction()['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['error_keys']).toEqual(['error', 'message']);
+  });
+
+  it('global error keys', () => {
+    const dm = new DataMap('fn').globalErrorKeys(['err']);
+    dm.webhook('GET', 'https://example.com').output(new SwaigFunctionResult('ok'));
+    const dataMap = dm.toSwaigFunction()['data_map'] as Record<string, unknown>;
+    expect(dataMap['error_keys']).toEqual(['err']);
+  });
+
+  it('throws if body/output/params/foreach called without webhook', () => {
+    const dm = new DataMap('fn');
+    expect(() => dm.body({})).toThrow('Must add webhook');
+    expect(() => dm.output(new SwaigFunctionResult('x'))).toThrow('Must add webhook');
+    expect(() => dm.params({})).toThrow('Must add webhook');
+    expect(() => dm.foreach({ input_key: 'a', output_key: 'b', append: 'c' })).toThrow('Must add webhook');
+  });
+
+  it('webhookExpressions', () => {
+    const dm = new DataMap('fn')
+      .webhook('GET', 'https://example.com')
+      .webhookExpressions([{ string: '${response.status}', pattern: 'ok', output: { response: 'good' } }])
+      .output(new SwaigFunctionResult('ok'));
+    const webhooks = (dm.toSwaigFunction()['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['expressions']).toBeDefined();
+  });
+
+  it('webhook with advanced options', () => {
+    const dm = new DataMap('fn')
+      .webhook('POST', 'https://example.com', {
+        formParam: 'data',
+        inputArgsAsParams: true,
+        requireArgs: ['query'],
+      })
+      .output(new SwaigFunctionResult('ok'));
+    const webhooks = (dm.toSwaigFunction()['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['form_param']).toBe('data');
+    expect(webhooks[0]['input_args_as_params']).toBe(true);
+    expect(webhooks[0]['require_args']).toEqual(['query']);
+  });
+});
+
+describe('createSimpleApiTool', () => {
+  it('creates a simple API tool', () => {
+    const dm = createSimpleApiTool({
+      name: 'weather',
+      url: 'https://api.weather.com?q=${location}',
+      responseTemplate: 'Temp: ${response.temp}',
+      parameters: { location: { type: 'string', description: 'City', required: true } },
+    });
+    const fn = dm.toSwaigFunction();
+    expect(fn['function']).toBe('weather');
+    const params = fn['parameters'] as Record<string, unknown>;
+    expect(params['required']).toEqual(['location']);
+  });
+});
+
+describe('createExpressionTool', () => {
+  it('creates expression-based tool', () => {
+    const dm = createExpressionTool({
+      name: 'ctrl',
+      patterns: {
+        '${args.cmd}': ['start', new SwaigFunctionResult('Starting')],
+      },
+    });
+    const fn = dm.toSwaigFunction();
+    const exprs = (fn['data_map'] as Record<string, unknown>)['expressions'] as Record<string, unknown>[];
+    expect(exprs.length).toBe(1);
+  });
+});
+
+// ── Pass 3: DataMap enhancements ──────────────────────────────────
+
+describe('DataMap - registerWithAgent', () => {
+  it('registers DataMap with an agent-like object', () => {
+    const registered: Record<string, unknown>[] = [];
+    const mockAgent = {
+      registerSwaigFunction(fn: Record<string, unknown>) {
+        registered.push(fn);
+      },
+    };
+    const dm = new DataMap('my_tool')
+      .purpose('Test tool')
+      .webhook('GET', 'https://example.com')
+      .output(new SwaigFunctionResult('ok'));
+
+    dm.registerWithAgent(mockAgent);
+    expect(registered.length).toBe(1);
+    expect(registered[0]['function']).toBe('my_tool');
+  });
+
+  it('registerWithAgent returns this for chaining', () => {
+    const mockAgent = { registerSwaigFunction() {} };
+    const dm = new DataMap('fn')
+      .webhook('GET', 'https://example.com')
+      .output(new SwaigFunctionResult('ok'));
+    expect(dm.registerWithAgent(mockAgent)).toBe(dm);
+  });
+});
+
+describe('DataMap - ENV expansion', () => {
+  it('expands ${ENV.*} variables in webhook URLs', () => {
+    const saved = process.env['TEST_API_KEY'];
+    process.env['TEST_API_KEY'] = 'secret123';
+    try {
+      const dm = new DataMap('fn')
+        .enableEnvExpansion()
+        .purpose('Test')
+        .webhook('GET', 'https://api.example.com?key=${ENV.TEST_API_KEY}')
+        .output(new SwaigFunctionResult('ok'));
+      const fn = dm.toSwaigFunction();
+      const webhooks = (fn['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+      expect(webhooks[0]['url']).toBe('https://api.example.com?key=secret123');
+    } finally {
+      if (saved) process.env['TEST_API_KEY'] = saved;
+      else delete process.env['TEST_API_KEY'];
+    }
+  });
+
+  it('missing ENV vars expand to empty string', () => {
+    delete process.env['NONEXISTENT_VAR_12345'];
+    const dm = new DataMap('fn')
+      .enableEnvExpansion()
+      .webhook('GET', 'https://api.example.com?key=${ENV.NONEXISTENT_VAR_12345}')
+      .output(new SwaigFunctionResult('ok'));
+    const fn = dm.toSwaigFunction();
+    const webhooks = (fn['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+    expect(webhooks[0]['url']).toBe('https://api.example.com?key=');
+  });
+
+  it('no expansion when enableEnvExpansion not called', () => {
+    process.env['TEST_NO_EXPAND'] = 'should-not-appear';
+    try {
+      const dm = new DataMap('fn')
+        .webhook('GET', 'https://api.example.com?key=${ENV.TEST_NO_EXPAND}')
+        .output(new SwaigFunctionResult('ok'));
+      const fn = dm.toSwaigFunction();
+      const webhooks = (fn['data_map'] as Record<string, unknown>)['webhooks'] as Record<string, unknown>[];
+      expect(webhooks[0]['url']).toBe('https://api.example.com?key=${ENV.TEST_NO_EXPAND}');
+    } finally {
+      delete process.env['TEST_NO_EXPAND'];
+    }
+  });
+
+  it('expands ENV vars in descriptions and outputs', () => {
+    process.env['TEST_SERVICE_NAME'] = 'MyService';
+    try {
+      const dm = new DataMap('fn')
+        .enableEnvExpansion()
+        .purpose('Call ${ENV.TEST_SERVICE_NAME} API')
+        .webhook('GET', 'https://example.com')
+        .output(new SwaigFunctionResult('ok'));
+      const fn = dm.toSwaigFunction();
+      expect(fn['description']).toBe('Call MyService API');
+    } finally {
+      delete process.env['TEST_SERVICE_NAME'];
+    }
+  });
+
+  it('enableEnvExpansion returns this for chaining', () => {
+    const dm = new DataMap('fn');
+    expect(dm.enableEnvExpansion()).toBe(dm);
+  });
+});