smswire 0.0.1.pre → 0.1.0

data/docs/guides/migrating-from-noticed-twilio.md

@@ -0,0 +1,105 @@
+# Migrating from Noticed's Twilio delivery method
+
+Noticed is a good fit for notification inboxes and fan-out across channels.
+Its `twilio_messaging` delivery method posts a message string to Twilio and
+leaves templates, consent, retries, and delivery tracking to the app.
+Smswire adds a `deliver_by :smswire` delivery method, so you keep Noticed
+and move only the SMS channel.
+
+## Before
+
+```ruby
+class OrderShippedNotifier < Noticed::Event
+  deliver_by :twilio_messaging do |config|
+    config.json = -> {
+      {
+        From: Rails.application.credentials.dig(:twilio, :phone_number),
+        To: recipient.phone_number,
+        Body: "Order #{params[:order].number} has shipped"
+      }
+    }
+    config.error_handler = ->(response) { ... }
+  end
+end
+```
+
+## After
+
+```ruby
+class OrderShippedNotifier < Noticed::Event
+  deliver_by :smswire do |config|
+    config.messenger = "OrderMessenger"
+    config.action = :shipped
+  end
+end
+```
+
+```ruby
+class OrderMessenger < ApplicationMessenger
+  # Called with the Noticed recipient. params holds the event params plus
+  # notification, record, and recipient.
+  def shipped(user)
+    @order = params[:order]
+    text to: user
+  end
+end
+```
+
+```erb
+<%# app/views/order_messenger/shipped.text.erb %>
+Order <%= @order.number %> has shipped
+```
+
+Install Smswire first with the [getting started](getting-started.md) steps.
+The delivery method loads automatically when Noticed is in the bundle.
+
+## Options
+
+| Option | Default | Use |
+|---|---|---|
+| `messenger` | required | class or class name |
+| `action` | required | messenger action |
+| `args` | `[recipient]` | positional arguments for the action |
+| `kwargs` | `{}` | keyword arguments |
+| `params` | the event params | the messenger's `params`, merged with `notification`, `record`, `recipient` |
+| `sms_queue`, `sms_priority` | Smswire's defaults | queue and priority for `Smswire::DeliveryJob` |
+
+Noticed's own options, such as `if`, `unless`, `wait`, and `queue`, still
+apply to the Noticed job. A `wait` delays the message once; Smswire does not
+add a second delay.
+
+## Credentials
+
+Noticed reads `Rails.application.credentials.twilio`, and so does Smswire.
+The `phone_number` key becomes a sender:
+
+```ruby
+config.senders = {transactional: {number: Rails.application.credentials.dig(:twilio, :phone_number)}}
+```
+
+## Error handling
+
+`config.error_handler` received Twilio's 4xx response. With Smswire:
+
+- permanent errors become a `:failed` delivery with a reason, such as
+  `:invalid_number` or `:opted_out`;
+- a 21610 opt-out also records the opt-out, so later sends are refused;
+- 429 and 5xx errors are retried by `Smswire::DeliveryJob`.
+
+Use an observer for alerting; see the
+[twilio-ruby guide](migrating-from-twilio-ruby.md#3-map-your-error-handling).
+
+## Joining notifications and deliveries
+
+Each `Smswire::Delivery` stores `noticed_notification_id` and
+`noticed_event_id` in `metadata`, and `recipient` points at the Noticed
+recipient when it is an Active Record model.
+
+## What you gain
+
+- Templates, previews, and test helpers for the SMS body.
+- Delivery status from Twilio callbacks on every send.
+- STOP / START / HELP handling and consent checks before sending.
+- Quiet hours and rate limits per category.
+- Deduplication and retries.
+- The same code works with Telnyx or Vonage by changing the provider.

data/docs/guides/migrating-from-twilio-ruby.md

@@ -0,0 +1,146 @@
+# Migrating from direct twilio-ruby calls
+
+Many apps send SMS by calling the Twilio SDK from models, jobs, or service
+objects. This guide moves that code onto Smswire one message at a time.
+Both can run side by side during the move.
+
+## What changes
+
+| Before | After |
+|---|---|
+| `client.messages.create(from:, to:, body:)` | a messenger action plus `deliver_later` |
+| bodies built in Ruby strings | `.text.erb` templates with I18n and URL helpers |
+| your own job and retry logic | `Smswire::DeliveryJob` with transient and permanent errors separated |
+| `rescue Twilio::REST::RestError` | a `Smswire::Result` with a status and a reason |
+| your own status callback controller | the engine's signed `/smswire/status/twilio` endpoint |
+| stubbing the Twilio client in tests | `Smswire::TestHelper` and the `:test` provider |
+| `twilio-ruby` in the Gemfile | no provider SDK |
+
+Smswire calls Twilio's REST API directly. You can remove `twilio-ruby` once
+nothing else uses it, such as Voice or Verify.
+
+## 1. Install and keep your credentials
+
+Run the [getting started](getting-started.md) install steps. Smswire reads
+`Rails.application.credentials.twilio[:account_sid]` and `[:auth_token]`, the
+same keys most apps already use. Move the sending number into a sender:
+
+```ruby
+config.senders = {
+  transactional: {number: Rails.application.credentials.dig(:twilio, :phone_number)},
+  # A Messaging Service maps to messaging_service:
+  # marketing: {messaging_service: "MG...", consent_scope: "marketing"}
+}
+```
+
+## 2. Replace one send
+
+Before:
+
+```ruby
+class ShipmentNotifier
+  def call(order)
+    client = Twilio::REST::Client.new(sid, token)
+    client.messages.create(
+      from: ENV["TWILIO_NUMBER"],
+      to: order.customer.phone,
+      body: "Order #{order.number} has shipped",
+      status_callback: twilio_status_url(order_id: order.id)
+    )
+  rescue Twilio::REST::RestError => error
+    Rails.logger.error(error.message)
+  end
+end
+```
+
+After:
+
+```ruby
+class OrderMessenger < ApplicationMessenger
+  def shipped(order)
+    @order = order
+    text to: order.customer.phone
+  end
+end
+
+OrderMessenger.shipped(order).deliver_later
+```
+
+```erb
+<%# app/views/order_messenger/shipped.text.erb %>
+Order <%= @order.number %> has shipped
+```
+
+`text to:` takes a string here. Pass the customer instead if it has a
+`phone_number` method, which also links the delivery row to the customer.
+
+## 3. Map your error handling
+
+Smswire turns Twilio errors into outcomes:
+
+| Twilio | Smswire |
+|---|---|
+| 21211, 21214, 21217, 21614 invalid number | `:failed`, `error.reason == :invalid_number` |
+| 21610 recipient replied STOP | `:failed`, reason `:opted_out`, and the number is opted out |
+| 21408, 21606, 21612 cannot route | `:failed`, reason `:unroutable` |
+| 401, 403, 20003 | `:failed`, reason `:authentication` |
+| 429 | retried after `Retry-After` |
+| 5xx, timeouts | retried with backoff, up to `retry_attempts` |
+| other 4xx | `:failed`, reason `:rejected` |
+
+Code that rescued `RestError` to log or alert becomes an observer:
+
+```ruby
+class SmsAlerts
+  def self.delivered_sms(result)
+    Sentry.capture_message("SMS failed: #{result.error.message}") if result.failed?
+  end
+end
+Smswire.register_observer(SmsAlerts)
+```
+
+## 4. Retire your status controller
+
+If you had a controller for Twilio status callbacks, set
+`config.callbacks_url` and delete it. Every message then carries a
+`StatusCallback` URL with its delivery id, the engine checks the
+`X-Twilio-Signature`, and `Smswire::Delivery#status` only moves forward. Use
+`sms_status_updated(delivery, update)` on an observer for anything you did
+in that controller.
+
+Behind a load balancer that terminates TLS, the signature still verifies
+because Smswire rebuilds the URL from `callbacks_url`.
+
+## 5. Point incoming messages at the engine
+
+Set the number's or Messaging Service's incoming webhook to
+`https://app.example.com/smswire/inbound/twilio`. If you use Twilio Advanced
+Opt-Out, Smswire records the opt-out and skips its own reply, since Twilio
+already sent one.
+
+## 6. Update tests
+
+Before:
+
+```ruby
+client = instance_double(Twilio::REST::Client)
+expect(client).to receive_message_chain(:messages, :create)
+```
+
+After:
+
+```ruby
+assert_sms_delivered(to: "+15555550100", messenger: OrderMessenger) { order.ship! }
+```
+
+The test environment uses the `:test` provider automatically, so no request
+leaves the process.
+
+## Behaviour to expect
+
+- **Duplicates.** The same messenger, action, recipient, and body inside 10
+  minutes returns `:duplicate`. Pass `idempotency_key:` to `text`, or set
+  `config.dedupe_window = nil`.
+- **Opt-outs.** Opted-out numbers are refused for every category.
+- **Marketing.** Messages with `category: :marketing` need an opt-in and wait
+  for quiet hours to end.

data/docs/guides/writing-a-provider.md

@@ -0,0 +1,126 @@
+# Writing a provider adapter
+
+An adapter connects Smswire to one SMS API. It sends messages, classifies
+errors, and optionally verifies and parses webhooks. Every adapter must pass
+`Smswire::ProviderContract`, a Minitest suite shipped in the gem.
+
+## Generate the skeleton
+
+```
+bin/rails generate smswire:provider Acme
+```
+
+This writes:
+
+- `app/sms_providers/acme_provider.rb`, a working adapter for a fictional API;
+- `test/sms_providers/acme_provider_test.rb`, which runs the contract against it;
+- a `Smswire::Providers.register(:acme, "AcmeProvider")` line in the initializer.
+
+The generated pair passes the contract as generated. Change the API calls,
+error codes, and stubs together, running the test as you go.
+
+## The adapter contract
+
+```ruby
+class AcmeProvider < Smswire::Providers::Base
+  def deliver(message)          # => Smswire::Receipt, or raises
+  def capabilities              # => Set of :mms, :status_callbacks, :inbound, :messaging_services, :scheduling
+  def verify_credentials!       # => true, or raises; nil if unsupported
+
+  # With :status_callbacks or :inbound:
+  def verify_signature!(request, url:)   # raises Smswire::SignatureError
+  def parse_status_callback(request)     # => Smswire::StatusUpdate, or nil if not a status event
+  def parse_inbound(request)             # => Smswire::Inbound, or nil if not an inbound message
+  def inbound_response                   # => [body, content_type], or nil for 204
+end
+```
+
+`options` holds `Smswire.config.providers[:acme]` with symbol keys, and
+`name` is the registered name.
+
+### Sending
+
+Read `message.to` (E.164), `from`, `messaging_service`, `body`,
+`media_urls`, `validity_period`, and `status_callback_url`. Use
+`Smswire::HTTP.post_form` or `post_json`; both turn network failures into
+`TransientError` and never log bodies. Return `receipt(provider_id:, status:,
+segments:, price_amount:, price_currency:, raw:)` with a status from the
+normalized vocabulary: `:queued`, `:accepted`, `:sent`, `:delivered`,
+`:undelivered`, `:failed`, `:read`.
+
+### Errors
+
+| Situation | Raise |
+|---|---|
+| network failure, timeout, 5xx | `Smswire::TransientError` (retried) |
+| rate limit | `Smswire::ThrottledError.new(..., retry_after: seconds)` |
+| retrying cannot help | `Smswire::PermanentError.new(..., reason:)` |
+| missing credentials or settings | `Smswire::ConfigurationError` |
+
+Pass `provider: name, provider_code:, http_status:, raw:` to error
+constructors. Reasons are `:invalid_number`, `:opted_out`, `:unroutable`,
+`:authentication`, and `:rejected`. Use `:opted_out` only for an error that
+specifically means the recipient opted out, because Smswire records an
+opt-out when it sees one. If the provider has no such error, define
+`contract_reports_opt_outs?` as `false` in the test.
+
+### Webhooks
+
+Verify before parsing. Use constant-time comparison, such as
+`ActiveSupport::SecurityUtils.secure_compare`, and reject stale timestamps
+when the provider signs them. `url:` is the public URL the provider posted
+to, rebuilt from `config.callbacks_url` when that is set.
+
+Return `nil` from `parse_status_callback` for events that are not status
+updates, and from `parse_inbound` for events that are not messages. The
+engine tries both, so a provider that posts every event to one URL works.
+
+## Contract hooks
+
+```ruby
+class AcmeProviderTest < ActiveSupport::TestCase
+  include Smswire::TestHelper
+  include Smswire::ProviderContract
+
+  def contract_provider_name = :acme
+  def contract_provider_options = {api_key: "test-key"}
+
+  # Stub the API for :success, :invalid_number, :opted_out, :authentication,
+  # :throttled, :server_error, and :timeout. Return the WebMock stub.
+  def stub_contract_send(outcome, message) = ...
+
+  # With :status_callbacks; status is :delivered or :undelivered.
+  def contract_status_request(provider_id:, status:, signed: true) = ...
+
+  # With :inbound.
+  def contract_inbound_request(from:, to:, body:, signed: true) = ...
+end
+```
+
+Build requests with `contract_request(url, params:)` for form posts or
+`contract_request(url, body: json)` for JSON, plus `headers:`. Override
+`contract_message` to run the contract with one of your own messengers.
+
+The suite checks:
+
+- the receipt, its provider id, and its status;
+- a full pipeline send that records a delivery row;
+- each permanent outcome's reason, and that throttling, server errors, and
+  timeouts are retryable;
+- for declared capabilities, that signed requests parse and verify and
+  unsigned ones raise `SignatureError`, and that status and inbound events
+  are not mistaken for each other.
+
+The bundled Twilio, Telnyx, and Vonage adapters pass the same suite; their
+tests in `test/provider_contract_test.rb` in the Smswire repository are
+worked examples.
+
+## Sharing an adapter
+
+Publish it as a gem that depends on `smswire` and registers itself:
+
+```ruby
+# lib/smswire-acme.rb
+require "smswire"
+Smswire::Providers.register(:acme, "Smswire::Acme::Provider")
+```

data/lib/generators/smswire/install/install_generator.rb

@@ -0,0 +1,44 @@
+require "rails/generators"
+require "active_record"
+
+module Smswire
+  module Generators
+    # bin/rails generate smswire:install
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Copy Smswire migrations, add an initializer and ApplicationMessenger, and mount the engine."
+
+      def copy_migrations
+        destination = File.join(destination_root, "db/migrate")
+        FileUtils.mkdir_p(destination)
+        copied = ActiveRecord::Migration.copy(destination, {smswire: Smswire::Engine.root.join("db/migrate").to_s})
+        copied.each { |migration| say_status :create, "db/migrate/#{File.basename(migration.filename)}" }
+        say_status :identical, "db/migrate (Smswire migrations already installed)" if copied.empty?
+      end
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/smswire.rb"
+      end
+
+      def create_application_messenger
+        template "application_messenger.rb", "app/messengers/application_messenger.rb"
+      end
+
+      def mount_engine
+        route %(mount Smswire::Engine => "/smswire")
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          Smswire is installed. Next:
+            1. bin/rails db:migrate
+            2. Set provider credentials, senders, and callbacks_url in config/initializers/smswire.rb
+            3. Point your provider's status and inbound webhooks at /smswire/status/<provider> and /smswire/inbound/<provider>
+            4. bin/rails generate smswire:messenger Welcome greeting
+        TEXT
+      end
+    end
+  end
+end

data/lib/generators/smswire/install/templates/application_messenger.rb.tt

@@ -0,0 +1,3 @@
+class ApplicationMessenger < Smswire::Base
+  default from: :transactional
+end

data/lib/generators/smswire/install/templates/initializer.rb.tt

@@ -0,0 +1,35 @@
+Smswire.configure do |config|
+  # Development uses the :log provider and tests use :test unless set here.
+  # config.default_provider = :twilio
+
+  # Credentials default to Rails.application.credentials.twilio.
+  # config.providers = {
+  #   twilio: {account_sid: ENV["TWILIO_ACCOUNT_SID"], auth_token: ENV["TWILIO_AUTH_TOKEN"]}
+  # }
+
+  # Named senders. Messengers pick one with `default from: :transactional`.
+  config.senders = {
+    transactional: {number: ENV.fetch("SMS_FROM_NUMBER", "+15555550100")}
+    # marketing: {messaging_service: "MG...", provider: :twilio, consent_scope: "marketing"}
+  }
+
+  # Public URL where Smswire::Engine is mounted. Enables delivery status callbacks.
+  # config.callbacks_url = "https://example.com/smswire"
+
+  # Used in STOP / START / HELP auto-replies. HELP replies should name a
+  # support contact (phone, email, or URL).
+  # config.program_name = "<%= Rails.application.class.module_parent_name.titleize rescue "My App" %>"
+  # config.support_contact = "support@example.com"
+
+  # Verify provider credentials at boot (one read-only API call):
+  # Rails.application.config.after_initialize { Smswire.verify_credentials! } if Rails.env.production?
+
+  # Category rules merge over the defaults (marketing requires opt-in and has quiet hours).
+  # config.categories = {marketing: {rate_limit: {max: 3, per: 1.day}}}
+  # config.default_time_zone = "America/New_York"
+end
+
+# Staging safety: only listed numbers receive messages.
+# if ENV["SMS_ALLOWLIST"]
+#   Smswire.register_interceptor(Smswire::Interceptors::Allowlist.new(numbers: ENV["SMS_ALLOWLIST"].split(",")))
+# end

data/lib/generators/smswire/messenger/messenger_generator.rb

@@ -0,0 +1,51 @@
+require "rails/generators/named_base"
+
+module Smswire
+  module Generators
+    # bin/rails generate smswire:messenger Order shipped delivered
+    class MessengerGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      argument :actions, type: :array, default: [], banner: "action action"
+
+      desc "Create a messenger with text templates, a preview, and a test."
+
+      check_class_collision suffix: "Messenger"
+
+      def create_application_messenger
+        return if File.exist?(File.join(destination_root, "app/messengers/application_messenger.rb"))
+
+        template "../../install/templates/application_messenger.rb", "app/messengers/application_messenger.rb"
+      end
+
+      def create_messenger
+        template "messenger.rb", File.join("app/messengers", class_path, "#{file_name}.rb")
+      end
+
+      def create_templates
+        actions.each do |action|
+          @action = action
+          template "view.text.erb", File.join("app/views", class_path, file_name, "#{action}.text.erb")
+        end
+      end
+
+      def create_preview
+        template "preview.rb", File.join("test/messengers/previews", class_path, "#{file_name}_preview.rb")
+      end
+
+      def create_test
+        template "test.rb", File.join("test/messengers", class_path, "#{file_name}_test.rb")
+      end
+
+      private
+
+      def file_name
+        @_file_name ||= super.sub(/_messenger\z/i, "") + "_messenger"
+      end
+
+      def sample_number
+        "+15555550100"
+      end
+    end
+  end
+end

data/lib/generators/smswire/messenger/templates/messenger.rb.tt

@@ -0,0 +1,14 @@
+<% module_namespacing do -%>
+class <%= class_name.delete_suffix("Messenger") %>Messenger < ApplicationMessenger
+<% actions.each_with_index do |action, index| -%>
+<% if index > 0 -%>
+
+<% end -%>
+  # Template: app/views/<%= file_path %>/<%= action %>.text.erb
+  def <%= action %>(recipient)
+    @greeting = "Hi"
+    text to: recipient
+  end
+<% end -%>
+end
+<% end -%>

data/lib/generators/smswire/messenger/templates/preview.rb.tt

@@ -0,0 +1,13 @@
+# Preview at /smswire/previews/<%= file_path %>
+<% module_namespacing do -%>
+class <%= class_name.delete_suffix("Messenger") %>MessengerPreview < Smswire::Preview
+<% actions.each_with_index do |action, index| -%>
+<% if index > 0 -%>
+
+<% end -%>
+  def <%= action %>
+    <%= class_name.delete_suffix("Messenger") %>Messenger.<%= action %>("<%= sample_number %>")
+  end
+<% end -%>
+end
+<% end -%>

data/lib/generators/smswire/messenger/templates/test.rb.tt

@@ -0,0 +1,18 @@
+require "test_helper"
+
+<% module_namespacing do -%>
+class <%= class_name.delete_suffix("Messenger") %>MessengerTest < ActiveSupport::TestCase
+  include Smswire::TestHelper
+<% actions.each do |action| -%>
+
+  test "<%= action %>" do
+    message = <%= class_name.delete_suffix("Messenger") %>Messenger.<%= action %>("<%= sample_number %>").message
+    assert_match "<%= class_name.delete_suffix("Messenger") %>Messenger#<%= action %>", message.body
+
+    assert_sms_delivered(to: "<%= sample_number %>", action: :<%= action %>) do
+      <%= class_name.delete_suffix("Messenger") %>Messenger.<%= action %>("<%= sample_number %>").deliver_later
+    end
+  end
+<% end -%>
+end
+<% end -%>

data/lib/generators/smswire/messenger/templates/view.text.erb.tt

@@ -0,0 +1 @@
+<%%= @greeting %>, this is <%= class_name.delete_suffix("Messenger") %>Messenger#<%= @action %>.

data/lib/generators/smswire/provider/provider_generator.rb

@@ -0,0 +1,36 @@
+require "rails/generators/named_base"
+
+module Smswire
+  module Generators
+    # bin/rails generate smswire:provider Acme
+    class ProviderGenerator < ::Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Create a Smswire provider adapter skeleton and register it."
+
+      def create_provider
+        template "provider.rb", File.join("app/sms_providers", class_path, "#{file_name}_provider.rb")
+      end
+
+      def create_test
+        template "test.rb", File.join("test/sms_providers", class_path, "#{file_name}_provider_test.rb")
+      end
+
+      def register_provider
+        initializer = File.join(destination_root, "config/initializers/smswire.rb")
+        line = %(\nSmswire::Providers.register(:#{file_name}, "#{provider_class}")\n)
+        if File.exist?(initializer)
+          append_to_file "config/initializers/smswire.rb", line
+        else
+          say "Register the adapter in an initializer:#{line}"
+        end
+      end
+
+      private
+
+      def provider_class
+        "#{class_name}Provider"
+      end
+    end
+  end
+end

data/lib/generators/smswire/provider/templates/provider.rb.tt

@@ -0,0 +1,52 @@
+# Smswire adapter for <%= class_name %>.
+#
+# Options come from Smswire.config.providers[:<%= file_name %>].
+# Raise Smswire::TransientError for network failures and 5xx responses,
+# Smswire::ThrottledError (with retry_after) for rate limiting, and
+# Smswire::PermanentError (with a reason) when retrying cannot help.
+# test/sms_providers/<%= file_name %>_provider_test.rb runs the shared
+# Smswire::ProviderContract against this class.
+class <%= provider_class %> < Smswire::Providers::Base
+  API_URL = "https://api.example.com/messages".freeze
+
+  # Replace with the provider's error codes.
+  PERMANENT_REASONS = {
+    "invalid_number" => :invalid_number,
+    "opted_out" => :opted_out
+  }.freeze
+
+  def deliver(message)
+    response = Smswire::HTTP.post_form(API_URL, [
+      ["to", message.to],
+      ["from", message.from.to_s],
+      ["body", message.body.to_s]
+    ], headers: {"Authorization" => "Bearer #{options.fetch(:api_key)}"}, provider: name)
+
+    status = response.code.to_i
+    json = Smswire::HTTP.parse_json(response.body)
+    code = json.dig("error", "code")&.to_s
+    error_options = {provider: name, provider_code: code, http_status: status, raw: json}
+
+    case status
+    when 200..299
+      receipt(provider_id: json["id"], status: :accepted, segments: message.segments, raw: json)
+    when 401, 403
+      raise Smswire::PermanentError.new("<%= class_name %> authentication failed", reason: :authentication, **error_options)
+    when 429
+      raise Smswire::ThrottledError.new("<%= class_name %> rate limited", retry_after: response["Retry-After"]&.to_i, **error_options)
+    when 500..599
+      raise Smswire::TransientError.new("<%= class_name %> #{status}", **error_options)
+    else
+      raise Smswire::PermanentError.new("<%= class_name %> #{status}: #{code}",
+        reason: PERMANENT_REASONS.fetch(code, :rejected), **error_options)
+    end
+  end
+
+  # Add :status_callbacks and :inbound once verify_signature!,
+  # parse_status_callback, and parse_inbound are implemented; the contract
+  # then also checks them through contract_status_request and
+  # contract_inbound_request.
+  def capabilities
+    Set.new
+  end
+end