@topolo/sdk 0.4.6 → 0.4.8

package/dist/index.cjs

@@ -113,54 +113,53 @@ var TopoloHttpError = class extends TopoloSdkError {
 
 // src/services.generated.ts
 var SERVICES = {
-  agent: "https://agent-api.topolo.app",
+  agent: "https://agent.topolo.app",
   auth: "https://auth.topolo.app",
   backup: "https://backup.topolo.app",
   books: "https://books.topolo.app",
   bugfix: "https://bugfix.topolo.app",
-  bytes: "https://bytes-api.topolo.app",
+  bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
-  commerce: "https://commerce-api.topolo.app",
+  commerce: "https://commerce.topolo.app",
   compose: "https://compose.topolo.app",
   consent: "https://consent.topolo.app",
-  crm: "https://crm-api.topolo.app",
+  crm: "https://crm.topolo.app",
   developers: "https://developers.topolo.app",
   director: "https://director.topolo.app",
-  feed: "https://feed-api.topolo.app",
+  feed: "https://feed.topolo.app",
   flow: "https://flow.topolo.app",
-  forecast: "https://forecast-api.topolo.app",
+  forecast: "https://forecast.topolo.app",
   forms: "https://forms.topolo.app",
   home: "https://home.topolo.app",
   insights: "https://insights.topolo.app",
   inventory: "https://inventory.topolo.app",
-  learn: "https://learn-api.topolo.app",
+  learn: "https://learn.topolo.app",
   localize: "https://localize.topolo.app",
-  mail: "https://mail-api.topolo.app",
-  mdm: "https://mdm-api.topolo.app",
+  mail: "https://mail.topolo.app",
+  mdm: "https://mdm.topolo.app",
   messages: "https://messages.topolo.app",
   nexus: "https://nexus-api.topolo.app",
   notify: "https://notify.topolo.app",
   observability_watch: "https://observability-watch.topolo.app",
-  one: "https://one.topolo.app",
+  one: "https://www.topolo.app",
   p2p: "https://p2p.topolo.app",
   pay: "https://pay.topolo.app",
   people: "https://people.topolo.app",
-  pulse: "https://pulse.topolo.app",
   "quro.api": "https://api.ol0.me",
   "quro.redirect": "https://ol0.me",
-  roadmapper: "https://roadmapper-api.topolo.app",
+  roadmapper: "https://roadmapper.topolo.app",
   sign: "https://sign.topolo.app",
-  social_studio: "https://studio-api.topolo.app",
-  socialize: "https://socialize-api.topolo.app",
+  social_studio: "https://studio.topolo.app",
+  socialize: "https://socialize.topolo.app",
   spaces: "https://spaces.topolo.app",
   status: "https://status.topolo.app",
   success: "https://success.topolo.app",
   support: "https://support.topolo.app",
   survey: "https://survey.topolo.app",
   voice: "https://voice.topolo.app",
-  web: "https://web-api.topolo.app"
+  web: "https://web.topolo.app"
 };
 
 // src/applications.generated.ts
@@ -211,17 +210,15 @@ var 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
       }
     ]
   },
@@ -341,17 +338,15 @@ var 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
       }
     ]
   },
@@ -450,12 +445,10 @@ var 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",
@@ -475,7 +468,7 @@ var APPLICATIONS = {
           "commerce.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "commerce"
       },
       {
         "name": "topolo-commerce-station-web",
@@ -562,12 +555,10 @@ var 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",
@@ -577,7 +568,7 @@ var APPLICATIONS = {
           "crm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "crm"
       }
     ]
   },
@@ -700,12 +691,10 @@ var 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",
@@ -715,7 +704,7 @@ var APPLICATIONS = {
           "feed.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "feed"
       }
     ]
   },
@@ -767,17 +756,15 @@ var 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
       }
     ]
   },
@@ -919,17 +906,15 @@ var 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
       }
     ]
   },
@@ -975,17 +960,15 @@ var 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
       }
     ]
   },
@@ -1002,12 +985,10 @@ var 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",
@@ -1017,7 +998,7 @@ var APPLICATIONS = {
           "mdm.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "mdm"
       }
     ]
   },
@@ -1150,20 +1131,23 @@ var 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"
@@ -1273,36 +1257,6 @@ var 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",
@@ -1368,17 +1322,15 @@ var 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
       }
     ]
   },
@@ -1430,17 +1382,15 @@ var 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",
@@ -1470,17 +1420,15 @@ var 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",
@@ -1681,12 +1629,10 @@ var 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",
@@ -1709,14 +1655,14 @@ var APPLICATIONS = {
           "web.topolo.app"
         ],
         "routes": [],
-        "serviceId": null
+        "serviceId": "web"
       }
     ]
   }
 };
 
 // src/application-requirements.ts
-var APPLICATION_REQUIREMENTS_VERSION = "2026-05-01.1";
+var APPLICATION_REQUIREMENTS_VERSION = "2026-06-07.1";
 var APPLICATION_REQUIREMENTS = [
   {
     id: "platform-metadata",
@@ -1772,16 +1718,20 @@ var APPLICATION_REQUIREMENTS = [
     summary: "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"
     ]
@@ -1860,11 +1810,13 @@ var 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"
     ]
   },
@@ -2161,6 +2113,8 @@ function firstString(...values) {
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
+var TOPOLO_RESOURCE_TYPE_HEADER = "X-Topolo-Resource-Type";
+var TOPOLO_RESOURCE_ID_HEADER = "X-Topolo-Resource-ID";
 var POSITIVE_CACHE_TTL_MS = 5 * 60 * 1e3;
 var NEGATIVE_CACHE_TTL_MS = 60 * 1e3;
 var CATALOG_CACHE_TTL_MS = 60 * 1e3;
@@ -2239,6 +2193,18 @@ var TopoloClient = 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);
     const signal = opts.signal ? mergeSignals(opts.signal, controller.signal) : controller.signal;
@@ -2421,6 +2387,11 @@ var TopoloClient = class _TopoloClient {
       const serviceId = typeof s.service_id === "string" ? s.service_id : typeof s.id === "string" ? s.id : null;
       if (!serviceId) continue;
       const permissions = Array.isArray(s.granted_permissions) ? s.granted_permissions.filter((permission) => 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,
@@ -2431,7 +2402,9 @@ var TopoloClient = class _TopoloClient {
         status: typeof s.status === "string" ? s.status : null,
         surfaceKind: typeof s.surface_kind === "string" ? s.surface_kind : null,
         launchable: s.launchable === true,
-        permissions
+        permissions,
+        apiKeyResource,
+        apiKeyResources
       });
     }
     this.serviceCatalogCache = {
@@ -2517,7 +2490,9 @@ var TopoloClient = class _TopoloClient {
       status: "bundled",
       surfaceKind: "application",
       launchable: Boolean(app.productionUrl),
-      permissions: []
+      permissions: [],
+      apiKeyResource: null,
+      apiKeyResources: []
     }));
   }
   /**
@@ -2566,6 +2541,46 @@ function resolveConfiguredServiceId(slug, serviceIds) {
   }
   return null;
 }
+function normalizeApiKeyResourceMetadata(input) {
+  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) {
+  if (!Array.isArray(input)) return [];
+  const resources = [];
+  const seenTypes = /* @__PURE__ */ new Set();
+  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) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
   for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = serviceUrls?.[serviceKey];
@@ -3133,7 +3148,7 @@ function createTopoloWidgetError(error) {
 }
 function validateTopoloWidgetResponse(response) {
   const errors = [];
-  if (!isRecord(response)) {
+  if (!isRecord2(response)) {
     return { ok: false, errors: ["response must be an object"] };
   }
   if (typeof response.success !== "boolean") {
@@ -3152,7 +3167,7 @@ function validateTopoloWidgetResponse(response) {
   return { ok: errors.length === 0, errors };
 }
 function validateWidget(widget, path, errors) {
-  if (!isRecord(widget)) {
+  if (!isRecord2(widget)) {
     errors.push(`${path} must be an object`);
     return;
   }
@@ -3179,7 +3194,7 @@ function validateWidget(widget, path, errors) {
     case "chart":
       validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
       validateNonEmptyString(widget.title, `${path}.title`, errors);
-      if (!isRecord(widget.data)) {
+      if (!isRecord2(widget.data)) {
         errors.push(`${path}.data must be an object`);
       } else {
         validateArray(widget.data.labels, `${path}.data.labels`, errors);
@@ -3192,12 +3207,14 @@ function validateWidget(widget, path, errors) {
 }
 function validateSnapshotMetadata(snapshot, path, errors) {
   if (snapshot === void 0) {
+    errors.push(`${path} must be an object`);
     return;
   }
-  if (!isRecord(snapshot)) {
-    errors.push(`${path} must be an object when provided`);
+  if (!isRecord2(snapshot)) {
+    errors.push(`${path} must be an object`);
     return;
   }
+  validateNonEmptyString(snapshot.summary, `${path}.summary`, errors);
   if (snapshot.defaultMetricKeys !== void 0 && !Array.isArray(snapshot.defaultMetricKeys)) {
     errors.push(`${path}.defaultMetricKeys must be an array when provided`);
   }
@@ -3213,7 +3230,7 @@ function validateSnapshotMetadata(snapshot, path, errors) {
   }
   snapshot.availableMetrics.forEach((metric, index) => {
     const metricPath = `${path}.availableMetrics[${index}]`;
-    if (!isRecord(metric)) {
+    if (!isRecord2(metric)) {
       errors.push(`${metricPath} must be an object`);
       return;
     }
@@ -3234,7 +3251,7 @@ function validateArray(value, path, errors) {
     errors.push(`${path} must be an array`);
   }
 }
-function isRecord(value) {
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function toIsoTimestamp(input) {