ark-email 0.13.0 → 0.14.0

data/rbi/ark_email/models/log_list_params.rbi

@@ -0,0 +1,163 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class LogListParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ArkEmail::LogListParams, ArkEmail::Internal::AnyHash)
+        end
+
+      # Filter by API credential ID
+      sig { returns(T.nilable(String)) }
+      attr_reader :credential_id
+
+      sig { params(credential_id: String).void }
+      attr_writer :credential_id
+
+      # Filter logs before this date (ISO 8601 format)
+      sig { returns(T.nilable(Time)) }
+      attr_reader :end_date
+
+      sig { params(end_date: Time).void }
+      attr_writer :end_date
+
+      # Filter by endpoint name
+      sig { returns(T.nilable(String)) }
+      attr_reader :endpoint
+
+      sig { params(endpoint: String).void }
+      attr_writer :endpoint
+
+      # Page number
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :page
+
+      sig { params(page: Integer).void }
+      attr_writer :page
+
+      # Results per page (max 100)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :per_page
+
+      sig { params(per_page: Integer).void }
+      attr_writer :per_page
+
+      # Filter by request ID (partial match)
+      sig { returns(T.nilable(String)) }
+      attr_reader :request_id
+
+      sig { params(request_id: String).void }
+      attr_writer :request_id
+
+      # Filter logs after this date (ISO 8601 format)
+      sig { returns(T.nilable(Time)) }
+      attr_reader :start_date
+
+      sig { params(start_date: Time).void }
+      attr_writer :start_date
+
+      # Filter by status category:
+      #
+      # - `success` - Status codes < 400
+      # - `error` - Status codes >= 400
+      sig { returns(T.nilable(ArkEmail::LogListParams::Status::OrSymbol)) }
+      attr_reader :status
+
+      sig { params(status: ArkEmail::LogListParams::Status::OrSymbol).void }
+      attr_writer :status
+
+      # Filter by exact HTTP status code (100-599)
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :status_code
+
+      sig { params(status_code: Integer).void }
+      attr_writer :status_code
+
+      sig do
+        params(
+          credential_id: String,
+          end_date: Time,
+          endpoint: String,
+          page: Integer,
+          per_page: Integer,
+          request_id: String,
+          start_date: Time,
+          status: ArkEmail::LogListParams::Status::OrSymbol,
+          status_code: Integer,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Filter by API credential ID
+        credential_id: nil,
+        # Filter logs before this date (ISO 8601 format)
+        end_date: nil,
+        # Filter by endpoint name
+        endpoint: nil,
+        # Page number
+        page: nil,
+        # Results per page (max 100)
+        per_page: nil,
+        # Filter by request ID (partial match)
+        request_id: nil,
+        # Filter logs after this date (ISO 8601 format)
+        start_date: nil,
+        # Filter by status category:
+        #
+        # - `success` - Status codes < 400
+        # - `error` - Status codes >= 400
+        status: nil,
+        # Filter by exact HTTP status code (100-599)
+        status_code: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            credential_id: String,
+            end_date: Time,
+            endpoint: String,
+            page: Integer,
+            per_page: Integer,
+            request_id: String,
+            start_date: Time,
+            status: ArkEmail::LogListParams::Status::OrSymbol,
+            status_code: Integer,
+            request_options: ArkEmail::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      # Filter by status category:
+      #
+      # - `success` - Status codes < 400
+      # - `error` - Status codes >= 400
+      module Status
+        extend ArkEmail::Internal::Type::Enum
+
+        TaggedSymbol =
+          T.type_alias { T.all(Symbol, ArkEmail::LogListParams::Status) }
+        OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+        SUCCESS = T.let(:success, ArkEmail::LogListParams::Status::TaggedSymbol)
+        ERROR = T.let(:error, ArkEmail::LogListParams::Status::TaggedSymbol)
+
+        sig do
+          override.returns(
+            T::Array[ArkEmail::LogListParams::Status::TaggedSymbol]
+          )
+        end
+        def self.values
+        end
+      end
+    end
+  end
+end

data/rbi/ark_email/models/log_retrieve_params.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class LogRetrieveParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ArkEmail::LogRetrieveParams, ArkEmail::Internal::AnyHash)
+        end
+
+      sig do
+        params(request_options: ArkEmail::RequestOptions::OrHash).returns(
+          T.attached_class
+        )
+      end
+      def self.new(request_options: {})
+      end
+
+      sig { override.returns({ request_options: ArkEmail::RequestOptions }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/ark_email/models/log_retrieve_response.rbi

@@ -0,0 +1,59 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class LogRetrieveResponse < ArkEmail::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            ArkEmail::Models::LogRetrieveResponse,
+            ArkEmail::Internal::AnyHash
+          )
+        end
+
+      # Full API request log entry with bodies
+      sig { returns(ArkEmail::LogEntryDetail) }
+      attr_reader :data
+
+      sig { params(data: ArkEmail::LogEntryDetail::OrHash).void }
+      attr_writer :data
+
+      sig { returns(ArkEmail::APIMeta) }
+      attr_reader :meta
+
+      sig { params(meta: ArkEmail::APIMeta::OrHash).void }
+      attr_writer :meta
+
+      sig { returns(T::Boolean) }
+      attr_accessor :success
+
+      # Detailed API request log with request/response bodies
+      sig do
+        params(
+          data: ArkEmail::LogEntryDetail::OrHash,
+          meta: ArkEmail::APIMeta::OrHash,
+          success: T::Boolean
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # Full API request log entry with bodies
+        data:,
+        meta:,
+        success: true
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            data: ArkEmail::LogEntryDetail,
+            meta: ArkEmail::APIMeta,
+            success: T::Boolean
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/ark_email/models.rbi

@@ -30,6 +30,14 @@ module ArkEmail
 
   EmailSendRawParams = ArkEmail::Models::EmailSendRawParams
 
+  LogEntry = ArkEmail::Models::LogEntry
+
+  LogEntryDetail = ArkEmail::Models::LogEntryDetail
+
+  LogListParams = ArkEmail::Models::LogListParams
+
+  LogRetrieveParams = ArkEmail::Models::LogRetrieveParams
+
   SuppressionBulkCreateParams = ArkEmail::Models::SuppressionBulkCreateParams
 
   SuppressionCreateParams = ArkEmail::Models::SuppressionCreateParams

data/rbi/ark_email/resources/emails.rbi

@@ -20,10 +20,13 @@ module ArkEmail
         email_id,
         # Comma-separated list of fields to include:
         #
+        # - `full` - Include all expanded fields in a single request
         # - `content` - HTML and plain text body
         # - `headers` - Email headers
         # - `deliveries` - Delivery attempt history
-        # - `activity` - Opens and clicks
+        # - `activity` - Opens and clicks tracking data
+        # - `attachments` - File attachments with content (base64 encoded)
+        # - `raw` - Complete raw MIME message (base64 encoded)
         expand: nil,
         request_options: {}
       )

data/rbi/ark_email/resources/logs.rbi

@@ -0,0 +1,104 @@
+# typed: strong
+
+module ArkEmail
+  module Resources
+    class Logs
+      # Retrieve detailed information about a specific API request log, including the
+      # full request and response bodies.
+      #
+      # **Body decryption:** Request and response bodies are stored encrypted and
+      # automatically decrypted when retrieved. Bodies larger than 25KB are truncated at
+      # storage time with a `... [truncated]` marker.
+      #
+      # **Use cases:**
+      #
+      # - Debug a specific failed request
+      # - Review the exact payload sent/received
+      # - Share request details with support
+      #
+      # **Related endpoints:**
+      #
+      # - `GET /logs` - List logs with filters
+      sig do
+        params(
+          request_id: String,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Models::LogRetrieveResponse)
+      end
+      def retrieve(
+        # The request ID (format `req_*`)
+        request_id,
+        request_options: {}
+      )
+      end
+
+      # Retrieve a paginated list of API request logs for debugging and monitoring.
+      # Results are ordered by timestamp, newest first.
+      #
+      # **Use cases:**
+      #
+      # - Debug integration issues by reviewing recent requests
+      # - Monitor error rates and response times
+      # - Audit API usage patterns
+      #
+      # **Filters:**
+      #
+      # - `status` - Filter by success or error category
+      # - `statusCode` - Filter by exact HTTP status code
+      # - `endpoint` - Filter by endpoint name (e.g., `emails.send`)
+      # - `credentialId` - Filter by API key
+      # - `startDate`/`endDate` - Filter by date range
+      #
+      # **Note:** Request and response bodies are only included when retrieving a single
+      # log entry with `GET /logs/{requestId}`.
+      #
+      # **Related endpoints:**
+      #
+      # - `GET /logs/{requestId}` - Get full log details with request/response bodies
+      sig do
+        params(
+          credential_id: String,
+          end_date: Time,
+          endpoint: String,
+          page: Integer,
+          per_page: Integer,
+          request_id: String,
+          start_date: Time,
+          status: ArkEmail::LogListParams::Status::OrSymbol,
+          status_code: Integer,
+          request_options: ArkEmail::RequestOptions::OrHash
+        ).returns(ArkEmail::Internal::PageNumberPagination[ArkEmail::LogEntry])
+      end
+      def list(
+        # Filter by API credential ID
+        credential_id: nil,
+        # Filter logs before this date (ISO 8601 format)
+        end_date: nil,
+        # Filter by endpoint name
+        endpoint: nil,
+        # Page number
+        page: nil,
+        # Results per page (max 100)
+        per_page: nil,
+        # Filter by request ID (partial match)
+        request_id: nil,
+        # Filter logs after this date (ISO 8601 format)
+        start_date: nil,
+        # Filter by status category:
+        #
+        # - `success` - Status codes < 400
+        # - `error` - Status codes >= 400
+        status: nil,
+        # Filter by exact HTTP status code (100-599)
+        status_code: nil,
+        request_options: {}
+      )
+      end
+
+      # @api private
+      sig { params(client: ArkEmail::Client).returns(T.attached_class) }
+      def self.new(client:)
+      end
+    end
+  end
+end

data/sig/ark_email/client.rbs

@@ -20,6 +20,8 @@ module ArkEmail
 
     attr_reader tracking: ArkEmail::Resources::Tracking
 
+    attr_reader logs: ArkEmail::Resources::Logs
+
     private def auth_headers: -> ::Hash[String, String]
 
     def initialize: (

data/sig/ark_email/models/email_retrieve_response.rbs

@@ -37,11 +37,14 @@ module ArkEmail
           timestamp: Float,
           timestamp_iso: Time,
           to: String,
+          activity: ArkEmail::Models::EmailRetrieveResponse::Data::Activity,
+          attachments: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment],
           deliveries: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Delivery],
           headers: ::Hash[Symbol, String],
           html_body: String,
           message_id: String,
           plain_body: String,
+          raw_message: String,
           spam: bool,
           spam_score: Float,
           tag: String
@@ -66,6 +69,18 @@ module ArkEmail
 
         attr_accessor to: String
 
+        attr_reader activity: ArkEmail::Models::EmailRetrieveResponse::Data::Activity?
+
+        def activity=: (
+          ArkEmail::Models::EmailRetrieveResponse::Data::Activity
+        ) -> ArkEmail::Models::EmailRetrieveResponse::Data::Activity
+
+        attr_reader attachments: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment]?
+
+        def attachments=: (
+          ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment]
+        ) -> ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment]
+
         attr_reader deliveries: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Delivery]?
 
         def deliveries=: (
@@ -88,6 +103,10 @@ module ArkEmail
 
         def plain_body=: (String) -> String
 
+        attr_reader raw_message: String?
+
+        def raw_message=: (String) -> String
+
         attr_reader spam: bool?
 
         def spam=: (bool) -> bool
@@ -110,11 +129,14 @@ module ArkEmail
           timestamp: Float,
           timestamp_iso: Time,
           to: String,
+          ?activity: ArkEmail::Models::EmailRetrieveResponse::Data::Activity,
+          ?attachments: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment],
           ?deliveries: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Delivery],
           ?headers: ::Hash[Symbol, String],
           ?html_body: String,
           ?message_id: String,
           ?plain_body: String,
+          ?raw_message: String,
           ?spam: bool,
           ?spam_score: Float,
           ?tag: String
@@ -130,11 +152,14 @@ module ArkEmail
           timestamp: Float,
           timestamp_iso: Time,
           to: String,
+          activity: ArkEmail::Models::EmailRetrieveResponse::Data::Activity,
+          attachments: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Attachment],
           deliveries: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Delivery],
           headers: ::Hash[Symbol, String],
           html_body: String,
           message_id: String,
           plain_body: String,
+          raw_message: String,
           spam: bool,
           spam_score: Float,
           tag: String
@@ -167,6 +192,160 @@ module ArkEmail
           def self?.values: -> ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::status]
         end
 
+        type activity =
+          {
+            clicks: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click],
+            opens: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]
+          }
+
+        class Activity < ArkEmail::Internal::Type::BaseModel
+          attr_reader clicks: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click]?
+
+          def clicks=: (
+            ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click]
+          ) -> ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click]
+
+          attr_reader opens: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]?
+
+          def opens=: (
+            ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]
+          ) -> ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]
+
+          def initialize: (
+            ?clicks: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click],
+            ?opens: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]
+          ) -> void
+
+          def to_hash: -> {
+            clicks: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Click],
+            opens: ::Array[ArkEmail::Models::EmailRetrieveResponse::Data::Activity::Open]
+          }
+
+          type click =
+            {
+              ip_address: String,
+              timestamp: Float,
+              timestamp_iso: Time,
+              url: String,
+              user_agent: String
+            }
+
+          class Click < ArkEmail::Internal::Type::BaseModel
+            attr_reader ip_address: String?
+
+            def ip_address=: (String) -> String
+
+            attr_reader timestamp: Float?
+
+            def timestamp=: (Float) -> Float
+
+            attr_reader timestamp_iso: Time?
+
+            def timestamp_iso=: (Time) -> Time
+
+            attr_reader url: String?
+
+            def url=: (String) -> String
+
+            attr_reader user_agent: String?
+
+            def user_agent=: (String) -> String
+
+            def initialize: (
+              ?ip_address: String,
+              ?timestamp: Float,
+              ?timestamp_iso: Time,
+              ?url: String,
+              ?user_agent: String
+            ) -> void
+
+            def to_hash: -> {
+              ip_address: String,
+              timestamp: Float,
+              timestamp_iso: Time,
+              url: String,
+              user_agent: String
+            }
+          end
+
+          type open_ =
+            {
+              ip_address: String,
+              timestamp: Float,
+              timestamp_iso: Time,
+              user_agent: String
+            }
+
+          class Open < ArkEmail::Internal::Type::BaseModel
+            attr_reader ip_address: String?
+
+            def ip_address=: (String) -> String
+
+            attr_reader timestamp: Float?
+
+            def timestamp=: (Float) -> Float
+
+            attr_reader timestamp_iso: Time?
+
+            def timestamp_iso=: (Time) -> Time
+
+            attr_reader user_agent: String?
+
+            def user_agent=: (String) -> String
+
+            def initialize: (
+              ?ip_address: String,
+              ?timestamp: Float,
+              ?timestamp_iso: Time,
+              ?user_agent: String
+            ) -> void
+
+            def to_hash: -> {
+              ip_address: String,
+              timestamp: Float,
+              timestamp_iso: Time,
+              user_agent: String
+            }
+          end
+        end
+
+        type attachment =
+          {
+            content_type: String,
+            data: String,
+            filename: String,
+            hash_: String,
+            size: Integer
+          }
+
+        class Attachment < ArkEmail::Internal::Type::BaseModel
+          attr_accessor content_type: String
+
+          attr_accessor data: String
+
+          attr_accessor filename: String
+
+          attr_accessor hash_: String
+
+          attr_accessor size: Integer
+
+          def initialize: (
+            content_type: String,
+            data: String,
+            filename: String,
+            hash_: String,
+            size: Integer
+          ) -> void
+
+          def to_hash: -> {
+            content_type: String,
+            data: String,
+            filename: String,
+            hash_: String,
+            size: Integer
+          }
+        end
+
         type delivery =
           {
             id: String,