@topolo/sdk 0.7.0 → 0.8.1

package/src/errors.ts

@@ -1,39 +0,0 @@
-export class TopoloSdkError extends Error {
-  readonly code: string;
-  constructor(code: string, message: string) {
-    super(message);
-    this.name = 'TopoloSdkError';
-    this.code = code;
-  }
-}
-
-export class TopoloAuthError extends TopoloSdkError {
-  constructor(message: string, code: string = 'auth_error') {
-    super(code, message);
-    this.name = 'TopoloAuthError';
-  }
-}
-
-export class TopoloPermissionError extends TopoloSdkError {
-  readonly required: string[];
-  constructor(message: string, required: string[]) {
-    super('permission_denied', message);
-    this.name = 'TopoloPermissionError';
-    this.required = required;
-  }
-}
-
-export class TopoloHttpError extends TopoloSdkError {
-  readonly status: number;
-  readonly body: unknown;
-  readonly service: string;
-  readonly path: string;
-  constructor(service: string, path: string, status: number, body: unknown, message?: string) {
-    super('http_error', message ?? `HTTP ${status} from ${service}${path}`);
-    this.name = 'TopoloHttpError';
-    this.status = status;
-    this.body = body;
-    this.service = service;
-    this.path = path;
-  }
-}

package/src/index.test.ts

@@ -1,69 +0,0 @@
-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: { app_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.clearAppIdCache();
-    const topolo = createTopolo({
-      credential: { kind: 'access_token', accessToken: 'tok' },
-      agent: AGENT,
-      fetch: impl,
-      appIds: { 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, null).name).toBe('TopoloHttpError');
-    expect(new TopoloPermissionError('nope', []).name).toBe('TopoloPermissionError');
-  });
-});

package/src/index.ts

@@ -1,125 +0,0 @@
-export {
-  TopoloClient,
-  type TopoloClientOptions,
-  type RequestOptions,
-  type CredentialIntrospection,
-  type TopoloDebugEvent,
-  type TopoloServiceCatalogEntry,
-  type TopoloApiKeyResourceMetadata,
-  type TopoloActionCatalogEntry,
-} from "./client.js";
-export type { TopoloCredential, AgentIdentity } from "./auth.js";
-export {
-  DEFAULT_APP_URLS,
-  APPLICATIONS,
-  APPLICATION_REQUIREMENTS,
-  APPLICATION_REQUIREMENTS_VERSION,
-  auditAllApplicationRequirements,
-  auditApplicationRequirements,
-  applicationRequirementScopes,
-  requirementsForApplication,
-  resolveCatalogServiceUrl,
-  resolveServiceUrl,
-  type ApplicationCatalogEntry,
-  type ApplicationDeployTarget,
-  type ApplicationId,
-  type ApplicationRequirement,
-  type ApplicationRequirementAudit,
-  type ApplicationRequirementFinding,
-  type ApplicationRequirementMigrationItem,
-  type ApplicationRequirementScore,
-  type ApplicationRequirementScope,
-  type ApplicationRequirementStatus,
-  type ApplicationRequirementsAuditReport,
-  type ServiceCatalogUrlEntry,
-  type AppApiId,
-} from "./services.js";
-export {
-  TopoloSdkError,
-  TopoloAuthError,
-  TopoloPermissionError,
-  TopoloHttpError,
-} from "./errors.js";
-export {
-  CrmModule,
-  type CrmContactSummary,
-  type ListContactsOptions,
-  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,
-  type DeviceAuthorizationResponse,
-  type TokenResponse,
-} from "./oauth.js";
-export {
-  TOPOLO_WIDGET_ENDPOINT,
-  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
-  createTopoloWidgetError,
-  createTopoloWidgetResponse,
-  defineTopoloChartWidget,
-  defineTopoloNotificationsWidget,
-  defineTopoloQuickActionsWidget,
-  defineTopoloRecentActivityWidget,
-  defineTopoloStatsWidget,
-  validateTopoloWidgetResponse,
-  type TopoloChartWidget,
-  type TopoloNotificationsWidget,
-  type TopoloQuickActionsWidget,
-  type TopoloRecentActivityWidget,
-  type TopoloStatsWidget,
-  type TopoloWidget,
-  type TopoloWidgetActionItem,
-  type TopoloWidgetActivityItem,
-  type TopoloWidgetApiResponse,
-  type TopoloWidgetBase,
-  type TopoloWidgetConfig,
-  type TopoloWidgetDraft,
-  type TopoloWidgetMetric,
-  type TopoloWidgetNotificationItem,
-  type TopoloWidgetResponseOptions,
-  type TopoloWidgetSnapshotMetadata,
-  type TopoloWidgetSnapshotMetric,
-  type TopoloWidgetType,
-  type TopoloWidgetValidationResult,
-} from "./widgets.js";
-
-import { TopoloClient, type TopoloClientOptions } from "./client.js";
-import { CrmModule } from "./modules/crm.js";
-import { IdentityModule } from "./modules/identity.js";
-
-/**
- * Convenience factory that returns a ready-to-use typed Topolo client plus
- * domain module surfaces (identity, crm, ...).
- *
- * Phase 1 exposes identity + crm; subsequent phases add more modules
- * incrementally as each app's API contract stabilizes.
- */
-export function createTopolo(options: TopoloClientOptions) {
-  const client = new TopoloClient(options);
-  return {
-    client,
-    identity: new IdentityModule(client),
-    crm: new CrmModule(client),
-  };
-}
-
-export type Topolo = ReturnType<typeof createTopolo>;

package/src/modules/crm.test.ts

@@ -1,208 +0,0 @@
-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: { app_id: 'service_crm' } }), {
-        status: 200,
-        headers: { 'Content-Type': 'application/json' },
-      });
-    }
-    if (String(url).includes('/api/services/catalog')) {
-      return new Response(
-        JSON.stringify({
-          data: {
-            services: [
-              {
-                app_id: 'app_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: ['app_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.clearAppIdCache();
-});
-
-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/crm.ts

@@ -1,110 +0,0 @@
-import type { TopoloClient } from '../client.js';
-
-export interface CrmContactSummary {
-  id: string;
-  firstName: string | null;
-  lastName: string | null;
-  email: string | null;
-  phone: string | null;
-  company: string | null;
-  leadStatus: string | null;
-  lifecycleStage: string | null;
-  updatedAt: string | null;
-}
-
-export interface ListContactsOptions {
-  /** Full-text search string. */
-  q?: string;
-  /** Page number, 1-indexed. */
-  page?: number;
-  /** Page size. */
-  pageSize?: number;
-}
-
-export interface ListContactsResult {
-  contacts: CrmContactSummary[];
-  total: number;
-  page: number;
-  pageSize: number;
-}
-
-/**
- * CRM module — thin typed wrapper over the TopoloCRM HTTP API.
- *
- * Cross-org isolation: there is intentionally NO `orgId` parameter anywhere in
- * this module. The organization is derived entirely from the auth credential
- * by the CRM backend, which scopes all SQL queries by `org_slug`/`org_id`.
- */
-export class CrmModule {
-  constructor(private readonly client: TopoloClient) {}
-
-  async listContacts(options: ListContactsOptions = {}): Promise<ListContactsResult> {
-    const res = await this.client.request<RawListResponse>({
-      service: 'crm',
-      path: '/api/contacts',
-      query: {
-        q: options.q,
-        page: options.page,
-        pageSize: options.pageSize,
-      },
-    });
-
-    const rows = Array.isArray(res?.contacts)
-      ? res.contacts
-      : Array.isArray(res?.data)
-        ? res.data
-        : [];
-
-    return {
-      contacts: rows.map(toSummary),
-      total: res?.total ?? res?.pagination?.total ?? rows.length,
-      page: res?.page ?? res?.pagination?.page ?? options.page ?? 1,
-      pageSize: res?.pageSize ?? res?.pagination?.pageSize ?? options.pageSize ?? rows.length,
-    };
-  }
-
-  async getContact(contactId: string): Promise<CrmContactSummary | null> {
-    if (!contactId) throw new Error('contactId is required');
-    const res = await this.client.request<{ data?: RawContact } | RawContact>({
-      service: 'crm',
-      path: `/api/contacts/${encodeURIComponent(contactId)}`,
-    });
-    const row = (res as { data?: RawContact }).data ?? (res as RawContact);
-    return row ? toSummary(row) : null;
-  }
-}
-
-interface RawContact {
-  id: string;
-  first?: string | null;
-  last?: string | null;
-  email?: string | null;
-  phone?: string | null;
-  company?: string | null;
-  lead_status?: string | null;
-  lifecycle_stage?: string | null;
-  updated_at?: string | null;
-}
-
-interface RawListResponse {
-  contacts?: RawContact[];
-  data?: RawContact[];
-  total?: number;
-  page?: number;
-  pageSize?: number;
-  pagination?: { total?: number; page?: number; pageSize?: number };
-}
-
-function toSummary(row: RawContact): CrmContactSummary {
-  return {
-    id: row.id,
-    firstName: row.first ?? null,
-    lastName: row.last ?? null,
-    email: row.email ?? null,
-    phone: row.phone ?? null,
-    company: row.company ?? null,
-    leadStatus: row.lead_status ?? null,
-    lifecycleStage: row.lifecycle_stage ?? null,
-    updatedAt: row.updated_at ?? null,
-  };
-}