helo-email-sdk 1.0.0.pre.beta.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 298571a7c53335cc539139041493cb71bdb10a8c94cb01bf88bf64027b59bfec
+  data.tar.gz: eeadd57916455673769b3918e151651b47f677d6b918a8a1fb43bab81caa51bd
+SHA512:
+  metadata.gz: 30bf674dca548f389a28f107da2f878ac9b4b7bb9e27b2ca25964421ddfd4f5e9f519b81a6c1439fa9b013e1cd98181ea9adf2e52ecffd5d00305914c766e0ce
+  data.tar.gz: ec8aa5f075af43c849b1ec6d3c37d650e6fbdf1a473bc597729acc381467e3f8762f80424e468c1b5d6090e11bf64c53eda7d4a3578c1dbbf1863c3063b74c79

data/lib/helo/api_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Helo
+  class APIError < Helo::Core::APIError
+    def detail
+      json_response.fetch(:detail, ["API Error", code, @message].compact.join(" - "))
+    end
+
+    def errors
+      json_response
+        .fetch(:errors, {})
+        .transform_keys(&:to_s)
+    end
+
+    private
+
+    def json_response
+      @_json_response ||= response_body.try(:deep_symbolize_keys) || {}
+    end
+  end
+end

data/lib/helo/apis/activity.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Helo
+  class Activity < API
+    def list_events(request_data = {})
+      request = ActivityListEventsRequest.new(request_data)
+      response = @client.request(:get, "/activity/events", params: request.to_params)
+      PaginatedEventsResponse.from_hash(response.body)
+    end
+
+    def list_messages(request_data = {})
+      request = ActivityListMessagesRequest.new(request_data)
+      response = @client.request(:get, "/activity/messages", params: request.to_params)
+      PaginatedMessagesResponse.from_hash(response.body)
+    end
+
+    def retrieve_message(id)
+      response = @client.request(:get, "/activity/messages/#{id}")
+      MessageDetailsResponse.from_hash(response.body)
+    end
+
+    class_methods :list_events, :list_messages, :retrieve_message
+  end
+end

data/lib/helo/apis/broadcasts.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Helo
+  class Broadcasts < API
+    def list(request_data = {})
+      request = BroadcastsListRequest.new(request_data)
+      response = @client.request(:get, "/broadcasts", params: request.to_params)
+      PaginatedResponseOfBroadcast.from_hash(response.body)
+    end
+
+    def retrieve(id)
+      response = @client.request(:get, "/broadcasts/#{id}")
+      BroadcastDetailsResponse.from_hash(response.body)
+    end
+
+    def list_failures(id, request_data = {})
+      request = BroadcastsListFailuresRequest.new(request_data)
+      response = @client.request(:get, "/broadcasts/#{id}/failures", params: request.to_params)
+      PaginatedResponseOfBroadcastFailure.from_hash(response.body)
+    end
+
+    def list_suppressions(id, request_data = {})
+      request = BroadcastsListSuppressionsRequest.new(request_data)
+      response = @client.request(:get, "/broadcasts/#{id}/suppressions", params: request.to_params)
+      PaginatedResponseOfBroadcastSuppression.from_hash(response.body)
+    end
+
+    class_methods :list, :retrieve, :list_failures, :list_suppressions
+  end
+end

data/lib/helo/apis/channels.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Helo
+  class Channels < API
+    def list(request_data = {})
+      request = ChannelsListRequest.new(request_data)
+      response = @client.request(:get, "/channels", params: request.to_params)
+      PaginationResultOfChannelBasicResponse.from_hash(response.body)
+    end
+
+    def create(request_data)
+      request = CreateChannelRequest.new(request_data)
+      response = @client.request(:post, "/channels", body: request.to_params)
+      ChannelDetailsResponse.from_hash(response.body)
+    end
+
+    def retrieve(id)
+      response = @client.request(:get, "/channels/#{id}")
+      ChannelDetailsResponse.from_hash(response.body)
+    end
+
+    def update(id, request_data)
+      request = UpdateChannelRequest.new(request_data)
+      response = @client.request(:patch, "/channels/#{id}", body: request.to_params)
+      ChannelDetailsResponse.from_hash(response.body)
+    end
+
+    def delete(id)
+      response = @client.request(:delete, "/channels/#{id}")
+      nil
+    end
+
+    class_methods :list, :create, :retrieve, :update, :delete
+  end
+end

data/lib/helo/apis/domains.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Helo
+  class Domains < API
+    def list(request_data = {})
+      request = DomainsListRequest.new(request_data)
+      response = @client.request(:get, "/domains", params: request.to_params)
+      PaginatedResponseOfDomainResponse.from_hash(response.body)
+    end
+
+    def create(request_data)
+      request = CreateDomainRequest.new(request_data)
+      response = @client.request(:post, "/domains", body: request.to_params)
+      DomainWithDnsResponse.from_hash(response.body)
+    end
+
+    def retrieve(id)
+      response = @client.request(:get, "/domains/#{id}")
+      DomainWithDnsResponse.from_hash(response.body)
+    end
+
+    def update(id, request_data)
+      request = UpdateDomainRequest.new(request_data)
+      response = @client.request(:patch, "/domains/#{id}", body: request.to_params)
+      DomainResponse.from_hash(response.body)
+    end
+
+    def delete(id)
+      response = @client.request(:delete, "/domains/#{id}")
+      nil
+    end
+
+    def verify(id)
+      response = @client.request(:post, "/domains/#{id}/verify")
+      DnsRecordsResponse.from_hash(response.body)
+    end
+
+    def rotate_key(id)
+      response = @client.request(:post, "/domains/#{id}/rotate-key")
+      DnsRecordResponse.from_hash(response.body)
+    end
+
+    class_methods :list, :create, :retrieve, :update, :delete, :verify, :rotate_key
+  end
+end

data/lib/helo/apis/sending.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Helo
+  class Sending < API
+    def transactional(request_data, channel_id: nil, idempotency_key: nil)
+      request = SendMessageRequest.new(request_data)
+      headers = {}
+      headers["X-Helo-Channel-Id"] = channel_id unless channel_id.nil?
+      headers["X-Helo-Idempotency-Key"] = idempotency_key unless idempotency_key.nil?
+      response = @client.request(:post, "/send/transactional", body: request.to_params, headers: headers)
+      SendMessageAcceptedResponse.from_hash(response.body)
+    end
+
+    def transactional_batch(request_data, channel_id: nil, idempotency_key: nil)
+      request = SendMessageBatchRequest.new(request_data)
+      headers = {}
+      headers["X-Helo-Channel-Id"] = channel_id unless channel_id.nil?
+      headers["X-Helo-Idempotency-Key"] = idempotency_key unless idempotency_key.nil?
+      response = @client.request(:post, "/send/transactional/batch", body: request.to_params, headers: headers)
+      SendMessageBatchResponse.from_hash(response.body)
+    end
+
+    def broadcast(request_data, channel_id: nil, idempotency_key: nil)
+      request = SendBroadcastRequest.new(request_data)
+      headers = {}
+      headers["X-Helo-Channel-Id"] = channel_id unless channel_id.nil?
+      headers["X-Helo-Idempotency-Key"] = idempotency_key unless idempotency_key.nil?
+      response = @client.request(:post, "/send/broadcast", body: request.to_params, headers: headers)
+      SendBroadcastResponse.from_hash(response.body)
+    end
+
+    def broadcast_message(request_data, channel_id: nil, idempotency_key: nil)
+      request = SendMessageRequest.new(request_data)
+      headers = {}
+      headers["X-Helo-Channel-Id"] = channel_id unless channel_id.nil?
+      headers["X-Helo-Idempotency-Key"] = idempotency_key unless idempotency_key.nil?
+      response = @client.request(:post, "/send/broadcast/message", body: request.to_params, headers: headers)
+      SendMessageAcceptedResponse.from_hash(response.body)
+    end
+
+    class_methods :transactional, :transactional_batch, :broadcast, :broadcast_message
+  end
+end

data/lib/helo/apis/statistics.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Helo
+  class Statistics < API
+    def retrieve_hourly(request_data = {})
+      request = StatisticsRetrieveHourlyRequest.new(request_data)
+      response = @client.request(:get, "/activity/statistics/hourly", params: request.to_params)
+      StatisticsHourlyResponse.from_hash(response.body)
+    end
+
+    def retrieve_daily(request_data = {})
+      request = StatisticsRetrieveDailyRequest.new(request_data)
+      response = @client.request(:get, "/activity/statistics/daily", params: request.to_params)
+      StatisticsDailyResponse.from_hash(response.body)
+    end
+
+    def retrieve_totals(request_data = {})
+      request = StatisticsRetrieveTotalsRequest.new(request_data)
+      response = @client.request(:get, "/activity/statistics/totals", params: request.to_params)
+      StatisticsTotalsResponse.from_hash(response.body)
+    end
+
+    class_methods :retrieve_hourly, :retrieve_daily, :retrieve_totals
+  end
+end

data/lib/helo/apis/suppressions.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Helo
+  class Suppressions < API
+    def list(request_data = {})
+      request = SuppressionsListRequest.new(request_data)
+      response = @client.request(:get, "/suppressions", params: request.to_params)
+      PaginatedResponseOfSuppressionResponse.from_hash(response.body)
+    end
+
+    def create(request_data)
+      request = CreateSuppressionsRequest.new(request_data)
+      response = @client.request(:post, "/suppressions", body: request.to_params)
+      CreateSuppressionsResponse.from_hash(response.body)
+    end
+
+    def remove(request_data)
+      request = RemoveSuppressionsRequest.new(request_data)
+      response = @client.request(:post, "/suppressions/remove", body: request.to_params)
+      RemoveSuppressionsResponse.from_hash(response.body)
+    end
+
+    class_methods :list, :create, :remove
+  end
+end

data/lib/helo/apis/webhooks.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Helo
+  class Webhooks < API
+    def list(request_data = {})
+      request = WebhooksListRequest.new(request_data)
+      response = @client.request(:get, "/webhooks", params: request.to_params)
+      PaginationResultOfWebhookResponse.from_hash(response.body)
+    end
+
+    def create(request_data)
+      request = CreateWebhookRequest.new(request_data)
+      response = @client.request(:post, "/webhooks", body: request.to_params)
+      WebhookResponse.from_hash(response.body)
+    end
+
+    def retrieve(id)
+      response = @client.request(:get, "/webhooks/#{id}")
+      WebhookResponse.from_hash(response.body)
+    end
+
+    def update(id, request_data)
+      request = UpdateWebhookRequest.new(request_data)
+      response = @client.request(:patch, "/webhooks/#{id}", body: request.to_params)
+      WebhookResponse.from_hash(response.body)
+    end
+
+    def delete(id)
+      response = @client.request(:delete, "/webhooks/#{id}")
+      nil
+    end
+
+    def regenerate_signing_key(id)
+      response = @client.request(:post, "/webhooks/#{id}/regenerate-signing-key")
+      WebhookResponse.from_hash(response.body)
+    end
+
+    class_methods :list, :create, :retrieve, :update, :delete, :regenerate_signing_key
+  end
+end

data/lib/helo/client.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Helo
+  class Client < Helo::Core::Client
+    private
+
+    def handle_error_response(response)
+      raise APIError.new(
+        "Request failed",
+        code: response.status,
+        response_body: response.body,
+        response_headers: response.headers
+      )
+    end
+
+    def handle_connection_error(exception)
+      raise APIError.new("Connection failed: #{exception.message}")
+    end
+  end
+end

data/lib/helo/configuration.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Helo
+  class Configuration < Helo::Core::Configuration
+    def initialize(base_url: "https://api.helohq.com", api_key: nil)
+      super
+    end
+  end
+end

data/lib/helo/core/api.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/class/attribute"
+
+module Helo::Core
+  # Base class for all API resources
+  class API
+    class_attribute :default_client
+
+    def self.class_methods(*methods)
+      methods.each do |method|
+        define_singleton_method(method) do |*args, **kwargs, &block|
+          new(default_client).public_send(method, *args, **kwargs, &block)
+        end
+      end
+    end
+
+    def initialize(client)
+      @client = client
+    end
+  end
+end

data/lib/helo/core/api_error.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Helo::Core
+  class APIError < StandardError
+    attr_reader :code, :response_body, :response_headers
+
+    def initialize(message = nil, code: nil, response_body: nil, response_headers: nil)
+      @message = message
+      @code = code
+      @response_body = response_body
+      @response_headers = response_headers
+      super(message)
+    end
+
+    def message
+      msg = @message
+      msg += "\nHTTP status code: #{code}" if code
+      msg += "\nResponse headers: #{response_headers}" if response_headers
+      msg += "\nResponse body: #{response_body}" if response_body
+      msg
+    end
+  end
+end

data/lib/helo/core/array_type.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Helo::Core
+  # Custom ActiveModel type for arrays of model objects
+  class ArrayType < ActiveModel::Type::Value
+    def initialize(model_class_name)
+      @model_class_name = model_class_name
+      super()
+    end
+
+    def cast(value)
+      return if value.nil?
+
+      value.map do |item|
+        case item
+        when model_class
+          item
+        when Hash
+          model_class.from_hash(item)
+        end
+      end
+    end
+
+    private
+
+    def model_class
+      @_model_class ||= @model_class_name.constantize
+    end
+  end
+end

data/lib/helo/core/client.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "faraday"
+
+module Helo::Core
+  class Client
+    attr_reader :configuration
+
+    def initialize(configuration)
+      raise ArgumentError, "base_url is not configured" if configuration.base_url.to_s.empty?
+
+      @configuration = configuration
+      @connection = Faraday.new(url: configuration.base_url) do |f|
+        f.request :json
+        f.response :json
+        f.adapter Faraday.default_adapter
+        f.options.params_encoder = Faraday::FlatParamsEncoder
+
+        # Allow custom Faraday configuration
+        configuration.faraday_configuration_block&.call(f)
+      end
+    end
+
+    def request(method, path, params: {}, body: nil, headers: {})
+      response = connection.public_send(method, path) do |req|
+        req.params = params
+        req.body = body
+
+        # Set Authorization header with dynamic or static token
+        token = current_api_key
+        req.headers["Authorization"] = "Bearer #{token}" if token
+
+        # Apply per-request headers verbatim (already in wire form)
+        headers.each do |key, value|
+          req.headers[key.to_s] = value.to_s
+        end
+      end
+
+      handle_response(response)
+    rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+      handle_connection_error(e)
+    end
+
+    private
+
+    attr_reader :connection
+
+    def current_api_key
+      token = configuration.api_key
+      token.respond_to?(:call) ? token.call : token
+    end
+
+    def handle_response(response)
+      case response.status
+      when 200..299
+        response
+      else
+        handle_error_response(response)
+      end
+    end
+
+    def handle_error_response(response)
+      raise APIError.new(
+        "Request failed",
+        code: response.status,
+        response_body: response.body,
+        response_headers: response.headers
+      )
+    end
+
+    def handle_connection_error(exception)
+      raise APIError.new("Connection failed: #{exception.message}")
+    end
+  end
+end

data/lib/helo/core/configuration.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Helo::Core
+  class Configuration
+    attr_accessor :base_url, :api_key
+    attr_reader :faraday_configuration_block
+
+    def initialize(base_url: nil, api_key: nil)
+      @base_url = base_url
+      @api_key = api_key
+      @faraday_configuration_block = nil
+    end
+
+    def configure_faraday_connection(&block)
+      @faraday_configuration_block = block
+    end
+  end
+end

data/lib/helo/core/model.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require "active_model"
+require "active_support/concern"
+require "date"
+
+module Helo::Core
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      include ActiveModel::AttributeAssignment
+      include ActiveModel::Attributes
+      include ActiveModel::Serializers::JSON
+
+      class_attribute :_api_attributes, default: {}
+
+      def initialize(attributes = {})
+        super()
+        assign_attributes(attributes) if attributes
+      end
+
+      # Serialize to hash for API requests (camelCase keys)
+      def to_params
+        result = {}
+        self.class._api_attributes.each do |attr_name, meta|
+          value = attributes[attr_name.to_s]
+
+          if value.nil?
+            next unless meta[:nullable] && @_explicitly_set&.include?(attr_name)
+          end
+
+          result[meta[:json_key]] = serialize_for_api(value, meta)
+        end
+        result
+      end
+
+      def to_h
+        attributes.to_h do |key, value|
+          [ key.to_sym, deep_to_h(value) ]
+        end
+      end
+
+      def slice(*keys)
+        attributes.symbolize_keys.slice(*keys.map(&:to_sym))
+      end
+
+      def [](key)
+        attributes[key.to_s]
+      end
+
+      def []=(key, value)
+        assign_attributes(key => value)
+      end
+
+      def inspect
+        attrs = attributes.map { |k, v| "#{k}: #{v.inspect}" }.join(", ")
+        "#<#{self.class.name} #{attrs}>"
+      end
+
+      private
+
+      def _write_attribute(attr_name, value)
+        @_explicitly_set ||= Set.new
+        @_explicitly_set << attr_name.to_sym
+        super
+      end
+
+      def deep_to_h(value)
+        if value.nil?
+          nil
+        elsif value.is_a?(Array)
+          value.map { |item| deep_to_h(item) }
+        elsif value.respond_to?(:to_h)
+          value.to_h
+        else
+          value
+        end
+      end
+
+      def serialize_for_api(value, meta = {})
+        return value if value.nil?
+
+        case value
+        when Array
+          serialized = value.map { |item| serialize_for_api(item) }
+          meta[:explode] == false ? serialized.join(",") : serialized
+        when Time, DateTime
+          value.utc.iso8601
+        when Date
+          value.to_s
+        else
+          value.respond_to?(:to_params) ? value.to_params : value
+        end
+      end
+    end
+
+    class_methods do
+      def new(input = {})
+        return input if input.is_a?(self)
+        super(input)
+      end
+
+      def api_attribute(name, type = nil, key:, nullable: false, explode: true)
+        attribute(name, type)
+
+        self._api_attributes[name] = {
+          json_key: key,
+          nullable: nullable,
+          explode: explode
+        }
+      end
+
+      def from_hash(hash)
+        return if hash.nil?
+
+        hash = hash.transform_keys(&:to_sym)
+
+        attributes = _api_attributes.to_h do |attr_name, meta|
+          json_key = meta.fetch(:json_key).to_sym
+          value = hash[json_key] || hash[attr_name]
+          [ attr_name, value ]
+        end
+
+        new(attributes)
+      end
+    end
+  end
+end

data/lib/helo/core/model_type.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Helo::Core
+  # Custom ActiveModel type for nested model objects
+  class ModelType < ActiveModel::Type::Value
+    def initialize(model_class_name)
+      @model_class_name = model_class_name
+      super()
+    end
+
+    def cast(value)
+      return if value.nil?
+
+      case value
+      when model_class
+        value
+      when Hash
+        model_class.from_hash(value)
+      else
+        raise ArgumentError, "Expected #{@model_class_name}, got #{value.class}"
+      end
+    end
+
+    private
+
+    def model_class
+      @_model_class ||= @model_class_name.constantize
+    end
+  end
+end

data/lib/helo/enums/attachment_disposition.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Helo
+  class AttachmentDisposition
+    ATTACHMENT = "attachment"
+    INLINE = "inline"
+
+    def self.all
+      [ATTACHMENT, INLINE].freeze
+    end
+  end
+end