ark-email 0.13.0 → 0.14.0

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/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.13.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: {}
       )