@topolo/cli 0.1.2 → 0.1.4

package/dist/index.js

@@ -8,7 +8,366 @@ import { spawn } from "child_process";
 import { platform as platform2 } from "os";
 import { createInterface } from "readline/promises";
 import { stdin as input } from "process";
-import { TopoloOAuth, TopoloAuthError } from "@topolo/sdk";
+
+// ../packages/topolo-sdk/dist/index.js
+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)}`;
+}
+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;
+  }
+};
+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];
+}
+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;
+    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
+    if (resolved) return resolved;
+  }
+  return fallback;
+}
+function pickString(value) {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  if (value && typeof value === "object") {
+    const nested = value;
+    if (typeof nested.message === "string" && nested.message.trim().length > 0) return nested.message;
+    if (typeof nested.description === "string" && nested.description.trim().length > 0)
+      return nested.description;
+  }
+  return void 0;
+}
+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;
+}
+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
+  };
+}
+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();
+  }
+};
+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;
+  }
+};
+function createTopolo(options) {
+  const client = new TopoloClient(options);
+  return {
+    client,
+    identity: new IdentityModule(client),
+    crm: new CrmModule(client)
+  };
+}
 
 // src/config.ts
 import { mkdir, readFile, writeFile, chmod } from "fs/promises";
@@ -50,6 +409,37 @@ async function resolveCredential() {
   const config = await readConfig();
   return config.credential ?? null;
 }
+var REFRESH_SKEW_SECONDS = 60;
+async function refreshCredentialIfNeeded() {
+  if (process.env.TOPOLO_API_KEY || process.env.TOPOLO_ACCESS_TOKEN) {
+    return resolveCredential();
+  }
+  const config = await readConfig();
+  const cred = config.credential;
+  if (!cred || cred.kind !== "access_token") return cred ?? null;
+  if (!cred.refreshToken || !cred.expiresAt || !config.oauthClientId) return cred;
+  const now = Math.floor(Date.now() / 1e3);
+  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(config.serviceUrls)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: config.oauthClientId,
+      refreshToken: cred.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: cred.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    await writeConfig({ ...config, credential: refreshed });
+    return refreshed;
+  } catch {
+    return cred;
+  }
+}
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
@@ -226,6 +616,7 @@ async function runDeviceFlow(options) {
     ...token.refresh_token ? { refreshToken: token.refresh_token } : {},
     expiresAt: Math.floor(Date.now() / 1e3) + token.expires_in
   };
+  updated.oauthClientId = options.clientId;
   await writeConfig(updated);
   emit(
     {
@@ -304,15 +695,12 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-// src/client.ts
-import { createTopolo } from "@topolo/sdk";
-
 // src/version.ts
-var CLI_VERSION = "0.1.2";
+var CLI_VERSION = "0.1.4";
 
 // src/client.ts
 async function buildClient(options) {
-  const credential = await resolveCredential();
+  const credential = await refreshCredentialIfNeeded();
   if (!credential) return null;
   const config = await readConfig();
   const serviceUrls = resolveServiceUrls(config.serviceUrls);
@@ -423,7 +811,7 @@ function formatContact(c) {
 
 // src/commands/api.ts
 var KNOWN_SERVICES = ["auth", "crm"];
-var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var WRITE_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function registerApiCommand(program2) {
   program2.command("api <service> <method> <path>").description("Generic passthrough to a Topolo service (escape hatch for untyped endpoints)").option("-d, --data <json>", "JSON body (for POST/PUT/PATCH)").option("--confirm", "Acknowledge a mutating request").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(
     async (service, method, path, opts) => {
@@ -438,7 +826,7 @@ function registerApiCommand(program2) {
             `Unknown service "${service}". Known services: ${KNOWN_SERVICES.join(", ")}`
           );
         }
-        if (WRITE_METHODS.has(upperMethod) && !opts.confirm) {
+        if (WRITE_METHODS2.has(upperMethod) && !opts.confirm) {
           throw new Error(`Mutating ${upperMethod} requires --confirm.`);
         }
         let body = void 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Command-line interface for the Topolo platform. Designed for humans and for agents (Claude, Codex, etc.) that prefer shell invocation.",
   "type": "module",
   "bin": {
@@ -16,10 +16,10 @@
     "start": "node dist/index.js"
   },
   "dependencies": {
-    "@topolo/sdk": "file:../packages/topolo-sdk",
     "commander": "^12.1.0"
   },
   "devDependencies": {
+    "@topolo/sdk": "file:../packages/topolo-sdk",
     "@types/node": "^20.12.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0"