@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.

Use @topolo/login for Login with Topolo OAuth/OIDC provider integration, token exchange, userinfo, ID-token verification, and local account linking. Use @topolo/sdk after login, when the app already has a Topolo API credential and needs to call Topolo APIs.

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 actions = await topolo.client.listActions({ service: 'mail' });
const sendMessage = actions.find((action) => action.name === 'messages.send');
if (sendMessage) {
  await topolo.client.callAction(sendMessage.actionId, {
    mailboxId: 'primary',
    subject: 'Hello',
    text: '...',
  }, { confirm: true });
}

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.

OAuth context is credential-bound: refresh rotation preserves the token's personal/org selection and never re-resolves it from the user's mutable web preference. Separate CLI/MCP credentials can therefore remain in different contexts concurrently.

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

| Surface | Methods | | ------------ | ------------------------------------- | | identity | whoami() | | client | listServices(), listActions(), getAction(), callAction() | | app modules | compatibility helpers for stable app-specific contracts |

Agents should use the action catalog for app-specific operations so new services and actions become usable without an SDK, CLI, or MCP release.

Application catalog

APPLICATIONS describes every Topolo platform application discovered from the PlatformApplications metadata, including Worker apps that do not expose a callable app API. DEFAULT_APP_URLS is the bundled callable API service snapshot generated from topolo.cloudcontrol.json.

For agent-scale fleets, the bundle is packaging metadata, not an authorization source. TopoloClient.listServices() always calls the live TopoloAuth catalog with the current credential and returns only services that credential can use in its organization, including the granted permissions. TopoloClient.request() uses that credential-scoped catalog before routing any non-Auth service, so a bundled app ID is only a convenient alias after Auth confirms access.

listBundledServices() is available for packaging/audit tooling that needs the generated snapshot. Do not use it to decide what an end user or agent may call.

Action catalog

TopoloClient.listActions() reads TopoloAuth's live action catalog for the current credential. Applications publish their action definitions through Topolo Developers, and Auth returns only actions whose existing service permission is granted to the credential. Actions with input-dependent policy use authorizationMode: runtime; they remain typed and discoverable while the target service evaluates the supplied organization, application, and resource against current RBAC on every call. The action entry includes the service, HTTP method/path, authorization mode, required permission when static, input/output schemas, read-only and destructive hints, and the stable MCP/agent tool name.

TopoloClient.callAction(actionRef, input, options) resolves an action by actionId, name, or toolName, maps path parameters and query/body values from input, and routes the request through the same auth, audit-header, and write-confirmation flow as request().

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({
  appId: '<runtime-app-id>',
  appName: '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: {
    mail: 'https://mail.stg.topolo.us',
  },
});

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

Development

npm install
npm run build
npm run typecheck