ark-email 0.14.0 → 0.15.0

data/rbi/ark_email/models/domain_retrieve_response.rbi

@@ -61,47 +61,70 @@ 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::DomainRetrieveResponse::Data::DNSRecords)
+          returns(
+            T.nilable(
+              ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords
+            )
+          )
         end
         attr_reader :dns_records
 
         sig do
           params(
             dns_records:
-              ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords::OrHash
+              T.nilable(
+                ArkEmail::Models::DomainRetrieveResponse::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::DomainRetrieveResponse::Data::DNSRecords::OrHash,
+              T.nilable(
+                ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords::OrHash
+              ),
             name: String,
             uuid: String,
             verified: T::Boolean,
@@ -109,16 +132,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
@@ -126,10 +164,12 @@ module ArkEmail
         sig do
           override.returns(
             {
-              id: String,
+              id: Integer,
               created_at: Time,
               dns_records:
-                ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords,
+                T.nilable(
+                  ArkEmail::Models::DomainRetrieveResponse::Data::DNSRecords
+                ),
               name: String,
               uuid: String,
               verified: T::Boolean,
@@ -149,40 +189,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_verify_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::DomainVerifyResponse::Data::DNSRecords)
+          returns(
+            T.nilable(ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords)
+          )
         end
         attr_reader :dns_records
 
         sig do
           params(
             dns_records:
-              ArkEmail::Models::DomainVerifyResponse::Data::DNSRecords::OrHash
+              T.nilable(
+                ArkEmail::Models::DomainVerifyResponse::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::DomainVerifyResponse::Data::DNSRecords::OrHash,
+              T.nilable(
+                ArkEmail::Models::DomainVerifyResponse::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::DomainVerifyResponse::Data::DNSRecords,
+                T.nilable(
+                  ArkEmail::Models::DomainVerifyResponse::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/track_domain.rbi

@@ -16,7 +16,8 @@ module ArkEmail
       sig { returns(Time) }
       attr_accessor :created_at
 
-      # Whether DNS is correctly configured
+      # Whether the tracking CNAME record is correctly configured. Must be true to use
+      # tracking features.
       sig { returns(T::Boolean) }
       attr_accessor :dns_ok
 
@@ -99,7 +100,8 @@ module ArkEmail
         id:,
         # When the track domain was created
         created_at:,
-        # Whether DNS is correctly configured
+        # Whether the tracking CNAME record is correctly configured. Must be true to use
+        # tracking features.
         dns_ok:,
         # ID of the parent sending domain
         domain_id:,

data/rbi/ark_email/models/usage_retrieve_params.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module ArkEmail
+  module Models
+    class UsageRetrieveParams < ArkEmail::Internal::Type::BaseModel
+      extend ArkEmail::Internal::Type::RequestParameters::Converter
+      include ArkEmail::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(ArkEmail::UsageRetrieveParams, 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