ark-email 0.12.0 → 0.14.0

data/lib/ark_email/models/log_entry_detail.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    class LogEntryDetail < ArkEmail::Models::LogEntry
+      # @!attribute request
+      #   Request body information
+      #
+      #   @return [ArkEmail::Models::LogEntryDetail::Request, nil]
+      optional :request, -> { ArkEmail::LogEntryDetail::Request }
+
+      # @!attribute response
+      #   Response body information
+      #
+      #   @return [ArkEmail::Models::LogEntryDetail::Response, nil]
+      optional :response, -> { ArkEmail::LogEntryDetail::Response }
+
+      # @!method initialize(request: nil, response: nil)
+      #   Full API request log entry with bodies
+      #
+      #   @param request [ArkEmail::Models::LogEntryDetail::Request] Request body information
+      #
+      #   @param response [ArkEmail::Models::LogEntryDetail::Response] Response body information
+
+      class Request < ArkEmail::Internal::Type::BaseModel
+        # @!attribute body
+        #   Decrypted request body (JSON or string). Bodies over 25KB are truncated.
+        #
+        #   @return [Hash{Symbol=>Object}, String, nil]
+        optional :body, union: -> { ArkEmail::LogEntryDetail::Request::Body }, nil?: true
+
+        # @!attribute body_size
+        #   Original request body size in bytes
+        #
+        #   @return [Integer, nil]
+        optional :body_size, Integer, api_name: :bodySize, nil?: true
+
+        # @!method initialize(body: nil, body_size: nil)
+        #   Request body information
+        #
+        #   @param body [Hash{Symbol=>Object}, String, nil] Decrypted request body (JSON or string). Bodies over 25KB are truncated.
+        #
+        #   @param body_size [Integer, nil] Original request body size in bytes
+
+        # Decrypted request body (JSON or string). Bodies over 25KB are truncated.
+        #
+        # @see ArkEmail::Models::LogEntryDetail::Request#body
+        module Body
+          extend ArkEmail::Internal::Type::Union
+
+          variant -> { ArkEmail::Models::LogEntryDetail::Request::Body::UnionMember0Map }
+
+          variant String
+
+          # @!method self.variants
+          #   @return [Array(Hash{Symbol=>Object}, String)]
+
+          # @type [ArkEmail::Internal::Type::Converter]
+          UnionMember0Map = ArkEmail::Internal::Type::HashOf[ArkEmail::Internal::Type::Unknown]
+        end
+      end
+
+      class Response < ArkEmail::Internal::Type::BaseModel
+        # @!attribute body
+        #   Decrypted response body (JSON or string). Bodies over 25KB are truncated.
+        #
+        #   @return [Hash{Symbol=>Object}, String, nil]
+        optional :body, union: -> { ArkEmail::LogEntryDetail::Response::Body }, nil?: true
+
+        # @!attribute body_size
+        #   Response body size in bytes
+        #
+        #   @return [Integer, nil]
+        optional :body_size, Integer, api_name: :bodySize, nil?: true
+
+        # @!method initialize(body: nil, body_size: nil)
+        #   Response body information
+        #
+        #   @param body [Hash{Symbol=>Object}, String, nil] Decrypted response body (JSON or string). Bodies over 25KB are truncated.
+        #
+        #   @param body_size [Integer, nil] Response body size in bytes
+
+        # Decrypted response body (JSON or string). Bodies over 25KB are truncated.
+        #
+        # @see ArkEmail::Models::LogEntryDetail::Response#body
+        module Body
+          extend ArkEmail::Internal::Type::Union
+
+          variant -> { ArkEmail::Models::LogEntryDetail::Response::Body::UnionMember0Map }
+
+          variant String
+
+          # @!method self.variants
+          #   @return [Array(Hash{Symbol=>Object}, String)]
+
+          # @type [ArkEmail::Internal::Type::Converter]
+          UnionMember0Map = ArkEmail::Internal::Type::HashOf[ArkEmail::Internal::Type::Unknown]
+        end
+      end
+    end
+  end
+end

data/lib/ark_email/models/log_list_params.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Logs#list
+    class LogListParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!attribute credential_id
+      #   Filter by API credential ID
+      #
+      #   @return [String, nil]
+      optional :credential_id, String
+
+      # @!attribute end_date
+      #   Filter logs before this date (ISO 8601 format)
+      #
+      #   @return [Time, nil]
+      optional :end_date, Time
+
+      # @!attribute endpoint
+      #   Filter by endpoint name
+      #
+      #   @return [String, nil]
+      optional :endpoint, String
+
+      # @!attribute page
+      #   Page number
+      #
+      #   @return [Integer, nil]
+      optional :page, Integer
+
+      # @!attribute per_page
+      #   Results per page (max 100)
+      #
+      #   @return [Integer, nil]
+      optional :per_page, Integer
+
+      # @!attribute request_id
+      #   Filter by request ID (partial match)
+      #
+      #   @return [String, nil]
+      optional :request_id, String
+
+      # @!attribute start_date
+      #   Filter logs after this date (ISO 8601 format)
+      #
+      #   @return [Time, nil]
+      optional :start_date, Time
+
+      # @!attribute status
+      #   Filter by status category:
+      #
+      #   - `success` - Status codes < 400
+      #   - `error` - Status codes >= 400
+      #
+      #   @return [Symbol, ArkEmail::Models::LogListParams::Status, nil]
+      optional :status, enum: -> { ArkEmail::LogListParams::Status }
+
+      # @!attribute status_code
+      #   Filter by exact HTTP status code (100-599)
+      #
+      #   @return [Integer, nil]
+      optional :status_code, Integer
+
+      # @!method initialize(credential_id: nil, end_date: nil, endpoint: nil, page: nil, per_page: nil, request_id: nil, start_date: nil, status: nil, status_code: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {ArkEmail::Models::LogListParams} for more details.
+      #
+      #   @param credential_id [String] Filter by API credential ID
+      #
+      #   @param end_date [Time] Filter logs before this date (ISO 8601 format)
+      #
+      #   @param endpoint [String] Filter by endpoint name
+      #
+      #   @param page [Integer] Page number
+      #
+      #   @param per_page [Integer] Results per page (max 100)
+      #
+      #   @param request_id [String] Filter by request ID (partial match)
+      #
+      #   @param start_date [Time] Filter logs after this date (ISO 8601 format)
+      #
+      #   @param status [Symbol, ArkEmail::Models::LogListParams::Status] Filter by status category:
+      #
+      #   @param status_code [Integer] Filter by exact HTTP status code (100-599)
+      #
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+
+      # Filter by status category:
+      #
+      # - `success` - Status codes < 400
+      # - `error` - Status codes >= 400
+      module Status
+        extend ArkEmail::Internal::Type::Enum
+
+        SUCCESS = :success
+        ERROR = :error
+
+        # @!method self.values
+        #   @return [Array<Symbol>]
+      end
+    end
+  end
+end

data/lib/ark_email/models/log_retrieve_params.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Logs#retrieve
+    class LogRetrieveParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      # @!method initialize(request_options: {})
+      #   @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}]
+    end
+  end
+end

data/lib/ark_email/models/log_retrieve_response.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Logs#retrieve
+    class LogRetrieveResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #   Full API request log entry with bodies
+      #
+      #   @return [ArkEmail::Models::LogEntryDetail]
+      required :data, -> { ArkEmail::LogEntryDetail }
+
+      # @!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 API request log with request/response bodies
+      #
+      #   @param data [ArkEmail::Models::LogEntryDetail] Full API request log entry with bodies
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param success [Boolean, true]
+    end
+  end
+end

data/lib/ark_email/models.rb

@@ -67,6 +67,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/lib/ark_email/resources/emails.rb

@@ -263,16 +263,21 @@ module ArkEmail
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::EmailSendRawParams} for more details.
+      #
       # Send a pre-formatted RFC 2822 MIME message. Use this for advanced use cases or
       # when migrating from systems that generate raw email content.
       #
-      # The `rawMessage` field should contain the base64-encoded raw email.
+      # **Important:** The `rawMessage` field must be base64-encoded. Your raw MIME
+      # message (with headers like From, To, Subject, Content-Type, followed by a blank
+      # line and the body) must be encoded to base64 before sending.
       #
       # @overload send_raw(from:, raw_message:, to:, bounce: nil, request_options: {})
       #
-      # @param from [String] Sender email address
+      # @param from [String] Sender email address. Must be from a verified domain.
       #
-      # @param raw_message [String] Base64-encoded RFC 2822 MIME message
+      # @param raw_message [String] Base64-encoded RFC 2822 MIME message.
       #
       # @param to [Array<String>] Recipient email addresses
       #

data/lib/ark_email/resources/logs.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+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
+      #
+      # @overload retrieve(request_id, request_options: {})
+      #
+      # @param request_id [String] The request ID (format `req_*`)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::LogRetrieveResponse]
+      #
+      # @see ArkEmail::Models::LogRetrieveParams
+      def retrieve(request_id, params = {})
+        @client.request(
+          method: :get,
+          path: ["logs/%1$s", request_id],
+          model: ArkEmail::Models::LogRetrieveResponse,
+          options: params[:request_options]
+        )
+      end
+
+      # Some parameter documentations has been truncated, see
+      # {ArkEmail::Models::LogListParams} for more details.
+      #
+      # 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
+      #
+      # @overload list(credential_id: nil, end_date: nil, endpoint: nil, page: nil, per_page: nil, request_id: nil, start_date: nil, status: nil, status_code: nil, request_options: {})
+      #
+      # @param credential_id [String] Filter by API credential ID
+      #
+      # @param end_date [Time] Filter logs before this date (ISO 8601 format)
+      #
+      # @param endpoint [String] Filter by endpoint name
+      #
+      # @param page [Integer] Page number
+      #
+      # @param per_page [Integer] Results per page (max 100)
+      #
+      # @param request_id [String] Filter by request ID (partial match)
+      #
+      # @param start_date [Time] Filter logs after this date (ISO 8601 format)
+      #
+      # @param status [Symbol, ArkEmail::Models::LogListParams::Status] Filter by status category:
+      #
+      # @param status_code [Integer] Filter by exact HTTP status code (100-599)
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Internal::PageNumberPagination<ArkEmail::Models::LogEntry>]
+      #
+      # @see ArkEmail::Models::LogListParams
+      def list(params = {})
+        parsed, options = ArkEmail::LogListParams.dump_request(params)
+        @client.request(
+          method: :get,
+          path: "logs",
+          query: parsed.transform_keys(
+            credential_id: "credentialId",
+            end_date: "endDate",
+            per_page: "perPage",
+            request_id: "requestId",
+            start_date: "startDate",
+            status_code: "statusCode"
+          ),
+          page: ArkEmail::Internal::PageNumberPagination,
+          model: ArkEmail::LogEntry,
+          options: options
+        )
+      end
+
+      # @api private
+      #
+      # @param client [ArkEmail::Client]
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/ark_email/version.rb

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

data/lib/ark_email.rb

@@ -53,6 +53,7 @@ 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/log_entry"
 require_relative "ark_email/models/api_meta"
 require_relative "ark_email/models/dns_record"
 require_relative "ark_email/models/domain_create_params"
@@ -79,6 +80,10 @@ 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/log_entry_detail"
+require_relative "ark_email/models/log_list_params"
+require_relative "ark_email/models/log_retrieve_params"
+require_relative "ark_email/models/log_retrieve_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"
@@ -123,6 +128,7 @@ 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/logs"
 require_relative "ark_email/resources/suppressions"
 require_relative "ark_email/resources/tracking"
 require_relative "ark_email/resources/webhooks"

data/rbi/ark_email/client.rbi

@@ -34,6 +34,9 @@ module ArkEmail
     sig { returns(ArkEmail::Resources::Tracking) }
     attr_reader :tracking
 
+    sig { returns(ArkEmail::Resources::Logs) }
+    attr_reader :logs
+
     # @api private
     sig { override.returns(T::Hash[String, String]) }
     private def auth_headers

data/rbi/ark_email/models/email_retrieve_params.rbi

@@ -13,10 +13,13 @@ module ArkEmail
 
       # 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)
       sig { returns(T.nilable(String)) }
       attr_reader :expand
 
@@ -32,10 +35,13 @@ module ArkEmail
       def self.new(
         # 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: {}
       )