From 8d870c031b4af6a9f635e8615336d3a2afc446f8 Mon Sep 17 00:00:00 2001
From: Teyler Halama <teyler@polleverywhere.com>
Date: Wed, 30 Jul 2025 12:14:43 -0600
Subject: [PATCH 1/2] Add screen_hint to UserManagement

As a solution to build "Sign-Up" paths in Rails applications, this adds
the `screen_hint` to the UserManagement.authorization_url flow. This
appears to be a valid api in NodeJS already (https://workos.com/docs/reference/authkit/authentication/get-authorization-url),
this simply adds it to the Ruby Gem.

Unit tests have been added as well.
---
 lib/workos/user_management.rb           |  4 +++
 spec/lib/workos/user_management_spec.rb | 35 +++++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/lib/workos/user_management.rb b/lib/workos/user_management.rb
index 9b30e6d2..8084e0e1 100644
--- a/lib/workos/user_management.rb
+++ b/lib/workos/user_management.rb
@@ -69,6 +69,8 @@ def load_sealed_session(client_id:, session_data:, cookie_password:)
       #  that is preserved and available to the client in the response.
       # @param [String] login_hint Can be used to pre-fill the username/email address
       # field of the IdP sign-in page for the user, if you know their username ahead of time.
+      # @param [String] screen_hint Specify which AuthKit screen users should land on upon redirection
+      # (Only applicable when provider is 'authkit').
       # @param [String] domain_hint Can be used to pre-fill the domain field when
       # initiating authentication with Microsoft OAuth, or with a GoogleSAML connection type.
       # @param [Array<String>] provider_scopes An array of additional OAuth scopes to request from the provider.
@@ -94,6 +96,7 @@ def authorization_url(
         client_id: nil,
         domain_hint: nil,
         login_hint: nil,
+        screen_hint: nil,
         provider: nil,
         connection_id: nil,
         organization_id: nil,
@@ -114,6 +117,7 @@ def authorization_url(
           state: state,
           domain_hint: domain_hint,
           login_hint: login_hint,
+          screen_hint: screen_hint,
           provider: provider,
           connection_id: connection_id,
           organization_id: organization_id,
diff --git a/spec/lib/workos/user_management_spec.rb b/spec/lib/workos/user_management_spec.rb
index 5b595563..1192e936 100644
--- a/spec/lib/workos/user_management_spec.rb
+++ b/spec/lib/workos/user_management_spec.rb
@@ -202,6 +202,41 @@
       end
     end
 
+    context 'with a screen hint' do
+      let(:args) do
+        {
+          provider: 'authkit',
+          screen_hint: 'sign_up',
+          client_id: 'workos-proj-123',
+          redirect_uri: 'foo.com/auth/callback',
+          state: {
+            next_page: '/dashboard/edit',
+          }.to_s,
+        }
+      end
+      it 'returns a valid URL' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url)).to be_a URI
+      end
+
+      it 'returns the expected hostname' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).host).to eq(WorkOS.config.api_hostname)
+      end
+
+      it 'returns the expected query string' do
+        authorization_url = described_class.authorization_url(**args)
+
+        expect(URI.parse(authorization_url).query).to eq(
+          'client_id=workos-proj-123&redirect_uri=foo.com%2Fauth%2Fcallback' \
+          '&response_type=code&state=%7B%3Anext_page%3D%3E%22%2Fdashboard%2F' \
+          'edit%22%7D&screen_hint=sign_up&provider=authkit',
+        )
+      end
+    end
+
     context 'with neither connection_id, organization_id or provider' do
       let(:args) do
         {

From 5277fbf436209f2248dce0346d39d1fe40d63078 Mon Sep 17 00:00:00 2001
From: Teyler Halama <teyler@polleverywhere.com>
Date: Wed, 30 Jul 2025 12:22:31 -0600
Subject: [PATCH 2/2] Update VCR to resolve global_hook failure

From research, this is a pretty well known issue in vcr 5 that has been
resolved in vcr 6. Running bundle exec rspec still passes with this
update.

Resolves .rbenv/versions/3.1.4/lib/ruby/gems/3.1.0/gems/vcr-5.0.0/lib/vcr/library_hooks/webmock.rb:36:in
`block in global_hook_disabled_requests': wrong number of arguments
(given 1, expected 0) (ArgumentError).
---
 Gemfile.lock   | 7 +++----
 workos.gemspec | 2 +-
 2 files changed, 4 insertions(+), 5 deletions(-)

diff --git a/Gemfile.lock b/Gemfile.lock
index ce1cfa39..b5c57b1d 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -32,7 +32,6 @@ GEM
     rainbow (3.1.1)
     regexp_parser (2.10.0)
     rexml (3.4.1)
-      strscan
     rspec (3.9.0)
       rspec-core (~> 3.9.0)
       rspec-expectations (~> 3.9.0)
@@ -59,11 +58,11 @@ GEM
     rubocop-ast (1.37.0)
       parser (>= 3.3.1.0)
     ruby-progressbar (1.13.0)
-    strscan (3.1.0)
     unicode-display_width (3.1.4)
       unicode-emoji (~> 4.0, >= 4.0.4)
     unicode-emoji (4.0.4)
-    vcr (5.0.0)
+    vcr (6.3.1)
+      base64
     webmock (3.23.0)
       addressable (>= 2.8.0)
       crack (>= 0.3.2)
@@ -76,7 +75,7 @@ DEPENDENCIES
   bundler (>= 2.0.1)
   rspec (~> 3.9.0)
   rubocop (~> 1.71)
-  vcr (~> 5.0.0)
+  vcr (~> 6.0)
   webmock
   workos!
 
diff --git a/workos.gemspec b/workos.gemspec
index 20b5f427..b9f827a5 100644
--- a/workos.gemspec
+++ b/workos.gemspec
@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '>= 2.0.1'
   spec.add_development_dependency 'rspec', '~> 3.9.0'
   spec.add_development_dependency 'rubocop', '~> 1.71'
-  spec.add_development_dependency 'vcr', '~> 5.0.0'
+  spec.add_development_dependency 'vcr', '~> 6.0'
   spec.add_development_dependency 'webmock'
 
   spec.required_ruby_version = '>= 3.1'