ark-email 0.5.1

data/rbi/ark_email/resources/suppressions.rbi

@@ -0,0 +1,84 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Suppressions
+      # Add an email address to the suppression list. The address will not receive any
+      # emails until removed.
+      sig do
+        params(
+          address: String,
+          reason: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::SuppressionCreateResponse)
+      end
+      def create(
+        # Email address to suppress
+        address:,
+        # Reason for suppression
+        reason: nil,
+        request_options: {}
+      )
+      end
+
+      # Check if a specific email address is on the suppression list
+      sig do
+        params(
+          email: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::SuppressionRetrieveResponse)
+      end
+      def retrieve(
+        # Email address (URL-encoded)
+        email,
+        request_options: {}
+      )
+      end
+
+      # Get all email addresses on the suppression list. These addresses will not
+      # receive any emails.
+      sig do
+        params(
+          page: Integer,
+          per_page: Integer,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(
+          ArkEmail::Internal::PageNumberPagination[
+            ArkEmail::Models::SuppressionListResponse
+          ]
+        )
+      end
+      def list(page: nil, per_page: nil, request_options: {})
+      end
+
+      # Remove an email address from the suppression list. The address will be able to
+      # receive emails again.
+      sig do
+        params(
+          email: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::SuppressionDeleteResponse)
+      end
+      def delete(email, request_options: {})
+      end
+
+      # Add up to 1000 email addresses to the suppression list at once
+      sig do
+        params(
+          suppressions:
+            T::Array[
+              ArkEmail::SuppressionBulkCreateParams::Suppression::OrHash
+            ],
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::SuppressionBulkCreateResponse)
+      end
+      def bulk_create(suppressions:, request_options: {})
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/ark_email/resources/tracking.rbi

@@ -0,0 +1,130 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Tracking
+      # Create a new track domain for open/click tracking.
+      #
+      # After creation, you must configure a CNAME record pointing to the provided DNS
+      # value before tracking will work.
+      sig do
+        params(
+          domain_id: String,
+          name: String,
+          ssl_enabled: T::Boolean,
+          track_clicks: T::Boolean,
+          track_opens: T::Boolean,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::TrackingCreateResponse)
+      end
+      def create(
+        # ID of the sending domain to attach this track domain to
+        domain_id:,
+        # Subdomain name (e.g., 'track' for track.yourdomain.com)
+        name:,
+        # Enable SSL for tracking URLs (recommended)
+        ssl_enabled: nil,
+        # Enable click tracking
+        track_clicks: nil,
+        # Enable open tracking (tracking pixel)
+        track_opens: nil,
+        request_options: {}
+      )
+      end
+
+      # Get details of a specific track domain including DNS configuration
+      sig do
+        params(
+          tracking_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::TrackingRetrieveResponse)
+      end
+      def retrieve(
+        # Track domain ID or UUID
+        tracking_id,
+        request_options: {}
+      )
+      end
+
+      # Update track domain settings.
+      #
+      # Use this to:
+      #
+      # - Enable/disable click tracking
+      # - Enable/disable open tracking
+      # - Enable/disable SSL
+      # - Set excluded click domains
+      sig do
+        params(
+          tracking_id: String,
+          excluded_click_domains: String,
+          ssl_enabled: T::Boolean,
+          track_clicks: T::Boolean,
+          track_opens: T::Boolean,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::TrackingUpdateResponse)
+      end
+      def update(
+        # Track domain ID or UUID
+        tracking_id,
+        # Comma-separated list of domains to exclude from click tracking
+        excluded_click_domains: nil,
+        # Enable or disable SSL for tracking URLs
+        ssl_enabled: nil,
+        # Enable or disable click tracking
+        track_clicks: nil,
+        # Enable or disable open tracking
+        track_opens: nil,
+        request_options: {}
+      )
+      end
+
+      # List all track domains configured for your server. Track domains enable open and
+      # click tracking for your emails.
+      sig do
+        params(request_options: ArkEmail::RequestOptions::OrHash).returns(
+          ArkEmail::Models::TrackingListResponse
+        )
+      end
+      def list(request_options: {})
+      end
+
+      # Delete a track domain. This will disable tracking for any emails using this
+      # domain.
+      sig do
+        params(
+          tracking_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::TrackingDeleteResponse)
+      end
+      def delete(
+        # Track domain ID or UUID
+        tracking_id,
+        request_options: {}
+      )
+      end
+
+      # Check DNS configuration for the track domain.
+      #
+      # The track domain requires a CNAME record to be configured before open and click
+      # tracking will work. Use this endpoint to verify the DNS is correctly set up.
+      sig do
+        params(
+          tracking_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::TrackingVerifyResponse)
+      end
+      def verify(
+        # Track domain ID or UUID
+        tracking_id,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/ark_email/resources/webhooks.rbi

@@ -0,0 +1,137 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Webhooks
+      # 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
+      sig do
+        params(
+          events: T::Array[ArkEmail::WebhookCreateParams::Event::OrSymbol],
+          name: String,
+          url: String,
+          all_events: T::Boolean,
+          enabled: T::Boolean,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookCreateResponse)
+      end
+      def create(
+        # Events to subscribe to:
+        #
+        # - `MessageSent` - Email successfully delivered to recipient's server
+        # - `MessageDelayed` - Temporary delivery failure, will retry
+        # - `MessageDeliveryFailed` - Permanent delivery failure
+        # - `MessageHeld` - Email held for manual review
+        # - `MessageBounced` - Email bounced back
+        # - `MessageLinkClicked` - Recipient clicked a tracked link
+        # - `MessageLoaded` - Recipient opened the email (tracking pixel loaded)
+        # - `DomainDNSError` - DNS configuration issue detected
+        events:,
+        # Webhook name for identification
+        name:,
+        # HTTPS endpoint URL
+        url:,
+        # Subscribe to all events (ignores events array)
+        all_events: nil,
+        enabled: nil,
+        request_options: {}
+      )
+      end
+
+      # Get webhook details
+      sig do
+        params(
+          webhook_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookRetrieveResponse)
+      end
+      def retrieve(webhook_id, request_options: {})
+      end
+
+      # Update a webhook
+      sig do
+        params(
+          webhook_id: String,
+          all_events: T::Boolean,
+          enabled: T::Boolean,
+          events: T::Array[String],
+          name: String,
+          url: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookUpdateResponse)
+      end
+      def update(
+        webhook_id,
+        all_events: nil,
+        enabled: nil,
+        events: nil,
+        name: nil,
+        url: nil,
+        request_options: {}
+      )
+      end
+
+      # Get all configured webhook endpoints
+      sig do
+        params(request_options: ArkEmail::RequestOptions::OrHash).returns(
+          ArkEmail::Models::WebhookListResponse
+        )
+      end
+      def list(request_options: {})
+      end
+
+      # Delete a webhook
+      sig do
+        params(
+          webhook_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookDeleteResponse)
+      end
+      def delete(webhook_id, 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.
+      sig do
+        params(
+          webhook_id: String,
+          event: ArkEmail::WebhookTestParams::Event::OrSymbol,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::WebhookTestResponse)
+      end
+      def test_(
+        # Webhook ID or UUID
+        webhook_id,
+        # Event type to simulate
+        event:,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/rbi/ark_email/version.rbi

@@ -0,0 +1,5 @@
+# typed: strong
+
+module ArkEmail
+  VERSION = T.let(T.unsafe(nil), String)
+end

data/sig/ark_email/client.rbs

@@ -0,0 +1,34 @@
+module ArkEmail
+  class Client < ArkEmail::Internal::Transport::BaseClient
+    DEFAULT_MAX_RETRIES: 2
+
+    DEFAULT_TIMEOUT_IN_SECONDS: Float
+
+    DEFAULT_INITIAL_RETRY_DELAY: Float
+
+    DEFAULT_MAX_RETRY_DELAY: Float
+
+    attr_reader api_key: String
+
+    attr_reader emails: ArkEmail::Resources::Emails
+
+    attr_reader domains: ArkEmail::Resources::Domains
+
+    attr_reader suppressions: ArkEmail::Resources::Suppressions
+
+    attr_reader webhooks: ArkEmail::Resources::Webhooks
+
+    attr_reader tracking: ArkEmail::Resources::Tracking
+
+    private def auth_headers: -> ::Hash[String, String]
+
+    def initialize: (
+      ?api_key: String?,
+      ?base_url: String?,
+      ?max_retries: Integer,
+      ?timeout: Float,
+      ?initial_retry_delay: Float,
+      ?max_retry_delay: Float
+    ) -> void
+  end
+end

data/sig/ark_email/errors.rbs

@@ -0,0 +1,117 @@
+module ArkEmail
+  module Errors
+    class Error < StandardError
+      attr_accessor cause: StandardError?
+    end
+
+    class ConversionError < ArkEmail::Errors::Error
+      def cause: -> StandardError?
+
+      def initialize: (
+        on: Class,
+        method: Symbol,
+        target: top,
+        value: top,
+        ?cause: StandardError?
+      ) -> void
+    end
+
+    class APIError < ArkEmail::Errors::Error
+      attr_accessor url: URI::Generic
+
+      attr_accessor status: Integer?
+
+      attr_accessor headers: ::Hash[String, String]?
+
+      attr_accessor body: top?
+
+      def initialize: (
+        url: URI::Generic,
+        ?status: Integer?,
+        ?headers: ::Hash[String, String]?,
+        ?body: Object?,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIConnectionError < ArkEmail::Errors::APIError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APITimeoutError < ArkEmail::Errors::APIConnectionError
+      def initialize: (
+        url: URI::Generic,
+        ?status: nil,
+        ?headers: ::Hash[String, String]?,
+        ?body: nil,
+        ?request: nil,
+        ?response: nil,
+        ?message: String?
+      ) -> void
+    end
+
+    class APIStatusError < ArkEmail::Errors::APIError
+      def self.for: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> instance
+
+      def initialize: (
+        url: URI::Generic,
+        status: Integer,
+        headers: ::Hash[String, String]?,
+        body: Object?,
+        request: nil,
+        response: nil,
+        ?message: String?
+      ) -> void
+    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: Range[Integer]
+    end
+  end
+end

data/sig/ark_email/file_part.rbs

@@ -0,0 +1,21 @@
+module ArkEmail
+  class FilePart
+    attr_reader content: Pathname | StringIO | IO | String
+
+    attr_reader content_type: String?
+
+    attr_reader filename: String?
+
+    private def read: -> String
+
+    def to_json: (*top a) -> String
+
+    def to_yaml: (*top a) -> String
+
+    def initialize: (
+      Pathname | StringIO | IO | String content,
+      ?filename: (Pathname | String)?,
+      ?content_type: String?
+    ) -> void
+  end
+end

data/sig/ark_email/internal/page_number_pagination.rbs

@@ -0,0 +1,32 @@
+module ArkEmail
+  module Internal
+    class PageNumberPagination[Elem]
+      include ArkEmail::Internal::Type::BasePage[Elem]
+
+      attr_accessor data: ::Array[Elem]?
+
+      attr_accessor page: Integer
+
+      attr_accessor per_page: Integer
+
+      attr_accessor total: Integer
+
+      attr_accessor total_pages: Integer
+
+      attr_accessor meta: Meta
+
+      def inspect: -> String
+
+      type meta = { request_id: String }
+      class Meta < ArkEmail::Internal::Type::BaseModel
+        attr_reader request_id: String?
+
+        def request_id=: (String) -> String
+
+        def initialize: (?request_id: String) -> void
+
+        def to_hash: -> { request_id: String }
+      end
+    end
+  end
+end

data/sig/ark_email/internal/transport/base_client.rbs

@@ -0,0 +1,133 @@
+module ArkEmail
+  module Internal
+    module Transport
+      class BaseClient
+        extend ArkEmail::Internal::Util::SorbetRuntimeSupport
+
+        type request_components =
+          {
+            method: Symbol,
+            path: String | ::Array[String],
+            query: ::Hash[String, (::Array[String] | String)?]?,
+            headers: ::Hash[String, (String
+            | Integer
+            | ::Array[(String | Integer)?])?]?,
+            body: top?,
+            unwrap: (Symbol
+            | Integer
+            | ::Array[(Symbol | Integer)]
+            | (^(top arg0) -> top))?,
+            page: Class?,
+            stream: Class?,
+            model: ArkEmail::Internal::Type::Converter::input?,
+            options: ArkEmail::request_opts?
+          }
+        type request_input =
+          {
+            method: Symbol,
+            url: URI::Generic,
+            headers: ::Hash[String, String],
+            body: top,
+            max_retries: Integer,
+            timeout: Float
+          }
+
+        MAX_REDIRECTS: 20
+
+        PLATFORM_HEADERS: ::Hash[String, String]
+
+        def self.validate!: (
+          ArkEmail::Internal::Transport::BaseClient::request_components req
+        ) -> void
+
+        def self.should_retry?: (
+          Integer status,
+          headers: ::Hash[String, String]
+        ) -> bool
+
+        def self.follow_redirect: (
+          ArkEmail::Internal::Transport::BaseClient::request_input request,
+          status: Integer,
+          response_headers: ::Hash[String, String]
+        ) -> ArkEmail::Internal::Transport::BaseClient::request_input
+
+        def self.reap_connection!: (
+          Integer | ArkEmail::Errors::APIConnectionError status,
+          stream: Enumerable[String]?
+        ) -> void
+
+        attr_reader base_url: URI::Generic
+
+        attr_reader timeout: Float
+
+        attr_reader max_retries: Integer
+
+        attr_reader initial_retry_delay: Float
+
+        attr_reader max_retry_delay: Float
+
+        attr_reader headers: ::Hash[String, String]
+
+        attr_reader idempotency_header: String?
+
+        # @api private
+        attr_reader requester: ArkEmail::Internal::Transport::PooledNetRequester
+
+        def initialize: (
+          base_url: String,
+          ?timeout: Float,
+          ?max_retries: Integer,
+          ?initial_retry_delay: Float,
+          ?max_retry_delay: Float,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?],
+          ?idempotency_header: String?
+        ) -> void
+
+        private def auth_headers: -> ::Hash[String, String]
+
+        private def user_agent: -> String
+
+        private def generate_idempotency_key: -> String
+
+        private def build_request: (
+          ArkEmail::Internal::Transport::BaseClient::request_components req,
+          ArkEmail::request_options opts
+        ) -> ArkEmail::Internal::Transport::BaseClient::request_input
+
+        private def retry_delay: (
+          ::Hash[String, String] headers,
+          retry_count: Integer
+        ) -> Float
+
+        def send_request: (
+          ArkEmail::Internal::Transport::BaseClient::request_input request,
+          redirect_count: Integer,
+          retry_count: Integer,
+          send_retry_header: bool
+        ) -> [Integer, top, Enumerable[String]]
+
+        def request: (
+          Symbol method,
+          String | ::Array[String] path,
+          ?query: ::Hash[String, (::Array[String] | String)?]?,
+          ?headers: ::Hash[String, (String
+          | Integer
+          | ::Array[(String | Integer)?])?]?,
+          ?body: top?,
+          ?unwrap: (Symbol
+          | Integer
+          | ::Array[(Symbol | Integer)]
+          | (^(top arg0) -> top))?,
+          ?page: Class?,
+          ?stream: Class?,
+          ?model: ArkEmail::Internal::Type::Converter::input?,
+          ?options: ArkEmail::request_opts?
+        ) -> top
+
+        def inspect: -> String
+      end
+    end
+  end
+end