@topolo/sdk 0.5.0 → 0.7.0

package/README.md

@@ -96,7 +96,7 @@ services and actions become usable without an SDK, CLI, or MCP release.
 
 `APPLICATIONS` describes every Topolo platform application discovered from the
 PlatformApplications metadata, including Worker apps that do not expose a
-callable service. `DEFAULT_SERVICE_URLS` is the bundled callable API service
+callable app API. `DEFAULT_APP_URLS` is the bundled callable API service
 snapshot generated from `topolo.cloudcontrol.json`.
 
 For agent-scale fleets, the bundle is packaging metadata, not an authorization
@@ -104,7 +104,7 @@ 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.
+bundled app 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.
@@ -143,7 +143,7 @@ import { createTopoloWidgetResponse } from '@topolo/sdk';
 
 return Response.json(createTopoloWidgetResponse({
   appId: '<runtime-app-id>',
-  serviceName: 'Example',
+  appName: 'Example',
   widgets: [
     {
       type: 'stats',

package/dist/index.cjs

@@ -24,7 +24,7 @@ __export(index_exports, {
   APPLICATION_REQUIREMENTS: () => APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION: () => APPLICATION_REQUIREMENTS_VERSION,
   CrmModule: () => CrmModule,
-  DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS: () => DEFAULT_APP_URLS,
   IdentityModule: () => IdentityModule,
   P2PModule: () => P2PModule,
   TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
@@ -112,7 +112,7 @@ var TopoloHttpError = class extends TopoloSdkError {
 };
 
 // src/services.generated.ts
-var SERVICES = {
+var APP_API_URLS = {
   agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
@@ -1703,12 +1703,12 @@ var APPLICATION_REQUIREMENTS = [
   {
     id: "shared-auth-boundary",
     title: "Use the shared Topolo auth boundary",
-    summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.",
+    summary: "Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.",
     appliesTo: ["browser", "api", "tooling", "agent_surface"],
     evidence: [
       "@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"
+      "App slug and Auth app registration are documented for protected APIs"
     ],
     implementation: [
       "Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows",
@@ -1741,20 +1741,20 @@ var APPLICATION_REQUIREMENTS = [
     ]
   },
   {
-    id: "service-registration-and-scopes",
-    title: "Register protected APIs as platform services",
-    summary: "Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
+    id: "app-registration-and-scopes",
+    title: "Register protected APIs as platform apps",
+    summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
     appliesTo: ["api"],
     evidence: [
-      "Auth service catalog contains the service ID and slug",
-      "Permissions, role bundles, and API-key scopes exist for the service",
-      "SDK, CLI, and MCP service discovery include the callable production API",
-      "CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false"
+      "Auth app catalog contains the app ID and slug",
+      "Permissions, role bundles, and API-key scopes exist for the app",
+      "SDK, CLI, and MCP app discovery include the callable production API",
+      "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"
     ],
     implementation: [
-      "Add production Worker api_url metadata and sdk_service_id for every agent-callable API target",
+      "Add production Worker api_url metadata and sdk_app_id for every agent-callable API target",
       "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false",
-      "Expose stable service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery",
+      "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery",
       "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"
     ]
   },
@@ -1960,7 +1960,7 @@ function evaluateRequirement(application, requirement) {
         "Catalog metadata cannot verify shared shell, launcher, and account menu adoption.",
         evidence
       );
-    case "service-registration-and-scopes": {
+    case "app-registration-and-scopes": {
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(",")}`);
         return finding(
@@ -1970,7 +1970,7 @@ function evaluateRequirement(application, requirement) {
           evidence
         );
       }
-      return finding(requirement, "missing", "No SDK service ID is registered for this callable API surface.", evidence);
+      return finding(requirement, "missing", "No SDK app API id is registered for this callable API surface.", evidence);
     }
     case "organization-scoped-data":
       return finding(
@@ -2057,7 +2057,7 @@ function statusRank(status) {
 }
 
 // src/services.ts
-var DEFAULT_SERVICE_URLS = SERVICES;
+var DEFAULT_APP_URLS = APP_API_URLS;
 function resolveCatalogServiceUrl(entry, options = {}) {
   const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
   const override = resolveServiceUrlOverride(keys, options.overrides);
@@ -2069,7 +2069,7 @@ function resolveCatalogServiceUrl(entry, options = {}) {
 function resolveServiceUrl(service, overrides) {
   const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  return DEFAULT_SERVICE_URLS[service];
+  return DEFAULT_APP_URLS[service];
 }
 function catalogServiceKeyCandidates(entry, preferred) {
   const values = [preferred, entry.slug, entry.name, entry.appId].filter(
@@ -2100,7 +2100,7 @@ function resolveServiceUrlOverride(keys, overrides) {
     if (envStyle) return envStyle;
   }
   for (const key of keys) {
-    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, "_").toUpperCase()}`;
     const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
     if (envValue) return envValue;
   }
@@ -2287,7 +2287,7 @@ var TopoloClient = class _TopoloClient {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl("auth", this.serviceUrls));
         if (derived) return { serviceKey, baseUrl: derived };
       }
-      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS[serviceKey] };
+      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey] };
     }
     const live = await this.resolveLiveCallableService(serviceKey);
     if (live) {
@@ -2296,7 +2296,7 @@ var TopoloClient = class _TopoloClient {
     }
     throw new TopoloSdkError(
       "unknown_service",
-      `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
+      `Unknown Topolo app API "${service}". Run app discovery first and pass a callable app id or slug.`
     );
   }
   async resolveLiveCallableService(serviceKey) {
@@ -2469,7 +2469,7 @@ var TopoloClient = class _TopoloClient {
   async callAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
     const mapped = mapActionInput(entry, input);
-    const service = entry.serviceSlug || entry.appId;
+    const service = entry.appSlug || entry.appId;
     return this.request({
       service,
       method: entry.method,
@@ -2657,8 +2657,8 @@ function normalizeActionCatalogEntry(item) {
     title: pickActionString(a.title) ?? name,
     description: pickActionString(a.description) ?? "",
     appId,
-    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
-    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    appSlug: pickActionString(a.app_slug) ?? pickActionString(a.appSlug) ?? null,
+    appName: pickActionString(a.app_name) ?? pickActionString(a.appName) ?? null,
     method,
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
@@ -2775,6 +2775,7 @@ var CrmModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   async listContacts(options = {}) {
     const res = await this.client.request({
       service: "crm",
@@ -2822,6 +2823,7 @@ var IdentityModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   /** Returns the resolved user, organization, and permission set for the
    *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
    *  on this module for symmetry with the other domain modules. */
@@ -2835,6 +2837,7 @@ var P2PModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   // Directory ----------------------------------------------------------------
   async listDirectory(options = {}) {
     const res = await this.client.request({
@@ -3296,7 +3299,7 @@ function createTopolo(options) {
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
   CrmModule,
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   IdentityModule,
   P2PModule,
   TOPOLO_WIDGET_ENDPOINT,

package/dist/index.d.cts

@@ -134,8 +134,8 @@ interface TopoloActionCatalogEntry {
     title: string;
     description: string;
     appId: string;
-    serviceSlug: string | null;
-    serviceName: string | null;
+    appSlug: string | null;
+    appName: string | null;
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     path: string;
     permissionName: string;
@@ -252,7 +252,7 @@ interface CredentialIntrospection {
     } | null;
 }
 
-declare const SERVICES: {
+declare const APP_API_URLS: {
     readonly agent: "https://agent.topolo.app";
     readonly auth: "https://auth.topolo.app";
     readonly backup: "https://backup.topolo.app";
@@ -301,7 +301,7 @@ declare const SERVICES: {
     readonly voice: "https://voice.topolo.app";
     readonly web: "https://web.topolo.app";
 };
-type ServiceId = keyof typeof SERVICES;
+type AppApiId = keyof typeof APP_API_URLS;
 
 declare const APPLICATIONS: {
     readonly admin: {
@@ -1492,9 +1492,9 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
 }, {
     readonly id: "shared-auth-boundary";
     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 summary: "Applications must derive identity, organization, scopes, and app 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-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 evidence: readonly ["@topolo/auth-client or @topolo-io/worker-runtime is used where applicable", "No public command, tool, or SDK method accepts orgId", "App slug and Auth app registration are documented for protected APIs"];
     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";
@@ -1504,12 +1504,12 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly evidence: readonly ["@topolo-io/app-shell is used for the platform shell where the app has authenticated UI", "@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome", "Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive", "Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges", "Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states", "Authenticated app body content stays inside the viewport on mobile and desktop widths"];
     readonly implementation: readonly ["Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts", "Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome", "Pass app-specific account actions as additive menu items instead of forking dropdowns", "Use shared design tokens and platform UI primitives before creating local equivalents", "Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns", "Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state", "Keep mobile and desktop shell behavior aligned with the platform UI kit", "Constrain app-owned workspace wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow"];
 }, {
-    readonly id: "service-registration-and-scopes";
-    readonly title: "Register protected APIs as platform services";
-    readonly summary: "Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
+    readonly id: "app-registration-and-scopes";
+    readonly title: "Register protected APIs as platform apps";
+    readonly summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
     readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["Auth service catalog contains the service ID and slug", "Permissions, role bundles, and API-key scopes exist for the service", "SDK, CLI, and MCP service discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false"];
-    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_service_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
+    readonly evidence: readonly ["Auth app catalog contains the app ID and slug", "Permissions, role bundles, and API-key scopes exist for the app", "SDK, CLI, and MCP app discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"];
+    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_app_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
 }, {
     readonly id: "organization-scoped-data";
     readonly title: "Keep application data organization-scoped";
@@ -1559,22 +1559,22 @@ declare function auditApplicationRequirements(applicationOrId: ApplicationCatalo
 declare function auditAllApplicationRequirements(applicationIds?: readonly ApplicationId[]): ApplicationRequirementsAuditReport;
 
 /**
- * Service registry — base URLs for every Topolo platform service.
+ * App API registry — base URLs for callable Topolo platform APIs.
  *
  * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
- * `SERVICES` map is regenerated from those files via
+ * `APP_API_URLS` map is regenerated from those files via
  * `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_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
- * (dots in service IDs become underscores in env vars).
+ * via env vars like `TOPOLO_APP_URL_MAIL` or `TOPOLO_APP_URL_WEB_API`
+ * (dots in app API keys become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
 
-declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+declare const DEFAULT_APP_URLS: Record<AppApiId, string>;
 interface ServiceCatalogUrlEntry {
     appId?: string | null;
     slug?: string | null;
@@ -1586,9 +1586,9 @@ interface ServiceCatalogUrlEntry {
 }
 declare function resolveCatalogServiceUrl(entry: ServiceCatalogUrlEntry, options?: {
     serviceKey?: string;
-    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+    overrides?: Record<string, string> | Partial<Record<AppApiId, string>>;
 }): string | null;
-declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
+declare function resolveServiceUrl(service: AppApiId, overrides?: Partial<Record<AppApiId, string>>): string;
 
 declare class TopoloSdkError extends Error {
     readonly code: string;
@@ -1904,7 +1904,7 @@ interface TokenResponse {
 }
 interface OAuthHelperOptions {
     /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
-    serviceUrls?: Partial<Record<ServiceId, string>>;
+    serviceUrls?: Partial<Record<AppApiId, string>>;
     /** Injected fetch. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -2092,4 +2092,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 ServiceCatalogUrlEntry, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloApiKeyResourceMetadata, 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, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };
+export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, 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_APP_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 ServiceCatalogUrlEntry, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloApiKeyResourceMetadata, 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, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -134,8 +134,8 @@ interface TopoloActionCatalogEntry {
     title: string;
     description: string;
     appId: string;
-    serviceSlug: string | null;
-    serviceName: string | null;
+    appSlug: string | null;
+    appName: string | null;
     method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
     path: string;
     permissionName: string;
@@ -252,7 +252,7 @@ interface CredentialIntrospection {
     } | null;
 }
 
-declare const SERVICES: {
+declare const APP_API_URLS: {
     readonly agent: "https://agent.topolo.app";
     readonly auth: "https://auth.topolo.app";
     readonly backup: "https://backup.topolo.app";
@@ -301,7 +301,7 @@ declare const SERVICES: {
     readonly voice: "https://voice.topolo.app";
     readonly web: "https://web.topolo.app";
 };
-type ServiceId = keyof typeof SERVICES;
+type AppApiId = keyof typeof APP_API_URLS;
 
 declare const APPLICATIONS: {
     readonly admin: {
@@ -1492,9 +1492,9 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
 }, {
     readonly id: "shared-auth-boundary";
     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 summary: "Applications must derive identity, organization, scopes, and app 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-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 evidence: readonly ["@topolo/auth-client or @topolo-io/worker-runtime is used where applicable", "No public command, tool, or SDK method accepts orgId", "App slug and Auth app registration are documented for protected APIs"];
     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";
@@ -1504,12 +1504,12 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly evidence: readonly ["@topolo-io/app-shell is used for the platform shell where the app has authenticated UI", "@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome", "Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive", "Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges", "Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states", "Authenticated app body content stays inside the viewport on mobile and desktop widths"];
     readonly implementation: readonly ["Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts", "Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome", "Pass app-specific account actions as additive menu items instead of forking dropdowns", "Use shared design tokens and platform UI primitives before creating local equivalents", "Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns", "Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state", "Keep mobile and desktop shell behavior aligned with the platform UI kit", "Constrain app-owned workspace wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow"];
 }, {
-    readonly id: "service-registration-and-scopes";
-    readonly title: "Register protected APIs as platform services";
-    readonly summary: "Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
+    readonly id: "app-registration-and-scopes";
+    readonly title: "Register protected APIs as platform apps";
+    readonly summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.";
     readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["Auth service catalog contains the service ID and slug", "Permissions, role bundles, and API-key scopes exist for the service", "SDK, CLI, and MCP service discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false"];
-    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_service_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
+    readonly evidence: readonly ["Auth app catalog contains the app ID and slug", "Permissions, role bundles, and API-key scopes exist for the app", "SDK, CLI, and MCP app discovery include the callable production API", "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"];
+    readonly implementation: readonly ["Add production Worker api_url metadata and sdk_app_id for every agent-callable API target", "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false", "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery", "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"];
 }, {
     readonly id: "organization-scoped-data";
     readonly title: "Keep application data organization-scoped";
@@ -1559,22 +1559,22 @@ declare function auditApplicationRequirements(applicationOrId: ApplicationCatalo
 declare function auditAllApplicationRequirements(applicationIds?: readonly ApplicationId[]): ApplicationRequirementsAuditReport;
 
 /**
- * Service registry — base URLs for every Topolo platform service.
+ * App API registry — base URLs for callable Topolo platform APIs.
  *
  * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
- * `SERVICES` map is regenerated from those files via
+ * `APP_API_URLS` map is regenerated from those files via
  * `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_MAIL` or `TOPOLO_SERVICE_URL_WEB_API`
- * (dots in service IDs become underscores in env vars).
+ * via env vars like `TOPOLO_APP_URL_MAIL` or `TOPOLO_APP_URL_WEB_API`
+ * (dots in app API keys become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
 
-declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+declare const DEFAULT_APP_URLS: Record<AppApiId, string>;
 interface ServiceCatalogUrlEntry {
     appId?: string | null;
     slug?: string | null;
@@ -1586,9 +1586,9 @@ interface ServiceCatalogUrlEntry {
 }
 declare function resolveCatalogServiceUrl(entry: ServiceCatalogUrlEntry, options?: {
     serviceKey?: string;
-    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+    overrides?: Record<string, string> | Partial<Record<AppApiId, string>>;
 }): string | null;
-declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
+declare function resolveServiceUrl(service: AppApiId, overrides?: Partial<Record<AppApiId, string>>): string;
 
 declare class TopoloSdkError extends Error {
     readonly code: string;
@@ -1904,7 +1904,7 @@ interface TokenResponse {
 }
 interface OAuthHelperOptions {
     /** Overrides for TopoloAuth URL. Staging/dev should pass a mapping. */
-    serviceUrls?: Partial<Record<ServiceId, string>>;
+    serviceUrls?: Partial<Record<AppApiId, string>>;
     /** Injected fetch. Defaults to global fetch. */
     fetch?: typeof fetch;
 }
@@ -2092,4 +2092,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 ServiceCatalogUrlEntry, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloApiKeyResourceMetadata, 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, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };
+export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type AppApiId, 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_APP_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 ServiceCatalogUrlEntry, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, type TopoloApiKeyResourceMetadata, 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, resolveCatalogServiceUrl, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.js

@@ -57,7 +57,7 @@ var TopoloHttpError = class extends TopoloSdkError {
 };
 
 // src/services.generated.ts
-var SERVICES = {
+var APP_API_URLS = {
   agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
@@ -1648,12 +1648,12 @@ var APPLICATION_REQUIREMENTS = [
   {
     id: "shared-auth-boundary",
     title: "Use the shared Topolo auth boundary",
-    summary: "Applications must derive identity, organization, scopes, and service entitlement from TopoloAuth rather than inventing parallel auth state.",
+    summary: "Applications must derive identity, organization, scopes, and app entitlement from TopoloAuth rather than inventing parallel auth state.",
     appliesTo: ["browser", "api", "tooling", "agent_surface"],
     evidence: [
       "@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"
+      "App slug and Auth app registration are documented for protected APIs"
     ],
     implementation: [
       "Use shared auth/runtime packages instead of copying token parsing, gateway, or browser storage flows",
@@ -1686,20 +1686,20 @@ var APPLICATION_REQUIREMENTS = [
     ]
   },
   {
-    id: "service-registration-and-scopes",
-    title: "Register protected APIs as platform services",
-    summary: "Callable app APIs need a stable service ID, service slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
+    id: "app-registration-and-scopes",
+    title: "Register protected APIs as platform apps",
+    summary: "Callable app APIs need a stable app ID, app slug, permissions, role bundles, and API-key scopes before agents or users rely on them.",
     appliesTo: ["api"],
     evidence: [
-      "Auth service catalog contains the service ID and slug",
-      "Permissions, role bundles, and API-key scopes exist for the service",
-      "SDK, CLI, and MCP service discovery include the callable production API",
-      "CloudControl production HTTP targets classify agent reachability with sdk_service_id or agent_callable:false"
+      "Auth app catalog contains the app ID and slug",
+      "Permissions, role bundles, and API-key scopes exist for the app",
+      "SDK, CLI, and MCP app discovery include the callable production API",
+      "CloudControl production HTTP targets classify agent reachability with sdk_app_id or agent_callable:false"
     ],
     implementation: [
-      "Add production Worker api_url metadata and sdk_service_id for every agent-callable API target",
+      "Add production Worker api_url metadata and sdk_app_id for every agent-callable API target",
       "Mark browser, documentation, and runtime-only Worker targets with agent_callable:false",
-      "Expose stable service IDs through generated DEFAULT_SERVICE_URLS and live catalog discovery",
+      "Expose stable app IDs through generated DEFAULT_APP_URLS and live catalog discovery",
       "Keep typed SDK/CLI/MCP surfaces in sync when an API contract stabilizes"
     ]
   },
@@ -1905,7 +1905,7 @@ function evaluateRequirement(application, requirement) {
         "Catalog metadata cannot verify shared shell, launcher, and account menu adoption.",
         evidence
       );
-    case "service-registration-and-scopes": {
+    case "app-registration-and-scopes": {
       if (application.services.length > 0) {
         evidence.push(`services=${application.services.join(",")}`);
         return finding(
@@ -1915,7 +1915,7 @@ function evaluateRequirement(application, requirement) {
           evidence
         );
       }
-      return finding(requirement, "missing", "No SDK service ID is registered for this callable API surface.", evidence);
+      return finding(requirement, "missing", "No SDK app API id is registered for this callable API surface.", evidence);
     }
     case "organization-scoped-data":
       return finding(
@@ -2002,7 +2002,7 @@ function statusRank(status) {
 }
 
 // src/services.ts
-var DEFAULT_SERVICE_URLS = SERVICES;
+var DEFAULT_APP_URLS = APP_API_URLS;
 function resolveCatalogServiceUrl(entry, options = {}) {
   const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
   const override = resolveServiceUrlOverride(keys, options.overrides);
@@ -2014,7 +2014,7 @@ function resolveCatalogServiceUrl(entry, options = {}) {
 function resolveServiceUrl(service, overrides) {
   const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  return DEFAULT_SERVICE_URLS[service];
+  return DEFAULT_APP_URLS[service];
 }
 function catalogServiceKeyCandidates(entry, preferred) {
   const values = [preferred, entry.slug, entry.name, entry.appId].filter(
@@ -2045,7 +2045,7 @@ function resolveServiceUrlOverride(keys, overrides) {
     if (envStyle) return envStyle;
   }
   for (const key of keys) {
-    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envKey = `TOPOLO_APP_URL_${key.replace(/\./g, "_").toUpperCase()}`;
     const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
     if (envValue) return envValue;
   }
@@ -2232,7 +2232,7 @@ var TopoloClient = class _TopoloClient {
         const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl("auth", this.serviceUrls));
         if (derived) return { serviceKey, baseUrl: derived };
       }
-      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS[serviceKey] };
+      return { serviceKey, baseUrl: DEFAULT_APP_URLS[serviceKey] };
     }
     const live = await this.resolveLiveCallableService(serviceKey);
     if (live) {
@@ -2241,7 +2241,7 @@ var TopoloClient = class _TopoloClient {
     }
     throw new TopoloSdkError(
       "unknown_service",
-      `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`
+      `Unknown Topolo app API "${service}". Run app discovery first and pass a callable app id or slug.`
     );
   }
   async resolveLiveCallableService(serviceKey) {
@@ -2414,7 +2414,7 @@ var TopoloClient = class _TopoloClient {
   async callAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
     const mapped = mapActionInput(entry, input);
-    const service = entry.serviceSlug || entry.appId;
+    const service = entry.appSlug || entry.appId;
     return this.request({
       service,
       method: entry.method,
@@ -2602,8 +2602,8 @@ function normalizeActionCatalogEntry(item) {
     title: pickActionString(a.title) ?? name,
     description: pickActionString(a.description) ?? "",
     appId,
-    serviceSlug: pickActionString(a.service_slug) ?? pickActionString(a.serviceSlug) ?? null,
-    serviceName: pickActionString(a.service_name) ?? pickActionString(a.serviceName) ?? null,
+    appSlug: pickActionString(a.app_slug) ?? pickActionString(a.appSlug) ?? null,
+    appName: pickActionString(a.app_name) ?? pickActionString(a.appName) ?? null,
     method,
     path,
     permissionName: pickActionString(a.permission_name) ?? pickActionString(a.permissionName) ?? "",
@@ -2720,6 +2720,7 @@ var CrmModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   async listContacts(options = {}) {
     const res = await this.client.request({
       service: "crm",
@@ -2767,6 +2768,7 @@ var IdentityModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   /** Returns the resolved user, organization, and permission set for the
    *  current credential. Equivalent to `TopoloClient.introspect()` — exposed
    *  on this module for symmetry with the other domain modules. */
@@ -2780,6 +2782,7 @@ var P2PModule = class {
   constructor(client) {
     this.client = client;
   }
+  client;
   // Directory ----------------------------------------------------------------
   async listDirectory(options = {}) {
     const res = await this.client.request({
@@ -3240,7 +3243,7 @@ export {
   APPLICATION_REQUIREMENTS,
   APPLICATION_REQUIREMENTS_VERSION,
   CrmModule,
-  DEFAULT_SERVICE_URLS,
+  DEFAULT_APP_URLS,
   IdentityModule,
   P2PModule,
   TOPOLO_WIDGET_ENDPOINT,