organizations 0.4.3 → 0.6.0

data/lib/organizations.rb

@@ -41,6 +41,52 @@ module Organizations
   class InvitationAlreadyAccepted < InvitationError; end
   class InvitationEmailMismatch < InvitationError; end
 
+  # User-level membership errors — canonical TOP-LEVEL homes (0.5.0). These
+  # were historically defined four modules deep inside the HasOrganizations
+  # concern, forcing hosts to rescue
+  # Organizations::Models::Concerns::HasOrganizations::CannotLeaveAsLastOwner
+  # — a real papercut found in a production host. The nested constants are
+  # kept as aliases; rescue THESE.
+  class OrganizationLimitReached < Error; end
+  class CannotLeaveLastOrganization < Error; end
+  class CannotLeaveAsLastOwner < Error; end
+  class CannotDeleteAsOrganizationOwner < Error; end
+  class NoCurrentOrganization < Error; end
+
+  # Join request errors (verified joining)
+  class JoinRequestError < Error; end
+  class JoinRequestExpired < JoinRequestError; end
+  class JoinRequestAlreadyDecided < JoinRequestError; end
+
+  # Raised (typically by the host's `on_member_joining` gate) to VETO a
+  # membership that is about to be created — seat limits, member caps,
+  # compliance holds. The gate dispatches strictly inside the creating
+  # transaction, so raising this rolls everything back cleanly: no membership
+  # row, join requests stay pending (resumable), invitations stay unaccepted.
+  # Raising without a message gets the localized default
+  # (organizations.errors.membership_vetoed).
+  class MembershipVetoed < Error
+    def initialize(message = nil)
+      super(message || Organizations.t(:"errors.membership_vetoed"))
+    end
+  end
+
+  # Join code errors (verified joining)
+  # JoinCodeInvalid covers unknown, revoked, and expired codes — hosts should
+  # show the same generic message for all three (don't leak which codes exist).
+  class JoinCodeError < Error; end
+  class JoinCodeInvalid < JoinCodeError; end
+  class JoinCodeExhausted < JoinCodeInvalid; end
+
+  # Email verification errors (verified joining)
+  class VerificationError < JoinRequestError; end
+  class VerificationEmailNotEligible < VerificationError; end
+  class VerificationEmailAlreadyClaimed < VerificationError; end
+  class VerificationCodeInvalid < VerificationError; end
+  class VerificationCodeExpired < VerificationError; end
+  class VerificationAttemptsExceeded < VerificationError; end
+  class VerificationThrottled < VerificationError; end
+
   # === Autoload Components (lazy loading) ===
 
   autoload :Configuration, "organizations/configuration"
@@ -54,6 +100,11 @@ module Organizations
   autoload :CurrentUserResolution, "organizations/current_user_resolution"
   autoload :InvitationAcceptanceResult, "organizations/invitation_acceptance_result"
   autoload :InvitationAcceptanceFailure, "organizations/invitation_acceptance_failure"
+  autoload :EmailNormalizer, "organizations/email_normalizer"
+  autoload :JoinFlow, "organizations/join_flow"
+  autoload :JoinState, "organizations/join_state"
+  autoload :MetadataFlags, "organizations/metadata_flags"
+  autoload :OrganizationScoped, "organizations/organization_scoped"
 
   # Alias for README compatibility: `include Organizations::Controller`
   Controller = ControllerHelpers
@@ -87,6 +138,19 @@ module Organizations
     autoload :Organization, "organizations/models/organization"
     autoload :Membership, "organizations/models/membership"
     autoload :Invitation, "organizations/models/invitation"
+    autoload :Domain, "organizations/models/domain"
+    autoload :JoinCode, "organizations/models/join_code"
+    autoload :AllowlistEntry, "organizations/models/allowlist_entry"
+    autoload :JoinRequest, "organizations/models/join_request"
+
+    # Non-Rails contexts (plain ActiveRecord, the gem's own test suite) don't
+    # get the Rails engine's automatic `config/locales` pickup, so register
+    # the gem's locale files directly. `|=` keeps this idempotent. In Rails
+    # apps the engine handles it (Rails::Engine adds paths["config/locales"]
+    # to I18n.load_path — https://guides.rubyonrails.org/engines.html).
+    # I18n itself is always available: it's a hard dependency of
+    # activesupport, which this gem depends on.
+    I18n.load_path |= Dir[File.expand_path("../config/locales/*.yml", __dir__)]
   end
 
   class << self
@@ -107,22 +171,123 @@ module Organizations
     #     config.invitation_expiry = 7.days
     #   end
     #
+    # ATOMIC on validation failure: a configure block that raises (typically
+    # via validate!) restores the previous configuration instead of leaving
+    # half-applied settings on the live object. Found the hard way: a
+    # validation-failure left its invalid assignment behind on the shared
+    # config, and every LATER configure call re-raised that stale error —
+    # an order-dependent heisenbug in test suites and a real hazard for
+    # hosts rescuing ConfigurationError in initializers.
+    # NOTE: restoration is a shallow dup — use SETTERS in configure blocks
+    # (config.x = [...]), never in-place mutation (config.x << ...), which
+    # is the documented contract anyway.
     def configure
+      snapshot = configuration.dup
       yield(configuration)
       configuration.validate!
+    rescue StandardError
+      @configuration = snapshot
+      raise
     end
 
     # Reset configuration to defaults
     # Primarily used in tests
     def reset_configuration!
       @configuration = nil
+      remove_instance_variable(:@engine_mount_path) if defined?(@engine_mount_path)
       Roles.reset!
     end
 
+    # The path prefix the engine is mounted at in the HOST app ("" when
+    # mounted at root, "/orgs" when mounted there, "" outside Rails).
+    #
+    # Why this exists: engine route helpers called WITHOUT a controller
+    # context (from models/mailers — e.g. building an invitation acceptance
+    # URL) don't know the mount point, so URLs built as
+    # "/invitations/<token>" silently 404 for any host that mounts the
+    # engine anywhere but root. Both known hosts mount at root, which is
+    # exactly why nobody noticed. Memoized — the mount point is fixed at
+    # boot. Source on mounted helpers vs raw engine url_helpers:
+    # https://guides.rubyonrails.org/engines.html#routes
+    # @return [String]
+    def engine_mount_path
+      return @engine_mount_path if defined?(@engine_mount_path)
+
+      @engine_mount_path = compute_engine_mount_path
+    end
+
+    # @api private
+    def compute_engine_mount_path
+      routes = host_application_routes
+      return "" unless routes && defined?(Organizations::Engine)
+
+      mount = routes.routes.detect do |route|
+        route.app.respond_to?(:app) && route.app.app == Organizations::Engine
+      end
+      return "" unless mount
+
+      # "/orgs(.:format)" → "/orgs"; a root mount "/" → "".
+      mount.path.spec.to_s.delete_suffix("(.:format)").chomp("/")
+    rescue StandardError
+      ""
+    end
+
+    # True only under a real, booted Rails app — the ONE home for this guard
+    # (mailers and URL builders all need it). ⚠️ `defined?(Rails)` alone is
+    # NOT enough: several gems define a bare `Rails` module WITHOUT
+    # `.application` (globalid setups, railtie fragments, bare test
+    # harnesses), where `Rails.application` raises NoMethodError instead of
+    # returning nil. Found by the first tests to ever render the stock mails.
+    def full_rails_app?
+      !!(defined?(Rails) && Rails.respond_to?(:application) && Rails.application)
+    end
+
+    # @api private
+    def host_application_routes
+      return nil unless full_rails_app?
+
+      Rails.application.routes
+    end
+
     # Get the roles module
     # @return [Module]
     def roles
       Roles
     end
+
+    # The host's user model class name (config.user_class, default "User").
+    # Used as `class_name:` at association-definition time in the gem's
+    # models — they load AFTER initializers in Rails (Zeitwerk shims) and on
+    # first constant reference in plain Ruby, so a configured value is
+    # visible as long as hosts configure before touching the models.
+    # @return [String]
+    def user_class_name
+      configuration.user_class
+    end
+
+    # The host's user model class (constantized user_class_name).
+    # @return [Class]
+    def user_class
+      user_class_name.constantize
+    end
+
+    # Resolve a gem string through I18n under the `organizations.` namespace.
+    # This is the ONE door every user-facing string the gem produces goes
+    # through — error messages, labels, mailer copy. en.yml is the catalog
+    # SSOT (no inline English defaults on purpose: a missing key renders as
+    # "Translation missing: …", a loud and findable bug, instead of silently
+    # drifting from the catalog).
+    #
+    # Hosts override any key the standard Rails way — app locale files load
+    # after engine locale files, so the host's value wins.
+    #
+    # @param key [String, Symbol] key under the `organizations.` scope,
+    #   e.g. :"errors.join_code_invalid" or "roles.owner"
+    # @param options [Hash] I18n options (interpolations, :locale, :default…)
+    # @return [String]
+    def translate(key, **)
+      I18n.t(key, scope: :organizations, **)
+    end
+    alias t translate
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.4.3
+  version: 0.6.0
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-19 00:00:00.000000000 Z
+date: 2026-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -81,6 +81,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".rubocop_todo.yml"
 - ".simplecov"
 - AGENTS.md
 - Appraisals
@@ -97,11 +98,20 @@ files:
 - app/controllers/organizations/public_invitations_controller.rb
 - app/controllers/organizations/switch_controller.rb
 - app/mailers/organizations/invitation_mailer.rb
+- app/mailers/organizations/verification_mailer.rb
+- app/models/organizations/allowlist_entry.rb
+- app/models/organizations/domain.rb
 - app/models/organizations/invitation.rb
+- app/models/organizations/join_code.rb
+- app/models/organizations/join_request.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
+- app/views/organizations/verification_mailer/code_email.html.erb
+- app/views/organizations/verification_mailer/code_email.text.erb
+- config/locales/en.yml
+- config/locales/es.yml
 - config/routes.rb
 - context7.json
 - docs/organizations-invitation-accept-create-account.webp
@@ -113,6 +123,19 @@ files:
 - lib/generators/organizations/install/install_generator.rb
 - lib/generators/organizations/install/templates/create_organizations_tables.rb.erb
 - lib/generators/organizations/install/templates/initializer.rb
+- lib/generators/organizations/upgrade/templates/add_verified_joining_to_organizations.rb.erb
+- lib/generators/organizations/upgrade/upgrade_generator.rb
+- lib/generators/organizations/views/templates/organizations/invitations/_form.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/index.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/new.html.erb
+- lib/generators/organizations/views/templates/organizations/invitations/show.html.erb
+- lib/generators/organizations/views/templates/organizations/memberships/index.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/_form.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/edit.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/index.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/new.html.erb
+- lib/generators/organizations/views/templates/organizations/organizations/show.html.erb
+- lib/generators/organizations/views/views_generator.rb
 - lib/organizations.rb
 - lib/organizations/acts_as_tenant_integration.rb
 - lib/organizations/callback_context.rb
@@ -120,13 +143,22 @@ files:
 - lib/organizations/configuration.rb
 - lib/organizations/controller_helpers.rb
 - lib/organizations/current_user_resolution.rb
+- lib/organizations/email_normalizer.rb
 - lib/organizations/engine.rb
 - lib/organizations/invitation_acceptance_failure.rb
 - lib/organizations/invitation_acceptance_result.rb
+- lib/organizations/join_flow.rb
+- lib/organizations/join_state.rb
+- lib/organizations/metadata_flags.rb
+- lib/organizations/models/allowlist_entry.rb
 - lib/organizations/models/concerns/has_organizations.rb
+- lib/organizations/models/domain.rb
 - lib/organizations/models/invitation.rb
+- lib/organizations/models/join_code.rb
+- lib/organizations/models/join_request.rb
 - lib/organizations/models/membership.rb
 - lib/organizations/models/organization.rb
+- lib/organizations/organization_scoped.rb
 - lib/organizations/roles.rb
 - lib/organizations/test_helpers.rb
 - lib/organizations/version.rb