@lowdefy/errors 0.0.0-experimental-20260909123240 → 0.0.0-experimental-20260909201552

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

@@ -59,8 +59,10 @@
         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;
+        // Check HTTP status codes (5xx = server error). AWS SDK v3 errors carry the
+        // status on $metadata.httpStatusCode; @google-cloud errors carry the numeric
+        // HTTP status as `code`.
+        const statusCode = error.statusCode ?? error.status ?? error.response?.status ?? error.$metadata?.httpStatusCode ?? (Number.isInteger(error.code) ? error.code : undefined);
         if (statusCode && statusCode >= 500 && statusCode < 600) {
             return true;
         }
@@ -104,7 +106,9 @@
    * @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.
+   */ constructor(message, { cause, service, code, statusCode, configKey, hint } = {}){
         // Extract info from wrapped error if provided
         const errorCode = code ?? cause?.code;
         const errorStatusCode = statusCode ?? cause?.statusCode ?? cause?.status ?? cause?.response?.status;
@@ -121,8 +125,11 @@
         this._message = baseMessage;
         this.service = service;
         this.code = errorCode;
+        this.hint = hint ?? cause?.hint ?? null;
         this.statusCode = errorStatusCode;
-        this.configKey = configKey ?? null;
+        // 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)
@@ -59,6 +73,7 @@
  *   shouldSuppressBuildCheck   - Check ~ignoreBuildChecks in parent chain
  */ 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';
@@ -73,5 +88,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, OperatorError, PluginError, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, UserError, VALID_CHECK_SLUGS };
+export { ActionError, AuthenticationError, AuthorizationError, BlockError, BuildError, ConfigError, ConfigWarning, errorToDisplayString, LowdefyInternalError, OperatorError, PluginError, RequestError, resolveConfigLocation, loadAndResolveErrorLocation, resolveErrorLocation, ServiceError, shouldSuppressBuildCheck, TwoFactorEnrolmentRequiredError, UserError, VALID_CHECK_SLUGS };

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-20260909123240",
+  "version": "0.0.0-experimental-20260909201552",
   "license": "Apache-2.0",
   "description": "Lowdefy error classes for consistent error handling across build, server, and client",
   "homepage": "https://lowdefy.com",