smswire 0.0.1.pre → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 513ee2707d29f757c1f3dd7f43eefda758ff634decbd09bfae3bcde38b29c775
-  data.tar.gz: 8edba21706e42e4825524d28f5de622294aeacec784089ddb83b88cecc19276c
+  metadata.gz: 2fa9a8b61ee54a3bb0b7e0addffcf887fac34022b9f34765390fff4e6d230b3b
+  data.tar.gz: '0649a4c714cab2a26a4abf71014a4cd88d6713eef7c88aef0ce4f17c20ccb853'
 SHA512:
-  metadata.gz: 908a9ff9f247261b23fbecaad6e91e78e12310b0afa0c282a7da55cb581cef0f2779851903ddd6184bb1fa34de917e2dd887646ad5085de8246cc7514daadcbc
-  data.tar.gz: 1d5ee0fa8d452ea828004fe551dfb69a1468a5e0dd6e8770793d8a2c94e825948cb684f6b2c5ab6228f5fb0e46a9225fa939ff5a37ac2d46632010a6577d56b3
+  metadata.gz: 06e54b416dcb1e58be5cdd8a563ce1a1fde6022ab82fe084012be2b15bc702dd49fa90c6f5251927d92d2b3c3c4ddf8acb7b6389ffc1a4069208dd3fba25c45f
+  data.tar.gz: '095e78ad1679ec376c2f3787f1699b940190ac619226b3c16b47f7af4b3a92bfef80faeaea0d0ea830d19a6b2e09dc39a828b5aad212c418bccc0939b289ccc5'

data/CHANGELOG.md

@@ -1,10 +1,74 @@
 # Changelog
 
 All notable changes to this project are documented here. The format follows
-[Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/). Before 1.0, minor versions may
+include breaking changes, which are called out here.
 
 ## [Unreleased]
 
-## [0.0.1.pre]
+## [0.1.0] - 2026-10-15
 
-- Reserve the gem name. No functionality yet; see `docs/SPEC.md`.
+First functional release. Requires Ruby 3.2+ and Rails 7.1 to 8.1.
+
+### Messengers and delivery
+
+- `Smswire::Base` messenger classes with `default`, `with(params)`, `.text.erb`
+  templates, layouts, I18n lazy lookup, URL helpers, and named senders.
+- `Smswire::Message` with GSM-7 / UCS-2 detection and segment counting.
+- A delivery pipeline with E.164 normalization, consent checks, quiet hours,
+  rate limits, deduplication, interceptors, and observers, returning a
+  `Smswire::Result` with a typed status.
+- `deliver_later` through `Smswire::DeliveryJob`, retrying transient errors
+  with backoff and honoring `Retry-After`.
+
+### Providers
+
+- Twilio, Telnyx, and Vonage adapters over REST with no provider SDK, plus
+  `log`, `test`, and `null` providers and a registry for custom adapters.
+- Webhook signature verification for each provider: Twilio HMAC-SHA1, Telnyx
+  Ed25519, and Vonage `md5hash` or HMAC.
+- `Smswire::ProviderContract`, a Minitest suite every adapter passes.
+- `Smswire.verify_credentials!` for boot checks and health endpoints.
+
+### Persistence and tracking
+
+- `Smswire::Engine` with `smswire:install:migrations` and tables for
+  deliveries, consents, and inbound messages, following the app's primary
+  key type.
+- A `Smswire::Delivery` row for every send, with atomic send claims, retries
+  that reuse their row, and forward-only status from provider callbacks.
+
+### Consent and compliance
+
+- `Smswire::Consent` with per-sender scopes and evidence metadata.
+- STOP / START / HELP keyword handling with replies following CTIA guidance,
+  including a `support_contact` in HELP replies.
+- Category rules: `marketing` requires opt-in and observes 9pm to 8am quiet
+  hours in the recipient's time zone. Carrier opt-out errors record opt-outs.
+
+### Developer experience
+
+- Previews at `<mount>/previews` and a development inbox at `<mount>/inbox`.
+- Generators: `smswire:install`, `smswire:messenger`, and `smswire:provider`.
+- `Smswire::TestHelper` for Minitest and RSpec matchers in `smswire/rspec`.
+- `Smswire::Interceptors::Allowlist` for staging.
+- `Noticed::DeliveryMethods::Smswire` for `deliver_by :smswire`.
+- Guides in `docs/guides`.
+
+### Known limitations
+
+- Free-text opt-outs such as "please stop texting me" are stored but not
+  acted on; the compliance guide shows how to review them.
+- Concurrent sends can briefly exceed a rate limit.
+- Vonage receipts for the second and later parts of a long message are not
+  matched to the delivery, and Vonage has no MMS.
+- Telnyx ignores `validity_period`.
+
+## [0.0.1.pre] - 2026-10-08
+
+- Reserve the gem name. No functionality.
+
+[Unreleased]: https://github.com/timimsms/smswire/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/timimsms/smswire/compare/v0.0.1.pre...v0.1.0
+[0.0.1.pre]: https://github.com/timimsms/smswire/releases/tag/v0.0.1.pre

data/README.md

@@ -3,18 +3,231 @@
 > The production SMS layer for Rails that Noticed and twilio-ruby both leave to you.
 
 Smswire gives Rails applications Action Mailer-style messenger classes and
-templates for SMS, a provider-agnostic message object, persisted deliveries
-with provider status callbacks, consent and keyword handling (STOP / HELP /
-START), quiet hours, retries with a transient-vs-permanent error taxonomy,
-development sandboxing, previews, and test helpers.
+templates for SMS, a provider-agnostic message object, a delivery pipeline
+with typed outcomes, retries with a transient-versus-permanent error
+taxonomy, and test helpers. Persisted deliveries with status callbacks,
+consent and STOP / HELP / START handling, quiet hours, previews, and a
+[Noticed](https://github.com/excid3/noticed) delivery method are included.
+See the [specification](docs/SPEC.md) for the full design.
 
-It complements [Noticed](https://github.com/excid3/noticed) by shipping a
-`Noticed::DeliveryMethods::Smswire` adapter, and it works standalone for apps
-that do not need a notification inbox.
+**Status:** `0.1.0`, the first functional release. The API may still change
+before 1.0; breaking changes are called out in the [changelog](CHANGELOG.md).
 
-**Status:** specification stage. Nothing is published yet.
+## Guides
 
-- [Scoped specification](docs/SPEC.md)
+- [Getting started](docs/guides/getting-started.md)
+- [Migrating from direct twilio-ruby calls](docs/guides/migrating-from-twilio-ruby.md)
+- [Migrating from Noticed's Twilio delivery method](docs/guides/migrating-from-noticed-twilio.md)
+- [Compliance primer](docs/guides/compliance.md)
+- [Writing a provider adapter](docs/guides/writing-a-provider.md)
+
+## Requirements
+
+Ruby 3.2+ and Rails 7.1 through 8.1.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "smswire"
+```
+
+```
+bin/rails generate smswire:install
+bin/rails db:migrate
+bin/rails generate smswire:messenger Order shipped
+```
+
+The install generator copies the migrations, writes
+`config/initializers/smswire.rb` and `ApplicationMessenger`, and mounts the
+engine at `/smswire`. The messenger generator writes the class, a template per
+action, a preview, and a test.
+
+## Usage
+
+```ruby
+# config/initializers/smswire.rb
+Smswire.configure do |config|
+  config.default_provider = :twilio   # :log in development and :test in test by default
+  config.providers = {twilio: {account_sid: "AC...", auth_token: "..."}}  # or credentials.twilio
+  config.senders = {transactional: {number: "+15005550006"}}
+end
+```
+
+```ruby
+# app/messengers/order_messenger.rb
+class OrderMessenger < Smswire::Base
+  default from: :transactional
+
+  def shipped(user)
+    @order = params[:order]
+    text to: user   # any object with #phone_number, or an E.164 string
+  end
+end
+```
+
+```erb
+<%# app/views/order_messenger/shipped.text.erb %>
+<%= t(".greeting", name: @order.customer_name) %> Order <%= @order.number %> has shipped.
+Track it: <%= order_url(@order) %>
+```
+
+```ruby
+OrderMessenger.with(order:).shipped(user).deliver_later
+result = OrderMessenger.with(order:).shipped(user).deliver_now
+result.status       # => :accepted, :failed, :rejected_invalid_number, ...
+result.provider_id  # => "SM..."
+```
+
+Every message is normalized to E.164, checked for an empty body, passed
+through interceptors, sent, and reported to observers and
+`ActiveSupport::Notifications` (`deliver.smswire`, `reject.smswire`). Bodies
+are never instrumented or logged by provider adapters.
+
+### Deliveries and status callbacks
+
+```
+bin/rails smswire:install:migrations
+bin/rails db:migrate
+```
+
+```ruby
+# config/routes.rb
+mount Smswire::Engine => "/smswire"
+
+# config/initializers/smswire.rb
+config.callbacks_url = "https://app.example.com/smswire"
+```
+
+Every send is recorded in `Smswire::Delivery` with the provider message id,
+segments, price, and status. With `callbacks_url` set, Twilio posts status
+updates to the engine, which verifies the signature and moves the row
+forward: `pending`, `queued`, `sent`, `delivered` (or `undelivered` /
+`failed`). Out-of-order callbacks never move a status backwards.
+
+Identical messages to the same number inside `dedupe_window` (10 minutes by
+default) are refused with status `:duplicate`. Pass `idempotency_key:` to
+`text` to choose what counts as identical. Bodies are stored unless the
+category opts out; `otp` does by default.
+
+```ruby
+result = OrderMessenger.with(order:).shipped(user).deliver_now
+result.delivery.status          # => "accepted"
+Smswire::Delivery.for_number("+15551234567").recent
+```
+
+### Consent, keywords, quiet hours, and rate limits
+
+Point your Twilio number's incoming message webhook at
+`https://app.example.com/smswire/inbound/twilio`. Replies of STOP, START,
+and HELP (and their synonyms) update `Smswire::Consent` and send the
+configured confirmation. Record opt-ins from your own forms with evidence:
+
+```ruby
+Smswire::Consent.opt_in!(user.phone, source: :web_form,
+  metadata: {ip: request.remote_ip, form: "checkout", copy: terms_text})
+```
+
+Each message has a category. The shipped rules are:
+
+| Category | Consent | Quiet hours |
+|---|---|---|
+| `transactional` (default) | send unless opted out | none |
+| `otp` | send unless opted out; body not stored | none |
+| `marketing` | requires opt-in | 9pm to 8am recipient time |
+| `compliance` | not checked; keyword replies | none |
+
+Override any key, and add rate limits, in `config.categories`. Messages in
+quiet hours or over a rate limit are re-enqueued for when they may send and
+return `:deferred_quiet_hours` or `:deferred_rate_limited`. A carrier
+opt-out error from the provider records an opt-out automatically.
+
+Smswire provides these mechanisms. Your app is still responsible for its
+messaging program's legal compliance.
+
+### Development tools
+
+In development, open `/smswire/previews` to see every preview rendered in a
+phone frame with its encoding, segment count, and remaining characters, and
+which characters force UCS-2. Open `/smswire/inbox` to see what was sent and
+received, and to simulate a reply such as STOP.
+
+```ruby
+# test/messengers/previews/order_messenger_preview.rb
+class OrderMessengerPreview < Smswire::Preview
+  def shipped
+    OrderMessenger.with(order: Order.first).shipped(User.first)
+  end
+end
+```
+
+For staging, only let messages through to known numbers:
+
+```ruby
+Smswire.register_interceptor(
+  Smswire::Interceptors::Allowlist.new(numbers: ENV.fetch("SMS_ALLOWLIST", "").split(","))
+  # or redirect_to: "+15555550100" to reroute everything else to one phone
+)
+```
+
+### Providers
+
+| Name | Use |
+|---|---|
+| `:twilio` | Twilio Programmable Messaging over REST, no SDK |
+| `:telnyx` | Telnyx Messaging API v2; `api_key`, `public_key` for webhooks |
+| `:vonage` | Vonage SMS API; `api_key`, `api_secret`, `signature_secret` |
+| `:log` | Writes messages to the logger; development default |
+| `:test` | Records messages in memory; test default |
+| `:null` | Accepts and discards |
+
+Each adapter passes `Smswire::ProviderContract`, a test suite shipped in the
+gem. Generate your own with `bin/rails generate smswire:provider Acme`, which
+writes an adapter and a test that runs the contract against it, or
+subclass `Smswire::Providers::Base` and call
+`Smswire::Providers.register(:acme, "AcmeProvider")`.
+
+### Noticed
+
+```ruby
+class OrderShippedNotifier < Noticed::Event
+  deliver_by :smswire do |config|
+    config.messenger = "OrderMessenger"
+    config.action = :shipped        # called with the recipient by default
+  end
+end
+```
+
+The messenger gets the event params plus `notification`, `record`, and
+`recipient`, so consent, quiet hours, deduplication, retries, and status
+tracking all apply. Each delivery stores the Noticed notification and event
+ids in its metadata.
+
+### Testing
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  include Smswire::TestHelper
+
+  test "ships" do
+    assert_sms_delivered(to: "+15551234567", messenger: OrderMessenger, body: /shipped/) do
+      order.ship!   # deliver_later jobs inside the block are performed
+    end
+    assert_enqueued_sms(OrderMessenger, :shipped) { order.ship! }
+  end
+end
+```
+
+RSpec: `require "smswire/rspec"` for `deliver_sms(...)` and
+`have_enqueued_sms(OrderMessenger, :shipped)`.
+
+## Development
+
+```
+bin/setup
+bundle exec rake            # tests and Standard
+RAILS_VERSION=7.1 bundle exec rake test
+```
 
 ## License
 

data/RELEASING.md

@@ -0,0 +1,49 @@
+# Releasing
+
+Releases publish to RubyGems from GitHub Actions with
+[trusted publishing](https://guides.rubygems.org/trusted-publishing/), so no
+API key or one-time code is stored anywhere. The gem requires MFA for
+manual pushes.
+
+## One-time setup
+
+1. On rubygems.org, open the `smswire` gem, then **Trusted publishers**, and
+   add a GitHub Actions publisher:
+   - Repository: `timimsms/smswire`
+   - Workflow filename: `release.yml`
+   - Environment: `rubygems`
+2. In the GitHub repository settings, create an environment named
+   `rubygems`. Add required reviewers if releases should need approval.
+
+## Before 1.0
+
+- Confirm open decisions 4 to 6 in `docs/SPEC.md`.
+- Review the known limitations in `CHANGELOG.md` and `docs/SPEC.md`.
+- Try the getting-started guide in a new Rails app against a real provider
+  account, including a STOP reply and a delivery status callback.
+
+## Each release
+
+1. Open a pull request that:
+   - updates `lib/smswire/version.rb`;
+   - in `CHANGELOG.md`, moves the `[Unreleased]` entries under a new
+     `[X.Y.Z] - YYYY-MM-DD` heading, leaves `[Unreleased]` empty, and updates
+     the compare links at the bottom.
+2. Merge it once CI is green.
+3. In GitHub, open **Actions > Release > Run workflow** on `main`.
+4. The workflow runs the tests, then `rake release` builds the gem, creates
+   and pushes the `vX.Y.Z` tag, and publishes with trusted publishing. It
+   waits until the version is available on RubyGems.
+5. Create a GitHub release from the new tag with the changelog section:
+
+   ```
+   gh release create vX.Y.Z --notes-file <(sed -n '/^## \[X.Y.Z\]/,/^## \[/p' CHANGELOG.md | sed '$d')
+   ```
+
+If the workflow fails before publishing, fix the problem and run it again;
+`rake release` skips tagging when the tag already exists.
+
+## If a release goes wrong
+
+`gem yank smswire -v X.Y.Z` removes a version from installs, but the version
+number cannot be reused. Fix forward with a patch release.

data/app/controllers/smswire/development_controller.rb

@@ -0,0 +1,17 @@
+module Smswire
+  # Base for the development tools. Each subclass names the config flag
+  # that enables it; when the flag is off the tool answers 404.
+  class DevelopmentController < ActionController::Base
+    layout "smswire/application"
+
+    class_attribute :enabled_by
+
+    before_action :require_enabled
+
+    private
+
+    def require_enabled
+      head :not_found unless Smswire.config.public_send(enabled_by)
+    end
+  end
+end

data/app/controllers/smswire/inbound_messages_controller.rb

@@ -0,0 +1,9 @@
+module Smswire
+  # POST <mount>/inbound/:provider. Apps can build two-way messaging with
+  # an observer that implements +sms_received(inbound_message)+.
+  class InboundMessagesController < WebhooksController
+    def create
+      handle_inbound || handle_status || head(:no_content)
+    end
+  end
+end

data/app/controllers/smswire/inbox_controller.rb

@@ -0,0 +1,31 @@
+require "securerandom"
+
+module Smswire
+  # Development inbox: recent deliveries and inbound messages, plus a form
+  # to simulate a reply such as STOP without a real provider.
+  class InboxController < DevelopmentController
+    self.enabled_by = :show_inbox
+
+    LIMIT = 50
+
+    def index
+      @deliveries = Delivery.recent.limit(LIMIT)
+      @inbound_messages = InboundMessage.recent.limit(LIMIT)
+      @default_to = Smswire.config.senders.values.filter_map { |sender| sender.to_h.symbolize_keys[:number] }.first
+    end
+
+    def receive
+      from = PhoneNumber.normalize(params[:from])
+      if from.nil? || params[:body].blank?
+        flash[:alert] = "Enter a valid From number and a message body."
+        return redirect_to(inbox_path)
+      end
+
+      inbound = Inbound.new(provider_id: "inbox-#{SecureRandom.hex(8)}", from:, to: params[:to].presence, body: params[:body])
+      record = InboundHandler.call(inbound, provider: Smswire.config.default_provider || :log)
+      keyword = record&.reload&.keyword
+      flash[:notice] = keyword ? "Received from #{from}; handled keyword #{keyword.upcase}." : "Received from #{from}."
+      redirect_to inbox_path
+    end
+  end
+end

data/app/controllers/smswire/previews_controller.rb

@@ -0,0 +1,22 @@
+module Smswire
+  class PreviewsController < DevelopmentController
+    self.enabled_by = :show_previews
+
+    def index
+      @previews = Preview.all
+    end
+
+    def show
+      preview_name, _, message_name = params[:path].rpartition("/")
+      @preview = Preview.find(preview_name)
+      return head(:not_found) unless @preview&.message_exists?(message_name)
+
+      @message_name = message_name
+      @message = @preview.call(message_name)
+      return render(plain: @message&.body.to_s) if params[:raw].present?
+
+      @analysis = @message && Segments.analyze(@message.body)
+      @non_gsm = @message ? Segments.non_gsm_characters(@message.body) : []
+    end
+  end
+end

data/app/controllers/smswire/status_callbacks_controller.rb

@@ -0,0 +1,8 @@
+module Smswire
+  # POST <mount>/status/:provider
+  class StatusCallbacksController < WebhooksController
+    def create
+      handle_status || handle_inbound || head(:no_content)
+    end
+  end
+end

data/app/controllers/smswire/webhooks_controller.rb

@@ -0,0 +1,49 @@
+module Smswire
+  # Shared provider webhook handling. Each endpoint tries its own kind of
+  # event first and falls back to the other, so a provider that posts every
+  # event to one URL (Telnyx messaging profiles do) is handled either way.
+  # Signed, well-formed requests always get a 2xx so providers do not retry.
+  class WebhooksController < ActionController::Base
+    skip_forgery_protection
+
+    before_action :load_provider
+    before_action :verify_signature
+
+    private
+
+    def load_provider
+      @provider = Providers.resolve(params[:provider])
+      head(:not_found) unless (@provider.capabilities & %i[status_callbacks inbound]).any?
+    rescue ConfigurationError
+      head :not_found
+    end
+
+    def verify_signature
+      return unless Smswire.config.verify_callback_signatures
+
+      @provider.verify_signature!(request, url: Callbacks.request_url(request))
+    rescue SignatureError => error
+      Smswire.logger.warn("[Smswire] Rejected #{@provider.name} webhook: #{error.message}")
+      head :forbidden
+    end
+
+    def handle_status
+      return false unless @provider.capabilities.include?(:status_callbacks)
+
+      update = @provider.parse_status_callback(request) or return false
+      StatusHandler.call(update, provider: @provider.name, delivery_id: params[:delivery_id])
+      head :no_content
+      true
+    end
+
+    def handle_inbound
+      return false unless @provider.capabilities.include?(:inbound)
+
+      inbound = @provider.parse_inbound(request) or return false
+      InboundHandler.call(inbound, provider: @provider.name)
+      body, content_type = @provider.inbound_response
+      body ? render(plain: body, content_type:) : head(:no_content)
+      true
+    end
+  end
+end

data/app/models/smswire/application_record.rb

@@ -0,0 +1,5 @@
+module Smswire
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/smswire/consent.rb

@@ -0,0 +1,71 @@
+module Smswire
+  # A phone number's messaging consent within a scope. The scope is
+  # "default" unless a sender sets +consent_scope+, which lets separate
+  # programs (for example two brands on two numbers) keep separate consent.
+  #
+  #   Smswire::Consent.opt_in!("+15551234567", source: :web_form,
+  #     metadata: {ip: request.remote_ip, form: "checkout", copy: terms_text})
+  #   Smswire::Consent.status_for("+15551234567")  # => "opted_in"
+  class Consent < ApplicationRecord
+    DEFAULT_SCOPE = "default".freeze
+    STATUSES = %w[opted_in opted_out pending unknown].freeze
+
+    enum :status, STATUSES.index_with(&:itself)
+
+    class << self
+      def status_for(phone, scope: DEFAULT_SCOPE)
+        find_by(phone: normalize!(phone), scope: scope.to_s)&.status || "unknown"
+      end
+
+      def opt_in!(phone, source:, scope: DEFAULT_SCOPE, keyword: nil, metadata: {})
+        record!(phone, scope, {status: "opted_in", opted_in_at: Time.current}, source:, keyword:, metadata:)
+      end
+
+      def opt_out!(phone, source:, scope: DEFAULT_SCOPE, keyword: nil, metadata: {})
+        record!(phone, scope, {status: "opted_out", opted_out_at: Time.current}, source:, keyword:, metadata:)
+      end
+
+      # STOPALL: opt out of every scope this number has, plus every scope
+      # the configured senders use.
+      def opt_out_everywhere!(phone, source:, keyword: nil)
+        number = normalize!(phone)
+        scopes = (where(phone: number).pluck(:scope) + Smswire.config.consent_scopes).uniq
+        scopes.map { |scope| opt_out!(number, scope:, source:, keyword:) }
+      end
+
+      # The consent scope of the configured sender that owns +number+ or
+      # +messaging_service+, used for inbound keywords.
+      def scope_for_sender(number: nil, messaging_service: nil)
+        Smswire.config.senders.each_value do |options|
+          options = options.to_h.symbolize_keys
+          matched = (number.present? && options[:number] == number) ||
+            (messaging_service.present? && options[:messaging_service] == messaging_service)
+          return (options[:consent_scope] || DEFAULT_SCOPE).to_s if matched
+        end
+        DEFAULT_SCOPE
+      end
+
+      private
+
+      def normalize!(phone)
+        PhoneNumber.normalize(phone) || raise(ArgumentError, "Invalid phone number: #{phone.inspect}")
+      end
+
+      def record!(phone, scope, attributes, source:, keyword:, metadata:)
+        retried = false
+        begin
+          consent = find_or_initialize_by(phone: normalize!(phone), scope: scope.to_s)
+          consent.assign_attributes(attributes.merge(source: source.to_s))
+          consent.assign_attributes(last_keyword: keyword, last_keyword_at: Time.current) if keyword
+          consent.metadata = (consent.metadata || {}).merge(metadata.deep_stringify_keys) if metadata.present?
+          consent.save!
+          consent
+        rescue ActiveRecord::RecordNotUnique
+          raise if retried
+          retried = true
+          retry
+        end
+      end
+    end
+  end
+end