slack_sender 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 320590e57f220cb0e85688e3987c1fdee1b9f1bc014a9907099ec277568a06f6
-  data.tar.gz: b478553cd49da506001a5223673cc9a2ca0d2adf79cba6d6fc4e5a317f33db89
+  metadata.gz: 00e8fd0b67a215e7066b491b3dc85afae96e4eec260bb156bf8a8835c1a96269
+  data.tar.gz: ed385d6feb6cfd4fadd85d05f4a7716ec021b97c64e26156fa798cda9d7bd80b
 SHA512:
-  metadata.gz: a5153bb970a492024ac5ddc16f1fab9e6debe046636f87330c4ab19ebade650702123e2edc7a7d3473e9e31a84f51ac6e0830cae0be2add5c18542996ae89b8d
-  data.tar.gz: 5c5737bfa9581c9766d0eb66b4d20367501006f2b40acff2f41aafabc3455be2db2c9174b1fa3feff31f5d70db032124b4928a7c2d1fb2140975f792cd8a614c
+  metadata.gz: 3ba5e9b7ddf025229eef2707025aa6871044c1f17dfb74e330d5e95852aa08c4589b719743c23b4e72fa2fe83b61b1c8cef3d051b4d1f32882576a12db2bcfcf
+  data.tar.gz: b15b68b15932c145ccbcb855609dcd3e405716288565f43493528b943fef0c7be2a3ddd2978641798392bf4a562fff4b664d6fc99962b7226df82c74faf0ad5e

data/CHANGELOG.md

@@ -1,6 +1,62 @@
 ## [Unreleased]
 
-* N/A
+## [0.1.1] - 2026-08-05
+
+- `sandbox_mode` is now a per-class-overridable setting. An Axn action using the `:slack` strategy
+  can opt in/out of sandbox for its own sends via `configure(:slack_sender) { |c| c.sandbox_mode = false }`
+  (the axn `PRO-2880` namespaced-config DSL); the override is resolved at the origin action when it
+  sends, threaded down to `DeliveryAxn`, and inherits into subclasses. Actions that declare none are
+  unaffected and follow global config. Applies to the strategy delivery path only, not
+  `SlackSender.group_link`. Internally, `Configuration#sandbox_mode` moved to the `Axn::Configurable`
+  DSL (a dynamic Proc `default:` preserving the `Rails.env`-derived behavior); `sandbox_mode?` is unchanged.
+  `sandbox_mode?` is now the DSL-generated predicate reader (PRO-2888) rather than a hand-written
+  alias. Requires an `axn` with `Axn::Configurable` namespaced config (PRO-2880) and predicate
+  readers (PRO-2888).
+- Source `axn` from the published `0.1.0-alpha.5` release on RubyGems instead of the temporary
+  `github: teamshares/axn, branch: main` git pin. The gemspec lower bound is now `>= 0.1.0-alpha.5`
+  — the first release where a Proc `default:` is dynamic on its own (the `callable:` kwarg removed),
+  which `Configuration#sandbox_mode` relies on. No behavior change.
+- Adopt the upstream `Axn::Configurable::Settings` DSL for the simple, declarative
+  `SlackSender::Configuration` settings (`enabled`, `silence_archived_channel_exceptions`,
+  `sandbox_default_behavior`, `use_slack_notifiers_namespace`). Bespoke/computed settings
+  (`sandbox_mode?`, `async_backend`, `max_async_file_upload_size`) remain hand-written.
+- **Behavior change:** invalid `sandbox_default_behavior` values now raise the DSL's
+  `ArgumentError` (`sandbox_default_behavior must be one of ...`) instead of the previous
+  hand-written `Unsupported sandbox behavior` message. `Profile`'s per-profile
+  `sandbox: { behavior: ... }` validation now shares `Configuration::SUPPORTED_SANDBOX_BEHAVIORS`
+  and raises the matching wording (`sandbox.behavior must be one of ...`), so the two no longer
+  diverge.
+- Requires a release of upstream `axn` that includes `Axn::Configurable` (PRO-2769) and the error
+  message presentation behavior from PRO-2820 (#132) and PRO-2832 (#134) — the base/reason prefix
+  and nested-`call!` header aggregation that the base-message behavior below relies on. The gemspec
+  runtime dependency lower bound is raised to `axn >= 0.1.0-alpha.5` accordingly (see the sourcing
+  note above), so consumers can't resolve an older `axn` and `NameError` on `require`.
+- **Behavior change:** failed deliveries now carry a consistent base message on `result.error`.
+  Every failure reason is prefixed as `"Unable to send Slack message: <reason>"`, and unexpected
+  errors with no specific reason handler surface `"Unable to send Slack message"` instead of axn's
+  generic `"Something went wrong"`. This is presentation-only — error classification, retries, and
+  exception reporting are unchanged. The `MISSING_SCOPE`/`MISSING_SCOPE_UNKNOWN` messages were
+  rewritten as complete, self-contained sentences (`"Missing required Slack scope '%s'. ..."`) so
+  they read cleanly both prefixed by the base (`DeliveryAxn`'s text-post path) and standalone
+  (`FileUploader`'s async pre-upload path, which has no base to attach to).
+- Add a `slack_options:` passthrough hash for forwarding arbitrary `chat.postMessage` options
+  (`unfurl_links`, `unfurl_media`, `reply_broadcast`, `metadata`, …) straight to Slack. Managed
+  keys (channel/text/blocks/attachments/icon_emoji/thread_ts) take precedence; applies to the
+  text-post path only, not file uploads. Like `blocks`/`attachments`, `slack_options` is
+  deep-stringified before an async job is enqueued, so a symbol-keyed hash (e.g.
+  `slack_options: { unfurl_links: false }`) doesn't get rejected by Sidekiq's strict argument
+  checks before the message is ever sent. A call with blank `text:` but a non-empty
+  `slack_options:` (and no real content) now fails fast with the `NO_CONTENT_PROVIDED` validation
+  error instead of being silently dropped as a no-op — `slack_options` are message modifiers, not
+  content, so forwarding a content-less call to Slack would only return `no_text` and burn async
+  retries. The error is an `InvalidArgumentsError`, so async jobs discard it rather than retrying.
+  `slack_options` is also available in the `Notifier` `notify do … end` DSL
+  (`slack_options unfurl_links: false`).
+- **Behavior change:** async deliveries that fail argument validation inside a `preprocess` lambda
+  (e.g. an unknown channel) are now discarded instead of retried. `axn` wraps such errors in an
+  `Axn::ContractViolation::PreprocessingError`, so the previous `InvalidArgumentsError`-only
+  Sidekiq `sidekiq_retry_in` / ActiveJob `discard_on` checks missed them and burned all 5 retries
+  on a permanently-invalid job.
 
 ## [0.1.0] - 2026-02-19
 

data/README.md

@@ -20,7 +20,7 @@ bundle install
 
 **Requirements:**
 - Ruby >= 3.2.1
-- A Slack Bot User OAuth Token with `chat:write` scope (see [Configuration](docs/configuration.md#required-slack-scopes) for full scope list)
+- A Slack Bot User OAuth Token with `chat:write` scope (see [Configuration](https://github.com/teamshares/slack_sender/blob/main/docs/configuration.md#required-slack-scopes) for full scope list)
 - For async delivery: Sidekiq or ActiveJob (auto-detected)
 
 ## Quick Start - Minimal
@@ -67,18 +67,19 @@ That's it. SlackSender handles rate limits, retries, and sandbox redirection (if
 
 | Guide | Description |
 |-------|-------------|
-| [Usage Guide](docs/usage.md) | Messages, files, threading, multi-channel delivery |
-| [Configuration](docs/configuration.md) | Profiles, sandbox mode, global settings |
-| [Axn Integration](docs/axn_integration.md) | `use :slack` strategy and `SlackSender::Notifier` |
-| [Troubleshooting](docs/troubleshooting.md) | Common errors and FAQ |
+| [Usage Guide](https://github.com/teamshares/slack_sender/blob/main/docs/usage.md) | Messages, files, threading, multi-channel delivery |
+| [Configuration](https://github.com/teamshares/slack_sender/blob/main/docs/configuration.md) | Profiles, sandbox mode, global settings |
+| [Axn Integration](https://github.com/teamshares/slack_sender/blob/main/docs/axn_integration.md) | `use :slack` strategy and `SlackSender::Notifier` |
+| [Troubleshooting](https://github.com/teamshares/slack_sender/blob/main/docs/troubleshooting.md) | Common errors and FAQ |
 
 ## Features
 
 - **Background dispatch** with automatic rate-limit retries via Sidekiq or ActiveJob
 - **Multi-channel delivery** — broadcast to multiple channels efficiently
-- **Sandbox mode** — redirect or suppress messages in non-production environments
+- **Sandbox mode** — redirect or suppress messages in non-production environments, with per-action overrides via `configure(:slack_sender)`
 - **File uploads** — sync and async, with automatic size handling
 - **Multiple profiles** — manage multiple Slack workspaces
+- **Full option passthrough** — forward any [`chat.postMessage`](https://www.rubydoc.info/gems/slack-ruby-client/Slack/Web/Api/Endpoints/Chat#chat_postMessage-instance_method) option via [`slack_options:`](https://github.com/teamshares/slack_sender/blob/main/docs/usage.md#other-chatpostmessage-options)
 - **Axn integration** — `use :slack` strategy and dedicated `Notifier` base class
 
 ## Development

data/lib/slack_sender/configuration.rb

@@ -2,6 +2,16 @@
 
 module SlackSender
   class Configuration
+    # Validated instance settings via the upstream Axn::Configurable DSL (class flavor).
+    # Only the simple settings are declared here; everything bespoke below stays hand-written.
+    extend Axn::Configurable::Settings
+
+    # Per-class overrides (e.g. `sandbox_mode`) live under the :slack_sender namespace, reached via
+    # `MyAction.configure(:slack_sender) { |c| c.sandbox_mode = false }` on any `use :slack` action.
+    # Must precede any `overridable: true` setting.
+    config_namespace :slack_sender
+    overridable_config_source { SlackSender.config }
+
     SUPPORTED_ASYNC_BACKENDS = %i[sidekiq active_job].freeze
     SUPPORTED_SANDBOX_BEHAVIORS = %i[noop redirect passthrough].freeze
 
@@ -11,42 +21,62 @@ module SlackSender
     # Default file size threshold for async uploads
     DEFAULT_MAX_ASYNC_FILE_UPLOAD_SIZE = 26_214_400 # 25 MB
 
-    attr_writer :sandbox_mode
-    attr_accessor :enabled, :silence_archived_channel_exceptions
+    setting :enabled, default: true
+    setting :silence_archived_channel_exceptions
+    setting :sandbox_default_behavior, default: :noop, one_of: SUPPORTED_SANDBOX_BEHAVIORS
 
     # Whether to autoload files in app/slack_notifiers under the SlackNotifiers namespace.
     # When true (default): app/slack_notifiers/foo.rb defines SlackNotifiers::Foo
     # When false: app/slack_notifiers/foo.rb defines Foo (standard Rails behavior)
-    attr_accessor :use_slack_notifiers_namespace
-
-    def initialize
-      # Default values
-      @enabled = true
-      @sandbox_default_behavior = :noop
-      @max_async_file_upload_size = DEFAULT_MAX_ASYNC_FILE_UPLOAD_SIZE
-      @use_slack_notifiers_namespace = true
-    end
-
-    def sandbox_mode?
-      return @sandbox_mode unless @sandbox_mode.nil?
-
-      if defined?(Rails) && Rails.respond_to?(:env)
-        !Rails.env.production?
+    setting :use_slack_notifiers_namespace, default: true
+
+    # Whether messages are redirected/suppressed for non-production. The Proc default is dynamic:
+    # axn's Configurable re-derives it from Rails.env on every read while the setting is unset. An
+    # explicit true/false wins; an explicit nil resets to the default (custom writer below). Marked
+    # overridable so an individual action can opt in/out of sandbox for its own sends via
+    # `configure(:slack_sender)` (resolved in the strategy and threaded down to DeliveryAxn).
+    setting :sandbox_mode,
+            default: -> { defined?(Rails) && Rails.respond_to?(:env) ? !Rails.env.production? : true },
+            overridable: true
+
+    # nil is a documented value (`Boolean or nil`) meaning "use the default". The DSL writer would
+    # store an explicit nil as-is, making `sandbox_mode?` return `!!nil == false` and silently
+    # disabling sandbox in non-production. Treat an assigned nil as a reset to the dynamic default
+    # (remove the ivar so the Proc default re-derives), matching the pre-DSL hand-written reader.
+    def sandbox_mode=(value)
+      if value.nil?
+        remove_instance_variable(:@sandbox_mode) if instance_variable_defined?(:@sandbox_mode)
       else
-        true
+        @sandbox_mode = value
       end
     end
 
-    attr_reader :sandbox_default_behavior
+    def initialize
+      # Bespoke settings (not backed by the DSL) need their defaults set here.
+      @max_async_file_upload_size = DEFAULT_MAX_ASYNC_FILE_UPLOAD_SIZE
+    end
 
-    def sandbox_default_behavior=(value)
-      unless SUPPORTED_SANDBOX_BEHAVIORS.include?(value)
-        raise ArgumentError,
-              "Unsupported sandbox behavior: #{value.inspect}. " \
-              "Supported behaviors: #{SUPPORTED_SANDBOX_BEHAVIORS.inspect}"
+    # `sandbox_mode?` is generated by the Axn::Configurable DSL (predicate reader, PRO-2888) as
+    # `!!sandbox_mode`; it remains the public API used throughout the codebase.
+
+    # Returns [found, value] for the per-class `name` override declared via `configure(:slack_sender)`
+    # on `origin` (or the nearest ancestor), found=false when none. Reads axn's per-class override
+    # store directly: axn exposes resolution (`resolve_override_for`) but not presence, and the
+    # delivery path must diverge from global config *only* when an action actually opted in.
+    def self.class_override(origin, name)
+      return [false, nil] unless origin.is_a?(Module)
+
+      klass = origin
+      while klass.is_a?(Module)
+        if klass.instance_variable_defined?(:@_axn_config_overrides)
+          slot = klass.instance_variable_get(:@_axn_config_overrides)[config_namespace]
+          return [true, slot[name]] if slot&.key?(name)
+        end
+        break unless klass.is_a?(Class) && klass.superclass
+
+        klass = klass.superclass
       end
-
-      @sandbox_default_behavior = value
+      [false, nil]
     end
 
     def async_backend

data/lib/slack_sender/delivery_axn/async_configuration.rb

@@ -19,21 +19,24 @@ module SlackSender
         # Backend is already validated by Configuration#async_backend=
         case backend
         when :sidekiq
-          async :sidekiq, retry: 5, dead: false
-          # Configure Sidekiq-specific retry logic (including skipping retries for InvalidArgumentsError)
-          if defined?(Sidekiq::Job) && respond_to?(:sidekiq_retry_in)
+          # Configure Sidekiq-specific retry logic (including skipping retries for InvalidArgumentsError).
+          # On axn's current Sidekiq adapter the action is not itself a Sidekiq::Job; sidekiq_retry_in is a
+          # worker-subclass hook, so it must be declared inside the `async :sidekiq do…end` block (the block
+          # is class_eval'd onto the generated AxnSidekiqWorker).
+          async :sidekiq, retry: 5, dead: false do
             sidekiq_retry_in do |_count, exception|
-              # Don't retry invalid arguments
-              next :discard if exception.is_a?(SlackSender::InvalidArgumentsError)
+              # Don't retry invalid arguments (incl. an InvalidArgumentsError raised from a
+              # preprocess lambda, which the worker re-raises wrapped in a PreprocessingError).
+              next :discard if SlackSender::Util.invalid_arguments_error?(exception)
 
               SlackSender::Util.parse_retry_delay_from_exception(exception)
             end
           end
         when :active_job
           async :active_job do
-            # Skip retries for invalid arguments - these will never succeed
-            discard_on SlackSender::InvalidArgumentsError
-
+            # ActiveJob reads rescue handlers bottom-to-top (last declared is matched first), so the
+            # catch-all retry_on StandardError MUST be declared before the specific discards below —
+            # otherwise it shadows them and permanent errors burn all attempts.
             retry_on StandardError, wait: :exponentially_longer, attempts: 5 do |_job, exception|
               retry_behavior = SlackSender::Util.parse_retry_delay_from_exception(exception)
               next if retry_behavior == :discard
@@ -42,6 +45,21 @@ module SlackSender
               retry_job wait: retry_behavior.seconds if retry_behavior.is_a?(Numeric) && retry_behavior.positive?
               # Otherwise, let ActiveJob use its default retry behavior
             end
+
+            # Skip retries for invalid arguments - these will never succeed. Declared after retry_on
+            # so this specific handler takes precedence over the catch-all above.
+            discard_on SlackSender::InvalidArgumentsError
+
+            # An InvalidArgumentsError raised from a preprocess lambda (e.g. an unknown channel)
+            # arrives wrapped in a PreprocessingError, which discard_on can't match by cause. Unwrap
+            # only those to the InvalidArgumentsError so the discard_on above catches them (no
+            # retries); every other preprocessing error propagates unchanged to retry_on/reporting,
+            # mirroring the Sidekiq path (Util.invalid_arguments_error?).
+            around_perform do |_job, block|
+              block.call
+            rescue Axn::ContractViolation::PreprocessingError => e
+              raise SlackSender::Util.invalid_arguments_error?(e) ? e.cause : e
+            end
           end
         end
       end

data/lib/slack_sender/delivery_axn/validation.rb

@@ -19,13 +19,19 @@ module SlackSender
 
       private
 
+      # slack_options are message *modifiers* (unfurl_links, metadata, …), not content, so they do
+      # NOT count here: a call with no text/blocks/attachments/files is content-blank even when it
+      # carries slack_options. Forwarding such a call to Slack would return no_text and burn async
+      # retries on a deterministic failure, so we fail fast with NO_CONTENT_PROVIDED instead.
       def content_blank? = text.blank? && blocks.blank? && attachments.blank? && files.blank? && file_ids.blank?
 
       def explicit_blank_text_only?
-        # Caller explicitly passed `text:` but it's blank, and no other content.
+        # Caller explicitly passed `text:` but it's blank, with no other content. Treat as an
+        # intentional no-op so we don't error or retry on intent-only blank sends. But if
+        # slack_options are present the caller clearly meant to send something, so fall through to
+        # raise NO_CONTENT_PROVIDED rather than silently dropping the call.
         # Optional text is nil when omitted; preprocess returns "" when text: "" is passed.
-        # Treat as no-op so we don't error or retry on intent-only blank sends.
-        content_blank? && text.is_a?(String)
+        content_blank? && text.is_a?(String) && slack_options.blank?
       end
 
       # TODO: Add better validations against slack block kit API

data/lib/slack_sender/delivery_axn.rb

@@ -9,6 +9,10 @@ module SlackSender
   class DeliveryAxn
     include Axn
 
+    # chat.postMessage keys SlackSender owns. slack_options may never set these — even when a
+    # managed key is blank (and thus dropped by compact_blank), the passthrough must not fill it.
+    MANAGED_POST_MESSAGE_KEYS = %i[channel text blocks attachments icon_emoji thread_ts].freeze
+
     # Class method modules (extend)
     extend AsyncConfiguration
 
@@ -17,10 +21,21 @@ module SlackSender
     include ErrorMessageParsing
     include Validation
 
-    # Expose InvalidArgumentsError message directly (these errors skip retries)
-    # Handle both direct raises and raises from preprocess lambdas (wrapped in PreprocessingError)
-    error(if: InvalidArgumentsError, &:message)
-    error(if: ->(exception:) { exception.is_a?(Axn::ContractViolation::PreprocessingError) && exception.cause.is_a?(InvalidArgumentsError) }) { |e| e.cause.message }
+    # Base/headline message. axn prefixes every failure *reason* with this as
+    # "Unable to send Slack message: <reason>", and uses it standalone as result.error for any
+    # unexpected error that has no specific reason handler (instead of axn's generic "Something
+    # went wrong"). It only affects the error-message *presentation* — classification, retries,
+    # and on_exception reporting are unchanged.
+    error "Unable to send Slack message"
+
+    # Surface the underlying SlackSender::Error's message on result.error so it gets the base
+    # prefix too (InvalidArgumentsError, the re-raised missing-scope error, etc.). A direct raise
+    # matches on the exception itself; one raised from a preprocess lambda arrives wrapped in an
+    # Axn::ContractViolation::PreprocessingError, so #unwrapped_slack_error unwraps the cause. One
+    # resolver handles both cases, so there is no ordering dependency between separate handlers.
+    # Message presentation only — these stay exception-bucket (still reported + retried like any
+    # other StandardError).
+    error(if: ->(exception:) { unwrapped_slack_error(exception) }) { |exception| unwrapped_slack_error(exception).message }
 
     expects :profile, type: Profile, preprocess: lambda { |p|
       # If given a string/symbol (profile name), look it up in the registry
@@ -54,6 +69,18 @@ module SlackSender
     # Array of hashes with "id" and "title" keys.
     expects :file_ids, type: Array, optional: true
 
+    # Escape hatch: arbitrary chat.postMessage options forwarded straight to Slack
+    # (e.g. unfurl_links:, unfurl_media:, reply_broadcast:, metadata:). Managed keys
+    # (channel/text/blocks/attachments/icon_emoji/thread_ts) take precedence so sandbox
+    # redirection and text formatting can't be clobbered. Applies to the text-post path only,
+    # not file uploads (a different endpoint with a different option set).
+    expects :slack_options, type: Hash, optional: true
+
+    # Per-action sandbox override, resolved from the origin action's configure(:slack_sender) and
+    # threaded down by the strategy. Absent (nil) on the direct SlackSender.call path — then the
+    # global SlackSender.config.sandbox_mode? applies, as before.
+    expects :sandbox_mode, type: :boolean, optional: true
+
     exposes :thread_ts, type: String, optional: true
 
     def call
@@ -84,11 +111,14 @@ module SlackSender
 
     # Sandbox behavior handling
     def effective_sandbox_behavior
-      return nil unless SlackSender.config.sandbox_mode?
+      return nil unless sandbox_mode_enabled?
 
       profile.resolved_sandbox_behavior
     end
 
+    # A per-action override (threaded from the strategy) wins; otherwise fall back to global config.
+    def sandbox_mode_enabled? = sandbox_mode.nil? ? SlackSender.config.sandbox_mode? : sandbox_mode
+
     def sandbox_noop? = effective_sandbox_behavior == :noop
     def sandbox_redirect? = effective_sandbox_behavior == :redirect
     def sandbox_passthrough? = effective_sandbox_behavior == :passthrough || effective_sandbox_behavior.nil?
@@ -210,8 +240,27 @@ module SlackSender
         thread_ts:,
       }.compact_blank
 
+      # Merge caller passthrough options. Managed keys always win: strip them from the passthrough
+      # first, so a blank managed key (dropped by compact_blank above) can't be shadowed by a
+      # same-named slack_options key. deep_symbolize_keys mirrors the deep_stringify_keys applied at
+      # enqueue (Profile#normalize_for_async_serialization!), so nested option hashes (e.g. metadata:)
+      # round-trip with symbol keys intact rather than staying string-keyed after the async hop.
+      if slack_options.present?
+        passthrough = slack_options.deep_symbolize_keys.except(*MANAGED_POST_MESSAGE_KEYS)
+        params = passthrough.merge(params)
+      end
+
       response = client.chat_postMessage(**params)
       expose thread_ts: response["ts"]
     end
+
+    # Returns the SlackSender::Error carried by an exception — the exception itself, or the
+    # unwrapped cause of an Axn preprocessing wrapper — or nil if there is none.
+    def unwrapped_slack_error(exception)
+      return exception if exception.is_a?(SlackSender::Error)
+      return exception.cause if exception.is_a?(Axn::ContractViolation::PreprocessingError) && exception.cause.is_a?(SlackSender::Error)
+
+      nil
+    end
   end
 end

data/lib/slack_sender/error_messages.rb

@@ -23,10 +23,14 @@ module SlackSender
     FILES_EXCEED_ASYNC_LIMIT = "Total file size (%s bytes) exceeds max_async_file_upload_size (%s bytes). " \
                                "Use SlackSender.call! for synchronous upload, or increase config.max_async_file_upload_size"
 
-    # Slack API scope errors
-    MISSING_SCOPE = "Slack API missing_scope error: required scope '%s' is not granted. " \
+    # Slack API scope errors.
+    # NOTE: these are shared by two call sites with different framing — DeliveryAxn's text-post
+    # path (prefixed by its base message, "Unable to send Slack message: ...") and FileUploader's
+    # async pre-upload path (raised standalone, with no base to attach to). Written as complete,
+    # self-contained sentences so they read correctly either way.
+    MISSING_SCOPE = "Missing required Slack scope '%s'. " \
                     "Add this scope to your Slack app at https://api.slack.com/apps and reinstall the app."
-    MISSING_SCOPE_UNKNOWN = "Slack API missing_scope error (scope not specified in response). " \
+    MISSING_SCOPE_UNKNOWN = "Missing a required Slack scope (not specified in response). " \
                             "Check your Slack app's OAuth scopes at https://api.slack.com/apps"
 
     # File upload errors

data/lib/slack_sender/file_wrapper.rb

@@ -12,8 +12,9 @@ module SlackSender
       # If it's already a FileWrapper, return it as-is
       return file if file.instance_of?(self)
 
-      # If it's a string file path, open it first
-      file = File.open(file) if file.instance_of?(String) && File.exist?(file)
+      # If it's a string file path, open it first. Use the block form so the
+      # file descriptor is closed once initialize has read its content.
+      return File.open(file) { |f| new(f, index) } if file.instance_of?(String) && File.exist?(file)
 
       new(file, index)
     end

data/lib/slack_sender/notifier/notification_definition.rb

@@ -30,8 +30,11 @@ module SlackSender
         # Resolve payload
         resolved_payload = payload.transform_values { |v| resolve(v, notifier) }.compact
 
-        # Validate: at least one payload field
-        raise ArgumentError, "Missing payload in notify block. Add `text`, `blocks`, `attachments`, or `files`." if resolved_payload.empty?
+        # Validate: at least one real content field. slack_options are modifiers, not content, so a
+        # block that sets only them (or whose dynamic content resolver returned nil) has no payload
+        # and must fail fast here rather than enqueue a job that later fails with NO_CONTENT_PROVIDED.
+        content_payload = resolved_payload.except(*NotificationDSL::PASSTHROUGH_FIELDS)
+        raise ArgumentError, "Missing payload in notify block. Add `text`, `blocks`, `attachments`, or `files`." if content_payload.empty?
 
         # Resolve profile if specified
         resolved_profile = profile ? resolve(profile, notifier) : nil

data/lib/slack_sender/notifier/notification_dsl.rb

@@ -5,7 +5,11 @@ module SlackSender
     # Builder DSL for the `notify do ... end` block.
     # Collects routing, payload, and condition settings into a NotificationDefinition.
     class NotificationDSL
-      PAYLOAD_FIELDS = %i[text blocks attachments icon_emoji thread_ts files].freeze
+      PAYLOAD_FIELDS = %i[text blocks attachments icon_emoji thread_ts files slack_options].freeze
+
+      # Fields that modify a message rather than constitute its content. A notify block that sets
+      # only these has no real payload, so they don't count toward the "Missing payload" check.
+      PASSTHROUGH_FIELDS = %i[slack_options].freeze
 
       def initialize
         @channels = []

data/lib/slack_sender/profile.rb

@@ -2,8 +2,6 @@
 
 module SlackSender
   class Profile # rubocop:disable Metrics/ClassLength
-    SUPPORTED_SANDBOX_BEHAVIORS = %i[redirect noop passthrough].freeze
-
     # Valid kwargs accepted by Profile#call / Profile#call!
     # These are validated early (before backgrounding) to catch typos like `test:` instead of `text:`
     VALID_CALL_KWARGS = %i[
@@ -16,9 +14,14 @@ module SlackSender
       thread_ts
       file
       files
+      slack_options
       profile
     ].freeze
 
+    # Keys whose (possibly nested) symbol keys must be stringified before an async enqueue, so
+    # Sidekiq's strict argument checking doesn't reject them. Add new passthrough-style keys here.
+    ASYNC_SERIALIZABLE_KEYS = %i[blocks attachments slack_options].freeze
+
     attr_reader :default_channel, :channels, :user_groups, :slack_client_config, :key, :sandbox
 
     def initialize(key:, token:, default_channel: nil, channels: {}, user_groups: {}, slack_client_config: {}, sandbox: {})
@@ -62,13 +65,16 @@ module SlackSender
         user_group: normalize_sandbox_user_group(config[:user_group]),
       }.compact
 
-      # Extract and validate behavior if present
+      # Extract and validate behavior if present. Shares Configuration::SUPPORTED_SANDBOX_BEHAVIORS
+      # (single source of truth) and mirrors its `one_of:` DSL wording, so a mistyped
+      # `sandbox: { behavior: ... }` and a mistyped `config.sandbox_default_behavior =` read the
+      # same way.
       if config[:behavior]
         behavior = config[:behavior].to_sym
-        unless SUPPORTED_SANDBOX_BEHAVIORS.include?(behavior)
+        supported = Configuration::SUPPORTED_SANDBOX_BEHAVIORS
+        unless supported.include?(behavior)
           raise ArgumentError,
-                "Unsupported sandbox behavior: #{behavior.inspect}. " \
-                "Supported behaviors: #{SUPPORTED_SANDBOX_BEHAVIORS.inspect}"
+                "sandbox.behavior must be one of #{supported.map(&:inspect).join(", ")}; got #{behavior.inspect}"
         end
         result[:behavior] = behavior
       end
@@ -97,8 +103,11 @@ module SlackSender
 
     public
 
-    def call(**)
-      enabled, kwargs = enabled_and_preprocessed_kwargs(**)
+    # sandbox_mode: threads a per-action sandbox override down to DeliveryAxn (resolved by the
+    # strategy from the caller's configure(:slack_sender)). :inherit means "not overridden" — omit
+    # it so DeliveryAxn falls back to global config, preserving behavior for every other caller.
+    def call(sandbox_mode: :inherit, **kwargs)
+      enabled, kwargs = enabled_and_preprocessed_kwargs(**kwargs)
       return false unless enabled
 
       # Validate async backend is configured and available
@@ -114,6 +123,8 @@ module SlackSender
               "Profile must be registered before using async delivery. Register it with SlackSender.register(name, config)"
       end
 
+      kwargs[:sandbox_mode] = sandbox_mode unless sandbox_mode == :inherit
+
       if kwargs[:channels]
         dispatch_to_channels(kwargs)
       else
@@ -123,12 +134,14 @@ module SlackSender
       true
     end
 
-    def call!(**)
-      enabled, kwargs = enabled_and_preprocessed_kwargs(**)
+    def call!(sandbox_mode: :inherit, **kwargs)
+      enabled, kwargs = enabled_and_preprocessed_kwargs(**kwargs)
       return false unless enabled
 
       raise ArgumentError, ErrorMessages::MULTI_CHANNEL_SYNC_NOT_SUPPORTED if kwargs[:channels]
 
+      kwargs[:sandbox_mode] = sandbox_mode unless sandbox_mode == :inherit
+
       DeliveryAxn.call!(profile: self, **kwargs).thread_ts
     end
 
@@ -195,7 +208,7 @@ module SlackSender
         normalize_file_to_files!(kwargs)
         normalize_and_apply_channels!(kwargs)
         validate_and_handle_profile_parameter!(kwargs)
-        preprocess_blocks_and_attachments!(kwargs)
+        normalize_async_serializable_keys!(kwargs)
       end
     end
 
@@ -283,11 +296,8 @@ module SlackSender
       kwargs[:validate_known_channel] = true
     end
 
-    def preprocess_blocks_and_attachments!(kwargs)
-      # Convert symbol keys to strings in blocks and attachments for JSON serialization
-      # This ensures they're serializable for async jobs (Sidekiq/ActiveJob)
-      normalize_for_async_serialization!(kwargs, :blocks)
-      normalize_for_async_serialization!(kwargs, :attachments)
+    def normalize_async_serializable_keys!(kwargs)
+      ASYNC_SERIALIZABLE_KEYS.each { |key| normalize_for_async_serialization!(kwargs, key) }
     end
 
     def normalize_for_async_serialization!(kwargs, key)

data/lib/slack_sender/strategy.rb

@@ -86,10 +86,17 @@ module SlackSender
 
           raise ArgumentError, "No channel(s) specified and no default channel configured" unless channel || channels
 
+          # Resolve this action's per-class sandbox override (configure(:slack_sender)) at the origin,
+          # where the action class is known, and thread it down. :inherit when unset leaves global
+          # config in charge — unchanged for every action that doesn't opt in.
+          found, override = SlackSender::Configuration.class_override(self.class, :sandbox_mode)
+          sandbox_mode = found ? override : :inherit
+          target = SlackSender.profile(profile)
+
           if channels
-            SlackSender.profile(profile).public_send(method, channels:, **merged)
+            target.public_send(method, channels:, sandbox_mode:, **merged)
           else
-            SlackSender.profile(profile).public_send(method, channel:, **merged)
+            target.public_send(method, channel:, sandbox_mode:, **merged)
           end
         end
       end

data/lib/slack_sender/util.rb

@@ -13,6 +13,17 @@ module SlackSender
       NON_RETRYABLE_CHANNEL_ERRORS.any? { |klass| exception.is_a?(klass) }
     end
 
+    # True if the exception is a permanent InvalidArgumentsError — either raised directly, or
+    # wrapped by axn in an Axn::ContractViolation::PreprocessingError (which happens when it is
+    # raised from an `expects ... preprocess:` lambda, e.g. an unknown channel). The async worker
+    # re-raises result.exception, so the wrapped form is what the retry hooks see. Such jobs can
+    # never succeed on retry, so both async backends use this to discard them.
+    def self.invalid_arguments_error?(exception)
+      return true if exception.is_a?(SlackSender::InvalidArgumentsError)
+
+      exception.is_a?(Axn::ContractViolation::PreprocessingError) && exception.cause.is_a?(SlackSender::InvalidArgumentsError)
+    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
@@ -26,7 +37,8 @@ module SlackSender
         kwargs[:blocks].blank? &&
         kwargs[:attachments].blank? &&
         kwargs[:file].blank? &&
-        kwargs[:files].blank?
+        kwargs[:files].blank? &&
+        kwargs[:slack_options].blank?
     end
 
     # Determines retry behavior for Slack API exceptions

data/lib/slack_sender/version.rb

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