@topolo/sdk 0.2.12 → 0.4.0

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,7 +80,6 @@ declare const SERVICES: {
     readonly web: "https://web-api.topolo.app";
 };
 type ServiceId = keyof typeof SERVICES;
-declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 
 declare const APPLICATIONS: {
     readonly admin: {
@@ -136,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";
@@ -239,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";
@@ -365,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";
@@ -617,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";
@@ -723,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"];
@@ -803,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";
@@ -936,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";
@@ -1102,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";
@@ -1190,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.
@@ -1246,14 +1254,42 @@ 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;
     private readonly debug?;
+    /**
+     * Process-wide cache for slug → service-id lookups. Keyed by
+     * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+     * the same Auth share, but staging vs prod don't poison each other.
+     * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+     */
+    private static readonly serviceIdCache;
+    /**
+     * Drop the slug→service-id cache. Test-only — production callers should
+     * let the 5-minute TTL expire naturally.
+     */
+    static clearServiceIdCache(): void;
     constructor(options: TopoloClientOptions);
     private emit;
     /**
@@ -1262,6 +1298,33 @@ declare class TopoloClient {
      * use and for the generic `topolo api` / MCP passthrough tool.
      */
     request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * 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
+     * resolver. Returns null when the slug isn't registered — callers decide
+     * whether to throw.
+     *
+     * No credential is sent: the endpoint is public (slugs aren't secret).
+     * This keeps the resolver usable during early bootstrap before a caller
+     * 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
@@ -1793,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 };

package/dist/index.d.ts

@@ -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,7 +80,6 @@ declare const SERVICES: {
     readonly web: "https://web-api.topolo.app";
 };
 type ServiceId = keyof typeof SERVICES;
-declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 
 declare const APPLICATIONS: {
     readonly admin: {
@@ -136,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";
@@ -239,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";
@@ -365,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";
@@ -617,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";
@@ -723,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"];
@@ -803,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";
@@ -936,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";
@@ -1102,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";
@@ -1190,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.
@@ -1246,14 +1254,42 @@ 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;
     private readonly debug?;
+    /**
+     * Process-wide cache for slug → service-id lookups. Keyed by
+     * `${authBaseUrl}|${slug}` so multiple `TopoloClient` instances pointing at
+     * the same Auth share, but staging vs prod don't poison each other.
+     * Cleared via `TopoloClient.clearServiceIdCache()` if a test needs it.
+     */
+    private static readonly serviceIdCache;
+    /**
+     * Drop the slug→service-id cache. Test-only — production callers should
+     * let the 5-minute TTL expire naturally.
+     */
+    static clearServiceIdCache(): void;
     constructor(options: TopoloClientOptions);
     private emit;
     /**
@@ -1262,6 +1298,33 @@ declare class TopoloClient {
      * use and for the generic `topolo api` / MCP passthrough tool.
      */
     request<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * 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
+     * resolver. Returns null when the slug isn't registered — callers decide
+     * whether to throw.
+     *
+     * No credential is sent: the endpoint is public (slugs aren't secret).
+     * This keeps the resolver usable during early bootstrap before a caller
+     * 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
@@ -1793,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 };