@topolo/sdk 0.6.0 → 0.8.0

package/src/client.test.ts

@@ -1,13 +1,36 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { TopoloClient } from './client.js';
-import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from './errors.js';
+import {
+  TopoloAuthError,
+  TopoloConfirmationRequiredError,
+  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 ?? {}), {
+    let body = next.body ?? {};
+    const parsedUrl = new URL(url);
+    if (parsedUrl.pathname === '/api/services/catalog' && parsedUrl.searchParams.has('application')) {
+      const services = (body as { data?: { services?: unknown[] } }).data?.services;
+      if (Array.isArray(services)) body = { data: { application: services[0] } };
+    }
+    if (parsedUrl.pathname === '/api/actions/catalog' && parsedUrl.searchParams.has('actionId')) {
+      const actionId = parsedUrl.searchParams.get('actionId');
+      const actions = (body as { data?: { actions?: Array<Record<string, unknown>> } }).data?.actions;
+      if (Array.isArray(actions)) {
+        body = {
+          data: {
+            action: actions.find((action) =>
+              action.action_id === actionId || action.name === actionId || action.tool_name === actionId),
+          },
+        };
+      }
+    }
+    return new Response(JSON.stringify(body), {
       status: next.status ?? 200,
       headers: { 'Content-Type': next.contentType ?? 'application/json' },
     });
@@ -52,6 +75,7 @@ const ACTION_CATALOG = {
           path: '/api/mail/mailboxes/{mailboxId}/messages',
           permission_name: 'messages:read',
           required_permission: 'app_mail.messages:read',
+          authorization_mode: 'runtime',
           input_schema: { type: 'object' },
           output_schema: {},
           read_only: true,
@@ -186,7 +210,7 @@ describe('TopoloClient.request', () => {
     });
     await expect(
       client.request({ service: 'mail', method: 'POST', path: '/api/mail/mailboxes/primary/messages', body: {} }),
-    ).rejects.toBeInstanceOf(TopoloAuthError);
+    ).rejects.toBeInstanceOf(TopoloConfirmationRequiredError);
   });
 
   it('allows mutating requests with confirm: true', async () => {
@@ -222,6 +246,76 @@ describe('TopoloClient.request', () => {
     });
   });
 
+  it('refreshes a rejected access token and retries the request once', async () => {
+    const { impl, calls } = stubFetch([
+      { status: 401, body: { error: { message: 'Expired' } } },
+      { body: { ok: true } },
+    ]);
+    const refreshCredential = vi.fn(async () => ({
+      kind: 'access_token' as const,
+      accessToken: 'fresh',
+    }));
+    const client = new TopoloClient({
+      credential: { kind: 'access_token', accessToken: 'stale' },
+      agent: AGENT,
+      fetch: impl,
+      refreshCredential,
+    });
+
+    await expect(client.request({ service: 'auth', path: '/api/me' })).resolves.toEqual({ ok: true });
+    expect(refreshCredential).toHaveBeenCalledTimes(1);
+    expect(requestCalls(calls)).toHaveLength(2);
+    expect(new Headers(requestCalls(calls)[0]!.init.headers).get('Authorization')).toBe('Bearer stale');
+    expect(new Headers(requestCalls(calls)[1]!.init.headers).get('Authorization')).toBe('Bearer fresh');
+  });
+
+  it('shares one refresh across concurrent rejected requests', async () => {
+    let resolveRefresh!: (credential: { kind: 'access_token'; accessToken: string }) => void;
+    const refreshCredential = vi.fn(() => new Promise<{ kind: 'access_token'; accessToken: string }>((resolve) => {
+      resolveRefresh = resolve;
+    }));
+    const impl = vi.fn(async (_url: string, init: RequestInit) => {
+      const authorization = new Headers(init.headers).get('Authorization');
+      return new Response(JSON.stringify(authorization === 'Bearer fresh'
+        ? { ok: true }
+        : { error: { message: 'Expired' } }), {
+        status: authorization === 'Bearer fresh' ? 200 : 401,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }) as unknown as typeof fetch;
+    const client = new TopoloClient({
+      credential: { kind: 'access_token', accessToken: 'stale' },
+      agent: AGENT,
+      fetch: impl,
+      refreshCredential,
+    });
+
+    const requests = Promise.all([
+      client.request({ service: 'auth', path: '/api/me' }),
+      client.request({ service: 'auth', path: '/api/me' }),
+    ]);
+    await vi.waitFor(() => expect(refreshCredential).toHaveBeenCalledTimes(1));
+    resolveRefresh({ kind: 'access_token', accessToken: 'fresh' });
+    await expect(requests).resolves.toEqual([{ ok: true }, { ok: true }]);
+    expect(refreshCredential).toHaveBeenCalledTimes(1);
+  });
+
+  it('never invokes token refresh for an API key 401', async () => {
+    const { impl } = stubFetch([
+      { status: 401, body: { error: { message: 'Rejected' } } },
+    ]);
+    const refreshCredential = vi.fn();
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      refreshCredential,
+    });
+
+    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toThrow('Rejected');
+    expect(refreshCredential).not.toHaveBeenCalled();
+  });
+
   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' } } },
@@ -476,6 +570,52 @@ describe('TopoloClient.getAppIdBySlug', () => {
 });
 
 describe('TopoloClient.listServices', () => {
+  it('supports bounded top-level service search and exact application lookup', async () => {
+    const minimal = {
+      id: 'app_minimal',
+      name: 'Minimal App',
+      apiBaseUrl: 'https://minimal-api.example',
+      launchUrl: 'https://minimal.example',
+      launchable: true,
+    };
+    const { impl, calls } = stubFetch([
+      { body: { services: [null, minimal], page: { nextCursor: 'cursor-2', hasMore: true } } },
+      { body: { application: minimal } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+
+    const page = await client.searchServices({ query: ' minimal ', cursor: ' cursor-1 ', limit: 2.9 });
+    expect(page).toMatchObject({
+      services: [{ appId: 'app_minimal', name: 'Minimal App', apiBaseUrl: 'https://minimal-api.example' }],
+      page: { nextCursor: 'cursor-2', hasMore: true },
+    });
+    expect(calls[0]!.url).toBe('https://developers.example/api/services/catalog?query=minimal&cursor=cursor-1&limit=2');
+
+    await expect(client.getService('  ')).rejects.toMatchObject({ code: 'unknown_service' });
+    await expect(client.getService(' app_minimal ')).resolves.toMatchObject({ appId: 'app_minimal' });
+    expect(calls[1]!.url).toBe('https://developers.example/api/services/catalog?application=app_minimal');
+  });
+
+  it('rejects malformed service catalog and exact lookup responses', async () => {
+    const { impl } = stubFetch([
+      { body: { data: {} } },
+      { body: { data: { application: null } } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+    await expect(client.searchServices()).rejects.toMatchObject({ code: 'service_catalog_unavailable' });
+    await expect(client.getService('missing')).rejects.toMatchObject({ code: 'unknown_service' });
+  });
+
   it('normalizes the live catalog and attaches the credential', async () => {
     const { impl, calls } = stubFetch([
       {
@@ -610,7 +750,7 @@ describe('TopoloClient.listServices', () => {
 
     await client.request({ service: 'mail', path: '/api/health' });
 
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog?application=mail');
     expect(calls[1]!.url).toBe('https://mail-api.topolo.app/api/health');
   });
 
@@ -645,7 +785,7 @@ describe('TopoloClient.listServices', () => {
 
     await client.request({ service: 'crm', path: '/health' });
 
-    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog?application=crm');
     expect(calls[1]!.url).toBe('https://crm-api.topolo.app/health');
   });
 
@@ -765,27 +905,29 @@ describe('TopoloClient.listServices', () => {
     });
   });
 
-  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'],
-              },
-            ],
-          },
+  it('uses bounded exact catalog resolution for repeated dynamic service calls', async () => {
+    const warehouseCatalog = {
+      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'],
+            },
+          ],
         },
       },
+    };
+    const { impl, calls } = stubFetch([
+      warehouseCatalog,
       { body: { ok: true } },
+      warehouseCatalog,
       { body: { ok: true } },
     ]);
     const client = new TopoloClient({
@@ -799,14 +941,61 @@ describe('TopoloClient.listServices', () => {
     await client.request({ service: 'warehouse', path: '/api/two' });
 
     expect(calls.map((call) => call.url)).toEqual([
-      'https://auth.example.com/api/services/catalog',
+      'https://auth.example.com/api/services/catalog?application=warehouse',
       'https://warehouse.topolo.app/api/one',
+      'https://auth.example.com/api/services/catalog?application=warehouse',
       'https://warehouse.topolo.app/api/two',
     ]);
   });
 });
 
 describe('TopoloClient action catalog', () => {
+  it('supports bounded top-level action search and rejects missing service bounds', async () => {
+    const action = structuredClone(ACTION_CATALOG.body.data.actions[0]);
+    const { impl, calls } = stubFetch([
+      { body: { actions: [null, action], page: { nextCursor: 'next-action', hasMore: true } } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+
+    await expect(client.searchActions({ service: ' ' })).rejects.toMatchObject({ code: 'service_required' });
+    await expect(client.listActions()).rejects.toMatchObject({ code: 'service_required' });
+    const page = await client.searchActions({
+      service: 'topolo-mail',
+      query: ' messages ',
+      cursor: ' action-1 ',
+      limit: 5,
+    });
+    expect(page.actions).toHaveLength(1);
+    expect(page.actions[0]?.authorizationMode).toBe('runtime');
+    expect(page.page).toEqual({ nextCursor: 'next-action', hasMore: true });
+    expect(calls[0]!.url).toBe(
+      'https://developers.example/api/actions/catalog?service=topolo-mail&query=messages&cursor=action-1&limit=5',
+    );
+  });
+
+  it('rejects malformed action searches and exact action lookups', async () => {
+    const { impl } = stubFetch([
+      { body: {} },
+      { body: { action: null } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+    await expect(client.searchActions({ service: 'topolo-mail' })).rejects.toMatchObject({
+      code: 'action_catalog_unavailable',
+    });
+    await expect(client.getAction(' ')).rejects.toMatchObject({ code: 'unknown_action' });
+    await expect(client.getAction('missing.action')).rejects.toMatchObject({ code: 'unknown_action' });
+  });
+
   it('lists scoped actions from Auth', async () => {
     const { impl, calls } = stubFetch([ACTION_CATALOG]);
     const client = new TopoloClient({
@@ -815,13 +1004,13 @@ describe('TopoloClient action catalog', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
     });
-    const actions = await client.listActions();
+    const actions = await client.listActions({ service: 'topolo-mail' });
     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');
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/actions/catalog?service=topolo-mail');
   });
 
   it('calls GET actions by mapping remaining input to query params', async () => {
@@ -832,7 +1021,7 @@ describe('TopoloClient action catalog', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
     });
-    await client.callAction('messages.list', { mailboxId: 'primary', q: 'Ada', page: 2 });
+    await client.callAction('app_mail.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');
@@ -842,6 +1031,47 @@ describe('TopoloClient action catalog', () => {
     expect(headers.get('X-Topolo-Action-Name')).toBe('messages.list');
   });
 
+  it('forwards resource context when calling an action', 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(
+      'app_mail.messages.list',
+      { mailboxId: 'primary' },
+      { resource: { resourceType: 'workspace', resourceId: 'workspace_123' } },
+    );
+
+    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
+    expect(headers.get('X-Topolo-Resource-Type')).toBe('workspace');
+    expect(headers.get('X-Topolo-Resource-ID')).toBe('workspace_123');
+  });
+
+  it('calls the action target origin without an app-level service lookup', async () => {
+    const targetedCatalog = structuredClone(ACTION_CATALOG);
+    const first = targetedCatalog.body.data.actions[0] as Record<string, unknown>;
+    first.target_key = 'api';
+    first.api_base_url = 'https://mail-actions.example';
+    const { impl, calls } = stubFetch([targetedCatalog, { 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('app_mail.messages.list', { mailboxId: 'primary' });
+
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://auth.example.com/api/actions/catalog?actionId=app_mail.messages.list',
+      'https://mail-actions.example/api/mail/mailboxes/primary/messages',
+    ]);
+  });
+
   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({
@@ -850,7 +1080,7 @@ describe('TopoloClient action catalog', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
     });
-    await client.callAction('topolo_mail_messages_get', {
+    await client.callAction('app_mail.messages.get', {
       mailboxId: 'primary',
       messageId: 'm 1',
       includeDeleted: false,
@@ -871,8 +1101,41 @@ describe('TopoloClient action catalog', () => {
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
     });
     await expect(
-      client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }),
-    ).rejects.toBeInstanceOf(TopoloAuthError);
+      client.callAction('app_mail.messages.send', { mailboxId: 'primary', subject: 'Hello' }),
+    ).rejects.toBeInstanceOf(TopoloConfirmationRequiredError);
+  });
+
+  it('enforces confirmation metadata even on a GET action', async () => {
+    const catalog = structuredClone(ACTION_CATALOG);
+    const action = catalog.body.data.actions[0]!;
+    action.requires_confirmation = true;
+    (action as Record<string, unknown>).agent_access = 'confirm';
+    const { impl } = stubFetch([catalog]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+
+    await expect(client.callAction(action.action_id, { mailboxId: 'primary' }))
+      .rejects.toBeInstanceOf(TopoloConfirmationRequiredError);
+  });
+
+  it('refuses actions whose developer config disables agent access', async () => {
+    const catalog = structuredClone(ACTION_CATALOG);
+    const action = catalog.body.data.actions[0]!;
+    (action as Record<string, unknown>).agent_access = 'off';
+    const { impl } = stubFetch([catalog]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { developers: 'https://developers.example' },
+    });
+
+    await expect(client.callAction(action.action_id, { mailboxId: 'primary' }, { confirm: true }))
+      .rejects.toBeInstanceOf(TopoloPermissionError);
   });
 
   it('sends remaining input as the body when a mutating action is confirmed', async () => {
@@ -883,7 +1146,7 @@ describe('TopoloClient action catalog', () => {
       fetch: impl,
       serviceUrls: { auth: 'https://auth.example.com', developers: 'https://auth.example.com' },
     });
-    await client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }, { confirm: true });
+    await client.callAction('app_mail.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' });