ark-email 0.7.0 → 0.8.0

data/lib/ark_email/models/webhook_retrieve_delivery_response.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Webhooks#retrieve_delivery
+    class WebhookRetrieveDeliveryResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #   Full details of a webhook delivery including request and response
+      #
+      #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data]
+      required :data, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data }
+
+      # @!attribute meta
+      #
+      #   @return [ArkEmail::Models::APIMeta]
+      required :meta, -> { ArkEmail::APIMeta }
+
+      # @!attribute success
+      #
+      #   @return [Boolean, true]
+      required :success, const: true
+
+      # @!method initialize(data:, meta:, success: true)
+      #   Detailed information about a webhook delivery attempt
+      #
+      #   @param data [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data] Full details of a webhook delivery including request and response
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param success [Boolean, true]
+
+      # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse#data
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute id
+        #   Unique delivery ID (UUID)
+        #
+        #   @return [String]
+        required :id, String
+
+        # @!attribute attempt
+        #   Attempt number for this delivery
+        #
+        #   @return [Integer]
+        required :attempt, Integer
+
+        # @!attribute event
+        #   Event type that triggered this delivery
+        #
+        #   @return [Symbol, ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event]
+        required :event, enum: -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event }
+
+        # @!attribute request
+        #   The request that was sent to your endpoint
+        #
+        #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request]
+        required :request, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request }
+
+        # @!attribute response
+        #   The response received from your endpoint
+        #
+        #   @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response]
+        required :response, -> { ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response }
+
+        # @!attribute status_code
+        #   HTTP status code returned by the endpoint
+        #
+        #   @return [Integer, nil]
+        required :status_code, Integer, api_name: :statusCode, nil?: true
+
+        # @!attribute success
+        #   Whether the delivery was successful (2xx response)
+        #
+        #   @return [Boolean]
+        required :success, ArkEmail::Internal::Type::Boolean
+
+        # @!attribute timestamp
+        #   When this delivery attempt occurred
+        #
+        #   @return [Time]
+        required :timestamp, Time
+
+        # @!attribute url
+        #   URL the webhook was delivered to
+        #
+        #   @return [String]
+        required :url, String
+
+        # @!attribute webhook_id
+        #   ID of the webhook this delivery belongs to
+        #
+        #   @return [String]
+        required :webhook_id, String, api_name: :webhookId
+
+        # @!attribute webhook_name
+        #   Name of the webhook for easy identification
+        #
+        #   @return [String]
+        required :webhook_name, String, api_name: :webhookName
+
+        # @!attribute will_retry
+        #   Whether this delivery will be retried
+        #
+        #   @return [Boolean]
+        required :will_retry, ArkEmail::Internal::Type::Boolean, api_name: :willRetry
+
+        # @!method initialize(id:, attempt:, event:, request:, response:, status_code:, success:, timestamp:, url:, webhook_id:, webhook_name:, will_retry:)
+        #   Full details of a webhook delivery including request and response
+        #
+        #   @param id [String] Unique delivery ID (UUID)
+        #
+        #   @param attempt [Integer] Attempt number for this delivery
+        #
+        #   @param event [Symbol, ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Event] Event type that triggered this delivery
+        #
+        #   @param request [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Request] The request that was sent to your endpoint
+        #
+        #   @param response [ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data::Response] The response received from your endpoint
+        #
+        #   @param status_code [Integer, nil] HTTP status code returned by the endpoint
+        #
+        #   @param success [Boolean] Whether the delivery was successful (2xx response)
+        #
+        #   @param timestamp [Time] When this delivery attempt occurred
+        #
+        #   @param url [String] URL the webhook was delivered to
+        #
+        #   @param webhook_id [String] ID of the webhook this delivery belongs to
+        #
+        #   @param webhook_name [String] Name of the webhook for easy identification
+        #
+        #   @param will_retry [Boolean] Whether this delivery will be retried
+
+        # Event type that triggered this delivery
+        #
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#event
+        module Event
+          extend ArkEmail::Internal::Type::Enum
+
+          MESSAGE_SENT = :MessageSent
+          MESSAGE_DELAYED = :MessageDelayed
+          MESSAGE_DELIVERY_FAILED = :MessageDeliveryFailed
+          MESSAGE_HELD = :MessageHeld
+          MESSAGE_BOUNCED = :MessageBounced
+          MESSAGE_LINK_CLICKED = :MessageLinkClicked
+          MESSAGE_LOADED = :MessageLoaded
+          DOMAIN_DNS_ERROR = :DomainDNSError
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#request
+        class Request < ArkEmail::Internal::Type::BaseModel
+          # @!attribute headers
+          #   HTTP headers that were sent with the request
+          #
+          #   @return [Hash{Symbol=>String}]
+          required :headers, ArkEmail::Internal::Type::HashOf[String]
+
+          # @!attribute payload
+          #   The complete webhook payload that was sent
+          #
+          #   @return [Hash{Symbol=>Object}]
+          required :payload, ArkEmail::Internal::Type::HashOf[ArkEmail::Internal::Type::Unknown]
+
+          # @!method initialize(headers:, payload:)
+          #   The request that was sent to your endpoint
+          #
+          #   @param headers [Hash{Symbol=>String}] HTTP headers that were sent with the request
+          #
+          #   @param payload [Hash{Symbol=>Object}] The complete webhook payload that was sent
+        end
+
+        # @see ArkEmail::Models::WebhookRetrieveDeliveryResponse::Data#response
+        class Response < ArkEmail::Internal::Type::BaseModel
+          # @!attribute status_code
+          #   HTTP status code from your endpoint
+          #
+          #   @return [Integer, nil]
+          required :status_code, Integer, api_name: :statusCode, nil?: true
+
+          # @!attribute body
+          #   Response body from your endpoint (may be truncated)
+          #
+          #   @return [String, nil]
+          optional :body, String, nil?: true
+
+          # @!method initialize(status_code:, body: nil)
+          #   The response received from your endpoint
+          #
+          #   @param status_code [Integer, nil] HTTP status code from your endpoint
+          #
+          #   @param body [String, nil] Response body from your endpoint (may be truncated)
+        end
+      end
+    end
+  end
+end

data/lib/ark_email/models.rb

@@ -95,8 +95,14 @@ module ArkEmail
 
   WebhookDeleteParams = ArkEmail::Models::WebhookDeleteParams
 
+  WebhookListDeliveriesParams = ArkEmail::Models::WebhookListDeliveriesParams
+
   WebhookListParams = ArkEmail::Models::WebhookListParams
 
+  WebhookReplayDeliveryParams = ArkEmail::Models::WebhookReplayDeliveryParams
+
+  WebhookRetrieveDeliveryParams = ArkEmail::Models::WebhookRetrieveDeliveryParams
+
   WebhookRetrieveParams = ArkEmail::Models::WebhookRetrieveParams
 
   WebhookTestParams = ArkEmail::Models::WebhookTestParams

data/lib/ark_email/resources/webhooks.rb

@@ -129,6 +129,133 @@ module ArkEmail
         )
       end
 
+      # Get a paginated list of delivery attempts for a specific webhook.
+      #
+      # Use this to:
+      #
+      # - Monitor webhook health and delivery success rate
+      # - Debug failed deliveries
+      # - Find specific events to replay
+      #
+      # **Filtering:**
+      #
+      # - Filter by success/failure to find problematic deliveries
+      # - Filter by event type to find specific events
+      # - Filter by time range for debugging recent issues
+      #
+      # **Retry behavior:** Failed deliveries are automatically retried with exponential
+      # backoff over ~3 days. Check `willRetry` to see if more attempts are scheduled.
+      #
+      # @overload list_deliveries(webhook_id, after: nil, before: nil, event: nil, page: nil, per_page: nil, success: nil, request_options: {})
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param after [Integer] Only deliveries after this Unix timestamp
+      #
+      # @param before [Integer] Only deliveries before this Unix timestamp
+      #
+      # @param event [Symbol, ArkEmail::Models::WebhookListDeliveriesParams::Event] Filter by event type
+      #
+      # @param page [Integer] Page number (default 1)
+      #
+      # @param per_page [Integer] Items per page (default 30, max 100)
+      #
+      # @param success [Boolean] Filter by delivery success (true = 2xx response, false = non-2xx or error)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookListDeliveriesResponse]
+      #
+      # @see ArkEmail::Models::WebhookListDeliveriesParams
+      def list_deliveries(webhook_id, params = {})
+        parsed, options = ArkEmail::WebhookListDeliveriesParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: ["webhooks/%1$s/deliveries", webhook_id],
+          query: parsed.transform_keys(per_page: "perPage"),
+          model: ArkEmail::Models::WebhookListDeliveriesResponse,
+          options: options
+        )
+      end
+
+      # Re-send a webhook delivery to your endpoint.
+      #
+      # **Use cases:**
+      #
+      # - Recover from transient failures after fixing your endpoint
+      # - Test endpoint changes with real historical data
+      # - Retry deliveries that failed due to downtime
+      #
+      # **How it works:**
+      #
+      # 1. Fetches the original payload from the delivery
+      # 2. Generates a new timestamp and signature
+      # 3. Sends to your webhook URL immediately
+      # 4. Returns the result (does not queue for retry if it fails)
+      #
+      # **Note:** The webhook must be enabled to replay deliveries.
+      #
+      # @overload replay_delivery(delivery_id, webhook_id:, request_options: {})
+      #
+      # @param delivery_id [String] Delivery ID (UUID) to replay
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookReplayDeliveryResponse]
+      #
+      # @see ArkEmail::Models::WebhookReplayDeliveryParams
+      def replay_delivery(delivery_id, params)
+        parsed, options = ArkEmail::WebhookReplayDeliveryParams.dump_request(params)
+        webhook_id =
+          parsed.delete(:webhook_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :post,
+          path: ["webhooks/%1$s/deliveries/%2$s/replay", webhook_id, delivery_id],
+          model: ArkEmail::Models::WebhookReplayDeliveryResponse,
+          options: options
+        )
+      end
+
+      # Get detailed information about a specific webhook delivery attempt.
+      #
+      # Returns:
+      #
+      # - The complete request payload that was sent
+      # - Request headers including the signature
+      # - Response status code and body from your endpoint
+      # - Timing information
+      #
+      # Use this to debug why a delivery failed or verify what data was sent.
+      #
+      # @overload retrieve_delivery(delivery_id, webhook_id:, request_options: {})
+      #
+      # @param delivery_id [String] Delivery ID (UUID)
+      #
+      # @param webhook_id [String] Webhook ID or UUID
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::WebhookRetrieveDeliveryResponse]
+      #
+      # @see ArkEmail::Models::WebhookRetrieveDeliveryParams
+      def retrieve_delivery(delivery_id, params)
+        parsed, options = ArkEmail::WebhookRetrieveDeliveryParams.dump_request(params)
+        webhook_id =
+          parsed.delete(:webhook_id) do
+            raise ArgumentError.new("missing required path argument #{_1}")
+          end
+        @client.request(
+          method: :get,
+          path: ["webhooks/%1$s/deliveries/%2$s", webhook_id, delivery_id],
+          model: ArkEmail::Models::WebhookRetrieveDeliveryResponse,
+          options: options
+        )
+      end
+
       # Send a test payload to your webhook endpoint and verify it receives the data
       # correctly.
       #

data/lib/ark_email/version.rb

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

data/lib/ark_email.rb

@@ -106,8 +106,14 @@ 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_deliveries_params"
+require_relative "ark_email/models/webhook_list_deliveries_response"
 require_relative "ark_email/models/webhook_list_params"
 require_relative "ark_email/models/webhook_list_response"
+require_relative "ark_email/models/webhook_replay_delivery_params"
+require_relative "ark_email/models/webhook_replay_delivery_response"
+require_relative "ark_email/models/webhook_retrieve_delivery_params"
+require_relative "ark_email/models/webhook_retrieve_delivery_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"

data/rbi/ark_email/models/email_send_batch_params.rbi

@@ -82,9 +82,18 @@ module ArkEmail
         #
         # This is useful for correlating webhook events with your internal systems (e.g.,
         # user IDs, order IDs, campaign identifiers).
+        #
+        # **Validation Rules:**
+        #
+        # - Maximum 10 keys per email
+        # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+        #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+        # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+        # - Total size: 4KB maximum (JSON-encoded)
         sig { returns(T.nilable(T::Hash[Symbol, String])) }
         attr_accessor :metadata
 
+        # Tag for categorization and filtering
         sig { returns(T.nilable(String)) }
         attr_accessor :tag
 
@@ -115,7 +124,16 @@ module ArkEmail
           #
           # This is useful for correlating webhook events with your internal systems (e.g.,
           # user IDs, order IDs, campaign identifiers).
+          #
+          # **Validation Rules:**
+          #
+          # - Maximum 10 keys per email
+          # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+          #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+          # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+          # - Total size: 4KB maximum (JSON-encoded)
           metadata: nil,
+          # Tag for categorization and filtering
           tag: nil,
           text: nil
         )

data/rbi/ark_email/models/email_send_params.rbi

@@ -64,6 +64,14 @@ module ArkEmail
       #
       # This is useful for correlating webhook events with your internal systems (e.g.,
       # user IDs, order IDs, campaign identifiers).
+      #
+      # **Validation Rules:**
+      #
+      # - Maximum 10 keys per email
+      # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+      #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+      # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+      # - Total size: 4KB maximum (JSON-encoded)
       sig { returns(T.nilable(T::Hash[Symbol, String])) }
       attr_accessor :metadata
 
@@ -141,6 +149,14 @@ module ArkEmail
         #
         # This is useful for correlating webhook events with your internal systems (e.g.,
         # user IDs, order IDs, campaign identifiers).
+        #
+        # **Validation Rules:**
+        #
+        # - Maximum 10 keys per email
+        # - Keys: 1-40 characters, must start with a letter, only alphanumeric and
+        #   underscores (`^[a-zA-Z][a-zA-Z0-9_]*$`)
+        # - Values: 1-500 characters, no control characters (newlines, tabs, etc.)
+        # - Total size: 4KB maximum (JSON-encoded)
         metadata: nil,
         # Reply-to address (accepts null)
         reply_to: nil,

data/rbi/ark_email/models/webhook_list_deliveries_params.rbi

@@ -0,0 +1,172 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class WebhookListDeliveriesParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            ArkEmail::WebhookListDeliveriesParams,
+            ArkEmail::Internal::AnyHash
+          )
+        end
+
+      # Only deliveries after this Unix timestamp
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :after
+
+      sig { params(after: Integer).void }
+      attr_writer :after
+
+      # Only deliveries before this Unix timestamp
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :before
+
+      sig { params(before: Integer).void }
+      attr_writer :before
+
+      # Filter by event type
+      sig do
+        returns(
+          T.nilable(ArkEmail::WebhookListDeliveriesParams::Event::OrSymbol)
+        )
+      end
+      attr_reader :event
+
+      sig do
+        params(
+          event: ArkEmail::WebhookListDeliveriesParams::Event::OrSymbol
+        ).void
+      end
+      attr_writer :event
+
+      # Page number (default 1)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :page
+
+      sig { params(page: Integer).void }
+      attr_writer :page
+
+      # Items per page (default 30, max 100)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :per_page
+
+      sig { params(per_page: Integer).void }
+      attr_writer :per_page
+
+      # Filter by delivery success (true = 2xx response, false = non-2xx or error)
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :success
+
+      sig { params(success: T::Boolean).void }
+      attr_writer :success
+
+      sig do
+        params(
+          after: Integer,
+          before: Integer,
+          event: ArkEmail::WebhookListDeliveriesParams::Event::OrSymbol,
+          page: Integer,
+          per_page: Integer,
+          success: T::Boolean,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Only deliveries after this Unix timestamp
+        after: nil,
+        # Only deliveries before this Unix timestamp
+        before: nil,
+        # Filter by event type
+        event: nil,
+        # Page number (default 1)
+        page: nil,
+        # Items per page (default 30, max 100)
+        per_page: nil,
+        # Filter by delivery success (true = 2xx response, false = non-2xx or error)
+        success: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            after: Integer,
+            before: Integer,
+            event: ArkEmail::WebhookListDeliveriesParams::Event::OrSymbol,
+            page: Integer,
+            per_page: Integer,
+            success: T::Boolean,
+            request_options: ArkEmail::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Filter by event type
+      module Event
+        extend ArkEmail::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias do
+            T.all(Symbol, ArkEmail::WebhookListDeliveriesParams::Event)
+          end
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        MESSAGE_SENT =
+          T.let(
+            :MessageSent,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_DELAYED =
+          T.let(
+            :MessageDelayed,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_DELIVERY_FAILED =
+          T.let(
+            :MessageDeliveryFailed,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_HELD =
+          T.let(
+            :MessageHeld,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_BOUNCED =
+          T.let(
+            :MessageBounced,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_LINK_CLICKED =
+          T.let(
+            :MessageLinkClicked,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        MESSAGE_LOADED =
+          T.let(
+            :MessageLoaded,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+        DOMAIN_DNS_ERROR =
+          T.let(
+            :DomainDNSError,
+            ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol
+          )
+
+        sig do
+          override.returns(
+            T::Array[ArkEmail::WebhookListDeliveriesParams::Event::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end