hellio-messaging 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45de36c0b40d47f5073fcce914ac1f18583a7ef9a13ad128deed76abdc6205f7
+  data.tar.gz: 4e68b72f61d9c5431807c4797b81a75ad445ba1ed5b941f3fa8b69e384ebf98b
+SHA512:
+  metadata.gz: '09058b69a323ccdafc77293a97f0fcadb8567c4bf3cfa3f01c97b675ef7690eff30515da914bdc050f637d8b25092367d3bd844c1d7898beaebded4c2fa621b3'
+  data.tar.gz: 244a062620713196303429e28b74db4073f9120b7a9d818e3bc00862198c944a4c998b5fd206cd018a74897f237945d0cca9775681e3dbceaa977f74fef9e116

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to `hellio-messaging` are documented here.
+This project follows [Semantic Versioning](https://semver.org).
+
+## [1.0.0] - 2026-07-05
+
+Initial release of the official Ruby SDK for the Hellio Messaging API v1.
+
+### Added
+- `Hellio::Client` with Bearer-token auth and one method per endpoint:
+  - Account: `balance`, `pricing`.
+  - SMS: `sms`, `message`, `campaign`.
+  - OTP: `otp`, `verify_otp`, `verify` (channels `sms`, `email`, `voice`).
+  - Voice: `voice`, `voice_status`.
+  - Number lookup (HLR): `lookup`, `lookups`, `lookup_result`.
+  - Email verification: `verify_email`.
+  - Webhooks: `webhooks`, `create_webhook`, `delete_webhook`.
+- Recipient normalization: methods accept a single string, a comma-separated
+  string, or an array.
+- Typed errors: `Hellio::InvalidApiTokenError` (401),
+  `Hellio::InsufficientBalanceError` (402), `Hellio::ValidationError` (422, with
+  `#errors`), `Hellio::RateLimitError` (429), and `Hellio::Error` (base). Each
+  carries `status_code` and the parsed `response` body.
+- Configuration via constructor or the `HELLIO_API_TOKEN`, `HELLIO_BASE_URL`,
+  and `HELLIO_DEFAULT_SENDER` environment variables.
+- Pluggable HTTP adapter (defaults to the standard library `net/http`) so tests
+  can inject a fake transport.
+- RSpec suite with WebMock and a GitHub Actions matrix (Ruby 3.1, 3.2, 3.3).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Albert Ninyeh, Hellio Solutions
+
+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,144 @@
+# Hellio Messaging - Official Ruby SDK
+
+[![tests](https://github.com/HellioSolutions/hellio-ruby/actions/workflows/tests.yml/badge.svg)](https://github.com/HellioSolutions/hellio-ruby/actions/workflows/tests.yml)
+[![Gem Version](https://img.shields.io/gem/v/hellio-messaging.svg)](https://rubygems.org/gems/hellio-messaging)
+[![Gem Downloads](https://img.shields.io/gem/dt/hellio-messaging.svg)](https://rubygems.org/gems/hellio-messaging)
+[![License](https://img.shields.io/github/license/HellioSolutions/hellio-ruby.svg)](LICENSE)
+
+Ruby client for the [Hellio Messaging](https://helliomessaging.com) API v1:
+**SMS**, **OTP** (SMS / email / voice), **Voice broadcasts**, **Number Lookup (HLR)**,
+**Email Verification**, **Pricing**, **Balance**, and **Webhooks**. It uses only
+the Ruby standard library (`net/http` and `json`), so there are no runtime
+dependencies.
+
+## Install
+
+```bash
+gem install hellio-messaging
+```
+
+Or with Bundler, add to your `Gemfile`:
+
+```ruby
+gem "hellio-messaging"
+```
+
+then run `bundle install`.
+
+## Configure
+
+Generate a token in your dashboard (**Settings -> API -> Generate API token**),
+then create a client. You can pass values directly or set environment variables.
+
+```ruby
+require "hellio"
+
+client = Hellio::Client.new(
+  token: "your-token-here",
+  default_sender: "HellioSMS"
+)
+```
+
+Environment variables are read as fallbacks when an option is omitted:
+
+```dotenv
+HELLIO_BASE_URL=https://api.helliomessaging.com/v1
+HELLIO_API_TOKEN=your-token-here
+HELLIO_DEFAULT_SENDER=HellioSMS
+```
+
+```ruby
+client = Hellio::Client.new   # reads HELLIO_API_TOKEN, HELLIO_BASE_URL, HELLIO_DEFAULT_SENDER
+```
+
+Optional constructor options: `base_url` (defaults to
+`https://api.helliomessaging.com/v1`), `timeout` (seconds, default 30), and
+`http` (a custom HTTP adapter, mainly for tests).
+
+Every call returns the decoded JSON as a `Hash` with string keys (payloads are
+under the `"data"` key). Non-2xx responses raise a typed error (see below).
+
+## Usage
+
+```ruby
+# Account
+client.balance            # {"data" => {"balance" => "195.0000", "available" => "194.65", ...}}
+client.pricing("GH")      # optional ISO-2 country filter
+
+# SMS (recipients: string, comma list, or array)
+client.sms("233241234567", "Hello!")
+client.sms(["233241234567", "233201234567"], "Hi all", sender: "HellioSMS")
+client.message(1024)      # delivery status
+client.campaign(1024)     # campaign summary
+
+# OTP - sender (Sender ID) is REQUIRED for sms/voice and must be approved on your account.
+# Optional length (4-10 digits) and expiry (minutes). Returns status "queued".
+client.otp("233241234567", sender: "HellioSMS")                       # SMS
+client.otp("233241234567", sender: "HellioSMS", channel: "voice")     # Voice (TTS reads the code)
+client.otp("233241234567", sender: "HellioSMS", length: 6, expiry: 10)
+client.otp("user@example.com", channel: "email")                      # Email (no sender)
+client.verify("233241234567", "123456")                               # true / false
+client.verify_otp("user@example.com", "123456", channel: "email")     # full response
+
+# Voice broadcast - text (we TTS it) or a hosted audio_url
+client.voice("233241234567", "HELLIO", text: "Your code is 1 2 3 4")
+client.voice(["233241234567"], "HELLIO", audio_url: "https://cdn.example.com/promo.mp3")
+
+# Number lookup (HLR) - async; poll results
+client.lookup(["233241234567"])
+client.lookups
+client.lookup_result(5)
+
+# Email verification
+client.verify_email(["user@gmail.com", "bad@nodomain.invalid"])
+
+# Webhooks (receive delivery reports)
+client.create_webhook("https://your-app.com/hooks/hellio", events: ["message.delivered", "message.failed"])
+client.webhooks
+client.delete_webhook(1)
+```
+
+Recipient inputs (`sms`, `voice`, `lookup`, `verify_email`) accept a single
+string, a comma-separated string, or an array. They are normalized to a list
+before the request is sent.
+
+## Error handling
+
+Non-2xx responses raise typed errors (all subclass `Hellio::Error`). Each error
+carries `status_code` and the parsed `response` body; `ValidationError` also
+exposes field-level details through `#errors`.
+
+| Error | Status |
+|---|---|
+| `Hellio::InvalidApiTokenError` | 401 |
+| `Hellio::InsufficientBalanceError` | 402 |
+| `Hellio::ValidationError` (`#errors`) | 422 |
+| `Hellio::RateLimitError` | 429 |
+| `Hellio::Error` | other |
+
+```ruby
+begin
+  client.sms("233241234567", "Hi")
+rescue Hellio::InsufficientBalanceError => e
+  # top up
+rescue Hellio::ValidationError => e
+  e.errors        # field-level messages
+  e.status_code   # 422
+  e.response      # full parsed body
+end
+```
+
+Rate limit: **120 requests/minute** per token.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+Tests use RSpec and WebMock to mock the HTTP layer.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/hellio/client.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+require "hellio/errors"
+require "hellio/http"
+
+module Hellio
+  # Hellio Messaging API v1 client. Authenticates with a Bearer token and exposes
+  # one method per endpoint. Every call returns the decoded JSON as a Hash with
+  # string keys (payloads are under "data"); non-2xx responses raise a typed
+  # Hellio::Error subclass.
+  class Client
+    DEFAULT_BASE_URL = "https://api.helliomessaging.com/v1"
+    DEFAULT_TIMEOUT = 30
+
+    attr_reader :base_url, :timeout, :default_sender
+
+    # token          - API token (falls back to HELLIO_API_TOKEN).
+    # base_url       - API base URL (falls back to HELLIO_BASE_URL, then default).
+    # timeout        - request timeout in seconds (default 30).
+    # default_sender - Sender ID used by #sms (falls back to HELLIO_DEFAULT_SENDER).
+    # http           - HTTP adapter; inject a fake in tests. Defaults to net/http.
+    def initialize(token: nil, base_url: nil, timeout: nil, default_sender: nil, http: nil)
+      @token = token || ENV["HELLIO_API_TOKEN"]
+      @base_url = (base_url || ENV["HELLIO_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @timeout = timeout || DEFAULT_TIMEOUT
+      @default_sender = default_sender || ENV["HELLIO_DEFAULT_SENDER"]
+      @http = http || NetHttpAdapter.new
+    end
+
+    # ---------------------------------------------------------------- Account
+
+    # Current account balance and available credit.
+    def balance
+      get("balance")
+    end
+
+    # Per-network SMS pricing. Pass an ISO-2 country code to narrow by country.
+    def pricing(country = nil)
+      get("pricing", country.nil? ? {} : { "country" => country })
+    end
+
+    # -------------------------------------------------------------------- SMS
+
+    # Send an SMS. recipients may be a single string, a comma-separated string,
+    # or an array of numbers.
+    def sms(recipients, message, sender: nil, gateway: nil)
+      post("sms/send", compact(
+        "recipients" => to_list(recipients),
+        "sender" => sender || default_sender,
+        "message" => message,
+        "gateway" => gateway
+      ))
+    end
+
+    # Delivery status for a single message.
+    def message(id)
+      get("messages/#{id}")
+    end
+
+    # Summary for a single campaign.
+    def campaign(id)
+      get("campaigns/#{id}")
+    end
+
+    # -------------------------------------------------------------------- OTP
+
+    # Send a one-time passcode. `to` is a phone number (sms/voice/whatsapp) or an
+    # email (email). `sender` (Sender ID) is required for sms/voice and must be
+    # approved on your account; it is ignored for whatsapp and email. Optional
+    # `length` (4-10 digits) and `expiry` (validity in minutes).
+    def otp(to, sender: nil, channel: "sms", purpose: nil, length: nil, expiry: nil, gateway: nil)
+      destination_key = (channel == "email" ? "email" : "mobile_number")
+
+      post("otp/send", compact(
+        "channel" => channel,
+        destination_key => to,
+        "sender" => sender,
+        "purpose" => purpose,
+        "length" => length,
+        "expiry" => expiry,
+        "gateway" => gateway
+      ))
+    end
+
+    # Verify a one-time passcode and return the full response.
+    def verify_otp(to, code, channel: "sms")
+      destination_key = (channel == "email" ? "email" : "mobile_number")
+
+      post("otp/verify", compact(
+        "channel" => channel,
+        destination_key => to,
+        "code" => code
+      ))
+    end
+
+    # Convenience wrapper: true when the code is valid, false otherwise.
+    # A 422 validation failure is treated as "not verified".
+    def verify(to, code, channel: "sms")
+      result = verify_otp(to, code, channel: channel)
+      truthy?(result.is_a?(Hash) ? result.dig("data", "verified") : nil)
+    rescue ValidationError
+      false
+    end
+
+    # ------------------------------------------------------------------ Voice
+
+    # Voice broadcast. Provide `text` (read with TTS) OR `audio_url` (fetched
+    # and played). recipients accepts the same shapes as #sms.
+    def voice(recipients, caller_id, text: nil, audio_url: nil, name: nil)
+      post("voice/send", compact(
+        "recipients" => to_list(recipients),
+        "caller_id" => caller_id,
+        "text" => text,
+        "audio_url" => audio_url,
+        "name" => name
+      ))
+    end
+
+    # Status for a single voice broadcast.
+    def voice_status(id)
+      get("voice/#{id}")
+    end
+
+    # ----------------------------------------------------------- Number lookup
+
+    # Submit numbers for HLR lookup. numbers accepts a string, comma list, or array.
+    def lookup(numbers)
+      post("lookup", "numbers" => to_list(numbers))
+    end
+
+    # List previously submitted lookups.
+    def lookups
+      get("lookups")
+    end
+
+    # Result for a single lookup.
+    def lookup_result(id)
+      get("lookup/#{id}")
+    end
+
+    # ------------------------------------------------------- Email verification
+
+    # Verify one or more email addresses. emails accepts a string, comma list, or array.
+    def verify_email(emails)
+      post("email/verify", "emails" => to_list(emails))
+    end
+
+    # --------------------------------------------------------------- Webhooks
+
+    # List registered webhooks.
+    def webhooks
+      get("webhooks")
+    end
+
+    # Register a webhook. Pass `events` to subscribe to specific event types.
+    def create_webhook(url, events: [])
+      post("webhooks", compact(
+        "url" => url,
+        "events" => (events.nil? || events.empty? ? nil : events)
+      ))
+    end
+
+    # Delete a webhook by id.
+    def delete_webhook(id)
+      delete("webhooks/#{id}")
+    end
+
+    # --------------------------------------------------------------- internals
+
+    private
+
+    def get(path, query = {})
+      request(:get, path, query: query)
+    end
+
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    def delete(path)
+      request(:delete, path)
+    end
+
+    def request(method, path, query: {}, body: nil)
+      response = @http.call(
+        method: method,
+        url: build_url(path, query),
+        headers: headers,
+        body: body.nil? ? nil : JSON.generate(body),
+        timeout: timeout
+      )
+
+      data = parse(response.body)
+      return data if response.status.to_i.between?(200, 299)
+
+      raise error_for(response.status.to_i, data)
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{@token}",
+        "Accept" => "application/json",
+        "Content-Type" => "application/json"
+      }
+    end
+
+    def build_url(path, query)
+      url = "#{base_url}/#{path.sub(%r{\A/+}, "")}"
+      return url if query.nil? || query.empty?
+
+      "#{url}?#{URI.encode_www_form(query)}"
+    end
+
+    def parse(body)
+      return {} if body.nil? || body.to_s.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      {}
+    end
+
+    def error_for(status, data)
+      message =
+        if data.is_a?(Hash) && data["message"].is_a?(String)
+          data["message"]
+        else
+          "Hellio API request failed."
+        end
+
+      error_class =
+        case status
+        when 401 then InvalidApiTokenError
+        when 402 then InsufficientBalanceError
+        when 422 then ValidationError
+        when 429 then RateLimitError
+        when 503 then ServiceUnavailableError
+        else Error
+        end
+
+      error_class.new(message, status_code: status, response: data)
+    end
+
+    # Normalize a recipient/number/email input into an array of strings.
+    def to_list(value)
+      return value.map(&:to_s) if value.is_a?(Array)
+
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+
+    # Drop keys whose value is nil so they are omitted from the request body.
+    def compact(hash)
+      hash.reject { |_, v| v.nil? }
+    end
+
+    def truthy?(value)
+      return false if value.nil? || value == false
+      return false if value == 0
+      return false if value.is_a?(String) && (value.empty? || value == "0")
+
+      true
+    end
+  end
+end

data/lib/hellio/errors.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Hellio
+  # Base error for every failure returned by the Hellio Messaging API.
+  # Carries the HTTP status code and the parsed response body so callers can
+  # inspect the details (for 422, read #errors for field-level messages).
+  class Error < StandardError
+    attr_reader :status_code, :response
+
+    def initialize(message = nil, status_code: nil, response: nil)
+      super(message)
+      @status_code = status_code
+      @response = response
+    end
+
+    # Field-level validation details, present on 422 responses.
+    def errors
+      return nil unless response.is_a?(Hash)
+
+      response["errors"]
+    end
+  end
+
+  # 401: the API token is missing, malformed, or revoked.
+  class InvalidApiTokenError < Error; end
+
+  # 402: the account balance is too low to complete the request.
+  class InsufficientBalanceError < Error; end
+
+  # 422: the request failed validation. See #errors for the details.
+  class ValidationError < Error; end
+
+  # 429: too many requests. The limit is 120 requests per minute per token.
+  class RateLimitError < Error; end
+
+  # 503: the service is temporarily unavailable, because an admin switched it off
+  # (SMS, OTP, voice, WhatsApp, lookup, email) or the API is paused. Retry later.
+  class ServiceUnavailableError < Error; end
+end

data/lib/hellio/http.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Hellio
+  # A minimal HTTP response value object returned by an adapter.
+  Response = Struct.new(:status, :body)
+
+  # Default HTTP adapter built on the standard library `net/http`. Tests (or
+  # advanced users) can inject any object that responds to #call with the same
+  # keyword arguments and returns an object exposing #status and #body.
+  class NetHttpAdapter
+    def call(method:, url:, headers:, body:, timeout:)
+      uri = URI.parse(url)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+
+      request_class =
+        case method
+        when :get then Net::HTTP::Get
+        when :post then Net::HTTP::Post
+        when :delete then Net::HTTP::Delete
+        else raise ArgumentError, "Unsupported HTTP method: #{method}"
+        end
+
+      request = request_class.new(uri.request_uri)
+      headers.each { |key, value| request[key] = value }
+      request.body = body unless body.nil?
+
+      response = http.request(request)
+      Response.new(response.code.to_i, response.body.to_s)
+    end
+  end
+end

data/lib/hellio/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Hellio
+  VERSION = "1.0.0"
+end

data/lib/hellio.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "hellio/version"
+require "hellio/errors"
+require "hellio/http"
+require "hellio/client"
+
+# Official Ruby SDK for the Hellio Messaging API v1.
+#
+# Quick start:
+#
+#   client = Hellio::Client.new(token: "your-token")
+#   client.sms("233241234567", "Hello!")
+#
+module Hellio
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: hellio-messaging
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Albert Ninyeh
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+description: 'Ruby client for the Hellio Messaging API v1: SMS, OTP (SMS / email /
+  voice), voice broadcasts, number lookup (HLR), email verification, pricing, balance,
+  and webhooks.'
+email:
+- eaglesecurity0@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/hellio.rb
+- lib/hellio/client.rb
+- lib/hellio/errors.rb
+- lib/hellio/http.rb
+- lib/hellio/version.rb
+homepage: https://github.com/HellioSolutions/hellio-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/HellioSolutions/hellio-ruby
+  changelog_uri: https://github.com/HellioSolutions/hellio-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/HellioSolutions/hellio-ruby/issues
+  documentation_uri: https://helliomessaging.com
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for the Hellio Messaging API v1.
+test_files: []