Load @castleio/castle-js UMD from npm and support 2.x and 3.x (#85)

* Load @castleio/castle-js from /vendor/castle-js and support 2.x and 3.x.

* Load castle.umd.js and seed window.Castle for the 3.x UMD global.

* Drop app_id. Configure with api_secret and publishable_key only.

* Document public/vendor copy for castle-js UMD and add local mise pins.

* Let castle_javascript_tag take a hosted UMD src instead of serving node_modules.

* Load castle.umd.js by default from /vendor/castle-js.

Author: bartes

.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.10

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased][main]
 
+- Drop `cdn.castle.io`; load `castle.umd.js` from `/vendor/castle-js` via `castle_javascript_tag`
+- Seed `window.Castle` before a UMD script so 3.x (`name: @castleio/castle-js`) attaches to the same global
+- Support `@castleio/castle-js` 2.x (`injectTokenOnSubmit` / `createRequestToken`) and 3.x (`configure({ pk })` + `createRequestToken`)
+- Add `publishable_key` configuration and drop `app_id`
+
 ## [0.6.0] - 2026-05-25
 - Add support for Rails 8.1
 - Add support for Devise 5

README.md

@@ -20,12 +20,12 @@ Include `castle_devise` in your Gemfile:
 gem 'castle_devise'
 ```
 
-Create `config/initializers/castle_devise.rb` and fill in your API secret and APP_ID from the [Castle Dashboard](https://dashboard.castle.io/settings/general)
+Create `config/initializers/castle_devise.rb` and fill in your API secret and publishable key from the [Castle Dashboard](https://dashboard.castle.io/settings/general)
 
 ```ruby
 CastleDevise.configure do |config|
   config.api_secret = ENV.fetch('CASTLE_API_SECRET')
-  config.app_id = ENV.fetch('CASTLE_APP_ID')
+  config.publishable_key = ENV.fetch('CASTLE_PK')
 
   # When monitoring mode is enabled, CastleDevise sends
   # requests to Castle but it doesn't act on the "deny" verdicts.
@@ -60,14 +60,20 @@ en:
 
 (See [devise.en.yml in our specs](spec/dummy_app/config/locales/devise.en.yml#L40))
 
-#### Further steps if you're not using Webpacker
+#### Browser SDK
 
-Include Castle's c.js script in the head section of your layout:
+Install [`@castleio/castle-js`](https://docs.castle.io/docs/sdk-browser) and serve the npm `dist` directory at `/vendor/castle-js` (keep `castle.umd.js` and the worker files together):
 
 ```ruby
 <%= castle_javascript_tag %>
 ```
 
+That loads `/vendor/castle-js/castle.umd.js` and seeds `window.Castle` before the script runs (3.x UMD is named `@castleio/castle-js`). Pass `src:` for a different UMD URL:
+
+```ruby
+<%= castle_javascript_tag(src: "/assets/castle.umd.js") %>
+```
+
 Add the following tag to the the `<form>` tag in both `devise/registrations/new.html.erb` and `devise/sessions/new.html.erb` (if you haven't generated them yet, run `rails generate devise:views`):
 
 ```ruby
@@ -76,26 +82,9 @@ Add the following tag to the the `<form>` tag in both `devise/registrations/new.
 <% end %>
 ```
 
-You're set! Now verify that everything works by logging in to your application as any user. You should be able to see that User on the [Castle Users Page](https://dashboard.castle.io/users)
+`castle_on_form_submit` uses 2.x `injectTokenOnSubmit` when present, and 2.x/3.x `createRequestToken` otherwise.
 
-
-#### Further steps if you're using Webpacker
-
-Add `@castleio/castle-js` to your package.json file:
-
-```
-yarn add @castleio/castle-js
-```
-
-configure castle in your application pack:
-
-```javascript
-import * as Castle from '@castleio/castle-js'
-
-Castle.configure(YOUR_APPLICATION_ID);
-```
-
-for advanced configuration follow [the readme](https://www.npmjs.com/package/@castleio/castle-js#configuration)
+You're set! Now verify that everything works by logging in to your application as any user. You should be able to see that User on the [Castle Users Page](https://dashboard.castle.io/users)
 
 ## How-Tos
 
@@ -213,6 +202,7 @@ end
 ### Setup
 
 ```bash
+mise install
 bundle install
 ```
 
@@ -221,9 +211,11 @@ bundle install
 Most of the specs should pass just by running the following command:
 
 ```bash
-bundle exec rake
+mise run test
 ```
 
+or `bundle exec rake`.
+
 We also have a few VCR tests that will periodically rebuild the cassettes just to make sure that the integration with Castle API is working.
 For those, you need to run your specs with a proper Castle API Secret:
 

lib/castle_devise/configuration.rb

@@ -12,9 +12,9 @@ class Configuration
     #   @return [String] Your API secret
     attr_accessor :api_secret
 
-    # @!attribute app_id
-    #   @return [String] Your Castle App ID
-    attr_accessor :app_id
+    # @!attribute publishable_key
+    #   @return [String] Publishable key passed to @castleio/castle-js as { pk: }
+    attr_accessor :publishable_key
 
     # @!attribute monitoring_mode
     #   When CastleDevise is in monitoring mode, it sends requests to Castle

lib/castle_devise/helpers/castle_devise.js

@@ -0,0 +1,48 @@
+(function () {
+  var CastleGlobal = window.Castle || window["@castleio/castle-js"];
+  var pk = __CASTLE_DEVISE_PK__;
+  if (!window.__castleDevise && CastleGlobal && typeof CastleGlobal.configure === "function") {
+    window.__castleDevise = CastleGlobal.configure({ pk: pk });
+  }
+
+  window.castleDeviseOnFormSubmit = function (event) {
+    var client = window.__castleDevise || window.Castle || window["@castleio/castle-js"];
+    // 2.x exposes injectTokenOnSubmit; 3.x only has createRequestToken on the configured instance.
+    if (client && typeof client.injectTokenOnSubmit === "function") {
+      return client.injectTokenOnSubmit(event);
+    }
+    if (!client || typeof client.createRequestToken !== "function") {
+      event.preventDefault();
+      return false;
+    }
+    var form = event.target;
+    if (form.getAttribute("data-castle-submitting") === "1") {
+      return true;
+    }
+    event.preventDefault();
+    client.createRequestToken().then(function (token) {
+      var field = form.querySelector('input[name="castle_request_token"]');
+      if (!field) {
+        field = document.createElement("input");
+        field.type = "hidden";
+        field.name = "castle_request_token";
+        form.appendChild(field);
+      }
+      field.value = token || "";
+      form.setAttribute("data-castle-submitting", "1");
+      if (typeof form.requestSubmit === "function") {
+        form.requestSubmit();
+      } else {
+        form.submit();
+      }
+    }).catch(function () {
+      form.setAttribute("data-castle-submitting", "1");
+      if (typeof form.requestSubmit === "function") {
+        form.requestSubmit();
+      } else {
+        form.submit();
+      }
+    });
+    return false;
+  };
+})();

lib/castle_devise/helpers/castle_helper.rb

@@ -4,13 +4,23 @@ module CastleDevise
   module Helpers
     # Methods defined here will be available in all your views.
     module CastleHelper
-      # Creates a <script> tag that includes our c.js script from a CDN.
-      # You have to make sure that your app_id is valid, otherwise the script won't work.
-      #
-      # You shouldn't call this method if you bundle our c.js script with your other
-      # JS packages.
+      BOOTSTRAP_JS = File.read(File.expand_path("castle_devise.js", __dir__)).freeze
+      # 3.x UMD is named @castleio/castle-js, so seed module.exports as window.Castle before the script tag.
+      UMD_SHIM = <<~JS
+        if (!window.Castle) {
+          window.exports = window.exports || {};
+          window.module = window.module || { exports: window.exports };
+          window.Castle = window.module.exports;
+        }
+      JS
+
+      DEFAULT_UMD_SRC = "/vendor/castle-js/castle.umd.js"
+
+      # Loads castle.umd.js and configures it with { pk: }. Pass src: to use a
+      # different UMD URL, or src: nil when the host app already loaded the SDK.
       #
-      # You should put this in the <head> section of your page:
+      # @param src [String, nil] URL or path of castle.umd.js (keep workers in the same directory)
+      # @return [String]
       #
       # @example
       #   # app/views/layouts/application.html.erb
@@ -21,14 +31,18 @@ module CastleHelper
       #   <title>Your app title</title>
       #
       #   <!-- the rest of your layout -->
-      def castle_javascript_tag
-        javascript_include_tag(
-          "https://cdn.castle.io/v2/castle.js?#{CastleDevise.configuration.app_id}"
-        )
+      def castle_javascript_tag(src: DEFAULT_UMD_SRC)
+        parts = []
+        if src
+          parts << javascript_tag(UMD_SHIM)
+          parts << javascript_include_tag(src)
+        end
+        parts << javascript_tag(castle_js_bootstrap)
+        safe_join(parts)
       end
 
-      # Puts an inline <script> tag that includes a "castle_devise_token" field
-      # within the current form.
+      # onsubmit handler that mints castle_request_token via 2.x injectTokenOnSubmit
+      # or 2.x/3.x createRequestToken.
       #
       # @example
       #   <%= form_for(resource, as: resource_name, url: sessions_path(resource_name), html: { onsubmit: castle_on_form_submit }) do |f| %>
@@ -38,7 +52,13 @@ def castle_javascript_tag
       #
       # @return [String]
       def castle_on_form_submit
-        "typeof(_castle)=='undefined'?event.preventDefault():_castle('onFormSubmit', event)"
+        "castleDeviseOnFormSubmit(event)"
+      end
+
+      private
+
+      def castle_js_bootstrap
+        BOOTSTRAP_JS.sub("__CASTLE_DEVISE_PK__", CastleDevise.configuration.publishable_key.to_json)
       end
     end
   end

mise.toml

@@ -0,0 +1,11 @@
+[tasks.install]
+description = "Install Ruby gems"
+run = "bundle install"
+
+[tasks.test]
+description = "Run the RSpec suite"
+run = "bundle exec rspec"
+
+[tasks.lint]
+description = "Run Standard Ruby"
+run = "bundle exec standardrb"

spec/castle_devise/helpers/castle_helper_spec.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+RSpec.describe CastleDevise::Helpers::CastleHelper, type: :helper do
+  describe "#castle_javascript_tag" do
+    before do
+      CastleDevise.configuration.publishable_key = "pk_test"
+    end
+
+    after do
+      CastleDevise.configuration.publishable_key = "pk_spec"
+    end
+
+    it "loads castle.umd.js from /vendor/castle-js" do
+      html = helper.castle_javascript_tag
+
+      expect(html).to include("/vendor/castle-js/castle.umd.js")
+      expect(html).to include("window.module")
+      expect(html).to include("window.Castle")
+      expect(html).to include("@castleio/castle-js")
+      expect(html).to include(".configure")
+      expect(html).to include("pk_test")
+      expect(html).to include("castleDeviseOnFormSubmit")
+      expect(html).not_to include("cdn.castle.io")
+      expect(html).not_to include("castle.browser.js")
+    end
+
+    it "loads a custom UMD src when given" do
+      html = helper.castle_javascript_tag(src: "/assets/castle.umd.js")
+
+      expect(html).to include("/assets/castle.umd.js")
+      expect(html).not_to include("/vendor/castle-js/castle.umd.js")
+      expect(html).to include("window.module")
+      expect(html).not_to include("cdn.castle.io")
+    end
+
+    it "skips the script tag when src is nil" do
+      html = helper.castle_javascript_tag(src: nil)
+
+      expect(html).to include(".configure")
+      expect(html).to include("pk_test")
+      expect(html).not_to include("castle.umd.js")
+      expect(html).not_to include("cdn.castle.io")
+    end
+  end
+
+  describe "#castle_on_form_submit" do
+    it "delegates to the shared submit helper" do
+      expect(helper.castle_on_form_submit).to eq("castleDeviseOnFormSubmit(event)")
+    end
+  end
+end

spec/support/init_castle_device.rb

@@ -6,6 +6,6 @@
   # no real secret is needed, so a fixed dummy value keeps the specs valid
   # everywhere (including Dependabot runs that don't get repo secrets).
   config.api_secret = "fake-secret-123"
-  config.app_id = "123456789"
+  config.publishable_key = "pk_spec"
   config.logger = Logger.new($stdout)
 end