@topolo/sdk 0.1.1 → 0.2.1

package/dist/index.cjs

@@ -93,18 +93,41 @@ var TopoloHttpError = class extends TopoloSdkError {
   }
 };
 
-// src/services.ts
-var DEFAULT_SERVICE_URLS = {
+// src/services.generated.ts
+var SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
-  crm: "https://topolo-crm-worker.topolo.workers.dev"
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mdm: "https://nodo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  "web.api": "https://web-api.topolo.app",
+  "web.runtime": "https://sites.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
   crm: "srv_iCwM4jGXcwlj"
 };
+
+// src/services.ts
+var DEFAULT_SERVICE_URLS = SERVICES;
 function resolveServiceUrl(service, overrides) {
   const override = overrides?.[service];
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  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];
@@ -119,6 +142,7 @@ var TopoloClient = class {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  debug;
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -128,6 +152,14 @@ var TopoloClient = class {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.debug = options.debug;
+  }
+  emit(event) {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+    }
   }
   /**
    * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
@@ -154,27 +186,56 @@ var TopoloClient = class {
     const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
-    applyAuditHeaders(headers, this.agent, generateRequestId());
+    const requestId = generateRequestId();
+    applyAuditHeaders(headers, this.agent, requestId);
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
     const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    const urlStr = url.toString();
+    const startedAt = Date.now();
+    this.emit({ phase: "request", method, service: opts.service, path: opts.path, url: urlStr, requestId });
     let res;
     try {
-      res = await this.fetchImpl(url.toString(), {
+      res = await this.fetchImpl(urlStr, {
         method,
         headers,
         body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
         signal
       });
+    } catch (err) {
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
     } finally {
       clearTimeout(timeoutId);
     }
     const contentType = res.headers.get("Content-Type") ?? "";
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
     if (!res.ok) {
+      const durationMs = Date.now() - startedAt;
+      const message = describeError(parsed, `HTTP ${res.status}`);
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs,
+        error: message,
+        status: res.status
+      });
       if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
       if (res.status === 403) {
         throw new TopoloPermissionError(
@@ -184,6 +245,16 @@ var TopoloClient = class {
       }
       throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
     }
+    this.emit({
+      phase: "response",
+      method,
+      service: opts.service,
+      path: opts.path,
+      url: urlStr,
+      requestId,
+      status: res.status,
+      durationMs: Date.now() - startedAt
+    });
     return parsed;
   }
   /**

package/dist/index.d.cts

@@ -31,24 +31,50 @@ interface AgentIdentity {
     agentName?: string;
 }
 
+declare const SERVICES: {
+    readonly agent: "https://topolo-agent-worker.topolo.workers.dev";
+    readonly auth: "https://auth.topolo.app";
+    readonly bugfix: "https://bugfix.topolo.app";
+    readonly bytes: "https://r2-media-manager-worker.topolo.workers.dev";
+    readonly chat: "https://chat.topolo.app";
+    readonly commerce: "https://topolo-commerce-api.topolo.workers.dev";
+    readonly crm: "https://crm-api.topolo.app";
+    readonly forecast: "https://forecast-worker-production.topolo.workers.dev";
+    readonly learn: "https://topololearn-api.topolo.workers.dev";
+    readonly mdm: "https://nodo-mdm-api.topolo.app";
+    readonly messaging: "https://messages.topolo.app";
+    readonly nexus: "https://topolo-nexus-gateway.topolo.workers.dev";
+    readonly one: "https://topoloone-worker.topolo.workers.dev";
+    readonly pay: "https://topolo-pay.topolo.workers.dev";
+    readonly "quro.api": "https://api.ol0.me";
+    readonly "quro.redirect": "https://ol0.me";
+    readonly roadmapper: "https://roadmapper-api.topolo.app";
+    readonly social_studio: "https://topolo-social-studio-api.topolo.workers.dev";
+    readonly socialize: "https://socialize-prod-api.topolo.workers.dev";
+    readonly support: "https://support.topolo.app";
+    readonly "web.api": "https://web-api.topolo.app";
+    readonly "web.runtime": "https://sites.topolo.app";
+};
+type ServiceId = keyof typeof SERVICES;
+declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
+
 /**
- * Service registry — base URLs for each Topolo platform service.
+ * Service registry — base URLs for every Topolo platform service.
  *
- * Defaults point at production. Any entry can be overridden per-call via
- * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
+ * `SERVICES` map is regenerated from those files via
+ * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
+ *
+ * Any entry can be overridden per-call via `TopoloClient` options, or globally
+ * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
-type ServiceId = 'auth' | 'crm';
+
 declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
-/**
- * Service IDs as registered in TopoloAuth's service catalog. These are sent in
- * the `X-Service-ID` header when the platform needs to route an API-key
- * introspection or permission check.
- */
-declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
 
 interface TopoloClientOptions {
@@ -65,7 +91,41 @@ interface TopoloClientOptions {
     timeoutMs?: number;
     /** Injected fetch, for testing. Defaults to global fetch. */
     fetch?: typeof fetch;
+    /**
+     * Observability hook. Fires once per request lifecycle (`request` at start,
+     * then exactly one of `response` or `error`). Safe to leave unset — off by
+     * default. Intended for CLI/MCP hosts to surface request-level diagnostics
+     * and for consumers building their own logging/tracing.
+     */
+    debug?: (event: TopoloDebugEvent) => void;
 }
+type TopoloDebugEvent = {
+    phase: 'request';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+} | {
+    phase: 'response';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+    status: number;
+    durationMs: number;
+} | {
+    phase: 'error';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+    durationMs: number;
+    error: string;
+    status?: number;
+};
 interface RequestOptions {
     service: ServiceId;
     path: string;
@@ -85,7 +145,9 @@ declare class TopoloClient {
     private readonly requireConfirmForWrites;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    private readonly debug?;
     constructor(options: TopoloClientOptions);
+    private emit;
     /**
      * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
      * for anything a caller would reach for; this stays exported for escape-hatch
@@ -274,4 +336,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };
+export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };

package/dist/index.d.ts

@@ -31,24 +31,50 @@ interface AgentIdentity {
     agentName?: string;
 }
 
+declare const SERVICES: {
+    readonly agent: "https://topolo-agent-worker.topolo.workers.dev";
+    readonly auth: "https://auth.topolo.app";
+    readonly bugfix: "https://bugfix.topolo.app";
+    readonly bytes: "https://r2-media-manager-worker.topolo.workers.dev";
+    readonly chat: "https://chat.topolo.app";
+    readonly commerce: "https://topolo-commerce-api.topolo.workers.dev";
+    readonly crm: "https://crm-api.topolo.app";
+    readonly forecast: "https://forecast-worker-production.topolo.workers.dev";
+    readonly learn: "https://topololearn-api.topolo.workers.dev";
+    readonly mdm: "https://nodo-mdm-api.topolo.app";
+    readonly messaging: "https://messages.topolo.app";
+    readonly nexus: "https://topolo-nexus-gateway.topolo.workers.dev";
+    readonly one: "https://topoloone-worker.topolo.workers.dev";
+    readonly pay: "https://topolo-pay.topolo.workers.dev";
+    readonly "quro.api": "https://api.ol0.me";
+    readonly "quro.redirect": "https://ol0.me";
+    readonly roadmapper: "https://roadmapper-api.topolo.app";
+    readonly social_studio: "https://topolo-social-studio-api.topolo.workers.dev";
+    readonly socialize: "https://socialize-prod-api.topolo.workers.dev";
+    readonly support: "https://support.topolo.app";
+    readonly "web.api": "https://web-api.topolo.app";
+    readonly "web.runtime": "https://sites.topolo.app";
+};
+type ServiceId = keyof typeof SERVICES;
+declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
+
 /**
- * Service registry — base URLs for each Topolo platform service.
+ * Service registry — base URLs for every Topolo platform service.
  *
- * Defaults point at production. Any entry can be overridden per-call via
- * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
+ * `SERVICES` map is regenerated from those files via
+ * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
+ *
+ * Any entry can be overridden per-call via `TopoloClient` options, or globally
+ * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
-type ServiceId = 'auth' | 'crm';
+
 declare const DEFAULT_SERVICE_URLS: Record<ServiceId, string>;
-/**
- * Service IDs as registered in TopoloAuth's service catalog. These are sent in
- * the `X-Service-ID` header when the platform needs to route an API-key
- * introspection or permission check.
- */
-declare const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>>;
 declare function resolveServiceUrl(service: ServiceId, overrides?: Partial<Record<ServiceId, string>>): string;
 
 interface TopoloClientOptions {
@@ -65,7 +91,41 @@ interface TopoloClientOptions {
     timeoutMs?: number;
     /** Injected fetch, for testing. Defaults to global fetch. */
     fetch?: typeof fetch;
+    /**
+     * Observability hook. Fires once per request lifecycle (`request` at start,
+     * then exactly one of `response` or `error`). Safe to leave unset — off by
+     * default. Intended for CLI/MCP hosts to surface request-level diagnostics
+     * and for consumers building their own logging/tracing.
+     */
+    debug?: (event: TopoloDebugEvent) => void;
 }
+type TopoloDebugEvent = {
+    phase: 'request';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+} | {
+    phase: 'response';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+    status: number;
+    durationMs: number;
+} | {
+    phase: 'error';
+    method: string;
+    service: ServiceId;
+    path: string;
+    url: string;
+    requestId: string;
+    durationMs: number;
+    error: string;
+    status?: number;
+};
 interface RequestOptions {
     service: ServiceId;
     path: string;
@@ -85,7 +145,9 @@ declare class TopoloClient {
     private readonly requireConfirmForWrites;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    private readonly debug?;
     constructor(options: TopoloClientOptions);
+    private emit;
     /**
      * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
      * for anything a caller would reach for; this stays exported for escape-hatch
@@ -274,4 +336,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };
+export { type AgentIdentity, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, createTopolo, resolveServiceUrl };

package/dist/index.js

@@ -56,18 +56,41 @@ var TopoloHttpError = class extends TopoloSdkError {
   }
 };
 
-// src/services.ts
-var DEFAULT_SERVICE_URLS = {
+// src/services.generated.ts
+var SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
   auth: "https://auth.topolo.app",
-  crm: "https://topolo-crm-worker.topolo.workers.dev"
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mdm: "https://nodo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  "web.api": "https://web-api.topolo.app",
+  "web.runtime": "https://sites.topolo.app"
 };
 var PLATFORM_SERVICE_IDS = {
   crm: "srv_iCwM4jGXcwlj"
 };
+
+// src/services.ts
+var DEFAULT_SERVICE_URLS = SERVICES;
 function resolveServiceUrl(service, overrides) {
   const override = overrides?.[service];
   if (override) return override;
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  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];
@@ -82,6 +105,7 @@ var TopoloClient = class {
   requireConfirmForWrites;
   timeoutMs;
   fetchImpl;
+  debug;
   constructor(options) {
     if (!options.credential) throw new TopoloAuthError("credential is required");
     if (!options.agent?.clientName) throw new TopoloAuthError("agent.clientName is required");
@@ -91,6 +115,14 @@ var TopoloClient = class {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 3e4;
     this.fetchImpl = options.fetch ?? fetch;
+    this.debug = options.debug;
+  }
+  emit(event) {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+    }
   }
   /**
    * Low-level JSON request. Prefer the typed module helpers (identity, crm, ...)
@@ -117,27 +149,56 @@ var TopoloClient = class {
     const platformServiceId = PLATFORM_SERVICE_IDS[opts.service];
     if (platformServiceId) headers.set("X-Service-ID", platformServiceId);
     applyAuthHeaders(headers, this.credential);
-    applyAuditHeaders(headers, this.agent, generateRequestId());
+    const requestId = generateRequestId();
+    applyAuditHeaders(headers, this.agent, requestId);
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
     const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
+    const urlStr = url.toString();
+    const startedAt = Date.now();
+    this.emit({ phase: "request", method, service: opts.service, path: opts.path, url: urlStr, requestId });
     let res;
     try {
-      res = await this.fetchImpl(url.toString(), {
+      res = await this.fetchImpl(urlStr, {
         method,
         headers,
         body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
         signal
       });
+    } catch (err) {
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      throw err;
     } finally {
       clearTimeout(timeoutId);
     }
     const contentType = res.headers.get("Content-Type") ?? "";
     const parsed = contentType.includes("application/json") ? await res.json().catch(() => null) : await res.text().catch(() => null);
     if (!res.ok) {
+      const durationMs = Date.now() - startedAt;
+      const message = describeError(parsed, `HTTP ${res.status}`);
+      this.emit({
+        phase: "error",
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs,
+        error: message,
+        status: res.status
+      });
       if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
       if (res.status === 403) {
         throw new TopoloPermissionError(
@@ -147,6 +208,16 @@ var TopoloClient = class {
       }
       throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
     }
+    this.emit({
+      phase: "response",
+      method,
+      service: opts.service,
+      path: opts.path,
+      url: urlStr,
+      requestId,
+      status: res.status,
+      durationMs: Date.now() - startedAt
+    });
     return parsed;
   }
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,9 +18,11 @@
     "src"
   ],
   "scripts": {
+    "generate:services": "node scripts/generate-services.mjs",
+    "prebuild": "node scripts/generate-services.mjs",
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "node scripts/generate-services.mjs && tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"
   },

package/src/client.test.ts

@@ -167,5 +167,89 @@ describe('TopoloClient.request', () => {
   });
 });
 
+describe('TopoloClient.debug hook', () => {
+  it('fires request → response on a successful call with stable requestId + duration', async () => {
+    const { impl } = stubFetch([{ body: { ok: true } }]);
+    const events: unknown[] = [];
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      debug: (e) => events.push(e),
+    });
+    await client.request({ service: 'auth', path: '/api/me' });
+    expect(events).toHaveLength(2);
+    const typed = events as Array<{
+      phase: string;
+      method: string;
+      service: string;
+      path: string;
+      url: string;
+      requestId: string;
+      status?: number;
+      durationMs?: number;
+    }>;
+    const req = typed[0]!;
+    const res = typed[1]!;
+    expect(req.phase).toBe('request');
+    expect(req.method).toBe('GET');
+    expect(req.service).toBe('auth');
+    expect(req.path).toBe('/api/me');
+    expect(req.requestId).toMatch(/.+/);
+    expect(res.phase).toBe('response');
+    expect(res.status).toBe(200);
+    expect(res.requestId).toBe(req.requestId);
+    expect(typeof res.durationMs).toBe('number');
+  });
+
+  it('fires request → error on 4xx with the unwrapped message and status', async () => {
+    const { impl } = stubFetch([
+      { status: 401, body: { error: { code: 'auth_error', message: 'Expired' } } },
+    ]);
+    const events: Array<{ phase: string; error?: string; status?: number }> = [];
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      debug: (e) => events.push(e),
+    });
+    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toThrow(TopoloAuthError);
+    expect(events.map((e) => e.phase)).toEqual(['request', 'error']);
+    expect(events[1]!.status).toBe(401);
+    expect(events[1]!.error).toBe('Expired');
+  });
+
+  it('fires request → error on a thrown fetch (network failure)', async () => {
+    const impl = (vi.fn(async () => {
+      throw new Error('ECONNREFUSED');
+    }) as unknown) as typeof fetch;
+    const events: Array<{ phase: string; error?: string; status?: number }> = [];
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      debug: (e) => events.push(e),
+    });
+    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toThrow('ECONNREFUSED');
+    expect(events.map((e) => e.phase)).toEqual(['request', 'error']);
+    expect(events[1]!.error).toBe('ECONNREFUSED');
+    expect(events[1]!.status).toBeUndefined();
+  });
+
+  it('swallows throws from the debug callback without affecting the request path', async () => {
+    const { impl } = stubFetch([{ body: { ok: true } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'x' },
+      agent: AGENT,
+      fetch: impl,
+      debug: () => {
+        throw new Error('callback blew up');
+      },
+    });
+    // Returns normally despite the callback throwing on both events.
+    await expect(client.request({ service: 'auth', path: '/api/me' })).resolves.toBeDefined();
+  });
+});
+
 // Silence unused-import warning if the bundler later tree-shakes these
 void TopoloHttpError;

package/src/client.ts

@@ -26,8 +26,46 @@ export interface TopoloClientOptions {
   timeoutMs?: number;
   /** Injected fetch, for testing. Defaults to global fetch. */
   fetch?: typeof fetch;
+  /**
+   * Observability hook. Fires once per request lifecycle (`request` at start,
+   * then exactly one of `response` or `error`). Safe to leave unset — off by
+   * default. Intended for CLI/MCP hosts to surface request-level diagnostics
+   * and for consumers building their own logging/tracing.
+   */
+  debug?: (event: TopoloDebugEvent) => void;
 }
 
+export type TopoloDebugEvent =
+  | {
+      phase: 'request';
+      method: string;
+      service: ServiceId;
+      path: string;
+      url: string;
+      requestId: string;
+    }
+  | {
+      phase: 'response';
+      method: string;
+      service: ServiceId;
+      path: string;
+      url: string;
+      requestId: string;
+      status: number;
+      durationMs: number;
+    }
+  | {
+      phase: 'error';
+      method: string;
+      service: ServiceId;
+      path: string;
+      url: string;
+      requestId: string;
+      durationMs: number;
+      error: string;
+      status?: number;
+    };
+
 export interface RequestOptions {
   service: ServiceId;
   path: string;
@@ -50,6 +88,7 @@ export class TopoloClient {
   private readonly requireConfirmForWrites: boolean;
   private readonly timeoutMs: number;
   private readonly fetchImpl: typeof fetch;
+  private readonly debug?: (event: TopoloDebugEvent) => void;
 
   constructor(options: TopoloClientOptions) {
     if (!options.credential) throw new TopoloAuthError('credential is required');
@@ -60,6 +99,16 @@ export class TopoloClient {
     this.requireConfirmForWrites = options.requireConfirmForWrites !== false;
     this.timeoutMs = options.timeoutMs ?? 30_000;
     this.fetchImpl = options.fetch ?? fetch;
+    this.debug = options.debug;
+  }
+
+  private emit(event: TopoloDebugEvent): void {
+    if (!this.debug) return;
+    try {
+      this.debug(event);
+    } catch {
+      // Never let a debug consumer crash the request path.
+    }
   }
 
   /**
@@ -91,7 +140,8 @@ export class TopoloClient {
     if (platformServiceId) headers.set('X-Service-ID', platformServiceId);
 
     applyAuthHeaders(headers, this.credential);
-    applyAuditHeaders(headers, this.agent, generateRequestId());
+    const requestId = generateRequestId();
+    applyAuditHeaders(headers, this.agent, requestId);
 
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
@@ -103,14 +153,30 @@ export class TopoloClient {
       ? mergeSignals(opts.signal, controller.signal)
       : controller.signal;
 
+    const urlStr = url.toString();
+    const startedAt = Date.now();
+    this.emit({ phase: 'request', method, service: opts.service, path: opts.path, url: urlStr, requestId });
+
     let res: Response;
     try {
-      res = await this.fetchImpl(url.toString(), {
+      res = await this.fetchImpl(urlStr, {
         method,
         headers,
         body: opts.body !== undefined ? JSON.stringify(opts.body) : null,
         signal,
       });
+    } catch (err) {
+      this.emit({
+        phase: 'error',
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs: Date.now() - startedAt,
+        error: err instanceof Error ? err.message : String(err),
+      });
+      throw err;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -121,6 +187,19 @@ export class TopoloClient {
       : await res.text().catch(() => null);
 
     if (!res.ok) {
+      const durationMs = Date.now() - startedAt;
+      const message = describeError(parsed, `HTTP ${res.status}`);
+      this.emit({
+        phase: 'error',
+        method,
+        service: opts.service,
+        path: opts.path,
+        url: urlStr,
+        requestId,
+        durationMs,
+        error: message,
+        status: res.status,
+      });
       if (res.status === 401) throw new TopoloAuthError(describeError(parsed, 'Unauthorized'));
       if (res.status === 403) {
         throw new TopoloPermissionError(
@@ -131,6 +210,17 @@ export class TopoloClient {
       throw new TopoloHttpError(opts.service, opts.path, res.status, parsed);
     }
 
+    this.emit({
+      phase: 'response',
+      method,
+      service: opts.service,
+      path: opts.path,
+      url: urlStr,
+      requestId,
+      status: res.status,
+      durationMs: Date.now() - startedAt,
+    });
+
     return parsed as T;
   }
 

package/src/index.ts

@@ -3,6 +3,7 @@ export {
   type TopoloClientOptions,
   type RequestOptions,
   type CredentialIntrospection,
+  type TopoloDebugEvent,
 } from './client.js';
 export type { TopoloCredential, AgentIdentity } from './auth.js';
 export {

package/src/services.generated.ts

@@ -0,0 +1,34 @@
+// AUTO-GENERATED by scripts/generate-services.mjs. Do not edit by hand.
+// Source of truth: topolo.cloudcontrol.json in every app repo.
+// Regenerate: npm run generate:services
+
+export const SERVICES = {
+  agent: "https://topolo-agent-worker.topolo.workers.dev",
+  auth: "https://auth.topolo.app",
+  bugfix: "https://bugfix.topolo.app",
+  bytes: "https://r2-media-manager-worker.topolo.workers.dev",
+  chat: "https://chat.topolo.app",
+  commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  crm: "https://crm-api.topolo.app",
+  forecast: "https://forecast-worker-production.topolo.workers.dev",
+  learn: "https://topololearn-api.topolo.workers.dev",
+  mdm: "https://nodo-mdm-api.topolo.app",
+  messaging: "https://messages.topolo.app",
+  nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  one: "https://topoloone-worker.topolo.workers.dev",
+  pay: "https://topolo-pay.topolo.workers.dev",
+  "quro.api": "https://api.ol0.me",
+  "quro.redirect": "https://ol0.me",
+  roadmapper: "https://roadmapper-api.topolo.app",
+  social_studio: "https://topolo-social-studio-api.topolo.workers.dev",
+  socialize: "https://socialize-prod-api.topolo.workers.dev",
+  support: "https://support.topolo.app",
+  "web.api": "https://web-api.topolo.app",
+  "web.runtime": "https://sites.topolo.app",
+} as const;
+
+export type ServiceId = keyof typeof SERVICES;
+
+export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
+  crm: "srv_iCwM4jGXcwlj",
+};

package/src/services.ts

@@ -1,30 +1,28 @@
 /**
- * Service registry — base URLs for each Topolo platform service.
+ * Service registry — base URLs for every Topolo platform service.
  *
- * Defaults point at production. Any entry can be overridden per-call via
- * `TopoloClient` options, or globally via env vars like `TOPOLO_SERVICE_URL_CRM`.
+ * Source of truth lives in each app's `topolo.cloudcontrol.json`. The
+ * `SERVICES` map is regenerated from those files via
+ * `scripts/generate-services.mjs`; edit the JSON, not the generated file.
+ *
+ * Any entry can be overridden per-call via `TopoloClient` options, or globally
+ * via env vars like `TOPOLO_SERVICE_URL_CRM` or `TOPOLO_SERVICE_URL_WEB_API`
+ * (dots in service IDs become underscores in env vars).
  *
  * IMPORTANT: The SDK NEVER accepts `orgId` as a parameter. Every request is
  * scoped to the organization embedded in the auth credential (JWT claim or
  * API-key binding). This is the load-bearing cross-org isolation guarantee.
  */
-export type ServiceId =
-  | 'auth'
-  | 'crm';
+import {
+  SERVICES,
+  PLATFORM_SERVICE_IDS,
+  type ServiceId,
+} from './services.generated.js';
 
-export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = {
-  auth: 'https://auth.topolo.app',
-  crm: 'https://topolo-crm-worker.topolo.workers.dev',
-};
+export { SERVICES, PLATFORM_SERVICE_IDS };
+export type { ServiceId };
 
-/**
- * Service IDs as registered in TopoloAuth's service catalog. These are sent in
- * the `X-Service-ID` header when the platform needs to route an API-key
- * introspection or permission check.
- */
-export const PLATFORM_SERVICE_IDS: Partial<Record<ServiceId, string>> = {
-  crm: 'srv_iCwM4jGXcwlj',
-};
+export const DEFAULT_SERVICE_URLS: Record<ServiceId, string> = SERVICES;
 
 export function resolveServiceUrl(
   service: ServiceId,
@@ -33,7 +31,7 @@ export function resolveServiceUrl(
   const override = overrides?.[service];
   if (override) return override;
 
-  const envKey = `TOPOLO_SERVICE_URL_${service.toUpperCase()}`;
+  const envKey = `TOPOLO_SERVICE_URL_${service.replace(/\./g, '_').toUpperCase()}`;
   const envValue = typeof process !== 'undefined' ? process.env?.[envKey] : undefined;
   if (envValue) return envValue;