pink-house-sms-sender 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e314dfc5e9603195c8a2a0856b3ad8dbadfffb05385e3f8cc6a3de30a5b5ce3
+  data.tar.gz: 320b578a16f4fa37b6b310128cdc3355d622973a6a22bfb62a1cfc4677dbdbae
+SHA512:
+  metadata.gz: b3edba5ba1dc4a4d29133d9b09b7fdbf287c7aa491bc5bf671a1c7b4bd591e5caea95fdc5c88ad8738a25b2651b50cd7152a254d1927e335626f5d233aee0bcf
+  data.tar.gz: 156726c35e889348db6e87abb26ff796f80fc191cdd5f966629ad0459b95711021e47a48b0f9fe34b0baa56541971d99152a4887cb9b4b96d4e045ace2088d0e

data/CHANGELOG.md

@@ -0,0 +1,30 @@
+## [Unreleased]
+
+### Added
+
+- Support multiple named instances of the same SMS provider adapter with
+  independent settings and runtime state.
+- Mark Infobip as an advisory `unsupported` provider after live delivery
+  verification could not be completed.
+- Identify catalog providers with advisory `support_level` metadata; values are
+  informational and never prevent provider use.
+- Add the `Sms::Sender` API backed by shared `sender-core` contracts while
+  preserving legacy require paths.
+- Add provider configuration, lazy loading, capability filtering, and
+  adapters for TextBee, Semaphore, Twilio, and Infobip.
+- Add a standard-library HTTP transport with JSON and form serialization,
+  configurable timeouts, normalized transport errors, and credential
+  redaction.
+- Add provider-neutral routing with deterministic election, bounded failover,
+  circuit protection, health tracking, and attempt history.
+- Add immutable delivery events and state updates for receipt integrations.
+- Add dependency-free structured observability events for elections, attempts,
+  failovers, and circuit transitions.
+
+### Quality
+
+- Add focused tests, concurrency coverage, RBS signatures, and the
+  `bundle exec rake` quality harness with 100% YARD documentation coverage.
+- Add gem metadata and publishing configuration.
+- Add environment-based provider selection, default-provider priority, and
+  JSON provider settings configuration.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"sms-sender" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["kenneth.c.demanawa@gmail.com"](mailto:"kenneth.c.demanawa@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ken C. Demanawa
+
+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,230 @@
+# sms-sender
+
+`sms-sender` is a Ruby gem for provider-neutral SMS delivery. It is designed
+to let applications use one domain API while provider adapters handle the
+details of individual HTTP APIs.
+
+The project uses thin, lazily loaded provider adapters and a shared runtime
+for health-aware provider selection, controlled failover, circuit breaking,
+capability filtering, and normalized delivery results and errors.
+
+## Origin
+
+`sms-sender` was extracted from the Pink House SaaS project so its SMS
+delivery capability could be reused independently of the application. Shared
+delivery contracts and runtime behavior live in
+[`sender-core`](https://github.com/kanutocd/sender-core); this gem owns SMS
+validation, provider adapters, and SMS-specific request and response mapping.
+
+## Installation
+
+Add the gem to your application's Gemfile:
+
+```ruby
+gem "sms-sender"
+```
+
+Then install it with Bundler:
+
+```bash
+bundle install
+```
+
+The gem depends on the channel-neutral `sender-core` runtime and has no
+mandatory provider SDK dependencies. Provider integrations use documented
+HTTP APIs directly.
+
+To configure providers from environment variables, list the desired providers
+and identify the preferred default. The default receives the highest election
+priority; other selected providers remain available for failover:
+
+```bash
+SMS_SENDER_PROVIDERS=textbee,twilio
+SMS_SENDER_DEFAULT_PROVIDER=twilio
+SMS_SENDER_TEXTBEE_SETTINGS='{"api_key":"...","device_id":"..."}'
+```
+
+Multiple accounts of one provider can be configured as named instances. An
+instance name uses the adapter name as its prefix:
+
+```bash
+SMS_SENDER_PROVIDERS=textbee_primary,textbee_backup
+SMS_SENDER_DEFAULT_PROVIDER=textbee_primary
+SMS_SENDER_TEXTBEE_PRIMARY_SETTINGS='{"api_key":"...","device_id":"..."}'
+SMS_SENDER_TEXTBEE_BACKUP_SETTINGS='{"api_key":"...","device_id":"..."}'
+```
+
+Each instance has independent priority, fallback, circuit-breaker, and health
+state. Existing single-provider variables remain supported.
+
+Call `Sms::Sender.configure_from_env` during application boot. Each provider's
+`*_SETTINGS` value is a JSON object whose keys match that adapter's settings.
+Provider metadata includes an advisory `support_level`; it is informational
+only and does not prevent use of experimental, deprecated, or unsupported
+providers.
+
+## Compatibility boundary
+
+Shared contracts such as `Message`, `Delivery`, `Provider`, `Router`, and
+normalized errors are supplied by `sender-core` and exposed through the
+existing `Sms::Sender` constants. SMS provider adapters and the SMS provider
+catalog remain in this gem. Existing `lib/sms/sender/*` require paths are
+preserved as compatibility shims.
+
+## Usage
+
+Construct provider-neutral messages and configurations:
+
+```ruby
+require "sms_sender"
+
+message = Sms::Sender::Message.new(
+  to: "+639171234567",
+  body: "Your OTP is 123456",
+  requirements: [:unicode]
+)
+
+configuration = Sms::Sender::ProviderConfiguration.new(
+  name: :textbee,
+  settings: {
+    api_key: ENV.fetch("TEXTBEE_API_KEY")
+  },
+  priority: 10,
+  capabilities: [:sms, :unicode]
+)
+```
+
+`Message` and `ProviderConfiguration` are immutable after construction.
+Recipients and bodies are validated, provider capabilities and message
+requirements are normalized to symbols, and delivery results distinguish
+provider acceptance from confirmed handset delivery.
+
+Provider adapters implement the common contract:
+
+```ruby
+class MyProvider < Sms::Sender::Provider
+  def deliver(message)
+    # Translate `message` to the provider's HTTP API and return a
+    # Sms::Sender::Delivery result.
+  end
+end
+```
+
+The high-level API routes through configured providers and returns a normalized
+delivery result:
+
+```ruby
+delivery = Sms::Sender.deliver(
+  to: "+639171234567",
+  body: "Your OTP is 123456"
+)
+```
+
+The registry exposes the providers supported by the gem without loading their
+adapter implementations:
+
+```ruby
+Sms::Sender.providers
+# => [:textbee, :semaphore, :twilio, :infobip]
+```
+
+Provider adapters can use the HTTP client without taking a dependency on a
+provider SDK:
+
+```ruby
+client = Sms::Sender::HTTP::Client.new
+response = client.request(
+  :post,
+  "https://example.test/messages",
+  headers: { "Authorization" => "Bearer secret" },
+  body: { to: message.to, body: message.body }
+)
+```
+
+The client normalizes responses, serializes Hash bodies as JSON, supports
+separate connection/read/write and total timeouts, maps transport failures to
+normalized errors, and provides redacted headers for diagnostics.
+
+The first provider adapter can be used through the registry:
+
+```ruby
+registry = Sms::Sender::ProviderRegistry.new
+registry.configure(
+  :textbee,
+  settings: { api_key: ENV.fetch("TEXTBEE_API_KEY") }
+)
+
+delivery = registry.provider(:textbee).deliver(message)
+```
+
+TextBee sends through its default device unless `device_id` is configured.
+The adapter returns an accepted delivery with the provider's batch ID; that
+acceptance does not confirm handset delivery.
+
+## Design principles
+
+- One repository and one gem for all supported providers.
+- Direct documented HTTP integrations instead of provider Ruby SDKs.
+- Lazy loading so unused providers and dependencies remain unloaded.
+- Thin adapters limited to configuration, authentication, HTTP mapping,
+  response parsing, and provider error mapping.
+- Provider-neutral routing, health, failover, and circuit-breaking behavior.
+- Explicit error classification so terminal request errors do not trigger
+  provider failover.
+- Provider acceptance is distinct from final handset delivery.
+- Process-local state initially, behind an abstraction for future shared state.
+
+The initial provider set is TextBee, Semaphore, Twilio, and Infobip. Telnyx,
+Vonage, and Plivo are potential later additions. AWS SNS is not part of the
+initial provider set.
+
+## Development
+
+After checking out the repository, install dependencies:
+
+```bash
+bin/setup
+```
+
+Run the complete quality harness with:
+
+```bash
+bundle exec rake
+```
+
+This runs the test suite, RuboCop, RBS validation, and YARD documentation
+coverage checks. Normal tests do not require provider credentials or send
+real SMS messages.
+
+Other useful commands:
+
+```bash
+bundle exec rake test       # Run tests
+bundle exec rake rubocop   # Run RuboCop
+bundle exec rake rbs       # Validate RBS signatures
+bundle exec rake yard      # Generate API documentation
+bundle exec rake build     # Build the gem
+bin/console                # Open a Ruby console
+```
+
+### Compatibility and integration boundary
+
+The supported runtime is Ruby 3.2 and newer. Standard CI uses only injected
+HTTP transports and in-memory state; it never requires provider credentials,
+network access, or live SMS delivery. Provider-specific integration tests are
+opt-in and should be isolated from the normal `bundle exec rake` quality gate.
+
+## Contributing
+
+Bug reports and pull requests are welcome at
+[github.com/kanutocd/sms-sender](https://github.com/kanutocd/sms-sender).
+
+Changes should preserve the provider-neutral core, keep adapters thin, and
+include focused tests. Meaningful user, operator, integration, tooling, or
+architectural changes should be recorded in `CHANGELOG.md` under `Unreleased`.
+
+## License
+
+This project is available under the [MIT License](LICENSE.txt).
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community guidelines.

data/Rakefile

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |task|
+  task.libs << "test"
+  task.libs << "lib"
+  task.test_files = FileList["test/**/test_*.rb", "test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+require "yard"
+require "yard/rake/yardoc_task"
+
+RuboCop::RakeTask.new do |task|
+  task.options = ["--cache", "false"]
+end
+
+YARD::Rake::YardocTask.new(:yard) do |task|
+  task.files = ["lib/**/*.rb"]
+  task.options = ["--output-dir", "doc", "--readme", "README.md", "--markup", "markdown"]
+end
+
+desc "Validate RBS signatures"
+task :rbs do
+  sh "rbs validate"
+end
+
+desc "Enforce YARD documentation coverage"
+task "yard:coverage" => :yard do
+  output = `yard stats --no-progress --list-undoc --exclude sig`
+  puts output
+  coverage = output[/([0-9]+(?:\.[0-9]+)?)% documented/, 1]&.to_f
+  abort "Could not determine YARD documentation coverage" unless coverage
+  abort "YARD documentation coverage #{coverage}% is below 100%" if coverage < 100.0
+end
+
+desc "Run the test and lint quality gates"
+task quality: %i[test rubocop rbs yard:coverage]
+
+task default: :quality

data/lib/sms/sender/capabilities.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the capabilities contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/circuit_breaker.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the circuit breaker contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/delivery.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the delivery contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/delivery_event.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the delivery event contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/election.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the election contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/errors.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the errors contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/health.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the health contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/http.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the http contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/message.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the message contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/observability.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the observability contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/provider.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the provider contract now supplied by
+# sender-core.
+require "sender/core"

data/lib/sms/sender/provider_configuration.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the provider configuration contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/provider_registry.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Backwards-compatible load path for the provider registry contract now supplied by
+# sender-core.
+require_relative "../sender"

data/lib/sms/sender/providers/infobip.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Sms
+  module Sender
+    module Providers
+      # Infobip HTTP adapter for advanced SMS message submission.
+      class Infobip < Provider
+        # Default Infobip SMS API base URL.
+        BASE_URL = "https://api.infobip.com"
+        # Infobip advanced SMS endpoint path.
+        SEND_PATH = "/sms/3/messages"
+
+        # @param configuration [ProviderConfiguration] Infobip settings
+        # @param http [HTTP::Client] injectable HTTP client
+        def initialize(configuration:, http: HTTP::Client.new)
+          super(configuration: configuration)
+          @http = http
+        end
+
+        # Submit an SMS through Infobip.
+        # @param message [Message] normalized outbound message
+        # @return [Delivery] accepted provider response
+        def deliver(message)
+          validate_message(message)
+          response = @http.request(:post, endpoint, headers: headers, body: request_body(message))
+          map_response(response)
+        end
+
+        private
+
+        def endpoint
+          "#{configuration[:base_url] || BASE_URL}#{SEND_PATH}"
+        end
+
+        def headers
+          { "Authorization" => "App #{api_key}", "Content-Type" => "application/json", "Accept" => "application/json" }
+        end
+
+        def api_key
+          key = configuration[:api_key]
+          return key.to_s unless key.nil? || key.to_s.empty?
+
+          raise Errors::ConfigurationError.new("Infobip api_key is required", category: :configuration,
+                                                                              provider: :infobip)
+        end
+
+        def sender
+          value = configuration[:from] || configuration[:sender]
+          return value.to_s unless value.nil? || value.to_s.empty?
+
+          raise Errors::ConfigurationError.new("Infobip from or sender is required", category: :configuration,
+                                                                                     provider: :infobip)
+        end
+
+        def request_body(message)
+          {
+            "messages" => [
+              {
+                "sender" => sender,
+                "destinations" => [{ "to" => message.to }],
+                "content" => { "text" => message.body }
+              }
+            ]
+          }
+        end
+
+        def map_response(response)
+          payload = JSON.parse(response.body.to_s)
+          return map_failure(response.status, payload) unless response.successful?
+
+          result = payload.is_a?(Hash) && payload["messages"]&.first
+          raise TypeError unless result.is_a?(Hash) && result["messageId"]
+
+          Delivery.new(status: :accepted, provider: :infobip, provider_message_id: result["messageId"],
+                       metadata: payload)
+        rescue JSON::ParserError, TypeError, NoMethodError
+          raise Errors::Unknown.new("Infobip returned an invalid response", category: :malformed_response,
+                                                                            provider: :infobip)
+        end
+
+        def map_failure(status, payload)
+          message = payload.is_a?(Hash) ? payload["requestError"] : nil
+          if message.is_a?(Hash) && message["serviceException"].is_a?(Hash)
+            message = message["serviceException"]["text"]
+          end
+          message ||= "Infobip request failed with HTTP #{status}"
+          error_class = case status
+                        when 400 then Errors::InvalidRequest
+                        when 401 then Errors::Authentication
+                        when 403 then Errors::Authorization
+                        when 429 then Errors::RateLimited
+                        when 500..599 then Errors::ProviderUnavailable
+                        else Errors::Unknown
+                        end
+          raise error_class.new(message, category: error_class.name.split("::").last.downcase.to_sym,
+                                         provider: :infobip)
+        end
+
+        def validate_message(message)
+          return if message.is_a?(Message)
+
+          raise ArgumentError, "message must be a Sms::Sender::Message"
+        end
+      end
+    end
+  end
+end

data/lib/sms/sender/providers/semaphore.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module Sms
+  module Sender
+    module Providers
+      # Semaphore HTTP adapter for Philippine SMS delivery.
+      class Semaphore < Provider
+        # Default hosted Semaphore API base URL.
+        BASE_URL = "https://api.semaphore.co"
+        # Semaphore SMS submission endpoint path.
+        SEND_PATH = "/api/v4/messages"
+
+        # @param configuration [ProviderConfiguration] Semaphore settings
+        # @param http [HTTP::Client] injectable HTTP client
+        def initialize(configuration:, http: HTTP::Client.new)
+          super(configuration: configuration)
+          @http = http
+        end
+
+        # Submit an SMS through Semaphore.
+        # @param message [Message] normalized outbound message
+        # @return [Delivery] accepted provider response
+        def deliver(message)
+          validate_message(message)
+          response = @http.request(:post, endpoint, headers: headers, body: request_body(message))
+          map_response(response)
+        end
+
+        private
+
+        def endpoint
+          "#{configuration[:base_url] || BASE_URL}#{SEND_PATH}"
+        end
+
+        def headers
+          { "Content-Type" => "application/x-www-form-urlencoded" }
+        end
+
+        def api_key
+          key = configuration[:api_key]
+          return key.to_s unless key.nil? || key.to_s.empty?
+
+          raise Errors::ConfigurationError.new("Semaphore api_key is required", category: :configuration,
+                                                                                provider: :semaphore)
+        end
+
+        def request_body(message)
+          fields = { "apikey" => api_key, "number" => message.to, "message" => message.body }
+          fields["sendername"] = configuration[:sender] if configuration[:sender]
+          URI.encode_www_form(fields)
+        end
+
+        def map_response(response)
+          payload = JSON.parse(response.body.to_s)
+          return map_failure(response.status, payload) unless response.successful?
+
+          result = payload.first
+          raise TypeError unless result.is_a?(Hash)
+          if result["status"].to_s.casecmp("failed").zero? || result["status"].to_s.casecmp("refunded").zero?
+            return map_rejection(result)
+          end
+
+          Delivery.new(
+            status: :accepted,
+            provider: :semaphore,
+            provider_message_id: result["message_id"].to_s,
+            metadata: result
+          )
+        rescue JSON::ParserError, TypeError, NoMethodError
+          raise Errors::Unknown.new("Semaphore returned an invalid response", category: :malformed_response,
+                                                                              provider: :semaphore)
+        end
+
+        def map_failure(status, payload)
+          message = payload.is_a?(Hash) ? payload["message"] : nil
+          message ||= "Semaphore request failed with HTTP #{status}"
+          error_class = case status
+                        when 401 then Errors::Authentication
+                        when 429 then Errors::RateLimited
+                        when 400 then Errors::InvalidRequest
+                        when 500..599 then Errors::ProviderUnavailable
+                        else Errors::Unknown
+                        end
+          raise error_class.new(message, category: error_class.name.split("::").last.downcase.to_sym,
+                                         provider: :semaphore)
+        end
+
+        def map_rejection(_result)
+          raise Errors::ProviderRejected.new("Semaphore rejected the message", category: :provider_rejected,
+                                                                               provider: :semaphore)
+        end
+
+        def validate_message(message)
+          return if message.is_a?(Message)
+
+          raise ArgumentError, "message must be a Sms::Sender::Message"
+        end
+      end
+    end
+  end
+end