organizations 0.4.2 → 0.5.0

data/app/controllers/organizations/application_controller.rb

@@ -76,3 +76,7 @@ module Organizations
     end
   end
 end
+
+# Host extension seam — see the load-hooks note in
+# lib/organizations/models/organization.rb.
+ActiveSupport.run_load_hooks(:organizations_application_controller, Organizations::ApplicationController)

data/app/controllers/organizations/memberships_controller.rb

@@ -142,16 +142,16 @@ module Organizations
       # Can't change your own role
       if @membership.user_id == current_user.id
         raise Organizations::NotAuthorized.new(
-          "You cannot change your own role",
+          Organizations.t(:"errors.cannot_change_own_role"),
           permission: :edit_member_roles,
           organization: current_organization,
           user: current_user
         )
       end
 
-      # Validate the new role is valid
+      # Validate the new role is valid (user-reachable via form params, so localized)
       unless Roles.valid_role?(new_role)
-        raise Organizations::Error, "Invalid role: #{new_role}"
+        raise Organizations::Error, Organizations.t(:"errors.invalid_role", role: new_role)
       end
 
       # Note: Owner promotion/demotion rules are enforced by Organization#change_role_of!

data/app/controllers/organizations/public_controller.rb

@@ -28,6 +28,24 @@ module Organizations
     # Minimal helpers needed for public routes
     helper_method :current_user if respond_to?(:helper_method)
 
+    # Host helper decoration (config.public_controller_helpers): this
+    # controller deliberately does NOT inherit the host ApplicationController
+    # (to dodge auth filters), which also means host layouts rendered by
+    # public pages (invitation acceptance in the app's devise/marketing
+    # layout) are missing the app's helper modules. Both known production
+    # hosts hand-patched exactly this in an initializer — declare it instead:
+    #
+    #   config.public_controller_helpers = ["ApplicationHelper", "PageHelper"]
+    #
+    # Strings are constantized HERE, at controller-class load time (after
+    # initializers, reload-safe), so the initializer never has to reference
+    # autoloadable constants directly.
+    if respond_to?(:helper)
+      Organizations.configuration.public_controller_helpers.each do |helper_module|
+        helper(helper_module.is_a?(Module) ? helper_module : helper_module.to_s.constantize)
+      end
+    end
+
     private
 
     # Returns the current user from the host application (if any).
@@ -59,3 +77,11 @@ module Organizations
     helper_method :main_app if respond_to?(:helper_method)
   end
 end
+
+# Host extension seam — see the load-hooks note in
+# lib/organizations/models/organization.rb. Typical use: decorating this
+# controller with host helper modules its layout needs (it inherits
+# ActionController::Base, NOT the host ApplicationController, so app helpers
+# aren't present by default). Prefer config.public_controller_helpers for
+# that common case; this hook is for arbitrary decoration.
+ActiveSupport.run_load_hooks(:organizations_public_controller, Organizations::PublicController)

data/app/mailers/organizations/invitation_mailer.rb

@@ -11,6 +11,13 @@ module Organizations
   #   InvitationMailer.invitation_email(invitation).deliver_later
   #
   class InvitationMailer < ActionMailer::Base
+    # Self-register the gem's app/views so this mailer renders OUTSIDE a full
+    # Rails app too (plain-ActiveRecord consumers, this gem's own test env).
+    # Under Rails the engine already provides the path — appending a
+    # duplicate is harmless (lowest precedence), and host template overrides
+    # in the app's own app/views still win.
+    append_view_path File.expand_path("../../views", __dir__)
+
     default from: -> { default_from_address }
 
     # Invitation email
@@ -20,18 +27,23 @@ module Organizations
       @invitation = invitation
       @organization = invitation.organization
       @inviter = invitation.invited_by
+      @inviter_name = inviter_name
       @accept_url = invitation_accept_url(invitation)
+      # Pre-formatted in the mailer (not the templates) so the strftime
+      # fallback lives in exactly one place — see #format_expiry.
+      @expires_on = @invitation.expires_at ? format_expiry(@invitation.expires_at) : nil
 
       mail(
         to: invitation.email,
-        subject: "#{inviter_name} invited you to join #{@organization.name}"
+        subject: Organizations.t(:"mailers.invitation.subject",
+                                 inviter: @inviter_name, organization: @organization.name)
       )
     end
 
     private
 
     def inviter_name
-      return "The team" unless @inviter
+      return Organizations.t(:"mailers.from_team") unless @inviter
 
       if @inviter.respond_to?(:name) && @inviter.name.present?
         @inviter.name
@@ -40,25 +52,33 @@ module Organizations
       end
     end
 
+    # Localize the expiry timestamp when the host has date/time translations
+    # (rails-i18n or its own time.formats.long); otherwise fall back to the
+    # historical English strftime. Bare i18n (this gem's own test env, plain
+    # Ruby consumers) has no time formats, and I18n.l raises in that case —
+    # never let a missing date format break invitation delivery.
+    def format_expiry(time)
+      I18n.l(time, format: :long)
+    rescue I18n::MissingTranslationData, I18n::ArgumentError
+      time.strftime("%B %d, %Y at %I:%M %p %Z")
+    end
+
     def invitation_accept_url(invitation)
-      if defined?(Rails) && Rails.application&.routes
-        # Try to use the engine routes
-        begin
-          Organizations::Engine.routes.url_helpers.invitation_url(
-            invitation.token,
-            host: default_host
-          )
-        rescue StandardError
-          # Fallback to basic URL construction
-          "#{default_host}/invitations/#{invitation.token}"
-        end
-      else
-        "/invitations/#{invitation.token}"
-      end
+      # ONE implementation for acceptance URLs: Invitation#acceptance_url
+      # (mount-point aware via Organizations.engine_mount_path). The previous
+      # engine-url_helpers attempt here was mount-UNAWARE — raw engine route
+      # helpers don't know where the host mounted the engine, so links broke
+      # for any non-root mount.
+      invitation.acceptance_url(base_url: full_rails_app? ? default_host : "")
+    end
+
+    # SSOT for the bare-`Rails`-module guard — see Organizations.full_rails_app?.
+    def full_rails_app?
+      Organizations.full_rails_app?
     end
 
     def default_from_address
-      if defined?(Rails) && Rails.application&.config&.action_mailer&.default_options
+      if full_rails_app? && Rails.application.config.action_mailer&.default_options
         Rails.application.config.action_mailer.default_options[:from] || "noreply@example.com"
       else
         "noreply@example.com"
@@ -66,7 +86,7 @@ module Organizations
     end
 
     def default_host
-      if defined?(Rails) && Rails.application&.config&.action_mailer&.default_url_options
+      if full_rails_app? && Rails.application.config.action_mailer&.default_url_options
         options = Rails.application.config.action_mailer.default_url_options
         protocol = options[:protocol] || "https"
         host = options[:host] || "localhost"

data/app/mailers/organizations/verification_mailer.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Mailer for emailed verification codes (verified joining).
+  # Can be customized via Organizations.configuration.verification_mailer —
+  # custom mailers must implement `code_email(join_request, code)`.
+  #
+  # SECURITY: `code` is the plaintext one-time code. It exists only in this
+  # delivery path — the database stores a digest (see JoinRequest).
+  #
+  # @example
+  #   VerificationMailer.code_email(join_request, "492817").deliver_later
+  #
+  class VerificationMailer < ActionMailer::Base
+    # Self-register the gem's app/views — see InvitationMailer for rationale.
+    append_view_path File.expand_path("../../views", __dir__)
+
+    default from: -> { default_from_address }
+
+    # Verification code email
+    # @param join_request [Organizations::JoinRequest]
+    # @param code [String] the plaintext 6-digit code
+    # @return [Mail::Message]
+    def code_email(join_request, code)
+      @join_request = join_request
+      @organization = join_request.organization
+      @code = code
+      @expires_in_minutes = ttl_minutes
+
+      mail(
+        to: join_request.verification_email,
+        subject: Organizations.t(:"mailers.verification.subject",
+                                 code: @code, organization: @organization.name)
+      )
+    end
+
+    private
+
+    def ttl_minutes
+      ttl = Organizations.configuration.verification_code_ttl
+      (ttl.to_i / 60.0).ceil
+    end
+
+    def default_from_address
+      # Deliberately identical to InvitationMailer#default_from_address —
+      # keep the two in sync. The bare-`Rails`-module guard lives in ONE
+      # place: Organizations.full_rails_app?.
+      if Organizations.full_rails_app? &&
+         Rails.application.config.action_mailer&.default_options
+        Rails.application.config.action_mailer.default_options[:from] || "noreply@example.com"
+      else
+        "noreply@example.com"
+      end
+    end
+  end
+end

data/app/models/organizations/allowlist_entry.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::AllowlistEntry 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/allowlist_entry.rb", __dir__)

data/app/models/organizations/domain.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::Domain 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/domain.rb", __dir__)

data/app/models/organizations/join_code.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::JoinCode 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/join_code.rb", __dir__)

data/app/models/organizations/join_request.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Reloadable entrypoint for Organizations::JoinRequest 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/join_request.rb", __dir__)

data/app/views/organizations/invitation_mailer/invitation_email.html.erb

@@ -3,7 +3,7 @@
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>You're invited to join <%= @organization.name %></title>
+  <title><%= Organizations.t(:"mailers.invitation.title", organization: @organization.name) %></title>
   <style>
     body {
       font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
@@ -53,45 +53,48 @@
 </head>
 <body>
   <div class="header">
-    <h1>You're invited!</h1>
+    <h1><%= Organizations.t(:"mailers.invitation.header") %></h1>
   </div>
 
   <div class="content">
-    <p>Hi there,</p>
+    <p><%= Organizations.t(:"mailers.invitation.greeting") %></p>
 
     <p>
+      <%# The *_html keys go through the view `t` helper: its _html-suffix
+          convention marks the translation html_safe while HTML-escaping every
+          interpolated value (inviter/org names are user input). Source:
+          https://guides.rubyonrails.org/i18n.html#using-safe-html-translations %>
       <% if @inviter %>
-        <strong><%= @inviter.respond_to?(:name) && @inviter.name.present? ? @inviter.name : @inviter.email %></strong>
-        has invited you to join <strong><%= @organization.name %></strong>.
+        <%= t("organizations.mailers.invitation.invited_by_html", inviter: @inviter_name, organization: @organization.name) %>
       <% else %>
-        You've been invited to join <strong><%= @organization.name %></strong>.
+        <%= t("organizations.mailers.invitation.invited_generic_html", organization: @organization.name) %>
       <% end %>
     </p>
 
     <p>
-      You'll be joining as:
-      <span class="role-badge"><%= @invitation.role.to_s.capitalize %></span>
+      <%= Organizations.t(:"mailers.invitation.joining_as_label") %>
+      <span class="role-badge"><%= Organizations.t(:"roles.#{@invitation.role}", default: @invitation.role.to_s.capitalize) %></span>
     </p>
 
     <p style="text-align: center;">
-      <a href="<%= @accept_url %>" class="button">Accept Invitation</a>
+      <a href="<%= @accept_url %>" class="button"><%= Organizations.t(:"mailers.invitation.accept_button") %></a>
     </p>
 
     <p>
-      Or copy and paste this link into your browser:<br>
+      <%= Organizations.t(:"mailers.invitation.copy_link") %><br>
       <a href="<%= @accept_url %>"><%= @accept_url %></a>
     </p>
 
-    <% if @invitation.expires_at %>
+    <% if @expires_on %>
     <p style="color: #666; font-size: 14px;">
-      This invitation will expire on <%= @invitation.expires_at.strftime("%B %d, %Y at %I:%M %p %Z") %>.
+      <%= Organizations.t(:"mailers.invitation.expires_on", date: @expires_on) %>
     </p>
     <% end %>
   </div>
 
   <div class="footer">
     <p>
-      If you weren't expecting this invitation, you can safely ignore this email.
+      <%= Organizations.t(:"mailers.invitation.ignore") %>
     </p>
   </div>
 </body>

data/app/views/organizations/invitation_mailer/invitation_email.text.erb

@@ -1,18 +1,18 @@
-You're invited to join <%= @organization.name %>!
+<%= Organizations.t(:"mailers.invitation.title", organization: @organization.name) %>
 
-Hi there,
+<%= Organizations.t(:"mailers.invitation.greeting") %>
 
-<% if @inviter %><%= @inviter.respond_to?(:name) && @inviter.name.present? ? @inviter.name : @inviter.email %> has invited you to join <%= @organization.name %>.<% else %>You've been invited to join <%= @organization.name %>.<% end %>
+<% if @inviter %><%= Organizations.t(:"mailers.invitation.invited_by", inviter: @inviter_name, organization: @organization.name) %><% else %><%= Organizations.t(:"mailers.invitation.invited_generic", organization: @organization.name) %><% end %>
 
-You'll be joining as: <%= @invitation.role.to_s.capitalize %>
+<%= Organizations.t(:"mailers.invitation.joining_as", role: Organizations.t(:"roles.#{@invitation.role}", default: @invitation.role.to_s.capitalize)) %>
 
-Accept your invitation here:
+<%= Organizations.t(:"mailers.invitation.accept_cta") %>
 <%= @accept_url %>
 
-<% if @invitation.expires_at %>
-This invitation will expire on <%= @invitation.expires_at.strftime("%B %d, %Y at %I:%M %p %Z") %>.
+<% if @expires_on %>
+<%= Organizations.t(:"mailers.invitation.expires_on", date: @expires_on) %>
 <% end %>
 
 ---
 
-If you weren't expecting this invitation, you can safely ignore this email.
+<%= Organizations.t(:"mailers.invitation.ignore") %>

data/app/views/organizations/verification_mailer/code_email.html.erb

@@ -0,0 +1,22 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta content="text/html; charset=UTF-8" http-equiv="Content-Type" />
+  </head>
+  <body style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; color: #111827; margin: 0; padding: 24px;">
+    <%# _html key via the view `t` helper: html_safe translation, escaped
+        interpolations (the org name is user input). Source:
+        https://guides.rubyonrails.org/i18n.html#using-safe-html-translations %>
+    <p><%= t("organizations.mailers.verification.lead_html", organization: @organization.name) %></p>
+
+    <p style="font-size: 32px; font-weight: 700; letter-spacing: 6px; background: #f3f4f6; border-radius: 8px; display: inline-block; padding: 12px 24px;">
+      <%= @code %>
+    </p>
+
+    <p><%= Organizations.t(:"mailers.verification.expires", minutes: @expires_in_minutes) %></p>
+
+    <p style="color: #6b7280; font-size: 14px;">
+      <%= Organizations.t(:"mailers.verification.ignore", organization: @organization.name) %>
+    </p>
+  </body>
+</html>

data/app/views/organizations/verification_mailer/code_email.text.erb

@@ -0,0 +1,7 @@
+<%= Organizations.t(:"mailers.verification.lead", organization: @organization.name) %>
+
+  <%= @code %>
+
+<%= Organizations.t(:"mailers.verification.expires", minutes: @expires_in_minutes) %>
+
+<%= Organizations.t(:"mailers.verification.ignore", organization: @organization.name) %>

data/config/locales/en.yml

@@ -0,0 +1,158 @@
+# Organizations gem — English (default) locale.
+#
+# This file is the SINGLE SOURCE OF TRUTH for every user-facing string the
+# gem produces: error messages raised by the models, role/status labels used
+# by the view helpers, model validation messages, and the stock mailer copy.
+#
+# Hosts override any of these the standard Rails way: define the same keys in
+# the app's own locale files (app files load after engine files, so they win).
+# See README "Internationalization (i18n)".
+#
+# ⚠️ Developer-facing errors (ArgumentError, ConfigurationError, wrong-API
+# usage like "user is required") are deliberately NOT translated — they are
+# for programmers, and English keeps them greppable/searchable.
+#
+# ⚠️ Keys under `errors:` are 1:1 with raise sites in lib/organizations/**.
+# If you add a raise site, add its key HERE (and to es.yml) — a missing key
+# renders as "Translation missing: ..." which is a loud, findable bug.
+en:
+  organizations:
+    # Role labels (used by organization_role_label / organization_role_info)
+    roles:
+      owner: "Owner"
+      admin: "Admin"
+      member: "Member"
+      viewer: "Viewer"
+
+    # Invitation status labels (organization_invitation_status_label)
+    invitation_status:
+      pending: "Pending"
+      accepted: "Accepted"
+      expired: "Expired"
+
+    # Join request statuses — lowercase on purpose: interpolated mid-sentence
+    # into errors.join_request_already_decided ("...has already been %{status}").
+    join_request_status:
+      pending: "pending"
+      approved: "approved"
+      rejected: "rejected"
+      withdrawn: "withdrawn"
+      expired: "expired"
+
+    errors:
+      # — Join codes —
+      join_code_invalid: "This code is not valid"
+      join_code_exhausted: "This code has reached its usage limit"
+
+      # — Join requests —
+      join_request_expired: "This join request has expired"
+      join_request_already_decided: "This join request has already been %{status}"
+      join_request_already_member: "You are already a member of this organization"
+      join_request_create_failed: "Could not create join request"
+      join_request_membership_gone: "Request was approved but the membership no longer exists"
+
+      # — Membership veto gate (on_member_joining raising MembershipVetoed) —
+      # Default shown when the host's veto raises without its own message.
+      membership_vetoed: "You can't join this organization right now"
+
+      # — Email verification challenge —
+      verification_email_invalid: "This is not a valid email address"
+      verification_email_not_eligible: "This email address is not eligible to join this organization"
+      verification_email_already_claimed: "This email address is already associated with a member of this organization"
+      verification_code_invalid: "The code is incorrect"
+      verification_code_missing: "No verification code is active for this request"
+      verification_code_expired: "This code has expired — request a new one"
+      verification_attempts_exceeded: "Too many incorrect attempts — request a new code"
+      verification_sends_exceeded: "Too many codes requested for this request"
+      verification_resend_throttled: "Please wait before requesting another code"
+      account_email_trust_disabled: "Account-email trust is disabled (see config.trust_confirmed_account_email)"
+      account_email_unconfirmed: "The account email has not been confirmed"
+      not_accepting_requests: "This organization is not accepting join requests right now"
+
+      # — Invitations —
+      invitation_expired: "This invitation has expired"
+      invitation_already_accepted: "This invitation has already been accepted"
+      invitation_cannot_resend_accepted: "Cannot resend an accepted invitation"
+      invitation_email_mismatch: "This invitation was sent to a different email address"
+      invitation_accept_as_owner: "Cannot accept invitation as owner. Invite as admin, then use transfer_ownership_to! after joining."
+      invitation_already_member: "User is already a member of this organization"
+      invite_as_owner: "Cannot invite as owner. Invite as admin, then use transfer_ownership_to! after they join."
+      invite_not_a_member: "Only organization members can send invitations"
+      invite_not_authorized: "You don't have permission to invite members"
+
+      # — Ownership / role invariants (reachable from admin UIs) —
+      cannot_remove_owner: "Cannot remove the organization owner. Transfer ownership first."
+      cannot_add_as_owner: "Cannot add member as owner. Use transfer_ownership_to! instead."
+      cannot_promote_to_owner: "Cannot promote to owner. Use transfer_ownership_to! instead."
+      cannot_demote_owner_directly: "Cannot demote owner directly. Use transfer_ownership_to! instead."
+      cannot_demote_owner: "Cannot demote owner. Transfer ownership first."
+      promote_not_higher: "Cannot promote to %{new_role} - it's not a higher role than %{role}"
+      demote_not_lower: "Cannot demote to %{new_role} - it's not a lower role than %{role}"
+      transfer_no_owner: "Cannot transfer ownership because organization has no owner membership"
+      transfer_to_non_member: "Cannot transfer ownership to a non-member"
+      transfer_to_non_admin: "Cannot transfer ownership to non-admin. Promote them to admin first."
+
+      # — Leaving / user-level —
+      cannot_leave_as_last_owner: "Cannot leave organization as the only owner. Transfer ownership first."
+      cannot_leave_last_organization: "Cannot leave your only organization"
+      organization_limit_reached: "Maximum number of organizations (%{max}) reached"
+      no_current_organization_to_leave: "No current organization to leave"
+      cannot_delete_user_owns_organizations: "Cannot delete a user who still owns organizations. Transfer ownership or delete those organizations first."
+
+      # — Controller guards (default unauthorized copy) —
+      unauthorized_role: "You need %{role} access to perform this action"
+      unauthorized_permission: "You don't have permission to %{permission}"
+      unauthorized: "You are not authorized to perform this action"
+      not_a_member: "You are not a member of this organization"
+      organization_required: "Organization required"
+      cannot_change_own_role: "You cannot change your own role"
+      invalid_role: "Invalid role: %{role}"
+
+    # Flash notices produced by the controller-helper invitation flow.
+    notices:
+      welcome: "Welcome to %{organization}!"
+      already_member: "You're already a member of %{organization}."
+      select_or_create_organization: "Please select or create an organization."
+
+    # Model validation messages (errors.add second argument). These read as
+    # "<Attribute> <message>" in full_messages — keep them lowercase fragments.
+    attributes:
+      membership_taken: "is already a member of this organization"
+      owner_taken: "owner already exists for this organization"
+      pending_request_taken: "already has a pending request for this organization"
+      invitation_taken: "has already been invited to this organization"
+      allowlist_taken: "is already on this organization's allowlist"
+      domain_invalid: "is not a valid domain name"
+
+    # Stock mailer copy. Hosts that swap in their own mailer
+    # (config.invitation_mailer / config.verification_mailer) ignore all of
+    # this; hosts that keep the stock mailers can retheme by overriding keys.
+    mailers:
+      from_team: "The team"
+      invitation:
+        subject: "%{inviter} invited you to join %{organization}"
+        header: "You're invited!"
+        title: "You're invited to join %{organization}!"
+        greeting: "Hi there,"
+        invited_by: "%{inviter} has invited you to join %{organization}."
+        # _html variants: rendered through the view `t` helper, whose *_html
+        # convention marks the string html_safe and HTML-escapes every
+        # interpolated argument (Rails i18n guide §4.1.2 "HTML translations",
+        # https://guides.rubyonrails.org/i18n.html) — keep markup here, never
+        # in the interpolated values.
+        invited_by_html: "<strong>%{inviter}</strong> has invited you to join <strong>%{organization}</strong>."
+        invited_generic: "You've been invited to join %{organization}."
+        invited_generic_html: "You've been invited to join <strong>%{organization}</strong>."
+        joining_as: "You'll be joining as: %{role}"
+        joining_as_label: "You'll be joining as:"
+        accept_cta: "Accept your invitation here:"
+        accept_button: "Accept Invitation"
+        copy_link: "Or copy and paste this link into your browser:"
+        expires_on: "This invitation will expire on %{date}."
+        ignore: "If you weren't expecting this invitation, you can safely ignore this email."
+      verification:
+        subject: "%{code} is your %{organization} verification code"
+        lead: "Use this code to verify your email address and join %{organization}:"
+        lead_html: "Use this code to verify your email address and join <strong>%{organization}</strong>:"
+        expires: "The code expires in %{minutes} minutes."
+        ignore: "If you didn't request this code, you can safely ignore this email — nobody can join %{organization} with your address without it."