smswire 0.0.1.pre → 0.1.0

data/docs/SPEC.md

@@ -196,11 +196,15 @@ end
   `deliver_later` is called, exactly like `mail`.
 - Templates live at `app/views/<messenger_name>/<action>.text.erb`. I18n via
   `t(".key")` scoped the same way Action Mailer scopes it.
-- Body whitespace is squished by default (configurable) since SMS has no
-  layout. Rendering computes `segments` and `encoding` (GSM-7 vs. UCS-2) on the
+- Body whitespace is cleaned with `body_whitespace = :strip` by default:
+  trailing spaces on each line are removed, three or more newlines collapse to
+  two, and the ends are stripped. `:squish` and `:preserve` are the
+  alternatives. Layouts are supported, which suits a shared opt-out footer.
+  Rendering computes `segments` and `encoding` (GSM-7 vs. UCS-2) on the
   message so previews, logs, and callbacks can report them.
-- `default` supports `from`, `category`, `sender`, `provider`,
-  `messaging_service`, `validity_period`, `quiet_hours`.
+- `default` supports `from`, `category`, `provider`, `messaging_service`,
+  `metadata`, `validity_period`. A named sender is given as `from: :name`.
+  Quiet hours and rate limits are set per category, not per messenger.
 
 ### 6.2 Message object
 
@@ -208,9 +212,13 @@ end
 ActiveJob (GlobalID for the recipient object, primitives for the rest). It
 exposes:
 
-- `deliver_now` runs the pipeline inline and returns a `Smswire::Delivery`.
+- `deliver_now` runs the pipeline inline and returns a `Smswire::Result`
+  (status, message, receipt, error). From Phase 2 the result also carries the
+  persisted `Smswire::Delivery`.
 - `deliver_later(wait:, wait_until:, queue:, priority:)` enqueues
-  `Smswire::DeliveryJob`. The job re-runs the pipeline, so consent and quiet
+  `Smswire::DeliveryJob` with the messenger name, action, params, and
+  arguments, like Action Mailer. Arguments must be ActiveJob-serializable.
+  The job re-runs the action and the pipeline, so consent and quiet
   hours are evaluated at send time, not enqueue time.
 - `segments`, `encoding`, `length` computed at render.
 - `idempotency_key` defaults to a digest of messenger, action, recipient, and
@@ -228,6 +236,8 @@ halt with a typed outcome so callers and observers can distinguish:
 - `:deferred_quiet_hours` (re-enqueued for the next allowed window)
 - `:deferred_rate_limited`
 - `:suppressed_by_interceptor` (dev sandbox, allowlist)
+- `:rejected_empty_body` (no body and no media)
+- `:skipped` (the action returned without calling `text`)
 - `:duplicate`
 - `:accepted` / `:failed`
 
@@ -272,6 +282,33 @@ Later: `sinch`, `bandwidth`, `aws_sns`, `plivo`, `messagebird`.
 All adapters use Net::HTTP (or a tiny shared client as in Noticed). No
 provider SDKs are runtime dependencies. Bodies are never logged.
 
+Adapter notes:
+
+- **Twilio** signs webhooks with HMAC-SHA1 over the URL and sorted POST
+  parameters. Messaging services map to `MessagingServiceSid`.
+- **Telnyx** signs webhooks with Ed25519 over `<timestamp>|<raw body>`,
+  verified against the account public key, with a five-minute timestamp
+  tolerance. Messaging services map to `messaging_profile_id`. A messaging
+  profile can post every event to one URL, so both webhook endpoints accept
+  both event kinds. Telnyx takes no validity period here, so it is ignored.
+- **Vonage** (SMS API) signs webhooks with sorted `&key=value` pairs using the
+  configured `signature_secret` and `signature_method` (`md5hash`, Vonage's
+  default, or an HMAC). Its send error 7, "number barred," also covers blocks
+  other than opt-outs, so it maps to `:unroutable` and never records an
+  opt-out. Long messages are billed as several parts with separate ids; the
+  receipt keeps the first, so receipts for later parts are acknowledged but
+  not matched. The API does not name a price currency.
+
+**Contract suite.** `Smswire::ProviderContract` is a Minitest module shipped
+in the gem. An adapter's test includes it and defines hooks that stub the
+provider for each outcome (`success`, `invalid_number`, `opted_out`,
+`authentication`, `throttled`, `server_error`, `timeout`) and build signed
+status and inbound requests. The suite checks receipts, the normalized status
+vocabulary, the error taxonomy and reasons, a full pipeline send, and, for
+declared capabilities, callback parsing and signature rejection. An adapter
+whose provider cannot report opt-outs at send time says so with
+`contract_reports_opt_outs?` rather than guessing.
+
 ### 6.5 Persistence
 
 Three tables, installed by `rails g smswire:install`.
@@ -280,22 +317,25 @@ Three tables, installed by `rails g smswire:install`.
 
 | column | type | notes |
 |---|---|---|
-| id | uuid/bigint | |
+| id | app default | follows the app's generator `primary_key_type`, like Active Storage |
 | messenger, action | string | e.g. `OrderMessenger`, `shipped` |
-| to, from | string | E.164 |
-| recipient_type, recipient_id | string, string | polymorphic, optional |
+| to_number, from_number | string | E.164; named to avoid the reserved words `to` and `from` |
+| messaging_service | string | |
+| recipient_type, recipient_id | string, app key type | polymorphic, optional; set only for persisted Active Record recipients |
 | category | string | `transactional`, `otp`, `marketing`, custom |
 | body | text | nullable; `store_bodies` config defaults to true, with a per-category override so OTP bodies can be excluded |
 | segments, encoding | integer, string | |
 | provider | string | |
 | provider_id | string | indexed, unique with provider |
-| status | string | normalized vocabulary |
+| status | string | `pending`, `suppressed`, then the normalized vocabulary; only moves forward |
 | error_code, error_message | string, text | provider raw code + normalized message |
-| idempotency_key | string | unique index |
+| idempotency_key | string | unique index; cleared on the old row when the dedupe window expires |
 | price_amount, price_currency | decimal, string | if the provider reports it |
 | metadata | json | app-supplied |
 | scheduled_at, sent_at, delivered_at, failed_at | datetime | |
 | attempts | integer | |
+| claimed_at | datetime | send claim; released on transient errors, expires after two minutes |
+| status_updated_at | datetime | |
 | created_at, updated_at | datetime | |
 
 **smswire_consents**
@@ -331,18 +371,30 @@ legal compliance. Defaults follow CTIA messaging principles so an app that does
 nothing is at least not wrong:
 
 - **Keyword handling** on inbound: opt-out set (`STOP`, `STOPALL`,
-  `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`), help set (`HELP`, `INFO`), opt-in
-  set (`START`, `YES`, `UNSTOP`). Case-insensitive, trimmed, configurable.
+  `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`, `OPTOUT`, `REVOKE`), help set
+  (`HELP`, `INFO`), opt-in set (`START`, `YES`, `UNSTOP`). A keyword matches
+  only as the whole message, ignoring case, whitespace, and surrounding
+  punctuation. Configurable. `STOPALL` opts out of every consent scope.
+- **Consent scopes**: consent is stored per phone number and scope. A
+  sender's `consent_scope` (default `"default"`) decides the scope for both
+  outbound checks and inbound keywords to that sender's number.
 - **Auto-replies** for each keyword are templated and configurable; the
-  opt-out confirmation is sent even if consent is already `opted_out`.
+  opt-out confirmation is sent even if consent is already `opted_out`,
+  through the built-in `compliance` category, which skips consent checks.
+  When the provider already replied, as Twilio Advanced Opt-Out signals with
+  `OptOutType`, consent is recorded and no second reply is sent.
 - **Consent gating** by category: `otp` and `transactional` default to
   `allow_unless_opted_out`; `marketing` defaults to `require_opted_in`.
   Apps can define categories and rules.
 - **Quiet hours** per category, evaluated in the recipient's time zone when
   resolvable (recipient object responds to `time_zone`), otherwise in a
-  configured default. Deferred messages re-enqueue for the next window.
-- **Rate limits** per recipient per category over a sliding window, backed by
-  `Rails.cache`.
+  configured default. Deferred messages re-enqueue for the next window,
+  from both `deliver_now` and `deliver_later`. The marketing default is the
+  US federal TCPA window, 9pm to 8am; some states are stricter.
+- **Rate limits** per recipient per category over a sliding window, counted
+  from `smswire_deliveries` so they survive restarts and are shared across
+  processes. Failed and suppressed deliveries do not count. Concurrent sends
+  can exceed the limit briefly.
 - **Carrier opt-out sync**: a permanent error with an unsubscribed/blocked
   code updates the consent row to `opted_out` with `source: carrier`.
 
@@ -368,7 +420,23 @@ assert_no_sms_delivered
 Previews mirror Action Mailer previews, at `test/messengers/previews/` or
 `spec/messengers/previews/`, served at `/smswire/previews` in development.
 Each preview renders the body in a phone frame, shows segment count, encoding,
-character budget remaining, and the resolved sender.
+character budget remaining, and the resolved sender, and names any characters
+that force UCS-2. Previews build the message without running interceptors or
+sending.
+
+The development inbox at `/smswire/inbox` lists recent deliveries and inbound
+messages, and has a form that simulates a reply such as STOP through the same
+handling as the inbound webhook.
+
+Both tools are enabled with `config.smswire.show_previews` and
+`config.smswire.show_inbox` in `config/application.rb` or an environment
+file, and default to true in development only. Preview paths are registered
+for autoloading before initializers run, as Action Mailer does, so they cannot
+be set from `config/initializers`.
+
+The allowlist interceptor either suppresses messages to unlisted numbers or,
+with `redirect_to:`, reroutes them to one number with the original recipient
+prefixed to the body.
 
 ### 6.8 Observability
 
@@ -394,15 +462,20 @@ class OrderShippedNotifier < Noticed::Event
     config.messenger = "OrderMessenger"
     config.action    = :shipped
     config.params    = -> { {order: record} }
-    # Optional: config.category, config.wait, config.if
+    # Optional: config.args, config.kwargs, config.params, config.sms_queue;
+    # Noticed options such as config.wait and config.if apply to its own job
   end
 end
 ```
 
 The adapter builds the message through the messenger, so templates, consent,
-quiet hours, persistence, and status tracking all apply. The resulting
-`Smswire::Delivery` id is written back to the Noticed notification via
-`error_handler`-style callbacks so the two records can be joined.
+quiet hours, persistence, and status tracking all apply. It always uses
+`deliver_later`, so Smswire's retry policy applies even though Noticed's own
+delivery jobs do not retry. The messenger receives the event params plus
+`notification`, `record`, and `recipient`, and the default action argument is
+the recipient. Each `Smswire::Delivery` records `noticed_notification_id` and
+`noticed_event_id` in its metadata, which joins the two records without a
+schema dependency between the gems.
 
 ### 6.10 Generators
 
@@ -410,7 +483,10 @@ quiet hours, persistence, and status tracking all apply. The resulting
   route mount, credentials scaffold hints.
 - `rails g smswire:messenger Order shipped delivered` — class, templates,
   preview, test.
-- `rails g smswire:provider Acme` — adapter skeleton with contract tests.
+- `rails g smswire:provider Acme` — adapter skeleton in `app/sms_providers`,
+  a test that runs `Smswire::ProviderContract` against it with WebMock stubs,
+  and a registration line in the initializer. The generated pair passes the
+  contract as generated.
 
 ## 7. Configuration surface
 
@@ -431,26 +507,36 @@ Smswire.configure do |c|
 
   c.recipient_resolver = ->(obj) { obj.respond_to?(:mobile_phone) ? obj.mobile_phone : obj.phone_number }
   c.default_region = "US"             # for parsing national-format numbers
-  c.phone_validator = :phonelib        # or :e164_regex (no extra dependency)
+  c.phone_validator = :auto            # :phonelib, or :e164 (built-in, no extra dependency)
 
+  # Merged per key over the shipped defaults:
+  #   otp:           { consent: :allow_unless_opted_out, store_body: false }
+  #   transactional: { consent: :allow_unless_opted_out }
+  #   marketing:     { consent: :require_opted_in, quiet_hours: "21:00".."08:00" }
+  #   compliance:    { consent: :none }   # keyword auto-replies
   c.categories = {
-    otp:           { consent: :allow_unless_opted_out, quiet_hours: nil,            store_body: false },
-    transactional: { consent: :allow_unless_opted_out, quiet_hours: nil },
-    marketing:     { consent: :require_opted_in,      quiet_hours: "21:00".."09:00", rate_limit: {max: 3, per: 1.day} }
+    marketing: { rate_limit: {max: 3, per: 1.day} }   # exceed: :defer (default) or :reject
   }
+  c.default_time_zone = "America/New_York"   # quiet hours when the recipient has no time_zone
+  c.program_name = "Acme Alerts"             # used in keyword auto-replies
 
   c.dedupe_window = 10.minutes
-  c.retry = { attempts: 5, wait: :polynomially_longer }
+  c.retry_attempts = 5                # total attempts for transient errors; polynomial backoff
   c.store_bodies = true
-  c.interceptors = []                 # per-env additions in config/environments/*.rb
-  c.callbacks_host = "https://app.example.com"   # used to build StatusCallback URLs
+  c.body_whitespace = :strip          # or :squish, :preserve
+  c.deliver_later_queue = :default
+  # Smswire.register_interceptor / register_observer, per environment
+  c.callbacks_url = "https://app.example.com/smswire"  # engine mount URL; builds StatusCallback URLs
+  c.persist_deliveries = true
+  c.verify_callback_signatures = true
 end
 ```
 
 ### 7.1 Dependency policy
 
-Runtime: `activesupport`, `activejob`, `activerecord`, `actionview`,
-`railties` (all `>= 7.1`). Optional: `phonelib` (soft dependency, detected at
+Runtime: `actionpack` (for AbstractController and Action View rendering),
+`activejob`, `activesupport`, `railties` (all `>= 7.1, < 9`), and `zeitwerk`.
+`activerecord` joins in Phase 2 with the persistence tables. Optional: `phonelib` (soft dependency, detected at
 load). No provider SDKs. No HTTP client gem.
 
 ### 7.2 Recipient resolution
@@ -496,6 +582,8 @@ next. No phase includes a calendar estimate.
 - `TestHelper`, RSpec matchers, interceptors and observers.
 - Accept: a dummy-app messenger renders a template, sends through Twilio
   against WebMock, and the full test-helper surface passes.
+- Status: implemented. Built-in phone validation accepts E.164 input and
+  North American national formats; other national formats need `phonelib`.
 
 ### Phase 2: Persistence and status tracking
 
@@ -506,6 +594,11 @@ next. No phase includes a calendar estimate.
 - Accept: a delivery row moves `pending → accepted → delivered` from a
   replayed Twilio callback fixture; duplicate sends inside the window are
   refused.
+- Status: implemented. Rows are claimed atomically before sending, so a
+  transient-error retry reuses its row and two workers never send the same
+  claimed message. Callback URLs carry the delivery id to survive the race
+  between the provider's response and its first callback. Rejected messages
+  are not persisted; they are reported through `reject.smswire`.
 
 ### Phase 3: Consent and inbound keywords
 
@@ -516,12 +609,16 @@ next. No phase includes a calendar estimate.
   confirmation; a `marketing` send to a non-opted-in number is rejected with
   `:rejected_no_consent`; a quiet-hours send is re-enqueued for the next
   window.
+- Status: implemented. Inbound webhooks are recorded once per provider
+  message id, so retries never double-process a keyword. Observers can
+  implement `sms_received(inbound_message)` to build two-way messaging.
 
 ### Phase 4: Developer experience
 
 - Previews route and UI, local inbox UI, generators, allowlist interceptor.
 - Accept: `rails g smswire:messenger` output renders in previews with correct
   segment and encoding display; development deliveries appear in the inbox.
+- Status: implemented.
 
 ### Phase 5: Breadth
 
@@ -530,12 +627,31 @@ next. No phase includes a calendar estimate.
 - `Noticed::DeliveryMethods::Smswire`.
 - Accept: the same dummy-app messenger passes the contract suite against all
   three real adapters (WebMock) and delivers through a Noticed notifier.
+- Status: implemented. Webhook endpoints share one controller, so a provider
+  that sends every event to one URL is routed by event kind.
 
 ### Phase 6: Release
 
 - Guides: getting started, migrating from direct twilio-ruby, migrating from
   Noticed `twilio_messaging`, compliance primer, provider authoring.
 - `1.0.0` once the adapter contract and schema are considered stable.
+- Status: guides written in `docs/guides`, with a test that every setting,
+  constant, and generator they name exists. Compliance research changed the
+  defaults: HELP replies include `support_contact`, the opt-out confirmation
+  follows CTIA wording, keywords ignore spaces ("opt out"), and
+  `opt_out_all_scopes` prepares for the FCC revoke-all provision.
+  `Smswire.verify_credentials!` from section 6.8 is implemented. Release
+  steps are in `RELEASING.md`; publishing 1.0 is left to the maintainer.
+
+### Known limitations at 1.0
+
+- Free-text opt-outs ("please stop texting me") are stored but not acted on;
+  the compliance guide shows an observer for review.
+- Rate limits can be exceeded briefly by concurrent sends.
+- Vonage receipts for the second and later parts of a long message are
+  acknowledged but not matched to the delivery.
+- Vonage uses the SMS API, not the newer Messages API, and has no MMS.
+- Telnyx ignores `validity_period`.
 
 ## 10. Risks and mitigations
 
@@ -549,17 +665,22 @@ next. No phase includes a calendar estimate.
 
 ## 11. Open decisions
 
-These do not block Phase 0 or 1 but should be settled before Phase 2:
+Decisions 1 to 3 are settled. Decisions 4 to 6 are proposed as settled in
+Phase 6, matching the implementation; confirm them before tagging 1.0.
 
 1. **Name.** `smswire` is recommended; `textable` and `smsable` are the
    fallbacks. Decide before the pre-release push.
-2. **Body storage default.** Spec says `true` with OTP excluded. Privacy-first
-   alternative is `false` by default.
-3. **UUID vs. bigint** primary keys for the engine tables. Spec leans UUID.
-4. **Phone validation**: `phonelib` soft dependency vs. a vendored minimal
-   E.164 validator.
-5. **Whether `deliver_now` should be allowed in production** or warn, given
-   Noticed's stance that inline delivery slows requests. Spec allows it; the
-   Noticed adapter always uses `deliver_later`.
-6. **MMS in 1.0.** `media_urls` is on the message object; whether adapters
-   must support it for 1.0 is open.
+2. **Body storage default.** Settled in Phase 2: `store_bodies = true`, with
+   `categories: { otp: { store_body: false } }` as the shipped default.
+3. **UUID vs. bigint** primary keys. Settled in Phase 2: the migration follows
+   the app's generator `primary_key_type`, so both work without a choice here.
+4. **Phone validation.** Proposed: both. The built-in validator handles E.164
+   input and North American national formats with no dependency; `phonelib`
+   is used automatically when it is in the bundle, for other regions.
+5. **`deliver_now` in production.** Proposed: allowed without a warning. It
+   returns a `Result`, which is useful for interactive flows such as
+   verification codes. Guides recommend `deliver_later`, and the Noticed
+   adapter always uses it.
+6. **MMS in 1.0.** Proposed: a capability, not a requirement. Twilio and
+   Telnyx send `media_urls`; Vonage's SMS API does not and does not declare
+   `:mms`. The contract does not require it.

data/docs/guides/compliance.md

@@ -0,0 +1,124 @@
+# Compliance primer
+
+This primer explains what Smswire does for SMS compliance, what it leaves to
+you, and which settings matter. It summarizes US rules and industry
+guidance as of 2026 and is not legal advice. Have counsel review your
+messaging program.
+
+## The rules in brief
+
+- **TCPA and FCC rules** govern automated texts in the US. Marketing texts
+  need prior express written consent. Consumers may revoke consent by any
+  reasonable means, and since April 11, 2025 a revocation must be honored
+  within 10 days. One confirmation text is allowed after an opt-out; it must
+  not contain marketing and may ask the person to clarify what they want to
+  stop.
+- **The FCC "revoke all" provision**, which makes an opt-out from one kind of
+  message apply to all of a sender's unrelated messages, is delayed to
+  January 31, 2027.
+- **Quiet hours.** Federal rules restrict telemarketing outside 8am to 9pm in
+  the recipient's local time. Several states are stricter.
+- **CTIA Messaging Principles and Best Practices** are what carriers enforce.
+  They expect opt-out keywords to work regardless of case or punctuation; one
+  confirmation after an opt-out and then silence; HELP replies that name the
+  brand and give a support contact; and consent specific to the program it
+  was collected for.
+- **Carrier registration.** US long codes need 10DLC brand and campaign
+  registration. Toll-free numbers need verification. Unregistered traffic is
+  filtered or blocked.
+
+## What Smswire does
+
+| Requirement | Smswire |
+|---|---|
+| Honor STOP-type replies | STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, OPTOUT (or "opt out"), and REVOKE opt the number out immediately |
+| One confirmation, no marketing | one opt-out reply through the `compliance` category; deduplication blocks repeats inside 10 minutes |
+| HELP reply with brand and contact | HELP and INFO reply with `program_name` and `support_contact` |
+| Re-subscribe | START, YES, and UNSTOP opt back in |
+| Refuse sends to opted-out numbers | every category except `compliance` checks consent first |
+| Marketing needs opt-in | `marketing` requires `opted_in` consent |
+| Quiet hours | `marketing` waits outside 9pm to 8am, recipient time |
+| Carrier opt-outs | a provider "recipient opted out" error records an opt-out |
+| Evidence | consent rows keep source, timestamps, last keyword, and your metadata |
+
+## What you must do
+
+1. **Collect and record opt-in** before marketing. Store the evidence:
+
+   ```ruby
+   Smswire::Consent.opt_in!(user.phone, source: :web_form,
+     metadata: {ip: request.remote_ip, form: "checkout", copy: SMS_TERMS, at: Time.current.iso8601})
+   ```
+
+2. **Set your program name and support contact.**
+
+   ```ruby
+   config.program_name = "Acme Alerts"
+   config.support_contact = "help@acme.example"
+   ```
+
+   Without a contact, HELP replies omit it and Smswire logs a warning.
+
+3. **Route incoming messages to Smswire** at `/smswire/inbound/<provider>`.
+   Without this, STOP replies never reach your app. If your provider handles
+   opt-outs itself, such as Twilio Advanced Opt-Out, Smswire still records
+   them and skips its own reply.
+
+4. **Watch for free-text opt-outs.** Smswire matches keywords only when they
+   are the whole message. "Please stop texting me" is stored but not acted
+   on, yet it is a reasonable revocation. Review unmatched messages:
+
+   ```ruby
+   class OptOutReview
+     def self.sms_received(message)
+       return if message.keyword
+       SupportTicket.create!(phone: message.from_number, body: message.body) if message.body.match?(/\b(stop|unsubscribe|remove me)\b/i)
+     end
+   end
+   Smswire.register_observer(OptOutReview)
+   ```
+
+5. **Honor opt-outs from other channels.** When a customer opts out by email
+   or phone, call `Smswire::Consent.opt_out!(phone, source: :support)`.
+
+6. **Choose consent scopes deliberately.** By default STOP applies to the
+   `consent_scope` of the number that received it, so two programs on two
+   numbers keep separate consent. To make every STOP apply everywhere, as the
+   FCC revoke-all provision will require across a sender's messages, set:
+
+   ```ruby
+   config.opt_out_all_scopes = true
+   ```
+
+7. **Check your categories.** Anything promotional must use
+   `category: :marketing`. Transactional messages skip the opt-in
+   requirement, so mislabeling a promotion as transactional defeats the
+   checks.
+
+8. **Set time zones.** Quiet hours use `recipient.time_zone` when the
+   recipient object has one, and `config.default_time_zone` otherwise.
+
+9. **Register with the carriers** and keep your messages consistent with the
+   registered campaign: brand name in messages, opt-out instructions at least
+   periodically, and content matching the sample messages.
+
+## Settings reference
+
+| Setting | Default | Notes |
+|---|---|---|
+| `enforce_consent` | `true` | turn off only if another system owns consent |
+| `categories` | see README | merged per key over the shipped rules |
+| `keywords` | the lists above | add synonyms, such as `ARRET` |
+| `keyword_replies` | CTIA-style replies | `%{program}` and `%{contact}` are replaced; `nil` sends no reply |
+| `program_name` | the app name | |
+| `support_contact` | none | phone, email, or URL |
+| `opt_out_all_scopes` | `false` | STOP applies to every scope |
+| `default_time_zone` | `Time.zone` | for quiet hours |
+
+## Sources
+
+- [FCC consent revocation order, FCC 24-24](https://docs.fcc.gov/public/attachments/FCC-24-24A1.pdf)
+- [FCC revocation rule effective April 11, 2025 (JD Supra)](https://www.jdsupra.com/legalnews/fcc-s-tcpa-consent-revocation-rule-8022288/)
+- [Revoke-all provision delayed to January 31, 2027 (Wiley)](https://www.wiley.law/alert-FCC-Extends-Limited-Waiver-for-Part-of-the-TCPA-Consent-Revocation-Rule)
+- [CTIA Messaging Principles summary (Bird)](https://bird.com/explained/compliance/what-are-the-ctia-messaging-principles)
+- [Vonage 10DLC traffic compliance](https://api.support.vonage.com/hc/en-us/articles/8443130026140-10DLC-Traffic-compliance)

data/docs/guides/getting-started.md

@@ -0,0 +1,154 @@
+# Getting started
+
+This guide takes a Rails app from no SMS to a tested, previewable message
+with delivery tracking. It assumes Rails 7.1 or newer and Ruby 3.2 or newer.
+
+## Install
+
+```ruby
+# Gemfile
+gem "smswire"
+```
+
+```
+bundle install
+bin/rails generate smswire:install
+bin/rails db:migrate
+```
+
+The install generator:
+
+- copies three tables: `smswire_deliveries`, `smswire_consents`, and
+  `smswire_inbound_messages`;
+- writes `config/initializers/smswire.rb` and `app/messengers/application_messenger.rb`;
+- mounts the engine at `/smswire` in `config/routes.rb`.
+
+Out of the box, development uses the `:log` provider, which writes each
+message to the log, and tests use the `:test` provider, which records
+messages in memory. Nothing is sent until you configure a real provider.
+
+## Configure a sender and a provider
+
+```ruby
+# config/initializers/smswire.rb
+Smswire.configure do |config|
+  config.default_provider = :twilio if Rails.env.production?
+  config.providers = {
+    twilio: {
+      account_sid: Rails.application.credentials.dig(:twilio, :account_sid),
+      auth_token: Rails.application.credentials.dig(:twilio, :auth_token)
+    }
+  }
+  config.senders = {
+    transactional: {number: "+15555550100"}
+  }
+  config.callbacks_url = "https://app.example.com/smswire"
+  config.program_name = "Acme"
+  config.support_contact = "help@acme.example"
+end
+```
+
+Twilio credentials default to `Rails.application.credentials.twilio`, so the
+`providers` entry can be omitted when the credentials file has `account_sid`
+and `auth_token` under `twilio:`. Telnyx and Vonage work the same way under
+`telnyx:` and `vonage:`.
+
+`callbacks_url` is the public URL of the engine mount. With it set, every
+message asks the provider to post delivery status back, and each
+`Smswire::Delivery` row moves from `pending` to `delivered` or `failed`.
+
+## Write a messenger
+
+```
+bin/rails generate smswire:messenger Order shipped
+```
+
+```ruby
+# app/messengers/order_messenger.rb
+class OrderMessenger < ApplicationMessenger
+  def shipped(user)
+    @order = params[:order]
+    text to: user
+  end
+end
+```
+
+```erb
+<%# app/views/order_messenger/shipped.text.erb %>
+Order <%= @order.number %> has shipped. Track it: <%= order_url(@order) %>
+```
+
+`text to:` accepts an E.164 string or any object with `phone_number`. Use
+`config.recipient_resolver` if your column is named differently. URL helpers
+use `Rails.application.routes.default_url_options`, so set a host there.
+
+Send it:
+
+```ruby
+OrderMessenger.with(order:).shipped(user).deliver_later
+```
+
+`deliver_later` is the right default. `deliver_now` runs the pipeline inline
+and returns a `Smswire::Result`:
+
+```ruby
+result = OrderMessenger.with(order:).shipped(user).deliver_now
+result.status        # :accepted, :failed, :duplicate, :rejected_opted_out, ...
+result.delivery      # the Smswire::Delivery row
+```
+
+## Preview it
+
+Open `http://localhost:3000/smswire/previews`. The generator wrote a preview
+in `test/messengers/previews/order_messenger_preview.rb`; point it at real
+records:
+
+```ruby
+class OrderMessengerPreview < Smswire::Preview
+  def shipped
+    OrderMessenger.with(order: Order.last).shipped(User.first)
+  end
+end
+```
+
+Each preview shows the message in a phone frame with its encoding, segment
+count, and remaining characters, and names any character that forces UCS-2,
+which cuts a segment from 160 characters to 70. The inbox at
+`/smswire/inbox` shows what development sent and lets you simulate a reply
+such as STOP.
+
+## Test it
+
+```ruby
+class OrderTest < ActiveSupport::TestCase
+  include Smswire::TestHelper
+
+  test "shipping texts the customer" do
+    assert_sms_delivered(to: users(:ada).phone_number, messenger: OrderMessenger, body: /has shipped/) do
+      orders(:one).ship!
+    end
+  end
+end
+```
+
+Inside the block, `deliver_later` jobs are performed. RSpec users can
+`require "smswire/rspec"` for `deliver_sms` and `have_enqueued_sms`.
+
+## Point the provider at the webhooks
+
+| Webhook | URL |
+|---|---|
+| Delivery status | sent automatically per message when `callbacks_url` is set |
+| Incoming messages | `https://app.example.com/smswire/inbound/<provider>` |
+
+Incoming messages are needed for STOP, START, and HELP handling. Read the
+[compliance primer](compliance.md) before sending marketing messages.
+
+## Before production
+
+- Set `config.default_provider` and real credentials.
+- Run `Smswire.verify_credentials!` from a boot check or health endpoint.
+- In staging, register `Smswire::Interceptors::Allowlist` so only your team's
+  numbers receive messages.
+- Register your sender with the carriers: 10DLC brand and campaign
+  registration for US long codes, or toll-free verification.