@lowdefy/errors 7.0.0 → 7.2.0

package/dist/ServiceError.js

@@ -12,7 +12,10 @@
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-*/ /**
+*/ import findInErrorChain from './findInErrorChain.js';
+import hasTimeoutInChain from './hasTimeoutInChain.js';
+import isTimeoutError from './isTimeoutError.js';
+/**
  * Network error codes that indicate service issues (not config problems).
  */ const SERVICE_ERROR_CODES = new Set([
     'ECONNREFUSED',
@@ -37,11 +40,22 @@ function readHttpStatus(error) {
     const numericCode = Number.isInteger(error.code) && error.code >= 100 && error.code < 600 ? error.code : undefined;
     return error.statusCode ?? error.status ?? error.response?.status ?? error.$metadata?.httpStatusCode ?? numericCode;
 }
-// The first HTTP status down a retrying client's lastError and the cause chain.
-function findHttpStatus(error, seen = new Set()) {
-    if (!error || typeof error !== 'object' || seen.has(error)) return undefined;
-    seen.add(error);
-    return readHttpStatus(error) ?? findHttpStatus(error.lastError, seen) ?? findHttpStatus(error.cause, seen);
+// What failed, read once from the error and its chain. A call that ran out of time got no
+// answer, so any status attached above the cancellation is one a client made up, not a
+// server response: the AI gateway client reports 500 for an AbortSignal.timeout, and 408
+// for an undici timeout. A real 5xx or 429 wrapped around a timeout looks the same, so the
+// timeout wins.
+function classifyFailure(error) {
+    if (hasTimeoutInChain(error)) {
+        return {
+            timedOut: true,
+            statusCode: undefined
+        };
+    }
+    return {
+        timedOut: false,
+        statusCode: findInErrorChain(error, readHttpStatus)
+    };
 }
 // 5xx is a failing service; 429 is a service throttling its callers. Both pass with
 // time, and neither is fixed by changing config.
@@ -87,6 +101,10 @@ function readRetryAfterHeader(headers) {
    */ static isServiceError(error, seen = new Set()) {
         if (!error || seen.has(error)) return false;
         seen.add(error);
+        // A connection that has already classified its error as the service refusing the request
+        // (a duplicate key, an invalid query) says so. The message checks below would otherwise
+        // match words in a collection name or in the document values a driver message quotes.
+        if (error.isServiceError === false) return false;
         // A client that retried and gave up (the AI SDK's RetryError) carries the
         // failure it retried on; its own message and fields hold no status.
         if (error.lastError) {
@@ -97,8 +115,8 @@ function readRetryAfterHeader(headers) {
             return true;
         }
         // A call cancelled because it ran out of time (AbortSignal.timeout, the AI SDK's
-        // timeout option, the server's request timeout).
-        if (error.name === 'TimeoutError') {
+        // timeout option, the server's request timeout, undici's timeouts).
+        if (isTimeoutError(error)) {
             return true;
         }
         // AWS SDK v3 marks throttling exceptions as retryable throttling; some services
@@ -121,10 +139,12 @@ function readRetryAfterHeader(headers) {
     /**
    * Enhances an error message with more helpful context.
    * @param {Error} error - The original error
+   * @param {Object} [failure] - Whether the call timed out and the status it failed with,
+   *   when the caller already worked them out
    * @returns {string} Enhanced error message
-   */ static enhanceMessage(error) {
+   */ static enhanceMessage(error, failure = classifyFailure(error)) {
         const code = error.code;
-        const statusCode = findHttpStatus(error);
+        const { timedOut, statusCode } = failure;
         if (code === 'ECONNREFUSED') {
             return `Connection refused. The service may be down or the address may be incorrect. ${error.message ?? ''}`;
         }
@@ -137,6 +157,9 @@ function readRetryAfterHeader(headers) {
         if (code === 'ECONNRESET') {
             return `Connection reset by the server. ${error.message ?? ''}`;
         }
+        if (timedOut) {
+            return `Request timed out. The service may be slow, or the timeout too short. ${error.message ?? ''}`;
+        }
         if (statusCode === 429) {
             const retryAfter = ServiceError.readRetryAfter(error);
             const retry = retryAfter ? ` Retry after ${retryAfter}.` : '';
@@ -151,16 +174,10 @@ function readRetryAfterHeader(headers) {
    * Reads the Retry-After header a throttling service sent, from the error, the
    * failure a retrying client gave up on, or its cause chain.
    * @param {Error} error - The error to read
-   * @param {Set} [seen] - Errors already read, so a cyclic cause chain ends
    * @returns {string|null} The header value (seconds or an HTTP date), or null
-   */ static readRetryAfter(error, seen = new Set()) {
-        if (!error || typeof error !== 'object' || seen.has(error)) return null;
-        seen.add(error);
-        const retryAfter = readRetryAfterHeader(error.responseHeaders) ?? readRetryAfterHeader(error.response?.headers) ?? readRetryAfterHeader(error.headers) ?? readRetryAfterHeader(error.$response?.headers);
-        if (retryAfter !== undefined && retryAfter !== null) {
-            return String(retryAfter);
-        }
-        return ServiceError.readRetryAfter(error.lastError, seen) ?? ServiceError.readRetryAfter(error.cause, seen);
+   */ static readRetryAfter(error) {
+        const retryAfter = findInErrorChain(error, (node)=>readRetryAfterHeader(node.responseHeaders) ?? readRetryAfterHeader(node.response?.headers) ?? readRetryAfterHeader(node.headers) ?? readRetryAfterHeader(node.$response?.headers) ?? undefined);
+        return retryAfter === undefined ? null : String(retryAfter);
     }
     /**
    * Creates a ServiceError instance with formatted message.
@@ -178,9 +195,13 @@ function readRetryAfterHeader(headers) {
    */ constructor(message, { cause, service, code, statusCode, configKey, hint, retryAfter } = {}){
         // Extract info from wrapped error if provided
         const errorCode = code ?? cause?.code;
-        const errorStatusCode = statusCode ?? findHttpStatus(cause);
+        // A status passed in is the caller saying a service answered with it.
+        const failure = statusCode === undefined || statusCode === null ? classifyFailure(cause) : {
+            timedOut: false,
+            statusCode
+        };
         // Use provided message, or enhance wrapped error's message
-        const baseMessage = message ?? (cause ? ServiceError.enhanceMessage(cause) : 'Service error');
+        const baseMessage = message ?? (cause ? ServiceError.enhanceMessage(cause, failure) : 'Service error');
         // Message without prefix - logger uses error.name for display
         // Include service in message if provided
         const formattedMessage = service ? `${service}: ${baseMessage}` : baseMessage;
@@ -193,7 +214,7 @@ function readRetryAfterHeader(headers) {
         this.service = service;
         this.code = errorCode;
         this.hint = hint ?? cause?.hint ?? null;
-        this.statusCode = errorStatusCode;
+        this.statusCode = failure.statusCode;
         this.retryAfter = retryAfter ?? ServiceError.readRetryAfter(cause);
         // Extract from the wrapped error like PluginError does, so a ServiceError
         // wrapped around an error that already resolved its config location keeps it.

package/dist/errorSummaryForLog.js

@@ -0,0 +1,68 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import hasTimeoutInChain from './hasTimeoutInChain.js';
+import readErrorCodes from './readErrorCodes.js';
+// What a log may say about an error. Chat text and other inputs can hold personal information,
+// and logs have their own retention and access, so a log carries no prompt, request property,
+// tool input or document. An error carries them where a plain `{ err }` log would write them: a
+// driver's error embeds the document it rejected, an AI SDK TypeValidationError's or
+// JSONParseError's message embeds the value it rejected (the whole conversation, a tool's
+// input), InvalidToolInputError, ToolCallRepairError and RetryError repeat their cause's
+// message, and every stack opens with its message. So an AI SDK error is summarised by name
+// and code alone, except APICallError, whose message is the provider's reply; any other error
+// keeps its name, code, status code and message, cut to 500 characters, and none of its other
+// fields. Causes are followed the same way, three deep.
+const MESSAGE_LIMIT = 500;
+const CAUSE_DEPTH = 3;
+// AISDKError.isInstance reads this marker; the error classes themselves are not imported so
+// any copy of the AI SDK in the app is recognised.
+const aiSdkErrorMarker = Symbol.for('vercel.ai.error');
+function isAiSdkError(error) {
+    return error[aiSdkErrorMarker] === true;
+}
+// An error from another realm, such as a DOMException in a VM context, fails instanceof Error.
+function isError(value) {
+    if (value instanceof Error) return true;
+    return typeof value === 'object' && value !== null && typeof value.stack === 'string' && typeof value.message === 'string';
+}
+function truncate(text) {
+    if (text.length <= MESSAGE_LIMIT) return text;
+    return `${text.slice(0, MESSAGE_LIMIT - 1)}…`;
+}
+function errorSummaryForLog(error, depth = 0) {
+    if (!isError(error)) {
+        return {
+            name: typeof error
+        };
+    }
+    const summary = {
+        name: error.name
+    };
+    if (!isAiSdkError(error) || error.name === 'AI_APICallError') {
+        summary.message = truncate(String(error.message));
+    }
+    const { code, statusCode } = readErrorCodes(error);
+    if (code !== undefined) summary.code = code;
+    // A status above a call that ran out of time is one the client made up, not a server
+    // response (see ServiceError), so neither the log nor the client is told it.
+    if (statusCode !== undefined && !hasTimeoutInChain(error)) summary.statusCode = statusCode;
+    // A RetryError holds the attempt that failed last as lastError rather than as its cause.
+    const cause = error.lastError ?? error.cause;
+    if (cause !== undefined && depth < CAUSE_DEPTH) {
+        summary.cause = errorSummaryForLog(cause, depth + 1);
+    }
+    return summary;
+}
+export default errorSummaryForLog;

package/dist/findInErrorChain.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // The first value `read` gives for an error, the failure a retrying client gave up on
+// (lastError), or the cause chain, in that order. Stops on a cycle.
+function findInErrorChain(error, read, seen = new Set()) {
+    if (!error || typeof error !== 'object' || seen.has(error)) return undefined;
+    seen.add(error);
+    return read(error) ?? findInErrorChain(error.lastError, read, seen) ?? findInErrorChain(error.cause, read, seen);
+}
+export default findInErrorChain;

package/dist/hasTimeoutInChain.js

@@ -0,0 +1,22 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import findInErrorChain from './findInErrorChain.js';
+import isTimeoutError from './isTimeoutError.js';
+// Whether the error, or anything down its lastError and cause chain, is a call cancelled
+// because it ran out of time.
+function hasTimeoutInChain(error) {
+    return findInErrorChain(error, (node)=>isTimeoutError(node) ? true : undefined) === true;
+}
+export default hasTimeoutInChain;

package/dist/index.js

@@ -73,7 +73,9 @@
  *   shouldSuppressBuildCheck   - Check ~ignoreBuildChecks in parent chain
  *
  * Error Field Utilities:
+ *   errorSummaryForLog        - {name, message, code, statusCode, cause} an error may log
  *   expectedErrorNames        - Set of error class names that are expected outcomes, not faults
+ *   isExpectedError           - The one test for an expected outcome versus a fault
  *   readErrorCodes            - {code, statusCode} from one error node's own fields
  *   lowdefyErrorNames         - Set of Lowdefy error class names
  *   lowdefyErrorTypes         - Lowdefy error class by name, for reviving and reshaping errors
@@ -84,8 +86,10 @@ import BlockError from './BlockError.js';
 import BuildError from './BuildError.js';
 import ConfigError from './ConfigError.js';
 import ConfigWarning from './ConfigWarning.js';
+import errorSummaryForLog from './errorSummaryForLog.js';
 import errorToDisplayString from './errorToDisplayString.js';
 import expectedErrorNames from './expectedErrorNames.js';
+import isExpectedError from './isExpectedError.js';
 import LowdefyInternalError from './LowdefyInternalError.js';
 import lowdefyErrorNames from './lowdefyErrorNames.js';
 import lowdefyErrorTypes from './lowdefyErrorTypes.js';
@@ -101,4 +105,4 @@ import shouldSuppressBuildCheck, { PLUGIN_CHECKS_SLUG, PLUGIN_SCHEMA_SLUG, VALID
 import TenantIntegrityError from './TenantIntegrityError.js';
 import TwoFactorEnrolmentRequiredError from './TwoFactorEnrolmentRequiredError.js';
 import UserError from './UserError.js';
-export { ActionError, AuthenticationError, AuthorizationError, BlockError, BuildError, ConfigError, ConfigWarning, errorToDisplayString, expectedErrorNames, LowdefyInternalError, lowdefyErrorNames, lowdefyErrorTypes, OperatorError, PluginError, PLUGIN_CHECKS_SLUG, PLUGIN_SCHEMA_SLUG, readErrorCodes, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, TenantIntegrityError, TwoFactorEnrolmentRequiredError, UserError, VALID_CHECK_SLUGS };
+export { ActionError, AuthenticationError, AuthorizationError, BlockError, BuildError, ConfigError, ConfigWarning, errorSummaryForLog, errorToDisplayString, expectedErrorNames, isExpectedError, LowdefyInternalError, lowdefyErrorNames, lowdefyErrorTypes, OperatorError, PluginError, PLUGIN_CHECKS_SLUG, PLUGIN_SCHEMA_SLUG, readErrorCodes, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, TenantIntegrityError, TwoFactorEnrolmentRequiredError, UserError, VALID_CHECK_SLUGS };

package/dist/isExpectedError.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import expectedErrorNames from './expectedErrorNames.js';
+// The one test for "the system worked and said no" (an expected outcome) versus a
+// fault. Every site that picks a log level, decides on Sentry or feeds the dev
+// agent feed asks this, so a refusal is classified the same way on every route
+// and transport. Keyed on the name: a serializer round trip or another package's
+// copy of a class keeps the name but not the class identity.
+function isExpectedError(error) {
+    return expectedErrorNames.has(error?.name);
+}
+export default isExpectedError;

package/dist/isTimeoutError.js

@@ -0,0 +1,37 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // Codes a client sets when it gave up waiting: Node sockets, request, and undici's
+// connect, headers and body timeouts.
+const TIMEOUT_CODES = new Set([
+    'ETIMEDOUT',
+    'ESOCKETTIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_HEADERS_TIMEOUT',
+    'UND_ERR_BODY_TIMEOUT'
+]);
+// Names of the errors undici and AbortSignal.timeout throw when a call runs out of time.
+const TIMEOUT_NAMES = new Set([
+    'TimeoutError',
+    'ConnectTimeoutError',
+    'HeadersTimeoutError',
+    'BodyTimeoutError'
+]);
+// Whether this one error is a call cancelled because it ran out of time. Read from the
+// error's own name and code only; a message that mentions a timeout is not enough.
+function isTimeoutError(error) {
+    if (!error || typeof error !== 'object') return false;
+    return TIMEOUT_NAMES.has(error.name) || TIMEOUT_CODES.has(error.code);
+}
+export default isTimeoutError;

package/dist/shouldSuppressBuildCheck.js

@@ -29,6 +29,7 @@
     'websocket-refs': 'Invalid websocket action reference warnings',
     'callmethod-refs': 'CallMethod actions targeting blocks not defined on the page',
     icons: 'Unresolvable icon name warnings',
+    'native-ignored': 'Properties set on a mobile page that the native block ignores',
     types: 'All type validation (blocks, operators, actions, requests, connections)',
     schema: 'JSON schema validation errors',
     secrets: 'Environment variable names that are not set in the build environment',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/errors",
-  "version": "7.0.0",
+  "version": "7.2.0",
   "license": "Apache-2.0",
   "description": "Lowdefy error classes for consistent error handling across build, server, and client",
   "homepage": "https://lowdefy.com",
@@ -34,11 +34,9 @@
     "dist/*"
   ],
   "devDependencies": {
-    "@jest/globals": "28.1.3",
     "@swc/cli": "0.8.1",
     "@swc/core": "1.15.32",
-    "@swc/jest": "0.2.39",
-    "jest": "28.1.3"
+    "vitest": "4.1.12"
   },
   "publishConfig": {
     "access": "public"
@@ -46,6 +44,6 @@
   "scripts": {
     "build": "swc src --out-dir dist --config-file ../../../.swcrc --cli-config-file ../../../.swc-cli.json",
     "clean": "rm -rf dist",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --passWithNoTests"
+    "test": "vitest run --passWithNoTests"
   }
 }