@topolo/sdk 0.1.0 → 0.1.1

package/dist/index.cjs

@@ -225,10 +225,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.js

@@ -188,10 +188,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.1",
   "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,171 @@
+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);
+  });
+});
+
+// Silence unused-import warning if the bundler later tree-shakes these
+void TopoloHttpError;

package/src/client.ts

@@ -220,12 +220,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/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;