short_message 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f916f657d8160e670f3557e3419605b40dc214151bfb596de9215be72d531d3
-  data.tar.gz: 24380097ac98b0c0c45dee6503f14c7e0cedaacf8461f439e4b9ef3ba2cec7d6
+  metadata.gz: 84df6eda6507a99c19b2389c62b3d1bfd1f7624a87aed826533c6162ced857a3
+  data.tar.gz: 18a283ab3dd2cf9a49eb8170c38d51f0a8dafd4b2105d43f088b4a3aeffd7f60
 SHA512:
-  metadata.gz: 271e4a3c1fb3714ca093544ef7c381f854432905bd841384948677a6b0255f0f0ad1bbbcb8eaed0a728a60181a5ab9f4d5c5935e2dfd244013eee48c6723f03d
-  data.tar.gz: a0dad5f6eebdf7161cd4f08b6cde79b9e40e2f4ba9e2eec09eb9ff40fd662d1675c3c7b507c68092ecbb1def34e8efb2eadf05045f5a481dc7adbdd7417ffbb0
+  metadata.gz: a0f5a7a88e8480910af30ff20be783fbbf8abc73fa41dee4dd8a29ddb4346040588d7effd776ea3e699f6ee4ba2be82bccd0b8245a5454a35e22d38c13248834
+  data.tar.gz: 321c0fc81da7c2d44b727a9481442ab89ff10ecd3f75b92e120fa1894efe626edf95529e97889c16efc28c2cea9a11b95de9a752db3179293148bf8e37773e45

data/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+## 2.0.0 - 2026-06-09
+
+### Breaking Changes
+- Removed legacy GTX v1 user/pass delivery mode.
+- Removed legacy configuration keys: gateway_server, gateway_port, send_file_path, account_functions_path, user, password.
+- Delivery now requires api_key and uses GTX REST API v2 endpoint semantics.
+- Removed legacy customization hook based on build_deliver_params_string.
+- Updated runtime requirements to Ruby 3.2+ and Rails 6.1+.
+
+### Added
+- Delivery metadata persistence fields and indexes:
+  - provider_http_status
+  - provider_status
+  - provider_response_body
+  - unique index on message_key
+- Optional callback token validation for status endpoint.
+- Tests for delivery success/failure and callback authorization.
+
+### Changed
+- Improved HTTP/TLS safety defaults and timeout configuration.
+- Development/test DB defaults now use sqlite3 in dummy app.
+- Updated Rails compatibility to support Rails 8 (gemspec constraint raised to `< 9.0`).
+- `error_notification` mailer now renders a clean error summary instead of serializing the raw HTTP response object.
+- `payment_required_notification` mailer now references `api_base_url` instead of the removed `gateway_server` config key.
+
+### Removed
+- Dropped all Rails 4/5 compatibility shims: `skip_filter`, `render text:`, and the `deliver_method` version guard.
+- Removed `require_dependency` usage (removed in Rails 7).
+- Removed unused `param_name` metaprogramming from `Configuration`.
+- Raised initial migration version from `[4.2]` to `[6.1]`.

data/README.md

@@ -2,74 +2,420 @@
 
 [![Gem Version](https://badge.fury.io/rb/short_message.png)](http://badge.fury.io/rb/short_message)
 
+ShortMessage is a Rails Engine that sends SMS messages via the GTX Messaging REST API v2 and receives delivery status callbacks.
+
+**Requires:** Ruby >= 3.2, Rails >= 6.1
+
+---
+
+## Table of Contents
+
+- [ShortMessage](#shortmessage)
+  - [Table of Contents](#table-of-contents)
+  - [Installation](#installation)
+  - [Configuration](#configuration)
+    - [Configuration reference](#configuration-reference)
+  - [Usage](#usage)
+    - [Message attributes](#message-attributes)
+  - [Delivery Reports](#delivery-reports)
+  - [Events](#events)
+    - [`short_message.delivered`](#short_messagedelivered)
+    - [`short_message.status_updated`](#short_messagestatus_updated)
+  - [Email Notifications](#email-notifications)
+  - [Customization](#customization)
+    - [Status code labels](#status-code-labels)
+    - [Extending the request payload](#extending-the-request-payload)
+  - [Development](#development)
+    - [Testing DLR callbacks locally](#testing-dlr-callbacks-locally)
+  - [Building \& Releasing](#building--releasing)
+  - [Local Development (using in another project)](#local-development-using-in-another-project)
+  - [Upgrade Guide (1.x → 2.0)](#upgrade-guide-1x--20)
+  - [License](#license)
+
+---
+
 ## Installation
 
-Add it to your Gemfile:
+Add to your Gemfile:
 
 ```ruby
 gem 'short_message'
 ```
 
-Run the following command to install it:
+Install dependencies:
 
 ```console
 bundle install
 ```
 
-Run the generator:
+Run the install generator:
 
 ```console
 rails generate short_message:install
 ```
 
-And run the migrations:
+Copy and run the migrations:
 
 ```console
-rake db:migrate
+bundle exec rails railties:install:migrations FROM=short_message
+bundle exec rails db:migrate
+```
+
+---
+
+## Configuration
+
+The generator creates `config/initializers/short_message.rb`. Edit it to suit your setup:
+
+```ruby
+ShortMessage.configure do |config|
+  # --- Required ---
+  config.api_base_url    = "https://rest.gtx-messaging.net"
+  config.api_key         = ENV.fetch("GTX_API_KEY")
+  config.response_format = "json"   # "json", "xml", or "plain"
+
+  # --- SMS defaults ---
+  config.default_sms_sender = "MyApp"   # sender name or number used when none is set on the message
+
+  # --- Delivery reports (DLR) ---
+  config.dlr_mask        = 3            # 1 = delivered, 2 = undelivered, 3 = both
+  config.callback_token  = ENV["SHORT_MESSAGE_CALLBACK_TOKEN"]
+  config.dlr_url         = "https://example.com/short_message/messages/status?token=#{config.callback_token}"
+
+  # --- HTTP timeouts ---
+  config.open_timeout = 5    # seconds
+  config.read_timeout = 30   # seconds
+
+  # --- Email notifications (optional) ---
+  config.default_mail_sender       = "sms@example.com"
+  config.admin_notification_email  = "admin@example.com"   # set nil to disable error emails
+  config.reload_notification_email = "billing@example.com" # notified on HTTP 402 from GTX
+end
 ```
 
+### Configuration reference
+
+| Key                         | Required | Default                            | Description                                        |
+| --------------------------- | -------- | ---------------------------------- | -------------------------------------------------- |
+| `api_base_url`              | yes      | `"https://rest.gtx-messaging.net"` | GTX API endpoint                                   |
+| `api_key`                   | yes      | —                                  | GTX API authentication key                         |
+| `response_format`           | no       | `"json"`                           | `"json"`, `"xml"`, or `"plain"`                    |
+| `default_sms_sender`        | no       | —                                  | Fallback sender when none is set on the message    |
+| `dlr_mask`                  | no       | `3`                                | Delivery report event mask                         |
+| `dlr_url`                   | no       | —                                  | Callback URL GTX posts status updates to           |
+| `callback_token`            | no       | —                                  | Token validated on incoming status callbacks       |
+| `open_timeout`              | no       | `5`                                | HTTP connection open timeout (seconds)             |
+| `read_timeout`              | no       | `30`                               | HTTP read timeout (seconds)                        |
+| `default_mail_sender`       | no       | —                                  | From address for notification emails               |
+| `admin_notification_email`  | no       | —                                  | Receives error notifications; set `nil` to disable |
+| `reload_notification_email` | no       | —                                  | Receives payment-required (HTTP 402) alerts        |
+
+---
+
 ## Usage
 
-Create a message and deliver it:
+Create a `ShortMessage::Message` and call `deliver`:
 
 ```ruby
-@sms = ShortMessage::Message.new(sender: "0041791234567", recipient: "0041799876543", text: "Hello World!")
-@sms.deliver
+sms = ShortMessage::Message.new(
+  sender:    "+41791234567",   # or a name up to 11 chars
+  recipient: "+41799876543",
+  text:      "Hello World!"
+)
+
+sms.deliver   # => true on success, false on failure
+```
+
+`sender` is optional when `config.default_sms_sender` is configured.
+
+Recipient normalization: if `recipient` starts with `00`, the gem automatically converts it to `+` format (for example `0041791234567` -> `+41791234567`). Any other non-E.164 recipient format is rejected before sending.
+
+After a successful delivery, `sms.message_key` holds the provider-assigned message ID and `sms.provider_http_status` holds the HTTP status code returned by GTX.
+
+### Message attributes
+
+| Attribute                | Description                                     |
+| ------------------------ | ----------------------------------------------- |
+| `sender`                 | SMS sender name or number                       |
+| `recipient`              | SMS recipient phone number in E.164 (`+...`)    |
+| `text`                   | Message body                                    |
+| `message_key`            | Unique ID assigned by GTX after delivery        |
+| `status_code`            | Delivery status code (updated via DLR callback) |
+| `provider_http_status`   | HTTP status from GTX at delivery time           |
+| `provider_status`        | Status string from GTX response                 |
+| `provider_response_body` | Full raw response payload from GTX              |
+| `error_code`             | Error code if delivery failed                   |
+| `error_message`          | Error description if delivery failed            |
+| `submitted_at`           | Timestamp when message was submitted to GTX     |
+| `delivered_at`           | Timestamp when delivery confirmed               |
+
+---
+
+## Delivery Reports
+
+ShortMessage mounts a status-update endpoint at `/short_message/messages/status`. Configure GTX to POST (or GET) to this URL with the message ID and status:
+
+```
+POST /short_message/messages/status?id=<message_key>&status=<code>&token=<callback_token>
 ```
 
-## Delivery Report
+| Parameter | Description                                  |
+| --------- | -------------------------------------------- |
+| `id`      | The `message_key` of the message to update   |
+| `status`  | Numeric status code from GTX                 |
+| `token`   | Required when `config.callback_token` is set |
+
+**Response codes**
+
+| HTTP | Meaning                            |
+| ---- | ---------------------------------- |
+| 200  | Status updated successfully        |
+| 400  | Missing `id` or `status` parameter |
+| 401  | Invalid or missing callback token  |
+| 404  | Message not found                  |
+
+When `config.callback_token` is set, every incoming callback must include `token=<value>` or it will be rejected with a 401.
+
+---
 
-ShortMessage listens for status updates on `/short_message/messages/status`. Provide `:id` and `:status` by either `POST` or `GET`.
+## Events
+
+ShortMessage fires `ActiveSupport::Notifications` events so you can react to delivery and status changes without monkey-patching.
+
+### `short_message.delivered`
+
+Fired after a message is successfully sent to GTX.
+
+```ruby
+ActiveSupport::Notifications.subscribe('short_message.delivered') do |name, start, finish, id, payload|
+  Rails.logger.info "SMS #{payload[:key]} delivered"
+end
+```
+
+Payload keys: `key` (the `message_key` assigned by GTX).
+
+### `short_message.status_updated`
+
+Fired when a delivery report callback is received.
+
+```ruby
+ActiveSupport::Notifications.subscribe('short_message.status_updated') do |name, start, finish, id, payload|
+  Activity.create(
+    message: "Message #{payload[:key]} status → #{payload[:status]}"
+  )
+end
+```
+
+Payload keys: `key` (message ID), `status` (new status code).
+
+---
+
+## Email Notifications
+
+When `admin_notification_email` is configured, ShortMessage sends an email on delivery failure or unexpected exceptions. Set it to `nil` to disable.
+
+When `reload_notification_email` is configured, ShortMessage sends an email when GTX returns HTTP 402 (payment required / credit exhausted).
+
+---
 
 ## Customization
 
-### Status Codes
+### Status code labels
 
-If you need to customize the status response codes simply edit the internationalization files in config/locales
+Status code descriptions are stored in locale files under `config/locales/`. Add or override keys there to customise the text returned by `message.status_text`.
 
-### Params
+```yaml
+# config/locales/short_message.en.yml
+en:
+  short_message:
+    status:
+      code_1:  "Delivered to handset"
+      code_2:  "Delivery failed"
+      code_4:  "Queued on SMSC"
+      code_8:  "Delivered to SMSC"
+      code_16: "Not delivered to SMSC"
+```
 
-To override the params string add the code below into `config/initializers/short_message.rb`:
+```ruby
+sms.status_text   # => "Delivered to handset"
+```
+
+### Extending the request payload
+
+Override `build_deliver_params_hash` in an initializer to add or change parameters sent to GTX:
 
 ```ruby
 ShortMessage::Message.module_eval do
   private
-  def build_deliver_params_string
-    # your code here
-  end
 
-  def build_recharge_params_string amount
-    # your code here
+  def build_deliver_params_hash
+    super.merge("coding" => 2)   # e.g. enable UCS-2 encoding
   end
 end
 ```
 
-### Events
+---
 
-ShortMessage sends event notifications on message delivery `short_message.delivered` and on status update `short_message.status_updated`. Add following code to an initializer to listen:
+## Development
+
+Clone the repo and install dependencies:
+
+```console
+git clone https://github.com/asaurer/short_message.git
+cd short_message
+bundle install
+```
+
+Run the test suite (migrations run automatically):
+
+```console
+bundle exec rake test
+```
+
+### Testing DLR callbacks locally
+
+GTX needs a publicly reachable HTTPS URL to deliver status callbacks. Use [ngrok](https://ngrok.com) to expose your local server:
+
+```console
+ngrok http 3000
+```
+
+Then configure the tunnel URL in your initializer:
 
 ```ruby
-ActiveSupport::Notifications.subscribe('short_message.status_updated') do |name, start, finish, id, payload|
-  Activity.create(successful: true, message: "Message #{payload[:options][:key]} has now status #{payload[:options][:status]}.")
-end
+config.callback_token = "dev-secret"
+config.dlr_url = "https://abc123.ngrok.io/short_message/messages/status?token=dev-secret"
+```
+
+Restart your Rails server after changing the initializer. Once a message is delivered, GTX will POST the status update to the ngrok URL which forwards it to your local app.
+
+You can also simulate a callback manually without ngrok:
+
+```console
+curl -X POST "http://localhost:3000/short_message/messages/status" \
+  -d "id=YOUR_MESSAGE_KEY&status=1&token=dev-secret"
+```
+
+Replace `YOUR_MESSAGE_KEY` with the value of `sms.message_key` after calling `sms.deliver`.
+
+---
+
+## Building & Releasing
+
+Build the gem locally:
+
+```console
+gem build short_message.gemspec
+```
+
+This creates `short_message-<version>.gem` in the project root.
+
+Install the built gem locally to verify it works:
+
+```console
+gem install short_message-<version>.gem
+```
+
+Push to RubyGems:
+
+```console
+gem push short_message-<version>.gem
+```
+
+You need a [RubyGems account](https://rubygems.org) with push access to the `short_message` gem. Credentials are stored in `~/.gem/credentials`.
+
+**Release checklist:**
+
+1. Update `lib/short_message/version.rb` with the new version number
+2. Update `CHANGELOG.md` with the release notes
+3. Commit the version bump and changelog
+4. Build and push the gem
+5. Tag the release: `git tag v<version> && git push origin v<version>`
+
+---
+
+## Local Development (using in another project)
+
+When you want to work on `short_message` and test changes inside a host Rails app simultaneously, point the host app's Gemfile at your local checkout instead of RubyGems:
+
+```ruby
+# host-app/Gemfile
+gem 'short_message', path: '/path/to/short_message'
+```
+
+Then in the host app:
+
+```console
+bundle install
+```
+
+Bundler symlinks the gem from the local path, so every change you make in the `short_message` directory is picked up immediately on the next request (or `reload!` in the console) without re-running `bundle install`.
+
+If the gem has pending migrations that need to land in the host app's database:
+
+```console
+bundle exec rails railties:install:migrations FROM=short_message
+bundle exec rails db:migrate
+```
+
+To re-generate the initializer or locales after making changes to the generator templates:
+
+```console
+bundle exec rails generate short_message:install
 ```
+
+When you are done and want to switch back to the published gem, restore the Gemfile entry:
+
+```ruby
+gem 'short_message', '~> 2.0'
+```
+
+---
+
+## Upgrade Guide (1.x → 2.0)
+
+1. Replace old GTX config keys with `api_base_url`, `api_key`, and `response_format`.
+2. Remove any initializer override of `build_deliver_params_string` (renamed to `build_deliver_params_hash`).
+3. Install and run the new migration:
+
+   ```console
+   bundle exec rails railties:install:migrations FROM=short_message
+   bundle exec rails db:migrate
+   ```
+
+   If the `short_message_messages` table already
+   exists you will see `Mysql2::Error: Table 'short_message_messages' already exists`.
+   This happens because `railties:install:migrations` re-copies the original
+   create migration under a new timestamp. Mark it as already applied, then migrate:
+  
+   ```bash
+   bundle exec rails runner \
+     "ActiveRecord::Base.connection.execute(
+       \"INSERT IGNORE INTO schema_migrations (version) \" \
+       \"VALUES ('$(ls db/migrate/*create_short_message_messages.short_message.rb \
+         | grep -oP '[0-9]+(?=_)')' )\")"
+   bundle exec rails db:migrate
+   ```
+  
+   SQLite users: replace `INSERT IGNORE` with `INSERT OR IGNORE`.
+
+4. Optionally refresh the initializer and locales:
+
+   ```console
+   bundle exec rails generate short_message:install
+   ```
+
+5. Configure delivery reports — set `config.dlr_url` to your callback endpoint and `config.callback_token` for request validation:
+
+   ```ruby
+   config.callback_token = ENV["SHORT_MESSAGE_CALLBACK_TOKEN"]
+   config.dlr_url        = "https://your-app.example/short_message/messages/status?token=#{config.callback_token}"
+   ```
+
+   In the GTX portal, ensure delivery report callbacks are enabled for your API key and that your app's callback URL is publicly reachable over HTTPS.
+
+---
+
+## License
+
+MIT — see [MIT-LICENSE](MIT-LICENSE).

data/Rakefile

@@ -18,9 +18,6 @@ APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
 load 'rails/tasks/engine.rake'
 
 
-load 'rails/tasks/statistics.rake'
-
-
 
 Bundler::GemHelper.install_tasks
 
@@ -33,5 +30,7 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = false
 end
 
+Rake::Task[:test].enhance(["app:db:migrate"])
+
 
 task default: :test

data/app/controllers/short_message/messages_controller.rb

@@ -1,29 +1,44 @@
-require_dependency "short_message/application_controller"
-
 module ShortMessage
   class MessagesController < ApplicationController
+    skip_before_action :verify_authenticity_token, only: :status
+
     def status
-      unless params[:id].blank? or params[:status].blank?
-        if message = ShortMessage::Message.where(message_key: params[:id]).first
-          message.status_code = params[:status]
-          message.save!
-
-          ActiveSupport::Notifications.instrument('short_message.status_updated', options: { key: params[:id], status: params[:status] })
-          message = "Message #{params[:id]} has now status #{params[:status]}"
-        else
-          message = "Message #{params[:id]} not found!"
-          status = 404
-        end
-      else
-        message = "Message ID or status not provided!"
-        status = 400
+      if callback_token_invalid?
+        return render plain: "Unauthorized", status: :unauthorized
       end
 
-      if Rails.version[0].to_i > 4
-        render plain: message, status: status
-      else
-        render text: message, status: status
+      message_id = params[:id] || params[:"message-id"]
+      dlr_mask = params[:"dlr-mask"]
+      error_code = params[:"error-code"]
+
+      return render plain: "OK", status: :ok if message_id.blank?
+
+      record = ShortMessage::Message.find_by(message_key: message_id)
+      return render plain: "OK", status: :ok unless record
+
+      update_params = {}
+      update_params[:status_code] = dlr_mask.to_i if dlr_mask.present?
+
+      # Only store error fields if error-code is not "0000" (success)
+      if error_code.present? && error_code != "0000"
+        update_params[:error_code] = error_code
+        update_params[:error_message] = params[:"error-message"] if params[:"error-message"].present?
       end
+
+      update_params[:submitted_at] = params[:"submit-date"] if params[:"submit-date"].present?
+      update_params[:delivered_at] = params[:"done-date"] if params[:"done-date"].present?
+
+      record.update(update_params)
+      render plain: "OK", status: :ok
+    end
+
+    private
+
+    def callback_token_invalid?
+      expected_token = ShortMessage.config.callback_token.to_s
+      return false if expected_token.empty?
+
+      params[:token].to_s != expected_token
     end
   end
 end

data/app/mailers/short_message/application_mailer.rb

@@ -0,0 +1,6 @@
+module ShortMessage
+  class ApplicationMailer < ActionMailer::Base
+    default from: -> { ShortMessage.config.default_mail_sender }
+    layout false
+  end
+end

data/app/mailers/short_message/mailer.rb

@@ -1,11 +1,25 @@
 module ShortMessage
   class Mailer < ApplicationMailer
-    def error_notification message, response
-      mail to: ShortMessage.config.admin_notification_email, subject: "Error delivering SMS to #{message.recipient}", body: "SMS from #{message.sender} to #{message.recipient} could not be sent!\r\n\r\nResponse: #{response.to_yaml}"
+    def error_notification(message, response_or_error)
+      details = if response_or_error.respond_to?(:code)
+        "HTTP #{response_or_error.code}: #{response_or_error.body.to_s.truncate(500)}"
+      else
+        "#{response_or_error.class}: #{response_or_error.message}"
+      end
+
+      mail(
+        to: ShortMessage.config.admin_notification_email,
+        subject: "Error delivering SMS to #{message.recipient}",
+        body: "SMS from #{message.sender} to #{message.recipient} could not be sent!\r\n\r\nResponse: #{details}"
+      )
     end
 
     def payment_required_notification
-      mail to: ShortMessage.config.reload_notification_email, subject: "SMS Gateway requires payment", body: "Your SMS Gateway API #{ShortMessage.config.gateway_server} requires payment!"
+      mail(
+        to: ShortMessage.config.reload_notification_email,
+        subject: "SMS Gateway requires payment",
+        body: "Your SMS Gateway API (#{ShortMessage.config.api_base_url}) requires payment!"
+      )
     end
   end
 end

data/app/models/short_message/application_record.rb

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