Add get widget token API support

lib/workos.rb

@@ -81,6 +81,7 @@ def self.key
   autoload :VerifyChallenge, 'workos/verify_challenge'
   autoload :Webhook, 'workos/webhook'
   autoload :Webhooks, 'workos/webhooks'
+  autoload :Widgets, 'workos/widgets'
 
   # Errors
   autoload :APIError, 'workos/errors'

lib/workos/types.rb

@@ -7,5 +7,6 @@ module Types
     autoload :Intent, 'workos/types/intent'
     autoload :ListStruct, 'workos/types/list_struct'
     autoload :PasswordlessSessionStruct, 'workos/types/passwordless_session_struct'
+    autoload :WidgetScope, 'workos/types/widget_scope'
   end
 end

lib/workos/types/widget_scope.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module WorkOS
+  module Types
+    # The WidgetScope constants are declarations of a fixed set of values for
+    # scopes while generating a widget token.
+    module WidgetScope
+      USERS_TABLE_MANAGE = 'widgets:users-table:manage'
+
+      ALL = [USERS_TABLE_MANAGE].freeze
+    end
+  end
+end

lib/workos/widgets.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'net/http'
+
+module WorkOS
+  # The Widgets module provides resource methods for working with the Widgets APIs
+  module Widgets
+    class << self
+      include Client
+
+      WIDGET_SCOPES = WorkOS::Types::WidgetScope::ALL
+
+      # Generate a widget token.
+      #
+      # @param [String] organization_id The ID of the organization to generate the token for.
+      # @param [String] user_id The ID of the user to generate the token for.
+      # @param [WidgetScope[]] The scopes to generate the token for.
+      def get_token(organization_id:, user_id:, scopes:)
+        validate_scopes(scopes)
+
+        request = post_request(
+          auth: true,
+          body: {
+            organization_id: organization_id,
+            user_id: user_id,
+            scopes: scopes,
+          },
+          path: '/widgets/token',
+        )
+
+        response = execute_request(request: request)
+
+        JSON.parse(response.body)['token']
+      end
+
+      private
+
+      def validate_scopes(scopes)
+        return if scopes.all? { |scope| WIDGET_SCOPES.include?(scope) }
+
+        raise ArgumentError, 'scopes contains an invalid value.' \
+        " Every item in `scopes` must be in #{WIDGET_SCOPES}"
+      end
+    end
+  end
+end

spec/lib/workos/widgets_spec.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+describe WorkOS::Widgets do
+  it_behaves_like 'client'
+
+  describe '.get_token' do
+    let(:organization_id) { 'org_01JCP9G67MNAH0KC4B72XZ67M7' }
+    let(:user_id) { 'user_01JCP9H4SHS4N3J6XTKDT7JNPE' }
+
+    describe 'with a valid organization_id and user_id and scopes' do
+      it 'returns a widget token' do
+        VCR.use_cassette 'widgets/get_token' do
+          token = described_class.get_token(
+            organization_id: organization_id,
+            user_id: user_id,
+            scopes: ['widgets:users-table:manage'],
+          )
+
+          expect(token).to start_with('eyJhbGciOiJSUzI1NiIsImtpZ')
+        end
+      end
+    end
+
+    describe 'with an invalid organization_id' do
+      it 'raises an error' do
+        VCR.use_cassette 'widgets/get_token_invalid_organization_id' do
+          expect do
+            described_class.get_token(
+              organization_id: 'bogus-id',
+              user_id: user_id,
+              scopes: ['widgets:users-table:manage'],
+            )
+          end.to raise_error(
+            WorkOS::NotFoundError,
+            /Organization not found: 'bogus-id'/,
+          )
+        end
+      end
+    end
+
+    describe 'with an invalid user_id' do
+      it 'raises an error' do
+        VCR.use_cassette 'widgets/get_token_invalid_user_id' do
+          expect do
+            described_class.get_token(
+              organization_id: organization_id,
+              user_id: 'bogus-id',
+              scopes: ['widgets:users-table:manage'],
+            )
+          end.to raise_error(
+            WorkOS::NotFoundError,
+            /User not found: 'bogus-id'/,
+          )
+        end
+      end
+    end
+
+    describe 'with invalid scopes' do
+      it 'raises an error' do
+        expect do
+          described_class.get_token(
+            organization_id: organization_id,
+            user_id: user_id,
+            scopes: ['bogus-scope'],
+          )
+        end.to raise_error(
+          ArgumentError,
+          /scopes contains an invalid value/,
+        )
+      end
+    end
+  end
+end