ezacloud-sdk 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1658a6b210b8eb35fe76419f6e663a32bf00e57608732cdc929df8bb7a3c4e82
+  data.tar.gz: '093119db377c253025950995267b620ff174e556ad00a0fde5f21ebb67184d07'
+SHA512:
+  metadata.gz: ac1b28e9cf7b25e37feea948fb94c16d4cdc3c5d1cb8726881ee45b427d7c6a157255e65c79067730767fc87b738f6333a3c76622bad60e732c9d99c3f0bae9d
+  data.tar.gz: 95bdfd4f4d844a58634bcf918d601004da45345caeca1e6a50525022eca6522c3d6f6d25b69d3e9d4fc337f9c02fe06a9214dc45b282360bc7828bc7a5477b90

data/README.md

@@ -0,0 +1,57 @@
+# Eza Cloud SDK for Ruby (`ezacloud-sdk`)
+
+Official Ruby SDK for [Eza Cloud](https://eza.co.ke): PayEdge M-Pesa STK push, transactional emails, and cryptographically signed webhook verification.
+
+Zero third-party runtime dependencies. Built entirely with the Ruby standard library (`net/http`, `openssl`, `json`, `securerandom`).
+
+---
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem "ezacloud-sdk"
+```
+
+Or install directly:
+
+```bash
+gem install ezacloud-sdk
+```
+
+---
+
+## Usage
+
+```ruby
+require "eza"
+
+# Auto-configures using EZA_API_KEY, EZA_EMAIL_KEY from ENV on Eza Cloud pods
+eza = Eza.new(api_key: "eza_live_...")
+
+# 1. Trigger an M-Pesa STK push
+tx = eza.payedge.stk_push(
+  phone: "254712345678",
+  amount_kes: 1500,
+  account_reference: "INV1024"
+)
+puts "Transaction pending: #{tx['checkout_request_id']}"
+
+# 2. Send a transactional email
+mail = eza.emails.send(
+  from: "Shop <orders@mail.shop.co.ke>",
+  to: "wanjiku@gmail.com",
+  subject: "Your receipt",
+  html: "<p>Thank you for your order!</p>"
+)
+puts "Email sent: #{mail['id']}"
+
+# 3. Verify incoming webhook signatures
+event = Eza.verify_webhook(
+  request.raw_post,
+  request.headers["Eza-Signature"],
+  ENV["EZA_WEBHOOK_SECRET"]
+)
+puts "Verified event: #{event['type']}"
+```

data/lib/eza/client.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Eza
+  class Client
+    DEFAULT_EMAIL_URL   = "https://email.eza.co.ke"
+    DEFAULT_PAYEDGE_URL = "https://payedge.eza.co.ke"
+
+    attr_reader :api_key, :email_key, :email_url, :payedge_url, :max_retries, :payedge, :emails
+
+    def initialize(
+      api_key: nil,
+      email_key: nil,
+      email_url: nil,
+      payedge_url: nil,
+      max_retries: 2,
+      adapter: nil
+    )
+      @api_key = api_key || ENV["EZA_API_KEY"]
+      @email_key = email_key || ENV["EZA_EMAIL_KEY"] || @api_key
+      @email_url = (email_url || ENV["EZA_EMAIL_URL"] || DEFAULT_EMAIL_URL).chomp("/")
+      @payedge_url = (payedge_url || ENV["EZA_PAYEDGE_URL"] || DEFAULT_PAYEDGE_URL).chomp("/")
+      @max_retries = max_retries
+      @adapter = adapter
+
+      @payedge = PayEdge.new(self)
+      @emails = Emails.new(self)
+    end
+
+    def request(method, url_str, service:, body: nil, idempotency_key: nil)
+      auth_key = service == :email ? @email_key : @api_key
+      if auth_key.nil? || auth_key.empty?
+        service_name = service == :email ? "Email" : "PayEdge"
+        env_var = service == :email ? "EZA_EMAIL_KEY or EZA_API_KEY" : "EZA_API_KEY"
+        raise ConfigurationError, "No API key configured for #{service_name}. Pass api_key/email_key or set #{env_var}."
+      end
+
+      uri = URI.parse(url_str)
+      idempotency_key ||= SecureRandom.uuid if method.to_sym == :post
+
+      attempts = 0
+      loop do
+        attempts += 1
+        headers = {
+          "Authorization" => "Bearer #{auth_key}",
+          "Content-Type" => "application/json",
+          "Accept" => "application/json",
+          "User-Agent" => "eza-ruby/#{VERSION}"
+        }
+        headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+        begin
+          res_status, res_headers, res_body = execute_http(method, uri, headers, body)
+        rescue StandardError => e
+          if attempts <= @max_retries
+            sleep(0.1 * (2**(attempts - 1)))
+            next
+          end
+          raise
+        end
+
+        # Handle 429 Rate Limit (honor Retry-After)
+        if res_status == 429 && attempts <= @max_retries
+          retry_after = res_headers["retry-after"]
+          delay = retry_after ? [retry_after.to_f, 0.05].max : 0.2 * (2**(attempts - 1))
+          sleep(delay)
+          next
+        end
+
+        # Handle 503 / 504 Service Unavailable / Gateway Timeout
+        if (res_status == 503 || res_status == 504) && attempts <= @max_retries
+          sleep(0.1 * (2**(attempts - 1)))
+          next
+        end
+
+        if res_status >= 200 && res_status < 300
+          return res_body.empty? ? {} : JSON.parse(res_body)
+        end
+
+        raise Error.from_response(res_status, res_body, res_headers)
+      end
+    end
+
+    private
+
+    def execute_http(method, uri, headers, body)
+      if @adapter
+        return @adapter.call(method, uri, headers, body)
+      end
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      req_class = case method.to_sym
+                  when :post then Net::HTTP::Post
+                  when :get  then Net::HTTP::Get
+                  when :delete then Net::HTTP::Delete
+                  else Net::HTTP::Get
+                  end
+
+      req = req_class.new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = JSON.generate(body) if body
+
+      res = http.request(req)
+      res_headers = {}
+      res.each_header { |k, v| res_headers[k.downcase] = v }
+
+      [res.code.to_i, res_headers, res.body || ""]
+    end
+  end
+end

data/lib/eza/emails.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "base64"
+require "uri"
+
+module Eza
+  class Emails
+    def initialize(client)
+      @client = client
+    end
+
+    def send(from:, to:, subject:, text: nil, html: nil, cc: nil, bcc: nil, reply_to: nil, attachments: nil, idempotency_key: nil)
+      raise ArgumentError, "Must provide text or html content" if text.nil? && html.nil?
+
+      recipients = Array(to)
+      payload = {
+        from: from,
+        to: recipients,
+        subject: subject
+      }
+      payload[:text] = text if text
+      payload[:html] = html if html
+      payload[:cc] = Array(cc) if cc
+      payload[:bcc] = Array(bcc) if bcc
+      payload[:reply_to] = reply_to if reply_to
+
+      if attachments && !attachments.empty?
+        payload[:attachments] = attachments.map do |att|
+          content = att[:content]
+          encoded = if content.is_a?(String) && !att[:already_base64]
+                      Base64.strict_encode64(content)
+                    else
+                      content
+                    end
+          {
+            filename: att[:filename] || att["filename"],
+            content: encoded
+          }
+        end
+      end
+
+      @client.request(
+        :post,
+        "#{@client.email_url}/emails",
+        service: :email,
+        body: payload,
+        idempotency_key: idempotency_key
+      )
+    end
+
+    def get(id)
+      escaped = URI.encode_www_form_component(id)
+      @client.request(
+        :get,
+        "#{@client.email_url}/emails/#{escaped}",
+        service: :email
+      )
+    end
+  end
+end

data/lib/eza/errors.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Eza
+  class Error < StandardError
+    attr_reader :status, :code, :request_id, :fields
+
+    def self.from_response(status, body, headers = {})
+      data = begin
+        JSON.parse(body)
+      rescue StandardError
+        {}
+      end
+
+      request_id = headers["eza-request-id"] || headers["x-request-id"] || data["request_id"]
+      code = data["code"] || data["name"]
+      message = data["message"] || data["detail"] || "HTTP #{status}"
+      fields = data["fields"] || data["errors"]
+
+      new(message, status: status, code: code, request_id: request_id, fields: fields)
+    end
+
+    def initialize(message, status: nil, code: nil, request_id: nil, fields: nil)
+      @status = status
+      @code = code
+      @request_id = request_id
+      @fields = fields
+      super(build_message(message))
+    end
+
+    private
+
+    def build_message(base_message)
+      parts = []
+      parts << "[#{@code}]" if @code
+      parts << base_message
+      parts << "(status #{@status})" if @status
+      parts << "(request_id: #{@request_id})" if @request_id
+      parts.join(" ")
+    end
+  end
+
+  class SignatureError < StandardError; end
+  class ConfigurationError < StandardError; end
+end

data/lib/eza/payedge.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Eza
+  class PayEdge
+    def initialize(client)
+      @client = client
+    end
+
+    def stk_push(phone:, amount_kes:, account_reference:, description: nil, config_id: nil, idempotency_key: nil)
+      raise ArgumentError, "amount_kes must be an integer, got #{amount_kes.inspect}" unless amount_kes.is_a?(Integer)
+      raise ArgumentError, "amount_kes must be at least 1 KES" if amount_kes < 1
+
+      payload = {
+        phone: phone,
+        amount_kes: amount_kes,
+        account_reference: account_reference
+      }
+      payload[:description] = description if description
+      payload[:config_id] = config_id if config_id
+      payload[:idempotency_key] = idempotency_key if idempotency_key
+
+      @client.request(
+        :post,
+        "#{@client.payedge_url}/v1/stk-push",
+        service: :payedge,
+        body: payload,
+        idempotency_key: idempotency_key
+      )
+    end
+
+    def get_transaction(reference)
+      escaped = URI.encode_www_form_component(reference)
+      @client.request(
+        :get,
+        "#{@client.payedge_url}/v1/transactions/#{escaped}",
+        service: :payedge
+      )
+    end
+  end
+end

data/lib/eza/version.rb

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

data/lib/eza/webhook.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+
+module Eza
+  module Webhook
+    DEFAULT_TOLERANCE = 300
+
+    module_function
+
+    def verify(raw_body, signature_header, secret, tolerance: DEFAULT_TOLERANCE, now: nil)
+      raise SignatureError, "Missing raw body or signature header" if raw_body.nil? || signature_header.nil?
+      raise SignatureError, "Missing webhook secret" if secret.nil? || secret.empty?
+
+      timestamp = nil
+      signature = nil
+
+      signature_header.to_s.split(",").each do |part|
+        key, value = part.strip.split("=", 2)
+        case key
+        when "t"
+          timestamp = Integer(value, 10) rescue nil
+        when "v1"
+          signature = value
+        end
+      end
+
+      raise SignatureError, "Malformed signature header: missing timestamp or signature" if timestamp.nil? || signature.nil?
+
+      current_time = now ? now.to_i : Time.now.to_i
+      if (current_time - timestamp).abs > tolerance
+        raise SignatureError, "Webhook timestamp outside tolerance zone (#{tolerance}s)"
+      end
+
+      signed_payload = "t.#{timestamp}.#{raw_body}"
+      computed = OpenSSL::HMAC.hexdigest("SHA256", secret, signed_payload)
+
+      unless secure_compare(computed, signature)
+        raise SignatureError, "Webhook signature mismatch"
+      end
+
+      JSON.parse(raw_body)
+    end
+
+    def secure_compare(a, b)
+      return false unless a.is_a?(String) && b.is_a?(String) && a.bytesize == b.bytesize
+
+      if OpenSSL.respond_to?(:secure_compare)
+        OpenSSL.secure_compare(a, b)
+      else
+        res = 0
+        a.bytes.zip(b.bytes) { |x, y| res |= x ^ y }
+        res.zero?
+      end
+    end
+  end
+end

data/lib/eza.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "eza/version"
+require_relative "eza/errors"
+require_relative "eza/webhook"
+require_relative "eza/payedge"
+require_relative "eza/emails"
+require_relative "eza/client"
+
+module Eza
+  class << self
+    def new(**options)
+      Client.new(**options)
+    end
+
+    def verify_webhook(...)
+      Webhook.verify(...)
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: ezacloud-sdk
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Eza Cloud
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Zero-dependency Ruby client for Eza Cloud. Initiate M-Pesa STK pushes,
+  send transactional emails, and verify cryptographically signed webhooks.
+email:
+- support@eza.co.ke
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/eza.rb
+- lib/eza/client.rb
+- lib/eza/emails.rb
+- lib/eza/errors.rb
+- lib/eza/payedge.rb
+- lib/eza/version.rb
+- lib/eza/webhook.rb
+homepage: https://eza.co.ke/docs
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://eza.co.ke/docs
+  source_code_uri: https://github.com/ezacloud/eza/tree/main/sdks/ruby
+  documentation_uri: https://eza.co.ke/docs
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby SDK for Eza Cloud (PayEdge M-Pesa, Transactional Email, Webhooks)
+test_files: []