@lowdefy/errors 0.0.0-experimental-20260928105334 → 0.0.0-experimental-20260928120643

package/dist/AuthorizationError.js

@@ -0,0 +1,31 @@
+/*
+  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.
+*/ // Thrown when an authenticated caller is refused by an authorization gate - the
+// caller holds a session or a strategy credential but not the roles the
+// request, endpoint, agent, websocket or auth step requires. Maps to 403. The
+// message is written by the gate and may stay deliberately generic so it does
+// not reveal what exists. The server error handlers branch on the name before
+// the structured-log and Sentry pipeline: a caller with the wrong roles is
+// expected traffic and produces one warning line, not an error log.
+let AuthorizationError = class AuthorizationError extends Error {
+    constructor(message = 'Forbidden.', { cause } = {}){
+        super(message, {
+            cause
+        });
+        this.name = 'AuthorizationError';
+        this.isLowdefyError = true;
+    }
+};
+export default AuthorizationError;

package/dist/ServiceError.js

@@ -28,8 +28,38 @@
     'UNABLE_TO_VERIFY_LEAF_SIGNATURE',
     'DEPTH_ZERO_SELF_SIGNED_CERT'
 ]);
+// The HTTP status an error carries, in the places client libraries put it: most HTTP
+// clients use `statusCode`, `status` or `response.status`, AWS SDK v3 uses
+// `$metadata.httpStatusCode`, and @google-cloud and SendGrid use a numeric `code`. A
+// numeric `code` outside the HTTP range is a driver's own code (MongoDB), not a status.
+function readHttpStatus(error) {
+    if (!error || typeof error !== 'object') return undefined;
+    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);
+}
+// 5xx is a failing service; 429 is a service throttling its callers. Both pass with
+// time, and neither is fixed by changing config.
+function isServiceStatus(statusCode) {
+    return statusCode === 429 || statusCode >= 500 && statusCode < 600;
+}
+// Retry-After from response headers, which clients expose as a plain object (the AI
+// SDK's responseHeaders, axios and SendGrid response.headers, Stripe headers) or as a
+// fetch Headers instance.
+function readRetryAfterHeader(headers) {
+    if (!headers || typeof headers !== 'object') return undefined;
+    if (typeof headers.get === 'function') {
+        return headers.get('retry-after') ?? undefined;
+    }
+    return headers['retry-after'] ?? headers['Retry-After'];
+}
 /**
- * Error class for external service failures (network, timeout, database, 5xx).
+ * Error class for external service failures (network, timeout, database, 5xx, 429).
  *
  * ServiceError represents infrastructure/service issues that are NOT caused by
  * invalid configuration. The config location is still resolved to help developers
@@ -50,26 +80,43 @@
  * // error.message = "MongoDB: Connection refused. The service may be down..."
  */ let ServiceError = class ServiceError extends Error {
     /**
-   * Checks if an error is a service error (network issues, timeouts, 5xx).
+   * Checks if an error is a service error (network issues, timeouts, 5xx, rate limits).
    * @param {Error} error - The error to check
+   * @param {Set} [seen] - Errors already checked, so a cyclic cause chain ends
    * @returns {boolean} True if this is a service error
-   */ static isServiceError(error) {
-        if (!error) return false;
+   */ static isServiceError(error, seen = new Set()) {
+        if (!error || seen.has(error)) return false;
+        seen.add(error);
+        // 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) {
+            return ServiceError.isServiceError(error.lastError, seen);
+        }
         // Check error code
         if (error.code && SERVICE_ERROR_CODES.has(error.code)) {
             return true;
         }
-        // Check HTTP status codes (5xx = server error)
-        const statusCode = error.statusCode ?? error.status ?? error.response?.status;
-        if (statusCode && statusCode >= 500 && statusCode < 600) {
+        // 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') {
+            return true;
+        }
+        // AWS SDK v3 marks throttling exceptions as retryable throttling; some services
+        // answer them with 400 rather than 429.
+        if (error.$retryable?.throttling === true) {
+            return true;
+        }
+        if (isServiceStatus(readHttpStatus(error))) {
             return true;
         }
         // Check for common service error messages
         const message = error.message?.toLowerCase() ?? '';
-        if (message.includes('network') || message.includes('timeout') || message.includes('connection refused') || message.includes('dns lookup failed') || message.includes('socket hang up') || message.includes('certificate') || message.includes('unavailable')) {
+        if (message.includes('network') || message.includes('timeout') || message.includes('too many requests') || message.includes('connection refused') || message.includes('dns lookup failed') || message.includes('socket hang up') || message.includes('certificate') || message.includes('unavailable')) {
             return true;
         }
-        return false;
+        // A client error that wraps the network failure underneath it (the AI
+        // SDK's "Cannot connect to API" around a refused or timed-out fetch).
+        return ServiceError.isServiceError(error.cause, seen);
     }
     /**
    * Enhances an error message with more helpful context.
@@ -77,7 +124,7 @@
    * @returns {string} Enhanced error message
    */ static enhanceMessage(error) {
         const code = error.code;
-        const statusCode = error.statusCode ?? error.status ?? error.response?.status;
+        const statusCode = findHttpStatus(error);
         if (code === 'ECONNREFUSED') {
             return `Connection refused. The service may be down or the address may be incorrect. ${error.message ?? ''}`;
         }
@@ -90,12 +137,32 @@
         if (code === 'ECONNRESET') {
             return `Connection reset by the server. ${error.message ?? ''}`;
         }
+        if (statusCode === 429) {
+            const retryAfter = ServiceError.readRetryAfter(error);
+            const retry = retryAfter ? ` Retry after ${retryAfter}.` : '';
+            return `Rate limited by the service (429 Too Many Requests).${retry} ${error.message ?? ''}`;
+        }
         if (statusCode && statusCode >= 500) {
             return `Server returned error ${statusCode}. ${error.message ?? ''}`;
         }
         return error.message;
     }
     /**
+   * 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);
+    }
+    /**
    * Creates a ServiceError instance with formatted message.
    * @param {string} [message] - Error message (falls back to enhanced cause message)
    * @param {Object} [options]
@@ -104,10 +171,14 @@
    * @param {string} [options.code] - Error code (e.g., 'ECONNREFUSED')
    * @param {number} [options.statusCode] - HTTP status code if applicable
    * @param {string} [options.configKey] - Config key for location resolution
-   */ constructor(message, { cause, service, code, statusCode, configKey } = {}){
+   * @param {string} [options.hint] - A sentence telling the developer what to do about the
+   *   failure. Enumerable, so it survives serialization to the client.
+   * @param {string} [options.retryAfter] - The Retry-After a throttling service sent
+   *   (seconds or an HTTP date). Read from the cause when not given.
+   */ constructor(message, { cause, service, code, statusCode, configKey, hint, retryAfter } = {}){
         // Extract info from wrapped error if provided
         const errorCode = code ?? cause?.code;
-        const errorStatusCode = statusCode ?? cause?.statusCode ?? cause?.status ?? cause?.response?.status;
+        const errorStatusCode = statusCode ?? findHttpStatus(cause);
         // Use provided message, or enhance wrapped error's message
         const baseMessage = message ?? (cause ? ServiceError.enhanceMessage(cause) : 'Service error');
         // Message without prefix - logger uses error.name for display
@@ -121,8 +192,12 @@
         this._message = baseMessage;
         this.service = service;
         this.code = errorCode;
+        this.hint = hint ?? cause?.hint ?? null;
         this.statusCode = errorStatusCode;
-        this.configKey = configKey ?? null;
+        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.
+        this.configKey = configKey ?? cause?.configKey ?? null;
     }
 };
 export default ServiceError;

package/dist/TwoFactorEnrolmentRequiredError.js

@@ -0,0 +1,31 @@
+/*
+  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.
+*/ // Thrown when an authorized caller has not enrolled a second factor and the
+// deployment sets auth.twoFactor.required. Distinct from AuthenticationError on
+// purpose: a 401 reads to the client as a dead session and bounces the user to
+// sign-in, which is the redirect loop the enrolment gate exists to avoid, so this
+// maps to 403. The server error handlers branch on the name before the
+// structured-log and Sentry pipeline - under required: true this is expected
+// traffic from every unenrolled caller, not a fault.
+let TwoFactorEnrolmentRequiredError = class TwoFactorEnrolmentRequiredError extends Error {
+    constructor(message = 'Two-factor enrolment required.', { cause } = {}){
+        super(message, {
+            cause
+        });
+        this.name = 'TwoFactorEnrolmentRequiredError';
+        this.isLowdefyError = true;
+    }
+};
+export default TwoFactorEnrolmentRequiredError;

package/dist/errorToDisplayString.js

@@ -16,7 +16,10 @@
     if (typeof error === 'string') return error;
     if (error?.message === undefined) return String(error);
     const name = error.name || 'Error';
-    let msg = `[${name}] ${error.message}`;
+    // Prod-gated build warnings are not fatal in dev but fail `lowdefy build`, so
+    // the name segment says so wherever the error is displayed.
+    const nameSegment = error.prodError === true ? `${name} · fails in prod` : name;
+    let msg = `[${nameSegment}] ${error.message}`;
     if (error.received !== undefined) {
         try {
             msg = `${msg} Received: ${JSON.stringify(error.received)}`;

package/dist/index.js

@@ -42,9 +42,13 @@
  *    - Extends ConfigError with name override
  *    - Format: source:line\n[ConfigWarning] message
  *
- * 6. UserError - User-authored deliberate failure
- *    - Thrown: Client-side Throw action; server-side controlThrow (routine :throw) and controlReject (routine :reject)
- *    - Caught: Caller of the action/resolver; signals "the called routine deliberately failed" as distinct from a system fault
+ * 6. UserError - An expected outcome of user interaction, never a config or system fault
+ *    - Thrown: Client-side Throw and Validate actions; server-side controlThrow (routine :throw)
+ *      and controlReject (routine :reject); client auth methods when the auth server rejects
+ *      the attempt (4xx: wrong password, expired or used link, invalid code, stale OAuth query)
+ *    - Caught: Caller of the action/resolver; the message is shown to the user and catch actions
+ *      run, but it logs to the browser console only - never posted to /api/client-error, never
+ *      logged on the server at error level, never resolved to a config location
  *    - Format: [User Error] message
  *
  * 7. AuthenticationError - Unauthenticated request to a protected endpoint
@@ -52,6 +56,16 @@
  *    - Caught: Server error handlers, before structured logging and Sentry (401)
  *    - Format: [AuthenticationError] message
  *
+ * 8. TwoFactorEnrolmentRequiredError - Authorized caller with no enrolled second factor
+ *    - Thrown: The authorization gate, when auth.twoFactor.required is set and the caller is unenrolled
+ *    - Caught: Server error handlers, before structured logging and Sentry (403)
+ *    - Format: [TwoFactorEnrolmentRequiredError] message
+ *
+ * 9. AuthorizationError - Authenticated caller refused by an authorization gate (wrong roles)
+ *    - Thrown: Request, endpoint, agent, websocket and auth-step authorization gates
+ *    - Caught: Server error handlers, before structured logging and Sentry (403)
+ *    - Format: [AuthorizationError] message
+ *
  * Location Resolution Utilities:
  *   resolveConfigLocation     - Sync: configKey → {source, config} via keyMap/refMap
  *   resolveErrorLocation      - Sync: unified resolver (configKey or filePath/lineNumber)
@@ -64,6 +78,7 @@
  *   lowdefyErrorTypes         - Lowdefy error class by name, for reviving and reshaping errors
  */ import ActionError from './ActionError.js';
 import AuthenticationError from './AuthenticationError.js';
+import AuthorizationError from './AuthorizationError.js';
 import BlockError from './BlockError.js';
 import BuildError from './BuildError.js';
 import ConfigError from './ConfigError.js';
@@ -81,5 +96,6 @@ import loadAndResolveErrorLocation from './loadAndResolveErrorLocation.js';
 import resolveErrorLocation from './resolveErrorLocation.js';
 import ServiceError from './ServiceError.js';
 import shouldSuppressBuildCheck, { VALID_CHECK_SLUGS } from './shouldSuppressBuildCheck.js';
+import TwoFactorEnrolmentRequiredError from './TwoFactorEnrolmentRequiredError.js';
 import UserError from './UserError.js';
-export { ActionError, AuthenticationError, BlockError, BuildError, ConfigError, ConfigWarning, errorToDisplayString, LowdefyInternalError, lowdefyErrorNames, lowdefyErrorTypes, OperatorError, PluginError, readErrorCodes, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, UserError, VALID_CHECK_SLUGS };
+export { ActionError, AuthenticationError, AuthorizationError, BlockError, BuildError, ConfigError, ConfigWarning, errorToDisplayString, LowdefyInternalError, lowdefyErrorNames, lowdefyErrorTypes, OperatorError, PluginError, readErrorCodes, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, TwoFactorEnrolmentRequiredError, UserError, VALID_CHECK_SLUGS };

package/dist/lowdefyErrorTypes.js

@@ -13,6 +13,8 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import ActionError from './ActionError.js';
+import AuthenticationError from './AuthenticationError.js';
+import AuthorizationError from './AuthorizationError.js';
 import BlockError from './BlockError.js';
 import BuildError from './BuildError.js';
 import ConfigError from './ConfigError.js';
@@ -22,11 +24,14 @@ import OperatorError from './OperatorError.js';
 import PluginError from './PluginError.js';
 import RequestError from './RequestError.js';
 import ServiceError from './ServiceError.js';
+import TwoFactorEnrolmentRequiredError from './TwoFactorEnrolmentRequiredError.js';
 import UserError from './UserError.js';
 // Name to class, for rebuilding an error whose class identity is gone but whose
 // name survived - a serializer round trip, or a caught error being reshaped.
 const lowdefyErrorTypes = {
     ActionError,
+    AuthenticationError,
+    AuthorizationError,
     BlockError,
     BuildError,
     ConfigError,
@@ -36,6 +41,7 @@ const lowdefyErrorTypes = {
     PluginError,
     RequestError,
     ServiceError,
+    TwoFactorEnrolmentRequiredError,
     UserError
 };
 export default lowdefyErrorTypes;

package/dist/shouldSuppressBuildCheck.js

@@ -23,8 +23,14 @@
     'link-refs': 'Invalid Link action page reference warnings',
     'request-refs': 'Invalid Request action reference warnings',
     'connection-refs': 'Nonexistent connection ID references',
+    'callapi-refs': 'Invalid CallAPI action endpoint reference warnings',
+    'callapi-internal-refs': 'CallAPI actions targeting InternalApi endpoints',
+    'dynamic-endpoint-refs': 'Invalid Dynamic block endpoint reference warnings',
+    'websocket-refs': 'Invalid websocket action reference warnings',
+    icons: 'Unresolvable icon name warnings',
     types: 'All type validation (blocks, operators, actions, requests, connections)',
-    schema: 'JSON schema validation errors'
+    schema: 'JSON schema validation errors',
+    secrets: 'Environment variable names that are not set in the build environment'
 };
 /**
  * Checks if a build check should be suppressed based on ~ignoreBuildChecks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/errors",
-  "version": "0.0.0-experimental-20260928105334",
+  "version": "0.0.0-experimental-20260928120643",
   "license": "Apache-2.0",
   "description": "Lowdefy error classes for consistent error handling across build, server, and client",
   "homepage": "https://lowdefy.com",