@topolo/sdk 0.3.0 → 0.4.0

package/README.md

@@ -103,7 +103,7 @@ their own `GET /api/widget` endpoint. The SDK owns the shared payload contract:
 import { createTopoloWidgetResponse } from '@topolo/sdk';
 
 return Response.json(createTopoloWidgetResponse({
-  serviceId: 'srv_topolo_example',
+  serviceId: '<runtime-service-id>',
   serviceName: 'Example',
   widgets: [
     {

package/dist/index.cjs

@@ -27,7 +27,6 @@ __export(index_exports, {
   DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
   IdentityModule: () => IdentityModule,
   P2PModule: () => P2PModule,
-  PLATFORM_SERVICE_IDS: () => PLATFORM_SERVICE_IDS,
   TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS: () => TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError: () => TopoloAuthError,
@@ -146,41 +145,20 @@ var SERVICES = {
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
   people: "https://people.topolo.app",
+  pulse: "https://pulse.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
   roadmapper: "https://roadmapper-api.topolo.app",
   sign: "https://sign.topolo.app",
   social_studio: "https://studio-api.topolo.app",
   socialize: "https://socialize-api.topolo.app",
+  spaces: "https://spaces.topolo.app",
   status: "https://status.topolo.app",
   support: "https://support.topolo.app",
   survey: "https://survey.topolo.app",
   voice: "https://voice.topolo.app",
   web: "https://web-api.topolo.app"
 };
-var PLATFORM_SERVICE_IDS = {
-  books: "srv_0g260hbN8oqv",
-  bugfix: "srv_kQ1t8qUSDgNs",
-  compose: "srv_aR3ETYmgygmd",
-  consent: "srv_8FIGR7Q7zP9r",
-  crm: "srv_iCwM4jGXcwlj",
-  customer_success: "srv_RWpOxkgZdZbH",
-  developers: "srv_NjDq9G9qyyjr",
-  director: "srv_wRCnLLbtvmVT",
-  flow: "srv_GBCuKkHhnRXv",
-  forms: "srv_UE7IcGe80J5o",
-  home: "srv_hE6HBldVzjth",
-  insights: "srv_DgbBMwWSIhmC",
-  inventory: "srv_hmvjbv3ZxDnh",
-  localize: "srv_Ze1g9OmXuZjF",
-  notify: "srv_9pRdkIjYyKX0",
-  p2p: "srv_4BzeLqH0wCve",
-  people: "srv_VDMBAonA5fKb",
-  sign: "srv_Bd8pRw5ZqRBT",
-  status: "srv_topolo_status",
-  survey: "srv_RCOi7CJkwf7R",
-  voice: "srv_BZANHkshGAK5"
-};
 
 // src/applications.generated.ts
 var APPLICATIONS = {
@@ -260,6 +238,24 @@ var APPLICATIONS = {
       }
     ]
   },
+  "backup": {
+    "id": "backup",
+    "appDir": "TopoloBackup",
+    "name": "topolo-backup",
+    "packageName": "topolo-backup",
+    "productionUrl": null,
+    "services": [],
+    "deployTargets": [
+      {
+        "name": "topolo-backup",
+        "kind": "worker",
+        "apiUrl": null,
+        "domains": [],
+        "routes": [],
+        "serviceId": null
+      }
+    ]
+  },
   "books": {
     "id": "books",
     "appDir": "TopoloBooks",
@@ -410,15 +406,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "cli": {
-    "id": "cli",
-    "appDir": "TopoloCli",
-    "name": "@topolo/cli",
-    "packageName": "@topolo/cli",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
-  },
   "cloudcontrol": {
     "id": "cloudcontrol",
     "appDir": "TopoloCloudControl",
@@ -584,24 +571,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "d1_backup": {
-    "id": "d1_backup",
-    "appDir": "TopoloD1Backup",
-    "name": "topolo-d1-backup",
-    "packageName": "topolo-d1-backup",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": [
-      {
-        "name": "topolo-d1-backup",
-        "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
-        "serviceId": null
-      }
-    ]
-  },
   "developers": {
     "id": "developers",
     "appDir": "TopoloDevelopers",
@@ -944,15 +913,6 @@ var APPLICATIONS = {
       }
     ]
   },
-  "mcp": {
-    "id": "mcp",
-    "appDir": "TopoloMCP",
-    "name": "@topolo/mcp",
-    "packageName": "@topolo/mcp",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
-  },
   "mdm": {
     "id": "mdm",
     "appDir": "TopoloMDM",
@@ -1087,7 +1047,7 @@ var APPLICATIONS = {
   "one": {
     "id": "one",
     "appDir": "TopoloOne",
-    "name": "topolo-oneclick-sso",
+    "name": "TopoloOne",
     "packageName": "topolo-oneclick-sso",
     "productionUrl": "https://one.topolo.app",
     "services": [
@@ -1208,9 +1168,24 @@ var APPLICATIONS = {
     "appDir": "TopoloPulse",
     "name": "topolo-pulse",
     "packageName": "topolo-pulse",
-    "productionUrl": null,
-    "services": [],
-    "deployTargets": []
+    "productionUrl": "https://pulse.topolo.app",
+    "services": [
+      "pulse"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-pulse",
+        "kind": "worker",
+        "apiUrl": "https://pulse.topolo.app",
+        "domains": [
+          "pulse.topolo.app"
+        ],
+        "routes": [
+          "pulse.topolo.app"
+        ],
+        "serviceId": "pulse"
+      }
+    ]
   },
   "quro": {
     "id": "quro",
@@ -1393,6 +1368,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "spaces": {
+    "id": "spaces",
+    "appDir": "TopoloSpaces",
+    "name": "topolo-spaces",
+    "packageName": "@topolo/spaces",
+    "productionUrl": "https://spaces.topolo.app",
+    "services": [
+      "spaces"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-spaces",
+        "kind": "worker",
+        "apiUrl": "https://spaces.topolo.app",
+        "domains": [
+          "spaces.topolo.app"
+        ],
+        "routes": [
+          "spaces.topolo.app"
+        ],
+        "serviceId": "spaces"
+      }
+    ]
+  },
   "status": {
     "id": "status",
     "appDir": "TopoloStatus",
@@ -1574,12 +1573,12 @@ var APPLICATION_REQUIREMENTS = [
     summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.",
     appliesTo: ["browser", "api", "tooling", "agent_surface"],
     evidence: [
-      "@topolo/auth-client or @topolo/auth-middleware is used where applicable",
+      "@topolo/auth-client or @topolo-io/worker-runtime is used where applicable",
       "No public command, tool, or SDK method accepts orgId",
       "Service slug and Auth service registration are documented for protected services"
     ],
     implementation: [
-      "Use shared auth packages instead of copying token parsing or browser storage flows",
+      "Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows",
       "Derive organization from the credential on every request",
       "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"
     ]
@@ -1719,14 +1718,15 @@ var APPLICATION_REQUIREMENTS = [
 ];
 function applicationRequirementScopes(application) {
   const scopes = /* @__PURE__ */ new Set(["all"]);
+  const appId = application.id;
   const hasBrowserSurface = Boolean(application.productionUrl) || application.deployTargets.some((target) => target.kind === "pages");
   const hasApiSurface = application.services.length > 0 || application.deployTargets.some((target) => Boolean(target.apiUrl));
   if (hasBrowserSurface) scopes.add("browser");
   if (hasApiSurface) scopes.add("api");
-  if (application.id === "cli" || application.id === "mcp" || application.id === "cloudcontrol") {
+  if (appId === "cli" || appId === "mcp" || appId === "cloudcontrol") {
     scopes.add("tooling");
   }
-  if (application.id === "cli" || application.id === "mcp" || hasApiSurface) {
+  if (appId === "cli" || appId === "mcp" || hasApiSurface) {
     scopes.add("agent_surface");
   }
   return Array.from(scopes);
@@ -1845,12 +1845,13 @@ function evaluateRequirement(application, requirement) {
       return finding(requirement, "met", "CloudControl deploy target metadata is present.", evidence);
     }
     case "agent-and-operator-surfaces": {
+      const appId = application.id;
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(",")}`);
         return finding(requirement, "partial", "SDK service discovery exists; typed SDK/CLI/MCP workflow coverage should be checked as APIs stabilize.", evidence);
       }
-      if (application.id === "cli" || application.id === "mcp" || application.id === "cloudcontrol") {
-        evidence.push(`tooling=${application.id}`);
+      if (appId === "cli" || appId === "mcp" || appId === "cloudcontrol") {
+        evidence.push(`tooling=${appId}`);
         return finding(requirement, "met", "This application is itself an agent/operator surface.", evidence);
       }
       return finding(requirement, "missing", "No SDK service or tooling surface is registered.", evidence);
@@ -1931,6 +1932,7 @@ var TopoloClient = class _TopoloClient {
   credential;
   agent;
   serviceUrls;
+  serviceIds;
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
@@ -1955,6 +1957,7 @@ var TopoloClient = class _TopoloClient {
     this.credential = options.credential;
     this.agent = options.agent;
     this.serviceUrls = options.serviceUrls;
+    this.serviceIds = options.serviceIds;
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
@@ -1989,7 +1992,7 @@ var TopoloClient = class _TopoloClient {
     const headers = new Headers();
     headers.set("Accept", "application/json");
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
-    const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
+    const platformServiceId = resolveConfiguredServiceId(opts.service, this.serviceIds);
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
     const requestId = generateRequestId();
@@ -2064,12 +2067,7 @@ var TopoloClient = class _TopoloClient {
     return parsed;
   }
   /**
-   * Resolve a service-slug → opaque service-id via TopoloAuth.
-   *
-   * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
-   * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
-   * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
-   * understands both.
+   * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
    *
    * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
    * results (404) are cached for 60s so a typo doesn't hot-loop the
@@ -2084,6 +2082,8 @@ var TopoloClient = class _TopoloClient {
     if (typeof slug !== "string") return null;
     const normalized = slug.trim().toLowerCase();
     if (!normalized) return null;
+    const configuredServiceId = resolveConfiguredServiceId(normalized, this.serviceIds);
+    if (configuredServiceId) return configuredServiceId;
     const authBase = resolveServiceUrl("auth", this.serviceUrls);
     const cacheKey = `${authBase}|${normalized}`;
     const now = Date.now();
@@ -2123,6 +2123,58 @@ var TopoloClient = class _TopoloClient {
     });
     return value;
   }
+  /**
+   * 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.
+   *
+   * 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.
+   */
+  async listServices() {
+    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) return entries;
+      }
+    } catch {
+    }
+    return this.generatedCatalogFallback();
+  }
+  generatedCatalogFallback() {
+    const apps = Object.values(APPLICATIONS);
+    return apps.map((app) => ({
+      serviceId: app.id,
+      slug: app.id,
+      name: app.name ?? app.id,
+      description: null,
+      baseUrl: app.productionUrl ?? null,
+      status: "active",
+      surfaceKind: "application",
+      launchable: Boolean(app.productionUrl)
+    }));
+  }
   /**
    * Introspect the current credential. Returns the caller's resolved identity,
    * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -2159,6 +2211,26 @@ var TopoloClient = class _TopoloClient {
     };
   }
 };
+function resolveConfiguredServiceId(slug, serviceIds) {
+  for (const serviceKey of serviceKeyCandidates(slug)) {
+    const configured = serviceIds?.[serviceKey];
+    if (typeof configured === "string" && configured.trim()) return configured.trim();
+    const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (typeof envValue === "string" && envValue.trim()) return envValue.trim();
+  }
+  return null;
+}
+function serviceKeyCandidates(slug) {
+  const normalized = slug.trim().toLowerCase();
+  const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, "_")
+  ])];
+}
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
@@ -2725,7 +2797,6 @@ function createTopolo(options) {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   P2PModule,
-  PLATFORM_SERVICE_IDS,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,

package/dist/index.d.cts

@@ -65,12 +65,14 @@ declare const SERVICES: {
     readonly p2p: "https://p2p.topolo.app";
     readonly pay: "https://pay.topolo.app";
     readonly people: "https://people.topolo.app";
+    readonly pulse: "https://pulse.topolo.app";
     readonly "quro.api": "https://api.ol0.me";
     readonly "quro.redirect": "https://ol0.me";
     readonly roadmapper: "https://roadmapper-api.topolo.app";
     readonly sign: "https://sign.topolo.app";
     readonly social_studio: "https://studio-api.topolo.app";
     readonly socialize: "https://socialize-api.topolo.app";
+    readonly spaces: "https://spaces.topolo.app";
     readonly status: "https://status.topolo.app";
     readonly support: "https://support.topolo.app";
     readonly survey: "https://survey.topolo.app";
@@ -78,15 +80,6 @@ declare const SERVICES: {
     readonly web: "https://web-api.topolo.app";
 };
 type ServiceId = keyof typeof SERVICES;
-/**
- * @deprecated since 0.3.0 — opaque service ids are no longer baked into the
- * SDK. Use `TopoloClient.getServiceIdBySlug(slug)` which hits
- * `GET /api/services/by-slug/:slug` on TopoloAuth at runtime. This map is
- * still populated as a build-time snapshot for backward compatibility and
- * will be removed in 0.4.0. Stale entries are expected — do not rely on
- * presence/absence for catalog membership.
- */
-declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 
 declare const APPLICATIONS: {
     readonly admin: {
@@ -144,6 +137,22 @@ declare const APPLICATIONS: {
             readonly serviceId: "auth";
         }];
     };
+    readonly backup: {
+        readonly id: "backup";
+        readonly appDir: "TopoloBackup";
+        readonly name: "topolo-backup";
+        readonly packageName: "topolo-backup";
+        readonly productionUrl: null;
+        readonly services: readonly [];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-backup";
+            readonly kind: "worker";
+            readonly apiUrl: null;
+            readonly domains: readonly [];
+            readonly routes: readonly [];
+            readonly serviceId: null;
+        }];
+    };
     readonly books: {
         readonly id: "books";
         readonly appDir: "TopoloBooks";
@@ -247,15 +256,6 @@ declare const APPLICATIONS: {
             readonly serviceId: "chat";
         }];
     };
-    readonly cli: {
-        readonly id: "cli";
-        readonly appDir: "TopoloCli";
-        readonly name: "@topolo/cli";
-        readonly packageName: "@topolo/cli";
-        readonly productionUrl: null;
-        readonly services: readonly [];
-        readonly deployTargets: readonly [];
-    };
     readonly cloudcontrol: {
         readonly id: "cloudcontrol";
         readonly appDir: "TopoloCloudControl";
@@ -373,22 +373,6 @@ declare const APPLICATIONS: {
             readonly serviceId: "customer_success";
         }];
     };
-    readonly d1_backup: {
-        readonly id: "d1_backup";
-        readonly appDir: "TopoloD1Backup";
-        readonly name: "topolo-d1-backup";
-        readonly packageName: "topolo-d1-backup";
-        readonly productionUrl: null;
-        readonly services: readonly [];
-        readonly deployTargets: readonly [{
-            readonly name: "topolo-d1-backup";
-            readonly kind: "worker";
-            readonly apiUrl: null;
-            readonly domains: readonly [];
-            readonly routes: readonly [];
-            readonly serviceId: null;
-        }];
-    };
     readonly developers: {
         readonly id: "developers";
         readonly appDir: "TopoloDevelopers";
@@ -625,15 +609,6 @@ declare const APPLICATIONS: {
             readonly serviceId: "mail";
         }];
     };
-    readonly mcp: {
-        readonly id: "mcp";
-        readonly appDir: "TopoloMCP";
-        readonly name: "@topolo/mcp";
-        readonly packageName: "@topolo/mcp";
-        readonly productionUrl: null;
-        readonly services: readonly [];
-        readonly deployTargets: readonly [];
-    };
     readonly mdm: {
         readonly id: "mdm";
         readonly appDir: "TopoloMDM";
@@ -731,7 +706,7 @@ declare const APPLICATIONS: {
     readonly one: {
         readonly id: "one";
         readonly appDir: "TopoloOne";
-        readonly name: "topolo-oneclick-sso";
+        readonly name: "TopoloOne";
         readonly packageName: "topolo-oneclick-sso";
         readonly productionUrl: "https://one.topolo.app";
         readonly services: readonly ["one"];
@@ -811,9 +786,16 @@ declare const APPLICATIONS: {
         readonly appDir: "TopoloPulse";
         readonly name: "topolo-pulse";
         readonly packageName: "topolo-pulse";
-        readonly productionUrl: null;
-        readonly services: readonly [];
-        readonly deployTargets: readonly [];
+        readonly productionUrl: "https://pulse.topolo.app";
+        readonly services: readonly ["pulse"];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-pulse";
+            readonly kind: "worker";
+            readonly apiUrl: "https://pulse.topolo.app";
+            readonly domains: readonly ["pulse.topolo.app"];
+            readonly routes: readonly ["pulse.topolo.app"];
+            readonly serviceId: "pulse";
+        }];
     };
     readonly quro: {
         readonly id: "quro";
@@ -944,6 +926,22 @@ declare const APPLICATIONS: {
             readonly serviceId: null;
         }];
     };
+    readonly spaces: {
+        readonly id: "spaces";
+        readonly appDir: "TopoloSpaces";
+        readonly name: "topolo-spaces";
+        readonly packageName: "@topolo/spaces";
+        readonly productionUrl: "https://spaces.topolo.app";
+        readonly services: readonly ["spaces"];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-spaces";
+            readonly kind: "worker";
+            readonly apiUrl: "https://spaces.topolo.app";
+            readonly domains: readonly ["spaces.topolo.app"];
+            readonly routes: readonly ["spaces.topolo.app"];
+            readonly serviceId: "spaces";
+        }];
+    };
     readonly status: {
         readonly id: "status";
         readonly appDir: "TopoloStatus";
@@ -1110,8 +1108,8 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly title: "Use the shared Topolo auth boundary";
     readonly summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.";
     readonly appliesTo: readonly ["browser", "api", "tooling", "agent_surface"];
-    readonly evidence: readonly ["@topolo/auth-client or @topolo/auth-middleware is used where applicable", "No public command, tool, or SDK method accepts orgId", "Service slug and Auth service registration are documented for protected services"];
-    readonly implementation: readonly ["Use shared auth packages instead of copying token parsing or browser storage flows", "Derive organization from the credential on every request", "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"];
+    readonly evidence: readonly ["@topolo/auth-client or @topolo-io/worker-runtime is used where applicable", "No public command, tool, or SDK method accepts orgId", "Service slug and Auth service registration are documented for protected services"];
+    readonly implementation: readonly ["Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows", "Derive organization from the credential on every request", "Route OAuth, refresh, logout, and SSO paths according to the shared Auth contract"];
 }, {
     readonly id: "shared-shell-and-launcher";
     readonly title: "Use the shared shell, launcher, and account menu";
@@ -1198,6 +1196,8 @@ interface TopoloClientOptions {
     agent: AgentIdentity;
     /** Per-service URL overrides. Useful for staging/dev. */
     serviceUrls?: Partial<Record<ServiceId, string>>;
+    /** Per-service TopoloAuth service id overrides from the owning app/deployment. */
+    serviceIds?: Partial<Record<ServiceId, string>>;
     /**
      * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
      * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
@@ -1254,10 +1254,26 @@ interface RequestOptions {
     headers?: Record<string, string>;
     signal?: AbortSignal;
 }
+/**
+ * A single entry from the live platform service catalog. Returned by
+ * {@link TopoloClient.listServices}. Shape mirrors the public-safe projection
+ * from TopoloAuth `GET /api/services/catalog`.
+ */
+interface TopoloServiceCatalogEntry {
+    serviceId: string;
+    slug: string | null;
+    name: string | null;
+    description: string | null;
+    baseUrl: string | null;
+    status: string | null;
+    surfaceKind: string | null;
+    launchable: boolean;
+}
 declare class TopoloClient {
     private readonly credential;
     private readonly agent;
     private readonly serviceUrls?;
+    private readonly serviceIds?;
     private readonly requireConfirmForWrites;
     private readonly timeoutMs;
     private readonly fetchImpl;
@@ -1283,12 +1299,7 @@ declare class TopoloClient {
      */
     request<T = unknown>(opts: RequestOptions): Promise<T>;
     /**
-     * Resolve a service-slug → opaque service-id via TopoloAuth.
-     *
-     * Replaces the SDK-baked `PLATFORM_SERVICE_IDS` map (deprecated in 0.3.0,
-     * removed in 0.4.0). Slug shape accepted: either the canonical Auth slug
-     * (e.g. `topolo-notify`) or the SDK short id (`notify`) — Auth's resolver
-     * understands both.
+     * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
      *
      * Cache: 5 minutes per process per `(slug, auth_base_url)`. Negative
      * results (404) are cached for 60s so a typo doesn't hot-loop the
@@ -1300,6 +1311,20 @@ declare class TopoloClient {
      * has acquired an access token.
      */
     getServiceIdBySlug(slug: string): Promise<string | null>;
+    /**
+     * 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.
+     *
+     * 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.
+     */
+    listServices(): Promise<TopoloServiceCatalogEntry[]>;
+    private generatedCatalogFallback;
     /**
      * Introspect the current credential. Returns the caller's resolved identity,
      * organization, and permission set. Used by CLI `whoami` and by MCP to gate
@@ -1831,4 +1856,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, PLATFORM_SERVICE_IDS, 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 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, 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 };