organizations 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ca06945acfae769816fdc7c19ba44778791697325d1f59967fb4794c7b8a274
-  data.tar.gz: 9601aa8b0835819532b1aed0a79a410ef4bf51f023b90088c463950dff5616c0
+  metadata.gz: 9182741872f9485ca52d426a687201fc785e5959a79fa3e4acd6b8af6e0fa9e5
+  data.tar.gz: 4836859405283c87543e3470e4d3cfeaf543096c76bf2589efed04099ea5112d
 SHA512:
-  metadata.gz: 666c1b825cb64d0d822d654bf1db23c6672b993e7769369d43b0afb01480e13218511b1bd7da4c100b5761360049f9408c6c74a33a177a8e86b34ce6cab27efa
-  data.tar.gz: 6416fb315eb949d06672665f5909bcf463976d265a05bbcdbc508978f5f20c6ccf9367c64c8a94ccbe1e8da57eeb934b3d12354dd9adb40ed51f00a9421f2883
+  metadata.gz: eedcce955043e1aa3bd6c0a10ed0ecc8d61d89f004176c90df5c048badbc5e8f8db6d473eeb863bdb5e0716a0b66cd543cacd7f9f8ce588e9a2702992b7b56ff
+  data.tar.gz: ff8cc67de84d9e9964d1888ea8404d3d10f80c271240551c1d4b8a77d3c0e3da199abdcc5c779e793d400197fc3b2c987b19a2410146b9f07c106942846c454d

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.3.0] - 2026-02-20
+
+- Invitation onboarding is now first-class and configurable, so host apps can remove most custom signup/invite glue code.
+- Public invitation flows now work with Devise out of the box under the default public controller setup.
+- Redirect behavior is now configurable for auth-required invitation acceptance, post-acceptance, post-switch, and no-organization flows.
+- Invitation acceptance now returns structured success/failure objects, making controller handling clearer and safer.
+- Switching and current-user resolution were hardened for auth-transition and stale-cache edge cases.
+- Engine views now delegate host-app route helpers more cleanly, reducing `main_app.` boilerplate in host layouts/partials.
+- `create_organization!` now forwards full attribute hashes, enabling custom organization validations/fields without workarounds.
+- Performance improved: owner lookup avoids unnecessary SQL when memberships are preloaded (lower N+1 risk on list/admin pages).
+- Test coverage expanded significantly around invitation flow, switching behavior, current-user resolution, and configuration contracts.
+
+## [0.2.0] - 2026-02-20
+
+- Namespaced all tables with `organizations_` prefix to prevent collisions with host apps
+
 ## [0.1.1] - 2026-02-19
 
 - Removed `slugifiable` dependency (deferred to host app)

data/README.md

@@ -7,6 +7,8 @@
 
 `organizations` adds organizations with members to any Rails app. It handles team invites, user memberships, roles, and permissions.
 
+**🎮 [Try the live demo →](https://organizations.rameerez.com)**
+
 [TODO: invitation / member management gif]
 
 It's everything you need to turn a `User`-based app into a multi-tenant, `Organization`-based B2B SaaS (users belong in organizations, and organizations share resources and billing, etc.)
@@ -369,6 +371,36 @@ current_organization            # Active organization (from session)
 current_membership              # Current user's membership in active org
 organization_signed_in?         # Is there an active organization?
 
+# Pending invitation helpers
+pending_organization_invitation_token   # Get pending invitation token from session
+pending_organization_invitation         # Get pending invitation (clears if expired)
+pending_organization_invitation?        # Check if valid pending invitation exists
+pending_organization_invitation_email   # Get invited email (for signup prefill)
+clear_pending_organization_invitation!  # Clear invitation token and cache
+
+# Invitation acceptance (canonical helper for post-signup flows)
+accept_pending_organization_invitation!(user)                    # Accept with session token
+accept_pending_organization_invitation!(user, token: token)      # Explicit token
+accept_pending_organization_invitation!(user, switch: false)     # Don't auto-switch org
+accept_pending_organization_invitation!(user, return_failure: true) # Returns failure object on rejection
+pending_invitation_acceptance_redirect_path_for(user)            # Accept + resolve redirect path
+handle_pending_invitation_acceptance_for(user, redirect: true)   # Accept + optionally redirect
+# Returns InvitationAcceptanceResult or nil
+
+# Invitation redirect helpers
+redirect_path_when_invitation_requires_authentication(invitation)  # Get auth redirect
+redirect_path_after_invitation_accepted(invitation, user: user)    # Get post-accept redirect
+redirect_path_after_organization_switched(org, user: user)         # Get post-switch redirect
+
+# No-organization helpers
+redirect_path_when_no_organization(user: nil)                     # Resolve configured no-org redirect path
+no_organization_redirect_path                                     # Alias
+redirect_to_no_organization!(alert: "...", notice: "...")         # Redirect and return false
+
+# Organization creation helper
+create_organization_and_switch!(current_user, name: "Acme")       # Create and set context in one call
+create_organization_with_context!(current_user, name: "Acme")     # Backward-compatible alias
+
 # Authorization
 require_organization!                               # Redirect if no active org
 require_organization_role!(:admin)                  # Require at least admin role
@@ -379,7 +411,8 @@ require_organization_owner!     # Same as require_organization_role!(:owner)
 require_organization_admin!     # Same as require_organization_role!(:admin)
 
 # Switching
-switch_to_organization!(org)       # Change active org in session
+switch_to_organization!(org)              # Change active org in session
+switch_to_organization!(org, user: user)  # Explicit user (for auth-transition flows)
 ```
 
 ### Protecting resources
@@ -629,21 +662,80 @@ The gem handles **both existing users and new signups** with a single invitation
 2. User clicks link → Sees invitation details + "Sign up to accept" button
 3. User registers → Token stored in session, your app calls `invitation.accept!(user)` post-signup
 
-The gem stores the invitation token in `session[:pending_invitation_token]` when an unauthenticated user tries to accept. In your registration callback, check for this token and accept the invitation:
+The gem stores the invitation token in `session[:organizations_pending_invitation_token]` when an unauthenticated user tries to accept. Use the built-in helper to accept the invitation in your auth callbacks:
+
+```ruby
+# In your ApplicationController (works with Devise or any auth system)
+def after_sign_in_path_for(resource)
+  if (path = pending_invitation_acceptance_redirect_path_for(resource))
+    return path
+  end
+  super
+end
+
+def after_sign_up_path_for(resource)
+  if (path = pending_invitation_acceptance_redirect_path_for(resource))
+    return path
+  end
+  super
+end
+```
+
+The `accept_pending_organization_invitation!` helper handles:
+- Token lookup from session
+- Invitation validation (expired, already accepted, email match)
+- Membership creation
+- Organization context switching
+- Session cleanup
+
+It returns an `InvitationAcceptanceResult` object or `nil`:
 
 ```ruby
-# In your User model or registration controller
-after_create :accept_pending_invitation
+result = accept_pending_organization_invitation!(user)
+result.accepted?      # => true if freshly accepted
+result.already_member? # => true if user was already a member
+result.switched?      # => true if org context was switched
+result.invitation     # => the invitation record
+result.membership     # => the membership record
 
-def accept_pending_invitation
-  token = session.delete(:pending_invitation_token)
-  return unless token
+# Default flash notice (when using pending_invitation_acceptance_redirect_path_for)
+# accepted?       -> "Welcome to <organization>!"
+# already_member? -> "You're already a member of <organization>."
+```
+
+If you want structured failure reasons instead of `nil`, pass `return_failure: true`:
+
+```ruby
+result = accept_pending_organization_invitation!(user, return_failure: true)
+
+if result.success?
+  # InvitationAcceptanceResult
+else
+  # InvitationAcceptanceFailure
+  result.failure_reason # => :missing_token, :email_mismatch, :invitation_expired, etc.
+end
+```
+
+Configure redirects in your initializer:
 
-  invitation = Organizations::Invitation.find_by(token: token)
-  invitation&.accept!(self, skip_email_validation: true)
+```ruby
+Organizations.configure do |config|
+  config.redirect_path_when_invitation_requires_authentication = "/users/sign_up"
+  config.redirect_path_after_invitation_accepted = "/dashboard"
+  config.redirect_path_after_organization_switched = "/dashboard"
+
+  # Or use procs for dynamic paths:
+  config.redirect_path_after_invitation_accepted = ->(inv, user) {
+    "/org/#{inv.organization_id}/welcome"
+  }
+  config.redirect_path_after_organization_switched = ->(org, user) {
+    "/orgs/#{org.id}?user=#{user.id}"
+  }
 end
 ```
 
+> **Note:** When accepting invitations in custom auth flows (Devise overrides, `bypass_sign_in`, etc.), the gem handles stale memoization issues automatically by passing the explicit user to `switch_to_organization!`.
+
 ### Invitation emails
 
 The gem ships with a clean ActionMailer-based invitation email.
@@ -712,8 +804,8 @@ When you mount the engine, you get:
 
 ```
 POST /organizations/switch/:id  → Organizations::SwitchController#create
-GET  /invitations/:token        → Organizations::InvitationsController#show
-POST /invitations/:token/accept → Organizations::InvitationsController#accept
+GET  /invitations/:token        → Organizations::PublicInvitationsController#show
+POST /invitations/:token/accept → Organizations::PublicInvitationsController#accept
 ```
 
 ## Auto-created organizations
@@ -837,6 +929,51 @@ Organizations.configure do |config|
   # Where to redirect when user has no organization
   config.redirect_path_when_no_organization = "/organizations/new"
 
+  # Where to redirect after organization is created (nil = default show page)
+  # Can be a String or Proc: ->(org) { "/orgs/#{org.id}/setup" }
+  config.after_organization_created_redirect_path = "/dashboard"
+
+  # === Invitation Flow Redirects ===
+  # Where to redirect unauthenticated users when they try to accept an invitation
+  # Default: nil (uses new_user_registration_path or root_path)
+  config.redirect_path_when_invitation_requires_authentication = "/users/sign_up"
+  # Or use a Proc: ->(invitation, user) { "/signup?invite=#{invitation.token}" }
+
+  # Where to redirect after an invitation is accepted
+  # Default: nil (uses root_path)
+  config.redirect_path_after_invitation_accepted = "/dashboard"
+  # Or use a Proc: ->(invitation, user) { "/org/#{invitation.organization_id}/welcome" }
+
+  # Where to redirect after organization switch
+  # Default: nil (uses root_path)
+  config.redirect_path_after_organization_switched = "/dashboard"
+  # Or use a Proc: ->(organization, user) { "/orgs/#{organization.id}" }
+
+  # Optional flash messages for built-in no-organization redirects.
+  # Leave nil to keep default alert behavior.
+  config.no_organization_alert = "Please create an organization first."
+  config.no_organization_notice = "Please create or join an organization to continue."
+
+  # === Organizations Controller ===
+  # Additional params to permit when creating/updating organizations
+  # Use this to add custom fields like support_email, billing_email, logo
+  config.additional_organization_params = [:support_email]
+
+  # === Engine Controllers ===
+  # Base controller for authenticated routes (default: ::ApplicationController)
+  config.parent_controller = "::ApplicationController"
+
+  # Base controller for public routes like invitation acceptance.
+  # Works with Devise out of the box - no configuration needed.
+  # Only override if using custom auth or needing specific inheritance.
+  # Default: ActionController::Base
+  # config.public_controller = "ActionController::Base"
+
+  # Layout overrides for engine controllers (optional)
+  # Resolved at request-time, so runtime config changes are respected.
+  config.authenticated_controller_layout = "dashboard"
+  config.public_controller_layout = "devise"
+
   # === Handlers ===
   # Called when authorization fails
   config.on_unauthorized do |context|
@@ -1064,9 +1201,9 @@ The gem provides `Organizations::Organization` as the base model. You can extend
 # db/migrate/xxx_add_custom_fields_to_organizations.rb
 class AddCustomFieldsToOrganizations < ActiveRecord::Migration[8.0]
   def change
-    add_column :organizations, :support_email, :string
-    add_column :organizations, :billing_address, :text
-    add_column :organizations, :settings, :jsonb, default: {}
+    add_column :organizations_organizations, :support_email, :string
+    add_column :organizations_organizations, :billing_address, :text
+    add_column :organizations_organizations, :settings, :jsonb, default: {}
   end
 end
 ```
@@ -1110,10 +1247,10 @@ This is standard Rails practice — the gem provides the foundation (memberships
 
 The gem creates three tables:
 
-### organizations
+### organizations_organizations
 
 ```sql
-organizations
+organizations_organizations
   - id (primary key, auto-detects UUID or integer from your app)
   - name (string, required)
   - metadata (jsonb, default: {})
@@ -1123,10 +1260,10 @@ organizations
 
 > **Note:** The gem automatically detects your app's primary key type (UUID or integer) and uses it for all tables.
 
-### memberships
+### organizations_memberships
 
 ```sql
-memberships
+organizations_memberships
   - id (primary key)
   - user_id (foreign key, indexed)
   - organization_id (foreign key, indexed)
@@ -1138,10 +1275,10 @@ memberships
   unique index: [user_id, organization_id]
 ```
 
-### organization_invitations
+### organizations_invitations
 
 ```sql
-organization_invitations
+organizations_invitations
   - id (primary key)
   - organization_id (foreign key, indexed)
   - email (string, required, indexed)
@@ -1254,7 +1391,7 @@ If you display member counts frequently (pricing pages, org listings), consider
 
 ```ruby
 # In a migration
-add_column :organizations, :memberships_count, :integer, default: 0, null: false
+add_column :organizations_organizations, :memberships_count, :integer, default: 0, null: false
 
 # Reset existing counts
 Organization.find_each do |org|
@@ -1275,9 +1412,9 @@ org.member_count
 Boolean checks use efficient SQL `EXISTS` queries:
 
 ```ruby
-user.belongs_to_any_organization?     # SELECT 1 FROM memberships WHERE ... LIMIT 1
-user.has_pending_organization_invitations?  # SELECT 1 FROM organization_invitations WHERE ... LIMIT 1
-org.has_any_members?                  # SELECT 1 FROM memberships WHERE ... LIMIT 1
+user.belongs_to_any_organization?     # SELECT 1 FROM organizations_memberships WHERE ... LIMIT 1
+user.has_pending_organization_invitations?  # SELECT 1 FROM organizations_invitations WHERE ... LIMIT 1
+org.has_any_members?                  # SELECT 1 FROM organizations_memberships WHERE ... LIMIT 1
 ```
 
 ### Scoped associations use JOINs
@@ -1287,13 +1424,13 @@ Methods like `org.admins` and `user.owned_organizations` use proper SQL JOINs:
 ```ruby
 org.admins
 # SELECT users.* FROM users
-# INNER JOIN memberships ON memberships.user_id = users.id
-# WHERE memberships.organization_id = ? AND memberships.role IN ('admin', 'owner')
+# INNER JOIN organizations_memberships ON organizations_memberships.user_id = users.id
+# WHERE organizations_memberships.organization_id = ? AND organizations_memberships.role IN ('admin', 'owner')
 
 user.owned_organizations
-# SELECT organizations.* FROM organizations
-# INNER JOIN memberships ON memberships.organization_id = organizations.id
-# WHERE memberships.user_id = ? AND memberships.role = 'owner'
+# SELECT organizations_organizations.* FROM organizations_organizations
+# INNER JOIN organizations_memberships ON organizations_memberships.organization_id = organizations_organizations.id
+# WHERE organizations_memberships.user_id = ? AND organizations_memberships.role = 'owner'
 ```
 
 ### Current organization memoization
@@ -1445,14 +1582,14 @@ The gem creates these indexes automatically:
 
 ```sql
 -- Fast membership lookups
-CREATE UNIQUE INDEX index_memberships_on_user_and_org ON memberships (user_id, organization_id);
-CREATE INDEX index_memberships_on_organization_id ON memberships (organization_id);
-CREATE INDEX index_memberships_on_role ON memberships (role);
+CREATE UNIQUE INDEX index_organizations_memberships_on_user_and_org ON organizations_memberships (user_id, organization_id);
+CREATE INDEX index_organizations_memberships_on_organization_id ON organizations_memberships (organization_id);
+CREATE INDEX index_organizations_memberships_on_role ON organizations_memberships (role);
 
 -- Fast invitation lookups
-CREATE UNIQUE INDEX index_invitations_on_token ON organization_invitations (token);
-CREATE INDEX index_invitations_on_email ON organization_invitations (email);
-CREATE UNIQUE INDEX index_invitations_pending ON organization_invitations (organization_id, LOWER(email)) WHERE accepted_at IS NULL;
+CREATE UNIQUE INDEX index_organizations_invitations_on_token ON organizations_invitations (token);
+CREATE INDEX index_organizations_invitations_on_email ON organizations_invitations (email);
+CREATE UNIQUE INDEX index_organizations_invitations_pending ON organizations_invitations (organization_id, LOWER(email)) WHERE accepted_at IS NULL;
 ```
 
 ## Migration from 1:1 relationships

data/Rakefile

@@ -7,7 +7,8 @@ require "rubocop/rake_task"
 Rake::TestTask.new(:test) do |t|
   t.libs << "test"
   t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  # Exclude dummy app tests - they require Rails and are run separately
+  t.test_files = FileList["test/**/*_test.rb"].exclude("test/dummy/**/*")
 end
 
 RuboCop::RakeTask.new

data/app/controllers/organizations/application_controller.rb

@@ -7,21 +7,28 @@ module Organizations
   #
   # All engine controllers inherit from this class and get:
   # - Authentication via configured method
-  # - Organization context helpers
-  # - Permission guards
+  # - Organization context helpers (via ControllerHelpers)
+  # - Permission guards (via ControllerHelpers)
   #
   class ApplicationController < (Organizations.configuration.parent_controller.constantize rescue ::ApplicationController)
+    # Include ControllerHelpers for organization context and permission guards
+    # This provides: current_organization, current_membership, organization_signed_in?,
+    # switch_to_organization!, require_organization!, require_organization_admin!, etc.
+    include Organizations::ControllerHelpers
+
     # Protect from forgery if the parent controller does
     protect_from_forgery with: :exception if respond_to?(:protect_from_forgery)
 
+    if respond_to?(:layout)
+      # Resolve layout at request-time so runtime config changes are respected.
+      layout :organizations_authenticated_layout
+    end
+
     # Ensure user is authenticated for all actions
     before_action :authenticate_organizations_user!
 
-    # Expose helpers to views
+    # Expose current_user to views (ControllerHelpers exposes org-related helpers)
     helper_method :current_user
-    helper_method :current_organization
-    helper_method :current_membership
-    helper_method :organization_signed_in?
 
     private
 
@@ -50,202 +57,22 @@ module Organizations
     # Uses the configured method name (defaults to :current_user)
     # NOTE: We call the PARENT class method to avoid infinite recursion
     def current_user
-      return @_current_user if defined?(@_current_user)
-
-      user_method = Organizations.configuration.current_user_method
-
-      # Avoid infinite recursion: if configured method is :current_user,
-      # call the parent implementation, not this method
-      @_current_user = if user_method == :current_user
-                         super rescue nil
-                       elsif user_method && respond_to?(user_method, true)
-                         send(user_method)
-                       end
+      resolve_organizations_current_user(
+        cache_ivar: :@_current_user,
+        cache_nil: true,
+        prefer_super_for_current_user: true
+      )
     end
 
     # Alias for compatibility
     alias_method :current_organizations_user, :current_user
 
-    # === Organization Context ===
-
-    # Returns the current organization from the session
-    # Validates membership - if user was removed, auto-switches to next available org
-    # Falls back to most recently joined org if no session set
-    def current_organization
-      return @_current_organization if defined?(@_current_organization)
-      return @_current_organization = nil unless current_user
-
-      session_key = Organizations.configuration.session_key
-      org_id = session[session_key]
-
-      org = org_id ? Organization.find_by(id: org_id) : nil
-
-      if org && current_user.is_member_of?(org)
-        # Valid membership - use this org
-        current_user._current_organization_id = org.id
-        @_current_organization = org
-      else
-        # User was removed from this org OR no session set
-        # Auto-switch to next available org (most recently joined)
-        clear_organization_session!
-
-        fallback_org = fallback_organization_for(current_user)
-        if fallback_org
-          session[session_key] = fallback_org.id
-          current_user._current_organization_id = fallback_org.id
-          @_current_organization = fallback_org
-        else
-          @_current_organization = nil
-        end
-      end
-    end
-
-    # Returns the current user's membership in the current organization
-    def current_membership
-      return @_current_membership if defined?(@_current_membership)
-      return @_current_membership = nil unless current_user && current_organization
-
-      @_current_membership = current_user.memberships.find_by(organization_id: current_organization.id)
-    end
-
-    # Check if there's an active organization
-    def organization_signed_in?
-      current_organization.present?
-    end
-
-    # Sets the current organization in session
-    def current_organization=(org)
-      session_key = Organizations.configuration.session_key
-
-      if org
-        session[session_key] = org.id
-        @_current_organization = org
-        @_current_membership = nil
-        current_user&._current_organization_id = org.id
-      else
-        clear_organization_session!
-      end
-    end
-
-    # Switches to a different organization
-    def switch_to_organization!(org)
-      unless current_user&.is_member_of?(org)
-        raise Organizations::NotAMember.new(
-          "You are not a member of this organization",
-          organization: org,
-          user: current_user
-        )
-      end
-
-      self.current_organization = org
-      mark_membership_as_recent!(current_user, org)
-    end
-
-    # Clear organization session and cached values
-    def clear_organization_session!
-      session_key = Organizations.configuration.session_key
-      session.delete(session_key)
-      @_current_organization = nil
-      @_current_membership = nil
-      current_user&.clear_organization_cache!
-    end
-
-    # === Permission Guards ===
-
-    # Requires a current organization to be set
-    def require_organization!
-      return if current_organization
+    def organizations_authenticated_layout
+      configured_layout = Organizations.configuration.authenticated_controller_layout
+      return nil if configured_layout.nil?
+      return configured_layout unless configured_layout.is_a?(Symbol)
 
-      config = Organizations.configuration
-
-      if config.no_organization_handler
-        context = CallbackContext.new(event: :no_organization, user: current_user)
-        instance_exec(context, &config.no_organization_handler)
-      else
-        respond_to do |format|
-          format.html { redirect_to config.redirect_path_when_no_organization, alert: "Please select or create an organization." }
-          format.json { render json: { error: "Organization required" }, status: :forbidden }
-        end
-      end
-    end
-
-    # Requires the user to have at least the specified role
-    def require_organization_role!(role)
-      require_organization!
-      return unless current_organization
-
-      return if current_user&.is_at_least?(role, in: current_organization)
-
-      handle_unauthorized(required_role: role)
-    end
-
-    # Requires the user to have a specific permission
-    def require_organization_permission_to!(permission)
-      require_organization!
-      return unless current_organization
-
-      return if current_user&.has_organization_permission_to?(permission)
-
-      handle_unauthorized(permission: permission)
-    end
-
-    # Requires the user to be an admin of the current organization
-    def require_organization_admin!
-      require_organization_role!(:admin)
-    end
-
-    # Requires the user to be the owner of the current organization
-    def require_organization_owner!
-      require_organization_role!(:owner)
-    end
-
-    # Handle unauthorized access
-    def handle_unauthorized(permission: nil, required_role: nil)
-      config = Organizations.configuration
-
-      if config.unauthorized_handler
-        context = CallbackContext.new(
-          event: :unauthorized,
-          user: current_user,
-          organization: current_organization,
-          permission: permission,
-          required_role: required_role
-        )
-        instance_exec(context, &config.unauthorized_handler)
-      else
-        error = Organizations::NotAuthorized.new(
-          build_unauthorized_message(permission, required_role),
-          permission: permission || required_role,
-          organization: current_organization,
-          user: current_user
-        )
-
-        respond_to do |format|
-          format.html { redirect_back fallback_location: main_app.root_path, alert: error.message }
-          format.json { render json: { error: error.message }, status: :forbidden }
-        end
-      end
-    end
-
-    def fallback_organization_for(user)
-      membership = user.memberships.includes(:organization).order(updated_at: :desc, created_at: :desc).first
-      membership&.organization
-    end
-
-    def mark_membership_as_recent!(user, org)
-      return unless user && org
-
-      user.memberships.where(organization_id: org.id).update_all(updated_at: Time.current)
-    end
-
-    def build_unauthorized_message(permission, required_role)
-      if required_role
-        "You need #{required_role} access to perform this action"
-      elsif permission
-        "You don't have permission to #{permission.to_s.humanize.downcase}"
-      else
-        "You are not authorized to perform this action"
-      end
+      send(configured_layout)
     end
   end
 end