slack_sender 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 320590e57f220cb0e85688e3987c1fdee1b9f1bc014a9907099ec277568a06f6
+  data.tar.gz: b478553cd49da506001a5223673cc9a2ca0d2adf79cba6d6fc4e5a317f33db89
+SHA512:
+  metadata.gz: a5153bb970a492024ac5ddc16f1fab9e6debe046636f87330c4ab19ebade650702123e2edc7a7d3473e9e31a84f51ac6e0830cae0be2add5c18542996ae89b8d
+  data.tar.gz: 5c5737bfa9581c9766d0eb66b4d20367501006f2b40acff2f41aafabc3455be2db2c9174b1fa3feff31f5d70db032124b4928a7c2d1fb2140975f792cd8a614c

data/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

data/.lintstagedrc

@@ -0,0 +1 @@
+{"*.rb":["bundle exec rubocop -A -c .rubocop.yml --force-exclusion"]}

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [Unreleased]
+
+* N/A
+
+## [0.1.0] - 2026-02-19
+
+- Initial release

data/README.md

@@ -0,0 +1,97 @@
+# SlackSender
+
+**Reliable Slack messaging for Ruby — with automatic retries, rate-limit handling, and sandbox safety.**
+
+SlackSender handles the plumbing so you can focus on your application: background dispatch, retry logic, multi-workspace support, and development environment redirects are all built in.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'slack_sender'
+```
+
+Then run:
+
+```bash
+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)
+- For async delivery: Sidekiq or ActiveJob (auto-detected)
+
+## Quick Start - Minimal
+
+```ruby
+SlackSender.register(token: ENV['SLACK_BOT_TOKEN'])
+```
+
+```ruby
+SlackSender.call!(channel: "some_channel_name", text: "Hi there")
+```
+
+## Quick Start - Realistic
+
+### 1. Register a Profile
+
+```ruby
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  channels: {
+    ops_alerts: 'C1111111111',
+    deployments: 'C2222222222',
+  },
+  sandbox: {
+    channel: { replace_with: 'C_DEV_CHANNEL' }  # Redirects in non-production
+  }
+)
+```
+
+### 2. Send Messages
+
+```ruby
+# Async (recommended) — background job with automatic retries
+SlackSender.call(channel: :ops_alerts, text: ":rotating_light: High error rate detected")
+
+# Sync — when you need the thread timestamp
+thread_ts = SlackSender.call!(channel: :deployments, text: ":rocket: Deploy started")
+SlackSender.call(channel: :deployments, text: "Deploy complete!", thread_ts:)
+```
+
+That's it. SlackSender handles rate limits, retries, and sandbox redirection (if configured, all messages sent from non-production environments will be delivered to your `replace_with` channel) automatically.
+
+## Documentation
+
+| 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 |
+
+## 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
+- **File uploads** — sync and async, with automatic size handling
+- **Multiple profiles** — manage multiple Slack workspaces
+- **Axn integration** — `use :slack` strategy and dedicated `Notifier` base class
+
+## Development
+
+```bash
+bin/setup         # Install dependencies
+bundle exec rspec # Run tests
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/teamshares/slack_sender.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+# Require default to pass before release. This relies on the default gem release task
+# (from bundler/gem_tasks) depending on "build"; default runs before build, so before push.
+Rake::Task["build"].enhance([:default])

data/docs/axn_integration.md

@@ -0,0 +1,168 @@
+# Axn Integration
+
+[← Back to README](../README.md)
+
+SlackSender provides deep integration with [Axn](https://teamshares.github.io/axn/) for building Slack-enabled actions and dedicated notifier classes.
+
+## Slack Strategy for Axn Actions
+
+Add Slack messaging capabilities to any Axn action using the `:slack` strategy:
+
+```ruby
+class Deployments::Finish
+  include Axn
+  use :slack, channel: :deployments  # Default channel for all slack() calls
+
+  expects :deployment, type: Deployment
+
+  on_success { slack ":rocket: Deploy finished for `#{deployment.service}`" }
+  on_failure { slack ":x: Deploy failed for `#{deployment.service}`", channel: :ops_alerts }
+
+  def call
+    # slack() is async (background job) - recommended for fire-and-forget
+    slack "Finalizing deploy for `#{deployment.service}`..."
+
+    # slack!() is sync - use when you need the thread_ts
+    thread_ts = slack! "Starting rollout..."
+    # ... rollout / status checks / persistence ...
+    slack "Rollout complete!", thread_ts: thread_ts
+  end
+end
+```
+
+### Strategy Configuration
+
+```ruby
+use :slack, channel: :general             # Default channel for all slack() calls
+use :slack, channel: :general, profile: :support  # Use a specific SlackSender profile
+use :slack, channels: [:alerts, :ops]     # Default to multiple channels (async only)
+use :slack                                # No default channel (must pass channel: each time)
+```
+
+### The `slack(...)` and `slack!(...)` Methods
+
+The strategy adds two instance methods for sending Slack messages:
+
+| Method | Delivery | Return Value | Use When |
+|--------|----------|--------------|----------|
+| `slack(...)` | Async (background job) | `true` or `false` | Default; enables auto-retry for rate limits |
+| `slack!(...)` | Sync (immediate) | Thread timestamp or `false` | You need the `thread_ts` return value |
+
+```ruby
+# Async delivery (recommended) - uses Sidekiq or ActiveJob
+slack "Hello world"
+slack "Hello", channel: :other_channel
+
+# Sync delivery - immediate execution, returns thread_ts
+thread_ts = slack! "Starting deployment..."
+slack! "Deployment finished", thread_ts: thread_ts
+
+# Full kwargs work with both methods
+slack text: "Hello", channel: :ops_alerts, icon_emoji: "robot"
+slack! channel: :ops_alerts, blocks: [{ type: "section", text: { type: "mrkdwn", text: "*Bold*" } }]
+```
+
+**Note:** `slack(...)` requires an async backend to be configured (Sidekiq or ActiveJob). If no async backend is available, it raises `SlackSender::Error` with instructions to either use `slack!(...)` or configure an async backend.
+
+---
+
+## SlackSender::Notifier Base Class
+
+For actions whose sole purpose is sending Slack notifications, inherit from `SlackSender::Notifier`. These are built on top of Axn (that's where the `expects` DSL comes from below), so you'll want to [familiarize yourself with that library](https://teamshares.github.io/axn/) before continuing:
+
+```ruby
+# app/slack_notifiers/deployments/finished.rb
+module SlackNotifiers
+  module Deployments
+    class Finished < SlackSender::Notifier
+      expects :deployment_id, type: Integer
+
+      # Post to the deployments channel for production releases
+      notify do
+        channel :deployments
+        only_if { production_release? }
+        text { ":rocket: *Deploy finished* for `#{deployment.service}` (#{deployment.environment})" }
+      end
+
+      # Optionally also post in the incident channel if this deploy is related to an incident
+      notify do
+        channel :incident_channel_id
+        only_if { incident_channel_id.present? }
+        text { ":rocket: *Deploy finished* for `#{deployment.service}` (#{deployment.environment})" }
+      end
+
+      private
+
+      def production_release? = deployment.environment.to_s == "production"
+
+      # Dynamic channel ID string (e.g., "C123...") sourced from your domain model
+      def incident_channel_id = deployment.incident_slack_channel_id
+
+      def deployment = @deployment ||= Deployment.find(deployment_id)
+    end
+  end
+end
+
+# Call it like any Axn
+SlackNotifiers::Deployments::Finished.call(deployment_id: 123)
+```
+
+---
+
+## The `notify do ... end` DSL
+
+The `notify` block groups all Slack message configuration together, keeping it visually separated from Axn declarations like `expects`:
+
+```ruby
+notify do
+  channel :notifications           # Single channel
+  text { "Hello!" }                # Dynamic text (block)
+end
+
+notify do
+  channels :ops_alerts, :ic        # Multiple channels (files uploaded once, shared to all)
+  only_if { priority == :high }    # Conditional send
+  text :message_text               # Text from method
+  attachments :build_attachments   # Attachments from method
+end
+```
+
+### DSL Options
+
+| Option | Description |
+|--------|-------------|
+| `channel :sym` | Single channel (symbol resolved via profile, or method if defined) |
+| `channels :a, :b` | Multiple channels |
+| `text { ... }` | Text content (block evaluated in instance context) |
+| `text :method` | Text from method |
+| `text "static"` | Static text |
+| `blocks { ... }` | Slack blocks |
+| `attachments { ... }` | Slack attachments |
+| `icon_emoji :emoji` | Custom emoji |
+| `thread_ts :method` | Thread timestamp |
+| `files { ... }` | File attachments |
+| `only_if { ... }` | Condition (block) — only send if truthy |
+| `only_if :method` | Condition (method) — only send if truthy |
+| `profile :name` | Use a specific SlackSender profile |
+
+### Value Resolution
+
+For each field, values are resolved in this order:
+1. **Block**: `text { "dynamic #{value}" }` — evaluated in instance context
+2. **Symbol**: `text :my_method` — calls method if it exists, otherwise treated as literal
+3. **Literal**: `text "static"` — used as-is
+
+### Required Fields
+
+- At least one `channel` or `channels`
+- At least one payload field (`text`, `blocks`, `attachments`, or `files`)
+
+---
+
+## Notifier Features
+
+Since `SlackSender::Notifier` inherits from Axn, you get:
+- `expects` / `exposes` for input/output contracts
+- Hooks (`before`, `after`, `on_success`, `on_failure`)
+- Automatic logging and error handling
+- Async execution with `call_async`

data/docs/configuration.md

@@ -0,0 +1,252 @@
+# Configuration
+
+[← Back to README](../README.md)
+
+This guide covers global configuration, profile registration, and sandbox mode settings.
+
+## Global Configuration
+
+Configure SlackSender behavior via `SlackSender.configure` (e.g. in a Rails initializer):
+
+```ruby
+SlackSender.configure do |config|
+  # Set async backend (auto-detects Sidekiq or ActiveJob if available)
+  config.async_backend = :sidekiq  # or :active_job
+
+  # Set sandbox mode (affects sandbox channel/user_group redirects)
+  # Defaults to true in non-production, false in production
+  config.sandbox_mode = !Rails.env.production?
+
+  # Set default sandbox behavior when sandbox_mode is true but profile
+  # doesn't specify a sandbox.mode or sandbox.channel.replace_with
+  # Options: :noop (default), :redirect, :passthrough
+  config.sandbox_default_behavior = :noop
+
+  # Enable/disable SlackSender globally (default: true)
+  config.enabled = ENV["DISABLE_SLACK"] != "1"
+
+  # Silence archived channel exceptions (default: false)
+  config.silence_archived_channel_exceptions = false
+
+  # Control autoloading namespace for app/slack_notifiers (default: true)
+  # When true:  app/slack_notifiers/foo.rb -> SlackNotifiers::Foo
+  # When false: app/slack_notifiers/foo.rb -> Foo (standard Rails behavior)
+  config.use_slack_notifiers_namespace = true
+end
+```
+
+### Global Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `async_backend` | `Symbol` or `nil` | Auto-detected | Backend for async delivery. Supported: `:sidekiq`, `:active_job` |
+| `sandbox_mode` | `Boolean` or `nil` | `!Rails.env.production?` if Rails available, else `true` | Whether app is in sandbox mode |
+| `sandbox_default_behavior` | `Symbol` | `:noop` | Default behavior when in sandbox mode if profile doesn't specify. Options: `:noop`, `:redirect`, `:passthrough` |
+| `enabled` | `Boolean` | `true` | Global enable/disable flag. When `false`, `call` and `call!` return `false` without sending |
+| `silence_archived_channel_exceptions` | `Boolean` | `false` | If `true`, silently ignores `IsArchived` errors instead of reporting them |
+| `max_async_file_upload_size` | `Integer` or `nil` | `26_214_400` (25 MB) | Max total file size for async uploads. Set to `nil` to disable |
+| `use_slack_notifiers_namespace` | `Boolean` | `true` | When `true`, files in `app/slack_notifiers` are autoloaded under the `SlackNotifiers` namespace |
+
+---
+
+## Profile Registration
+
+A **profile** represents a Slack workspace configuration. Register profiles with `SlackSender.register`:
+
+```ruby
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  default_channel: :ops_alerts,
+  channels: {
+    ops_alerts: 'C1111111111',
+    deployments: 'C2222222222',
+    reports: 'C3333333333',
+  },
+  user_groups: {
+    engineers: 'S1234567890',
+  },
+  sandbox: {
+    channel: {
+      replace_with: 'C1234567890',
+      message_prefix: ':construction: _This message would have been sent to %s in production_'
+    },
+    user_group: {
+      replace_with: 'S_DEV_GROUP'
+    }
+  }
+)
+```
+
+### Profile Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `token` | `String` or callable | Required | Slack Bot User OAuth Token. Can be a proc/lambda for dynamic fetching |
+| `default_channel` | `Symbol`, `String`, or `nil` | `nil` | Default channel when none is specified in `call`/`call!` |
+| `channels` | `Hash` | `{}` | Hash mapping symbol keys to channel IDs (e.g., `{ alerts: 'C123' }`) |
+| `user_groups` | `Hash` | `{}` | Hash mapping symbol keys to user group IDs (e.g., `{ engineers: 'S123' }`) |
+| `slack_client_config` | `Hash` | `{}` | Additional options passed to `Slack::Web::Client` constructor |
+| `sandbox` | `Hash` | `{}` | Sandbox mode configuration (see below) |
+
+### Dynamic Token
+
+Use a callable for the token to fetch it dynamically:
+
+```ruby
+SlackSender.register(
+  token: -> { SecretsManager.get_slack_token },
+  channels: { ops_alerts: 'C123' }
+)
+```
+
+The token is memoized after first access.
+
+### Multiple Profiles
+
+Register multiple profiles for different Slack workspaces:
+
+```ruby
+# Internal engineering workspace (default profile)
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  channels: { ops_alerts: 'C123', deployments: 'C234' }
+)
+
+# Customer support workspace
+SlackSender.register(:support,
+  token: ENV['SUPPORT_SLACK_TOKEN'],
+  channels: { support_tickets: 'C456' }
+)
+
+# Use specific profile
+SlackSender.profile(:support).call(
+  channel: :support_tickets,
+  text: "New high-priority ticket received"
+)
+
+# Or use bracket notation
+SlackSender[:support].call(channel: :support_tickets, text: "...")
+
+# Or override default profile with profile parameter
+SlackSender.call(profile: :support, channel: :support_tickets, text: "...")
+```
+
+---
+
+## Sandbox Mode
+
+When `config.sandbox_mode?` is true (default in non-production), SlackSender applies sandbox behavior based on the profile's `sandbox` configuration.
+
+### Sandbox Options Reference
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `behavior` | `Symbol` or `nil` | Inferred | Explicit sandbox behavior: `:redirect`, `:noop`, or `:passthrough` |
+| `channel.replace_with` | `String` or `nil` | `nil` | Channel ID to redirect all messages when behavior is `:redirect` |
+| `channel.message_prefix` | `String` or `nil` | See below | Custom prefix for sandbox channel redirects. Use `%s` placeholder for channel name |
+| `user_group.replace_with` | `String` or `nil` | `nil` | User group ID to replace all group mentions when in sandbox mode |
+
+Default message prefix: `:construction: _This message would have been sent to %s in production_`
+
+### Behavior Resolution
+
+When `config.sandbox_mode?` is true, the effective sandbox behavior is determined by:
+
+1. **Explicit `sandbox.behavior`** — if set, use it
+2. **Inferred from `sandbox.channel.replace_with`** — if present, behavior is `:redirect`
+3. **Global default** — `config.sandbox_default_behavior` (defaults to `:noop`)
+
+| Behavior | Description |
+|----------|-------------|
+| `:redirect` | Redirect messages to `sandbox.channel.replace_with` (required). Adds message prefix. |
+| `:noop` | Don't send anything. Logs what would have been sent. Returns `false`. |
+| `:passthrough` | Send to real channel (explicit opt-out of sandbox safety). |
+
+### Mode: Redirect
+
+Redirect all messages to a sandbox channel:
+
+```ruby
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  channels: { production_alerts: 'C9999999999' },
+  sandbox: {
+    behavior: :redirect,  # Optional - inferred when channel.replace_with is set
+    channel: {
+      replace_with: 'C1234567890',
+      message_prefix: ':test_tube: Sandbox redirect from %s'
+    }
+  }
+)
+
+# In sandbox mode, this goes to C1234567890 with a prefix
+SlackSender.call(channel: :production_alerts, text: "Critical alert")
+```
+
+### Mode: Noop (Default)
+
+Don't send anything, just log what would have been sent:
+
+```ruby
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  channels: { alerts: 'C999' },
+  sandbox: { behavior: :noop }
+)
+
+# In sandbox mode, this logs the message but doesn't send to Slack
+SlackSender.call(channel: :alerts, text: "Test message")
+# => Logs: "[SANDBOX NOOP] Profile: default | Channel: <#C999> | Text: Test message"
+# => Returns false
+```
+
+### Mode: Passthrough
+
+Explicitly opt out of sandbox safety and send to real channels:
+
+```ruby
+SlackSender.register(
+  token: ENV['SLACK_BOT_TOKEN'],
+  channels: { alerts: 'C999' },
+  sandbox: { behavior: :passthrough }
+)
+
+# In sandbox mode, this still sends to the real channel
+SlackSender.call(channel: :alerts, text: "This goes to production!")
+```
+
+---
+
+## Required Slack Scopes
+
+Your Slack app needs specific OAuth scopes depending on which features you use. Add these under **OAuth & Permissions** → **Bot Token Scopes** in your [Slack app settings](https://api.slack.com/apps).
+
+**Minimum scopes for basic messaging:**
+- `chat:write`
+
+**Recommended scopes for full functionality:**
+
+| Scope | Required For | Notes |
+|-------|--------------|-------|
+| `chat:write` | All messaging | Required for `chat.postMessage` |
+| `chat:write.public` | Public channels | Post to public channels your bot hasn't been added to |
+| `files:write` | File uploads | Required for `files.getUploadURLExternal` and `files.completeUploadExternal` |
+| `files:read` | File metadata | Required if you need thread timestamps from file uploads |
+
+After adding scopes, reinstall the app to your workspace to apply the changes.
+
+---
+
+## Exception Notifications
+
+Exception notifications to error tracking services (e.g., Honeybadger) are handled via Axn's `on_exception` handler:
+
+```ruby
+Axn.configure do |c|
+  c.on_exception = proc do |e, action:, context:|
+    Honeybadger.notify(e, context: { axn_context: context })
+  end
+end
+```
+
+See [Axn configuration documentation](https://teamshares.github.io/axn/reference/configuration#on_exception) for details.