@topolo/sdk 0.1.0

package/README.md

@@ -0,0 +1,123 @@
+# @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
+
+```bash
+npm install @topolo/sdk
+```
+
+## Usage
+
+```ts
+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.
+
+## Escape hatch
+
+```ts
+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:
+
+```ts
+createTopolo({
+  /* ... */
+  serviceUrls: {
+    crm: 'https://edge-crm-stg.topolo.workers.dev',
+  },
+});
+```
+
+Or via env: `TOPOLO_SERVICE_URL_CRM=...` (falls through `resolveServiceUrl`).
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run typecheck
+```

package/dist/index.cjs

@@ -0,0 +1,414 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  CrmModule: () => CrmModule,
+  DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
+  IdentityModule: () => IdentityModule,
+  PLATFORM_SERVICE_IDS: () => PLATFORM_SERVICE_IDS,
+  TopoloAuthError: () => TopoloAuthError,
+  TopoloClient: () => TopoloClient,
+  TopoloHttpError: () => TopoloHttpError,
+  TopoloOAuth: () => TopoloOAuth,
+  TopoloPermissionError: () => TopoloPermissionError,
+  TopoloSdkError: () => TopoloSdkError,
+  createTopolo: () => createTopolo,
+  resolveServiceUrl: () => resolveServiceUrl
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/auth.ts
+function applyAuthHeaders(headers, credential) {
+  if (credential.kind === "api_key") {
+    headers.set("X-Api-Key", credential.apiKey);
+    return;
+  }
+  headers.set("Authorization", `Bearer ${credential.accessToken}`);
+}
+function applyAuditHeaders(headers, agent, requestId) {
+  headers.set("X-Topolo-Client", `${agent.clientName}/${agent.clientVersion}`);
+  if (agent.agentName) headers.set("X-Topolo-Agent", agent.agentName);
+  headers.set("X-Topolo-Request-Id", requestId);
+}
+function generateRequestId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return `req_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+// src/errors.ts
+var TopoloSdkError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "TopoloSdkError";
+    this.code = code;
+  }
+};
+var TopoloAuthError = class extends TopoloSdkError {
+  constructor(message, code = "auth_error") {
+    super(code, message);
+    this.name = "TopoloAuthError";
+  }
+};
+var TopoloPermissionError = class extends TopoloSdkError {
+  required;
+  constructor(message, required) {
+    super("permission_denied", message);
+    this.name = "TopoloPermissionError";
+    this.required = required;
+  }
+};
+var TopoloHttpError = class extends TopoloSdkError {
+  status;
+  body;
+  service;
+  path;
+  constructor(service, path, status, body, message) {
+    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+    this.name = "TopoloHttpError";
+    this.status = status;
+    this.body = body;
+    this.service = service;
+    this.path = path;
+  }
+};
+
+// src/services.ts
+var DEFAULT_SERVICE_URLS = {
+  auth: "https://auth.topolo.app",
+  crm: "https://topolo-crm-worker.topolo.workers.dev"
+};
+var PLATFORM_SERVICE_IDS = {
+  crm: "srv_iCwM4jGXcwlj"
+};
+function resolveServiceUrl(service, overrides) {
+  const override = overrides?.[service];
+  if (override) return override;
+  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+  if (envValue) return envValue;
+  return DEFAULT_SERVICE_URLS[service];
+}
+
+// src/client.ts
+var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TopoloClient = class {
+  credential;
+  agent;
+  serviceUrls;
+  requireConfirmForWrites;
+  timeoutMs;
+  fetchImpl;
+  constructor(options) {
+    if (!options.credential) throw new TopoloAuthError("credential is required");
+    if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
+    this.credential = options.credential;
+    this.agent = options.agent;
+    this.serviceUrls = options.serviceUrls;
+    this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
+   * for anything a caller would reach for; this stays exported for escape-hatch
+   * use and for the generic `topolo api` / MCP passthrough tool.
+   */
+  async request(opts) {
+    const method = opts.method ?? "GET";
+    if (this.requireConfirmForWrites && WRITE_METHODS.has(method) && !opts.confirm) {
+      throw new TopoloAuthError(
+        `Mutating ${method} requests require { confirm: true }. This guardrail prevents agents from issuing writes without an explicit human-in-the-loop acknowledgement.`
+      );
+    }
+    const baseUrl = resolveServiceUrl(opts.service, this.serviceUrls);
+    const url = new URL(opts.path, baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+    if (opts.query) {
+      for (const [k, v] of Object.entries(opts.query)) {
+        if (v !== void 0) url.searchParams.set(k, String(v));
+      }
+    }
+    const headers = new Headers();
+    headers.set("Accept", "application/json");
+    if (opts.body !== void 0) headers.set("Content-Type", "application/json");
+    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
+    applyAuthHeaders(headers, this.credential);
+    applyAuditHeaders(headers, this.agent, generateRequestId());
+    if (opts.headers) {
+      for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
+    }
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+    const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    let res;
+    try {
+      res = await this.fetchImpl(url.toString(), {
+        method,
+        headers,
+        body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+        signal
+      });
+    } finally {
+      clearTimeout(timeoutId);
+    }
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
+      if (res.status === 403) {
+        throw new TopoloPermissionError(
+          describeError(parsed, "Permission denied"),
+          extractRequired(parsed)
+        );
+      }
+      throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
+    }
+    return parsed;
+  }
+  /**
+   * Introspect the current credential. Returns the caller's resolved identity,
+   * organization, and permission set. Used by CLI `whoami` and by MCP to gate
+   * advertised tools by scope.
+   *
+   * Both JWT access tokens and platform API keys are resolved via the unified
+   * `GET /api/auth/me` endpoint on TopoloAuth, which does not require service
+   * credentials. The caller's possession of the credential secret is proof.
+   */
+  async introspect() {
+    const res = await this.request({
+      service: "auth",
+      method: "GET",
+      path: "/api/auth/me"
+    });
+    const payload = res.data ?? res;
+    const user = payload.user;
+    const organization = payload.organization;
+    const kind = payload.credentialType === "api_key" ? "api_key" : "access_token";
+    return {
+      kind,
+      user: {
+        id: user.id,
+        email: user.email,
+        name: user.name ?? null,
+        role: user.role ?? (kind === "api_key" ? "service" : "member"),
+        permissions: payload.permissions ?? user.permissions ?? []
+      },
+      organization: organization ? {
+        id: organization.id,
+        slug: organization.slug,
+        name: organization.name ?? organization.slug
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+    };
+  }
+};
+function describeError(body, fallback) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    return maybe.message ?? maybe.error ?? fallback;
+  }
+  return fallback;
+}
+function extractRequired(body) {
+  if (body && typeof body === "object") {
+    const maybe = body;
+    if (Array.isArray(maybe.required)) return maybe.required.map(String);
+  }
+  return [];
+}
+function mergeSignals(a, b) {
+  if (a.aborted) return a;
+  if (b.aborted) return b;
+  const controller = new AbortController();
+  const onAbort = () => controller.abort();
+  a.addEventListener("abort", onAbort, { once: true });
+  b.addEventListener("abort", onAbort, { once: true });
+  return controller.signal;
+}
+
+// src/modules/crm.ts
+var CrmModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async listContacts(options = {}) {
+    const res = await this.client.request({
+      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) {
+    if (!contactId) throw new Error("contactId is required");
+    const res = await this.client.request({
+      service: "crm",
+      path: `/api/contacts/${encodeURIComponent(contactId)}`
+    });
+    const row = res.data ?? res;
+    return row ? toSummary(row) : null;
+  }
+};
+function toSummary(row) {
+  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
+  };
+}
+
+// src/modules/identity.ts
+var IdentityModule = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  /** Returns the resolved user, organization, and permission set for the
+   *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
+   *  on this module for symmetry with the other domain modules. */
+  whoami() {
+    return this.client.introspect();
+  }
+};
+
+// src/oauth.ts
+var DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+var TopoloOAuth = class {
+  baseUrl;
+  fetchImpl;
+  constructor(options = {}) {
+    this.baseUrl = resolveServiceUrl("auth", options.serviceUrls);
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+  /**
+   * RFC 8628 device authorization grant — starts the flow by asking the server
+   * for a device_code + user_code. The caller prints the user_code +
+   * verification_uri and then polls `pollDeviceToken` until approval.
+   */
+  async requestDeviceCode(params) {
+    const body = new URLSearchParams();
+    body.set("client_id", params.clientId);
+    if (params.scope) {
+      body.set("scope", Array.isArray(params.scope) ? params.scope.join(" ") : params.scope);
+    }
+    return this.#postForm("/api/developer-oauth/device_authorization", body);
+  }
+  /**
+   * Polls the token endpoint once. Returns the token pair on success, or
+   * throws a `TopoloAuthError` whose `code` is one of the RFC 8628 poll
+   * states: `authorization_pending`, `slow_down`, `access_denied`,
+   * `expired_token`. Callers should back off on `slow_down`, wait at least
+   * one `interval` on `authorization_pending`, and give up on the rest.
+   */
+  async pollDeviceToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", DEVICE_GRANT);
+    body.set("client_id", params.clientId);
+    body.set("device_code", params.deviceCode);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Exchange an authorization code (with PKCE) for tokens. */
+  async exchangeAuthorizationCode(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "authorization_code");
+    body.set("client_id", params.clientId);
+    body.set("code", params.code);
+    body.set("redirect_uri", params.redirectUri);
+    if (params.codeVerifier) body.set("code_verifier", params.codeVerifier);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  /** Rotate a refresh token for a new token pair. */
+  async refreshToken(params) {
+    const body = new URLSearchParams();
+    body.set("grant_type", "refresh_token");
+    body.set("client_id", params.clientId);
+    body.set("refresh_token", params.refreshToken);
+    if (params.clientSecret) body.set("client_secret", params.clientSecret);
+    return this.#postForm("/api/developer-oauth/token", body);
+  }
+  async #postForm(path, body) {
+    const url = new URL(path, this.baseUrl.endsWith("/") ? this.baseUrl : `${this.baseUrl}/`);
+    const res = await this.fetchImpl(url.toString(), {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json"
+      },
+      body: body.toString()
+    });
+    const contentType = res.headers.get("Content-Type") ?? "";
+    const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
+    if (!res.ok) {
+      if (parsed && typeof parsed === "object" && "error" in parsed) {
+        const err = parsed;
+        throw new TopoloAuthError(err.error_description || err.error, err.error);
+      }
+      throw new TopoloHttpError("auth", path, res.status, parsed);
+    }
+    return parsed;
+  }
+};
+
+// src/index.ts
+function createTopolo(options) {
+  const client = new TopoloClient(options);
+  return {
+    client,
+    identity: new IdentityModule(client),
+    crm: new CrmModule(client)
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CrmModule,
+  DEFAULT_SERVICE_URLS,
+  IdentityModule,
+  PLATFORM_SERVICE_IDS,
+  TopoloAuthError,
+  TopoloClient,
+  TopoloHttpError,
+  TopoloOAuth,
+  TopoloPermissionError,
+  TopoloSdkError,
+  createTopolo,
+  resolveServiceUrl
+});