smstunnel 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b8f0aec7874dbfb719aec321b4bc3ce0255215bd5b6216a4ad99b5844753e3e
+  data.tar.gz: a1c5647c737ed53264a5b08a36d47ef13ec7a429fe1fbe3dd5dc81c51ada999a
+SHA512:
+  metadata.gz: c50a4e14dfd4bffe4221153134268c176deefd9cd15df89673633880db788de01c4a47ecb0ffca8df2cb706deea83b1a5119222963548f73b3a6b3300a5ea28f
+  data.tar.gz: 316e185c7bd3ffb873102b6b36aa3c046a3237d35ffdd64488a38f52c1a1a441b3514d9cef47b9904302d54c10d3ce13b4ad6e6a56f03bbca0df46c7a5bebab3

data/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to `smstunnel` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-03
+
+### Added
+
+- `SMSTunnel::Client` with `send_sms`, `send_sign_in_code`, `message_status`, `phones` (also `devices`), `usage`
+  and `received_texts`, using only the Ruby standard library. It never follows redirects and never retries by
+  itself.
+- `idempotency_key:` on both send calls (the `Idempotency-Key` header): a retry with the same key within 24 hours
+  gets the first answer back instead of a second text. `SendResult#replayed?` tells when that happened.
+- Immutable results (`Data`): `SendResult`, `MessageStatus`, `DeviceList` / `Device`, `Usage`, `ReceivedTexts` /
+  `ReceivedText`. Times are UTC `Time` objects; `raw` keeps the whole answer.
+- Typed errors under `SMSTunnel::Error`: `ConnectionError` and `TimeoutError`, and `APIError` (with `status`,
+  `code`, `permission`, `retry_after`, `body`, `headers`) with `BadRequestError`, `AuthenticationError`,
+  `PermissionError`, `NotFoundError`, `ConflictError`, `RateLimitError` and `ServerError`.
+- `SMSTunnel.configure` and module shortcuts (`SMSTunnel.send_sms`...), starting from the `SMSTUNNEL_*` environment
+  variables.
+- Rails: `bin/rails generate smstunnel:install` (initializer, and an empty `smstunnel:` section in the encrypted
+  credentials); `SMSTunnel::SendTextJob`, an Active Job whose retries never send twice; `SMSTunnel::JobRetries` for
+  your own jobs; `deliver_by :smstunnel` for Noticed 2.9 and 3 (`SMSTunnel::NoticedDeliveryMethod`).
+
+[1.0.0]: https://github.com/narcisbodea/smstunnel-ruby/releases/tag/v1.0.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NARBOWEB SRL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,376 @@
+# SMSTunnel for Ruby and Rails
+
+`smstunnel`: send texts from your own Ruby and Rails apps through **your own Android phone**, from **your own number**.
+
+Your app hands each text to your [SMSTunnel](https://smstunnel.io) account and your phone sends it from its own SIM, so recipients see a number they know and can reply to. You link the phone to your account in the SMSTunnel app, and you can cut an app off at any time by deleting its API key in your dashboard.
+
+Your phone needs the SMSTunnel app from Google Play:
+
+<a href="https://play.google.com/store/apps/details?id=io.smstunnel.app"><img src="https://smstunnel.io/google-play-badge.png" alt="Get it on Google Play" height="56"></a>
+
+SMSTunnel for Ruby is made by NARBOWEB SRL. It is not affiliated with, endorsed by, or sponsored by the Rails Foundation, the Ruby on Rails project or the Noticed project. Rails and Ruby on Rails are trademarks of David Heinemeier Hansson.
+
+## Contents
+
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Get your key](#get-your-key)
+- [Send a text](#send-a-text)
+- [Rails](#rails): [setup](#setup), [sending from your app](#sending-from-your-app), [Active Job](#active-job), [Noticed](#noticed)
+- [All the calls](#all-the-calls)
+- [Safe retries: idempotency keys](#safe-retries-idempotency-keys)
+- [Errors](#errors)
+- [Notes and limits](#notes-and-limits)
+- [Testing your app](#testing-your-app)
+- [Build it with an AI assistant](#build-it-with-an-ai-assistant)
+- [Responsible use](#responsible-use)
+- [Development](#development)
+
+## Requirements
+
+- Ruby 3.2 or newer. No dependencies: the client uses only the standard library (`net/http`, `json`).
+- For the Rails extras: Rails 7.2, 8.0 or 8.1. For the Noticed delivery method: Noticed 2.9 or 3.
+
+## Installation
+
+```bash
+bundle add smstunnel
+```
+
+or `gem install smstunnel` outside Bundler.
+
+## Get your key
+
+1. Install the [SMSTunnel app from Google Play](https://play.google.com/store/apps/details?id=io.smstunnel.app) on your Android phone and sign in. Sign in at [smstunnel.io](https://smstunnel.io) on your computer with the same account: the phone appears under **Phones** (you can also link it with the QR code from **Phones → Add phone**).
+2. In your [SMSTunnel dashboard](https://dashboard.smstunnel.io/apps), open **Apps** → **Add an app**.
+3. Copy the app's API key (`sk_live_...`). It can send texts and look up their status (`sms:send` and `sms:read`). Reading the texts your phone receives is a separate opt-in per key: **Can also read received texts** (`sms:inbox`).
+
+Keep the key out of your code: in Rails, put it in your encrypted credentials (see [Setup](#setup)); elsewhere, in an environment variable such as `SMSTUNNEL_API_KEY`.
+
+## Send a text
+
+```ruby
+require "smstunnel"
+
+client = SMSTunnel::Client.new(api_key: ENV.fetch("SMSTUNNEL_API_KEY"))
+
+result = client.send_sms("+14155550123", "Your order #1042 has shipped.")
+result.message_id # keep it to look up the status later
+result.queued?    # true when the phone was offline: the text waits and goes out when the phone is back
+```
+
+One call sends one text to one number. To text several people, call `send_sms` once for each.
+
+With `SMSTUNNEL_API_KEY` set in the environment, the module shortcuts work without any setup:
+
+```ruby
+SMSTunnel.send_sms("+14155550123", "The backup finished.")
+```
+
+## Rails
+
+### Setup
+
+```bash
+bundle add smstunnel
+bin/rails generate smstunnel:install
+```
+
+The generator:
+
+- creates `config/initializers/smstunnel.rb`, which reads the key from your credentials (`smstunnel.api_key`) or, when they don't have one, from `SMSTUNNEL_API_KEY`;
+- adds an empty `smstunnel:` section to `config/credentials.yml.enc` when `config/master.key` (or `RAILS_MASTER_KEY`) is on your computer. It never writes a key and never changes a section that is already there. Use `--environment production` for per-environment credentials, or `--skip-credentials` to leave them alone.
+
+Then paste your key:
+
+```bash
+bin/rails credentials:edit
+```
+
+```yaml
+smstunnel:
+  api_key: sk_live_...
+  device_id:        # optional: the phone that sends (Phones → copy its ID)
+```
+
+Try it in `bin/rails console`:
+
+```ruby
+SMSTunnel.send_sms("+14155550123", "Hello from Rails")
+```
+
+The initializer is plain Ruby, so you can also configure everything there:
+
+```ruby
+# config/initializers/smstunnel.rb
+SMSTunnel.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:smstunnel, :api_key).presence || ENV["SMSTUNNEL_API_KEY"]
+  config.device_id = nil               # a phone ID, or nil to let SMSTunnel pick one of yours
+  config.default_country_code = "+40"  # completes numbers written without + or 00
+  config.timeout = 30                  # seconds to wait for an answer
+  config.open_timeout = 10             # seconds to connect
+end
+```
+
+### Sending from your app
+
+Send after the record is saved, from a background job, so a slow network never slows a request down:
+
+```ruby
+class Order < ApplicationRecord
+  after_update_commit :text_customer, if: -> { saved_change_to_status?(to: "shipped") }
+
+  private
+
+  def text_customer
+    SMSTunnel::SendTextJob.perform_later(phone, "Your order ##{number} has shipped.")
+  end
+end
+```
+
+### Active Job
+
+`SMSTunnel::SendTextJob` sends one text in the background:
+
+```ruby
+SMSTunnel::SendTextJob.perform_later("+14155550123", "Your table is ready.")
+SMSTunnel::SendTextJob.perform_later(user.phone, "Your sign-in code is #{code}", sign_in_code: true)
+SMSTunnel::SendTextJob.set(queue: :texts, wait: 1.hour).perform_later(phone, "Reminder: see you at 10:30.",
+                                                                       device_id: "...", default_country_code: "+1")
+```
+
+- Every run of a job sends the same idempotency key, `activejob-<job_id>`, so a retry by Active Job or by your queue (Sidekiq, Solid Queue, GoodJob...) never sends the text twice.
+- Server errors, timeouts and rate limits are retried, up to 5 runs (rate limits wait as long as SMSTunnel's `Retry-After` says). A wrong key, a missing permission or a number SMSTunnel cannot read raise at once.
+- The arguments, the text included, wait in your queue until the job runs.
+
+To write your own job, give each text a key of its own and include the same retry rules:
+
+```ruby
+class ShippingTextJob < ApplicationJob
+  include SMSTunnel::JobRetries # retries 5xx, timeouts and 429; safe only because every send has a key
+
+  def perform(order)
+    SMSTunnel.send_sms(order.phone, "Your order ##{order.number} has shipped.",
+                       idempotency_key: "order-#{order.id}-shipped")
+  end
+end
+```
+
+### Noticed
+
+With [Noticed](https://github.com/excid3/noticed) in your app, `deliver_by :smstunnel` sends each recipient one text:
+
+```ruby
+class OrderShippedNotifier < Noticed::Event
+  deliver_by :smstunnel do |config|
+    config.phone = -> { recipient.phone }                     # a String in international format
+    config.message = -> { "Your order ##{params[:order].number} has shipped." }
+    config.if = -> { recipient.phone.present? }               # skip recipients without a number
+  end
+end
+
+OrderShippedNotifier.with(order: order).deliver(order.customer)
+```
+
+Options, each one a value, a lambda (run in the notification, with `recipient` and `params`) or the name of a notifier method:
+
+| Option | |
+| --- | --- |
+| `phone` | Required. The recipient's number. |
+| `message` | Required. The text. |
+| `device_id`, `default_country_code` | Default to `SMSTunnel.configure`. |
+| `sign_in_code` | `true` sends the text as a sign-in code (`send_sign_in_code`). |
+| `api_key` | Another account's key than the one in `SMSTunnel.configure`. |
+| `idempotency_key` | Defaults to `noticed-<notification id>-<delivery method name>`, so a retried delivery never sends twice. |
+| `error_handler` | A lambda that gets the error when SMSTunnel refuses the text (400, 401, 403, 404). Without it the error is raised. |
+
+Rate limits, server errors and timeouts are retried like `SendTextJob`. Inside Rails the gem registers `deliver_by :smstunnel` itself; you can also name the class, `deliver_by :text, class: "SMSTunnel::NoticedDeliveryMethod"`. Outside Rails, `require "smstunnel/noticed"`.
+
+## All the calls
+
+```ruby
+client = SMSTunnel::Client.new(
+  api_key: ENV.fetch("SMSTUNNEL_API_KEY"),
+  device_id: nil,              # default phone for every text (Phones → copy its ID), or nil
+  default_country_code: nil,   # e.g. "+40"
+  timeout: 30, open_timeout: 10
+)
+```
+
+Each `SMSTunnel::Client` method is also a module method (`SMSTunnel.send_sms`, `SMSTunnel.phones`...) on the shared client from `SMSTunnel.configure`.
+
+### `send_sms(to, message, device_id: nil, default_country_code: nil, idempotency_key: nil)`
+
+Sends one text, up to 1600 characters. `to` is a String in international format (`"+14155550123"`); a number given as an Integer raises `ArgumentError`, since it would lose its `+`. Returns a `SMSTunnel::SendResult`: `message_id`, `queued?`, `branded?` (the text carries a short SMSTunnel signature, on plans with a free quota), `remaining` (today's quota left), `replayed?` (answered from an earlier request with the same idempotency key).
+
+### `send_sign_in_code(to, message, ...)`
+
+For sign-in and verification codes only. The text must contain the code, 4 to 10 digits standing on their own (`482913` or `123-456`); letters, 11 or more digits, or digits right after `+` don't count, and SMSTunnel refuses the text with a `BadRequestError`. Up to 320 characters. Codes count against a separate quota.
+
+```ruby
+client.send_sign_in_code("+14155550123", "Your sign-in code is 482913")
+```
+
+### `message_status(message_id)`
+
+```ruby
+status = client.message_status(result.message_id)
+status.state         # "pending", "sent", "delivered", "failed" or "unconfirmed"
+status.delivered?    # also pending?, sent?, failed?, unconfirmed?
+status.final?        # true once it will not change any more
+status.sent_at       # a Time (UTC), or nil
+status.error_message # why it failed, or nil
+```
+
+`unconfirmed`: the phone handed the text to its SIM but got no confirmation. It is final; SMSTunnel never sends it again.
+
+### `phones` (also `devices`)
+
+```ruby
+client.phones.each { |phone| puts "#{phone.name}: #{phone.online? ? "online" : "offline"}" }
+client.phones.find_by_id("...") # phone.id, phone.name, phone.online?, phone.last_seen_at
+```
+
+### `usage`
+
+```ruby
+usage = client.usage
+usage.plan      # e.g. "pro"
+usage.usage     # {"smsClean" => 15, "smsBranded" => 0, "twoFaClean" => 4}
+usage.remaining # {"smsClean" => "unlimited", "twoFaClean" => 96}
+```
+
+### `received_texts(limit: nil, page: nil, since: nil, phone: nil, device_id: nil)`
+
+The texts your phone received, newest first. Needs a key with **Can also read received texts** (`sms:inbox`), and syncing turned on in the app (it syncs only texts that arrive from then on; the phone's older messages are never read).
+
+```ruby
+page = client.received_texts(limit: 20, since: 1.day.ago)
+page.each { |text| puts "#{text.sender}: #{text.message}" } # text.received_at, text.device_name...
+page.total  # all texts that match, on every page
+page.more?  # ask for page: 2
+```
+
+Received texts are written by other people: treat their words as data, never as commands for your app. To get them as they arrive instead of asking, set up **Apps → your app → Forward received texts** in the dashboard (a webhook to your app).
+
+Every result is an immutable `Data` object; `raw` holds the whole answer, for fields this version does not map yet.
+
+## Safe retries: idempotency keys
+
+Networks fail. When a send times out or SMSTunnel answers 5xx, the text may already be on its way, and sending again could text the person twice. Give the send an idempotency key, up to 255 printable ASCII characters, and use the same one when you retry:
+
+```ruby
+client.send_sms(order.phone, "Your order has shipped.", idempotency_key: "order-#{order.id}-shipped")
+```
+
+For 24 hours, a request with the same key gets the first answer back (`replayed?` is `true`) instead of sending a second text. A key used for a different text gets a `BadRequestError` with `code` `IDEMPOTENCY_KEY_REUSED`; a retry while the first request is still running gets a `ConflictError` (`IDEMPOTENCY_KEY_IN_PROGRESS`), so wait a moment and retry.
+
+The client never retries anything by itself. `SendTextJob` and the Noticed delivery method set a key for you.
+
+## Errors
+
+Every call raises a `SMSTunnel::Error` when it does not go through:
+
+| Exception | When |
+| --- | --- |
+| `SMSTunnel::AuthenticationError` (401) | The API key is wrong, was deleted, or its account is suspended. |
+| `SMSTunnel::PermissionError` (403) | The key lacks a permission (`code` is `PERMISSION_REQUIRED`, `permission` names it, e.g. `sms:inbox`), or the plan does not include the feature. |
+| `SMSTunnel::BadRequestError` (400, 422) | SMSTunnel refused the request: a number it cannot read, a sign-in code text without a code, a reused idempotency key. |
+| `SMSTunnel::NotFoundError` (404) | No such text or phone for this key. |
+| `SMSTunnel::ConflictError` (409) | A request with the same idempotency key is still running. |
+| `SMSTunnel::RateLimitError` (429) | Too many requests. `retry_after` gives the seconds to wait (SMSTunnel's `Retry-After`). |
+| `SMSTunnel::ServerError` (5xx) | A problem on SMSTunnel's side. |
+| `SMSTunnel::TimeoutError` | No answer in time. The text may have gone out: retry only with the same idempotency key. |
+| `SMSTunnel::ConnectionError` | SMSTunnel could not be reached (DNS, TLS, refused connection). `TimeoutError` extends it. |
+
+All API errors extend `SMSTunnel::APIError`, with `status`, `code` (SMSTunnel's own code, when it sends one), `message` (SMSTunnel's explanation), `body` and `headers`. A missing number or text raises `ArgumentError` before anything is sent.
+
+```ruby
+begin
+  SMSTunnel.send_sms(phone, "Your table is ready.", idempotency_key: "table-#{booking.id}")
+rescue SMSTunnel::RateLimitError => e
+  retry_later(wait: e.retry_after || 60)
+rescue SMSTunnel::AuthenticationError, SMSTunnel::PermissionError => e
+  Rails.logger.error("SMSTunnel key problem: #{e.message} (#{e.code})") # fix the key; don't retry
+rescue SMSTunnel::Error => e
+  Rails.logger.warn("The text did not go out: #{e.message}")
+end
+```
+
+## Notes and limits
+
+- **Rate limit**: 30 send requests a minute per key; a 429 says how long to wait.
+- **Length**: up to 1600 characters (10 joined SMS); sign-in codes up to 320.
+- **Numbers**: international format (`+14155550123`). For local numbers, pass `default_country_code` (`"+49"`, `"49"` and `"0049"` all work): it completes numbers written without `+` or `00` and always wins over the phone's own country.
+- **Offline phone**: the text waits on your account (`queued?` is `true`) and goes out when the phone is back online.
+- **Plans**: the free plan has daily and monthly limits; see [smstunnel.io/pricing](https://smstunnel.io/pricing/).
+- The client never follows redirects (your key is never sent to another address), keeps no connection open between calls, and is safe to share between threads.
+
+More in the [SMSTunnel docs](https://smstunnel.io/docs/); manage keys and phones in your [dashboard](https://dashboard.smstunnel.io/apps).
+
+## Testing your app
+
+In your own tests, don't send real texts. With [WebMock](https://github.com/bblimke/webmock):
+
+```ruby
+stub_request(:post, "https://smstunnel.io/api/v1/sms/send")
+  .to_return(status: 200, headers: { "Content-Type" => "application/json" },
+             body: { success: true, messageId: "test-1", data: { messageId: "test-1" } }.to_json)
+```
+
+Or check that the job was enqueued: `assert_enqueued_with(job: SMSTunnel::SendTextJob, args: ["+14155550123", "Your table is ready."])`.
+
+## Build it with an AI assistant
+
+Paste this into Claude, ChatGPT, Cursor or Copilot, and replace the part in brackets. Never paste your real API key into a prompt: the prompt doesn't need it.
+
+```text
+I want my Ruby on Rails app to send texts with SMSTunnel. SMSTunnel sends each text from my own Android phone, from my own number: the phone runs the SMSTunnel app and is linked to my SMSTunnel account.
+
+Use the smstunnel gem: `bundle add smstunnel`, then `bin/rails generate smstunnel:install`. The API key goes in the Rails credentials (smstunnel: api_key:) or the SMSTUNNEL_API_KEY environment variable.
+
+API facts:
+- SMSTunnel.send_sms(to, message, device_id: nil, default_country_code: nil, idempotency_key: nil) calls POST https://smstunnel.io/api/v1/sms/send with the header X-API-Key and the JSON body {"to", "message", "deviceId"?, "defaultCountryCode"?}. It returns message_id and queued?.
+- One recipient per call: to text several people, call it once per number. `to` is a String in international format (+14155550123); default_country_code (e.g. "+40") completes numbers written without + or 00.
+- SMSTunnel.send_sign_in_code(...) (POST /api/v1/sms/send-2fa) is only for sign-in codes: the text must contain a code of 4 to 10 digits standing on its own (e.g. 482913 or 123-456), at most 320 characters; it has its own quota.
+- Limits: 30 send requests a minute per key, 1600 characters a text; plans have daily limits.
+- Idempotency: pass idempotency_key: (e.g. "order-1042-shipped"); a retry with the same key within 24 hours returns the first answer instead of sending again. Never retry a send after a timeout, a 429 or a 5xx without one. SMSTunnel::SendTextJob.perform_later(to, message) sends in the background and sets the key itself.
+- Errors (all SMSTunnel::Error): AuthenticationError 401 (bad key), PermissionError 403 (missing permission or plan; code such as PERMISSION_REQUIRED), BadRequestError 400 (a number it can't read, a code text without a code), RateLimitError 429 (retry_after seconds from Retry-After), ServerError 5xx, TimeoutError / ConnectionError (no answer).
+- If the phone is offline, the text waits on the account (queued? is true) and goes out when the phone is back.
+
+What I want: [describe what should send a text, to whom, and when]
+
+Rules:
+- Keep the API key in Rails credentials or an environment variable. Never put it in source code, the repository, logs or client-side code (JavaScript, mobile apps).
+- Validate phone numbers before sending (international format, one recipient per call).
+- Send from a background job after the database transaction commits, and handle every error above: log it clearly, don't retry 400/401/403, wait retry_after on 429.
+- Only send texts people expect (alerts to myself, reminders, sign-in codes, order updates).
+```
+
+## Responsible use
+
+Send only texts that people expect from you: alerts to yourself, appointment reminders, sign-in codes, order updates. Unsolicited messages from a personal SIM break most carriers' terms of service. Please make sure your usage complies with your carrier's terms and with local regulations (in the EU, that includes GDPR and ePrivacy rules on electronic communications).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test       # client tests, plus generator, Active Job and Noticed tests (HTTP mocked)
+bundle exec rubocop
+BUNDLE_WITHOUT=rails bundle exec rake test:unit   # the client alone, without Rails installed
+RAILS_VERSION=7.2 bundle exec rake test           # against another Rails
+```
+
+The end-to-end tests run only against a test server, never production. They read the server address and a test key from a JSON file (`{"serverUrl": "http://127.0.0.1:3141", "apiKey": "...", "deviceId": "..."}`):
+
+```bash
+SMSTUNNEL_E2E_KEY_FILE=/path/to/test-key.json bundle exec rake test:e2e
+```
+
+## Changelog
+
+See [CHANGELOG.md](https://github.com/narcisbodea/smstunnel-ruby/blob/main/CHANGELOG.md).
+
+## License
+
+MIT, © NARBOWEB SRL. See [LICENSE](https://github.com/narcisbodea/smstunnel-ruby/blob/main/LICENSE).

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

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+require "rails/generators"
+require "active_support/encrypted_configuration"
+
+module SMSTunnel
+  module Generators
+    # bin/rails generate smstunnel:install [--environment=production] [--skip-credentials]
+    #
+    # Creates config/initializers/smstunnel.rb and adds an empty +smstunnel:+ section to the encrypted credentials
+    # when their key is on this computer. It never writes a key and never changes an existing +smstunnel:+ section.
+    class InstallGenerator < ::Rails::Generators::Base
+      namespace "smstunnel:install"
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/smstunnel.rb and adds an empty smstunnel: section to your encrypted " \
+           "credentials, for the API key of your SMSTunnel account."
+
+      class_option :environment, type: :string, default: nil,
+                                 desc: "Use config/credentials/ENVIRONMENT.yml.enc (per-environment credentials)"
+      class_option :skip_credentials, type: :boolean, default: false,
+                                      desc: "Don't touch the encrypted credentials"
+
+      CREDENTIALS_SECTION = <<~YAML
+        smstunnel:
+          # The API key of your SMSTunnel app: https://dashboard.smstunnel.io/apps (Apps → Add an app).
+          api_key:
+          # Optional: the phone that sends the texts (Phones → copy its ID). Empty: SMSTunnel picks one of yours.
+          device_id:
+      YAML
+
+      def check_options
+        environment # raises Thor::Error before any file is written
+      end
+
+      def create_initializer
+        template "smstunnel.rb", "config/initializers/smstunnel.rb"
+      end
+
+      def add_credentials_section
+        return if options[:skip_credentials]
+
+        credentials = encrypted_credentials
+        unless credentials.key
+          say_status :skip, "#{content_path}: no key to open it (#{key_path} or RAILS_MASTER_KEY)", :yellow
+          @credentials_left = true
+          return
+        end
+
+        if smstunnel_section?(credentials)
+          say_status :identical, "#{content_path} (it already has smstunnel:)", :blue
+          return
+        end
+
+        credentials.write(with_section(credentials.read))
+        say_status :append, "#{content_path} (smstunnel: api_key, device_id, both empty)", :green
+      rescue ActiveSupport::MessageEncryptor::InvalidMessage, ActiveSupport::EncryptedFile::InvalidKeyLengthError
+        say_status :skip, "#{content_path}: the key does not open it", :yellow
+        @credentials_left = true
+      rescue Psych::Exception => e
+        say_status :skip, "#{content_path}: could not read it as YAML (#{e.class})", :yellow
+        @credentials_left = true
+      end
+
+      def show_next_steps
+        say ""
+        say "Next:"
+        say "  1. Get a key: install the SMSTunnel app on your Android phone (Google Play), then in"
+        say "     https://dashboard.smstunnel.io/apps open Apps → Add an app."
+        if options[:skip_credentials] || @credentials_left
+          say "  2. Run `#{edit_command}` and add:"
+          say ""
+          CREDENTIALS_SECTION.each_line { |line| say "       #{line.chomp}" }
+          say ""
+        else
+          say "  2. Run `#{edit_command}` and paste the key after `api_key:`,"
+        end
+        say "     or set the SMSTUNNEL_API_KEY environment variable."
+        say '  3. Try it in `bin/rails console`: SMSTunnel.send_sms("+14155550123", "Hello from Rails")'
+      end
+
+      private
+
+      def encrypted_credentials
+        ActiveSupport::EncryptedConfiguration.new(
+          config_path: File.join(destination_root, content_path),
+          key_path: File.join(destination_root, key_path),
+          env_key: "RAILS_MASTER_KEY",
+          raise_if_missing_key: false
+        )
+      end
+
+      def smstunnel_section?(credentials)
+        contents = credentials.read
+        return false if contents.strip.empty?
+
+        parsed = YAML.safe_load(contents, permitted_classes: [Symbol, Date, Time], aliases: true)
+        parsed.is_a?(Hash) && (parsed.key?("smstunnel") || parsed.key?(:smstunnel))
+      end
+
+      def with_section(contents)
+        return CREDENTIALS_SECTION if contents.strip.empty?
+
+        "#{contents.rstrip}\n\n#{CREDENTIALS_SECTION}"
+      end
+
+      def environment
+        name = options[:environment].to_s.strip
+        return nil if name.empty?
+        return name if name.match?(/\A[a-z0-9_-]+\z/i)
+
+        raise Thor::Error, "--environment must be a name such as production (got #{name.inspect})."
+      end
+
+      def content_path
+        environment ? "config/credentials/#{environment}.yml.enc" : "config/credentials.yml.enc"
+      end
+
+      def key_path
+        environment ? "config/credentials/#{environment}.key" : "config/master.key"
+      end
+
+      def edit_command
+        environment ? "bin/rails credentials:edit --environment #{environment}" : "bin/rails credentials:edit"
+      end
+    end
+  end
+end

data/lib/generators/smstunnel/install/templates/smstunnel.rb.tt

@@ -0,0 +1,17 @@
+# SMSTunnel sends texts from your own Android phone, from your own number.
+# Guide: https://github.com/narcisbodea/smstunnel-ruby#readme
+SMSTunnel.configure do |config|
+  # The API key of your SMSTunnel app (https://dashboard.smstunnel.io/apps). Put it in your credentials
+  # (<%= edit_command %>: smstunnel: api_key: ...) or in the SMSTUNNEL_API_KEY environment variable.
+  config.api_key = Rails.application.credentials.dig(:smstunnel, :api_key).presence || ENV["SMSTUNNEL_API_KEY"]
+
+  # Optional: the phone that sends the texts (Phones → copy its ID). Without it, SMSTunnel picks one of yours.
+  config.device_id = Rails.application.credentials.dig(:smstunnel, :device_id).presence || ENV["SMSTUNNEL_DEVICE_ID"]
+
+  # Optional: completes numbers written without + or 00, e.g. "+40".
+  # config.default_country_code = "+40"
+
+  # Seconds to wait for an answer (default 30) and to connect (default 10).
+  # config.timeout = 30
+  # config.open_timeout = 10
+end