organizations 0.2.0 → 0.3.0

data/lib/organizations/engine.rb

@@ -6,17 +6,15 @@ module Organizations
   class Engine < ::Rails::Engine
     isolate_namespace Organizations
 
-    # Load models when ActiveRecord is ready
-    # Note: We use explicit requires instead of autoload_paths because the models
-    # are namespaced under Organizations:: but live in lib/organizations/models/
+    # Make has_organizations available on all ActiveRecord models.
+    #
+    # NOTE: We intentionally avoid explicit `require` calls for models here.
+    # In Rails apps, Organizations models are loaded through Zeitwerk from app/models,
+    # which keeps them reload-safe in development. Explicit requires would create
+    # non-reloadable class references that cause STI errors with gems like Pay
+    # after code reloads.
     initializer "organizations.active_record" do
       ActiveSupport.on_load(:active_record) do
-        require "organizations/models/organization"
-        require "organizations/models/membership"
-        require "organizations/models/invitation"
-        require "organizations/models/concerns/has_organizations"
-
-        # Make has_organizations available on all AR models
         extend Organizations::Models::Concerns::HasOrganizations::ClassMethods
       end
     end

data/lib/organizations/invitation_acceptance_failure.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Value object representing a failed invitation acceptance attempt.
+  class InvitationAcceptanceFailure
+    REASONS = %i[
+      missing_user
+      missing_token
+      invitation_not_found
+      invitation_expired
+      email_mismatch
+      already_accepted_without_membership
+    ].freeze
+
+    attr_reader :reason, :invitation
+
+    def initialize(reason:, invitation: nil)
+      unless REASONS.include?(reason)
+        raise ArgumentError, "Invalid reason: #{reason.inspect}. Must be one of: #{REASONS.join(', ')}"
+      end
+
+      @reason = reason
+      @invitation = invitation
+    end
+
+    def success?
+      false
+    end
+
+    def failure?
+      true
+    end
+
+    def failure_reason
+      reason
+    end
+
+    REASONS.each do |value|
+      define_method("#{value}?") do
+        reason == value
+      end
+    end
+  end
+end

data/lib/organizations/invitation_acceptance_result.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Value object returned by accept_pending_organization_invitation!
+  # Encapsulates the result of an invitation acceptance attempt.
+  #
+  # @example Checking result status
+  #   result = accept_pending_organization_invitation!(user)
+  #   if result&.accepted?
+  #     redirect_to dashboard_path, notice: "Welcome!"
+  #   end
+  #
+  class InvitationAcceptanceResult
+    STATUSES = %i[accepted already_member].freeze
+
+    attr_reader :status, :invitation, :membership
+
+    # @param status [Symbol] :accepted or :already_member
+    # @param invitation [Organizations::Invitation] The invitation that was accepted
+    # @param membership [Organizations::Membership] The resulting membership
+    # @param switched [Boolean] Whether organization context was switched (default: false)
+    def initialize(status:, invitation:, membership:, switched: false)
+      unless STATUSES.include?(status)
+        raise ArgumentError, "Invalid status: #{status.inspect}. Must be one of: #{STATUSES.join(', ')}"
+      end
+
+      @status = status
+      @invitation = invitation
+      @membership = membership
+      @switched = switched
+    end
+
+    # @return [Boolean] true if invitation was freshly accepted
+    def accepted?
+      status == :accepted
+    end
+
+    def success?
+      true
+    end
+
+    def failure?
+      false
+    end
+
+    def failure_reason
+      nil
+    end
+
+    # @return [Boolean] true if user was already a member
+    def already_member?
+      status == :already_member
+    end
+
+    # @return [Boolean] true if organization context was switched
+    def switched?
+      !!@switched
+    end
+  end
+end

data/lib/organizations/models/concerns/has_organizations.rb

@@ -204,9 +204,12 @@ module Organizations
 
           # Check if user belongs to any organization
           # Uses efficient EXISTS query
+          # Falls back to DB query when loaded association is empty to avoid stale false negatives
           # @return [Boolean]
           def belongs_to_any_organization?
-            memberships.loaded? ? memberships.any? : memberships.exists?
+            return true if memberships.loaded? && memberships.any?
+
+            memberships.exists?
           end
 
           # Check if user has pending invitations
@@ -271,31 +274,35 @@ module Organizations
           # === Role Checks (specific organization) ===
 
           # Get user's role in a specific organization
-          # Smart about reusing loaded associations
+          # Smart about reusing loaded associations, with DB fallback for stale caches
           # @param org [Organization] The organization
           # @return [Symbol, nil]
           def role_in(org)
             return nil unless org
 
+            # Try org's loaded memberships first
             if org.respond_to?(:association) && org.association(:memberships).loaded?
               membership = org.memberships.find { |m| m.user_id == id }
-              return membership&.role&.to_sym
+              return membership.role.to_sym if membership
             end
 
-            # Try to use already-loaded association first
+            # Try user's loaded memberships
             if memberships.loaded?
               membership = memberships.find { |m| m.organization_id == org.id }
-              return membership&.role&.to_sym
+              return membership.role.to_sym if membership
             end
 
+            # Try loaded organizations' memberships
             if organizations.loaded?
               loaded_org = organizations.find { |candidate| candidate.id == org.id }
               if loaded_org && loaded_org.respond_to?(:association) && loaded_org.association(:memberships).loaded?
                 membership = loaded_org.memberships.find { |m| m.user_id == id }
-                return membership&.role&.to_sym
+                return membership.role.to_sym if membership
               end
             end
 
+            # DB fallback - loaded associations may be stale if membership was created
+            # via another association path (e.g., organization.memberships.create!)
             memberships.find_by(organization_id: org.id)&.role&.to_sym
           end
 
@@ -318,16 +325,15 @@ module Organizations
 
           # Check if user is a member of specific organization
           # Uses efficient EXISTS query
+          # Falls back to DB query when loaded association misses to avoid stale false negatives
+          # (e.g., membership created via organization.memberships.create! bypasses user cache)
           # @param org [Organization] The organization
           # @return [Boolean]
           def is_member_of?(org)
             return false unless org
+            return true if memberships.loaded? && memberships.any? { |m| m.organization_id == org.id }
 
-            if memberships.loaded?
-              memberships.any? { |membership| membership.organization_id == org.id }
-            else
-              memberships.exists?(organization_id: org.id)
-            end
+            memberships.exists?(organization_id: org.id)
           end
 
           # Check if user is viewer (or higher) of specific organization
@@ -369,11 +375,18 @@ module Organizations
 
           # Creates a new organization with this user as owner
           # Sets the new organization as the current organization
-          # @param name_or_options [String, Hash] Organization name or options hash
+          # @param name_or_attributes [String, Hash] Organization name or attributes hash
           # @return [Organizations::Organization]
           # @raise [OrganizationLimitReached] if user has reached their organization limit
-          def create_organization!(name_or_options)
-            name = name_or_options.is_a?(Hash) ? name_or_options[:name] : name_or_options
+          #
+          # @example With just a name
+          #   user.create_organization!("Acme Corp")
+          #
+          # @example With additional attributes
+          #   user.create_organization!(name: "Acme Corp", support_email: "support@acme.com")
+          #
+          def create_organization!(name_or_attributes)
+            attributes = name_or_attributes.is_a?(Hash) ? name_or_attributes : { name: name_or_attributes }
 
             # Check max organizations limit
             settings = self.class.organization_settings
@@ -384,7 +397,7 @@ module Organizations
 
             org = nil
             ActiveRecord::Base.transaction do
-              org = Organizations::Organization.create!(name: name)
+              org = Organizations::Organization.create!(attributes)
 
               Organizations::Membership.create!(
                 user: self,

data/lib/organizations/models/organization.rb

@@ -68,7 +68,11 @@ module Organizations
     # Get the owner's membership
     # @return [Membership, nil]
     def owner_membership
-      memberships.find_by(role: "owner")
+      if association(:memberships).loaded?
+        memberships.find { |membership| membership.role == "owner" }
+      else
+        memberships.find_by(role: "owner")
+      end
     end
 
     # Get all admins (users with admin role or higher)
@@ -244,7 +248,9 @@ module Organizations
         # Lock organization first to prevent concurrent operations
         lock!
 
-        old_owner_membership = owner_membership
+        # Always perform a fresh read in this write path, even if memberships
+        # are preloaded on this instance, to avoid stale-owner selection.
+        old_owner_membership = memberships.find_by(role: "owner")
         new_owner_membership = memberships.find_by(user_id: new_owner.id)
 
         unless old_owner_membership

data/lib/organizations/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Organizations
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/organizations/view_helpers.rb

@@ -21,6 +21,34 @@ module Organizations
   #   </div>
   #
   module ViewHelpers
+    # === Host App Route Helper Delegation ===
+    #
+    # When views are rendered from engine controllers, route helpers like `root_path`
+    # resolve to the engine's routes, not the host app's routes. This delegation
+    # forwards missing route methods to `main_app` so host app routes work transparently.
+    #
+    # Instead of requiring `main_app.root_path` everywhere, you can just use `root_path`.
+    #
+    def method_missing(method, *args, &block)
+      if _organizations_route_helper?(method) && respond_to?(:main_app) && main_app.respond_to?(method)
+        main_app.public_send(method, *args, &block)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      (_organizations_route_helper?(method) && respond_to?(:main_app) && main_app.respond_to?(method)) || super
+    end
+
+    private
+
+    def _organizations_route_helper?(method)
+      method_name = method.to_s
+      method_name.end_with?("_path") || method_name.end_with?("_url")
+    end
+
+    public
     # === Organization Switcher ===
 
     # Returns optimized data for building an organization switcher

data/lib/organizations.rb

@@ -51,23 +51,44 @@ module Organizations
   autoload :CallbackContext, "organizations/callback_context"
   autoload :ActsAsTenantIntegration, "organizations/acts_as_tenant_integration"
   autoload :TestHelpers, "organizations/test_helpers"
+  autoload :CurrentUserResolution, "organizations/current_user_resolution"
+  autoload :InvitationAcceptanceResult, "organizations/invitation_acceptance_result"
+  autoload :InvitationAcceptanceFailure, "organizations/invitation_acceptance_failure"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers
 
-  # Models - autoload directly under Organizations namespace
-  # Model files define Organizations::Organization, etc.
-  autoload :Organization, "organizations/models/organization"
-  autoload :Membership, "organizations/models/membership"
-  autoload :Invitation, "organizations/models/invitation"
-
   # Models module kept for backwards compatibility
   module Models
     module Concerns
+      # HasOrganizations is always autoloaded from lib/ because:
+      # 1. It's extended onto ActiveRecord::Base at boot time via the engine initializer
+      # 2. It doesn't define any associations that point to reloadable classes
       autoload :HasOrganizations, "organizations/models/concerns/has_organizations"
     end
   end
 
+  # In Rails apps, Organization/Membership/Invitation models are loaded from
+  # app/models via Zeitwerk (reload-safe). This is critical because these models
+  # define associations to other reloadable classes (like Pay::Customer), and we
+  # need the association reflections to point to current class objects after reload.
+  #
+  # In non-Rails environments (plain Ruby, tests without Rails), use lib-based autoloading.
+  #
+  # NOTE on the guard: Rails::Engine is defined when `railties` has been required.
+  # In typical usage, this means a Rails app context where Zeitwerk manages app/models.
+  # Edge cases (e.g., requiring railties without a full app) are rare and would need
+  # custom setup anyway. For standard Rails apps, this correctly delegates to Zeitwerk.
+  #
+  # IMPORTANT: The app/models/*.rb entrypoints delegate to lib/ via `load`. This means
+  # Zeitwerk watches the entrypoint files, not the lib/ files. Changes to lib/ model
+  # files during gem development won't auto-reload; restart the server in that case.
+  unless defined?(Rails::Engine)
+    autoload :Organization, "organizations/models/organization"
+    autoload :Membership, "organizations/models/membership"
+    autoload :Invitation, "organizations/models/invitation"
+  end
+
   class << self
     attr_writer :configuration
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-02-20 00:00:00.000000000 Z
+date: 2026-02-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -86,7 +86,6 @@ files:
 - Appraisals
 - CHANGELOG.md
 - CLAUDE.md
-- LICENSE
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -94,8 +93,13 @@ files:
 - app/controllers/organizations/invitations_controller.rb
 - app/controllers/organizations/memberships_controller.rb
 - app/controllers/organizations/organizations_controller.rb
+- app/controllers/organizations/public_controller.rb
+- app/controllers/organizations/public_invitations_controller.rb
 - app/controllers/organizations/switch_controller.rb
 - app/mailers/organizations/invitation_mailer.rb
+- app/models/organizations/invitation.rb
+- app/models/organizations/membership.rb
+- app/models/organizations/organization.rb
 - app/views/organizations/invitation_mailer/invitation_email.html.erb
 - app/views/organizations/invitation_mailer/invitation_email.text.erb
 - config/routes.rb
@@ -110,7 +114,10 @@ files:
 - lib/organizations/callbacks.rb
 - lib/organizations/configuration.rb
 - lib/organizations/controller_helpers.rb
+- lib/organizations/current_user_resolution.rb
 - lib/organizations/engine.rb
+- lib/organizations/invitation_acceptance_failure.rb
+- lib/organizations/invitation_acceptance_result.rb
 - lib/organizations/models/concerns/has_organizations.rb
 - lib/organizations/models/invitation.rb
 - lib/organizations/models/membership.rb

data/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Javi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.