@topolo/cli 0.2.3 → 0.3.0

package/dist/index.js

@@ -78,6 +78,7 @@ var APP_API_URLS = {
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
+  campaigns: "https://campaigns.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://commerce.topolo.app",
@@ -336,6 +337,38 @@ var APPLICATIONS = {
       }
     ]
   },
+  "campaigns": {
+    "id": "campaigns",
+    "appDir": "TopoloCampaigns",
+    "name": "topolo-campaigns",
+    "packageName": "topolo-campaigns",
+    "productionUrl": "https://campaigns.topolo.app",
+    "services": [
+      "campaigns"
+    ],
+    "deployTargets": [
+      {
+        "name": "topolo-campaigns",
+        "kind": "worker",
+        "apiUrl": "https://campaigns.topolo.app",
+        "domains": [
+          "campaigns.topolo.app"
+        ],
+        "routes": [
+          "campaigns.topolo.app"
+        ],
+        "appId": "campaigns"
+      },
+      {
+        "name": "topolo-campaigns-api",
+        "kind": "worker",
+        "apiUrl": null,
+        "domains": [],
+        "routes": [],
+        "appId": null
+      }
+    ]
+  },
   "capacity": {
     "id": "capacity",
     "appDir": "TopoloCapacity",
@@ -2065,6 +2098,262 @@ function firstString(...values) {
   }
   return null;
 }
+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, input2) {
+  const schemaIssue = inspectSchema(schema, "$", schema, 0);
+  if (schemaIssue) return { valid: false, errors: [schemaIssue] };
+  const errors = [];
+  validateNode(schema, input2, "$", schema, errors, 0);
+  return { valid: errors.length === 0, errors };
+}
+function inspectSchema(schema, path4, root, depth) {
+  if (depth > 128) return { path: path4, 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: path4, 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: path4, code: "unsupported_schema_format", message: `Action schema uses unsupported format ${schema.format}.` };
+  }
+  if (typeof schema.$ref === "string" && !resolveLocalReference(root, schema.$ref)) {
+    return { path: path4, 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, `${path4}.${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, path4, root, errors, depth) {
+  if (depth > 128) {
+    errors.push({ path: path4, 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: path4, code: "unsupported_schema_ref", message: `Cannot resolve schema reference ${schema.$ref}.` });
+      return;
+    }
+    validateNode(resolved, value, path4, root, errors, depth + 1);
+  }
+  if (Array.isArray(schema.allOf)) {
+    for (const candidate of schema.allOf) {
+      if (isRecord(candidate)) validateNode(candidate, value, path4, root, errors, depth + 1);
+    }
+  }
+  if (Array.isArray(schema.anyOf) && !schema.anyOf.some((candidate) => candidateMatches(candidate, value, root, depth))) {
+    errors.push({ path: path4, 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: path4, 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: path4, 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: path4, 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: path4, code: "type", message: `Expected ${String(schema.type)}.` });
+    return;
+  }
+  if (typeof value === "string") validateString(schema, value, path4, errors);
+  if (typeof value === "number") validateNumber(schema, value, path4, errors);
+  if (Array.isArray(value)) validateArray(schema, value, path4, root, errors, depth);
+  if (isRecord(value)) validateObject(schema, value, path4, root, errors, depth);
+}
+function validateObject(schema, value, path4, root, errors, depth) {
+  if (typeof schema.minProperties === "number" && Object.keys(value).length < schema.minProperties) {
+    errors.push({ path: path4, code: "min_properties", message: `Expected at least ${schema.minProperties} properties.` });
+  }
+  if (typeof schema.maxProperties === "number" && Object.keys(value).length > schema.maxProperties) {
+    errors.push({ path: path4, 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: `${path4}.${key}`, code: "required", message: "Required property is missing." });
+    }
+  }
+  if (isRecord(schema.propertyNames)) {
+    for (const key of Object.keys(value)) {
+      validateNode(schema.propertyNames, key, `${path4}.${key}`, root, errors, depth + 1);
+    }
+  }
+  for (const [key, child] of Object.entries(value)) {
+    const childSchema = properties[key];
+    if (isRecord(childSchema)) {
+      validateNode(childSchema, child, `${path4}.${key}`, root, errors, depth + 1);
+    } else if (schema.additionalProperties === false) {
+      errors.push({ path: `${path4}.${key}`, code: "additional_property", message: "Property is not declared by the action schema." });
+    } else if (isRecord(schema.additionalProperties)) {
+      validateNode(schema.additionalProperties, child, `${path4}.${key}`, root, errors, depth + 1);
+    }
+  }
+}
+function validateArray(schema, value, path4, root, errors, depth) {
+  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+    errors.push({ path: path4, code: "min_items", message: `Expected at least ${schema.minItems} items.` });
+  }
+  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+    errors.push({ path: path4, code: "max_items", message: `Expected at most ${schema.maxItems} items.` });
+  }
+  if (schema.uniqueItems === true) {
+    const unique2 = new Set(value.map((item) => JSON.stringify(item)));
+    if (unique2.size !== value.length) errors.push({ path: path4, code: "unique_items", message: "Expected every item to be unique." });
+  }
+  if (isRecord(schema.items)) {
+    value.forEach((item, index) => validateNode(schema.items, item, `${path4}[${index}]`, root, errors, depth + 1));
+  }
+}
+function validateString(schema, value, path4, errors) {
+  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
+    errors.push({ path: path4, code: "min_length", message: `Expected at least ${schema.minLength} characters.` });
+  }
+  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
+    errors.push({ path: path4, 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: path4, code: "pattern", message: "Value does not match the required pattern." });
+    } catch {
+      errors.push({ path: path4, code: "invalid_schema_pattern", message: "Action schema contains an invalid pattern." });
+    }
+  }
+  if (schema.format === "uri" && !isUrl(value)) errors.push({ path: path4, code: "format_uri", message: "Expected an absolute URL." });
+  if (schema.format === "email" && !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(value)) errors.push({ path: path4, code: "format_email", message: "Expected an email address." });
+  if (schema.format === "date-time" && !isDateTime(value)) errors.push({ path: path4, code: "format_date_time", message: "Expected an ISO-8601 date-time." });
+}
+function validateNumber(schema, value, path4, errors) {
+  if (typeof schema.minimum === "number" && value < schema.minimum) errors.push({ path: path4, code: "minimum", message: `Expected a value of at least ${schema.minimum}.` });
+  if (typeof schema.maximum === "number" && value > schema.maximum) errors.push({ path: path4, 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: path4, code: "exclusive_minimum", message: `Expected a value greater than ${exclusiveMinimum}.` });
+  }
+  if (exclusiveMaximum !== null && value >= exclusiveMaximum) {
+    errors.push({ path: path4, code: "exclusive_maximum", message: `Expected a value less than ${exclusiveMaximum}.` });
+  }
+  if (typeof schema.multipleOf === "number" && !isMultipleOf(value, schema.multipleOf)) {
+    errors.push({ path: path4, 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;
+}
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
 var TOPOLO_ACTION_NAME_HEADER = "X-Topolo-Action-Name";
@@ -2284,7 +2573,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.
@@ -2369,7 +2661,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;
@@ -2419,6 +2711,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
@@ -2511,6 +2841,54 @@ var TopoloClient = class _TopoloClient {
   }
   async callAction(action, input2 = {}, options = {}) {
     const entry = await this.getAction(action);
+    return this.executeResolvedAction(entry, input2, options);
+  }
+  async validateActionInput(action, input2 = {}) {
+    const entry = await this.getAction(action);
+    return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input2) };
+  }
+  async planAction(action, input2 = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const validation = validateTopoloActionInput(entry.inputSchema, input2);
+    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, input2);
+      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, input2 = {}, options = {}) {
+    const entry = await this.getAction(action);
+    const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
+    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] : []
+      );
+    }
+    return this.executeResolvedAction(entry, input2, options);
+  }
+  async executeResolvedAction(entry, input2, options) {
     const agentAccess = entry.agentAccess ?? (entry.destructive ? "off" : entry.readOnly && !entry.requiresConfirmation ? "auto" : "confirm");
     if (agentAccess === "off") {
       throw new TopoloPermissionError(
@@ -2523,6 +2901,13 @@ var TopoloClient = class _TopoloClient {
         `Topolo action "${entry.actionId}" requires { confirm: true } before invocation.`
       );
     }
+    const validation = validateTopoloActionInput(entry.inputSchema, input2);
+    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, input2);
     const service = entry.appSlug || entry.appId;
     return this.request({
@@ -2537,7 +2922,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
     });
   }
   /**
@@ -2594,7 +2979,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
     };
   }
 };
@@ -2609,7 +3001,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input2) {
-  if (!isRecord(input2)) return null;
+  if (!isRecord2(input2)) return null;
   const resourceType = readString(input2.resourceType ?? input2.resource_type);
   const label = readString(input2.label);
   const emptyLabel = readString(input2.emptyLabel ?? input2.empty_label);
@@ -2642,10 +3034,38 @@ function normalizeApiKeyResourceMetadataList(input2) {
   }
   return resources;
 }
+function normalizeBindableResource(input2) {
+  if (!isRecord2(input2)) return null;
+  const resourceType = readString(input2.resourceType ?? input2.resource_type);
+  const resourceId = readString(input2.resourceId ?? input2.resource_id);
+  if (!resourceType || !resourceId) return null;
+  return {
+    resourceType,
+    resourceId,
+    label: readOptionalString(input2.label),
+    slug: readOptionalString(input2.slug),
+    status: readOptionalString(input2.status),
+    organizationId: readOptionalString(input2.organizationId ?? input2.organization_id),
+    metadata: isRecord2(input2.metadata) ? input2.metadata : {}
+  };
+}
+function normalizeResourceBindings(input2) {
+  if (!Array.isArray(input2)) return [];
+  return input2.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) {
@@ -2717,14 +3137,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(
@@ -2779,6 +3199,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),
@@ -2802,6 +3223,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, input2) {
   const remaining = { ...input2 || {} };
   const path4 = action.path.replace(/\{([a-zA-Z0-9_]+)\}/g, (_match, key) => {
@@ -3070,6 +3494,7 @@ var APP_API_URLS2 = {
   bugfix: "https://bugfix.topolo.app",
   bytes: "https://bytes.topolo.app",
   calendar: "https://calendar.topolo.app",
+  campaigns: "https://campaigns.topolo.app",
   capacity: "https://capacity.topolo.app",
   chat: "https://chat.topolo.app",
   commerce: "https://commerce.topolo.app",
@@ -3394,6 +3819,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 TopoloOAuth2({
+      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;
 }
@@ -3871,8 +4336,10 @@ function formatPretty(info) {
   return lines.join("\n");
 }
 
+// src/commands/actions.ts
+import { readFileSync as readFileSync2 } from "fs";
+
 // src/commands/api.ts
-var STATIC_APP_IDS = new Set(Object.keys(DEFAULT_APP_URLS));
 var HTTP_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 var WRITE_METHODS2 = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 function registerApiCommand(program2) {
@@ -3899,9 +4366,8 @@ function registerApiCommand(program2) {
         const config = await readConfig();
         const profile = resolvedProfileConfig(config, environment);
         const configuredUrl = resolveConfiguredServiceUrl2(service, profile.serviceUrls);
-        const staticUrl = STATIC_APP_IDS.has(service) ? DEFAULT_APP_URLS[service] : void 0;
-        if (configuredUrl || staticUrl) {
-          assertServiceUrlForEnvironment(service, configuredUrl ?? staticUrl, environment);
+        if (configuredUrl) {
+          assertServiceUrlForEnvironment(service, configuredUrl, environment);
         }
         let body = void 0;
         if (opts.data) {
@@ -4008,7 +4474,7 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
-  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json>", "JSON action input", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+  actions.command("call <action>").description("Call a permission-scoped Topolo action").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Acknowledge a mutating action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
     const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
     try {
       const topolo = await buildClient();
@@ -4026,11 +4492,78 @@ function registerActionsCommand(program2) {
       fail(err, mode);
     }
   });
+  actions.command("validate <action>").description("Validate action input locally against the published JSON Schema").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const result = await topolo.client.validateActionInput(action, parseJsonObject(opts.data || "{}"));
+      emit(result, mode, () => result.validation.valid ? `Valid input for ${result.action.actionId}.` : result.validation.errors.map((issue) => `${issue.path}: ${issue.message}`).join("\n"));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("plan <action>").description("Validate and preview the exact request, confirmation, verification, and rollback plan").option("-d, --data <json-or-@file>", "JSON action input or @path to a JSON file", "{}").option("--resource-type <type>", "App-local resource alias, such as workspace").option("--resource-id <id>", "Resource id for the selected resource type").option("--confirm", "Include confirmation in the plan without executing it").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const resource = parseResourceOption(opts.resourceType, opts.resourceId);
+      const plan = await topolo.client.planAction(action, parseJsonObject(opts.data || "{}"), {
+        confirm: opts.confirm === true,
+        ...resource ? { resource } : {}
+      });
+      emit(plan, mode, () => formatActionPlan(plan));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("examples <action>").description("Show published examples and public docs for one action").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (action, opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const entry = await topolo.client.getAction(action);
+      const result = {
+        actionId: entry.actionId,
+        docsUrl: entry.agentContract?.docsUrl ?? null,
+        examples: entry.agentContract?.examples ?? []
+      };
+      emit(result, mode, () => result.examples.length ? JSON.stringify(result, null, 2) : `No inline examples published. Docs: ${result.docsUrl || "not published"}`);
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+  actions.command("capabilities").description("Discover capability and schema actions for one application").option("-s, --service <service>", "App id, slug, or name").option("--json", "Output JSON").option("--no-json", "Output human-readable table").action(async (opts, command) => {
+    const mode = resolveOutputMode(opts.json ?? command.parent?.opts().json);
+    try {
+      const topolo = await requiredClient();
+      const service = opts.service || command.parent?.opts().service;
+      if (!service?.trim()) throw new Error("--service is required for capability discovery");
+      const result = await topolo.client.searchActions({ service: service.trim(), query: "capabilities", limit: 100 });
+      emit(result, mode, () => formatActionRows(result.actions, result.page.nextCursor));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+async function requiredClient() {
+  const topolo = await buildClient();
+  if (!topolo) throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+  return topolo;
 }
 function parseJsonObject(value) {
+  let source = value;
+  if (value.startsWith("@")) {
+    const path4 = value.slice(1);
+    if (!path4) throw new Error("--data @file path must not be empty");
+    try {
+      source = readFileSync2(path4, "utf8");
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new Error(`Could not read --data file ${path4}: ${detail}`);
+    }
+  }
   let parsed;
   try {
-    parsed = JSON.parse(value);
+    parsed = JSON.parse(source);
   } catch {
     throw new Error("--data must be valid JSON");
   }
@@ -4076,21 +4609,37 @@ function formatActionDetail(action) {
     `Path:         ${action.path}`,
     `Permission:   ${action.requiredPermission}`,
     `Confirmation: ${action.requiresConfirmation ? "required" : "not required"}`,
+    `Docs:         ${action.agentContract?.docsUrl || "-"}`,
+    `Rollback:     ${action.agentContract?.rollbackActionId || "-"}`,
     "",
     action.description
   ].join("\n");
 }
+function formatActionPlan(plan) {
+  const lines = [
+    `Action:       ${plan.action.actionId}`,
+    `Valid:        ${plan.validation.valid ? "yes" : "no"}`,
+    `Executable:   ${plan.executable ? "yes" : "no"}`,
+    `Confirmation: ${plan.confirmationRequired ? plan.confirmationProvided ? "provided" : "required" : "not required"}`
+  ];
+  if (plan.request) lines.push(`Request:      ${plan.request.method} ${plan.request.apiBaseUrl || plan.request.service}${plan.request.path}`);
+  if (plan.request?.resource) lines.push(`Resource:     ${plan.request.resource.resourceType}:${plan.request.resource.resourceId}`);
+  if (plan.validation.errors.length) lines.push("", ...plan.validation.errors.map((issue) => `${issue.path}: ${issue.message}`));
+  if (plan.verification.length) lines.push("", "Verify:", ...plan.verification.map((step) => `- ${step}`));
+  if (plan.rollbackActionId) lines.push("", `Rollback: ${plan.rollbackActionId}`);
+  return lines.join("\n");
+}
 
 // src/commands/apps.ts
 import { execSync } from "child_process";
-import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync3, writeFileSync } from "fs";
+import { existsSync as existsSync3, mkdirSync, readFileSync as readFileSync4, writeFileSync } from "fs";
 import path2 from "path";
 
 // src/commands/app-audit-local.ts
 import {
   existsSync as existsSync2,
   readdirSync,
-  readFileSync as readFileSync2,
+  readFileSync as readFileSync3,
   statSync
 } from "fs";
 import path from "path";
@@ -4101,7 +4650,7 @@ function readEvidenceFile(appRoot) {
   const candidate = path.join(appRoot, ".topolo", "evidence.json");
   if (!isFile(candidate)) return null;
   try {
-    const raw = JSON.parse(readFileSync2(candidate, "utf8"));
+    const raw = JSON.parse(readFileSync3(candidate, "utf8"));
     if (raw && typeof raw === "object" && raw.version === 1) {
       return raw;
     }
@@ -5045,7 +5594,7 @@ function readSourceIndex(root) {
   const files = collectSourceFiles(root, 4e3);
   const chunks = files.map((file) => {
     try {
-      return readFileSync2(file, "utf8");
+      return readFileSync3(file, "utf8");
     } catch {
       return "";
     }
@@ -5105,7 +5654,7 @@ function sortedDirEntries(dir) {
 function readJson(filePath) {
   if (!isFile(filePath)) return null;
   try {
-    return JSON.parse(readFileSync2(filePath, "utf8"));
+    return JSON.parse(readFileSync3(filePath, "utf8"));
   } catch {
     return null;
   }
@@ -9201,7 +9750,8 @@ function applicationRowsFromCatalog(catalog) {
     name: entry.name ?? entry.slug ?? entry.appId,
     appDir: "-",
     packageName: null,
-    productionUrl: entry.launchUrl ?? null,
+    apiBaseUrl: entry.apiBaseUrl ?? null,
+    launchUrl: entry.launchUrl ?? null,
     services: [displayCatalogId(entry)],
     deployTargets: 0
   })).sort((left, right) => left.id.localeCompare(right.id));
@@ -9266,7 +9816,7 @@ function recordApplicationEvidence(application, options = {}) {
   let before = null;
   if (existsSync3(evidencePath)) {
     try {
-      const raw = JSON.parse(readFileSync3(evidencePath, "utf8"));
+      const raw = JSON.parse(readFileSync4(evidencePath, "utf8"));
       if (raw && typeof raw === "object" && raw.version === 1) {
         before = raw;
       }
@@ -9346,7 +9896,7 @@ function evaluateApplicationAuditGate(payload, failOn) {
 function formatRows(rows) {
   const idWidth = Math.max(2, ...rows.map((r) => r.id.length));
   const nameWidth = Math.max(4, ...rows.map((r) => r.name.length));
-  const urlWidth = Math.max(3, ...rows.map((r) => (r.productionUrl ?? "-").length));
+  const urlWidth = Math.max(3, ...rows.map((r) => (applicationUrl(r) ?? "-").length));
   const servicesWidth = Math.max(
     8,
     ...rows.map((r) => r.services.length ? r.services.join(",").length : 1)
@@ -9361,7 +9911,7 @@ function formatRows(rows) {
   for (const r of rows) {
     const services = r.services.length ? r.services.join(",") : "-";
     lines.push(
-      `${r.id.padEnd(idWidth)}  ${r.name.padEnd(nameWidth)}  ${(r.productionUrl ?? "-").padEnd(urlWidth)}  ${services.padEnd(servicesWidth)}  ${r.deployTargets}`
+      `${r.id.padEnd(idWidth)}  ${r.name.padEnd(nameWidth)}  ${(applicationUrl(r) ?? "-").padEnd(urlWidth)}  ${services.padEnd(servicesWidth)}  ${r.deployTargets}`
     );
   }
   return lines.join("\n");
@@ -9370,10 +9920,14 @@ function formatApplicationRow(application) {
   return [
     `ID: ${application.id}`,
     `Name: ${application.name}`,
-    `URL: ${application.productionUrl ?? "-"}`,
+    `API URL: ${application.apiBaseUrl ?? "-"}`,
+    `Launch URL: ${application.launchUrl ?? application.productionUrl ?? "-"}`,
     `Services: ${application.services.length ? application.services.join(", ") : "-"}`
   ].join("\n");
 }
+function applicationUrl(application) {
+  return application.apiBaseUrl ?? application.launchUrl ?? application.productionUrl ?? null;
+}
 function displayCatalogId(entry) {
   for (const value of [entry.slug, entry.name, entry.appId]) {
     if (typeof value !== "string" || !value.trim()) continue;
@@ -9557,7 +10111,7 @@ function statusesAtOrWorse(threshold) {
 }
 
 // src/commands/platform.ts
-import { readdirSync as readdirSync2, readFileSync as readFileSync4, statSync as statSync2 } from "fs";
+import { readdirSync as readdirSync2, readFileSync as readFileSync5, statSync as statSync2 } from "fs";
 import path3 from "path";
 function registerPlatformCommand(program2) {
   const platform3 = program2.command("platform").description("Internal Topolo first-party platform and personal app commands");
@@ -9691,7 +10245,7 @@ function scanStagingProductionUrls(rootInput, allowPatterns) {
   function scanFile(filePath) {
     if (shouldSkipFile(filePath)) return;
     const relativePath = path3.relative(root, filePath);
-    const content = readFileSync4(filePath, "utf8");
+    const content = readFileSync5(filePath, "utf8");
     const lines = content.split(/\r?\n/);
     lines.forEach((line, index) => {
       const matches = [...line.matchAll(PRODUCTION_TOPOLO_URL_PATTERN)].map((match) => match[0]);
@@ -10714,11 +11268,25 @@ function registerContextCommand(program2) {
       }
       const wantPersonal = /^(personal|me)$/i.test(target.trim());
       let resolved;
-      if (wantPersonal) {
+      let exchangeCredential = cred;
+      const needle = target.trim().toLowerCase();
+      const storedEntry = Object.entries(profile.contexts ?? {}).find(([, candidate]) => {
+        if (wantPersonal) return candidate.contextType === "personal";
+        return candidate.contextType === "organization" && (candidate.organizationId === target || candidate.organizationSlug?.toLowerCase() === needle || candidate.organizationName?.toLowerCase() === needle);
+      });
+      const storedContext = storedEntry?.[1];
+      if (storedEntry && storedContext?.credential) {
+        exchangeCredential = await refreshContextCredentialIfNeeded(environment, storedEntry[0]) ?? storedContext.credential;
+        resolved = {
+          contextType: storedContext.contextType,
+          organizationId: storedContext.organizationId,
+          organizationSlug: storedContext.organizationSlug,
+          organizationName: storedContext.organizationName
+        };
+      } else if (wantPersonal) {
         resolved = { contextType: "personal" };
       } else {
         const me = await fetchMe(cred, serviceUrls);
-        const needle = target.trim().toLowerCase();
         const match = me.memberships.find(
           (m) => m.id === target || m.slug?.toLowerCase() === needle || m.name?.toLowerCase() === needle
         );
@@ -10737,13 +11305,13 @@ function registerContextCommand(program2) {
       }
       const key = contextKey(resolved.contextType, resolved.organizationId);
       const existing = profile.contexts?.[key];
-      const newCredential = await exchangeForContext(cred, serviceUrls, {
+      const newCredential = await exchangeForContext(exchangeCredential, serviceUrls, {
         type: resolved.contextType,
         id: resolved.organizationId
       });
       resolved.credential = newCredential;
       resolved.oauthClientId = existing?.oauthClientId ?? profile.oauthClientId;
-      const updated = writeContextCredential(config, environment, resolved, true);
+      const updated = writeContextCredential(await readConfig(), environment, resolved, true);
       await writeConfig(updated);
       emit(
         { environment, active: key, context: { type: resolved.contextType, label: labelFor(resolved) } },
@@ -10757,6 +11325,34 @@ function registerContextCommand(program2) {
   });
 }
 
+// src/commands/resources.ts
+function registerResourcesCommand(program2) {
+  program2.command("resources <application>").description("List bindable resource ids for one credential-scoped Topolo application").option("--json", "Output JSON").option("--no-json", "Output human-readable text").action(async (application, opts) => {
+    const mode = resolveOutputMode(opts.json);
+    try {
+      const topolo = await buildClient();
+      if (!topolo) throw new Error("No credential configured. Run `topolo auth login` or set TOPOLO_API_KEY.");
+      const result = await topolo.client.listBindableResources(application);
+      emit(result, mode, () => formatResources(result));
+    } catch (err) {
+      fail(err, mode);
+    }
+  });
+}
+function formatResources(result) {
+  const lines = [
+    `Application: ${result.application.name || result.application.slug || result.application.appId}`,
+    `Source:      ${result.source}`
+  ];
+  if (result.resources.length === 0) return [...lines, "", "No bindable resources available."].join("\n");
+  lines.push("", "TYPE  ID  LABEL");
+  for (const resource of result.resources) {
+    lines.push(`${resource.resourceType}  ${resource.resourceId}  ${resource.label || resource.slug || "-"}`);
+  }
+  if (result.syncError) lines.push("", `Sync warning: ${result.syncError}`);
+  return lines.join("\n");
+}
+
 // src/index.ts
 var program = new Command();
 var argv;
@@ -10787,6 +11383,7 @@ registerServicesCommand(program);
 registerSeedCommands(program);
 registerSkillsCommand(program);
 registerContextCommand(program);
+registerResourcesCommand(program);
 program.parseAsync(argv).catch((err) => {
   process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}
 `);