misarmail 1.0.0

data/lib/misar_mail/core/query.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module MisarMail
+  module Core
+    # Query-string encoding shared by every generated GET/DELETE method.
+    module Query
+      # Returns "" for an empty bag so a generated call site can always append
+      # unconditionally. Nil values are dropped so optional filters stay out of
+      # the URL entirely rather than being sent as the string "".
+      def self.encode(params)
+        return "" if params.nil? || params.empty?
+
+        pairs = params.reject { |_, v| v.nil? }
+                      .map { |k, v| "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}" }
+        pairs.empty? ? "" : "?#{pairs.join('&')}"
+      end
+    end
+  end
+end

data/lib/misar_mail/core/sse.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module MisarMail
+  module Core
+    # Server-Sent Events client for the MisarMail streaming endpoints.
+    #
+    # Both streams frame events as "data: <json>" and close with the sentinel
+    # "data: [DONE]". One of the two is a POST, so this reads the response body
+    # incrementally rather than using an EventSource-style helper.
+    module SSE
+      DONE = "[DONE]"
+
+      module_function
+
+      # Yields one decoded payload per event until the stream terminates.
+      def stream(url, api_key, method: "GET", body: nil)
+        return enum_for(:stream, url, api_key, method: method, body: body) unless block_given?
+
+        uri = URI.parse(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = 300
+
+        headers = {
+          "Authorization" => "Bearer #{api_key}",
+          "Accept" => "text/event-stream"
+        }
+        headers["Content-Type"] = "application/json" unless body.nil?
+
+        request = Net::HTTP.const_get(method.capitalize).new(uri.request_uri, headers)
+        request.body = JSON.generate(body) unless body.nil?
+
+        http.request(request) do |response|
+          # Errors arrive as a normal JSON body, not as an SSE frame.
+          if response.code.to_i >= 400
+            data = begin
+              JSON.parse(response.read_body)
+            rescue StandardError
+              {}
+            end
+            raise MisarMail::Error.new(response.code.to_i, data["error"].to_s, "api_error", data)
+          end
+
+          buffer = +""
+          response.read_body do |chunk|
+            buffer << chunk
+            while (index = buffer.index("\n"))
+              line = buffer.slice!(0..index).chomp
+              next unless line.start_with?("data:")
+
+              payload = line[5..].strip
+              return if payload == DONE
+              next if payload.empty?
+
+              begin
+                yield JSON.parse(payload)
+              rescue JSON::ParserError
+                # One malformed frame should not discard everything already
+                # streamed.
+                yield({ "raw" => payload })
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/misar_mail/core/transport.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+require_relative "../errors"
+
+module MisarMail
+  module Core
+    # HTTP transport shared by the generated resource layer.
+    #
+    # Everything the SDK does goes through one of three transports — HTTP for
+    # REST, SSE for streaming, WebSocket for push — and all three authenticate
+    # the same way: the account API key, sent as a bearer token. There is no
+    # second credential path. What a key may do, and how much of it, is decided
+    # server-side from the subscription behind that key.
+    class Transport
+      RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+
+      attr_reader :api_key, :base_url
+
+      def initialize(api_key, base_url: "https://api.misar.io/mail", max_retries: 3, timeout: 30)
+        raise ArgumentError, "A MisarMail API key is required" if api_key.nil? || api_key.empty?
+
+        @api_key = api_key
+        @base_url = base_url.chomp("/")
+        @max_retries = max_retries
+        @timeout = timeout
+      end
+
+      def request(method, path, body = nil)
+        uri = URI.parse("#{@base_url}#{path}")
+        attempt = 0
+
+        loop do
+          response = perform(uri, method, body)
+
+          if RETRYABLE_STATUSES.include?(response.code.to_i) && attempt < @max_retries - 1
+            sleep(backoff(attempt, response))
+            attempt += 1
+            next
+          end
+
+          return decode(response)
+        rescue StandardError => e
+          raise if e.is_a?(MisarMail::Error)
+
+          if attempt < @max_retries - 1
+            sleep(backoff(attempt))
+            attempt += 1
+            next
+          end
+          raise MisarMail::NetworkError.new(e.message)
+        end
+      end
+
+      def headers
+        {
+          "Authorization" => "Bearer #{@api_key}",
+          "Content-Type" => "application/json"
+        }
+      end
+
+      private
+
+      def perform(uri, method, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = @timeout
+        http.open_timeout = @timeout
+
+        request_class = Net::HTTP.const_get(method.to_s.capitalize)
+        req = request_class.new(uri.request_uri, headers)
+        req.body = JSON.generate(body) unless body.nil?
+        http.request(req)
+      end
+
+      def decode(response)
+        status = response.code.to_i
+        data = begin
+          response.body.nil? || response.body.empty? ? {} : JSON.parse(response.body)
+        rescue JSON::ParserError
+          {}
+        end
+
+        if status >= 400
+          message = data["error"] || data["message"] || response.message
+          raise MisarMail::Error.new(status, message.to_s, data["error_type"] || "api_error", data)
+        end
+
+        data
+      end
+
+      # Exponential backoff, but honour Retry-After when the server sends one:
+      # on a 429 the server knows when the window reopens, and guessing wastes
+      # the caller's remaining budget.
+      def backoff(attempt, response = nil)
+        if response
+          header = response["retry-after"]
+          return [header.to_f, 60].min if header && header.to_f.positive?
+        end
+        0.2 * (2**attempt)
+      end
+    end
+  end
+end

data/lib/misar_mail/core/webhooks.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module MisarMail
+  # Inbound webhook signature verification.
+  #
+  # MisarMail signs each webhook as HMAC-SHA256(timestamp + "." + raw_body) with
+  # the endpoint's signing secret, sending the digest in X-Misar-Signature and
+  # the Unix timestamp in X-Misar-Timestamp.
+  #
+  # Verify against the RAW body, not a re-serialized hash: key order and
+  # whitespace both change the digest. The comparison is constant-time so a
+  # timing oracle cannot recover the digest byte by byte.
+  module Webhooks
+    DEFAULT_TOLERANCE_SECONDS = 300
+
+    module_function
+
+    # Returns true when the signature is authentic and the timestamp is fresh.
+    # Never raises on malformed input — a bad signature is false, not an error.
+    def verify(payload:, signature:, timestamp:, secret:, tolerance: DEFAULT_TOLERANCE_SECONDS)
+      return false if [payload, signature, timestamp, secret].any? { |v| v.nil? || v.to_s.empty? }
+
+      sent_at = Float(timestamp) rescue (return false)
+
+      # Rejecting stale timestamps is what stops a captured request from being
+      # replayed forever, so this is a real check rather than a formality.
+      return false if (Time.now.to_f - sent_at).abs > tolerance
+
+      secure_compare(sign(payload, timestamp, secret), signature.strip)
+    end
+
+    # Constant-time comparison. OpenSSL.fixed_length_secure_compare exists only
+    # on newer Rubies and raises on length mismatch (which itself leaks length),
+    # so compare lengths first and then XOR every byte regardless of where the
+    # first difference is.
+    def secure_compare(expected, actual)
+      return false unless expected.bytesize == actual.bytesize
+
+      difference = 0
+      expected.bytes.zip(actual.bytes) { |a, b| difference |= a ^ b }
+      difference.zero?
+    end
+
+    # Produces the digest MisarMail sends. Exported because verification is only
+    # half the job: testing a webhook consumer needs a valid signature, and the
+    # exact framing is where that usually goes wrong.
+    def sign(payload, timestamp, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{payload}")
+    end
+  end
+end

data/lib/misar_mail/errors.rb

@@ -0,0 +1,59 @@
+module MisarMail
+  class ApiError < StandardError
+    attr_reader :status, :error_type
+
+    def initialize(status, message, error_type = "api_error")
+      @status = status
+      @error_type = error_type
+      super("misar-mail: API error #{status} (#{error_type}): #{message}")
+    end
+
+    def self.from_response(response)
+      body = begin
+        JSON.parse(response.body)
+      rescue StandardError
+        {}
+      end
+      new(response.status, body["error"] || response.reason_phrase || "unknown error")
+    end
+  end
+
+  # Raised when the subscription attached to the API key blocks the call.
+  #
+  # MisarMail meters per-plan server-side: a spent allowance answers 429 and a
+  # feature not on the plan answers 402. Raised as its own class rather than a
+  # generic 429 because retrying cannot help until the allowance resets or the
+  # plan changes — the client stops retrying on sight.
+  class PlanLimitError < ApiError
+    # @return [String, nil] the account's current plan slug
+    attr_reader :plan
+    # @return [String, nil] pricing page to send the user to
+    attr_reader :upgrade_url
+    # @return [Integer, nil] seconds until the allowance resets
+    attr_reader :retry_after
+    # @return [String, nil] the allowance that was exhausted
+    attr_reader :feature
+
+    def initialize(status, message, body = nil, headers = {})
+      body    ||= {}
+      headers   = (headers || {}).transform_keys { |k| k.to_s.downcase }
+      offer     = body["upgrade"].is_a?(Hash) ? body["upgrade"] : {}
+      # Headers are authoritative; the offer body is the fallback when a proxy
+      # has stripped them.
+      @plan        = headers["x-misar-plan"] || offer["currentPlanSlug"] ||
+                     offer.dig("current_plan", "slug")
+      @upgrade_url = headers["x-misar-upgrade-url"] || offer.dig("urls", "pricing")
+      ra           = headers["retry-after"]
+      @retry_after = ra.to_s.match?(/\A\d+\z/) ? ra.to_i : nil
+      @feature     = offer["feature"]
+      super(status, message, "plan_limit_exceeded")
+    end
+  end
+
+  class NetworkError < ApiError
+    def initialize(message, cause = nil)
+      super(0, message, "network_error")
+      @cause = cause
+    end
+  end
+end

data/lib/misar_mail.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative "misar_mail/errors"
+require_relative "misar_mail/core/webhooks"
+require_relative "misar_mail/client"
+
+module MisarMail
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,101 @@
+--- !ruby/object:Gem::Specification
+name: misarmail
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Misar AI
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.22'
+description: Full-featured Ruby SDK for the MisarMail API (misarmail.com). Covers
+  all 24 resource groups and 101 methods.
+email:
+- hello@misar.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/misar_mail.rb
+- lib/misar_mail/client.rb
+- lib/misar_mail/core/query.rb
+- lib/misar_mail/core/sse.rb
+- lib/misar_mail/core/transport.rb
+- lib/misar_mail/core/webhooks.rb
+- lib/misar_mail/errors.rb
+homepage: https://misarmail.com/docs/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://misarmail.com/docs/sdks/ruby
+  source_code_uri: https://github.com/Misar-AI/misarmail-sdks
+  changelog_uri: https://github.com/Misar-AI/misarmail-sdks/blob/main/ruby/CHANGELOG.md
+  bug_tracker_uri: https://github.com/Misar-AI/misarmail-sdks/issues
+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 SDK for MisarMail — transactional email, campaigns, leads,
+  CRM
+test_files: []