@topolo/sdk

Typed client SDK for the Topolo platform. Consumed by @topolo/cli and @topolo/mcp, and available to any first- or third-party code that needs to call Topolo APIs on a user's behalf.

This package is the single place where cross-org isolation is enforced on the client side.

Install

npm install @topolo/sdk

Usage

import { createTopolo } from '@topolo/sdk';

const topolo = createTopolo({
  credential: { kind: 'api_key', apiKey: process.env.TOPOLO_API_KEY! },
  agent: {
    clientName: 'my-integration',
    clientVersion: '1.0.0',
    agentName: 'my-backend-service',
  },
});

const me = await topolo.identity.whoami();
console.log(me.organization?.slug);

const { contacts } = await topolo.crm.listContacts({ q: 'acme' });

Design invariants

No orgId parameter, anywhere

No public method, tool definition, or CLI command in the Topolo agent surface accepts an orgId input. Every request derives the org from the credential — a JWT orgId claim for access tokens, or the organization_id bound to an API key at issuance.

This is enforced at every layer:

1. @topolo/sdk — no typed method takes an orgId arg.
2. @topolo/cli — no command takes an --org flag.
3. @topolo/mcp — no tool schema has an orgId field.
4. Each Topolo backend app re-derives orgId from the credential on every request and binds it into SQL WHERE clauses.

Write-action gating

TopoloClient rejects POST/PUT/PATCH/DELETE by default unless the call passes { confirm: true }. This prevents an agent from accidentally issuing writes during casual exploration. Disable with requireConfirmForWrites: false only for trusted surfaces.

Audit headers

Every request sends:

• X-Topolo-Client: <clientName>/<clientVersion>
• X-Topolo-Agent: <agentName> (if set)
• X-Topolo-Request-Id: <uuid>

Combined with the credential identity, this makes every platform API call traceable to a specific agent invocation.

Modules (Phase 1)

| Module | Methods | | ------------ | ------------------------------------- | | identity | whoami() | | crm | listContacts(), getContact(id) |

Additional modules land per-app as each backend contract stabilizes.

Application catalog

APPLICATIONS describes every Topolo platform application discovered from the PlatformApplications metadata, including pages-only apps that do not expose a callable service. DEFAULT_SERVICE_URLS remains the callable API service map used by TopoloClient.

APPLICATION_REQUIREMENTS is the versioned app-build contract agents should read before creating or expanding a Topolo app. requirementsForApplication() filters the shared contract to the browser/API/tooling scopes implied by the app catalog entry.

auditApplicationRequirements() and auditAllApplicationRequirements() turn that contract into catalog-backed conformance reports and migration-queue items. Catalog-visible evidence is marked directly; implementation details that require code or docs inspection are deliberately marked needs_review.

Native dashboard widgets

Launchable first-party applications populate the TopoloOne live workspace through their own GET /api/widget endpoint. The SDK owns the shared payload contract:

import { createTopoloWidgetResponse } from '@topolo/sdk';

return Response.json(createTopoloWidgetResponse({
  serviceId: 'srv_topolo_example',
  serviceName: 'Example',
  widgets: [
    {
      type: 'stats',
      stats: [{ label: 'Open items', value: 3 }],
    },
  ],
}));

Use validateTopoloWidgetResponse() in endpoint tests to prevent app-local payload drift.

Escape hatch

await topolo.client.request({
  service: 'crm',
  method: 'GET',
  path: '/api/some/untyped/endpoint',
});

Still routes through auth + audit headers. Mutating methods still require confirm: true.

Errors

| Class | Thrown for | | ------------------------ | ---------------------------------------- | | TopoloAuthError | 401 responses, missing credentials | | TopoloPermissionError | 403 responses (includes .required) | | TopoloHttpError | Other non-2xx responses | | TopoloSdkError | Base class |

Service URL overrides

Defaults target production. Override per-service for staging/dev:

createTopolo({
  /* ... */
  serviceUrls: {
    crm: 'https://edge-crm-stg.topolo.workers.dev',
  },
});

Or via env: TOPOLO_SERVICE_URL_CRM=... (falls through resolveServiceUrl).

Development

npm install
npm run build
npm run typecheck