@topolo/sdk 0.14.2 → 0.14.3

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   TOPOLO_RUNTIME_ENVIRONMENTS: () => TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION: () => TOPOLO_WIDGET_CONTRACT_VERSION,
   TOPOLO_WIDGET_ENDPOINT: () => TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_OUTPUT_SCHEMA: () => TOPOLO_WIDGET_OUTPUT_SCHEMA,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS: () => TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError: () => TopoloAuthError,
   TopoloClient: () => TopoloClient,
@@ -66,6 +67,7 @@ __export(index_exports, {
   extractTopoloServiceErrorDetails: () => extractTopoloServiceErrorDetails,
   formatDirectoryApplicationIds: () => formatDirectoryApplicationIds,
   friendlyAppId: () => friendlyAppId,
+  isTopoloWidgetOutputSchema: () => isTopoloWidgetOutputSchema,
   listApplicationDirectory: () => listApplicationDirectory,
   parseTopoloActionUploadContract: () => parseTopoloActionUploadContract,
   preferExactActionMatches: () => preferExactActionMatches,
@@ -3736,22 +3738,22 @@ function validateRuntimeSemantics(widget, contributionPath, declared, errors) {
       validateSeriesDimensions(metric.series, declared.dimensionKeys, contributionPath, errors);
     }
   }
-  const series = Array.isArray(widget.series) ? widget.series : [];
-  for (const item of series) {
+  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(series, known, path, errors) {
-  if (!Array.isArray(series.points)) return;
-  for (const point of series.points) if (isRecord5(point)) validateRuntimeDimensions(point.dimensions, known, path, 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 dimension of value) {
-    if (isRecord5(dimension) && typeof dimension.key === "string" && !known.has(dimension.key)) {
-      errors.push(`${path}.dimensions is missing runtime dimension ${dimension.key}`);
+  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}`);
     }
   }
 }
@@ -3788,12 +3790,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) {
@@ -3807,7 +3809,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;
@@ -4005,6 +4007,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);
@@ -4026,6 +4500,7 @@ function createTopolo(options) {
   TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION,
   TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_OUTPUT_SCHEMA,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
@@ -4063,6 +4538,7 @@ function createTopolo(options) {
   extractTopoloServiceErrorDetails,
   formatDirectoryApplicationIds,
   friendlyAppId,
+  isTopoloWidgetOutputSchema,
   listApplicationDirectory,
   parseTopoloActionUploadContract,
   preferExactActionMatches,

package/dist/index.d.cts

@@ -1574,6 +1574,10 @@ declare function defineTopoloActionsWidget(widget: Omit<TopoloActionsWidget, "ty
 declare function createTopoloWidgetResponse({ appId, serviceName, widgets, now, }: TopoloWidgetResponseOptions): TopoloWidgetApiSuccessResponse;
 declare function createTopoloWidgetError({ appId, serviceName, code, message, retryable, retryAfter, now, }: TopoloWidgetErrorResponseOptions): TopoloWidgetApiErrorResponse;
 
+type TopoloJsonSchema = Readonly<Record<string, unknown>>;
+declare const TOPOLO_WIDGET_OUTPUT_SCHEMA: TopoloJsonSchema;
+declare function isTopoloWidgetOutputSchema(schema: unknown): boolean;
+
 /**
  * Convenience factory that returns a ready-to-use typed Topolo client plus
  * domain module surfaces (identity, crm, ...).
@@ -1589,4 +1593,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -1574,6 +1574,10 @@ declare function defineTopoloActionsWidget(widget: Omit<TopoloActionsWidget, "ty
 declare function createTopoloWidgetResponse({ appId, serviceName, widgets, now, }: TopoloWidgetResponseOptions): TopoloWidgetApiSuccessResponse;
 declare function createTopoloWidgetError({ appId, serviceName, code, message, retryable, retryAfter, now, }: TopoloWidgetErrorResponseOptions): TopoloWidgetApiErrorResponse;
 
+type TopoloJsonSchema = Readonly<Record<string, unknown>>;
+declare const TOPOLO_WIDGET_OUTPUT_SCHEMA: TopoloJsonSchema;
+declare function isTopoloWidgetOutputSchema(schema: unknown): boolean;
+
 /**
  * Convenience factory that returns a ready-to-use typed Topolo client plus
  * domain module surfaces (identity, crm, ...).
@@ -1589,4 +1593,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, type ActionContractManifest, type ActionContractSource, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.js

@@ -3652,22 +3652,22 @@ function validateRuntimeSemantics(widget, contributionPath, declared, errors) {
       validateSeriesDimensions(metric.series, declared.dimensionKeys, contributionPath, errors);
     }
   }
-  const series = Array.isArray(widget.series) ? widget.series : [];
-  for (const item of series) {
+  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(series, known, path, errors) {
-  if (!Array.isArray(series.points)) return;
-  for (const point of series.points) if (isRecord5(point)) validateRuntimeDimensions(point.dimensions, known, path, 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 dimension of value) {
-    if (isRecord5(dimension) && typeof dimension.key === "string" && !known.has(dimension.key)) {
-      errors.push(`${path}.dimensions is missing runtime dimension ${dimension.key}`);
+  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}`);
     }
   }
 }
@@ -3704,12 +3704,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) {
@@ -3723,7 +3723,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;
@@ -3921,6 +3921,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);
@@ -3941,6 +4413,7 @@ export {
   TOPOLO_RUNTIME_ENVIRONMENTS,
   TOPOLO_WIDGET_CONTRACT_VERSION,
   TOPOLO_WIDGET_ENDPOINT,
+  TOPOLO_WIDGET_OUTPUT_SCHEMA,
   TOPOLO_WIDGET_REFRESH_INTERVAL_MS,
   TopoloAuthError,
   TopoloClient,
@@ -3978,6 +4451,7 @@ export {
   extractTopoloServiceErrorDetails,
   formatDirectoryApplicationIds,
   friendlyAppId,
+  isTopoloWidgetOutputSchema,
   listApplicationDirectory,
   parseTopoloActionUploadContract,
   preferExactActionMatches,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@topolo/sdk",
-  "version": "0.14.2",
-  "topoloPublishedVersion": "0.14.2",
+  "version": "0.14.3",
+  "topoloPublishedVersion": "0.14.3",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",