@topolo/sdk 0.2.5 → 0.2.7

package/README.md

@@ -94,6 +94,29 @@ that contract into catalog-backed conformance reports and migration-queue items.
 Catalog-visible evidence is marked directly; implementation details that require
 code or docs inspection are deliberately marked `needs_review`.
 
+## 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:
+
+```ts
+import { createTopoloWidgetResponse } from '@topolo/sdk';
+
+return Response.json(createTopoloWidgetResponse({
+  serviceId: 'srv_topolo_example',
+  serviceName: 'Example',
+  widgets: [
+    {
+      type: 'stats',
+      stats: [{ label: 'Open items', value: 3 }],
+    },
+  ],
+}));
+```
+
+Use `validateTopoloWidgetResponse()` in endpoint tests to prevent app-local
+payload drift.
+
 ## Escape hatch
 
 ```ts

package/dist/index.cjs

@@ -27,6 +27,8 @@ __export(index_exports, {
   DEFAULT_SERVICE_URLS: () => DEFAULT_SERVICE_URLS,
   IdentityModule: () => IdentityModule,
   PLATFORM_SERVICE_IDS: () => PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS: () => TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError: () => TopoloAuthError,
   TopoloClient: () => TopoloClient,
   TopoloHttpError: () => TopoloHttpError,
@@ -37,8 +39,16 @@ __export(index_exports, {
   auditAllApplicationRequirements: () => auditAllApplicationRequirements,
   auditApplicationRequirements: () => auditApplicationRequirements,
   createTopolo: () => createTopolo,
+  createTopoloWidgetError: () => createTopoloWidgetError,
+  createTopoloWidgetResponse: () => createTopoloWidgetResponse,
+  defineTopoloChartWidget: () => defineTopoloChartWidget,
+  defineTopoloNotificationsWidget: () => defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget: () => defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget: () => defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   requirementsForApplication: () => requirementsForApplication,
-  resolveServiceUrl: () => resolveServiceUrl
+  resolveServiceUrl: () => resolveServiceUrl,
+  validateTopoloWidgetResponse: () => validateTopoloWidgetResponse
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -108,8 +118,10 @@ var SERVICES = {
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://r2-media-manager-worker.topolo.workers.dev",
   calendar: "https://calendar.topolo.app",
+  capacity: "https://topolo-capacity.topolo.workers.dev",
   chat: "https://chat.topolo.app",
   commerce: "https://topolo-commerce-api.topolo.workers.dev",
+  compose: "https://compose.topolo.app",
   crm: "https://crm-api.topolo.app",
   customer_success: "https://customer-success.topolo.app",
   feed: "https://topolo-feed-api.topolo.app",
@@ -123,6 +135,7 @@ var SERVICES = {
   mdm: "https://topolo-mdm-api.topolo.app",
   messaging: "https://messages.topolo.app",
   nexus: "https://topolo-nexus-gateway.topolo.workers.dev",
+  notify: "https://notify.topolo.app",
   one: "https://one.topolo.app",
   pay: "https://topolo-pay.topolo.workers.dev",
   people: "https://people.topolo.app",
@@ -139,12 +152,14 @@ var SERVICES = {
 };
 var PLATFORM_SERVICE_IDS = {
   books: "srv_topolo_books",
+  compose: "srv_topolo_compose",
   crm: "srv_iCwM4jGXcwlj",
   customer_success: "srv_topolo_customer_success",
   flow: "srv_topolo_flow",
   forms: "srv_topolo_forms",
   insights: "srv_topolo_insights",
   inventory: "srv_topolo_inventory",
+  notify: "svc_topolo_notify",
   people: "srv_topolo_people",
   sign: "srv_topolo_sign",
   survey: "srv_topolo_survey",
@@ -323,6 +338,29 @@ var APPLICATIONS = {
       }
     ]
   },
+  "capacity": {
+    "id": "capacity",
+    "appDir": "TopoloCapacity",
+    "name": "topolo-capacity",
+    "packageName": "topolo-capacity",
+    "productionUrl": "https://capacity.topolo.app",
+    "services": [
+      "capacity"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-capacity",
+        "kind": "worker",
+        "apiUrl": "https://topolo-capacity.topolo.workers.dev",
+        "domains": [
+          "capacity.topolo.app",
+          "topolo-capacity.topolo.workers.dev"
+        ],
+        "routes": [],
+        "serviceId": "capacity"
+      }
+    ]
+  },
   "chat": {
     "id": "chat",
     "appDir": "TopoloChat",
@@ -420,6 +458,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "compose": {
+    "id": "compose",
+    "appDir": "TopoloCompose",
+    "name": "topolo-compose",
+    "packageName": "@topolo/compose",
+    "productionUrl": "https://compose.topolo.app",
+    "services": [
+      "compose"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-compose",
+        "kind": "worker",
+        "apiUrl": "https://compose.topolo.app",
+        "domains": [
+          "compose.topolo.app"
+        ],
+        "routes": [
+          "compose.topolo.app"
+        ],
+        "serviceId": "compose"
+      }
+    ]
+  },
   "crm": {
     "id": "crm",
     "appDir": "TopoloCRM",
@@ -837,6 +899,30 @@ var APPLICATIONS = {
       }
     ]
   },
+  "notify": {
+    "id": "notify",
+    "appDir": "TopoloNotify",
+    "name": "topolo-notify",
+    "packageName": "@topolo/notify",
+    "productionUrl": "https://notify.topolo.app",
+    "services": [
+      "notify"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-notify",
+        "kind": "worker",
+        "apiUrl": "https://notify.topolo.app",
+        "domains": [
+          "notify.topolo.app"
+        ],
+        "routes": [
+          "notify.topolo.app"
+        ],
+        "serviceId": "notify"
+      }
+    ]
+  },
   "one": {
     "id": "one",
     "appDir": "TopoloOne",
@@ -1219,7 +1305,7 @@ var APPLICATIONS = {
 };
 
 // src/application-requirements.ts
-var APPLICATION_REQUIREMENTS_VERSION = "2026-04-22.1";
+var APPLICATION_REQUIREMENTS_VERSION = "2026-04-25.1";
 var APPLICATION_REQUIREMENTS = [
   {
     id: "platform-metadata",
@@ -1351,6 +1437,22 @@ var APPLICATION_REQUIREMENTS = [
       "Keep command output JSON-stable for agents and human-readable with --no-json"
     ]
   },
+  {
+    id: "native-dashboard-widget",
+    title: "Expose a native dashboard widget contract",
+    summary: "Launchable first-party applications must populate TopoloOne live workspace through an app-owned /api/widget endpoint using the SDK widget response contract.",
+    appliesTo: ["api"],
+    evidence: [
+      "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"
+    ],
+    implementation: [
+      "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"
+    ]
+  },
   {
     id: "observability-and-audit",
     title: "Emit platform audit and debugging signals",
@@ -1522,6 +1624,13 @@ function evaluateRequirement(application, requirement) {
       }
       return finding(requirement, "missing", "No SDK service or tooling surface is registered.", evidence);
     }
+    case "native-dashboard-widget":
+      return finding(
+        requirement,
+        "needs_review",
+        "Catalog metadata cannot verify app-owned /api/widget implementation details.",
+        evidence
+      );
     case "observability-and-audit":
       return finding(
         requirement,
@@ -1920,6 +2029,161 @@ var TopoloOAuth = class {
   }
 };
 
+// src/widgets.ts
+var TOPOLO_WIDGET_ENDPOINT = "/api/widget";
+var TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 6e4;
+function defineTopoloStatsWidget(widget) {
+  return { ...widget, type: "stats" };
+}
+function defineTopoloRecentActivityWidget(widget) {
+  return { ...widget, type: "recent-activity" };
+}
+function defineTopoloQuickActionsWidget(widget) {
+  return { ...widget, type: "quick-actions" };
+}
+function defineTopoloNotificationsWidget(widget) {
+  return { ...widget, type: "notifications" };
+}
+function defineTopoloChartWidget(widget) {
+  return { ...widget, type: "chart" };
+}
+function createTopoloWidgetResponse({
+  serviceId,
+  serviceName,
+  widgets,
+  now
+}) {
+  const lastUpdated = toIsoTimestamp(now);
+  return {
+    success: true,
+    widgets: widgets.map((widget) => ({
+      ...widget,
+      serviceId: widget.serviceId?.trim() || serviceId,
+      serviceName: widget.serviceName?.trim() || serviceName,
+      lastUpdated: widget.lastUpdated?.trim() || lastUpdated
+    }))
+  };
+}
+function createTopoloWidgetError(error) {
+  return {
+    success: false,
+    widgets: [],
+    error
+  };
+}
+function validateTopoloWidgetResponse(response) {
+  const errors = [];
+  if (!isRecord(response)) {
+    return { ok: false, errors: ["response must be an object"] };
+  }
+  if (typeof response.success !== "boolean") {
+    errors.push("success must be a boolean");
+  }
+  if (!Array.isArray(response.widgets)) {
+    errors.push("widgets must be an array");
+    return { ok: errors.length === 0, errors };
+  }
+  response.widgets.forEach((widget, index) => {
+    validateWidget(widget, `widgets[${index}]`, errors);
+  });
+  if (response.success === false && response.error !== void 0 && typeof response.error !== "string") {
+    errors.push("error must be a string when provided");
+  }
+  return { ok: errors.length === 0, errors };
+}
+function validateWidget(widget, path, errors) {
+  if (!isRecord(widget)) {
+    errors.push(`${path} must be an object`);
+    return;
+  }
+  validateNonEmptyString(widget.serviceId, `${path}.serviceId`, errors);
+  validateNonEmptyString(widget.serviceName, `${path}.serviceName`, errors);
+  validateNonEmptyString(widget.lastUpdated, `${path}.lastUpdated`, errors);
+  validateSnapshotMetadata(widget.snapshot, `${path}.snapshot`, errors);
+  switch (widget.type) {
+    case "stats":
+      validateArray(widget.stats, `${path}.stats`, errors);
+      break;
+    case "recent-activity":
+      validateArray(widget.activities, `${path}.activities`, errors);
+      break;
+    case "quick-actions":
+      validateArray(widget.actions, `${path}.actions`, errors);
+      break;
+    case "notifications":
+      validateArray(widget.notifications, `${path}.notifications`, errors);
+      if (typeof widget.unreadCount !== "number") {
+        errors.push(`${path}.unreadCount must be a number`);
+      }
+      break;
+    case "chart":
+      validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
+      validateNonEmptyString(widget.title, `${path}.title`, errors);
+      if (!isRecord(widget.data)) {
+        errors.push(`${path}.data must be an object`);
+      } else {
+        validateArray(widget.data.labels, `${path}.data.labels`, errors);
+        validateArray(widget.data.values, `${path}.data.values`, errors);
+      }
+      break;
+    default:
+      errors.push(`${path}.type must be a supported Topolo widget type`);
+  }
+}
+function validateSnapshotMetadata(snapshot, path, errors) {
+  if (snapshot === void 0) {
+    return;
+  }
+  if (!isRecord(snapshot)) {
+    errors.push(`${path} must be an object when provided`);
+    return;
+  }
+  if (snapshot.defaultMetricKeys !== void 0 && !Array.isArray(snapshot.defaultMetricKeys)) {
+    errors.push(`${path}.defaultMetricKeys must be an array when provided`);
+  }
+  if (snapshot.highlights !== void 0 && !Array.isArray(snapshot.highlights)) {
+    errors.push(`${path}.highlights must be an array when provided`);
+  }
+  if (snapshot.availableMetrics === void 0) {
+    return;
+  }
+  if (!Array.isArray(snapshot.availableMetrics)) {
+    errors.push(`${path}.availableMetrics must be an array when provided`);
+    return;
+  }
+  snapshot.availableMetrics.forEach((metric, index) => {
+    const metricPath = `${path}.availableMetrics[${index}]`;
+    if (!isRecord(metric)) {
+      errors.push(`${metricPath} must be an object`);
+      return;
+    }
+    validateNonEmptyString(metric.key, `${metricPath}.key`, errors);
+    validateNonEmptyString(metric.label, `${metricPath}.label`, errors);
+    if (typeof metric.value !== "number" || Number.isNaN(metric.value)) {
+      errors.push(`${metricPath}.value must be a number`);
+    }
+  });
+}
+function validateNonEmptyString(value, path, errors) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    errors.push(`${path} must be a non-empty string`);
+  }
+}
+function validateArray(value, path, errors) {
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function toIsoTimestamp(input) {
+  if (input instanceof Date) {
+    return input.toISOString();
+  }
+  return input ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+
 // src/index.ts
 function createTopolo(options) {
   const client = new TopoloClient(options);
@@ -1938,6 +2202,8 @@ function createTopolo(options) {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
   TopoloHttpError,
@@ -1948,6 +2214,14 @@ function createTopolo(options) {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   createTopolo,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   requirementsForApplication,
-  resolveServiceUrl
+  resolveServiceUrl,
+  validateTopoloWidgetResponse
 });

package/dist/index.d.cts

@@ -38,8 +38,10 @@ declare const SERVICES: {
     readonly bugfix: "https://bugfix.topolo.app";
     readonly bytes: "https://r2-media-manager-worker.topolo.workers.dev";
     readonly calendar: "https://calendar.topolo.app";
+    readonly capacity: "https://topolo-capacity.topolo.workers.dev";
     readonly chat: "https://chat.topolo.app";
     readonly commerce: "https://topolo-commerce-api.topolo.workers.dev";
+    readonly compose: "https://compose.topolo.app";
     readonly crm: "https://crm-api.topolo.app";
     readonly customer_success: "https://customer-success.topolo.app";
     readonly feed: "https://topolo-feed-api.topolo.app";
@@ -53,6 +55,7 @@ declare const SERVICES: {
     readonly mdm: "https://topolo-mdm-api.topolo.app";
     readonly messaging: "https://messages.topolo.app";
     readonly nexus: "https://topolo-nexus-gateway.topolo.workers.dev";
+    readonly notify: "https://notify.topolo.app";
     readonly one: "https://one.topolo.app";
     readonly pay: "https://topolo-pay.topolo.workers.dev";
     readonly people: "https://people.topolo.app";
@@ -197,6 +200,22 @@ declare const APPLICATIONS: {
             readonly serviceId: "calendar";
         }];
     };
+    readonly capacity: {
+        readonly id: "capacity";
+        readonly appDir: "TopoloCapacity";
+        readonly name: "topolo-capacity";
+        readonly packageName: "topolo-capacity";
+        readonly productionUrl: "https://capacity.topolo.app";
+        readonly services: readonly ["capacity"];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-capacity";
+            readonly kind: "worker";
+            readonly apiUrl: "https://topolo-capacity.topolo.workers.dev";
+            readonly domains: readonly ["capacity.topolo.app", "topolo-capacity.topolo.workers.dev"];
+            readonly routes: readonly [];
+            readonly serviceId: "capacity";
+        }];
+    };
     readonly chat: {
         readonly id: "chat";
         readonly appDir: "TopoloChat";
@@ -268,6 +287,22 @@ declare const APPLICATIONS: {
             readonly serviceId: null;
         }];
     };
+    readonly compose: {
+        readonly id: "compose";
+        readonly appDir: "TopoloCompose";
+        readonly name: "topolo-compose";
+        readonly packageName: "@topolo/compose";
+        readonly productionUrl: "https://compose.topolo.app";
+        readonly services: readonly ["compose"];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-compose";
+            readonly kind: "worker";
+            readonly apiUrl: "https://compose.topolo.app";
+            readonly domains: readonly ["compose.topolo.app"];
+            readonly routes: readonly ["compose.topolo.app"];
+            readonly serviceId: "compose";
+        }];
+    };
     readonly crm: {
         readonly id: "crm";
         readonly appDir: "TopoloCRM";
@@ -566,6 +601,22 @@ declare const APPLICATIONS: {
             readonly serviceId: "nexus";
         }];
     };
+    readonly notify: {
+        readonly id: "notify";
+        readonly appDir: "TopoloNotify";
+        readonly name: "topolo-notify";
+        readonly packageName: "@topolo/notify";
+        readonly productionUrl: "https://notify.topolo.app";
+        readonly services: readonly ["notify"];
+        readonly deployTargets: readonly [{
+            readonly name: "topolo-notify";
+            readonly kind: "worker";
+            readonly apiUrl: "https://notify.topolo.app";
+            readonly domains: readonly ["notify.topolo.app"];
+            readonly routes: readonly ["notify.topolo.app"];
+            readonly serviceId: "notify";
+        }];
+    };
     readonly one: {
         readonly id: "one";
         readonly appDir: "TopoloOne";
@@ -847,7 +898,7 @@ type ApplicationId = keyof typeof APPLICATIONS;
 type ApplicationCatalogEntry = (typeof APPLICATIONS)[ApplicationId];
 type ApplicationDeployTarget = ApplicationCatalogEntry['deployTargets'][number];
 
-declare const APPLICATION_REQUIREMENTS_VERSION = "2026-04-22.1";
+declare const APPLICATION_REQUIREMENTS_VERSION = "2026-04-25.1";
 type ApplicationRequirementScope = 'all' | 'browser' | 'api' | 'tooling' | 'agent_surface';
 interface ApplicationRequirement {
     id: string;
@@ -951,6 +1002,13 @@ declare const APPLICATION_REQUIREMENTS: readonly [{
     readonly appliesTo: readonly ["api", "tooling", "agent_surface"];
     readonly evidence: readonly ["Read operations have typed SDK/CLI/MCP surfaces once their contract stabilizes", "Mutating generic calls require --confirm or confirm:true", "MCP tools never accept orgId and advertise only appropriate scope-gated tools"];
     readonly implementation: readonly ["Add SDK types first, then CLI commands and MCP tools for durable workflows", "Use generic API passthrough only as a temporary escape hatch", "Keep command output JSON-stable for agents and human-readable with --no-json"];
+}, {
+    readonly id: "native-dashboard-widget";
+    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 id: "observability-and-audit";
     readonly title: "Emit platform audit and debugging signals";
@@ -1235,6 +1293,128 @@ declare class TopoloOAuth {
     }): Promise<TokenResponse>;
 }
 
+declare const TOPOLO_WIDGET_ENDPOINT = "/api/widget";
+declare const TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 60000;
+type TopoloWidgetType = "stats" | "recent-activity" | "quick-actions" | "notifications" | "chart";
+interface TopoloWidgetBase {
+    serviceId: string;
+    serviceName: string;
+    serviceIcon?: string;
+    type: TopoloWidgetType;
+    lastUpdated: string;
+    snapshot?: TopoloWidgetSnapshotMetadata;
+}
+interface TopoloWidgetMetric {
+    label: string;
+    value: string | number;
+    change?: number;
+    changeLabel?: string;
+    icon?: string;
+}
+interface TopoloWidgetSnapshotMetric {
+    key: string;
+    label: string;
+    value: number;
+    unit?: string;
+    change?: number;
+    changeLabel?: string;
+}
+interface TopoloWidgetSnapshotMetadata {
+    presetKey?: string;
+    audience?: string;
+    scope?: string;
+    scopeLabel?: string;
+    generatedAt?: string;
+    summary?: string;
+    defaultMetricKeys?: string[];
+    availableMetrics?: TopoloWidgetSnapshotMetric[];
+    highlights?: string[];
+}
+interface TopoloStatsWidget extends TopoloWidgetBase {
+    type: "stats";
+    stats: TopoloWidgetMetric[];
+}
+interface TopoloWidgetActivityItem {
+    id: string;
+    title: string;
+    description?: string;
+    timestamp: string;
+    icon?: string;
+    link?: string;
+}
+interface TopoloRecentActivityWidget extends TopoloWidgetBase {
+    type: "recent-activity";
+    activities: TopoloWidgetActivityItem[];
+}
+interface TopoloWidgetActionItem {
+    id: string;
+    label: string;
+    icon?: string;
+    link: string;
+    primary?: boolean;
+}
+interface TopoloQuickActionsWidget extends TopoloWidgetBase {
+    type: "quick-actions";
+    actions: TopoloWidgetActionItem[];
+}
+interface TopoloWidgetNotificationItem {
+    id: string;
+    title: string;
+    message: string;
+    type: "info" | "warning" | "error" | "success";
+    timestamp: string;
+    read: boolean;
+    link?: string;
+}
+interface TopoloNotificationsWidget extends TopoloWidgetBase {
+    type: "notifications";
+    notifications: TopoloWidgetNotificationItem[];
+    unreadCount: number;
+}
+interface TopoloChartWidget extends TopoloWidgetBase {
+    type: "chart";
+    chartType: "line" | "bar" | "pie" | "donut";
+    title: string;
+    data: {
+        labels: string[];
+        values: number[];
+    };
+}
+type TopoloWidget = TopoloStatsWidget | TopoloRecentActivityWidget | TopoloQuickActionsWidget | TopoloNotificationsWidget | TopoloChartWidget;
+type TopoloWidgetWithOptionalMetadata<T extends TopoloWidget> = Omit<T, "serviceId" | "serviceName" | "lastUpdated"> & Partial<Pick<TopoloWidgetBase, "serviceId" | "serviceName" | "lastUpdated">>;
+type TopoloWidgetDraft = TopoloWidget extends infer Widget ? Widget extends TopoloWidget ? TopoloWidgetWithOptionalMetadata<Widget> : never : never;
+interface TopoloWidgetApiResponse {
+    success: boolean;
+    widgets: TopoloWidget[];
+    error?: string;
+}
+interface TopoloWidgetResponseOptions {
+    serviceId: string;
+    serviceName: string;
+    widgets: TopoloWidgetDraft[];
+    now?: Date | string;
+}
+interface TopoloWidgetValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+interface TopoloWidgetConfig {
+    serviceId: string;
+    serviceName: string;
+    baseUrl: string;
+    widgetEndpoint: string;
+    enabled: boolean;
+    refreshInterval: number;
+}
+declare function defineTopoloStatsWidget(widget: Omit<TopoloStatsWidget, "type">): TopoloStatsWidget;
+declare function defineTopoloRecentActivityWidget(widget: Omit<TopoloRecentActivityWidget, "type">): TopoloRecentActivityWidget;
+declare function defineTopoloQuickActionsWidget(widget: Omit<TopoloQuickActionsWidget, "type">): TopoloQuickActionsWidget;
+declare function defineTopoloNotificationsWidget(widget: Omit<TopoloNotificationsWidget, "type">): TopoloNotificationsWidget;
+declare function defineTopoloChartWidget(widget: Omit<TopoloChartWidget, "type">): TopoloChartWidget;
+declare function createTopoloWidgetResponse({ serviceId, serviceName, widgets, now, }: TopoloWidgetResponseOptions): TopoloWidgetApiResponse;
+declare function createTopoloWidgetError(error: string): TopoloWidgetApiResponse;
+declare function validateTopoloWidgetResponse(response: unknown): TopoloWidgetValidationResult;
+
 /**
  * Convenience factory that returns a ready-to-use typed Topolo client plus
  * domain module surfaces (identity, crm, ...).
@@ -1249,4 +1429,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, type TokenResponse, type Topolo, TopoloAuthError, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, TopoloOAuth, TopoloPermissionError, TopoloSdkError, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, requirementsForApplication, resolveServiceUrl };
+export { APPLICATIONS, APPLICATION_REQUIREMENTS, APPLICATION_REQUIREMENTS_VERSION, type AgentIdentity, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationId, type ApplicationRequirement, type ApplicationRequirementAudit, type ApplicationRequirementFinding, type ApplicationRequirementMigrationItem, type ApplicationRequirementScope, type ApplicationRequirementScore, type ApplicationRequirementStatus, type ApplicationRequirementsAuditReport, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_SERVICE_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, PLATFORM_SERVICE_IDS, type RequestOptions, type ServiceId, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, TopoloAuthError, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloQuickActionsWidget, type TopoloRecentActivityWidget, TopoloSdkError, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetActionItem, type TopoloWidgetActivityItem, type TopoloWidgetApiResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetDraft, type TopoloWidgetMetric, type TopoloWidgetNotificationItem, type TopoloWidgetResponseOptions, type TopoloWidgetSnapshotMetadata, type TopoloWidgetSnapshotMetric, type TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };