@topolo/sdk 0.4.0 → 0.4.1

package/src/client.test.ts

@@ -415,6 +415,109 @@ describe('TopoloClient.listServices', () => {
     expect(out.some((e) => e.serviceId === 'admin')).toBe(true);
     expect(out.every((e) => typeof e.serviceId === 'string')).toBe(true);
   });
+
+  it('resolves future API services from the live catalog during request routing', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_future',
+                app_slug: 'topolo-warehouse',
+                name: 'Warehouse',
+                base_url: 'https://warehouse.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+              },
+            ],
+          },
+        },
+      },
+      { 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: 'warehouse', path: '/api/health' });
+
+    expect(calls[0]!.url).toBe('https://auth.example.com/api/services/catalog');
+    expect(calls[1]!.url).toBe('https://warehouse.topolo.app/api/health');
+  });
+
+  it('does not treat live browser applications as generic API services', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_future_app',
+                app_slug: 'topolo-future-app',
+                name: 'Future App',
+                base_url: 'https://future-app.topolo.app',
+                surface_kind: 'application',
+                status: 'active',
+                launchable: true,
+              },
+            ],
+          },
+        },
+      },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+      serviceUrls: { auth: 'https://auth.example.com' },
+    });
+
+    await expect(client.request({ service: 'future-app', path: '/api/health' })).rejects.toMatchObject({
+      code: 'unknown_service',
+    });
+  });
+
+  it('caches the live catalog per client for repeated dynamic service calls', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            services: [
+              {
+                service_id: 'srv_future',
+                app_slug: 'topolo-warehouse',
+                name: 'Warehouse',
+                base_url: 'https://warehouse.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+              },
+            ],
+          },
+        },
+      },
+      { body: { ok: true } },
+      { 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: 'warehouse', path: '/api/one' });
+    await client.request({ service: 'warehouse', path: '/api/two' });
+
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://auth.example.com/api/services/catalog',
+      'https://warehouse.topolo.app/api/one',
+      'https://warehouse.topolo.app/api/two',
+    ]);
+  });
 });
 
 // Silence unused-import warning if the bundler later tree-shakes these

package/src/client.ts

@@ -5,8 +5,9 @@ import {
   type AgentIdentity,
   type TopoloCredential,
 } from './auth.js';
-import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from './errors.js';
+import { TopoloAuthError, TopoloHttpError, TopoloPermissionError, TopoloSdkError } from './errors.js';
 import {
+  DEFAULT_SERVICE_URLS,
   APPLICATIONS,
   resolveServiceUrl,
   type ServiceId,
@@ -16,9 +17,9 @@ export interface TopoloClientOptions {
   credential: TopoloCredential;
   agent: AgentIdentity;
   /** Per-service URL overrides. Useful for staging/dev. */
-  serviceUrls?: Partial<Record<ServiceId, string>>;
+  serviceUrls?: Record<string, string>;
   /** Per-service TopoloAuth service id overrides from the owning app/deployment. */
-  serviceIds?: Partial<Record<ServiceId, string>>;
+  serviceIds?: Record<string, string>;
   /**
    * When true, mutating helpers (POST/PUT/PATCH/DELETE) require callers to pass
    * `{ confirm: true }`. Defaults to true. Set false only for trusted surfaces.
@@ -41,7 +42,7 @@ export type TopoloDebugEvent =
   | {
       phase: 'request';
       method: string;
-      service: ServiceId;
+      service: string;
       path: string;
       url: string;
       requestId: string;
@@ -49,7 +50,7 @@ export type TopoloDebugEvent =
   | {
       phase: 'response';
       method: string;
-      service: ServiceId;
+      service: string;
       path: string;
       url: string;
       requestId: string;
@@ -59,7 +60,7 @@ export type TopoloDebugEvent =
   | {
       phase: 'error';
       method: string;
-      service: ServiceId;
+      service: string;
       path: string;
       url: string;
       requestId: string;
@@ -69,7 +70,7 @@ export type TopoloDebugEvent =
     };
 
 export interface RequestOptions {
-  service: ServiceId;
+  service: string;
   path: string;
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   query?: Record<string, string | number | boolean | undefined>;
@@ -85,6 +86,7 @@ const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 
 const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
+const CATALOG_CACHE_TTL_MS = 60 * 1000; // 1 minute
 
 interface ServiceIdCacheEntry {
   value: string | null;
@@ -110,12 +112,13 @@ export interface TopoloServiceCatalogEntry {
 export class TopoloClient {
   private readonly credential: TopoloCredential;
   private readonly agent: AgentIdentity;
-  private readonly serviceUrls?: Partial<Record<ServiceId, string>>;
-  private readonly serviceIds?: Partial<Record<ServiceId, string>>;
+  private readonly serviceUrls?: Record<string, string>;
+  private readonly serviceIds?: Record<string, string>;
   private readonly requireConfirmForWrites: boolean;
   private readonly timeoutMs: number;
   private readonly fetchImpl: typeof fetch;
   private readonly debug?: (event: TopoloDebugEvent) => void;
+  private serviceCatalogCache: { entries: TopoloServiceCatalogEntry[]; expiresAt: number } | null = null;
 
   /**
    * Process-wide cache for slug → service-id lookups. Keyed by
@@ -169,7 +172,8 @@ export class TopoloClient {
       );
     }
 
-    const baseUrl = resolveServiceUrl(opts.service, this.serviceUrls);
+    const resolvedService = await this.resolveRequestService(opts.service);
+    const baseUrl = resolvedService.baseUrl;
     const url = new URL(opts.path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`);
     if (opts.query) {
       for (const [k, v] of Object.entries(opts.query)) {
@@ -180,7 +184,7 @@ export class TopoloClient {
     const headers = new Headers();
     headers.set('Accept', 'application/json');
     if (opts.body !== undefined) headers.set('Content-Type', 'application/json');
-    const platformServiceId = resolveConfiguredServiceId(opts.service, this.serviceIds);
+    const platformServiceId = resolveConfiguredServiceId(resolvedService.serviceKey, this.serviceIds);
     if (platformServiceId) headers.set('X-Service-ID', platformServiceId);
 
     applyAuthHeaders(headers, this.credential);
@@ -199,7 +203,7 @@ export class TopoloClient {
 
     const urlStr = url.toString();
     const startedAt = Date.now();
-    this.emit({ phase: 'request', method, service: opts.service, path: opts.path, url: urlStr, requestId });
+    this.emit({ phase: 'request', method, service: resolvedService.serviceKey, path: opts.path, url: urlStr, requestId });
 
     let res: Response;
     try {
@@ -213,7 +217,7 @@ export class TopoloClient {
       this.emit({
         phase: 'error',
         method,
-        service: opts.service,
+        service: resolvedService.serviceKey,
         path: opts.path,
         url: urlStr,
         requestId,
@@ -236,7 +240,7 @@ export class TopoloClient {
       this.emit({
         phase: 'error',
         method,
-        service: opts.service,
+        service: resolvedService.serviceKey,
         path: opts.path,
         url: urlStr,
         requestId,
@@ -251,13 +255,13 @@ export class TopoloClient {
           extractRequired(parsed),
         );
       }
-      throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
+      throw new TopoloHttpError(resolvedService.serviceKey, opts.path, res.status, parsed);
     }
 
     this.emit({
       phase: 'response',
       method,
-      service: opts.service,
+      service: resolvedService.serviceKey,
       path: opts.path,
       url: urlStr,
       requestId,
@@ -268,6 +272,37 @@ export class TopoloClient {
     return parsed as T;
   }
 
+  private async resolveRequestService(service: string): Promise<{ serviceKey: string; baseUrl: string }> {
+    const serviceKey = normalizeLookupKey(service);
+    if (!serviceKey) {
+      throw new TopoloSdkError('unknown_service', 'service is required');
+    }
+
+    const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
+    if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
+
+    const staticUrl = DEFAULT_SERVICE_URLS[serviceKey as ServiceId];
+    if (staticUrl) return { serviceKey, baseUrl: staticUrl };
+
+    const live = await this.resolveLiveCallableService(serviceKey);
+    if (live) return live;
+
+    throw new TopoloSdkError(
+      'unknown_service',
+      `Unknown Topolo service "${service}". Run service discovery first and pass a callable service id or slug.`,
+    );
+  }
+
+  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: normalizeLookupKey(match.slug || match.name || match.serviceId) || serviceKey,
+      baseUrl: match.baseUrl,
+    };
+  }
+
   /**
    * Resolve a service-slug → opaque service-id via caller config or TopoloAuth.
    *
@@ -349,6 +384,11 @@ export class TopoloClient {
    * authoritative; the snapshot is a floor, not a cap.
    */
   async listServices(): Promise<TopoloServiceCatalogEntry[]> {
+    const now = Date.now();
+    if (this.serviceCatalogCache && this.serviceCatalogCache.expiresAt > now) {
+      return this.serviceCatalogCache.entries;
+    }
+
     try {
       const res = await this.request<
         | { data?: { services?: unknown[] } }
@@ -381,7 +421,13 @@ export class TopoloClient {
             launchable: s.launchable === true,
           });
         }
-        if (entries.length > 0) return entries;
+        if (entries.length > 0) {
+          this.serviceCatalogCache = {
+            entries,
+            expiresAt: now + CATALOG_CACHE_TTL_MS,
+          };
+          return entries;
+        }
       }
     } catch {
       // Fall through to the generated snapshot.
@@ -453,7 +499,7 @@ export class TopoloClient {
 
 function resolveConfiguredServiceId(
   slug: string,
-  serviceIds?: Partial<Record<ServiceId, string>>,
+  serviceIds?: Record<string, string>,
 ): string | null {
   for (const serviceKey of serviceKeyCandidates(slug)) {
     const configured = serviceIds?.[serviceKey as ServiceId];
@@ -467,8 +513,24 @@ function resolveConfiguredServiceId(
   return null;
 }
 
+function resolveConfiguredServiceUrl(
+  slug: string,
+  serviceUrls?: Record<string, string>,
+): string | null {
+  for (const serviceKey of serviceKeyCandidates(slug)) {
+    const configured = serviceUrls?.[serviceKey];
+    if (typeof configured === 'string' && configured.trim()) return configured.trim();
+
+    const envKey = `TOPOLO_SERVICE_URL_${serviceKey.replace(/\./g, '_').toUpperCase()}`;
+    const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
+    if (typeof envValue === 'string' && envValue.trim()) return envValue.trim();
+  }
+
+  return null;
+}
+
 function serviceKeyCandidates(slug: string): string[] {
-  const normalized = slug.trim().toLowerCase();
+  const normalized = normalizeLookupKey(slug);
   const withoutTopolo = normalized.startsWith('topolo-')
     ? normalized.slice('topolo-'.length)
     : normalized;
@@ -480,6 +542,39 @@ function serviceKeyCandidates(slug: string): string[] {
   ])];
 }
 
+function normalizeLookupKey(value: string): string {
+  return String(value || '').trim().toLowerCase();
+}
+
+function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string): boolean {
+  return catalogEntryLookupKeys(entry).includes(needle);
+}
+
+function catalogEntryLookupKeys(entry: TopoloServiceCatalogEntry): string[] {
+  const values = [entry.serviceId, entry.slug, entry.name].filter((value): value is string => (
+    typeof value === 'string' && value.trim().length > 0
+  ));
+  const keys = new Set<string>();
+  for (const value of values) {
+    const normalized = normalizeLookupKey(value);
+    if (!normalized) continue;
+    keys.add(normalized);
+    keys.add(normalized.replace(/-/g, '_'));
+    if (normalized.startsWith('topolo-')) {
+      const withoutTopolo = normalized.slice('topolo-'.length);
+      keys.add(withoutTopolo);
+      keys.add(withoutTopolo.replace(/-/g, '_'));
+    }
+  }
+  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.slug && Object.prototype.hasOwnProperty.call(DEFAULT_SERVICE_URLS, catalogEntryLookupKeys(entry)[0] ?? ''));
+}
+
 interface AuthMePayload {
   credentialType?: 'access_token' | 'api_key';
   user: RawUser;

package/src/services.generated.ts

@@ -5,6 +5,7 @@
 export const SERVICES = {
   agent: "https://agent-api.topolo.app",
   auth: "https://auth.topolo.app",
+  backup: "https://backup.topolo.app",
   books: "https://books.topolo.app",
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://bytes-api.topolo.app",
@@ -15,7 +16,6 @@ export const SERVICES = {
   compose: "https://compose.topolo.app",
   consent: "https://consent.topolo.app",
   crm: "https://crm-api.topolo.app",
-  customer_success: "https://success.topolo.app",
   developers: "https://developers.topolo.app",
   director: "https://director.topolo.app",
   feed: "https://feed-api.topolo.app",
@@ -29,9 +29,10 @@ export const SERVICES = {
   localize: "https://localize.topolo.app",
   mail: "https://mail.topolo.app",
   mdm: "https://mdm-api.topolo.app",
-  messaging: "https://messages.topolo.app",
+  messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
   notify: "https://notify.topolo.app",
+  observability_watch: "https://observability-watch.topolo.app",
   one: "https://one.topolo.app",
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
@@ -45,6 +46,7 @@ export const SERVICES = {
   socialize: "https://socialize-api.topolo.app",
   spaces: "https://spaces.topolo.app",
   status: "https://status.topolo.app",
+  success: "https://success.topolo.app",
   support: "https://support.topolo.app",
   survey: "https://survey.topolo.app",
   voice: "https://voice.topolo.app",

package/src/services.test.ts

@@ -21,12 +21,10 @@ const EXPECTED_APPLICATION_IDS = [
   'calendar',
   'capacity',
   'chat',
-  'cloudcontrol',
   'commerce',
   'compose',
   'consent',
   'crm',
-  'customer_success',
   'developers',
   'director',
   'docs',
@@ -41,7 +39,7 @@ const EXPECTED_APPLICATION_IDS = [
   'localize',
   'mail',
   'mdm',
-  'messaging',
+  'messages',
   'nexus',
   'notify',
   'observability_watch',
@@ -57,6 +55,7 @@ const EXPECTED_APPLICATION_IDS = [
   'socialize',
   'spaces',
   'status',
+  'success',
   'support',
   'survey',
   'voice',
@@ -75,7 +74,7 @@ describe('service registry', () => {
       web: 'https://web-api.topolo.app',
     });
     expect(DEFAULT_SERVICE_URLS).toMatchObject({
-      customer_success: 'https://success.topolo.app',
+      success: 'https://success.topolo.app',
       forms: 'https://forms.topolo.app',
       survey: 'https://survey.topolo.app',
     });
@@ -118,14 +117,21 @@ describe('application catalog', () => {
     }
   });
 
-  it('treats TopoloWeb runtime as a deploy target, not an agent-callable API service', () => {
+  it('treats TopoloWeb runtime as a standalone deploy, not an agent-callable API service', () => {
     expect(APPLICATIONS.web.services).toEqual(['web']);
     expect(
       APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-api')?.serviceId,
     ).toBe('web');
+    // topolo-web-runtime (Astro, sites.topolo.app) deploys from its own wrangler
+    // config and is intentionally listed as non-callable, so it can never be an
+    // agent-callable service.
     expect(
       APPLICATIONS.web.deployTargets.find((target) => target.name === 'topolo-web-runtime')?.serviceId,
     ).toBeNull();
+    const callableTargetNames = APPLICATIONS.web.deployTargets
+      .filter((target) => target.serviceId)
+      .map((target) => target.name);
+    expect(callableTargetNames).not.toContain('topolo-web-runtime');
   });
 
   it('treats TopoloFeed analytics as telemetry, not an agent-callable API service', () => {