@topolo/sdk 0.4.4 → 0.4.6

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(index_exports, {
   defineTopoloRecentActivityWidget: () => defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   requirementsForApplication: () => requirementsForApplication,
+  resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
   validateTopoloWidgetResponse: () => validateTopoloWidgetResponse
 });
@@ -136,7 +137,7 @@ var SERVICES = {
   inventory: "https://inventory.topolo.app",
   learn: "https://learn-api.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail.topolo.app",
+  mail: "https://mail-api.topolo.app",
   mdm: "https://mdm-api.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
@@ -974,15 +975,17 @@ var APPLICATIONS = {
           "mail.topolo.app"
         ],
         "routes": [],
-        "serviceId": "mail"
+        "serviceId": null
       },
       {
         "name": "topolo-mail-api",
         "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
+        "apiUrl": "https://mail-api.topolo.app",
+        "domains": [
+          "mail-api.topolo.app"
+        ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mail"
       }
     ]
   },
@@ -2099,14 +2102,60 @@ function statusRank(status) {
 
 // src/services.ts
 var DEFAULT_SERVICE_URLS = SERVICES;
+function resolveCatalogServiceUrl(entry, options = {}) {
+  const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
+  const override = resolveServiceUrlOverride(keys, options.overrides);
+  if (override) return override;
+  const apiBaseUrl = firstString(entry.apiBaseUrl, entry.api_base_url);
+  if (apiBaseUrl) return apiBaseUrl;
+  return null;
+}
 function resolveServiceUrl(service, overrides) {
-  const override = overrides?.[service];
+  const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
-  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
-  if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
 }
+function catalogServiceKeyCandidates(entry, preferred) {
+  const values = [preferred, entry.slug, entry.name, entry.serviceId].filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+  const keys = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    for (const candidate of serviceKeyCandidates(value)) keys.add(candidate);
+  }
+  return [...keys];
+}
+function serviceKeyCandidates(value) {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+  const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, "_")
+  ])].filter(Boolean);
+}
+function resolveServiceUrlOverride(keys, overrides) {
+  for (const key of keys) {
+    const direct = overrides?.[key];
+    if (direct) return direct;
+    const envStyleKey = key.replace(/\./g, "_");
+    const envStyle = overrides?.[envStyleKey];
+    if (envStyle) return envStyle;
+  }
+  for (const key of keys) {
+    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (envValue) return envValue;
+  }
+  return null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
@@ -2279,8 +2328,12 @@ var TopoloClient = class _TopoloClient {
   async resolveLiveCallableService(serviceKey) {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return { serviceKey, baseUrl: match.baseUrl };
+    if (!match) return null;
+    const baseUrl = resolveCatalogServiceUrl(match, {
+      serviceKey,
+      overrides: this.serviceUrls
+    });
+    return baseUrl ? { serviceKey, baseUrl } : null;
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2373,7 +2426,8 @@ var TopoloClient = class _TopoloClient {
         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,
+        apiBaseUrl: typeof s.api_base_url === "string" ? s.api_base_url : typeof s.apiBaseUrl === "string" ? s.apiBaseUrl : null,
+        launchUrl: typeof s.launch_url === "string" ? s.launch_url : typeof s.launchUrl === "string" ? s.launchUrl : null,
         status: typeof s.status === "string" ? s.status : null,
         surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
         launchable: s.launchable === true,
@@ -2458,7 +2512,8 @@ var TopoloClient = class _TopoloClient {
       slug: app.id,
       name: app.name ?? app.id,
       description: null,
-      baseUrl: app.productionUrl ?? null,
+      apiBaseUrl: null,
+      launchUrl: app.productionUrl ?? null,
       status: "bundled",
       surfaceKind: "application",
       launchable: Boolean(app.productionUrl),
@@ -2502,7 +2557,7 @@ var TopoloClient = class _TopoloClient {
   }
 };
 function resolveConfiguredServiceId(slug, serviceIds) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceIds?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2512,7 +2567,7 @@ function resolveConfiguredServiceId(slug, serviceIds) {
   return null;
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_URL_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2521,7 +2576,7 @@ function resolveConfiguredServiceUrl(slug, serviceUrls) {
   }
   return null;
 }
-function serviceKeyCandidates(slug) {
+function serviceKeyCandidates2(slug) {
   const normalized = normalizeLookupKey(slug);
   const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
   return [.../* @__PURE__ */ new Set([
@@ -2543,19 +2598,12 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    for (const candidate of serviceKeyCandidates(normalized)) {
+    for (const candidate of serviceKeyCandidates2(normalized)) {
       keys.add(candidate);
     }
   }
   return [...keys];
 }
-function isCallableCatalogEntry(entry) {
-  const kind = normalizeLookupKey(entry.surfaceKind || "");
-  if (kind === "api" || kind === "technical_service" || kind === "service") return true;
-  return Boolean(
-    entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
-  );
-}
 function normalizeActionCatalogEntry(item) {
   if (!item || typeof item !== "object" || Array.isArray(item)) return null;
   const a = item;
@@ -3234,6 +3282,7 @@ function createTopolo(options) {
   defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   validateTopoloWidgetResponse
 });

package/dist/index.d.cts

@@ -104,7 +104,8 @@ interface TopoloServiceCatalogEntry {
     slug: string | null;
     name: string | null;
     description: string | null;
-    baseUrl: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
@@ -257,7 +258,7 @@ declare const SERVICES: {
     readonly inventory: "https://inventory.topolo.app";
     readonly learn: "https://learn-api.topolo.app";
     readonly localize: "https://localize.topolo.app";
-    readonly mail: "https://mail.topolo.app";
+    readonly mail: "https://mail-api.topolo.app";
     readonly mdm: "https://mdm-api.topolo.app";
     readonly messages: "https://messages.topolo.app";
     readonly nexus: "https://nexus-api.topolo.app";
@@ -889,14 +890,14 @@ declare const APPLICATIONS: {
             readonly apiUrl: "https://mail.topolo.app";
             readonly domains: readonly ["mail.topolo.app"];
             readonly routes: readonly [];
-            readonly serviceId: "mail";
+            readonly serviceId: null;
         }, {
             readonly name: "topolo-mail-api";
             readonly kind: "worker";
-            readonly apiUrl: null;
-            readonly domains: readonly [];
+            readonly apiUrl: "https://mail-api.topolo.app";
+            readonly domains: readonly ["mail-api.topolo.app"];
             readonly routes: readonly [];
-            readonly serviceId: null;
+            readonly serviceId: "mail";
         }];
     };
     readonly mdm: {
@@ -1579,6 +1580,19 @@ declare function auditAllApplicationRequirements(applicationIds?: readonly Appli
  */
 
 declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+interface ServiceCatalogUrlEntry {
+    serviceId?: string | null;
+    slug?: string | null;
+    name?: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
+    api_base_url?: string | null;
+    launch_url?: string | null;
+}
+declare function resolveCatalogServiceUrl(entry: ServiceCatalogUrlEntry, options?: {
+    serviceKey?: string;
+    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+}): string | null;
 declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
 
 declare class TopoloSdkError extends Error {
@@ -2085,4 +2099,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };
+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, 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

@@ -104,7 +104,8 @@ interface TopoloServiceCatalogEntry {
     slug: string | null;
     name: string | null;
     description: string | null;
-    baseUrl: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
@@ -257,7 +258,7 @@ declare const SERVICES: {
     readonly inventory: "https://inventory.topolo.app";
     readonly learn: "https://learn-api.topolo.app";
     readonly localize: "https://localize.topolo.app";
-    readonly mail: "https://mail.topolo.app";
+    readonly mail: "https://mail-api.topolo.app";
     readonly mdm: "https://mdm-api.topolo.app";
     readonly messages: "https://messages.topolo.app";
     readonly nexus: "https://nexus-api.topolo.app";
@@ -889,14 +890,14 @@ declare const APPLICATIONS: {
             readonly apiUrl: "https://mail.topolo.app";
             readonly domains: readonly ["mail.topolo.app"];
             readonly routes: readonly [];
-            readonly serviceId: "mail";
+            readonly serviceId: null;
         }, {
             readonly name: "topolo-mail-api";
             readonly kind: "worker";
-            readonly apiUrl: null;
-            readonly domains: readonly [];
+            readonly apiUrl: "https://mail-api.topolo.app";
+            readonly domains: readonly ["mail-api.topolo.app"];
             readonly routes: readonly [];
-            readonly serviceId: null;
+            readonly serviceId: "mail";
         }];
     };
     readonly mdm: {
@@ -1579,6 +1580,19 @@ declare function auditAllApplicationRequirements(applicationIds?: readonly Appli
  */
 
 declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
+interface ServiceCatalogUrlEntry {
+    serviceId?: string | null;
+    slug?: string | null;
+    name?: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
+    api_base_url?: string | null;
+    launch_url?: string | null;
+}
+declare function resolveCatalogServiceUrl(entry: ServiceCatalogUrlEntry, options?: {
+    serviceKey?: string;
+    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+}): string | null;
 declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
 
 declare class TopoloSdkError extends Error {
@@ -2085,4 +2099,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionCatalogEntry, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };
+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, 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

@@ -82,7 +82,7 @@ var SERVICES = {
   inventory: "https://inventory.topolo.app",
   learn: "https://learn-api.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail.topolo.app",
+  mail: "https://mail-api.topolo.app",
   mdm: "https://mdm-api.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
@@ -920,15 +920,17 @@ var APPLICATIONS = {
           "mail.topolo.app"
         ],
         "routes": [],
-        "serviceId": "mail"
+        "serviceId": null
       },
       {
         "name": "topolo-mail-api",
         "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
+        "apiUrl": "https://mail-api.topolo.app",
+        "domains": [
+          "mail-api.topolo.app"
+        ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mail"
       }
     ]
   },
@@ -2045,14 +2047,60 @@ function statusRank(status) {
 
 // src/services.ts
 var DEFAULT_SERVICE_URLS = SERVICES;
+function resolveCatalogServiceUrl(entry, options = {}) {
+  const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
+  const override = resolveServiceUrlOverride(keys, options.overrides);
+  if (override) return override;
+  const apiBaseUrl = firstString(entry.apiBaseUrl, entry.api_base_url);
+  if (apiBaseUrl) return apiBaseUrl;
+  return null;
+}
 function resolveServiceUrl(service, overrides) {
-  const override = overrides?.[service];
+  const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, "_").toUpperCase()}`;
-  const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
-  if (envValue) return envValue;
   return DEFAULT_SERVICE_URLS[service];
 }
+function catalogServiceKeyCandidates(entry, preferred) {
+  const values = [preferred, entry.slug, entry.name, entry.serviceId].filter(
+    (value) => typeof value === "string" && value.trim().length > 0
+  );
+  const keys = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    for (const candidate of serviceKeyCandidates(value)) keys.add(candidate);
+  }
+  return [...keys];
+}
+function serviceKeyCandidates(value) {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, "-");
+  const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
+  return [.../* @__PURE__ */ new Set([
+    normalized,
+    normalized.replace(/-/g, "_"),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, "_")
+  ])].filter(Boolean);
+}
+function resolveServiceUrlOverride(keys, overrides) {
+  for (const key of keys) {
+    const direct = overrides?.[key];
+    if (direct) return direct;
+    const envStyleKey = key.replace(/\./g, "_");
+    const envStyle = overrides?.[envStyleKey];
+    if (envStyle) return envStyle;
+  }
+  for (const key of keys) {
+    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, "_").toUpperCase()}`;
+    const envValue = typeof process !== "undefined" ? process.env?.[envKey] : void 0;
+    if (envValue) return envValue;
+  }
+  return null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
@@ -2225,8 +2273,12 @@ var TopoloClient = class _TopoloClient {
   async resolveLiveCallableService(serviceKey) {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return { serviceKey, baseUrl: match.baseUrl };
+    if (!match) return null;
+    const baseUrl = resolveCatalogServiceUrl(match, {
+      serviceKey,
+      overrides: this.serviceUrls
+    });
+    return baseUrl ? { serviceKey, baseUrl } : null;
   }
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
@@ -2319,7 +2371,8 @@ var TopoloClient = class _TopoloClient {
         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,
+        apiBaseUrl: typeof s.api_base_url === "string" ? s.api_base_url : typeof s.apiBaseUrl === "string" ? s.apiBaseUrl : null,
+        launchUrl: typeof s.launch_url === "string" ? s.launch_url : typeof s.launchUrl === "string" ? s.launchUrl : null,
         status: typeof s.status === "string" ? s.status : null,
         surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
         launchable: s.launchable === true,
@@ -2404,7 +2457,8 @@ var TopoloClient = class _TopoloClient {
       slug: app.id,
       name: app.name ?? app.id,
       description: null,
-      baseUrl: app.productionUrl ?? null,
+      apiBaseUrl: null,
+      launchUrl: app.productionUrl ?? null,
       status: "bundled",
       surfaceKind: "application",
       launchable: Boolean(app.productionUrl),
@@ -2448,7 +2502,7 @@ var TopoloClient = class _TopoloClient {
   }
 };
 function resolveConfiguredServiceId(slug, serviceIds) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceIds?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_ID_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2458,7 +2512,7 @@ function resolveConfiguredServiceId(slug, serviceIds) {
   return null;
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
-  for (const serviceKey of serviceKeyCandidates(slug)) {
+  for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
     if (typeof configured === "string" && configured.trim()) return configured.trim();
     const envKey = `TOPOLO_SERVICE_URL_${serviceKey.replace(/\./g, "_").toUpperCase()}`;
@@ -2467,7 +2521,7 @@ function resolveConfiguredServiceUrl(slug, serviceUrls) {
   }
   return null;
 }
-function serviceKeyCandidates(slug) {
+function serviceKeyCandidates2(slug) {
   const normalized = normalizeLookupKey(slug);
   const withoutTopolo = normalized.startsWith("topolo-") ? normalized.slice("topolo-".length) : normalized;
   return [.../* @__PURE__ */ new Set([
@@ -2489,19 +2543,12 @@ function catalogEntryLookupKeys(entry) {
   for (const value of values) {
     const normalized = normalizeLookupKey(value);
     if (!normalized) continue;
-    for (const candidate of serviceKeyCandidates(normalized)) {
+    for (const candidate of serviceKeyCandidates2(normalized)) {
       keys.add(candidate);
     }
   }
   return [...keys];
 }
-function isCallableCatalogEntry(entry) {
-  const kind = normalizeLookupKey(entry.surfaceKind || "");
-  if (kind === "api" || kind === "technical_service" || kind === "service") return true;
-  return Boolean(
-    entry.baseUrl && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
-  );
-}
 function normalizeActionCatalogEntry(item) {
   if (!item || typeof item !== "object" || Array.isArray(item)) return null;
   const a = item;
@@ -3179,6 +3226,7 @@ export {
   defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   validateTopoloWidgetResponse
 };

package/package.json

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

package/src/applications.generated.ts

@@ -813,15 +813,17 @@ export const APPLICATIONS = {
           "mail.topolo.app"
         ],
         "routes": [],
-        "serviceId": "mail"
+        "serviceId": null
       },
       {
         "name": "topolo-mail-api",
         "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
+        "apiUrl": "https://mail-api.topolo.app",
+        "domains": [
+          "mail-api.topolo.app"
+        ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mail"
       }
     ]
   },

package/src/client.test.ts

@@ -25,7 +25,8 @@ const MAIL_CATALOG = {
           service_id: 'srv_mail',
           app_slug: 'topolo-mail',
           name: 'Topolo Mail',
-          base_url: 'https://mail-api.topolo.app',
+          api_base_url: 'https://mail-api.topolo.app',
+          launch_url: 'https://mail.topolo.app',
           surface_kind: 'api',
           status: 'active',
           granted_permissions: ['srv_mail.messages:read'],
@@ -376,7 +377,7 @@ describe('TopoloClient.getServiceIdBySlug', () => {
 
   it('falls back to /api/services/by-slug/:slug for unknown slugs', async () => {
     const { impl, calls } = stubFetch([
-      { body: { success: true, data: { service_id: 'service_abc123', base_url: 'https://x' } } },
+      { body: { success: true, data: { service_id: 'service_abc123', api_base_url: 'https://x-api' } } },
     ]);
     const client = freshClient(impl, { auth: 'https://auth.example.com' });
     const id = await client.getServiceIdBySlug('external-service');
@@ -452,7 +453,8 @@ describe('TopoloClient.listServices', () => {
                 app_slug: 'topolo-director',
                 name: 'Topolo Director',
                 description: 'Demo control plane',
-                base_url: 'https://director.topolo.app',
+                api_base_url: 'https://director-api.topolo.app',
+                launch_url: 'https://director.topolo.app',
                 status: 'active',
                 surface_kind: 'application',
                 launchable: true,
@@ -476,7 +478,8 @@ describe('TopoloClient.listServices', () => {
         slug: 'topolo-director',
         name: 'Topolo Director',
         description: 'Demo control plane',
-        baseUrl: 'https://director.topolo.app',
+        apiBaseUrl: 'https://director-api.topolo.app',
+        launchUrl: 'https://director.topolo.app',
         status: 'active',
         surfaceKind: 'application',
         launchable: true,
@@ -512,7 +515,8 @@ describe('TopoloClient.listServices', () => {
                 service_id: 'srv_mail',
                 app_slug: 'topolo-mail',
                 name: 'Topolo Mail',
-                base_url: 'https://mail.topolo.app',
+                api_base_url: 'https://mail-api.topolo.app',
+                launch_url: 'https://mail.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
                 granted_permissions: ['srv_mail.messages:read'],
@@ -533,7 +537,76 @@ describe('TopoloClient.listServices', () => {
     await client.request({ service: 'mail', path: '/api/health' });
 
     expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
-    expect(calls[1]!.url).toBe('https://mail.topolo.app/api/health');
+    expect(calls[1]!.url).toBe('https://mail-api.topolo.app/api/health');
+  });
+
+  it('routes known split-surface services to the callable API URL', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_crm',
+                app_slug: 'topolo-crm',
+                name: 'Topolo CRM',
+                api_base_url: 'https://crm-api.topolo.app',
+                launch_url: 'https://crm.topolo.app',
+                surface_kind: 'application',
+                status: 'active',
+                granted_permissions: ['srv_crm.contacts:read'],
+              },
+            ],
+          },
+        },
+      },
+      { body: { ok: true } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+
+    await client.request({ service: 'crm', path: '/health' });
+
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
+    expect(calls[1]!.url).toBe('https://crm-api.topolo.app/health');
+  });
+
+  it('prefers live catalog api_base_url for dynamic services', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_future',
+                app_slug: 'topolo-future',
+                name: 'Future',
+                api_base_url: 'https://future-api.topolo.app',
+                launch_url: 'https://future.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+                granted_permissions: ['srv_future.read:all'],
+              },
+            ],
+          },
+        },
+      },
+      { body: { ok: true } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+
+    await client.request({ service: 'future', path: '/health' });
+
+    expect(calls[1]!.url).toBe('https://future-api.topolo.app/health');
   });
 
   it('refuses a bundled static service that is absent from the scoped live catalog', async () => {
@@ -546,7 +619,8 @@ describe('TopoloClient.listServices', () => {
                 service_id: 'srv_crm',
                 app_slug: 'topolo-crm',
                 name: 'Topolo CRM',
-                base_url: 'https://crm-api.topolo.app',
+                api_base_url: 'https://crm-api.topolo.app',
+                launch_url: 'https://crm.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
                 granted_permissions: ['srv_crm.contacts:read'],
@@ -579,7 +653,7 @@ describe('TopoloClient.listServices', () => {
                 service_id: 'srv_future_app',
                 app_slug: 'topolo-future-app',
                 name: 'Future App',
-                base_url: 'https://future-app.topolo.app',
+                launch_url: 'https://future-app.topolo.app',
                 surface_kind: 'application',
                 status: 'active',
                 granted_permissions: ['srv_future_app.launch:read'],
@@ -612,7 +686,8 @@ describe('TopoloClient.listServices', () => {
                 service_id: 'srv_future',
                 app_slug: 'topolo-warehouse',
                 name: 'Warehouse',
-                base_url: 'https://warehouse.topolo.app',
+                api_base_url: 'https://warehouse.topolo.app',
+                launch_url: 'https://warehouse.topolo.app',
                 surface_kind: 'api',
                 status: 'active',
                 granted_permissions: ['srv_future.read:all'],

package/src/client.ts

@@ -9,6 +9,7 @@ import { TopoloAuthError, TopoloHttpError, TopoloPermissionError, TopoloSdkError
 import {
   DEFAULT_SERVICE_URLS,
   APPLICATIONS,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   type ServiceId,
 } from './services.js';
@@ -105,7 +106,8 @@ export interface TopoloServiceCatalogEntry {
   slug: string | null;
   name: string | null;
   description: string | null;
-  baseUrl: string | null;
+  apiBaseUrl?: string | null;
+  launchUrl?: string | null;
   status: string | null;
   surfaceKind: string | null;
   launchable: boolean;
@@ -325,8 +327,12 @@ export class TopoloClient {
   private async resolveLiveCallableService(serviceKey: string): Promise<{ serviceKey: string; baseUrl: string } | null> {
     const catalog = await this.listServices();
     const match = catalog.find((entry) => catalogEntryMatches(entry, serviceKey));
-    if (!match?.baseUrl || !isCallableCatalogEntry(match)) return null;
-    return { serviceKey, baseUrl: match.baseUrl };
+    if (!match) return null;
+    const baseUrl = resolveCatalogServiceUrl(match, {
+      serviceKey,
+      overrides: this.serviceUrls,
+    });
+    return baseUrl ? { serviceKey, baseUrl } : null;
   }
 
   /**
@@ -447,7 +453,18 @@ export class TopoloClient {
         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,
+        apiBaseUrl:
+          typeof s.api_base_url === 'string'
+            ? s.api_base_url
+            : typeof s.apiBaseUrl === 'string'
+              ? s.apiBaseUrl
+              : null,
+        launchUrl:
+          typeof s.launch_url === 'string'
+            ? s.launch_url
+            : typeof s.launchUrl === 'string'
+              ? s.launchUrl
+              : null,
         status: typeof s.status === 'string' ? s.status : null,
         surfaceKind:
           typeof s.surface_kind === 'string' ? s.surface_kind : null,
@@ -554,7 +571,8 @@ export class TopoloClient {
       slug: app.id,
       name: app.name ?? app.id,
       description: null,
-      baseUrl: app.productionUrl ?? null,
+      apiBaseUrl: null,
+      launchUrl: app.productionUrl ?? null,
       status: 'bundled',
       surfaceKind: 'application',
       launchable: Boolean(app.productionUrl),
@@ -674,15 +692,6 @@ function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
   return [...keys];
 }
 
-function isCallableCatalogEntry(entry: TopoloServiceCatalogEntry): boolean {
-  const kind = normalizeLookupKey(entry.surfaceKind || '');
-  if (kind === 'api' || kind === 'technical_service' || kind === 'service') return true;
-  return Boolean(
-    entry.baseUrl &&
-    catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key)),
-  );
-}
-
 function normalizeActionCatalogEntry(item: unknown): TopoloActionCatalogEntry | null {
   if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
   const a = item as Record<string, unknown>;

package/src/index.ts

@@ -17,6 +17,7 @@ export {
   auditApplicationRequirements,
   applicationRequirementScopes,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   type ApplicationCatalogEntry,
   type ApplicationDeployTarget,
@@ -29,6 +30,7 @@ export {
   type ApplicationRequirementScope,
   type ApplicationRequirementStatus,
   type ApplicationRequirementsAuditReport,
+  type ServiceCatalogUrlEntry,
   type ServiceId,
 } from "./services.js";
 export {

package/src/modules/p2p.test.ts

@@ -22,7 +22,8 @@ function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
               service_id: 'srv_p2p',
               app_slug: 'topolo-p2p',
               name: 'Topolo P2P',
-              base_url: 'https://p2p.topolo.app',
+              api_base_url: 'https://p2p.topolo.app',
+              launch_url: 'https://p2p.topolo.app',
               surface_kind: 'api',
               status: 'active',
               granted_permissions: ['srv_p2p.directory:read'],

package/src/services.generated.ts

@@ -27,7 +27,7 @@ export const SERVICES = {
   inventory: "https://inventory.topolo.app",
   learn: "https://learn-api.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail.topolo.app",
+  mail: "https://mail-api.topolo.app",
   mdm: "https://mdm-api.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",

package/src/services.test.ts

@@ -7,6 +7,7 @@ import {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   applicationRequirementScopes,
+  resolveCatalogServiceUrl,
   requirementsForApplication,
 } from './services.js';
 
@@ -69,7 +70,7 @@ describe('service registry', () => {
       books: 'https://books.topolo.app',
       consent: 'https://consent.topolo.app',
       feed: 'https://feed-api.topolo.app',
-      mail: 'https://mail.topolo.app',
+      mail: 'https://mail-api.topolo.app',
       one: 'https://one.topolo.app',
       web: 'https://web-api.topolo.app',
     });
@@ -97,6 +98,35 @@ describe('service registry', () => {
       expect(applicationServices.has(serviceId)).toBe(true);
     }
   });
+
+  it('resolves services from explicit catalog API URLs', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_crm',
+      slug: 'topolo-crm',
+      name: 'Topolo CRM',
+      launchUrl: 'https://crm.topolo.app',
+      apiBaseUrl: 'https://crm-api.topolo.app',
+    }, { serviceKey: 'crm' })).toBe('https://crm-api.topolo.app');
+  });
+
+  it('does not infer callable URLs from launcher URLs', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_crm',
+      slug: 'topolo-crm',
+      name: 'Topolo CRM',
+      launchUrl: 'https://crm.stg.topolo.us',
+    }, { serviceKey: 'crm' })).toBeNull();
+  });
+
+  it('prefers explicit catalog API URLs over launch URLs', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_future',
+      slug: 'topolo-future',
+      name: 'Future',
+      launchUrl: 'https://future.topolo.app',
+      apiBaseUrl: 'https://future-api.topolo.app',
+    })).toBe('https://future-api.topolo.app');
+  });
 });
 
 describe('application catalog', () => {

package/src/services.ts

@@ -47,16 +47,92 @@ export type { ApplicationCatalogEntry, ApplicationDeployTarget, ApplicationId };
 
 export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = SERVICES;
 
+export interface ServiceCatalogUrlEntry {
+  serviceId?: string | null;
+  slug?: string | null;
+  name?: string | null;
+  apiBaseUrl?: string | null;
+  launchUrl?: string | null;
+  api_base_url?: string | null;
+  launch_url?: string | null;
+}
+
+export function resolveCatalogServiceUrl(
+  entry: ServiceCatalogUrlEntry,
+  options: {
+    serviceKey?: string;
+    overrides?: Record<string, string> | Partial<Record<ServiceId, string>>;
+  } = {},
+): string | null {
+  const keys = catalogServiceKeyCandidates(entry, options.serviceKey);
+  const override = resolveServiceUrlOverride(keys, options.overrides);
+  if (override) return override;
+
+  const apiBaseUrl = firstString(entry.apiBaseUrl, entry.api_base_url);
+  if (apiBaseUrl) return apiBaseUrl;
+
+  return null;
+}
+
 export function resolveServiceUrl(
   service: ServiceId,
   overrides?: Partial<Record<ServiceId, string>>,
 ): string {
-  const override = overrides?.[service];
+  const override = resolveServiceUrlOverride([service], overrides);
   if (override) return override;
 
-  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, '_').toUpperCase()}`;
-  const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
-  if (envValue) return envValue;
-
   return DEFAULT_SERVICE_URLS[service];
 }
+
+function catalogServiceKeyCandidates(entry: ServiceCatalogUrlEntry, preferred?: string): string[] {
+  const values = [preferred, entry.slug, entry.name, entry.serviceId].filter(
+    (value): value is string => typeof value === 'string' && value.trim().length > 0,
+  );
+  const keys = new Set<string>();
+  for (const value of values) {
+    for (const candidate of serviceKeyCandidates(value)) keys.add(candidate);
+  }
+  return [...keys];
+}
+
+function serviceKeyCandidates(value: string): string[] {
+  const normalized = value.trim().toLowerCase().replace(/\s+/g, '-');
+  const withoutTopolo = normalized.startsWith('topolo-')
+    ? normalized.slice('topolo-'.length)
+    : normalized;
+  return [...new Set([
+    normalized,
+    normalized.replace(/-/g, '_'),
+    withoutTopolo,
+    withoutTopolo.replace(/-/g, '_'),
+  ])].filter(Boolean);
+}
+
+function resolveServiceUrlOverride(
+  keys: string[],
+  overrides?: Record<string, string> | Partial<Record<ServiceId, string>>,
+): string | null {
+  for (const key of keys) {
+    const direct = overrides?.[key as ServiceId];
+    if (direct) return direct;
+
+    const envStyleKey = key.replace(/\./g, '_');
+    const envStyle = overrides?.[envStyleKey as ServiceId];
+    if (envStyle) return envStyle;
+  }
+
+  for (const key of keys) {
+    const envKey = `TOPOLO_SERVICE_URL_${key.replace(/\./g, '_').toUpperCase()}`;
+    const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
+    if (envValue) return envValue;
+  }
+
+  return null;
+}
+
+function firstString(...values: Array<string | null | undefined>): string | null {
+  for (const value of values) {
+    if (typeof value === 'string' && value.trim()) return value.trim();
+  }
+  return null;
+}