siel 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 30da03ac501823e026013c4b68357b532666f49450dfb01dbce7c565515dd360
+  data.tar.gz: 56fa3b33cac95b9f97d5e61485c06d26729ee9f11fc3e19ded6d7b983f6a3895
+SHA512:
+  metadata.gz: 4bf5eb85f8520035f050dc7018c120cb398e6ce9dd44af3f62cb7bd76d8568d0c8856b0b9e3de943da3796fa4c506f6acf9bc59287fd83d95515c23a1803bded
+  data.tar.gz: 2042f27f6c608034f60738bcfe87c4edbf9de85ac30871e6a5de7ad81e4bf0ed2b38c215bd1011b095df2f4957715d81993a95f84c29d13a556756f94cff93d0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siel Labs
+
+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,51 @@
+# Siel for Ruby
+
+The Siel SMS API from Ruby 3.0 or later: messages, batches, OTP codes,
+templates, prices and webhook signatures. No dependencies.
+
+```sh
+gem install siel
+```
+
+Or in your Gemfile: `gem "siel"`.
+
+```ruby
+require "siel"
+
+siel = Siel::Client.new(ENV.fetch("SIEL_API_KEY"))
+
+message = siel.messages.send(
+  to: "+447700900123",
+  from: "YourBrand",
+  body: "Your order #4821 has shipped",
+  client_reference: "order-4821"
+)
+puts message["id"], message["status"] # "01a1…", "queued"
+```
+
+Fields are keyword arguments with the API's names (pass a hash of them as
+`**fields`); answers are hashes with string keys.
+
+- **Retries are safe.** A send gets an `Idempotency-Key` of its own unless you
+  pass `idempotency_key:`, so a retry after a timeout never sends twice. `429`
+  is retried after `Retry-After`; network errors and `5xx` only where
+  repeating can't do anything twice.
+- **Errors** are `Siel::Error` with `status`, `code` (branch on it:
+  `invalid_to`, `insufficient_balance`…), `message` and `retry_after`.
+- **Webhooks:** `Siel.verify_webhook(secret, timestamp: …, signature: …, body: raw)`
+  checks the `X-Smsgw-Timestamp` and `X-Smsgw-Signature` headers against the
+  raw body (`request.body.read`).
+
+| | |
+|---|---|
+| `messages` | `send`, `send_batch`, `get`, `list` |
+| `otp` | `start`, `check`, `check_number`, `get`, `list` |
+| `templates`, `webhooks` | `list`, `get`, `create`, `update`, `delete` |
+| `senders` | `list`, `get` |
+| | `balance`, `prices(country:)` |
+
+Docs: https://docs.siellabs.com · The API as OpenAPI: https://docs.siellabs.com/openapi.yaml
+
+Tests: `ruby -Ilib test/test_client.rb` (against a stand-in server).
+`test/live.rb` runs against a real gateway, given `SIEL_BASE_URL`, `SIEL_API_KEY`
+and `SIEL_FROM`.

data/lib/siel/client.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+
+module Siel
+  DEFAULT_BASE_URL = "https://api.siellabs.com"
+
+  # A client for one API key. Fields go in as keyword arguments with the API's
+  # names; answers come back as the API's JSON, parsed into hashes with
+  # string keys.
+  class Client
+    # What can go wrong before any answer comes.
+    NETWORK_ERRORS = [
+      IOError, SocketError, SystemCallError, Timeout::Error,
+      OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError
+    ].freeze
+
+    attr_reader :base_url, :timeout, :max_retries, :messages, :otp, :templates, :webhooks, :senders
+
+    # api_key is one of your API keys, smsgw_…. timeout is in seconds, per
+    # request. max_retries counts the retries of refused (429) and, when it's
+    # safe, failed requests.
+    def initialize(api_key, base_url: DEFAULT_BASE_URL, timeout: 30, max_retries: 2)
+      raise ArgumentError, "Siel: pass one of your API keys" if api_key.nil? || api_key.to_s.empty?
+
+      @api_key = api_key.to_s
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+      @messages = Messages.new(self)
+      @otp = OTP.new(self)
+      @templates = Resource.new(self, "/v1/templates")
+      @webhooks = Resource.new(self, "/v1/webhooks")
+      @senders = Senders.new(self)
+    end
+
+    # Your balance, credit limit and what you can still spend, in micros.
+    def balance
+      request("GET", "/v1/balance")
+    end
+
+    # What you pay per part, by country and network.
+    def prices(country: nil)
+      request("GET", "/v1/prices", query: { country: country })
+    end
+
+    # Leaves the API key out of logs and consoles.
+    def inspect
+      "#<#{self.class} base_url=#{@base_url.inspect}>"
+    end
+
+    # Calls the API; the resources use this. Retried: what the API refused
+    # before doing anything (429), and, when the request is safe to repeat (a
+    # GET or DELETE, or a send with its key), network errors and 5xx.
+    def request(method, path, body: nil, query: nil, idempotency_key: nil)
+      uri = URI(@base_url + path)
+      params = (query || {}).reject { |_, v| v.nil? }
+      uri.query = URI.encode_www_form(params) unless params.empty?
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "siel-ruby/#{VERSION}"
+      }
+      payload = nil
+      unless body.nil?
+        payload = JSON.generate(body)
+        headers["Content-Type"] = "application/json"
+      end
+      key = idempotency_key.to_s
+      headers["Idempotency-Key"] = key unless key.empty?
+      repeatable = %w[GET DELETE].include?(method) || !key.empty?
+
+      attempt = 0
+      loop do
+        begin
+          res = perform(method, uri, headers, payload)
+        rescue *NETWORK_ERRORS => e
+          if repeatable && attempt < @max_retries
+            sleep(backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise Error, "request failed: #{e.message}"
+        end
+
+        status = res.code.to_i
+        raw = res.body.to_s
+        if status >= 200 && status < 300
+          return nil if status == 204 || raw.empty?
+
+          return parse(raw)
+        end
+
+        data = begin
+          parse(raw)
+        rescue JSON::ParserError
+          nil
+        end
+        err = data.is_a?(Hash) && data["error"].is_a?(Hash) ? data["error"] : {}
+        retry_after = seconds(res["Retry-After"]) || seconds(err["retry_after"])
+        if (status == 429 || (repeatable && status >= 500)) && attempt < @max_retries
+          sleep(retry_after&.between?(0, 30) ? retry_after : backoff(attempt))
+          attempt += 1
+          next
+        end
+        raise Error.new(err["message"] || "HTTP #{status}", status: status, code: err["code"] || "http_error",
+                                                            retry_after: retry_after, body: data)
+      end
+    end
+
+    private
+
+    def perform(method, uri, headers, payload)
+      req = Net::HTTPGenericRequest.new(method, !payload.nil?, true, uri.request_uri, headers)
+      req.body = payload unless payload.nil?
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      # Net::HTTP would quietly repeat a GET, PUT or DELETE once; the retries
+      # here are the only ones.
+      http.max_retries = 0
+      http.start { |conn| conn.request(req) }
+    end
+
+    def parse(raw)
+      JSON.parse(raw.dup.force_encoding(Encoding::UTF_8))
+    end
+
+    # Whole seconds from a header or the error, or nil.
+    def seconds(value)
+      case value
+      when Integer then value
+      when String then Integer(value.strip, 10, exception: false)
+      end
+    end
+
+    # 0.5 s, 1 s, 2 s…, with jitter so a burst of clients doesn't retry in step.
+    def backoff(attempt)
+      [0.5 * (2**attempt), 8.0].min * (0.8 + (0.4 * rand))
+    end
+  end
+end

data/lib/siel/error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Siel
+  # An error the API answered with, or a request that never got an answer.
+  class Error < StandardError
+    # The HTTP status; 0 when no answer came.
+    attr_reader :status
+    # The API's stable error code, such as "invalid_to": branch on this.
+    attr_reader :code
+    # Seconds until the same request can work, when the API says.
+    attr_reader :retry_after
+    # The whole answer, parsed: some errors carry more (an OTP's verification).
+    attr_reader :body
+
+    def initialize(message, status: 0, code: "connection_error", retry_after: nil, body: nil)
+      super(message)
+      @status = status
+      @code = code
+      @retry_after = retry_after
+      @body = body
+    end
+  end
+end

data/lib/siel/resources.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Siel
+  # Helpers the resources share.
+  module Util # :nodoc:
+    module_function
+
+    # Drops fields left as nil.
+    def clean(fields)
+      fields.reject { |_, v| v.nil? }
+    end
+
+    # Escapes an ID for a URL path: anything but letters, digits and -._~
+    def escape(id)
+      id.to_s.b.gsub(/[^A-Za-z0-9\-._~]/) { |c| format("%%%02X", c.ord) }
+    end
+
+    # The key you gave, or a new one, so a retry never sends twice.
+    def key(given)
+      given.nil? || given.to_s.empty? ? SecureRandom.uuid : given.to_s
+    end
+  end
+
+  # Messages: send, send_batch, get, list.
+  class Messages
+    def initialize(client)
+      @client = client
+    end
+
+    # Sends one message: to:, from:, and body: or template_id: with
+    # variables:. A retry after a timeout never sends it twice: an
+    # Idempotency-Key is made unless you pass idempotency_key:.
+    #
+    # Given a method name, as Object#send is, it calls that method.
+    def send(*args, **fields)
+      return super if args.first.is_a?(Symbol) || args.first.is_a?(String)
+
+      send_one(*args, **fields)
+    end
+
+    # One text or template to up to 100 numbers; each message answers for
+    # itself in "data".
+    def send_batch(from:, messages:, body: nil, template_id: nil, variables: nil, callback_url: nil,
+                   smart_encoding: nil, shorten_links: nil, validity_period: nil, idempotency_key: nil)
+      fields = Util.clean(from: from, messages: messages, body: body, template_id: template_id,
+                          variables: variables, callback_url: callback_url, smart_encoding: smart_encoding,
+                          shorten_links: shorten_links, validity_period: validity_period)
+      @client.request("POST", "/v1/messages/batch", body: fields, idempotency_key: Util.key(idempotency_key))
+    end
+
+    def get(id)
+      @client.request("GET", "/v1/messages/#{Util.escape(id)}")
+    end
+
+    # Your latest messages, newest first.
+    def list(limit: nil)
+      @client.request("GET", "/v1/messages", query: { limit: limit })["data"]
+    end
+
+    private
+
+    def send_one(to:, from:, body: nil, template_id: nil, variables: nil, callback_url: nil, smart_encoding: nil,
+                 shorten_links: nil, validity_period: nil, client_reference: nil, idempotency_key: nil)
+      fields = Util.clean(to: to, from: from, body: body, template_id: template_id, variables: variables,
+                          callback_url: callback_url, smart_encoding: smart_encoding, shorten_links: shorten_links,
+                          validity_period: validity_period, client_reference: client_reference)
+      @client.request("POST", "/v1/messages", body: fields, idempotency_key: Util.key(idempotency_key))
+    end
+  end
+
+  # OTP codes: start, check, check_number, get, list.
+  class OTP
+    def initialize(client)
+      @client = client
+    end
+
+    # Sends a code by Telegram or SMS.
+    def start(to:, channels: nil, code_length: nil, code: nil, ttl_seconds: nil, from: nil, sms_template: nil,
+              template_id: nil, payload: nil, callback_url: nil)
+      fields = Util.clean(to: to, channels: channels, code_length: code_length, code: code, ttl_seconds: ttl_seconds,
+                          from: from, sms_template: sms_template, template_id: template_id, payload: payload,
+                          callback_url: callback_url)
+      @client.request("POST", "/v1/verifications", body: fields)
+    end
+
+    # Checks what the person typed. A wrong code isn't an error: look at
+    # "valid" and "result".
+    def check(id, code)
+      @client.request("POST", "/v1/verifications/#{Util.escape(id)}/check", body: { code: code })
+    end
+
+    # Checks the latest code sent to a number.
+    def check_number(to, code)
+      @client.request("POST", "/v1/verifications/check", body: { to: to, code: code })
+    end
+
+    def get(id)
+      @client.request("GET", "/v1/verifications/#{Util.escape(id)}")
+    end
+
+    def list(to: nil, status: nil, channel: nil, limit: nil)
+      query = { to: to, status: status, channel: channel, limit: limit }
+      @client.request("GET", "/v1/verifications", query: query)["data"]
+    end
+  end
+
+  # Templates and webhooks: list, get, create, update, delete.
+  class Resource
+    def initialize(client, base)
+      @client = client
+      @base = base
+    end
+
+    def list(**query)
+      @client.request("GET", @base, query: query)["data"]
+    end
+
+    def get(id)
+      @client.request("GET", "#{@base}/#{Util.escape(id)}")
+    end
+
+    def create(**fields)
+      @client.request("POST", @base, body: Util.clean(fields))
+    end
+
+    def update(id, **fields)
+      @client.request("PUT", "#{@base}/#{Util.escape(id)}", body: Util.clean(fields))
+    end
+
+    def delete(id)
+      @client.request("DELETE", "#{@base}/#{Util.escape(id)}")
+      nil
+    end
+  end
+
+  # Your sender IDs; registering one is in the web app.
+  class Senders
+    def initialize(client)
+      @client = client
+    end
+
+    def list(status: nil)
+      @client.request("GET", "/v1/senders", query: { status: status })["data"]
+    end
+
+    def get(id)
+      @client.request("GET", "/v1/senders/#{Util.escape(id)}")
+    end
+  end
+end

data/lib/siel/version.rb

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

data/lib/siel/webhook.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Siel
+  # True when a webhook is signed with your webhook secret and recent.
+  #
+  # timestamp and signature are the X-Smsgw-Timestamp and X-Smsgw-Signature
+  # headers. Pass the raw body exactly as received (request.body.read), not
+  # JSON parsed and written again.
+  def self.verify_webhook(secret, timestamp:, signature:, body:, tolerance_seconds: 300, now: nil)
+    timestamp = timestamp.to_s
+    signature = signature.to_s
+    return false if timestamp.empty? || signature.empty?
+
+    ts = Integer(timestamp, 10, exception: false)
+    return false if ts.nil? || ((now || Time.now.to_f) - ts).abs > tolerance_seconds
+
+    signed = timestamp.b << "." << body.to_s.b
+    mac = OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, signed)
+    OpenSSL.secure_compare("v1=#{mac}", signature)
+  end
+end

data/lib/siel.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# The Siel SMS API for Ruby 3.0+, with no dependencies.
+#
+#   require "siel"
+#
+#   siel = Siel::Client.new(ENV.fetch("SIEL_API_KEY"))
+#   message = siel.messages.send(to: "+447700900123", from: "YourBrand", body: "Your order has shipped")
+#
+# Docs: https://docs.siellabs.com
+module Siel
+end
+
+require_relative "siel/version"
+require_relative "siel/error"
+require_relative "siel/client"
+require_relative "siel/resources"
+require_relative "siel/webhook"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: siel
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Siel Labs
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-14 00:00:00.000000000 Z
+dependencies: []
+description: 'The Siel SMS API from Ruby 3.0 or later: messages, batches, OTP codes,
+  templates, prices and webhook signatures. No dependencies.'
+email: support@siellabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/siel.rb
+- lib/siel/client.rb
+- lib/siel/error.rb
+- lib/siel/resources.rb
+- lib/siel/version.rb
+- lib/siel/webhook.rb
+homepage: https://docs.siellabs.com/sdks
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://siellabs.com/git/siel-ruby.git
+  documentation_uri: https://docs.siellabs.com/sdks
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'The Siel SMS API for Ruby: messages, batches, OTP codes, prices and webhook
+  signatures.'
+test_files: []