@topolo/sdk 0.1.0 → 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;
   }
   /**
@@ -225,10 +273,21 @@ var TopoloClient = class {
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
-    return maybe.message ?? maybe.error ?? fallback;
+    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
+    if (resolved) return resolved;
   }
   return fallback;
 }
+function pickString(value) {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  if (value && typeof value === "object") {
+    const nested = value;
+    if (typeof nested.message === "string" && nested.message.trim().length > 0) return nested.message;
+    if (typeof nested.description === "string" && nested.description.trim().length > 0)
+      return nested.description;
+  }
+  return void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;

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;
   }
   /**
@@ -188,10 +236,21 @@ var TopoloClient = class {
 function describeError(body, fallback) {
   if (body && typeof body === "object") {
     const maybe = body;
-    return maybe.message ?? maybe.error ?? fallback;
+    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
+    if (resolved) return resolved;
   }
   return fallback;
 }
+function pickString(value) {
+  if (typeof value === "string" && value.trim().length > 0) return value;
+  if (value && typeof value === "object") {
+    const nested = value;
+    if (typeof nested.message === "string" && nested.message.trim().length > 0) return nested.message;
+    if (typeof nested.description === "string" && nested.description.trim().length > 0)
+      return nested.description;
+  }
+  return void 0;
+}
 function extractRequired(body) {
   if (body && typeof body === "object") {
     const maybe = body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.1.0",
+  "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",
@@ -20,12 +20,15 @@
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "devDependencies": {
     "@types/node": "^20.19.39",
     "tsup": "^8.0.0",
-    "typescript": "^5.4.0"
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
   },
   "engines": {
     "node": ">=20"

package/src/client.test.ts

@@ -0,0 +1,255 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from './client.js';
+import { TopoloAuthError, TopoloHttpError, TopoloPermissionError } from './errors.js';
+
+function stubFetch(responses: Array<{ status?: number; body?: unknown; contentType?: string }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    const next = responses.shift() ?? { status: 200, body: { ok: true } };
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': next.contentType ?? 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+const AGENT = { clientName: 'topolo-test', clientVersion: '0.0.0' };
+
+describe('TopoloClient.request', () => {
+  it('injects Bearer auth + audit headers for access_token credentials', async () => {
+    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'access_token', accessToken: 'tok_abc' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({ service: 'auth', path: '/api/me' });
+    const headers = new Headers(calls[0]!.init.headers);
+    expect(headers.get('Authorization')).toBe('Bearer tok_abc');
+    expect(headers.get('X-Topolo-Client')).toBe('topolo-test/0.0.0');
+    expect(headers.get('X-Topolo-Request-Id')).toMatch(/.+/);
+  });
+
+  it('uses X-Api-Key header for api_key credentials', async () => {
+    const { impl, calls } = stubFetch([{ body: { ok: true } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({ service: 'crm', path: '/api/contacts' });
+    const headers = new Headers(calls[0]!.init.headers);
+    expect(headers.get('X-Api-Key')).toBe('dak_xyz');
+    expect(headers.get('Authorization')).toBeNull();
+  });
+
+  it('refuses mutating requests without confirm', async () => {
+    const { impl } = stubFetch([]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await expect(
+      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {} }),
+    ).rejects.toBeInstanceOf(TopoloAuthError);
+  });
+
+  it('allows mutating requests with confirm: true', async () => {
+    const { impl, calls } = stubFetch([{ body: { id: 'c_1' } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({
+      service: 'crm',
+      method: 'POST',
+      path: '/api/contacts',
+      body: { email: 'a@b.co' },
+      confirm: true,
+    });
+    expect(calls[0]!.init.method).toBe('POST');
+  });
+
+  it('maps 401 → TopoloAuthError with unwrapped message', async () => {
+    const { impl } = stubFetch([
+      { status: 401, body: { error: { code: 'invalid_token', message: 'Token expired' } } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await expect(client.request({ service: 'auth', path: '/api/me' })).rejects.toMatchObject({
+      name: 'TopoloAuthError',
+      code: 'auth_error',
+      message: 'Token expired',
+    });
+  });
+
+  it('regression: nested error.message object never stringifies to [object Object]', async () => {
+    const { impl } = stubFetch([
+      { status: 401, body: { error: { code: 'bad_sig', message: 'Bad signature' } } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'access_token', accessToken: 'bad' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    try {
+      await client.request({ service: 'auth', path: '/api/me' });
+      throw new Error('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(TopoloAuthError);
+      expect((err as Error).message).not.toBe('[object Object]');
+      expect((err as Error).message).toContain('Bad signature');
+    }
+  });
+
+  it('maps 403 → TopoloPermissionError with required scopes extracted', async () => {
+    const { impl } = stubFetch([
+      { status: 403, body: { error: 'forbidden', required: ['crm.contacts:write'] } },
+    ]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await expect(
+      client.request({ service: 'crm', method: 'POST', path: '/api/contacts', body: {}, confirm: true }),
+    ).rejects.toBeInstanceOf(TopoloPermissionError);
+  });
+
+  it('maps non-401/403 failures → TopoloHttpError with status preserved', async () => {
+    const { impl } = stubFetch([{ status: 500, body: { error: 'boom' } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await expect(client.request({ service: 'crm', path: '/api/contacts' })).rejects.toMatchObject({
+      name: 'TopoloHttpError',
+      status: 500,
+    });
+  });
+
+  it('appends query params as search string', async () => {
+    const { impl, calls } = stubFetch([{ body: { contacts: [] } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({ service: 'crm', path: '/api/contacts', query: { q: 'acme', page: 2 } });
+    const u = new URL(calls[0]!.url);
+    expect(u.searchParams.get('q')).toBe('acme');
+    expect(u.searchParams.get('page')).toBe('2');
+  });
+
+  it('rejects missing credential or agent.clientName at construction', () => {
+    expect(
+      () =>
+        new TopoloClient({
+          credential: undefined as never,
+          agent: AGENT,
+        }),
+    ).toThrow(TopoloAuthError);
+    expect(
+      () =>
+        new TopoloClient({
+          credential: { kind: 'api_key', apiKey: 'x' },
+          agent: { clientName: '' as unknown as string, clientVersion: '0' },
+        }),
+    ).toThrow(TopoloAuthError);
+  });
+});
+
+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;
   }
 
@@ -220,12 +310,24 @@ interface RawOrg {
 
 function describeError(body: unknown, fallback: string): string {
   if (body && typeof body === 'object') {
-    const maybe = body as { error?: string; message?: string };
-    return maybe.message ?? maybe.error ?? fallback;
+    const maybe = body as { error?: unknown; message?: unknown };
+    const resolved = pickString(maybe.message) ?? pickString(maybe.error);
+    if (resolved) return resolved;
   }
   return fallback;
 }
 
+function pickString(value: unknown): string | undefined {
+  if (typeof value === 'string' && value.trim().length > 0) return value;
+  if (value && typeof value === 'object') {
+    const nested = value as { message?: unknown; description?: unknown };
+    if (typeof nested.message === 'string' && nested.message.trim().length > 0) return nested.message;
+    if (typeof nested.description === 'string' && nested.description.trim().length > 0)
+      return nested.description;
+  }
+  return undefined;
+}
+
 function extractRequired(body: unknown): string[] {
   if (body && typeof body === 'object') {
     const maybe = body as { required?: unknown };

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

@@ -0,0 +1,113 @@
+import { describe, expect, it, vi } from 'vitest';
+import { TopoloOAuth } from './oauth.js';
+import { TopoloAuthError, TopoloHttpError } from './errors.js';
+
+function stubFetch(next: { status: number; body: unknown }) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+describe('TopoloOAuth.pollDeviceToken', () => {
+  it('maps authorization_pending response into TopoloAuthError(code=authorization_pending)', async () => {
+    const { impl } = stubFetch({
+      status: 400,
+      body: { error: 'authorization_pending', error_description: 'Pending user approval' },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await expect(
+      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
+    ).rejects.toMatchObject({
+      name: 'TopoloAuthError',
+      code: 'authorization_pending',
+    });
+  });
+
+  it('maps slow_down into TopoloAuthError(code=slow_down)', async () => {
+    const { impl } = stubFetch({
+      status: 400,
+      body: { error: 'slow_down', error_description: 'Back off' },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await expect(
+      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
+    ).rejects.toMatchObject({ code: 'slow_down' });
+  });
+
+  it('returns TokenResponse on 200', async () => {
+    const { impl } = stubFetch({
+      status: 200,
+      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600, refresh_token: 'rt' },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    const res = await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
+    expect(res.access_token).toBe('at');
+    expect(res.refresh_token).toBe('rt');
+  });
+
+  it('wraps unknown non-OAuth failures as TopoloHttpError', async () => {
+    const { impl } = stubFetch({ status: 500, body: { unexpected: true } });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await expect(
+      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
+    ).rejects.toBeInstanceOf(TopoloHttpError);
+  });
+});
+
+describe('TopoloOAuth.refreshToken', () => {
+  it('POSTs grant_type=refresh_token with the client_id + refresh_token', async () => {
+    const { impl, calls } = stubFetch({
+      status: 200,
+      body: { access_token: 'new', token_type: 'Bearer', expires_in: 3600, refresh_token: 'new_rt' },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    const res = await oauth.refreshToken({ clientId: 'doac_x', refreshToken: 'rt_old' });
+    expect(res.access_token).toBe('new');
+    const body = new URLSearchParams(calls[0]!.init.body as string);
+    expect(body.get('grant_type')).toBe('refresh_token');
+    expect(body.get('client_id')).toBe('doac_x');
+    expect(body.get('refresh_token')).toBe('rt_old');
+  });
+
+  it('surfaces invalid_grant as TopoloAuthError', async () => {
+    const { impl } = stubFetch({
+      status: 400,
+      body: { error: 'invalid_grant', error_description: 'Refresh token revoked' },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await expect(
+      oauth.refreshToken({ clientId: 'doac_x', refreshToken: 'rt_dead' }),
+    ).rejects.toMatchObject({
+      name: 'TopoloAuthError',
+      code: 'invalid_grant',
+    });
+  });
+});
+
+describe('TopoloOAuth.requestDeviceCode', () => {
+  it('joins array scopes with a space', async () => {
+    const { impl, calls } = stubFetch({
+      status: 200,
+      body: {
+        device_code: 'dc',
+        user_code: 'ABCD-1234',
+        verification_uri: 'https://ex/dev',
+        expires_in: 600,
+        interval: 5,
+      },
+    });
+    const oauth = new TopoloOAuth({ fetch: impl });
+    await oauth.requestDeviceCode({ clientId: 'doac_x', scope: ['read', 'write'] });
+    const body = new URLSearchParams(calls[0]!.init.body as string);
+    expect(body.get('scope')).toBe('read write');
+  });
+});
+
+// Keep the TopoloAuthError import non-dead for type inference
+void TopoloAuthError;