@deflectbot/deflect-sdk 1.3.8 → 1.4.0

package/dist/index.d.ts

@@ -12,12 +12,19 @@ declare class Deflect {
     private scriptCache;
     private isWarmupInProgress;
     private hasWarmupError;
-    private static readonly SDK_ERROR_MARKER;
+    private pulseReporter;
     constructor();
-    private initializeSentry;
     private initializeGlobalState;
     private setupAutomaticWarmup;
+    private resolvePulseConfig;
+    private reportError;
     private tryWarmup;
+    /**
+     * @param actionId - The action ID to validate
+     * @returns The sanitized action ID
+     * @throws Error if actionId contains invalid characters
+     */
+    private validateActionId;
     private buildScriptUrl;
     private fetchScript;
     private executeScript;
@@ -27,18 +34,80 @@ declare class Deflect {
     private loadScriptElement;
     private getTokenFromScript;
     private cleanup;
+    /**
+     * Configures the Deflect SDK with the provided parameters.
+     * Must be called before using getToken() or other SDK methods.
+     *
+     * @param params - Configuration options for the SDK
+     * @param params.actionId - The unique action identifier from your Deflect dashboard (required)
+     * @param params.scriptUrl - Optional custom script URL (defaults to Deflect CDN)
+     * @throws Error if actionId is empty or contains invalid characters
+     *
+     * @example
+     * ```typescript
+     * Deflect.configure({ actionId: "your-action-id" });
+     * ```
+     */
     configure(params: DeflectConfig): void;
     private isTestMode;
+    /**
+     * @deprecated Use {@link getToken} instead. This method is kept for backward compatibility.
+     * @returns A promise that resolves to the Deflect token string
+     */
     solveChallenge(): Promise<string>;
+    /**
+     * Retrieves a Deflect token for the configured action.
+     * The token should be included in requests to your protected endpoints.
+     *
+     * @returns A promise that resolves to the Deflect token string
+     * @throws Error if configure() has not been called first
+     * @throws Error if the script fails to load or execute
+     *
+     * @example
+     * ```typescript
+     * const token = await Deflect.getToken();
+     * // Include token in your API request
+     * fetch('/api/protected', {
+     *   headers: { 'X-Deflect-Token': token }
+     * });
+     * ```
+     */
     getToken(): Promise<string>;
+    /**
+     * Pre-fetches the challenge script to reduce latency on the first getToken() call.
+     * This is automatically called after configure(), but can be manually triggered.
+     *
+     * @returns A promise that resolves to true if warmup succeeded, false otherwise
+     *
+     * @example
+     * ```typescript
+     * Deflect.configure({ actionId: "your-action-id" });
+     * const warmedUp = await Deflect.warmup();
+     * console.log('Script pre-cached:', warmedUp);
+     * ```
+     */
     warmup(): Promise<boolean>;
+    /**
+     * Clears the cached challenge script.
+     * Useful when you need to force a fresh script fetch on the next getToken() call.
+     */
     clearCache(): void;
     /**
-     * Inject a fresh token as a hidden input into a form. Only accepts a submit event from onsubmit.
-     * Usage: <form ... onsubmit="return Deflect.injectToken(event)">
-     * Returns false to prevent double submit.
+     * Injects a Deflect token as a hidden input into a form and submits it.
+     * Designed for use with form onsubmit handlers.
+     *
+     * @param event - The form submit event
+     * @throws Error if not called from a form submit event
+     *
+     * @example
+     * ```html
+     * <form action="/login" method="POST" onsubmit="Deflect.injectToken(event)">
+     *   <input name="username" />
+     *   <button type="submit">Login</button>
+     * </form>
+     * ```
      */
-    injectToken(event: SubmitEvent): Promise<false>;
+    injectToken(event: SubmitEvent): Promise<void>;
 }
 declare const DeflectInstance: Deflect;
 export default DeflectInstance;

package/dist/index.esm.js

@@ -1,58 +1,14 @@
-import * as Sentry from "@sentry/browser";
+import PulseReporter from "./pulse";
 class Deflect {
   constructor() {
     this.config = null;
     this.scriptCache = null;
     this.isWarmupInProgress = false;
     this.hasWarmupError = false;
-    this.initializeSentry();
     this.initializeGlobalState();
+    this.pulseReporter = new PulseReporter(this.resolvePulseConfig());
     this.setupAutomaticWarmup();
   }
-  static {
-    this.SDK_ERROR_MARKER = "__DEFLECT_SDK_ERROR__";
-  }
-  initializeSentry() {
-    try {
-      Sentry.init({
-        dsn: "https://4a62ed75ab362d4694ae4215c2b4f621@o4509968565665792.ingest.de.sentry.io/4510257986469968",
-        sendDefaultPii: true,
-        // Enable to capture IP address
-        environment: typeof window !== "undefined" ? window.location.hostname : "unknown",
-        beforeSend(event) {
-          const isSDKError = event.tags?.deflect_sdk_error === "true";
-          if (!isSDKError) {
-            return null;
-          }
-          if (typeof window !== "undefined" && typeof navigator !== "undefined") {
-            event.contexts = event.contexts || {};
-            event.contexts.browser = {
-              name: navigator.userAgent,
-              version: navigator.appVersion
-            };
-            event.request = event.request || {};
-            event.request.headers = event.request.headers || {};
-            event.request.headers["User-Agent"] = navigator.userAgent;
-            event.contexts.page = {
-              url: window.location.href,
-              referrer: document.referrer,
-              title: document.title
-            };
-            event.contexts.device = {
-              screen_width: window.screen.width,
-              screen_height: window.screen.height,
-              viewport_width: window.innerWidth,
-              viewport_height: window.innerHeight,
-              language: navigator.language,
-              platform: navigator.platform
-            };
-          }
-          return event;
-        }
-      });
-    } catch {
-    }
-  }
   initializeGlobalState() {
     if (typeof window === "undefined") return;
     window.Deflect = window.Deflect || {};
@@ -65,6 +21,16 @@ class Deflect {
       setTimeout(() => this.tryWarmup(), 100);
     }
   }
+  resolvePulseConfig() {
+    const runtimeConfig = typeof window !== "undefined" && typeof window.Deflect === "object" && window.Deflect?.pulseConfig && typeof window.Deflect.pulseConfig === "object" ? window.Deflect.pulseConfig : {};
+    return {
+      ...runtimeConfig,
+      environment: runtimeConfig.environment || (typeof window !== "undefined" ? window.location.hostname : void 0)
+    };
+  }
+  reportError(error, tags, context) {
+    this.pulseReporter.captureException(error, { tags, context });
+  }
   async tryWarmup() {
     if (!this.config?.actionId || this.isWarmupInProgress || this.scriptCache || this.hasWarmupError) {
       return;
@@ -79,55 +45,108 @@ class Deflect {
       this.isWarmupInProgress = false;
     }
   }
+  /**
+   * @param actionId - The action ID to validate
+   * @returns The sanitized action ID
+   * @throws Error if actionId contains invalid characters
+   */
+  validateActionId(actionId) {
+    const sanitized = actionId.trim();
+    const validPattern = /^[a-zA-Z0-9/_-]+$/;
+    if (!validPattern.test(sanitized)) {
+      throw new Error("Invalid actionId format: contains disallowed characters");
+    }
+    return encodeURIComponent(sanitized);
+  }
   buildScriptUrl(actionId) {
     const baseUrl = this.config?.scriptUrl || "https://js.deflect.bot/main.js";
+    const sanitizedActionId = this.validateActionId(actionId);
     const nonce = Date.now().toString();
-    return `${baseUrl}?action_id=${actionId}&_=${nonce}`;
+    return `${baseUrl}?action_id=${sanitizedActionId}&_=${nonce}`;
   }
   async fetchScript() {
     if (!this.config?.actionId) {
       throw new Error("actionId is required");
     }
     const url = this.buildScriptUrl(this.config.actionId);
-    const response = await fetch(url, { cache: "no-store" });
-    if (!response.ok) {
-      throw new Error(`Failed to fetch script: ${response.status}`);
-    }
-    const content = await response.text();
     try {
-      const maybeError = JSON.parse(content);
-      if (maybeError.success === false || maybeError.error) {
-        const errorMessage = maybeError.error || "Script fetch failed";
-        const error = new Error(errorMessage);
-        if (errorMessage === "action_does_not_exist" || errorMessage.includes("invalid action")) {
-          error.isUserError = true;
-        }
-        throw error;
+      const response = await fetch(url, {
+        cache: "no-store",
+        mode: "cors",
+        credentials: "omit"
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch script: ${response.status}`);
       }
-    } catch (e) {
-      if (e instanceof SyntaxError) {
-      } else {
-        throw e;
+      const content = await response.text();
+      try {
+        const maybeError = JSON.parse(content);
+        if (maybeError.success === false || maybeError.error) {
+          const errorMessage = maybeError.error || "Script fetch failed";
+          const error = new Error(errorMessage);
+          if (errorMessage === "action_does_not_exist" || errorMessage.includes("invalid action")) {
+            error.isUserError = true;
+          }
+          throw error;
+        }
+      } catch (e) {
+        if (!(e instanceof SyntaxError)) {
+          throw e;
+        }
       }
+      return {
+        content,
+        sessionId: response.headers.get("session_id") || void 0
+      };
+    } catch (error) {
+      this.reportError(
+        error,
+        {
+          deflect_sdk_error: "true",
+          method: "fetchScript",
+          action_id: this.config.actionId
+        },
+        {
+          actionId: this.config.actionId,
+          url
+        }
+      );
+      throw error;
     }
-    return {
-      content,
-      sessionId: response.headers.get("session_id") || void 0
-    };
   }
   async executeScript(script) {
     if (script.sessionId && typeof window !== "undefined") {
       window.Deflect.sessionId = script.sessionId;
     }
     const blobUrl = this.createScriptBlob(script.content);
-    const scriptElement = await this.loadScriptElement(blobUrl);
+    let scriptElement = null;
     try {
+      scriptElement = await this.loadScriptElement(blobUrl);
       await this.waitForGetToken();
       const token = await this.getTokenFromScript();
       this.prefetchNextScript();
       return token;
+    } catch (error) {
+      this.reportError(
+        error,
+        {
+          deflect_sdk_error: "true",
+          method: "executeScript",
+          stage: "load_or_execute",
+          action_id: this.config?.actionId || "unknown"
+        },
+        {
+          hasCache: this.scriptCache !== null,
+          hasWarmupError: this.hasWarmupError
+        }
+      );
+      throw error;
     } finally {
-      this.cleanup(blobUrl, scriptElement);
+      if (scriptElement) {
+        this.cleanup(blobUrl, scriptElement);
+      } else {
+        URL.revokeObjectURL(blobUrl);
+      }
     }
   }
   prefetchNextScript() {
@@ -137,16 +156,16 @@ class Deflect {
     }
   }
   async waitForGetToken() {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       const checkInterval = setInterval(() => {
         if (typeof window !== "undefined" && typeof window.Deflect?.getToken === "function") {
           clearInterval(checkInterval);
           resolve();
         }
-      }, 10);
+      }, 50);
       setTimeout(() => {
         clearInterval(checkInterval);
-        resolve();
+        reject(new Error("Timeout: getToken function did not become available within 10 seconds"));
       }, 1e4);
     });
   }
@@ -181,6 +200,20 @@ class Deflect {
       delete window.Deflect.getToken;
     }
   }
+  /**
+   * Configures the Deflect SDK with the provided parameters.
+   * Must be called before using getToken() or other SDK methods.
+   * 
+   * @param params - Configuration options for the SDK
+   * @param params.actionId - The unique action identifier from your Deflect dashboard (required)
+   * @param params.scriptUrl - Optional custom script URL (defaults to Deflect CDN)
+   * @throws Error if actionId is empty or contains invalid characters
+   * 
+   * @example
+   * ```typescript
+   * Deflect.configure({ actionId: "your-action-id" });
+   * ```
+   */
   configure(params) {
     try {
       if (!params.actionId?.trim()) {
@@ -200,25 +233,53 @@ class Deflect {
       }
     } catch (error) {
       const isUserError = error && typeof error === "object" && "isUserError" in error && error.isUserError === true;
-      if (!isUserError) {
-        Sentry.captureException(error, {
-          tags: {
-            deflect_sdk_error: "true",
-            method: "configure",
-            actionId: params?.actionId || "unknown"
-          }
-        });
-      }
+      this.reportError(
+        error,
+        {
+          deflect_sdk_error: "true",
+          deflect_user_error: isUserError ? "true" : "false",
+          method: "configure",
+          action_id: params?.actionId || "unknown"
+        },
+        {
+          actionId: params?.actionId,
+          hasCache: this.scriptCache !== null,
+          hasWarmupError: this.hasWarmupError
+        }
+      );
       throw error;
     }
   }
   isTestMode() {
+    if (this.config?.actionId === "PULSE_TEST" || this.config?.actionId === "SENTRY_TEST") {
+      throw new Error("PULSE_TEST: This is a test error to verify Pulse integration is working");
+    }
     return this.config?.actionId === "t/FFFFFFFFFFFFF/111111111" || this.config?.actionId === "t/FFFFFFFFFFFFF/000000000";
   }
-  // Deprecated name kept for backward compatibility
+  /**
+   * @deprecated Use {@link getToken} instead. This method is kept for backward compatibility.
+   * @returns A promise that resolves to the Deflect token string
+   */
   async solveChallenge() {
     return this.getToken();
   }
+  /**
+   * Retrieves a Deflect token for the configured action.
+   * The token should be included in requests to your protected endpoints.
+   * 
+   * @returns A promise that resolves to the Deflect token string
+   * @throws Error if configure() has not been called first
+   * @throws Error if the script fails to load or execute
+   * 
+   * @example
+   * ```typescript
+   * const token = await Deflect.getToken();
+   * // Include token in your API request
+   * fetch('/api/protected', {
+   *   headers: { 'X-Deflect-Token': token }
+   * });
+   * ```
+   */
   async getToken() {
     try {
       if (!this.config?.actionId) {
@@ -227,9 +288,6 @@ class Deflect {
       if (this.isTestMode()) {
         return "TESTTOKEN";
       }
-      if (this.config.actionId === "SENTRY_TEST") {
-        throw new Error("SENTRY_TEST: This is a test error to verify Sentry integration is working");
-      }
       let script;
       if (this.scriptCache && !this.isWarmupInProgress) {
         script = this.scriptCache;
@@ -240,20 +298,39 @@ class Deflect {
       return this.executeScript(script);
     } catch (error) {
       const isUserError = error && typeof error === "object" && "isUserError" in error && error.isUserError === true;
-      if (!isUserError) {
-        Sentry.captureException(error, {
-          tags: {
-            deflect_sdk_error: "true",
-            method: "getToken",
-            actionId: this.config?.actionId || "unknown",
-            hasCache: this.scriptCache !== null,
-            hasWarmupError: this.hasWarmupError
-          }
-        });
-      }
+      this.reportError(
+        error,
+        {
+          deflect_sdk_error: "true",
+          deflect_user_error: isUserError ? "true" : "false",
+          method: "getToken",
+          action_id: this.config?.actionId || "unknown",
+          has_cache: this.scriptCache !== null ? "true" : "false",
+          has_warmup_error: this.hasWarmupError ? "true" : "false",
+          stage: "call"
+        },
+        {
+          actionId: this.config?.actionId,
+          hasCache: this.scriptCache !== null,
+          hasWarmupError: this.hasWarmupError
+        }
+      );
       throw error;
     }
   }
+  /**
+   * Pre-fetches the challenge script to reduce latency on the first getToken() call.
+   * This is automatically called after configure(), but can be manually triggered.
+   * 
+   * @returns A promise that resolves to true if warmup succeeded, false otherwise
+   * 
+   * @example
+   * ```typescript
+   * Deflect.configure({ actionId: "your-action-id" });
+   * const warmedUp = await Deflect.warmup();
+   * console.log('Script pre-cached:', warmedUp);
+   * ```
+   */
   async warmup() {
     if (!this.config?.actionId) {
       return false;
@@ -265,13 +342,27 @@ class Deflect {
       return false;
     }
   }
+  /**
+   * Clears the cached challenge script.
+   * Useful when you need to force a fresh script fetch on the next getToken() call.
+   */
   clearCache() {
     this.scriptCache = null;
   }
   /**
-   * Inject a fresh token as a hidden input into a form. Only accepts a submit event from onsubmit.
-   * Usage: <form ... onsubmit="return Deflect.injectToken(event)">
-   * Returns false to prevent double submit.
+   * Injects a Deflect token as a hidden input into a form and submits it.
+   * Designed for use with form onsubmit handlers.
+   * 
+   * @param event - The form submit event
+   * @throws Error if not called from a form submit event
+   * 
+   * @example
+   * ```html
+   * <form action="/login" method="POST" onsubmit="Deflect.injectToken(event)">
+   *   <input name="username" />
+   *   <button type="submit">Login</button>
+   * </form>
+   * ```
    */
   async injectToken(event) {
     if (!event || !event.target || !(event.target instanceof HTMLFormElement)) {
@@ -289,7 +380,6 @@ class Deflect {
     hidden.value = token;
     form.appendChild(hidden);
     form.submit();
-    return false;
   }
 }
 const DeflectInstance = new Deflect();