@topolo/sdk 0.4.7 → 0.4.8

package/src/applications.generated.ts

@@ -49,17 +49,15 @@ export const APPLICATIONS = {
           "agent.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "agent"
       },
       {
         "name": "topolo-agent-api",
         "kind": "worker",
-        "apiUrl": "https://agent-api.topolo.app",
-        "domains": [
-          "agent-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "agent"
+        "serviceId": null
       }
     ]
   },
@@ -179,17 +177,15 @@ export const APPLICATIONS = {
           "bytes.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "bytes"
       },
       {
         "name": "topolo-bytes-api",
         "kind": "worker",
-        "apiUrl": "https://bytes-api.topolo.app",
-        "domains": [
-          "bytes-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "bytes"
+        "serviceId": null
       }
     ]
   },
@@ -288,12 +284,10 @@ export const APPLICATIONS = {
       {
         "name": "topolo-commerce-api",
         "kind": "worker",
-        "apiUrl": "https://commerce-api.topolo.app",
-        "domains": [
-          "commerce-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "commerce"
+        "serviceId": null
       },
       {
         "name": "topolo-commerce-guest-web",
@@ -313,7 +307,7 @@ export const APPLICATIONS = {
           "commerce.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "commerce"
       },
       {
         "name": "topolo-commerce-station-web",
@@ -400,12 +394,10 @@ export const APPLICATIONS = {
       {
         "name": "topolo-crm-api",
         "kind": "worker",
-        "apiUrl": "https://crm-api.topolo.app",
-        "domains": [
-          "crm-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "crm"
+        "serviceId": null
       },
       {
         "name": "topolo-crm-app",
@@ -415,7 +407,7 @@ export const APPLICATIONS = {
           "crm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "crm"
       }
     ]
   },
@@ -538,12 +530,10 @@ export const APPLICATIONS = {
       {
         "name": "topolo-feed-api",
         "kind": "worker",
-        "apiUrl": "https://feed-api.topolo.app",
-        "domains": [
-          "feed-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "feed"
+        "serviceId": null
       },
       {
         "name": "topolo-feed-web",
@@ -553,7 +543,7 @@ export const APPLICATIONS = {
           "feed.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "feed"
       }
     ]
   },
@@ -605,17 +595,15 @@ export const APPLICATIONS = {
           "forecast.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "forecast"
       },
       {
         "name": "topolo-forecast-api",
         "kind": "worker",
-        "apiUrl": "https://forecast-api.topolo.app",
-        "domains": [
-          "forecast-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "forecast"
+        "serviceId": null
       }
     ]
   },
@@ -757,17 +745,15 @@ export const APPLICATIONS = {
           "learn.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "learn"
       },
       {
         "name": "topolo-learn-api",
         "kind": "worker",
-        "apiUrl": "https://learn-api.topolo.app",
-        "domains": [
-          "learn-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "learn"
+        "serviceId": null
       }
     ]
   },
@@ -813,17 +799,15 @@ export const APPLICATIONS = {
           "mail.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mail"
       },
       {
         "name": "topolo-mail-api",
         "kind": "worker",
-        "apiUrl": "https://mail-api.topolo.app",
-        "domains": [
-          "mail-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "mail"
+        "serviceId": null
       }
     ]
   },
@@ -840,12 +824,10 @@ export const APPLICATIONS = {
       {
         "name": "topolo-mdm-api",
         "kind": "worker",
-        "apiUrl": "https://mdm-api.topolo.app",
-        "domains": [
-          "mdm-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "mdm"
+        "serviceId": null
       },
       {
         "name": "topolo-mdm-console",
@@ -855,7 +837,7 @@ export const APPLICATIONS = {
           "mdm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mdm"
       }
     ]
   },
@@ -1114,36 +1096,6 @@ export const APPLICATIONS = {
       }
     ]
   },
-  "pulse": {
-    "id": "pulse",
-    "appDir": "TopoloPulse",
-    "name": "topolo-pulse",
-    "packageName": "topolo-pulse",
-    "productionUrl": "https://pulse.topolo.app",
-    "services": [
-      "pulse"
-    ],
-    "deployTargets": [
-      {
-        "name": "topolo-pulse",
-        "kind": "worker",
-        "apiUrl": "https://pulse.topolo.app",
-        "domains": [
-          "pulse.topolo.app"
-        ],
-        "routes": [],
-        "serviceId": "pulse"
-      },
-      {
-        "name": "topolo-pulse-api",
-        "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
-        "serviceId": null
-      }
-    ]
-  },
   "quro": {
     "id": "quro",
     "appDir": "TopoloQuro",
@@ -1209,17 +1161,15 @@ export const APPLICATIONS = {
           "roadmapper.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "roadmapper"
       },
       {
         "name": "topolo-roadmapper-api",
         "kind": "worker",
-        "apiUrl": "https://roadmapper-api.topolo.app",
-        "domains": [
-          "roadmapper-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "roadmapper"
+        "serviceId": null
       }
     ]
   },
@@ -1271,17 +1221,15 @@ export const APPLICATIONS = {
           "studio.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "social_studio"
       },
       {
         "name": "topolo-social-studio-api",
         "kind": "worker",
-        "apiUrl": "https://studio-api.topolo.app",
-        "domains": [
-          "studio-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "social_studio"
+        "serviceId": null
       },
       {
         "name": "topolo-social-studio-queue",
@@ -1311,17 +1259,15 @@ export const APPLICATIONS = {
           "socialize.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "socialize"
       },
       {
         "name": "topolo-socialize-api",
         "kind": "worker",
-        "apiUrl": "https://socialize-api.topolo.app",
-        "domains": [
-          "socialize-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "socialize"
+        "serviceId": null
       },
       {
         "name": "topolo-socialize-scheduler",
@@ -1522,12 +1468,10 @@ export const APPLICATIONS = {
       {
         "name": "topolo-web-api",
         "kind": "worker",
-        "apiUrl": "https://web-api.topolo.app",
-        "domains": [
-          "web-api.topolo.app"
-        ],
+        "apiUrl": null,
+        "domains": [],
         "routes": [],
-        "serviceId": "web"
+        "serviceId": null
       },
       {
         "name": "topolo-web-runtime",
@@ -1550,7 +1494,7 @@ export const APPLICATIONS = {
           "web.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "web"
       }
     ]
   }

package/src/client.test.ts

@@ -143,6 +143,40 @@ describe('TopoloClient.request', () => {
     expect(headers.get('Authorization')).toBeNull();
   });
 
+  it('adds canonical resource headers for resource-scoped API keys', async () => {
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({
+      service: 'mail',
+      path: '/api/mail/mailboxes/mbx_1/messages',
+      resource: { resourceType: 'mailbox', resourceId: 'mbx_1' },
+    });
+    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
+    expect(headers.get('X-Topolo-Resource-Type')).toBe('mailbox');
+    expect(headers.get('X-Topolo-Resource-ID')).toBe('mbx_1');
+  });
+
+  it('passes arbitrary cataloged workspace aliases through resource headers', async () => {
+    const { impl, calls } = stubFetch([MAIL_CATALOG, { body: { ok: true } }]);
+    const client = new TopoloClient({
+      credential: { kind: 'api_key', apiKey: 'dak_xyz' },
+      agent: AGENT,
+      fetch: impl,
+    });
+    await client.request({
+      service: 'mail',
+      path: '/api/example',
+      resource: { resourceType: 'studio_portfolio', resourceId: 'portfolio_1' },
+    });
+    const headers = new Headers(requestCalls(calls)[0]!.init.headers);
+    expect(headers.get('X-Topolo-Resource-Type')).toBe('studio_portfolio');
+    expect(headers.get('X-Topolo-Resource-ID')).toBe('portfolio_1');
+  });
+
   it('refuses mutating requests without confirm', async () => {
     const { impl } = stubFetch([]);
     const client = new TopoloClient({
@@ -458,6 +492,26 @@ describe('TopoloClient.listServices', () => {
                 status: 'active',
                 surface_kind: 'application',
                 launchable: true,
+                api_key_resource: {
+                  resourceType: 'brand',
+                  label: 'Brands',
+                  emptyLabel: 'All brands in the organization',
+                  resourceConcept: 'workspace',
+                  canonicalResourceType: 'workspace',
+                  defaultEntitlement: 'enterprise',
+                  exceptionPolicy: 'app_or_organization',
+                },
+                api_key_resources: [
+                  {
+                    resourceType: 'brand',
+                    label: 'Brands',
+                    emptyLabel: 'All brands in the organization',
+                    resourceConcept: 'workspace',
+                    canonicalResourceType: 'workspace',
+                    defaultEntitlement: 'enterprise',
+                    exceptionPolicy: 'app_or_organization',
+                  },
+                ],
                 granted_permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
               },
             ],
@@ -483,6 +537,26 @@ describe('TopoloClient.listServices', () => {
         status: 'active',
         surfaceKind: 'application',
         launchable: true,
+        apiKeyResource: {
+          resourceType: 'brand',
+          label: 'Brands',
+          emptyLabel: 'All brands in the organization',
+          resourceConcept: 'workspace',
+          canonicalResourceType: 'workspace',
+          defaultEntitlement: 'enterprise',
+          exceptionPolicy: 'app_or_organization',
+        },
+        apiKeyResources: [
+          {
+            resourceType: 'brand',
+            label: 'Brands',
+            emptyLabel: 'All brands in the organization',
+            resourceConcept: 'workspace',
+            canonicalResourceType: 'workspace',
+            defaultEntitlement: 'enterprise',
+            exceptionPolicy: 'app_or_organization',
+          },
+        ],
         permissions: ['srv_wRCnLLbtvmVT.dashboard:read'],
       },
     ]);

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);
@@ -447,6 +478,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 +513,8 @@ export class TopoloClient {
           typeof s.surface_kind === 'string' ? s.surface_kind : null,
         launchable: s.launchable === true,
         permissions,
+        apiKeyResource,
+        apiKeyResources,
       });
     }
     this.serviceCatalogCache = {
@@ -577,6 +622,8 @@ export class TopoloClient {
       surfaceKind: 'application',
       launchable: Boolean(app.productionUrl),
       permissions: [],
+      apiKeyResource: null,
+      apiKeyResources: [],
     }));
   }
 
@@ -640,6 +687,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>,

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";