rails_authentication 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6369064c5074eb057abc1ed169b7efbe7ae0758730dc6c764b86fee19f96b0d3
-  data.tar.gz: 5bdc5cb01eb60fed2449f0a1544d29102c79f917faf345f86a1a86bca6b6adc6
+  metadata.gz: fcff113ea0549fb291f38ebe6d9ef6d7306bb2c4a444cb01d7f2bd99a21626ef
+  data.tar.gz: 33fb15023005e91589fb07fe846748e7c7af9876fae8b517bef98dee41994ebf
 SHA512:
-  metadata.gz: da49badfb4b8c58c2525329479154961cb10cbd6b6d683a4dbc56171198e9ad1d1f31d097455f106d47d19332a14391ee0e4370394aa23535e85b47be6ebf0f8
-  data.tar.gz: 4407fbc0f0c7daafc4324fb1e0ba7c366c4c810fa81b579bf464fd2f2e31b7d5e3da6c6e8741b189e0399a28660b4e0a728d80b1bfec63282eee3f8c0d204756
+  metadata.gz: 0c0849f4c52e57761a6d43a555b2c70712be764c96dc205ec10805ba983637777e53d1326e1b41b106c4ad7baeae258680e073aec19e47a42f08d9fce2b731f9
+  data.tar.gz: 8f1021d0c9e8c7a7ef71f791a83b24948af32b628154671b1dce31ad8cfe2299d5234a278412a45cff9b11fdc81201281ebbdd89ea391a49d7a41664bba14e03

data/README.md

@@ -99,9 +99,53 @@ the generated concerns — e.g. `TimeoutableConcern::TIMEOUT_IN`, `LockableConce
 `ValidatableConcern::PASSWORD_LENGTH`, `ValidatableConcern::PASSWORD_MINIMUM_COMPLEXITY`,
 `OttConcern::OTT_CODE_LENGTH` — edit them there. Concerns keep the model clean.
 
-### Generated routes
+### Inviting users
+
+Invitable generates a `User.invite!` class method. It takes a **hash of attributes** for the new
+user (not just an email address) plus an optional `invited_by:`:
 
+```ruby
+User.invite!({ email_address: "new@example.com" }, invited_by: Current.user)
+
+# Any other attributes your User requires go in the same hash
+User.invite!({ email_address: "new@example.com", name: "Ada Lovelace" }, invited_by: Current.user)
 ```
+
+`invite!` accepts symbol or string keys, or permitted `ActionController::Parameters`. It
+returns the user either way, so check `persisted?` and `errors` to see whether it worked.
+
+- **New email address**: the user is built from the attributes and gets a random temporary
+  password, a fresh invitation token, and `invited_by`, then is saved. On success the invitation
+  email is sent and the inviter's `invitations_count` goes up. On a validation failure it returns
+  the unsaved user with `errors` and sends nothing.
+- **Existing pending invitee**: the token is refreshed and the invitation re-sent. The other
+  attributes are ignored.
+- **Existing user who isn't a pending invitee**: the user is returned untouched, the other
+  attributes are ignored, and no email is sent.
+
+Any `password` in the hash is overwritten with the temporary one, because invitees choose their
+own password when they accept. Everything else is mass-assigned, so pass only attributes you've
+permitted. Never pass raw `params`.
+
+**Upgrading from the email-only signature.** Earlier versions took the email address as a string,
+`User.invite!(email_address, invited_by: ...)`. That form no longer works, so wrap the address in
+a hash: `User.invite!({ email_address: email_address }, invited_by: ...)`.
+
+**Requiring more than an email address.** The generated `InvitationsController` passes
+`invitation_params` (`params.permit(:email_address)`) to `invite!`. To collect more fields, add
+them in three places: the `permit` list, the inputs in `app/views/invitations/new.html.erb`, and
+the validations on your model:
+
+```ruby
+# app/controllers/invitations_controller.rb
+def invitation_params
+  params.permit(:email_address, :name)
+end
+```
+
+### Generated routes
+
+```ruby
 resource  :registration, only: %i[ new create edit update destroy ]
 resources :confirmations, only: %i[ new create show ], param: :token
 resources :unlocks,       only: %i[ new create show ], param: :token

data/lib/generators/authentication/templates/app/controllers/invitations_controller.rb.tt

@@ -6,7 +6,7 @@ class InvitationsController < ApplicationController
   end
 
   def create
-    user = User.invite!(params[:email_address], invited_by: Current.user)
+    user = User.invite!(invitation_params, invited_by: Current.user)
 
     if user.persisted?
       redirect_to new_invitation_path, notice: "Invitation sent to #{user.email_address}."
@@ -29,6 +29,11 @@ class InvitationsController < ApplicationController
 
   private
 
+  # Add any other attributes your User requires (e.g. :name) here and to the invitation form.
+  def invitation_params
+    params.permit(:email_address)
+  end
+
   def set_user_by_token
     @user = User.find_by_valid_invitation_token(params[:token])
     redirect_to new_session_path, alert: "Invitation link is invalid or has expired." unless @user

data/lib/generators/authentication/templates/app/models/concerns/invitable_concern.rb.tt

@@ -8,8 +8,9 @@ module InvitableConcern
   end
 
   class_methods do
-    def invite!(email_address, invited_by: nil)
-      user = find_by(email_address: email_address)
+    def invite!(attributes, invited_by: nil)
+      attributes = attributes.to_h.symbolize_keys
+      user = find_by(email_address: attributes[:email_address])
 
       if user
         # Re-inviting an existing pending invitee refreshes their token; anyone else
@@ -23,8 +24,8 @@ module InvitableConcern
         return user
       end
 
-      user = new(
-        email_address: email_address,
+      user = new(attributes)
+      user.assign_attributes(
         password: generate_temporary_password,
         invited_by: invited_by,
         invitation_token: generate_invitable_token,

data/lib/rails_authentication/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsAuthentication
-  VERSION = "0.5.0"
+  VERSION = "0.6.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_authentication
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - David Freerksen
@@ -132,7 +132,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Devise-style features on top of Rails 8's built-in authentication generator
 test_files: []