@topolo/cli 0.1.26 → 0.1.27

package/README.md

@@ -10,7 +10,7 @@ via `stdin`/`stdout`.
 - Access-token authentication via OAuth device flow when a CLI OAuth client id is configured.
 - Stored access-token refresh when the config includes a refresh token and OAuth client id.
 - First-class `production` and `staging` CLI environments with separate stored credentials, OAuth client ids, and service URL overrides.
-- Commands: `auth login/logout/status`, `whoami`, `apps`, `apps scaffold`, `oauth clients`, `integrations prompt/check`, `services`, `crm contacts:list`, `crm contacts:get`, and generic `api` passthrough for SDK-registered services.
+- Commands: `auth login/logout/status`, `whoami`, `apps`, `apps scaffold`, `oauth clients`, `integrations prompt/check`, `services`, credential-scoped `actions`, and generic `api` passthrough for SDK-registered services.
 
 ## Install
 
@@ -76,10 +76,12 @@ The platform logs these for traceability.
 ## Write-action gating
 
 The SDK defaults to requiring an explicit `--confirm` flag on any mutating
-request. The generic `topolo api` passthrough enforces this too:
+request. Dynamic action calls and the generic `topolo api` passthrough enforce
+this too:
 
 ```bash
-topolo api crm POST /api/contacts --data '{"email":"a@b.co"}' --confirm
+topolo actions call topolo_mail_messages_send --data '{"mailboxId":"primary","subject":"Hello"}' --confirm
+topolo api mail POST /api/mail/mailboxes/primary/messages --data '{"subject":"Hello"}' --confirm
 ```
 
 ## Commands
@@ -93,19 +95,6 @@ topolo whoami           # pretty
 topolo whoami --json    # machine-readable
 ```
 
-### `topolo crm contacts:list`
-
-```bash
-topolo crm contacts:list
-topolo crm contacts:list -q "acme" -p 2 -s 50 --json
-```
-
-### `topolo crm contacts:get <id>`
-
-```bash
-topolo crm contacts:get contact_abc123
-```
-
 ### `topolo services`
 
 Lists the services the current credential can use in its organization, with the
@@ -123,6 +112,26 @@ topolo services --env staging --json
 catalog. New services become usable without a CLI release once Auth grants the
 organization and credential the relevant permissions.
 
+### `topolo actions`
+
+Lists the callable actions available to the current credential. Applications
+publish actions through Topolo Developers, Auth filters them by the same
+service permissions already used by API keys, launchers, and backend services,
+and the CLI calls them through the shared SDK.
+
+```bash
+topolo actions --json
+topolo actions --service mail --json
+topolo actions get topolo_mail_messages_send --json
+topolo actions call topolo_mail_messages_send \
+  --data '{"mailboxId":"primary","subject":"Hello","text":"..."}' \
+  --confirm --json
+```
+
+Use `topolo actions` before `topolo api` when an app has published a machine
+contract for the operation. `topolo api` remains the escape hatch for endpoints
+that are not yet in the action catalog.
+
 ### `topolo apps`
 
 Lists launchable Topolo applications available to the current credential. This
@@ -206,7 +215,7 @@ Escape hatch for endpoints without typed modules yet.
 
 ```bash
 topolo api auth GET /api/me
-topolo api crm POST /api/contacts --data '{"first":"Jane"}' --confirm
+topolo api mail POST /api/mail/mailboxes/primary/messages --data '{"subject":"Hello"}' --confirm
 ```
 
 Use `topolo services --json` to discover service ids permitted for the current

package/dist/index.js

@@ -2068,6 +2068,7 @@ var TopoloClient = class _TopoloClient {
   fetchImpl;
   debug;
   serviceCatalogCache = null;
+  actionCatalogCache = null;
   /**
    * Process-wide cache for slug → service-id lookups. Keyed by
    * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -2328,6 +2329,63 @@ var TopoloClient = class _TopoloClient {
     };
     return entries;
   }
+  /**
+   * List callable actions from the live Auth catalog. The response is scoped to
+   * the caller's organization and effective permissions; no bundled/static app
+   * action list is used as an authorization source.
+   */
+  async listActions(options = {}) {
+    const now = Date.now();
+    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
+      return this.actionCatalogCache.entries;
+    }
+    const res = await this.request({
+      service: "auth",
+      method: "GET",
+      path: "/api/actions/catalog",
+      ...options.service ? { query: { service: options.service } } : {}
+    });
+    const raw = res.data?.actions ?? res.actions;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        "action_catalog_unavailable",
+        "TopoloAuth did not return an action catalog for the current credential."
+      );
+    }
+    const entries = raw.map((item) => normalizeActionCatalogEntry(item)).filter((entry) => Boolean(entry));
+    if (!options.service) {
+      this.actionCatalogCache = {
+        entries,
+        expiresAt: now + CATALOG_CACHE_TTL_MS
+      };
+    }
+    return entries;
+  }
+  async getAction(action) {
+    const needle = normalizeActionLookupKey(action);
+    const actions = await this.listActions();
+    const match = actions.find((entry) => actionEntryMatches(entry, needle));
+    if (!match) {
+      throw new TopoloSdkError(
+        "unknown_action",
+        `Unknown Topolo action "${action}". Run action discovery first and pass an action id, name, or tool name.`
+      );
+    }
+    return match;
+  }
+  async callAction(action, input2 = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input2);
+    const service = entry.serviceSlug || entry.serviceId;
+    return this.request({
+      service,
+      method: entry.method,
+      path: mapped.path,
+      ...mapped.query ? { query: mapped.query } : {},
+      ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      confirm: options.confirm === true
+    });
+  }
   /**
    * Bundled generated registry for tooling that audits platform packaging, not
    * for deciding what the current credential may use.
@@ -2437,6 +2495,98 @@ function isCallableCatalogEntry(entry) {
     entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
   );
 }
+function normalizeActionCatalogEntry(item) {
+  if (!item || typeof item !== "object" || Array.isArray(item)) return null;
+  const a = item;
+  const actionId = pickActionString(a.action_id) ?? pickActionString(a.actionId);
+  const name = pickActionString(a.name);
+  const serviceId = pickActionString(a.service_id) ?? pickActionString(a.serviceId);
+  const method = pickActionString(a.method)?.toUpperCase();
+  const path4 = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path4 || !isHttpMethod(method)) {
+    return null;
+  }
+  return {
+    actionId,
+    name,
+    toolName: pickActionString(a.tool_name) ?? pickActionString(a.toolName) ?? null,
+    title: pickActionString(a.title) ?? name,
+    description: pickActionString(a.description) ?? "",
+    serviceId,
+    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
+    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    method,
+    path: path4,
+    permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
+    requiredPermission: pickActionString(a.required_permission) ?? pickActionString(a.requiredPermission) ?? "",
+    inputSchema: plainObject(a.input_schema ?? a.inputSchema),
+    outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    readOnly: Boolean(a.read_only ?? a.readOnly),
+    destructive: Boolean(a.destructive),
+    requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
+    status: pickActionString(a.status),
+    sourceRevision: pickActionString(a.source_revision) ?? pickActionString(a.sourceRevision)
+  };
+}
+function isHttpMethod(value) {
+  return value === "GET" || value === "POST" || value === "PUT" || value === "PATCH" || value === "DELETE";
+}
+function pickActionString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function plainObject(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function normalizeActionLookupKey(value) {
+  return String(value || "").trim().toLowerCase();
+}
+function actionEntryMatches(entry, needle) {
+  if (!needle) return false;
+  return [entry.actionId, entry.name, entry.toolName].filter((value) => typeof value === "string" && value.length > 0).some((value) => value.toLowerCase() === needle);
+}
+function mapActionInput(action, input2) {
+  const remaining = { ...input2 || {} };
+  const path4 = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
+    const value = remaining[key];
+    if (value === void 0 || value === null || value === "") {
+      throw new TopoloSdkError(
+        "invalid_action_input",
+        `Action "${action.name}" requires path parameter "${key}".`
+      );
+    }
+    delete remaining[key];
+    return encodeURIComponent(String(value));
+  });
+  const explicitQuery = plainObject(remaining.query);
+  delete remaining.query;
+  const explicitBody = Object.prototype.hasOwnProperty.call(remaining, "body") ? remaining.body : void 0;
+  delete remaining.body;
+  if (action.method === "GET") {
+    return {
+      path: path4,
+      query: objectToQuery({ ...remaining, ...explicitQuery })
+    };
+  }
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== void 0 ? explicitBody : remaining;
+  return {
+    path: path4,
+    ...query ? { query } : {},
+    body
+  };
+}
+function objectToQuery(value) {
+  const query = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw === void 0 || raw === null) continue;
+    if (typeof raw === "string" || typeof raw === "number" || typeof raw === "boolean") {
+      query[key] = raw;
+    } else {
+      query[key] = JSON.stringify(raw);
+    }
+  }
+  return Object.keys(query).length > 0 ? query : void 0;
+}
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -3198,78 +3348,90 @@ function formatPretty(info) {
   return lines.join("\n");
 }
 
-// src/commands/crm.ts
-function registerCrmCommands(program2) {
-  const crm = program2.command("crm").description("TopoloCRM operations");
-  crm.command("contacts:list").description("List contacts in the authenticated organization").option("-q, --query <text>", "Full-text search").option("-p, --page <n>", "Page number (1-indexed)", (v) => parseInt(v, 10), 1).option("-s, --page-size <n>", "Page size", (v) => parseInt(v, 10), 25).option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (opts) => {
+// src/commands/actions.ts
+function registerActionsCommand(program2) {
+  const actions = program2.command("actions").description("List and call permission-scoped Topolo actions from the live catalog").option("-s, --service <service>", "Filter by service id, slug, or name").option("--json", "Output JSON", true).option("--no-json", "Output human-readable table").action(async (opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      await assertCrmRoutable();
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
       }
-      const result = await topolo.crm.listContacts({
-        q: opts.query,
-        page: opts.page,
-        pageSize: opts.pageSize
-      });
-      emit(result, mode, () => formatContactsTable(result.contacts, result.total, result.page));
+      const rows = await topolo.client.listActions({ service: opts.service });
+      emit({ actions: rows }, mode, () => formatActionRows(rows));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("get <action>").description("Describe one Topolo action by action id, name, or tool name").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (action, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) {
+        throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      }
+      const entry = await topolo.client.getAction(action);
+      emit(entry, mode, () => formatActionDetail(entry));
     } catch (err) {
       fail(err, mode);
     }
   });
-  crm.command("contacts:get <id>").description("Fetch a single contact by id").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (id, opts) => {
+  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json>", "JSON action input", "{}").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON", true).option("--no-json", "Output human-readable text").action(async (action, opts) => {
     const mode = resolveOutputMode(opts.json);
     try {
-      await assertCrmRoutable();
       const topolo = await buildClient();
       if (!topolo) {
         throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
       }
-      const contact = await topolo.crm.getContact(id);
-      if (!contact) throw new Error(`Contact not found: ${id}`);
-      emit(contact, mode, () => formatContact(contact));
+      const input2 = parseJsonObject(opts.data || "{}");
+      const result = await topolo.client.callAction(action, input2, { confirm: opts.confirm === true });
+      emit(result, mode, () => JSON.stringify(result, null, 2));
     } catch (err) {
       fail(err, mode);
     }
   });
 }
-async function assertCrmRoutable() {
-  const environment = selectedEnvironment();
-  const profile = resolvedProfileConfig(await readConfig(), environment);
-  assertServiceUrlForEnvironment(
-    "crm",
-    resolveServiceUrl("crm", profile.serviceUrls),
-    environment
-  );
+function parseJsonObject(value) {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new Error("--data must be valid JSON");
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("--data must be a JSON object");
+  }
+  return parsed;
 }
-function formatContactsTable(rows, total, page) {
-  if (rows.length === 0) return "No contacts found.";
-  const lines = [];
-  lines.push(`Showing ${rows.length} of ${total} contacts (page ${page})`);
-  lines.push("");
+function formatActionRows(rows) {
+  if (rows.length === 0) return "No actions available for this credential.";
+  const serviceWidth = Math.max(7, ...rows.map((row) => (row.serviceSlug || row.serviceId).length));
+  const nameWidth = Math.max(6, ...rows.map((row) => row.name.length));
+  const methodWidth = Math.max(6, ...rows.map((row) => row.method.length));
+  const lines = [
+    `${"SERVICE".padEnd(serviceWidth)}  ${"ACTION".padEnd(nameWidth)}  ${"METHOD".padEnd(methodWidth)}  CONFIRM  PERMISSION`,
+    `${"-".repeat(serviceWidth)}  ${"-".repeat(nameWidth)}  ${"-".repeat(methodWidth)}  -------  ----------`
+  ];
   for (const row of rows) {
-    const name = [row.firstName, row.lastName].filter(Boolean).join(" ") || "(no name)";
-    const parts = [name];
-    if (row.email) parts.push(row.email);
-    if (row.company) parts.push(`@ ${row.company}`);
-    if (row.leadStatus) parts.push(`[${row.leadStatus}]`);
-    lines.push(`  ${row.id}  ${parts.join(" \xB7 ")}`);
+    const confirmation = row.requiresConfirmation ? "yes" : "no";
+    lines.push(
+      `${(row.serviceSlug || row.serviceId).padEnd(serviceWidth)}  ${row.name.padEnd(nameWidth)}  ${row.method.padEnd(methodWidth)}  ${confirmation.padEnd(7)}  ${row.requiredPermission}`
+    );
   }
   return lines.join("\n");
 }
-function formatContact(c) {
-  const name = [c.firstName, c.lastName].filter(Boolean).join(" ") || "(no name)";
+function formatActionDetail(action) {
   return [
-    `ID:             ${c.id}`,
-    `Name:           ${name}`,
-    `Email:          ${c.email ?? "-"}`,
-    `Phone:          ${c.phone ?? "-"}`,
-    `Company:        ${c.company ?? "-"}`,
-    `Lead status:    ${c.leadStatus ?? "-"}`,
-    `Lifecycle:      ${c.lifecycleStage ?? "-"}`,
-    `Updated at:     ${c.updatedAt ?? "-"}`
+    `Action:       ${action.name}`,
+    `ID:           ${action.actionId}`,
+    `Tool:         ${action.toolName || "-"}`,
+    `Service:      ${action.serviceSlug || action.serviceId}`,
+    `Method:       ${action.method}`,
+    `Path:         ${action.path}`,
+    `Permission:   ${action.requiredPermission}`,
+    `Confirmation: ${action.requiresConfirmation ? "required" : "not required"}`,
+    "",
+    action.description
   ].join("\n");
 }
 
@@ -9190,7 +9352,7 @@ program.hook("preAction", (thisCommand) => {
 });
 registerAuthCommands(program);
 registerWhoamiCommand(program);
-registerCrmCommands(program);
+registerActionsCommand(program);
 registerApiCommand(program);
 registerAppsCommand(program);
 registerOAuthCommands(program);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/cli",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "description": "Command-line interface for Topolo developers, operators, and agents, with internal first-party scaffolding available under the topolo platform namespace.",
   "type": "module",
   "bin": {