@topolo/sdk 0.1.1 → 0.1.2

package/dist/index.cjs

@@ -119,6 +119,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 +129,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 +163,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 +222,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

@@ -65,7 +65,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 +119,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 +310,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

@@ -65,7 +65,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 +119,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 +310,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

@@ -82,6 +82,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 +92,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 +126,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 +185,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.1.2",
   "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

@@ -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 {