organizations 0.4.1 → 0.4.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5a2f3a64510fcf3f08245894e49fbdd1a2aae8e76b9b9fb17fa2a6baa212c3e9
-  data.tar.gz: 593fdc944621beb95f6bb318ade8ae88e4933a81f25bd273253704ab9f491f05
+  metadata.gz: 41b5d77cf4271b72a242ed018982a20a62de1aa65be8b44aeb0a1bdca6ca095f
+  data.tar.gz: 47da19b07cb78b00d63e3c682389d3b9cce80c10860883af947d25fb75ad4fa1
 SHA512:
-  metadata.gz: 3c5327208fd86db81f8255bf95405736abc01e374e72a190041f31eb4ced7cff63bf2cb7b040d3a4dfc32fcdde7d11282ad6949c70a282eaed1454f318dc9908
-  data.tar.gz: 7537c69f044a08a8e8422549b4b9272768c412ef3c13a97600808bb8b1a5d1102479c7d9c5c5d61e062ecec84be92132a687405f751033fdfc58f29fc2ca0227
+  metadata.gz: 21cd1f525064c45d471ec8a8e271ddb524aa21843130f2124c0e1b2f903aed5edfb8cbe0a3376f1d699983191eabfdada1304b391244ed65f5e1f7292420d693
+  data.tar.gz: f8b6512de051110d180d894a3e23c49f6b16f50b7bb81f0ba8f4d79257f79063ee345f23332d1d923bc3baff0f7feeac56f62f726594a4750a6b7b6522a57acc

data/CHANGELOG.md

@@ -1,3 +1,18 @@
+## [0.4.3] - 2026-03-19
+
+- Added `can_view_billing?` and `can_manage_billing?` view helpers for billing permission checks
+- Refactored `can_manage_organization?` and `can_invite_members?` to use shared permission predicate
+- Fixed `pricing_plans` integration examples to use `current_pricing_plan` (effective plan API)
+- Clarified that billing permissions are authorization checks only, not subscription state indicators
+
+## [0.4.2] - 2026-03-19
+
+- Added `should_create_personal_organization?` predicate as extension seam for conditional personal org creation
+- DSL `create_personal_organization` setting now accepts procs for dynamic evaluation
+- Added `DELETE /memberships/leave` route for users to leave organizations
+- Updated owner deletion guard message to clarify transfer/delete solution
+- Documentation: added "Pattern 4: Hybrid Onboarding" to README
+
 ## [0.4.1] - 2026-03-17
 
 - Fixed `memberships_count` counter cache writes on `Organizations::Membership.create!`

data/README.md

@@ -7,9 +7,9 @@
 
 `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)**
+<img src="docs/organizations-invitation-accept-create-account.webp" width="500" />
 
-[TODO: invitation / member management gif]
+**🎮 [Try the live demo →](https://organizations.rameerez.com)**
 
 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.)
 
@@ -41,6 +41,8 @@ current_user.is_organization_owner?     # => true
 current_user.is_organization_admin?     # => true (owners inherit admin permissions)
 ```
 
+https://github.com/user-attachments/assets/2eddafe2-025b-4670-af9f-e0d5480508c5
+
 ## Installation
 
 Add to your Gemfile:
@@ -74,13 +76,13 @@ That's the simplest setup. You can also configure per-model options:
 class User < ApplicationRecord
   has_organizations do
     max_organizations 5         # Limit how many orgs a user can own (nil = unlimited)
-    create_personal_org true    # Auto-create org on signup (default: false)
+    create_personal_org true    # Auto-create org on signup (default: false). Can also be a proc.
     require_organization true   # Require users to have at least one org (default: false)
   end
 end
 ```
 
-> **Note:** By default, users can exist without any organization (invite-to-join flow). Set `create_personal_org true` if you want to auto-create a personal organization when users sign up.
+> **Note:** By default, users can exist without any organization (invite-to-join flow). Set `create_personal_org true` if you want to auto-create a personal organization when users sign up. For conditional creation, use a proc: `create_personal_org ->(user) { ... }` or override `should_create_personal_organization?` on your User model (see Pattern 4: Hybrid Onboarding).
 
 Mount the engine in your routes:
 
@@ -108,6 +110,8 @@ org = current_user.create_organization!("Acme Corp")
 
 ### Invite teammates
 
+<img src="docs/organizations-team-members.webp" width="500" />
+
 ```ruby
 current_user.send_organization_invite_to!("teammate@example.com")
 # Sends invitation email: "John invited you to join Acme Corp"
@@ -122,6 +126,8 @@ current_user.send_organization_invite_to!("teammate@example.com", organization:
 
 ### Check roles and permissions
 
+<img src="docs/organizations-member-permissions.webp" width="500" />
+
 ```ruby
 # Quick role checks (in current organization)
 current_user.is_organization_owner?   # => true/false
@@ -141,6 +147,8 @@ current_user.is_member_of?(@org)
 
 ### Switch between organizations
 
+<img src="docs/organizations-switcher.webp" width="400" />
+
 ```ruby
 # User belongs to multiple organizations? No problem.
 current_user.organizations        # => [acme, startup_co, personal]
@@ -160,7 +168,7 @@ end
 
 > **Note:** This is an integration pattern, not built-in functionality. You implement the limit checks in your callbacks.
 
-If you're using [`pricing_plans`](https://github.com/rameerez/pricing_plans), you can limit how many members an organization can have based on their subscription using callbacks:
+If you're using [`pricing_plans`](https://github.com/rameerez/pricing_plans), you can limit how many members an organization can have based on their effective pricing plan using callbacks:
 
 ```ruby
 # config/initializers/pricing_plans.rb
@@ -180,7 +188,7 @@ Then hook into the `on_member_invited` callback to enforce limits. **This callba
 Organizations.configure do |config|
   config.on_member_invited do |ctx|
     org = ctx.organization
-    limit = org.current_plan.limit_for(:organization_members)
+    limit = org.current_pricing_plan.limit_for(:organization_members)
 
     if limit && org.member_count >= limit
       raise Organizations::InvitationError, "Member limit reached. Please upgrade your plan."
@@ -428,6 +436,8 @@ class SettingsController < ApplicationController
 end
 ```
 
+`manage_billing` and `view_billing` are authorization checks only. They control who in the organization can access your billing UI, but they do not imply an active Stripe subscription or determine the effective pricing plan.
+
 ### Handling unauthorized access
 
 Configure how unauthorized access is handled:
@@ -652,6 +662,8 @@ org.send_invite_to!("teammate@example.com", invited_by: current_user)
 
 The gem handles **both existing users and new signups** with a single invitation link:
 
+<img src="docs/organizations-invitation-accept-create-account.webp" width="500" />
+
 **For existing users:**
 1. Invitation created → Email sent with unique link
 2. User clicks link → Sees invitation details (org name, inviter, role)
@@ -888,6 +900,165 @@ Organizations.configure do |config|
 end
 ```
 
+## User Onboarding Patterns
+
+The `always_create_personal_organization_for_each_user` setting controls how new users get their first organization. This is one of the most important decisions when integrating the gem.
+
+### Pattern 1: Instant Access (auto-create)
+
+**Think:** Notion, Slack, Trello — "Sign up and start using it in 10 seconds"
+
+```ruby
+config.always_create_personal_organization_for_each_user = true
+config.default_organization_name = "My Workspace"
+```
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  User signs up  →  "My Workspace" created  →  Dashboard 🎉  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+Users land in the app immediately. Zero friction. They can invite teammates later.
+
+```ruby
+# config/initializers/organizations.rb
+Organizations.configure do |config|
+  config.always_create_personal_organization_for_each_user = true
+  config.default_organization_name = "My Workspace"
+  # Or personalize it:
+  # config.default_organization_name = ->(user) { "#{user.email.split('@').first}'s Workspace" }
+end
+```
+
+Best for: productivity tools, note apps, personal SaaS, anything where "just let me in" matters.
+
+### Pattern 2: Guided Onboarding (manual create)
+
+**Think:** Stripe, HubSpot, Salesforce — "Tell us about your company first"
+
+```ruby
+config.always_create_personal_organization_for_each_user = false
+config.redirect_path_when_no_organization = "/onboarding/create_organization"
+```
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│  User signs up  →  Onboarding wizard  →  "Create your company"  →  App  │
+│                    (collect company name, billing email, etc.)           │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+You control the experience. Collect whatever info you need before they enter.
+
+```ruby
+# config/initializers/organizations.rb
+Organizations.configure do |config|
+  config.always_create_personal_organization_for_each_user = false
+  config.redirect_path_when_no_organization = "/onboarding/create_organization"
+  config.no_organization_notice = "Let's set up your company first."
+  config.additional_organization_params = [:billing_email, :company_size, :industry]
+end
+```
+
+```ruby
+# app/controllers/onboarding_controller.rb
+def create_organization
+  @organization = current_user.create_organization!(
+    name: params[:company_name],
+    billing_email: params[:billing_email]
+  )
+  redirect_to dashboard_path
+end
+```
+
+Best for: B2B SaaS, enterprise tools, apps that need company details for billing/compliance.
+
+### Pattern 3: Invitation-Only
+
+**Think:** Internal company tools, private beta, enterprise deployments
+
+```ruby
+config.always_create_personal_organization_for_each_user = false
+config.redirect_path_when_no_organization = "/waiting_room"
+```
+
+```
+┌───────────────────────────────────────────────────────────────────────┐
+│  User signs up  →  "Waiting for invitation" page  →  (nothing yet)    │
+│                                                                       │
+│  Admin invites user  →  User accepts  →  Joins org  →  Dashboard 🎉   │
+└───────────────────────────────────────────────────────────────────────┘
+```
+
+Users can't do anything until an admin invites them. Full control over who gets in.
+
+Best for: internal tools, private beta programs, enterprise B2B where orgs are pre-provisioned.
+
+### Pattern 4: Hybrid Onboarding
+
+**Think:** Best of both worlds — instant access for direct signups, no clutter for invited users
+
+Direct signups get a personal workspace immediately. Invited users skip the personal workspace and join the organization that invited them directly. This avoids creating unnecessary "My Workspace" organizations for users who are joining an existing team.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  Direct signup  →  "My Workspace" auto-created  →  Dashboard 🎉              │
+│                                                                              │
+│  Invited signup  →  No personal org  →  Joins invited org  →  Dashboard 🎉   │
+└──────────────────────────────────────────────────────────────────────────────┘
+```
+
+Implementation requires overriding the `should_create_personal_organization?` method on your User model:
+
+```ruby
+# app/models/user.rb
+class User < ApplicationRecord
+  has_organizations
+
+  # Skip personal org creation for users signing up via invitation
+  attr_accessor :skip_personal_organization
+
+  def should_create_personal_organization?
+    return false if skip_personal_organization
+    super
+  end
+end
+```
+
+Then set the flag before the user is persisted. With Devise, override `build_resource`:
+
+```ruby
+# app/controllers/users/registrations_controller.rb
+class Users::RegistrationsController < Devise::RegistrationsController
+  protected
+
+  def build_resource(hash = {})
+    super
+    # Skip personal org for users signing up via invitation
+    resource.skip_personal_organization = true if pending_organization_invitation?
+  end
+end
+```
+
+The `should_create_personal_organization?` method is the official extension seam. It evaluates:
+1. Your method override (if defined)
+2. The `create_personal_org` setting (boolean or proc)
+3. The global `always_create_personal_organization_for_each_user` config
+
+You can also use a proc for the setting itself:
+
+```ruby
+# In has_organizations block
+has_organizations do
+  create_personal_org ->(user) { !user.skip_personal_organization }
+end
+```
+
+Best for: SaaS products that want instant onboarding for individual users but clean team onboarding for invited members.
+
+---
+
 ## Configuration
 
 Full configuration options:
@@ -1048,7 +1219,7 @@ end
 
 ### Integrates with pricing_plans
 
-Enforce member limits based on pricing plans using callbacks:
+Enforce member limits based on the effective pricing plan using callbacks:
 
 ```ruby
 # In your Organization model

data/app/controllers/organizations/memberships_controller.rb

@@ -79,6 +79,31 @@ module Organizations
       end
     end
 
+    # DELETE /memberships/leave
+    # Leave the current organization (current user removes themselves)
+    # Note: No permission guard needed — users can only leave themselves, and
+    # require_organization! ensures valid org context. Domain rules (can't leave
+    # as last owner, etc.) are enforced by leave_organization!.
+    def leave
+      org_name = current_organization.name
+
+      begin
+        current_user.leave_organization!(current_organization)
+
+        respond_to do |format|
+          format.html { redirect_to organizations_path, notice: "You have left #{org_name}." }
+          format.json { head :no_content }
+        end
+      rescue Models::Concerns::HasOrganizations::CannotLeaveLastOrganization,
+             Models::Concerns::HasOrganizations::CannotLeaveAsLastOwner,
+             Error => e
+        respond_to do |format|
+          format.html { redirect_back fallback_location: organizations_path, alert: e.message }
+          format.json { render json: { error: e.message }, status: :unprocessable_entity }
+        end
+      end
+    end
+
     # POST /memberships/:id/transfer_ownership
     # Transfer organization ownership to another member
     def transfer_ownership

data/config/routes.rb

@@ -15,6 +15,9 @@ Organizations::Engine.routes.draw do
     member do
       post :transfer_ownership
     end
+    collection do
+      delete :leave
+    end
   end
 
   # Invitation management (scoped to current_organization)

data/context7.json

@@ -0,0 +1,4 @@
+{
+  "url": "https://context7.com/rameerez/organizations",
+  "public_key": "pk_HibNJE5rTFvy1txHHXUot"
+}

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

@@ -6,11 +6,33 @@ Organizations.configure do |config|
   # ============================================================================
 
   # Automatically create a personal organization when a user signs up.
-  # The organization will be named after the user (e.g., "John's Organization").
+  # The organization will be named using default_organization_name (below).
   # Set to true if you want every user to have their own organization on signup.
   # Default: false (invite-to-join flow)
   # config.always_create_personal_organization_for_each_user = false
 
+  # NOTE: This is a coarse, global default. For conditional creation (e.g., skip
+  # personal org for invited signups), override should_create_personal_organization?
+  # on your User model instead:
+  #
+  #   class User < ApplicationRecord
+  #     has_organizations
+  #     attr_accessor :skip_personal_organization
+  #
+  #     def should_create_personal_organization?
+  #       return false if skip_personal_organization
+  #       super
+  #     end
+  #   end
+  #
+  # See "Pattern 4: Hybrid Onboarding" in the README for the full pattern.
+
+  # Name for auto-created organizations.
+  # Can be a string or a proc that receives the user.
+  # Default: "Personal"
+  # config.default_organization_name = "My Workspace"
+  # config.default_organization_name = ->(user) { "#{user.name}'s Workspace" }
+
   # ============================================================================
   # ORGANIZATION REQUIREMENTS
   # ============================================================================

data/lib/organizations/configuration.rb

@@ -33,10 +33,41 @@ module Organizations
     attr_accessor :authenticate_user_method
 
     # === Auto-creation ===
-    # Create personal organization on user signup
+    #
+    # Create personal organization automatically on user signup.
+    #
+    # This setting controls the user's first-time experience:
+    #
+    # ┌─────────────────────────────────────────────────────────────────────────┐
+    # │  true  → "Instant access" pattern                                       │
+    # │                                                                         │
+    # │  User signs up → auto-created workspace → lands in app immediately      │
+    # │                                                                         │
+    # │  Think: Notion, Slack, Trello                                           │
+    # │  "Sign up and start using it in seconds"                                │
+    # │                                                                         │
+    # │  Best for: productivity tools, note apps, simple SaaS                   │
+    # └─────────────────────────────────────────────────────────────────────────┘
+    #
+    # ┌─────────────────────────────────────────────────────────────────────────┐
+    # │  false → "Guided onboarding" pattern                                    │
+    # │                                                                         │
+    # │  User signs up → onboarding wizard → enters company info → dashboard    │
+    # │                                                                         │
+    # │  Think: Stripe, HubSpot, enterprise B2B tools                           │
+    # │  "Tell us about your company before you start"                          │
+    # │                                                                         │
+    # │  Best for: B2B SaaS needing company details, billing info, etc.         │
+    # └─────────────────────────────────────────────────────────────────────────┘
+    #
+    # Related settings:
+    #   - default_organization_name: Name for auto-created orgs (only when true)
+    #   - redirect_path_when_no_organization: Where to send users without an org
+    #   - always_require_users_to_belong_to_one_organization: Prevent leaving last org
+    #
     attr_accessor :always_create_personal_organization_for_each_user
 
-    # Name for auto-created organizations
+    # Name for auto-created organizations (only used when always_create_personal_organization_for_each_user = true)
     # Can be a String or a Proc/Lambda: ->(user) { "#{user.name}'s Workspace" }
     attr_accessor :default_organization_name
 

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

@@ -37,7 +37,8 @@ module Organizations
           # Enable organization support on this model
           # @param options [Hash] Configuration options
           # @option options [Integer, nil] :max_organizations Maximum orgs user can own
-          # @option options [Boolean] :create_personal_org Create personal org on signup
+          # @option options [Boolean, Proc] :create_personal_org Create personal org on signup.
+          #   Can be a boolean or a proc that receives the user instance for conditional creation.
           # @option options [Boolean] :require_organization Require user to have an org
           # @yield Configuration block using DSL
           def has_organizations(**options, &block)
@@ -111,9 +112,10 @@ module Organizations
           end
 
           def setup_personal_org_callback
-            after_create :create_personal_organization_if_configured, if: -> {
-              self.class.organization_settings[:create_personal_org]
-            }
+            # Callback that creates personal organization.
+            # The condition is checked inside the callback to ensure it's evaluated
+            # at the right time with the correct instance state.
+            after_create :create_personal_organization_if_configured
           end
 
           def setup_owner_deletion_guard
@@ -136,7 +138,14 @@ module Organizations
           end
 
           # Enable/disable personal organization creation on signup
-          # @param value [Boolean]
+          # @param value [Boolean, Proc] Boolean or proc that receives the user instance
+          #
+          # @example Boolean (backward-compatible)
+          #   create_personal_org true
+          #
+          # @example Proc for conditional creation
+          #   create_personal_org ->(user) { !user.skip_personal_organization }
+          #
           def create_personal_org(value)
             @settings[:create_personal_org] = value
           end
@@ -499,9 +508,41 @@ module Organizations
             org.send_invite_to!(email, invited_by: self, role: role)
           end
 
+          # Extension seam for personal organization creation.
+          # Override this method in your User model to implement custom logic.
+          #
+          # @return [Boolean] true if a personal organization should be created
+          #
+          # @example Skip personal org for invited signups
+          #   class User < ApplicationRecord
+          #     has_organizations
+          #     attr_accessor :skip_personal_organization
+          #
+          #     def should_create_personal_organization?
+          #       return false if skip_personal_organization
+          #       super
+          #     end
+          #   end
+          #
+          def should_create_personal_organization?
+            setting = self.class.organization_settings[:create_personal_org]
+
+            case setting
+            when Proc
+              setting.call(self)
+            else
+              !!setting
+            end
+          end
+
           private
 
           def create_personal_organization_if_configured
+            # Check condition inside callback (not via `if:` option) to ensure
+            # proper evaluation of instance state, including singleton methods
+            # and dynamically-set attributes.
+            return unless should_create_personal_organization?
+
             org_name = Organizations.configuration.resolve_default_organization_name(self)
             create_organization!(org_name)
           rescue StandardError => e
@@ -512,7 +553,7 @@ module Organizations
           def prevent_deletion_while_owning_organizations
             return unless memberships.where(role: "owner").exists?
 
-            errors.add(:base, "Cannot delete a user who still owns organizations. Transfer ownership first.")
+            errors.add(:base, "Cannot delete a user who still owns organizations. Transfer ownership or delete those organizations first.")
             throw(:abort)
           end
         end

data/lib/organizations/version.rb

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

data/lib/organizations/view_helpers.rb

@@ -213,10 +213,7 @@ module Organizations
     # @param organization [Organizations::Organization] The organization
     # @return [Boolean]
     def can_manage_organization?(user, organization)
-      return false unless user && organization
-
-      role = user.role_in(organization)
-      role && Roles.has_permission?(role, :manage_settings)
+      user_has_permission_in_org?(user, organization, :manage_settings)
     end
 
     # Check if current user can invite members
@@ -225,10 +222,25 @@ module Organizations
     # @param organization [Organizations::Organization] The organization
     # @return [Boolean]
     def can_invite_members?(user, organization)
-      return false unless user && organization
+      user_has_permission_in_org?(user, organization, :invite_members)
+    end
 
-      role = user.role_in(organization)
-      role && Roles.has_permission?(role, :invite_members)
+    # Check if current user can view billing information
+    # Uses permission-based check to respect custom role configurations
+    # @param user [User] The user
+    # @param organization [Organizations::Organization] The organization
+    # @return [Boolean]
+    def can_view_billing?(user, organization)
+      user_has_permission_in_org?(user, organization, :view_billing)
+    end
+
+    # Check if current user can manage billing
+    # Uses permission-based check to respect custom role configurations
+    # @param user [User] The user
+    # @param organization [Organizations::Organization] The organization
+    # @return [Boolean]
+    def can_manage_billing?(user, organization)
+      user_has_permission_in_org?(user, organization, :manage_billing)
     end
 
     # Check if current user can remove a member

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: organizations
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.3
 platform: ruby
 authors:
 - rameerez
 bindir: exe
 cert_chain: []
-date: 2026-03-17 00:00:00.000000000 Z
+date: 2026-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -103,6 +103,11 @@ files:
 - app/views/organizations/invitation_mailer/invitation_email.html.erb
 - app/views/organizations/invitation_mailer/invitation_email.text.erb
 - config/routes.rb
+- context7.json
+- docs/organizations-invitation-accept-create-account.webp
+- docs/organizations-member-permissions.webp
+- docs/organizations-switcher.webp
+- docs/organizations-team-members.webp
 - gemfiles/rails_7.2.gemfile
 - gemfiles/rails_8.1.gemfile
 - lib/generators/organizations/install/install_generator.rb