@topolo/sdk 0.13.0 → 0.14.1

package/dist/index.js

@@ -3237,7 +3237,7 @@ var TopoloOAuth = class {
 };
 
 // src/widget-validation.ts
-var CONTRACT_VERSION = "2.0.0";
+var CONTRACT_VERSION = "3.0.0";
 var WIDGET_TYPES = ["stats", "chart", "activity", "notifications", "actions"];
 var CONTEXTS = ["personal", "organization", "workspace", "resource"];
 var SIZES = ["compact", "medium", "wide", "full"];
@@ -3248,6 +3248,9 @@ var AGGREGATIONS = ["last", "sum", "average", "minimum", "maximum", "count", "di
 var CHART_TYPES = ["line", "bar", "area", "pie", "donut"];
 var SEVERITIES = ["info", "warning", "error", "success"];
 var RECOVERY_MODES = ["not_applicable", "retry", "compensating_action"];
+var VISUALIZATION_FAMILIES = ["number", "line", "area", "bar", "donut", "table", "funnel", "timeline", "actions"];
+var WORKSPACE_SELECTOR_MODES = ["none", "optional", "required"];
+var DIMENSION_VALUE_TYPES = ["string", "number", "boolean", "date", "datetime"];
 var SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 function validateTopoloWidgetResponse(response) {
   const errors = [];
@@ -3298,6 +3301,7 @@ function validateWidget(value, path, errors) {
   validateActions(value.controls, `${path}.controls`, errors);
   validateLocalization(value.localization, `${path}.localization`, errors);
   validateAccessibility(value.accessibility, `${path}.accessibility`, errors);
+  validateContribution(value.contribution, `${path}.contribution`, value, errors);
   switch (value.type) {
     case "stats":
       validateMetrics(value.metrics, `${path}.metrics`, errors, requiresContent(value));
@@ -3435,6 +3439,208 @@ function validateAccessibility(value, path, errors) {
   nonEmptyString(value.label, `${path}.label`, errors);
   optionalNonEmptyString(value.description, `${path}.description`, errors);
 }
+function validateContribution(value, path, widget, errors) {
+  if (!recordValue(value, path, errors)) return;
+  nonEmptyString(value.summary, `${path}.summary`, errors);
+  if (recordValue(value.identity, `${path}.identity`, errors)) {
+    exactValue(value.identity.iconSource, "catalog", `${path}.identity.iconSource`, errors);
+  }
+  if (recordValue(value.workspaceSelector, `${path}.workspaceSelector`, errors)) {
+    enumValue(value.workspaceSelector.mode, WORKSPACE_SELECTOR_MODES, `${path}.workspaceSelector.mode`, errors);
+    nonEmptyString(value.workspaceSelector.resourceType, `${path}.workspaceSelector.resourceType`, errors);
+    nonEmptyString(value.workspaceSelector.label, `${path}.workspaceSelector.label`, errors);
+    booleanValue(value.workspaceSelector.supportsMultiple, `${path}.workspaceSelector.supportsMultiple`, errors);
+    if (value.workspaceSelector.mode === "required" && requiresContent(widget) && isRecord5(widget.resource) && typeof widget.resource.resourceId !== "string") {
+      errors.push(`${path}.workspaceSelector requires a bound resourceId for ready or stale data`);
+    }
+  }
+  const metricKeys = validateMetricDefinitions(value.metricDefinitions, `${path}.metricDefinitions`, errors);
+  const seriesKeys = validateSeriesDefinitions(value.seriesDefinitions, `${path}.seriesDefinitions`, metricKeys, errors);
+  const dimensionKeys = validateDimensionDefinitions(value.dimensions, `${path}.dimensions`, errors);
+  const lifecycleKeys = validateLifecycleStages(value.lifecycleStages, `${path}.lifecycleStages`, errors);
+  const eventKeys = validateEventDefinitions(value.events, `${path}.events`, errors);
+  const actionKeys = widgetActionKeys(widget);
+  validateDatasets(value.datasets, `${path}.datasets`, {
+    metricKeys,
+    seriesKeys,
+    dimensionKeys,
+    eventKeys,
+    actionKeys
+  }, errors);
+  enumArray(
+    value.compatibleVisualizations,
+    VISUALIZATION_FAMILIES,
+    `${path}.compatibleVisualizations`,
+    errors,
+    true
+  );
+  enumValue(value.defaultVisualization, VISUALIZATION_FAMILIES, `${path}.defaultVisualization`, errors);
+  if (typeof value.defaultVisualization === "string" && Array.isArray(value.compatibleVisualizations) && !value.compatibleVisualizations.includes(value.defaultVisualization)) {
+    errors.push(`${path}.defaultVisualization must be included in compatibleVisualizations`);
+  }
+  if (Array.isArray(value.compatibleVisualizations)) {
+    for (const family of value.compatibleVisualizations) {
+      if (family === "number" && metricKeys.size === 0) errors.push(`${path}.compatibleVisualizations number requires a metric definition`);
+      if ((family === "line" || family === "area") && seriesKeys.size === 0) errors.push(`${path}.compatibleVisualizations ${family} requires a series definition`);
+      if (family === "donut" && (metricKeys.size === 0 || dimensionKeys.size === 0)) errors.push(`${path}.compatibleVisualizations donut requires metric and dimension definitions`);
+      if (family === "funnel" && lifecycleKeys.size < 2) errors.push(`${path}.compatibleVisualizations funnel requires at least two lifecycle stages`);
+      if (family === "timeline" && eventKeys.size === 0) errors.push(`${path}.compatibleVisualizations timeline requires an event definition`);
+      if (family === "actions" && actionKeys.size === 0) errors.push(`${path}.compatibleVisualizations actions requires a published action`);
+      if (family === "bar" && metricKeys.size === 0 && seriesKeys.size === 0) errors.push(`${path}.compatibleVisualizations bar requires a metric or series definition`);
+    }
+  }
+  validateRuntimeSemantics(widget, path, { metricKeys, seriesKeys, dimensionKeys }, errors);
+}
+function validateMetricDefinitions(value, path, errors) {
+  const keys = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors)) return keys;
+  value.forEach((definition, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(definition, itemPath, errors)) return;
+    nonEmptyString(definition.key, `${itemPath}.key`, errors);
+    nonEmptyString(definition.label, `${itemPath}.label`, errors);
+    nonEmptyString(definition.description, `${itemPath}.description`, errors);
+    nonEmptyString(definition.unit, `${itemPath}.unit`, errors);
+    enumValue(definition.semantic, SEMANTICS, `${itemPath}.semantic`, errors);
+    enumValue(definition.aggregation, AGGREGATIONS, `${itemPath}.aggregation`, errors);
+    addUniqueKey(definition.key, itemPath, keys, errors);
+  });
+  return keys;
+}
+function validateSeriesDefinitions(value, path, metricKeys, errors) {
+  const keys = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors)) return keys;
+  value.forEach((definition, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(definition, itemPath, errors)) return;
+    nonEmptyString(definition.key, `${itemPath}.key`, errors);
+    nonEmptyString(definition.label, `${itemPath}.label`, errors);
+    nonEmptyString(definition.metricKey, `${itemPath}.metricKey`, errors);
+    nonEmptyString(definition.unit, `${itemPath}.unit`, errors);
+    addUniqueKey(definition.key, itemPath, keys, errors);
+    if (typeof definition.metricKey === "string" && !metricKeys.has(definition.metricKey)) {
+      errors.push(`${itemPath}.metricKey must reference a declared metric definition`);
+    }
+  });
+  return keys;
+}
+function validateDimensionDefinitions(value, path, errors) {
+  const keys = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors)) return keys;
+  value.forEach((definition, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(definition, itemPath, errors)) return;
+    nonEmptyString(definition.key, `${itemPath}.key`, errors);
+    nonEmptyString(definition.label, `${itemPath}.label`, errors);
+    nonEmptyString(definition.description, `${itemPath}.description`, errors);
+    enumValue(definition.valueType, DIMENSION_VALUE_TYPES, `${itemPath}.valueType`, errors);
+    addUniqueKey(definition.key, itemPath, keys, errors);
+  });
+  return keys;
+}
+function validateLifecycleStages(value, path, errors) {
+  const keys = /* @__PURE__ */ new Set();
+  const orders = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors)) return keys;
+  value.forEach((stage, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(stage, itemPath, errors)) return;
+    nonEmptyString(stage.key, `${itemPath}.key`, errors);
+    nonEmptyString(stage.label, `${itemPath}.label`, errors);
+    nonNegativeInteger(stage.order, `${itemPath}.order`, errors);
+    booleanValue(stage.terminal, `${itemPath}.terminal`, errors);
+    addUniqueKey(stage.key, itemPath, keys, errors);
+    if (typeof stage.order === "number") {
+      if (orders.has(stage.order)) errors.push(`${itemPath}.order must be unique`);
+      orders.add(stage.order);
+    }
+  });
+  return keys;
+}
+function validateEventDefinitions(value, path, errors) {
+  const keys = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors)) return keys;
+  value.forEach((event, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(event, itemPath, errors)) return;
+    nonEmptyString(event.key, `${itemPath}.key`, errors);
+    nonEmptyString(event.label, `${itemPath}.label`, errors);
+    nonEmptyString(event.description, `${itemPath}.description`, errors);
+    addUniqueKey(event.key, itemPath, keys, errors);
+  });
+  return keys;
+}
+function validateDatasets(value, path, references, errors) {
+  const ids = /* @__PURE__ */ new Set();
+  if (!arrayValue(value, path, errors, true)) return;
+  value.forEach((dataset, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (!recordValue(dataset, itemPath, errors)) return;
+    nonEmptyString(dataset.id, `${itemPath}.id`, errors);
+    nonEmptyString(dataset.label, `${itemPath}.label`, errors);
+    nonEmptyString(dataset.description, `${itemPath}.description`, errors);
+    nonEmptyString(dataset.grain, `${itemPath}.grain`, errors);
+    addUniqueKey(dataset.id, itemPath, ids, errors);
+    const fields = ["metricKeys", "seriesKeys", "dimensionKeys", "eventKeys", "actionIds"];
+    for (const field of fields) stringArray2(dataset[field], `${itemPath}.${field}`, errors);
+    const totalReferences = fields.reduce((total, field) => total + (Array.isArray(dataset[field]) ? dataset[field].length : 0), 0);
+    if (totalReferences === 0) errors.push(`${itemPath} must reference at least one declared metric, series, dimension, event, or action`);
+    validateReferences(dataset.metricKeys, references.metricKeys, `${itemPath}.metricKeys`, errors);
+    validateReferences(dataset.seriesKeys, references.seriesKeys, `${itemPath}.seriesKeys`, errors);
+    validateReferences(dataset.dimensionKeys, references.dimensionKeys, `${itemPath}.dimensionKeys`, errors);
+    validateReferences(dataset.eventKeys, references.eventKeys, `${itemPath}.eventKeys`, errors);
+    validateReferences(dataset.actionIds, references.actionKeys, `${itemPath}.actionIds`, errors);
+  });
+}
+function validateReferences(value, known, path, errors) {
+  if (!Array.isArray(value)) return;
+  for (const reference of value) {
+    if (typeof reference === "string" && !known.has(reference)) errors.push(`${path} references undeclared key ${reference}`);
+  }
+}
+function widgetActionKeys(widget) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const collection of [widget.controls, widget.actions]) {
+    if (!Array.isArray(collection)) continue;
+    for (const action of collection) if (isRecord5(action) && typeof action.id === "string") keys.add(action.id);
+  }
+  return keys;
+}
+function validateRuntimeSemantics(widget, contributionPath, declared, errors) {
+  const metrics = Array.isArray(widget.metrics) ? widget.metrics : [];
+  for (const metric of metrics) {
+    if (!isRecord5(metric) || typeof metric.key !== "string") continue;
+    if (!declared.metricKeys.has(metric.key)) errors.push(`${contributionPath}.metricDefinitions is missing runtime metric ${metric.key}`);
+    validateRuntimeDimensions(metric.dimensions, declared.dimensionKeys, contributionPath, errors);
+    if (isRecord5(metric.series)) {
+      if (typeof metric.series.id === "string" && !declared.seriesKeys.has(metric.series.id)) errors.push(`${contributionPath}.seriesDefinitions is missing runtime series ${metric.series.id}`);
+      validateSeriesDimensions(metric.series, declared.dimensionKeys, contributionPath, errors);
+    }
+  }
+  const series2 = Array.isArray(widget.series) ? widget.series : [];
+  for (const item of series2) {
+    if (!isRecord5(item)) continue;
+    if (typeof item.id === "string" && !declared.seriesKeys.has(item.id)) errors.push(`${contributionPath}.seriesDefinitions is missing runtime series ${item.id}`);
+    validateSeriesDimensions(item, declared.dimensionKeys, contributionPath, errors);
+  }
+}
+function validateSeriesDimensions(series2, known, path, errors) {
+  if (!Array.isArray(series2.points)) return;
+  for (const point of series2.points) if (isRecord5(point)) validateRuntimeDimensions(point.dimensions, known, path, errors);
+}
+function validateRuntimeDimensions(value, known, path, errors) {
+  if (!Array.isArray(value)) return;
+  for (const dimension2 of value) {
+    if (isRecord5(dimension2) && typeof dimension2.key === "string" && !known.has(dimension2.key)) {
+      errors.push(`${path}.dimensions is missing runtime dimension ${dimension2.key}`);
+    }
+  }
+}
+function addUniqueKey(value, path, keys, errors) {
+  if (typeof value !== "string" || value.trim().length === 0) return;
+  if (keys.has(value)) errors.push(`${path}.key must be unique`);
+  keys.add(value);
+}
 function validateMetrics(value, path, errors, requireOne) {
   if (!arrayValue(value, path, errors, requireOne)) return;
   value.forEach((metric, index) => {
@@ -3463,12 +3669,12 @@ function validatePeriod(value, path, errors) {
 }
 function validateDimensions(value, path, errors) {
   if (!arrayValue(value, path, errors)) return;
-  value.forEach((dimension, index) => {
+  value.forEach((dimension2, 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);
+    if (!recordValue(dimension2, itemPath, errors)) return;
+    nonEmptyString(dimension2.key, `${itemPath}.key`, errors);
+    nonEmptyString(dimension2.label, `${itemPath}.label`, errors);
+    nonEmptyString(dimension2.value, `${itemPath}.value`, errors);
   });
 }
 function validateComparison(value, path, errors) {
@@ -3482,7 +3688,7 @@ function validateComparison(value, path, errors) {
 }
 function validateSeriesCollection(value, path, errors, requireOne) {
   if (!arrayValue(value, path, errors, requireOne)) return;
-  value.forEach((series, index) => validateSeries(series, `${path}[${index}]`, errors));
+  value.forEach((series2, index) => validateSeries(series2, `${path}[${index}]`, errors));
 }
 function validateSeries(value, path, errors) {
   if (!recordValue(value, path, errors)) return;
@@ -3602,7 +3808,7 @@ function isRecord5(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";
+var TOPOLO_WIDGET_CONTRACT_VERSION = "3.0.0";
 function defineTopoloStatsWidget(widget) {
   return { ...widget, type: "stats" };
 }
@@ -3680,6 +3886,478 @@ function toIsoTimestamp(input) {
   return input ?? (/* @__PURE__ */ new Date()).toISOString();
 }
 
+// src/widget-output-schema.ts
+var nonEmptyString2 = { type: "string", minLength: 1 };
+var stringArray3 = { type: "array", items: nonEmptyString2 };
+var actionBinding = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    label: nonEmptyString2,
+    actionId: nonEmptyString2,
+    resourceType: nonEmptyString2,
+    resourceId: nonEmptyString2,
+    input: { type: "object" },
+    requiresConfirmation: { type: "boolean" },
+    destructive: { type: "boolean" },
+    effects: stringArray3,
+    verification: stringArray3,
+    recovery: {
+      type: "object",
+      properties: {
+        mode: { enum: ["not_applicable", "retry", "compensating_action"] },
+        actionId: nonEmptyString2,
+        instructions: nonEmptyString2
+      },
+      required: ["mode", "instructions"],
+      additionalProperties: false
+    }
+  },
+  required: [
+    "id",
+    "label",
+    "actionId",
+    "resourceType",
+    "input",
+    "requiresConfirmation",
+    "destructive",
+    "effects",
+    "verification",
+    "recovery"
+  ],
+  additionalProperties: false
+};
+var dimension = {
+  type: "object",
+  properties: { key: nonEmptyString2, label: nonEmptyString2, value: nonEmptyString2 },
+  required: ["key", "label", "value"],
+  additionalProperties: false
+};
+var period = {
+  type: "object",
+  properties: {
+    start: nonEmptyString2,
+    end: nonEmptyString2,
+    timezone: nonEmptyString2
+  },
+  required: ["start", "end", "timezone"],
+  additionalProperties: false
+};
+var series = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    label: nonEmptyString2,
+    unit: nonEmptyString2,
+    points: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          timestamp: nonEmptyString2,
+          value: { type: "number" },
+          dimensions: { type: "array", items: dimension }
+        },
+        required: ["timestamp", "value", "dimensions"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["id", "label", "unit", "points"],
+  additionalProperties: false
+};
+var contribution = {
+  type: "object",
+  properties: {
+    summary: nonEmptyString2,
+    identity: {
+      type: "object",
+      properties: { iconSource: { const: "catalog" } },
+      required: ["iconSource"],
+      additionalProperties: false
+    },
+    workspaceSelector: {
+      type: "object",
+      properties: {
+        mode: { enum: ["none", "optional", "required"] },
+        resourceType: nonEmptyString2,
+        label: nonEmptyString2,
+        supportsMultiple: { type: "boolean" }
+      },
+      required: ["mode", "resourceType", "label", "supportsMultiple"],
+      additionalProperties: false
+    },
+    metricDefinitions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          unit: nonEmptyString2,
+          semantic: {
+            enum: ["gauge", "counter", "rate", "duration", "currency", "percentage"]
+          },
+          aggregation: {
+            enum: ["last", "sum", "average", "minimum", "maximum", "count", "distinct_count"]
+          }
+        },
+        required: ["key", "label", "description", "unit", "semantic", "aggregation"],
+        additionalProperties: false
+      }
+    },
+    seriesDefinitions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          metricKey: nonEmptyString2,
+          unit: nonEmptyString2
+        },
+        required: ["key", "label", "metricKey", "unit"],
+        additionalProperties: false
+      }
+    },
+    dimensions: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          valueType: { enum: ["string", "number", "boolean", "date", "datetime"] }
+        },
+        required: ["key", "label", "description", "valueType"],
+        additionalProperties: false
+      }
+    },
+    lifecycleStages: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          order: { type: "number" },
+          terminal: { type: "boolean" }
+        },
+        required: ["key", "label", "order", "terminal"],
+        additionalProperties: false
+      }
+    },
+    events: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2
+        },
+        required: ["key", "label", "description"],
+        additionalProperties: false
+      }
+    },
+    datasets: {
+      type: "array",
+      minItems: 1,
+      items: {
+        type: "object",
+        properties: {
+          id: nonEmptyString2,
+          label: nonEmptyString2,
+          description: nonEmptyString2,
+          grain: nonEmptyString2,
+          metricKeys: stringArray3,
+          seriesKeys: stringArray3,
+          dimensionKeys: stringArray3,
+          eventKeys: stringArray3,
+          actionIds: stringArray3
+        },
+        required: [
+          "id",
+          "label",
+          "description",
+          "grain",
+          "metricKeys",
+          "seriesKeys",
+          "dimensionKeys",
+          "eventKeys",
+          "actionIds"
+        ],
+        additionalProperties: false
+      }
+    },
+    compatibleVisualizations: {
+      type: "array",
+      minItems: 1,
+      items: {
+        enum: ["number", "line", "area", "bar", "donut", "table", "funnel", "timeline", "actions"]
+      }
+    },
+    defaultVisualization: {
+      enum: ["number", "line", "area", "bar", "donut", "table", "funnel", "timeline", "actions"]
+    }
+  },
+  required: [
+    "summary",
+    "identity",
+    "workspaceSelector",
+    "metricDefinitions",
+    "seriesDefinitions",
+    "dimensions",
+    "lifecycleStages",
+    "events",
+    "datasets",
+    "compatibleVisualizations",
+    "defaultVisualization"
+  ],
+  additionalProperties: false
+};
+var widgetItem = {
+  type: "object",
+  properties: {
+    id: nonEmptyString2,
+    version: nonEmptyString2,
+    appId: nonEmptyString2,
+    serviceName: nonEmptyString2,
+    lastUpdated: nonEmptyString2,
+    type: { enum: ["stats", "chart", "activity", "notifications", "actions"] },
+    presentation: {
+      type: "object",
+      properties: {
+        title: nonEmptyString2,
+        description: nonEmptyString2,
+        contexts: {
+          type: "array",
+          minItems: 1,
+          items: { enum: ["personal", "organization", "workspace", "resource"] }
+        },
+        supportedSizes: {
+          type: "array",
+          minItems: 1,
+          items: { enum: ["compact", "medium", "wide", "full"] }
+        },
+        defaultSize: { enum: ["compact", "medium", "wide", "full"] }
+      },
+      required: ["title", "contexts", "supportedSizes", "defaultSize"],
+      additionalProperties: false
+    },
+    resource: {
+      type: "object",
+      properties: {
+        resourceType: nonEmptyString2,
+        resourceId: nonEmptyString2,
+        requiredPermissions: stringArray3
+      },
+      required: ["resourceType", "requiredPermissions"],
+      additionalProperties: false
+    },
+    state: {
+      type: "object",
+      properties: {
+        status: { enum: ["ready", "empty", "unavailable", "stale", "error"] },
+        observedAt: nonEmptyString2,
+        lastSuccessfulAt: nonEmptyString2,
+        code: nonEmptyString2,
+        message: nonEmptyString2
+      },
+      required: ["status", "observedAt"],
+      additionalProperties: false
+    },
+    refresh: {
+      type: "object",
+      properties: {
+        intervalSeconds: { type: "number" },
+        timeoutSeconds: { type: "number" },
+        maxAgeSeconds: { type: "number" },
+        staleWhileRevalidateSeconds: { type: "number" }
+      },
+      required: ["intervalSeconds", "timeoutSeconds", "maxAgeSeconds", "staleWhileRevalidateSeconds"],
+      additionalProperties: false
+    },
+    configuration: {
+      type: "object",
+      properties: {
+        allowMultipleInstances: { type: "boolean" },
+        fields: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              key: nonEmptyString2,
+              label: nonEmptyString2,
+              type: { enum: ["string", "number", "boolean", "select", "multi-select", "date-range"] },
+              required: { type: "boolean" },
+              options: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: { value: nonEmptyString2, label: nonEmptyString2 },
+                  required: ["value", "label"],
+                  additionalProperties: false
+                }
+              }
+            },
+            required: ["key", "label", "type", "required"],
+            additionalProperties: false
+          }
+        },
+        defaults: { type: "object" }
+      },
+      required: ["allowMultipleInstances", "fields", "defaults"],
+      additionalProperties: false
+    },
+    drilldowns: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { id: nonEmptyString2, label: nonEmptyString2, href: nonEmptyString2 },
+        required: ["id", "label", "href"],
+        additionalProperties: false
+      }
+    },
+    controls: { type: "array", items: actionBinding },
+    localization: {
+      type: "object",
+      properties: {
+        locale: nonEmptyString2,
+        titleKey: nonEmptyString2,
+        descriptionKey: nonEmptyString2,
+        title: nonEmptyString2,
+        description: nonEmptyString2
+      },
+      required: ["locale", "titleKey"],
+      additionalProperties: false
+    },
+    accessibility: {
+      type: "object",
+      properties: { label: nonEmptyString2, description: nonEmptyString2 },
+      required: ["label"],
+      additionalProperties: false
+    },
+    contribution,
+    metrics: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          key: nonEmptyString2,
+          label: nonEmptyString2,
+          value: { type: "number" },
+          unit: nonEmptyString2,
+          semantic: {
+            enum: ["gauge", "counter", "rate", "duration", "currency", "percentage"]
+          },
+          aggregation: {
+            enum: ["last", "sum", "average", "minimum", "maximum", "count", "distinct_count"]
+          },
+          period,
+          dimensions: { type: "array", items: dimension },
+          series
+        },
+        required: ["key", "label", "value", "unit", "semantic", "aggregation", "period", "dimensions"],
+        additionalProperties: false
+      }
+    },
+    chartType: { enum: ["line", "bar", "area", "pie", "donut"] },
+    series: { type: "array", items: series },
+    activities: { type: "array", items: { type: "object" } },
+    notifications: { type: "array", items: { type: "object" } },
+    unreadCount: { type: "number" },
+    actions: { type: "array", items: actionBinding }
+  },
+  required: [
+    "id",
+    "version",
+    "appId",
+    "serviceName",
+    "lastUpdated",
+    "type",
+    "presentation",
+    "resource",
+    "state",
+    "refresh",
+    "configuration",
+    "drilldowns",
+    "controls",
+    "localization",
+    "accessibility",
+    "contribution"
+  ],
+  allOf: [
+    { if: { properties: { type: { const: "stats" } } }, then: { required: ["metrics"] } },
+    { if: { properties: { type: { const: "chart" } } }, then: { required: ["chartType", "series"] } },
+    { if: { properties: { type: { const: "activity" } } }, then: { required: ["activities"] } },
+    {
+      if: { properties: { type: { const: "notifications" } } },
+      then: { required: ["notifications", "unreadCount"] }
+    },
+    { if: { properties: { type: { const: "actions" } } }, then: { required: ["actions"] } }
+  ],
+  additionalProperties: false
+};
+var TOPOLO_WIDGET_OUTPUT_SCHEMA = Object.freeze({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  type: "object",
+  properties: {
+    success: { type: "boolean", const: true },
+    contractVersion: { type: "string", const: "3.0.0" },
+    appId: nonEmptyString2,
+    serviceName: nonEmptyString2,
+    generatedAt: nonEmptyString2,
+    widgets: { type: "array", minItems: 1, items: widgetItem },
+    workspace: {
+      anyOf: [
+        {
+          type: "object",
+          properties: {
+            id: { anyOf: [{ type: "string" }, { type: "number" }] },
+            name: nonEmptyString2
+          },
+          required: ["id", "name"],
+          additionalProperties: true
+        },
+        { type: "null" }
+      ]
+    },
+    workspaces: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          id: { anyOf: [{ type: "string" }, { type: "number" }] },
+          name: nonEmptyString2,
+          isDefault: { type: "boolean" }
+        },
+        required: ["id", "name"],
+        additionalProperties: false
+      }
+    }
+  },
+  required: ["success", "contractVersion", "appId", "serviceName", "generatedAt", "widgets"],
+  additionalProperties: false
+});
+function isTopoloWidgetOutputSchema(schema) {
+  if (!isRecord6(schema) || !isRecord6(schema.properties)) return false;
+  const properties = schema.properties;
+  const widgetItemSchema = isRecord6(properties.widgets) && isRecord6(properties.widgets.items) ? properties.widgets.items : void 0;
+  const widgetProperties = widgetItemSchema && isRecord6(widgetItemSchema.properties) ? widgetItemSchema.properties : void 0;
+  const contributionSchema = widgetProperties && isRecord6(widgetProperties.contribution) ? widgetProperties.contribution : void 0;
+  const contractVersion = isRecord6(properties.contractVersion) ? properties.contractVersion.const : void 0;
+  return schema.type === "object" && contractVersion === "3.0.0" && isRecord6(properties.widgets) && properties.widgets.type === "array" && widgetItemSchema?.type === "object" && hasRequired(schema, "contractVersion") && hasRequired(schema, "widgets") && hasRequired(widgetItemSchema, "contribution") && hasRequired(contributionSchema, "datasets") && hasRequired(contributionSchema, "compatibleVisualizations") && hasRequired(contributionSchema, "defaultVisualization");
+}
+function isRecord6(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasRequired(schema, field) {
+  return isRecord6(schema) && Array.isArray(schema.required) && schema.required.includes(field);
+}
+
 // src/index.ts
 function createTopolo(options) {
   const client = new TopoloClient(options);
@@ -3700,6 +4378,7 @@ export {
   TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION,
   TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_OUTPUT_SCHEMA,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
@@ -3737,6 +4416,7 @@ export {
   extractTopoloServiceErrorDetails,
   formatDirectoryApplicationIds,
   friendlyAppId,
+  isTopoloWidgetOutputSchema,
   listApplicationDirectory,
   parseTopoloActionUploadContract,
   preferExactActionMatches,