has_helpers 5.0.2

data/lib/has_helpers/utils/log_notifier.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# An LogNotifier can be used to send notifications to Elk, and/or the
+# console - all depending on the options passed to the initializer (see
+# the comments for #initialize).
+#
+# In addition, there is also a class level method (HasHelpers::LogNotifier.notify) which uses
+# a default notifier that outputs to Elk in production and staging, and
+# outputs to the console in dev and test. We can use this instead of directly
+# calling Elk so we still get error output in dev and test, and also in case
+# we ever move away from Elk.
+#
+# based on ::Frameworkhq::HQNotifier
+
+module HasHelpers
+  class LogNotifier
+    MAX_SNS_SUBJECT_LENGTH = 99
+
+    ###### CLASS METHODS ######
+
+    # This uses a default notifier to write the exception_or_msg to the console
+    def self.notify(exception_or_msg, subject: nil, user: nil)
+      @default_notifier ||= HasHelpers::LogNotifier.new
+      @default_notifier.notify(exception_or_msg, subject: subject, user: user)
+    end
+
+    ###### INSTANCE METHODS ######
+
+    # Instantiates an HasHelpers::HQNotifier that outputs to ELK, and/or the console
+    # depending on these options:
+    # - notify_console: By default, this notifier will output to the console.
+    #   Set this to false if you don't want log messages copied to the console.
+
+    def initialize(notify_console: true)
+      @notify_console = notify_console
+    end
+
+    # The argument can be an Exception or a String.
+    # Paramerters are:
+    # - subject: an optional subject for SNS messages
+    # - file_path: required if the argument is String | Optional if Exception
+    # - line_number: required if the argument is String | Optional if Exception
+    # - function_name: required if the argument is String | Optional if Exception
+    def notify(exception_or_msg, subject: nil, user: nil, backtrace: caller) # rubocop:disable Lint/UnusedMethodArgument
+      unless exception_or_msg.is_a?(Exception) || exception_or_msg.is_a?(String)
+        raise "HasHelpers::HQNotifier expected an Exception or String, but got a #{exception_or_msg.class}."
+      end
+
+      message = message_from_exception(exception_or_msg)
+
+      exception = exception_or_msg.is_a?(Exception) ? exception_or_msg : message_to_exception(exception_or_msg, backtrace: backtrace) # rubocop:disable Lint/UselessAssignment
+
+      puts message if @notify_console
+    end
+
+    private
+
+    def message_to_exception(exception_or_msg = nil, backtrace: caller)
+      unless exception_or_msg.is_a? Class
+        exception = RuntimeError.new(exception_or_msg.to_s)
+        exception.set_backtrace(backtrace)
+        return exception
+      end
+      exception_or_msg
+    end
+
+    # If the argument passed in is an Exception, combines the exception message
+    # with its backtrace, formatted with newlines. Otherwise, just returns the
+    # argument converted to a String.
+    def message_from_exception(exception_or_msg)
+      if exception_or_msg.is_a?(Exception)
+        lines = [exception_or_msg.to_s, *exception_or_msg.backtrace]
+        lines.join("\n")
+      else
+        exception_or_msg.to_s
+      end
+    end
+  end
+end

data/lib/has_helpers/utils/render_object.rb

@@ -0,0 +1,32 @@
+# typed: true
+# frozen_string_literal: true
+
+# A light-weight container for arguments intended for use with rendering a template.
+#
+# === Examples
+#   render_object = RenderObject.new(:partial => "some/template", :object => :derp)
+#
+#   # Inside a view
+#   <%= render *render_object.args %>
+class RenderObject # TODO: Find a better name. This one is horrible *
+  attr_accessor :args
+
+  def initialize(*args)
+    self.args = args
+  end
+
+  def to_action
+    ::Action.new(render_object: self)
+  end
+
+  def to_renderable
+    self
+  end
+
+  # :nocov:
+  def to_partial_path
+    "/has_helpers/render_objects/render_object"
+  end
+
+  # :nocov:
+end

data/lib/has_helpers/utils/s3_utils.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module S3Utils
+    # Returns the requested bucket.
+    # Raises a RuntimeError if there is an error getting that bucket.
+    def get_s3_bucket(bucket_name)
+      @s3_client ||= ::HasHelpers::Aws.new_s3_client(credentials_conf: ::HasHelpers::Aws.credentials_conf)
+      @s3_resource ||= ::Aws::S3::Resource.new(client: @s3_client)
+
+      bucket = @s3_resource.bucket(bucket_name)
+
+      unless bucket.exists?
+        raise "Cannot access S3 bucket: #{bucket_name}"
+      end
+
+      bucket
+    end
+
+    def get_s3_file(bucket_name, s3_file_path)
+      s3_object = get_s3_bucket(bucket_name).object(s3_file_path)
+
+      begin
+        file_name = File.basename(s3_object.key)
+        ::Tempfile.new(file_name).tap do |temp_file|
+          s3_object.get do |chunk|
+            temp_file.write(chunk.dup.force_encoding("UTF-8"))
+          end
+          temp_file.rewind
+        end
+      rescue => e
+        Rails.logger.error("Fetching file(/#{bucket_name}/#{s3_file_path}) in S3 encountered an issue with message: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/has_helpers/utils/service.rb

@@ -0,0 +1,87 @@
+# typed: true
+# frozen_string_literal: true
+
+class Service
+  include ::HasHelpers::Attributes::AttributeAssignment
+  include ::HasHelpers::UIAttributes
+  attr_accessor :external,
+                :nested,
+                :http_method # HTTP method to use, e.g., one of :get, :post, :put
+  attr_writer :icon, :icon_placement
+
+  # Handle options passed to new. Hash args are assigned to attributes like ActiveRecord does.
+  # ==== Examples
+  #   Service.new("http://derp.com")
+  #   Service.new("Derp", :url => "http://derp.com")
+  #   Service.new("Derp", :url => "http://derp.com", :external => true)
+  def initialize(name, **options)
+    @name = name
+    assign_attributes(options)
+  end
+
+  def url=(value)
+    @url_cached = true
+    @url = value
+  end
+
+  # Returns the current url value or falls back to the current object. Note
+  # that if url is explicitly set to nil, then no fallback will be used, but
+  # rather nil will be returned.
+  def url
+    @url_cached ? @url : to_s
+  end
+
+  def to_s
+    @name
+  end
+
+  def to_service(**options)
+    assign_attributes(**options) # Apply any given attributes
+    self
+  end
+
+  def to_action
+    ::Action.new(service: self)
+  end
+
+  def to_partial_path
+    "has_helpers/services/service"
+  end
+
+  def icon
+    @icon && @icon.to_icon
+  end
+
+  # :right or :left, default to :left
+  def icon_placement
+    @icon_placement == :right ? :right : :left
+  end
+
+  def to_renderable
+    self
+  end
+
+  def raw_html_attrs
+    super.tap do |raw_attrs|
+      raw_attrs.reverse_merge!(external: nil) if external
+    end
+  end
+
+  def props
+    {}.tap do |hash|
+      hash[:type] = "Service"
+      hash[:icon] = icon
+      hash[:url] = url
+      hash[:children] = @name
+    end.camelize_keys!
+  end
+
+  def ==(other)
+    case other
+    when self.class
+      url == other.url && to_s == other.to_s
+    else
+      super
+    end
+  end
+end

data/lib/has_helpers/utils/slack_conf.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "slack"
+
+class SlackConf
+  class << self
+    def client
+      @client ||= begin
+                    Slack.configure do |config|
+                      config.token = config_options
+                    end
+
+                    Slack::Web::Client.new
+                  end
+    end
+
+    def config_options
+      @config_options ||= (config.token || "")
+    end
+
+    private
+
+    def config
+      @config ||= ::HasHelpers::LazyConfig.new(config_path)
+    end
+
+    def config_path
+      Rails.root.join("config/secrets/slack.yaml")
+    end
+  end
+end

data/lib/has_helpers/utils/slack_notifier.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  class SlackNotifier
+    ###### CLASS METHODS ######
+
+    def self.notify(message, channel: default_channel)
+      @default_notifier ||= HasHelpers::SlackNotifier.new
+      @default_notifier.notify(message, channel: channel)
+    end
+
+    class << self
+      attr_accessor :default_channel_resolver
+    end
+
+    def self.default_channel
+      return nil if ::HasUtils::Env.test? || ::HasUtils::Env.development?
+      default_channel_resolver&.call
+    end
+
+    ###### INSTANCE METHODS ######
+
+    def notify(message, channel:)
+      if channel.nil?
+        puts message
+        return
+      end
+
+      begin
+        slack_client.chat_postMessage(channel: channel, text: message, as_user: true, mrkdwn: true, link_names: true)
+      rescue => e
+        ::Rails.logger.warn("Unable to send slack notification: #{e.message}")
+      end
+    end
+
+    private
+
+    def slack_client
+      @slack_client ||= SlackConf.client
+    end
+  end
+end

data/lib/has_helpers/utils/text_node.rb

@@ -0,0 +1,34 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers
+  class TextNode
+    include HasHelpers::Attributes
+    include HasHelpers::UIAttributes
+
+    attr_accessor :str
+    alias to_s str
+
+    def initialize(str, *args, **options, &block)
+      super(*args, **options, &block)
+      self.str = str.to_s
+    end
+
+    def to_renderable
+      self
+    end
+
+    def to_partial_path
+      "has_helpers/text_nodes/text_node"
+    end
+
+    def ==(other)
+      case other
+      when self.class
+        to_s == other.to_s
+      else
+        super
+      end
+    end
+  end
+end

data/lib/has_helpers/utils/user_restrictions.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "cancan"
+require "has_helpers/concerns/restrictions_parseable"
+
+module HasHelpers
+  # Resolves and queries the resource-level restrictions of a user, and exposes
+  # them through the CanCanCan interface (`can?`/`cannot?`).
+  #
+  # Uses a restrictions-based model (negative permissions): the restrictions_hash
+  # on the user's primary user_organization defines what the user CANNOT do.
+  # An empty restrictions hash means the user is unrestricted (`can :manage, :all`).
+  #
+  # This class `include`s `CanCan::Ability` and mirrors frameworkhq's `Ability`:
+  # a single catch-all `can` block delegates each check to the negative
+  # `restricted?` query, and results are memoized per (subject, action) within the
+  # instance (see `memoized_permissions`). Build one instance per request and reuse
+  # it — the authorize lambda and host `::Ability` subclasses do exactly this.
+  #
+  # The hash is keyed by application name and may hold restrictions for several
+  # host apps at once (e.g. AgenciesHQ, ReadyGOP, Reports, HQAdmin). Each host
+  # passes its own keys via `app_keys` (looked up first), or relies on
+  # case-insensitive matching against `application` / the PsqlHq `client_app`
+  # variable.
+  #
+  # Payload shape (populated by hqadmin during the login sync; may arrive
+  # multi-encoded as JSON text — see RestrictionsParseable):
+  #
+  #   {
+  #     "AppName" => {
+  #       "Client" => {
+  #         "restriction_operations" => ["View", "Create"], # operations the user CANNOT do
+  #         "resource_type"          => "Base",
+  #         "alias_name"             => "Customer",          # optional: alternate resource name
+  #         "nested_resources"       => [...]                # optional: NOT consumed here
+  #       }
+  #     }
+  #   }
+  #
+  # Usage:
+  #
+  #   restrictions = HasHelpers::UserRestrictions.new(user, app_keys: ["MyApp"])
+  #   restrictions.empty?                            # => true if unrestricted
+  #   restrictions.can?(:read, "Client")             # => false if View/Read restricted
+  #   restrictions.restricted?(:read, "Client")      # => true if View/Read restricted
+  #   restrictions.restricted_resource_names         # => ["Client", ...] (read-restricted)
+  class UserRestrictions
+    include ::CanCan::Ability
+    include ::HasHelpers::Concerns::RestrictionsParseable
+
+    # Operations that block reading a resource.
+    READ_OPERATIONS = %w[View Read].freeze
+
+    # Maps CanCanCan-style action names to the restriction operation names
+    # stored in the DB. Read-like actions match both "View" and "Read".
+    OPERATION_MAP = {
+      "read" => READ_OPERATIONS,
+      "view" => READ_OPERATIONS,
+      "create" => ["Create"].freeze,
+      "update" => ["Update"].freeze,
+      "destroy" => ["Delete"].freeze,
+      "delete" => ["Delete"].freeze,
+      "export" => ["Export"].freeze,
+      "merge" => ["Merge"].freeze
+    }.freeze
+
+    # UI/action aliases (the standard frameworkhq set) mapped to the canonical
+    # action that `OPERATION_MAP` understands. CanCanCan passes the ORIGINAL
+    # action to a catch-all `can` block (not the one expanded by `alias_action`),
+    # so the block normalizes through this map before delegating to `restricted?`.
+    # The `alias_action` declarations in `ability_aliases!` mirror this and cover
+    # the rest of the CanCanCan API (e.g. `cannot?`). Keeping both in sync is
+    # intentional — do not remove either.
+    ACTION_ALIASES = {
+      cards: :read,
+      download: :read,
+      favorite: :read,
+      copy: :create,
+      delete: :destroy,
+      edit: :update,
+      email: :export,
+      re_run: :update
+    }.freeze
+
+    attr_reader :user, :application, :app_keys
+
+    def initialize(user, application: nil, app_keys: [])
+      @user = user
+      @application = application
+      @app_keys = Array(app_keys)
+
+      ability_aliases!
+      authorize_restrictions!
+    end
+
+    # Restrictions hash for the resolved application, keyed by resource name.
+    def restrictions
+      return @restrictions if defined?(@restrictions)
+
+      @restrictions = restrictions_for_app
+    end
+
+    def empty?
+      restrictions.blank?
+    end
+
+    # Returns true if the given action is restricted for the resource.
+    # action: CanCanCan-style (:read, :create, ...); resource: String, Class,
+    # or an object responding to :klass (e.g. HasReports::Resource).
+    def restricted?(action, resource)
+      resource_info = find_resource_info(resource)
+      return false if resource_info.blank?
+
+      operations = Array(resource_info["restriction_operations"]).map(&:to_s)
+      (normalize_operations(action) & operations).any?
+    end
+
+    # Names of the resources restricted for any of the given operations.
+    def restricted_resource_names(operations: READ_OPERATIONS)
+      ops = Array(operations).map(&:to_s)
+      restrictions.select do |_name, info|
+        info.is_a?(Hash) && (Array(info["restriction_operations"]).map(&:to_s) & ops).any?
+      end.keys
+    end
+
+    private
+
+    # Registers the standard OneHQ action aliases (mirrors frameworkhq's
+    # `ability_aliases!`) so `can?`/`cannot?` accept UI action names.
+    def ability_aliases!
+      alias_action :cards,    to: :read
+      alias_action :download, to: :read
+      alias_action :favorite, to: :read
+      alias_action :copy,     to: :create
+      alias_action :delete,   to: :destroy
+      alias_action :edit,     to: :update
+      alias_action :email,    to: :export
+      alias_action :re_run,   to: :update
+    end
+
+    # Defines the CanCanCan rules from the user's restrictions. With no
+    # restrictions the user can manage everything; otherwise a single catch-all
+    # `can` block delegates to the negative `restricted?` query and memoizes the
+    # boolean result per (subject, action) within this instance (mirrors
+    # frameworkhq's `Ability`). The instance is request-scoped, so the cache dies
+    # with the request — there is no cross-request state.
+    def authorize_restrictions!
+      if empty?
+        can :manage, :all
+        return
+      end
+
+      can do |action, subject_class, subject|
+        subject_key = subject || subject_class
+        memoized = memoized_permissions[subject_key] ||= {}
+        memoized.fetch(action) do |cached_action|
+          canonical = ACTION_ALIASES.fetch(action.to_sym, action)
+          memoized[cached_action] = !restricted?(canonical, subject_key)
+        end
+      end
+    end
+
+    def memoized_permissions
+      @memoized_permissions ||= {}
+    end
+
+    # Resolves the application key in the restrictions hash:
+    #   1. Explicit app_keys (first present key wins)
+    #   2. Case-insensitive match against application_name
+    #   3. Case-insensitive match against application_name.titleize
+    def restrictions_for_app
+      hash = restrictions_hash_for_user
+      return {} if hash.blank?
+
+      key =
+        app_keys.find { |k| hash.key?(k) } ||
+        hash.keys.find { |k| k.to_s.casecmp(application_name.to_s).zero? } ||
+        hash.keys.find { |k| k.to_s.casecmp(application_name.to_s.titleize).zero? }
+
+      normalize_restrictions(hash[key])
+    end
+
+    # Reads and parses the raw restrictions_hash from the user's primary
+    # organization (falling back to the first one).
+    def restrictions_hash_for_user
+      user_organization =
+        user&.user_organizations&.find_by(is_primary: true) ||
+        user&.user_organizations&.first
+      raw = user_organization&.restrictions_hash
+      parse_raw_restrictions(raw, user_id: user&.id)
+    end
+
+    # Resolves the application name from the application object, string, or
+    # falls back to the PsqlHq client_app variable.
+    def application_name
+      if application.respond_to?(:name)
+        application.name
+      elsif application.present?
+        application.to_s
+      else
+        PsqlHq::Variables.get(:client_app).to_s.strip.presence
+      end
+    end
+
+    # Converts a CanCanCan action (e.g., :read, :destroy) to the restriction
+    # operation names stored in the DB (e.g., ["View", "Read"], ["Delete"]).
+    def normalize_operations(action)
+      OPERATION_MAP.fetch(action.to_s, [action.to_s.capitalize])
+    end
+
+    # Finds the restriction info hash for a given resource.
+    # Supports multiple matching strategies:
+    #   1. Exact name match (e.g., "Client")
+    #   2. Demodulized match (e.g., "Crm::Client" matches "Client" key)
+    #   3. Reverse demodulized match (e.g., "Client" matches "Crm::Client" key)
+    #   4. Alias name match (e.g., resource has alias_name "CustomName")
+    def find_resource_info(resource)
+      name = resource_name(resource)
+      return nil if name.blank?
+
+      info = restrictions[name] || restrictions[name.demodulize]
+      return info if info
+
+      demodulized_name = name.demodulize
+      restrictions.each do |key, resource_info|
+        return resource_info if key.demodulize == demodulized_name
+      end
+
+      # `alias_name` is an alternate NAME a resource may be exposed under — it is
+      # unrelated to the payload's `nested_resources` key (which is not consumed
+      # here). Nested/cross-resource columns in reports are covered by the
+      # demodulized name matching above, not by this branch.
+      restrictions.each_value do |resource_info|
+        next unless resource_info.is_a?(Hash)
+
+        alias_name = resource_info["alias_name"]
+        next if alias_name.blank?
+        return resource_info if [alias_name, alias_name.demodulize].include?(name)
+      end
+
+      nil
+    end
+
+    # Extracts a string resource name from various input types:
+    #   - String: returned as-is (e.g., "Client")
+    #   - Class: returns class name (e.g., Client → "Client")
+    #   - Objects responding to :klass (e.g. HasReports::Resource): reads klass safely
+    #   - Other objects: falls back to class name
+    def resource_name(resource)
+      case resource
+      when String
+        resource
+      when Class
+        resource.name
+      else
+        if resource.respond_to?(:klass)
+          klass_value = resource.respond_to?(:read_attribute) ? resource.read_attribute(:klass) : resource.klass
+          return nil if klass_value.blank?
+          klass_value.is_a?(Class) ? klass_value.name : klass_value.to_s
+        elsif resource.respond_to?(:class)
+          resource.class.name
+        end
+      end
+    end
+  end
+end

data/lib/has_helpers/utils.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "has_helpers/utils/alert"
+require "has_helpers/utils/input"
+require "has_helpers/utils/action"
+require "has_helpers/utils/icon"
+require "has_helpers/utils/render_object"
+require "has_helpers/utils/service"
+require "has_helpers/utils/container"
+require "has_helpers/utils/dataset"
+require "has_helpers/utils/log_notifier"
+require "has_helpers/utils/email_notifier"
+require "has_helpers/utils/slack_conf"
+require "has_helpers/utils/slack_notifier"
+require "has_helpers/utils/text_node"
+require "has_helpers/utils/active_record_utils"
+require "has_helpers/utils/s3_utils"
+require "has_helpers/utils/user_restrictions"

data/lib/has_helpers/version.rb

@@ -0,0 +1,6 @@
+# typed: strong
+# frozen_string_literal: true
+
+module HasHelpers
+  VERSION = "5.0.2"
+end

data/lib/has_helpers/web_socket_publisher.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module HasHelpers
+  module WebSocketPublisher
+    def self.publish(channel, _payload)
+      Rails.logger.warn <<~LOG.strip
+        [HasHelpers::WebSocketPublisher] Attempted to publish to Redis (#{channel}) but no publisher is configured.
+        Please define `HasHelpers::WebSocketPublisher` in an initializer (e.g., config/initializers/web_socket_publisher.rb)
+        Example:
+          module HasHelpers
+            module WebSocketPublisher
+              def self.publish(channel, payload)
+                REDIS.publish(channel, payload.to_json)
+              end
+            end
+          end
+      LOG
+    end
+  end
+end

data/lib/has_helpers/webhook.rb

@@ -0,0 +1,17 @@
+# typed: false
+# frozen_string_literal: true
+
+module HasHelpers::Webhook
+  # Sends a webhook request in a standard format.
+  def self.send(action:, data:, url:, type:)
+    conn = Faraday.new(url: url)
+    conn.post do |req|
+      req.headers["Content-Type"] = "application/json"
+      req.body = {
+        action: action,
+        type: type,
+        data: data
+      }.to_json
+    end
+  end
+end