Module: Plutonium::Invites::Concerns::InviteToken

Extended by:
ActiveSupport::Concern
Defined in:
lib/plutonium/invites/concerns/invite_token.rb

Overview

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

Examples:

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

Instance Method Summary collapse

Instance Method Details

#accept_for_user!(user) ⇒ Object

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)

Parameters:

  • user (Object) —

    the user accepting the invitation

Raises:

  • (ActiveRecord::RecordInvalid) —

    if acceptance fails



124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 124

def accept_for_user!(user)
  validate_email_constraints!(user.email)

  transaction do
    update!(
      :state => :accepted,
      :accepted_at => Time.current,
      user_attribute => user
    )

    create_membership_for(user)
    notify_invitable(user)
  end
end

#create_membership_for(user) ⇒ Object

Override this method to create the entity membership.

Parameters:

  • user (Object) —

    the user who accepted the invitation

Raises:

  • (NotImplementedError) —

    if not overridden



159
160
161
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 159

def create_membership_for(user)
  raise NotImplementedError, "#{self.class}#create_membership_for must be implemented to create the membership record"
end

#enforce_domain ⇒ String?

Override in subclass to enforce email domain matching.

Returns:

  • (String, nil) —

    the domain to enforce, or nil to skip domain check



83
84
85
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 83

def enforce_domain
  nil
end

#enforce_email? ⇒ Boolean

Override in subclass to require exact email match.

Returns:

  • (Boolean) —

    true to require exact email match



90
91
92
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 90

def enforce_email?
  true
end

#invitation_mailer ⇒ Class

Override this method to specify the mailer class.

Returns:

  • (Class) —

    the mailer class for sending invitation emails

Raises:

  • (NotImplementedError) —

    if not overridden



151
152
153
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 151

def invitation_mailer
  raise NotImplementedError, "#{self.class}#invitation_mailer must be implemented to return the mailer class"
end

#user_attribute ⇒ Symbol

Override to specify the user association name on the invite model. Defaults to :user. Override when the invite model's belongs_to uses a different name (e.g., :spender_account, :staff_user).

Returns:

  • (Symbol) 


143
144
145
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 143

def user_attribute
  :user
end

#validate_email_constraints!(user_email) ⇒ Object

Validate email constraints against the accepting user's email.

Parameters:

  • user_email (String) —

    the email of the user accepting the invite

Raises:

  • (ActiveRecord::RecordInvalid) —

    if constraints are violated



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/plutonium/invites/concerns/invite_token.rb', line 98

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