Merge pull request #7 from Crowdhandler/improvement/lite-validator-support

Native support for the lite validator and some other minor adjustments

Author: luke-owen-crowdhandler

README.md

@@ -158,7 +158,9 @@ const result = await gatekeeper.validateRequest();
   responseID: string,     // Response ID for performance tracking (when promoted)
   deployment: string,     // Deployment identifier from the API
   token: string,          // The session token
-  hash: string | null     // Signature hash for validation (when available)
+  hash: string | null,    // Signature hash for validation (when available)
+  liteValidatorRedirect: boolean,  // true = redirect to lite validator
+  liteValidatorUrl: string         // URL for lite validator redirect
 }
 ```
 
@@ -262,7 +264,16 @@ const instance = crowdhandler.init({
     timeout: 5000,        // API timeout in milliseconds
     trustOnFail: true,    // Allow access if API fails
     fallbackSlug: '',     // Fallback room slug when trustOnFail is false
-    cookieName: 'crowdhandler'  // Custom cookie name (default: 'crowdhandler')
+    cookieName: 'crowdhandler',  // Custom cookie name (default: 'crowdhandler')
+    liteValidator: false, // Enable lite validator mode (default: false)
+    roomsConfig: [{       // Array of room configurations for lite validator
+      domain: string,     // e.g. 'https://example.com'
+      slug: string,       // Room identifier
+      urlPattern?: string,  // URL pattern to match
+      patternType?: 'regex' | 'contains' | 'all',
+      queueActivatesOn?: number,  // Unix timestamp
+      timeout?: number    // Timeout in seconds
+    }]
   }
 });
 ```
@@ -567,6 +578,43 @@ await gatekeeper.recordPerformance({
 });
 ```
 
+### Lite Validator Mode
+
+Lite validator mode provides token refresh without API calls by checking room configuration locally. To enable it:
+
+1. Set `liteValidator: true` in options
+2. Fetch and provide your rooms configuration from the CrowdHandler API
+
+```javascript
+// First, fetch your rooms configuration
+const { client } = init({ publicKey: 'YOUR_PUBLIC_KEY' });
+const roomsResponse = await client.rooms().get();
+
+// Then initialize with lite validator enabled
+const { gatekeeper } = init({
+  publicKey: 'YOUR_PUBLIC_KEY',
+  request: req,
+  response: res,
+  options: {
+    liteValidator: true,              // Enable lite validator
+    roomsConfig: roomsResponse.result // Pass the rooms array from API
+  }
+});
+
+// Handle the lite validator redirect
+const result = await gatekeeper.validateRequest();
+
+if (result.liteValidatorRedirect) {
+  // Redirect to refresh token/session
+  return gatekeeper.redirect(result.liteValidatorUrl);
+}
+```
+
+**When lite validator activates:**
+- URL matches a room in your config
+- Token is missing or >12 hours old
+- Redirects to CrowdHandler to refresh session
+
 ## Testing
 
 The SDK includes comprehensive testing tools:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "crowdhandler-sdk",
-  "version": "2.0.2",
+  "version": "2.0.3",
   "description": "",
   "homepage": "https://www.crowdhandler.com",
   "repository": {

src/common/types.ts

@@ -1,5 +1,17 @@
 import { z } from "zod";
 
+// Lite Validator types
+export const RoomConfig = z.object({
+  domain: z.string(), // Format: "https://example.com"
+  urlPattern: z.string().optional(),
+  patternType: z.enum(['regex', 'contains', 'all']).optional(),
+  queueActivatesOn: z.number().optional(),
+  slug: z.string(),
+  timeout: z.number().optional()
+});
+
+export const RoomsConfig = z.array(RoomConfig);
+
 //Gatekeeper Options
 export const GatekeeperOptions = z.object({
   debug: z.boolean().optional(),
@@ -8,6 +20,8 @@ export const GatekeeperOptions = z.object({
   timeout: z.number().optional(),
   trustOnFail: z.boolean().optional(),
   cookieName: z.string().optional(),
+  liteValidator: z.boolean().optional(),
+  roomsConfig: RoomsConfig.optional(), // Array of room configs
 });
 
 export const GatekeeperKeyPair = z.object({
@@ -94,7 +108,7 @@ export const SignatureSourceObject = z.object({
   crowdhandlerCookieValue: CookieObject.optional(),
 });
 
-export const GetTokenOptions = z.object({
+export const ExtractTokenOptions = z.object({
   //object can contain anything and we don't know any of the possible values
   crowdhandlerCookieValue: CookieObject.optional(),
   chID: z.string().optional(),
@@ -132,6 +146,8 @@ export const ValidateRequestObject = z.object({
   deployment: z.string().optional(),
   hash: z.string().nullable().optional(),
   token: z.string().optional(),
+  liteValidatorRedirect: z.boolean().optional(),
+  liteValidatorUrl: z.string().optional(),
 });
 
 export const HttpErrorWrapper = z.object({