@slates/provider 1.0.0-rc.28 → 1.0.0-rc.30

package/src/axios/trace.ts

@@ -1,5 +1,8 @@
 import type { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from 'axios';
-import { AuthConfigSecretRedactor } from '../auth/redact';
+import {
+  AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX,
+  AuthConfigSecretRedactor
+} from '../auth/redact';
 import type { SlatePublicContext } from '../context';
 
 export interface SlateHttpTraceTextBody {
@@ -84,6 +87,9 @@ let CORE_SECRET_KEY_ATOMS = [
   'app[-_.]?key',
   'x[-_.]?api[-_.]?key',
   'x[-_.]?app[-_.]?key',
+  // HubSpot legacy API key query param
+  'hapikey',
+  'access[-_.]?key',
 
   // OAuth client credentials
   'client[-_.]?secret',
@@ -149,6 +155,9 @@ let CORE_SECRET_KEY_ATOMS = [
   'session[-_.]?id',
   'sessionid',
   'sid',
+  'sessid',
+  'jsessionid',
+  'phpsessid',
   'cookie',
   'cookies',
   'set[-_.]?cookie',
@@ -255,18 +264,119 @@ let NON_SECRET_KEY_EXACT = new Set<string>([
   'kid'
 ]);
 
-let isSecretKeyName = (name: string): boolean => {
+export let isSecretKeyName = (name: string): boolean => {
   let normalized = name.toLowerCase();
   if (NON_SECRET_KEY_EXACT.has(normalized)) return false;
   return SECRET_KEY_PATTERN.test(normalized);
 };
 
+// Whole query/form names that carry a credential only in URLs: Google's `?key=AIza...`.
+// Matched exactly so compound names such as `sort_key` or `partition_key` stay visible.
+let URL_FORM_EXACT_SECRET_KEYS = new Set(['key']);
+
 let isUrlFormSecretKeyName = (name: string): boolean => {
   let normalized = name.toLowerCase();
   if (NON_SECRET_KEY_EXACT.has(normalized)) return false;
+  if (URL_FORM_EXACT_SECRET_KEYS.has(normalized)) return true;
   return URL_FORM_SECRET_KEY_PATTERN.test(normalized);
 };
 
+let splitCamelCase = (key: string) => key.replace(/([a-z0-9])([A-Z])/g, '$1_$2');
+
+// `githubToken` -> ['github', 'token'], `ASP.NET_SessionId` -> ['asp', 'net', 'session', 'id'].
+export let splitKeyParts = (key: string) =>
+  splitCamelCase(key)
+    .toLowerCase()
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean);
+
+// A compound key ending in one of these describes a secret (its count, expiry, URL,
+// type, error, ...) rather than holding it: `tokenCount`, `sessionTimeout`,
+// `authError`, `signatureValid`, `authorizationUrl`, `token_type`, `tokenExpiresAt`.
+let NON_SECRET_KEY_SUFFIXES = new Set([
+  'count',
+  'limit',
+  'timeout',
+  'expired',
+  'expires',
+  'expiry',
+  'at',
+  'valid',
+  'url',
+  'uri',
+  'error',
+  'type',
+  'id',
+  'ids',
+  'name'
+]);
+
+// Pagination cursors, not credentials.
+let NON_SECRET_FIELD_KEYS = new Set([
+  'page_token',
+  'next_page_token',
+  'prev_page_token',
+  'previous_page_token',
+  'next_token',
+  'continuation_token'
+]);
+
+// `<qualifier>_id` keys that are credentials despite the `id` suffix: session IDs
+// (`sessionId`, `user_session_ids`, `ASP.NET_SessionId`) and `secret_id`.
+let SECRET_ID_QUALIFIERS = new Set(['session', 'sess', 'secret']);
+
+/**
+ * Split-camelCase-aware secret field classifier shared by error baggage, auth-config
+ * path checks, and the prose `key: value` scan. Matches camelCase keys
+ * (`githubToken`, `apiSecret`, `accessKey`) and bare `session` keys, but not keys that
+ * describe a secret (`tokenCount`, `token_type`) or pagination cursors (`pageToken`).
+ */
+export let isSecretFieldName = (key: string): boolean => {
+  let parts = splitKeyParts(key);
+  if (parts.length === 0) return false;
+  let normalized = parts.join('_');
+  if (NON_SECRET_FIELD_KEYS.has(normalized)) return false;
+
+  let last = parts[parts.length - 1] ?? '';
+  if (parts.length > 1 && NON_SECRET_KEY_SUFFIXES.has(last)) {
+    return (
+      (last === 'id' || last === 'ids') &&
+      SECRET_ID_QUALIFIERS.has(parts[parts.length - 2] ?? '')
+    );
+  }
+
+  return isSecretKeyName(key) || isSecretKeyName(normalized) || parts.includes('session');
+};
+
+// Auth-config fields named for the credential's role rather than its kind:
+// `subscriptionKey`, `writeKey`, `integrationKey`, `provisioningHash`.
+let AUTH_CONFIG_CREDENTIAL_SUFFIXES = new Set(['key', 'keys', 'hash']);
+
+// `tokenHeader: 'authorization'` names a header; it does not hold a credential.
+let HEADER_NAME_VALUE_PATTERN = /^[A-Za-z]+(?:-[A-Za-z]+)*$/;
+
+/**
+ * Whether an auth-config value at `path` (e.g. `oauth.accessToken`, `apiKeys.0`) is a
+ * credential worth replacing in diagnostics. Only secret-named fields qualify: auth
+ * configs also hold account IDs, emails, subdomains, scopes, and token types, and
+ * replacing those wherever they appear destroys useful context. Field names are chosen
+ * by integration authors and describe credentials consistently (`token`, `apiKey`,
+ * `clientSecret`, `password`, `*Key`), while an entropy fallback would also hit
+ * high-entropy non-secrets such as `clientId`, `tenantId`, or `cloudId`.
+ */
+export let isAuthConfigSecretValue = (secret: string, path: string): boolean => {
+  let segment = path
+    .split('.')
+    .reverse()
+    .find(part => !/^\d+$/.test(part));
+  if (!segment) return false;
+
+  let parts = splitKeyParts(segment);
+  let last = parts[parts.length - 1] ?? '';
+  if (last === 'header' && HEADER_NAME_VALUE_PATTERN.test(secret)) return false;
+  return isSecretFieldName(segment) || AUTH_CONFIG_CREDENTIAL_SUFFIXES.has(last);
+};
+
 // Patterns that identify well-known secret values regardless of the surrounding key.
 // Keeps low false-positive risk by matching formats that are unlikely to occur otherwise.
 let KNOWN_SECRET_VALUE_PATTERNS: RegExp[] = [
@@ -360,6 +470,14 @@ let isTextContentType = (contentType?: string) =>
   !contentType ||
   /(^text\/)|json|xml|html|javascript|graphql|x-www-form-urlencoded|svg/.test(contentType);
 
+let redactKnownSecretValues = (text: string) => {
+  let result = text;
+  for (let pattern of KNOWN_SECRET_VALUE_PATTERNS) {
+    result = result.replace(pattern, REDACTED_VALUE);
+  }
+  return result;
+};
+
 let isSafeHeaderName = (name: string) => {
   let normalized = name.toLowerCase();
   if (isSecretKeyName(normalized)) return false;
@@ -383,16 +501,14 @@ let sanitizeFreeText = (text: string, redactor?: AuthConfigSecretRedactor) => {
 
   // Literal auth-config secret values are replaced first -- this catches secrets sitting
   // under a key name the heuristics below don't recognize as secret-like.
-  let result = redactor ? redactor.redact(text) : text;
+  let result = redactor ? redactor.redact(text, isAuthConfigSecretValue) : text;
 
   result = result.replace(
     HTTP_AUTH_SCHEME_PATTERN,
     (_match, scheme: string) => `${scheme} ${REDACTED_VALUE}`
   );
 
-  for (let pattern of KNOWN_SECRET_VALUE_PATTERNS) {
-    result = result.replace(pattern, REDACTED_VALUE);
-  }
+  result = redactKnownSecretValues(result);
 
   result = result.replace(
     GENERIC_KEY_VALUE_PATTERN,
@@ -409,6 +525,185 @@ let sanitizeFreeText = (text: string, redactor?: AuthConfigSecretRedactor) => {
   return result;
 };
 
+// A credential after an auth scheme word, so messages like "Invalid token provided"
+// or "Basic plan required" are left intact (see looksLikeCredential).
+let PROSE_SAFE_AUTH_SCHEME_PATTERN =
+  /\b(bearer|basic|digest|token|negotiate|apikey)(\s+)([A-Za-z0-9_\-.~+/=]{8,})/gi;
+
+// A value counts as a credential when it carries a digit or token punctuation, or mixes
+// case past its first character (base64 such as `dXNlcjpwYXNz`). Plain lowercase or
+// Title-case words are prose. `key=value` fragments are left to the key/value scan so
+// "token code=404" is not mistaken for a credential.
+let looksLikeCredential = (value: string) => {
+  if (/^[A-Za-z][A-Za-z0-9_\-.]*=/.test(value)) return false;
+  return /[0-9_\-.~+/=]/.test(value) || (/[a-z]/.test(value) && /[A-Z]/.test(value.slice(1)));
+};
+
+// Credential header names in free text. The value runs to the closing quote when it is
+// quoted, otherwise to the end of the line or the next `&`; redactCredentialHeaderValue
+// decides how much of it is the credential.
+let CREDENTIAL_HEADER_VALUE_PATTERN =
+  /\b(proxy-authorization|authorization|x-api-key|api[-_]?key|set-cookie|cookie)(\s*[:=]\s*)(?:(["'])((?:\\.|(?!\3)[^\\\r\n])*)|([^\r\n&]*))/gi;
+
+let AUTH_SCHEME_WORD_PATTERN = /^(?:bearer|basic|digest|token|negotiate|apikey)$/i;
+
+let COOKIE_HEADER_NAME_PATTERN = /^(?:set-)?cookie$/i;
+let AUTHORIZATION_HEADER_NAME_PATTERN = /^(?:proxy-)?authorization$/i;
+
+// `sid=1; theme=dark`: a cookie pair followed by any chained pairs.
+let COOKIE_PAIRS_PATTERN = /^[^\s;=&"',]+=[^\s;&"',]*(?:;\s*[^\s;=&"',]+=[^\s;&"',]*)*/;
+let HEADER_TOKEN_PATTERN = /^[^\s&"',;]+/;
+// A scheme word (`Bearer`, `OAuth`, `Bot`, `SSWS`, `Zoho-oauthtoken`, `Klaviyo-API-Key`)
+// followed by its credential.
+let HEADER_SCHEME_PATTERN = /^([A-Za-z][\w-]*)(\s+)([\s\S]*)$/;
+// `Digest username="x", response="..."`, `AWS4-HMAC-SHA256 Credential=..., Signature=...`.
+let HEADER_AUTH_PARAMS_PATTERN = /^[A-Za-z][\w-]*\s*=/;
+
+// Header values are redacted only when they hold a credential, so prose such as
+// `Authorization: missing or invalid` or `Missing cookie: please log in` stays readable.
+let redactCredentialHeaderValue = (name: string, value: string) => {
+  if (COOKIE_HEADER_NAME_PATTERN.test(name)) {
+    let pairs = COOKIE_PAIRS_PATTERN.exec(value)?.[0];
+    if (pairs) return `${REDACTED_VALUE}${value.slice(pairs.length)}`;
+  }
+
+  let scheme = HEADER_SCHEME_PATTERN.exec(value);
+  if (scheme) {
+    let [, word = '', space = '', rest = ''] = scheme;
+    let schemePrefix = `${word}${space}`;
+    if (
+      AUTHORIZATION_HEADER_NAME_PATTERN.test(name) &&
+      HEADER_AUTH_PARAMS_PATTERN.test(rest)
+    ) {
+      // Auth-param lists carry the credential in any parameter, so all of them go.
+      return `${schemePrefix}${REDACTED_VALUE}`;
+    }
+
+    let credential = HEADER_TOKEN_PATTERN.exec(rest)?.[0];
+    if (credential === REDACTED_VALUE) return value;
+    if (
+      credential &&
+      (AUTH_SCHEME_WORD_PATTERN.test(word) || looksLikeCredential(credential))
+    ) {
+      return `${schemePrefix}${REDACTED_VALUE}${rest.slice(credential.length)}`;
+    }
+  }
+
+  // No scheme: the first token is the credential itself (`X-API-Key: k1`).
+  let token = HEADER_TOKEN_PATTERN.exec(value)?.[0];
+  if (token && token !== REDACTED_VALUE && looksLikeCredential(token)) {
+    return `${REDACTED_VALUE}${value.slice(token.length)}`;
+  }
+  return value;
+};
+
+// Generic `'key': 'value'` scan (Python reprs, single-quoted logs); the key is filtered
+// via isSecretKeyName at replace time.
+let GENERIC_SINGLE_QUOTED_KEY_VALUE_PATTERN =
+  /'([^'\\]*(?:\\.[^'\\]*)*)'(\s*:\s*)'([^'\\]*(?:\\.[^'\\]*)*)'/g;
+
+// Unquoted `key: value` in prose and JS-style object dumps: `password: Hunter2`,
+// `Invalid token: ya29...`, `{ access_token: 'abc' }`. The key is the word right before
+// the colon; the value is one token, optionally quoted.
+let PROSE_KEY_VALUE_PATTERN =
+  /(?<![A-Za-z0-9_\-.])([A-Za-z][A-Za-z0-9_\-.]*)([ \t]*:[ \t]*)(["'`]?)([^\s"'`,;&)\]}]+)/g;
+
+// Words that describe a credential's state rather than being one (`token: expired`).
+let PROSE_STATE_WORD_PATTERN =
+  /^(?:required|missing|invalid|expired|revoked|empty|blank|null|undefined|none|not|is|was|has|must|should|cannot|incorrect|wrong|malformed|provided|present|absent|unknown|denied|rejected|unauthorized|forbidden|true|false|too|the|a|an)$/i;
+
+// Lowercase snake_case words are error codes (`token: invalid_grant`), not credentials.
+let PROSE_ERROR_CODE_PATTERN = /^[a-z]+(?:_[a-z]+)+$/;
+
+let redactProseKeyValue = (
+  match: string,
+  key: string,
+  separator: string,
+  quote: string,
+  value: string
+) => {
+  if (AUTHORIZATION_HEADER_NAME_PATTERN.test(key) || COOKIE_HEADER_NAME_PATTERN.test(key)) {
+    return match;
+  }
+  if (value.startsWith('[') || value.startsWith(AUTH_CONFIG_SECRET_PLACEHOLDER_PREFIX)) {
+    return match;
+  }
+  if (!isSecretFieldName(key)) return match;
+
+  // Sentence punctuation after the value (`token: expired.`) is not part of it.
+  let credential = value.replace(/[.!?:]+$/, '');
+  if (!credential || PROSE_ERROR_CODE_PATTERN.test(credential)) return match;
+
+  // A single-word key (`token`, `password`) needs a credential-shaped value; a compound
+  // key (`access_token`, `sessionToken`) is specific enough that any non-state word is
+  // treated as its value.
+  let compoundKey = splitKeyParts(key).length > 1;
+  if (
+    looksLikeCredential(credential) ||
+    (compoundKey && !PROSE_STATE_WORD_PATTERN.test(credential))
+  ) {
+    return `${key}${separator}${quote}${REDACTED_VALUE}${value.slice(credential.length)}`;
+  }
+  return match;
+};
+
+// Narrower than sanitizeFreeText for human-readable error text: redacts known secret
+// formats, scheme credentials, credential header values, and secret-named
+// `key=value` / `key: value` / `"key": "value"` / `'key': 'value'` pairs, but never a
+// bare `code=` value or a prose word that merely follows "token"/"basic".
+export let sanitizeSecretValuesInText = (text: string) => {
+  if (!text) return text;
+
+  let result = text.replace(
+    PROSE_SAFE_AUTH_SCHEME_PATTERN,
+    (match, scheme: string, space: string, value: string) =>
+      looksLikeCredential(value) ? `${scheme}${space}${REDACTED_VALUE}` : match
+  );
+
+  result = result.replace(
+    CREDENTIAL_HEADER_VALUE_PATTERN,
+    (
+      _match,
+      name: string,
+      separator: string,
+      quote: string | undefined,
+      quotedValue: string | undefined,
+      plainValue: string | undefined
+    ) =>
+      `${name}${separator}${quote ?? ''}${redactCredentialHeaderValue(
+        name,
+        quote ? (quotedValue ?? '') : (plainValue ?? '')
+      )}`
+  );
+
+  result = redactKnownSecretValues(result);
+
+  result = result.replace(
+    GENERIC_KEY_VALUE_PATTERN,
+    (match, key: string, equals: string, value: string, offset: number, whole: string) => {
+      if (!isSecretKeyName(key)) return match;
+      // `Authorization=Basic [redacted]` was already handled by the scheme patterns.
+      let rest = whole.slice(offset + match.length);
+      if (AUTH_SCHEME_WORD_PATTERN.test(value) && /^\s+\[redacted\]/.test(rest)) return match;
+      return `${key}${equals}${REDACTED_VALUE}`;
+    }
+  );
+
+  result = result.replace(PROSE_KEY_VALUE_PATTERN, redactProseKeyValue);
+
+  result = result.replace(
+    GENERIC_SINGLE_QUOTED_KEY_VALUE_PATTERN,
+    (match, key: string, colon: string, _value: string) =>
+      isSecretKeyName(key) ? `'${key}'${colon}'${REDACTED_VALUE}'` : match
+  );
+
+  return result.replace(
+    GENERIC_JSON_KEY_VALUE_PATTERN,
+    (match, key: string, colon: string, _value: string) =>
+      isSecretKeyName(key) ? `"${key}"${colon}"${REDACTED_VALUE}"` : match
+  );
+};
+
 let sanitizeScalar = (value: string, redactor?: AuthConfigSecretRedactor) =>
   truncateText(sanitizeFreeText(value, redactor));
 
@@ -549,6 +844,13 @@ let decodeRedactedMarker = (value: string) =>
     ? value
     : value.split(REDACTED_ENCODED).join(REDACTED_VALUE);
 
+// A query/fragment value under a non-secret name: a literal secret-named auth-config
+// value or a known credential format (`?q=sk_live_...`) is still replaced.
+let redactQueryValue = (rawValue: string, redactor?: AuthConfigSecretRedactor) =>
+  redactKnownSecretValues(
+    redactor ? redactor.redact(rawValue, isAuthConfigSecretValue) : rawValue
+  );
+
 let redactHashFragment = (hash: string, redactor?: AuthConfigSecretRedactor) => {
   if (!hash?.includes('=')) return hash;
   let withoutHash = hash.startsWith('#') ? hash.slice(1) : hash;
@@ -556,8 +858,8 @@ let redactHashFragment = (hash: string, redactor?: AuthConfigSecretRedactor) =>
     /(?<![A-Za-z0-9])([A-Za-z0-9][A-Za-z0-9_\-.]*)=([^&]*)/g,
     (match, key: string, rawValue: string) => {
       if (isUrlFormSecretKeyName(key)) return `${key}=${REDACTED_VALUE}`;
-      let literalRedacted = redactor ? redactor.redact(rawValue) : rawValue;
-      return literalRedacted !== rawValue ? `${key}=${literalRedacted}` : match;
+      let redactedValue = redactQueryValue(rawValue, redactor);
+      return redactedValue !== rawValue ? `${key}=${redactedValue}` : match;
     }
   );
   return redacted ? `#${redacted}` : '';
@@ -565,9 +867,16 @@ let redactHashFragment = (hash: string, redactor?: AuthConfigSecretRedactor) =>
 
 // Redacts secret-keyed auth values embedded in URL paths (e.g. Telegram's `/bot<token>/...`).
 let isEmbeddedPathSecret = (secret: string, path: string) =>
-  secret.length >= 8 && isSecretKeyName(path.split('.').pop() ?? '');
+  secret.length >= 8 && isAuthConfigSecretValue(secret, path);
+
+// Replaces secret-named auth-config values in free text: whole-value matches, plus
+// values of 8+ chars embedded in longer text such as URL paths or error messages.
+export let redactAuthConfigSecretsInText = (
+  text: string,
+  redactor: AuthConfigSecretRedactor
+): string => redactor.redactEmbedded(text, isEmbeddedPathSecret, isAuthConfigSecretValue);
 
-let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
+export let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
   if (!value) return value;
 
   try {
@@ -578,7 +887,7 @@ let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
       url.password = '';
     }
 
-    if (redactor) url.pathname = redactor.redactEmbedded(url.pathname, isEmbeddedPathSecret);
+    if (redactor) url.pathname = redactAuthConfigSecretsInText(url.pathname, redactor);
 
     for (let key of Array.from(url.searchParams.keys())) {
       if (isUrlFormSecretKeyName(key)) {
@@ -586,21 +895,24 @@ let sanitizeUrl = (value: string, redactor?: AuthConfigSecretRedactor) => {
         continue;
       }
 
-      // Not a secret-looking key -- still catch a literal auth-config secret value.
+      // Not a secret-looking key -- still catch a literal auth-config secret value or a
+      // known credential format.
       let rawValue = url.searchParams.get(key) ?? '';
-      let literalRedacted = redactor ? redactor.redact(rawValue) : rawValue;
-      if (literalRedacted !== rawValue) url.searchParams.set(key, literalRedacted);
+      let redactedValue = redactQueryValue(rawValue, redactor);
+      if (redactedValue !== rawValue) url.searchParams.set(key, redactedValue);
     }
 
     url.hash = redactHashFragment(url.hash, redactor);
 
     return decodeRedactedMarker(url.toString());
   } catch {
-    let text = redactor ? redactor.redactEmbedded(value, isEmbeddedPathSecret) : value;
+    let text = redactor ? redactAuthConfigSecretsInText(value, redactor) : value;
     return text.replace(
       /([?&]([^=&#]+)=)([^&#]+)/g,
       (_match, prefix: string, key: string, rawValue: string) =>
-        isUrlFormSecretKeyName(key) ? `${prefix}${REDACTED_VALUE}` : `${prefix}${rawValue}`
+        isUrlFormSecretKeyName(key)
+          ? `${prefix}${REDACTED_VALUE}`
+          : `${prefix}${redactKnownSecretValues(rawValue)}`
     );
   }
 };
@@ -802,6 +1114,8 @@ export let __traceInternals = {
   sanitizeHeaders,
   isSafeHeaderName,
   isSecretKeyName,
+  isSecretFieldName,
+  isAuthConfigSecretValue,
   isUrlFormSecretKeyName,
   redactStructuredValue,
   SECRET_KEY_PATTERN,

package/src/error/api.test.ts

@@ -1,8 +1,30 @@
 import { ServiceError } from '@lowerdeck/error';
+import { AxiosError, AxiosHeaders } from 'axios';
 import { describe, expect, it } from 'vitest';
-import { buildApiServiceError, collectApiErrorDetails, createApiServiceError } from './api';
+import {
+  buildApiServiceError,
+  collectApiErrorDetails,
+  createApiServiceError,
+  decodeApiErrorBody,
+  getApiErrorResponseWithBody,
+  looksLikeHtmlErrorBody,
+  pushBoundedApiErrorDetail,
+  readApiErrorText,
+  truncateApiErrorMessage
+} from './api';
 import { SlateError } from './base';
 
+let axiosFailure = (status: number, data: unknown) => {
+  let config = { url: '/widgets', method: 'get', headers: new AxiosHeaders() };
+  return new AxiosError('Request failed', 'ERR_BAD_REQUEST', config, undefined, {
+    status,
+    statusText: 'Error',
+    data,
+    headers: {},
+    config
+  });
+};
+
 describe('API service error helpers', () => {
   it('collects unique nested API error details', () => {
     let details: string[] = [];
@@ -111,4 +133,104 @@ describe('API service error helpers', () => {
       })
     ).toBe(existing);
   });
+
+  it('recovers the upstream body from SlateError baggage', () => {
+    let parent = SlateError.fromAxios(
+      axiosFailure(422, { errors: [{ message: 'Name is required' }] })
+    );
+
+    expect(parent.name).toBe('SlateError');
+    expect((parent as any).response).toBeUndefined();
+    expect(getApiErrorResponseWithBody(parent)).toEqual({
+      status: 422,
+      data: { errors: [{ message: 'Name is required' }] }
+    });
+
+    let error = buildApiServiceError(parent, {
+      providerLabel: 'Example',
+      reason: 'example_api_error',
+      extractResponse: (input, helpers) => helpers.getResponseWithBody(input)
+    });
+
+    expect(error.data.upstreamStatus).toBe(422);
+    expect(error.data.message).toBe('Example API request failed: HTTP 422: Name is required');
+  });
+
+  it('prefers an existing response body and ignores non-SlateErrors without one', () => {
+    let response = { status: 400, data: { message: 'Direct' } };
+
+    expect(getApiErrorResponseWithBody({ response })).toEqual({
+      status: 400,
+      statusText: undefined,
+      data: { message: 'Direct' }
+    });
+    expect(
+      getApiErrorResponseWithBody({ name: 'Error', data: { baggage: { response: 'x' } } })
+    ).toBeUndefined();
+  });
+
+  it('detects HTML error pages without dropping plain text that starts with <', () => {
+    expect(looksLikeHtmlErrorBody('<!DOCTYPE html><html><body>Bad</body></html>')).toBe(true);
+    expect(looksLikeHtmlErrorBody('  <html lang="en">')).toBe(true);
+    expect(looksLikeHtmlErrorBody('<h1>502 Bad Gateway</h1>')).toBe(true);
+    expect(looksLikeHtmlErrorBody('Error page: <body>oops</body>')).toBe(true);
+    expect(looksLikeHtmlErrorBody('<id> is required')).toBe(false);
+    expect(looksLikeHtmlErrorBody('<body> is required')).toBe(false);
+    expect(looksLikeHtmlErrorBody('Invalid <body> parameter')).toBe(false);
+    expect(looksLikeHtmlErrorBody('<title> is required')).toBe(false);
+    expect(looksLikeHtmlErrorBody('<p> must be a string')).toBe(false);
+    expect(looksLikeHtmlErrorBody('<= 100 items allowed')).toBe(false);
+    expect(looksLikeHtmlErrorBody('Field must be a number')).toBe(false);
+  });
+
+  it('reads displayable error text and keeps detail lists bounded and unique', () => {
+    expect(readApiErrorText('  Bad input ')).toBe('Bad input');
+    expect(readApiErrorText(42)).toBe('42');
+    expect(readApiErrorText(42, { includeNumbers: false })).toBeUndefined();
+    expect(readApiErrorText('[truncated]')).toBeUndefined();
+    expect(readApiErrorText(' [redacted] ')).toBeUndefined();
+    expect(readApiErrorText('[unserializable]')).toBeUndefined();
+    expect(readApiErrorText('Token [redacted] is invalid')).toBe(
+      'Token [redacted] is invalid'
+    );
+    expect(readApiErrorText('<html></html>')).toBeUndefined();
+    expect(readApiErrorText({ message: 'x' })).toBeUndefined();
+
+    let details: string[] = [];
+    for (let value of ['a', 'a', '', '[truncated]', 'b', 'c', 'd', 'e', 'f']) {
+      pushBoundedApiErrorDetail(details, value);
+    }
+    expect(details).toEqual(['a', 'b', 'c', 'd', 'e']);
+
+    let fieldDetails: string[] = [];
+    pushBoundedApiErrorDetail(fieldDetails, 'is required', { field: 'name' });
+    pushBoundedApiErrorDetail(fieldDetails, 'is required', { field: 'name' });
+    pushBoundedApiErrorDetail(fieldDetails, 'second', { maxDetails: 1 });
+    expect(fieldDetails).toEqual(['name: is required']);
+  });
+
+  it('truncates long error messages', () => {
+    expect(truncateApiErrorMessage('abc', 5)).toBe('abc');
+    expect(truncateApiErrorMessage('abcdef', 3)).toBe('abc...');
+    expect(truncateApiErrorMessage('x'.repeat(1_001))).toBe(`${'x'.repeat(1_000)}...`);
+  });
+
+  it('decodes text and binary error bodies', () => {
+    let json = '{"error":{"message":"Not found"}}';
+    let bytes = new TextEncoder().encode(json);
+
+    expect(decodeApiErrorBody(json)).toEqual({ error: { message: 'Not found' } });
+    expect(decodeApiErrorBody(bytes.buffer)).toEqual({ error: { message: 'Not found' } });
+    expect(decodeApiErrorBody(bytes)).toEqual({ error: { message: 'Not found' } });
+    expect(decodeApiErrorBody(Buffer.from(` ${json} `))).toEqual({
+      error: { message: 'Not found' }
+    });
+    expect(decodeApiErrorBody('  plain text  ')).toBe('plain text');
+    expect(decodeApiErrorBody('{not json')).toBe('{not json');
+    expect(decodeApiErrorBody(new TextEncoder().encode('abcdef'), { maxBytes: 3 })).toBe(
+      'abc'
+    );
+    expect(decodeApiErrorBody({ already: 'parsed' })).toEqual({ already: 'parsed' });
+    expect(decodeApiErrorBody(undefined)).toBeUndefined();
+  });
 });