ternwire 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10179adca67dec7ba097d6b2595055038f15fa27f65cf87ac5c37df34b3b13fe
+  data.tar.gz: e7b1c6feff097229fa8dfc5b3735ef82531fa75cb64a169930cbbfb23dadb258
+SHA512:
+  metadata.gz: 478a9cb9bea050a2ecf89ee3009863c3ce36a7dcc2cf1b58a4ed72429bf7619c98d56f1e8174c22441cacaf7cac1cb9c02abe23ea6dfc1c63cb8fb3464c5810f
+  data.tar.gz: d3ed0c692a0df8003c172982bbe8f5fc7734296dddc2b15a97864999dbc4f418160552424863def77c07d00cc3db3607aee60dce83fa6f959f4745ba96d76bf3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BNSM s. r. o.
+
+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,43 @@
+# Ternwire Ruby SDK
+
+Ruby client for the Ternwire transactional email API, for Ruby 3.1+. Uses Net::HTTP,
+JSON, and OpenSSL from the Ruby distribution, with no other dependencies.
+
+Add `gem "ternwire"` to your Gemfile, or run `gem install ternwire`.
+
+```ruby
+require "ternwire"
+
+client = Ternwire::Client.new(
+  api_key: ENV.fetch("TERNWIRE_API_KEY"),
+  base_url: ENV.fetch("TERNWIRE_API_ORIGIN"),
+  timeout: 30
+)
+message = client.submit_email({
+  "from" => "notifications@your-verified-domain.com",
+  "to" => ["recipient@example.com"],
+  "subject" => "Your receipt",
+  "text" => "Thanks for your order."
+}, "order-123-receipt")
+puts client.get_message(message.fetch("id"))
+```
+
+All 17 operations use snake_case names and accept or return hashes with camelCase
+JSON keys. Template deletion returns `nil`. The client is synchronous.
+`list_email_templates(cursor: nil, limit: nil)` returns one page of summaries;
+pass the previous `page.nextCursor` as `cursor` to fetch the next page.
+
+Rescue `Ternwire::APIError` to inspect `status`, `body`, `raw_body`, and `headers`.
+Response headers are lowercase and map to arrays of values. Native network and
+timeout exceptions propagate separately.
+
+Use `Ternwire::Webhooks.verify(signature_header, raw_body, signing_secret)` before
+parsing the request. The optional `tolerance_seconds:` keyword defaults to 300.
+Use the exact body string without re-encoding or normalizing it.
+
+Set `TERNWIRE_API_KEY`, `TERNWIRE_API_ORIGIN`, `TERNWIRE_FROM`, and `TERNWIRE_TO`
+before deliberately running `ruby -Ilib examples/send.rb` from this directory.
+
+Use `https://ternwire.com` as the API origin. Read the full documentation at
+[ternwire.com/docs](https://ternwire.com/docs), or contact support@ternwire.com.
+Released under the MIT License.

data/examples/send.rb

@@ -0,0 +1,14 @@
+require "ternwire"
+
+client = Ternwire::Client.new(
+  api_key: ENV.fetch("TERNWIRE_API_KEY"),
+  base_url: ENV.fetch("TERNWIRE_API_ORIGIN")
+)
+accepted = client.submit_email({
+  "from" => ENV.fetch("TERNWIRE_FROM"),
+  "to" => [ENV.fetch("TERNWIRE_TO")],
+  "subject" => "Your receipt",
+  "text" => "Thanks for your order."
+}, "order-123-receipt")
+puts JSON.pretty_generate(accepted)
+puts JSON.pretty_generate(client.get_message(accepted.fetch("id")))

data/lib/ternwire/client.rb

@@ -0,0 +1,167 @@
+require "ipaddr"
+require "json"
+require "net/http"
+require "uri"
+
+module Ternwire
+  class APIError < StandardError
+    attr_reader :status, :raw_body, :body, :headers
+
+    def initialize(status, raw_body, headers)
+      super("Ternwire API returned HTTP #{status}")
+      @status, @raw_body, @headers = status, raw_body, headers
+      @body = begin
+        JSON.parse(raw_body)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+  end
+
+  class Client
+    def initialize(api_key:, base_url:, timeout: 30)
+      unless /\Aem_(live|test)_[A-Za-z0-9_-]+\z/.match?(api_key)
+        raise ArgumentError, "Use an em_live_ or em_test_ API key"
+      end
+      origin = URI.parse(base_url)
+      unless %w[http https].include?(origin.scheme) && origin.host && !origin.userinfo &&
+          ["", "/"].include?(origin.path) && !origin.query && !origin.fragment
+        raise ArgumentError, "base_url must be an HTTP(S) origin without /v1"
+      end
+      if origin.scheme == "http" && !loopback_host?(origin.hostname)
+        raise ArgumentError, "base_url must use https unless it points at localhost or a loopback address"
+      end
+      unless timeout.is_a?(Numeric) && timeout.finite? && timeout.positive?
+        raise ArgumentError, "timeout must be positive and finite"
+      end
+      @api_key, @base_url, @timeout = api_key, base_url.sub(%r{/+\z}, ""), timeout
+    end
+
+    # BEGIN GENERATED OPERATIONS
+    def submit_email(input, idempotency_key)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      raise ArgumentError, "idempotency_key is required" unless idempotency_key.is_a?(String)
+      request("POST", "/v1/emails", 202, input, idempotency_key)
+    end
+
+    def get_message(message_id)
+      request("GET", "/v1/emails/" + resource_id(message_id), 200, nil, nil)
+    end
+
+    def create_email_template(input)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      request("POST", "/v1/templates", 201, input, nil)
+    end
+
+    def list_email_templates(cursor: nil, limit: nil)
+      request("GET", "/v1/templates" + query_string(cursor: cursor, limit: limit), 200, nil, nil)
+    end
+
+    def get_email_template(template_id)
+      request("GET", "/v1/templates/" + resource_id(template_id), 200, nil, nil)
+    end
+
+    def replace_email_template(template_id, input)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      request("PUT", "/v1/templates/" + resource_id(template_id), 200, input, nil)
+    end
+
+    def delete_email_template(template_id)
+      request("DELETE", "/v1/templates/" + resource_id(template_id), 204, nil, nil)
+    end
+
+    def create_attachment_upload_slot(input)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      request("POST", "/v1/attachments", 201, input, nil)
+    end
+
+    def get_attachment(attachment_id)
+      request("GET", "/v1/attachments/" + resource_id(attachment_id), 200, nil, nil)
+    end
+
+    def complete_attachment_upload(attachment_id)
+      request("POST", "/v1/attachments/" + resource_id(attachment_id) + "/complete", 202, nil, nil)
+    end
+
+    def create_sending_domain(input)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      request("POST", "/v1/domains", 201, input, nil)
+    end
+
+    def get_sending_domain(domain_id)
+      request("GET", "/v1/domains/" + resource_id(domain_id), 200, nil, nil)
+    end
+
+    def delete_sending_domain(domain_id)
+      request("DELETE", "/v1/domains/" + resource_id(domain_id), 202, nil, nil)
+    end
+
+    def create_webhook_endpoint(input)
+      raise ArgumentError, "input must be a Hash" unless input.is_a?(Hash)
+      request("POST", "/v1/webhook-endpoints", 201, input, nil)
+    end
+
+    def rotate_webhook_endpoint_signing_secret(endpoint_id)
+      request("POST", "/v1/webhook-endpoints/" + resource_id(endpoint_id) + "/rotate-signing-secret", 200, nil, nil)
+    end
+
+    def get_webhook_attempt(attempt_id)
+      request("GET", "/v1/webhook-attempts/" + resource_id(attempt_id), 200, nil, nil)
+    end
+
+    def replay_webhook_attempt(attempt_id)
+      request("POST", "/v1/webhook-attempts/" + resource_id(attempt_id) + "/replay", 202, nil, nil)
+    end
+    # END GENERATED OPERATIONS
+
+    private
+
+    def resource_id(value)
+      raise ArgumentError, "Invalid Ternwire resource ID" unless /\A[a-z0-9][a-z0-9_-]{7,127}\z/.match?(value)
+      value
+    end
+
+    def query_string(values)
+      present = values.compact
+      present.empty? ? "" : "?" + URI.encode_www_form(present)
+    end
+
+    def loopback_host?(host)
+      host = host.downcase
+      return true if host == "localhost" || host.end_with?(".localhost")
+      IPAddr.new(host).loopback?
+    rescue IPAddr::Error
+      false
+    end
+
+    def request(method, path, expected_status, body = nil, idempotency_key = nil)
+      headers = { "Authorization" => "Bearer #{@api_key}", "Accept" => "application/json" }
+      if idempotency_key
+        unless /\A[\x21-\x7e]{1,128}\z/.match?(idempotency_key)
+          raise ArgumentError, "idempotency_key must contain 1-128 visible ASCII characters"
+        end
+        headers["Idempotency-Key"] = idempotency_key
+      end
+      uri = URI.parse(@base_url + path)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout
+      http.max_retries = 0
+      request = Net::HTTPGenericRequest.new(method, !body.nil?, true, uri.request_uri, headers)
+      unless body.nil?
+        raise ArgumentError, "body must be a Hash" unless body.is_a?(Hash)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+      response = http.request(request)
+      raw = response.body || ""
+      raise APIError.new(response.code.to_i, raw, response.to_hash) unless response.code.to_i == expected_status
+      return nil if expected_status == 204
+      result = JSON.parse(raw)
+      raise JSON::ParserError, "Ternwire API returned a non-object JSON response" unless result.is_a?(Hash)
+      result
+    end
+  end
+end

data/lib/ternwire/version.rb

@@ -0,0 +1,3 @@
+module Ternwire
+  VERSION = "0.1.0"
+end

data/lib/ternwire/webhooks.rb

@@ -0,0 +1,14 @@
+require "openssl"
+
+module Ternwire
+  module Webhooks
+    def self.verify(header, body, secret, tolerance_seconds: 300)
+      return false if secret.empty? || !tolerance_seconds.finite? || tolerance_seconds.negative?
+      match = /\A\s*t=([1-9][0-9]{0,11})\s*,\s*v1=([a-f0-9]{64})\s*\z/.match(header)
+      return false unless match && (Time.now.to_i - match[1].to_i).abs <= tolerance_seconds
+      payload = "#{match[1]}.".b + body.b
+      expected = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+      OpenSSL.fixed_length_secure_compare(expected, match[2])
+    end
+  end
+end

data/lib/ternwire.rb

@@ -0,0 +1,3 @@
+require_relative "ternwire/version"
+require_relative "ternwire/client"
+require_relative "ternwire/webhooks"

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: ternwire
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ternwire
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/send.rb
+- lib/ternwire.rb
+- lib/ternwire/client.rb
+- lib/ternwire/version.rb
+- lib/ternwire/webhooks.rb
+homepage: https://ternwire.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ternwire/ternwire-ruby
+  documentation_uri: https://ternwire.com/docs
+  bug_tracker_uri: https://ternwire.com/contact
+  rubygems_mfa_required: 'true'
+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.6.9
+specification_version: 4
+summary: Ruby client for the Ternwire transactional email API
+test_files: []