slack_sender 0.1.0 → 0.1.1

data/lib/slack_sender.rb

@@ -26,23 +26,7 @@ module SlackSender
   # 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)
@@ -67,5 +51,19 @@ module SlackSender
   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"
+
 # Rails integration (if in Rails context)
 require_relative "slack_sender/rails/engine" if defined?(Rails) && Rails.const_defined?(:Engine)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: slack_sender
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Kali Donovan
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-02-19 00:00:00.000000000 Z
+date: 2026-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: axn
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.1
+        version: 0.1.0.pre.alpha.5
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.1.0.pre.alpha.4.1
+        version: 0.1.0.pre.alpha.5
     - - "<"
       - !ruby/object:Gem::Version
         version: 0.2.0
@@ -36,14 +36,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 description: Slack messaging with background dispatch with automatic rate-limit retries.
 email:
 - kali@teamshares.com
@@ -51,15 +57,8 @@ 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

data/.husky/pre-commit

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

data/.lintstagedrc

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

data/Rakefile

@@ -1,15 +0,0 @@
-# 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

@@ -1,168 +0,0 @@
-# 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

@@ -1,252 +0,0 @@
-# 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.