organizations 0.2.0 → 0.3.1

data/app/controllers/organizations/organizations_controller.rb

@@ -40,13 +40,10 @@ module Organizations
     # Create a new organization
     def create
       begin
-        @organization = current_user.create_organization!(organization_params[:name])
-
-        # Switch to the new organization
-        switch_to_organization!(@organization)
+        @organization = create_organization_and_switch!(current_user, organization_params.to_h)
 
         respond_to do |format|
-          format.html { redirect_to organization_path(@organization), notice: "Organization created successfully." }
+          format.html { redirect_to after_create_redirect_path(@organization), notice: "Organization created successfully." }
           format.json { render json: organization_json(@organization), status: :created }
         end
       rescue Organizations::Models::Concerns::HasOrganizations::OrganizationLimitReached => e
@@ -117,7 +114,18 @@ module Organizations
     end
 
     def organization_params
-      params.require(:organization).permit(:name)
+      base_params = [:name]
+      additional_params = Organizations.configuration.additional_organization_params || []
+      params.require(:organization).permit(base_params + additional_params)
+    end
+
+    def after_create_redirect_path(organization)
+      custom_path = Organizations.configuration.after_organization_created_redirect_path
+      resolve_controller_redirect_path(
+        custom_path,
+        organization,
+        default: -> { organization_path(organization) }
+      )
     end
 
     def authorize_manage_settings!

data/app/controllers/organizations/public_controller.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Base controller for public routes that don't require authentication.
+  # Inherits from the configured public_controller (defaults to ActionController::Base)
+  # to avoid inheriting host app filters that might enforce authentication.
+  #
+  # Use cases:
+  # - Invitation acceptance pages (users clicking email links)
+  # - Any other routes that should work for unauthenticated users
+  #
+  class PublicController < (Organizations.configuration.public_controller.constantize rescue ActionController::Base)
+    include Organizations::CurrentUserResolution
+
+    # Protect from forgery if available
+    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_public_layout
+    end
+
+    # Include main app route helpers so host app layouts work correctly
+    # (e.g., root_path, pricing_path in navbar partials)
+    include Rails.application.routes.url_helpers if defined?(Rails.application.routes.url_helpers)
+    helper Rails.application.routes.url_helpers if respond_to?(:helper)
+
+    # Minimal helpers needed for public routes
+    helper_method :current_user if respond_to?(:helper_method)
+
+    private
+
+    # Returns the current user from the host application (if any).
+    # Uses the configured method name (defaults to :current_user)
+    #
+    # NOTE: Nil values are intentionally not cached to handle auth-transition flows
+    # where user state changes mid-request (e.g., sign_in during invitation acceptance).
+    def current_user
+      resolve_organizations_current_user(
+        cache_ivar: :@_current_user,
+        cache_nil: false,
+        prefer_super_for_current_user: true,
+        prefer_warden_for_current_user: true
+      )
+    end
+
+    def organizations_public_layout
+      configured_layout = Organizations.configuration.public_controller_layout
+      return nil if configured_layout.nil?
+      return configured_layout unless configured_layout.is_a?(Symbol)
+
+      send(configured_layout)
+    end
+
+    # Access main_app routes from engine views
+    def main_app
+      Rails.application.routes.url_helpers
+    end
+    helper_method :main_app if respond_to?(:helper_method)
+  end
+end

data/app/controllers/organizations/public_invitations_controller.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Controller for public invitation routes (show and accept).
+  # Inherits from PublicController to avoid host app authentication filters.
+  #
+  # Routes:
+  #   GET  /invitations/:token        → View invitation details
+  #   POST /invitations/:token/accept → Accept the invitation
+  #
+  class PublicInvitationsController < PublicController
+    include Organizations::Controller if defined?(Organizations::Controller)
+
+    before_action :set_invitation
+
+    # Use the same view path as InvitationsController so host apps
+    # don't need to duplicate views for public routes
+    def self.controller_path
+      "organizations/invitations"
+    end
+
+    # GET /invitations/:token
+    # View invitation details (public route)
+    def show
+      @user_exists = user_exists_for_invitation?
+      @user_is_logged_in = current_user.present?
+      @user_email_matches = @user_is_logged_in && current_user.email.downcase == @invitation.email.downcase
+
+      respond_to do |format|
+        format.html
+        format.json { render json: invitation_show_json }
+      end
+    end
+
+    # POST /invitations/:token/accept
+    # Accept an invitation (public route)
+    def accept
+      return respond_invitation_authentication_required unless current_user
+
+      result = accept_pending_organization_invitation!(
+        current_user,
+        token: @invitation.token,
+        switch: true,
+        skip_email_validation: false,
+        return_failure: true
+      )
+
+      return respond_invitation_acceptance_failure(result) if result.failure?
+
+      respond_invitation_acceptance_success(result)
+    end
+
+    private
+
+    def respond_invitation_authentication_required
+      session[pending_invitation_session_key] = @invitation.token
+
+      respond_to do |format|
+        format.html do
+          redirect_to redirect_path_when_invitation_requires_authentication(@invitation),
+                      alert: "Please sign in or create an account to accept this invitation."
+        end
+        format.json { render json: { error: "Authentication required" }, status: :unauthorized }
+      end
+    end
+
+    def respond_invitation_acceptance_failure(failure)
+      case failure.failure_reason
+      when :email_mismatch
+        return respond_invitation_email_mismatch
+      when :invitation_expired
+        return respond_invitation_expired
+      end
+
+      respond_invitation_error(
+        html_path: main_app.root_path,
+        alert: "Unable to accept this invitation.",
+        json_error: "Acceptance failed",
+        status: :unprocessable_entity
+      )
+    end
+
+    def respond_invitation_email_mismatch
+      respond_invitation_error(
+        html_path: invitation_path(@invitation.token),
+        alert: "This invitation was sent to a different email address.",
+        json_error: "Email mismatch",
+        status: :forbidden
+      )
+    end
+
+    def respond_invitation_expired
+      respond_invitation_error(
+        html_path: main_app.root_path,
+        alert: "This invitation has expired. Please request a new one.",
+        json_error: "Invitation expired",
+        status: :gone
+      )
+    end
+
+    def respond_invitation_acceptance_success(result)
+      after_path = redirect_path_after_invitation_accepted(result.invitation, user: current_user)
+      payload, status = invitation_acceptance_json_response(result)
+
+      respond_to do |format|
+        format.html { redirect_to after_path, notice: invitation_acceptance_notice(result) }
+        format.json { render json: payload, status: status }
+      end
+    end
+
+    def set_invitation
+      @invitation = ::Organizations::Invitation.find_by!(token: params[:token])
+    rescue ActiveRecord::RecordNotFound
+      respond_to do |format|
+        format.html { redirect_to main_app.root_path, alert: "Invitation not found or has been revoked." }
+        format.json { render json: { error: "Invitation not found" }, status: :not_found }
+      end
+    end
+
+    def user_exists_for_invitation?
+      if defined?(User) && User.respond_to?(:exists?)
+        User.exists?(email: @invitation.email.downcase)
+      else
+        false
+      end
+    end
+
+    # JSON serialization helpers
+
+    def invitation_show_json
+      inviter = @invitation.invited_by
+      inviter_name = if inviter
+                       inviter.respond_to?(:name) && inviter.name.present? ? inviter.name : inviter.email
+                     else
+                       "Someone"
+                     end
+      {
+        invitation: {
+          organization_name: @invitation.organization.name,
+          role: @invitation.role,
+          invited_by_name: inviter_name,
+          status: @invitation.status,
+          expires_at: @invitation.expires_at
+        },
+        user_exists: @user_exists,
+        user_is_logged_in: @user_is_logged_in,
+        user_email_matches: @user_email_matches
+      }
+    end
+
+    def membership_json(membership)
+      {
+        id: membership.id,
+        organization_id: membership.organization_id,
+        role: membership.role,
+        created_at: membership.created_at
+      }
+    end
+
+    def respond_invitation_error(html_path:, alert:, json_error:, status:)
+      respond_to do |format|
+        format.html { redirect_to html_path, alert: alert }
+        format.json { render json: { error: json_error }, status: status }
+      end
+    end
+
+    def invitation_acceptance_notice(result)
+      org_name = result.invitation.organization.name
+
+      if result.already_member?
+        "You're already a member of #{org_name}."
+      elsif result.switched?
+        "Welcome to #{org_name}!"
+      else
+        # Rare edge case: membership was created but context switch failed
+        "You've joined #{org_name}! Navigate to the organization to get started."
+      end
+    end
+
+    def invitation_acceptance_json_response(result)
+      if result.already_member?
+        [{ message: "Already accepted" }, :ok]
+      elsif result.switched?
+        [{ membership: membership_json(result.membership) }, :created]
+      else
+        # Rare edge case: membership was created but context switch failed
+        [{ membership: membership_json(result.membership), warning: "Could not switch context automatically" }, :created]
+      end
+    end
+
+    # Route helpers for engine routes
+    def invitation_path(token)
+      Organizations::Engine.routes.url_helpers.invitation_path(token)
+    end
+  end
+end

data/app/controllers/organizations/switch_controller.rb

@@ -12,13 +12,16 @@ module Organizations
     # Switch to a different organization
     # POST /organizations/switch/:id
     def create
-      org = current_user.organizations.find_by(id: params[:id])
+      user = organizations_current_user(refresh: true)
+      return respond_unauthorized unless user
+
+      org = user.organizations.find_by(id: params[:id])
 
       if org
-        switch_to_organization!(org)
+        switch_to_organization!(org, user: user)
 
         respond_to do |format|
-          format.html { redirect_to after_switch_path, notice: "Switched to #{org.name}" }
+          format.html { redirect_to after_switch_path(org, user: user), notice: "Switched to #{org.name}" }
           format.json { render json: { organization: { id: org.id, name: org.name } } }
         end
       else
@@ -31,8 +34,15 @@ module Organizations
 
     private
 
-    def after_switch_path
-      main_app.respond_to?(:root_path) ? main_app.root_path : "/"
+    def after_switch_path(organization, user:)
+      redirect_path_after_organization_switched(organization, user: user)
+    end
+
+    def respond_unauthorized
+      respond_to do |format|
+        format.html { redirect_to main_app.root_path, alert: "You need to sign in to switch organizations." }
+        format.json { render json: { error: "Unauthorized" }, status: :unauthorized }
+      end
     end
   end
 end

data/app/models/organizations/invitation.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::Invitation in Rails apps.
+# This file lives in app/models so Zeitwerk manages it, making the class
+# reload-safe. It delegates to the canonical implementation in lib/.
+load File.expand_path("../../../lib/organizations/models/invitation.rb", __dir__)

data/app/models/organizations/membership.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::Membership in Rails apps.
+# This file lives in app/models so Zeitwerk manages it, making the class
+# reload-safe. It delegates to the canonical implementation in lib/.
+load File.expand_path("../../../lib/organizations/models/membership.rb", __dir__)

data/app/models/organizations/organization.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::Organization in Rails apps.
+# This file lives in app/models so Zeitwerk manages it, making the class
+# reload-safe. It delegates to the canonical implementation in lib/.
+load File.expand_path("../../../lib/organizations/models/organization.rb", __dir__)

data/config/routes.rb

@@ -27,9 +27,11 @@ Organizations::Engine.routes.draw do
   end
 
   # Invitation acceptance (public routes with token)
+  # These use PublicInvitationsController which inherits from a minimal base controller
+  # to avoid host app filters that might enforce authentication.
   # GET  /invitations/:token        → View invitation details
   # POST /invitations/:token/accept → Accept the invitation
   # NOTE: These must come AFTER resourceful routes to avoid matching "new" as a token
-  get "invitations/:token", to: "invitations#show", as: :invitation
-  post "invitations/:token/accept", to: "invitations#accept", as: :accept_invitation
+  get "invitations/:token", to: "public_invitations#show", as: :invitation
+  post "invitations/:token/accept", to: "public_invitations#accept", as: :accept_invitation
 end

data/lib/generators/organizations/install/templates/initializer.rb

@@ -71,4 +71,80 @@ Organizations.configure do |config|
   # Default: :current_organization_id
   # config.session_key = :current_organization_id
 
+  # ============================================================================
+  # ORGANIZATIONS CONTROLLER
+  # ============================================================================
+
+  # Additional params to permit when creating/updating organizations.
+  # Use this to add custom fields to organizations (e.g., support_email, logo).
+  # Default: [] (only :name is permitted)
+  # config.additional_organization_params = [:support_email, :billing_email]
+
+  # Where to redirect after organization is created.
+  # Can be a String path or a Proc that receives the organization.
+  # Default: nil (redirects to organization show page)
+  # config.after_organization_created_redirect_path = "/dashboard"
+  # config.after_organization_created_redirect_path = ->(org) { "/orgs/#{org.id}/setup" }
+
+  # ============================================================================
+  # REDIRECTS
+  # ============================================================================
+
+  # Where to redirect when user has no organization.
+  # Default: "/organizations/new"
+  # config.redirect_path_when_no_organization = "/onboarding"
+
+  # Optional flash messages used by the built-in no-organization handler.
+  # Leave both nil to keep the default alert:
+  # "Please select or create an organization."
+  # config.no_organization_alert = "Please create an organization first."
+  # config.no_organization_notice = "Please create or join an organization to continue."
+
+  # ============================================================================
+  # INVITATION FLOW REDIRECTS
+  # ============================================================================
+
+  # Where to redirect unauthenticated users when they try to accept an invitation.
+  # Use this to customize the signup/login page for invited users.
+  # Can be a String path or a Proc receiving (invitation, user).
+  # Default: nil (uses new_user_registration_path or root_path)
+  # config.redirect_path_when_invitation_requires_authentication = "/users/sign_up"
+  # config.redirect_path_when_invitation_requires_authentication = ->(inv, _user) { "/signup?invite=#{inv.token}" }
+
+  # Where to redirect after an invitation is accepted.
+  # Can be a String path or a Proc receiving (invitation, user).
+  # Default: nil (uses root_path)
+  # config.redirect_path_after_invitation_accepted = "/dashboard"
+  # config.redirect_path_after_invitation_accepted = ->(inv, user) { "/org/#{inv.organization_id}/welcome" }
+
+  # Where to redirect after switching organizations.
+  # Can be a String path or a Proc receiving (organization, user).
+  # Default: nil (uses root_path)
+  # config.redirect_path_after_organization_switched = "/dashboard"
+  # config.redirect_path_after_organization_switched = ->(org, user) { "/orgs/#{org.id}?user=#{user.id}" }
+
+  # ============================================================================
+  # ENGINE CONTROLLERS
+  # ============================================================================
+
+  # Base controller for authenticated routes (default: ::ApplicationController)
+  # All organization management controllers inherit from this.
+  # config.parent_controller = "::ApplicationController"
+
+  # Base controller for public routes like invitation acceptance.
+  # Uses a minimal base to avoid host app filters that enforce authentication.
+  # 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 override for authenticated engine controllers.
+  # Use this to avoid host-side layout monkey patches.
+  # Default: nil (inherits host controller defaults)
+  # config.authenticated_controller_layout = "dashboard"
+
+  # Layout override for public engine controllers (invitation pages).
+  # Default: nil (inherits host controller defaults)
+  # config.public_controller_layout = "devise"
+
 end

data/lib/organizations/configuration.rb

@@ -67,9 +67,55 @@ module Organizations
     # Where to redirect when user has no organization
     attr_accessor :redirect_path_when_no_organization
 
+    # Where to redirect after organization is created (nil = default show page)
+    # Can be a String ("/dashboard") or Proc (->(org) { "/orgs/#{org.id}" })
+    attr_accessor :after_organization_created_redirect_path
+
+    # Default flash alert for no-organization redirects when using the built-in handler
+    # nil keeps backward-compatible default alert
+    attr_accessor :no_organization_alert
+
+    # Default flash notice for no-organization redirects when using the built-in handler
+    # nil means no notice
+    attr_accessor :no_organization_notice
+
+    # === Invitation Flow Redirects ===
+    # Where to redirect unauthenticated users when they try to accept an invitation
+    # Can be nil (use default: new_user_registration_path or root_path),
+    # a String ("/users/sign_up"), or a Proc receiving (invitation, user)
+    attr_accessor :redirect_path_when_invitation_requires_authentication
+
+    # Where to redirect after invitation is accepted
+    # Can be nil (use default: root_path), a String ("/dashboard"),
+    # or a Proc receiving (invitation, user)
+    attr_accessor :redirect_path_after_invitation_accepted
+
+    # Where to redirect after organization switch
+    # Can be nil (use default: root_path), a String ("/dashboard"),
+    # or a Proc receiving (organization, user)
+    attr_accessor :redirect_path_after_organization_switched
+
+    # === Organizations Controller ===
+    # Additional params to permit when creating/updating organizations
+    # @example [:support_email, :billing_email, :logo]
+    attr_accessor :additional_organization_params
+
     # === Engine configuration ===
+    # Base controller for authenticated routes (default: ::ApplicationController)
     attr_accessor :parent_controller
 
+    # Base controller for public routes like invitation acceptance (default: ActionController::Base)
+    # Use this to avoid inheriting host app filters that enforce authentication
+    attr_accessor :public_controller
+
+    # Layout for authenticated engine controllers (OrganizationsController, etc.)
+    # Can be nil (use controller default), String, or Symbol
+    attr_accessor :authenticated_controller_layout
+
+    # Layout for public engine controllers (PublicInvitationsController, etc.)
+    # Can be nil (use controller default), String, or Symbol
+    attr_accessor :public_controller_layout
+
     # === Handlers (blocks) ===
     # @private - stored handler blocks
     attr_reader :unauthorized_handler, :no_organization_handler
@@ -112,9 +158,23 @@ module Organizations
 
       # Redirects
       @redirect_path_when_no_organization = "/organizations/new"
+      @after_organization_created_redirect_path = nil
+      @no_organization_alert = nil
+      @no_organization_notice = nil
+
+      # Invitation flow redirects
+      @redirect_path_when_invitation_requires_authentication = nil
+      @redirect_path_after_invitation_accepted = nil
+      @redirect_path_after_organization_switched = nil
+
+      # Organizations controller
+      @additional_organization_params = []
 
       # Engine
       @parent_controller = "::ApplicationController"
+      @public_controller = "ActionController::Base"
+      @authenticated_controller_layout = nil
+      @public_controller_layout = nil
 
       # Handlers (nil by default - use default behavior)
       @unauthorized_handler = nil
@@ -248,6 +308,9 @@ module Organizations
       validate_authentication_methods!
       validate_invitation_settings!
       validate_limits!
+      validate_invitation_redirects!
+      validate_no_organization_messages!
+      validate_controller_layouts!
       true
     end
 
@@ -282,5 +345,51 @@ module Organizations
         raise ConfigurationError, "max_organizations_per_user must be at least 1"
       end
     end
+
+    def validate_invitation_redirects!
+      validate_redirect_option!(
+        @redirect_path_when_invitation_requires_authentication,
+        "redirect_path_when_invitation_requires_authentication"
+      )
+      validate_redirect_option!(
+        @redirect_path_after_invitation_accepted,
+        "redirect_path_after_invitation_accepted"
+      )
+      validate_redirect_option!(
+        @redirect_path_after_organization_switched,
+        "redirect_path_after_organization_switched"
+      )
+    end
+
+    def validate_controller_layouts!
+      validate_layout_option!(@authenticated_controller_layout, "authenticated_controller_layout")
+      validate_layout_option!(@public_controller_layout, "public_controller_layout")
+    end
+
+    def validate_no_organization_messages!
+      validate_string_option!(@no_organization_alert, "no_organization_alert")
+      validate_string_option!(@no_organization_notice, "no_organization_notice")
+    end
+
+    def validate_redirect_option!(value, option_name)
+      return if value.nil? || value.is_a?(String) || value.is_a?(Proc)
+
+      raise ConfigurationError,
+            "#{option_name} must be nil, a String, or a Proc"
+    end
+
+    def validate_layout_option!(value, option_name)
+      return if value.nil? || value.is_a?(String) || value.is_a?(Symbol)
+
+      raise ConfigurationError,
+            "#{option_name} must be nil, a String, or a Symbol"
+    end
+
+    def validate_string_option!(value, option_name)
+      return if value.nil? || value.is_a?(String)
+
+      raise ConfigurationError,
+            "#{option_name} must be nil or a String"
+    end
   end
 end