@topolo/sdk 0.4.3 → 0.4.5

package/dist/index.cjs

@@ -47,6 +47,7 @@ __export(index_exports, {
   defineTopoloRecentActivityWidget: () => defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   requirementsForApplication: () => requirementsForApplication,
+  resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
   validateTopoloWidgetResponse: () => validateTopoloWidgetResponse
 });
@@ -2099,17 +2100,90 @@ 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;
+  const bundledUrl = firstBundledServiceUrl(keys);
+  const liveUrl = firstString(entry.baseUrl);
+  if (bundledUrl && (!liveUrl || sameUrlEnvironment(bundledUrl, liveUrl))) return bundledUrl;
+  return liveUrl ?? bundledUrl ?? 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 firstBundledServiceUrl(keys) {
+  for (const key of keys) {
+    const url = DEFAULT_SERVICE_URLS[key];
+    if (url) return url;
+  }
+  return null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+function sameUrlEnvironment(left, right) {
+  return urlEnvironment(left) === urlEnvironment(right);
+}
+function urlEnvironment(value) {
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1") return "local";
+    if (host.endsWith(".stg.topolo.us") || host.includes("topolo-staging")) return "staging";
+    if (host.endsWith(".topolo.app") || host.endsWith(".topolo.us")) return "production";
+    return "external";
+  } catch {
+    return "external";
+  }
+}
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
+var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2277,8 +2351,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 || !isCallableCatalogEntry(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.
@@ -2372,6 +2450,8 @@ var TopoloClient = 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,
         launchable: s.launchable === true,
@@ -2438,6 +2518,10 @@ var TopoloClient = class _TopoloClient {
       path: mapped.path,
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name
+      },
       confirm: options.confirm === true
     });
   }
@@ -2453,6 +2537,8 @@ var TopoloClient = class _TopoloClient {
       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),
@@ -2496,7 +2582,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()}`;
@@ -2506,7 +2592,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()}`;
@@ -2515,7 +2601,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([
@@ -2537,7 +2623,7 @@ 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);
     }
   }
@@ -2547,7 +2633,7 @@ 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))
+    (entry.baseUrl || entry.apiBaseUrl) && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
   );
 }
 function normalizeActionCatalogEntry(item) {
@@ -3228,6 +3314,7 @@ function createTopolo(options) {
   defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   validateTopoloWidgetResponse
 });

package/dist/index.d.cts

@@ -105,6 +105,8 @@ interface TopoloServiceCatalogEntry {
     name: string | null;
     description: string | null;
     baseUrl: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
@@ -1579,6 +1581,20 @@ 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;
+    baseUrl?: 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 +2101,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

@@ -105,6 +105,8 @@ interface TopoloServiceCatalogEntry {
     name: string | null;
     description: string | null;
     baseUrl: string | null;
+    apiBaseUrl?: string | null;
+    launchUrl?: string | null;
     status: string | null;
     surfaceKind: string | null;
     launchable: boolean;
@@ -1579,6 +1581,20 @@ 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;
+    baseUrl?: 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 +2101,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

@@ -2045,17 +2045,90 @@ 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;
+  const bundledUrl = firstBundledServiceUrl(keys);
+  const liveUrl = firstString(entry.baseUrl);
+  if (bundledUrl && (!liveUrl || sameUrlEnvironment(bundledUrl, liveUrl))) return bundledUrl;
+  return liveUrl ?? bundledUrl ?? 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 firstBundledServiceUrl(keys) {
+  for (const key of keys) {
+    const url = DEFAULT_SERVICE_URLS[key];
+    if (url) return url;
+  }
+  return null;
+}
+function firstString(...values) {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return null;
+}
+function sameUrlEnvironment(left, right) {
+  return urlEnvironment(left) === urlEnvironment(right);
+}
+function urlEnvironment(value) {
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    if (host === "localhost" || host === "127.0.0.1") return "local";
+    if (host.endsWith(".stg.topolo.us") || host.includes("topolo-staging")) return "staging";
+    if (host.endsWith(".topolo.app") || host.endsWith(".topolo.us")) return "production";
+    return "external";
+  } catch {
+    return "external";
+  }
+}
 
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
+var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
+var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2223,8 +2296,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 || !isCallableCatalogEntry(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.
@@ -2318,6 +2395,8 @@ var TopoloClient = 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,
         launchable: s.launchable === true,
@@ -2384,6 +2463,10 @@ var TopoloClient = class _TopoloClient {
       path: mapped.path,
       ...mapped.query ? { query: mapped.query } : {},
       ...mapped.body !== void 0 ? { body: mapped.body } : {},
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name
+      },
       confirm: options.confirm === true
     });
   }
@@ -2399,6 +2482,8 @@ var TopoloClient = class _TopoloClient {
       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),
@@ -2442,7 +2527,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()}`;
@@ -2452,7 +2537,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()}`;
@@ -2461,7 +2546,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([
@@ -2483,7 +2568,7 @@ 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);
     }
   }
@@ -2493,7 +2578,7 @@ 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))
+    (entry.baseUrl || entry.apiBaseUrl) && catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key))
   );
 }
 function normalizeActionCatalogEntry(item) {
@@ -3173,6 +3258,7 @@ export {
   defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget,
   requirementsForApplication,
+  resolveCatalogServiceUrl,
   resolveServiceUrl,
   validateTopoloWidgetResponse
 };

package/package.json

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

package/src/client.test.ts

@@ -477,6 +477,8 @@ describe('TopoloClient.listServices', () => {
         name: 'Topolo Director',
         description: 'Demo control plane',
         baseUrl: 'https://director.topolo.app',
+        apiBaseUrl: null,
+        launchUrl: null,
         status: 'active',
         surfaceKind: 'application',
         launchable: true,
@@ -536,6 +538,74 @@ describe('TopoloClient.listServices', () => {
     expect(calls[1]!.url).toBe('https://mail.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',
+                base_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',
+                base_url: 'https://future.topolo.app',
+                api_base_url: 'https://future-api.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 () => {
     const { impl, calls } = stubFetch([
       {
@@ -671,8 +741,11 @@ describe('TopoloClient action catalog', () => {
     await client.callAction('messages.list', { mailboxId: 'primary', q: 'Ada', page: 2 });
     const call = requestCalls(calls)[0]!;
     const url = new URL(call.url);
-    expect(url.toString()).toBe('https://mail-api.topolo.app/api/mail/mailboxes/primary/messages?q=Ada&page=2');
+    expect(url.toString()).toBe('https://mail.topolo.app/api/mail/mailboxes/primary/messages?q=Ada&page=2');
     expect(call.init.method).toBe('GET');
+    const headers = new Headers(call.init.headers);
+    expect(headers.get('X-Topolo-Action-Id')).toBe('srv_mail.messages.list');
+    expect(headers.get('X-Topolo-Action-Name')).toBe('messages.list');
   });
 
   it('substitutes action path params and removes them from the query', async () => {

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';
@@ -83,6 +84,8 @@ export interface RequestOptions {
 }
 
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const TOPOLO_ACTION_ID_HEADER = 'X-Topolo-Action-Id';
+const TOPOLO_ACTION_NAME_HEADER = 'X-Topolo-Action-Name';
 
 const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
@@ -104,6 +107,8 @@ export interface TopoloServiceCatalogEntry {
   name: string | null;
   description: string | null;
   baseUrl: string | null;
+  apiBaseUrl?: string | null;
+  launchUrl?: string | null;
   status: string | null;
   surfaceKind: string | null;
   launchable: boolean;
@@ -323,8 +328,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 || !isCallableCatalogEntry(match)) return null;
+    const baseUrl = resolveCatalogServiceUrl(match, {
+      serviceKey,
+      overrides: this.serviceUrls,
+    });
+    return baseUrl ? { serviceKey, baseUrl } : null;
   }
 
   /**
@@ -446,6 +455,18 @@ export class TopoloClient {
         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,
@@ -529,6 +550,10 @@ export class TopoloClient {
       path: mapped.path,
       ...(mapped.query ? { query: mapped.query } : {}),
       ...(mapped.body !== undefined ? { body: mapped.body } : {}),
+      headers: {
+        [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
+        [TOPOLO_ACTION_NAME_HEADER]: entry.name,
+      },
       confirm: options.confirm === true,
     });
   }
@@ -549,6 +574,8 @@ export class TopoloClient {
       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),
@@ -672,7 +699,7 @@ function isCallableCatalogEntry(entry: TopoloServiceCatalogEntry): boolean {
   const kind = normalizeLookupKey(entry.surfaceKind || '');
   if (kind === 'api' || kind === 'technical_service' || kind === 'service') return true;
   return Boolean(
-    entry.baseUrl &&
+    (entry.baseUrl || entry.apiBaseUrl) &&
     catalogEntryLookupKeys(entry).some((key) => Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, key)),
   );
 }

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/services.test.ts

@@ -7,6 +7,7 @@ import {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   applicationRequirementScopes,
+  resolveCatalogServiceUrl,
   requirementsForApplication,
 } from './services.js';
 
@@ -97,6 +98,34 @@ describe('service registry', () => {
       expect(applicationServices.has(serviceId)).toBe(true);
     }
   });
+
+  it('resolves known split-surface services to the generated callable URL', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_crm',
+      slug: 'topolo-crm',
+      name: 'Topolo CRM',
+      baseUrl: 'https://crm.topolo.app',
+    }, { serviceKey: 'crm' })).toBe('https://crm-api.topolo.app');
+  });
+
+  it('uses a live staging URL instead of a production bundled default', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_crm',
+      slug: 'topolo-crm',
+      name: 'Topolo CRM',
+      baseUrl: 'https://crm.stg.topolo.us',
+    }, { serviceKey: 'crm' })).toBe('https://crm.stg.topolo.us');
+  });
+
+  it('prefers explicit catalog API URLs over launcher URLs', () => {
+    expect(resolveCatalogServiceUrl({
+      serviceId: 'srv_future',
+      slug: 'topolo-future',
+      name: 'Future',
+      baseUrl: '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,122 @@ 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;
+  baseUrl?: 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;
+
+  const bundledUrl = firstBundledServiceUrl(keys);
+  const liveUrl = firstString(entry.baseUrl);
+  if (bundledUrl && (!liveUrl || sameUrlEnvironment(bundledUrl, liveUrl))) return bundledUrl;
+
+  return liveUrl ?? bundledUrl ?? 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 firstBundledServiceUrl(keys: string[]): string | null {
+  for (const key of keys) {
+    const url = DEFAULT_SERVICE_URLS[key as ServiceId];
+    if (url) return url;
+  }
+  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;
+}
+
+function sameUrlEnvironment(left: string, right: string): boolean {
+  return urlEnvironment(left) === urlEnvironment(right);
+}
+
+function urlEnvironment(value: string): 'staging' | 'production' | 'local' | 'external' {
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    if (host === 'localhost' || host === '127.0.0.1') return 'local';
+    if (host.endsWith('.stg.topolo.us') || host.includes('topolo-staging')) return 'staging';
+    if (host.endsWith('.topolo.app') || host.endsWith('.topolo.us')) return 'production';
+    return 'external';
+  } catch {
+    return 'external';
+  }
+}