runearc 0.1.0

data/lib/runearc/webhook.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Runearc
+  # Standard Webhooks verification (https://www.standardwebhooks.com). Mirrors
+  # +runearc_core::webhooks::sign+:
+  #
+  #   signature = "v1," + base64(HMAC-SHA256(base64decode(secret without "whsec_"),
+  #                                          "{webhook-id}.{webhook-timestamp}.{body}"))
+  module Webhook
+    # Signatures older or newer than this many seconds are refused (replay protection).
+    TOLERANCE_SECONDS = 5 * 60
+
+    HEADER_NAMES = %w[webhook-id webhook-timestamp webhook-signature].freeze
+    private_constant :HEADER_NAMES
+
+    # Checks that a webhook request came from Runearc and is fresh, then returns the parsed event.
+    #
+    # @param payload [String] the raw request body, exactly as received; do not parse it and serialize it again
+    # @param headers [Hash, #[]] the request headers: a Hash with keys in any case (or Rack style
+    #   +HTTP_WEBHOOK_ID+ keys), or any object that answers +headers["webhook-id"]+
+    # @param secret [String] the endpoint's signing secret, +whsec_...+, from +webhooks.create+
+    # @param tolerance [Integer] seconds of clock difference allowed (default 300)
+    # @param now [Integer, nil] for tests: the current time in seconds since the epoch
+    # @return [Hash] the event: +:id+, +:type+, +:timestamp+ and +:data+ (symbol keys)
+    # @raise [WebhookVerificationError] when the payload is not a genuine, fresh Runearc webhook;
+    #   its +code+ is +missing_headers+, +invalid_timestamp+, +timestamp_out_of_range+, +invalid_secret+,
+    #   +invalid_signature+ or +invalid_payload+
+    def self.verify(payload:, headers:, secret:, tolerance: TOLERANCE_SECONDS, now: nil)
+      id, timestamp, signatures = HEADER_NAMES.map { |name| header(headers, name) }
+      if [id, timestamp, signatures].any? { |v| v.nil? || v.empty? }
+        raise WebhookVerificationError.new(
+          "the webhook-id, webhook-timestamp and webhook-signature headers are required",
+          code: "missing_headers",
+          fix: "Pass the request headers unchanged; check that a proxy does not strip them"
+        )
+      end
+      check_timestamp(timestamp, tolerance, now || Time.now.to_i)
+
+      body = payload.to_s.b
+      expected = OpenSSL::HMAC.digest("SHA256", decode_secret(secret), "#{id}.#{timestamp}.".b + body)
+      raise_invalid_signature unless signatures.split.any? { |part| match?(part, expected) }
+
+      parse(body)
+    end
+
+    def self.check_timestamp(timestamp, tolerance, now)
+      unless timestamp.strip.match?(/\A\d+\z/)
+        raise WebhookVerificationError.new(
+          "webhook-timestamp is not a number of seconds", code: "invalid_timestamp"
+        )
+      end
+      return if (now - timestamp.to_i).abs <= tolerance
+
+      raise WebhookVerificationError.new(
+        "the webhook timestamp is more than #{tolerance} seconds from now",
+        code: "timestamp_out_of_range",
+        fix: "Check your server clock; old deliveries are refused to stop replays"
+      )
+    end
+
+    def self.decode_secret(secret)
+      secret.to_s.strip.delete_prefix("whsec_").unpack1("m0")
+    rescue ArgumentError
+      raise WebhookVerificationError.new(
+        "the webhook secret is not valid base64",
+        code: "invalid_secret",
+        fix: "Use the secret returned by webhooks.create, which starts with whsec_"
+      )
+    end
+
+    def self.match?(part, expected)
+      version, sig = part.split(",", 2)
+      return false unless version == "v1" && sig
+
+      given = sig.unpack1("m0")
+      given.bytesize == expected.bytesize && OpenSSL.fixed_length_secure_compare(given, expected)
+    rescue ArgumentError
+      false
+    end
+
+    def self.raise_invalid_signature
+      raise WebhookVerificationError.new(
+        "no webhook-signature matches the payload",
+        code: "invalid_signature",
+        fix: "Verify the raw body (not JSON parsed and serialized again) with this endpoint's whsec_ secret"
+      )
+    end
+
+    def self.parse(body)
+      JSON.parse(body.dup.force_encoding(Encoding::UTF_8), symbolize_names: true)
+    rescue JSON::ParserError
+      raise WebhookVerificationError.new("the webhook body is not JSON", code: "invalid_payload")
+    end
+
+    def self.header(headers, name)
+      value = lookup(headers, name)
+      value = value.join(" ") if value.is_a?(Array)
+      value&.to_s
+    end
+
+    def self.lookup(headers, name)
+      return headers[name] unless headers.is_a?(Hash)
+
+      wanted = name.tr("-", "_")
+      headers.each do |key, value|
+        return value if key.to_s.downcase.delete_prefix("http_").tr("-", "_") == wanted
+      end
+      nil
+    end
+
+    private_class_method :check_timestamp, :decode_secret, :match?, :raise_invalid_signature, :parse, :header, :lookup
+  end
+
+  # Same as {Webhook.verify}.
+  #
+  # @return [Hash]
+  def self.verify_webhook(**kwargs)
+    Webhook.verify(**kwargs)
+  end
+end

data/lib/runearc.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "runearc/version"
+
+# The official Ruby SDK for the Runearc email API. Start with {Runearc::Client}.
+module Runearc
+  # The API origin used when neither +base_url:+ nor +RUNEARC_BASE_URL+ is set.
+  DEFAULT_BASE_URL = "https://api.runearc.com"
+end
+
+require_relative "runearc/errors"
+require_relative "runearc/support"
+require_relative "runearc/webhook"
+require_relative "runearc/resources"
+require_relative "runearc/client"

data/sig/runearc.rbs

@@ -0,0 +1,171 @@
+module Runearc
+  VERSION: String
+  DEFAULT_BASE_URL: String
+
+  type json = Hash[Symbol, untyped]
+  type time = Time | String
+
+  def self.verify_webhook: (payload: String, headers: untyped, secret: String, ?tolerance: Integer, ?now: Integer?) -> json
+
+  class Error < StandardError
+    attr_reader status: Integer
+    attr_reader code: String
+    attr_reader kind: String?
+    attr_reader fix: String?
+    attr_reader errors: Array[json]?
+    attr_reader retry_after: Integer?
+
+    def initialize: (?String? message, ?status: Integer, ?code: String, ?kind: String?, ?fix: String?, ?errors: Array[json]?, ?retry_after: Integer?) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class ConnectionError < Error
+  end
+
+  class TimeoutError < ConnectionError
+  end
+
+  class WebhookVerificationError < Error
+  end
+
+  class ApiError < Error
+    def self.build: (String message, status: Integer, **untyped fields) -> ApiError
+  end
+
+  class InvalidRequestError < ApiError
+  end
+
+  class AuthenticationError < ApiError
+  end
+
+  class LimitReachedError < ApiError
+  end
+
+  class PermissionError < ApiError
+  end
+
+  class NotFoundError < ApiError
+  end
+
+  class ConflictError < ApiError
+  end
+
+  class RateLimitError < ApiError
+  end
+
+  class ServerError < ApiError
+  end
+
+  module Webhook
+    TOLERANCE_SECONDS: Integer
+
+    def self.verify: (payload: String, headers: untyped, secret: String, ?tolerance: Integer, ?now: Integer?) -> json
+  end
+
+  class Resource
+    def initialize: (Client client) -> void
+  end
+
+  class Emails < Resource
+    def deliver: (?idempotency_key: String?, ?request_timeout: Numeric?, **untyped email) -> json
+    def batch: (Array[json] emails, ?batch_validation: (String | Symbol)?, ?idempotency_key: String?, ?request_timeout: Numeric?) -> json
+    def get: (String id, ?request_timeout: Numeric?) -> json
+    def list: (?limit: Integer?, ?cursor: String?, ?request_timeout: Numeric?) -> json
+    def update: (String id, scheduled_at: time, ?request_timeout: Numeric?) -> json
+    def reschedule: (String id, time scheduled_at, ?request_timeout: Numeric?) -> json
+    def cancel: (String id, ?request_timeout: Numeric?) -> json
+  end
+
+  class Senders < Resource
+    def list: (?request_timeout: Numeric?) -> json
+  end
+
+  class Inboxes < Resource
+    def create: (?local_part: String?, ?display_name: String?, ?domain: String?, ?request_timeout: Numeric?) -> json
+    def list: (?request_timeout: Numeric?) -> json
+    def get: (String id, ?request_timeout: Numeric?) -> json
+    def delete: (String id, ?request_timeout: Numeric?) -> nil
+  end
+
+  class Messages < Resource
+    def list: (String inbox_id, ?limit: Integer?, ?cursor: String?, ?request_timeout: Numeric?) -> json
+    def get: (String id, ?request_timeout: Numeric?) -> json
+    def raw: (String id, ?request_timeout: Numeric?) -> String
+    def wait: (String inbox_id, ?from: String?, ?subject: String?, ?to: String?, ?timeout: Integer, ?after: time?, ?request_timeout: Numeric?) -> json?
+    def deliver: (String inbox_id, ?idempotency_key: String?, ?request_timeout: Numeric?, **untyped message) -> json
+    def reply: (String message_id, ?idempotency_key: String?, ?request_timeout: Numeric?, **untyped reply) -> json
+  end
+
+  class Threads < Resource
+    def list: (String inbox_id, ?request_timeout: Numeric?) -> json
+    def get: (String id, ?request_timeout: Numeric?) -> json
+  end
+
+  class Conversations < Resource
+    def list: (?status: String?, ?assignee: String?, ?inbox_id: String?, ?q: String?, ?cursor: String?, ?limit: Integer?, ?request_timeout: Numeric?) -> json
+    def counts: (?request_timeout: Numeric?) -> json
+    def update: (String id, ?request_timeout: Numeric?, **untyped fields) -> json
+    def read: (String id, ?request_timeout: Numeric?) -> nil
+    def unread: (String id, ?request_timeout: Numeric?) -> nil
+  end
+
+  class Domains < Resource
+    def create: (name: String, ?request_timeout: Numeric?) -> json
+    def list: (?request_timeout: Numeric?) -> json
+    def get: (String id, ?request_timeout: Numeric?) -> json
+    def delete: (String id, ?request_timeout: Numeric?) -> nil
+    def verify: (String id, ?request_timeout: Numeric?) -> json
+  end
+
+  class Webhooks < Resource
+    def create: (url: String, ?event_types: Array[String]?, ?inbox_id: String?, ?request_timeout: Numeric?) -> json
+    def list: (?request_timeout: Numeric?) -> json
+    def delete: (String id, ?request_timeout: Numeric?) -> nil
+    def deliveries: (String id, ?limit: Integer?, ?request_timeout: Numeric?) -> json
+    def replay: (String id, String delivery_id, ?request_timeout: Numeric?) -> json
+    def verify: (payload: String, headers: untyped, secret: String, ?tolerance: Integer, ?now: Integer?) -> json
+  end
+
+  class Keys < Resource
+    def create: (name: String, ?permissions: String?, ?inbox_id: String?, ?domain_id: String?, ?request_timeout: Numeric?) -> json
+    def list: (?request_timeout: Numeric?) -> json
+    def delete: (String id, ?request_timeout: Numeric?) -> nil
+  end
+
+  class Suppressions < Resource
+    def list: (?request_timeout: Numeric?) -> json
+    def delete: (String address, ?request_timeout: Numeric?) -> nil
+  end
+
+  class Events < Resource
+    def list: (?after: String?, ?limit: Integer?, ?request_timeout: Numeric?) -> json
+  end
+
+  class Client
+    DEFAULT_MAX_RETRIES: Integer
+    DEFAULT_TIMEOUT: Integer
+    MAX_RETRY_WAIT: Integer
+
+    attr_reader base_url: String
+    attr_reader max_retries: Integer
+    attr_reader timeout: Numeric
+    attr_reader emails: Emails
+    attr_reader senders: Senders
+    attr_reader inboxes: Inboxes
+    attr_reader messages: Messages
+    attr_reader threads: Threads
+    attr_reader conversations: Conversations
+    attr_reader domains: Domains
+    attr_reader webhooks: Webhooks
+    attr_reader keys: Keys
+    attr_reader suppressions: Suppressions
+    attr_reader events: Events
+
+    def initialize: (?String? api_key, ?base_url: String?, ?max_retries: Integer, ?timeout: Numeric, ?headers: Hash[String, String]) -> void
+    def inspect: () -> String
+    def request: (Symbol method, String path, ?query: Hash[Symbol, untyped]?, ?body: untyped, ?headers: Hash[String, String]?, ?sends_mail: bool, ?idempotent: bool, ?text: bool, ?idempotency_key: String?, ?request_timeout: Numeric?) -> untyped
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: runearc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Runearc
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-15 00:00:00.000000000 Z
+dependencies: []
+description: Send, batch and schedule email, create inboxes your agents can read,
+  manage domains and verify webhooks with the Runearc API. Standard library only.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/runearc.rb
+- lib/runearc/client.rb
+- lib/runearc/errors.rb
+- lib/runearc/resources.rb
+- lib/runearc/support.rb
+- lib/runearc/version.rb
+- lib/runearc/webhook.rb
+- sig/runearc.rbs
+homepage: https://runearc.com/integrations/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://runearc.com/integrations/ruby
+  source_code_uri: https://github.com/runearc-labs/runearc-ruby
+  bug_tracker_uri: https://github.com/runearc-labs/runearc-ruby/issues
+  documentation_uri: https://runearc.com/docs/sdk
+  changelog_uri: https://github.com/runearc-labs/runearc-ruby/blob/main/CHANGELOG.md
+  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: 'Official Runearc SDK for Ruby: send and schedule email, read agent inboxes,
+  manage domains, verify webhooks.'
+test_files: []