@topolo/sdk 0.9.6 → 0.9.8

package/dist/index.cjs

@@ -51,6 +51,9 @@ __export(index_exports, {
   defineTopoloStatsWidget: () => defineTopoloStatsWidget,
   digestTopoloActionCatalog: () => digestTopoloActionCatalog,
   enrichActionContract: () => enrichActionContract,
+  parseTopoloActionUploadContract: () => parseTopoloActionUploadContract,
+  prepareTopoloActionBase64UploadInput: () => prepareTopoloActionBase64UploadInput,
+  prepareTopoloActionUploadInput: () => prepareTopoloActionUploadInput,
   requirementsForApplication: () => requirementsForApplication,
   resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
@@ -89,19 +92,54 @@ var TopoloSdkError = class extends Error {
   }
 };
 var TopoloAuthError = class extends TopoloSdkError {
-  constructor(message, code = "auth_error") {
+  status;
+  body;
+  service;
+  path;
+  requestId;
+  retryAfter;
+  constructor(message, code = "auth_error", options = {}) {
     super(code, message);
     this.name = "TopoloAuthError";
+    this.status = options.status ?? 401;
+    this.body = options.body;
+    this.service = options.service;
+    this.path = options.path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
 var TopoloPermissionError = class extends TopoloSdkError {
   required;
-  constructor(message, required) {
+  status;
+  body;
+  service;
+  path;
+  requestId;
+  retryAfter;
+  constructor(message, required, options = {}) {
     super("permission_denied", message);
     this.name = "TopoloPermissionError";
     this.required = required;
+    this.status = options.status ?? 403;
+    this.body = options.body;
+    this.service = options.service;
+    this.path = options.path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
+function extractHttpErrorCode(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return "http_error";
+  const record = body;
+  if (typeof record.code === "string" && record.code.trim()) return record.code.trim();
+  const nested = record.error;
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    const code = nested.code;
+    if (typeof code === "string" && code.trim()) return code.trim();
+  }
+  return "http_error";
+}
 var TopoloConfirmationRequiredError = class extends TopoloSdkError {
   constructor(message) {
     super("confirmation_required", message);
@@ -113,13 +151,17 @@ var TopoloHttpError = class extends TopoloSdkError {
   body;
   service;
   path;
-  constructor(service, path, status, body, message) {
-    super("http_error", message ?? `HTTP ${status} from ${service}${path}`);
+  requestId;
+  retryAfter;
+  constructor(service, path, status, body, message, options = {}) {
+    super(extractHttpErrorCode(body), message ?? `HTTP ${status} from ${service}${path}`);
     this.name = "TopoloHttpError";
     this.status = status;
     this.body = body;
     this.service = service;
     this.path = path;
+    this.requestId = options.requestId;
+    this.retryAfter = options.retryAfter;
   }
 };
 
@@ -333,7 +375,9 @@ var APPLICATIONS = {
         "domains": [
           "brand.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "brand.topolo.app"
+        ],
         "appId": "brand"
       },
       {
@@ -505,7 +549,9 @@ var APPLICATIONS = {
         "domains": [
           "chat.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "chat.topolo.app"
+        ],
         "appId": "chat"
       },
       {
@@ -1065,7 +1111,9 @@ var APPLICATIONS = {
         "domains": [
           "mail.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "mail.topolo.app"
+        ],
         "appId": "mail"
       },
       {
@@ -1416,7 +1464,9 @@ var APPLICATIONS = {
         "domains": [
           "quro.topolo.app"
         ],
-        "routes": [],
+        "routes": [
+          "quro.topolo.app"
+        ],
         "appId": null
       }
     ]
@@ -2498,6 +2548,168 @@ function isMultipleOf(value, divisor) {
   return Math.abs(quotient - Math.round(quotient)) < Number.EPSILON * Math.max(1, Math.abs(quotient)) * 4;
 }
 
+// src/action-upload.ts
+function parseTopoloActionUploadContract(value) {
+  if (!isRecord2(value) || value.profile !== "inline-base64" && value.profile !== "url-session") {
+    throw new TopoloSdkError("upload_contract_unavailable", "This action does not publish a supported upload contract.");
+  }
+  const contentTypeField = requiredField(value.contentTypeField, "contentTypeField");
+  const fileNameField = requiredField(value.fileNameField, "fileNameField");
+  const maxBytes = Number(value.maxBytes);
+  const acceptedContentTypes = Array.isArray(value.acceptedContentTypes) ? value.acceptedContentTypes.map((item) => String(item).trim().toLowerCase()).filter(Boolean) : [];
+  if (!Number.isSafeInteger(maxBytes) || maxBytes <= 0 || acceptedContentTypes.length === 0) {
+    throw new TopoloSdkError("invalid_upload_contract", "The action upload contract must declare maxBytes and acceptedContentTypes.");
+  }
+  if (value.profile === "inline-base64") {
+    return {
+      profile: "inline-base64",
+      contentField: requiredField(value.contentField, "contentField"),
+      contentTypeField,
+      fileNameField,
+      maxBytes,
+      acceptedContentTypes
+    };
+  }
+  const uploadMethod = value.uploadMethod === "PUT" || value.uploadMethod === "POST" ? value.uploadMethod : null;
+  const uploadUrlPath = requiredPath(value.uploadUrlPath, "uploadUrlPath");
+  const complete = value.complete === void 0 ? void 0 : parseCompleteContract(value.complete);
+  if (!uploadMethod) throw new TopoloSdkError("invalid_upload_contract", "The action upload contract has an invalid uploadMethod.");
+  return {
+    profile: "url-session",
+    fileNameField,
+    contentTypeField,
+    sizeField: requiredField(value.sizeField, "sizeField"),
+    maxBytes,
+    acceptedContentTypes,
+    uploadUrlPath,
+    uploadMethod,
+    ...complete ? { complete } : {}
+  };
+}
+function prepareTopoloActionUploadInput(contractValue, content, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "inline-base64") throw unsupportedInlineProfile();
+  const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+  if (bytes.byteLength === 0) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  }
+  if (bytes.byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  return mapUploadInput(contract, bytesToBase64(bytes), input, options);
+}
+function prepareTopoloActionBase64UploadInput(contractValue, contentBase64, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "inline-base64") throw unsupportedInlineProfile();
+  if (!isCanonicalBase64(contentBase64)) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must be canonical base64.");
+  }
+  const padding = contentBase64.endsWith("==") ? 2 : contentBase64.endsWith("=") ? 1 : 0;
+  const byteLength = contentBase64.length / 4 * 3 - padding;
+  if (byteLength === 0) throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  if (byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  return mapUploadInput(contract, contentBase64, input, options);
+}
+function prepareTopoloUrlSessionUploadInput(contractValue, byteLength, input, options) {
+  const contract = parseTopoloActionUploadContract(contractValue);
+  if (contract.profile !== "url-session") {
+    throw new TopoloSdkError("invalid_upload_contract", "This action does not publish a URL-session upload contract.");
+  }
+  validateUploadMetadata(contract, byteLength, options);
+  return {
+    contract,
+    input: {
+      ...input,
+      [contract.fileNameField]: options.fileName.trim(),
+      [contract.contentTypeField]: options.contentType.trim().toLowerCase(),
+      [contract.sizeField]: byteLength
+    }
+  };
+}
+function topoloUploadResponseValue(response, path) {
+  return path.split(".").reduce((value, segment) => isRecord2(value) ? value[segment] : void 0, response);
+}
+function decodeTopoloActionBase64(contentBase64) {
+  if (!isCanonicalBase64(contentBase64)) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must be canonical base64.");
+  }
+  const binary = atob(contentBase64);
+  return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+}
+function mapUploadInput(contract, contentBase64, input, options) {
+  validateUploadMetadata(contract, Math.max(1, decodedBase64Size(contentBase64)), options);
+  const fileName = options.fileName.trim();
+  const contentType = options.contentType.trim().toLowerCase();
+  return {
+    ...input,
+    [contract.contentField]: contentBase64,
+    [contract.contentTypeField]: contentType,
+    [contract.fileNameField]: fileName
+  };
+}
+function validateUploadMetadata(contract, byteLength, options) {
+  const fileName = options.fileName.trim();
+  const contentType = options.contentType.trim().toLowerCase();
+  if (!fileName) throw new TopoloSdkError("invalid_upload_file_name", "Upload fileName must not be empty.");
+  if (!Number.isSafeInteger(byteLength) || byteLength <= 0) {
+    throw new TopoloSdkError("invalid_upload_content", "Upload content must not be empty.");
+  }
+  if (byteLength > contract.maxBytes) {
+    throw new TopoloSdkError("upload_too_large", `Upload content exceeds the ${contract.maxBytes}-byte action limit.`);
+  }
+  if (!matchesContentType(contentType, contract.acceptedContentTypes)) {
+    throw new TopoloSdkError("unsupported_upload_content_type", `Content type "${contentType}" is not accepted by this action.`);
+  }
+}
+function decodedBase64Size(contentBase64) {
+  const padding = contentBase64.endsWith("==") ? 2 : contentBase64.endsWith("=") ? 1 : 0;
+  return contentBase64.length / 4 * 3 - padding;
+}
+function parseCompleteContract(value) {
+  if (!isRecord2(value)) throw new TopoloSdkError("invalid_upload_contract", "The action upload completion contract is invalid.");
+  return {
+    actionId: requiredPath(value.actionId, "complete.actionId"),
+    inputField: requiredField(value.inputField, "complete.inputField"),
+    responsePath: requiredPath(value.responsePath, "complete.responsePath")
+  };
+}
+function requiredPath(value, name) {
+  const path = typeof value === "string" ? value.trim() : "";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*$/.test(path)) {
+    throw new TopoloSdkError("invalid_upload_contract", `The action upload contract has an invalid ${name}.`);
+  }
+  return path;
+}
+function unsupportedInlineProfile() {
+  return new TopoloSdkError("invalid_upload_contract", "This action does not publish an inline-base64 upload contract.");
+}
+function isCanonicalBase64(value) {
+  return value.length > 0 && value.length % 4 === 0 && /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value);
+}
+function requiredField(value, name) {
+  const field = typeof value === "string" ? value.trim() : "";
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(field)) {
+    throw new TopoloSdkError("invalid_upload_contract", `The action upload contract has an invalid ${name}.`);
+  }
+  return field;
+}
+function matchesContentType(contentType, accepted) {
+  return accepted.some((candidate) => candidate === "*/*" || candidate === contentType || candidate.endsWith("/*") && contentType.startsWith(candidate.slice(0, -1)));
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  const chunkSize = 32768;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+  return btoa(binary);
+}
+function isRecord2(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 // src/client.ts
 var WRITE_METHODS = /* @__PURE__ */ new Set(["POST", "PUT", "PATCH", "DELETE"]);
 var TOPOLO_ACTION_ID_HEADER = "X-Topolo-Action-Id";
@@ -2575,6 +2787,9 @@ var TopoloClient = class _TopoloClient {
         if (v !== void 0) url.searchParams.set(k, String(v));
       }
     }
+    if (opts.body !== void 0 && opts.rawBody !== void 0) {
+      throw new TopoloSdkError("invalid_request_body", "body and rawBody are mutually exclusive.");
+    }
     const headers = new Headers();
     headers.set("Accept", "application/json");
     if (opts.body !== void 0) headers.set("Content-Type", "application/json");
@@ -2609,7 +2824,7 @@ var TopoloClient = class _TopoloClient {
         return await this.fetchImpl(urlStr, {
           method,
           headers: new Headers(headers),
-          body: opts.body !== void 0 ? JSON.stringify(opts.body) : null,
+          body: opts.rawBody ?? (opts.body !== void 0 ? JSON.stringify(opts.body) : null),
           signal
         });
       } finally {
@@ -2657,14 +2872,32 @@ var TopoloClient = class _TopoloClient {
         error: message,
         status: res.status
       });
-      if (res.status === 401) throw new TopoloAuthError(describeError(parsed, "Unauthorized"));
+      const errorContext = {
+        status: res.status,
+        body: parsed,
+        service: resolvedService.serviceKey,
+        path: opts.path,
+        requestId: res.headers.get("X-Topolo-Request-Id") || requestId,
+        retryAfter: res.headers.get("Retry-After") || void 0
+      };
+      if (res.status === 401) {
+        throw new TopoloAuthError(describeError(parsed, "Unauthorized"), "auth_error", errorContext);
+      }
       if (res.status === 403) {
         throw new TopoloPermissionError(
           describeError(parsed, "Permission denied"),
-          extractRequired(parsed)
+          extractRequired(parsed),
+          errorContext
         );
       }
-      throw new TopoloHttpError(resolvedService.serviceKey, opts.path, res.status, parsed);
+      throw new TopoloHttpError(
+        resolvedService.serviceKey,
+        opts.path,
+        res.status,
+        parsed,
+        message,
+        errorContext
+      );
     }
     this.emit({
       phase: "response",
@@ -2823,7 +3056,7 @@ var TopoloClient = class _TopoloClient {
     }
     const entries = [];
     for (const item of raw) {
-      if (!isRecord2(item)) continue;
+      if (!isRecord3(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;
@@ -2898,8 +3131,8 @@ var TopoloClient = class _TopoloClient {
       "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)) {
+    const payload = isRecord3(response) && isRecord3(response.data) ? response.data : response;
+    if (!isRecord3(payload) || !Array.isArray(payload.resources)) {
       throw new TopoloSdkError("resource_catalog_unavailable", "TopoloAuth did not return bindable resources.");
     }
     return {
@@ -3005,6 +3238,71 @@ var TopoloClient = class _TopoloClient {
     const entry = await this.getAction(action);
     return this.executeResolvedAction(entry, input, options);
   }
+  async uploadAction(action, content, input, options) {
+    const entry = await this.getAction(action);
+    const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
+    if (contract.profile === "url-session") {
+      const bytes = content instanceof Uint8Array ? content : new Uint8Array(content);
+      return this.executeUrlSessionUpload(entry, contract, bytes, input, options);
+    }
+    const uploadInput = prepareTopoloActionUploadInput(entry.agentContract?.upload, content, input, options);
+    return this.executeResolvedAction(entry, uploadInput, options);
+  }
+  async uploadActionBase64(action, contentBase64, input, options) {
+    const entry = await this.getAction(action);
+    const contract = parseTopoloActionUploadContract(entry.agentContract?.upload);
+    if (contract.profile === "url-session") {
+      return this.executeUrlSessionUpload(entry, contract, decodeTopoloActionBase64(contentBase64), input, options);
+    }
+    const uploadInput = prepareTopoloActionBase64UploadInput(entry.agentContract?.upload, contentBase64, input, options);
+    return this.executeResolvedAction(entry, uploadInput, options);
+  }
+  async executeUrlSessionUpload(entry, contract, bytes, input, options) {
+    const prepared = prepareTopoloUrlSessionUploadInput(contract, bytes.byteLength, input, options);
+    const initiation = await this.executeResolvedAction(entry, prepared.input, options);
+    const uploadUrl = topoloUploadResponseValue(initiation, contract.uploadUrlPath);
+    if (typeof uploadUrl !== "string" || !uploadUrl.trim()) {
+      throw new TopoloSdkError("invalid_upload_response", `Upload action response is missing ${contract.uploadUrlPath}.`);
+    }
+    await this.putUrlSessionContent(entry, uploadUrl, contract.uploadMethod, bytes, options);
+    if (!contract.complete) return initiation;
+    const completionValue = topoloUploadResponseValue(initiation, contract.complete.responsePath);
+    if (typeof completionValue !== "string" || !completionValue.trim()) {
+      throw new TopoloSdkError("invalid_upload_response", `Upload action response is missing ${contract.complete.responsePath}.`);
+    }
+    const completion = await this.getAction(contract.complete.actionId);
+    return this.executeResolvedAction(completion, {
+      ...options.completionInput ?? {},
+      [contract.complete.inputField]: completionValue
+    }, options);
+  }
+  async putUrlSessionContent(entry, uploadUrl, method, bytes, options) {
+    const service = entry.appSlug || entry.appId;
+    const resolved = entry.apiBaseUrl ? { serviceKey: normalizeLookupKey(service), baseUrl: requireHttpOrigin(entry.apiBaseUrl) } : await this.resolveRequestService(service);
+    const target = new URL(uploadUrl, resolved.baseUrl.endsWith("/") ? resolved.baseUrl : `${resolved.baseUrl}/`);
+    const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    if (target.origin === new URL(resolved.baseUrl).origin) {
+      await this.request({
+        service,
+        baseUrl: resolved.baseUrl,
+        path: target.toString(),
+        method,
+        rawBody: body,
+        headers: { "Content-Type": options.contentType.trim().toLowerCase() },
+        resource: options.resource,
+        confirm: options.confirm
+      });
+      return;
+    }
+    const response = await this.fetchImpl(target, {
+      method,
+      headers: { "Content-Type": options.contentType.trim().toLowerCase() },
+      body
+    });
+    if (!response.ok) {
+      throw new TopoloHttpError(service, target.pathname, response.status, await response.text(), `Upload transport failed with HTTP ${response.status}.`);
+    }
+  }
   async validateActionInput(action, input = {}) {
     const entry = await this.getAction(action);
     return { action: entry, validation: validateTopoloActionInput(entry.inputSchema, input) };
@@ -3163,7 +3461,7 @@ function resolveConfiguredAppId(slug, appIds) {
   return null;
 }
 function normalizeApiKeyResourceMetadata(input) {
-  if (!isRecord2(input)) return null;
+  if (!isRecord3(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const label = readString(input.label);
   const emptyLabel = readString(input.emptyLabel ?? input.empty_label);
@@ -3197,7 +3495,7 @@ function normalizeApiKeyResourceMetadataList(input) {
   return resources;
 }
 function normalizeBindableResource(input) {
-  if (!isRecord2(input)) return null;
+  if (!isRecord3(input)) return null;
   const resourceType = readString(input.resourceType ?? input.resource_type);
   const resourceId = readString(input.resourceId ?? input.resource_id);
   if (!resourceType || !resourceId) return null;
@@ -3208,13 +3506,13 @@ function normalizeBindableResource(input) {
     slug: readOptionalString(input.slug),
     status: readOptionalString(input.status),
     organizationId: readOptionalString(input.organizationId ?? input.organization_id),
-    metadata: isRecord2(input.metadata) ? input.metadata : {}
+    metadata: isRecord3(input.metadata) ? input.metadata : {}
   };
 }
 function normalizeResourceBindings(input) {
   if (!Array.isArray(input)) return [];
   return input.flatMap((binding) => {
-    if (!isRecord2(binding)) return [];
+    if (!isRecord3(binding)) return [];
     const resourceType = readString(binding.resourceType ?? binding.resource_type);
     const resourceId = readString(binding.resourceId ?? binding.resource_id);
     return resourceType && resourceId ? [{ resourceType, resourceId }] : [];
@@ -3227,7 +3525,7 @@ function readOptionalString(value) {
   const normalized = readString(value);
   return normalized || null;
 }
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function resolveConfiguredServiceUrl(slug, serviceUrls) {
@@ -3299,14 +3597,14 @@ function catalogSearchQuery(options) {
   return query;
 }
 function normalizeCatalogPage(value) {
-  if (!isRecord2(value)) return { nextCursor: null, hasMore: false };
+  if (!isRecord3(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 (!isRecord2(item)) return null;
+  if (!isRecord3(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(
@@ -3564,7 +3862,7 @@ var INVERSE_OPERATIONS = /* @__PURE__ */ new Map([
   ["restore", "archive"],
   ["unpublish", "publish"]
 ]);
-function isRecord3(value) {
+function isRecord4(value) {
   return Boolean(value && typeof value === "object" && !Array.isArray(value));
 }
 function nonEmptyStrings(value) {
@@ -3574,9 +3872,15 @@ function slugify(value) {
   return String(value || "").trim().replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
 }
 function singularize(value) {
+  const irregular = /* @__PURE__ */ new Map([
+    ["analyses", "analysis"],
+    ["buses", "bus"],
+    ["statuses", "status"]
+  ]);
+  if (irregular.has(value)) return irregular.get(value);
   if (value.endsWith("ies") && value.length > 3) return `${value.slice(0, -3)}y`;
-  if (value.endsWith("sses")) return value.slice(0, -2);
-  if (value.endsWith("s") && !value.endsWith("ss")) return value.slice(0, -1);
+  if (/(?:ches|shes|sses|xes|zes)$/.test(value)) return value.slice(0, -2);
+  if (value.endsWith("s") && !/(?:ss|us|is)$/.test(value)) return value.slice(0, -1);
   return value || "resource";
 }
 function operationFor(action) {
@@ -3590,11 +3894,16 @@ function resourceFor(action) {
   const pathToken = String(action.path || "").split("/").filter((token) => token && token !== "api" && !token.startsWith("{")).find((token) => !OPERATION_TOKENS.has(slugify(token)));
   return singularize(slugify(pathToken || "resource").replaceAll("-", "_"));
 }
+function collectionFor(action, resource) {
+  const named = String(action.name || "").split(/[._:-]+/).filter(Boolean).find((token) => !OPERATION_TOKENS.has(token));
+  if (named) return slugify(named).replaceAll("-", "_");
+  return resource.endsWith("s") ? resource : `${resource}s`;
+}
 function isConcreteOutputSchema(schema) {
-  if (!isRecord3(schema)) return false;
+  if (!isRecord4(schema)) return false;
   if (typeof schema.$ref === "string" && schema.$ref.trim()) return true;
-  if (schema.type === "array" && isRecord3(schema.items) && Object.keys(schema.items).length > 0) return true;
-  if (isRecord3(schema.properties) && Object.keys(schema.properties).length > 0) return true;
+  if (schema.type === "array" && isRecord4(schema.items) && Object.keys(schema.items).length > 0) return true;
+  if (isRecord4(schema.properties) && Object.keys(schema.properties).length > 0) return true;
   return ["oneOf", "anyOf", "allOf"].some((key) => Array.isArray(schema[key]) && schema[key].some(isConcreteOutputSchema));
 }
 function resourceSchema(resource) {
@@ -3620,6 +3929,7 @@ function derivedOutputSchema(action) {
     "x-topolo-contract-precision": "structural"
   };
   if (operation === "list" || operation === "search") {
+    const collection = collectionFor(action, resource);
     return {
       title: `${action.title || action.name} response`,
       description: `Collection response returned by ${action.name}. The service may return the collection directly or in an envelope.`,
@@ -3630,7 +3940,7 @@ function derivedOutputSchema(action) {
           properties: {
             data: { oneOf: [records, { type: "object", additionalProperties: true }] },
             items: records,
-            [resource.endsWith("s") ? resource : `${resource}s`]: records,
+            [collection]: records,
             count: { type: "integer", minimum: 0 },
             nextCursor: { type: ["string", "null"] }
           },
@@ -3674,7 +3984,7 @@ function derivedOutputSchema(action) {
   };
 }
 function sampleForSchema(schema, depth = 0) {
-  if (!isRecord3(schema) || depth > 5) return null;
+  if (!isRecord4(schema) || depth > 5) return null;
   if (schema.const !== void 0) return schema.const;
   if (Array.isArray(schema.enum) && schema.enum.length > 0) return schema.enum[0];
   if (Array.isArray(schema.oneOf) && schema.oneOf.length > 0) return sampleForSchema(schema.oneOf[0], depth + 1);
@@ -3688,8 +3998,8 @@ function sampleForSchema(schema, depth = 0) {
     return schema.minLength > 1 ? "example".padEnd(schema.minLength, "x") : "example";
   }
   if (schema.type === "null") return null;
-  if (schema.type === "object" || isRecord3(schema.properties)) {
-    const properties = isRecord3(schema.properties) ? schema.properties : {};
+  if (schema.type === "object" || isRecord4(schema.properties)) {
+    const properties = isRecord4(schema.properties) ? schema.properties : {};
     const required = new Set(Array.isArray(schema.required) ? schema.required : []);
     const entries = Object.entries(properties).filter(([key]) => required.has(key)).map(([key, child]) => [key, sampleForSchema(child, depth + 1)]);
     return Object.fromEntries(entries);
@@ -3739,21 +4049,32 @@ function defaultErrors(action) {
   const errors = [
     { status: 401, code: "authentication_required", recovery: "Authenticate again or provide a valid Topolo API key." },
     { status: 403, code: "permission_denied", recovery: `Grant the credential permission ${action.permission || action.permissionName || "required by this action"} and the required resource binding.` },
-    { status: 422, code: "invalid_input", recovery: "Correct the payload using inputSchema, then validate before retrying." }
+    { status: 429, code: "rate_limited", recovery: "Wait for Retry-After when present, then retry without parallel duplicate calls." },
+    { status: 422, code: "invalid_input", recovery: "Correct the payload using inputSchema, then validate before retrying." },
+    { status: 503, code: "dependency_unavailable", recovery: "Retry the action. If it continues, inspect the structured error details using the request ID." }
   ];
   if (action.method !== "GET") {
     errors.push({ status: 409, code: "state_conflict", recovery: "Read the current resource state, reconcile the intended change, and retry only if still valid." });
   }
   return errors;
 }
+function mergeErrors(defaults, declared) {
+  const merged = [...defaults];
+  for (const error of Array.isArray(declared) ? declared : []) {
+    const index = merged.findIndex((candidate) => candidate.status === error?.status && candidate.code === error?.code);
+    if (index === -1) merged.push(error);
+    else merged[index] = error;
+  }
+  return merged;
+}
 function enrichActionContract(manifest, action, allActions = manifest.actions || []) {
   const appId = String(manifest.appId || manifest.app_id || "").trim();
   const service = slugify(manifest.slug || appId.replace(/^app_/, "").replaceAll("_", "-") || manifest.name);
   const outputSchema = isConcreteOutputSchema(action.outputSchema) ? structuredClone(action.outputSchema) : derivedOutputSchema(action);
   const resource = resourceFor(action);
   const readOnly = action.readOnly !== void 0 ? action.readOnly === true : action.method === "GET";
-  const existing = isRecord3(action.agentContract) ? structuredClone(action.agentContract) : {};
-  const recovery = isRecord3(existing.recovery) ? existing.recovery : recoveryFor(action, allActions, appId);
+  const existing = isRecord4(action.agentContract) ? structuredClone(action.agentContract) : {};
+  const recovery = isRecord4(existing.recovery) ? existing.recovery : recoveryFor(action, allActions, appId);
   const rollbackActionId = typeof existing.rollbackActionId === "string" && existing.rollbackActionId.trim() ? existing.rollbackActionId.trim() : recovery.mode === "compensating_action" ? recovery.actionId : void 0;
   const inputExample = sampleForSchema(action.inputSchema);
   const examples = Array.isArray(existing.examples) && existing.examples.length > 0 ? existing.examples : [{ input: inputExample ?? {}, expected: `A response matching the published outputSchema for ${action.name}.` }];
@@ -3765,9 +4086,9 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
       ...existing,
       docsUrl,
       ...existingDocsUrl && existingDocsUrl !== docsUrl ? { guideUrl: existingDocsUrl } : {},
-      resource: isRecord3(existing.resource) ? existing.resource : { kind: resource, idPath: readOnly && ["list", "search"].includes(operationFor(action)) ? "$.items[].id" : "$.id" },
+      resource: isRecord4(existing.resource) ? existing.resource : { kind: resource, idPath: readOnly && ["list", "search"].includes(operationFor(action)) ? "$.items[].id" : "$.id" },
       effects: nonEmptyStrings(existing.effects) ? existing.effects : [readOnly ? `Reads ${resource.replaceAll("_", " ")} data without changing service state.` : action.destructive === true || action.method === "DELETE" ? `Permanently removes or invalidates ${resource.replaceAll("_", " ")} state.` : `Changes ${resource.replaceAll("_", " ")} state in the selected Topolo resource context.`],
-      errors: Array.isArray(existing.errors) && existing.errors.length > 0 ? existing.errors : defaultErrors(action),
+      errors: mergeErrors(defaultErrors(action), existing.errors),
       verify: nonEmptyStrings(existing.verify) ? existing.verify : [`Validate the response against outputSchema and ${readOnly ? "confirm it belongs to the selected resource context" : "re-read the affected resource to confirm the intended state"}.`],
       examples,
       recovery,
@@ -3779,15 +4100,15 @@ function enrichActionContract(manifest, action, allActions = manifest.actions ||
 function actionContractCompleteness(action) {
   const contract = action?.agentContract;
   return {
-    inputSchema: isRecord3(action?.inputSchema),
+    inputSchema: isRecord4(action?.inputSchema),
     outputSchema: isConcreteOutputSchema(action?.outputSchema),
     effects: nonEmptyStrings(contract?.effects),
     errors: Array.isArray(contract?.errors) && contract.errors.length > 0,
     docs: typeof contract?.docsUrl === "string" && contract.docsUrl.startsWith("https://"),
     examples: Array.isArray(contract?.examples) && contract.examples.length > 0,
     verification: nonEmptyStrings(contract?.verify),
-    recovery: isRecord3(contract?.recovery) && ["not_applicable", "compensating_action", "irreversible"].includes(contract.recovery.mode),
-    agentContract: isRecord3(contract) && isRecord3(contract.resource) && nonEmptyStrings(contract.effects) && Array.isArray(contract.errors) && contract.errors.length > 0
+    recovery: isRecord4(contract?.recovery) && ["not_applicable", "compensating_action", "irreversible"].includes(contract.recovery.mode),
+    agentContract: isRecord4(contract) && isRecord4(contract.resource) && nonEmptyStrings(contract.effects) && Array.isArray(contract.errors) && contract.errors.length > 0
   };
 }
 
@@ -4192,7 +4513,7 @@ function createTopoloWidgetError(error) {
 }
 function validateTopoloWidgetResponse(response) {
   const errors = [];
-  if (!isRecord4(response)) {
+  if (!isRecord5(response)) {
     return { ok: false, errors: ["response must be an object"] };
   }
   if (typeof response.success !== "boolean") {
@@ -4211,7 +4532,7 @@ function validateTopoloWidgetResponse(response) {
   return { ok: errors.length === 0, errors };
 }
 function validateWidget(widget, path, errors) {
-  if (!isRecord4(widget)) {
+  if (!isRecord5(widget)) {
     errors.push(`${path} must be an object`);
     return;
   }
@@ -4238,7 +4559,7 @@ function validateWidget(widget, path, errors) {
     case "chart":
       validateNonEmptyString(widget.chartType, `${path}.chartType`, errors);
       validateNonEmptyString(widget.title, `${path}.title`, errors);
-      if (!isRecord4(widget.data)) {
+      if (!isRecord5(widget.data)) {
         errors.push(`${path}.data must be an object`);
       } else {
         validateArray2(widget.data.labels, `${path}.data.labels`, errors);
@@ -4254,7 +4575,7 @@ function validateSnapshotMetadata(snapshot, path, errors) {
     errors.push(`${path} must be an object`);
     return;
   }
-  if (!isRecord4(snapshot)) {
+  if (!isRecord5(snapshot)) {
     errors.push(`${path} must be an object`);
     return;
   }
@@ -4274,7 +4595,7 @@ function validateSnapshotMetadata(snapshot, path, errors) {
   }
   snapshot.availableMetrics.forEach((metric, index) => {
     const metricPath = `${path}.availableMetrics[${index}]`;
-    if (!isRecord4(metric)) {
+    if (!isRecord5(metric)) {
       errors.push(`${metricPath} must be an object`);
       return;
     }
@@ -4295,7 +4616,7 @@ function validateArray2(value, path, errors) {
     errors.push(`${path} must be an array`);
   }
 }
-function isRecord4(value) {
+function isRecord5(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function toIsoTimestamp(input) {
@@ -4347,6 +4668,9 @@ function createTopolo(options) {
   defineTopoloStatsWidget,
   digestTopoloActionCatalog,
   enrichActionContract,
+  parseTopoloActionUploadContract,
+  prepareTopoloActionBase64UploadInput,
+  prepareTopoloActionUploadInput,
   requirementsForApplication,
   resolveCatalogServiceUrl,
   resolveServiceUrl,