@topolo/sdk 0.11.11 → 0.13.0

package/README.md

@@ -148,26 +148,78 @@ any additional fields required by a declared URL-session completion action.
 
 ## Native dashboard widgets
 
-Launchable first-party applications populate the TopoloOne live workspace through
-their own `GET /api/widget` endpoint. The SDK owns the shared payload contract:
+Every marketplace application populates Topolo One through its own
+`GET /api/widget` endpoint. The SDK owns the complete, versioned payload
+contract; Topolo One never assumes how many applications or widgets a
+credential can discover.
 
 ```ts
-import { createTopoloWidgetResponse } from '@topolo/sdk';
+import {
+  createTopoloWidgetResponse,
+  defineTopoloStatsWidget,
+} from '@topolo/sdk';
 
 return Response.json(createTopoloWidgetResponse({
   appId: '<runtime-app-id>',
-  appName: 'Example',
+  serviceName: 'Example',
   widgets: [
-    {
-      type: 'stats',
-      stats: [{ label: 'Open items', value: 3 }],
-    },
+    defineTopoloStatsWidget({
+      id: 'example.open-items',
+      version: '1.0.0',
+      appId: '<runtime-app-id>',
+      serviceName: 'Example',
+      lastUpdated: new Date().toISOString(),
+      presentation: {
+        title: 'Open items',
+        contexts: ['workspace'],
+        supportedSizes: ['compact', 'medium'],
+        defaultSize: 'compact',
+      },
+      resource: {
+        resourceType: 'workspace',
+        requiredPermissions: ['app_example.items:read'],
+      },
+      state: { status: 'ready', observedAt: new Date().toISOString() },
+      refresh: {
+        intervalSeconds: 60,
+        timeoutSeconds: 5,
+        maxAgeSeconds: 60,
+        staleWhileRevalidateSeconds: 300,
+      },
+      configuration: {
+        allowMultipleInstances: true,
+        fields: [],
+        defaults: {},
+      },
+      drilldowns: [],
+      controls: [],
+      localization: { locale: 'en', titleKey: 'widgets.openItems.title' },
+      accessibility: { label: 'Open items' },
+      metrics: [{
+        key: 'open_items',
+        label: 'Open items',
+        value: 3,
+        unit: 'count',
+        semantic: 'gauge',
+        aggregation: 'last',
+        period: {
+          start: '2026-08-29T00:00:00.000Z',
+          end: '2026-08-30T00:00:00.000Z',
+          timezone: 'UTC',
+        },
+        dimensions: [],
+      }],
+    }),
   ],
 }));
 ```
 
-Use `validateTopoloWidgetResponse()` in endpoint tests to prevent app-local
-payload drift.
+Successful responses must contain at least one complete widget. Represent
+legitimate no-data with the widget's explicit `empty` state; an empty widget
+array is a conformance failure. Actions use published `actionId` bindings with
+their confirmation, effects, verification, and recovery contract. Use
+`validateTopoloWidgetResponse()` in endpoint and marketplace conformance tests
+to prevent app-local payload drift.
 
 ## Escape hatch