plutonium 0.39.2 → 0.40.0

data/lib/plutonium/invites/concerns/invite_token.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # InviteToken provides core invite functionality for models.
+      #
+      # This concern handles:
+      # - Token generation and validation
+      # - State machine (pending, accepted, expired, cancelled)
+      # - Email constraint validation
+      # - Invite acceptance flow
+      #
+      # @example Basic usage
+      #   class UserInvite < ApplicationRecord
+      #     include Plutonium::Resource::Record
+      #     include Plutonium::Invites::Concerns::InviteToken
+      #
+      #     belongs_to :entity
+      #     belongs_to :invited_by, polymorphic: true
+      #     belongs_to :user, optional: true
+      #     belongs_to :invitable, polymorphic: true, optional: true
+      #
+      #     enum :role, member: 0, admin: 1
+      #
+      #     def invitation_mailer
+      #       UserInviteMailer
+      #     end
+      #
+      #     def create_membership_for(user)
+      #       EntityMembership.create!(entity: entity, user: user, role: role)
+      #     end
+      #   end
+      #
+      module InviteToken
+        extend ActiveSupport::Concern
+
+        included do
+          # State machine for invite lifecycle
+          enum :state, pending: 0, accepted: 1, expired: 2, cancelled: 3
+
+          # Callbacks
+          before_validation :set_token_defaults, on: :create
+          after_create :send_invitation_email
+
+          # Core validations
+          validates :email, presence: true
+          validates :token, presence: true
+          validates :state, presence: true
+        end
+
+        class_methods do
+          # Find a valid invitation for acceptance.
+          #
+          # Returns nil if the token is invalid, expired, or already accepted.
+          # Automatically marks expired invites as expired.
+          #
+          # @param token [String] the invitation token
+          # @return [Object, nil] the invite record or nil
+          def find_for_acceptance(token)
+            return nil if token.blank?
+
+            invite = find_by(token: token)
+            return nil unless invite
+
+            # Check if invitation is expired
+            if invite.expires_at && invite.expires_at < Time.current
+              invite.expired! if invite.pending?
+              return nil
+            end
+
+            # Only pending invites can be accepted
+            return nil unless invite.pending?
+
+            invite
+          end
+        end
+
+        # Override in subclass to enforce email domain matching.
+        #
+        # @return [String, nil] the domain to enforce, or nil to skip domain check
+        def enforce_domain
+          nil
+        end
+
+        # Override in subclass to require exact email match.
+        #
+        # @return [Boolean] true to require exact email match
+        def enforce_email?
+          true
+        end
+
+        # Validate email constraints against the accepting user's email.
+        #
+        # @param user_email [String] the email of the user accepting the invite
+        # @raise [ActiveRecord::RecordInvalid] if constraints are violated
+        def validate_email_constraints!(user_email)
+          if enforce_email? && user_email.downcase != email.downcase
+            errors.add(:base, "This invitation is for #{email}. You must use an account with that email address.")
+            raise ActiveRecord::RecordInvalid.new(self)
+          end
+
+          if (required_domain = enforce_domain)
+            user_domain = extract_domain(user_email)
+
+            if user_domain != required_domain
+              errors.add(:base, "This invitation requires an email from the #{required_domain} domain.")
+              raise ActiveRecord::RecordInvalid.new(self)
+            end
+          end
+        end
+
+        # Accept the invitation for a user.
+        #
+        # This method:
+        # 1. Validates email constraints
+        # 2. Marks the invite as accepted
+        # 3. Creates the entity membership
+        # 4. Notifies the invitable (if present)
+        #
+        # @param user [Object] the user accepting the invitation
+        # @raise [ActiveRecord::RecordInvalid] if acceptance fails
+        def accept_for_user!(user)
+          validate_email_constraints!(user.email)
+
+          transaction do
+            update!(
+              state: :accepted,
+              accepted_at: Time.current,
+              user: user
+            )
+
+            create_membership_for(user)
+            notify_invitable(user)
+          end
+        end
+
+        # Override this method to specify the mailer class.
+        #
+        # @return [Class] the mailer class for sending invitation emails
+        # @raise [NotImplementedError] if not overridden
+        def invitation_mailer
+          raise NotImplementedError, "#{self.class}#invitation_mailer must be implemented to return the mailer class"
+        end
+
+        # Override this method to create the entity membership.
+        #
+        # @param user [Object] the user who accepted the invitation
+        # @raise [NotImplementedError] if not overridden
+        def create_membership_for(user)
+          raise NotImplementedError, "#{self.class}#create_membership_for must be implemented to create the membership record"
+        end
+
+        # Alias method for the entity association.
+        # Override if your entity association has a different name.
+        #
+        # @return [Object] the entity record
+        def entity
+          raise NotImplementedError, "#{self.class}#entity must be implemented or an entity association must exist"
+        end
+
+        private
+
+        def extract_domain(email)
+          return nil unless email&.include?("@")
+          email.split("@").last&.downcase
+        end
+
+        def set_token_defaults
+          self.token ||= SecureRandom.urlsafe_base64(32)
+          self.expires_at ||= 1.week.from_now
+        end
+
+        def send_invitation_email
+          invitation_mailer.invitation(self).deliver_later
+        end
+
+        def notify_invitable(user)
+          return unless invitable_id.present?
+
+          invitable.on_invite_accepted(user)
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/invites/concerns/invite_user.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # InviteUser provides the core logic for inviting users to an entity.
+      #
+      # Include this in your InviteUserInteraction and implement the required methods.
+      #
+      # @example Basic usage with polymorphic entity
+      #   class Organization::InviteUserInteraction < Plutonium::Resource::Interaction
+      #     include Plutonium::Invites::Concerns::InviteUser
+      #
+      #     def invite_class
+      #       Invites::UserInvite
+      #     end
+      #
+      #     def membership_class
+      #       OrganizationMembership
+      #     end
+      #   end
+      #
+      module InviteUser
+        extend ActiveSupport::Concern
+
+        included do
+          presents label: "Invite User", icon: Phlex::TablerIcons::Mail
+
+          attribute :resource
+          attribute :email
+
+          validates :email, presence: true
+          validate :role_is_present
+          validate :user_not_already_member
+          validate :no_pending_invitation
+        end
+
+        def execute
+          attrs = {
+            entity: entity,
+            email: email,
+            role: role,
+            invited_by: current_user,
+            **additional_invite_attributes
+          }
+          attrs[:invitable] = invitable if invitable.present?
+
+          invite_class.create!(attrs)
+
+          succeed(resource).with_message(success_message)
+        rescue ActiveRecord::RecordInvalid => e
+          failed(e.record.errors)
+        end
+
+        private
+
+        # Override to specify the invite model class
+        # @return [Class]
+        def invite_class
+          Invites::UserInvite
+        end
+
+        # Override to specify the membership model class
+        # @return [Class]
+        def membership_class
+          EntityMembership
+        end
+
+        # Override to specify the user model class
+        # @return [Class]
+        def user_class
+          User
+        end
+
+        # Override to specify how to get the entity from the resource.
+        # By default assumes resource IS the entity.
+        # @return [Object]
+        def entity
+          resource
+        end
+
+        # Override to specify the invitable (model that triggered the invite).
+        # By default returns nil (no invitable).
+        # @return [Object, nil]
+        def invitable
+          nil
+        end
+
+        # Override to specify the role to assign
+        # @return [Symbol, String]
+        def role
+          raise NotImplementedError, "#{self.class}#role must return the role to assign"
+        end
+
+        # Override to add additional attributes when creating the invite
+        # @return [Hash]
+        def additional_invite_attributes
+          {}
+        end
+
+        # Override to customize success message
+        def success_message
+          "Invitation sent to #{email}"
+        end
+
+        # Override to specify the entity association name on membership
+        # @return [Symbol]
+        def membership_entity_attribute
+          entity.class.name.underscore.to_sym
+        end
+
+        def role_is_present
+          errors.add(:role, :blank) if role.blank?
+        end
+
+        def user_not_already_member
+          return unless email.present? && entity.present?
+
+          existing_user = user_class.find_by(email: email)
+          return unless existing_user
+
+          membership = membership_class.find_by(
+            membership_entity_attribute => entity,
+            user_association => existing_user
+          )
+          errors.add(:email, "is already a member") if membership
+        end
+
+        def no_pending_invitation
+          return unless email.present? && entity.present?
+
+          pending = invite_class.find_by(
+            entity: entity,
+            email: email,
+            state: :pending
+          )
+          errors.add(:email, "already has a pending invitation") if pending
+        end
+
+        # Override if user association has a different name
+        def user_association
+          :user
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/invites/concerns/resend_invite.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # ResendInvite provides the core logic for resending invitations.
+      #
+      # Include this in your ResendInviteInteraction to get the default behavior,
+      # then override methods as needed.
+      #
+      # @example Basic usage
+      #   class ResendInviteInteraction < Plutonium::Resource::Interaction
+      #     include Plutonium::Invites::Concerns::ResendInvite
+      #   end
+      #
+      # @example With custom expiry
+      #   class ResendInviteInteraction < Plutonium::Resource::Interaction
+      #     include Plutonium::Invites::Concerns::ResendInvite
+      #
+      #     def new_expiry
+      #       2.weeks.from_now
+      #     end
+      #   end
+      #
+      module ResendInvite
+        extend ActiveSupport::Concern
+
+        included do
+          presents label: "Resend Invitation", icon: Phlex::TablerIcons::MailForward
+
+          attribute :resource
+        end
+
+        def execute
+          unless resource.pending?
+            return failed("Can only resend pending invitations")
+          end
+
+          resource.update!(expires_at: new_expiry)
+          send_invitation_email
+
+          succeed(resource).with_message(success_message)
+        rescue => error
+          failed("Failed to resend: #{error.message}")
+        end
+
+        private
+
+        # Override to customize expiry duration
+        def new_expiry
+          1.week.from_now
+        end
+
+        # Override to customize email sending
+        def send_invitation_email
+          resource.invitation_mailer.invitation(resource).deliver_later
+        end
+
+        # Override to customize success message
+        def success_message
+          "Invitation resent to #{resource.email}"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/invites/controller.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    # Controller provides the invitation acceptance flow for controllers.
+    #
+    # This concern handles:
+    # - Showing the invitation landing page
+    # - Accepting invitations for logged-in users
+    # - Signup flow for new users
+    # - Cookie management for pending invitations
+    #
+    # @example Basic usage
+    #   class UserInvitationsController < ApplicationController
+    #     include Plutonium::Invites::Controller
+    #
+    #     layout "invitation"
+    #
+    #     private
+    #
+    #     def invite_class
+    #       UserInvite
+    #     end
+    #
+    #     def after_accept_path
+    #       root_path
+    #     end
+    #
+    #     def login_path
+    #       rodauth.login_path
+    #     end
+    #   end
+    #
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :current_user if respond_to?(:helper_method)
+      end
+
+      # GET /invitations/:token
+      #
+      # Shows the invitation landing page. If the user is logged in,
+      # shows the acceptance form. If not, shows signup/login options.
+      def show
+        return unless (@invite = load_and_validate_invite(params[:token]))
+
+        # Store invitation token in cookie for later use
+        cookies.encrypted[:pending_invitation] = {
+          value: params[:token],
+          expires: 1.hour.from_now
+        }
+
+        if current_user
+          begin
+            @invite.validate_email_constraints!(current_user.email)
+            render :show
+          rescue ActiveRecord::RecordInvalid => e
+            @error_title = "Email Validation Error"
+            @error_message = e.record.errors.full_messages.join(", ")
+            render :error, status: :forbidden
+          end
+        else
+          render :landing
+        end
+      end
+
+      # POST /invitations/:token/accept
+      #
+      # Accepts the invitation for the currently logged-in user.
+      def accept
+        return unless (@invite = load_and_validate_invite(params[:token]))
+
+        unless current_user
+          redirect_to invitation_path(token: params[:token]),
+            alert: "Please sign in to accept this invitation"
+          return
+        end
+
+        @invite.accept_for_user!(current_user)
+        cookies.delete(:pending_invitation)
+
+        redirect_to after_accept_path,
+          notice: "Invitation accepted! Welcome to #{@invite.entity.to_label}!"
+      rescue ActiveRecord::RecordInvalid => e
+        @error_title = "Acceptance Error"
+        @error_message = e.record.errors.full_messages.join(", ")
+        render :error, status: :forbidden
+      end
+
+      # GET/POST /invitations/:token/signup
+      #
+      # Handles new user signup directly from the invitation.
+      def signup
+        return unless (@invite = load_and_validate_invite(params[:token]))
+
+        if request.post?
+          handle_signup_submission
+        else
+          render :signup
+        end
+      end
+
+      private
+
+      # Load and validate an invite by token.
+      #
+      # @param token [String] the invitation token
+      # @return [Object, nil] the invite or nil (renders error)
+      def load_and_validate_invite(token)
+        invite = invite_class.find_for_acceptance(token)
+
+        unless invite
+          @error_title = "Invalid or Expired Invitation"
+          @error_message = "This invitation link is no longer valid. It may have expired or already been used."
+          render :error, status: :not_found
+          return nil
+        end
+
+        invite
+      end
+
+      # Handle the signup form submission.
+      def handle_signup_submission
+        email = @invite.enforce_email? ? @invite.email : params[:email]
+        password = params[:password]
+        password_confirmation = params[:password_confirmation]
+
+        if password != password_confirmation
+          flash.now[:alert] = "Passwords don't match"
+          render :signup
+          return
+        end
+
+        begin
+          ActiveRecord::Base.transaction do
+            existing_user = user_class.find_by(email: email)
+            if existing_user
+              flash.now[:alert] = "An account with this email already exists. Please sign in instead."
+              render :signup
+              return
+            end
+
+            user = create_user_for_signup(email, password)
+
+            if user&.persisted?
+              @invite.accept_for_user!(user)
+              cookies.delete(:pending_invitation)
+              sign_in_user(user)
+              redirect_to after_accept_path
+            else
+              flash.now[:alert] = "Failed to create account"
+              render :signup
+            end
+          end
+        rescue ActiveRecord::RecordInvalid => e
+          if e.record.is_a?(invite_class)
+            flash.now[:alert] = e.record.errors.full_messages.join(", ")
+          else
+            flash.now[:alert] = "Failed to create account: #{e.record.errors.full_messages.join(", ")}"
+          end
+          render :signup
+        rescue => e
+          flash.now[:alert] = "Failed to create account: #{e.message}"
+          render :signup
+        end
+      end
+
+      # Override to specify the invite model class.
+      #
+      # @return [Class] the invite model class
+      # @raise [NotImplementedError] if not overridden
+      def invite_class
+        raise NotImplementedError, "#{self.class}#invite_class must return the invite model class"
+      end
+
+      # Override to specify the user model class.
+      #
+      # @return [Class] the user model class
+      def user_class
+        User
+      end
+
+      # Override to customize redirect after acceptance.
+      #
+      # @return [String] the path to redirect to
+      def after_accept_path
+        "/"
+      end
+
+      # Override to customize the login path.
+      #
+      # @return [String] the login path
+      def login_path
+        "/login"
+      end
+
+      # Override to create a user during signup.
+      #
+      # This method should be overridden to integrate with your
+      # authentication system (e.g., Rodauth).
+      #
+      # @param email [String] the user's email
+      # @param password [String] the user's password
+      # @return [Object] the created user
+      def create_user_for_signup(email, password)
+        raise NotImplementedError, "#{self.class}#create_user_for_signup must be implemented for signup flow"
+      end
+
+      # Override to sign in the user after signup.
+      #
+      # @param user [Object] the user to sign in
+      def sign_in_user(user)
+        # Override in controller to sign in the user
+        # e.g., for Rodauth: rodauth.account_from_login(user.email); rodauth.login("signup")
+      end
+
+      # Override to return the current logged-in user.
+      #
+      # @return [Object, nil] the current user or nil
+      def current_user
+        nil
+      end
+    end
+  end
+end

data/lib/plutonium/invites/pending_invite_check.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    # PendingInviteCheck provides post-login invitation handling.
+    #
+    # Include this in a controller that users land on after login
+    # (e.g., WelcomeController, DashboardController) to check for
+    # pending invitations stored in cookies.
+    #
+    # @example Basic usage
+    #   class WelcomeController < ApplicationController
+    #     include Plutonium::Invites::PendingInviteCheck
+    #
+    #     def index
+    #       return if redirect_to_pending_invite!
+    #
+    #       # Normal post-login flow...
+    #       redirect_to dashboard_path
+    #     end
+    #
+    #     private
+    #
+    #     def invite_class
+    #       Invites::UserInvite
+    #     end
+    #   end
+    #
+    module PendingInviteCheck
+      extend ActiveSupport::Concern
+
+      private
+
+      # Check for a pending invitation and redirect if found.
+      #
+      # @return [Boolean] true if redirected, false otherwise
+      def redirect_to_pending_invite!
+        token = cookies.encrypted[:pending_invitation]
+        return false unless token
+
+        invite = invite_class.find_for_acceptance(token)
+
+        if invite
+          redirect_to invitation_path(token: token)
+          true
+        else
+          cookies.delete(:pending_invitation)
+          false
+        end
+      end
+
+      # Returns the pending invite if one exists.
+      #
+      # @return [Object, nil] the pending invite or nil
+      def pending_invite
+        token = cookies.encrypted[:pending_invitation]
+        return nil unless token
+
+        invite = invite_class.find_for_acceptance(token)
+        unless invite
+          cookies.delete(:pending_invitation)
+          return nil
+        end
+
+        invite
+      end
+
+      # Override to specify the invite model class.
+      #
+      # @return [Class] the invite model class
+      def invite_class
+        raise NotImplementedError, "#{self.class}#invite_class must return the invite model class"
+      end
+    end
+  end
+end

data/lib/plutonium/invites.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+  end
+end