ark-email 0.14.0 → 0.15.0

data/lib/ark_email.rb

@@ -107,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"
@@ -131,4 +133,5 @@ 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

@@ -37,6 +37,9 @@ module ArkEmail
     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

data/rbi/ark_email/models/dns_record.rbi

@@ -6,29 +6,55 @@ module ArkEmail
       OrHash =
         T.type_alias { T.any(ArkEmail::DNSRecord, ArkEmail::Internal::AnyHash) }
 
-      # DNS record name (hostname)
+      # The complete fully-qualified domain name (FQDN). Use this as a reference to
+      # verify the record is configured correctly.
+      sig { returns(String) }
+      attr_accessor :full_name
+
+      # The relative hostname to enter in your DNS provider. Most DNS providers
+      # auto-append the zone name, so you only need to enter this relative part.
+      #
+      # - `"@"` means the apex/root of the zone (for root domains)
+      # - `"mail"` for a subdomain like `mail.example.com`
+      # - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain
       sig { returns(String) }
       attr_accessor :name
 
-      # DNS record type
+      # The DNS record type to create
       sig { returns(ArkEmail::DNSRecord::Type::TaggedSymbol) }
       attr_accessor :type
 
-      # DNS record value
+      # The value to set for the DNS record
       sig { returns(String) }
       attr_accessor :value
 
-      # DNS verification status:
+      # Current verification status of this DNS record:
       #
-      # - `OK` - Record is correctly configured
-      # - `Missing` - Record not found in DNS
-      # - `Invalid` - Record exists but has wrong value
-      # - `null` - Not yet checked
+      # - `OK` - Record is correctly configured and verified
+      # - `Missing` - Record was not found in your DNS
+      # - `Invalid` - Record exists but has an incorrect value
+      # - `null` - Record has not been checked yet
       sig { returns(T.nilable(ArkEmail::DNSRecord::Status::TaggedSymbol)) }
       attr_accessor :status
 
+      # A DNS record that needs to be configured in your domain's DNS settings.
+      #
+      # The `name` field contains the relative hostname to enter in your DNS provider
+      # (which auto-appends the zone). The `fullName` field contains the complete
+      # fully-qualified domain name (FQDN) for reference.
+      #
+      # **Example for subdomain `mail.example.com`:**
+      #
+      # - `name`: `"mail"` (what you enter in DNS provider)
+      # - `fullName`: `"mail.example.com"` (the complete hostname)
+      #
+      # **Example for root domain `example.com`:**
+      #
+      # - `name`: `"@"` (DNS shorthand for apex/root)
+      # - `fullName`: `"example.com"`
       sig do
         params(
+          full_name: String,
           name: String,
           type: ArkEmail::DNSRecord::Type::OrSymbol,
           value: String,
@@ -36,18 +62,26 @@ module ArkEmail
         ).returns(T.attached_class)
       end
       def self.new(
-        # DNS record name (hostname)
+        # The complete fully-qualified domain name (FQDN). Use this as a reference to
+        # verify the record is configured correctly.
+        full_name:,
+        # The relative hostname to enter in your DNS provider. Most DNS providers
+        # auto-append the zone name, so you only need to enter this relative part.
+        #
+        # - `"@"` means the apex/root of the zone (for root domains)
+        # - `"mail"` for a subdomain like `mail.example.com`
+        # - `"ark-xyz._domainkey.mail"` for DKIM on a subdomain
         name:,
-        # DNS record type
+        # The DNS record type to create
         type:,
-        # DNS record value
+        # The value to set for the DNS record
         value:,
-        # DNS verification status:
+        # Current verification status of this DNS record:
         #
-        # - `OK` - Record is correctly configured
-        # - `Missing` - Record not found in DNS
-        # - `Invalid` - Record exists but has wrong value
-        # - `null` - Not yet checked
+        # - `OK` - Record is correctly configured and verified
+        # - `Missing` - Record was not found in your DNS
+        # - `Invalid` - Record exists but has an incorrect value
+        # - `null` - Record has not been checked yet
         status: nil
       )
       end
@@ -55,6 +89,7 @@ module ArkEmail
       sig do
         override.returns(
           {
+            full_name: String,
             name: String,
             type: ArkEmail::DNSRecord::Type::TaggedSymbol,
             value: String,
@@ -65,7 +100,7 @@ module ArkEmail
       def to_hash
       end
 
-      # DNS record type
+      # The DNS record type to create
       module Type
         extend ArkEmail::Internal::Type::Enum
 
@@ -83,12 +118,12 @@ module ArkEmail
         end
       end
 
-      # DNS verification status:
+      # Current verification status of this DNS record:
       #
-      # - `OK` - Record is correctly configured
-      # - `Missing` - Record not found in DNS
-      # - `Invalid` - Record exists but has wrong value
-      # - `null` - Not yet checked
+      # - `OK` - Record is correctly configured and verified
+      # - `Missing` - Record was not found in your DNS
+      # - `Invalid` - Record exists but has an incorrect value
+      # - `null` - Record has not been checked yet
       module Status
         extend ArkEmail::Internal::Type::Enum
 

data/rbi/ark_email/models/domain_create_response.rbi

@@ -59,47 +59,68 @@ module ArkEmail
             )
           end
 
-        # Domain ID
-        sig { returns(String) }
+        # Unique domain identifier
+        sig { returns(Integer) }
         attr_accessor :id
 
+        # Timestamp when the domain was added
         sig { returns(Time) }
         attr_accessor :created_at
 
+        # DNS records that must be added to your domain's DNS settings. Null if records
+        # are not yet generated.
+        #
+        # **Important:** The `name` field contains the relative hostname that you should
+        # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+        # only need to enter the relative part.
+        #
+        # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+        #
+        # - SPF `name` would be `mail` (not `@`)
+        # - DKIM `name` would be `ark-xyz._domainkey.mail`
+        # - Return Path `name` would be `psrp.mail`
         sig do
-          returns(ArkEmail::Models::DomainCreateResponse::Data::DNSRecords)
+          returns(
+            T.nilable(ArkEmail::Models::DomainCreateResponse::Data::DNSRecords)
+          )
         end
         attr_reader :dns_records
 
         sig do
           params(
             dns_records:
-              ArkEmail::Models::DomainCreateResponse::Data::DNSRecords::OrHash
+              T.nilable(
+                ArkEmail::Models::DomainCreateResponse::Data::DNSRecords::OrHash
+              )
           ).void
         end
         attr_writer :dns_records
 
-        # Domain name
+        # The domain name used for sending emails
         sig { returns(String) }
         attr_accessor :name
 
+        # UUID of the domain
         sig { returns(String) }
         attr_accessor :uuid
 
-        # Whether DNS is verified
+        # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+        # Domain must be verified before sending emails.
         sig { returns(T::Boolean) }
         attr_accessor :verified
 
-        # When the domain was verified (null if not verified)
+        # Timestamp when the domain ownership was verified, or null if not yet verified
         sig { returns(T.nilable(Time)) }
         attr_accessor :verified_at
 
         sig do
           params(
-            id: String,
+            id: Integer,
             created_at: Time,
             dns_records:
-              ArkEmail::Models::DomainCreateResponse::Data::DNSRecords::OrHash,
+              T.nilable(
+                ArkEmail::Models::DomainCreateResponse::Data::DNSRecords::OrHash
+              ),
             name: String,
             uuid: String,
             verified: T::Boolean,
@@ -107,16 +128,31 @@ module ArkEmail
           ).returns(T.attached_class)
         end
         def self.new(
-          # Domain ID
+          # Unique domain identifier
           id:,
+          # Timestamp when the domain was added
           created_at:,
+          # DNS records that must be added to your domain's DNS settings. Null if records
+          # are not yet generated.
+          #
+          # **Important:** The `name` field contains the relative hostname that you should
+          # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+          # only need to enter the relative part.
+          #
+          # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+          #
+          # - SPF `name` would be `mail` (not `@`)
+          # - DKIM `name` would be `ark-xyz._domainkey.mail`
+          # - Return Path `name` would be `psrp.mail`
           dns_records:,
-          # Domain name
+          # The domain name used for sending emails
           name:,
+          # UUID of the domain
           uuid:,
-          # Whether DNS is verified
+          # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+          # Domain must be verified before sending emails.
           verified:,
-          # When the domain was verified (null if not verified)
+          # Timestamp when the domain ownership was verified, or null if not yet verified
           verified_at: nil
         )
         end
@@ -124,10 +160,12 @@ module ArkEmail
         sig do
           override.returns(
             {
-              id: String,
+              id: Integer,
               created_at: Time,
               dns_records:
-                ArkEmail::Models::DomainCreateResponse::Data::DNSRecords,
+                T.nilable(
+                  ArkEmail::Models::DomainCreateResponse::Data::DNSRecords
+                ),
               name: String,
               uuid: String,
               verified: T::Boolean,
@@ -147,40 +185,163 @@ module ArkEmail
               )
             end
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :dkim
 
-          sig { params(dkim: ArkEmail::DNSRecord::OrHash).void }
+          sig { params(dkim: T.nilable(ArkEmail::DNSRecord::OrHash)).void }
           attr_writer :dkim
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :return_path
 
-          sig { params(return_path: ArkEmail::DNSRecord::OrHash).void }
+          sig do
+            params(return_path: T.nilable(ArkEmail::DNSRecord::OrHash)).void
+          end
           attr_writer :return_path
 
-          sig { returns(ArkEmail::DNSRecord) }
+          # A DNS record that needs to be configured in your domain's DNS settings.
+          #
+          # The `name` field contains the relative hostname to enter in your DNS provider
+          # (which auto-appends the zone). The `fullName` field contains the complete
+          # fully-qualified domain name (FQDN) for reference.
+          #
+          # **Example for subdomain `mail.example.com`:**
+          #
+          # - `name`: `"mail"` (what you enter in DNS provider)
+          # - `fullName`: `"mail.example.com"` (the complete hostname)
+          #
+          # **Example for root domain `example.com`:**
+          #
+          # - `name`: `"@"` (DNS shorthand for apex/root)
+          # - `fullName`: `"example.com"`
+          sig { returns(T.nilable(ArkEmail::DNSRecord)) }
           attr_reader :spf
 
-          sig { params(spf: ArkEmail::DNSRecord::OrHash).void }
+          sig { params(spf: T.nilable(ArkEmail::DNSRecord::OrHash)).void }
           attr_writer :spf
 
+          # The DNS zone (registrable domain) where records should be added. This is the
+          # root domain that your DNS provider manages. For `mail.example.com`, the zone is
+          # `example.com`. For `example.co.uk`, the zone is `example.co.uk`.
+          sig { returns(T.nilable(String)) }
+          attr_reader :zone
+
+          sig { params(zone: String).void }
+          attr_writer :zone
+
+          # DNS records that must be added to your domain's DNS settings. Null if records
+          # are not yet generated.
+          #
+          # **Important:** The `name` field contains the relative hostname that you should
+          # enter in your DNS provider. Most DNS providers auto-append the zone name, so you
+          # only need to enter the relative part.
+          #
+          # For subdomains like `mail.example.com`, the zone is `example.com`, so:
+          #
+          # - SPF `name` would be `mail` (not `@`)
+          # - DKIM `name` would be `ark-xyz._domainkey.mail`
+          # - Return Path `name` would be `psrp.mail`
           sig do
             params(
-              dkim: ArkEmail::DNSRecord::OrHash,
-              return_path: ArkEmail::DNSRecord::OrHash,
-              spf: ArkEmail::DNSRecord::OrHash
+              dkim: T.nilable(ArkEmail::DNSRecord::OrHash),
+              return_path: T.nilable(ArkEmail::DNSRecord::OrHash),
+              spf: T.nilable(ArkEmail::DNSRecord::OrHash),
+              zone: String
             ).returns(T.attached_class)
           end
-          def self.new(dkim:, return_path:, spf:)
+          def self.new(
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            dkim: nil,
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            return_path: nil,
+            # A DNS record that needs to be configured in your domain's DNS settings.
+            #
+            # The `name` field contains the relative hostname to enter in your DNS provider
+            # (which auto-appends the zone). The `fullName` field contains the complete
+            # fully-qualified domain name (FQDN) for reference.
+            #
+            # **Example for subdomain `mail.example.com`:**
+            #
+            # - `name`: `"mail"` (what you enter in DNS provider)
+            # - `fullName`: `"mail.example.com"` (the complete hostname)
+            #
+            # **Example for root domain `example.com`:**
+            #
+            # - `name`: `"@"` (DNS shorthand for apex/root)
+            # - `fullName`: `"example.com"`
+            spf: nil,
+            # The DNS zone (registrable domain) where records should be added. This is the
+            # root domain that your DNS provider manages. For `mail.example.com`, the zone is
+            # `example.com`. For `example.co.uk`, the zone is `example.co.uk`.
+            zone: nil
+          )
           end
 
           sig do
             override.returns(
               {
-                dkim: ArkEmail::DNSRecord,
-                return_path: ArkEmail::DNSRecord,
-                spf: ArkEmail::DNSRecord
+                dkim: T.nilable(ArkEmail::DNSRecord),
+                return_path: T.nilable(ArkEmail::DNSRecord),
+                spf: T.nilable(ArkEmail::DNSRecord),
+                zone: String
               }
             )
           end

data/rbi/ark_email/models/domain_list_response.rbi

@@ -95,44 +95,38 @@ module ArkEmail
               )
             end
 
-          # Domain ID
-          sig { returns(String) }
+          # Unique domain identifier
+          sig { returns(Integer) }
           attr_accessor :id
 
-          sig { returns(T::Boolean) }
-          attr_accessor :dns_ok
-
+          # The domain name used for sending emails
           sig { returns(String) }
           attr_accessor :name
 
+          # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+          # Domain must be verified before sending emails.
           sig { returns(T::Boolean) }
           attr_accessor :verified
 
           sig do
-            params(
-              id: String,
-              dns_ok: T::Boolean,
-              name: String,
-              verified: T::Boolean
-            ).returns(T.attached_class)
+            params(id: Integer, name: String, verified: T::Boolean).returns(
+              T.attached_class
+            )
           end
           def self.new(
-            # Domain ID
+            # Unique domain identifier
             id:,
-            dns_ok:,
+            # The domain name used for sending emails
             name:,
+            # Whether all DNS records (SPF, DKIM, Return Path) are correctly configured.
+            # Domain must be verified before sending emails.
             verified:
           )
           end
 
           sig do
             override.returns(
-              {
-                id: String,
-                dns_ok: T::Boolean,
-                name: String,
-                verified: T::Boolean
-              }
+              { id: Integer, name: String, verified: T::Boolean }
             )
           end
           def to_hash