has_helpers 5.0.2

data/app/models/has_helpers/cards/card_builder/field_builder.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module CardBuilder
+      class FieldBuilder
+        class ValidationError < StandardError; end
+
+        attr_reader :kind,
+                    :ref,
+                    :key,
+                    :name,
+                    :data_type,
+                    :mapper,
+                    :source,
+                    :url,
+                    :badge_color,
+                    :hover_card,
+                    :hover_card_source,
+                    :hover_record_source,
+                    :hover_resource,
+                    :hover_resource_source,
+                    :icon,
+                    :default_visibility,
+                    :default_position,
+                    :is_required,
+                    :custom_label,
+                    :custom_label_key
+
+        def initialize(kind:, ref:, key:, name:, data_type:, mapper:, source: nil, url: nil, badge_color: nil,
+                       hover_card: nil, hover_card_source: nil, hover_record_source: nil,
+                       hover_resource: nil, hover_resource_source: nil, icon: nil,
+                       default_visibility:, default_position:, is_required:, custom_label: false, custom_label_key: nil)
+          @kind                  = kind # :resource or :custom
+          @ref                   = ref
+          @key                   = key&.to_sym
+          @name                  = name
+          @data_type             = normalize_data_type(data_type)
+          @mapper                = mapper && mapper.to_s
+          @source                = source
+          @url                   = url
+          @badge_color           = badge_color
+          @hover_card            = hover_card&.to_s
+          @hover_card_source     = normalize_source(hover_card_source)
+          @hover_record_source   = normalize_source(hover_record_source)
+          @hover_resource        = hover_resource&.to_s
+          @hover_resource_source = normalize_source(hover_resource_source)
+          @icon                  = icon&.to_s
+          @default_visibility    = !!default_visibility
+          @default_position      = default_position
+          @is_required           = !!is_required
+          @custom_label          = !!custom_label
+          @custom_label_key      = custom_label_key&.to_s
+        end
+
+        def validate!
+          unless %i[resource custom virtual].include?(kind)
+            raise ValidationError, "Invalid field kind: #{kind.inspect}"
+          end
+
+          raise ValidationError, "data_type is required" if data_type.nil?
+
+          case kind
+          when :resource
+            raise ValidationError, "resource field must have ref" if ref.nil?
+          when :custom
+            raise ValidationError, "custom field must have key" if key.nil?
+          when :virtual
+            raise ValidationError, "virtual field must have ref" if ref.nil?
+          end
+        end
+
+        def to_h
+          base = {
+            kind:                  kind,
+            data_type:             data_type,
+            default_visibility:    default_visibility,
+            default_position:      default_position,
+            is_required:           is_required,
+            source:                source,
+            url:                   url,
+            badge_color:           badge_color,
+            hover_card:            hover_card,
+            hover_card_source:     hover_card_source,
+            hover_record_source:   hover_record_source,
+            hover_resource:        hover_resource,
+            hover_resource_source: hover_resource_source,
+            icon:                  icon,
+            custom_label:          custom_label,
+            custom_label_key:      custom_label_key
+          }
+
+          case kind
+          when :resource
+            base.merge(
+              ref: ref,
+              name: name
+            )
+          when :custom
+            base.merge(
+              key:    key,
+              name:   name,
+              mapper: mapper
+            )
+          when :virtual
+            base.merge(
+              ref:  ref,
+              name: name
+            )
+          end
+        end
+
+        def as_json(*)
+          to_h
+        end
+
+        private
+
+        # Normalize CardDataType options or symbols to a compact symbol
+        def normalize_data_type(value)
+          return nil if value.nil?
+
+          if value.respond_to?(:name)
+            # e.g. HasHelpers::Cards::CardDataType::Numeric -> :numeric
+            value.name.to_s.underscore.to_sym
+          elsif value.is_a?(Symbol)
+            value
+          else
+            value.to_s.underscore.to_sym
+          end
+        end
+
+        def normalize_source(value)
+          return nil if value.nil?
+          return value if value.is_a?(Hash)
+
+          { mapper: value.to_s }
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/card_builder/resource_builder.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    module CardBuilder
+      class ResourceBuilder
+        attr_reader :resources
+
+        def initialize
+          @resources = []
+        end
+
+        # DSL:
+        #
+        # resources do
+        #   add Advisor
+        #   add Client, mandatory: true
+        #   add Advisor, Client, HasContactInfo::Contact
+        # end
+        #
+        # Defaults:
+        # - mandatory: false
+        def add(*klasses, mandatory: false)
+          klasses.each do |klass|
+            @resources << {
+              class_name: klass.name,
+              is_mandatory: !!mandatory
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/card_definition.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class CardDefinition < ::ActiveRecord::Base
+      self.table_name = "card_definitions"
+
+      attr_accessor :relationship, :relationship_klass
+
+      ###### associations ######
+      belongs_to :identifier,  class_name: "::HasHelpers::Cards::CardIdentifier"
+      belongs_to :layout_type, class_name: "::HasHelpers::Cards::CardLayoutType"
+      belongs_to :variant,     class_name: "::HasHelpers::Cards::CardVariantType", optional: true
+
+      has_many :card_definition_resources, class_name: "::HasHelpers::Cards::CardDefinitionResource", dependent: :destroy, inverse_of: :card_definition
+      has_many :resources, through: :card_definition_resources, source: :resource
+      has_many :card_fields,               class_name: "::HasHelpers::Cards::CardField", dependent: :destroy, inverse_of: :card_definition
+      has_many :role_resource_cards,       class_name: "::HasHelpers::Cards::RoleResourceCard", dependent: :destroy, inverse_of: :card_definition
+
+      ###### validations ######
+      validates :name, :identifier_id, :layout_type_id, presence: true
+      validates :identifier_id,  inclusion: { in: proc { ::HasHelpers::Cards::CardIdentifier.pluck(:id) } }, allow_nil: false
+      validates :layout_type_id, inclusion: { in: proc { ::HasHelpers::Cards::CardLayoutType.pluck(:id) } }, allow_nil: false
+      validates :variant_id,     inclusion: { in: proc { ::HasHelpers::Cards::CardVariantType.pluck(:id) } }, allow_nil: true
+
+      ###### scopes ######
+      scope :ordered, -> { order(position: :asc, created_at: :asc) }
+
+      # Returns all card_definitions that are linked to the given resource name.
+      # We join through the `resources` association (HasHelpers::Resource)
+      # and filter by resource.name.
+      scope :for_resource_name, lambda { |resource_name|
+        joins(:resources).where(
+          ::HasHelpers::Resource.table_name => {
+            name: resource_name.to_s
+          }
+        ).distinct
+      }
+    end
+  end
+end

data/app/models/has_helpers/cards/card_definition_resource.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class CardDefinitionResource < ::ActiveRecord::Base
+      self.table_name = "card_definition_resources"
+
+      belongs_to :card_definition, class_name: "::HasHelpers::Cards::CardDefinition", inverse_of: :card_definition_resources
+      belongs_to :resource, class_name: "::HasHelpers::Resource", inverse_of: :card_definition_resources
+
+      validates :card_definition_id, :resource_id, presence: true
+      validates :card_definition_id, uniqueness: { scope: :resource_id }
+
+      scope :for_resource, ->(res_id) { where(resource_id: res_id) }
+      # default_position is used for ordering when there are multiple resources linked to the same card
+      scope :ordered, -> { order(default_position: :asc, created_at: :asc) }
+    end
+  end
+end

data/app/models/has_helpers/cards/card_field.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class CardField < ::ActiveRecord::Base
+      self.table_name = "card_fields"
+
+      belongs_to :card_definition, class_name: "::HasHelpers::Cards::CardDefinition", inverse_of: :card_fields
+      belongs_to :field_resource, class_name: "::HasHelpers::Resource", foreign_key: :field_id, optional: true, inverse_of: :card_fields_as_field_resource
+      belongs_to :data_type, class_name: "::HasHelpers::Cards::CardDataType"
+
+      has_many :role_card_fields, class_name: "::HasHelpers::Cards::RoleCardField", inverse_of: :card_field, dependent: :destroy
+
+      validates :card_definition_id, :data_type_id, presence: true
+      validates :data_type_id, inclusion: { in: proc { ::HasHelpers::Cards::CardDataType.pluck(:id) } }, allow_nil: false
+      validates :default_position, numericality: true, allow_nil: true
+      validates :virtual_ref, uniqueness: { scope: :card_definition_id }, allow_nil: true
+      validates :field_custom_name, uniqueness: { scope: :card_definition_id }, allow_nil: true
+
+      validate :exclusive_field_target
+
+      scope :visible_by_default, -> { where(default_visibility: true) }
+      scope :ordered_default, -> { order(default_position: :asc, created_at: :asc) }
+
+      private
+
+      # Valid target combos:
+      # 1) resource field: field_resource present, virtual_ref nil
+      # 2) virtual field: virtual_ref present, field_resource nil
+      # 3) custom field: both nil (uses field_custom_name/mapper)
+      # Invalid: both present.
+      def exclusive_field_target
+        if field_resource.present? && virtual_ref.present?
+          errors.add(:base, "Cannot set both field_resource and virtual_ref")
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/registry.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class Registry
+      class DuplicateIdentifierError < StandardError; end
+
+      DefinitionEntry = Struct.new(:owner, :block, :built, keyword_init: true)
+
+      class << self
+        # Returns all registered card definitions.
+        # Structure: array of normalized hashes ready for import.
+        def cards
+          load_card_files_once!
+          build_pending_definitions!
+
+          cards_storage
+        end
+
+        # Registers a lazy card definition block for a given owner class.
+        def register_definition(owner:, block:)
+          raise ArgumentError, "Block required for card definition" unless block
+
+          pending_definitions[owner] = DefinitionEntry.new(owner: owner, block: block, built: false)
+        end
+
+        # Registers all card files to load when cards are requested.
+        def register_card_files(paths)
+          @card_file_paths = Array(paths)
+          @card_files_loaded = false
+        end
+
+        # Registers a card definition (normalized hash).
+        # Validates that the identifier is unique across all registered cards.
+        def register_card!(card_hash)
+          if cards_storage.any? { |c| c[:identifier] == card_hash[:identifier] }
+            identifier = card_hash[:identifier].try(:name) || card_hash[:identifier]
+            raise DuplicateIdentifierError, "Duplicate card identifier: #{identifier}"
+          end
+
+          cards_storage << deep_freeze(card_hash)
+        end
+
+        # Ensures the definitions for a single owner are built (used by Base.definitions).
+        def ensure_definitions_for(owner)
+          build_pending_definitions!(only: owner)
+          owner.instance_variable_get(:@definitions) || []
+        end
+
+        # Only intended for tests.
+        def reset!
+          @cards = []
+          @pending_definitions = {}
+          @card_files_loaded = false
+        end
+
+        private
+
+        def build_pending_definitions!(only: nil)
+          pending_definitions.values.each do |entry|
+            next if entry.built
+            next if only && entry.owner != only
+
+            entry.owner.build_definitions_from(entry.block)
+            entry.built = true
+          end
+        end
+
+        def load_card_files_once!
+          return if @card_files_loaded
+
+          card_file_paths.each { |file| require_dependency file }
+          @card_files_loaded = true
+        end
+
+        def card_file_paths
+          @card_file_paths || default_card_file_paths
+        end
+
+        def default_card_file_paths
+          Dir[HasHelpers::Engine.root.join("app/models/has_helpers/cards/**/*_card.rb")].sort
+        end
+
+        # rubocop:disable Naming/MemoizedInstanceVariableName
+        def cards_storage
+          @cards ||= []
+        end
+
+        # rubocop:enable Naming/MemoizedInstanceVariableName
+
+        def pending_definitions
+          @pending_definitions ||= {}
+        end
+
+        # Deep-freezes the structure so it becomes immutable at runtime.
+        def deep_freeze(obj)
+          case obj
+          when Hash
+            obj.each_value { |v| deep_freeze(v) }
+            obj.freeze
+          when Array
+            obj.each { |v| deep_freeze(v) }
+            obj.freeze
+          when String, Symbol, Numeric, TrueClass, FalseClass, NilClass
+            obj.freeze
+          when Class, Module
+            obj
+          else
+            obj
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/cards/role_card_field.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class RoleCardField < ::ActiveRecord::Base
+      self.table_name = "role_card_fields"
+
+      autoset :organization_id
+      autoset :created_by_id, :user_id, before: :validation
+      autoset :updated_by_id, :user_id, before: :validation, overwrite: true
+
+      belongs_to :role_resource_card, class_name: "::HasHelpers::Cards::RoleResourceCard", inverse_of: :role_card_fields
+      belongs_to :card_field, class_name: "::HasHelpers::Cards::CardField", inverse_of: :role_card_fields
+      belongs_to :organization, class_name: "::HasHelpers::Organization"
+      belongs_to :created_by, class_name: "::HasHelpers::User"
+      belongs_to :updated_by, class_name: "::HasHelpers::User"
+
+      validates :role_resource_card_id, :card_field_id, :organization_id, presence: true
+      validates :card_field_id, uniqueness: {
+        scope: %i[role_resource_card_id],
+        message: "already exists for this role resource card"
+      }
+
+      scope :ordered, -> { order(position: :asc, created_at: :asc) }
+      scope :visible, -> { where(is_visible: true) }
+    end
+  end
+end

data/app/models/has_helpers/cards/role_resource_card.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module Cards
+    class RoleResourceCard < ::ActiveRecord::Base
+      self.table_name = "role_resource_cards"
+
+      autoset :organization_id
+      autoset :created_by_id, :user_id, before: :validation
+      autoset :updated_by_id, :user_id, before: :validation, overwrite: true
+
+      belongs_to :role,            class_name: "::HasHelpers::Role",                inverse_of: :role_resource_cards, optional: true
+      belongs_to :resource,        class_name: "::HasHelpers::Resource",            inverse_of: :role_resource_cards
+      belongs_to :card_definition, class_name: "HasHelpers::Cards::CardDefinition", inverse_of: :role_resource_cards
+      belongs_to :organization,    class_name: "::HasHelpers::Organization"
+      belongs_to :created_by,      class_name: "::HasHelpers::User"
+      belongs_to :updated_by,      class_name: "::HasHelpers::User"
+
+      has_many :role_card_fields, class_name: "::HasHelpers::Cards::RoleCardField", inverse_of: :role_resource_card, dependent: :destroy
+
+      validates :organization_id, :role_id, :resource_id, :card_definition_id, presence: true
+
+      validates :card_definition_id, uniqueness: {
+        scope: %i[organization_id role_id resource_id],
+        message: "already assigned to this roles and resource in the organization"
+      }
+
+      scope :active, -> { where(disabled_at: nil) }
+      scope :visible, -> { where(is_visible: true) }
+      scope :ordered, -> { order(position: :asc, created_at: :asc) }
+
+      def role
+        ::HasHelpers::Cards::Roles.find(role_id)
+      end
+
+      def role=(value)
+        self.role_id = value&.id
+      end
+    end
+  end
+end

data/app/models/has_helpers/dn_utils.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module HasHelpers
+  module DNUtils
+    def update_denormalized_columns
+      return unless ::Rails.application.config.x.dn_enabled == true
+      dependencies = "#{self.class.table_name.camelize}Dependencies".constantize rescue nil
+      return if dependencies.nil?
+      type = saved_changes.key?("id") ? "insert" : "update"
+      changes = saved_changes
+
+      if dependencies.respond_to?(:indirect_fields) && type == "update"
+        reloaded_resource = self.class.find_by(id: self.id)
+        # indirect_field stores the fileds that are changed on a db level
+        # for example the column name on advisors changes with a db trigger (not at rails level)
+        dependencies.indirect_fields.each { |field| changes["#{field}"] = [self.send(field), reloaded_resource.send(field)] if self.send(field) != reloaded_resource.send(field) }
+      end
+      return if dependencies.dependent_tables.keys.intersection(changes.keys).empty?
+
+      if Object.const_defined?("ChangeLog") && ::ActiveRecord::Base.connection.data_source_exists?("change_logs")
+        exists_subquery = "EXISTS (
+          SELECT 1
+          FROM unnest(changed_columns) AS col
+          WHERE col = ANY(ARRAY[?])
+        )"
+
+        change_log_id = ChangeLog.select(:id).
+          where(record_id: id, type: type, denormalized_at: nil, table_name: self.class.table_name).
+          where(type == "insert" ? "true" : exists_subquery, dependencies.dependent_tables.keys).
+          order(id: :desc).
+          first&.id
+      end
+      if dependencies.present? && changes.present?
+        ::GoodJob::DNWorker.perform_deferred(
+          self.class.table_name,
+          ensure_json_serializable(dependencies.dependent_tables),
+          self.class.name,
+          id,
+          ensure_json_serializable(changes),
+          change_log_id
+        )
+      end
+    end
+
+    def ensure_json_serializable(obj)
+      case obj
+      when Hash
+        obj.transform_keys(&:to_s).transform_values { |v| ensure_json_serializable(v) }
+      when Array
+        obj.map { |v| ensure_json_serializable(v) }
+      when Symbol
+        obj.to_s
+      when Time
+        obj.iso8601
+      else
+        obj
+      end
+    end
+  end
+end

data/app/models/has_helpers/favorite.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class HasHelpers::Favorite < ::ActiveRecord::Base
+  self.table_name = "favorites"
+
+  autoset :organization_id
+  autoset :created_by_id, :user_id, before: :validation
+  autoset :updated_by_id, :user_id, before: :validation, overwrite: true
+
+  belongs_to :organization, class_name: "::HasHelpers::Organization"
+  belongs_to :created_by,   class_name: "::HasHelpers::User"
+  belongs_to :updated_by,   class_name: "::HasHelpers::User"
+
+  scope :by_user_id, -> (created_by_id, org_id) { where(created_by_id: created_by_id, organization_id: org_id) }
+  default_scope { order(created_at: :desc) }
+
+  def self.ignored_classes
+    []
+  end
+end

data/app/models/has_helpers/master_record.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  class MasterRecord < ::ActiveRecord::Base
+    self.abstract_class = true
+    establish_connection :master
+
+    def self.without_pgpool
+      if Marginalia::Comment.inline_annotations.include? "NO LOAD BALANCE"
+        yield if block_given?
+      else
+        Marginalia.with_annotation("NO LOAD BALANCE") do
+          yield if block_given?
+        end
+      end
+    end
+  end
+end

data/app/models/has_helpers/notification_alert.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  class NotificationAlert < ApplicationRecord
+    self.table_name = :notification_alerts
+
+    belongs_to :organization, class_name: "::HasHelpers::Organization"
+    belongs_to :user,         class_name: "::HasHelpers::User", optional: true
+    belongs_to :status,       class_name: "HasHelpers::NotificationAlertStatus"
+    belongs_to :alert_type,   class_name: "HasHelpers::NotificationAlertType"
+
+    validates :alert_type, presence: true
+    validates :payload,    presence: true
+    validates :status,     presence: true
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :active, -> { where("expires_at IS NULL OR expires_at > ?", Time.current) }
+
+    after_initialize :hydrate
+    after_commit :broadcast_to_organization, on: :create
+
+    private
+
+    def hydrate
+      self.status ||= HasHelpers::NotificationAlertStatus::UNREAD
+    end
+
+    def broadcast_to_organization
+      Rails.logger.info("Broadcasting to notifications:#{organization_id} - #{alert_type}")
+
+      message = {
+        topic: "notification_alerts",
+        id: organization_id,
+        event_type: "new_notification",
+        payload: {
+          type: alert_type,
+          payload: payload.deep_symbolize_keys
+        }
+      }
+
+      Rails.logger.debug("[NotificationBroadcast] Sending Redis message: #{message.to_json}")
+
+      begin
+        HasHelpers::WebSocketPublisher.publish("events", message)
+      rescue => e
+        Rails.logger.error("[NotificationBroadcast] Failed to publish to Redis: #{e.class} - #{e.message}")
+        Rails.logger.error("[NotificationBroadcast] Message: #{message.inspect}")
+        Rails.logger.error("[NotificationBroadcast] Backtrace:\n#{e.backtrace.join("\n")}")
+      end
+    end
+  end
+end

data/app/models/has_helpers/organization.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+module HasHelpers
+  class Organization < ApplicationRecord
+    self.table_name = :organizations
+
+    belongs_to :time_zone
+    has_many :recently_vieweds, dependent: :destroy
+
+    has_many :user_organizations, dependent: :destroy, class_name: "::HasHelpers::UserOrganization", inverse_of: :organization
+    has_many :users, class_name: "::HasHelpers::User", through: :user_organizations, inverse_of: :organizations
+
+    validates :name, :domain, :time_zone, presence: true
+  end
+end