@topolo/sdk 0.7.0 → 0.8.1

package/src/client.test.ts

@@ -1,894 +0,0 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-import { TopoloClient } from './client.js';
-import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from './errors.js';
-
-function stubFetch(responses: Array<{ status?: number; body?: unknown; contentType?: string }>) {
-  const calls: Array<{ url: string; init: RequestInit }> = [];
-  const impl = vi.fn(async (url: string, init: RequestInit) => {
-    calls.push({ url, init });
-    const next = responses.shift() ?? { status: 200, body: { ok: true } };
-    return new Response(JSON.stringify(next.body ?? {}), {
-      status: next.status ?? 200,
-      headers: { 'Content-Type': next.contentType ?? 'application/json' },
-    });
-  });
-  return { impl: impl as unknown as typeof fetch, calls };
-}
-
-const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
-const SERVICE_LOOKUP = { body: { success: true, data: { app_id: 'app_test' } } };
-const MAIL_CATALOG = {
-  body: {
-    data: {
-      services: [
-        {
-          app_id: 'app_mail',
-          app_slug: 'topolo-mail',
-          name: 'Topolo Mail',
-          api_base_url: 'https://mail-api.topolo.app',
-          launch_url: 'https://mail.topolo.app',
-          surface_kind: 'api',
-          status: 'active',
-          granted_permissions: ['app_mail.messages:read'],
-        },
-      ],
-    },
-  },
-};
-const ACTION_CATALOG = {
-  body: {
-    data: {
-      actions: [
-        {
-          action_id: 'app_mail.messages.list',
-          name: 'messages.list',
-          tool_name: 'topolo_mail_messages_list',
-          title: 'List messages',
-          description: 'List Mail messages',
-          app_id: 'app_mail',
-          app_slug: 'topolo-mail',
-          app_name: 'Topolo Mail',
-          method: 'GET',
-          path: '/api/mail/mailboxes/{mailboxId}/messages',
-          permission_name: 'messages:read',
-          required_permission: 'app_mail.messages:read',
-          input_schema: { type: 'object' },
-          output_schema: {},
-          read_only: true,
-          destructive: false,
-          requires_confirmation: false,
-        },
-        {
-          action_id: 'app_mail.messages.get',
-          name: 'messages.get',
-          tool_name: 'topolo_mail_messages_get',
-          title: 'Get message',
-          description: 'Get Mail message',
-          app_id: 'app_mail',
-          app_slug: 'topolo-mail',
-          app_name: 'Topolo Mail',
-          method: 'GET',
-          path: '/api/mail/mailboxes/{mailboxId}/messages/{messageId}',
-          permission_name: 'messages:read',
-          required_permission: 'app_mail.messages:read',
-          input_schema: { type: 'object' },
-          output_schema: {},
-          read_only: true,
-          destructive: false,
-          requires_confirmation: false,
-        },
-        {
-          action_id: 'app_mail.messages.send',
-          name: 'messages.send',
-          tool_name: 'topolo_mail_messages_send',
-          title: 'Send message',
-          description: 'Send Mail message',
-          app_id: 'app_mail',
-          app_slug: 'topolo-mail',
-          app_name: 'Topolo Mail',
-          method: 'POST',
-          path: '/api/mail/mailboxes/{mailboxId}/messages',
-          permission_name: 'messages:send',
-          required_permission: 'app_mail.messages:send',
-          input_schema: { type: 'object' },
-          output_schema: {},
-          read_only: false,
-          destructive: false,
-          requires_confirmation: true,
-        },
-      ],
-    },
-  },
-};
-
-function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
-  return calls.filter((call) =>
-    !call.url.includes('/api/services/by-slug/') &&
-    !call.url.includes('/api/services/catalog') &&
-    !call.url.includes('/api/actions/catalog')
-  );
-}
-
-beforeEach(() => {
-  TopoloClient.clearAppIdCache();
-});
-
-describe('TopoloClient.request', () => {
-  it('injects Bearer auth + audit headers for access_token credentials', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'access_token', accessToken: 'tok_abc' },
-      agent: AGENT,
-      fetch: impl,
-      appIds: { auth: 'service_auth' },
-    });
-    await client.request({ service: 'auth', path: '/api/me' });
-    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
-    expect(headers.get('Authorization')).toBe('Bearer tok_abc');
-    expect(headers.get('X-App-ID')).toBe('service_auth');
-    expect(headers.get('X-Topolo-Client')).toBe('topolo-test/0.0.0');
-    expect(headers.get('X-Topolo-Request-Id')).toMatch(/.+/);
-  });
-
-  it('uses X-Api-Key header for api_key credentials', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages' });
-    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
-    expect(headers.get('X-Api-Key')).toBe('dak_xyz');
-    expect(headers.get('Authorization')).toBeNull();
-  });
-
-  it('adds canonical resource headers for resource-scoped API keys', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await client.request({
-      service: 'mail',
-      path: '/api/mail/mailboxes/mbx_1/messages',
-      resource: { resourceType: 'mailbox', resourceId: 'mbx_1' },
-    });
-    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
-    expect(headers.get('X-Topolo-Resource-Type')).toBe('mailbox');
-    expect(headers.get('X-Topolo-Resource-ID')).toBe('mbx_1');
-  });
-
-  it('passes arbitrary cataloged workspace aliases through resource headers', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await client.request({
-      service: 'mail',
-      path: '/api/example',
-      resource: { resourceType: 'studio_portfolio', resourceId: 'portfolio_1' },
-    });
-    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
-    expect(headers.get('X-Topolo-Resource-Type')).toBe('studio_portfolio');
-    expect(headers.get('X-Topolo-Resource-ID')).toBe('portfolio_1');
-  });
-
-  it('refuses mutating requests without confirm', async () => {
-    const { impl } = stubFetch([]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await expect(
-      client.request({ service: 'mail', method: 'POST', path: '/api/mail/mailboxes/primary/messages', body: {} }),
-    ).rejects.toBeInstanceOf(TopoloAuthError);
-  });
-
-  it('allows mutating requests with confirm: true', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { id: 'm_1' } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await client.request({
-      service: 'mail',
-      method: 'POST',
-      path: '/api/mail/mailboxes/primary/messages',
-      body: { subject: 'Hello' },
-      confirm: true,
-    });
-    expect(requestCalls(calls)[0]!.init.method).toBe('POST');
-  });
-
-  it('maps 401 → TopoloAuthError with unwrapped message', async () => {
-    const { impl } = stubFetch([
-      { status: 401, body: { error: { code: 'invalid_token', message: 'Token expired' } } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toMatchObject({
-      name: 'TopoloAuthError',
-      code: 'auth_error',
-      message: 'Token expired',
-    });
-  });
-
-  it('regression: nested error.message object never stringifies to [object Object]', async () => {
-    const { impl } = stubFetch([
-      { status: 401, body: { error: { code: 'bad_sig', message: 'Bad signature' } } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'access_token', accessToken: 'bad' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    try {
-      await client.request({ service: 'auth', path: '/api/me' });
-      throw new Error('expected throw');
-    } catch (err) {
-      expect(err).toBeInstanceOf(TopoloAuthError);
-      expect((err as Error).message).not.toBe('[object Object]');
-      expect((err as Error).message).toContain('Bad signature');
-    }
-  });
-
-  it('maps 403 → TopoloPermissionError with required scopes extracted', async () => {
-    const { impl } = stubFetch([
-      MAIL_CATALOG,
-      { status: 403, body: { error: 'forbidden', required: ['mail.messages:send'] } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await expect(
-      client.request({ service: 'mail', method: 'POST', path: '/api/mail/mailboxes/primary/messages', body: {}, confirm: true }),
-    ).rejects.toBeInstanceOf(TopoloPermissionError);
-  });
-
-  it('maps non-401/403 failures → TopoloHttpError with status preserved', async () => {
-    const { impl } = stubFetch([MAIL_CATALOG, { status: 500, body: { error: 'boom' } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await expect(client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages' })).rejects.toMatchObject({
-      name: 'TopoloHttpError',
-      status: 500,
-    });
-  });
-
-  it('appends query params as search string', async () => {
-    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { messages: [] } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-    });
-    await client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages', query: { q: 'acme', page: 2 } });
-    const u = new URL(requestCalls(calls)[0]!.url);
-    expect(u.searchParams.get('q')).toBe('acme');
-    expect(u.searchParams.get('page')).toBe('2');
-  });
-
-  it('rejects missing credential or agent.clientName at construction', () => {
-    expect(
-      () =>
-        new TopoloClient({
-          credential: undefined as never,
-          agent: AGENT,
-        }),
-    ).toThrow(TopoloAuthError);
-    expect(
-      () =>
-        new TopoloClient({
-          credential: { kind: 'api_key', apiKey: 'x' },
-          agent: { clientName: '' as unknown as string, clientVersion: '0' },
-        }),
-    ).toThrow(TopoloAuthError);
-  });
-});
-
-describe('TopoloClient.debug hook', () => {
-  it('fires request → response on a successful call with stable requestId + duration', async () => {
-    const { impl } = stubFetch([SERVICE_LOOKUP, { body: { ok: true } }]);
-    const events: unknown[] = [];
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      debug: (e) => events.push(e),
-    });
-    await client.request({ service: 'auth', path: '/api/me' });
-    expect(events).toHaveLength(2);
-    const typed = events as Array<{
-      phase: string;
-      method: string;
-      service: string;
-      path: string;
-      url: string;
-      requestId: string;
-      status?: number;
-      durationMs?: number;
-    }>;
-    const req = typed[0]!;
-    const res = typed[1]!;
-    expect(req.phase).toBe('request');
-    expect(req.method).toBe('GET');
-    expect(req.service).toBe('auth');
-    expect(req.path).toBe('/api/me');
-    expect(req.requestId).toMatch(/.+/);
-    expect(res.phase).toBe('response');
-    expect(res.status).toBe(200);
-    expect(res.requestId).toBe(req.requestId);
-    expect(typeof res.durationMs).toBe('number');
-  });
-
-  it('fires request → error on 4xx with the unwrapped message and status', async () => {
-    const { impl } = stubFetch([
-      { status: 401, body: { error: { code: 'auth_error', message: 'Expired' } } },
-    ]);
-    const events: Array<{ phase: string; error?: string; status?: number }> = [];
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      debug: (e) => events.push(e),
-    });
-    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toThrow(TopoloAuthError);
-    expect(events.map((e) => e.phase)).toEqual(['request', 'error']);
-    expect(events[1]!.status).toBe(401);
-    expect(events[1]!.error).toBe('Expired');
-  });
-
-  it('fires request → error on a thrown fetch (network failure)', async () => {
-    const impl = (vi.fn(async () => {
-      throw new Error('ECONNREFUSED');
-    }) as unknown) as typeof fetch;
-    const events: Array<{ phase: string; error?: string; status?: number }> = [];
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      debug: (e) => events.push(e),
-    });
-    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toThrow('ECONNREFUSED');
-    expect(events.map((e) => e.phase)).toEqual(['request', 'error']);
-    expect(events[1]!.error).toBe('ECONNREFUSED');
-    expect(events[1]!.status).toBeUndefined();
-  });
-
-  it('swallows throws from the debug callback without affecting the request path', async () => {
-    const { impl } = stubFetch([{ body: { ok: true } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      debug: () => {
-        throw new Error('callback blew up');
-      },
-    });
-    // Returns normally despite the callback throwing on both events.
-    await expect(client.request({ service: 'auth', path: '/api/me' })).resolves.toBeDefined();
-  });
-});
-
-describe('TopoloClient.getAppIdBySlug', () => {
-  function freshClient(impl: typeof fetch, serviceUrls?: Record<string, string>) {
-    TopoloClient.clearAppIdCache();
-    return new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: serviceUrls as never,
-    });
-  }
-
-  it('uses configured app ids without calling Auth', async () => {
-    const { impl, calls } = stubFetch([]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' } as never,
-      appIds: { notify: 'service_notify' },
-    });
-    const id = await client.getAppIdBySlug('topolo-notify');
-    expect(id).toBe('service_notify');
-    expect(calls).toEqual([]);
-  });
-
-  it('falls back to /api/services/by-slug/:slug for unknown slugs', async () => {
-    const { impl, calls } = stubFetch([
-      { body: { success: true, data: { app_id: 'service_abc123', api_base_url: 'https://x-api' } } },
-    ]);
-    const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    const id = await client.getAppIdBySlug('external-service');
-    expect(id).toBe('service_abc123');
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/external-service');
-    // No auth header — endpoint is public.
-    const headers = new Headers(calls[0]!.init.headers);
-    expect(headers.get('Authorization')).toBeNull();
-    expect(headers.get('X-Api-Key')).toBeNull();
-  });
-
-  it('returns null on 404 and caches the negative result', async () => {
-    const { impl, calls } = stubFetch([{ status: 404, body: { success: false } }]);
-    const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    expect(await client.getAppIdBySlug('nope')).toBeNull();
-    expect(await client.getAppIdBySlug('nope')).toBeNull();
-    expect(calls.length).toBe(1);
-  });
-
-  it('caches positive results across calls', async () => {
-    const { impl, calls } = stubFetch([
-      { body: { success: true, data: { app_id: 'service_external' } } },
-    ]);
-    const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    expect(await client.getAppIdBySlug('external-service')).toBe('service_external');
-    expect(await client.getAppIdBySlug('external-service')).toBe('service_external');
-    expect(calls.length).toBe(1);
-  });
-
-  it('normalizes slug case + whitespace before hitting the network', async () => {
-    const { impl, calls } = stubFetch([
-      { body: { success: true, data: { app_id: 'service_x' } } },
-    ]);
-    const client = freshClient(impl, { auth: 'https://auth.example.com', developers: 'https://auth.example.com' });
-    await client.getAppIdBySlug('  EXTERNAL-SERVICE  ');
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/by-slug/external-service');
-  });
-
-  it('returns null on network failure without poisoning cache', async () => {
-    let throws = true;
-    const impl = vi.fn(async (url: string) => {
-      if (throws) {
-        throws = false;
-        throw new Error('ECONNREFUSED');
-      }
-      return new Response(JSON.stringify({ success: true, data: { app_id: 'service_y' } }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }) as unknown as typeof fetch;
-    TopoloClient.clearAppIdCache();
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'x' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' } as never,
-    });
-    expect(await client.getAppIdBySlug('flaky')).toBeNull();
-    // Second call retries — earlier null was not cached.
-    expect(await client.getAppIdBySlug('flaky')).toBe('service_y');
-  });
-});
-
-describe('TopoloClient.listServices', () => {
-  it('normalizes the live catalog and attaches the credential', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_topolo_director',
-                app_slug: 'topolo-director',
-                name: 'Topolo Director',
-                description: 'Demo control plane',
-                api_base_url: 'https://director-api.topolo.app',
-                launch_url: 'https://director.topolo.app',
-                status: 'active',
-                surface_kind: 'application',
-                launchable: true,
-                api_key_resource: {
-                  resourceType: 'brand',
-                  label: 'Brands',
-                  emptyLabel: 'All brands in the organization',
-                  resourceConcept: 'workspace',
-                  canonicalResourceType: 'workspace',
-                  defaultEntitlement: 'enterprise',
-                  exceptionPolicy: 'app_or_organization',
-                },
-                api_key_resources: [
-                  {
-                    resourceType: 'brand',
-                    label: 'Brands',
-                    emptyLabel: 'All brands in the organization',
-                    resourceConcept: 'workspace',
-                    canonicalResourceType: 'workspace',
-                    defaultEntitlement: 'enterprise',
-                    exceptionPolicy: 'app_or_organization',
-                  },
-                ],
-                granted_permissions: ['app_topolo_director.dashboard:read'],
-              },
-            ],
-          },
-        },
-      },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'access_token', accessToken: 'tok_abc' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    const out = await client.listServices();
-    expect(out).toEqual([
-      {
-        appId: 'app_topolo_director',
-        slug: 'topolo-director',
-        name: 'Topolo Director',
-        description: 'Demo control plane',
-        apiBaseUrl: 'https://director-api.topolo.app',
-        launchUrl: 'https://director.topolo.app',
-        status: 'active',
-        surfaceKind: 'application',
-        launchable: true,
-        apiKeyResource: {
-          resourceType: 'brand',
-          label: 'Brands',
-          emptyLabel: 'All brands in the organization',
-          resourceConcept: 'workspace',
-          canonicalResourceType: 'workspace',
-          defaultEntitlement: 'enterprise',
-          exceptionPolicy: 'app_or_organization',
-        },
-        apiKeyResources: [
-          {
-            resourceType: 'brand',
-            label: 'Brands',
-            emptyLabel: 'All brands in the organization',
-            resourceConcept: 'workspace',
-            canonicalResourceType: 'workspace',
-            defaultEntitlement: 'enterprise',
-            exceptionPolicy: 'app_or_organization',
-          },
-        ],
-        permissions: ['app_topolo_director.dashboard:read'],
-      },
-    ]);
-    expect(calls[0]!.url).toBe(
-      'https://auth.example.com/api/services/catalog',
-    );
-    expect(new Headers(calls[0]!.init.headers).get('Authorization')).toBe(
-      'Bearer tok_abc',
-    );
-  });
-
-  it('does not fall back to the generated global snapshot on HTTP failure', async () => {
-    const { impl } = stubFetch([{ status: 503, body: { error: 'down' } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    await expect(client.listServices()).rejects.toBeInstanceOf(TopoloHttpError);
-  });
-
-  it('routes bundled service aliases only after the scoped live catalog grants access', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_mail',
-                app_slug: 'topolo-mail',
-                name: 'Topolo Mail',
-                api_base_url: 'https://mail-api.topolo.app',
-                launch_url: 'https://mail.topolo.app',
-                surface_kind: 'application',
-                status: 'active',
-                granted_permissions: ['app_mail.messages:read'],
-              },
-            ],
-          },
-        },
-      },
-      { body: { ok: true } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await client.request({ service: 'mail', path: '/api/health' });
-
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
-    expect(calls[1]!.url).toBe('https://mail-api.topolo.app/api/health');
-  });
-
-  it('routes known split-surface services to the callable API URL', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_crm',
-                app_slug: 'topolo-crm',
-                name: 'Topolo CRM',
-                api_base_url: 'https://crm-api.topolo.app',
-                launch_url: 'https://crm.topolo.app',
-                surface_kind: 'application',
-                status: 'active',
-                granted_permissions: ['app_crm.contacts:read'],
-              },
-            ],
-          },
-        },
-      },
-      { body: { ok: true } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await client.request({ service: 'crm', path: '/health' });
-
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
-    expect(calls[1]!.url).toBe('https://crm-api.topolo.app/health');
-  });
-
-  it('derives the catalog (developers) host from the auth url when developers is unset', async () => {
-    const { impl, calls } = stubFetch([{ body: { data: { services: [] } } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      // Fleet apps configure only `auth` per-env; the catalog host is derived.
-      serviceUrls: { auth: 'https://auth.stg.topolo.us' },
-    });
-
-    await client.listServices();
-
-    expect(calls[0]!.url).toBe('https://developers.stg.topolo.us/api/services/catalog');
-  });
-
-  it('prefers live catalog api_base_url for dynamic services', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_future',
-                app_slug: 'topolo-future',
-                name: 'Future',
-                api_base_url: 'https://future-api.topolo.app',
-                launch_url: 'https://future.topolo.app',
-                surface_kind: 'api',
-                status: 'active',
-                granted_permissions: ['app_future.read:all'],
-              },
-            ],
-          },
-        },
-      },
-      { body: { ok: true } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await client.request({ service: 'future', path: '/health' });
-
-    expect(calls[1]!.url).toBe('https://future-api.topolo.app/health');
-  });
-
-  it('refuses a bundled static service that is absent from the scoped live catalog', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_crm',
-                app_slug: 'topolo-crm',
-                name: 'Topolo CRM',
-                api_base_url: 'https://crm-api.topolo.app',
-                launch_url: 'https://crm.topolo.app',
-                surface_kind: 'api',
-                status: 'active',
-                granted_permissions: ['app_crm.contacts:read'],
-              },
-            ],
-          },
-        },
-      },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await expect(client.request({ service: 'mail', path: '/api/health' })).rejects.toMatchObject({
-      code: 'unknown_service',
-    });
-    expect(calls).toHaveLength(1);
-  });
-
-  it('does not treat live browser applications as generic API services', async () => {
-    const { impl } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_future_app',
-                app_slug: 'topolo-future-app',
-                name: 'Future App',
-                launch_url: 'https://future-app.topolo.app',
-                surface_kind: 'application',
-                status: 'active',
-                granted_permissions: ['app_future_app.launch:read'],
-                launchable: true,
-              },
-            ],
-          },
-        },
-      },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await expect(client.request({ service: 'future-app', path: '/api/health' })).rejects.toMatchObject({
-      code: 'unknown_service',
-    });
-  });
-
-  it('caches the live catalog per client for repeated dynamic service calls', async () => {
-    const { impl, calls } = stubFetch([
-      {
-        body: {
-          data: {
-            services: [
-              {
-                app_id: 'app_future',
-                app_slug: 'topolo-warehouse',
-                name: 'Warehouse',
-                api_base_url: 'https://warehouse.topolo.app',
-                launch_url: 'https://warehouse.topolo.app',
-                surface_kind: 'api',
-                status: 'active',
-                granted_permissions: ['app_future.read:all'],
-              },
-            ],
-          },
-        },
-      },
-      { body: { ok: true } },
-      { body: { ok: true } },
-    ]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-
-    await client.request({ service: 'warehouse', path: '/api/one' });
-    await client.request({ service: 'warehouse', path: '/api/two' });
-
-    expect(calls.map((call) => call.url)).toEqual([
-      'https://auth.example.com/api/services/catalog',
-      'https://warehouse.topolo.app/api/one',
-      'https://warehouse.topolo.app/api/two',
-    ]);
-  });
-});
-
-describe('TopoloClient action catalog', () => {
-  it('lists scoped actions from Auth', async () => {
-    const { impl, calls } = stubFetch([ACTION_CATALOG]);
-    const client = new TopoloClient({
-      credential: { kind: 'access_token', accessToken: 'tok_abc' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    const actions = await client.listActions();
-    expect(actions.map((action) => action.name)).toEqual([
-      'messages.list',
-      'messages.get',
-      'messages.send',
-    ]);
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/actions/catalog');
-  });
-
-  it('calls GET actions by mapping remaining input to query params', async () => {
-    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { messages: [] } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    await client.callAction('messages.list', { mailboxId: 'primary', q: 'Ada', page: 2 });
-    const call = requestCalls(calls)[0]!;
-    const url = new URL(call.url);
-    expect(url.toString()).toBe('https://mail-api.topolo.app/api/mail/mailboxes/primary/messages?q=Ada&page=2');
-    expect(call.init.method).toBe('GET');
-    const headers = new Headers(call.init.headers);
-    expect(headers.get('X-Topolo-Action-Id')).toBe('app_mail.messages.list');
-    expect(headers.get('X-Topolo-Action-Name')).toBe('messages.list');
-  });
-
-  it('substitutes action path params and removes them from the query', async () => {
-    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { id: 'm1' } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    await client.callAction('topolo_mail_messages_get', {
-      mailboxId: 'primary',
-      messageId: 'm 1',
-      includeDeleted: false,
-    });
-    const url = new URL(requestCalls(calls)[0]!.url);
-    expect(url.pathname).toBe('/api/mail/mailboxes/primary/messages/m%201');
-    expect(url.searchParams.get('includeDeleted')).toBe('false');
-    expect(url.searchParams.has('mailboxId')).toBe(false);
-    expect(url.searchParams.has('messageId')).toBe(false);
-  });
-
-  it('requires confirmation for mutating action calls', async () => {
-    const { impl } = stubFetch([ACTION_CATALOG]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    await expect(
-      client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }),
-    ).rejects.toBeInstanceOf(TopoloAuthError);
-  });
-
-  it('sends remaining input as the body when a mutating action is confirmed', async () => {
-    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { id: 'm1' } }]);
-    const client = new TopoloClient({
-      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
-      agent: AGENT,
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
-    });
-    await client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }, { confirm: true });
-    const call = requestCalls(calls)[0]!;
-    expect(call.init.method).toBe('POST');
-    expect(JSON.parse(String(call.init.body))).toEqual({ subject: 'Hello' });
-  });
-});
-
-// Silence unused-import warning if the bundler later tree-shakes these
-void TopoloHttpError;