@topolo/sdk 0.4.7 → 0.4.8

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([]);
+  });
+});

package/src/modules/p2p.test.ts

@@ -255,4 +255,290 @@ describe('P2PModule.releaseHold', () => {
     expect(sent.resolution).toBe('seller');
     expect(sent.reason).toBe('arbitration');
   });
+
+  it('rejects an empty holdId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.releaseHold('', 'buyer')).rejects.toThrow('holdId is required');
+  });
+
+  it('defaults reason to null when omitted', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { hold: { hold_id: 'h2' }, resolution: 'buyer', cancel_entries: [] } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.releaseHold('h2', 'buyer');
+    const sent = JSON.parse(String(requestCalls(calls)[0]!.init.body));
+    expect(sent.reason).toBeNull();
+  });
+});
+
+describe('P2PModule.getCapability (additional)', () => {
+  it('rejects an empty capabilityId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.getCapability('')).rejects.toThrow('capabilityId is required');
+  });
+
+  it('returns the unwrapped capability on success', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { capability: { capability_id: 'cap_ok' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const cap = await p2p.getCapability('cap ok/1');
+    expect(cap!.capability_id).toBe('cap_ok');
+    expect(requestCalls(calls)[0]!.url).toContain('/api/directory/capabilities/cap%20ok%2F1');
+  });
+
+  it('rethrows non-404 errors', async () => {
+    const { impl } = stubFetch([{ status: 500, body: { success: false, error: 'boom' } }]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.getCapability('cap_x')).rejects.toThrow();
+  });
+});
+
+describe('P2PModule.listActions', () => {
+  it('GETs /api/actions forwarding state + limit', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { actions: [{ request_id: 'req_1' }] } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const actions = await p2p.listActions({ state: 'pending', limit: 5 });
+    expect(actions).toHaveLength(1);
+    const url = new URL(requestCalls(calls)[0]!.url);
+    expect(url.pathname).toBe('/api/actions');
+    expect(url.searchParams.get('state')).toBe('pending');
+    expect(url.searchParams.get('limit')).toBe('5');
+  });
+});
+
+describe('P2PModule.getAction', () => {
+  it('rejects an empty requestId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.getAction('')).rejects.toThrow('requestId is required');
+  });
+
+  it('returns the action detail on success', async () => {
+    const { impl } = stubFetch([
+      { body: { success: true, data: { request: { request_id: 'req_2' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const detail = await p2p.getAction('req_2');
+    expect(detail).toMatchObject({ request: { request_id: 'req_2' } });
+  });
+
+  it('returns null on 404', async () => {
+    const { impl } = stubFetch([{ status: 404, body: { success: false, error: 'not_found' } }]);
+    const p2p = new P2PModule(clientWith(impl));
+    expect(await p2p.getAction('req_missing')).toBeNull();
+  });
+});
+
+describe('P2PModule.requestAction (validation + happy path)', () => {
+  it('rejects a missing capability_id', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(
+      p2p.requestAction({ capability_id: '', idempotency_key: 'k', inputs: {} }),
+    ).rejects.toThrow('capability_id is required');
+  });
+
+  it('POSTs the request and defaults inputs to {}', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { request_id: 'req_new', status: 'requested' } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const result = await p2p.requestAction({ capability_id: 'cap_1', idempotency_key: 'idem_1' });
+    expect(result).toMatchObject({ request_id: 'req_new' });
+    const call = requestCalls(calls)[0]!;
+    expect(new URL(call.url).pathname).toBe('/api/actions/request');
+    const sent = JSON.parse(String(call.init.body));
+    expect(sent.idempotency_key).toBe('idem_1');
+    expect(sent.inputs).toEqual({});
+  });
+});
+
+describe('P2PModule.respondAction / completeAction / disputeAction', () => {
+  it('respondAction POSTs response + extras and unwraps request', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { request: { request_id: 'req_3', state: 'accepted' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const row = await p2p.respondAction('req_3', 'accepted', { quote_minor: 100 });
+    expect(row).toMatchObject({ request_id: 'req_3', state: 'accepted' });
+    const call = requestCalls(calls)[0]!;
+    expect(new URL(call.url).pathname).toBe('/api/actions/req_3/respond');
+    const sent = JSON.parse(String(call.init.body));
+    expect(sent.response).toBe('accepted');
+    expect(sent.quote_minor).toBe(100);
+  });
+
+  it('respondAction rejects an empty requestId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.respondAction('', 'rejected')).rejects.toThrow('requestId is required');
+  });
+
+  it('completeAction POSTs the result payload', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { request: { request_id: 'req_4' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.completeAction('req_4', { output: 'done' });
+    const call = requestCalls(calls)[0]!;
+    expect(new URL(call.url).pathname).toBe('/api/actions/req_4/complete');
+    expect(JSON.parse(String(call.init.body)).result).toEqual({ output: 'done' });
+  });
+
+  it('completeAction rejects an empty requestId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.completeAction('')).rejects.toThrow('requestId is required');
+  });
+
+  it('disputeAction POSTs the reason', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { request: { request_id: 'req_5' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.disputeAction('req_5', 'wrong output');
+    const call = requestCalls(calls)[0]!;
+    expect(new URL(call.url).pathname).toBe('/api/actions/req_5/dispute');
+    expect(JSON.parse(String(call.init.body)).reason).toBe('wrong output');
+  });
+
+  it('disputeAction rejects an empty requestId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.disputeAction('', 'reason')).rejects.toThrow('requestId is required');
+  });
+});
+
+describe('P2PModule.getPolicy / updatePolicy', () => {
+  it('getPolicy GETs /api/policies and unwraps the policy', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { policy: { organization_id: 'org_a', auto_accept: false } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const policy = await p2p.getPolicy();
+    expect(policy).toMatchObject({ organization_id: 'org_a' });
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/policies');
+  });
+
+  it('updatePolicy PUTs the partial policy', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { policy: { organization_id: 'org_a', auto_accept: true } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const policy = await p2p.updatePolicy({ auto_accept: true } as never);
+    expect(policy).toMatchObject({ auto_accept: true });
+    const call = requestCalls(calls)[0]!;
+    expect((call.init.method ?? '').toUpperCase()).toBe('PUT');
+    expect(JSON.parse(String(call.init.body)).auto_accept).toBe(true);
+  });
+});
+
+describe('P2PModule connections', () => {
+  it('listConnections GETs /api/connections', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { connections: [{ connection_id: 'conn_1' }] } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const conns = await p2p.listConnections();
+    expect(conns).toHaveLength(1);
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/connections');
+  });
+
+  it('createConnection POSTs counterparty + default active status', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { connection: { connection_id: 'conn_2', status: 'active' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const conn = await p2p.createConnection('org_other');
+    expect(conn.status).toBe('active');
+    const sent = JSON.parse(String(requestCalls(calls)[0]!.init.body));
+    expect(sent.counterparty_org_id).toBe('org_other');
+    expect(sent.status).toBe('active');
+  });
+
+  it('createConnection honors an explicit status', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { connection: { connection_id: 'conn_3', status: 'pending' } } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.createConnection('org_other', { status: 'pending' });
+    expect(JSON.parse(String(requestCalls(calls)[0]!.init.body)).status).toBe('pending');
+  });
+
+  it('createConnection rejects an empty counterpartyOrgId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.createConnection('')).rejects.toThrow('counterpartyOrgId is required');
+  });
+
+  it('revokeConnection DELETEs the encoded connection id', async () => {
+    const { impl, calls } = stubFetch([{ body: { success: true, data: {} } }]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.revokeConnection('conn/9');
+    const call = requestCalls(calls)[0]!;
+    expect((call.init.method ?? '').toUpperCase()).toBe('DELETE');
+    expect(call.url).toContain('/api/connections/conn%2F9');
+  });
+
+  it('revokeConnection rejects an empty connectionId', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(p2p.revokeConnection('')).rejects.toThrow('connectionId is required');
+  });
+});
+
+describe('P2PModule ledger + settlements', () => {
+  it('listLedger GETs /api/ledger and unwraps entries', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { ledger_entries: [{ entry_id: 'led_1' }] } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const entries = await p2p.listLedger();
+    expect(entries).toHaveLength(1);
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/ledger');
+  });
+
+  it('previewSettlements POSTs filters and unwraps groups', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { groups: [{ buyer_org_id: 'org_b', seller_org_id: 'org_s' }] } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const groups = await p2p.previewSettlements({ currency: 'USD' });
+    expect(groups).toHaveLength(1);
+    const call = requestCalls(calls)[0]!;
+    expect(new URL(call.url).pathname).toBe('/api/settlements/preview');
+    expect(JSON.parse(String(call.init.body)).currency).toBe('USD');
+  });
+
+  it('createSettlement defaults trigger to manual and unwraps batch + group', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          success: true,
+          data: { batch: { batch_id: 'bat_1' }, group: { buyer_org_id: 'org_b' } },
+        },
+      },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const result = await p2p.createSettlement({ buyer_org_id: 'org_b' });
+    expect(result.batch.batch_id).toBe('bat_1');
+    const sent = JSON.parse(String(requestCalls(calls)[0]!.init.body));
+    expect(sent.trigger).toBe('manual');
+    expect(sent.buyer_org_id).toBe('org_b');
+  });
+
+  it('createSettlement honors an explicit trigger override', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { batch: { batch_id: 'bat_2' }, group: {} } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.createSettlement({ trigger: 'schedule' });
+    expect(JSON.parse(String(requestCalls(calls)[0]!.init.body)).trigger).toBe('schedule');
+  });
 });