organizations 0.1.0

data/lib/organizations/callback_context.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Immutable context object passed to all callbacks.
+  # Provides consistent, typed access to event data.
+  #
+  # Different events populate different fields:
+  # - :organization_created => organization, user
+  # - :member_invited => organization, invitation, invited_by
+  # - :member_joined => organization, membership, user
+  # - :member_removed => organization, membership, user, removed_by
+  # - :role_changed => organization, membership, old_role, new_role, changed_by
+  # - :ownership_transferred => organization, old_owner, new_owner
+  #
+  # @example Accessing context data
+  #   config.on_organization_created do |ctx|
+  #     Analytics.track(ctx.user, "org_created", name: ctx.organization.name)
+  #   end
+  #
+  CallbackContext = Struct.new(
+    :event,           # Symbol - the event type (:organization_created, :member_joined, etc.)
+    :organization,    # Organizations::Organization instance
+    :user,            # User instance (the subject of the action)
+    :membership,      # Organizations::Membership instance (if applicable)
+    :invitation,      # Organizations::Invitation instance (if applicable)
+    :invited_by,      # User instance - who sent the invitation
+    :removed_by,      # User instance - who removed the member
+    :changed_by,      # User instance - who changed the role
+    :old_role,        # Symbol - previous role (for role_changed)
+    :new_role,        # Symbol - new role (for role_changed)
+    :old_owner,       # User instance - previous owner (for ownership_transferred)
+    :new_owner,       # User instance - new owner (for ownership_transferred)
+    :permission,      # Symbol - the permission that was required (for unauthorized)
+    :required_role,   # Symbol - the role that was required (for unauthorized)
+    :metadata,        # Hash - additional contextual data
+    keyword_init: true
+  ) do
+    # Convert to hash, removing nil values
+    # @return [Hash]
+    def to_h
+      super.compact
+    end
+
+    # Check if this is a specific event type
+    # @param event_name [Symbol] Event to check
+    # @return [Boolean]
+    def event?(event_name)
+      event == event_name
+    end
+  end
+end

data/lib/organizations/callbacks.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Organizations
+  # Centralized callback dispatch module.
+  # Handles executing callbacks with error isolation - callbacks should never
+  # break the main organization operations.
+  #
+  # @example Dispatching a callback
+  #   Callbacks.dispatch(:organization_created, organization: org, user: user)
+  #
+  module Callbacks
+    # Supported callback events
+    EVENTS = %i[
+      organization_created
+      member_invited
+      member_joined
+      member_removed
+      role_changed
+      ownership_transferred
+    ].freeze
+
+    module_function
+
+    # Dispatch a callback event.
+    # By default callbacks are isolated (errors logged, not raised).
+    # Pass strict: true when callback failures must abort the operation.
+    # @param event [Symbol] The event type (e.g., :organization_created)
+    # @param strict [Boolean] When true, callback errors are re-raised
+    # @param context_data [Hash] Data to pass to the callback via CallbackContext
+    def dispatch(event, strict: false, **context_data)
+      callback = callback_for(event)
+      return unless callback
+
+      context = CallbackContext.new(event: event, **context_data)
+      strict ? execute_strictly(callback, context) : execute_safely(event, callback, context)
+    end
+
+    # Get the callback proc for an event
+    # @param event [Symbol] The event type
+    # @return [Proc, nil]
+    def callback_for(event)
+      config = Organizations.configuration
+      return nil unless config
+
+      case event
+      when :organization_created
+        config.on_organization_created_callback
+      when :member_invited
+        config.on_member_invited_callback
+      when :member_joined
+        config.on_member_joined_callback
+      when :member_removed
+        config.on_member_removed_callback
+      when :role_changed
+        config.on_role_changed_callback
+      when :ownership_transferred
+        config.on_ownership_transferred_callback
+      end
+    end
+
+    # Execute callback with error isolation
+    # @param event [Symbol] Event name (for logging)
+    # @param callback [Proc] The callback to execute
+    # @param context [CallbackContext] The context to pass
+    def execute_safely(event, callback, context)
+      return unless callback.respond_to?(:call)
+
+      invoke_callback(callback, context)
+    rescue StandardError => e
+      # Log but don't re-raise - callbacks should never break organization operations
+      log_error("[Organizations] Callback error for #{event}: #{e.class}: #{e.message}")
+      log_debug(e.backtrace&.join("\n"))
+    end
+
+    # Execute callback and propagate any raised errors.
+    # Use this in flows where callbacks are expected to veto the operation.
+    def execute_strictly(callback, context)
+      return unless callback.respond_to?(:call)
+
+      invoke_callback(callback, context)
+    end
+
+    # Call callback while supporting flexible callback arities.
+    def invoke_callback(callback, context)
+      case callback.arity
+      when 0
+        callback.call
+      when 1, -1, -2
+        callback.call(context)
+      else
+        callback.call(context)
+      end
+    end
+
+    # Safe logging that works with or without Rails
+    def log_error(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.error(message)
+      else
+        warn(message)
+      end
+    end
+
+    def log_warn(message)
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger.warn(message)
+      else
+        warn(message)
+      end
+    end
+
+    def log_debug(message)
+      return unless message
+
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger&.debug?
+        Rails.logger.debug(message)
+      end
+    end
+  end
+end

data/lib/organizations/configuration.rb

@@ -0,0 +1,286 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/numeric/time"
+
+module Organizations
+  # Configuration class for the Organizations gem.
+  # Provides all customization options for organization behavior.
+  #
+  # @example Basic configuration
+  #   Organizations.configure do |config|
+  #     config.always_create_personal_organization_for_each_user = true
+  #     config.invitation_expiry = 7.days
+  #   end
+  #
+  # @example Custom roles
+  #   Organizations.configure do |config|
+  #     config.roles do
+  #       role :viewer do
+  #         can :view_organization
+  #       end
+  #       role :member, inherits: :viewer do
+  #         can :create_resources
+  #       end
+  #     end
+  #   end
+  #
+  class Configuration
+    # === Authentication ===
+    # Method that returns the current user (default: :current_user)
+    attr_accessor :current_user_method
+
+    # Method that ensures user is authenticated (default: :authenticate_user!)
+    attr_accessor :authenticate_user_method
+
+    # === Auto-creation ===
+    # Create personal organization on user signup
+    attr_accessor :always_create_personal_organization_for_each_user
+
+    # Name for auto-created organizations
+    # Can be a String or a Proc/Lambda: ->(user) { "#{user.name}'s Workspace" }
+    attr_accessor :default_organization_name
+
+    # === Invitations ===
+    # How long invitations are valid
+    attr_accessor :invitation_expiry
+
+    # Default role for invited members
+    attr_accessor :default_invitation_role
+
+    # Custom mailer for invitations (class name as string)
+    attr_accessor :invitation_mailer
+
+    # === Limits ===
+    # Maximum organizations a user can own (nil = unlimited)
+    attr_accessor :max_organizations_per_user
+
+    # === Onboarding ===
+    # Require users to always belong to at least one organization
+    # Set to true to prevent users from leaving their last organization
+    attr_accessor :always_require_users_to_belong_to_one_organization
+
+    # === Session/Switching ===
+    # Session key for storing current organization ID
+    attr_accessor :session_key
+
+    # === Redirects ===
+    # Where to redirect when user has no organization
+    attr_accessor :redirect_path_when_no_organization
+
+    # === Engine configuration ===
+    attr_accessor :parent_controller
+
+    # === Handlers (blocks) ===
+    # @private - stored handler blocks
+    attr_reader :unauthorized_handler, :no_organization_handler
+
+    # === Callbacks ===
+    # @private - stored callback blocks
+    attr_reader :on_organization_created_callback,
+                :on_member_invited_callback,
+                :on_member_joined_callback,
+                :on_member_removed_callback,
+                :on_role_changed_callback,
+                :on_ownership_transferred_callback
+
+    # === Custom Roles ===
+    # @private - custom roles definition
+    attr_reader :custom_roles_definition
+
+    def initialize
+      # Authentication defaults
+      @current_user_method = :current_user
+      @authenticate_user_method = :authenticate_user!
+
+      # Auto-creation defaults
+      @always_create_personal_organization_for_each_user = false
+      @default_organization_name = "Personal"
+
+      # Invitation defaults
+      @invitation_expiry = 7.days
+      @default_invitation_role = :member
+      @invitation_mailer = "Organizations::InvitationMailer"
+
+      # Limits
+      @max_organizations_per_user = nil
+
+      # Onboarding
+      @always_require_users_to_belong_to_one_organization = false
+
+      # Session/switching
+      @session_key = :current_organization_id
+
+      # Redirects
+      @redirect_path_when_no_organization = "/organizations/new"
+
+      # Engine
+      @parent_controller = "::ApplicationController"
+
+      # Handlers (nil by default - use default behavior)
+      @unauthorized_handler = nil
+      @no_organization_handler = nil
+
+      # Callbacks (nil by default - no-op)
+      @on_organization_created_callback = nil
+      @on_member_invited_callback = nil
+      @on_member_joined_callback = nil
+      @on_member_removed_callback = nil
+      @on_role_changed_callback = nil
+      @on_ownership_transferred_callback = nil
+
+      # Custom roles
+      @custom_roles_definition = nil
+    end
+
+    # === Handler Configuration Methods ===
+
+    # Configure unauthorized access handler
+    # @yield [context] Block to handle unauthorized access
+    # @yieldparam context [CallbackContext] Context with user, organization, permission info
+    #
+    # @example
+    #   config.on_unauthorized do |context|
+    #     redirect_to root_path, alert: "You don't have permission."
+    #   end
+    #
+    def on_unauthorized(&block)
+      @unauthorized_handler = block if block_given?
+    end
+
+    # Configure no organization handler
+    # @yield [context] Block to handle when user has no organization
+    # @yieldparam context [CallbackContext] Context with user info
+    #
+    # @example
+    #   config.on_no_organization do |context|
+    #     redirect_to new_organization_path, notice: "Please create an organization."
+    #   end
+    #
+    def on_no_organization(&block)
+      @no_organization_handler = block if block_given?
+    end
+
+    # === Callback Configuration Methods ===
+
+    # Called when an organization is created
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization and user
+    def on_organization_created(&block)
+      @on_organization_created_callback = block if block_given?
+    end
+
+    # Called when a member is invited
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, invitation, invited_by
+    def on_member_invited(&block)
+      @on_member_invited_callback = block if block_given?
+    end
+
+    # Called when a member joins (invitation accepted)
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, membership, user
+    def on_member_joined(&block)
+      @on_member_joined_callback = block if block_given?
+    end
+
+    # Called when a member is removed
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, membership, user, removed_by
+    def on_member_removed(&block)
+      @on_member_removed_callback = block if block_given?
+    end
+
+    # Called when a member's role changes
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, membership, old_role, new_role, changed_by
+    def on_role_changed(&block)
+      @on_role_changed_callback = block if block_given?
+    end
+
+    # Called when ownership is transferred
+    # @yield [context] Block to execute
+    # @yieldparam context [CallbackContext] Context with organization, old_owner, new_owner
+    def on_ownership_transferred(&block)
+      @on_ownership_transferred_callback = block if block_given?
+    end
+
+    # === Roles Configuration ===
+
+    # Define custom roles with permissions
+    # @yield DSL block for role definition
+    #
+    # @example
+    #   config.roles do
+    #     role :viewer do
+    #       can :view_organization
+    #       can :view_members
+    #     end
+    #     role :member, inherits: :viewer do
+    #       can :create_resources
+    #     end
+    #   end
+    #
+    def roles(&block)
+      if block_given?
+        @custom_roles_definition = block
+        # Reset cached permissions so new roles take effect
+        Roles.reset!
+      end
+    end
+
+    # Resolve the default organization name for a user
+    # @param user [Object] The user object
+    # @return [String] The organization name
+    def resolve_default_organization_name(user)
+      case @default_organization_name
+      when Proc
+        @default_organization_name.call(user)
+      when String
+        @default_organization_name
+      else
+        "Personal"
+      end
+    end
+
+    # Validate the configuration
+    # @raise [ConfigurationError] if configuration is invalid
+    def validate!
+      validate_authentication_methods!
+      validate_invitation_settings!
+      validate_limits!
+      true
+    end
+
+    private
+
+    def validate_authentication_methods!
+      unless @current_user_method.is_a?(Symbol)
+        raise ConfigurationError, "current_user_method must be a Symbol"
+      end
+
+      unless @authenticate_user_method.is_a?(Symbol)
+        raise ConfigurationError, "authenticate_user_method must be a Symbol"
+      end
+    end
+
+    def validate_invitation_settings!
+      unless @invitation_expiry.nil? || @invitation_expiry.is_a?(ActiveSupport::Duration) || @invitation_expiry.is_a?(Numeric)
+        raise ConfigurationError, "invitation_expiry must be a Duration (e.g., 7.days) or nil"
+      end
+
+      unless Roles::HIERARCHY.include?(@default_invitation_role.to_sym)
+        raise ConfigurationError, "default_invitation_role must be one of: #{Roles::HIERARCHY.join(', ')}"
+      end
+    end
+
+    def validate_limits!
+      if @max_organizations_per_user && !@max_organizations_per_user.is_a?(Integer)
+        raise ConfigurationError, "max_organizations_per_user must be an Integer or nil"
+      end
+
+      if @max_organizations_per_user && @max_organizations_per_user < 1
+        raise ConfigurationError, "max_organizations_per_user must be at least 1"
+      end
+    end
+  end
+end