@topolo/sdk 0.21.3 → 0.22.0

package/dist/index.cjs

@@ -52,6 +52,7 @@ __export(index_exports, {
   canonicalTopoloRequestId: () => canonicalTopoloRequestId,
   canonicalTopoloRequired: () => canonicalTopoloRequired,
   canonicalTopoloRetryAfter: () => canonicalTopoloRetryAfter,
+  canonicalTopoloServiceErrorCode: () => canonicalTopoloServiceErrorCode,
   canonicalizeActorEnvelope: () => canonicalizeActorEnvelope,
   compactActionCatalogEntry: () => compactActionCatalogEntry,
   compactActionPlan: () => compactActionPlan,
@@ -75,6 +76,7 @@ __export(index_exports, {
   enrichActionContract: () => enrichActionContract,
   extractTopoloServiceErrorCode: () => extractTopoloServiceErrorCode,
   extractTopoloServiceErrorDetails: () => extractTopoloServiceErrorDetails,
+  extractTopoloServiceErrorMessage: () => extractTopoloServiceErrorMessage,
   formatDirectoryApplicationIds: () => formatDirectoryApplicationIds,
   friendlyAppId: () => friendlyAppId,
   isTopoloWidgetOutputSchema: () => isTopoloWidgetOutputSchema,
@@ -89,6 +91,7 @@ __export(index_exports, {
   resolveApplicationDirectoryEntry: () => resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl: () => resolveCatalogServiceUrl,
   resolveServiceUrl: () => resolveServiceUrl,
+  sanitizeTopoloServiceMessage: () => sanitizeTopoloServiceMessage,
   sha256CanonicalValue: () => sha256CanonicalValue,
   topoloErrorHint: () => topoloErrorHint,
   topoloServiceOrigins: () => topoloServiceOrigins,
@@ -173,6 +176,9 @@ var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
   "unknown_service"
 ]);
 var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var SERVICE_ERROR_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*){1,9}$/;
+var SERVICE_MESSAGE_MAX_LENGTH = 300;
+var SERVICE_ISSUE_LIMIT = 32;
 var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
 var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
@@ -197,6 +203,24 @@ function canonicalTopoloErrorCode(value) {
   if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
   return candidate;
 }
+function canonicalTopoloServiceErrorCode(value) {
+  const platform = canonicalTopoloErrorCode(value);
+  if (platform) return platform;
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (candidate.length > 64 || !SERVICE_ERROR_CODE_PATTERN.test(candidate)) return null;
+  const wordLike = candidate.split("_").every((segment) => {
+    const digits = segment.replace(/[a-z]/g, "").length;
+    return digits === 0 || digits < segment.length - digits && segment.length <= 8;
+  });
+  return wordLike ? candidate : null;
+}
+function sanitizeTopoloServiceMessage(value) {
+  if (typeof value !== "string") return void 0;
+  const text2 = value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, "[url]").replace(/[^\s@<>()[\],;:"']+@[^\s@<>()[\],;:"']+\.[a-z]{2,}/gi, "[email]").replace(/[A-Za-z0-9_\-+/=.]{20,}/g, (run) => /[0-9]/.test(run) && /[A-Za-z]/.test(run) ? "[redacted]" : run).replace(/\s+/g, " ").trim();
+  if (!text2) return void 0;
+  return text2.length > SERVICE_MESSAGE_MAX_LENGTH ? `${text2.slice(0, SERVICE_MESSAGE_MAX_LENGTH - 1).trimEnd()}\u2026` : text2;
+}
 function canonicalTopoloRequestId(value) {
   if (typeof value !== "string") return void 0;
   const candidate = value.trim();
@@ -221,7 +245,7 @@ var TopoloAuthError = class extends TopoloSdkError {
   retryAfter;
   details;
   constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -245,7 +269,7 @@ var TopoloPermissionError = class extends TopoloSdkError {
   details;
   constructor(message, required, options = {}) {
     super(
-      canonicalTopoloErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
+      canonicalTopoloServiceErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
       message
     );
     this.name = "TopoloPermissionError";
@@ -264,18 +288,34 @@ var TopoloPermissionError = class extends TopoloSdkError {
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record2 = body;
-  const topLevel = canonicalTopoloErrorCode(record2.code);
+  const topLevel = canonicalTopoloServiceErrorCode(record2.code);
   if (topLevel) return topLevel;
   const nested = record2.error;
-  const nestedString = canonicalTopoloErrorCode(nested);
+  const nestedString = canonicalTopoloServiceErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    const nestedCode = canonicalTopoloErrorCode(code);
+    const nestedCode = canonicalTopoloServiceErrorCode(code);
     if (nestedCode) return nestedCode;
   }
   return null;
 }
+function extractTopoloServiceErrorMessage(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record2 = body;
+  const nested = record2.error;
+  const candidates = [];
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    candidates.push(nested.message);
+  }
+  candidates.push(record2.message, record2.error_description);
+  if (typeof nested === "string" && !canonicalTopoloServiceErrorCode(nested)) candidates.push(nested);
+  for (const candidate of candidates) {
+    const message = sanitizeTopoloServiceMessage(candidate);
+    if (message) return message;
+  }
+  return void 0;
+}
 function serviceErrorCode(body, fallback) {
   return extractTopoloServiceErrorCode(body) ?? fallback;
 }
@@ -289,10 +329,7 @@ function extractTopoloServiceErrorDetails(body) {
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
   if (candidate === void 0) candidate = record2;
-  if (Array.isArray(candidate)) {
-    const paths = canonicalTopoloValidationPaths(candidate);
-    return paths.length ? { paths } : void 0;
-  }
+  if (Array.isArray(candidate)) return validationIssueDetails(canonicalTopoloValidationIssues(candidate)) ?? void 0;
   if (!candidate || typeof candidate !== "object") return void 0;
   const source = candidate;
   const safe = {};
@@ -334,18 +371,59 @@ function extractTopoloServiceErrorDetails(body) {
       if (paths.length) safe[key] = paths;
     }
   }
+  const issues = [
+    ...Array.isArray(source.issues) ? canonicalTopoloValidationIssues(source.issues) : [],
+    ...flattenedValidationIssues(source.formErrors, source.fieldErrors)
+  ].slice(0, SERVICE_ISSUE_LIMIT);
+  Object.assign(safe, validationIssueDetails(issues));
   return Object.keys(safe).length ? safe : void 0;
 }
-function canonicalTopoloValidationPaths(issues) {
+function validationIssueDetails(issues) {
+  if (!issues.length) return null;
   const paths = [];
-  for (const issue of issues) {
-    if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record2 = issue;
+  for (const issue2 of issues) {
+    if (issue2.path && !paths.includes(issue2.path)) paths.push(issue2.path);
+  }
+  return paths.length ? { paths, issues } : { issues };
+}
+function issue(path, message) {
+  const text2 = sanitizeTopoloServiceMessage(message);
+  if (!path && !text2) return null;
+  return { ...path ? { path } : {}, ...text2 ? { message: text2 } : {} };
+}
+function canonicalTopoloValidationIssues(values) {
+  const issues = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record2 = value;
     const path = canonicalTopoloValidationPath(record2.field) ?? canonicalTopoloValidationPath(record2.path);
-    if (path && !paths.includes(path)) paths.push(path);
-    if (paths.length === 32) break;
+    if (!path) continue;
+    const projected = issue(path, record2.message);
+    if (projected) issues.push(projected);
+    if (issues.length === SERVICE_ISSUE_LIMIT) break;
+  }
+  return issues;
+}
+function flattenedValidationIssues(formErrors, fieldErrors) {
+  const issues = [];
+  if (Array.isArray(formErrors)) {
+    for (const message of formErrors) {
+      const projected = issue(void 0, message);
+      if (projected) issues.push(projected);
+    }
+  }
+  if (fieldErrors && typeof fieldErrors === "object" && !Array.isArray(fieldErrors)) {
+    for (const [key, messages] of Object.entries(fieldErrors)) {
+      const path = canonicalTopoloValidationPath(key);
+      if (!path) continue;
+      const list = Array.isArray(messages) && messages.length ? messages : [void 0];
+      for (const message of list) {
+        const projected = issue(path, message);
+        if (projected) issues.push(projected);
+      }
+    }
   }
-  return paths;
+  return issues;
 }
 function canonicalTopoloValidationPath(value) {
   if (typeof value === "string") {
@@ -367,7 +445,9 @@ function canonicalTopoloValidationPath(value) {
   return PUBLIC_FIELD_PATH_PATTERN.test(path) ? path : void 0;
 }
 function publicTopoloErrorMessage(error) {
-  const code = canonicalTopoloErrorCode(
+  const serviceMessage = typeof error === "string" ? void 0 : extractTopoloServiceErrorMessage(error.body);
+  if (serviceMessage) return serviceMessage;
+  const code = canonicalTopoloServiceErrorCode(
     typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
   ) ?? "request_failed";
   if (/(?:organization|org).*(?:enroll|membership|member|admission)/.test(code)) {
@@ -384,7 +464,7 @@ function publicTopoloErrorMessage(error) {
   return `Topolo request failed (${code}).`;
 }
 function topoloErrorHint(error) {
-  const code = canonicalTopoloErrorCode(
+  const code = canonicalTopoloServiceErrorCode(
     typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
   );
   if (!code) return void 0;
@@ -470,7 +550,8 @@ async function resolveActionSecrets(value, store, secrets) {
   if (isActionSecretReference(value)) {
     if (!store) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
     const resolved = await store.load(value);
-    if (typeof resolved === "string" && resolved) secrets.set(resolved, value);
+    if (typeof resolved !== "string" || !resolved) throw new TopoloSdkError("action_secret_unsupported_type", "Protected action handoff requires a nonempty string credential.");
+    secrets.set(resolved, value);
     return resolved;
   }
   if (Array.isArray(value)) return Promise.all(value.map((item) => resolveActionSecrets(item, store, secrets)));
@@ -891,8 +972,8 @@ function inspectSchema(schema, path, root, depth) {
   );
   for (const [key, child] of children) {
     if (!isRecord2(child)) continue;
-    const issue = inspectSchema(child, `${path}.${key}`, root, depth + 1);
-    if (issue) return issue;
+    const issue2 = inspectSchema(child, `${path}.${key}`, root, depth + 1);
+    if (issue2) return issue2;
   }
   return null;
 }
@@ -2232,7 +2313,7 @@ var TopoloClient = class _TopoloClient {
       input: selectedInput,
       inputSource: input ? "provided" : example ? "example" : "empty",
       missingFields: [...new Set(
-        plan.validation.errors.filter((issue) => issue.code === "required").map((issue) => issue.path)
+        plan.validation.errors.filter((issue2) => issue2.code === "required").map((issue2) => issue2.path)
       )],
       plan
     };
@@ -2297,7 +2378,7 @@ var TopoloClient = class _TopoloClient {
     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("; ")}`
+        `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue2) => `${issue2.path} ${issue2.message}`).join("; ")}`
       );
     }
     const resourceIssue = validateActionResource(entry, options.resource);
@@ -5073,6 +5154,7 @@ function createTopolo(options) {
   canonicalTopoloRequestId,
   canonicalTopoloRequired,
   canonicalTopoloRetryAfter,
+  canonicalTopoloServiceErrorCode,
   canonicalizeActorEnvelope,
   compactActionCatalogEntry,
   compactActionPlan,
@@ -5096,6 +5178,7 @@ function createTopolo(options) {
   enrichActionContract,
   extractTopoloServiceErrorCode,
   extractTopoloServiceErrorDetails,
+  extractTopoloServiceErrorMessage,
   formatDirectoryApplicationIds,
   friendlyAppId,
   isTopoloWidgetOutputSchema,
@@ -5110,6 +5193,7 @@ function createTopolo(options) {
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  sanitizeTopoloServiceMessage,
   sha256CanonicalValue,
   topoloErrorHint,
   topoloServiceOrigins,

package/dist/index.d.cts

@@ -922,6 +922,18 @@ declare class TopoloSdkError extends Error {
     constructor(code: string, message: string);
 }
 declare function canonicalTopoloErrorCode(value: unknown): string | null;
+/**
+ * Canonical code for a service's own error body: a platform code, or a
+ * service-published enum identifier that cannot carry identity or secret
+ * values. Everything else falls back to the caller's generic code.
+ */
+declare function canonicalTopoloServiceErrorCode(value: unknown): string | null;
+/**
+ * One line of service-authored error text that is safe to show the caller:
+ * control and bidirectional characters removed, emails, URLs and token-like
+ * runs redacted, and bounded length.
+ */
+declare function sanitizeTopoloServiceMessage(value: unknown): string | undefined;
 declare function canonicalTopoloRequestId(value: unknown): string | undefined;
 declare function canonicalTopoloRetryAfter(value: unknown): string | undefined;
 declare function canonicalTopoloRequired(value: unknown): string[];
@@ -957,7 +969,18 @@ interface HttpErrorContext {
     details?: unknown;
 }
 declare function extractTopoloServiceErrorCode(body: unknown): string | null;
+/**
+ * The service's own error message from a JSON error body (`error.message`,
+ * `message`, a prose `error` string, or OAuth `error_description`), sanitized
+ * for display. Non-object bodies such as HTML error pages yield nothing.
+ */
+declare function extractTopoloServiceErrorMessage(body: unknown): string | undefined;
 declare function extractTopoloServiceErrorDetails(body: unknown): unknown;
+/**
+ * Caller-facing message: the service's own sanitized message when its error
+ * body carries one, otherwise a fixed message derived from the code. The
+ * thrown error's `message` is never projected.
+ */
 declare function publicTopoloErrorMessage(error: string | {
     code?: string;
     body?: unknown;
@@ -1746,4 +1769,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionSecretStore, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloCredentialRequestContext, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionSecretStore, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloCredentialRequestContext, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalTopoloServiceErrorCode, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, extractTopoloServiceErrorMessage, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sanitizeTopoloServiceMessage, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.d.ts

@@ -922,6 +922,18 @@ declare class TopoloSdkError extends Error {
     constructor(code: string, message: string);
 }
 declare function canonicalTopoloErrorCode(value: unknown): string | null;
+/**
+ * Canonical code for a service's own error body: a platform code, or a
+ * service-published enum identifier that cannot carry identity or secret
+ * values. Everything else falls back to the caller's generic code.
+ */
+declare function canonicalTopoloServiceErrorCode(value: unknown): string | null;
+/**
+ * One line of service-authored error text that is safe to show the caller:
+ * control and bidirectional characters removed, emails, URLs and token-like
+ * runs redacted, and bounded length.
+ */
+declare function sanitizeTopoloServiceMessage(value: unknown): string | undefined;
 declare function canonicalTopoloRequestId(value: unknown): string | undefined;
 declare function canonicalTopoloRetryAfter(value: unknown): string | undefined;
 declare function canonicalTopoloRequired(value: unknown): string[];
@@ -957,7 +969,18 @@ interface HttpErrorContext {
     details?: unknown;
 }
 declare function extractTopoloServiceErrorCode(body: unknown): string | null;
+/**
+ * The service's own error message from a JSON error body (`error.message`,
+ * `message`, a prose `error` string, or OAuth `error_description`), sanitized
+ * for display. Non-object bodies such as HTML error pages yield nothing.
+ */
+declare function extractTopoloServiceErrorMessage(body: unknown): string | undefined;
 declare function extractTopoloServiceErrorDetails(body: unknown): unknown;
+/**
+ * Caller-facing message: the service's own sanitized message when its error
+ * body carries one, otherwise a fixed message derived from the code. The
+ * thrown error's `message` is never projected.
+ */
 declare function publicTopoloErrorMessage(error: string | {
     code?: string;
     body?: unknown;
@@ -1746,4 +1769,4 @@ declare function createTopolo(options: TopoloClientOptions): {
 };
 type Topolo = ReturnType<typeof createTopolo>;
 
-export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionSecretStore, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloCredentialRequestContext, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };
+export { ACTION_CATALOG_DIGEST_ALGORITHM, ACTOR_AUDIT_PROJECTION_VERSION, ACTOR_ENVELOPE_VERSION, type AccountableSubject, type AccountableSubjectType, type ActionContractManifest, type ActionContractSource, type ActorAssurance, type ActorAuditEventRole, type ActorAuditProjection, type ActorChannel, type ActorDelegationHop, type ActorEnvelope, ActorEnvelopeValidationError, type ActorIdentity, type ActorPrincipalType, type AgentIdentity, type AppApiId, type ApplicationCatalogEntry, type ApplicationDeployTarget, type ApplicationDirectory, type ApplicationDirectoryApplication, type ApplicationDirectoryClient, type ApplicationDirectorySource, type ApplicationId, type CredentialIntrospection, type CrmContactSummary, CrmModule, DEFAULT_APP_URLS, type DeviceAuthorizationResponse, type ExternalAgentCredentialIssueInput, type ExternalAgentCredentialIssueResult, IdentityModule, type ListContactsOptions, type ListContactsResult, type OAuthHelperOptions, type P2PActionDetail, type P2PActionRequestInput, type P2PActionRequestResult, type P2PActionRow, type P2PActionRun, type P2PCapability, type P2PConnection, type P2PHold, type P2PLedgerEntry, P2PModule, type P2PPolicy, type P2PPricingModel, type P2PSettlementBatch, type P2PSettlementGroup, type PublishCapabilityInput, type RequestOptions, type ServiceCatalogUrlEntry, TOPOLO_ACTOR_ENVELOPE_HEADER, TOPOLO_ENVIRONMENT_SERVICE_URLS, TOPOLO_RUNTIME_ENVIRONMENTS, TOPOLO_WIDGET_CONTRACT_VERSION, TOPOLO_WIDGET_ENDPOINT, TOPOLO_WIDGET_OUTPUT_SCHEMA, TOPOLO_WIDGET_REFRESH_INTERVAL_MS, type TokenResponse, type Topolo, type TopoloActionAgentContract, type TopoloActionCatalogEntry, type TopoloActionCatalogSummary, type TopoloActionDigestInput, type TopoloActionPlan, type TopoloActionPreparation, type TopoloActionSecretStore, type TopoloActionUploadOptions, type TopoloActionValidationIssue, type TopoloActionValidationResult, type TopoloActionsWidget, type TopoloActivityWidget, type TopoloAgentExecutionContext, type TopoloApiKeyResourceMetadata, TopoloAuthError, type TopoloBinaryResponse, type TopoloBindableResource, type TopoloBindableResourceCatalog, type TopoloChartWidget, TopoloClient, type TopoloClientOptions, TopoloConfirmationRequiredError, type TopoloCredential, type TopoloCredentialRequestContext, type TopoloDebugEvent, TopoloHttpError, type TopoloInlineBase64UploadContract, type TopoloJsonSchema, type TopoloNotificationsWidget, TopoloOAuth, TopoloPermissionError, type TopoloRuntimeEnvironment, TopoloSdkError, type TopoloServiceCatalogEntry, type TopoloStatsWidget, type TopoloWidget, type TopoloWidgetAccessibility, type TopoloWidgetActionBinding, type TopoloWidgetActionRecovery, type TopoloWidgetActivityItem, type TopoloWidgetApiError, type TopoloWidgetApiErrorResponse, type TopoloWidgetApiResponse, type TopoloWidgetApiSuccessResponse, type TopoloWidgetBase, type TopoloWidgetConfig, type TopoloWidgetConfiguration, type TopoloWidgetConfigurationField, type TopoloWidgetConfigurationOption, type TopoloWidgetContext, type TopoloWidgetContribution, type TopoloWidgetDatasetDefinition, type TopoloWidgetDimension, type TopoloWidgetDimensionDefinition, type TopoloWidgetDraft, type TopoloWidgetDrilldown, type TopoloWidgetErrorResponseOptions, type TopoloWidgetEventDefinition, type TopoloWidgetLifecycleStage, type TopoloWidgetLocalization, type TopoloWidgetMetric, type TopoloWidgetMetricAggregation, type TopoloWidgetMetricComparison, type TopoloWidgetMetricDefinition, type TopoloWidgetMetricSemantic, type TopoloWidgetNotificationItem, type TopoloWidgetPeriod, type TopoloWidgetPresentation, type TopoloWidgetRefreshPolicy, type TopoloWidgetResourceBinding, type TopoloWidgetResponseOptions, type TopoloWidgetSeries, type TopoloWidgetSeriesDefinition, type TopoloWidgetSeriesPoint, type TopoloWidgetSize, type TopoloWidgetState, type TopoloWidgetStatus, type TopoloWidgetType, type TopoloWidgetValidationResult, type TopoloWidgetVisualizationFamily, type TopoloWidgetWorkspaceSelector, type TopoloWorkspace, type TopoloWorkspaceListResult, type TopoloWorkspaceMutationResult, type TopoloWorkspacePolicy, WorkspacesModule, actionContractCompleteness, applicationEntryFromCatalog, assertTopoloServiceUrlEnvironment, calculateDpopJkt, canonicalJson, canonicalTopoloErrorCode, canonicalTopoloRequestId, canonicalTopoloRequired, canonicalTopoloRetryAfter, canonicalTopoloServiceErrorCode, canonicalizeActorEnvelope, compactActionCatalogEntry, compactActionPlan, compactActionPreparation, compactActionResult, compactActionValidation, createDpopProof, createTopolo, createTopoloAgentExecutionContext, createTopoloWidgetError, createTopoloWidgetResponse, decodeActorEnvelopeHeader, defineTopoloActionsWidget, defineTopoloActivityWidget, defineTopoloChartWidget, defineTopoloNotificationsWidget, defineTopoloStatsWidget, digestTopoloActionCatalog, encodeActorEnvelopeHeader, encodeTopoloActionBase64, enrichActionContract, extractTopoloServiceErrorCode, extractTopoloServiceErrorDetails, extractTopoloServiceErrorMessage, formatDirectoryApplicationIds, friendlyAppId, isTopoloWidgetOutputSchema, listApplicationDirectory, parseActorEnvelope, parseTopoloActionUploadContract, preferExactActionMatches, prepareTopoloActionBase64UploadInput, prepareTopoloActionUploadInput, projectActorAuditEvent, publicTopoloErrorMessage, resolveApplicationDirectoryEntry, resolveCatalogServiceUrl, resolveServiceUrl, sanitizeTopoloServiceMessage, sha256CanonicalValue, topoloErrorHint, topoloServiceOrigins, validateTopoloActionInput, validateTopoloWidgetResponse };

package/dist/index.js

@@ -74,6 +74,9 @@ var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
   "unknown_service"
 ]);
 var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var SERVICE_ERROR_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*){1,9}$/;
+var SERVICE_MESSAGE_MAX_LENGTH = 300;
+var SERVICE_ISSUE_LIMIT = 32;
 var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
 var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
@@ -98,6 +101,24 @@ function canonicalTopoloErrorCode(value) {
   if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
   return candidate;
 }
+function canonicalTopoloServiceErrorCode(value) {
+  const platform = canonicalTopoloErrorCode(value);
+  if (platform) return platform;
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (candidate.length > 64 || !SERVICE_ERROR_CODE_PATTERN.test(candidate)) return null;
+  const wordLike = candidate.split("_").every((segment) => {
+    const digits = segment.replace(/[a-z]/g, "").length;
+    return digits === 0 || digits < segment.length - digits && segment.length <= 8;
+  });
+  return wordLike ? candidate : null;
+}
+function sanitizeTopoloServiceMessage(value) {
+  if (typeof value !== "string") return void 0;
+  const text2 = value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, "[url]").replace(/[^\s@<>()[\],;:"']+@[^\s@<>()[\],;:"']+\.[a-z]{2,}/gi, "[email]").replace(/[A-Za-z0-9_\-+/=.]{20,}/g, (run) => /[0-9]/.test(run) && /[A-Za-z]/.test(run) ? "[redacted]" : run).replace(/\s+/g, " ").trim();
+  if (!text2) return void 0;
+  return text2.length > SERVICE_MESSAGE_MAX_LENGTH ? `${text2.slice(0, SERVICE_MESSAGE_MAX_LENGTH - 1).trimEnd()}\u2026` : text2;
+}
 function canonicalTopoloRequestId(value) {
   if (typeof value !== "string") return void 0;
   const candidate = value.trim();
@@ -122,7 +143,7 @@ var TopoloAuthError = class extends TopoloSdkError {
   retryAfter;
   details;
   constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -146,7 +167,7 @@ var TopoloPermissionError = class extends TopoloSdkError {
   details;
   constructor(message, required, options = {}) {
     super(
-      canonicalTopoloErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
+      canonicalTopoloServiceErrorCode(options.code) ?? serviceErrorCode(options.body, "permission_denied"),
       message
     );
     this.name = "TopoloPermissionError";
@@ -165,18 +186,34 @@ var TopoloPermissionError = class extends TopoloSdkError {
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record2 = body;
-  const topLevel = canonicalTopoloErrorCode(record2.code);
+  const topLevel = canonicalTopoloServiceErrorCode(record2.code);
   if (topLevel) return topLevel;
   const nested = record2.error;
-  const nestedString = canonicalTopoloErrorCode(nested);
+  const nestedString = canonicalTopoloServiceErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    const nestedCode = canonicalTopoloErrorCode(code);
+    const nestedCode = canonicalTopoloServiceErrorCode(code);
     if (nestedCode) return nestedCode;
   }
   return null;
 }
+function extractTopoloServiceErrorMessage(body) {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return void 0;
+  const record2 = body;
+  const nested = record2.error;
+  const candidates = [];
+  if (nested && typeof nested === "object" && !Array.isArray(nested)) {
+    candidates.push(nested.message);
+  }
+  candidates.push(record2.message, record2.error_description);
+  if (typeof nested === "string" && !canonicalTopoloServiceErrorCode(nested)) candidates.push(nested);
+  for (const candidate of candidates) {
+    const message = sanitizeTopoloServiceMessage(candidate);
+    if (message) return message;
+  }
+  return void 0;
+}
 function serviceErrorCode(body, fallback) {
   return extractTopoloServiceErrorCode(body) ?? fallback;
 }
@@ -190,10 +227,7 @@ function extractTopoloServiceErrorDetails(body) {
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
   if (candidate === void 0) candidate = record2;
-  if (Array.isArray(candidate)) {
-    const paths = canonicalTopoloValidationPaths(candidate);
-    return paths.length ? { paths } : void 0;
-  }
+  if (Array.isArray(candidate)) return validationIssueDetails(canonicalTopoloValidationIssues(candidate)) ?? void 0;
   if (!candidate || typeof candidate !== "object") return void 0;
   const source = candidate;
   const safe = {};
@@ -235,18 +269,59 @@ function extractTopoloServiceErrorDetails(body) {
       if (paths.length) safe[key] = paths;
     }
   }
+  const issues = [
+    ...Array.isArray(source.issues) ? canonicalTopoloValidationIssues(source.issues) : [],
+    ...flattenedValidationIssues(source.formErrors, source.fieldErrors)
+  ].slice(0, SERVICE_ISSUE_LIMIT);
+  Object.assign(safe, validationIssueDetails(issues));
   return Object.keys(safe).length ? safe : void 0;
 }
-function canonicalTopoloValidationPaths(issues) {
+function validationIssueDetails(issues) {
+  if (!issues.length) return null;
   const paths = [];
-  for (const issue of issues) {
-    if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record2 = issue;
+  for (const issue2 of issues) {
+    if (issue2.path && !paths.includes(issue2.path)) paths.push(issue2.path);
+  }
+  return paths.length ? { paths, issues } : { issues };
+}
+function issue(path, message) {
+  const text2 = sanitizeTopoloServiceMessage(message);
+  if (!path && !text2) return null;
+  return { ...path ? { path } : {}, ...text2 ? { message: text2 } : {} };
+}
+function canonicalTopoloValidationIssues(values) {
+  const issues = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record2 = value;
     const path = canonicalTopoloValidationPath(record2.field) ?? canonicalTopoloValidationPath(record2.path);
-    if (path && !paths.includes(path)) paths.push(path);
-    if (paths.length === 32) break;
+    if (!path) continue;
+    const projected = issue(path, record2.message);
+    if (projected) issues.push(projected);
+    if (issues.length === SERVICE_ISSUE_LIMIT) break;
+  }
+  return issues;
+}
+function flattenedValidationIssues(formErrors, fieldErrors) {
+  const issues = [];
+  if (Array.isArray(formErrors)) {
+    for (const message of formErrors) {
+      const projected = issue(void 0, message);
+      if (projected) issues.push(projected);
+    }
+  }
+  if (fieldErrors && typeof fieldErrors === "object" && !Array.isArray(fieldErrors)) {
+    for (const [key, messages] of Object.entries(fieldErrors)) {
+      const path = canonicalTopoloValidationPath(key);
+      if (!path) continue;
+      const list = Array.isArray(messages) && messages.length ? messages : [void 0];
+      for (const message of list) {
+        const projected = issue(path, message);
+        if (projected) issues.push(projected);
+      }
+    }
   }
-  return paths;
+  return issues;
 }
 function canonicalTopoloValidationPath(value) {
   if (typeof value === "string") {
@@ -268,7 +343,9 @@ function canonicalTopoloValidationPath(value) {
   return PUBLIC_FIELD_PATH_PATTERN.test(path) ? path : void 0;
 }
 function publicTopoloErrorMessage(error) {
-  const code = canonicalTopoloErrorCode(
+  const serviceMessage = typeof error === "string" ? void 0 : extractTopoloServiceErrorMessage(error.body);
+  if (serviceMessage) return serviceMessage;
+  const code = canonicalTopoloServiceErrorCode(
     typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
   ) ?? "request_failed";
   if (/(?:organization|org).*(?:enroll|membership|member|admission)/.test(code)) {
@@ -285,7 +362,7 @@ function publicTopoloErrorMessage(error) {
   return `Topolo request failed (${code}).`;
 }
 function topoloErrorHint(error) {
-  const code = canonicalTopoloErrorCode(
+  const code = canonicalTopoloServiceErrorCode(
     typeof error === "string" ? error : error.code ?? extractTopoloServiceErrorCode(error.body)
   );
   if (!code) return void 0;
@@ -371,7 +448,8 @@ async function resolveActionSecrets(value, store, secrets) {
   if (isActionSecretReference(value)) {
     if (!store) throw new TopoloSdkError("action_secret_store_required", "Protected action references require a secret store.");
     const resolved = await store.load(value);
-    if (typeof resolved === "string" && resolved) secrets.set(resolved, value);
+    if (typeof resolved !== "string" || !resolved) throw new TopoloSdkError("action_secret_unsupported_type", "Protected action handoff requires a nonempty string credential.");
+    secrets.set(resolved, value);
     return resolved;
   }
   if (Array.isArray(value)) return Promise.all(value.map((item) => resolveActionSecrets(item, store, secrets)));
@@ -792,8 +870,8 @@ function inspectSchema(schema, path, root, depth) {
   );
   for (const [key, child] of children) {
     if (!isRecord2(child)) continue;
-    const issue = inspectSchema(child, `${path}.${key}`, root, depth + 1);
-    if (issue) return issue;
+    const issue2 = inspectSchema(child, `${path}.${key}`, root, depth + 1);
+    if (issue2) return issue2;
   }
   return null;
 }
@@ -2133,7 +2211,7 @@ var TopoloClient = class _TopoloClient {
       input: selectedInput,
       inputSource: input ? "provided" : example ? "example" : "empty",
       missingFields: [...new Set(
-        plan.validation.errors.filter((issue) => issue.code === "required").map((issue) => issue.path)
+        plan.validation.errors.filter((issue2) => issue2.code === "required").map((issue2) => issue2.path)
       )],
       plan
     };
@@ -2198,7 +2276,7 @@ var TopoloClient = class _TopoloClient {
     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("; ")}`
+        `Topolo action "${entry.actionId}" input is invalid: ${validation.errors.map((issue2) => `${issue2.path} ${issue2.message}`).join("; ")}`
       );
     }
     const resourceIssue = validateActionResource(entry, options.resource);
@@ -4973,6 +5051,7 @@ export {
   canonicalTopoloRequestId,
   canonicalTopoloRequired,
   canonicalTopoloRetryAfter,
+  canonicalTopoloServiceErrorCode,
   canonicalizeActorEnvelope,
   compactActionCatalogEntry,
   compactActionPlan,
@@ -4996,6 +5075,7 @@ export {
   enrichActionContract,
   extractTopoloServiceErrorCode,
   extractTopoloServiceErrorDetails,
+  extractTopoloServiceErrorMessage,
   formatDirectoryApplicationIds,
   friendlyAppId,
   isTopoloWidgetOutputSchema,
@@ -5010,6 +5090,7 @@ export {
   resolveApplicationDirectoryEntry,
   resolveCatalogServiceUrl,
   resolveServiceUrl,
+  sanitizeTopoloServiceMessage,
   sha256CanonicalValue,
   topoloErrorHint,
   topoloServiceOrigins,

package/dist/node/credential-store.cjs

@@ -114,6 +114,9 @@ var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
   "unknown_service"
 ]);
 var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var SERVICE_ERROR_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*){1,9}$/;
+var SERVICE_MESSAGE_MAX_LENGTH = 300;
+var SERVICE_ISSUE_LIMIT = 32;
 var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
 var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
@@ -138,6 +141,24 @@ function canonicalTopoloErrorCode(value) {
   if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
   return candidate;
 }
+function canonicalTopoloServiceErrorCode(value) {
+  const platform2 = canonicalTopoloErrorCode(value);
+  if (platform2) return platform2;
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (candidate.length > 64 || !SERVICE_ERROR_CODE_PATTERN.test(candidate)) return null;
+  const wordLike = candidate.split("_").every((segment) => {
+    const digits = segment.replace(/[a-z]/g, "").length;
+    return digits === 0 || digits < segment.length - digits && segment.length <= 8;
+  });
+  return wordLike ? candidate : null;
+}
+function sanitizeTopoloServiceMessage(value) {
+  if (typeof value !== "string") return void 0;
+  const text = value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, "[url]").replace(/[^\s@<>()[\],;:"']+@[^\s@<>()[\],;:"']+\.[a-z]{2,}/gi, "[email]").replace(/[A-Za-z0-9_\-+/=.]{20,}/g, (run) => /[0-9]/.test(run) && /[A-Za-z]/.test(run) ? "[redacted]" : run).replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  return text.length > SERVICE_MESSAGE_MAX_LENGTH ? `${text.slice(0, SERVICE_MESSAGE_MAX_LENGTH - 1).trimEnd()}\u2026` : text;
+}
 function canonicalTopoloRequestId(value) {
   if (typeof value !== "string") return void 0;
   const candidate = value.trim();
@@ -162,7 +183,7 @@ var TopoloAuthError = class extends TopoloSdkError {
   retryAfter;
   details;
   constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -178,14 +199,14 @@ var TopoloAuthError = class extends TopoloSdkError {
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record = body;
-  const topLevel = canonicalTopoloErrorCode(record.code);
+  const topLevel = canonicalTopoloServiceErrorCode(record.code);
   if (topLevel) return topLevel;
   const nested = record.error;
-  const nestedString = canonicalTopoloErrorCode(nested);
+  const nestedString = canonicalTopoloServiceErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    const nestedCode = canonicalTopoloErrorCode(code);
+    const nestedCode = canonicalTopoloServiceErrorCode(code);
     if (nestedCode) return nestedCode;
   }
   return null;
@@ -203,10 +224,7 @@ function extractTopoloServiceErrorDetails(body) {
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
   if (candidate === void 0) candidate = record;
-  if (Array.isArray(candidate)) {
-    const paths = canonicalTopoloValidationPaths(candidate);
-    return paths.length ? { paths } : void 0;
-  }
+  if (Array.isArray(candidate)) return validationIssueDetails(canonicalTopoloValidationIssues(candidate)) ?? void 0;
   if (!candidate || typeof candidate !== "object") return void 0;
   const source = candidate;
   const safe = {};
@@ -248,18 +266,59 @@ function extractTopoloServiceErrorDetails(body) {
       if (paths.length) safe[key] = paths;
     }
   }
+  const issues = [
+    ...Array.isArray(source.issues) ? canonicalTopoloValidationIssues(source.issues) : [],
+    ...flattenedValidationIssues(source.formErrors, source.fieldErrors)
+  ].slice(0, SERVICE_ISSUE_LIMIT);
+  Object.assign(safe, validationIssueDetails(issues));
   return Object.keys(safe).length ? safe : void 0;
 }
-function canonicalTopoloValidationPaths(issues) {
+function validationIssueDetails(issues) {
+  if (!issues.length) return null;
   const paths = [];
-  for (const issue of issues) {
-    if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record = issue;
+  for (const issue2 of issues) {
+    if (issue2.path && !paths.includes(issue2.path)) paths.push(issue2.path);
+  }
+  return paths.length ? { paths, issues } : { issues };
+}
+function issue(path, message) {
+  const text = sanitizeTopoloServiceMessage(message);
+  if (!path && !text) return null;
+  return { ...path ? { path } : {}, ...text ? { message: text } : {} };
+}
+function canonicalTopoloValidationIssues(values) {
+  const issues = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record = value;
     const path = canonicalTopoloValidationPath(record.field) ?? canonicalTopoloValidationPath(record.path);
-    if (path && !paths.includes(path)) paths.push(path);
-    if (paths.length === 32) break;
+    if (!path) continue;
+    const projected = issue(path, record.message);
+    if (projected) issues.push(projected);
+    if (issues.length === SERVICE_ISSUE_LIMIT) break;
+  }
+  return issues;
+}
+function flattenedValidationIssues(formErrors, fieldErrors) {
+  const issues = [];
+  if (Array.isArray(formErrors)) {
+    for (const message of formErrors) {
+      const projected = issue(void 0, message);
+      if (projected) issues.push(projected);
+    }
+  }
+  if (fieldErrors && typeof fieldErrors === "object" && !Array.isArray(fieldErrors)) {
+    for (const [key, messages] of Object.entries(fieldErrors)) {
+      const path = canonicalTopoloValidationPath(key);
+      if (!path) continue;
+      const list = Array.isArray(messages) && messages.length ? messages : [void 0];
+      for (const message of list) {
+        const projected = issue(path, message);
+        if (projected) issues.push(projected);
+      }
+    }
   }
-  return paths;
+  return issues;
 }
 function canonicalTopoloValidationPath(value) {
   if (typeof value === "string") {

package/dist/node/credential-store.js

@@ -60,6 +60,9 @@ var PUBLIC_ERROR_CODES = /* @__PURE__ */ new Set([
   "unknown_service"
 ]);
 var ERROR_CODE_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
+var SERVICE_ERROR_CODE_PATTERN = /^[a-z][a-z0-9]*(?:_[a-z][a-z0-9]*){1,9}$/;
+var SERVICE_MESSAGE_MAX_LENGTH = 300;
+var SERVICE_ISSUE_LIMIT = 32;
 var TOPOLO_REQUEST_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 var CLOUDFLARE_RAY_ID_PATTERN = /^[0-9a-f]{16}-[A-Z]{3}$/;
 var PERMISSION_PATTERN = /^[a-z][a-z0-9_-]{0,63}(?:\.[a-z][a-z0-9_-]{0,63})*:(?:[a-z][a-z0-9_-]{0,63}|\*)$/;
@@ -84,6 +87,24 @@ function canonicalTopoloErrorCode(value) {
   if (!ERROR_CODE_PATTERN.test(candidate) || !PUBLIC_ERROR_CODES.has(candidate)) return null;
   return candidate;
 }
+function canonicalTopoloServiceErrorCode(value) {
+  const platform2 = canonicalTopoloErrorCode(value);
+  if (platform2) return platform2;
+  if (typeof value !== "string") return null;
+  const candidate = value.trim();
+  if (candidate.length > 64 || !SERVICE_ERROR_CODE_PATTERN.test(candidate)) return null;
+  const wordLike = candidate.split("_").every((segment) => {
+    const digits = segment.replace(/[a-z]/g, "").length;
+    return digits === 0 || digits < segment.length - digits && segment.length <= 8;
+  });
+  return wordLike ? candidate : null;
+}
+function sanitizeTopoloServiceMessage(value) {
+  if (typeof value !== "string") return void 0;
+  const text = value.replace(/[\u0000-\u001f\u007f-\u009f\u200b-\u200f\u2028-\u202e\u2066-\u2069\ufeff]/g, " ").replace(/\b[a-z][a-z0-9+.-]*:\/\/\S+/gi, "[url]").replace(/[^\s@<>()[\],;:"']+@[^\s@<>()[\],;:"']+\.[a-z]{2,}/gi, "[email]").replace(/[A-Za-z0-9_\-+/=.]{20,}/g, (run) => /[0-9]/.test(run) && /[A-Za-z]/.test(run) ? "[redacted]" : run).replace(/\s+/g, " ").trim();
+  if (!text) return void 0;
+  return text.length > SERVICE_MESSAGE_MAX_LENGTH ? `${text.slice(0, SERVICE_MESSAGE_MAX_LENGTH - 1).trimEnd()}\u2026` : text;
+}
 function canonicalTopoloRequestId(value) {
   if (typeof value !== "string") return void 0;
   const candidate = value.trim();
@@ -108,7 +129,7 @@ var TopoloAuthError = class extends TopoloSdkError {
   retryAfter;
   details;
   constructor(message, code = "auth_error", options = {}) {
-    super(canonicalTopoloErrorCode(code) ?? "auth_error", message);
+    super(canonicalTopoloServiceErrorCode(code) ?? "auth_error", message);
     this.name = "TopoloAuthError";
     this.status = options.status ?? 401;
     this.body = options.body;
@@ -124,14 +145,14 @@ var TopoloAuthError = class extends TopoloSdkError {
 function extractTopoloServiceErrorCode(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) return null;
   const record = body;
-  const topLevel = canonicalTopoloErrorCode(record.code);
+  const topLevel = canonicalTopoloServiceErrorCode(record.code);
   if (topLevel) return topLevel;
   const nested = record.error;
-  const nestedString = canonicalTopoloErrorCode(nested);
+  const nestedString = canonicalTopoloServiceErrorCode(nested);
   if (nestedString) return nestedString;
   if (nested && typeof nested === "object" && !Array.isArray(nested)) {
     const code = nested.code;
-    const nestedCode = canonicalTopoloErrorCode(code);
+    const nestedCode = canonicalTopoloServiceErrorCode(code);
     if (nestedCode) return nestedCode;
   }
   return null;
@@ -149,10 +170,7 @@ function extractTopoloServiceErrorDetails(body) {
     if (candidate === void 0) candidate = nestedRecord.details ?? nestedRecord;
   }
   if (candidate === void 0) candidate = record;
-  if (Array.isArray(candidate)) {
-    const paths = canonicalTopoloValidationPaths(candidate);
-    return paths.length ? { paths } : void 0;
-  }
+  if (Array.isArray(candidate)) return validationIssueDetails(canonicalTopoloValidationIssues(candidate)) ?? void 0;
   if (!candidate || typeof candidate !== "object") return void 0;
   const source = candidate;
   const safe = {};
@@ -194,18 +212,59 @@ function extractTopoloServiceErrorDetails(body) {
       if (paths.length) safe[key] = paths;
     }
   }
+  const issues = [
+    ...Array.isArray(source.issues) ? canonicalTopoloValidationIssues(source.issues) : [],
+    ...flattenedValidationIssues(source.formErrors, source.fieldErrors)
+  ].slice(0, SERVICE_ISSUE_LIMIT);
+  Object.assign(safe, validationIssueDetails(issues));
   return Object.keys(safe).length ? safe : void 0;
 }
-function canonicalTopoloValidationPaths(issues) {
+function validationIssueDetails(issues) {
+  if (!issues.length) return null;
   const paths = [];
-  for (const issue of issues) {
-    if (!issue || typeof issue !== "object" || Array.isArray(issue)) continue;
-    const record = issue;
+  for (const issue2 of issues) {
+    if (issue2.path && !paths.includes(issue2.path)) paths.push(issue2.path);
+  }
+  return paths.length ? { paths, issues } : { issues };
+}
+function issue(path, message) {
+  const text = sanitizeTopoloServiceMessage(message);
+  if (!path && !text) return null;
+  return { ...path ? { path } : {}, ...text ? { message: text } : {} };
+}
+function canonicalTopoloValidationIssues(values) {
+  const issues = [];
+  for (const value of values) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+    const record = value;
     const path = canonicalTopoloValidationPath(record.field) ?? canonicalTopoloValidationPath(record.path);
-    if (path && !paths.includes(path)) paths.push(path);
-    if (paths.length === 32) break;
+    if (!path) continue;
+    const projected = issue(path, record.message);
+    if (projected) issues.push(projected);
+    if (issues.length === SERVICE_ISSUE_LIMIT) break;
+  }
+  return issues;
+}
+function flattenedValidationIssues(formErrors, fieldErrors) {
+  const issues = [];
+  if (Array.isArray(formErrors)) {
+    for (const message of formErrors) {
+      const projected = issue(void 0, message);
+      if (projected) issues.push(projected);
+    }
+  }
+  if (fieldErrors && typeof fieldErrors === "object" && !Array.isArray(fieldErrors)) {
+    for (const [key, messages] of Object.entries(fieldErrors)) {
+      const path = canonicalTopoloValidationPath(key);
+      if (!path) continue;
+      const list = Array.isArray(messages) && messages.length ? messages : [void 0];
+      for (const message of list) {
+        const projected = issue(path, message);
+        if (projected) issues.push(projected);
+      }
+    }
   }
-  return paths;
+  return issues;
 }
 function canonicalTopoloValidationPath(value) {
   if (typeof value === "string") {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@topolo/sdk",
   "packageManager": "pnpm@10.17.1",
-  "version": "0.21.3",
-  "topoloPublishedVersion": "0.21.3",
+  "version": "0.22.0",
+  "topoloPublishedVersion": "0.22.0",
   "description": "Typed client SDK for the Topolo platform. Used by TopoloCli, TopoloMCP, and third-party agents.",
   "license": "UNLICENSED",
   "author": "Topolo",