@topolo/sdk 0.12.0 → 0.14.0

package/dist/index.cjs

@@ -1229,16 +1229,29 @@ var TopoloClient = class _TopoloClient {
         clearTimeout(timeoutId);
       }
     };
+    const fetchWithReadRetry = async () => {
+      const maxAttempts = method === "GET" ? 2 : 1;
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+          return await fetchOnce();
+        } catch (error) {
+          const transportFailure = !(error instanceof TopoloSdkError) && !opts.signal?.aborted;
+          if (!transportFailure || attempt === maxAttempts) throw error;
+          await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+      }
+      throw new TopoloSdkError("network_error", "Topolo read retry loop exhausted.");
+    };
     let res;
     try {
       const attemptedCredential = this.credential;
-      res = await fetchOnce();
+      res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
           applyAuthHeaders(headers, refreshed);
-          res = await fetchOnce();
+          res = await fetchWithReadRetry();
         }
       }
     } catch (err) {
@@ -1890,26 +1903,29 @@ var TopoloClient = class _TopoloClient {
 };
 function validateActionResource(entry, resource) {
   const permissionName = entry.permissionName || entry.requiredPermission.split(".").at(-1) || "";
-  if (!permissionName.startsWith("workspace:")) return null;
+  const declaredContext = entry.agentContract?.resourceContext;
+  const declaredKind = typeof declaredContext?.kind === "string" ? declaredContext.kind.trim() : "";
+  const expectedType = declaredKind || (permissionName.startsWith("workspace:") ? "workspace" : "");
+  if (!expectedType || declaredContext?.required === false && !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."
+      message: `Select resourceType "${expectedType}" with the application resource catalog before planning or calling this action.`
     };
   }
-  if (resource.resourceType !== "workspace") {
+  if (resource.resourceType !== expectedType) {
     return {
       path: "$.resource.resourceType",
       code: "const",
-      message: 'This action requires resourceType "workspace".'
+      message: `This action requires resourceType "${expectedType}".`
     };
   }
   if (!resource.resourceId.trim()) {
     return {
       path: "$.resource.resourceId",
       code: "required",
-      message: "This action requires a workspace resourceId."
+      message: `This action requires a ${expectedType} resourceId.`
     };
   }
   return null;
@@ -2283,7 +2299,8 @@ function compactActionCatalogEntry(action) {
     agentAccess: action.agentAccess ?? (action.requiresConfirmation ? "confirm" : action.readOnly ? "auto" : "confirm"),
     requiredPermission: action.requiredPermission,
     requiredInput: required,
-    resourceType: action.agentContract?.resource?.kind ?? null,
+    resourceType: action.agentContract?.resourceContext?.kind ?? (action.permissionName.startsWith("workspace:") ? "workspace" : null),
+    resultResourceType: action.agentContract?.resource?.kind ?? null,
     exampleInput: example.value,
     exampleInputAvailable: example.available,
     docsUrl: action.agentContract?.docsUrl ?? null
@@ -3304,7 +3321,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"];
@@ -3315,6 +3332,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 = [];
@@ -3365,6 +3385,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));
@@ -3494,12 +3515,216 @@ function validateLocalization(value, path, errors) {
   nonEmptyString(value.locale, `${path}.locale`, errors);
   nonEmptyString(value.titleKey, `${path}.titleKey`, errors);
   optionalNonEmptyString(value.descriptionKey, `${path}.descriptionKey`, errors);
+  optionalNonEmptyString(value.title, `${path}.title`, errors);
+  optionalNonEmptyString(value.description, `${path}.description`, 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 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 series = Array.isArray(widget.series) ? widget.series : [];
+  for (const item of series) {
+    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 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}`);
+    }
+  }
+}
+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) => {
@@ -3667,7 +3892,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" };
 }

package/dist/index.d.cts

@@ -254,6 +254,10 @@ interface TopoloActionCatalogEntry {
 }
 interface TopoloActionAgentContract {
     docsUrl?: string;
+    resourceContext?: {
+        kind?: string;
+        required?: boolean;
+    };
     resource?: {
         kind?: string;
         idPath?: string;
@@ -513,6 +517,7 @@ declare function compactActionCatalogEntry(action: TopoloActionCatalogEntry): {
     requiredPermission: string;
     requiredInput: string[];
     resourceType: string | null;
+    resultResourceType: string | null;
     exampleInput: Record<string, unknown> | null;
     exampleInputAvailable: boolean;
     docsUrl: string | null;
@@ -1252,7 +1257,7 @@ declare function validateTopoloWidgetResponse(response: unknown): TopoloWidgetVa
 
 declare const TOPOLO_WIDGET_ENDPOINT = "/api/widget";
 declare const TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 60000;
-declare const TOPOLO_WIDGET_CONTRACT_VERSION: "2.0.0";
+declare const TOPOLO_WIDGET_CONTRACT_VERSION: "3.0.0";
 type TopoloWidgetType = "stats" | "chart" | "activity" | "notifications" | "actions";
 type TopoloWidgetContext = "personal" | "organization" | "workspace" | "resource";
 type TopoloWidgetSize = "compact" | "medium" | "wide" | "full";
@@ -1325,11 +1330,85 @@ interface TopoloWidgetLocalization {
     locale: string;
     titleKey: string;
     descriptionKey?: string;
+    /**
+     * English source text for `titleKey`. Hosts already fall back to their own
+     * title when the key misses, so this changes no rendering — it exists so the
+     * key HAS a source string: the i18n extractor reads a sibling literal named
+     * after the key's field, and without one the key never reaches a catalog and
+     * cannot be translated into any locale.
+     */
+    title?: string;
+    /** English source text for `descriptionKey`. See `title`. */
+    description?: string;
 }
 interface TopoloWidgetAccessibility {
     label: string;
     description?: string;
 }
+type TopoloWidgetVisualizationFamily = "number" | "line" | "area" | "bar" | "donut" | "table" | "funnel" | "timeline" | "actions";
+interface TopoloWidgetMetricDefinition {
+    key: string;
+    label: string;
+    description: string;
+    unit: string;
+    semantic: TopoloWidgetMetricSemantic;
+    aggregation: TopoloWidgetMetricAggregation;
+}
+interface TopoloWidgetSeriesDefinition {
+    key: string;
+    label: string;
+    metricKey: string;
+    unit: string;
+}
+interface TopoloWidgetDimensionDefinition {
+    key: string;
+    label: string;
+    description: string;
+    valueType: "string" | "number" | "boolean" | "date" | "datetime";
+}
+interface TopoloWidgetLifecycleStage {
+    key: string;
+    label: string;
+    order: number;
+    terminal: boolean;
+}
+interface TopoloWidgetEventDefinition {
+    key: string;
+    label: string;
+    description: string;
+}
+interface TopoloWidgetDatasetDefinition {
+    id: string;
+    label: string;
+    description: string;
+    grain: string;
+    metricKeys: string[];
+    seriesKeys: string[];
+    dimensionKeys: string[];
+    eventKeys: string[];
+    actionIds: string[];
+}
+interface TopoloWidgetWorkspaceSelector {
+    mode: "none" | "optional" | "required";
+    resourceType: string;
+    label: string;
+    supportsMultiple: boolean;
+}
+interface TopoloWidgetContribution {
+    summary: string;
+    identity: {
+        iconSource: "catalog";
+    };
+    workspaceSelector: TopoloWidgetWorkspaceSelector;
+    metricDefinitions: TopoloWidgetMetricDefinition[];
+    seriesDefinitions: TopoloWidgetSeriesDefinition[];
+    dimensions: TopoloWidgetDimensionDefinition[];
+    lifecycleStages: TopoloWidgetLifecycleStage[];
+    events: TopoloWidgetEventDefinition[];
+    datasets: TopoloWidgetDatasetDefinition[];
+    compatibleVisualizations: TopoloWidgetVisualizationFamily[];
+    defaultVisualization: TopoloWidgetVisualizationFamily;
+}
 interface TopoloWidgetBase {
     id: string;
     version: string;
@@ -1347,6 +1426,7 @@ interface TopoloWidgetBase {
     controls: TopoloWidgetActionBinding[];
     localization: TopoloWidgetLocalization;
     accessibility: TopoloWidgetAccessibility;
+    contribution: TopoloWidgetContribution;
 }
 type TopoloWidgetMetricSemantic = "gauge" | "counter" | "rate" | "duration" | "currency" | "percentage";
 type TopoloWidgetMetricAggregation = "last" | "sum" | "average" | "minimum" | "maximum" | "count" | "distinct_count";
@@ -1509,4 +1589,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 TopoloWidgetDimension, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, 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_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 };

package/dist/index.d.ts

@@ -254,6 +254,10 @@ interface TopoloActionCatalogEntry {
 }
 interface TopoloActionAgentContract {
     docsUrl?: string;
+    resourceContext?: {
+        kind?: string;
+        required?: boolean;
+    };
     resource?: {
         kind?: string;
         idPath?: string;
@@ -513,6 +517,7 @@ declare function compactActionCatalogEntry(action: TopoloActionCatalogEntry): {
     requiredPermission: string;
     requiredInput: string[];
     resourceType: string | null;
+    resultResourceType: string | null;
     exampleInput: Record<string, unknown> | null;
     exampleInputAvailable: boolean;
     docsUrl: string | null;
@@ -1252,7 +1257,7 @@ declare function validateTopoloWidgetResponse(response: unknown): TopoloWidgetVa
 
 declare const TOPOLO_WIDGET_ENDPOINT = "/api/widget";
 declare const TOPOLO_WIDGET_REFRESH_INTERVAL_MS = 60000;
-declare const TOPOLO_WIDGET_CONTRACT_VERSION: "2.0.0";
+declare const TOPOLO_WIDGET_CONTRACT_VERSION: "3.0.0";
 type TopoloWidgetType = "stats" | "chart" | "activity" | "notifications" | "actions";
 type TopoloWidgetContext = "personal" | "organization" | "workspace" | "resource";
 type TopoloWidgetSize = "compact" | "medium" | "wide" | "full";
@@ -1325,11 +1330,85 @@ interface TopoloWidgetLocalization {
     locale: string;
     titleKey: string;
     descriptionKey?: string;
+    /**
+     * English source text for `titleKey`. Hosts already fall back to their own
+     * title when the key misses, so this changes no rendering — it exists so the
+     * key HAS a source string: the i18n extractor reads a sibling literal named
+     * after the key's field, and without one the key never reaches a catalog and
+     * cannot be translated into any locale.
+     */
+    title?: string;
+    /** English source text for `descriptionKey`. See `title`. */
+    description?: string;
 }
 interface TopoloWidgetAccessibility {
     label: string;
     description?: string;
 }
+type TopoloWidgetVisualizationFamily = "number" | "line" | "area" | "bar" | "donut" | "table" | "funnel" | "timeline" | "actions";
+interface TopoloWidgetMetricDefinition {
+    key: string;
+    label: string;
+    description: string;
+    unit: string;
+    semantic: TopoloWidgetMetricSemantic;
+    aggregation: TopoloWidgetMetricAggregation;
+}
+interface TopoloWidgetSeriesDefinition {
+    key: string;
+    label: string;
+    metricKey: string;
+    unit: string;
+}
+interface TopoloWidgetDimensionDefinition {
+    key: string;
+    label: string;
+    description: string;
+    valueType: "string" | "number" | "boolean" | "date" | "datetime";
+}
+interface TopoloWidgetLifecycleStage {
+    key: string;
+    label: string;
+    order: number;
+    terminal: boolean;
+}
+interface TopoloWidgetEventDefinition {
+    key: string;
+    label: string;
+    description: string;
+}
+interface TopoloWidgetDatasetDefinition {
+    id: string;
+    label: string;
+    description: string;
+    grain: string;
+    metricKeys: string[];
+    seriesKeys: string[];
+    dimensionKeys: string[];
+    eventKeys: string[];
+    actionIds: string[];
+}
+interface TopoloWidgetWorkspaceSelector {
+    mode: "none" | "optional" | "required";
+    resourceType: string;
+    label: string;
+    supportsMultiple: boolean;
+}
+interface TopoloWidgetContribution {
+    summary: string;
+    identity: {
+        iconSource: "catalog";
+    };
+    workspaceSelector: TopoloWidgetWorkspaceSelector;
+    metricDefinitions: TopoloWidgetMetricDefinition[];
+    seriesDefinitions: TopoloWidgetSeriesDefinition[];
+    dimensions: TopoloWidgetDimensionDefinition[];
+    lifecycleStages: TopoloWidgetLifecycleStage[];
+    events: TopoloWidgetEventDefinition[];
+    datasets: TopoloWidgetDatasetDefinition[];
+    compatibleVisualizations: TopoloWidgetVisualizationFamily[];
+    defaultVisualization: TopoloWidgetVisualizationFamily;
+}
 interface TopoloWidgetBase {
     id: string;
     version: string;
@@ -1347,6 +1426,7 @@ interface TopoloWidgetBase {
     controls: TopoloWidgetActionBinding[];
     localization: TopoloWidgetLocalization;
     accessibility: TopoloWidgetAccessibility;
+    contribution: TopoloWidgetContribution;
 }
 type TopoloWidgetMetricSemantic = "gauge" | "counter" | "rate" | "duration" | "currency" | "percentage";
 type TopoloWidgetMetricAggregation = "last" | "sum" | "average" | "minimum" | "maximum" | "count" | "distinct_count";
@@ -1509,4 +1589,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 TopoloWidgetDimension, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, 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_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 };

package/dist/index.js

@@ -1145,16 +1145,29 @@ var TopoloClient = class _TopoloClient {
         clearTimeout(timeoutId);
       }
     };
+    const fetchWithReadRetry = async () => {
+      const maxAttempts = method === "GET" ? 2 : 1;
+      for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        try {
+          return await fetchOnce();
+        } catch (error) {
+          const transportFailure = !(error instanceof TopoloSdkError) && !opts.signal?.aborted;
+          if (!transportFailure || attempt === maxAttempts) throw error;
+          await new Promise((resolve) => setTimeout(resolve, 250));
+        }
+      }
+      throw new TopoloSdkError("network_error", "Topolo read retry loop exhausted.");
+    };
     let res;
     try {
       const attemptedCredential = this.credential;
-      res = await fetchOnce();
+      res = await fetchWithReadRetry();
       if (res.status === 401 && attemptedCredential.kind === "access_token" && this.refreshCredential) {
         await res.body?.cancel().catch(() => void 0);
         const refreshed = await this.refreshRejectedAccessToken(attemptedCredential.accessToken);
         if (refreshed) {
           applyAuthHeaders(headers, refreshed);
-          res = await fetchOnce();
+          res = await fetchWithReadRetry();
         }
       }
     } catch (err) {
@@ -1806,26 +1819,29 @@ var TopoloClient = class _TopoloClient {
 };
 function validateActionResource(entry, resource) {
   const permissionName = entry.permissionName || entry.requiredPermission.split(".").at(-1) || "";
-  if (!permissionName.startsWith("workspace:")) return null;
+  const declaredContext = entry.agentContract?.resourceContext;
+  const declaredKind = typeof declaredContext?.kind === "string" ? declaredContext.kind.trim() : "";
+  const expectedType = declaredKind || (permissionName.startsWith("workspace:") ? "workspace" : "");
+  if (!expectedType || declaredContext?.required === false && !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."
+      message: `Select resourceType "${expectedType}" with the application resource catalog before planning or calling this action.`
     };
   }
-  if (resource.resourceType !== "workspace") {
+  if (resource.resourceType !== expectedType) {
     return {
       path: "$.resource.resourceType",
       code: "const",
-      message: 'This action requires resourceType "workspace".'
+      message: `This action requires resourceType "${expectedType}".`
     };
   }
   if (!resource.resourceId.trim()) {
     return {
       path: "$.resource.resourceId",
       code: "required",
-      message: "This action requires a workspace resourceId."
+      message: `This action requires a ${expectedType} resourceId.`
     };
   }
   return null;
@@ -2199,7 +2215,8 @@ function compactActionCatalogEntry(action) {
     agentAccess: action.agentAccess ?? (action.requiresConfirmation ? "confirm" : action.readOnly ? "auto" : "confirm"),
     requiredPermission: action.requiredPermission,
     requiredInput: required,
-    resourceType: action.agentContract?.resource?.kind ?? null,
+    resourceType: action.agentContract?.resourceContext?.kind ?? (action.permissionName.startsWith("workspace:") ? "workspace" : null),
+    resultResourceType: action.agentContract?.resource?.kind ?? null,
     exampleInput: example.value,
     exampleInputAvailable: example.available,
     docsUrl: action.agentContract?.docsUrl ?? null
@@ -3220,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"];
@@ -3231,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 = [];
@@ -3281,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));
@@ -3410,12 +3431,216 @@ function validateLocalization(value, path, errors) {
   nonEmptyString(value.locale, `${path}.locale`, errors);
   nonEmptyString(value.titleKey, `${path}.titleKey`, errors);
   optionalNonEmptyString(value.descriptionKey, `${path}.descriptionKey`, errors);
+  optionalNonEmptyString(value.title, `${path}.title`, errors);
+  optionalNonEmptyString(value.description, `${path}.description`, 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 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 series = Array.isArray(widget.series) ? widget.series : [];
+  for (const item of series) {
+    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 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}`);
+    }
+  }
+}
+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) => {
@@ -3583,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" };
 }

package/package.json

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