Merge pull request #11 from Crowdhandler/improvement/error-handling

A few changes, primarily focussed on error handling improvements.

Author: luke-owen-crowdhandler

README.md

@@ -61,6 +61,13 @@ const { client, gatekeeper } = crowdhandler.init({
 // Validate the request
 const result = await gatekeeper.validateRequest();
 
+// Check for errors first
+if (result.error) {
+  console.error(`Validation error: ${result.error.message}`);
+  // 4xx errors: promoted = false (always block access)
+  // 5xx errors: promoted depends on trustOnFail setting
+}
+
 // Handle the validation result
 if (result.setCookie) {
   gatekeeper.setCookie(result.cookieValue, result.domain);
@@ -192,12 +199,10 @@ try {
   const result = await gatekeeper.validateRequest();
   // ... handle result ...
 } catch (error) {
-  if (error.code === 'API_CONNECTION_FAILED') {
-    // Handle based on trustOnFail setting
-    // true = allow access, false = use fallback room
-  }
+  console.error('Validation failed:', error.message);
+  console.error('Status code:', error.statusCode);
+  // Handle based on trustOnFail setting
 }
-```
 
 ### gatekeeper.setCookie(value, domain?)
 
@@ -418,27 +423,46 @@ Full API documentation with request/response examples is available in your [Crow
 
 ## Error Handling
 
-All SDK errors are instances of `CrowdHandlerError` with helpful context:
+All SDK errors are instances of `CrowdHandlerError` with consistent structure:
 
 ```javascript
 try {
   const rooms = await client.rooms().get();
 } catch (error) {
-  console.error(error.code);       // 'ROOM_NOT_FOUND'
-  console.error(error.message);    // Human-readable message
-  console.error(error.suggestion); // Helpful next steps
-  console.error(error.statusCode); // HTTP status code
+  console.error(error.message);    // The actual API error message
+  console.error(error.statusCode); // HTTP status code (e.g., 401, 404)
+  console.error(error.suggestion); // Helpful guidance for resolution
+  console.error(error.code);       // Error code for programmatic handling
 }
 ```
 
-### Error Codes
+### API Error Transparency
+
+The SDK preserves the exact error messages from the CrowdHandler API, allowing you to handle specific error scenarios:
+
+```javascript
+try {
+  const result = await gatekeeper.validateRequest({
+    custom: { code: 'user-code' }
+  });
+} catch (error) {
+  // Check the specific error message from the API
+  if (error.message.includes('Invalid priority code')) {
+    // Handle invalid access code
+  }
+  
+  // For advanced debugging, access the full API response
+  const apiResponse = error.context?.apiResponse;
+}
+```
+
+### Common Error Codes
 
 - `INVALID_CONFIG` - Invalid SDK configuration
 - `MISSING_PRIVATE_KEY` - Private key required for this operation
 - `API_CONNECTION_FAILED` - Cannot reach CrowdHandler API
-- `RESOURCE_NOT_FOUND` - Requested resource doesn't exist
-- `RATE_LIMITED` - Too many requests
-- Plus more specific error codes
+- `API_INVALID_RESPONSE` - API returned an error
+- `RATE_LIMITED` - Too many requests (includes retry-after)
 
 ## Integration Examples
 
@@ -468,6 +492,13 @@ async function protectRoute(req, res, next) {
 
     const result = await gatekeeper.validateRequest();
 
+    // Check if there was an error during validation
+    if (result.error) {
+      console.error(`API Error ${result.error.statusCode}: ${result.error.message}`);
+      // 4xx errors (e.g., invalid key, bad request): promoted = false (user blocked)
+      // 5xx errors (e.g., server error): promoted based on trustOnFail setting
+    }
+    
     if (result.setCookie) {
       gatekeeper.setCookie(result.cookieValue, result.domain);
     }
@@ -484,8 +515,10 @@ async function protectRoute(req, res, next) {
     res.locals.gatekeeper = gatekeeper;
     next();
   } catch (error) {
-    console.error('CrowdHandler error:', error);
-    // Decide whether to block or allow on error
+    // This catches unexpected errors (e.g., network issues, config errors)
+    console.error('CrowdHandler SDK error:', error.message);
+    // trustOnFail: true (default) = allow access on error
+    // trustOnFail: false = block access on error
     next();
   }
 }
@@ -607,6 +640,36 @@ await gatekeeper.recordPerformance({
 });
 ```
 
+### Test Error Simulation
+
+For testing your error handling without making real API calls, you can simulate errors:
+
+```javascript
+const { gatekeeper } = init({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  request: req,
+  response: res,
+  options: {
+    testError: {
+      statusCode: 500,  // Simulate a 500 error
+      message: 'Simulated server error for testing'
+    }
+  }
+});
+
+// This will return immediately with a simulated error
+const result = await gatekeeper.validateRequest();
+// result.error will contain the test error
+// result.promoted will be true (with default trustOnFail: true)
+```
+
+This is useful for:
+- Testing error handling logic in development
+- Verifying fallback behavior for different error types
+- Integration testing without affecting production metrics
+
+Note: 4xx test errors will always set `promoted: false`, while 5xx test errors respect your `trustOnFail` setting.
+
 ### Lite Validator Mode
 
 Lite validator mode provides token refresh without API calls by checking room configuration locally. To enable it:

dist/client/base_client.js

@@ -91,10 +91,31 @@ var BaseClient = /** @class */ (function () {
             stack: error.stack
         });
     };
+    /**
+     * Provides generic suggestion based on HTTP status code
+     */
+    BaseClient.prototype.getGenericSuggestion = function (status) {
+        switch (status) {
+            case 400: return 'Check your request parameters';
+            case 401: return 'Check your authentication credentials';
+            case 403: return 'You do not have permission for this action';
+            case 404: return 'The requested resource was not found';
+            case 429: return 'Too many requests - please slow down';
+            case 500:
+            case 502:
+            case 503:
+            case 504:
+                return 'Server error - please try again later';
+            default:
+                return status >= 500
+                    ? 'This appears to be a server error. Please try again later or contact support@crowdhandler.com'
+                    : 'Please check your request parameters and try again';
+        }
+    };
     BaseClient.prototype.errorHandler = function (error) {
         var _a, _b, _c, _d;
         return __awaiter(this, void 0, void 0, function () {
-            var status_1, data, retryAfter, urlMatch, resourceType, resourceId, errorMessage;
+            var status_1, data, errorMessage, retryAfter;
             return __generator(this, function (_e) {
                 // If it's already a CrowdHandlerError, just re-throw it
                 if (error instanceof errors_1.CrowdHandlerError) {
@@ -105,28 +126,24 @@ var BaseClient = /** @class */ (function () {
                     data = error.response.data;
                     (0, logger_1.logger)(this.debug, "error", "API Error - Status: ".concat(status_1, " - ").concat(JSON.stringify(data)));
                     (0, logger_1.logger)(this.debug, "error", "Response headers: ".concat(JSON.stringify(error.response.headers)));
-                    // Handle specific HTTP status codes
-                    if (status_1 === 401) {
-                        throw errors_1.createError.invalidApiKey('public');
-                    }
+                    errorMessage = (data === null || data === void 0 ? void 0 : data.error) || (data === null || data === void 0 ? void 0 : data.message) || "API request failed with status ".concat(status_1);
+                    // Special handling for rate limiting to include retry-after
                     if (status_1 === 429) {
                         retryAfter = error.response.headers['retry-after'];
-                        throw errors_1.createError.rateLimited(retryAfter);
-                    }
-                    if (status_1 === 404) {
-                        urlMatch = (_b = (_a = error.config) === null || _a === void 0 ? void 0 : _a.url) === null || _b === void 0 ? void 0 : _b.match(/\/v1\/(\w+)\/(\w+)/);
-                        if (urlMatch) {
-                            resourceType = urlMatch[1], resourceId = urlMatch[2];
-                            throw errors_1.createError.resourceNotFound(resourceType, resourceId);
-                        }
+                        throw new errors_1.CrowdHandlerError(errors_1.ErrorCodes.RATE_LIMITED, errorMessage, retryAfter
+                            ? "Wait ".concat(retryAfter, " seconds before retrying")
+                            : 'Reduce the frequency of API calls', status_1, {
+                            url: (_a = error.config) === null || _a === void 0 ? void 0 : _a.url,
+                            method: (_b = error.config) === null || _b === void 0 ? void 0 : _b.method,
+                            apiResponse: data,
+                            retryAfter: retryAfter
+                        });
                     }
-                    errorMessage = (data === null || data === void 0 ? void 0 : data.error) || (data === null || data === void 0 ? void 0 : data.message) || "API request failed with status ".concat(status_1);
-                    throw new errors_1.CrowdHandlerError(errors_1.ErrorCodes.API_INVALID_RESPONSE, errorMessage, status_1 >= 500
-                        ? 'This appears to be a server error. Please try again later or contact support@crowdhandler.com'
-                        : 'Please check your request parameters and try again', status_1, {
+                    // Pass through the API error with full response data
+                    throw new errors_1.CrowdHandlerError(errors_1.ErrorCodes.API_INVALID_RESPONSE, errorMessage, this.getGenericSuggestion(status_1), status_1, {
                         url: (_c = error.config) === null || _c === void 0 ? void 0 : _c.url,
                         method: (_d = error.config) === null || _d === void 0 ? void 0 : _d.method,
-                        responseData: JSON.stringify(data).substring(0, 200)
+                        apiResponse: data // Full API response, not truncated
                     });
                 }
                 else if (error.request) {

dist/common/types.js

@@ -23,6 +23,10 @@ exports.GatekeeperOptions = zod_1.z.object({
     liteValidator: zod_1.z.boolean().optional(),
     roomsConfig: exports.RoomsConfig.optional(),
     waitingRoom: zod_1.z.boolean().optional(),
+    testError: zod_1.z.object({
+        statusCode: zod_1.z.number(),
+        message: zod_1.z.string().optional(),
+    }).optional(), // For testing error handling
 });
 exports.GatekeeperKeyPair = zod_1.z.object({
     publicKey: zod_1.z.string(),
@@ -146,6 +150,11 @@ exports.ValidateRequestObject = zod_1.z.object({
     liteValidatorRedirect: zod_1.z.boolean().optional(),
     liteValidatorUrl: zod_1.z.string().optional(),
     domain: zod_1.z.string().optional(),
+    error: zod_1.z.object({
+        message: zod_1.z.string(),
+        statusCode: zod_1.z.number().optional(),
+        code: zod_1.z.string().optional(),
+    }).optional(),
 });
 exports.HttpErrorWrapper = zod_1.z.object({
     result: zod_1.z.object({