@topolo/sdk 0.8.3 → 0.9.0

package/dist/index.js

@@ -2098,6 +2098,264 @@ function firstString(...values) {
   return null;
 }
 
+// src/action-schema.ts
+var SUPPORTED_SCHEMA_KEYWORDS = /* @__PURE__ */ new Set([
+  "$schema",
+  "$id",
+  "$ref",
+  "$defs",
+  "definitions",
+  "title",
+  "description",
+  "default",
+  "examples",
+  "deprecated",
+  "readOnly",
+  "writeOnly",
+  "type",
+  "nullable",
+  "const",
+  "enum",
+  "allOf",
+  "anyOf",
+  "oneOf",
+  "properties",
+  "required",
+  "additionalProperties",
+  "propertyNames",
+  "minProperties",
+  "maxProperties",
+  "items",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "format",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf"
+]);
+function validateTopoloActionInput(schema, input) {
+  const schemaIssue = inspectSchema(schema, "$", schema, 0);
+  if (schemaIssue) return { valid: false, errors: [schemaIssue] };
+  const errors = [];
+  validateNode(schema, input, "$", schema, errors, 0);
+  return { valid: errors.length === 0, errors };
+}
+function inspectSchema(schema, path, root, depth) {
+  if (depth > 128) return { path, code: "schema_depth", message: "Schema recursion exceeded 128 levels." };
+  const unsupportedKeyword = Object.keys(schema).find((keyword) => !SUPPORTED_SCHEMA_KEYWORDS.has(keyword));
+  if (unsupportedKeyword) {
+    return { path, code: "unsupported_schema_keyword", message: `Action schema uses unsupported keyword ${unsupportedKeyword}.` };
+  }
+  if (typeof schema.format === "string" && !["uri", "email", "date-time"].includes(schema.format)) {
+    return { path, code: "unsupported_schema_format", message: `Action schema uses unsupported format ${schema.format}.` };
+  }
+  if (typeof schema.$ref === "string" && !resolveLocalReference(root, schema.$ref)) {
+    return { path, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` };
+  }
+  const children = [];
+  if (isRecord(schema.properties)) children.push(...Object.entries(schema.properties));
+  if (isRecord(schema.$defs)) children.push(...Object.entries(schema.$defs));
+  if (isRecord(schema.definitions)) children.push(...Object.entries(schema.definitions));
+  children.push(
+    ["additionalProperties", schema.additionalProperties],
+    ["propertyNames", schema.propertyNames],
+    ["items", schema.items],
+    ...arraySchemaEntries("allOf", schema.allOf),
+    ...arraySchemaEntries("anyOf", schema.anyOf),
+    ...arraySchemaEntries("oneOf", schema.oneOf)
+  );
+  for (const [key, child] of children) {
+    if (!isRecord(child)) continue;
+    const issue = inspectSchema(child, `${path}.${key}`, root, depth + 1);
+    if (issue) return issue;
+  }
+  return null;
+}
+function arraySchemaEntries(keyword, value) {
+  return Array.isArray(value) ? value.map((candidate, index) => [`${keyword}[${index}]`, candidate]) : [];
+}
+function validateNode(schema, value, path, root, errors, depth) {
+  if (depth > 128) {
+    errors.push({ path, code: "schema_depth", message: "Schema recursion exceeded 128 levels." });
+    return;
+  }
+  if (typeof schema.$ref === "string") {
+    const resolved = resolveLocalReference(root, schema.$ref);
+    if (!resolved) {
+      errors.push({ path, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` });
+      return;
+    }
+    validateNode(resolved, value, path, root, errors, depth + 1);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const candidate of schema.allOf) {
+      if (isRecord(candidate)) validateNode(candidate, value, path, root, errors, depth + 1);
+    }
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some((candidate) => candidateMatches(candidate, value, root, depth))) {
+    errors.push({ path, code: "any_of", message: "Value does not match any allowed schema." });
+    return;
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter((candidate) => candidateMatches(candidate, value, root, depth)).length;
+    if (matches !== 1) {
+      errors.push({ path, code: "one_of", message: "Value must match exactly one allowed schema." });
+      return;
+    }
+  }
+  if (value === null && schema.nullable === true) return;
+  if (Object.prototype.hasOwnProperty.call(schema, "const") && !sameJsonValue(value, schema.const)) {
+    errors.push({ path, code: "const", message: `Value must equal ${JSON.stringify(schema.const)}.` });
+    return;
+  }
+  if (Array.isArray(schema.enum) && !schema.enum.some((candidate) => sameJsonValue(value, candidate))) {
+    errors.push({ path, code: "enum", message: `Value must be one of ${schema.enum.map((item) => JSON.stringify(item)).join(", ")}.` });
+    return;
+  }
+  if (!matchesType(schema.type, value)) {
+    errors.push({ path, code: "type", message: `Expected ${String(schema.type)}.` });
+    return;
+  }
+  if (typeof value === "string") validateString(schema, value, path, errors);
+  if (typeof value === "number") validateNumber(schema, value, path, errors);
+  if (Array.isArray(value)) validateArray(schema, value, path, root, errors, depth);
+  if (isRecord(value)) validateObject(schema, value, path, root, errors, depth);
+}
+function validateObject(schema, value, path, root, errors, depth) {
+  if (typeof schema.minProperties === "number" && Object.keys(value).length < schema.minProperties) {
+    errors.push({ path, code: "min_properties", message: `Expected at least ${schema.minProperties} properties.` });
+  }
+  if (typeof schema.maxProperties === "number" && Object.keys(value).length > schema.maxProperties) {
+    errors.push({ path, code: "max_properties", message: `Expected at most ${schema.maxProperties} properties.` });
+  }
+  const properties = isRecord(schema.properties) ? schema.properties : {};
+  const required = Array.isArray(schema.required) ? schema.required.map(String) : [];
+  for (const key of required) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) {
+      errors.push({ path: `${path}.${key}`, code: "required", message: "Required property is missing." });
+    }
+  }
+  if (isRecord(schema.propertyNames)) {
+    for (const key of Object.keys(value)) {
+      validateNode(schema.propertyNames, key, `${path}.${key}`, root, errors, depth + 1);
+    }
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (isRecord(childSchema)) {
+      validateNode(childSchema, child, `${path}.${key}`, root, errors, depth + 1);
+    } else if (schema.additionalProperties === false) {
+      errors.push({ path: `${path}.${key}`, code: "additional_property", message: "Property is not declared by the action schema." });
+    } else if (isRecord(schema.additionalProperties)) {
+      validateNode(schema.additionalProperties, child, `${path}.${key}`, root, errors, depth + 1);
+    }
+  }
+}
+function validateArray(schema, value, path, root, errors, depth) {
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    errors.push({ path, code: "min_items", message: `Expected at least ${schema.minItems} items.` });
+  }
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    errors.push({ path, code: "max_items", message: `Expected at most ${schema.maxItems} items.` });
+  }
+  if (schema.uniqueItems === true) {
+    const unique = new Set(value.map((item) => JSON.stringify(item)));
+    if (unique.size !== value.length) errors.push({ path, code: "unique_items", message: "Expected every item to be unique." });
+  }
+  if (isRecord(schema.items)) {
+    value.forEach((item, index) => validateNode(schema.items, item, `${path}[${index}]`, root, errors, depth + 1));
+  }
+}
+function validateString(schema, value, path, errors) {
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    errors.push({ path, code: "min_length", message: `Expected at least ${schema.minLength} characters.` });
+  }
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    errors.push({ path, code: "max_length", message: `Expected at most ${schema.maxLength} characters.` });
+  }
+  if (typeof schema.pattern === "string") {
+    try {
+      if (!new RegExp(schema.pattern).test(value)) errors.push({ path, code: "pattern", message: "Value does not match the required pattern." });
+    } catch {
+      errors.push({ path, code: "invalid_schema_pattern", message: "Action schema contains an invalid pattern." });
+    }
+  }
+  if (schema.format === "uri" && !isUrl(value)) errors.push({ path, code: "format_uri", message: "Expected an absolute URL." });
+  if (schema.format === "email" && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) errors.push({ path, code: "format_email", message: "Expected an email address." });
+  if (schema.format === "date-time" && !isDateTime(value)) errors.push({ path, code: "format_date_time", message: "Expected an ISO-8601 date-time." });
+}
+function validateNumber(schema, value, path, errors) {
+  if (typeof schema.minimum === "number" && value < schema.minimum) errors.push({ path, code: "minimum", message: `Expected a value of at least ${schema.minimum}.` });
+  if (typeof schema.maximum === "number" && value > schema.maximum) errors.push({ path, code: "maximum", message: `Expected a value of at most ${schema.maximum}.` });
+  const exclusiveMinimum = typeof schema.exclusiveMinimum === "number" ? schema.exclusiveMinimum : schema.exclusiveMinimum === true && typeof schema.minimum === "number" ? schema.minimum : null;
+  const exclusiveMaximum = typeof schema.exclusiveMaximum === "number" ? schema.exclusiveMaximum : schema.exclusiveMaximum === true && typeof schema.maximum === "number" ? schema.maximum : null;
+  if (exclusiveMinimum !== null && value <= exclusiveMinimum) {
+    errors.push({ path, code: "exclusive_minimum", message: `Expected a value greater than ${exclusiveMinimum}.` });
+  }
+  if (exclusiveMaximum !== null && value >= exclusiveMaximum) {
+    errors.push({ path, code: "exclusive_maximum", message: `Expected a value less than ${exclusiveMaximum}.` });
+  }
+  if (typeof schema.multipleOf === "number" && !isMultipleOf(value, schema.multipleOf)) {
+    errors.push({ path, code: "multiple_of", message: `Expected a multiple of ${schema.multipleOf}.` });
+  }
+}
+function candidateMatches(candidate, value, root, depth) {
+  if (!isRecord(candidate)) return false;
+  const issues = [];
+  validateNode(candidate, value, "$", root, issues, depth + 1);
+  return issues.length === 0;
+}
+function resolveLocalReference(root, reference) {
+  if (!reference.startsWith("#/")) return null;
+  let current = root;
+  for (const token of reference.slice(2).split("/").map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"))) {
+    if (Array.isArray(current)) {
+      if (!/^\d+$/.test(token) || Number(token) >= current.length) return null;
+      current = current[Number(token)];
+      continue;
+    }
+    if (!isRecord(current) || !Object.prototype.hasOwnProperty.call(current, token)) return null;
+    current = current[token];
+  }
+  return isRecord(current) ? current : null;
+}
+function matchesType(type, value) {
+  if (type === void 0) return true;
+  if (Array.isArray(type)) return type.some((candidate) => matchesType(candidate, value));
+  if (type === "null") return value === null;
+  if (type === "array") return Array.isArray(value);
+  if (type === "object") return isRecord(value);
+  if (type === "integer") return typeof value === "number" && Number.isInteger(value);
+  return typeof value === type;
+}
+function sameJsonValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+function isRecord(value) {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function isUrl(value) {
+  try {
+    return Boolean(new URL(value).protocol);
+  } catch {
+    return false;
+  }
+}
+function isDateTime(value) {
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
+}
+function isMultipleOf(value, divisor) {
+  if (!(divisor > 0)) return false;
+  const quotient = value / divisor;
+  return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
+}
+
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
@@ -2318,7 +2576,10 @@ var TopoloClient = class _TopoloClient {
       serviceKey,
       overrides: this.serviceUrls
     });
-    return baseUrl ? { serviceKey, baseUrl } : null;
+    if (baseUrl) return { serviceKey, baseUrl };
+    const actionPage = await this.searchActions({ service: match.appId, limit: 1 }).catch(() => null);
+    const actionBaseUrl = actionPage?.actions.find((action) => action.apiBaseUrl)?.apiBaseUrl ?? null;
+    return actionBaseUrl ? { serviceKey, baseUrl: requireHttpOrigin(actionBaseUrl) } : null;
   }
   /**
    * Resolve a service-slug → opaque app-id via caller config or TopoloAuth.
@@ -2403,7 +2664,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord(item)) continue;
+      if (!isRecord2(item)) continue;
       const s = item;
       const appId = typeof s.app_id === "string" ? s.app_id : typeof s.id === "string" ? s.id : null;
       if (!appId) continue;
@@ -2453,6 +2714,44 @@ var TopoloClient = class _TopoloClient {
     }
     return entry;
   }
+  async listBindableResources(application) {
+    const service = await this.getService(application);
+    const identity = await this.introspect();
+    if (identity.apiKey) {
+      return {
+        application: { appId: service.appId, slug: service.slug, name: service.name },
+        organizationId: identity.organization?.id ?? null,
+        resources: identity.apiKey.resourceBindings.map((binding) => ({
+          resourceType: binding.resourceType,
+          resourceId: binding.resourceId,
+          label: null,
+          slug: null,
+          status: "active",
+          organizationId: identity.organization?.id ?? null,
+          metadata: {}
+        })),
+        resourceTypes: service.apiKeyResources,
+        syncError: null,
+        source: "api_key_binding"
+      };
+    }
+    const response = await this.readAction(
+      "app_topolo_auth.service_api_key_resources.list",
+      { appId: service.appId }
+    );
+    const payload = isRecord2(response) && isRecord2(response.data) ? response.data : response;
+    if (!isRecord2(payload) || !Array.isArray(payload.resources)) {
+      throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
+    }
+    return {
+      application: { appId: service.appId, slug: service.slug, name: service.name },
+      organizationId: readOptionalString(payload.organizationId ?? payload.organization_id),
+      resources: payload.resources.map(normalizeBindableResource).filter((resource) => Boolean(resource)),
+      resourceTypes: normalizeApiKeyResourceMetadataList(payload.resourceTypes ?? payload.resource_types),
+      syncError: readOptionalString(payload.syncError ?? payload.sync_error),
+      source: "auth_catalog"
+    };
+  }
   /**
    * List callable actions from the live registry-canonical catalog (definitions
    * from the Catalog registry, scoping from Auth). The response is scoped to the
@@ -2547,10 +2846,44 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async validateActionInput(action, input = {}) {
+    const entry = await this.getAction(action);
+    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input) };
+  }
+  async planAction(action, input = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const validation = validateTopoloActionInput(entry.inputSchema, input);
+    const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
+    const confirmationRequired = agentAccess === "confirm" || entry.requiresConfirmation || entry.destructive;
+    let request = null;
+    if (validation.valid) {
+      const mapped = mapActionInput(entry, input);
+      request = {
+        method: entry.method,
+        service: entry.appSlug || entry.appId,
+        apiBaseUrl: entry.apiBaseUrl,
+        path: mapped.path,
+        ...mapped.query ? { query: mapped.query } : {},
+        ...mapped.body !== void 0 ? { body: mapped.body } : {},
+        ...options.resource ? { resource: options.resource } : {}
+      };
+    }
+    return {
+      action: entry,
+      validation,
+      confirmationRequired,
+      confirmationProvided: options.confirm === true,
+      executable: validation.valid && agentAccess !== "off" && (!confirmationRequired || options.confirm === true),
+      request,
+      verification: stringArray(entry.agentContract?.verify),
+      rollbackActionId: pickActionString(entry.agentContract?.rollbackActionId),
+      nextActionIds: stringArray(entry.agentContract?.nextActionIds)
+    };
+  }
   async readAction(action, input = {}, options = {}) {
     const entry = await this.getAction(action);
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
-    if (entry.method !== "GET" || !entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
+    if (!entry.readOnly || entry.destructive || entry.requiresConfirmation || agentAccess !== "auto") {
       throw new TopoloPermissionError(
         `Topolo action "${entry.actionId}" is not an automatic read-only action.`,
         entry.requiredPermission ? [entry.requiredPermission] : []
@@ -2571,6 +2904,13 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
       );
     }
+    const validation = validateTopoloActionInput(entry.inputSchema, input);
+    if (!validation.valid) {
+      throw new TopoloSdkError(
+        "invalid_action_input",
+        `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue) => `${issue.path} ${issue.message}`).join("; ")}`
+      );
+    }
     const mapped = mapActionInput(entry, input);
     const service = entry.appSlug || entry.appId;
     return this.request({
@@ -2585,7 +2925,7 @@ var TopoloClient = class _TopoloClient {
         [TOPOLO_ACTION_ID_HEADER]: entry.actionId,
         [TOPOLO_ACTION_NAME_HEADER]: entry.name
       },
-      confirm: options.confirm === true
+      confirm: options.confirm === true || entry.readOnly && !entry.destructive && !entry.requiresConfirmation
     });
   }
   /**
@@ -2642,7 +2982,14 @@ var TopoloClient = class _TopoloClient {
         id: organization.id,
         slug: organization.slug,
         name: organization.name ?? organization.slug
-      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null
+      } : user.orgId && user.orgSlug ? { id: user.orgId, slug: user.orgSlug, name: user.orgSlug } : null,
+      apiKey: kind === "api_key" ? {
+        id: readOptionalString(payload.apiKey?.id),
+        name: readOptionalString(payload.apiKey?.name),
+        appId: readOptionalString(payload.apiKey?.appId),
+        scopes: stringArray(payload.apiKey?.scopes),
+        resourceBindings: normalizeResourceBindings(payload.apiKey?.resourceBindings)
+      } : null
     };
   }
 };
@@ -2657,7 +3004,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input) {
-  if (!isRecord(input)) return null;
+  if (!isRecord2(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const label = readString(input.label);
   const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
@@ -2690,10 +3037,38 @@ function normalizeApiKeyResourceMetadataList(input) {
   }
   return resources;
 }
+function normalizeBindableResource(input) {
+  if (!isRecord2(input)) return null;
+  const resourceType = readString(input.resourceType ?? input.resource_type);
+  const resourceId = readString(input.resourceId ?? input.resource_id);
+  if (!resourceType || !resourceId) return null;
+  return {
+    resourceType,
+    resourceId,
+    label: readOptionalString(input.label),
+    slug: readOptionalString(input.slug),
+    status: readOptionalString(input.status),
+    organizationId: readOptionalString(input.organizationId ?? input.organization_id),
+    metadata: isRecord2(input.metadata) ? input.metadata : {}
+  };
+}
+function normalizeResourceBindings(input) {
+  if (!Array.isArray(input)) return [];
+  return input.flatMap((binding) => {
+    if (!isRecord2(binding)) return [];
+    const resourceType = readString(binding.resourceType ?? binding.resource_type);
+    const resourceId = readString(binding.resourceId ?? binding.resource_id);
+    return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
+  });
+}
 function readString(value) {
   return typeof value === "string" ? value.trim() : "";
 }
-function isRecord(value) {
+function readOptionalString(value) {
+  const normalized = readString(value);
+  return normalized || null;
+}
+function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
@@ -2765,14 +3140,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord2(value)) return { nextCursor: null, hasMore: false };
   return {
     nextCursor: typeof value.nextCursor === "string" && value.nextCursor ? value.nextCursor : null,
     hasMore: value.hasMore === true
   };
 }
 function normalizeServiceCatalogEntry(item) {
-  if (!isRecord(item)) return null;
+  if (!isRecord2(item)) return null;
   const appId = typeof item.app_id === "string" ? item.app_id : typeof item.id === "string" ? item.id : null;
   if (!appId) return null;
   const permissions = Array.isArray(item.granted_permissions) ? item.granted_permissions.filter(
@@ -2827,6 +3202,7 @@ function normalizeActionCatalogEntry(item) {
     authorizationMode: pickAuthorizationMode(a.authorization_mode ?? a.authorizationMode),
     inputSchema: plainObject(a.input_schema ?? a.inputSchema),
     outputSchema: plainObject(a.output_schema ?? a.outputSchema),
+    agentContract: plainObject(a.agent_contract ?? a.agentContract),
     readOnly: Boolean(a.read_only ?? a.readOnly),
     destructive: Boolean(a.destructive),
     requiresConfirmation: Boolean(a.requires_confirmation ?? a.requiresConfirmation),
@@ -2850,6 +3226,9 @@ function pickAuthorizationMode(value) {
 function plainObject(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
+function stringArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item || "").trim()).filter(Boolean) : [];
+}
 function mapActionInput(action, input) {
   const remaining = { ...input || {} };
   const path = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -3368,7 +3747,7 @@ function createTopoloWidgetError(error) {
 }
 function validateTopoloWidgetResponse(response) {
   const errors = [];
-  if (!isRecord2(response)) {
+  if (!isRecord3(response)) {
     return { ok: false, errors: ["response must be an object"] };
   }
   if (typeof response.success !== "boolean") {
@@ -3387,7 +3766,7 @@ function validateTopoloWidgetResponse(response) {
   return { ok: errors.length === 0, errors };
 }
 function validateWidget(widget, path, errors) {
-  if (!isRecord2(widget)) {
+  if (!isRecord3(widget)) {
     errors.push(`${path} must be an object`);
     return;
   }
@@ -3397,16 +3776,16 @@ function validateWidget(widget, path, errors) {
   validateSnapshotMetadata(widget.snapshot, `${path}.snapshot`, errors);
   switch (widget.type) {
     case "stats":
-      validateArray(widget.stats, `${path}.stats`, errors);
+      validateArray2(widget.stats, `${path}.stats`, errors);
       break;
     case "recent-activity":
-      validateArray(widget.activities, `${path}.activities`, errors);
+      validateArray2(widget.activities, `${path}.activities`, errors);
       break;
     case "quick-actions":
-      validateArray(widget.actions, `${path}.actions`, errors);
+      validateArray2(widget.actions, `${path}.actions`, errors);
       break;
     case "notifications":
-      validateArray(widget.notifications, `${path}.notifications`, errors);
+      validateArray2(widget.notifications, `${path}.notifications`, errors);
       if (typeof widget.unreadCount !== "number") {
         errors.push(`${path}.unreadCount must be a number`);
       }
@@ -3414,11 +3793,11 @@ function validateWidget(widget, path, errors) {
     case "chart":
       validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
       validateNonEmptyString(widget.title, `${path}.title`, errors);
-      if (!isRecord2(widget.data)) {
+      if (!isRecord3(widget.data)) {
         errors.push(`${path}.data must be an object`);
       } else {
-        validateArray(widget.data.labels, `${path}.data.labels`, errors);
-        validateArray(widget.data.values, `${path}.data.values`, errors);
+        validateArray2(widget.data.labels, `${path}.data.labels`, errors);
+        validateArray2(widget.data.values, `${path}.data.values`, errors);
       }
       break;
     default:
@@ -3430,7 +3809,7 @@ function validateSnapshotMetadata(snapshot, path, errors) {
     errors.push(`${path} must be an object`);
     return;
   }
-  if (!isRecord2(snapshot)) {
+  if (!isRecord3(snapshot)) {
     errors.push(`${path} must be an object`);
     return;
   }
@@ -3450,7 +3829,7 @@ function validateSnapshotMetadata(snapshot, path, errors) {
   }
   snapshot.availableMetrics.forEach((metric, index) => {
     const metricPath = `${path}.availableMetrics[${index}]`;
-    if (!isRecord2(metric)) {
+    if (!isRecord3(metric)) {
       errors.push(`${metricPath} must be an object`);
       return;
     }
@@ -3466,12 +3845,12 @@ function validateNonEmptyString(value, path, errors) {
     errors.push(`${path} must be a non-empty string`);
   }
 }
-function validateArray(value, path, errors) {
+function validateArray2(value, path, errors) {
   if (!Array.isArray(value)) {
     errors.push(`${path} must be an array`);
   }
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function toIsoTimestamp(input) {
@@ -3523,5 +3902,6 @@ export {
   requirementsForApplication,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  validateTopoloActionInput,
   validateTopoloWidgetResponse
 };

package/dist/node/credential-store.cjs

@@ -31,6 +31,7 @@ __export(credential_store_exports, {
   normalizeEnvironment: () => normalizeEnvironment,
   profileForEnvironment: () => profileForEnvironment,
   readConfig: () => readConfig,
+  refreshContextCredentialIfNeeded: () => refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded: () => refreshCredentialIfNeeded,
   resolveAgentName: () => resolveAgentName,
   resolveCredential: () => resolveCredential,
@@ -428,6 +429,46 @@ async function refreshCredentialIfNeeded(environment = selectedEnvironment(), op
     return cred;
   }
 }
+async function refreshContextCredentialIfNeeded(environment, key, options = {}) {
+  const config = await readConfig();
+  const profile = profileForEnvironment(config, environment);
+  const context = profile.contexts?.[key];
+  const credential = context?.credential;
+  if (!credential || credential.kind !== "access_token") return credential ?? null;
+  const oauthClientId = context.oauthClientId ?? profile.oauthClientId;
+  if (!credential.refreshToken || !credential.expiresAt || !oauthClientId) return credential;
+  const now = Math.floor(Date.now() / 1e3);
+  if (!options.force && credential.expiresAt - REFRESH_SKEW_SECONDS > now) return credential;
+  try {
+    const oauth = new TopoloOAuth({
+      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment)
+    });
+    const tokens = await oauth.refreshToken({
+      clientId: oauthClientId,
+      refreshToken: credential.refreshToken
+    });
+    const refreshed = {
+      kind: "access_token",
+      accessToken: tokens.access_token,
+      ...tokens.refresh_token ? { refreshToken: tokens.refresh_token } : { refreshToken: credential.refreshToken },
+      expiresAt: Math.floor(Date.now() / 1e3) + tokens.expires_in
+    };
+    await writeConfig(writeProfileConfig(config, environment, {
+      ...profile.activeContext === key ? { credential: refreshed } : {},
+      contexts: {
+        ...profile.contexts ?? {},
+        [key]: {
+          ...context,
+          credential: refreshed,
+          oauthClientId
+        }
+      }
+    }));
+    return refreshed;
+  } catch {
+    return credential;
+  }
+}
 function resolveAgentName(configAgentName) {
   return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
 }
@@ -471,6 +512,7 @@ function resolvedProfileConfig(config, environment = selectedEnvironment()) {
   normalizeEnvironment,
   profileForEnvironment,
   readConfig,
+  refreshContextCredentialIfNeeded,
   refreshCredentialIfNeeded,
   resolveAgentName,
   resolveCredential,

package/dist/node/credential-store.d.cts

@@ -103,8 +103,12 @@ declare function resolveCredential(environment?: TopoloEnvironment): Promise<Top
 declare function refreshCredentialIfNeeded(environment?: TopoloEnvironment, options?: {
     force?: boolean;
 }): Promise<TopoloCredential | null>;
+/** Refresh one stored context without changing which context is active. */
+declare function refreshContextCredentialIfNeeded(environment: TopoloEnvironment, key: string, options?: {
+    force?: boolean;
+}): Promise<TopoloCredential | null>;
 declare function resolveAgentName(configAgentName?: string): string | undefined;
 declare function resolveServiceUrls(configUrls?: Record<string, string>, environment?: TopoloEnvironment): Record<string, string> | undefined;
 declare function resolvedProfileConfig(config: TopoloConfig, environment?: TopoloEnvironment): TopoloEnvironmentProfile;
 
-export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, writeConfig, writeContextCredential, writeProfileConfig };
+export { ENVIRONMENT_DEFAULT_SERVICE_URLS, TOPOLO_ENVIRONMENTS, type TopoloConfig, type TopoloContextCredential, type TopoloEnvironment, type TopoloEnvironmentProfile, activateContext, clearProfileCredential, configPath, contextKey, credentialSourceFromConfig, envVarPrefix, normalizeEnvironment, profileForEnvironment, readConfig, refreshContextCredentialIfNeeded, refreshCredentialIfNeeded, resolveAgentName, resolveCredential, resolveServiceUrls, resolvedProfileConfig, selectedEnvironment, writeConfig, writeContextCredential, writeProfileConfig };