@topolo/sdk 0.4.7 → 0.4.9

package/src/client.ts

@@ -76,6 +76,11 @@ export interface RequestOptions {
   method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
   query?: Record<string, string | number | boolean | undefined>;
   body?: unknown;
+  /** Workspace-boundary resource context for resource-scoped API keys. */
+  resource?: {
+    resourceType: string;
+    resourceId: string;
+  };
   /** Explicit write-acknowledgement for mutating calls. */
   confirm?: boolean;
   /** Extra headers appended after auth/audit headers. */
@@ -86,6 +91,8 @@ export interface RequestOptions {
 const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
 const TOPOLO_ACTION_ID_HEADER = 'X-Topolo-Action-Id';
 const TOPOLO_ACTION_NAME_HEADER = 'X-Topolo-Action-Name';
+const TOPOLO_RESOURCE_TYPE_HEADER = 'X-Topolo-Resource-Type';
+const TOPOLO_RESOURCE_ID_HEADER = 'X-Topolo-Resource-ID';
 
 const POSITIVE_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
 const NEGATIVE_CACHE_TTL_MS = 60 * 1000; // 1 minute
@@ -112,6 +119,18 @@ export interface TopoloServiceCatalogEntry {
   surfaceKind: string | null;
   launchable: boolean;
   permissions: string[];
+  apiKeyResource: TopoloApiKeyResourceMetadata | null;
+  apiKeyResources: TopoloApiKeyResourceMetadata[];
+}
+
+export interface TopoloApiKeyResourceMetadata {
+  resourceType: string;
+  label: string;
+  emptyLabel: string;
+  resourceConcept: 'workspace';
+  canonicalResourceType: 'workspace';
+  defaultEntitlement: 'enterprise';
+  exceptionPolicy: 'app_or_organization';
 }
 
 export interface TopoloActionCatalogEntry {
@@ -222,6 +241,18 @@ export class TopoloClient {
     if (opts.headers) {
       for (const [k, v] of Object.entries(opts.headers)) headers.set(k, v);
     }
+    if (opts.resource) {
+      const resourceType = opts.resource.resourceType.trim();
+      const resourceId = opts.resource.resourceId.trim();
+      if (!resourceType || !resourceId) {
+        throw new TopoloSdkError(
+          'invalid_resource_context',
+          'Both resource.resourceType and resource.resourceId are required when resource context is provided.',
+        );
+      }
+      headers.set(TOPOLO_RESOURCE_TYPE_HEADER, resourceType);
+      headers.set(TOPOLO_RESOURCE_ID_HEADER, resourceId);
+    }
 
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
@@ -306,10 +337,20 @@ export class TopoloClient {
       throw new TopoloSdkError('unknown_service', 'service is required');
     }
 
-    if (serviceKey === 'auth') {
+    // auth + developers are DIRECT services resolved without a catalog lookup:
+    // developers serves the catalog itself, so resolving it via the catalog would
+    // recurse infinitely.
+    if (serviceKey === 'auth' || serviceKey === 'developers') {
       const overrideUrl = resolveConfiguredServiceUrl(serviceKey, this.serviceUrls);
       if (overrideUrl) return { serviceKey, baseUrl: overrideUrl };
-      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS.auth };
+      // The catalog host (developers) defaults to the SAME environment as auth.
+      // Apps configure only `auth` per-env; derive developers from it (auth.X ->
+      // developers.X) so the catalog cutover needs no per-app config change.
+      if (serviceKey === 'developers') {
+        const derived = deriveDevelopersFromAuth(resolveConfiguredServiceUrl('auth', this.serviceUrls));
+        if (derived) return { serviceKey, baseUrl: derived };
+      }
+      return { serviceKey, baseUrl: DEFAULT_SERVICE_URLS[serviceKey as 'auth' | 'developers'] };
     }
 
     const live = await this.resolveLiveCallableService(serviceKey);
@@ -355,7 +396,8 @@ export class TopoloClient {
     const configuredServiceId = resolveConfiguredServiceId(normalized, this.serviceIds);
     if (configuredServiceId) return configuredServiceId;
 
-    const authBase = resolveServiceUrl('auth', this.serviceUrls);
+    // app-catalog greenfield: by-slug resolver lives on the Catalog (developers).
+    const authBase = resolveServiceUrl('developers', this.serviceUrls);
     const cacheKey = `${authBase}|${normalized}`;
     const now = Date.now();
     const cached = TopoloClient.serviceIdCache.get(cacheKey);
@@ -419,10 +461,13 @@ export class TopoloClient {
       return this.serviceCatalogCache.entries;
     }
 
+    // app-catalog greenfield: the catalog moved to the Catalog (developers)
+    // service. Auth no longer owns the registry; it only provides scoping, which
+    // the Catalog composes server-side. Consumers pass the per-env developers URL.
     const res = await this.request<
       | { data?: { services?: unknown[] } }
       | { services?: unknown[] }
-    >({ service: 'auth', method: 'GET', path: '/api/services/catalog' });
+    >({ service: 'developers', method: 'GET', path: '/api/services/catalog' });
     const raw =
       (res as { data?: { services?: unknown[] } }).data?.services ??
       (res as { services?: unknown[] }).services;
@@ -447,6 +492,18 @@ export class TopoloClient {
         ? s.granted_permissions
             .filter((permission): permission is string => typeof permission === 'string' && permission.trim().length > 0)
         : [];
+      const catalogApiKeyResources = normalizeApiKeyResourceMetadataList(
+        s.api_key_resources ?? s.apiKeyResources,
+      );
+      const apiKeyResource =
+        normalizeApiKeyResourceMetadata(s.api_key_resource ?? s.apiKeyResource) ??
+        catalogApiKeyResources[0] ??
+        null;
+      const apiKeyResources = catalogApiKeyResources.length > 0
+        ? catalogApiKeyResources
+        : apiKeyResource
+          ? [apiKeyResource]
+          : [];
       entries.push({
         serviceId,
         slug: typeof s.app_slug === 'string' ? s.app_slug : null,
@@ -470,6 +527,8 @@ export class TopoloClient {
           typeof s.surface_kind === 'string' ? s.surface_kind : null,
         launchable: s.launchable === true,
         permissions,
+        apiKeyResource,
+        apiKeyResources,
       });
     }
     this.serviceCatalogCache = {
@@ -577,6 +636,8 @@ export class TopoloClient {
       surfaceKind: 'application',
       launchable: Boolean(app.productionUrl),
       permissions: [],
+      apiKeyResource: null,
+      apiKeyResources: [],
     }));
   }
 
@@ -640,6 +701,60 @@ function resolveConfiguredServiceId(
   return null;
 }
 
+function normalizeApiKeyResourceMetadata(input: unknown): TopoloApiKeyResourceMetadata | null {
+  if (!isRecord(input)) return null;
+  const resourceType = readString(input.resourceType ?? input.resource_type);
+  const label = readString(input.label);
+  const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
+  const resourceConcept = readString(input.resourceConcept ?? input.resource_concept);
+  const canonicalResourceType = readString(input.canonicalResourceType ?? input.canonical_resource_type);
+  const defaultEntitlement = readString(input.defaultEntitlement ?? input.default_entitlement);
+  const exceptionPolicy = readString(input.exceptionPolicy ?? input.exception_policy);
+
+  if (
+    !resourceType ||
+    !label ||
+    !emptyLabel ||
+    resourceConcept !== 'workspace' ||
+    canonicalResourceType !== 'workspace' ||
+    defaultEntitlement !== 'enterprise' ||
+    exceptionPolicy !== 'app_or_organization'
+  ) {
+    return null;
+  }
+
+  return {
+    resourceType,
+    label,
+    emptyLabel,
+    resourceConcept,
+    canonicalResourceType,
+    defaultEntitlement,
+    exceptionPolicy,
+  };
+}
+
+function normalizeApiKeyResourceMetadataList(input: unknown): TopoloApiKeyResourceMetadata[] {
+  if (!Array.isArray(input)) return [];
+  const resources: TopoloApiKeyResourceMetadata[] = [];
+  const seenTypes = new Set<string>();
+  for (const item of input) {
+    const resource = normalizeApiKeyResourceMetadata(item);
+    if (!resource || seenTypes.has(resource.resourceType)) continue;
+    seenTypes.add(resource.resourceType);
+    resources.push(resource);
+  }
+  return resources;
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 function resolveConfiguredServiceUrl(
   slug: string,
   serviceUrls?: Record<string, string>,
@@ -673,6 +788,24 @@ function normalizeLookupKey(value: string): string {
   return String(value || '').trim().toLowerCase().replace(/\s+/g, '-');
 }
 
+/**
+ * Derive the Catalog (developers) base URL from a configured auth base URL by
+ * swapping the leading `auth` host label for `developers` (auth.stg.topolo.us ->
+ * developers.stg.topolo.us). Returns null if the auth URL is absent or doesn't
+ * start with the `auth.` label, so the caller falls back to the bundled default.
+ */
+function deriveDevelopersFromAuth(authUrl: string | null | undefined): string | null {
+  if (!authUrl) return null;
+  try {
+    const url = new URL(authUrl);
+    if (!/^auth\./i.test(url.hostname)) return null;
+    url.hostname = url.hostname.replace(/^auth\./i, 'developers.');
+    return url.origin;
+  } catch {
+    return null;
+  }
+}
+
 function catalogEntryMatches(entry: TopoloServiceCatalogEntry, needle: string): boolean {
   return catalogEntryLookupKeys(entry).includes(needle);
 }

package/src/index.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it, vi } from 'vitest';
+import {
+  createTopolo,
+  CrmModule,
+  IdentityModule,
+  TopoloClient,
+  TopoloAuthError,
+  TopoloHttpError,
+  TopoloPermissionError,
+} from './index.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+describe('createTopolo', () => {
+  it('returns a ready client plus identity + crm module surfaces', () => {
+    const topolo = createTopolo({
+      credential: { kind: 'access_token', accessToken: 'tok' },
+      agent: AGENT,
+      fetch: vi.fn() as unknown as typeof fetch,
+    });
+
+    expect(topolo.client).toBeInstanceOf(TopoloClient);
+    expect(topolo.identity).toBeInstanceOf(IdentityModule);
+    expect(topolo.crm).toBeInstanceOf(CrmModule);
+  });
+
+  it('wires every module to the same underlying client', async () => {
+    const calls: string[] = [];
+    const impl = vi.fn(async (url: string) => {
+      calls.push(String(url));
+      if (String(url).includes('/api/services/by-slug/')) {
+        return new Response(JSON.stringify({ success: true, data: { service_id: 'service_auth' } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      if (String(url).includes('/api/services/catalog')) {
+        return new Response(JSON.stringify({ data: { services: [] } }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        });
+      }
+      return new Response(
+        JSON.stringify({ data: { user: { id: 'u_1', email: 'a@b.c' } } }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }) as unknown as typeof fetch;
+
+    TopoloClient.clearServiceIdCache();
+    const topolo = createTopolo({
+      credential: { kind: 'access_token', accessToken: 'tok' },
+      agent: AGENT,
+      fetch: impl,
+      serviceIds: { auth: 'service_auth' },
+    });
+
+    const me = await topolo.identity.whoami();
+    expect(me.user.id).toBe('u_1');
+    expect(calls.some((u) => u.includes('/api/auth/me'))).toBe(true);
+  });
+});
+
+describe('package surface re-exports', () => {
+  it('re-exports the error classes from the barrel', () => {
+    expect(new TopoloAuthError('x').name).toBe('TopoloAuthError');
+    expect(new TopoloHttpError('auth', '/p', 500).name).toBe('TopoloHttpError');
+    expect(new TopoloPermissionError('nope', []).name).toBe('TopoloPermissionError');
+  });
+});

package/src/index.ts

@@ -5,6 +5,7 @@ export {
   type CredentialIntrospection,
   type TopoloDebugEvent,
   type TopoloServiceCatalogEntry,
+  type TopoloApiKeyResourceMetadata,
   type TopoloActionCatalogEntry,
 } from "./client.js";
 export type { TopoloCredential, AgentIdentity } from "./auth.js";

package/src/modules/crm.test.ts

@@ -0,0 +1,208 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from '../client.js';
+import { CrmModule } from './crm.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    if (String(url).includes('/api/services/by-slug/')) {
+      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_crm' } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(
+        JSON.stringify({
+          data: {
+            services: [
+              {
+                service_id: 'srv_crm',
+                app_slug: 'topolo-crm',
+                name: 'Topolo CRM',
+                api_base_url: 'https://crm.topolo.app',
+                launch_url: 'https://crm.topolo.app',
+                surface_kind: 'api',
+                status: 'active',
+                granted_permissions: ['srv_crm.contacts:read'],
+              },
+            ],
+          },
+        }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }
+    const next = responses.shift() ?? { status: 200, body: { data: {} } };
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
+  return calls.filter(
+    (call) =>
+      !call.url.includes('/api/services/by-slug/') &&
+      !call.url.includes('/api/services/catalog'),
+  );
+}
+
+function clientWith(impl: typeof fetch) {
+  return new TopoloClient({
+    credential: { kind: 'access_token', accessToken: 'tok_test' },
+    agent: AGENT,
+    fetch: impl,
+  });
+}
+
+beforeEach(() => {
+  TopoloClient.clearServiceIdCache();
+});
+
+describe('CrmModule.listContacts', () => {
+  it('maps snake_case rows into camelCase summaries and forwards query params', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          contacts: [
+            {
+              id: 'c_1',
+              first: 'Ada',
+              last: 'Lovelace',
+              email: 'ada@example.com',
+              phone: '+1',
+              company: 'Analytical',
+              lead_status: 'new',
+              lifecycle_stage: 'lead',
+              updated_at: '2026-01-01T00:00:00.000Z',
+            },
+          ],
+          total: 42,
+          page: 2,
+          pageSize: 25,
+        },
+      },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts({ q: 'ada', page: 2, pageSize: 25 });
+
+    expect(result.contacts).toEqual([
+      {
+        id: 'c_1',
+        firstName: 'Ada',
+        lastName: 'Lovelace',
+        email: 'ada@example.com',
+        phone: '+1',
+        company: 'Analytical',
+        leadStatus: 'new',
+        lifecycleStage: 'lead',
+        updatedAt: '2026-01-01T00:00:00.000Z',
+      },
+    ]);
+    expect(result.total).toBe(42);
+    expect(result.page).toBe(2);
+    expect(result.pageSize).toBe(25);
+
+    const url = new URL(requestCalls(calls)[0]!.url);
+    expect(url.pathname).toBe('/api/contacts');
+    expect(url.searchParams.get('q')).toBe('ada');
+    expect(url.searchParams.get('page')).toBe('2');
+    expect(url.searchParams.get('pageSize')).toBe('25');
+  });
+
+  it('reads rows from the data[] envelope and pagination block', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: [{ id: 'c_2' }],
+          pagination: { total: 7, page: 3, pageSize: 10 },
+        },
+      },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.contacts).toEqual([
+      {
+        id: 'c_2',
+        firstName: null,
+        lastName: null,
+        email: null,
+        phone: null,
+        company: null,
+        leadStatus: null,
+        lifecycleStage: null,
+        updatedAt: null,
+      },
+    ]);
+    expect(result.total).toBe(7);
+    expect(result.page).toBe(3);
+    expect(result.pageSize).toBe(10);
+  });
+
+  it('falls back to row count + option defaults when no metadata is returned', async () => {
+    const { impl } = stubFetch([{ body: { contacts: [{ id: 'c_3' }, { id: 'c_4' }] } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.total).toBe(2);
+    expect(result.page).toBe(1);
+    expect(result.pageSize).toBe(2);
+  });
+
+  it('returns an empty list when the response has neither contacts nor data arrays', async () => {
+    const { impl } = stubFetch([{ body: { unexpected: true } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const result = await crm.listContacts();
+
+    expect(result.contacts).toEqual([]);
+    expect(result.total).toBe(0);
+  });
+});
+
+describe('CrmModule.getContact', () => {
+  it('rejects an empty contactId', async () => {
+    const { impl } = stubFetch([]);
+    const crm = new CrmModule(clientWith(impl));
+    await expect(crm.getContact('')).rejects.toThrow('contactId is required');
+  });
+
+  it('unwraps a data-enveloped contact', async () => {
+    const { impl, calls } = stubFetch([
+      { body: { data: { id: 'c_9', first: 'Grace', last: 'Hopper' } } },
+    ]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const contact = await crm.getContact('c_9');
+
+    expect(contact).toMatchObject({ id: 'c_9', firstName: 'Grace', lastName: 'Hopper' });
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/contacts/c_9');
+  });
+
+  it('accepts a bare contact object (no data envelope)', async () => {
+    const { impl } = stubFetch([{ body: { id: 'c_10', email: 'g@example.com' } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    const contact = await crm.getContact('c_10');
+
+    expect(contact).toMatchObject({ id: 'c_10', email: 'g@example.com' });
+  });
+
+  it('url-encodes contact ids with special characters', async () => {
+    const { impl, calls } = stubFetch([{ body: { data: { id: 'a/b c' } } }]);
+    const crm = new CrmModule(clientWith(impl));
+
+    await crm.getContact('a/b c');
+
+    expect(requestCalls(calls)[0]!.url).toContain('/api/contacts/a%2Fb%20c');
+  });
+});

package/src/modules/identity.test.ts

@@ -0,0 +1,165 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { TopoloClient } from '../client.js';
+import { IdentityModule } from './identity.js';
+
+const AGENT = { clientName: 'topolo-sdk-test', clientVersion: '0.0.0' };
+
+function stubFetch(responses: Array<{ status?: number; body?: unknown }>) {
+  const calls: Array<{ url: string; init: RequestInit }> = [];
+  const impl = vi.fn(async (url: string, init: RequestInit) => {
+    calls.push({ url, init });
+    if (String(url).includes('/api/services/by-slug/')) {
+      return new Response(JSON.stringify({ success: true, data: { service_id: 'service_auth' } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    if (String(url).includes('/api/services/catalog')) {
+      return new Response(JSON.stringify({ data: { services: [] } }), {
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+      });
+    }
+    const next = responses.shift() ?? { status: 200, body: {} };
+    return new Response(JSON.stringify(next.body ?? {}), {
+      status: next.status ?? 200,
+      headers: { 'Content-Type': 'application/json' },
+    });
+  });
+  return { impl: impl as unknown as typeof fetch, calls };
+}
+
+function requestCalls(calls: Array<{ url: string; init: RequestInit }>) {
+  return calls.filter(
+    (call) =>
+      !call.url.includes('/api/services/by-slug/') &&
+      !call.url.includes('/api/services/catalog'),
+  );
+}
+
+function clientWith(
+  impl: typeof fetch,
+  credential: { kind: 'access_token'; accessToken: string } | { kind: 'api_key'; apiKey: string } = {
+    kind: 'access_token',
+    accessToken: 'tok_test',
+  },
+) {
+  return new TopoloClient({
+    credential,
+    agent: AGENT,
+    fetch: impl,
+    serviceIds: { auth: 'service_auth' },
+  });
+}
+
+beforeEach(() => {
+  TopoloClient.clearServiceIdCache();
+});
+
+describe('IdentityModule.whoami', () => {
+  it('resolves a data-enveloped access-token identity with an organization', async () => {
+    const { impl, calls } = stubFetch([
+      {
+        body: {
+          data: {
+            credentialType: 'access_token',
+            user: { id: 'u_1', email: 'ada@example.com', name: 'Ada', role: 'owner' },
+            organization: { id: 'org_1', slug: 'acme', name: 'Acme Inc' },
+            permissions: ['crm.contacts:read'],
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me).toEqual({
+      kind: 'access_token',
+      user: {
+        id: 'u_1',
+        email: 'ada@example.com',
+        name: 'Ada',
+        role: 'owner',
+        permissions: ['crm.contacts:read'],
+      },
+      organization: { id: 'org_1', slug: 'acme', name: 'Acme Inc' },
+    });
+    expect(new URL(requestCalls(calls)[0]!.url).pathname).toBe('/api/auth/me');
+  });
+
+  it('defaults api_key role to "service" and reads a bare (non-enveloped) payload', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          credentialType: 'api_key',
+          user: { id: 'svc_1', email: 'svc@example.com' },
+          organization: { id: 'org_2', slug: 'beta' },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(
+      clientWith(impl, { kind: 'api_key', apiKey: 'dak_xyz' }),
+    );
+
+    const me = await identity.whoami();
+
+    expect(me.kind).toBe('api_key');
+    expect(me.user.role).toBe('service');
+    expect(me.user.name).toBeNull();
+    // organization name falls back to slug when name is absent
+    expect(me.organization).toEqual({ id: 'org_2', slug: 'beta', name: 'beta' });
+  });
+
+  it('defaults access_token role to "member" and reads permissions from user when top-level absent', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: {
+            user: {
+              id: 'u_3',
+              email: 'm@example.com',
+              permissions: ['mail.messages:read'],
+            },
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.kind).toBe('access_token');
+    expect(me.user.role).toBe('member');
+    expect(me.user.permissions).toEqual(['mail.messages:read']);
+    expect(me.organization).toBeNull();
+  });
+
+  it('synthesizes an organization from user.orgId/orgSlug when no organization object is present', async () => {
+    const { impl } = stubFetch([
+      {
+        body: {
+          data: {
+            user: { id: 'u_4', email: 'o@example.com', orgId: 'org_9', orgSlug: 'gamma' },
+          },
+        },
+      },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.organization).toEqual({ id: 'org_9', slug: 'gamma', name: 'gamma' });
+  });
+
+  it('defaults missing permissions to an empty array', async () => {
+    const { impl } = stubFetch([
+      { body: { data: { user: { id: 'u_5', email: 'n@example.com' } } } },
+    ]);
+    const identity = new IdentityModule(clientWith(impl));
+
+    const me = await identity.whoami();
+
+    expect(me.user.permissions).toEqual([]);
+  });
+});