@topolo/sdk 0.4.1 → 0.4.3

package/src/client.test.ts

@@ -17,9 +17,95 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown; contentTy
 
 const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
 const SERVICE_LOOKUP = { body: { success: true, data: { service_id: 'service_test' } } };
+const MAIL_CATALOG = {
+  body: {
+    data: {
+      services: [
+        {
+          service_id: 'srv_mail',
+          app_slug: 'topolo-mail',
+          name: 'Topolo Mail',
+          base_url: 'https://mail-api.topolo.app',
+          surface_kind: 'api',
+          status: 'active',
+          granted_permissions: ['srv_mail.messages:read'],
+        },
+      ],
+    },
+  },
+};
+const ACTION_CATALOG = {
+  body: {
+    data: {
+      actions: [
+        {
+          action_id: 'srv_mail.messages.list',
+          name: 'messages.list',
+          tool_name: 'topolo_mail_messages_list',
+          title: 'List messages',
+          description: 'List Mail messages',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'GET',
+          path: '/api/mail/mailboxes/{mailboxId}/messages',
+          permission_name: 'messages:read',
+          required_permission: 'srv_mail.messages:read',
+          input_schema: { type: 'object' },
+          output_schema: {},
+          read_only: true,
+          destructive: false,
+          requires_confirmation: false,
+        },
+        {
+          action_id: 'srv_mail.messages.get',
+          name: 'messages.get',
+          tool_name: 'topolo_mail_messages_get',
+          title: 'Get message',
+          description: 'Get Mail message',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'GET',
+          path: '/api/mail/mailboxes/{mailboxId}/messages/{messageId}',
+          permission_name: 'messages:read',
+          required_permission: 'srv_mail.messages:read',
+          input_schema: { type: 'object' },
+          output_schema: {},
+          read_only: true,
+          destructive: false,
+          requires_confirmation: false,
+        },
+        {
+          action_id: 'srv_mail.messages.send',
+          name: 'messages.send',
+          tool_name: 'topolo_mail_messages_send',
+          title: 'Send message',
+          description: 'Send Mail message',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'POST',
+          path: '/api/mail/mailboxes/{mailboxId}/messages',
+          permission_name: 'messages:send',
+          required_permission: 'srv_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/'));
+  return calls.filter((call) =>
+    !call.url.includes('/api/services/by-slug/') &&
+    !call.url.includes('/api/services/catalog') &&
+    !call.url.includes('/api/actions/catalog')
+  );
 }
 
 beforeEach(() => {
@@ -28,7 +114,7 @@ beforeEach(() => {
 
 describe('TopoloClient.request', () => {
   it('injects Bearer auth + audit headers for access_token credentials', async () => {
-    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
     const client = new TopoloClient({
       credential: { kind: 'access_token', accessToken: 'tok_abc' },
       agent: AGENT,
@@ -44,13 +130,13 @@ describe('TopoloClient.request', () => {
   });
 
   it('uses X-Api-Key header for api_key credentials', async () => {
-    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    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: 'crm', path: '/api/contacts' });
+    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();
@@ -64,22 +150,22 @@ describe('TopoloClient.request', () => {
       fetch: impl,
     });
     await expect(
-      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {} }),
+      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([{ body: { id: 'c_1' } }]);
+    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: 'crm',
+      service: 'mail',
       method: 'POST',
-      path: '/api/contacts',
-      body: { email: 'a@b.co' },
+      path: '/api/mail/mailboxes/primary/messages',
+      body: { subject: 'Hello' },
       confirm: true,
     });
     expect(requestCalls(calls)[0]!.init.method).toBe('POST');
@@ -122,7 +208,8 @@ describe('TopoloClient.request', () => {
 
   it('maps 403 → TopoloPermissionError with required scopes extracted', async () => {
     const { impl } = stubFetch([
-      { status: 403, body: { error: 'forbidden', required: ['crm.contacts:write'] } },
+      MAIL_CATALOG,
+      { status: 403, body: { error: 'forbidden', required: ['mail.messages:send'] } },
     ]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
@@ -130,31 +217,31 @@ describe('TopoloClient.request', () => {
       fetch: impl,
     });
     await expect(
-      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {}, confirm: true }),
+      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([{ status: 500, body: { error: 'boom' } }]);
+    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: 'crm', path: '/api/contacts' })).rejects.toMatchObject({
+    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([{ body: { contacts: [] } }]);
+    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: 'crm', path: '/api/contacts', query: { q: 'acme', page: 2 } });
+    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');
@@ -369,6 +456,7 @@ describe('TopoloClient.listServices', () => {
                 status: 'active',
                 surface_kind: 'application',
                 launchable: true,
+                granted_permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
               },
             ],
           },
@@ -392,6 +480,7 @@ describe('TopoloClient.listServices', () => {
         status: 'active',
         surfaceKind: 'application',
         launchable: true,
+        permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
       },
     ]);
     expect(calls[0]!.url).toBe(
@@ -402,7 +491,7 @@ describe('TopoloClient.listServices', () => {
     );
   });
 
-  it('falls back to the generated snapshot on HTTP failure', async () => {
+  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' },
@@ -410,25 +499,23 @@ describe('TopoloClient.listServices', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com' },
     });
-    const out = await client.listServices();
-    expect(out.length).toBeGreaterThan(10);
-    expect(out.some((e) => e.serviceId === 'admin')).toBe(true);
-    expect(out.every((e) => typeof e.serviceId === 'string')).toBe(true);
+    await expect(client.listServices()).rejects.toBeInstanceOf(TopoloHttpError);
   });
 
-  it('resolves future API services from the live catalog during request routing', async () => {
+  it('routes bundled service aliases only after the scoped live catalog grants access', async () => {
     const { impl, calls } = stubFetch([
       {
         body: {
           data: {
             services: [
               {
-                service_id: 'srv_future',
-                app_slug: 'topolo-warehouse',
-                name: 'Warehouse',
-                base_url: 'https://warehouse.topolo.app',
-                surface_kind: 'api',
+                service_id: 'srv_mail',
+                app_slug: 'topolo-mail',
+                name: 'Topolo Mail',
+                base_url: 'https://mail.topolo.app',
+                surface_kind: 'application',
                 status: 'active',
+                granted_permissions: ['srv_mail.messages:read'],
               },
             ],
           },
@@ -443,10 +530,43 @@ describe('TopoloClient.listServices', () => {
       serviceUrls: { auth: 'https://auth.example.com' },
     });
 
-    await client.request({ service: 'warehouse', path: '/api/health' });
+    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://warehouse.topolo.app/api/health');
+    expect(calls[1]!.url).toBe('https://mail.topolo.app/api/health');
+  });
+
+  it('refuses a bundled static service that is absent from the scoped live catalog', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_crm',
+                app_slug: 'topolo-crm',
+                name: 'Topolo CRM',
+                base_url: 'https://crm-api.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+                granted_permissions: ['srv_crm.contacts:read'],
+              },
+            ],
+          },
+        },
+      },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: '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 () => {
@@ -462,6 +582,7 @@ describe('TopoloClient.listServices', () => {
                 base_url: 'https://future-app.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
+                granted_permissions: ['srv_future_app.launch:read'],
                 launchable: true,
               },
             ],
@@ -494,6 +615,7 @@ describe('TopoloClient.listServices', () => {
                 base_url: 'https://warehouse.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
+                granted_permissions: ['srv_future.read:all'],
               },
             ],
           },
@@ -520,5 +642,86 @@ describe('TopoloClient.listServices', () => {
   });
 });
 
+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' },
+    });
+    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' },
+    });
+    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');
+  });
+
+  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' },
+    });
+    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' },
+    });
+    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' },
+    });
+    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;