organizations 0.2.0 → 0.3.0

data/lib/organizations/controller_helpers.rb

@@ -19,6 +19,7 @@ module Organizations
   #
   module ControllerHelpers
     extend ActiveSupport::Concern
+    include Organizations::CurrentUserResolution
 
     included do
       # Make helpers available in views
@@ -26,6 +27,9 @@ module Organizations
         helper_method :current_organization
         helper_method :current_membership
         helper_method :organization_signed_in?
+        helper_method :pending_organization_invitation
+        helper_method :pending_organization_invitation?
+        helper_method :pending_organization_invitation_email
       end
     end
 
@@ -46,6 +50,7 @@ module Organizations
       org_id = session[session_key]
 
       # Find organization AND verify membership
+      # Use is_member_of? which has DB fallback for stale loaded associations
       org = org_id ? Organizations::Organization.find_by(id: org_id) : nil
 
       if org && user.is_member_of?(org)
@@ -85,6 +90,355 @@ module Organizations
       current_organization.present?
     end
 
+    # === Pending Invitation Helpers ===
+
+    # Returns the pending invitation token from session
+    # @return [String, nil]
+    def pending_organization_invitation_token
+      session[pending_invitation_session_key]
+    end
+
+    # Returns the pending invitation if token is valid and invitation is usable
+    # Clears token if invitation is missing, expired, or already accepted
+    # @return [Organizations::Invitation, nil]
+    def pending_organization_invitation
+      token = pending_organization_invitation_token
+      return nil unless token
+
+      # Check memoized value (keyed by token to handle mid-request changes)
+      if defined?(@_pending_organization_invitation_token) && @_pending_organization_invitation_token == token
+        return @_pending_organization_invitation
+      end
+
+      invitation = Organizations::Invitation.find_by(token: token)
+
+      unless invitation
+        clear_pending_organization_invitation!
+        return nil
+      end
+
+      if invitation.expired? || invitation.accepted?
+        clear_pending_organization_invitation!
+        return nil
+      end
+
+      @_pending_organization_invitation_token = token
+      @_pending_organization_invitation = invitation
+    end
+
+    # Check if there's a valid pending invitation
+    # @return [Boolean]
+    def pending_organization_invitation?
+      pending_organization_invitation.present?
+    end
+
+    # Returns the email from the pending invitation, if present
+    # @return [String, nil]
+    def pending_organization_invitation_email
+      pending_organization_invitation&.email
+    end
+
+    # Clear pending invitation token and memoized values
+    # @return [nil]
+    def clear_pending_organization_invitation!
+      session.delete(pending_invitation_session_key)
+      remove_instance_variable(:@_pending_organization_invitation) if defined?(@_pending_organization_invitation)
+      remove_instance_variable(:@_pending_organization_invitation_token) if defined?(@_pending_organization_invitation_token)
+      nil
+    end
+
+    # Accept pending invitation (if present) and return post-accept redirect path.
+    # Returns nil when there is no pending/acceptable invitation.
+    #
+    # @param user [User] The user accepting the invitation
+    # @param token [String, nil] Explicit invitation token (optional)
+    # @param switch [Boolean] Whether to switch organization context
+    # @param skip_email_validation [Boolean] Whether to skip invitation email checks
+    # @param notice [Boolean, String, Proc] Flash notice behavior (default: true)
+    # @return [String, nil] Redirect path or nil
+    def pending_invitation_acceptance_redirect_path_for(
+      user,
+      token: nil,
+      switch: true,
+      skip_email_validation: false,
+      notice: true
+    )
+      result = accept_pending_organization_invitation!(
+        user,
+        token: token,
+        switch: switch,
+        skip_email_validation: skip_email_validation
+      )
+      return nil unless result
+
+      set_pending_invitation_acceptance_notice!(result, user: user, notice: notice)
+      redirect_path_after_invitation_accepted(result.invitation, user: user)
+    end
+
+    # Accept pending invitation and either return redirect path or perform redirect.
+    #
+    # @param user [User] The user accepting the invitation
+    # @param redirect [Boolean] When true, performs redirect_to and returns true/false
+    # @param token [String, nil] Explicit invitation token (optional)
+    # @param switch [Boolean] Whether to switch organization context
+    # @param skip_email_validation [Boolean] Whether to skip invitation email checks
+    # @param notice [Boolean, String, Proc] Flash notice behavior (default: true)
+    # @return [String, Boolean, nil]
+    def handle_pending_invitation_acceptance_for(
+      user,
+      redirect: false,
+      token: nil,
+      switch: true,
+      skip_email_validation: false,
+      notice: true
+    )
+      path = pending_invitation_acceptance_redirect_path_for(
+        user,
+        token: token,
+        switch: switch,
+        skip_email_validation: skip_email_validation,
+        notice: notice
+      )
+
+      return false if redirect && path.nil?
+      return nil unless path
+      return path unless redirect
+
+      redirect_to path
+      true
+    end
+
+    # Accept a pending organization invitation for a user
+    # This is the canonical method for handling invitation acceptance after signup/signin.
+    #
+    # @param user [User] The user accepting the invitation
+    # @param token [String, nil] Explicit token (uses session token if not provided)
+    # @param switch [Boolean] Whether to switch to the organization after acceptance (default: true)
+    # @param skip_email_validation [Boolean] Skip email matching check (default: false)
+    # @param return_failure [Boolean] Return a structured failure object instead of nil
+    # @return [Organizations::InvitationAcceptanceResult, Organizations::InvitationAcceptanceFailure, nil]
+    #
+    # @example Basic usage in after_sign_in_path_for
+    #   def after_sign_in_path_for(resource)
+    #     if (result = accept_pending_organization_invitation!(resource))
+    #       return redirect_path_after_invitation_accepted(result.invitation, user: resource)
+    #     end
+    #     super
+    #   end
+    #
+    def accept_pending_organization_invitation!(
+      user,
+      token: nil,
+      switch: true,
+      skip_email_validation: false,
+      return_failure: false
+    )
+      return invitation_acceptance_failure(:missing_user, return_failure: return_failure) unless user
+
+      # Track whether we're using an explicit token that differs from session
+      # Only skip session clearing if explicit token fails and differs from session
+      explicit_token = token.presence
+      session_token = pending_organization_invitation_token
+      invitation_token = explicit_token || session_token
+      return invitation_acceptance_failure(:missing_token, return_failure: return_failure) unless invitation_token
+
+      # When explicit token differs from session, don't clear session on failure
+      using_different_explicit_token = explicit_token && explicit_token != session_token
+
+      invitation = Organizations::Invitation.find_by(token: invitation_token)
+      unless invitation
+        # Only clear session if we were using the session token (or same token)
+        clear_pending_organization_invitation! unless using_different_explicit_token
+        return invitation_acceptance_failure(:invitation_not_found, return_failure: return_failure)
+      end
+
+      if invitation.expired?
+        # Only clear session if we were using the session token (or same token)
+        clear_pending_organization_invitation! unless using_different_explicit_token
+        return invitation_acceptance_failure(
+          :invitation_expired,
+          return_failure: return_failure,
+          invitation: invitation
+        )
+      end
+
+      # Check email match (unless skipping validation)
+      unless skip_email_validation
+        if user.respond_to?(:email) && !invitation.for_email?(user.email)
+          # Email mismatch - keep token intact to allow switching accounts
+          return invitation_acceptance_failure(
+            :email_mismatch,
+            return_failure: return_failure,
+            invitation: invitation
+          )
+        end
+      end
+
+      status = :accepted
+      membership = nil
+
+      begin
+        membership = invitation.accept!(user, skip_email_validation: skip_email_validation)
+      rescue Organizations::InvitationExpired
+        # Race condition: invitation expired between our check and accept!
+        clear_pending_organization_invitation! unless using_different_explicit_token
+        return invitation_acceptance_failure(
+          :invitation_expired,
+          return_failure: return_failure,
+          invitation: invitation
+        )
+      rescue Organizations::InvitationAlreadyAccepted
+        # Check if user is actually a member
+        membership = Organizations::Membership.find_by(
+          user_id: user.id,
+          organization_id: invitation.organization_id
+        )
+        unless membership
+          # Data integrity anomaly: invitation marked accepted but membership missing
+          if defined?(Rails) && Rails.respond_to?(:logger)
+            Rails.logger.warn "[Organizations] InvitationAlreadyAccepted raised but no membership found for user=#{user.id} org=#{invitation.organization_id}"
+          end
+          clear_pending_organization_invitation! unless using_different_explicit_token
+          return invitation_acceptance_failure(
+            :already_accepted_without_membership,
+            return_failure: return_failure,
+            invitation: invitation
+          )
+        end
+        status = :already_member
+      end
+
+      # Attempt to switch to the organization
+      switched = true
+      if switch
+        begin
+          switch_to_organization!(invitation.organization, user: user)
+        rescue Organizations::NotAMember
+          switched = false
+        end
+      else
+        switched = false
+      end
+
+      # Always clear session token on successful acceptance
+      clear_pending_organization_invitation!
+
+      Organizations::InvitationAcceptanceResult.new(
+        status: status,
+        invitation: invitation,
+        membership: membership,
+        switched: switched
+      )
+    end
+
+    # Returns the path to redirect to when an invitation requires authentication
+    # Uses configured value or falls back to registration/root path
+    #
+    # @param invitation [Organizations::Invitation, nil] The invitation (optional)
+    # @param user [User, nil] The user (optional)
+    # @return [String] The redirect path
+    def redirect_path_when_invitation_requires_authentication(invitation = nil, user: nil)
+      config_value = Organizations.configuration.redirect_path_when_invitation_requires_authentication
+
+      resolve_controller_redirect_path(
+        config_value,
+        invitation,
+        user,
+        default: -> { default_auth_required_redirect_path }
+      )
+    end
+
+    # Returns the path to redirect to after invitation is accepted
+    # Uses configured value or falls back to root path
+    #
+    # @param invitation [Organizations::Invitation] The invitation that was accepted
+    # @param user [User, nil] The user who accepted (optional)
+    # @return [String] The redirect path
+    def redirect_path_after_invitation_accepted(invitation, user: nil)
+      config_value = Organizations.configuration.redirect_path_after_invitation_accepted
+
+      resolve_controller_redirect_path(
+        config_value,
+        invitation,
+        user,
+        default: -> { default_after_accept_redirect_path }
+      )
+    end
+
+    # Returns the path to redirect to after organization switch
+    # Uses configured value or falls back to root path
+    #
+    # @param organization [Organizations::Organization] The organization switched to
+    # @param user [User, nil] The user who switched (optional)
+    # @return [String] The redirect path
+    def redirect_path_after_organization_switched(organization, user: nil)
+      config_value = Organizations.configuration.redirect_path_after_organization_switched
+
+      resolve_controller_redirect_path(
+        config_value,
+        organization,
+        user,
+        default: -> { default_after_switch_redirect_path }
+      )
+    end
+
+    # Returns the redirect path used when the user has no active organization.
+    # Uses configured value or falls back to /organizations/new.
+    #
+    # @param user [User, nil] Optional user context for Proc redirects
+    # @return [String]
+    def redirect_path_when_no_organization(user: nil)
+      config_value = Organizations.configuration.redirect_path_when_no_organization
+      redirect_user = user || organizations_current_user
+
+      resolve_controller_redirect_path(
+        config_value,
+        redirect_user,
+        default: -> { "/organizations/new" }
+      )
+    end
+
+    # Alias used in many host apps for readability.
+    #
+    # @param user [User, nil] Optional user context for Proc redirects
+    # @return [String]
+    def no_organization_redirect_path(user: nil)
+      redirect_path_when_no_organization(user: user)
+    end
+
+    # Redirect helper for no-organization flows.
+    #
+    # When both alert and notice are nil, uses the default alert message.
+    #
+    # @param alert [String, nil] Flash alert message
+    # @param notice [String, nil] Flash notice message
+    # @return [false]
+    def redirect_to_no_organization!(alert: nil, notice: nil)
+      flash_options = {}
+      flash_options[:alert] = alert unless alert.nil?
+      flash_options[:notice] = notice unless notice.nil?
+
+      # Keep current behavior for existing apps when nothing is configured/passed.
+      flash_options[:alert] = "Please select or create an organization." if flash_options.empty?
+
+      redirect_to no_organization_redirect_path, **flash_options
+      false
+    end
+
+    # Creates an organization and switches context in one call.
+    #
+    # @param user [User] The user who will own the created organization
+    # @param attributes [Hash] Attributes passed to create_organization!
+    # @return [Organizations::Organization] The created organization
+    def create_organization_and_switch!(user, attributes = {})
+      organization = user.create_organization!(attributes)
+      switch_to_organization!(organization, user: user)
+      organization
+    end
+
+    # Alias for readability in host apps.
+    alias_method :create_organization_with_context!, :create_organization_and_switch!
+
     # === Switching ===
 
     # Sets the current organization in session
@@ -107,20 +461,28 @@ module Organizations
 
     # Switches to a different organization
     # @param org [Organizations::Organization]
+    # @param user [User, nil] Explicit user to switch for (useful in auth-transition flows)
     # @raise [Organizations::NotAMember] if user is not a member
-    def switch_to_organization!(org)
-      user = organizations_current_user
+    def switch_to_organization!(org, user: nil)
+      acting_user = user || organizations_current_user(refresh: true)
 
-      unless user&.is_member_of?(org)
+      unless membership_exists_for?(acting_user, org)
         raise Organizations::NotAMember.new(
           "You are not a member of this organization",
           organization: org,
-          user: user
+          user: acting_user
         )
       end
 
       self.current_organization = org
-      mark_membership_as_recent!(user, org)
+      # current_organization= calls organizations_current_user (without refresh) and
+      # updates that user's _current_organization_id. But in auth-transition flows:
+      # 1. The memoized user may still be nil (sign-in just happened)
+      # 2. An explicit user: was passed that differs from the memoized user
+      # In either case, acting_user won't be updated by current_organization=.
+      # This explicit assignment ensures acting_user always gets the correct org ID.
+      acting_user._current_organization_id = org.id if acting_user.respond_to?(:_current_organization_id=)
+      mark_membership_as_recent!(acting_user, org)
     end
 
     # === Permission Guards ===
@@ -184,18 +546,21 @@ module Organizations
 
     private
 
-    # Get the current user using the configured method
-    # NOTE: This method safely calls the host app's current_user method
-    def organizations_current_user
-      return @_organizations_current_user if defined?(@_organizations_current_user)
+    def organizations_current_user(refresh: false)
+      resolve_organizations_current_user(
+        cache_ivar: :@_organizations_current_user,
+        refresh: refresh,
+        cache_nil: false
+      )
+    end
 
-      method_name = Organizations.configuration.current_user_method
+    def invitation_acceptance_failure(reason, return_failure:, invitation: nil)
+      return nil unless return_failure
 
-      # The configured method should exist on the host controller
-      # (e.g., Devise's current_user). We call it directly.
-      @_organizations_current_user = if respond_to?(method_name, true)
-                                       send(method_name)
-                                     end
+      Organizations::InvitationAcceptanceFailure.new(
+        reason: reason,
+        invitation: invitation
+      )
     end
 
     # Clear organization session and cached values
@@ -218,6 +583,16 @@ module Organizations
       user.memberships.where(organization_id: org.id).update_all(updated_at: Time.current)
     end
 
+    # DB-authoritative membership check to avoid stale loaded association issues
+    # @param user [User, nil]
+    # @param org [Organization, nil]
+    # @return [Boolean]
+    def membership_exists_for?(user, org)
+      return false unless user && org
+
+      Organizations::Membership.exists?(user_id: user.id, organization_id: org.id)
+    end
+
     # Handle unauthorized access
     def handle_unauthorized(permission: nil, required_role: nil)
       config = Organizations.configuration
@@ -282,11 +657,131 @@ module Organizations
       # Default behavior
       respond_to do |format|
         format.html do
-          path = config.redirect_path_when_no_organization
-          redirect_to path, alert: "Please select or create an organization."
+          redirect_to_no_organization!(
+            alert: config.no_organization_alert,
+            notice: config.no_organization_notice
+          )
         end
         format.json { render json: { error: "Organization required" }, status: :forbidden }
       end
     end
+
+    def set_pending_invitation_acceptance_notice!(result, user:, notice:)
+      return unless notice
+      return unless respond_to?(:flash) && flash
+
+      message = case notice
+                when true
+                  default_pending_invitation_acceptance_notice(result)
+                when Proc
+                  resolve_pending_invitation_notice_message(notice, result, user)
+                when String
+                  notice
+                else
+                  notice.to_s
+                end
+
+      flash[:notice] = message if message.present?
+    end
+
+    def resolve_pending_invitation_notice_message(notice_proc, result, user)
+      case notice_proc.arity
+      when 0
+        instance_exec(&notice_proc)
+      when 1
+        instance_exec(result, &notice_proc)
+      when 2
+        instance_exec(result.invitation, user, &notice_proc)
+      else
+        instance_exec(result, result.invitation, user, &notice_proc)
+      end
+    rescue StandardError => e
+      if defined?(Rails) && Rails.respond_to?(:env) && (Rails.env.development? || Rails.env.test?)
+        raise
+      end
+      if defined?(Rails) && Rails.respond_to?(:logger)
+        Rails.logger.error "[Organizations] Invitation notice proc failed: #{e.message}"
+      end
+      default_pending_invitation_acceptance_notice(result)
+    end
+
+    # Session key for pending invitation token
+    # @return [Symbol]
+    def pending_invitation_session_key
+      :organizations_pending_invitation_token
+    end
+
+    # Resolve a redirect path from config value (nil, String, or Proc)
+    # @param config_value [nil, String, Proc] The configured value
+    # @param args [Array] Optional proc arguments
+    # @param default [Proc] Lambda returning default path
+    # @return [String]
+    def resolve_controller_redirect_path(config_value, *args, default:)
+      return default.call if config_value.nil?
+      return config_value if config_value.is_a?(String)
+      return default.call unless config_value.is_a?(Proc)
+
+      begin
+        case config_value.arity
+        when 0
+          instance_exec(&config_value)
+        when 1
+          instance_exec(args[0], &config_value)
+        when 2
+          instance_exec(args[0], args[1], &config_value)
+        else
+          exec_args = config_value.arity.negative? ? args : args.first(config_value.arity)
+          instance_exec(*exec_args, &config_value)
+        end
+      rescue StandardError => e
+        # Re-raise in dev/test to surface misconfigurations; fall back in production
+        if defined?(Rails) && Rails.respond_to?(:env) && (Rails.env.development? || Rails.env.test?)
+          raise
+        end
+        if defined?(Rails) && Rails.respond_to?(:logger)
+          Rails.logger.error "[Organizations] Redirect path proc failed: #{e.message}"
+        end
+        default.call
+      end
+    end
+
+    # Default path when invitation requires authentication
+    # @return [String]
+    def default_auth_required_redirect_path
+      if main_app.respond_to?(:new_user_registration_path)
+        main_app.new_user_registration_path
+      elsif main_app.respond_to?(:root_path)
+        main_app.root_path
+      else
+        "/"
+      end
+    end
+
+    # Default path after invitation acceptance
+    # @return [String]
+    def default_after_accept_redirect_path
+      if main_app.respond_to?(:root_path)
+        main_app.root_path
+      else
+        "/"
+      end
+    end
+
+    # Default path after organization switch
+    # @return [String]
+    def default_after_switch_redirect_path
+      if main_app.respond_to?(:root_path)
+        main_app.root_path
+      else
+        "/"
+      end
+    end
+
+    def default_pending_invitation_acceptance_notice(result)
+      organization_name = result.invitation.organization.name
+      return "You're already a member of #{organization_name}." if result.already_member?
+
+      "Welcome to #{organization_name}!"
+    end
   end
 end

data/lib/organizations/current_user_resolution.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Organizations
+  module CurrentUserResolution
+    private
+
+    # Resolve current user for organizations integration with configurable caching behavior.
+    #
+    # @param cache_ivar [Symbol] Instance variable used for memoization (e.g. :@_current_user)
+    # @param refresh [Boolean] Clear memoized value before resolving
+    # @param cache_nil [Boolean] Whether nil values should be memoized
+    # @param prefer_super_for_current_user [Boolean]
+    #   When true and configured method is :current_user, call super instead of send(:current_user)
+    # @param prefer_warden_for_current_user [Boolean]
+    #   When true, resolve via Warden before trying super.
+    #
+    # @return [Object, nil] Resolved current user object
+    def resolve_organizations_current_user(
+      cache_ivar:,
+      refresh: false,
+      cache_nil: false,
+      prefer_super_for_current_user: false,
+      prefer_warden_for_current_user: false
+    )
+      remove_instance_variable(cache_ivar) if refresh && instance_variable_defined?(cache_ivar)
+
+      if instance_variable_defined?(cache_ivar)
+        cached = instance_variable_get(cache_ivar)
+        return cached if cache_nil || !cached.nil?
+      end
+
+      method_name = Organizations.configuration.current_user_method
+
+      attempted_warden = false
+
+      resolved_user = nil
+
+      if method_name && respond_to?(method_name, true)
+        if method_name == :current_user
+          if prefer_warden_for_current_user
+            attempted_warden = true
+            resolved_user = warden_user
+          end
+
+          if resolved_user.nil?
+            resolved_user = prefer_super_for_current_user ? safe_super_current_user : send(method_name)
+          end
+        else
+          resolved_user = send(method_name)
+        end
+      elsif prefer_warden_for_current_user
+        attempted_warden = true
+        resolved_user = warden_user
+      end
+
+      if resolved_user.nil? && prefer_warden_for_current_user && !attempted_warden
+        resolved_user = warden_user
+      end
+
+      if resolved_user.nil? && prefer_super_for_current_user
+        resolved_user = safe_super_current_user
+      end
+
+      instance_variable_set(cache_ivar, resolved_user) if cache_nil || !resolved_user.nil?
+      resolved_user
+    end
+
+    # Resolve current user via Warden when available.
+    # Uses warden.user (read-only) to avoid triggering authentication strategies.
+    def warden_user
+      return nil unless respond_to?(:warden, true)
+
+      w = warden
+      return nil unless w
+
+      scope = defined?(Devise) ? Devise.default_scope : :user
+      w.user(scope)
+    end
+
+    def safe_super_current_user
+      super_method = method(:current_user).super_method
+      return nil unless super_method
+
+      super_method.call
+    rescue NoMethodError, NameError
+      nil
+    end
+  end
+end