ark-email 0.13.0 → 0.15.0

data/lib/ark_email/models/usage_retrieve_response.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Models
+    # @see ArkEmail::Resources::Usage#retrieve
+    class UsageRetrieveResponse < ArkEmail::Internal::Type::BaseModel
+      # @!attribute data
+      #   Current usage and limit information
+      #
+      #   @return [ArkEmail::Models::UsageRetrieveResponse::Data]
+      required :data, -> { ArkEmail::Models::UsageRetrieveResponse::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)
+      #   Account usage and limits response
+      #
+      #   @param data [ArkEmail::Models::UsageRetrieveResponse::Data] Current usage and limit information
+      #
+      #   @param meta [ArkEmail::Models::APIMeta]
+      #
+      #   @param success [Boolean, true]
+
+      # @see ArkEmail::Models::UsageRetrieveResponse#data
+      class Data < ArkEmail::Internal::Type::BaseModel
+        # @!attribute billing
+        #   Billing and credit information
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::Billing, nil]
+        required :billing, -> { ArkEmail::Models::UsageRetrieveResponse::Data::Billing }, nil?: true
+
+        # @!attribute rate_limit
+        #   API rate limit status
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit]
+        required :rate_limit,
+                 -> { ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit },
+                 api_name: :rateLimit
+
+        # @!attribute send_limit
+        #   Email send limit status (hourly cap)
+        #
+        #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit, nil]
+        required :send_limit,
+                 -> { ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit },
+                 api_name: :sendLimit,
+                 nil?: true
+
+        # @!method initialize(billing:, rate_limit:, send_limit:)
+        #   Current usage and limit information
+        #
+        #   @param billing [ArkEmail::Models::UsageRetrieveResponse::Data::Billing, nil] Billing and credit information
+        #
+        #   @param rate_limit [ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit] API rate limit status
+        #
+        #   @param send_limit [ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit, nil] Email send limit status (hourly cap)
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#billing
+        class Billing < ArkEmail::Internal::Type::BaseModel
+          # @!attribute auto_recharge
+          #   Auto-recharge configuration
+          #
+          #   @return [ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge]
+          required :auto_recharge,
+                   -> { ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge },
+                   api_name: :autoRecharge
+
+          # @!attribute credit_balance
+          #   Current credit balance as formatted string (e.g., "25.50")
+          #
+          #   @return [String]
+          required :credit_balance, String, api_name: :creditBalance
+
+          # @!attribute credit_balance_cents
+          #   Current credit balance in cents for precise calculations
+          #
+          #   @return [Integer]
+          required :credit_balance_cents, Integer, api_name: :creditBalanceCents
+
+          # @!attribute has_payment_method
+          #   Whether a payment method is configured
+          #
+          #   @return [Boolean]
+          required :has_payment_method, ArkEmail::Internal::Type::Boolean, api_name: :hasPaymentMethod
+
+          # @!method initialize(auto_recharge:, credit_balance:, credit_balance_cents:, has_payment_method:)
+          #   Billing and credit information
+          #
+          #   @param auto_recharge [ArkEmail::Models::UsageRetrieveResponse::Data::Billing::AutoRecharge] Auto-recharge configuration
+          #
+          #   @param credit_balance [String] Current credit balance as formatted string (e.g., "25.50")
+          #
+          #   @param credit_balance_cents [Integer] Current credit balance in cents for precise calculations
+          #
+          #   @param has_payment_method [Boolean] Whether a payment method is configured
+
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::Billing#auto_recharge
+          class AutoRecharge < ArkEmail::Internal::Type::BaseModel
+            # @!attribute amount
+            #   Amount to recharge when triggered
+            #
+            #   @return [String]
+            required :amount, String
+
+            # @!attribute enabled
+            #   Whether auto-recharge is enabled
+            #
+            #   @return [Boolean]
+            required :enabled, ArkEmail::Internal::Type::Boolean
+
+            # @!attribute threshold
+            #   Balance threshold that triggers recharge
+            #
+            #   @return [String]
+            required :threshold, String
+
+            # @!method initialize(amount:, enabled:, threshold:)
+            #   Auto-recharge configuration
+            #
+            #   @param amount [String] Amount to recharge when triggered
+            #
+            #   @param enabled [Boolean] Whether auto-recharge is enabled
+            #
+            #   @param threshold [String] Balance threshold that triggers recharge
+          end
+        end
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#rate_limit
+        class RateLimit < ArkEmail::Internal::Type::BaseModel
+          # @!attribute limit
+          #   Maximum requests allowed per period
+          #
+          #   @return [Integer]
+          required :limit, Integer
+
+          # @!attribute period
+          #   Time period for the limit
+          #
+          #   @return [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period]
+          required :period, enum: -> { ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period }
+
+          # @!attribute remaining
+          #   Requests remaining in current window
+          #
+          #   @return [Integer]
+          required :remaining, Integer
+
+          # @!attribute reset
+          #   Unix timestamp when the limit resets
+          #
+          #   @return [Integer]
+          required :reset, Integer
+
+          # @!method initialize(limit:, period:, remaining:, reset:)
+          #   API rate limit status
+          #
+          #   @param limit [Integer] Maximum requests allowed per period
+          #
+          #   @param period [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit::Period] Time period for the limit
+          #
+          #   @param remaining [Integer] Requests remaining in current window
+          #
+          #   @param reset [Integer] Unix timestamp when the limit resets
+
+          # Time period for the limit
+          #
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::RateLimit#period
+          module Period
+            extend ArkEmail::Internal::Type::Enum
+
+            SECOND = :second
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+
+        # @see ArkEmail::Models::UsageRetrieveResponse::Data#send_limit
+        class SendLimit < ArkEmail::Internal::Type::BaseModel
+          # @!attribute approaching
+          #   Whether approaching the limit (>90%)
+          #
+          #   @return [Boolean]
+          required :approaching, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute exceeded
+          #   Whether the limit has been exceeded
+          #
+          #   @return [Boolean]
+          required :exceeded, ArkEmail::Internal::Type::Boolean
+
+          # @!attribute limit
+          #   Maximum emails allowed per hour (null = unlimited)
+          #
+          #   @return [Integer, nil]
+          required :limit, Integer, nil?: true
+
+          # @!attribute period
+          #   Time period for the limit
+          #
+          #   @return [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period]
+          required :period, enum: -> { ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period }
+
+          # @!attribute remaining
+          #   Emails remaining in current period (null if unlimited)
+          #
+          #   @return [Integer, nil]
+          required :remaining, Integer, nil?: true
+
+          # @!attribute resets_at
+          #   ISO timestamp when the limit window resets (top of next hour)
+          #
+          #   @return [Time]
+          required :resets_at, Time, api_name: :resetsAt
+
+          # @!attribute usage_percent
+          #   Usage as a percentage (null if unlimited)
+          #
+          #   @return [Float, nil]
+          required :usage_percent, Float, api_name: :usagePercent, nil?: true
+
+          # @!attribute used
+          #   Emails sent in current period
+          #
+          #   @return [Integer]
+          required :used, Integer
+
+          # @!method initialize(approaching:, exceeded:, limit:, period:, remaining:, resets_at:, usage_percent:, used:)
+          #   Email send limit status (hourly cap)
+          #
+          #   @param approaching [Boolean] Whether approaching the limit (>90%)
+          #
+          #   @param exceeded [Boolean] Whether the limit has been exceeded
+          #
+          #   @param limit [Integer, nil] Maximum emails allowed per hour (null = unlimited)
+          #
+          #   @param period [Symbol, ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit::Period] Time period for the limit
+          #
+          #   @param remaining [Integer, nil] Emails remaining in current period (null if unlimited)
+          #
+          #   @param resets_at [Time] ISO timestamp when the limit window resets (top of next hour)
+          #
+          #   @param usage_percent [Float, nil] Usage as a percentage (null if unlimited)
+          #
+          #   @param used [Integer] Emails sent in current period
+
+          # Time period for the limit
+          #
+          # @see ArkEmail::Models::UsageRetrieveResponse::Data::SendLimit#period
+          module Period
+            extend ArkEmail::Internal::Type::Enum
+
+            HOUR = :hour
+
+            # @!method self.values
+            #   @return [Array<Symbol>]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ark_email/models/webhook_create_params.rb

@@ -75,8 +75,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_create_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_list_deliveries_params.rb

@@ -70,8 +70,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_list_deliveries_response.rb

@@ -144,8 +144,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_retrieve_delivery_response.rb

@@ -144,8 +144,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_retrieve_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_test_params.rb

@@ -30,8 +30,6 @@ module ArkEmail
         MESSAGE_LINK_CLICKED = :MessageLinkClicked
         MESSAGE_LOADED = :MessageLoaded
         DOMAIN_DNS_ERROR = :DomainDNSError
-        SEND_LIMIT_APPROACHING = :SendLimitApproaching
-        SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
         # @!method self.values
         #   @return [Array<Symbol>]

data/lib/ark_email/models/webhook_update_response.rb

@@ -101,8 +101,6 @@ module ArkEmail
           MESSAGE_LINK_CLICKED = :MessageLinkClicked
           MESSAGE_LOADED = :MessageLoaded
           DOMAIN_DNS_ERROR = :DomainDNSError
-          SEND_LIMIT_APPROACHING = :SendLimitApproaching
-          SEND_LIMIT_EXCEEDED = :SendLimitExceeded
 
           # @!method self.values
           #   @return [Array<Symbol>]

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
@@ -91,6 +99,8 @@ module ArkEmail
 
   TrackingVerifyParams = ArkEmail::Models::TrackingVerifyParams
 
+  UsageRetrieveParams = ArkEmail::Models::UsageRetrieveParams
+
   WebhookCreateParams = ArkEmail::Models::WebhookCreateParams
 
   WebhookDeleteParams = ArkEmail::Models::WebhookDeleteParams

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/resources/usage.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module ArkEmail
+  module Resources
+    class Usage
+      # Returns current usage and limit information for your account.
+      #
+      # This endpoint is designed for:
+      #
+      # - **AI agents/MCP servers:** Check constraints before planning batch operations
+      # - **Monitoring dashboards:** Display current usage status
+      # - **Rate limit awareness:** Know remaining capacity before making requests
+      #
+      # **Response includes:**
+      #
+      # - `rateLimit` - API request rate limit (requests per second)
+      # - `sendLimit` - Email sending limit (emails per hour)
+      # - `billing` - Credit balance and auto-recharge configuration
+      #
+      # **Notes:**
+      #
+      # - This request counts against your rate limit
+      # - `sendLimit` may be null if Postal is temporarily unavailable
+      # - `billing` is null if billing is not configured
+      # - Send limit resets at the top of each hour
+      #
+      # @overload retrieve(request_options: {})
+      #
+      # @param request_options [ArkEmail::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [ArkEmail::Models::UsageRetrieveResponse]
+      #
+      # @see ArkEmail::Models::UsageRetrieveParams
+      def retrieve(params = {})
+        @client.request(
+          method: :get,
+          path: "usage",
+          model: ArkEmail::Models::UsageRetrieveResponse,
+          options: params[:request_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.15.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"
@@ -102,6 +107,8 @@ require_relative "ark_email/models/tracking_update_params"
 require_relative "ark_email/models/tracking_update_response"
 require_relative "ark_email/models/tracking_verify_params"
 require_relative "ark_email/models/tracking_verify_response"
+require_relative "ark_email/models/usage_retrieve_params"
+require_relative "ark_email/models/usage_retrieve_response"
 require_relative "ark_email/models/webhook_create_params"
 require_relative "ark_email/models/webhook_create_response"
 require_relative "ark_email/models/webhook_delete_params"
@@ -123,6 +130,8 @@ 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/usage"
 require_relative "ark_email/resources/webhooks"

data/rbi/ark_email/client.rbi

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