@topolo/sdk 0.4.6 → 0.4.8

package/src/application-requirements.ts

@@ -4,7 +4,7 @@ import {
   type ApplicationId,
 } from './applications.generated.js';
 
-export const APPLICATION_REQUIREMENTS_VERSION = '2026-05-01.1';
+export const APPLICATION_REQUIREMENTS_VERSION = '2026-06-07.1';
 
 export type ApplicationRequirementScope =
   | 'all'
@@ -125,16 +125,20 @@ export const APPLICATION_REQUIREMENTS = [
       'Browser applications should feel like one platform and should not create isolated navigation or account surfaces.',
     appliesTo: ['browser'],
     evidence: [
-      '@topolo/ui-kit is used for the platform shell where the app has authenticated UI',
-      'The shared launcher/app switcher is reachable from authenticated app chrome',
-      'Account menu and sign-out behavior use TopoloAppShell or TopoloAccountMenu',
+      '@topolo-io/app-shell is used for the platform shell where the app has authenticated UI',
+      '@topolo-io/app-launcher keeps the shared launcher/app switcher reachable from authenticated app chrome',
+      'Account menu and sign-out behavior use TopoloAppShell or the ui-kit TopoloAccountMenu primitive',
+      'Repeated app body surfaces use shared TopoloAppLayout primitives instead of local stat cards, empty states, or status badges',
+      'Local preview supports deterministic visual QA fixtures for overview, list, detail, settings, and empty/loading states',
       'Authenticated app body content stays inside the viewport on mobile and desktop widths',
     ],
     implementation: [
-      'Use TopoloAppShell for authenticated app layouts',
-      'Use TopoloAccountMenu when a partial-shell surface still needs account chrome',
+      'Use @topolo-io/app-shell TopoloAppShell for authenticated app layouts',
+      'Use the @topolo-io/ui-kit TopoloAccountMenu primitive when a partial-shell surface still needs account chrome',
       'Pass app-specific account actions as additive menu items instead of forking dropdowns',
       'Use shared design tokens and platform UI primitives before creating local equivalents',
+      'Use TopoloAppMetricCard, TopoloAppEmptyState, TopoloAppStatusBadge, TopoloAppGrid, and TopoloAppSection for repeated app body patterns',
+      'Keep visual QA fixtures available through visualQa=1 or __devpreview=1 so screenshot checks do not depend on live API state',
       'Keep mobile and desktop shell behavior aligned with the platform UI kit',
       'Constrain app-owned workspace wrappers with min-width: 0, width: auto, and viewport-aware max-width so shell padding cannot create page-level horizontal overflow',
     ],
@@ -218,11 +222,13 @@ export const APPLICATION_REQUIREMENTS = [
     evidence: [
       'The app-owned API exposes GET /api/widget',
       'The endpoint returns TopoloWidgetApiResponse from @topolo/sdk',
+      'Every returned widget includes snapshot.summary with app-owned operational prose',
       'The endpoint derives organization/user context from the app auth boundary',
     ],
     implementation: [
       'Import createTopoloWidgetResponse from @topolo/sdk in the app backend',
       'Return native app metrics or action widgets instead of generic launch-card fallbacks',
+      'Populate snapshot.summary in the producing app for every widget instead of synthesizing summaries in TopoloOne',
       'Add a route-level test that validates the response with validateTopoloWidgetResponse',
     ],
   },

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"
       }
     ]
   },
@@ -988,20 +970,23 @@ export const APPLICATIONS = {
       {
         "name": "topolo-one",
         "kind": "worker",
-        "apiUrl": null,
-        "domains": [],
-        "routes": [],
+        "apiUrl": "https://one.topolo.app",
+        "domains": [
+          "one.topolo.app"
+        ],
+        "routes": [
+          "one.topolo.app/*"
+        ],
         "serviceId": null
       },
       {
         "name": "topolo-one-api",
         "kind": "worker",
-        "apiUrl": "https://one.topolo.app",
+        "apiUrl": "https://www.topolo.app",
         "domains": [
-          "one.topolo.app"
+          "www.topolo.app"
         ],
         "routes": [
-          "one.topolo.app/*",
           "www.topolo.app/*"
         ],
         "serviceId": "one"
@@ -1111,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",
@@ -1206,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
       }
     ]
   },
@@ -1268,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",
@@ -1308,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",
@@ -1519,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",
@@ -1547,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>,