@topolo/sdk 0.4.6 → 0.4.8

package/src/index.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createTopolo,
+  CrmModule,
+  IdentityModule,
+  TopoloClient,
+  TopoloAuthError,
+  TopoloHttpError,
+  TopoloPermissionError,
+} from './index.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+describe('createTopolo', () => {
+  it('returns a ready client plus identity + crm module surfaces', () => {
+    const topolo = createTopolo({
+      credential: { kind: 'access_token', accessToken: 'tok' },
+      agent: AGENT,
+      fetch: vi.fn() as unknown as typeof fetch,
+    });
+
+    expect(topolo.client).toBeInstanceOf(TopoloClient);
+    expect(topolo.identity).toBeInstanceOf(IdentityModule);
+    expect(topolo.crm).toBeInstanceOf(CrmModule);
+  });
+
+  it('wires every module to the same underlying client', async () => {
+    const calls: string[] = [];
+    const impl = vi.fn(async (url: string) => {
+      calls.push(String(url));
+      if (String(url).includes('/api/services/by-slug/')) {
+        return new Response(JSON.stringify({ success: true, data: { service_id: 'service_auth' } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      if (String(url).includes('/api/services/catalog')) {
+        return new Response(JSON.stringify({ data: { services: [] } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      return new Response(
+        JSON.stringify({ data: { user: { id: 'u_1', email: 'a@b.c' } } }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }) as unknown as typeof fetch;
+
+    TopoloClient.clearServiceIdCache();
+    const topolo = createTopolo({
+      credential: { kind: 'access_token', accessToken: 'tok' },
+      agent: AGENT,
+      fetch: impl,
+      serviceIds: { auth: 'service_auth' },
+    });
+
+    const me = await topolo.identity.whoami();
+    expect(me.user.id).toBe('u_1');
+    expect(calls.some((u) => u.includes('/api/auth/me'))).toBe(true);
+  });
+});
+
+describe('package surface re-exports', () => {
+  it('re-exports the error classes from the barrel', () => {
+    expect(new TopoloAuthError('x').name).toBe('TopoloAuthError');
+    expect(new TopoloHttpError('auth', '/p', 500).name).toBe('TopoloHttpError');
+    expect(new TopoloPermissionError('nope', []).name).toBe('TopoloPermissionError');
+  });
+});

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type CredentialIntrospection,
   type TopoloDebugEvent,
   type TopoloServiceCatalogEntry,
+  type TopoloApiKeyResourceMetadata,
   type TopoloActionCatalogEntry,
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";

package/src/modules/crm.test.ts

@@ -0,0 +1,208 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from '../client.js';
+import { CrmModule } from './crm.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    if (String(url).includes('/api/services/by-slug/')) {
+      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_crm' } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(
+        JSON.stringify({
+          data: {
+            services: [
+              {
+                service_id: 'srv_crm',
+                app_slug: 'topolo-crm',
+                name: 'Topolo CRM',
+                api_base_url: 'https://crm.topolo.app',
+                launch_url: 'https://crm.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+                granted_permissions: ['srv_crm.contacts:read'],
+              },
+            ],
+          },
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }
+    const next = responses.shift() ?? { status: 200, body: { data: {} } };
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+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'),
+  );
+}
+
+function clientWith(impl: typeof fetch) {
+  return new TopoloClient({
+    credential: { kind: 'access_token', accessToken: 'tok_test' },
+    agent: AGENT,
+    fetch: impl,
+  });
+}
+
+beforeEach(() => {
+  TopoloClient.clearServiceIdCache();
+});
+
+describe('CrmModule.listContacts', () => {
+  it('maps snake_case rows into camelCase summaries and forwards query params', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          contacts: [
+            {
+              id: 'c_1',
+              first: 'Ada',
+              last: 'Lovelace',
+              email: 'ada@example.com',
+              phone: '+1',
+              company: 'Analytical',
+              lead_status: 'new',
+              lifecycle_stage: 'lead',
+              updated_at: '2026-01-01T00:00:00.000Z',
+            },
+          ],
+          total: 42,
+          page: 2,
+          pageSize: 25,
+        },
+      },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts({ q: 'ada', page: 2, pageSize: 25 });
+
+    expect(result.contacts).toEqual([
+      {
+        id: 'c_1',
+        firstName: 'Ada',
+        lastName: 'Lovelace',
+        email: 'ada@example.com',
+        phone: '+1',
+        company: 'Analytical',
+        leadStatus: 'new',
+        lifecycleStage: 'lead',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      },
+    ]);
+    expect(result.total).toBe(42);
+    expect(result.page).toBe(2);
+    expect(result.pageSize).toBe(25);
+
+    const url = new URL(requestCalls(calls)[0]!.url);
+    expect(url.pathname).toBe('/api/contacts');
+    expect(url.searchParams.get('q')).toBe('ada');
+    expect(url.searchParams.get('page')).toBe('2');
+    expect(url.searchParams.get('pageSize')).toBe('25');
+  });
+
+  it('reads rows from the data[] envelope and pagination block', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: [{ id: 'c_2' }],
+          pagination: { total: 7, page: 3, pageSize: 10 },
+        },
+      },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.contacts).toEqual([
+      {
+        id: 'c_2',
+        firstName: null,
+        lastName: null,
+        email: null,
+        phone: null,
+        company: null,
+        leadStatus: null,
+        lifecycleStage: null,
+        updatedAt: null,
+      },
+    ]);
+    expect(result.total).toBe(7);
+    expect(result.page).toBe(3);
+    expect(result.pageSize).toBe(10);
+  });
+
+  it('falls back to row count + option defaults when no metadata is returned', async () => {
+    const { impl } = stubFetch([{ body: { contacts: [{ id: 'c_3' }, { id: 'c_4' }] } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.total).toBe(2);
+    expect(result.page).toBe(1);
+    expect(result.pageSize).toBe(2);
+  });
+
+  it('returns an empty list when the response has neither contacts nor data arrays', async () => {
+    const { impl } = stubFetch([{ body: { unexpected: true } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.contacts).toEqual([]);
+    expect(result.total).toBe(0);
+  });
+});
+
+describe('CrmModule.getContact', () => {
+  it('rejects an empty contactId', async () => {
+    const { impl } = stubFetch([]);
+    const crm = new CrmModule(clientWith(impl));
+    await expect(crm.getContact('')).rejects.toThrow('contactId is required');
+  });
+
+  it('unwraps a data-enveloped contact', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { data: { id: 'c_9', first: 'Grace', last: 'Hopper' } } },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const contact = await crm.getContact('c_9');
+
+    expect(contact).toMatchObject({ id: 'c_9', firstName: 'Grace', lastName: 'Hopper' });
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/contacts/c_9');
+  });
+
+  it('accepts a bare contact object (no data envelope)', async () => {
+    const { impl } = stubFetch([{ body: { id: 'c_10', email: 'g@example.com' } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const contact = await crm.getContact('c_10');
+
+    expect(contact).toMatchObject({ id: 'c_10', email: 'g@example.com' });
+  });
+
+  it('url-encodes contact ids with special characters', async () => {
+    const { impl, calls } = stubFetch([{ body: { data: { id: 'a/b c' } } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    await crm.getContact('a/b c');
+
+    expect(requestCalls(calls)[0]!.url).toContain('/api/contacts/a%2Fb%20c');
+  });
+});

package/src/modules/identity.test.ts

@@ -0,0 +1,165 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from '../client.js';
+import { IdentityModule } from './identity.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    if (String(url).includes('/api/services/by-slug/')) {
+      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_auth' } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(JSON.stringify({ data: { services: [] } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    const next = responses.shift() ?? { status: 200, body: {} };
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+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'),
+  );
+}
+
+function clientWith(
+  impl: typeof fetch,
+  credential: { kind: 'access_token'; accessToken: string } | { kind: 'api_key'; apiKey: string } = {
+    kind: 'access_token',
+    accessToken: 'tok_test',
+  },
+) {
+  return new TopoloClient({
+    credential,
+    agent: AGENT,
+    fetch: impl,
+    serviceIds: { auth: 'service_auth' },
+  });
+}
+
+beforeEach(() => {
+  TopoloClient.clearServiceIdCache();
+});
+
+describe('IdentityModule.whoami', () => {
+  it('resolves a data-enveloped access-token identity with an organization', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            credentialType: 'access_token',
+            user: { id: 'u_1', email: 'ada@example.com', name: 'Ada', role: 'owner' },
+            organization: { id: 'org_1', slug: 'acme', name: 'Acme Inc' },
+            permissions: ['crm.contacts:read'],
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me).toEqual({
+      kind: 'access_token',
+      user: {
+        id: 'u_1',
+        email: 'ada@example.com',
+        name: 'Ada',
+        role: 'owner',
+        permissions: ['crm.contacts:read'],
+      },
+      organization: { id: 'org_1', slug: 'acme', name: 'Acme Inc' },
+    });
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/auth/me');
+  });
+
+  it('defaults api_key role to "service" and reads a bare (non-enveloped) payload', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          credentialType: 'api_key',
+          user: { id: 'svc_1', email: 'svc@example.com' },
+          organization: { id: 'org_2', slug: 'beta' },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(
+      clientWith(impl, { kind: 'api_key', apiKey: 'dak_xyz' }),
+    );
+
+    const me = await identity.whoami();
+
+    expect(me.kind).toBe('api_key');
+    expect(me.user.role).toBe('service');
+    expect(me.user.name).toBeNull();
+    // organization name falls back to slug when name is absent
+    expect(me.organization).toEqual({ id: 'org_2', slug: 'beta', name: 'beta' });
+  });
+
+  it('defaults access_token role to "member" and reads permissions from user when top-level absent', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: {
+            user: {
+              id: 'u_3',
+              email: 'm@example.com',
+              permissions: ['mail.messages:read'],
+            },
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.kind).toBe('access_token');
+    expect(me.user.role).toBe('member');
+    expect(me.user.permissions).toEqual(['mail.messages:read']);
+    expect(me.organization).toBeNull();
+  });
+
+  it('synthesizes an organization from user.orgId/orgSlug when no organization object is present', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: {
+            user: { id: 'u_4', email: 'o@example.com', orgId: 'org_9', orgSlug: 'gamma' },
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.organization).toEqual({ id: 'org_9', slug: 'gamma', name: 'gamma' });
+  });
+
+  it('defaults missing permissions to an empty array', async () => {
+    const { impl } = stubFetch([
+      { body: { data: { user: { id: 'u_5', email: 'n@example.com' } } } },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.user.permissions).toEqual([]);
+  });
+});