@topolo/sdk 0.2.8 → 0.2.10

package/src/index.ts

@@ -43,6 +43,23 @@ export {
   type ListContactsResult,
 } from "./modules/crm.js";
 export { IdentityModule } from "./modules/identity.js";
+export {
+  P2PModule,
+  type P2PCapability,
+  type P2PPricingModel,
+  type PublishCapabilityInput,
+  type P2PActionRow,
+  type P2PActionRun,
+  type P2PActionRequestInput,
+  type P2PActionRequestResult,
+  type P2PActionDetail,
+  type P2PHold,
+  type P2PLedgerEntry,
+  type P2PPolicy,
+  type P2PConnection,
+  type P2PSettlementGroup,
+  type P2PSettlementBatch,
+} from "./modules/p2p.js";
 export {
   TopoloOAuth,
   type OAuthHelperOptions,

package/src/modules/p2p.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from '../client.js';
+import { P2PModule } from './p2p.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 });
+    const next = responses.shift() ?? { status: 200, body: { success: true, data: {} } };
+    return new Response(JSON.stringify(next.body ?? { success: true, data: {} }), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+function clientWith(impl: typeof fetch) {
+  return new TopoloClient({
+    credential: { kind: 'access_token', accessToken: 'tok_test' },
+    agent: AGENT,
+    fetch: impl,
+  });
+}
+
+describe('P2PModule.listDirectory', () => {
+  it('GETs /api/directory/capabilities and unwraps the envelope', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          success: true,
+          data: {
+            capabilities: [
+              {
+                capability_id: 'cap_1',
+                publisher_org_id: 'org_a',
+                app_id: 'app_x',
+                service_id: 'srv_x',
+                name: 'Demo',
+                description: 'A capability',
+                category: 'other',
+                pricing_model: 'free',
+                pricing_amount_minor: null,
+                currency: null,
+                requires_human_approval: false,
+                supported_contexts: ['agent'],
+                trust_level: 'standard',
+                source_revision: 'rev_1',
+                synced_at: 1,
+              },
+            ],
+          },
+        },
+      },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+
+    const capabilities = await p2p.listDirectory({ limit: 10 });
+    expect(capabilities).toHaveLength(1);
+    expect(capabilities[0]!.capability_id).toBe('cap_1');
+    const url = new URL(calls[0]!.url);
+    expect(url.pathname).toBe('/api/directory/capabilities');
+    expect(url.searchParams.get('limit')).toBe('10');
+    expect((calls[0]!.init.method ?? 'GET').toUpperCase()).toBe('GET');
+  });
+});
+
+describe('P2PModule.publishCapability', () => {
+  it('POSTs to the internal sync route with the publisher_org_id and acting_for_org_id default', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          success: true,
+          data: {
+            capability: {
+              capability_id: 'cap_z',
+              publisher_org_id: 'org_p',
+              app_id: 'app_x',
+              service_id: 'srv_x',
+              name: 'Demo',
+              description: 'A capability',
+              category: 'other',
+              pricing_model: 'fixed',
+              pricing_amount_minor: 500,
+              currency: 'USD',
+              requires_human_approval: false,
+              supported_contexts: ['agent'],
+              trust_level: 'standard',
+              source_revision: 'rev_2',
+              synced_at: 1,
+            },
+          },
+        },
+      },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+
+    const capability = await p2p.publishCapability({
+      capability_id: 'cap_z',
+      publisher_org_id: 'org_p',
+      app_id: 'app_x',
+      service_id: 'srv_x',
+      name: 'Demo',
+      description: 'A capability',
+      category: 'other',
+      pricing_model: 'fixed',
+      pricing_amount_minor: 500,
+      currency: 'USD',
+      supported_contexts: ['agent'],
+      public_directory_visible: true,
+      source_revision: 'rev_2',
+    });
+    expect(capability.capability_id).toBe('cap_z');
+
+    const sent = JSON.parse(String(calls[0]!.init.body));
+    expect(sent.publisher_org_id).toBe('org_p');
+    expect(sent.acting_for_org_id).toBe('org_p');
+    expect(sent.public_directory_visible).toBe(true);
+    expect(sent.requires_human_approval).toBe(false);
+    expect(sent.trust_level).toBe('standard');
+    const url = new URL(calls[0]!.url);
+    expect(url.pathname).toBe('/api/p2p/internal/capabilities/sync');
+    expect((calls[0]!.init.method ?? '').toUpperCase()).toBe('POST');
+  });
+
+  it('honours an explicit acting_for_org_id when the platform key is publishing for another org', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { success: true, data: { capability: null } } },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    await p2p.publishCapability({
+      capability_id: 'cap_other',
+      publisher_org_id: 'org_target',
+      app_id: 'app_x',
+      service_id: 'srv_x',
+      name: 'Demo',
+      description: '...',
+      category: 'other',
+      pricing_model: 'free',
+      supported_contexts: ['agent'],
+      public_directory_visible: true,
+      source_revision: 'rev_1',
+      acting_for_org_id: 'org_target',
+    });
+    const sent = JSON.parse(String(calls[0]!.init.body));
+    expect(sent.acting_for_org_id).toBe('org_target');
+  });
+});
+
+describe('P2PModule.requestAction', () => {
+  it('rejects without an idempotency_key', async () => {
+    const { impl } = stubFetch([]);
+    const p2p = new P2PModule(clientWith(impl));
+    await expect(
+      p2p.requestAction({ capability_id: 'cap_1', idempotency_key: '', inputs: {} }),
+    ).rejects.toThrow(/idempotency_key/);
+  });
+
+  it('returns the worker decision payload', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          success: true,
+          data: {
+            decision: 'auto_accepted',
+            idempotent: false,
+            request: { request_id: 'req_1', state: 'auto_accepted' },
+            run: null,
+          },
+        },
+      },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const result = await p2p.requestAction({
+      capability_id: 'cap_1',
+      idempotency_key: 'key_1',
+      inputs: { foo: 'bar' },
+    });
+    expect(result.decision).toBe('auto_accepted');
+    expect(result.idempotent).toBe(false);
+    expect(result.request.request_id).toBe('req_1');
+  });
+});
+
+describe('P2PModule.getCapability', () => {
+  it('returns null on a 404 from the worker', async () => {
+    const { impl } = stubFetch([{ status: 404, body: { success: false, error: 'capability_not_found' } }]);
+    const p2p = new P2PModule(clientWith(impl));
+    const capability = await p2p.getCapability('cap_missing');
+    expect(capability).toBeNull();
+  });
+});
+
+describe('P2PModule.releaseHold', () => {
+  it('POSTs the resolution + reason and returns hold + cancel entries', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          success: true,
+          data: {
+            hold: { hold_id: 'hold_1', status: 'released' },
+            resolution: 'seller',
+            cancel_entries: [{ entry_id: 'led_1', amount_minor: 500 }],
+          },
+        },
+      },
+    ]);
+    const p2p = new P2PModule(clientWith(impl));
+    const result = await p2p.releaseHold('hold_1', 'seller', { reason: 'arbitration' });
+    expect(result.resolution).toBe('seller');
+    expect(result.cancel_entries[0]!.entry_id).toBe('led_1');
+    const sent = JSON.parse(String(calls[0]!.init.body));
+    expect(sent.resolution).toBe('seller');
+    expect(sent.reason).toBe('arbitration');
+  });
+});

package/src/modules/p2p.ts

@@ -0,0 +1,451 @@
+import type { TopoloClient } from '../client.js';
+
+export type P2PPricingModel = 'free' | 'fixed' | 'metered' | 'quote' | 'invoice';
+
+export interface P2PCapability {
+  capability_id: string;
+  publisher_org_id: string;
+  app_id: string;
+  service_id: string;
+  name: string;
+  description: string;
+  category: string;
+  pricing_model: P2PPricingModel;
+  pricing_amount_minor: number | null;
+  currency: string | null;
+  requires_human_approval: boolean;
+  supported_contexts: string[];
+  trust_level: string;
+  source_revision: string;
+  synced_at: number;
+  input_schema?: Record<string, unknown>;
+  output_schema?: Record<string, unknown>;
+}
+
+export interface PublishCapabilityInput {
+  capability_id: string;
+  publisher_org_id: string;
+  app_id: string;
+  service_id: string;
+  name: string;
+  description: string;
+  category: string;
+  pricing_model: P2PPricingModel;
+  pricing_amount_minor?: number | null;
+  currency?: string | null;
+  requires_human_approval?: boolean;
+  supported_contexts: string[];
+  trust_level?: string;
+  public_directory_visible: boolean;
+  source_revision: string;
+  input_schema?: Record<string, unknown>;
+  output_schema?: Record<string, unknown>;
+  /** Set when the caller is the platform P2P service publishing on behalf of another org. */
+  acting_for_org_id?: string;
+}
+
+export interface P2PActionRequestInput {
+  capability_id: string;
+  idempotency_key: string;
+  inputs?: Record<string, unknown>;
+}
+
+export interface P2PActionRow {
+  request_id: string;
+  buyer_org_id: string;
+  seller_org_id: string;
+  capability_id: string;
+  initiating_principal_id: string;
+  inputs: Record<string, unknown>;
+  pricing_snapshot: Record<string, unknown>;
+  state: string;
+  policy_decision_id: string | null;
+  idempotency_key: string;
+  created_at: number;
+  updated_at: number;
+  capability: {
+    name: string | null;
+    category: string | null;
+    pricing_model: string | null;
+    pricing_amount_minor: number | null;
+    currency: string | null;
+  };
+  run: P2PActionRun | null;
+}
+
+export interface P2PActionRun {
+  run_id: string;
+  state: string;
+  result: Record<string, unknown> | null;
+  error: string | null;
+  started_at: number | null;
+  completed_at: number | null;
+  updated_at: number;
+}
+
+export interface P2PActionRequestResult {
+  decision: string;
+  idempotent: boolean;
+  request: P2PActionRow;
+  run: P2PActionRun | null;
+}
+
+export interface P2PActionDetail {
+  action: P2PActionRow;
+  policy_decision: {
+    decision_id: string;
+    decision: string;
+    rationale: string;
+    policy_snapshot: Record<string, unknown>;
+    created_at: number;
+  } | null;
+  ledger_entries: P2PLedgerEntry[];
+  holds: P2PHold[];
+}
+
+export interface P2PHold {
+  hold_id: string;
+  request_id: string;
+  buyer_org_id: string;
+  seller_org_id: string;
+  ledger_entry_id: string | null;
+  reason: string;
+  status: 'active' | 'released' | 'disputed' | 'expired';
+  release_after: number | null;
+  released_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface P2PLedgerEntry {
+  entry_id: string;
+  request_id: string;
+  capability_id: string;
+  pricing_component: string;
+  buyer_org_id: string;
+  seller_org_id: string;
+  initiating_principal_id: string;
+  executing_principal_id: string;
+  policy_decision_id: string;
+  amount_minor: number;
+  currency: string;
+  audit_correlation_id: string;
+  settlement_batch_id: string | null;
+  created_at: number;
+}
+
+export interface P2PPolicy {
+  organization_id: string;
+  auto_approve_under_minor: number;
+  agent_spend_limit_minor_per_day: number;
+  human_approval_threshold_minor: number;
+  unknown_counterparty_requires_approval: boolean;
+  blocked_capability_ids: string[];
+  trusted_counterparty_org_ids: string[];
+  updated_at: number | null;
+}
+
+export interface P2PConnection {
+  connection_id: string;
+  organization_id?: string;
+  counterparty_org_id: string;
+  status: 'pending' | 'active' | 'suspended' | 'revoked';
+  initiated_by_principal_id: string;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface P2PSettlementGroup {
+  buyer_org_id: string;
+  seller_org_id: string;
+  currency: string;
+  total_minor: number;
+  line_items: Array<{
+    entry_id: string;
+    request_id: string;
+    capability_id: string;
+    pricing_component: string;
+    amount_minor: number;
+    audit_correlation_id: string;
+  }>;
+}
+
+export interface P2PSettlementBatch {
+  batch_id: string;
+  buyer_org_id: string;
+  seller_org_id: string;
+  currency: string;
+  total_minor: number;
+  trigger: string;
+  pay_settlement_id: string | null;
+  status: string;
+  created_at: number;
+  updated_at: number;
+}
+
+type EnvelopeData<T> = { data: T };
+
+/**
+ * P2P module — typed wrapper over the TopoloP2P HTTP API.
+ *
+ * Cross-org isolation: `requestAction`, `respondAction`, `completeAction`,
+ * etc. all derive the buyer/seller org from the auth credential. There is
+ * intentionally no `orgId` parameter on per-org reads.
+ *
+ * Mutating calls go through TopoloClient's `confirm: true` write guardrail.
+ */
+export class P2PModule {
+  constructor(private readonly client: TopoloClient) {}
+
+  // Directory ----------------------------------------------------------------
+
+  async listDirectory(options: { limit?: number } = {}): Promise<P2PCapability[]> {
+    const res = await this.client.request<EnvelopeData<{ capabilities: P2PCapability[] }>>({
+      service: 'p2p',
+      path: '/api/directory/capabilities',
+      query: { limit: options.limit },
+    });
+    return res.data.capabilities;
+  }
+
+  async getCapability(capabilityId: string): Promise<P2PCapability | null> {
+    if (!capabilityId) throw new Error('capabilityId is required');
+    try {
+      const res = await this.client.request<EnvelopeData<{ capability: P2PCapability }>>({
+        service: 'p2p',
+        path: `/api/directory/capabilities/${encodeURIComponent(capabilityId)}`,
+      });
+      return res.data.capability;
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async publishCapability(input: PublishCapabilityInput): Promise<P2PCapability> {
+    const res = await this.client.request<EnvelopeData<{ capability: P2PCapability }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: '/api/p2p/internal/capabilities/sync',
+      body: {
+        capability_id: input.capability_id,
+        publisher_org_id: input.publisher_org_id,
+        app_id: input.app_id,
+        service_id: input.service_id,
+        name: input.name,
+        description: input.description,
+        category: input.category,
+        pricing_model: input.pricing_model,
+        pricing_amount_minor: input.pricing_amount_minor ?? null,
+        currency: input.currency ?? null,
+        requires_human_approval: input.requires_human_approval ?? false,
+        supported_contexts: input.supported_contexts,
+        trust_level: input.trust_level ?? 'standard',
+        public_directory_visible: input.public_directory_visible,
+        source_revision: input.source_revision,
+        input_schema: input.input_schema ?? {},
+        output_schema: input.output_schema ?? {},
+        acting_for_org_id: input.acting_for_org_id ?? input.publisher_org_id,
+      },
+      confirm: true,
+    });
+    return res.data.capability;
+  }
+
+  // Actions ------------------------------------------------------------------
+
+  async listActions(options: { state?: string; limit?: number } = {}): Promise<P2PActionRow[]> {
+    const res = await this.client.request<EnvelopeData<{ actions: P2PActionRow[] }>>({
+      service: 'p2p',
+      path: '/api/actions',
+      query: { state: options.state, limit: options.limit },
+    });
+    return res.data.actions;
+  }
+
+  async getAction(requestId: string): Promise<P2PActionDetail | null> {
+    if (!requestId) throw new Error('requestId is required');
+    try {
+      const res = await this.client.request<EnvelopeData<P2PActionDetail>>({
+        service: 'p2p',
+        path: `/api/actions/${encodeURIComponent(requestId)}`,
+      });
+      return res.data;
+    } catch (err) {
+      if (isNotFound(err)) return null;
+      throw err;
+    }
+  }
+
+  async requestAction(input: P2PActionRequestInput): Promise<P2PActionRequestResult> {
+    if (!input.capability_id) throw new Error('capability_id is required');
+    if (!input.idempotency_key) throw new Error('idempotency_key is required');
+    const res = await this.client.request<EnvelopeData<P2PActionRequestResult>>({
+      service: 'p2p',
+      method: 'POST',
+      path: '/api/actions/request',
+      body: {
+        capability_id: input.capability_id,
+        idempotency_key: input.idempotency_key,
+        inputs: input.inputs ?? {},
+      },
+      confirm: true,
+    });
+    return res.data;
+  }
+
+  async respondAction(
+    requestId: string,
+    response: 'accepted' | 'rejected' | 'approved' | 'quoted',
+    extras: Record<string, unknown> = {},
+  ): Promise<P2PActionRow> {
+    if (!requestId) throw new Error('requestId is required');
+    const res = await this.client.request<EnvelopeData<{ request: P2PActionRow }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: `/api/actions/${encodeURIComponent(requestId)}/respond`,
+      body: { response, ...extras },
+      confirm: true,
+    });
+    return res.data.request;
+  }
+
+  async completeAction(requestId: string, result: Record<string, unknown> = {}): Promise<P2PActionRow> {
+    if (!requestId) throw new Error('requestId is required');
+    const res = await this.client.request<EnvelopeData<{ request: P2PActionRow }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: `/api/actions/${encodeURIComponent(requestId)}/complete`,
+      body: { result },
+      confirm: true,
+    });
+    return res.data.request;
+  }
+
+  async disputeAction(requestId: string, reason: string): Promise<P2PActionRow> {
+    if (!requestId) throw new Error('requestId is required');
+    const res = await this.client.request<EnvelopeData<{ request: P2PActionRow }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: `/api/actions/${encodeURIComponent(requestId)}/dispute`,
+      body: { reason },
+      confirm: true,
+    });
+    return res.data.request;
+  }
+
+  // Policy + connections + ledger + settlement -----------------------------
+
+  async getPolicy(): Promise<P2PPolicy> {
+    const res = await this.client.request<EnvelopeData<{ policy: P2PPolicy }>>({
+      service: 'p2p',
+      path: '/api/policies',
+    });
+    return res.data.policy;
+  }
+
+  async updatePolicy(policy: Partial<Omit<P2PPolicy, 'organization_id' | 'updated_at'>>): Promise<P2PPolicy> {
+    const res = await this.client.request<EnvelopeData<{ policy: P2PPolicy }>>({
+      service: 'p2p',
+      method: 'PUT',
+      path: '/api/policies',
+      body: policy,
+      confirm: true,
+    });
+    return res.data.policy;
+  }
+
+  async listConnections(): Promise<P2PConnection[]> {
+    const res = await this.client.request<EnvelopeData<{ connections: P2PConnection[] }>>({
+      service: 'p2p',
+      path: '/api/connections',
+    });
+    return res.data.connections;
+  }
+
+  async createConnection(
+    counterpartyOrgId: string,
+    options: { status?: 'pending' | 'active' | 'suspended' } = {},
+  ): Promise<P2PConnection> {
+    if (!counterpartyOrgId) throw new Error('counterpartyOrgId is required');
+    const res = await this.client.request<EnvelopeData<{ connection: P2PConnection }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: '/api/connections',
+      body: { counterparty_org_id: counterpartyOrgId, status: options.status ?? 'active' },
+      confirm: true,
+    });
+    return res.data.connection;
+  }
+
+  async revokeConnection(connectionId: string): Promise<void> {
+    if (!connectionId) throw new Error('connectionId is required');
+    await this.client.request({
+      service: 'p2p',
+      method: 'DELETE',
+      path: `/api/connections/${encodeURIComponent(connectionId)}`,
+      confirm: true,
+    });
+  }
+
+  async listLedger(): Promise<P2PLedgerEntry[]> {
+    const res = await this.client.request<EnvelopeData<{ ledger_entries: P2PLedgerEntry[] }>>({
+      service: 'p2p',
+      path: '/api/ledger',
+    });
+    return res.data.ledger_entries;
+  }
+
+  async previewSettlements(
+    filters: Partial<{ buyer_org_id: string; seller_org_id: string; currency: string }> = {},
+  ): Promise<P2PSettlementGroup[]> {
+    const res = await this.client.request<EnvelopeData<{ groups: P2PSettlementGroup[] }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: '/api/settlements/preview',
+      body: filters,
+      confirm: true,
+    });
+    return res.data.groups;
+  }
+
+  async createSettlement(
+    filters: Partial<{
+      buyer_org_id: string;
+      seller_org_id: string;
+      currency: string;
+      trigger: 'threshold' | 'schedule' | 'manual' | 'invoice' | 'delivery';
+    }> = {},
+  ): Promise<{ batch: P2PSettlementBatch; group: P2PSettlementGroup }> {
+    const res = await this.client.request<EnvelopeData<{ batch: P2PSettlementBatch; group: P2PSettlementGroup }>>({
+      service: 'p2p',
+      method: 'POST',
+      path: '/api/settlements/create',
+      body: { trigger: 'manual', ...filters },
+      confirm: true,
+    });
+    return res.data;
+  }
+
+  async releaseHold(
+    holdId: string,
+    resolution: 'buyer' | 'seller',
+    options: { reason?: string } = {},
+  ): Promise<{ hold: P2PHold; resolution: 'buyer' | 'seller'; cancel_entries: P2PLedgerEntry[] }> {
+    if (!holdId) throw new Error('holdId is required');
+    const res = await this.client.request<
+      EnvelopeData<{ hold: P2PHold; resolution: 'buyer' | 'seller'; cancel_entries: P2PLedgerEntry[] }>
+    >({
+      service: 'p2p',
+      method: 'POST',
+      path: `/api/holds/${encodeURIComponent(holdId)}/release`,
+      body: { resolution, reason: options.reason ?? null },
+      confirm: true,
+    });
+    return res.data;
+  }
+}
+
+function isNotFound(err: unknown): boolean {
+  return Boolean(err && typeof err === 'object' && 'status' in err && (err as { status?: number }).status === 404);
+}