smswire 0.0.1.pre → 0.1.0

data/app/models/smswire/delivery.rb

@@ -0,0 +1,157 @@
+module Smswire
+  # One outbound SMS, from claim through provider status callbacks.
+  #
+  # Status lifecycle: pending, then queued / accepted / sent from the
+  # provider, then delivered, undelivered, or failed, and optionally read.
+  # suppressed means an interceptor cancelled it. Status only moves forward,
+  # so out-of-order callbacks are ignored.
+  class Delivery < ApplicationRecord
+    STATUSES = %w[pending suppressed queued accepted sent delivered undelivered failed read].freeze
+    PROGRESS = {
+      "pending" => 0, "suppressed" => 0, "queued" => 1, "accepted" => 2, "sent" => 3,
+      "delivered" => 4, "undelivered" => 4, "failed" => 4, "read" => 5
+    }.freeze
+    RECLAIMABLE = %w[pending failed suppressed].freeze
+    TERMINAL_FAILURES = %w[undelivered failed].freeze
+
+    # A claim older than this is treated as abandoned by a crashed worker.
+    CLAIM_TIMEOUT = 2.minutes
+
+    enum :status, STATUSES.index_with(&:itself)
+
+    belongs_to :recipient, polymorphic: true, optional: true
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :for_number, ->(number) { where(to_number: number) }
+
+    class << self
+      # Create or reuse the delivery row for +message+ and claim it for
+      # sending. Returns nil when an identical message was already sent
+      # inside the dedupe window, or another worker holds the claim.
+      def claim_for(message, provider:)
+        key = Smswire.config.dedupe_window ? message.idempotency_key : nil
+
+        if key && (existing = find_by(idempotency_key: key))
+          if existing.created_at < Smswire.config.dedupe_window.ago
+            where(id: existing.id, idempotency_key: key).update_all(idempotency_key: nil)
+          else
+            return existing.claim
+          end
+        end
+
+        create!(attributes_for(message, provider:).merge(
+          idempotency_key: key, status: "pending", attempts: 1, claimed_at: Time.current
+        ))
+      rescue ActiveRecord::RecordNotUnique
+        nil
+      end
+
+      # Apply a provider status callback. Looks up by delivery id when the
+      # callback URL carried one, falling back to the provider message id.
+      def apply_status_update(update, provider:, delivery_id: nil)
+        delivery = find_by(id: delivery_id, provider: provider.to_s) if delivery_id.present?
+        if delivery.nil? || (delivery.provider_id.present? && delivery.provider_id != update.provider_id)
+          delivery = find_by(provider: provider.to_s, provider_id: update.provider_id)
+        end
+        delivery&.advance!(update.status, provider_id: update.provider_id,
+          error_code: update.error_code, error_message: update.error_message)
+        delivery
+      end
+
+      def attributes_for(message, provider:)
+        record = message.recipient&.record
+        {
+          messenger: message.messenger,
+          action: message.action,
+          to_number: message.to,
+          from_number: message.from,
+          messaging_service: message.messaging_service,
+          recipient: (record if record.is_a?(ActiveRecord::Base) && record.persisted?),
+          category: message.category.to_s,
+          body: (message.body if Smswire.config.store_body?(message.category)),
+          segments: message.segments,
+          encoding: message.encoding.to_s,
+          provider: provider.to_s,
+          metadata: message.metadata.presence
+        }
+      end
+    end
+
+    # Atomically claim a reusable row for another send attempt.
+    def claim
+      return nil unless RECLAIMABLE.include?(status)
+
+      now = Time.current
+      claimed = self.class
+        .where(id:, status: RECLAIMABLE)
+        .where("claimed_at IS NULL OR claimed_at < ?", now - CLAIM_TIMEOUT)
+        .update_all(["claimed_at = ?, attempts = attempts + 1, status = 'pending', " \
+                     "error_code = NULL, error_message = NULL, failed_at = NULL, updated_at = ?", now, now])
+      reload if claimed == 1
+    end
+
+    def record_receipt!(receipt, message)
+      now = Time.current
+      with_lock do
+        assign_attributes(final_message_attributes(message))
+        assign_attributes(provider_id: receipt.provider_id, segments: receipt.segments || message.segments,
+          price_amount: receipt.price_amount, price_currency: receipt.price_currency,
+          sent_at: now, claimed_at: nil)
+        apply_status(receipt.status.to_s, now) if progresses_to?(receipt.status)
+        save!
+      end
+    end
+
+    def record_failure!(error, message)
+      update!(final_message_attributes(message).merge(
+        status: "failed", error_code: error.provider_code, error_message: error.message,
+        failed_at: Time.current, status_updated_at: Time.current, claimed_at: nil
+      ))
+    end
+
+    # Release the claim after a transient error so a retry can reclaim it.
+    def release!(error)
+      update!(claimed_at: nil, error_code: error.provider_code, error_message: error.message)
+    end
+
+    def record_suppression!(message)
+      update!(final_message_attributes(message).merge(status: "suppressed", claimed_at: nil, status_updated_at: Time.current))
+    end
+
+    def advance!(new_status, provider_id: nil, error_code: nil, error_message: nil)
+      with_lock do
+        self.provider_id ||= provider_id
+        if progresses_to?(new_status)
+          apply_status(new_status.to_s, Time.current)
+          self.error_code = error_code if error_code.present?
+          self.error_message = error_message if error_message.present?
+        end
+        save!
+      end
+    end
+
+    def progresses_to?(new_status)
+      PROGRESS.fetch(new_status.to_s) > PROGRESS.fetch(status)
+    end
+
+    private
+
+    def apply_status(new_status, at)
+      self.status = new_status
+      self.status_updated_at = at
+      self.delivered_at = at if new_status == "delivered"
+      self.failed_at = at if TERMINAL_FAILURES.include?(new_status)
+    end
+
+    def final_message_attributes(message)
+      {
+        to_number: message.to,
+        from_number: message.from,
+        messaging_service: message.messaging_service,
+        body: (message.body if Smswire.config.store_body?(message.category)),
+        segments: message.segments,
+        encoding: message.encoding.to_s
+      }
+    end
+  end
+end

data/app/models/smswire/inbound_message.rb

@@ -0,0 +1,25 @@
+module Smswire
+  # A message received from a provider webhook. Webhook retries for the
+  # same provider message id are recorded once.
+  class InboundMessage < ApplicationRecord
+    KEYWORDS = %w[stop start help].freeze
+
+    scope :recent, -> { order(created_at: :desc) }
+
+    # Returns the new record, or nil when this provider message id was
+    # already received.
+    def self.receive(inbound, provider:)
+      create!(
+        provider: provider.to_s,
+        provider_id: inbound.provider_id,
+        from_number: PhoneNumber.normalize(inbound.from) || inbound.from,
+        to_number: inbound.to,
+        messaging_service: inbound.messaging_service,
+        body: inbound.body,
+        raw: inbound.raw
+      )
+    rescue ActiveRecord::RecordNotUnique
+      nil
+    end
+  end
+end

data/app/views/layouts/smswire/application.html.erb

@@ -0,0 +1,60 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title><%= content_for?(:title) ? yield(:title) : "Smswire" %></title>
+  <%= csrf_meta_tags %>
+  <style>
+    :root { --bg: #f6f7f9; --panel: #fff; --text: #1d2330; --muted: #667085; --line: #e3e6ea;
+            --accent: #2f6fed; --bubble: #e9ecf1; --warn-bg: #fff4e5; --warn: #8a4b00; --ok: #137333; --bad: #b3261e; --on-accent: #fff; }
+    @media (prefers-color-scheme: dark) {
+      :root { --bg: #14161a; --panel: #1c1f25; --text: #e6e8eb; --muted: #9aa3af; --line: #2c313a;
+              --accent: #7aa2ff; --bubble: #2a2f38; --warn-bg: #3a2a12; --warn: #ffcc80; --ok: #81c995; --bad: #f28b82; --on-accent: #10131a; }
+    }
+    * { box-sizing: border-box; }
+    body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.5 system-ui, -apple-system, sans-serif; }
+    header { display: flex; gap: 20px; align-items: baseline; padding: 14px 24px; border-bottom: 1px solid var(--line); background: var(--panel); }
+    header strong { font-size: 17px; }
+    header a { color: var(--muted); text-decoration: none; }
+    header a.active, header a:hover { color: var(--accent); }
+    main { max-width: 1040px; margin: 0 auto; padding: 24px 16px 48px; }
+    h1 { font-size: 22px; margin: 0 0 16px; }
+    h2 { font-size: 16px; margin: 28px 0 10px; }
+    a { color: var(--accent); }
+    .panel { background: var(--panel); border: 1px solid var(--line); border-radius: 10px; padding: 16px; }
+    .muted { color: var(--muted); }
+    .flash { padding: 10px 14px; border-radius: 8px; margin-bottom: 16px; background: var(--warn-bg); color: var(--warn); }
+    table { width: 100%; border-collapse: collapse; }
+    th, td { text-align: left; padding: 8px 10px; border-bottom: 1px solid var(--line); vertical-align: top; }
+    th { font-weight: 600; color: var(--muted); font-size: 13px; }
+    .table-wrap { overflow-x: auto; }
+    .table-wrap table { min-width: 680px; }
+    .preview { display: grid; grid-template-columns: minmax(0, 340px) minmax(0, 1fr); gap: 24px; align-items: start; }
+    @media (max-width: 720px) { .preview { grid-template-columns: 1fr; } }
+    .phone { background: var(--panel); border: 1px solid var(--line); border-radius: 28px; padding: 24px 16px; min-height: 320px; }
+    .bubble { background: var(--bubble); border-radius: 18px 18px 18px 4px; padding: 10px 14px; white-space: pre-wrap; overflow-wrap: anywhere; }
+    .warn { background: var(--warn-bg); color: var(--warn); border-radius: 8px; padding: 10px 14px; margin-top: 16px; }
+    .status { font-weight: 600; }
+    .status-delivered, .status-accepted, .status-queued, .status-sent, .status-read { color: var(--ok); }
+    .status-failed, .status-undelivered { color: var(--bad); }
+    .body { white-space: pre-wrap; overflow-wrap: anywhere; max-width: 420px; }
+    form.inline { display: grid; grid-template-columns: repeat(auto-fit, minmax(min(180px, 100%), 1fr)); gap: 10px; align-items: end; }
+    label { display: grid; gap: 4px; font-size: 13px; color: var(--muted); }
+    input { font: inherit; padding: 8px 10px; border: 1px solid var(--line); border-radius: 6px; background: var(--bg); color: var(--text); }
+    button, input[type="submit"] { font: inherit; padding: 8px 14px; border: 0; border-radius: 6px; background: var(--accent); color: var(--on-accent); cursor: pointer; }
+    code { font-size: 13px; }
+  </style>
+</head>
+<body>
+  <header>
+    <strong>Smswire</strong>
+    <% if Smswire.config.show_previews %><%= link_to "Previews", previews_path, class: ("active" if controller_name == "previews") %><% end %>
+    <% if Smswire.config.show_inbox %><%= link_to "Inbox", inbox_path, class: ("active" if controller_name == "inbox") %><% end %>
+  </header>
+  <main>
+    <% flash.each do |_type, text| %><div class="flash"><%= text %></div><% end %>
+    <%= yield %>
+  </main>
+</body>
+</html>

data/app/views/smswire/inbox/index.html.erb

@@ -0,0 +1,56 @@
+<% content_for :title, "SMS inbox" %>
+<h1>SMS inbox</h1>
+
+<div class="panel">
+  <strong>Simulate a reply</strong>
+  <p class="muted">Runs the same handling as the inbound webhook, including STOP, START, and HELP.</p>
+  <%= form_with url: inbox_inbound_path, class: "inline" do |form| %>
+    <label>From <%= form.text_field :from, placeholder: "+15555550100" %></label>
+    <label>To <%= form.text_field :to, value: @default_to %></label>
+    <label>Body <%= form.text_field :body, placeholder: "STOP" %></label>
+    <%= form.submit "Receive" %>
+  <% end %>
+</div>
+
+<h2>Sent</h2>
+<div class="panel table-wrap">
+  <% if @deliveries.empty? %>
+    <span class="muted">Nothing sent yet.</span>
+  <% else %>
+    <table>
+      <tr><th>When</th><th>To</th><th>Message</th><th>Status</th><th>Details</th></tr>
+      <% @deliveries.each do |delivery| %>
+        <tr id="delivery_<%= delivery.id %>">
+          <td><%= time_ago_in_words(delivery.created_at) %> ago</td>
+          <td><%= delivery.to_number %></td>
+          <td class="body"><%= delivery.body || content_tag(:span, "(body not stored)", class: "muted") %></td>
+          <td class="status status-<%= delivery.status %>"><%= delivery.status %></td>
+          <td class="muted">
+            <%= [delivery.messenger, delivery.action].compact.join("#") %><br>
+            <%= delivery.category %> · <%= pluralize(delivery.segments.to_i, "segment") %> · <%= delivery.provider %>
+            <% if delivery.error_message.present? %><br><%= delivery.error_code %> <%= delivery.error_message %><% end %>
+          </td>
+        </tr>
+      <% end %>
+    </table>
+  <% end %>
+</div>
+
+<h2>Received</h2>
+<div class="panel table-wrap">
+  <% if @inbound_messages.empty? %>
+    <span class="muted">Nothing received yet.</span>
+  <% else %>
+    <table>
+      <tr><th>When</th><th>From</th><th>Message</th><th>Keyword</th></tr>
+      <% @inbound_messages.each do |message| %>
+        <tr>
+          <td><%= time_ago_in_words(message.created_at) %> ago</td>
+          <td><%= message.from_number %></td>
+          <td class="body"><%= message.body %></td>
+          <td><%= message.keyword&.upcase %></td>
+        </tr>
+      <% end %>
+    </table>
+  <% end %>
+</div>

data/app/views/smswire/previews/index.html.erb

@@ -0,0 +1,21 @@
+<% content_for :title, "SMS previews" %>
+<h1>SMS previews</h1>
+<% if @previews.empty? %>
+  <p class="muted">No previews found. Add classes ending in <code>Preview</code> under
+    <%= safe_join(Smswire.config.preview_paths.map { |path| content_tag(:code, path) }, " or ") %>,
+    or run <code>bin/rails generate smswire:messenger</code>.</p>
+<% end %>
+<% @previews.each do |preview| %>
+  <h2><%= preview.preview_name.camelize %></h2>
+  <div class="panel">
+    <% if preview.messages.empty? %>
+      <span class="muted">No public methods.</span>
+    <% else %>
+      <ul>
+        <% preview.messages.each do |name| %>
+          <li><%= link_to name, preview_path(path: "#{preview.preview_name}/#{name}") %></li>
+        <% end %>
+      </ul>
+    <% end %>
+  </div>
+<% end %>

data/app/views/smswire/previews/show.html.erb

@@ -0,0 +1,34 @@
+<% content_for :title, "#{@preview.preview_name.camelize}##{@message_name}" %>
+<p><%= link_to "All previews", previews_path %></p>
+<h1><%= @preview.preview_name.camelize %>#<%= @message_name %></h1>
+
+<% if @message.nil? %>
+  <div class="panel muted">This action returned without calling <code>text</code>, so nothing would be sent.</div>
+<% else %>
+  <div class="preview">
+    <div class="phone">
+      <div class="bubble"><%= @message.body %></div>
+      <% @message.media_urls.each do |url| %>
+        <p class="muted">Media: <%= link_to url, url %></p>
+      <% end %>
+    </div>
+    <div class="panel">
+      <table>
+        <tr><th>To</th><td><%= @message.to %></td></tr>
+        <tr><th>From</th><td><%= @message.from || @message.messaging_service || "(default)" %></td></tr>
+        <tr><th>Category</th><td><%= @message.category %></td></tr>
+        <tr><th>Provider</th><td><%= @message.provider || Smswire.config.default_provider %></td></tr>
+        <tr><th>Encoding</th><td data-encoding><%= @analysis.encoding_label %></td></tr>
+        <tr><th>Segments</th><td data-segments><%= pluralize(@analysis.segments, "segment") %></td></tr>
+        <tr><th>Length</th><td><%= @analysis.units %> units, <%= @analysis.remaining %> left in this segment</td></tr>
+      </table>
+      <p><%= link_to "Raw text", preview_path(path: params[:path], raw: 1) %></p>
+    </div>
+  </div>
+  <% if @non_gsm.any? %>
+    <div class="warn" data-non-gsm>
+      These characters switch the message to UCS-2, which fits 70 units per segment instead of 160:
+      <code><%= @non_gsm.join(" ") %></code>
+    </div>
+  <% end %>
+<% end %>

data/config/routes.rb

@@ -0,0 +1,10 @@
+Smswire::Engine.routes.draw do
+  post "status/:provider", to: "status_callbacks#create", as: :status_callback
+  post "inbound/:provider", to: "inbound_messages#create", as: :inbound_message
+
+  # Development tools; each answers 404 unless enabled.
+  get "previews", to: "previews#index", as: :previews
+  get "previews/*path", to: "previews#show", as: :preview, format: false
+  get "inbox", to: "inbox#index", as: :inbox
+  post "inbox/inbound", to: "inbox#receive", as: :inbox_inbound
+end

data/db/migrate/20261008000000_create_smswire_deliveries.rb

@@ -0,0 +1,47 @@
+class CreateSmswireDeliveries < ActiveRecord::Migration[7.1]
+  def change
+    primary_key_type, foreign_key_type = primary_and_foreign_key_types
+
+    create_table :smswire_deliveries, id: primary_key_type do |t|
+      t.string :messenger
+      t.string :action
+      t.string :to_number, null: false
+      t.string :from_number
+      t.string :messaging_service
+      t.references :recipient, polymorphic: true, type: foreign_key_type, index: true
+      t.string :category, null: false
+      t.text :body
+      t.integer :segments
+      t.string :encoding
+      t.string :provider, null: false
+      t.string :provider_id
+      t.string :status, null: false, default: "pending"
+      t.string :error_code
+      t.text :error_message
+      t.string :idempotency_key
+      t.decimal :price_amount, precision: 12, scale: 5
+      t.string :price_currency
+      t.json :metadata
+      t.integer :attempts, null: false, default: 0
+      t.datetime :claimed_at
+      t.datetime :sent_at
+      t.datetime :delivered_at
+      t.datetime :failed_at
+      t.datetime :status_updated_at
+      t.timestamps
+    end
+
+    add_index :smswire_deliveries, [:provider, :provider_id], unique: true
+    add_index :smswire_deliveries, :idempotency_key, unique: true
+    add_index :smswire_deliveries, [:to_number, :created_at]
+    add_index :smswire_deliveries, [:status, :created_at]
+  end
+
+  private
+
+  def primary_and_foreign_key_types
+    config = Rails.configuration.generators
+    setting = config.options[config.orm][:primary_key_type]
+    [setting || :primary_key, setting || :bigint]
+  end
+end

data/db/migrate/20261008000001_create_smswire_consents_and_inbound_messages.rb

@@ -0,0 +1,34 @@
+class CreateSmswireConsentsAndInboundMessages < ActiveRecord::Migration[7.1]
+  def change
+    primary_key_type = Rails.configuration.generators.options[Rails.configuration.generators.orm][:primary_key_type]
+
+    create_table :smswire_consents, id: primary_key_type || :primary_key do |t|
+      t.string :phone, null: false
+      t.string :scope, null: false, default: "default"
+      t.string :status, null: false, default: "unknown"
+      t.string :source
+      t.datetime :opted_in_at
+      t.datetime :opted_out_at
+      t.string :last_keyword
+      t.datetime :last_keyword_at
+      t.json :metadata
+      t.timestamps
+    end
+    add_index :smswire_consents, [:phone, :scope], unique: true
+
+    create_table :smswire_inbound_messages, id: primary_key_type || :primary_key do |t|
+      t.string :provider, null: false
+      t.string :provider_id, null: false
+      t.string :from_number, null: false
+      t.string :to_number
+      t.string :messaging_service
+      t.text :body
+      t.string :keyword
+      t.datetime :handled_at
+      t.json :raw
+      t.timestamps
+    end
+    add_index :smswire_inbound_messages, [:provider, :provider_id], unique: true
+    add_index :smswire_inbound_messages, [:from_number, :created_at]
+  end
+end