workos 5.3.0 → 6.1.0

data/lib/workos/user_management.rb

@@ -6,9 +6,9 @@ require 'uri'
 module WorkOS
   # The UserManagement module provides convenience methods for working with the
   # WorkOS User platform. You'll need a valid API key.
-
-  # rubocop:disable Metrics/ModuleLength
   module UserManagement
+    autoload :Session, 'workos/user_management/session'
+
     module Types
       # The ProviderEnum is a declaration of a
       # fixed set of values for User Management Providers.
@@ -19,7 +19,7 @@ module WorkOS
         Microsoft = 'MicrosoftOAuth'
         AuthKit = 'authkit'
 
-        ALL = [GitHub, Google, Microsoft, AuthKit].freeze
+        ALL = [Apple, GitHub, Google, Microsoft, AuthKit].freeze
       end
 
       # The AuthFactorType is a declaration of a
@@ -37,6 +37,24 @@ module WorkOS
       PROVIDERS = WorkOS::UserManagement::Types::Provider::ALL
       AUTH_FACTOR_TYPES = WorkOS::UserManagement::Types::AuthFactorType::ALL
 
+      # Load a sealed session
+      #
+      # @param [String] client_id The WorkOS client ID for the environment
+      # @param [String] session_data The sealed session data
+      # @param [String] cookie_password The password used to seal the session
+      # @param [Object] encryptor Optional custom encryptor that responds to #seal and #unseal
+      #
+      # @return WorkOS::Session
+      def load_sealed_session(client_id:, session_data:, cookie_password:, encryptor: nil)
+        WorkOS::Session.new(
+          user_management: self,
+          client_id: client_id,
+          session_data: session_data,
+          cookie_password: cookie_password,
+          encryptor: encryptor,
+        )
+      end
+
       # Generate an OAuth 2.0 authorization URL that automatically directs a user
       # to their Identity Provider.
       #
@@ -55,8 +73,11 @@ module WorkOS
       #  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.
       # @example
       #   WorkOS::UserManagement.authorization_url(
       #     connection_id: 'conn_123',
@@ -79,10 +100,12 @@ module WorkOS
         client_id: nil,
         domain_hint: nil,
         login_hint: nil,
+        screen_hint: nil,
         provider: nil,
         connection_id: nil,
         organization_id: nil,
-        state: ''
+        state: '',
+        provider_scopes: nil
       )
 
         validate_authorization_url_arguments(
@@ -98,9 +121,11 @@ module WorkOS
           state: state,
           domain_hint: domain_hint,
           login_hint: login_hint,
+          screen_hint: screen_hint,
           provider: provider,
           connection_id: connection_id,
           organization_id: organization_id,
+          provider_scopes: provider_scopes,
         }.compact)
 
         "https://#{WorkOS.config.api_hostname}/user_management/authorize?#{query}"
@@ -165,6 +190,7 @@ module WorkOS
       # @param [String] first_name The user's first name.
       # @param [String] last_name The user's last name.
       # @param [Boolean] email_verified Whether the user's email address was previously verified.
+      # @param [String] external_id The user's external ID.
       # @param [String] password_hash The user's hashed password.
       # @option [String] password_hash_type The algorithm originally used to hash the password.
       #
@@ -176,6 +202,7 @@ module WorkOS
         first_name: nil,
         last_name: nil,
         email_verified: nil,
+        external_id: nil,
         password_hash: nil,
         password_hash_type: nil
       )
@@ -187,9 +214,10 @@ module WorkOS
             first_name: first_name,
             last_name: last_name,
             email_verified: email_verified,
+            external_id: external_id,
             password_hash: password_hash,
             password_hash_type: password_hash_type,
-          },
+          }.compact,
           auth: true,
         )
 
@@ -201,9 +229,12 @@ module WorkOS
       # Update a user
       #
       # @param [String] id of the user.
+      # @param [String] email of the user.
       # @param [String] first_name The user's first name.
       # @param [String] last_name The user's last name.
       # @param [Boolean] email_verified Whether the user's email address was previously verified.
+      # @param [String] external_id The users's external ID
+      # @param [String] locale The user's locale.
       # @param [String] password The user's password.
       # @param [String] password_hash The user's hashed password.
       # @option [String] password_hash_type The algorithm originally used to hash the password.
@@ -212,23 +243,29 @@ module WorkOS
       # @return [WorkOS::User]
       def update_user(
         id:,
-        first_name: nil,
-        last_name: nil,
-        email_verified: nil,
-        password: nil,
-        password_hash: nil,
-        password_hash_type: nil
+        email: :not_set,
+        first_name: :not_set,
+        last_name: :not_set,
+        email_verified: :not_set,
+        external_id: :not_set,
+        locale: :not_set,
+        password: :not_set,
+        password_hash: :not_set,
+        password_hash_type: :not_set
       )
         request = put_request(
           path: "/user_management/users/#{id}",
           body: {
+            email: email,
             first_name: first_name,
             last_name: last_name,
             email_verified: email_verified,
+            external_id: external_id,
+            locale: locale,
             password: password,
             password_hash: password_hash,
             password_hash_type: password_hash_type,
-          },
+          }.reject { |_, v| v == :not_set },
           auth: true,
         )
 
@@ -261,9 +298,23 @@ module WorkOS
       # @param [String] client_id The WorkOS client ID for the environment
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [String] invitation_token The token of an Invitation, if required.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
-      def authenticate_with_password(email:, password:, client_id:, ip_address: nil, user_agent: nil)
+      # rubocop:disable Metrics/ParameterLists
+      def authenticate_with_password(
+        email:,
+        password:,
+        client_id:,
+        ip_address: nil,
+        user_agent: nil,
+        invitation_token: nil,
+        session: nil
+      )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -274,13 +325,15 @@ module WorkOS
               password: password,
               ip_address: ip_address,
               user_agent: user_agent,
+              invitation_token: invitation_token,
               grant_type: 'password',
             },
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Authenticate a user using OAuth or an organization's SSO connection.
       #
@@ -289,14 +342,21 @@ module WorkOS
       # @param [String] client_id The WorkOS client ID for the environment
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [String] invitation_token The token of an Invitation, if required.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
       def authenticate_with_code(
         code:,
         client_id:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        invitation_token: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -306,28 +366,36 @@ module WorkOS
               client_secret: WorkOS.config.key!,
               ip_address: ip_address,
               user_agent: user_agent,
+              invitation_token: invitation_token,
               grant_type: 'authorization_code',
             },
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Authenticate a user using a refresh token.
       #
       # @param [String] refresh_token The refresh token previously obtained from a successful authentication call
       # @param [String] client_id The WorkOS client ID for the environment
+      # @param [String] organization_id The organization to issue the new access token for. (Optional)
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::RefreshAuthenticationResponse
       def authenticate_with_refresh_token(
         refresh_token:,
         client_id:,
+        organization_id: nil,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -338,11 +406,12 @@ module WorkOS
               ip_address: ip_address,
               user_agent: user_agent,
               grant_type: 'refresh_token',
+              organization_id: organization_id,
             },
           ),
         )
 
-        WorkOS::RefreshAuthenticationResponse.new(response.body)
+        WorkOS::RefreshAuthenticationResponse.new(response.body, session)
       end
 
       # Authenticate user by Magic Auth Code.
@@ -354,16 +423,24 @@ module WorkOS
       # @param [String] link_authorization_code Used to link an OAuth profile to an existing user,
       # after having completed a Magic Code challenge.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [String] invitation_token The token of an Invitation, if required.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
+      # rubocop:disable Metrics/ParameterLists
       def authenticate_with_magic_auth(
         code:,
         email:,
         client_id:,
         ip_address: nil,
         user_agent: nil,
-        link_authorization_code: nil
+        link_authorization_code: nil,
+        invitation_token: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -376,12 +453,14 @@ module WorkOS
               user_agent: user_agent,
               grant_type: 'urn:workos:oauth:grant-type:magic-auth:code',
               link_authorization_code: link_authorization_code,
+              invitation_token: invitation_token,
             },
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Authenticate a user into an organization they are a member of.
       #
@@ -390,6 +469,8 @@ module WorkOS
       # @param [String] pending_authentication_token The pending authentication token
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
       def authenticate_with_organization_selection(
@@ -397,8 +478,11 @@ module WorkOS
         organization_id:,
         pending_authentication_token:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -414,7 +498,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Authenticate a user using TOTP.
@@ -427,16 +511,22 @@ module WorkOS
       # authentication request.
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
+      # rubocop:disable Metrics/ParameterLists
       def authenticate_with_totp(
         code:,
         client_id:,
         pending_authentication_token:,
         authentication_challenge_id:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -453,8 +543,9 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
+      # rubocop:enable Metrics/ParameterLists
 
       # Authenticate a user using Email Verification Code.
       #
@@ -464,6 +555,8 @@ module WorkOS
       # authentication attempt due to an unverified email address.
       # @param [String] ip_address The IP address of the request from the user who is attempting to authenticate.
       # @param [String] user_agent The user agent of the request from the user who is attempting to authenticate.
+      # @param [Hash] session An optional hash that determines whether the session should be sealed and
+      # the optional cookie password.
       #
       # @return WorkOS::AuthenticationResponse
       def authenticate_with_email_verification(
@@ -471,8 +564,11 @@ module WorkOS
         client_id:,
         pending_authentication_token:,
         ip_address: nil,
-        user_agent: nil
+        user_agent: nil,
+        session: nil
       )
+        validate_session(session)
+
         response = execute_request(
           request: post_request(
             path: '/user_management/authenticate',
@@ -488,7 +584,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::AuthenticationResponse.new(response.body)
+        WorkOS::AuthenticationResponse.new(response.body, session)
       end
 
       # Get the logout URL for a session
@@ -497,13 +593,17 @@ module WorkOS
       #
       # @param [String] session_id The session ID can be found in the `sid`
       #   claim of the access token
+      # @param [String] return_to The URL to redirect the user to after logging out
       #
       # @return String
-      def get_logout_url(session_id:)
+      def get_logout_url(session_id:, return_to: nil)
+        params = { session_id: session_id }
+        params[:return_to] = return_to if return_to
+
         URI::HTTPS.build(
           host: WorkOS.config.api_hostname,
           path: '/user_management/sessions/logout',
-          query: "session_id=#{session_id}",
+          query: URI.encode_www_form(params),
         ).to_s
       end
 
@@ -568,7 +668,7 @@ module WorkOS
             body: {
               email: email,
               invitation_token: invitation_token,
-            },
+            }.compact,
             auth: true,
           ),
         )
@@ -622,7 +722,7 @@ module WorkOS
               totp_issuer: totp_issuer,
               totp_user: totp_user,
               totp_secret: totp_secret,
-            },
+            }.compact,
             auth: true,
           ),
         )
@@ -655,6 +755,40 @@ module WorkOS
         )
       end
 
+      # Get all sessions for a user
+      #
+      # @param [String] user_id The id for the user.
+      # @param [Hash] options
+      # @option options [String] limit Maximum number of records to return.
+      # @option options [String] order The order in which to paginate records
+      # @option options [String] before Pagination cursor to receive records
+      #  before a provided Session ID.
+      # @option options [String] after Pagination cursor to receive records
+      #  after a provided Session ID.
+      #
+      # @return [WorkOS::Types::ListStruct<WorkOS::UserManagement::Session>]
+      def list_sessions(user_id:, options: {})
+        options[:order] ||= 'desc'
+        response = execute_request(
+          request: get_request(
+            path: "/user_management/users/#{user_id}/sessions",
+            auth: true,
+            params: options,
+          ),
+        )
+
+        parsed_response = JSON.parse(response.body)
+
+        sessions = parsed_response['data'].map do |session|
+          ::WorkOS::UserManagement::Session.new(session.to_json)
+        end
+
+        WorkOS::Types::ListStruct.new(
+          data: sessions,
+          list_metadata: parsed_response['list_metadata'],
+        )
+      end
+
       # Gets an email verification object
       #
       # @param [String] id The unique ID of the EmailVerification object.
@@ -784,7 +918,7 @@ module WorkOS
           ),
         )
 
-        WorkOS::User.new(response.body)
+        WorkOS::UserResponse.new(response.body).user
       end
 
       # Get an Organization Membership
@@ -844,16 +978,23 @@ module WorkOS
       # @param [String] user_id The ID of the User.
       # @param [String] organization_id The ID of the Organization to which the user belongs to.
       # @param [String] role_slug The slug of the role to grant to this membership. (Optional)
+      # @param [Array<String>] role_slugs Array of role slugs to assign to this membership. (Optional)
       #
       # @return [WorkOS::OrganizationMembership]
-      def create_organization_membership(user_id:, organization_id:, role_slug: nil)
+      def create_organization_membership(user_id:, organization_id:, role_slug: nil, role_slugs: nil)
+        raise ArgumentError, 'Cannot specify both role_slug and role_slugs' if role_slug && role_slugs
+
+        body = {
+          user_id: user_id,
+          organization_id: organization_id,
+        }
+
+        body[:role_slugs] = role_slugs if role_slugs
+        body[:role_slug] = role_slug if role_slug
+
         request = post_request(
           path: '/user_management/organization_memberships',
-          body: {
-            user_id: user_id,
-            organization_id: organization_id,
-            role_slug: role_slug,
-          },
+          body: body.compact,
           auth: true,
         )
 
@@ -864,17 +1005,22 @@ module WorkOS
 
       # Update an Organization Membership
       #
-      # @param [String] organization_membership_id The ID of the Organization Membership.
-      # @param [String] role_slug The slug of the role to grant to this membership.
+      # @param [String] id The ID of the Organization Membership.
+      # @param [String] role_slug The slug of the role to grant to this membership. (Optional)
+      # @param [Array<String>] role_slugs Array of role slugs to assign to this membership. (Optional)
       #
       # @return [WorkOS::OrganizationMembership]
-      def update_organization_membership(id:, role_slug:)
+      def update_organization_membership(id:, role_slug: nil, role_slugs: nil)
+        raise ArgumentError, 'Cannot specify both role_slug and role_slugs' if role_slug && role_slugs
+
+        body = { id: id }
+
+        body[:role_slugs] = role_slugs if role_slugs
+        body[:role_slug] = role_slug if role_slug
+
         request = put_request(
           path: "/user_management/organization_memberships/#{id}",
-          body: {
-            id: id,
-            role_slug: role_slug,
-          },
+          body: body.compact,
           auth: true,
         )
 
@@ -1018,7 +1164,7 @@ module WorkOS
               expires_in_days: expires_in_days,
               inviter_user_id: inviter_user_id,
               role_slug: role_slug,
-            },
+            }.compact,
             auth: true,
           ),
         )
@@ -1042,8 +1188,30 @@ module WorkOS
         WorkOS::Invitation.new(response.body)
       end
 
+      # Resends an existing Invitation.
+      #
+      # @param [String] id The unique ID of the Invitation.
+      #
+      # @return WorkOS::Invitation
+      def resend_invitation(id:)
+        request = post_request(
+          path: "/user_management/invitations/#{id}/resend",
+          auth: true,
+        )
+
+        response = execute_request(request: request)
+
+        WorkOS::Invitation.new(response.body)
+      end
+
       private
 
+      def validate_session(session)
+        return unless session && (session[:seal_session] == true) && session[:cookie_password].nil?
+
+        raise ArgumentError, 'cookie_password is required when sealing session'
+      end
+
       def validate_authorization_url_arguments(
         provider:,
         connection_id:,

data/lib/workos/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WorkOS
-  VERSION = '5.3.0'
+  VERSION = '6.1.0'
 end

data/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

data/lib/workos.rb

@@ -45,6 +45,7 @@ module WorkOS
   autoload :AuthenticationFactorAndChallenge, 'workos/authentication_factor_and_challenge'
   autoload :AuthenticationResponse, 'workos/authentication_response'
   autoload :AuditLogs, 'workos/audit_logs'
+  autoload :Cache, 'workos/cache'
   autoload :Challenge, 'workos/challenge'
   autoload :Client, 'workos/client'
   autoload :Connection, 'workos/connection'
@@ -55,13 +56,16 @@ module WorkOS
   autoload :DirectorySync, 'workos/directory_sync'
   autoload :DirectoryUser, 'workos/directory_user'
   autoload :EmailVerification, 'workos/email_verification'
+  autoload :Encryptors, 'workos/encryptors'
   autoload :Event, 'workos/event'
   autoload :Events, 'workos/events'
   autoload :Factor, 'workos/factor'
+  autoload :FeatureFlag, 'workos/feature_flag'
   autoload :Impersonator, 'workos/impersonator'
   autoload :Invitation, 'workos/invitation'
   autoload :MagicAuth, 'workos/magic_auth'
   autoload :MFA, 'workos/mfa'
+  autoload :OAuthTokens, 'workos/oauth_tokens'
   autoload :Organization, 'workos/organization'
   autoload :Organizations, 'workos/organizations'
   autoload :OrganizationMembership, 'workos/organization_membership'
@@ -71,6 +75,8 @@ module WorkOS
   autoload :Profile, 'workos/profile'
   autoload :ProfileAndToken, 'workos/profile_and_token'
   autoload :RefreshAuthenticationResponse, 'workos/refresh_authentication_response'
+  autoload :Role, 'workos/role'
+  autoload :Session, 'workos/session'
   autoload :SSO, 'workos/sso'
   autoload :Types, 'workos/types'
   autoload :User, 'workos/user'
@@ -80,11 +86,13 @@ module WorkOS
   autoload :VerifyChallenge, 'workos/verify_challenge'
   autoload :Webhook, 'workos/webhook'
   autoload :Webhooks, 'workos/webhooks'
+  autoload :Widgets, 'workos/widgets'
 
   # Errors
   autoload :APIError, 'workos/errors'
   autoload :AuthenticationError, 'workos/errors'
   autoload :InvalidRequestError, 'workos/errors'
+  autoload :ForbiddenRequestError, 'workos/errors'
   autoload :SignatureVerificationError, 'workos/errors'
   autoload :TimeoutError, 'workos/errors'
   autoload :NotFoundError, 'workos/errors'