ark-email 0.5.1

data/lib/ark_email/resources/webhooks.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Webhooks
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::WebhookCreateParams} for more details.
+      #
+      # Create a webhook endpoint to receive email event notifications.
+      #
+      # **Available events:**
+      #
+      # - `MessageSent` - Email accepted by recipient server
+      # - `MessageDeliveryFailed` - Delivery permanently failed
+      # - `MessageDelayed` - Delivery temporarily failed, will retry
+      # - `MessageBounced` - Email bounced
+      # - `MessageHeld` - Email held for review
+      # - `MessageLinkClicked` - Recipient clicked a link
+      # - `MessageLoaded` - Recipient opened the email
+      # - `DomainDNSError` - Domain DNS issue detected
+      #
+      # @overload create(events:, name:, url:, all_events: nil, enabled: nil, request_options: {})
+      #
+      # @param events [Array<Symbol, ArkEmail::Models::WebhookCreateParams::Event>] Events to subscribe to:
+      #
+      # @param name [String] Webhook name for identification
+      #
+      # @param url [String] HTTPS endpoint URL
+      #
+      # @param all_events [Boolean] Subscribe to all events (ignores events array)
+      #
+      # @param enabled [Boolean]
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookCreateResponse]
+      #
+      # @see ArkEmail::Models::WebhookCreateParams
+      def create(params)
+        parsed, options = ArkEmail::WebhookCreateParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "webhooks",
+          body: parsed,
+          model: ArkEmail::Models::WebhookCreateResponse,
+          options: options
+        )
+      end
+
+      # Get webhook details
+      #
+      # @overload retrieve(webhook_id, request_options: {})
+      #
+      # @param webhook_id [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookRetrieveResponse]
+      #
+      # @see ArkEmail::Models::WebhookRetrieveParams
+      def retrieve(webhook_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["webhooks/%1$s", webhook_id],
+          model: ArkEmail::Models::WebhookRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Update a webhook
+      #
+      # @overload update(webhook_id, all_events: nil, enabled: nil, events: nil, name: nil, url: nil, request_options: {})
+      #
+      # @param webhook_id [String]
+      # @param all_events [Boolean]
+      # @param enabled [Boolean]
+      # @param events [Array<String>]
+      # @param name [String]
+      # @param url [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookUpdateResponse]
+      #
+      # @see ArkEmail::Models::WebhookUpdateParams
+      def update(webhook_id, params = {})
+        parsed, options = ArkEmail::WebhookUpdateParams.dump_request(params)
+        @client.request(
+          method: :patch,
+          path: ["webhooks/%1$s", webhook_id],
+          body: parsed,
+          model: ArkEmail::Models::WebhookUpdateResponse,
+          options: options
+        )
+      end
+
+      # Get all configured webhook endpoints
+      #
+      # @overload list(request_options: {})
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookListResponse]
+      #
+      # @see ArkEmail::Models::WebhookListParams
+      def list(params = {})
+        @client.request(
+          method: :get,
+          path: "webhooks",
+          model: ArkEmail::Models::WebhookListResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Delete a webhook
+      #
+      # @overload delete(webhook_id, request_options: {})
+      #
+      # @param webhook_id [String]
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookDeleteResponse]
+      #
+      # @see ArkEmail::Models::WebhookDeleteParams
+      def delete(webhook_id, params = {})
+        @client.request(
+          method: :delete,
+          path: ["webhooks/%1$s", webhook_id],
+          model: ArkEmail::Models::WebhookDeleteResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Send a test payload to your webhook endpoint and verify it receives the data
+      # correctly.
+      #
+      # Use this to:
+      #
+      # - Verify your webhook URL is accessible
+      # - Test your signature verification code
+      # - Ensure your server handles the payload format correctly
+      #
+      # **Test payload format:** The test payload is identical to real webhook payloads,
+      # containing sample data for the specified event type. Your webhook should respond
+      # with a 2xx status code.
+      #
+      # @overload test_(webhook_id, event:, request_options: {})
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param event [Symbol, ArkEmail::Models::WebhookTestParams::Event] Event type to simulate
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookTestResponse]
+      #
+      # @see ArkEmail::Models::WebhookTestParams
+      def test_(webhook_id, params)
+        parsed, options = ArkEmail::WebhookTestParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: ["webhooks/%1$s/test", webhook_id],
+          body: parsed,
+          model: ArkEmail::Models::WebhookTestResponse,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  VERSION = "0.5.1"
+end

data/lib/ark_email.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+# Standard libraries.
+# rubocop:disable Lint/RedundantRequireStatement
+require "English"
+require "base64"
+require "cgi"
+require "date"
+require "erb"
+require "etc"
+require "json"
+require "net/http"
+require "openssl"
+require "pathname"
+require "rbconfig"
+require "securerandom"
+require "set"
+require "stringio"
+require "time"
+require "uri"
+# rubocop:enable Lint/RedundantRequireStatement
+
+# We already ship the preferred sorbet manifests in the package itself.
+# `tapioca` currently does not offer us a way to opt out of unnecessary compilation.
+if Object.const_defined?(:Tapioca) &&
+   caller.chain([$PROGRAM_NAME]).chain(ARGV).any?(/tapioca/) &&
+   ARGV.none?(/dsl/)
+  return
+end
+
+# Gems.
+require "connection_pool"
+
+# Package files.
+require_relative "ark_email/version"
+require_relative "ark_email/internal/util"
+require_relative "ark_email/internal/type/converter"
+require_relative "ark_email/internal/type/unknown"
+require_relative "ark_email/internal/type/boolean"
+require_relative "ark_email/internal/type/file_input"
+require_relative "ark_email/internal/type/enum"
+require_relative "ark_email/internal/type/union"
+require_relative "ark_email/internal/type/array_of"
+require_relative "ark_email/internal/type/hash_of"
+require_relative "ark_email/internal/type/base_model"
+require_relative "ark_email/internal/type/base_page"
+require_relative "ark_email/internal/type/request_parameters"
+require_relative "ark_email/internal"
+require_relative "ark_email/request_options"
+require_relative "ark_email/file_part"
+require_relative "ark_email/errors"
+require_relative "ark_email/internal/transport/base_client"
+require_relative "ark_email/internal/transport/pooled_net_requester"
+require_relative "ark_email/client"
+require_relative "ark_email/internal/page_number_pagination"
+require_relative "ark_email/models/api_meta"
+require_relative "ark_email/models/dns_record"
+require_relative "ark_email/models/domain_create_params"
+require_relative "ark_email/models/domain_create_response"
+require_relative "ark_email/models/domain_delete_params"
+require_relative "ark_email/models/domain_delete_response"
+require_relative "ark_email/models/domain_list_params"
+require_relative "ark_email/models/domain_list_response"
+require_relative "ark_email/models/domain_retrieve_params"
+require_relative "ark_email/models/domain_retrieve_response"
+require_relative "ark_email/models/domain_verify_params"
+require_relative "ark_email/models/domain_verify_response"
+require_relative "ark_email/models/email_list_params"
+require_relative "ark_email/models/email_list_response"
+require_relative "ark_email/models/email_retrieve_deliveries_params"
+require_relative "ark_email/models/email_retrieve_deliveries_response"
+require_relative "ark_email/models/email_retrieve_params"
+require_relative "ark_email/models/email_retrieve_response"
+require_relative "ark_email/models/email_retry_params"
+require_relative "ark_email/models/email_retry_response"
+require_relative "ark_email/models/email_send_batch_params"
+require_relative "ark_email/models/email_send_batch_response"
+require_relative "ark_email/models/email_send_params"
+require_relative "ark_email/models/email_send_raw_params"
+require_relative "ark_email/models/email_send_raw_response"
+require_relative "ark_email/models/email_send_response"
+require_relative "ark_email/models/suppression_bulk_create_params"
+require_relative "ark_email/models/suppression_bulk_create_response"
+require_relative "ark_email/models/suppression_create_params"
+require_relative "ark_email/models/suppression_create_response"
+require_relative "ark_email/models/suppression_delete_params"
+require_relative "ark_email/models/suppression_delete_response"
+require_relative "ark_email/models/suppression_list_params"
+require_relative "ark_email/models/suppression_list_response"
+require_relative "ark_email/models/suppression_retrieve_params"
+require_relative "ark_email/models/suppression_retrieve_response"
+require_relative "ark_email/models/track_domain"
+require_relative "ark_email/models/tracking_create_params"
+require_relative "ark_email/models/tracking_create_response"
+require_relative "ark_email/models/tracking_delete_params"
+require_relative "ark_email/models/tracking_delete_response"
+require_relative "ark_email/models/tracking_list_params"
+require_relative "ark_email/models/tracking_list_response"
+require_relative "ark_email/models/tracking_retrieve_params"
+require_relative "ark_email/models/tracking_retrieve_response"
+require_relative "ark_email/models/tracking_update_params"
+require_relative "ark_email/models/tracking_update_response"
+require_relative "ark_email/models/tracking_verify_params"
+require_relative "ark_email/models/tracking_verify_response"
+require_relative "ark_email/models/webhook_create_params"
+require_relative "ark_email/models/webhook_create_response"
+require_relative "ark_email/models/webhook_delete_params"
+require_relative "ark_email/models/webhook_delete_response"
+require_relative "ark_email/models/webhook_list_params"
+require_relative "ark_email/models/webhook_list_response"
+require_relative "ark_email/models/webhook_retrieve_params"
+require_relative "ark_email/models/webhook_retrieve_response"
+require_relative "ark_email/models/webhook_test_params"
+require_relative "ark_email/models/webhook_test_response"
+require_relative "ark_email/models/webhook_update_params"
+require_relative "ark_email/models/webhook_update_response"
+require_relative "ark_email/models"
+require_relative "ark_email/resources/domains"
+require_relative "ark_email/resources/emails"
+require_relative "ark_email/resources/suppressions"
+require_relative "ark_email/resources/tracking"
+require_relative "ark_email/resources/webhooks"

data/manifest.yaml

@@ -0,0 +1,17 @@
+dependencies:
+  - English
+  - base64
+  - cgi
+  - date
+  - erb
+  - etc
+  - json
+  - net/http
+  - openssl
+  - pathname
+  - rbconfig
+  - securerandom
+  - set
+  - stringio
+  - time
+  - uri

data/rbi/ark_email/client.rbi

@@ -0,0 +1,73 @@
+# typed: strong
+
+module ArkEmail
+  class Client < ArkEmail::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES = 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS = T.let(60.0, Float)
+
+    DEFAULT_INITIAL_RETRY_DELAY = T.let(0.5, Float)
+
+    DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
+
+    # Use your API key from
+    # [arkhq.io/org/credentials](https://arkhq.io/org/credentials)
+    #
+    # ```
+    # Authorization: Bearer YOUR_API_KEY
+    # ```
+    sig { returns(String) }
+    attr_reader :api_key
+
+    sig { returns(ArkEmail::Resources::Emails) }
+    attr_reader :emails
+
+    sig { returns(ArkEmail::Resources::Domains) }
+    attr_reader :domains
+
+    sig { returns(ArkEmail::Resources::Suppressions) }
+    attr_reader :suppressions
+
+    sig { returns(ArkEmail::Resources::Webhooks) }
+    attr_reader :webhooks
+
+    sig { returns(ArkEmail::Resources::Tracking) }
+    attr_reader :tracking
+
+    # @api private
+    sig { override.returns(T::Hash[String, String]) }
+    private def auth_headers
+    end
+
+    # Creates and returns a new client for interacting with the API.
+    sig do
+      params(
+        api_key: T.nilable(String),
+        base_url: T.nilable(String),
+        max_retries: Integer,
+        timeout: Float,
+        initial_retry_delay: Float,
+        max_retry_delay: Float
+      ).returns(T.attached_class)
+    end
+    def self.new(
+      # Use your API key from
+      # [arkhq.io/org/credentials](https://arkhq.io/org/credentials)
+      #
+      # ````
+      # Authorization: Bearer YOUR_API_KEY
+      # ``` Defaults to `ENV["ARK_API_KEY"]`
+      # ````
+      api_key: ENV["ARK_API_KEY"],
+      # Override the default base URL for the API, e.g.,
+      # `"https://api.example.com/v2/"`. Defaults to `ENV["ARK_BASE_URL"]`
+      base_url: ENV["ARK_BASE_URL"],
+      # Max number of retries to attempt after a failed retryable request.
+      max_retries: ArkEmail::Client::DEFAULT_MAX_RETRIES,
+      timeout: ArkEmail::Client::DEFAULT_TIMEOUT_IN_SECONDS,
+      initial_retry_delay: ArkEmail::Client::DEFAULT_INITIAL_RETRY_DELAY,
+      max_retry_delay: ArkEmail::Client::DEFAULT_MAX_RETRY_DELAY
+    )
+    end
+  end
+end

data/rbi/ark_email/errors.rbi

@@ -0,0 +1,205 @@
+# typed: strong
+
+module ArkEmail
+  module Errors
+    class Error < StandardError
+      sig { returns(T.nilable(StandardError)) }
+      attr_accessor :cause
+    end
+
+    class ConversionError < ArkEmail::Errors::Error
+      sig { returns(T.nilable(StandardError)) }
+      def cause
+      end
+
+      # @api private
+      sig do
+        params(
+          on: T::Class[StandardError],
+          method: Symbol,
+          target: T.anything,
+          value: T.anything,
+          cause: T.nilable(StandardError)
+        ).returns(T.attached_class)
+      end
+      def self.new(on:, method:, target:, value:, cause: nil)
+      end
+    end
+
+    class APIError < ArkEmail::Errors::Error
+      sig { returns(URI::Generic) }
+      attr_accessor :url
+
+      sig { returns(T.nilable(Integer)) }
+      attr_accessor :status
+
+      sig { returns(T.nilable(T::Hash[String, String])) }
+      attr_accessor :headers
+
+      sig { returns(T.nilable(T.anything)) }
+      attr_accessor :body
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: T.nilable(Integer),
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: nil
+      )
+      end
+    end
+
+    class APIConnectionError < ArkEmail::Errors::APIError
+      sig { returns(NilClass) }
+      attr_accessor :status
+
+      sig { returns(NilClass) }
+      attr_accessor :body
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: NilClass,
+          headers: T.nilable(T::Hash[String, String]),
+          body: NilClass,
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Connection error."
+      )
+      end
+    end
+
+    class APITimeoutError < ArkEmail::Errors::APIConnectionError
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: NilClass,
+          headers: T.nilable(T::Hash[String, String]),
+          body: NilClass,
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status: nil,
+        headers: nil,
+        body: nil,
+        request: nil,
+        response: nil,
+        message: "Request timed out."
+      )
+      end
+    end
+
+    class APIStatusError < ArkEmail::Errors::APIError
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: Integer,
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.for(
+        url:,
+        status:,
+        headers:,
+        body:,
+        request:,
+        response:,
+        message: nil
+      )
+      end
+
+      sig { returns(Integer) }
+      attr_accessor :status
+
+      # @api private
+      sig do
+        params(
+          url: URI::Generic,
+          status: Integer,
+          headers: T.nilable(T::Hash[String, String]),
+          body: T.nilable(Object),
+          request: NilClass,
+          response: NilClass,
+          message: T.nilable(String)
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        url:,
+        status:,
+        headers:,
+        body:,
+        request:,
+        response:,
+        message: nil
+      )
+      end
+    end
+
+    class BadRequestError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 400
+    end
+
+    class AuthenticationError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 401
+    end
+
+    class PermissionDeniedError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 403
+    end
+
+    class NotFoundError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 404
+    end
+
+    class ConflictError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 409
+    end
+
+    class UnprocessableEntityError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 422
+    end
+
+    class RateLimitError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = 429
+    end
+
+    class InternalServerError < ArkEmail::Errors::APIStatusError
+      HTTP_STATUS = T.let((500..), T::Range[Integer])
+    end
+  end
+end

data/rbi/ark_email/file_part.rbi

@@ -0,0 +1,37 @@
+# typed: strong
+
+module ArkEmail
+  class FilePart
+    sig { returns(T.any(Pathname, StringIO, IO, String)) }
+    attr_reader :content
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :content_type
+
+    sig { returns(T.nilable(String)) }
+    attr_reader :filename
+
+    # @api private
+    sig { returns(String) }
+    private def read
+    end
+
+    sig { params(a: T.anything).returns(String) }
+    def to_json(*a)
+    end
+
+    sig { params(a: T.anything).returns(String) }
+    def to_yaml(*a)
+    end
+
+    sig do
+      params(
+        content: T.any(Pathname, StringIO, IO, String),
+        filename: T.nilable(T.any(Pathname, String)),
+        content_type: T.nilable(String)
+      ).returns(T.attached_class)
+    end
+    def self.new(content, filename: nil, content_type: nil)
+    end
+  end
+end

data/rbi/ark_email/internal/page_number_pagination.rbi

@@ -0,0 +1,52 @@
+# typed: strong
+
+module ArkEmail
+  module Internal
+    class PageNumberPagination
+      include ArkEmail::Internal::Type::BasePage
+
+      Elem = type_member
+
+      sig { returns(T.nilable(T::Array[Elem])) }
+      attr_accessor :data
+
+      sig { returns(Integer) }
+      attr_accessor :page
+
+      sig { returns(Integer) }
+      attr_accessor :per_page
+
+      sig { returns(Integer) }
+      attr_accessor :total
+
+      sig { returns(Integer) }
+      attr_accessor :total_pages
+
+      sig { returns(Meta) }
+      attr_accessor :meta
+
+      # @api private
+      sig { returns(String) }
+      def inspect
+      end
+
+      class Meta < ArkEmail::Internal::Type::BaseModel
+        OrHash = T.type_alias { T.any(Meta, ArkEmail::Internal::AnyHash) }
+
+        sig { returns(T.nilable(String)) }
+        attr_reader :request_id
+
+        sig { params(request_id: String).void }
+        attr_writer :request_id
+
+        sig { params(request_id: String).returns(T.attached_class) }
+        def self.new(request_id: nil)
+        end
+
+        sig { override.returns({ request_id: String }) }
+        def to_hash
+        end
+      end
+    end
+  end
+end