sendclipper 0.1.0

data/lib/sendclipper/result.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module SendClipper
+  # What an API refusal or a network failure looks like.
+  #
+  # +name+ is SendClipper's machine-readable code (+domain_not_verified+,
+  # +validation_failed+, +rate_limited+, +network_error+, ...), +message+ a
+  # sentence for a person, +status_code+ the HTTP status (+nil+ when no
+  # answer arrived) and +detail+ any code-specific facts.
+  ErrorResponse = Struct.new(:name, :message, :status_code, :detail, keyword_init: true) do
+    def to_s = "#{name}: #{message}"
+  end
+
+  # Every API method returns one. Exactly one of +data+ and +error+ is set.
+  # It destructures to +data, error+:
+  #
+  #   data, error = client.emails.send(from: "...", to: "...", subject: "Hi", html: "<p>Hi</p>")
+  class Result
+    attr_reader :data, :error, :headers
+
+    def initialize(data, error, headers)
+      @data = data
+      @error = error
+      # Response headers with lower-case names, or nil when no answer arrived.
+      @headers = headers
+      freeze
+    end
+
+    def ok? = error.nil?
+
+    # +data+, or raise the error as a SendClipper::ApiError.
+    def unwrap
+      return data if error.nil?
+
+      raise ApiError.new(error.status_code || 0, error.name, error.message, error.detail, headers || {})
+    end
+    alias value! unwrap
+
+    def to_ary = [data, error]
+
+    def deconstruct = [data, error]
+
+    def deconstruct_keys(_keys) = { data: data, error: error, headers: headers }
+
+    def inspect = error ? "#<SendClipper::Result error=#{error.to_h}>" : "#<SendClipper::Result data=#{data.inspect}>"
+  end
+
+  # What a download returns.
+  DownloadedFile = Struct.new(:content, :content_type, :filename, keyword_init: true)
+end

data/lib/sendclipper/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SendClipper
+  # Kept equal to the release tag by CI.
+  VERSION = "0.1.0"
+end

data/lib/sendclipper/webhook.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module SendClipper
+  # SendClipper's documented tolerance: five minutes.
+  WEBHOOK_TOLERANCE_SECONDS = 300
+  SIGNATURE_HEADER = "x-sendclipper-signature-v2"
+
+  module_function
+
+  # Verify a webhook delivery and return its parsed event (a Hash).
+  #
+  # +payload+ is the body EXACTLY as received (+request.raw_post+ in Rails,
+  # +request.body.read+ in Rack/Sinatra), never re-encoded JSON. +headers+ is
+  # the request's headers (Rails +request.headers+, a Rack env, a Hash) or the
+  # X-SendClipper-Signature-V2 value itself.
+  #
+  # SendClipper signs "#{timestamp}.#{raw_body}" with HMAC-SHA256 and sends
+  # X-SendClipper-Signature-V2: t=<seconds>,v1=<hex>[,v1=<hex>]. During a
+  # secret rotation there are two v1= values; any match is accepted.
+  #
+  # Raises SendClipper::WebhookVerificationError when any check fails.
+  def verify_webhook(payload, headers, secret, tolerance: WEBHOOK_TOLERANCE_SECONDS, now: nil)
+    raise WebhookVerificationError.new("missing_header", "No webhook signing secret was given.") if secret.to_s.empty?
+    unless payload.is_a?(String)
+      raise WebhookVerificationError.new("invalid_payload",
+                                         "payload must be the raw request body as a String, not parsed JSON. " \
+                                         "Use request.raw_post in Rails or request.body.read in Rack.")
+    end
+
+    header = signature_header_of(headers)
+    raise WebhookVerificationError.new("missing_header", "The request carries no X-SendClipper-Signature-V2 header.") if header.to_s.empty?
+
+    timestamp, signatures = parse_signature_header(header)
+    if timestamp.nil? || signatures.empty?
+      raise WebhookVerificationError.new("malformed_header", "X-SendClipper-Signature-V2 has no t= or no v1= value.")
+    end
+
+    drift = ((now || Time.now).to_i - timestamp).abs
+    if drift > tolerance
+      raise WebhookVerificationError.new("timestamp_out_of_tolerance",
+                                         "The delivery was signed #{drift} s from now, outside the #{tolerance} s tolerance.")
+    end
+
+    expected = sign_payload(secret, timestamp, payload)
+    # ANY match, and every candidate is compared: a rotation sends two.
+    matched = signatures.map { |candidate| secure_compare(expected, candidate) }.any?
+    raise WebhookVerificationError.new("signature_mismatch", "The signature does not match this secret and body.") unless matched
+
+    event = begin
+      JSON.parse(payload.dup.force_encoding("UTF-8"))
+    rescue JSON::ParserError
+      nil
+    end
+    raise WebhookVerificationError.new("invalid_payload", "The signed body is not a JSON object.") unless event.is_a?(Hash)
+
+    event
+  end
+
+  # hex(HMAC-SHA256(secret, "#{timestamp}.#{raw_body}")). Exported for tests of your own handler.
+  def sign_payload(secret, timestamp, raw_body)
+    OpenSSL::HMAC.hexdigest("SHA256", secret.to_s, "#{timestamp}.".b + raw_body.to_s.b)
+  end
+
+  # Build a valid header for a body, e.g. to test your endpoint locally.
+  def webhook_signature_header(secret, raw_body, timestamp = Time.now.to_i)
+    "t=#{timestamp},v1=#{sign_payload(secret, timestamp, raw_body)}"
+  end
+
+  # [timestamp, [signatures]] from t=<seconds>,v1=<hex>[,v1=<hex>].
+  def parse_signature_header(header)
+    timestamp = nil
+    signatures = []
+    header.to_s.split(",").each do |part|
+      key, eq, value = part.partition("=")
+      next if eq.empty?
+
+      key = key.strip
+      value = value.strip
+      if key == "t" && value.match?(/\A[0-9]+\z/)
+        timestamp = value.to_i
+      elsif key == "v1" && !value.empty?
+        signatures << value
+      end
+    end
+    [timestamp, signatures]
+  end
+
+  def signature_header_of(source)
+    return source if source.is_a?(String)
+    return nil if source.nil?
+
+    found = []
+    if source.respond_to?(:each_pair) || source.respond_to?(:each)
+      source.each do |name, value|
+        # Rack spells it HTTP_X_SENDCLIPPER_SIGNATURE_V2.
+        normalised = name.to_s.downcase.tr("_", "-")
+        next unless [SIGNATURE_HEADER, "http-#{SIGNATURE_HEADER}"].include?(normalised)
+
+        Array(value).each { |v| found << v.to_s }
+      end
+    end
+    found.empty? ? nil : found.join(",")
+  end
+
+  def secure_compare(a, b)
+    return false unless a.bytesize == b.bytesize
+
+    OpenSSL.fixed_length_secure_compare(a, b)
+  end
+  private_class_method :signature_header_of, :secure_compare
+end

data/lib/sendclipper.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# The official Ruby SDK for the SendClipper email API.
+#
+#   require "sendclipper"
+#
+#   client = SendClipper::Client.new("sc_live_...")
+#   data, error = client.emails.send(
+#     from: "hello@send.acme.io",
+#     to: "ada@lumen.io",
+#     subject: "Your receipt",
+#     html: "<p>Thanks for your order.</p>"
+#   )
+module SendClipper; end
+
+require_relative "sendclipper/version"
+require_relative "sendclipper/errors"
+require_relative "sendclipper/result"
+require_relative "sendclipper/http_client"
+require_relative "sendclipper/webhook"
+require_relative "sendclipper/resources/base"
+require_relative "sendclipper/resources/emails"
+require_relative "sendclipper/resources/domains"
+require_relative "sendclipper/resources/templates"
+require_relative "sendclipper/resources/sandboxes"
+require_relative "sendclipper/resources/webhooks"
+require_relative "sendclipper/resources/audience"
+require_relative "sendclipper/resources/mailboxes"
+require_relative "sendclipper/resources/workspace"
+require_relative "sendclipper/client"

metadata

@@ -0,0 +1,66 @@
+--- !ruby/object:Gem::Specification
+name: sendclipper
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- SendClipper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Send mail, and manage domains, templates, sandboxes, webhooks, contacts
+  and suppressions with the SendClipper email API. No runtime dependencies.
+email:
+- support@sendclipper.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/sendclipper.rb
+- lib/sendclipper/client.rb
+- lib/sendclipper/errors.rb
+- lib/sendclipper/http_client.rb
+- lib/sendclipper/resources/audience.rb
+- lib/sendclipper/resources/base.rb
+- lib/sendclipper/resources/domains.rb
+- lib/sendclipper/resources/emails.rb
+- lib/sendclipper/resources/mailboxes.rb
+- lib/sendclipper/resources/sandboxes.rb
+- lib/sendclipper/resources/templates.rb
+- lib/sendclipper/resources/webhooks.rb
+- lib/sendclipper/resources/workspace.rb
+- lib/sendclipper/result.rb
+- lib/sendclipper/version.rb
+- lib/sendclipper/webhook.rb
+homepage: https://sendclipper.com/docs#sdk-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://sendclipper.com/docs#sdk-ruby
+  source_code_uri: https://github.com/sendclipper/sendclipper-ruby
+  bug_tracker_uri: https://github.com/sendclipper/sendclipper-ruby/issues
+  changelog_uri: https://github.com/sendclipper/sendclipper-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://sendclipper.com/docs#sdk-ruby
+  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: Official Ruby SDK for the SendClipper email API.
+test_files: []