@deflectbot/deflect-sdk 1.2.2 → 1.3.0

package/README.md

@@ -1,50 +1,78 @@
-# Deflect -
+# Deflect SDK (Client-side)
 
 ![npm](https://img.shields.io/npm/v/@deflectbot/deflect-sdk)
 ![downloads](https://img.shields.io/npm/dm/@deflectbot/deflect-sdk)
 
-Deflect is an antibot solution that works with Vue, React, NextJS, and other JavaScript frameworks.
+[Deflect](https://deflect.bot) is an advanced antibot engine that protects your site from bots on any scale.
 
----
+## Usage
 
-## CDN Install (Auto-Updates)
+See the [documentation](https://docs.deflect.bot/) for how to use this SDK with the Deflect APIs.
+
+## Installation
+
+#### yarn
 
 ```bash
-Include in your project:
-<script src="https://cdn.jsdelivr.net/npm/@deflectbot/deflect-sdk/dist/index.min.js"></script>
+yarn add @castleio/sdk
 ```
 
----
-
-## NPM Install (Requires Manual Updates)
+#### npm
 
 ```bash
-npm install deflect
+npm install --save @castleio/sdk
 ```
 
----
+#### CDN
 
-## Setup
+Use `@deflect-sdk@latest` to always use the latest version, or specify a version with `@deflect-sdk@x.x.x`.
 
-```ts
-import Deflect from '@deflectbot/deflect-sdk';
+```html
+<script src="https://cdn.jsdelivr.net/npm/@deflectbot/deflect-sdk@latest/dist/index.min.js" />
+```
 
+## Configuration
+
+Deflect works through Defense Actions™, which allows you to either setup a global configuration one-time to work across your entire application, or individual and more customized Defense Actions™ for each protected endpoint.
+
+#### One-time global initialization.
+
+```ts
 Deflect.configure({
-  actionId: 'YOUR_ACTION_ID',
-  extraArgs: { mode: 'strict' }, // Optional
-  forceRefresh: true, // Optional
+  actionId: "<ACTION_ID>",
 });
 ```
 
----
-
-## Solve Challenge
+#### To get a token to pass to a protected endpoint
 
 ```ts
-try {
-  const token = await Deflect.solveChallenge();
-  console.log('✅ Token received:', token);
-} catch (error) {
-  console.error('❌ Failed to solve challenge:', error);
-}
+const token = await Deflect.getToken(); // returns token as string
+```
+
+#### Helper for form submit
+
+If you're using forms like this:
+
+```html
+<form action="/login" method="POST">
+  <input name="username" />
+  <input name="password" type="password" />
+  <button type="submit">Login</button>
+</form>
 ```
+
+You can use the helper as shown:
+
+```html
+<form
+  action="/login"
+  method="POST"
+  onsubmit="return Deflect.injectToken(event)"
+>
+  <input name="username" />
+  <input name="password" type="password" />
+  <button type="submit">Login</button>
+</form>
+```
+
+`injectToken()` will fetch a token and insert it as a hidden input named `deflect_token` into your form. Use it directly in your form's onsubmit attribute:

package/dist/deflect.global.min.js

@@ -0,0 +1 @@
+"use strict";var Deflect=(()=>{var c=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var f=(n,e)=>{for(var t in e)c(n,t,{get:e[t],enumerable:!0})},u=(n,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of d(e))!p.call(n,i)&&i!==t&&c(n,i,{get:()=>e[i],enumerable:!(r=l(e,i))||r.enumerable});return n};var h=n=>u(c({},"__esModule",{value:!0}),n);var m={};f(m,{default:()=>w});var s=class{constructor(){this.config=null;this.scriptCache=null;this.isWarmupInProgress=!1;this.initializeGlobalState(),this.setupAutomaticWarmup()}initializeGlobalState(){typeof window>"u"||(window.Deflect=window.Deflect||{})}setupAutomaticWarmup(){typeof window>"u"||(document.readyState==="loading"?document.addEventListener("DOMContentLoaded",()=>this.tryWarmup()):setTimeout(()=>this.tryWarmup(),100))}async tryWarmup(){if(!(!this.config?.actionId||this.isWarmupInProgress||this.scriptCache)){this.isWarmupInProgress=!0;try{this.scriptCache=await this.fetchScript()}catch{}finally{this.isWarmupInProgress=!1}}}buildScriptUrl(e){let t=this.config?.scriptUrl||"https://js.deflect.bot/main.js";if(this.config?.scriptUrl)return t;let r=Date.now().toString();return`${t}?action_id=${e}&_=${r}`}async fetchScript(){if(!this.config?.actionId)throw new Error("actionId is required");let e=this.buildScriptUrl(this.config.actionId),t=await fetch(e,{cache:"no-store"});if(!t.ok)throw new Error(`Failed to fetch script: ${t.status}`);return{content:await t.text(),sessionId:t.headers.get("session_id")||void 0}}async executeScript(e){e.sessionId&&typeof window<"u"&&(window.Deflect.sessionId=e.sessionId);let t=this.createReadyPromise(),r=this.createScriptBlob(e.content),i=await this.loadScriptElement(r);try{await t;let o=await this.getTokenFromScript();return this.prefetchNextScript(),o}finally{this.cleanup(r,i)}}prefetchNextScript(){this.tryWarmup().catch(()=>{})}createReadyPromise(){return new Promise(e=>{typeof window<"u"&&(window.Deflect.ready={promise:new Promise(t=>{window.Deflect.ready.resolve=t}),resolve:()=>e()})})}createScriptBlob(e){let t=new Blob([e],{type:"text/javascript"});return URL.createObjectURL(t)}async loadScriptElement(e){return new Promise((t,r)=>{let i=document.createElement("script");i.type="module",i.src=e,i.onload=()=>t(i),i.onerror=()=>r(new Error("Script failed to load")),document.head.appendChild(i)})}async getTokenFromScript(){if(typeof window>"u"||typeof window.Deflect?.getToken!="function")throw new Error("Script did not load properly - getToken not available");try{return await window.Deflect.getToken()}catch(e){throw new Error(`Script execution failed: ${e}`)}}cleanup(e,t){URL.revokeObjectURL(e),t.remove(),typeof window<"u"&&window.Deflect?.getToken&&delete window.Deflect.getToken}configure(e){if(!e.actionId?.trim())throw new Error("actionId is required and cannot be empty");this.config={...e},typeof window<"u"&&(window.Deflect.actionId=e.actionId),this.tryWarmup()}async solveChallenge(){return this.getToken()}async getToken(){if(!this.config?.actionId)throw new Error("Must call configure() before solveChallenge()");let e;return this.scriptCache&&!this.isWarmupInProgress?(e=this.scriptCache,this.scriptCache=null):e=await this.fetchScript(),this.executeScript(e)}async warmup(){if(!this.config?.actionId)return!1;try{return await this.tryWarmup(),this.scriptCache!==null}catch{return!1}}clearCache(){this.scriptCache=null}async injectToken(e){if(!e||!e.target||!(e.target instanceof HTMLFormElement))throw new Error("injectToken: must be called from a form submit event");e.preventDefault();let t=e.target,r=await this.getToken();Array.from(t.querySelectorAll('input[name="deflect_token"]')).forEach(o=>o.remove());let i=document.createElement("input");return i.type="hidden",i.name="deflect_token",i.value=r,t.appendChild(i),t.submit(),!1}},a=new s;typeof window<"u"&&(window.Deflect=a);var w=a;return h(m);})();

package/dist/global.js

@@ -0,0 +1,7 @@
+// Re-export the default instance while also assigning it to window.Deflect for non-module usage.
+import DeflectInstance from "./index";
+if (typeof window !== "undefined") {
+    // Avoid overwriting if a user already attached something custom.
+    window.Deflect = DeflectInstance;
+}
+export default DeflectInstance;

package/dist/index.js

@@ -1,108 +1,226 @@
-var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
-    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
-    return new (P || (P = Promise))(function (resolve, reject) {
-        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
-        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
-        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
-        step((generator = generator.apply(thisArg, _arguments || [])).next());
-    });
-};
-class Deflect {
-    constructor() {
-        this._prefetchedScriptText = null;
-        this._hasUsedPrefetch = false;
-        window.Deflect = window.Deflect || {};
-        window.Deflect.extraArgs = window.Deflect.extraArgs || {};
-        if (typeof window !== "undefined") {
-            window.addEventListener("load", () => {
-                setTimeout(() => {
-                    this._warmupScript();
-                }, 500);
-            });
-        }
-    }
-    _warmupScript() {
-        if (!window.Deflect.actionId)
-            return;
-        const nonce = Date.now().toString();
-        const scriptUrl = `https://js.deflect.bot/main.js?action_id=${window.Deflect.actionId}&_=${nonce}`;
-        fetch(scriptUrl, { cache: "no-store" })
-            .then((res) => __awaiter(this, void 0, void 0, function* () {
-            if (!res.ok)
-                return;
-            this._prefetchedScriptText = yield res.text();
-        }))
-            .catch(() => { });
-    }
-    setupReady() {
-        let resolveFn;
-        const promise = new Promise((resolve) => {
-            resolveFn = resolve;
-        });
-        window.Deflect.ready = {
-            promise,
-            resolve: () => resolveFn(),
-        };
-    }
-    configure(params) {
-        if (!params.actionId) {
-            throw new Error("actionId is required in configuration");
-        }
-        window.Deflect.actionId = params.actionId;
-    }
-    solveChallenge() {
-        return __awaiter(this, void 0, void 0, function* () {
-            var _a;
-            if (!window.Deflect.actionId) {
-                throw new Error("actionId is missing in configuration");
-            }
-            this.setupReady();
-            let scriptText;
-            let sessionId = null;
-            if (this._prefetchedScriptText && !this._hasUsedPrefetch) {
-                scriptText = this._prefetchedScriptText;
-                this._hasUsedPrefetch = true;
-            }
-            else {
-                const nonce = Date.now().toString();
-                const scriptUrl = `https://js.deflect.bot/main.js?action_id=${window.Deflect.actionId}&_=${nonce}`;
-                const response = yield fetch(scriptUrl, { cache: "no-store" });
-                if (!response.ok) {
-                    throw new Error("Failed to fetch the Deflect script");
-                }
-                sessionId = response.headers.get("session_id");
-                scriptText = yield response.text();
-            }
-            if (sessionId) {
-                window.Deflect.sessionId = sessionId;
-            }
-            const blob = new Blob([scriptText], { type: "text/javascript" });
-            const blobUrl = URL.createObjectURL(blob);
-            const scriptEl = document.createElement("script");
-            scriptEl.type = "module";
-            scriptEl.src = blobUrl;
-            document.head.appendChild(scriptEl);
-            yield new Promise((resolve, reject) => {
-                scriptEl.onload = () => resolve();
-                scriptEl.onerror = () => reject("Failed to load the Deflect script");
-            });
-            yield ((_a = window.Deflect.ready) === null || _a === void 0 ? void 0 : _a.promise);
-            if (typeof window.Deflect === "undefined" ||
-                typeof window.Deflect.getToken !== "function") {
-                throw new Error("Deflect script did not load properly");
-            }
-            let token;
-            try {
-                token = yield window.Deflect.getToken();
-            }
-            catch (error) {
-                throw new Error(`Deflect script execution failed: ${error}`);
-            }
-            URL.revokeObjectURL(blobUrl);
-            scriptEl.remove();
-            delete window.Deflect.getToken;
-            return token;
-        });
-    }
-}
-export default new Deflect();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+class Deflect {
+    constructor() {
+        this.config = null;
+        this.scriptCache = null;
+        this.isWarmupInProgress = false;
+        this.initializeGlobalState();
+        this.setupAutomaticWarmup();
+    }
+    initializeGlobalState() {
+        if (typeof window === "undefined")
+            return;
+        window.Deflect = window.Deflect || {};
+    }
+    setupAutomaticWarmup() {
+        if (typeof window === "undefined")
+            return;
+        if (document.readyState === "loading") {
+            document.addEventListener("DOMContentLoaded", () => this.tryWarmup());
+        }
+        else {
+            setTimeout(() => this.tryWarmup(), 100);
+        }
+    }
+    tryWarmup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!((_a = this.config) === null || _a === void 0 ? void 0 : _a.actionId) || this.isWarmupInProgress || this.scriptCache) {
+                return;
+            }
+            this.isWarmupInProgress = true;
+            try {
+                this.scriptCache = yield this.fetchScript();
+            }
+            catch (_b) {
+                /* empty */
+            }
+            finally {
+                this.isWarmupInProgress = false;
+            }
+        });
+    }
+    buildScriptUrl(actionId) {
+        var _a, _b;
+        const baseUrl = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.scriptUrl) || "https://js.deflect.bot/main.js";
+        if ((_b = this.config) === null || _b === void 0 ? void 0 : _b.scriptUrl) {
+            return baseUrl;
+        }
+        const nonce = Date.now().toString();
+        return `${baseUrl}?action_id=${actionId}&_=${nonce}`;
+    }
+    fetchScript() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!((_a = this.config) === null || _a === void 0 ? void 0 : _a.actionId)) {
+                throw new Error("actionId is required");
+            }
+            const url = this.buildScriptUrl(this.config.actionId);
+            const response = yield fetch(url, { cache: "no-store" });
+            if (!response.ok) {
+                throw new Error(`Failed to fetch script: ${response.status}`);
+            }
+            return {
+                content: yield response.text(),
+                sessionId: response.headers.get("session_id") || undefined,
+            };
+        });
+    }
+    executeScript(script) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (script.sessionId && typeof window !== "undefined") {
+                window.Deflect.sessionId = script.sessionId;
+            }
+            const readyPromise = this.createReadyPromise();
+            const blobUrl = this.createScriptBlob(script.content);
+            const scriptElement = yield this.loadScriptElement(blobUrl);
+            try {
+                yield readyPromise;
+                const token = yield this.getTokenFromScript();
+                this.prefetchNextScript();
+                return token;
+            }
+            finally {
+                this.cleanup(blobUrl, scriptElement);
+            }
+        });
+    }
+    prefetchNextScript() {
+        this.tryWarmup().catch(() => { });
+    }
+    createReadyPromise() {
+        return new Promise((resolve) => {
+            if (typeof window !== "undefined") {
+                window.Deflect.ready = {
+                    promise: new Promise((innerResolve) => {
+                        window.Deflect.ready.resolve = innerResolve;
+                    }),
+                    resolve: () => resolve(),
+                };
+            }
+        });
+    }
+    createScriptBlob(content) {
+        const blob = new Blob([content], { type: "text/javascript" });
+        return URL.createObjectURL(blob);
+    }
+    loadScriptElement(blobUrl) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return new Promise((resolve, reject) => {
+                const script = document.createElement("script");
+                script.type = "module";
+                script.src = blobUrl;
+                script.onload = () => resolve(script);
+                script.onerror = () => reject(new Error("Script failed to load"));
+                document.head.appendChild(script);
+            });
+        });
+    }
+    getTokenFromScript() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (typeof window === "undefined" ||
+                typeof ((_a = window.Deflect) === null || _a === void 0 ? void 0 : _a.getToken) !== "function") {
+                throw new Error("Script did not load properly - getToken not available");
+            }
+            try {
+                return yield window.Deflect.getToken();
+            }
+            catch (error) {
+                throw new Error(`Script execution failed: ${error}`);
+            }
+        });
+    }
+    cleanup(blobUrl, scriptElement) {
+        var _a;
+        URL.revokeObjectURL(blobUrl);
+        scriptElement.remove();
+        if (typeof window !== "undefined" && ((_a = window.Deflect) === null || _a === void 0 ? void 0 : _a.getToken)) {
+            delete window.Deflect.getToken;
+        }
+    }
+    configure(params) {
+        var _a;
+        if (!((_a = params.actionId) === null || _a === void 0 ? void 0 : _a.trim())) {
+            throw new Error("actionId is required and cannot be empty");
+        }
+        this.config = Object.assign({}, params);
+        if (typeof window !== "undefined") {
+            window.Deflect.actionId = params.actionId;
+        }
+        this.tryWarmup();
+    }
+    // Deprecated name kept for backward compatibility
+    solveChallenge() {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.getToken();
+        });
+    }
+    getToken() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!((_a = this.config) === null || _a === void 0 ? void 0 : _a.actionId)) {
+                throw new Error("Must call configure() before solveChallenge()");
+            }
+            let script;
+            if (this.scriptCache && !this.isWarmupInProgress) {
+                script = this.scriptCache;
+                this.scriptCache = null;
+            }
+            else {
+                script = yield this.fetchScript();
+            }
+            return this.executeScript(script);
+        });
+    }
+    warmup() {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            if (!((_a = this.config) === null || _a === void 0 ? void 0 : _a.actionId)) {
+                return false;
+            }
+            try {
+                yield this.tryWarmup();
+                return this.scriptCache !== null;
+            }
+            catch (_b) {
+                return false;
+            }
+        });
+    }
+    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.
+     */
+    injectToken(event) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!event || !event.target || !(event.target instanceof HTMLFormElement)) {
+                throw new Error("injectToken: must be called from a form submit event");
+            }
+            event.preventDefault();
+            const form = event.target;
+            const token = yield this.getToken();
+            Array.from(form.querySelectorAll('input[name="deflect_token"]')).forEach((el) => el.remove());
+            const hidden = document.createElement("input");
+            hidden.type = "hidden";
+            hidden.name = "deflect_token";
+            hidden.value = token;
+            form.appendChild(hidden);
+            form.submit();
+            return false;
+        });
+    }
+}
+export default new Deflect();

package/dist/types/global.d.ts

@@ -0,0 +1,7 @@
+import DeflectInstance from "./index";
+declare global {
+    interface Window {
+        Deflect: any;
+    }
+}
+export default DeflectInstance;

package/dist/types/index.d.ts

@@ -1,17 +1,35 @@
-interface DeflectConfig {
-    actionId: string;
-    extraArgs?: {
-        [key: string]: string;
-    };
-}
-declare class Deflect {
-    private _prefetchedScriptText;
-    private _hasUsedPrefetch;
-    constructor();
-    private _warmupScript;
-    private setupReady;
-    configure(params: DeflectConfig): void;
-    solveChallenge(): Promise<string>;
-}
-declare const _default: Deflect;
-export default _default;
+interface DeflectConfig {
+    actionId: string;
+    scriptUrl?: string;
+}
+declare class Deflect {
+    private config;
+    private scriptCache;
+    private isWarmupInProgress;
+    constructor();
+    private initializeGlobalState;
+    private setupAutomaticWarmup;
+    private tryWarmup;
+    private buildScriptUrl;
+    private fetchScript;
+    private executeScript;
+    private prefetchNextScript;
+    private createReadyPromise;
+    private createScriptBlob;
+    private loadScriptElement;
+    private getTokenFromScript;
+    private cleanup;
+    configure(params: DeflectConfig): void;
+    solveChallenge(): Promise<string>;
+    getToken(): Promise<string>;
+    warmup(): Promise<boolean>;
+    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.
+     */
+    injectToken(event: SubmitEvent): Promise<false>;
+}
+declare const _default: Deflect;
+export default _default;

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@deflectbot/deflect-sdk",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "SDK for deflect.bot - Use it for seamless captcha integration on any website.",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc && npm run build:global",
+    "build:global": "esbuild src/global.ts --bundle --format=iife --global-name=Deflect --minify --outfile=dist/deflect.global.min.js"
   },
   "author": "Deflect",
   "license": "MIT",
@@ -14,12 +15,11 @@
     "eslint": "^9.22.0",
     "globals": "^16.0.0",
     "typescript": "^5.7.3",
-    "typescript-eslint": "^8.27.0"
+    "typescript-eslint": "^8.27.0",
+    "esbuild": "^0.23.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "dependencies": {
-    "@deflectbot/deflect-sdk": "file:"
-  }
+  "dependencies": {}
 }

package/src/global.ts

@@ -0,0 +1,18 @@
+// Re-export the default instance while also assigning it to window.Deflect for non-module usage.
+import DeflectInstance from "./index";
+
+// Ensure side effects (constructor) already ran on import.
+// Attach to window for classic script tag usage.
+declare global {
+  interface Window {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK attaches dynamic shape at runtime
+    Deflect: any;
+  }
+}
+
+if (typeof window !== "undefined") {
+  // Avoid overwriting if a user already attached something custom.
+  window.Deflect = DeflectInstance;
+}
+
+export default DeflectInstance;

package/src/index.ts

@@ -1,147 +1,237 @@
 interface DeflectConfig {
   actionId: string;
   scriptUrl?: string;
-  extraArgs?: { [key: string]: string };
+}
+
+interface DeflectScript {
+  sessionId?: string;
+  content: string;
 }
 
 class Deflect {
-  private _prefetchedScriptText: string | null = null;
-  private _hasUsedPrefetch = false;
-  private _customScriptUrl: string | null = null;
+  private config: DeflectConfig | null = null;
+  private scriptCache: DeflectScript | null = null;
+  private isWarmupInProgress = false;
 
   constructor() {
+    this.initializeGlobalState();
+    this.setupAutomaticWarmup();
+  }
+
+  private initializeGlobalState(): void {
+    if (typeof window === "undefined") return;
     window.Deflect = window.Deflect || {};
-    window.Deflect.extraArgs = window.Deflect.extraArgs || {};
+  }
 
-    if (typeof window !== "undefined") {
-      window.addEventListener("load", () => {
-        setTimeout(() => {
-          this._warmupScript();
-        }, 500);
-      });
+  private setupAutomaticWarmup(): void {
+    if (typeof window === "undefined") return;
+
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", () => this.tryWarmup());
+    } else {
+      setTimeout(() => this.tryWarmup(), 100);
     }
   }
 
-  private _getScriptUrl(): string {
-    const nonce = Date.now().toString();
-    if (this._customScriptUrl) {
-      const separator = this._customScriptUrl.includes("?") ? "&" : "?";
-      return `${this._customScriptUrl}${separator}action_id=${window.Deflect.actionId}&_=${nonce}`;
+  private async tryWarmup(): Promise<void> {
+    if (!this.config?.actionId || this.isWarmupInProgress || this.scriptCache) {
+      return;
     }
-    return `https://js.deflect.bot/main.js?action_id=${window.Deflect.actionId}&_=${nonce}`;
-  }
 
-  private _warmupScript(): void {
-    if (!window.Deflect.actionId) return;
+    this.isWarmupInProgress = true;
 
-    const scriptUrl = this._getScriptUrl();
-    fetch(scriptUrl, { cache: "no-store" })
-      .then(async (res) => {
-        if (!res.ok) return;
-        this._prefetchedScriptText = await res.text();
-      })
-      .catch(() => {});
+    try {
+      this.scriptCache = await this.fetchScript();
+    } catch {
+      /* empty */
+    } finally {
+      this.isWarmupInProgress = false;
+    }
   }
 
-  private _refetchScript(): void {
-    this._hasUsedPrefetch = false;
-    this._prefetchedScriptText = null;
+  private buildScriptUrl(actionId: string): string {
+    const baseUrl = this.config?.scriptUrl || "https://js.deflect.bot/main.js";
 
-    setTimeout(() => {
-      this._warmupScript();
-    }, 100);
-  }
+    if (this.config?.scriptUrl) {
+      return baseUrl;
+    }
 
-  private setupReady(): void {
-    let resolveFn: () => void;
-    const promise = new Promise<void>((resolve) => {
-      resolveFn = resolve;
-    });
-    window.Deflect.ready = {
-      promise,
-      resolve: () => resolveFn(),
-    };
+    const nonce = Date.now().toString();
+    return `${baseUrl}?action_id=${actionId}&_=${nonce}`;
   }
 
-  configure(params: DeflectConfig): void {
-    if (!params.actionId) {
-      throw new Error("actionId is required in configuration");
+  private async fetchScript(): Promise<DeflectScript> {
+    if (!this.config?.actionId) {
+      throw new Error("actionId is required");
     }
-    window.Deflect.actionId = params.actionId;
 
-    if (params.scriptUrl) {
-      this._customScriptUrl = params.scriptUrl;
+    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}`);
     }
+
+    return {
+      content: await response.text(),
+      sessionId: response.headers.get("session_id") || undefined,
+    };
   }
 
-  async solveChallenge(): Promise<string> {
-    if (!window.Deflect.actionId) {
-      throw new Error("actionId is missing in configuration");
+  private async executeScript(script: DeflectScript): Promise<string> {
+    if (script.sessionId && typeof window !== "undefined") {
+      window.Deflect.sessionId = script.sessionId;
     }
 
-    this.setupReady();
+    const readyPromise = this.createReadyPromise();
 
-    let scriptText: string;
-    let sessionId: string | null = null;
+    const blobUrl = this.createScriptBlob(script.content);
+    const scriptElement = await this.loadScriptElement(blobUrl);
 
-    if (this._prefetchedScriptText && !this._hasUsedPrefetch) {
-      scriptText = this._prefetchedScriptText;
-      this._hasUsedPrefetch = true;
-    } else {
-      const scriptUrl = this._getScriptUrl();
-      const response = await fetch(scriptUrl, { cache: "no-store" });
+    try {
+      await readyPromise;
 
-      if (!response.ok) {
-        throw new Error("Failed to fetch the Deflect script");
-      }
+      const token = await this.getTokenFromScript();
 
-      sessionId = response.headers.get("session_id");
-      scriptText = await response.text();
-    }
+      this.prefetchNextScript();
 
-    if (sessionId) {
-      window.Deflect.sessionId = sessionId;
+      return token;
+    } finally {
+      this.cleanup(blobUrl, scriptElement);
     }
+  }
 
-    const blob = new Blob([scriptText], { type: "text/javascript" });
-    const blobUrl = URL.createObjectURL(blob);
+  private prefetchNextScript(): void {
+    this.tryWarmup().catch(() => {});
+  }
 
-    const scriptEl = document.createElement("script");
-    scriptEl.type = "module";
-    scriptEl.src = blobUrl;
+  private createReadyPromise(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      if (typeof window !== "undefined") {
+        window.Deflect.ready = {
+          promise: new Promise<void>((innerResolve) => {
+            window.Deflect.ready.resolve = innerResolve;
+          }),
+          resolve: () => resolve(),
+        };
+      }
+    });
+  }
 
-    document.head.appendChild(scriptEl);
+  private createScriptBlob(content: string): string {
+    const blob = new Blob([content], { type: "text/javascript" });
+    return URL.createObjectURL(blob);
+  }
 
-    await new Promise<void>((resolve, reject) => {
-      scriptEl.onload = () => resolve();
-      scriptEl.onerror = () => reject("Failed to load the Deflect script");
-    });
+  private async loadScriptElement(blobUrl: string): Promise<HTMLScriptElement> {
+    return new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.type = "module";
+      script.src = blobUrl;
 
-    await window.Deflect.ready?.promise;
+      script.onload = () => resolve(script);
+      script.onerror = () => reject(new Error("Script failed to load"));
 
+      document.head.appendChild(script);
+    });
+  }
+
+  private async getTokenFromScript(): Promise<string> {
     if (
-      typeof window.Deflect === "undefined" ||
-      typeof window.Deflect.getToken !== "function"
+      typeof window === "undefined" ||
+      typeof window.Deflect?.getToken !== "function"
     ) {
-      throw new Error("Deflect script did not load properly");
+      throw new Error("Script did not load properly - getToken not available");
     }
 
-    let token: string;
-
     try {
-      token = await window.Deflect.getToken();
+      return await window.Deflect.getToken();
     } catch (error) {
-      throw new Error(`Deflect script execution failed: ${error}`);
+      throw new Error(`Script execution failed: ${error}`);
     }
+  }
 
-    this._refetchScript();
-
+  private cleanup(blobUrl: string, scriptElement: HTMLScriptElement): void {
     URL.revokeObjectURL(blobUrl);
-    scriptEl.remove();
+    scriptElement.remove();
+
+    if (typeof window !== "undefined" && window.Deflect?.getToken) {
+      delete window.Deflect.getToken;
+    }
+  }
 
-    delete window.Deflect.getToken;
+  public configure(params: DeflectConfig): void {
+    if (!params.actionId?.trim()) {
+      throw new Error("actionId is required and cannot be empty");
+    }
+    this.config = { ...params };
+    if (typeof window !== "undefined") {
+      window.Deflect.actionId = params.actionId;
+    }
+    this.tryWarmup();
+  }
+
+  // Deprecated name kept for backward compatibility
+  public async solveChallenge(): Promise<string> {
+    return this.getToken();
+  }
+
+  public async getToken(): Promise<string> {
+    if (!this.config?.actionId) {
+      throw new Error("Must call configure() before solveChallenge()");
+    }
 
-    return token;
+    let script: DeflectScript;
+
+    if (this.scriptCache && !this.isWarmupInProgress) {
+      script = this.scriptCache;
+      this.scriptCache = null;
+    } else {
+      script = await this.fetchScript();
+    }
+
+    return this.executeScript(script);
+  }
+
+  public async warmup(): Promise<boolean> {
+    if (!this.config?.actionId) {
+      return false;
+    }
+
+    try {
+      await this.tryWarmup();
+      return this.scriptCache !== null;
+    } catch {
+      return false;
+    }
+  }
+
+  public clearCache(): void {
+    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.
+   */
+  public async injectToken(event: SubmitEvent): Promise<false> {
+    if (!event || !event.target || !(event.target instanceof HTMLFormElement)) {
+      throw new Error("injectToken: must be called from a form submit event");
+    }
+    event.preventDefault();
+    const form = event.target;
+    const token = await this.getToken();
+    Array.from(form.querySelectorAll('input[name="deflect_token"]')).forEach(
+      (el) => el.remove()
+    );
+    const hidden = document.createElement("input");
+    hidden.type = "hidden";
+    hidden.name = "deflect_token";
+    hidden.value = token;
+    form.appendChild(hidden);
+    form.submit();
+    return false;
   }
 }
 

package/src/types/window.d.ts

@@ -1,3 +1,6 @@
+// Global window augmentation for Deflect SDK.
+// Using 'any' here keeps backward compatibility and avoids circular type issues.
 interface Window {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK attaches dynamic shape at runtime
   Deflect: any;
 }