@topolo/sdk 0.4.6 → 0.4.7

package/dist/index.cjs

@@ -143,7 +143,7 @@ var SERVICES = {
   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",
@@ -1150,20 +1150,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"
@@ -1716,7 +1719,7 @@ var APPLICATIONS = {
 };
 
 // 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",
@@ -1860,11 +1863,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"
     ]
   },
@@ -3192,12 +3197,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`);
+    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`);
   }

package/dist/index.d.cts

@@ -264,7 +264,7 @@ declare const SERVICES: {
     readonly nexus: "https://nexus-api.topolo.app";
     readonly notify: "https://notify.topolo.app";
     readonly observability_watch: "https://observability-watch.topolo.app";
-    readonly one: "https://one.topolo.app";
+    readonly one: "https://www.topolo.app";
     readonly p2p: "https://p2p.topolo.app";
     readonly pay: "https://pay.topolo.app";
     readonly people: "https://people.topolo.app";
@@ -1018,16 +1018,16 @@ declare const APPLICATIONS: {
         readonly deployTargets: readonly [{
             readonly name: "topolo-one";
             readonly kind: "worker";
-            readonly apiUrl: null;
-            readonly domains: readonly [];
-            readonly routes: readonly [];
+            readonly apiUrl: "https://one.topolo.app";
+            readonly domains: readonly ["one.topolo.app"];
+            readonly routes: readonly ["one.topolo.app/*"];
             readonly serviceId: null;
         }, {
             readonly name: "topolo-one-api";
             readonly kind: "worker";
-            readonly apiUrl: "https://one.topolo.app";
-            readonly domains: readonly ["one.topolo.app"];
-            readonly routes: readonly ["one.topolo.app/*", "www.topolo.app/*"];
+            readonly apiUrl: "https://www.topolo.app";
+            readonly domains: readonly ["www.topolo.app"];
+            readonly routes: readonly ["www.topolo.app/*"];
             readonly serviceId: "one";
         }, {
             readonly name: "topolo-one-website";
@@ -1432,7 +1432,7 @@ type ApplicationId = keyof typeof APPLICATIONS;
 type ApplicationCatalogEntry = (typeof APPLICATIONS)[ApplicationId];
 type ApplicationDeployTarget = ApplicationCatalogEntry['deployTargets'][number];
 
-declare const APPLICATION_REQUIREMENTS_VERSION = "2026-05-01.1";
+declare const APPLICATION_REQUIREMENTS_VERSION = "2026-06-07.1";
 type ApplicationRequirementScope = 'all' | 'browser' | 'api' | 'tooling' | 'agent_surface';
 interface ApplicationRequirement {
     id: string;
@@ -1541,8 +1541,8 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly title: "Expose a native dashboard widget contract";
     readonly summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.";
     readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["The app-owned API exposes GET /api/widget", "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk", "The endpoint derives organization/user context from the app auth boundary"];
-    readonly implementation: readonly ["Import createTopoloWidgetResponse from @topolo/sdk in the app backend", "Return native app metrics or action widgets instead of generic launch-card fallbacks", "Add a route-level test that validates the response with validateTopoloWidgetResponse"];
+    readonly evidence: readonly ["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"];
+    readonly implementation: readonly ["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"];
 }, {
     readonly id: "observability-and-audit";
     readonly title: "Emit platform audit and debugging signals";
@@ -1971,7 +1971,7 @@ interface TopoloWidgetBase {
     serviceIcon?: string;
     type: TopoloWidgetType;
     lastUpdated: string;
-    snapshot?: TopoloWidgetSnapshotMetadata;
+    snapshot: TopoloWidgetSnapshotMetadata;
 }
 interface TopoloWidgetMetric {
     key?: string;
@@ -1995,7 +1995,7 @@ interface TopoloWidgetSnapshotMetadata {
     scope?: string;
     scopeLabel?: string;
     generatedAt?: string;
-    summary?: string;
+    summary: string;
     defaultMetricKeys?: string[];
     availableMetrics?: TopoloWidgetSnapshotMetric[];
     highlights?: string[];

package/dist/index.d.ts

@@ -264,7 +264,7 @@ declare const SERVICES: {
     readonly nexus: "https://nexus-api.topolo.app";
     readonly notify: "https://notify.topolo.app";
     readonly observability_watch: "https://observability-watch.topolo.app";
-    readonly one: "https://one.topolo.app";
+    readonly one: "https://www.topolo.app";
     readonly p2p: "https://p2p.topolo.app";
     readonly pay: "https://pay.topolo.app";
     readonly people: "https://people.topolo.app";
@@ -1018,16 +1018,16 @@ declare const APPLICATIONS: {
         readonly deployTargets: readonly [{
             readonly name: "topolo-one";
             readonly kind: "worker";
-            readonly apiUrl: null;
-            readonly domains: readonly [];
-            readonly routes: readonly [];
+            readonly apiUrl: "https://one.topolo.app";
+            readonly domains: readonly ["one.topolo.app"];
+            readonly routes: readonly ["one.topolo.app/*"];
             readonly serviceId: null;
         }, {
             readonly name: "topolo-one-api";
             readonly kind: "worker";
-            readonly apiUrl: "https://one.topolo.app";
-            readonly domains: readonly ["one.topolo.app"];
-            readonly routes: readonly ["one.topolo.app/*", "www.topolo.app/*"];
+            readonly apiUrl: "https://www.topolo.app";
+            readonly domains: readonly ["www.topolo.app"];
+            readonly routes: readonly ["www.topolo.app/*"];
             readonly serviceId: "one";
         }, {
             readonly name: "topolo-one-website";
@@ -1432,7 +1432,7 @@ type ApplicationId = keyof typeof APPLICATIONS;
 type ApplicationCatalogEntry = (typeof APPLICATIONS)[ApplicationId];
 type ApplicationDeployTarget = ApplicationCatalogEntry['deployTargets'][number];
 
-declare const APPLICATION_REQUIREMENTS_VERSION = "2026-05-01.1";
+declare const APPLICATION_REQUIREMENTS_VERSION = "2026-06-07.1";
 type ApplicationRequirementScope = 'all' | 'browser' | 'api' | 'tooling' | 'agent_surface';
 interface ApplicationRequirement {
     id: string;
@@ -1541,8 +1541,8 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly title: "Expose a native dashboard widget contract";
     readonly summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.";
     readonly appliesTo: readonly ["api"];
-    readonly evidence: readonly ["The app-owned API exposes GET /api/widget", "The endpoint returns TopoloWidgetApiResponse from @topolo/sdk", "The endpoint derives organization/user context from the app auth boundary"];
-    readonly implementation: readonly ["Import createTopoloWidgetResponse from @topolo/sdk in the app backend", "Return native app metrics or action widgets instead of generic launch-card fallbacks", "Add a route-level test that validates the response with validateTopoloWidgetResponse"];
+    readonly evidence: readonly ["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"];
+    readonly implementation: readonly ["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"];
 }, {
     readonly id: "observability-and-audit";
     readonly title: "Emit platform audit and debugging signals";
@@ -1971,7 +1971,7 @@ interface TopoloWidgetBase {
     serviceIcon?: string;
     type: TopoloWidgetType;
     lastUpdated: string;
-    snapshot?: TopoloWidgetSnapshotMetadata;
+    snapshot: TopoloWidgetSnapshotMetadata;
 }
 interface TopoloWidgetMetric {
     key?: string;
@@ -1995,7 +1995,7 @@ interface TopoloWidgetSnapshotMetadata {
     scope?: string;
     scopeLabel?: string;
     generatedAt?: string;
-    summary?: string;
+    summary: string;
     defaultMetricKeys?: string[];
     availableMetrics?: TopoloWidgetSnapshotMetric[];
     highlights?: string[];

package/dist/index.js

@@ -88,7 +88,7 @@ var SERVICES = {
   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",
@@ -1095,20 +1095,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"
@@ -1661,7 +1664,7 @@ var APPLICATIONS = {
 };
 
 // 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",
@@ -1805,11 +1808,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"
     ]
   },
@@ -3137,12 +3142,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`);
+    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`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "type": "module",
   "main": "./dist/index.js",

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'
@@ -218,11 +218,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

@@ -988,20 +988,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"

package/src/services.generated.ts

@@ -33,7 +33,7 @@ export const SERVICES = {
   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",

package/src/services.test.ts

@@ -71,7 +71,7 @@ describe('service registry', () => {
       consent: 'https://consent.topolo.app',
       feed: 'https://feed-api.topolo.app',
       mail: 'https://mail-api.topolo.app',
-      one: 'https://one.topolo.app',
+      one: 'https://www.topolo.app',
       web: 'https://web-api.topolo.app',
     });
     expect(DEFAULT_SERVICE_URLS).toMatchObject({

package/src/widgets.test.ts

@@ -21,6 +21,9 @@ describe("Topolo widget contract", () => {
       widgets: [
         {
           type: "stats",
+          snapshot: {
+            summary: "Bytes is reporting 12 files in the current workspace.",
+          },
           stats: [{ key: "files", label: "Files", value: 12 }],
         },
       ],
@@ -34,6 +37,9 @@ describe("Topolo widget contract", () => {
           serviceName: "Bytes",
           lastUpdated: "2026-04-25T00:00:00.000Z",
           type: "stats",
+          snapshot: {
+            summary: "Bytes is reporting 12 files in the current workspace.",
+          },
           stats: [{ key: "files", label: "Files", value: 12 }],
         },
       ],
@@ -51,6 +57,9 @@ describe("Topolo widget contract", () => {
           serviceName: "CRM",
           lastUpdated: "2026-04-24T23:00:00.000Z",
           type: "stats",
+          snapshot: {
+            summary: "CRM is tracking 3 contacts for this workspace.",
+          },
           stats: [{ label: "Contacts", value: 3 }],
         },
       ],
@@ -79,6 +88,9 @@ describe("Topolo widget contract", () => {
       widgets: [
         {
           type: "notifications",
+          snapshot: {
+            summary: "CRM has one unread lead notification for review.",
+          },
           unreadCount: 1,
           notifications: [
             {
@@ -100,7 +112,7 @@ describe("Topolo widget contract", () => {
     });
   });
 
-  it("keeps optional snapshot metadata for configurable TopoloOne datapoints", () => {
+  it("keeps required snapshot metadata for configurable TopoloOne datapoints", () => {
     const response = createTopoloWidgetResponse({
       serviceId: "service_admin",
       serviceName: "Admin",
@@ -111,6 +123,8 @@ describe("Topolo widget contract", () => {
           stats: [{ label: "Team Members", value: 5 }],
           snapshot: {
             presetKey: "admin_morning_snapshot",
+            summary:
+              "Admin has 5 team members visible in the current workspace snapshot.",
             defaultMetricKeys: ["team_members"],
             availableMetrics: [
               {
@@ -131,6 +145,8 @@ describe("Topolo widget contract", () => {
     });
     expect(response.widgets[0]).toMatchObject({
       snapshot: {
+        summary:
+          "Admin has 5 team members visible in the current workspace snapshot.",
         defaultMetricKeys: ["team_members"],
         availableMetrics: [
           { key: "team_members", label: "Team Members", value: 5 },
@@ -156,7 +172,29 @@ describe("Topolo widget contract", () => {
     expect(result.errors).toEqual([
       "widgets[0].serviceId must be a non-empty string",
       "widgets[0].lastUpdated must be a non-empty string",
+      "widgets[0].snapshot must be an object",
       "widgets[0].type must be a supported Topolo widget type",
     ]);
   });
+
+  it("reports missing snapshot summaries", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          serviceId: "service_bad",
+          serviceName: "Bad App",
+          lastUpdated: "2026-04-25T00:00:00.000Z",
+          type: "stats",
+          snapshot: { summary: "" },
+          stats: [],
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors).toEqual([
+      "widgets[0].snapshot.summary must be a non-empty string",
+    ]);
+  });
 });

package/src/widgets.ts

@@ -14,7 +14,7 @@ export interface TopoloWidgetBase {
   serviceIcon?: string;
   type: TopoloWidgetType;
   lastUpdated: string;
-  snapshot?: TopoloWidgetSnapshotMetadata;
+  snapshot: TopoloWidgetSnapshotMetadata;
 }
 
 export interface TopoloWidgetMetric {
@@ -41,7 +41,7 @@ export interface TopoloWidgetSnapshotMetadata {
   scope?: string;
   scopeLabel?: string;
   generatedAt?: string;
-  summary?: string;
+  summary: string;
   defaultMetricKeys?: string[];
   availableMetrics?: TopoloWidgetSnapshotMetric[];
   highlights?: string[];
@@ -291,12 +291,14 @@ function validateSnapshotMetadata(
   errors: string[],
 ) {
   if (snapshot === undefined) {
+    errors.push(`${path} must be an object`);
     return;
   }
   if (!isRecord(snapshot)) {
-    errors.push(`${path} must be an object when provided`);
+    errors.push(`${path} must be an object`);
     return;
   }
+  validateNonEmptyString(snapshot.summary, `${path}.summary`, errors);
   if (
     snapshot.defaultMetricKeys !== undefined &&
     !Array.isArray(snapshot.defaultMetricKeys)