emailfuse 0.1.4 → 0.3.0

data/lib/email_fuse/webhooks.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module EmailFuse
+  # The Webhooks module provides methods for managing webhooks via the EmailFuse API.
+  # Webhooks allow you to receive real-time notifications about email events.
+  #
+  # Default tolerance for timestamp validation (5 minutes)
+  WEBHOOK_TOLERANCE_SECONDS = 300
+  #
+  # @example Create a webhook
+  #   EmailFuse::Webhooks.create(
+  #     endpoint: "https://webhook.example.com/handler",
+  #     events: ["email.sent", "email.delivered", "email.bounced"]
+  #   )
+  #
+  # @example List all webhooks
+  #   EmailFuse::Webhooks.list
+  #
+  # @example Retrieve a specific webhook
+  #   EmailFuse::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+  #
+  # @example Update a webhook
+  #   EmailFuse::Webhooks.update(
+  #     webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
+  #     endpoint: "https://new-webhook.example.com/handler",
+  #     events: ["email.sent", "email.delivered"],
+  #     status: "enabled"
+  #   )
+  #
+  # @example Delete a webhook
+  #   EmailFuse::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+  module Webhooks
+    class << self
+      # Create a new webhook to receive real-time notifications about email events
+      #
+      # @param params [Hash] The webhook parameters
+      # @option params [String] :endpoint The URL where webhook events will be sent (required)
+      # @option params [Array<String>] :events Array of event types to subscribe to (required)
+      #
+      # @return [Hash] The webhook object containing id, object type, and signing_secret
+      #
+      # @example
+      #   EmailFuse::Webhooks.create(
+      #     endpoint: "https://webhook.example.com/handler",
+      #     events: ["email.sent", "email.delivered", "email.bounced"]
+      #   )
+      def create(params = {})
+        path = "webhooks"
+        EmailFuse::Request.new(path, params, "post").perform
+      end
+
+      # Retrieve a list of webhooks for the authenticated user
+      #
+      # @param params [Hash] The pagination parameters
+      # @option params [Integer] :limit Number of webhooks to retrieve (max: 100, min: 1)
+      # @option params [String] :after The ID after which to retrieve more webhooks (for pagination)
+      # @option params [String] :before The ID before which to retrieve more webhooks (for pagination)
+      #
+      # @return [Hash] A paginated list of webhook objects
+      #
+      # @example
+      #   EmailFuse::Webhooks.list
+      #
+      # @example With pagination
+      #   EmailFuse::Webhooks.list(limit: 20, after: "4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def list(params = {})
+        path = EmailFuse::PaginationHelper.build_paginated_path("webhooks", params)
+        EmailFuse::Request.new(path, {}, "get").perform
+      end
+
+      # Retrieve a single webhook for the authenticated user
+      #
+      # @param webhook_id [String] The webhook ID (required)
+      #
+      # @return [Hash] The webhook object with full details
+      #
+      # @example
+      #   EmailFuse::Webhooks.get("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def get(webhook_id)
+        raise ArgumentError, "webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?
+
+        path = "webhooks/#{webhook_id}"
+        EmailFuse::Request.new(path, {}, "get").perform
+      end
+
+      # Update an existing webhook configuration
+      #
+      # @param params [Hash] The webhook update parameters
+      # @option params [String] :webhook_id The webhook ID (required)
+      # @option params [String] :endpoint The URL where webhook events will be sent
+      # @option params [Array<String>] :events Array of event types to subscribe to
+      # @option params [String] :status The webhook status ("enabled" or "disabled")
+      #
+      # @return [Hash] The updated webhook object
+      #
+      # @example
+      #   EmailFuse::Webhooks.update(
+      #     webhook_id: "430eed87-632a-4ea6-90db-0aace67ec228",
+      #     endpoint: "https://new-webhook.example.com/handler",
+      #     events: ["email.sent", "email.delivered"],
+      #     status: "enabled"
+      #   )
+      def update(params = {})
+        params = params.dup # Don't mutate caller's hash
+        webhook_id = params.delete(:webhook_id)
+        raise ArgumentError, ":webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?
+
+        path = "webhooks/#{webhook_id}"
+        EmailFuse::Request.new(path, params, "patch").perform
+      end
+
+      # Remove an existing webhook
+      #
+      # @param webhook_id [String] The webhook ID (required)
+      #
+      # @return [Hash] Confirmation object with id, object type, and deleted status
+      #
+      # @example
+      #   EmailFuse::Webhooks.remove("4dd369bc-aa82-4ff3-97de-514ae3000ee0")
+      def remove(webhook_id)
+        raise ArgumentError, "webhook_id is required" if webhook_id.nil? || webhook_id.to_s.empty?
+
+        path = "webhooks/#{webhook_id}"
+        EmailFuse::Request.new(path, {}, "delete").perform
+      end
+
+      # Verify a webhook payload using HMAC-SHA256 signature validation
+      # This validates that the webhook request came from EmailFuse and hasn't been tampered with
+      #
+      # @param params [Hash] The webhook verification parameters
+      # @option params [String] :payload The raw webhook payload body (required)
+      # @option params [Hash] :headers The webhook headers containing svix-id, svix-timestamp,
+      #   and svix-signature (required)
+      # @option params [String] :webhook_secret The signing secret from webhook creation (required)
+      #
+      # @return [Boolean] true if verification succeeds
+      # @raise [StandardError] If verification fails or required parameters are missing
+      #
+      # @example
+      #   EmailFuse::Webhooks.verify(
+      #     payload: request.body.read,
+      #     headers: {
+      #       svix_id: "id_1234567890abcdefghijklmnopqrstuvwxyz",
+      #       svix_timestamp: "1616161616",
+      #       svix_signature: "v1,signature_here"
+      #     },
+      #     webhook_secret: "whsec_1234567890abcdez"
+      #   )
+      def verify(params = {})
+        payload = params[:payload]
+        headers = params[:headers] || {}
+        webhook_secret = params[:webhook_secret]
+
+        validate_required_params(payload, headers, webhook_secret)
+        validate_timestamp(headers[:svix_timestamp])
+
+        signed_content = "#{headers[:svix_id]}.#{headers[:svix_timestamp]}.#{payload}"
+        decoded_secret = decode_secret(webhook_secret)
+        expected_signature = generate_signature(decoded_secret, signed_content)
+
+        verify_signature(headers[:svix_signature], expected_signature)
+      end
+
+      private
+
+      # Validate required parameters
+      def validate_required_params(payload, headers, webhook_secret)
+        validate_payload(payload)
+        validate_webhook_secret(webhook_secret)
+        validate_headers(headers)
+      end
+
+      # Validate payload is present
+      def validate_payload(payload)
+        raise "payload cannot be empty" if payload.nil? || payload.empty?
+      end
+
+      # Validate webhook secret is present
+      def validate_webhook_secret(webhook_secret)
+        raise "webhook_secret cannot be empty" if webhook_secret.nil? || webhook_secret.empty?
+      end
+
+      # Validate required headers are present
+      def validate_headers(headers)
+        raise "svix-id header is required" if headers[:svix_id].nil? || headers[:svix_id].empty?
+        raise "svix-timestamp header is required" if headers[:svix_timestamp].nil? || headers[:svix_timestamp].empty?
+        raise "svix-signature header is required" if headers[:svix_signature].nil? || headers[:svix_signature].empty?
+      end
+
+      # Validate timestamp to prevent replay attacks
+      def validate_timestamp(timestamp_header)
+        timestamp = timestamp_header.to_i
+        now = Time.now.to_i
+        diff = now - timestamp
+
+        return unless diff > WEBHOOK_TOLERANCE_SECONDS || diff < -WEBHOOK_TOLERANCE_SECONDS
+
+        raise "Timestamp outside tolerance window: difference of #{diff} seconds"
+      end
+
+      # Decode the signing secret (strip whsec_ prefix and base64 decode)
+      def decode_secret(webhook_secret)
+        secret = webhook_secret.sub(/^whsec_/, "")
+        Base64.strict_decode64(secret)
+      rescue ArgumentError => e
+        raise "Failed to decode webhook secret: #{e.message}"
+      end
+
+      # Verify signature using constant-time comparison
+      def verify_signature(signature_header, expected_signature)
+        signatures = signature_header.split(" ")
+        signatures.each do |sig|
+          parts = sig.split(",", 2)
+          next if parts.length != 2
+
+          received_signature = parts[1]
+          return true if secure_compare(expected_signature, received_signature)
+        end
+
+        raise "No matching signature found"
+      end
+
+      # Generate HMAC-SHA256 signature and return it as base64
+      def generate_signature(secret, content)
+        digest = OpenSSL::HMAC.digest("sha256", secret, content)
+        Base64.strict_encode64(digest)
+      end
+
+      # Constant-time string comparison to prevent timing attacks
+      #
+      # Note: We implement this manually for Ruby 2.7 compatibility.
+      # Ruby 3.0+ could use OpenSSL.fixed_length_secure_compare instead.
+      def secure_compare(str_a, str_b)
+        return false if str_a.nil? || str_b.nil? || str_a.bytesize != str_b.bytesize
+
+        bytes_a = str_a.unpack("C*")
+        result = 0
+        str_b.each_byte.with_index { |byte_b, i| result |= byte_b ^ bytes_a[i] }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/email_fuse.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Version
+require "email_fuse/version"
+
+# Utils
+require "httparty"
+require "json"
+require "cgi"
+require "email_fuse/errors"
+require "email_fuse/response"
+require "email_fuse/client"
+require "email_fuse/request"
+require "email_fuse/pagination_helper"
+
+# API Operations
+require "email_fuse/batch"
+require "email_fuse/emails"
+require "email_fuse/emails/receiving"
+require "email_fuse/emails/attachments"
+require "email_fuse/emails/receiving/attachments"
+require "email_fuse/webhooks"
+
+# Rails
+require "email_fuse/railtie" if defined?(Rails) && defined?(ActionMailer)
+
+# Main EmailFuse module
+module EmailFuse
+  DEFAULT_TIMEOUT = 30
+
+  class << self
+    attr_accessor :api_key, :timeout
+    attr_writer :base_url
+
+    def configure
+      yield self if block_given?
+      true
+    end
+    alias config configure
+
+    def base_url
+      @base_url ||= "https://api.emailfuse.net"
+    end
+  end
+end

data/lib/emailfuse.rb

@@ -1,32 +1,3 @@
-require "action_mailer"
+# frozen_string_literal: true
 
-require "faraday"
-require "faraday/multipart"
-
-require "emailfuse/version"
-
-module Emailfuse
-  autoload :Configuration, "emailfuse/configuration"
-  autoload :Client, "emailfuse/client"
-  autoload :Collection, "emailfuse/collection"
-  autoload :Error, "emailfuse/error"
-  autoload :Object, "emailfuse/object"
-
-  autoload :Deliverer, "emailfuse/deliverer"
-
-  class << self
-    attr_writer :config
-  end
-
-  def self.configure
-    yield(config) if block_given?
-  end
-
-  def self.config
-    @config ||= Configuration.new
-  end
-
-  autoload :Email, "emailfuse/models/email"
-end
-
-require "emailfuse/railtie" if defined?(Rails::Railtie)
+require "email_fuse"

metadata

@@ -1,81 +1,68 @@
 --- !ruby/object:Gem::Specification
 name: emailfuse
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.3.0
 platform: ruby
 authors:
 - Dean Perry
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-16 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: actionmailer
+  name: httparty
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.21.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.21.0
 - !ruby/object:Gem::Dependency
-  name: faraday
+  name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-- !ruby/object:Gem::Dependency
-  name: faraday-multipart
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
+        version: '7.2'
+  type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1.0'
-description:
-email:
-- dean@voupe.com
+        version: '7.2'
+email: dean@voupe.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - README.md
-- Rakefile
+- lib/email_fuse.rb
+- lib/email_fuse/batch.rb
+- lib/email_fuse/client.rb
+- lib/email_fuse/emails.rb
+- lib/email_fuse/emails/attachments.rb
+- lib/email_fuse/emails/receiving.rb
+- lib/email_fuse/emails/receiving/attachments.rb
+- lib/email_fuse/errors.rb
+- lib/email_fuse/mailer.rb
+- lib/email_fuse/pagination_helper.rb
+- lib/email_fuse/railtie.rb
+- lib/email_fuse/request.rb
+- lib/email_fuse/response.rb
+- lib/email_fuse/version.rb
+- lib/email_fuse/webhooks.rb
 - lib/emailfuse.rb
-- lib/emailfuse/client.rb
-- lib/emailfuse/collection.rb
-- lib/emailfuse/configuration.rb
-- lib/emailfuse/deliverer.rb
-- lib/emailfuse/error.rb
-- lib/emailfuse/models/email.rb
-- lib/emailfuse/object.rb
-- lib/emailfuse/railtie.rb
-- lib/emailfuse/version.rb
-homepage:
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -83,15 +70,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
-signing_key:
+rubygems_version: 4.0.3
 specification_version: 4
-summary: Ruby library for the Emailfuse API including an Rails Action Mailer adapter
+summary: The Ruby and Rails SDK for EmailFuse
 test_files: []

data/Rakefile

@@ -1,10 +0,0 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
-task default: :test

data/lib/emailfuse/client.rb

@@ -1,69 +0,0 @@
-module Emailfuse
-  class Client
-    class << self
-      def url
-        Emailfuse.config.host || "https://app.emailfuse.net"
-      end
-
-      def connection
-        @connection ||= Faraday.new("#{url}/api/v1") do |conn|
-          conn.request :authorization, :Bearer, Emailfuse.config.token
-
-          conn.headers = {
-            "User-Agent" => "emailfuse/v#{VERSION} (github.com/voupe/emailfuse-gem)"
-          }
-
-          conn.request :multipart
-          conn.request :json
-
-          conn.response :json
-        end
-      end
-
-      def get_request(url, params: {}, headers: {})
-        handle_response connection.get(url, params, headers)
-      end
-
-      def post_request(url, body: {}, headers: {})
-        handle_response connection.post(url, body, headers)
-      end
-
-      def patch_request(url, body:, headers: {})
-        handle_response connection.patch(url, body, headers)
-      end
-
-      def delete_request(url, headers: {})
-        handle_response connection.delete(url, headers)
-      end
-
-      def handle_response(response)
-        case response.status
-        when 400
-          raise Error, "Error 400: Your request was malformed."
-        when 401
-          raise Error, "Error 401: You did not supply valid authentication credentials."
-        when 403
-          raise Error, "Error 403: You are not allowed to perform that action."
-        when 404
-          raise Error, "Error 404: No results were found for your request."
-        when 409
-          raise Error, "Error 409: Your request was a conflict."
-        when 429
-          raise Error, "Error 429: Your request exceeded the API rate limit."
-        when 422
-          raise Error, "Error 422: Unprocessable Entity."
-        when 500
-          raise Error, "Error 500: We were unable to perform the request due to server-side problems."
-        when 503
-          raise Error, "Error 503: You have been rate limited for sending more than 20 requests per second."
-        when 501
-          raise Error, "Error 501: This resource has not been implemented."
-        when 204
-          return true
-        end
-
-        response
-      end
-    end
-  end
-end

data/lib/emailfuse/collection.rb

@@ -1,27 +0,0 @@
-module Emailfuse
-  class Collection
-    attr_reader :data, :total
-
-    def self.from_response(response, type:, key: nil)
-      body = response.body
-
-      if key.is_a?(String)
-        data  = body["data"][key].map { |attrs| type.new(attrs) }
-        total = body["data"]["total"]
-      else
-        data  = body["data"].map { |attrs| type.new(attrs) }
-        total = body["data"].count
-      end
-
-      new(
-        data: data,
-        total: total
-      )
-    end
-
-    def initialize(data:, total:)
-      @data = data
-      @total = total
-    end
-  end
-end

data/lib/emailfuse/configuration.rb

@@ -1,10 +0,0 @@
-# frozen_string_literal: true
-
-module Emailfuse
-  class Configuration
-    attr_accessor :host, :token
-
-    def initialize
-    end
-  end
-end

data/lib/emailfuse/deliverer.rb

@@ -1,72 +0,0 @@
-module Emailfuse
-  class Deliverer
-    class Attachment < StringIO
-      attr_reader :original_filename, :content_type, :path
-
-      def initialize (attachment, *rest)
-        @path = ""
-        @original_filename = attachment.filename
-        @content_type = attachment.content_type.split(";")[0]
-        super attachment.body.decoded
-      end
-    end
-
-    attr_accessor :settings
-
-    def initialize(settings)
-      self.settings = settings
-    end
-
-    def api_token
-      self.settings[:token] || Emailfuse.config.token
-    end
-
-    def deliver!(rails_message)
-      attributes = {
-        from: rails_message[:from],
-        to: rails_message[:to].formatted,
-        subject: rails_message.subject,
-        html: extract_html(rails_message),
-        text: extract_text(rails_message)
-      }
-
-      [ :reply_to, :cc ].each do |key|
-        attributes[key] = rails_message[key].formatted if rails_message[key]
-      end
-
-      unless rails_message.attachments.empty?
-        attributes[:attachments] = []
-        rails_message.attachments.each do |attachment|
-          attributes[:attachments] << Attachment.new(attachment, encoding: "ascii-8bit")
-        end
-      end
-
-      Email.create(**attributes)
-    end
-
-    private
-
-    # @see http://stackoverflow.com/questions/4868205/rails-mail-getting-the-body-as-plain-text
-    def extract_html(rails_message)
-      if rails_message.html_part
-        rails_message.html_part.body.decoded
-      else
-        rails_message.content_type =~ /text\/html/ ? rails_message.body.decoded : nil
-      end
-    end
-
-    def extract_text(rails_message)
-      if rails_message.multipart?
-        rails_message.text_part ? rails_message.text_part.body.decoded : nil
-      else
-        rails_message.content_type =~ /text\/plain/ ? rails_message.body.decoded : nil
-      end
-    end
-
-    def email_fuse_client
-      @email_fuse_client ||= Client.new(api_token, host)
-    end
-  end
-end
-
-ActionMailer::Base.add_delivery_method :email_fuse, Emailfuse::Deliverer

data/lib/emailfuse/error.rb

@@ -1,4 +0,0 @@
-module Emailfuse
-  class Error < StandardError
-  end
-end

data/lib/emailfuse/models/email.rb

@@ -1,21 +0,0 @@
-module Emailfuse
-  class Email < Object
-    class << self
-      def create(to:, from:, subject:, html: nil, text: nil, **attributes)
-        raise ArgumentError, "You must provide either html or text" if html.nil? && text.nil?
-
-        attrs = attributes.merge!(
-          to: to,
-          from: from,
-          subject: subject,
-          html: html,
-          text: text
-        )
-
-        response = Client.post_request("emails", body: attrs)
-
-        Email.new(response.body) if response.success?
-      end
-    end
-  end
-end

data/lib/emailfuse/object.rb

@@ -1,19 +0,0 @@
-require "ostruct"
-
-module Emailfuse
-  class Object < OpenStruct
-    def initialize(attributes)
-      super to_ostruct(attributes)
-    end
-
-    def to_ostruct(obj)
-      if obj.is_a?(Hash)
-        OpenStruct.new(obj.map { |key, val| [ key, to_ostruct(val) ] }.to_h)
-      elsif obj.is_a?(Array)
-        obj.map { |o| to_ostruct(o) }
-      else # Assumed to be a primitive value
-        obj
-      end
-    end
-  end
-end