@topolo/sdk 0.2.5 → 0.2.6

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);
 
@@ -1219,7 +1229,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 +1361,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 +1548,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 +1953,126 @@ 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);
+  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 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 +2091,8 @@ function createTopolo(options) {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
   TopoloHttpError,
@@ -1948,6 +2103,14 @@ function createTopolo(options) {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   createTopolo,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   requirementsForApplication,
-  resolveServiceUrl
+  resolveServiceUrl,
+  validateTopoloWidgetResponse
 });

package/dist/index.d.cts

@@ -847,7 +847,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 +951,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 +1242,108 @@ 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;
+}
+interface TopoloWidgetMetric {
+    label: string;
+    value: string | number;
+    change?: number;
+    changeLabel?: string;
+    icon?: 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 +1358,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 TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -847,7 +847,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 +951,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 +1242,108 @@ 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;
+}
+interface TopoloWidgetMetric {
+    label: string;
+    value: string | number;
+    change?: number;
+    changeLabel?: string;
+    icon?: 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 +1358,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 TopoloWidgetType, type TopoloWidgetValidationResult, applicationRequirementScopes, auditAllApplicationRequirements, auditApplicationRequirements, createTopolo, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloQuickActionsWidget, defineTopoloRecentActivityWidget, defineTopoloStatsWidget, requirementsForApplication, resolveServiceUrl, validateTopoloWidgetResponse };

package/dist/index.js

@@ -1175,7 +1175,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",
@@ -1307,6 +1307,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",
@@ -1478,6 +1494,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,
@@ -1876,6 +1899,126 @@ 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);
+  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 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);
@@ -1893,6 +2036,8 @@ export {
   DEFAULT_SERVICE_URLS,
   IdentityModule,
   PLATFORM_SERVICE_IDS,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
   TopoloHttpError,
@@ -1903,6 +2048,14 @@ export {
   auditAllApplicationRequirements,
   auditApplicationRequirements,
   createTopolo,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   requirementsForApplication,
-  resolveServiceUrl
+  resolveServiceUrl,
+  validateTopoloWidgetResponse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "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-04-22.1';
+export const APPLICATION_REQUIREMENTS_VERSION = '2026-04-25.1';
 
 export type ApplicationRequirementScope =
   | 'all'
@@ -205,6 +205,23 @@ export const 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',
@@ -411,6 +428,13 @@ function evaluateRequirement(
       }
       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,

package/src/index.ts

@@ -44,6 +44,35 @@ export {
   type DeviceAuthorizationResponse,
   type TokenResponse,
 } from './oauth.js';
+export {
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
+  validateTopoloWidgetResponse,
+  type TopoloChartWidget,
+  type TopoloNotificationsWidget,
+  type TopoloQuickActionsWidget,
+  type TopoloRecentActivityWidget,
+  type TopoloStatsWidget,
+  type TopoloWidget,
+  type TopoloWidgetActionItem,
+  type TopoloWidgetActivityItem,
+  type TopoloWidgetApiResponse,
+  type TopoloWidgetBase,
+  type TopoloWidgetConfig,
+  type TopoloWidgetDraft,
+  type TopoloWidgetMetric,
+  type TopoloWidgetNotificationItem,
+  type TopoloWidgetResponseOptions,
+  type TopoloWidgetType,
+  type TopoloWidgetValidationResult,
+} from './widgets.js';
 
 import { TopoloClient, type TopoloClientOptions } from './client.js';
 import { CrmModule } from './modules/crm.js';

package/src/services.test.ts

@@ -135,6 +135,9 @@ describe('application requirements', () => {
     expect(APPLICATION_REQUIREMENTS.map((requirement) => requirement.id)).toContain(
       'shared-auth-boundary',
     );
+    expect(APPLICATION_REQUIREMENTS.map((requirement) => requirement.id)).toContain(
+      'native-dashboard-widget',
+    );
   });
 
   it('derives browser and API scopes from app metadata', () => {
@@ -158,6 +161,7 @@ describe('application requirements', () => {
     expect(adminRequirementIds).not.toContain('organization-scoped-data');
     expect(mailRequirementIds).toContain('organization-scoped-data');
     expect(mailRequirementIds).toContain('service-registration-and-scopes');
+    expect(mailRequirementIds).toContain('native-dashboard-widget');
     expect(cliRequirementIds).toContain('agent-and-operator-surfaces');
     expect(cliRequirementIds).not.toContain('service-registration-and-scopes');
   });

package/src/widgets.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createTopoloWidgetError,
+  createTopoloWidgetResponse,
+  TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
+  validateTopoloWidgetResponse,
+} from './widgets.js';
+
+describe('Topolo widget contract', () => {
+  it('exports the platform widget endpoint defaults', () => {
+    expect(TOPOLO_WIDGET_ENDPOINT).toBe('/api/widget');
+    expect(TOPOLO_WIDGET_REFRESH_INTERVAL_MS).toBe(60_000);
+  });
+
+  it('stamps service metadata and timestamp onto widget drafts', () => {
+    const response = createTopoloWidgetResponse({
+      serviceId: 'srv_bytes',
+      serviceName: 'Bytes',
+      now: '2026-04-25T00:00:00.000Z',
+      widgets: [
+        {
+          type: 'stats',
+          stats: [{ label: 'Files', value: 12 }],
+        },
+      ],
+    });
+
+    expect(response).toEqual({
+      success: true,
+      widgets: [
+        {
+          serviceId: 'srv_bytes',
+          serviceName: 'Bytes',
+          lastUpdated: '2026-04-25T00:00:00.000Z',
+          type: 'stats',
+          stats: [{ label: 'Files', value: 12 }],
+        },
+      ],
+    });
+  });
+
+  it('keeps explicit widget metadata when an app needs multiple service cards', () => {
+    const response = createTopoloWidgetResponse({
+      serviceId: 'srv_platform',
+      serviceName: 'Platform',
+      now: '2026-04-25T00:00:00.000Z',
+      widgets: [
+        {
+          serviceId: 'srv_crm',
+          serviceName: 'CRM',
+          lastUpdated: '2026-04-24T23:00:00.000Z',
+          type: 'stats',
+          stats: [{ label: 'Contacts', value: 3 }],
+        },
+      ],
+    });
+
+    expect(response.widgets[0]).toMatchObject({
+      serviceId: 'srv_crm',
+      serviceName: 'CRM',
+      lastUpdated: '2026-04-24T23:00:00.000Z',
+    });
+  });
+
+  it('returns a stable error response shape', () => {
+    expect(createTopoloWidgetError('not configured')).toEqual({
+      success: false,
+      widgets: [],
+      error: 'not configured',
+    });
+  });
+
+  it('validates a compliant response', () => {
+    const response = createTopoloWidgetResponse({
+      serviceId: 'srv_crm',
+      serviceName: 'CRM',
+      now: '2026-04-25T00:00:00.000Z',
+      widgets: [
+        {
+          type: 'notifications',
+          unreadCount: 1,
+          notifications: [
+            {
+              id: 'n_1',
+              title: 'New lead',
+              message: 'A lead was created.',
+              type: 'info',
+              timestamp: '2026-04-25T00:00:00.000Z',
+              read: false,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(validateTopoloWidgetResponse(response)).toEqual({
+      ok: true,
+      errors: [],
+    });
+  });
+
+  it('reports missing metadata and unsupported widget types', () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          serviceId: '',
+          serviceName: 'Bad App',
+          lastUpdated: '',
+          type: 'calendar',
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.errors).toEqual([
+      'widgets[0].serviceId must be a non-empty string',
+      'widgets[0].lastUpdated must be a non-empty string',
+      'widgets[0].type must be a supported Topolo widget type',
+    ]);
+  });
+});

package/src/widgets.ts

@@ -0,0 +1,288 @@
+export const TOPOLO_WIDGET_ENDPOINT = '/api/widget';
+export const TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 60_000;
+
+export type TopoloWidgetType =
+  | 'stats'
+  | 'recent-activity'
+  | 'quick-actions'
+  | 'notifications'
+  | 'chart';
+
+export interface TopoloWidgetBase {
+  serviceId: string;
+  serviceName: string;
+  serviceIcon?: string;
+  type: TopoloWidgetType;
+  lastUpdated: string;
+}
+
+export interface TopoloWidgetMetric {
+  label: string;
+  value: string | number;
+  change?: number;
+  changeLabel?: string;
+  icon?: string;
+}
+
+export interface TopoloStatsWidget extends TopoloWidgetBase {
+  type: 'stats';
+  stats: TopoloWidgetMetric[];
+}
+
+export interface TopoloWidgetActivityItem {
+  id: string;
+  title: string;
+  description?: string;
+  timestamp: string;
+  icon?: string;
+  link?: string;
+}
+
+export interface TopoloRecentActivityWidget extends TopoloWidgetBase {
+  type: 'recent-activity';
+  activities: TopoloWidgetActivityItem[];
+}
+
+export interface TopoloWidgetActionItem {
+  id: string;
+  label: string;
+  icon?: string;
+  link: string;
+  primary?: boolean;
+}
+
+export interface TopoloQuickActionsWidget extends TopoloWidgetBase {
+  type: 'quick-actions';
+  actions: TopoloWidgetActionItem[];
+}
+
+export interface TopoloWidgetNotificationItem {
+  id: string;
+  title: string;
+  message: string;
+  type: 'info' | 'warning' | 'error' | 'success';
+  timestamp: string;
+  read: boolean;
+  link?: string;
+}
+
+export interface TopoloNotificationsWidget extends TopoloWidgetBase {
+  type: 'notifications';
+  notifications: TopoloWidgetNotificationItem[];
+  unreadCount: number;
+}
+
+export interface TopoloChartWidget extends TopoloWidgetBase {
+  type: 'chart';
+  chartType: 'line' | 'bar' | 'pie' | 'donut';
+  title: string;
+  data: {
+    labels: string[];
+    values: number[];
+  };
+}
+
+export type TopoloWidget =
+  | TopoloStatsWidget
+  | TopoloRecentActivityWidget
+  | TopoloQuickActionsWidget
+  | TopoloNotificationsWidget
+  | TopoloChartWidget;
+
+type TopoloWidgetWithOptionalMetadata<T extends TopoloWidget> = Omit<
+  T,
+  'serviceId' | 'serviceName' | 'lastUpdated'
+> &
+  Partial<Pick<TopoloWidgetBase, 'serviceId' | 'serviceName' | 'lastUpdated'>>;
+
+export type TopoloWidgetDraft = TopoloWidget extends infer Widget
+  ? Widget extends TopoloWidget
+    ? TopoloWidgetWithOptionalMetadata<Widget>
+    : never
+  : never;
+
+export interface TopoloWidgetApiResponse {
+  success: boolean;
+  widgets: TopoloWidget[];
+  error?: string;
+}
+
+export interface TopoloWidgetResponseOptions {
+  serviceId: string;
+  serviceName: string;
+  widgets: TopoloWidgetDraft[];
+  now?: Date | string;
+}
+
+export interface TopoloWidgetValidationResult {
+  ok: boolean;
+  errors: string[];
+}
+
+export interface TopoloWidgetConfig {
+  serviceId: string;
+  serviceName: string;
+  baseUrl: string;
+  widgetEndpoint: string;
+  enabled: boolean;
+  refreshInterval: number;
+}
+
+export function defineTopoloStatsWidget(
+  widget: Omit<TopoloStatsWidget, 'type'>
+): TopoloStatsWidget {
+  return { ...widget, type: 'stats' };
+}
+
+export function defineTopoloRecentActivityWidget(
+  widget: Omit<TopoloRecentActivityWidget, 'type'>
+): TopoloRecentActivityWidget {
+  return { ...widget, type: 'recent-activity' };
+}
+
+export function defineTopoloQuickActionsWidget(
+  widget: Omit<TopoloQuickActionsWidget, 'type'>
+): TopoloQuickActionsWidget {
+  return { ...widget, type: 'quick-actions' };
+}
+
+export function defineTopoloNotificationsWidget(
+  widget: Omit<TopoloNotificationsWidget, 'type'>
+): TopoloNotificationsWidget {
+  return { ...widget, type: 'notifications' };
+}
+
+export function defineTopoloChartWidget(
+  widget: Omit<TopoloChartWidget, 'type'>
+): TopoloChartWidget {
+  return { ...widget, type: 'chart' };
+}
+
+export function createTopoloWidgetResponse({
+  serviceId,
+  serviceName,
+  widgets,
+  now,
+}: TopoloWidgetResponseOptions): TopoloWidgetApiResponse {
+  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,
+    })) as TopoloWidget[],
+  };
+}
+
+export function createTopoloWidgetError(error: string): TopoloWidgetApiResponse {
+  return {
+    success: false,
+    widgets: [],
+    error,
+  };
+}
+
+export function validateTopoloWidgetResponse(
+  response: unknown
+): TopoloWidgetValidationResult {
+  const errors: string[] = [];
+
+  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 !== undefined &&
+    typeof response.error !== 'string'
+  ) {
+    errors.push('error must be a string when provided');
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+function validateWidget(widget: unknown, path: string, errors: string[]) {
+  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);
+
+  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 validateNonEmptyString(
+  value: unknown,
+  path: string,
+  errors: string[]
+) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    errors.push(`${path} must be a non-empty string`);
+  }
+}
+
+function validateArray(value: unknown, path: string, errors: string[]) {
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function toIsoTimestamp(input: Date | string | undefined): string {
+  if (input instanceof Date) {
+    return input.toISOString();
+  }
+
+  return input ?? new Date().toISOString();
+}