@topolo/sdk 0.2.6 → 0.2.7

package/src/widgets.ts

@@ -1,12 +1,12 @@
-export const TOPOLO_WIDGET_ENDPOINT = '/api/widget';
+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';
+  | "stats"
+  | "recent-activity"
+  | "quick-actions"
+  | "notifications"
+  | "chart";
 
 export interface TopoloWidgetBase {
   serviceId: string;
@@ -14,6 +14,7 @@ export interface TopoloWidgetBase {
   serviceIcon?: string;
   type: TopoloWidgetType;
   lastUpdated: string;
+  snapshot?: TopoloWidgetSnapshotMetadata;
 }
 
 export interface TopoloWidgetMetric {
@@ -24,8 +25,29 @@ export interface TopoloWidgetMetric {
   icon?: string;
 }
 
+export interface TopoloWidgetSnapshotMetric {
+  key: string;
+  label: string;
+  value: number;
+  unit?: string;
+  change?: number;
+  changeLabel?: string;
+}
+
+export interface TopoloWidgetSnapshotMetadata {
+  presetKey?: string;
+  audience?: string;
+  scope?: string;
+  scopeLabel?: string;
+  generatedAt?: string;
+  summary?: string;
+  defaultMetricKeys?: string[];
+  availableMetrics?: TopoloWidgetSnapshotMetric[];
+  highlights?: string[];
+}
+
 export interface TopoloStatsWidget extends TopoloWidgetBase {
-  type: 'stats';
+  type: "stats";
   stats: TopoloWidgetMetric[];
 }
 
@@ -39,7 +61,7 @@ export interface TopoloWidgetActivityItem {
 }
 
 export interface TopoloRecentActivityWidget extends TopoloWidgetBase {
-  type: 'recent-activity';
+  type: "recent-activity";
   activities: TopoloWidgetActivityItem[];
 }
 
@@ -52,7 +74,7 @@ export interface TopoloWidgetActionItem {
 }
 
 export interface TopoloQuickActionsWidget extends TopoloWidgetBase {
-  type: 'quick-actions';
+  type: "quick-actions";
   actions: TopoloWidgetActionItem[];
 }
 
@@ -60,21 +82,21 @@ export interface TopoloWidgetNotificationItem {
   id: string;
   title: string;
   message: string;
-  type: 'info' | 'warning' | 'error' | 'success';
+  type: "info" | "warning" | "error" | "success";
   timestamp: string;
   read: boolean;
   link?: string;
 }
 
 export interface TopoloNotificationsWidget extends TopoloWidgetBase {
-  type: 'notifications';
+  type: "notifications";
   notifications: TopoloWidgetNotificationItem[];
   unreadCount: number;
 }
 
 export interface TopoloChartWidget extends TopoloWidgetBase {
-  type: 'chart';
-  chartType: 'line' | 'bar' | 'pie' | 'donut';
+  type: "chart";
+  chartType: "line" | "bar" | "pie" | "donut";
   title: string;
   data: {
     labels: string[];
@@ -91,9 +113,9 @@ export type TopoloWidget =
 
 type TopoloWidgetWithOptionalMetadata<T extends TopoloWidget> = Omit<
   T,
-  'serviceId' | 'serviceName' | 'lastUpdated'
+  "serviceId" | "serviceName" | "lastUpdated"
 > &
-  Partial<Pick<TopoloWidgetBase, 'serviceId' | 'serviceName' | 'lastUpdated'>>;
+  Partial<Pick<TopoloWidgetBase, "serviceId" | "serviceName" | "lastUpdated">>;
 
 export type TopoloWidgetDraft = TopoloWidget extends infer Widget
   ? Widget extends TopoloWidget
@@ -129,33 +151,33 @@ export interface TopoloWidgetConfig {
 }
 
 export function defineTopoloStatsWidget(
-  widget: Omit<TopoloStatsWidget, 'type'>
+  widget: Omit<TopoloStatsWidget, "type">,
 ): TopoloStatsWidget {
-  return { ...widget, type: 'stats' };
+  return { ...widget, type: "stats" };
 }
 
 export function defineTopoloRecentActivityWidget(
-  widget: Omit<TopoloRecentActivityWidget, 'type'>
+  widget: Omit<TopoloRecentActivityWidget, "type">,
 ): TopoloRecentActivityWidget {
-  return { ...widget, type: 'recent-activity' };
+  return { ...widget, type: "recent-activity" };
 }
 
 export function defineTopoloQuickActionsWidget(
-  widget: Omit<TopoloQuickActionsWidget, 'type'>
+  widget: Omit<TopoloQuickActionsWidget, "type">,
 ): TopoloQuickActionsWidget {
-  return { ...widget, type: 'quick-actions' };
+  return { ...widget, type: "quick-actions" };
 }
 
 export function defineTopoloNotificationsWidget(
-  widget: Omit<TopoloNotificationsWidget, 'type'>
+  widget: Omit<TopoloNotificationsWidget, "type">,
 ): TopoloNotificationsWidget {
-  return { ...widget, type: 'notifications' };
+  return { ...widget, type: "notifications" };
 }
 
 export function defineTopoloChartWidget(
-  widget: Omit<TopoloChartWidget, 'type'>
+  widget: Omit<TopoloChartWidget, "type">,
 ): TopoloChartWidget {
-  return { ...widget, type: 'chart' };
+  return { ...widget, type: "chart" };
 }
 
 export function createTopoloWidgetResponse({
@@ -168,7 +190,7 @@ export function createTopoloWidgetResponse({
 
   return {
     success: true,
-    widgets: widgets.map(widget => ({
+    widgets: widgets.map((widget) => ({
       ...widget,
       serviceId: widget.serviceId?.trim() || serviceId,
       serviceName: widget.serviceName?.trim() || serviceName,
@@ -177,7 +199,9 @@ export function createTopoloWidgetResponse({
   };
 }
 
-export function createTopoloWidgetError(error: string): TopoloWidgetApiResponse {
+export function createTopoloWidgetError(
+  error: string,
+): TopoloWidgetApiResponse {
   return {
     success: false,
     widgets: [],
@@ -186,20 +210,20 @@ export function createTopoloWidgetError(error: string): TopoloWidgetApiResponse
 }
 
 export function validateTopoloWidgetResponse(
-  response: unknown
+  response: unknown,
 ): TopoloWidgetValidationResult {
   const errors: string[] = [];
 
   if (!isRecord(response)) {
-    return { ok: false, errors: ['response must be an object'] };
+    return { ok: false, errors: ["response must be an object"] };
   }
 
-  if (typeof response.success !== 'boolean') {
-    errors.push('success must be a boolean');
+  if (typeof response.success !== "boolean") {
+    errors.push("success must be a boolean");
   }
 
   if (!Array.isArray(response.widgets)) {
-    errors.push('widgets must be an array');
+    errors.push("widgets must be an array");
     return { ok: errors.length === 0, errors };
   }
 
@@ -210,9 +234,9 @@ export function validateTopoloWidgetResponse(
   if (
     response.success === false &&
     response.error !== undefined &&
-    typeof response.error !== 'string'
+    typeof response.error !== "string"
   ) {
-    errors.push('error must be a string when provided');
+    errors.push("error must be a string when provided");
   }
 
   return { ok: errors.length === 0, errors };
@@ -227,24 +251,25 @@ function validateWidget(widget: unknown, path: string, errors: string[]) {
   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':
+    case "stats":
       validateArray(widget.stats, `${path}.stats`, errors);
       break;
-    case 'recent-activity':
+    case "recent-activity":
       validateArray(widget.activities, `${path}.activities`, errors);
       break;
-    case 'quick-actions':
+    case "quick-actions":
       validateArray(widget.actions, `${path}.actions`, errors);
       break;
-    case 'notifications':
+    case "notifications":
       validateArray(widget.notifications, `${path}.notifications`, errors);
-      if (typeof widget.unreadCount !== 'number') {
+      if (typeof widget.unreadCount !== "number") {
         errors.push(`${path}.unreadCount must be a number`);
       }
       break;
-    case 'chart':
+    case "chart":
       validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
       validateNonEmptyString(widget.title, `${path}.title`, errors);
       if (!isRecord(widget.data)) {
@@ -259,12 +284,58 @@ function validateWidget(widget: unknown, path: string, errors: string[]) {
   }
 }
 
+function validateSnapshotMetadata(
+  snapshot: unknown,
+  path: string,
+  errors: string[],
+) {
+  if (snapshot === undefined) {
+    return;
+  }
+  if (!isRecord(snapshot)) {
+    errors.push(`${path} must be an object when provided`);
+    return;
+  }
+  if (
+    snapshot.defaultMetricKeys !== undefined &&
+    !Array.isArray(snapshot.defaultMetricKeys)
+  ) {
+    errors.push(`${path}.defaultMetricKeys must be an array when provided`);
+  }
+  if (
+    snapshot.highlights !== undefined &&
+    !Array.isArray(snapshot.highlights)
+  ) {
+    errors.push(`${path}.highlights must be an array when provided`);
+  }
+  if (snapshot.availableMetrics === undefined) {
+    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: unknown,
   path: string,
-  errors: string[]
+  errors: string[],
 ) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
+  if (typeof value !== "string" || value.trim().length === 0) {
     errors.push(`${path} must be a non-empty string`);
   }
 }
@@ -276,7 +347,7 @@ function validateArray(value: unknown, path: string, errors: string[]) {
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
+  return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
 function toIsoTimestamp(input: Date | string | undefined): string {