@topolo/sdk 0.4.1 → 0.4.3

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
 
@@ -89,12 +99,29 @@ PlatformApplications metadata, including Worker apps that do not expose a
 callable service. `DEFAULT_SERVICE_URLS` is the bundled callable API service
 snapshot generated from `topolo.cloudcontrol.json`.
 
-For agent-scale fleets, the bundle is a floor, not a cap. `TopoloClient.request`
-accepts bundled service IDs and live Auth-catalog service IDs/slugs. When a
-service is not in the bundled snapshot, the client resolves the selected
-environment's live catalog and only routes entries marked as API/technical
-service surfaces. Browser/runtime surfaces are not treated as generic API
-targets.
+For agent-scale fleets, the bundle is packaging metadata, not an authorization
+source. `TopoloClient.listServices()` always calls the live TopoloAuth catalog
+with the current credential and returns only services that credential can use in
+its organization, including the granted permissions. `TopoloClient.request()`
+uses that credential-scoped catalog before routing any non-Auth service, so a
+bundled 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()`
@@ -159,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

@@ -2123,6 +2123,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
@@ -2258,12 +2259,16 @@ var TopoloClient = class _TopoloClient {
     if (!serviceKey) {
       throw new TopoloSdkError("unknown_service", "service is required");
     }
-    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
-    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey];
-    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+    if (serviceKey === "auth") {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+    }
     const live = await this.resolveLiveCallableService(serviceKey);
-    if (live) return live;
+    if (live) {
+      const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+      return overrideUrl ? { ...live, baseUrl: overrideUrl } : live;
+    }
     throw new TopoloSdkError(
       "unknown_service",
       `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
@@ -2273,10 +2278,7 @@ var TopoloClient = class _TopoloClient {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
     if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return {
-      serviceKey: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
-      baseUrl: match.baseUrl
-    };
+    return { serviceKey, baseUrl: match.baseUrl };
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2338,53 +2340,112 @@ var TopoloClient = class _TopoloClient {
   /**
    * List the platform service catalog from the live registry
    * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-   * caller's credential is attached, so an authenticated caller in an
-   * entitled org also receives the `developer_only` services its role
-   * permits; an unauthenticated/agent caller receives `active` only.
+   * caller's credential is attached, so the result only includes services the
+   * credential's organization and effective permissions can use.
    *
-   * Resilient: on any network/HTTP failure this falls back to the
-   * build-time generated `APPLICATIONS` snapshot so offline/degraded
-   * callers still get a usable (if static) catalog. The live result is
-   * authoritative; the snapshot is a floor, not a cap.
+   * Security boundary: this never falls back to the generated global snapshot.
+   * The live Auth catalog is the authority because it is scoped to the caller's
+   * organization and effective permissions.
    */
   async listServices() {
     const now = Date.now();
     if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
       return this.serviceCatalogCache.entries;
     }
-    try {
-      const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
-      const raw = res.data?.services ?? res.services;
-      if (Array.isArray(raw) && raw.length > 0) {
-        const entries = [];
-        for (const item of raw) {
-          const s = item;
-          const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
-          if (!serviceId) continue;
-          entries.push({
-            serviceId,
-            slug: typeof s.app_slug === "string" ? s.app_slug : null,
-            name: typeof s.name === "string" ? s.name : null,
-            description: typeof s.description === "string" ? s.description : null,
-            baseUrl: typeof s.base_url === "string" ? s.base_url : null,
-            status: typeof s.status === "string" ? s.status : null,
-            surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
-            launchable: s.launchable === true
-          });
-        }
-        if (entries.length > 0) {
-          this.serviceCatalogCache = {
-            entries,
-            expiresAt: now + CATALOG_CACHE_TTL_MS
-          };
-          return entries;
-        }
-      }
-    } catch {
+    const res = await this.request({ service: "auth", method: "GET", path: "/api/services/catalog" });
+    const raw = res.data?.services ?? res.services;
+    if (!Array.isArray(raw)) {
+      throw new TopoloSdkError(
+        "service_catalog_unavailable",
+        "TopoloAuth did not return a service catalog for the current credential."
+      );
+    }
+    const entries = [];
+    for (const item of raw) {
+      const s = item;
+      const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
+      if (!serviceId) continue;
+      const permissions = Array.isArray(s.granted_permissions) ? s.granted_permissions.filter((permission) => typeof permission === "string" && permission.trim().length > 0) : [];
+      entries.push({
+        serviceId,
+        slug: typeof s.app_slug === "string" ? s.app_slug : null,
+        name: typeof s.name === "string" ? s.name : null,
+        description: typeof s.description === "string" ? s.description : null,
+        baseUrl: typeof s.base_url === "string" ? s.base_url : null,
+        status: typeof s.status === "string" ? s.status : null,
+        surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
+        launchable: s.launchable === true,
+        permissions
+      });
     }
-    return this.generatedCatalogFallback();
+    this.serviceCatalogCache = {
+      entries,
+      expiresAt: now + CATALOG_CACHE_TTL_MS
+    };
+    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 } : {},
+      confirm: options.confirm === true
+    });
   }
-  generatedCatalogFallback() {
+  /**
+   * Bundled generated registry for tooling that audits platform packaging, not
+   * for deciding what the current credential may use.
+   */
+  listBundledServices() {
     const apps = Object.values(APPLICATIONS);
     return apps.map((app) => ({
       serviceId: app.id,
@@ -2392,9 +2453,10 @@ var TopoloClient = class _TopoloClient {
       name: app.name ?? app.id,
       description: null,
       baseUrl: app.productionUrl ?? null,
-      status: "active",
+      status: "bundled",
       surfaceKind: "application",
-      launchable: Boolean(app.productionUrl)
+      launchable: Boolean(app.productionUrl),
+      permissions: []
     }));
   }
   /**
@@ -2464,7 +2526,7 @@ function serviceKeyCandidates(slug) {
   ])];
 }
 function normalizeLookupKey(value) {
-  return String(value || "").trim().toLowerCase();
+  return String(value || "").trim().toLowerCase().replace(/\s+/g, "-");
 }
 function catalogEntryMatches(entry, needle) {
   return catalogEntryLookupKeys(entry).includes(needle);
@@ -2475,12 +2537,8 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    keys.add(normalized);
-    keys.add(normalized.replace(/-/g, "_"));
-    if (normalized.startsWith("topolo-")) {
-      const withoutTopolo = normalized.slice("topolo-".length);
-      keys.add(withoutTopolo);
-      keys.add(withoutTopolo.replace(/-/g, "_"));
+    for (const candidate of serviceKeyCandidates(normalized)) {
+      keys.add(candidate);
     }
   }
   return [...keys];
@@ -2488,7 +2546,101 @@ function catalogEntryLookupKeys(entry) {
 function isCallableCatalogEntry(entry) {
   const kind = normalizeLookupKey(entry.surfaceKind || "");
   if (kind === "api" || kind === "technical_service" || kind === "service") return true;
-  return Boolean(entry.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ""));
+  return Boolean(
+    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") {

package/dist/index.d.cts

@@ -108,6 +108,28 @@ interface TopoloServiceCatalogEntry {
     status: string | null;
     surfaceKind: string | null;
     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;
@@ -119,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
@@ -157,17 +180,31 @@ declare class TopoloClient {
     /**
      * List the platform service catalog from the live registry
      * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-     * caller's credential is attached, so an authenticated caller in an
-     * entitled org also receives the `developer_only` services its role
-     * permits; an unauthenticated/agent caller receives `active` only.
+     * caller's credential is attached, so the result only includes services the
+     * credential's organization and effective permissions can use.
      *
-     * Resilient: on any network/HTTP failure this falls back to the
-     * build-time generated `APPLICATIONS` snapshot so offline/degraded
-     * callers still get a usable (if static) catalog. The live result is
-     * authoritative; the snapshot is a floor, not a cap.
+     * Security boundary: this never falls back to the generated global snapshot.
+     * The live Auth catalog is the authority because it is scoped to the caller's
+     * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
-    private generatedCatalogFallback;
+    /**
+     * 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.
+     */
+    listBundledServices(): TopoloServiceCatalogEntry[];
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -1533,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
@@ -2048,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

@@ -108,6 +108,28 @@ interface TopoloServiceCatalogEntry {
     status: string | null;
     surfaceKind: string | null;
     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;
@@ -119,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
@@ -157,17 +180,31 @@ declare class TopoloClient {
     /**
      * List the platform service catalog from the live registry
      * (`GET /api/services/catalog` on TopoloAuth). Credential-aware: the
-     * caller's credential is attached, so an authenticated caller in an
-     * entitled org also receives the `developer_only` services its role
-     * permits; an unauthenticated/agent caller receives `active` only.
+     * caller's credential is attached, so the result only includes services the
+     * credential's organization and effective permissions can use.
      *
-     * Resilient: on any network/HTTP failure this falls back to the
-     * build-time generated `APPLICATIONS` snapshot so offline/degraded
-     * callers still get a usable (if static) catalog. The live result is
-     * authoritative; the snapshot is a floor, not a cap.
+     * Security boundary: this never falls back to the generated global snapshot.
+     * The live Auth catalog is the authority because it is scoped to the caller's
+     * organization and effective permissions.
      */
     listServices(): Promise<TopoloServiceCatalogEntry[]>;
-    private generatedCatalogFallback;
+    /**
+     * 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.
+     */
+    listBundledServices(): TopoloServiceCatalogEntry[];
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -1533,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
@@ -2048,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 };