smsgora 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 51014d836b73e44b96133370765f4f0169def6197d5d0472fe8ef4056140c4e6
+  data.tar.gz: 6e44f8be098a567fe005026a7addc4b9c47aeeb5ef84c2f8b84114de53bae8e7
+SHA512:
+  metadata.gz: 14af794258be6bbcd416d3945fbec73db9af1fd88e35eb8ca8f91983cb768c547ef5ed67839d67659f4dbb52df84e5e4f293888c47ceaf4b9681d8904ec22eab
+  data.tar.gz: 9bd8449a841c46cee563ce97411b447c6534f42a8127b964e0fc2783136d0c7c32ae4eb5291f8a391d46c00b7e454b68165731287d2d7c5115b2f5e344897265

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tekservix
+
+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,128 @@
+# SMS Gora Ruby client
+
+[![Gem Version](https://badge.fury.io/rb/smsgora.svg)](https://rubygems.org/gems/smsgora)
+
+Ruby client for the [SMS Gora SMS Gateway](https://tekservix.com/smsgora/) API.
+
+SMS Gora turns Android phones with ordinary SIM cards into an SMS gateway. Your server calls the API, a linked phone sends the text, and replies and delivery reports come back to you. There's no sender ID registration and no per-message fee from us: your mobile operator bills the texts like any SMS.
+
+- Ruby 2.7+, no dependencies (standard library only)
+- Works in Rails, Sinatra, Hanami, Sidekiq jobs and scripts
+- Webhook signature check built in
+
+## Install
+
+```bash
+gem install smsgora
+```
+
+or in your Gemfile:
+
+```ruby
+gem 'smsgora'
+```
+
+## Quick start
+
+Create an API key in the SMS Gora dashboard (SMS Gora -> API keys) and keep it on your server.
+
+```ruby
+require 'smsgora'
+
+sms = SmsGora::Client.new(api_key: ENV['SMSGORA_KEY'])
+
+result = sms.send_sms(to: '+15551234567', message: 'Your verification code is 482913')
+result['message_ids'] # => [1873]
+```
+
+## Sending
+
+```ruby
+# Several recipients (up to 1,000 per call)
+sms.send_sms(to: ['+15551234567', '+447700900123'], message: 'Your order has shipped')
+
+# From a chosen phone and SIM, scheduled for later
+sms.send_sms(
+  to: '+15551234567',
+  message: 'Reminder: your appointment is tomorrow at 10:00',
+  device_id: 42,
+  sim_slot: 1, # 0 = SIM 1, 1 = SIM 2
+  schedule_at: Time.utc(2026, 12, 1, 8, 0)
+)
+
+# Different texts for different people in one call (up to 5,000 recipients)
+sms.send_bulk_sms(42,
+  message_template: 'Hello, your parcel is ready for pickup.',
+  messages: [
+    { recipients: ['+15551234567'], message: 'Hi Aline, parcel #1042 is ready.' },
+    { recipients: ['+15557654321'] }
+  ])
+```
+
+## Delivery status and incoming SMS
+
+```ruby
+msg = sms.get_message(1873)
+msg['status'] # queued -> dispatched -> sent -> delivered (or failed)
+
+sms.cancel_message(1874) # works while queued or scheduled
+
+inbox   = sms.list_received_sms(since: '2026-11-01', limit: 50)
+phones  = sms.list_devices
+account = sms.get_account
+```
+
+Anything else in the [API reference](https://tekservix.com/smsgora/docs/) is one call away:
+
+```ruby
+batch = sms.request(:get, '/batches/311')
+```
+
+## Webhooks
+
+Add your HTTPS URL in SMS Gora -> Webhooks (or with `create_webhook`) and keep the secret. Each request carries `X-SmsGora-Signature: sha256=...`, an HMAC-SHA256 of the raw body. Rails example:
+
+```ruby
+class SmsWebhooksController < ActionController::API
+  def create
+    unless SmsGora.verify_webhook(request.raw_post, request.headers['X-SmsGora-Signature'], ENV['SMSGORA_WEBHOOK_SECRET'])
+      return head :unauthorized
+    end
+
+    event = JSON.parse(request.raw_post)
+    if event['event'] == 'sms.received'
+      IncomingSmsJob.perform_later(event['data']['from'], event['data']['message'])
+    end
+    head :ok # answer within 10 seconds; do slow work in a job
+  end
+end
+```
+
+## Errors
+
+Failed calls raise `SmsGora::Error` with `status`, `message`, field `errors` and, on 429, `retry_after` in seconds.
+
+```ruby
+begin
+  sms.send_sms(to: '+15551234567', message: 'Hi')
+rescue SmsGora::Error => e
+  sleep(e.retry_after || 5) if e.status == 429 # 300 requests/minute per key, or plan limit
+end
+```
+
+Never put the key in JavaScript or a mobile app: anyone could read it. Call the API from your server.
+
+## Migrating from TextBee
+
+SMS Gora accepts TextBee-style requests, so most integrations switch by changing the base URL and key. See the [compatibility notes](https://tekservix.com/smsgora/docs/).
+
+## More from Tekservix
+
+- [WAservix WhatsApp API Gateway](https://tekservix.com/waservix/): send WhatsApp messages from your own number (`gem install waservix`)
+- [AI Sales Agent](https://tekservix.com/ai-sales-agent): answers customers on WhatsApp and SMS using your website's content
+- [Website to App](https://tekservix.com/mobile-apps): turn your website into Android and iOS apps
+- SMS Gora is also available for Node.js, Python, PHP, Go, Java/Kotlin and .NET: see [github.com/TekservixHQ](https://github.com/TekservixHQ)
+
+## License
+
+MIT

data/lib/smsgora.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'openssl'
+require 'time'
+require 'uri'
+
+# Ruby client for the SMS Gora SMS Gateway API.
+#
+#   sms = SmsGora::Client.new(api_key: ENV['SMSGORA_KEY'])
+#   sms.send_sms(to: '+15551234567', message: 'Your verification code is 482913')
+#
+# Docs: https://tekservix.com/smsgora/docs/
+module SmsGora
+  VERSION = '1.0.0'
+  DEFAULT_BASE_URL = 'https://tekservix.com/smsgora/api/v1'
+
+  # Raised when the API answers with an error.
+  class Error < StandardError
+    attr_reader :status, :errors, :body, :retry_after
+
+    def initialize(message, status: nil, errors: nil, body: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @errors = errors
+      @body = body
+      @retry_after = retry_after
+    end
+  end
+
+  class Client
+    attr_reader :base_url
+
+    # api_key: your SMS Gora API key (starts with sgk_). Keep it on your server.
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL, timeout: 30)
+      raise ArgumentError, 'SmsGora: api_key is required (create one in SMS Gora -> API keys)' if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.sub(%r{/+\z}, '')
+      @timeout = timeout
+    end
+
+    # Call any documented endpoint, e.g. request(:get, '/devices'). Returns the `data` field.
+    def request(method, path, body = nil)
+      uri = URI(@base_url + path)
+      klass = { get: Net::HTTP::Get, post: Net::HTTP::Post, put: Net::HTTP::Put, delete: Net::HTTP::Delete }.fetch(method.to_s.downcase.to_sym)
+      req = klass.new(uri)
+      req['x-api-key'] = @api_key
+      req['Accept'] = 'application/json'
+      req['User-Agent'] = "smsgora-ruby/#{VERSION}"
+      unless body.nil?
+        req['Content-Type'] = 'application/json'
+        req.body = JSON.generate(body)
+      end
+
+      res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https',
+                                                open_timeout: @timeout, read_timeout: @timeout) { |http| http.request(req) }
+      status = res.code.to_i
+      text = res.body.to_s
+      json = begin
+        text.empty? ? nil : JSON.parse(text)
+      rescue JSON::ParserError
+        nil
+      end
+
+      if status >= 400 || (json.is_a?(Hash) && json['success'] == false)
+        retry_after = res['Retry-After']
+        raise Error.new((json.is_a?(Hash) && json['message']) || "HTTP #{status}",
+                        status: status,
+                        errors: json.is_a?(Hash) ? json['errors'] : nil,
+                        body: json || text,
+                        retry_after: retry_after && Float(retry_after, exception: false))
+      end
+      json.is_a?(Hash) && json.key?('data') ? json['data'] : json
+    end
+
+    # Send an SMS to one number or up to 1,000. Picks your best online phone unless device_id is given.
+    # sim_slot: 0 = SIM 1, 1 = SIM 2. schedule_at: Time or ISO 8601 string.
+    def send_sms(to:, message:, device_id: nil, sim_slot: nil, schedule_at: nil)
+      body = { recipients: Array(to), message: message }
+      body[:sim_slot] = sim_slot unless sim_slot.nil?
+      body[:schedule_at] = schedule_at.respond_to?(:utc) ? schedule_at.utc.iso8601 : schedule_at if schedule_at
+      path = device_id ? "/devices/#{esc(device_id)}/send-sms" : '/send-sms'
+      request(:post, path, body)
+    end
+
+    # Different texts for different people in one call (up to 5,000 recipients).
+    # messages: [{ recipients: ['+1555...'], message: 'optional own text' }, ...]
+    def send_bulk_sms(device_id, messages:, message_template: nil)
+      body = { messages: messages }
+      body[:messageTemplate] = message_template if message_template
+      request(:post, "/devices/#{esc(device_id)}/send-bulk-sms", body)
+    end
+
+    # Status is queued, dispatched, sent, delivered, failed or cancelled.
+    def get_message(id)
+      request(:get, "/messages/#{esc(id)}")
+    end
+
+    # Cancel a queued or scheduled message.
+    def cancel_message(id)
+      request(:post, "/messages/#{esc(id)}/cancel")
+    end
+
+    # Filters: direction (in/out), status, device_id, phone, since, after_id, page, limit.
+    def list_messages(**filters)
+      request(:get, "/messages#{query(filters)}")
+    end
+
+    # Incoming SMS for all phones, or one phone with device_id.
+    def list_received_sms(device_id: nil, **filters)
+      path = device_id ? "/devices/#{esc(device_id)}/get-received-sms" : '/received-sms'
+      request(:get, path + query(filters))
+    end
+
+    def get_batch(id)
+      request(:get, "/batches/#{esc(id)}")
+    end
+
+    # Your linked Android phones.
+    def list_devices
+      request(:get, '/devices')
+    end
+
+    def get_device(id)
+      request(:get, "/devices/#{esc(id)}")
+    end
+
+    # Account, plan and usage.
+    def get_account
+      request(:get, '/account')
+    end
+
+    def list_webhooks
+      request(:get, '/webhooks')
+    end
+
+    # Register a webhook. The answer includes the secret (only returned once).
+    def create_webhook(url:, events: ['sms.received'], device_id: nil)
+      request(:post, '/webhooks', { url: url, events: events, device_id: device_id })
+    end
+
+    def delete_webhook(id)
+      request(:delete, "/webhooks/#{esc(id)}")
+    end
+
+    private
+
+    def esc(value)
+      URI.encode_www_form_component(value.to_s).gsub('+', '%20')
+    end
+
+    def query(params)
+      clean = params.reject { |_, v| v.nil? || v.to_s.empty? }
+      clean.empty? ? '' : "?#{URI.encode_www_form(clean)}"
+    end
+  end
+
+  # Check the X-SmsGora-Signature header (sha256=<hex HMAC-SHA256 of the raw body>).
+  # Pass the raw request body (e.g. request.raw_post in Rails), before JSON parsing.
+  def self.verify_webhook(raw_body, signature, secret)
+    return false if raw_body.nil? || raw_body.empty? || signature.nil? || signature.empty? || secret.nil? || secret.empty?
+
+    expected = "sha256=#{OpenSSL::HMAC.hexdigest('SHA256', secret, raw_body)}"
+    secure_compare(expected, signature.to_s)
+  end
+
+  # Constant-time string comparison (works on every Ruby version).
+  def self.secure_compare(a, b)
+    return false unless a.bytesize == b.bytesize
+
+    diff = 0
+    a.bytes.zip(b.bytes) { |x, y| diff |= x ^ y }
+    diff.zero?
+  end
+  private_class_method :secure_compare
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: smsgora
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Tekservix
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-10 00:00:00.000000000 Z
+dependencies: []
+description: 'Send and receive SMS through your own Android phones with SMS Gora:
+  delivery reports, scheduled and bulk sending, and signed webhooks. Works in Rails,
+  Sinatra and plain Ruby.'
+email: support@tekservix.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/smsgora.rb
+homepage: https://tekservix.com/smsgora/
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://tekservix.com/smsgora/
+  documentation_uri: https://tekservix.com/smsgora/docs/
+  source_code_uri: https://github.com/TekservixHQ/smsgora-ruby
+  bug_tracker_uri: https://github.com/TekservixHQ/smsgora-ruby/issues
+  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: '2.7'
+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: Official Ruby client for the SMS Gora SMS Gateway API
+test_files: []