plutonium 0.39.1 → 0.40.0

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

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Invites
+    module Concerns
+      # Invitable allows any model to trigger invites and be notified on acceptance.
+      #
+      # This pattern is useful when you have a profile or record that needs to
+      # invite a user and then connect itself to that user after acceptance.
+      #
+      # @example TenantProfile that invites users
+      #   class TenantProfile < ApplicationRecord
+      #     include Plutonium::Resource::Record
+      #     include Plutonium::Invites::Concerns::Invitable
+      #
+      #     belongs_to :entity
+      #     belongs_to :user, optional: true
+      #
+      #     def on_invite_accepted(user)
+      #       update!(user: user)
+      #     end
+      #   end
+      #
+      # @example Creating an invite from an invitable
+      #   tenant_profile.create_invite!(
+      #     email: tenant_profile.email,
+      #     entity: tenant_profile.entity,
+      #     invited_by: current_user,
+      #     role: :member,
+      #     email_template: "tenant"
+      #   )
+      #
+      module Invitable
+        extend ActiveSupport::Concern
+
+        included do
+          # Association to the pending user invite for this record.
+          # Scoped to pending only - cancelled/expired/accepted invites are kept for audit.
+          has_one :user_invite, -> { pending }, class_name: "Invites::UserInvite", as: :invitable
+        end
+
+        # Create an invite for this invitable.
+        #
+        # If there's already a pending invite for this invitable, it will be
+        # destroyed and replaced with a new one.
+        #
+        # @param email [String] the email address to invite
+        # @param entity [Object] the entity to join
+        # @param invited_by [Object] the user creating the invite
+        # @param role [Symbol, String] the role to assign (default: nil, uses model default)
+        # @param email_template [String, nil] optional template type for email customization
+        # @return [Object] the created invite record
+        def create_invite!(email:, entity:, invited_by:, role: nil, email_template: nil)
+          # Cancel any existing pending invite first (association is already scoped to pending)
+          user_invite&.cancelled!
+
+          attrs = {
+            email: email,
+            entity: entity,
+            invited_by: invited_by,
+            email_template: email_template
+          }
+          attrs[:role] = role if role.present?
+
+          create_user_invite!(attrs)
+        end
+
+        # Check if there's an active pending invite.
+        #
+        # @return [Boolean] true if there's a pending invite
+        def has_pending_invite?
+          user_invite.present?
+        end
+
+        # Check if this invitable can receive an invitation.
+        #
+        # Override this method to customize the logic. The default implementation
+        # returns true if no user is attached and no pending invite exists.
+        #
+        # @return [Boolean] true if invitation can be sent
+        def can_invite_user?
+          !user.present? && !has_pending_invite?
+        end
+
+        # Called when the invited user accepts and joins the entity.
+        #
+        # Override this method in your model to handle the acceptance,
+        # typically to connect the invitable to the user.
+        #
+        # @param user [Object] the user who accepted the invite
+        # @raise [NotImplementedError] if not overridden
+        def on_invite_accepted(user)
+          raise NotImplementedError, "#{self.class.name} must implement #on_invite_accepted(user)"
+        end
+      end
+    end
+  end
+end

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