plutonium 0.50.0 → 0.52.0

data/docs/guides/troubleshooting.md

@@ -77,6 +77,8 @@ If you encounter an issue not covered here, please [open an issue](https://githu
 
 ## Related
 
-- [Nested Resources Guide](./nested-resources)
-- [Adding Resources Guide](./adding-resources)
-- [Rails Inflections Documentation](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)
+- [Nested resources](./nested-resources)
+- [Adding resources](./adding-resources)
+- [Reference › Behavior › Controllers](/reference/behavior/controllers) — `controller_for`, `resource_url_for`, `current_parent`
+- [Reference › Tenancy › Nested resources](/reference/tenancy/nested-resources) — nested URL generation
+- [Rails Inflections](https://api.rubyonrails.org/classes/ActiveSupport/Inflector/Inflections.html)

data/docs/guides/user-invites.md

@@ -1,561 +1,248 @@
 # User Invites
 
-Plutonium provides a complete user invitation system for multi-tenant applications. This guide covers setting up invitations, customizing the flow, and integrating with your portals.
+Set up token-based email invitations so admins can invite users into a tenant's membership.
 
-## Overview
+## Goal
 
-The invitation system handles:
-- **Email Invitations**: Send secure invitation links to new or existing users
-- **Token Validation**: Time-limited tokens with automatic expiration
-- **Rodauth Integration**: Seamless signup and login flows
-- **Entity Memberships**: Automatic membership creation on acceptance
-- **Invitable Models**: Notify models when their invitations are accepted
+An admin enters an email, the user gets an invite link, clicks it, signs up (or logs in if they already have an account) with that email, and is added to the org as a member.
 
 ## Prerequisites
 
-Before installing invites, ensure you have:
+You need a user model, an entity model, and a membership model. The fastest path is `pu:saas:setup` — it creates all three and runs `pu:invites:install` automatically:
 
-1. **User Authentication**: A Rodauth user account
-2. **Entity Model**: An organization/company/team model
-3. **Membership Model**: A join model linking users to entities
-
-The easiest way to set this up is with the SaaS generator:
 ```bash
-rails g pu:saas:setup --user User --entity Organization
+rails g pu:saas:setup --user Customer --entity Organization
 ```
 
-## Installation
+For manual setup, ensure all three exist before running `pu:invites:install`.
+
+## Manual install
 
-### Step 1: Install the Invites Package
+### 1. Run the generator
 
 ```bash
 rails generate pu:invites:install
 ```
 
-With custom models:
+Or with custom models:
 
 ```bash
 rails g pu:invites:install \
   --entity-model=Organization \
-  --user-model=User \
-  --membership-model=OrganizationUser \
-  --roles=member,manager,admin
+  --user-model=Customer \
+  --membership-model=OrganizationCustomer
 ```
 
-### Options
-
 | Option | Default | Description |
-|--------|---------|-------------|
-| `--entity-model` | Entity | Entity model for scoping invites |
-| `--user-model` | User | User account model |
-| `--invite-model` | `<EntityModel><UserModel>Invite` | Invite class name. Omit for single-flow apps; set per-invocation to run the generator more than once for distinct flows. |
-| `--membership-model` | EntityUser | Join model for memberships |
-| `--roles` | member,admin | Available invitation roles |
-| `--rodauth` | user | Rodauth configuration name |
-| `--enforce-domain` | false | Require email domain matching |
+|---|---|---|
+| `--entity-model=NAME` | `Entity` | Entity model |
+| `--user-model=NAME` | `User` | User model |
+| `--invite-model=NAME` | `<EntityModel><UserModel>Invite` | Invite class name |
+| `--membership-model=NAME` | `EntityUser` | Membership join model (must already exist) |
+| `--rodauth=NAME` | `user` | Rodauth configuration for signup |
+| `--enforce-domain` | `false` | Require email domain to match entity |
 
-### Step 2: Run Migrations
+::: info Roles come from the membership model
+`pu:invites:install` reads the role list from the membership model's `enum :role` — it does not accept a `--roles=` flag. Define roles when you generate the membership model (`pu:saas:membership --roles=...`), or edit the enum directly. **Index 0 is the most privileged** (typically `owner`); the invite interaction excludes `owner` from selectable choices and defaults new invitees to the second role.
+:::
+
+### 2. Migrate
 
 ```bash
 rails db:migrate
 ```
 
-### Step 3: Configure Your Portal
-
-Register the invites package in your portal:
+### 3. Connect to your portal
 
 ```ruby
 # packages/customer_portal/lib/engine.rb
 module CustomerPortal
   class Engine < Rails::Engine
     include Plutonium::Portal::Engine
-
     register_package Invites::Engine
   end
 end
 ```
 
-## Generated Files
+### 4. Wire the post-login redirect
 
-The generator creates a complete `packages/invites/` package:
+```ruby
+# app/rodauth/user_rodauth_plugin.rb
+configure do
+  login_return_to_requested_location? true
+  login_redirect "/welcome"
 
-```
-packages/invites/
-├── app/
-│   ├── controllers/invites/
-│   │   ├── user_invitations_controller.rb  # Invitation acceptance
-│   │   └── welcome_controller.rb           # Post-login landing
-│   ├── definitions/invites/
-│   │   └── user_invite_definition.rb       # UI configuration
-│   ├── interactions/invites/
-│   │   ├── cancel_invite_interaction.rb    # Cancel action
-│   │   └── resend_invite_interaction.rb    # Resend action
-│   ├── mailers/invites/
-│   │   └── user_invite_mailer.rb           # Invitation emails
-│   ├── models/invites/
-│   │   └── user_invite.rb                  # Invite model
-│   ├── policies/invites/
-│   │   └── user_invite_policy.rb           # Authorization
-│   └── views/invites/
-│       ├── user_invitations/               # Acceptance views
-│       ├── user_invite_mailer/             # Email templates
-│       └── welcome/                        # Welcome page
-└── lib/
-    └── engine.rb                           # Package engine
+  after_login do
+    session[:after_welcome_redirect] = session.delete(:login_redirect)
+  end
+end
 ```
 
-## Invitation Flow
+Now users are redirected to `/welcome` after login, where pending invites are shown.
 
-### Sending Invitations
+## The flow
 
-Admins can invite users from the entity detail page or user management:
+### 1. Admin sends the invite
 
 ```ruby
-# The generated action in your entity definition
-action :invite_user,
-  interaction: Organization::InviteUserInteraction,
-  category: :secondary
+entity.invite_user(email: "user@example.com", role: :member)
 ```
 
-The interaction creates an `Invites::UserInvite` record and sends an email:
+Or via the auto-generated "Invite User" action on the entity's show page.
 
-```ruby
-# Generated interaction
-class Organization::InviteUserInteraction < Plutonium::Interaction::Base
-  attribute :email, :string
-  attribute :role, :string, default: "member"
-
-  validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-
-  def execute
-    invite = Invites::UserInvite.create!(
-      entity: resource,
-      email: email,
-      role: role,
-      invited_by: current_user
-    )
-
-    succeed(invite)
-      .with_message("Invitation sent to #{email}")
-  end
-end
-```
+### 2. Email goes out
+
+Token-based URL: `https://app.example.com/invitations/abc123...`
 
-### Accepting Invitations
+### 3. User accepts
 
-#### Existing Users
+Clicking the link lands on the invitation page:
 
-1. User receives email with invitation link
-2. Clicks link, sees invitation details
-3. If logged in with matching email, accepts directly
-4. If not logged in, redirected to login
-5. After login, redirected back to accept
+![Invitation landing page](/images/guides/user-invites-landing.png)
 
-#### New Users
+**Existing user:** clicks link → logs in (or already logged in) → email validated → membership created.
 
-1. User receives email with invitation link
-2. Clicks link, sees invitation details
-3. Clicks "Create Account"
-4. Signs up with the invited email address
-5. After signup, automatically accepts invitation
+**New user:** clicks link → "Create Account" → signs up with the invited email → membership created.
 
-### Post-Login Welcome
+### 4. After login
 
-After login, users land on `/welcome` where pending invitations are displayed:
+Users land on `/welcome` where pending invites are shown. Including `Plutonium::Invites::PendingInviteCheck`:
 
 ```ruby
-# The WelcomeController checks for pending invites
-class Invites::WelcomeController < ApplicationController
-  def index
-    @pending_invites = Invites::UserInvite
-      .pending
-      .where(email: current_user.email)
-
-    if @pending_invites.any?
-      render :pending_invitation
-    else
-      redirect_to session.delete(:after_welcome_redirect) || root_path
-    end
-  end
-end
+include Plutonium::Invites::PendingInviteCheck
 ```
 
-## Invitables
-
-Invitables are models that trigger invitations and receive callbacks when accepted. Use this when you need to:
-- Create a record that requires a user to be assigned
-- Notify specific models when their invitation is accepted
-- Customize invitation behavior per model type
+## Invitables — app models notified on acceptance
 
-### Creating an Invitable
+An invitable is a model that gets notified when its invitation is accepted. Examples: `Tenant`, `TeamMember`, `ProjectCollaborator`.
 
 ```bash
 rails g pu:invites:invitable Tenant
 rails g pu:invites:invitable TeamMember --role=member
 ```
 
-### Implementing the Callback
+Then implement the callback:
 
 ```ruby
-# app/models/tenant.rb
 class Tenant < ApplicationRecord
   include Plutonium::Invites::Concerns::Invitable
 
-  belongs_to :organization
+  belongs_to :entity
   belongs_to :user, optional: true
 
-  # Called when the invitation is accepted
   def on_invite_accepted(user)
-    update!(
-      user: user,
-      status: :active,
-      activated_at: Time.current
-    )
+    update!(user: user, status: :active)
   end
 end
 ```
 
-### How Invitables Work
+::: warning Without `on_invite_accepted`
+The invitable never learns about the new user — the invite is consumed but your app doesn't update its state.
+:::
 
-When creating an invite from an invitable:
+## Multiple invite flows in one app
 
-```ruby
-# The invitable triggers the invitation
-tenant.invite_user(email: "user@example.com")
+Run `pu:invites:install` once per flow with different `--entity-model` / `--user-model` / `--invite-model`:
+
+```bash
+rails g pu:invites:install \
+  --entity-model=FunderOrganization \
+  --user-model=SpenderAccount \
+  --invite-model=FunderInvite
 
-# Creates UserInvite with:
-# - invitable_type: "Tenant"
-# - invitable_id: tenant.id
+rails g pu:invites:install \
+  --entity-model=Project \
+  --user-model=Member \
+  --invite-model=ProjectInvite
 ```
 
-When the invite is accepted:
+Each invocation creates an independent flow: model, controller, route, helper all named for the invite-model.
 
-```ruby
-# System calls:
-invite.accept_for_user!(user)
+The shared `Invites::WelcomeController` accumulates each new class into its `invite_classes` array — `pending_invite` checks all flows in priority order (first-match wins).
 
-# Which internally:
-# 1. Creates entity membership
-# 2. Calls tenant.on_invite_accepted(user)
-```
+See [Reference › Tenancy › Invites › Multiple invite flows](/reference/tenancy/invites#multiple-invite-flows).
 
 ## Customization
 
-### Custom Email Templates
+### Email templates
 
-Override the default templates:
+Override views in your package:
 
 ```erb
 <%# packages/invites/app/views/invites/user_invite_mailer/invitation.html.erb %>
-<!DOCTYPE html>
-<html>
-<body>
-  <h1>Welcome to <%= @invite.entity.name %>!</h1>
-
-  <p>
-    <%= @invite.invited_by.email %> has invited you to join
-    as a <%= @invite.role %>.
-  </p>
-
-  <p>
-    <%= link_to "Accept Invitation", @invitation_url,
-        style: "background: #4F46E5; color: white; padding: 12px 24px;" %>
-  </p>
-
-  <p>This invitation expires in 7 days.</p>
-</body>
-</html>
+<h1>Welcome to <%= @invite.entity.name %>!</h1>
+<p><%= @invite.invited_by.email %> has invited you.</p>
+<p><%= link_to "Accept", @invitation_url %></p>
 ```
 
-### Per-Invitable Templates
-
-Create model-specific email templates:
-
-```erb
-<%# packages/invites/app/views/invites/user_invite_mailer/invitation_tenant.html.erb %>
-<h1>You've been assigned as a tenant!</h1>
-<p>Accept to access your tenant dashboard.</p>
-```
-
-### Custom Validation
-
-Add validation to the invite model:
+### Custom validation
 
 ```ruby
-# packages/invites/app/models/invites/user_invite.rb
 class Invites::UserInvite < Invites::ResourceRecord
   validate :email_not_already_member
-  validate :within_invite_limit
 
   private
 
   def email_not_already_member
-    if entity.users.exists?(email: email)
-      errors.add(:email, "is already a member of this organization")
-    end
-  end
-
-  def within_invite_limit
-    pending_count = entity.user_invites.pending.count
-    if pending_count >= 100
-      errors.add(:base, "Maximum pending invitations reached")
-    end
+    existing = membership_model.joins(:user)
+      .where(entity: entity, users: {email: email}).exists?
+    errors.add(:email, "is already a member") if existing
   end
 end
 ```
 
-### Domain Enforcement
-
-Require invited emails to match the entity's domain:
+### Domain enforcement
 
 ```bash
 rails g pu:invites:install --enforce-domain
 ```
 
-Or implement custom domain logic:
-
-```ruby
-# packages/invites/app/models/invites/user_invite.rb
-def enforce_domain
-  entity.domain  # e.g., "acme.com"
-end
-```
-
-### Custom Expiration
-
-Change the default expiration time:
-
-```ruby
-# packages/invites/app/models/invites/user_invite.rb
-private
-
-def set_token_defaults
-  self.token ||= SecureRandom.urlsafe_base64(32)
-  self.expires_at ||= 3.days.from_now  # Override default 1 week
-end
-```
-
-## Managing Invitations
-
-### Resend Invitation
-
-The generated `ResendInviteInteraction` allows resending:
-
-```ruby
-# Resets expiration and sends new email
-invite.resend!
-```
-
-### Cancel Invitation
-
-```ruby
-invite.cancel!
-# Sets state to :cancelled
-```
-
-### View Pending Invitations
-
-In your admin portal:
-
-```ruby
-# Invites are scoped to the current entity
-# Admins see all pending invites for their organization
-Invites::UserInvite.pending.where(entity: current_scoped_entity)
-```
-
-## Security Considerations
-
-### Token Security
-
-- Tokens are 32-byte URL-safe base64 strings
-- Tokens expire after 1 week by default
-- Each invite has a unique token
-
-### Email Validation
-
-By default, the accepting user's email must match the invited email:
-
-```ruby
-def enforce_email?
-  true  # Default: require exact match
-end
-```
-
-### Rate Limiting
+Requires the invited email domain to match the entity's domain.
 
-Consider adding rate limiting to prevent abuse:
+### Custom expiration
 
 ```ruby
-# In your interaction
-validate :rate_limit_invites
-
-def rate_limit_invites
-  recent = Invites::UserInvite
-    .where(invited_by: current_user)
-    .where("created_at > ?", 1.hour.ago)
-    .count
+class Invites::UserInvite < Invites::ResourceRecord
+  TOKEN_EXPIRATION = 30.days   # default: 1 week
 
-  if recent >= 50
-    errors.add(:base, "Too many invitations sent. Please wait.")
+  def expired?
+    created_at < TOKEN_EXPIRATION.ago
   end
 end
 ```
 
-## Troubleshooting
-
-### "Invitation not found or expired"
-
-- Check that the token hasn't expired (default: 1 week)
-- Verify the invite is still `pending` (not cancelled or accepted)
-- Ensure the URL is complete and not truncated
-
-### "Email mismatch" Error
-
-The system requires the accepting user's email to match:
-
-```
-This invitation is for user@example.com.
-You must use an account with that email address.
-```
-
-If you need to allow any email:
+## Managing invitations
 
 ```ruby
-def enforce_email?
-  false  # Not recommended for security
-end
-```
-
-### Rodauth Not Redirecting Properly
-
-Ensure your Rodauth plugin is configured:
+invite.resend!    # generates new token + sends email
+invite.cancel!    # transitions to :cancelled state
 
-```ruby
-# app/rodauth/user_rodauth_plugin.rb
-configure do
-  login_return_to_requested_location? true
-  login_redirect "/welcome"
-
-  after_login do
-    session[:after_welcome_redirect] = session.delete(:login_redirect)
-  end
-end
+entity.user_invites.pending    # list pending
 ```
 
-### Invitable Callback Not Called
+## Security
 
-Ensure your model includes the concern and implements the callback:
+- **Token security** — `SecureRandom.urlsafe_base64(32)` — 256 bits, URL-safe. Stored hashed, raw token shown only at creation.
+- **Email validation** — `enforce_email?` is `true` by default. The accepting user's email must match the invited email — prevents account hijacking via invite forwarding.
+- **Rate limiting** — use Rack::Attack or similar to throttle invite creation per admin and acceptance attempts per IP.
 
+::: danger Don't disable enforce_email?
 ```ruby
-class Tenant < ApplicationRecord
-  include Plutonium::Invites::Concerns::Invitable
-
-  def on_invite_accepted(user)
-    # This MUST be implemented
-    update!(user: user)
-  end
-end
+def enforce_email? = false   # ← only if you fully understand the trade-off
 ```
+Without this, anyone with the token can sign up — defeats the purpose of an invitation system.
+:::
 
-## API Reference
-
-### UserInvite States
-
-| State | Description |
-|-------|-------------|
-| `pending` | Awaiting acceptance |
-| `accepted` | Successfully accepted |
-| `expired` | Past expiration date |
-| `cancelled` | Manually cancelled |
-
-### Key Methods
-
-```ruby
-# Find valid invite
-invite = Invites::UserInvite.find_for_acceptance(token)
-
-# Accept invitation
-invite.accept_for_user!(user)
-
-# Resend email
-invite.resend!
-
-# Cancel
-invite.cancel!
-
-# Check state
-invite.pending?
-invite.accepted?
-invite.expired?
-invite.cancelled?
-```
-
-## Multiple invite flows in one app
-
-Some apps invite users to several distinct kinds of entity — for example, customers joining organizations and funders joining projects. Run `pu:invites:install` once per flow; each invocation produces independent migrations, models, policies, definitions, mailers, controllers, view templates, and route helpers.
-
-### Default-derivation rule
-
-When you omit `--invite-model`, the generator derives the class name as `<EntityModel><UserModel>Invite`. With the defaults (`--entity-model=Organization --user-model=User`) the generated class is `Invites::OrganizationUserInvite` — there is no literal `UserInvite` default. Single-flow apps never need to pass `--invite-model`.
-
-Multi-flow apps either:
-
-- Run the generator more than once with the **same** entity/user but different `--invite-model` values (rare), or
-- Run with **different** `--entity-model` / `--user-model` pairs (common). Different derivations make `--invite-model` unnecessary; pass it only when you want a custom class name.
-
-```bash
-rails g pu:invites:install \
-  --entity-model=FunderOrganization \
-  --user-model=SpenderAccount \
-  --invite-model=FunderInvite
-
-rails g pu:invites:install \
-  --entity-model=Project \
-  --user-model=Member \
-  --invite-model=ProjectInvite
-```
-
-After the second invocation you'll have, for example, `Invites::FunderInvite` on table `funder_invites` with controller `Invites::FunderInvitationsController` mounted at `/funder_invitations/:token`, alongside `Invites::ProjectInvite` on `project_invites` mounted at `/project_invitations/:token`. Route helpers are prefixed (`funder_invitation_path`, `project_invitation_path`).
-
-### How the welcome flow finds pending invites
-
-The shared `Invites::WelcomeController` keeps a running list of invite classes. Each install run injects its class into the array, preserving order:
-
-```ruby
-# packages/invites/app/controllers/invites/welcome_controller.rb
-def invite_classes
-  [::Invites::FunderInvite, ::Invites::ProjectInvite]
-end
-```
-
-After login, `Plutonium::Invites::PendingInviteCheck#pending_invite` iterates `invite_classes` and returns the first valid pending invite for the cookie-stored token (first-match wins). Plug a third-party invite class in by overriding `invite_classes` directly:
-
-```ruby
-class WelcomeController < ApplicationController
-  include Plutonium::Invites::PendingInviteCheck
-
-  def invite_classes
-    [::Invites::FunderInvite, ::Invites::ProjectInvite, ::Foreign::ApiInvite]
-  end
-end
-```
-
-### Per-flow controller overrides
-
-The install generator emits an `invitation_path_for` override on each invitations controller so post-login redirects target the correct prefixed route:
-
-```ruby
-# packages/invites/app/controllers/invites/funder_invitations_controller.rb
-def invitation_path_for(token)
-  funder_invitation_path(token: token)
-end
-```
+## Common issues
 
-You won't normally edit this — but it's worth knowing the hook exists, because that's how multi-flow controllers stay independent from the shared `Plutonium::Invites::Controller` concern.
+- **"Invitation not found or expired"** — token expired (default 1 week), invite cancelled, or no longer `pending`.
+- **Email mismatch error** — the accepting user's email doesn't match the invited email. This is by design (security).
+- **Rodauth redirect after login doesn't go to `/welcome`** — check `login_redirect "/welcome"` in the rodauth plugin's `configure` block.
+- **`on_invite_accepted` not called** — ensure the invitable model `include Plutonium::Invites::Concerns::Invitable` and defines `on_invite_accepted`.
 
-## Next Steps
+## Related
 
-- [Authentication](/guides/authentication) - Set up Rodauth
-- [Authorization](/guides/authorization) - Configure policies
-- [Custom Actions](/guides/custom-actions) - Add more invite actions
-- [Multi-tenancy](/guides/multi-tenancy) - Entity scoping
+- [Reference › Tenancy › Invites](/reference/tenancy/invites) — full surface, multi-flow apps, customization
+- [Multi-tenancy](./multi-tenancy) — entity scoping (invites are entity-scoped automatically)
+- [Authentication](./authentication) — Rodauth setup
+- [User profile](./user-profile) — account-settings page