@topolo/sdk 0.11.10 → 0.12.0

package/dist/index.js

@@ -1674,7 +1674,9 @@ var TopoloClient = class _TopoloClient {
     };
   }
   planResolvedAction(entry, input, options) {
-    const validation = validateTopoloActionInput(entry.inputSchema, input);
+    const inputValidation = validateTopoloActionInput(entry.inputSchema, input);
+    const resourceIssue = validateActionResource(entry, options.resource);
+    const validation = resourceIssue ? { valid: false, errors: [...inputValidation.errors, resourceIssue] } : inputValidation;
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
     let request = null;
@@ -1733,6 +1735,13 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`
       );
     }
+    const resourceIssue = validateActionResource(entry, options.resource);
+    if (resourceIssue) {
+      throw new TopoloSdkError(
+        "invalid_action_resource",
+        `Topolo action "${entry.actionId}" resource context is invalid: ${resourceIssue.message}`
+      );
+    }
     const mapped = mapActionInput(entry, input);
     const service = entry.appSlug || entry.appId;
     const result = await this.request({
@@ -1795,6 +1804,32 @@ var TopoloClient = class _TopoloClient {
     };
   }
 };
+function validateActionResource(entry, resource) {
+  const permissionName = entry.permissionName || entry.requiredPermission.split(".").at(-1) || "";
+  if (!permissionName.startsWith("workspace:")) return null;
+  if (!resource) {
+    return {
+      path: "$.resource",
+      code: "required",
+      message: "Select a workspace with the application resource catalog before planning or calling this action."
+    };
+  }
+  if (resource.resourceType !== "workspace") {
+    return {
+      path: "$.resource.resourceType",
+      code: "const",
+      message: 'This action requires resourceType "workspace".'
+    };
+  }
+  if (!resource.resourceId.trim()) {
+    return {
+      path: "$.resource.resourceId",
+      code: "required",
+      message: "This action requires a workspace resourceId."
+    };
+  }
+  return null;
+}
 function resolveConfiguredAppId(slug, appIds) {
   for (const serviceKey of serviceKeyCandidates2(slug)) {
     const configured = appIds?.[serviceKey];
@@ -3184,23 +3219,385 @@ var TopoloOAuth = class {
   }
 };
 
+// src/widget-validation.ts
+var CONTRACT_VERSION = "2.0.0";
+var WIDGET_TYPES = ["stats", "chart", "activity", "notifications", "actions"];
+var CONTEXTS = ["personal", "organization", "workspace", "resource"];
+var SIZES = ["compact", "medium", "wide", "full"];
+var STATES = ["ready", "empty", "unavailable", "stale", "error"];
+var FIELD_TYPES = ["string", "number", "boolean", "select", "multi-select", "date-range"];
+var SEMANTICS = ["gauge", "counter", "rate", "duration", "currency", "percentage"];
+var AGGREGATIONS = ["last", "sum", "average", "minimum", "maximum", "count", "distinct_count"];
+var CHART_TYPES = ["line", "bar", "area", "pie", "donut"];
+var SEVERITIES = ["info", "warning", "error", "success"];
+var RECOVERY_MODES = ["not_applicable", "retry", "compensating_action"];
+var SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+function validateTopoloWidgetResponse(response) {
+  const errors = [];
+  if (!isRecord5(response)) return { ok: false, errors: ["response must be an object"] };
+  exactValue(response.contractVersion, CONTRACT_VERSION, "contractVersion", errors);
+  nonEmptyString(response.appId, "appId", errors);
+  nonEmptyString(response.serviceName, "serviceName", errors);
+  isoTimestamp(response.generatedAt, "generatedAt", errors);
+  booleanValue(response.success, "success", errors);
+  arrayValue(response.widgets, "widgets", errors);
+  if (response.success === true) {
+    if (Array.isArray(response.widgets) && response.widgets.length === 0) {
+      errors.push("widgets must contain at least one complete widget; use widget state empty for intentional no-data");
+    }
+    if (response.error !== void 0) errors.push("error must be omitted when success is true");
+  } else if (response.success === false) {
+    if (Array.isArray(response.widgets) && response.widgets.length !== 0) {
+      errors.push("widgets must be empty when success is false");
+    }
+    validateApiError(response.error, "error", errors);
+  }
+  if (Array.isArray(response.widgets)) {
+    response.widgets.forEach((widget, index) => validateWidget(widget, `widgets[${index}]`, errors));
+  }
+  return { ok: errors.length === 0, errors };
+}
+function validateApiError(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.code, `${path}.code`, errors);
+  nonEmptyString(value.message, `${path}.message`, errors);
+  booleanValue(value.retryable, `${path}.retryable`, errors);
+  optionalIsoTimestamp(value.retryAfter, `${path}.retryAfter`, errors);
+}
+function validateWidget(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.id, `${path}.id`, errors);
+  patternString(value.version, SEMVER, `${path}.version`, errors);
+  nonEmptyString(value.appId, `${path}.appId`, errors);
+  nonEmptyString(value.serviceName, `${path}.serviceName`, errors);
+  enumValue(value.type, WIDGET_TYPES, `${path}.type`, errors);
+  isoTimestamp(value.lastUpdated, `${path}.lastUpdated`, errors);
+  validatePresentation(value.presentation, `${path}.presentation`, errors);
+  validateResource(value.resource, `${path}.resource`, errors);
+  validateState(value.state, `${path}.state`, errors);
+  validateRefresh(value.refresh, `${path}.refresh`, errors);
+  validateConfiguration(value.configuration, `${path}.configuration`, errors);
+  validateDrilldowns(value.drilldowns, `${path}.drilldowns`, errors);
+  validateActions(value.controls, `${path}.controls`, errors);
+  validateLocalization(value.localization, `${path}.localization`, errors);
+  validateAccessibility(value.accessibility, `${path}.accessibility`, errors);
+  switch (value.type) {
+    case "stats":
+      validateMetrics(value.metrics, `${path}.metrics`, errors, requiresContent(value));
+      break;
+    case "chart":
+      enumValue(value.chartType, CHART_TYPES, `${path}.chartType`, errors);
+      validateSeriesCollection(value.series, `${path}.series`, errors, requiresContent(value));
+      break;
+    case "activity":
+      validateActivities(value.activities, `${path}.activities`, errors, requiresContent(value));
+      break;
+    case "notifications":
+      validateNotifications(value.notifications, `${path}.notifications`, errors, requiresContent(value));
+      nonNegativeInteger(value.unreadCount, `${path}.unreadCount`, errors);
+      break;
+    case "actions":
+      validateActions(value.actions, `${path}.actions`, errors, requiresContent(value));
+      break;
+  }
+}
+function validatePresentation(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.title, `${path}.title`, errors);
+  optionalNonEmptyString(value.description, `${path}.description`, errors);
+  enumArray(value.contexts, CONTEXTS, `${path}.contexts`, errors, true);
+  enumArray(value.supportedSizes, SIZES, `${path}.supportedSizes`, errors, true);
+  enumValue(value.defaultSize, SIZES, `${path}.defaultSize`, errors);
+  if (typeof value.defaultSize === "string" && Array.isArray(value.supportedSizes) && !value.supportedSizes.includes(value.defaultSize)) {
+    errors.push(`${path}.defaultSize must be included in supportedSizes`);
+  }
+}
+function validateResource(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.resourceType, `${path}.resourceType`, errors);
+  optionalNonEmptyString(value.resourceId, `${path}.resourceId`, errors);
+  stringArray2(value.requiredPermissions, `${path}.requiredPermissions`, errors, true);
+}
+function validateState(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  enumValue(value.status, STATES, `${path}.status`, errors);
+  isoTimestamp(value.observedAt, `${path}.observedAt`, errors);
+  optionalIsoTimestamp(value.lastSuccessfulAt, `${path}.lastSuccessfulAt`, errors);
+  optionalNonEmptyString(value.code, `${path}.code`, errors);
+  optionalNonEmptyString(value.message, `${path}.message`, errors);
+  if (["empty", "unavailable", "error"].includes(String(value.status))) {
+    nonEmptyString(value.message, `${path}.message`, errors);
+  }
+  if (["unavailable", "error"].includes(String(value.status))) {
+    nonEmptyString(value.code, `${path}.code`, errors);
+  }
+  if (value.status === "stale") isoTimestamp(value.lastSuccessfulAt, `${path}.lastSuccessfulAt`, errors);
+}
+function validateRefresh(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  positiveInteger(value.intervalSeconds, `${path}.intervalSeconds`, errors);
+  positiveInteger(value.timeoutSeconds, `${path}.timeoutSeconds`, errors);
+  positiveInteger(value.maxAgeSeconds, `${path}.maxAgeSeconds`, errors);
+  nonNegativeInteger(value.staleWhileRevalidateSeconds, `${path}.staleWhileRevalidateSeconds`, errors);
+  if (isPositiveNumber(value.timeoutSeconds) && isPositiveNumber(value.intervalSeconds) && value.timeoutSeconds > value.intervalSeconds) {
+    errors.push(`${path}.timeoutSeconds must not exceed intervalSeconds`);
+  }
+}
+function validateConfiguration(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  booleanValue(value.allowMultipleInstances, `${path}.allowMultipleInstances`, errors);
+  recordValue(value.defaults, `${path}.defaults`, errors);
+  if (!arrayValue(value.fields, `${path}.fields`, errors)) return;
+  value.fields.forEach((field, index) => {
+    const fieldPath = `${path}.fields[${index}]`;
+    if (!recordValue(field, fieldPath, errors)) return;
+    nonEmptyString(field.key, `${fieldPath}.key`, errors);
+    nonEmptyString(field.label, `${fieldPath}.label`, errors);
+    enumValue(field.type, FIELD_TYPES, `${fieldPath}.type`, errors);
+    booleanValue(field.required, `${fieldPath}.required`, errors);
+    if (field.type === "select" || field.type === "multi-select") {
+      if (!arrayValue(field.options, `${fieldPath}.options`, errors, true)) return;
+      field.options.forEach((option, optionIndex) => {
+        const optionPath = `${fieldPath}.options[${optionIndex}]`;
+        if (!recordValue(option, optionPath, errors)) return;
+        nonEmptyString(option.value, `${optionPath}.value`, errors);
+        nonEmptyString(option.label, `${optionPath}.label`, errors);
+      });
+    } else if (field.options !== void 0) {
+      errors.push(`${fieldPath}.options is only valid for select fields`);
+    }
+  });
+}
+function validateDrilldowns(value, path, errors) {
+  if (!arrayValue(value, path, errors)) return;
+  value.forEach((drilldown, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(drilldown, itemPath, errors)) return;
+    nonEmptyString(drilldown.id, `${itemPath}.id`, errors);
+    nonEmptyString(drilldown.label, `${itemPath}.label`, errors);
+    nonEmptyString(drilldown.href, `${itemPath}.href`, errors);
+  });
+}
+function validateActions(value, path, errors, requireOne = false) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((action, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(action, itemPath, errors)) return;
+    nonEmptyString(action.id, `${itemPath}.id`, errors);
+    nonEmptyString(action.label, `${itemPath}.label`, errors);
+    nonEmptyString(action.actionId, `${itemPath}.actionId`, errors);
+    nonEmptyString(action.resourceType, `${itemPath}.resourceType`, errors);
+    optionalNonEmptyString(action.resourceId, `${itemPath}.resourceId`, errors);
+    recordValue(action.input, `${itemPath}.input`, errors);
+    booleanValue(action.requiresConfirmation, `${itemPath}.requiresConfirmation`, errors);
+    booleanValue(action.destructive, `${itemPath}.destructive`, errors);
+    stringArray2(action.effects, `${itemPath}.effects`, errors, true);
+    stringArray2(action.verification, `${itemPath}.verification`, errors, true);
+    validateRecovery(action.recovery, `${itemPath}.recovery`, errors);
+  });
+}
+function validateRecovery(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  enumValue(value.mode, RECOVERY_MODES, `${path}.mode`, errors);
+  optionalNonEmptyString(value.actionId, `${path}.actionId`, errors);
+  nonEmptyString(value.instructions, `${path}.instructions`, errors);
+  if (value.mode === "compensating_action" && value.actionId === void 0) {
+    errors.push(`${path}.actionId is required for compensating_action`);
+  }
+}
+function validateLocalization(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.locale, `${path}.locale`, errors);
+  nonEmptyString(value.titleKey, `${path}.titleKey`, errors);
+  optionalNonEmptyString(value.descriptionKey, `${path}.descriptionKey`, errors);
+}
+function validateAccessibility(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.label, `${path}.label`, errors);
+  optionalNonEmptyString(value.description, `${path}.description`, errors);
+}
+function validateMetrics(value, path, errors, requireOne) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((metric, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(metric, itemPath, errors)) return;
+    nonEmptyString(metric.key, `${itemPath}.key`, errors);
+    nonEmptyString(metric.label, `${itemPath}.label`, errors);
+    finiteNumber(metric.value, `${itemPath}.value`, errors);
+    nonEmptyString(metric.unit, `${itemPath}.unit`, errors);
+    enumValue(metric.semantic, SEMANTICS, `${itemPath}.semantic`, errors);
+    enumValue(metric.aggregation, AGGREGATIONS, `${itemPath}.aggregation`, errors);
+    validatePeriod(metric.period, `${itemPath}.period`, errors);
+    validateDimensions(metric.dimensions, `${itemPath}.dimensions`, errors);
+    if (metric.comparison !== void 0) validateComparison(metric.comparison, `${itemPath}.comparison`, errors);
+    if (metric.series !== void 0) validateSeries(metric.series, `${itemPath}.series`, errors);
+  });
+}
+function validatePeriod(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  isoTimestamp(value.start, `${path}.start`, errors);
+  isoTimestamp(value.end, `${path}.end`, errors);
+  nonEmptyString(value.timezone, `${path}.timezone`, errors);
+  if (isIsoTimestamp(value.start) && isIsoTimestamp(value.end) && Date.parse(value.start) > Date.parse(value.end)) {
+    errors.push(`${path}.start must not be after end`);
+  }
+}
+function validateDimensions(value, path, errors) {
+  if (!arrayValue(value, path, errors)) return;
+  value.forEach((dimension, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(dimension, itemPath, errors)) return;
+    nonEmptyString(dimension.key, `${itemPath}.key`, errors);
+    nonEmptyString(dimension.label, `${itemPath}.label`, errors);
+    nonEmptyString(dimension.value, `${itemPath}.value`, errors);
+  });
+}
+function validateComparison(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  finiteNumber(value.value, `${path}.value`, errors);
+  finiteNumber(value.absoluteChange, `${path}.absoluteChange`, errors);
+  optionalFiniteNumber(value.percentageChange, `${path}.percentageChange`, errors);
+  enumValue(value.direction, ["up", "down", "flat"], `${path}.direction`, errors);
+  nonEmptyString(value.label, `${path}.label`, errors);
+  validatePeriod(value.period, `${path}.period`, errors);
+}
+function validateSeriesCollection(value, path, errors, requireOne) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((series, index) => validateSeries(series, `${path}[${index}]`, errors));
+}
+function validateSeries(value, path, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.id, `${path}.id`, errors);
+  nonEmptyString(value.label, `${path}.label`, errors);
+  nonEmptyString(value.unit, `${path}.unit`, errors);
+  if (!arrayValue(value.points, `${path}.points`, errors, true)) return;
+  value.points.forEach((point, index) => {
+    const itemPath = `${path}.points[${index}]`;
+    if (!recordValue(point, itemPath, errors)) return;
+    isoTimestamp(point.timestamp, `${itemPath}.timestamp`, errors);
+    finiteNumber(point.value, `${itemPath}.value`, errors);
+    validateDimensions(point.dimensions, `${itemPath}.dimensions`, errors);
+  });
+}
+function validateActivities(value, path, errors, requireOne) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((activity, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(activity, itemPath, errors)) return;
+    nonEmptyString(activity.id, `${itemPath}.id`, errors);
+    nonEmptyString(activity.title, `${itemPath}.title`, errors);
+    optionalNonEmptyString(activity.description, `${itemPath}.description`, errors);
+    isoTimestamp(activity.timestamp, `${itemPath}.timestamp`, errors);
+    optionalNonEmptyString(activity.drilldownId, `${itemPath}.drilldownId`, errors);
+    optionalNonEmptyString(activity.actionId, `${itemPath}.actionId`, errors);
+  });
+}
+function validateNotifications(value, path, errors, requireOne) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((notification, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(notification, itemPath, errors)) return;
+    nonEmptyString(notification.id, `${itemPath}.id`, errors);
+    nonEmptyString(notification.title, `${itemPath}.title`, errors);
+    nonEmptyString(notification.message, `${itemPath}.message`, errors);
+    enumValue(notification.severity, SEVERITIES, `${itemPath}.severity`, errors);
+    isoTimestamp(notification.timestamp, `${itemPath}.timestamp`, errors);
+    booleanValue(notification.read, `${itemPath}.read`, errors);
+    optionalNonEmptyString(notification.drilldownId, `${itemPath}.drilldownId`, errors);
+    optionalNonEmptyString(notification.actionId, `${itemPath}.actionId`, errors);
+  });
+}
+function requiresContent(widget) {
+  return isRecord5(widget.state) && (widget.state.status === "ready" || widget.state.status === "stale");
+}
+function recordValue(value, path, errors) {
+  if (!isRecord5(value)) {
+    errors.push(`${path} must be an object`);
+    return false;
+  }
+  return true;
+}
+function arrayValue(value, path, errors, requireOne = false) {
+  if (!Array.isArray(value)) {
+    errors.push(`${path} must be an array`);
+    return false;
+  }
+  if (requireOne && value.length === 0) errors.push(`${path} must contain at least one item`);
+  return true;
+}
+function stringArray2(value, path, errors, requireOne = false) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((item, index) => nonEmptyString(item, `${path}[${index}]`, errors));
+}
+function enumArray(value, allowed, path, errors, requireOne) {
+  if (!arrayValue(value, path, errors, requireOne)) return;
+  value.forEach((item, index) => enumValue(item, allowed, `${path}[${index}]`, errors));
+  if (new Set(value).size !== value.length) errors.push(`${path} must not contain duplicates`);
+}
+function nonEmptyString(value, path, errors) {
+  if (typeof value !== "string" || value.trim().length === 0) errors.push(`${path} must be a non-empty string`);
+}
+function optionalNonEmptyString(value, path, errors) {
+  if (value !== void 0) nonEmptyString(value, path, errors);
+}
+function patternString(value, pattern, path, errors) {
+  if (typeof value !== "string" || !pattern.test(value)) errors.push(`${path} must be a semantic version`);
+}
+function enumValue(value, allowed, path, errors) {
+  if (typeof value !== "string" || !allowed.includes(value)) errors.push(`${path} must be one of: ${allowed.join(", ")}`);
+}
+function exactValue(value, expected, path, errors) {
+  if (value !== expected) errors.push(`${path} must be ${expected}`);
+}
+function booleanValue(value, path, errors) {
+  if (typeof value !== "boolean") errors.push(`${path} must be a boolean`);
+}
+function finiteNumber(value, path, errors) {
+  if (typeof value !== "number" || !Number.isFinite(value)) errors.push(`${path} must be a finite number`);
+}
+function optionalFiniteNumber(value, path, errors) {
+  if (value !== void 0) finiteNumber(value, path, errors);
+}
+function positiveInteger(value, path, errors) {
+  if (!Number.isInteger(value) || Number(value) <= 0) errors.push(`${path} must be a positive integer`);
+}
+function nonNegativeInteger(value, path, errors) {
+  if (!Number.isInteger(value) || Number(value) < 0) errors.push(`${path} must be a non-negative integer`);
+}
+function isoTimestamp(value, path, errors) {
+  if (!isIsoTimestamp(value)) errors.push(`${path} must be an ISO timestamp`);
+}
+function optionalIsoTimestamp(value, path, errors) {
+  if (value !== void 0) isoTimestamp(value, path, errors);
+}
+function isIsoTimestamp(value) {
+  return typeof value === "string" && value.trim().length > 0 && Number.isFinite(Date.parse(value));
+}
+function isPositiveNumber(value) {
+  return typeof value === "number" && value > 0;
+}
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 // src/widgets.ts
 var TOPOLO_WIDGET_ENDPOINT = "/api/widget";
 var TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 6e4;
+var TOPOLO_WIDGET_CONTRACT_VERSION = "2.0.0";
 function defineTopoloStatsWidget(widget) {
   return { ...widget, type: "stats" };
 }
-function defineTopoloRecentActivityWidget(widget) {
-  return { ...widget, type: "recent-activity" };
+function defineTopoloChartWidget(widget) {
+  return { ...widget, type: "chart" };
 }
-function defineTopoloQuickActionsWidget(widget) {
-  return { ...widget, type: "quick-actions" };
+function defineTopoloActivityWidget(widget) {
+  return { ...widget, type: "activity" };
 }
 function defineTopoloNotificationsWidget(widget) {
   return { ...widget, type: "notifications" };
 }
-function defineTopoloChartWidget(widget) {
-  return { ...widget, type: "chart" };
+function defineTopoloActionsWidget(widget) {
+  return { ...widget, type: "actions" };
 }
 function createTopoloWidgetResponse({
   appId,
@@ -3208,136 +3605,59 @@ function createTopoloWidgetResponse({
   widgets,
   now
 }) {
-  const lastUpdated = toIsoTimestamp(now);
-  return {
+  const generatedAt = toIsoTimestamp(now);
+  const response = {
     success: true,
+    contractVersion: TOPOLO_WIDGET_CONTRACT_VERSION,
+    appId,
+    serviceName,
+    generatedAt,
     widgets: widgets.map((widget) => ({
       ...widget,
       appId: widget.appId?.trim() || appId,
       serviceName: widget.serviceName?.trim() || serviceName,
-      lastUpdated: widget.lastUpdated?.trim() || lastUpdated
+      lastUpdated: widget.lastUpdated?.trim() || generatedAt
     }))
   };
+  assertValidTopoloWidgetResponse(response);
+  return response;
 }
-function createTopoloWidgetError(error) {
-  return {
+function createTopoloWidgetError({
+  appId,
+  serviceName,
+  code,
+  message,
+  retryable,
+  retryAfter,
+  now
+}) {
+  const response = {
     success: false,
+    contractVersion: TOPOLO_WIDGET_CONTRACT_VERSION,
+    appId,
+    serviceName,
+    generatedAt: toIsoTimestamp(now),
     widgets: [],
-    error
-  };
-}
-function validateTopoloWidgetResponse(response) {
-  const errors = [];
-  if (!isRecord5(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 (!isRecord5(widget)) {
-    errors.push(`${path} must be an object`);
-    return;
-  }
-  validateNonEmptyString(widget.appId, `${path}.appId`, errors);
-  validateNonEmptyString(widget.serviceName, `${path}.serviceName`, errors);
-  validateNonEmptyString(widget.lastUpdated, `${path}.lastUpdated`, errors);
-  validateSnapshotMetadata(widget.snapshot, `${path}.snapshot`, errors);
-  switch (widget.type) {
-    case "stats":
-      validateArray2(widget.stats, `${path}.stats`, errors);
-      break;
-    case "recent-activity":
-      validateArray2(widget.activities, `${path}.activities`, errors);
-      break;
-    case "quick-actions":
-      validateArray2(widget.actions, `${path}.actions`, errors);
-      break;
-    case "notifications":
-      validateArray2(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 (!isRecord5(widget.data)) {
-        errors.push(`${path}.data must be an object`);
-      } else {
-        validateArray2(widget.data.labels, `${path}.data.labels`, errors);
-        validateArray2(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) {
-    errors.push(`${path} must be an object`);
-    return;
-  }
-  if (!isRecord5(snapshot)) {
-    errors.push(`${path} must be an object`);
-    return;
-  }
-  validateNonEmptyString(snapshot.summary, `${path}.summary`, errors);
-  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 (!isRecord5(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`);
+    error: {
+      code,
+      message,
+      retryable,
+      ...retryAfter === void 0 ? {} : { retryAfter: toIsoTimestamp(retryAfter) }
     }
-  });
-}
-function validateNonEmptyString(value, path, errors) {
-  if (typeof value !== "string" || value.trim().length === 0) {
-    errors.push(`${path} must be a non-empty string`);
-  }
-}
-function validateArray2(value, path, errors) {
-  if (!Array.isArray(value)) {
-    errors.push(`${path} must be an array`);
+  };
+  assertValidTopoloWidgetResponse(response);
+  return response;
+}
+function assertValidTopoloWidgetResponse(response) {
+  const validation = validateTopoloWidgetResponse(response);
+  if (!validation.ok) {
+    throw new TypeError(
+      `Invalid Topolo widget contract: ${validation.errors.join("; ")}`
+    );
   }
 }
-function isRecord5(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 function toIsoTimestamp(input) {
-  if (input instanceof Date) {
-    return input.toISOString();
-  }
+  if (input instanceof Date) return input.toISOString();
   return input ?? (/* @__PURE__ */ new Date()).toISOString();
 }
 
@@ -3359,6 +3679,7 @@ export {
   P2PModule,
   TOPOLO_ENVIRONMENT_SERVICE_URLS,
   TOPOLO_RUNTIME_ENVIRONMENTS,
+  TOPOLO_WIDGET_CONTRACT_VERSION,
   TOPOLO_WIDGET_ENDPOINT,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
@@ -3385,10 +3706,10 @@ export {
   createTopoloAgentExecutionContext,
   createTopoloWidgetError,
   createTopoloWidgetResponse,
+  defineTopoloActionsWidget,
+  defineTopoloActivityWidget,
   defineTopoloChartWidget,
   defineTopoloNotificationsWidget,
-  defineTopoloQuickActionsWidget,
-  defineTopoloRecentActivityWidget,
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
   encodeTopoloActionBase64,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.11.10",
-  "topoloPublishedVersion": "0.11.10",
+  "version": "0.12.0",
+  "topoloPublishedVersion": "0.12.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",
@@ -50,7 +50,7 @@
             "tsconfig.json",
             "vitest.config.ts"
           ],
-          "digest": "4ecfb08c915533c17b3a4e0831241e1e223fd4ead89b60e5be40b749f5f624ee"
+          "digest": "2bb3a53e5241cde11d06fe2bd355cac5cd9141b1b5ad5f71ebc2d621c1c33fb0"
         }
       }
     ]