@topolo/sdk 0.4.6 → 0.4.8

package/src/widgets.test.ts

@@ -2,11 +2,23 @@ import { describe, expect, it } from "vitest";
 import {
   createTopoloWidgetError,
   createTopoloWidgetResponse,
+  defineTopoloChartWidget,
+  defineTopoloNotificationsWidget,
+  defineTopoloQuickActionsWidget,
+  defineTopoloRecentActivityWidget,
+  defineTopoloStatsWidget,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   validateTopoloWidgetResponse,
 } from "./widgets.js";
 
+const BASE = {
+  serviceId: "service_x",
+  serviceName: "X",
+  lastUpdated: "2026-04-25T00:00:00.000Z",
+  snapshot: { summary: "A summary that is long enough to read." },
+};
+
 describe("Topolo widget contract", () => {
   it("exports the platform widget endpoint defaults", () => {
     expect(TOPOLO_WIDGET_ENDPOINT).toBe("/api/widget");
@@ -21,6 +33,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 +49,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 +69,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 +100,9 @@ describe("Topolo widget contract", () => {
       widgets: [
         {
           type: "notifications",
+          snapshot: {
+            summary: "CRM has one unread lead notification for review.",
+          },
           unreadCount: 1,
           notifications: [
             {
@@ -100,7 +124,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 +135,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 +157,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 +184,233 @@ 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("stamps the literal type onto each define* helper", () => {
+    expect(defineTopoloStatsWidget({ ...BASE, stats: [] }).type).toBe("stats");
+    expect(
+      defineTopoloRecentActivityWidget({ ...BASE, activities: [] }).type,
+    ).toBe("recent-activity");
+    expect(
+      defineTopoloQuickActionsWidget({ ...BASE, actions: [] }).type,
+    ).toBe("quick-actions");
+    expect(
+      defineTopoloNotificationsWidget({ ...BASE, notifications: [], unreadCount: 0 })
+        .type,
+    ).toBe("notifications");
+    expect(
+      defineTopoloChartWidget({
+        ...BASE,
+        chartType: "line",
+        title: "Trend",
+        data: { labels: ["a"], values: [1] },
+      }).type,
+    ).toBe("chart");
+  });
+
+  it("derives lastUpdated from a Date instance passed as now", () => {
+    const response = createTopoloWidgetResponse({
+      serviceId: "service_x",
+      serviceName: "X",
+      now: new Date("2026-05-01T12:00:00.000Z"),
+      widgets: [
+        {
+          type: "stats",
+          snapshot: { summary: "Date branch summary content here." },
+          stats: [],
+        },
+      ],
+    });
+    expect(response.widgets[0]!.lastUpdated).toBe("2026-05-01T12:00:00.000Z");
+  });
+
+  it("generates a current timestamp when now is omitted", () => {
+    const before = Date.now();
+    const response = createTopoloWidgetResponse({
+      serviceId: "service_x",
+      serviceName: "X",
+      widgets: [
+        {
+          type: "stats",
+          snapshot: { summary: "Omitted-now summary content here." },
+          stats: [],
+        },
+      ],
+    });
+    const stamped = Date.parse(response.widgets[0]!.lastUpdated);
+    expect(stamped).toBeGreaterThanOrEqual(before);
+    expect(Number.isNaN(stamped)).toBe(false);
+  });
+
+  it("rejects a non-object response", () => {
+    expect(validateTopoloWidgetResponse(null)).toEqual({
+      ok: false,
+      errors: ["response must be an object"],
+    });
+  });
+
+  it("rejects a non-boolean success and a non-array widgets field", () => {
+    const result = validateTopoloWidgetResponse({ success: "yes", widgets: "nope" });
+    expect(result.ok).toBe(false);
+    expect(result.errors).toContain("success must be a boolean");
+    expect(result.errors).toContain("widgets must be an array");
+  });
+
+  it("flags a non-string error on a failed response", () => {
+    const result = validateTopoloWidgetResponse({
+      success: false,
+      widgets: [],
+      error: 42,
+    });
+    expect(result.errors).toContain("error must be a string when provided");
+  });
+
+  it("flags a chart widget whose data is not an object", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          type: "chart",
+          chartType: "bar",
+          title: "T",
+          data: "not-an-object",
+        },
+      ],
+    });
+    expect(result.errors).toContain("widgets[0].data must be an object");
+  });
+
+  it("flags non-number unreadCount and missing notifications array", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          type: "notifications",
+          notifications: "x",
+          unreadCount: "many",
+        },
+      ],
+    });
+    expect(result.errors).toContain("widgets[0].notifications must be an array");
+    expect(result.errors).toContain("widgets[0].unreadCount must be a number");
+  });
+
+  it("flags malformed snapshot metadata arrays and metric entries", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot with bad metadata arrays present here.",
+            defaultMetricKeys: "not-array",
+            highlights: "not-array",
+            availableMetrics: [{ key: "", label: "", value: "NaN" }],
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.defaultMetricKeys must be an array when provided",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.highlights must be an array when provided",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0].key must be a non-empty string",
+    );
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0].value must be a number",
+    );
+  });
+
+  it("flags availableMetrics when it is present but not an array", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot summary with bad availableMetrics field.",
+            availableMetrics: "nope",
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics must be an array when provided",
+    );
+  });
+
+  it("flags a non-object widget entry and a missing snapshot", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [42],
+    });
+    expect(result.errors).toContain("widgets[0] must be an object");
+
+    const result2 = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          serviceId: "s",
+          serviceName: "n",
+          lastUpdated: "2026-04-25T00:00:00.000Z",
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result2.errors).toContain("widgets[0].snapshot must be an object");
+  });
+
+  it("flags a non-object availableMetrics entry", () => {
+    const result = validateTopoloWidgetResponse({
+      success: true,
+      widgets: [
+        {
+          ...BASE,
+          snapshot: {
+            summary: "Snapshot with a non-object metric entry here.",
+            availableMetrics: [42],
+          },
+          type: "stats",
+          stats: [],
+        },
+      ],
+    });
+    expect(result.errors).toContain(
+      "widgets[0].snapshot.availableMetrics[0] must be an object",
+    );
+  });
+
+  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)