@topolo/sdk 0.4.2 → 0.4.4

package/README.md

@@ -35,7 +35,15 @@ const topolo = createTopolo({
 const me = await topolo.identity.whoami();
 console.log(me.organization?.slug);
 
-const { contacts } = await topolo.crm.listContacts({ q: 'acme' });
+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
@@ -73,14 +81,16 @@ Every request sends:
 Combined with the credential identity, this makes every platform API call
 traceable to a specific agent invocation.
 
-## Modules (Phase 1)
+## Modules
 
-| Module       | Methods                               |
+| Surface      | Methods                               |
 | ------------ | ------------------------------------- |
 | `identity`   | `whoami()`                            |
-| `crm`        | `listContacts()`, `getContact(id)`    |
+| `client`     | `listServices()`, `listActions()`, `getAction()`, `callAction()` |
+| app modules  | compatibility helpers for stable app-specific contracts |
 
-Additional modules land per-app as each backend contract stabilizes.
+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
 
@@ -99,6 +109,20 @@ bundled service 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. The action entry includes the service,
+HTTP method/path, required permission, 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
@@ -162,12 +186,12 @@ Defaults target production. Override per-service for staging/dev:
 createTopolo({
   /* ... */
   serviceUrls: {
-    crm: 'https://edge-crm-stg.topolo.workers.dev',
+    mail: 'https://mail.stg.topolo.us',
   },
 });
 ```
 
-Or via env: `TOPOLO_SERVICE_URL_CRM=...` (falls through `resolveServiceUrl`).
+Or via env: `TOPOLO_SERVICE_URL_MAIL=...` (falls through `resolveServiceUrl`).
 
 ## Development
 

package/dist/index.cjs

@@ -2110,6 +2110,8 @@ function resolveServiceUrl(service, overrides) {
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
+var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2123,6 +2125,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
@@ -2383,6 +2386,67 @@ 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, input = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input);
+    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 } : {},
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name
+      },
+      confirm: options.confirm === true
+    });
+  }
   /**
    * Bundled generated registry for tooling that audits platform packaging, not
    * for deciding what the current credential may use.
@@ -2492,6 +2556,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 path = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path || !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,
+    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, input) {
+  const remaining = { ...input || {} };
+  const path = 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,
+      query: objectToQuery({ ...remaining, ...explicitQuery })
+    };
+  }
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== void 0 ? explicitBody : remaining;
+  return {
+    path,
+    ...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;

package/dist/index.d.cts

@@ -110,6 +110,27 @@ interface TopoloServiceCatalogEntry {
     launchable: boolean;
     permissions: string[];
 }
+interface TopoloActionCatalogEntry {
+    actionId: string;
+    name: string;
+    toolName: string | null;
+    title: string;
+    description: string;
+    serviceId: string;
+    serviceSlug: string | null;
+    serviceName: string | null;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    permissionName: string;
+    requiredPermission: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    readOnly: boolean;
+    destructive: boolean;
+    requiresConfirmation: boolean;
+    status: string | null;
+    sourceRevision: string | null;
+}
 declare class TopoloClient {
     private readonly credential;
     private readonly agent;
@@ -120,6 +141,7 @@ declare class TopoloClient {
     private readonly fetchImpl;
     private readonly debug?;
     private serviceCatalogCache;
+    private actionCatalogCache;
     /**
      * Process-wide cache for slug → service-id lookups. Keyed by
      * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -166,6 +188,18 @@ declare class TopoloClient {
      * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
+    /**
+     * 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.
+     */
+    listActions(options?: {
+        service?: string;
+    }): Promise<TopoloActionCatalogEntry[]>;
+    getAction(action: string): Promise<TopoloActionCatalogEntry>;
+    callAction<T = unknown>(action: string, input?: Record<string, unknown>, options?: {
+        confirm?: boolean;
+    }): Promise<T>;
     /**
      * Bundled generated registry for tooling that audits platform packaging, not
      * for deciding what the current credential may use.
@@ -1536,7 +1570,7 @@ declare function auditAllApplicationRequirements(applicationIds?: readonly Appli
  * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
  *
  * Any entry can be overridden per-call via `TopoloClient` options, or globally
- * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * via env vars like `TOPOLO_SERVICE_URL_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
  * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
@@ -2051,4 +2085,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };
+export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -110,6 +110,27 @@ interface TopoloServiceCatalogEntry {
     launchable: boolean;
     permissions: string[];
 }
+interface TopoloActionCatalogEntry {
+    actionId: string;
+    name: string;
+    toolName: string | null;
+    title: string;
+    description: string;
+    serviceId: string;
+    serviceSlug: string | null;
+    serviceName: string | null;
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    permissionName: string;
+    requiredPermission: string;
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+    readOnly: boolean;
+    destructive: boolean;
+    requiresConfirmation: boolean;
+    status: string | null;
+    sourceRevision: string | null;
+}
 declare class TopoloClient {
     private readonly credential;
     private readonly agent;
@@ -120,6 +141,7 @@ declare class TopoloClient {
     private readonly fetchImpl;
     private readonly debug?;
     private serviceCatalogCache;
+    private actionCatalogCache;
     /**
      * Process-wide cache for slug → service-id lookups. Keyed by
      * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
@@ -166,6 +188,18 @@ declare class TopoloClient {
      * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
+    /**
+     * 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.
+     */
+    listActions(options?: {
+        service?: string;
+    }): Promise<TopoloActionCatalogEntry[]>;
+    getAction(action: string): Promise<TopoloActionCatalogEntry>;
+    callAction<T = unknown>(action: string, input?: Record<string, unknown>, options?: {
+        confirm?: boolean;
+    }): Promise<T>;
     /**
      * Bundled generated registry for tooling that audits platform packaging, not
      * for deciding what the current credential may use.
@@ -1536,7 +1570,7 @@ declare function auditAllApplicationRequirements(applicationIds?: readonly Appli
  * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
  *
  * Any entry can be overridden per-call via `TopoloClient` options, or globally
- * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * via env vars like `TOPOLO_SERVICE_URL_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
  * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
@@ -2051,4 +2085,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };
+export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.js

@@ -2056,6 +2056,8 @@ function resolveServiceUrl(service, overrides) {
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
+var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2069,6 +2071,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
@@ -2329,6 +2332,67 @@ 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, input = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input);
+    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 } : {},
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name
+      },
+      confirm: options.confirm === true
+    });
+  }
   /**
    * Bundled generated registry for tooling that audits platform packaging, not
    * for deciding what the current credential may use.
@@ -2438,6 +2502,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 path = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path || !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,
+    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, input) {
+  const remaining = { ...input || {} };
+  const path = 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,
+      query: objectToQuery({ ...remaining, ...explicitQuery })
+    };
+  }
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== void 0 ? explicitBody : remaining;
+  return {
+    path,
+    ...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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.test.ts

@@ -17,18 +17,83 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown; contentTy
 
 const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
 const SERVICE_LOOKUP = { body: { success: true, data: { service_id: 'service_test' } } };
-const CRM_CATALOG = {
+const MAIL_CATALOG = {
   body: {
     data: {
       services: [
         {
-          service_id: 'srv_crm',
-          app_slug: 'topolo-crm',
-          name: 'Topolo CRM',
-          base_url: 'https://crm-api.topolo.app',
+          service_id: 'srv_mail',
+          app_slug: 'topolo-mail',
+          name: 'Topolo Mail',
+          base_url: 'https://mail-api.topolo.app',
           surface_kind: 'api',
           status: 'active',
-          granted_permissions: ['srv_crm.contacts:read'],
+          granted_permissions: ['srv_mail.messages:read'],
+        },
+      ],
+    },
+  },
+};
+const ACTION_CATALOG = {
+  body: {
+    data: {
+      actions: [
+        {
+          action_id: 'srv_mail.messages.list',
+          name: 'messages.list',
+          tool_name: 'topolo_mail_messages_list',
+          title: 'List messages',
+          description: 'List Mail messages',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'GET',
+          path: '/api/mail/mailboxes/{mailboxId}/messages',
+          permission_name: 'messages:read',
+          required_permission: 'srv_mail.messages:read',
+          input_schema: { type: 'object' },
+          output_schema: {},
+          read_only: true,
+          destructive: false,
+          requires_confirmation: false,
+        },
+        {
+          action_id: 'srv_mail.messages.get',
+          name: 'messages.get',
+          tool_name: 'topolo_mail_messages_get',
+          title: 'Get message',
+          description: 'Get Mail message',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'GET',
+          path: '/api/mail/mailboxes/{mailboxId}/messages/{messageId}',
+          permission_name: 'messages:read',
+          required_permission: 'srv_mail.messages:read',
+          input_schema: { type: 'object' },
+          output_schema: {},
+          read_only: true,
+          destructive: false,
+          requires_confirmation: false,
+        },
+        {
+          action_id: 'srv_mail.messages.send',
+          name: 'messages.send',
+          tool_name: 'topolo_mail_messages_send',
+          title: 'Send message',
+          description: 'Send Mail message',
+          service_id: 'srv_mail',
+          service_slug: 'topolo-mail',
+          service_name: 'Topolo Mail',
+          method: 'POST',
+          path: '/api/mail/mailboxes/{mailboxId}/messages',
+          permission_name: 'messages:send',
+          required_permission: 'srv_mail.messages:send',
+          input_schema: { type: 'object' },
+          output_schema: {},
+          read_only: false,
+          destructive: false,
+          requires_confirmation: true,
         },
       ],
     },
@@ -38,7 +103,8 @@ const CRM_CATALOG = {
 function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
   return calls.filter((call) =>
     !call.url.includes('/api/services/by-slug/') &&
-    !call.url.includes('/api/services/catalog')
+    !call.url.includes('/api/services/catalog') &&
+    !call.url.includes('/api/actions/catalog')
   );
 }
 
@@ -48,7 +114,7 @@ beforeEach(() => {
 
 describe('TopoloClient.request', () => {
   it('injects Bearer auth + audit headers for access_token credentials', async () => {
-    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { ok: true } }]);
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
     const client = new TopoloClient({
       credential: { kind: 'access_token', accessToken: 'tok_abc' },
       agent: AGENT,
@@ -64,13 +130,13 @@ describe('TopoloClient.request', () => {
   });
 
   it('uses X-Api-Key header for api_key credentials', async () => {
-    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { ok: true } }]);
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
       fetch: impl,
     });
-    await client.request({ service: 'crm', path: '/api/contacts' });
+    await client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages' });
     const headers = new Headers(requestCalls(calls)[0]!.init.headers);
     expect(headers.get('X-Api-Key')).toBe('dak_xyz');
     expect(headers.get('Authorization')).toBeNull();
@@ -84,22 +150,22 @@ describe('TopoloClient.request', () => {
       fetch: impl,
     });
     await expect(
-      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {} }),
+      client.request({ service: 'mail', method: 'POST', path: '/api/mail/mailboxes/primary/messages', body: {} }),
     ).rejects.toBeInstanceOf(TopoloAuthError);
   });
 
   it('allows mutating requests with confirm: true', async () => {
-    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { id: 'c_1' } }]);
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { id: 'm_1' } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
       fetch: impl,
     });
     await client.request({
-      service: 'crm',
+      service: 'mail',
       method: 'POST',
-      path: '/api/contacts',
-      body: { email: 'a@b.co' },
+      path: '/api/mail/mailboxes/primary/messages',
+      body: { subject: 'Hello' },
       confirm: true,
     });
     expect(requestCalls(calls)[0]!.init.method).toBe('POST');
@@ -142,8 +208,8 @@ describe('TopoloClient.request', () => {
 
   it('maps 403 → TopoloPermissionError with required scopes extracted', async () => {
     const { impl } = stubFetch([
-      CRM_CATALOG,
-      { status: 403, body: { error: 'forbidden', required: ['crm.contacts:write'] } },
+      MAIL_CATALOG,
+      { status: 403, body: { error: 'forbidden', required: ['mail.messages:send'] } },
     ]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
@@ -151,31 +217,31 @@ describe('TopoloClient.request', () => {
       fetch: impl,
     });
     await expect(
-      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {}, confirm: true }),
+      client.request({ service: 'mail', method: 'POST', path: '/api/mail/mailboxes/primary/messages', body: {}, confirm: true }),
     ).rejects.toBeInstanceOf(TopoloPermissionError);
   });
 
   it('maps non-401/403 failures → TopoloHttpError with status preserved', async () => {
-    const { impl } = stubFetch([CRM_CATALOG, { status: 500, body: { error: 'boom' } }]);
+    const { impl } = stubFetch([MAIL_CATALOG, { status: 500, body: { error: 'boom' } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
       fetch: impl,
     });
-    await expect(client.request({ service: 'crm', path: '/api/contacts' })).rejects.toMatchObject({
+    await expect(client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages' })).rejects.toMatchObject({
       name: 'TopoloHttpError',
       status: 500,
     });
   });
 
   it('appends query params as search string', async () => {
-    const { impl, calls } = stubFetch([CRM_CATALOG, { body: { contacts: [] } }]);
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { messages: [] } }]);
     const client = new TopoloClient({
       credential: { kind: 'api_key', apiKey: 'dak_xyz' },
       agent: AGENT,
       fetch: impl,
     });
-    await client.request({ service: 'crm', path: '/api/contacts', query: { q: 'acme', page: 2 } });
+    await client.request({ service: 'mail', path: '/api/mail/mailboxes/primary/messages', query: { q: 'acme', page: 2 } });
     const u = new URL(requestCalls(calls)[0]!.url);
     expect(u.searchParams.get('q')).toBe('acme');
     expect(u.searchParams.get('page')).toBe('2');
@@ -576,5 +642,89 @@ describe('TopoloClient.listServices', () => {
   });
 });
 
+describe('TopoloClient action catalog', () => {
+  it('lists scoped actions from Auth', async () => {
+    const { impl, calls } = stubFetch([ACTION_CATALOG]);
+    const client = new TopoloClient({
+      credential: { kind: 'access_token', accessToken: 'tok_abc' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+    const actions = await client.listActions();
+    expect(actions.map((action) => action.name)).toEqual([
+      'messages.list',
+      'messages.get',
+      'messages.send',
+    ]);
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/actions/catalog');
+  });
+
+  it('calls GET actions by mapping remaining input to query params', async () => {
+    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { messages: [] } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+    await client.callAction('messages.list', { mailboxId: 'primary', q: 'Ada', page: 2 });
+    const call = requestCalls(calls)[0]!;
+    const url = new URL(call.url);
+    expect(url.toString()).toBe('https://mail-api.topolo.app/api/mail/mailboxes/primary/messages?q=Ada&page=2');
+    expect(call.init.method).toBe('GET');
+    const headers = new Headers(call.init.headers);
+    expect(headers.get('X-Topolo-Action-Id')).toBe('srv_mail.messages.list');
+    expect(headers.get('X-Topolo-Action-Name')).toBe('messages.list');
+  });
+
+  it('substitutes action path params and removes them from the query', async () => {
+    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { id: 'm1' } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+    await client.callAction('topolo_mail_messages_get', {
+      mailboxId: 'primary',
+      messageId: 'm 1',
+      includeDeleted: false,
+    });
+    const url = new URL(requestCalls(calls)[0]!.url);
+    expect(url.pathname).toBe('/api/mail/mailboxes/primary/messages/m%201');
+    expect(url.searchParams.get('includeDeleted')).toBe('false');
+    expect(url.searchParams.has('mailboxId')).toBe(false);
+    expect(url.searchParams.has('messageId')).toBe(false);
+  });
+
+  it('requires confirmation for mutating action calls', async () => {
+    const { impl } = stubFetch([ACTION_CATALOG]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+    await expect(
+      client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }),
+    ).rejects.toBeInstanceOf(TopoloAuthError);
+  });
+
+  it('sends remaining input as the body when a mutating action is confirmed', async () => {
+    const { impl, calls } = stubFetch([ACTION_CATALOG, MAIL_CATALOG, { body: { id: 'm1' } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+    await client.callAction('messages.send', { mailboxId: 'primary', subject: 'Hello' }, { confirm: true });
+    const call = requestCalls(calls)[0]!;
+    expect(call.init.method).toBe('POST');
+    expect(JSON.parse(String(call.init.body))).toEqual({ subject: 'Hello' });
+  });
+});
+
 // Silence unused-import warning if the bundler later tree-shakes these
 void TopoloHttpError;

package/src/client.ts

@@ -83,6 +83,8 @@ export interface RequestOptions {
 }
 
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const TOPOLO_ACTION_ID_HEADER = 'X-Topolo-Action-Id';
+const TOPOLO_ACTION_NAME_HEADER = 'X-Topolo-Action-Name';
 
 const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
@@ -110,6 +112,28 @@ export interface TopoloServiceCatalogEntry {
   permissions: string[];
 }
 
+export interface TopoloActionCatalogEntry {
+  actionId: string;
+  name: string;
+  toolName: string | null;
+  title: string;
+  description: string;
+  serviceId: string;
+  serviceSlug: string | null;
+  serviceName: string | null;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path: string;
+  permissionName: string;
+  requiredPermission: string;
+  inputSchema: Record<string, unknown>;
+  outputSchema: Record<string, unknown>;
+  readOnly: boolean;
+  destructive: boolean;
+  requiresConfirmation: boolean;
+  status: string | null;
+  sourceRevision: string | null;
+}
+
 export class TopoloClient {
   private readonly credential: TopoloCredential;
   private readonly agent: AgentIdentity;
@@ -120,6 +144,7 @@ export class TopoloClient {
   private readonly fetchImpl: typeof fetch;
   private readonly debug?: (event: TopoloDebugEvent) => void;
   private serviceCatalogCache: { entries: TopoloServiceCatalogEntry[]; expiresAt: number } | null = null;
+  private actionCatalogCache: { entries: TopoloActionCatalogEntry[]; expiresAt: number } | null = null;
 
   /**
    * Process-wide cache for slug → service-id lookups. Keyed by
@@ -437,6 +462,83 @@ export 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: { service?: string } = {}): Promise<TopoloActionCatalogEntry[]> {
+    const now = Date.now();
+    if (!options.service && this.actionCatalogCache && this.actionCatalogCache.expiresAt > now) {
+      return this.actionCatalogCache.entries;
+    }
+
+    const res = await this.request<
+      | { data?: { actions?: unknown[] } }
+      | { actions?: unknown[] }
+    >({
+      service: 'auth',
+      method: 'GET',
+      path: '/api/actions/catalog',
+      ...(options.service ? { query: { service: options.service } } : {}),
+    });
+    const raw =
+      (res as { data?: { actions?: unknown[] } }).data?.actions ??
+      (res as { actions?: unknown[] }).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): entry is TopoloActionCatalogEntry => Boolean(entry));
+    if (!options.service) {
+      this.actionCatalogCache = {
+        entries,
+        expiresAt: now + CATALOG_CACHE_TTL_MS,
+      };
+    }
+    return entries;
+  }
+
+  async getAction(action: string): Promise<TopoloActionCatalogEntry> {
+    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<T = unknown>(
+    action: string,
+    input: Record<string, unknown> = {},
+    options: { confirm?: boolean } = {},
+  ): Promise<T> {
+    const entry = await this.getAction(action);
+    const mapped = mapActionInput(entry, input);
+    const service = entry.serviceSlug || entry.serviceId;
+    return this.request<T>({
+      service,
+      method: entry.method,
+      path: mapped.path,
+      ...(mapped.query ? { query: mapped.query } : {}),
+      ...(mapped.body !== undefined ? { body: mapped.body } : {}),
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name,
+      },
+      confirm: options.confirm === true,
+    });
+  }
+
   /**
    * Bundled generated registry for tooling that audits platform packaging, not
    * for deciding what the current credential may use.
@@ -581,6 +683,119 @@ function isCallableCatalogEntry(entry: TopoloServiceCatalogEntry): boolean {
   );
 }
 
+function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry | null {
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+  const a = item as Record<string, unknown>;
+  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 path = pickActionString(a.path);
+  if (!actionId || !name || !serviceId || !method || !path || !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,
+    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: string): value is TopoloActionCatalogEntry['method'] {
+  return value === 'GET' || value === 'POST' || value === 'PUT' || value === 'PATCH' || value === 'DELETE';
+}
+
+function pickActionString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function plainObject(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : {};
+}
+
+function normalizeActionLookupKey(value: string): string {
+  return String(value || '').trim().toLowerCase();
+}
+
+function actionEntryMatches(entry: TopoloActionCatalogEntry, needle: string): boolean {
+  if (!needle) return false;
+  return [entry.actionId, entry.name, entry.toolName]
+    .filter((value): value is string => typeof value === 'string' && value.length > 0)
+    .some((value) => value.toLowerCase() === needle);
+}
+
+function mapActionInput(
+  action: TopoloActionCatalogEntry,
+  input: Record<string, unknown>,
+): { path: string; query?: Record<string, string | number | boolean>; body?: unknown } {
+  const remaining: Record<string, unknown> = { ...(input || {}) };
+  const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key: string) => {
+    const value = remaining[key];
+    if (value === undefined || 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
+    : undefined;
+  delete remaining.body;
+
+  if (action.method === 'GET') {
+    return {
+      path,
+      query: objectToQuery({ ...remaining, ...explicitQuery }),
+    };
+  }
+
+  const query = objectToQuery(explicitQuery);
+  const body = explicitBody !== undefined ? explicitBody : remaining;
+  return {
+    path,
+    ...(query ? { query } : {}),
+    body,
+  };
+}
+
+function objectToQuery(value: Record<string, unknown>): Record<string, string | number | boolean> | undefined {
+  const query: Record<string, string | number | boolean> = {};
+  for (const [key, raw] of Object.entries(value)) {
+    if (raw === undefined || 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 : undefined;
+}
+
 interface AuthMePayload {
   credentialType?: 'access_token' | 'api_key';
   user: RawUser;

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type CredentialIntrospection,
   type TopoloDebugEvent,
   type TopoloServiceCatalogEntry,
+  type TopoloActionCatalogEntry,
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";
 export {

package/src/services.ts

@@ -6,7 +6,7 @@
  * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
  *
  * Any entry can be overridden per-call via `TopoloClient` options, or globally
- * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * via env vars like `TOPOLO_SERVICE_URL_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
  * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is