slack_sender 0.1.0

data/lib/slack_sender/strategy.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module SlackSender
+  # Axn strategy that provides `slack(...)` and `slack!(...)` methods for sending Slack messages.
+  #
+  # Usage:
+  #   class MyAction
+  #     include Axn
+  #     use :slack, channel: :general
+  #
+  #     on_success { slack "It worked!" }
+  #
+  #     def call
+  #       slack "Processing..."
+  #       # ...
+  #     end
+  #   end
+  #
+  # Configuration options:
+  #   channel: - Default channel for all slack() calls (can be overridden per-call)
+  #   profile: - SlackSender profile to use (default: :default)
+  #
+  # All options can be overridden per-call. Call-time values take precedence over defaults.
+  #
+  # Methods:
+  #   slack(...)  - Async delivery via background job (recommended, enables auto-retry)
+  #   slack!(...) - Sync delivery in foreground (immediate execution, no auto-retry)
+  #
+  module Strategy
+    def self.configure(**defaults)
+      Module.new do
+        extend ActiveSupport::Concern
+
+        included do
+          define_method(:__slack_defaults) { defaults }
+          private :__slack_defaults
+        end
+
+        # Send a Slack message asynchronously via background job.
+        # Enables automatic retries for failed sends.
+        #
+        # @param text [String, nil] Optional positional argument for message text (sugar for text: kwarg)
+        # @param kwargs [Hash] SlackSender options (channel:, profile:, blocks:, attachments:, icon_emoji:, etc.)
+        # @return [true, false] true if message was enqueued, false if sending is disabled
+        # @raise [ArgumentError] If no channel specified and no default configured
+        # @raise [SlackSender::Error] If no async backend is configured
+        #
+        # Examples:
+        #   slack "Hello"                           # positional text, uses default channel
+        #   slack "Hello", channel: :other          # positional text, override channel
+        #   slack text: "Hello", channel: :other    # explicit kwargs
+        #   slack channel: :foo, text: "Hi", blocks: [...]  # full kwargs
+        #   slack "Hi", profile: :other_profile     # override profile for this call
+        #
+        def slack(text = nil, **kwargs)
+          __slack_deliver(text, :call, **kwargs)
+        end
+
+        # Send a Slack message synchronously in the foreground.
+        # Use when you need immediate execution or the thread_ts return value.
+        #
+        # @param text [String, nil] Optional positional argument for message text (sugar for text: kwarg)
+        # @param kwargs [Hash] SlackSender options (channel:, profile:, blocks:, attachments:, icon_emoji:, etc.)
+        # @return [String, nil] Thread timestamp from Slack response, or false if sending is disabled
+        # @raise [ArgumentError] If no channel specified and no default configured
+        #
+        # Examples:
+        #   thread_ts = slack! "Hello"              # get thread_ts for replies
+        #   slack! "Urgent!", channel: :alerts      # immediate delivery
+        #
+        def slack!(text = nil, **kwargs)
+          __slack_deliver(text, :call!, **kwargs)
+        end
+
+        private
+
+        def __slack_deliver(text, method, **kwargs)
+          kwargs[:text] = text if text
+
+          # Merge defaults with call-time kwargs (call-time wins)
+          merged = __slack_defaults.merge(kwargs)
+
+          channel = merged.delete(:channel)
+          channels = merged.delete(:channels)
+          profile = merged.delete(:profile) || :default
+
+          raise ArgumentError, "No channel(s) specified and no default channel configured" unless channel || channels
+
+          if channels
+            SlackSender.profile(profile).public_send(method, channels:, **merged)
+          else
+            SlackSender.profile(profile).public_send(method, channel:, **merged)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/slack_sender/util.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module SlackSender
+  module Util
+    # Channel-related errors that should not be retried (permanent failures)
+    NON_RETRYABLE_CHANNEL_ERRORS = [
+      ::Slack::Web::Api::Errors::NotInChannel,
+      ::Slack::Web::Api::Errors::ChannelNotFound,
+      ::Slack::Web::Api::Errors::IsArchived,
+    ].freeze
+
+    def self.non_retryable_channel_error?(exception)
+      NON_RETRYABLE_CHANNEL_ERRORS.any? { |klass| exception.is_a?(klass) }
+    end
+
+    # Checks if kwargs represent an explicit blank text-only call (no other content keys).
+    # Used to treat such calls as no-ops rather than errors.
+    # @param kwargs [Hash] The keyword arguments to check
+    # @return [Boolean] true if text is the only content key and is blank
+    def self.blank_text_only?(kwargs)
+      # Check for presence (not just key existence) since provided_data may include
+      # empty arrays from defaults
+      kwargs.key?(:text) &&
+        kwargs[:text].is_a?(String) &&
+        kwargs[:text].blank? &&
+        kwargs[:blocks].blank? &&
+        kwargs[:attachments].blank? &&
+        kwargs[:file].blank? &&
+        kwargs[:files].blank?
+    end
+
+    # Determines retry behavior for Slack API exceptions
+    # @param exception [Exception] The exception that occurred
+    # @return [Symbol, Integer, nil] :discard to skip retry, Integer (seconds) for custom delay, nil for default retry
+    def self.parse_retry_delay_from_exception(exception)
+      # Discard known-do-not-retry exceptions
+      return :discard if non_retryable_channel_error?(exception)
+
+      # Check for retry headers from Slack (e.g., rate limits)
+      if exception.respond_to?(:response_headers) && exception.response_headers.is_a?(Hash)
+        retry_after = exception.response_headers["Retry-After"] || exception.response_headers["retry-after"]
+        return add_jitter(retry_after.to_i) if retry_after.present?
+      end
+
+      # Default: let the backend use its default retry behavior
+      nil
+    end
+
+    # Adds random jitter to a delay to prevent thundering herd
+    # @param delay [Integer] The base delay in seconds
+    # @return [Integer] The delay with jitter added (0-30% extra)
+    def self.add_jitter(delay)
+      return delay if delay <= 0
+
+      jitter = (delay * rand * 0.3).ceil
+      delay + jitter
+    end
+
+    # Extracts the needed scope from a MissingScope exception.
+    # Tries multiple locations since slack-ruby-client's structure varies:
+    # - response_metadata["needed"] (documented but not always present)
+    # - response.body.needed (Slack::Messages::Message object)
+    # - HTTP header x-accepted-oauth-scopes
+    # @param exception [Slack::Web::Api::Errors::MissingScope] The exception
+    # @return [String, nil] The needed scope, or nil if not found
+    def self.extract_needed_scope(exception)
+      # Try response_metadata first (documented location)
+      exception.response_metadata&.dig("needed") ||
+        # Try response.body which is a Slack::Messages::Message
+        exception.response&.body&.try(:needed) ||
+        exception.response&.body&.try(:[], "needed") ||
+        # Try HTTP headers as fallback
+        exception.response&.env&.dig(:response_headers, "x-accepted-oauth-scopes")
+    end
+
+    # Builds a descriptive error message for MissingScope exceptions.
+    # @param exception [Slack::Web::Api::Errors::MissingScope] The exception
+    # @return [String] A user-friendly error message
+    def self.missing_scope_error_message(exception)
+      needed = extract_needed_scope(exception)
+      if needed.present?
+        format(ErrorMessages::MISSING_SCOPE, needed)
+      else
+        ErrorMessages::MISSING_SCOPE_UNKNOWN
+      end
+    end
+  end
+end

data/lib/slack_sender/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SlackSender
+  VERSION = "0.1.0"
+end

data/lib/slack_sender.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/hash/keys"
+require "active_support/concern"
+require "slack-ruby-client"
+begin
+  require "sidekiq"
+rescue LoadError
+  # Sidekiq is optional for runtime, only needed for async operations
+end
+begin
+  require "active_job"
+rescue LoadError
+  # ActiveJob is optional for runtime, only needed for async operations
+end
+require "axn"
+require_relative "slack_sender/version"
+require_relative "slack_sender/configuration"
+require_relative "slack_sender/util"
+require_relative "slack_sender/error_messages"
+
+module SlackSender
+  class Error < StandardError; end
+
+  # Raised for invalid arguments that should not be retried
+  # (e.g., missing content, invalid blocks, incompatible options)
+  class InvalidArgumentsError < Error; end
+end
+
+require_relative "slack_sender/channel_normalizer"
+require_relative "slack_sender/profile"
+require_relative "slack_sender/profile_registry"
+require_relative "slack_sender/delivery_axn"
+require_relative "slack_sender/file_wrapper"
+require_relative "slack_sender/multi_file_wrapper"
+require_relative "slack_sender/file_uploader"
+require_relative "slack_sender/strategy"
+
+# Register the slack strategy with Axn (before loading Notifier which uses it)
+Axn::Strategies.register(:slack, SlackSender::Strategy)
+
+require_relative "slack_sender/notifier"
+
+module SlackSender
+  class << self
+    def register(name = nil, **config)
+      ProfileRegistry.register(name.presence || :default, config)
+    end
+
+    def profile(name)
+      ProfileRegistry.find(name)
+    end
+
+    def [](name) = profile(name)
+
+    def default_profile
+      ProfileRegistry.find(:default)
+    rescue ProfileNotFound
+      raise Error, "No default profile set. Call SlackSender.register(...) first"
+    end
+
+    def client = default_profile.client
+    def call(**) = default_profile.call(**)
+    def call!(**) = default_profile.call!(**)
+    def group_link(key) = default_profile.group_link(key)
+  end
+end
+
+# Rails integration (if in Rails context)
+require_relative "slack_sender/rails/engine" if defined?(Rails) && Rails.const_defined?(:Engine)

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: slack_sender
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kali Donovan
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: axn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.alpha.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.alpha.4.1
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: slack-ruby-client
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Slack messaging with background dispatch with automatic rate-limit retries.
+email:
+- kali@teamshares.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".husky/pre-commit"
+- ".lintstagedrc"
+- CHANGELOG.md
+- README.md
+- Rakefile
+- docs/axn_integration.md
+- docs/configuration.md
+- docs/troubleshooting.md
+- docs/usage.md
+- lib/slack_sender.rb
+- lib/slack_sender/channel_normalizer.rb
+- lib/slack_sender/configuration.rb
+- lib/slack_sender/delivery_axn.rb
+- lib/slack_sender/delivery_axn/async_configuration.rb
+- lib/slack_sender/delivery_axn/error_message_parsing.rb
+- lib/slack_sender/delivery_axn/exception_handlers.rb
+- lib/slack_sender/delivery_axn/validation.rb
+- lib/slack_sender/error_messages.rb
+- lib/slack_sender/file_uploader.rb
+- lib/slack_sender/file_wrapper.rb
+- lib/slack_sender/multi_file_wrapper.rb
+- lib/slack_sender/notifier.rb
+- lib/slack_sender/notifier/notification_definition.rb
+- lib/slack_sender/notifier/notification_dsl.rb
+- lib/slack_sender/profile.rb
+- lib/slack_sender/profile_registry.rb
+- lib/slack_sender/rails/engine.rb
+- lib/slack_sender/strategy.rb
+- lib/slack_sender/util.rb
+- lib/slack_sender/version.rb
+homepage: https://github.com/teamshares/slack_sender
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/teamshares/slack_sender
+  source_code_uri: https://github.com/teamshares/slack_sender
+  changelog_uri: https://github.com/teamshares/slack_sender/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Slack messages for people who don’t want to babysit Slack.
+test_files: []