sendping 1.0.0

data/lib/sendping/campaigns.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Campaigns are DOMAIN-FIRST: `domain` (required on create) picks the
+  # contact pool the campaign targets; `from` may be any verified domain.
+  module Campaigns
+    class << self
+      # POST /campaigns
+      #   SendPing::Campaigns.create({ domain: "yourdomain.com", from: "you@yourdomain.com",
+      #                                  subject: "Hello", html: "<p>Hi</p>", segment_id: "seg_1" })
+      # Optional scheduling params: `schedule_timezone` (IANA zone the schedule +
+      # daily batching are evaluated in, e.g. "America/New_York") and
+      # `daily_batch_size` (max recipients per batch-day, 1-100000).
+      def create(params)
+        Client.require_domain!(params, "Campaigns.create")
+        Client.request(:post, "/campaigns", body: params)
+      end
+
+      # GET /campaigns/:id
+      def get(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}")
+      end
+
+      # GET /campaigns
+      def list(params = {})
+        Client.request(:get, "/campaigns", query: Client.pagination(params))
+      end
+
+      # PATCH /campaigns/:id (draft campaigns only). Accepts the create-side
+      # fields plus `followups` (replace pending follow-ups, [] clears),
+      # `list_to` (true/false), `unsubscribe_policy` ("account" | "domain" |
+      # "ignore"), `schedule_timezone` (IANA zone; nil clears), and
+      # `daily_batch_size` (1-100000; nil clears).
+      def update(campaign_id, params)
+        Client.request(:patch, "/campaigns/#{Client.path_escape(campaign_id)}", body: params)
+      end
+
+      # Send now, or schedule with { scheduled_at: "..." }. An optional
+      # `schedule_timezone` (IANA name) is persisted onto the campaign so daily
+      # batching evaluates batch-days in that zone. POST /campaigns/:id/send
+      def send(campaign_id, params = {})
+        Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/send", body: params)
+      end
+
+      # Stop a campaign's remaining work. Accepted on `scheduled`, `recurring`,
+      # `paused` and `queued`; anything else is a validation_error.
+      # `scheduled`/`recurring`/`paused` return to `draft` (editable, re-sendable);
+      # a `queued` campaign already fanning out becomes the TERMINAL `canceled`,
+      # which can never be edited, re-sent or deleted. Copies already handed to
+      # the mail service cannot be recalled; what stops is every remaining
+      # recipient (for a staggered campaign, every future batch-day).
+      # Read the returned `status` to see which happened.
+      # POST /campaigns/:id/cancel
+      def cancel(campaign_id)
+        Client.request(:post, "/campaigns/#{Client.path_escape(campaign_id)}/cancel")
+      end
+
+      # Per-campaign analytics (counts, engagement rates, top links). GET /campaigns/:id/stats
+      def stats(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/stats")
+      end
+
+      # Who opened, clicked and replied, contact by contact. Each list is
+      # capped at 500 rows and there is no pagination.
+      # GET /campaigns/:id/engagement
+      def engagement(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/engagement")
+      end
+
+      # A/B winner evaluation for an A/B campaign. GET /campaigns/:id/ab
+      def ab(campaign_id)
+        Client.request(:get, "/campaigns/#{Client.path_escape(campaign_id)}/ab")
+      end
+
+      # DELETE /campaigns/:id
+      def delete(campaign_id)
+        Client.request(:delete, "/campaigns/#{Client.path_escape(campaign_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/client.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "cgi"
+require "time"
+
+module SendPing
+  # Internal HTTP layer. Every resource funnels through Client.request;
+  # tests stub Client.deliver to avoid the network.
+  module Client
+    module_function
+
+    VERBS = {
+      get: Net::HTTP::Get,
+      post: Net::HTTP::Post,
+      patch: Net::HTTP::Patch,
+      delete: Net::HTTP::Delete
+    }.freeze
+
+    # Only 429/503 are candidates; retry_allowed? also checks progress and
+    # whether a write was rejected before processing or protected by a key.
+    RETRYABLE_STATUSES = [429, 503].freeze
+
+    # Upper bound (seconds) on any single backoff wait.
+    MAX_BACKOFF_SECONDS = 30.0
+
+    # `Idempotency-Key` is stored in a VARCHAR(255) column, so the API accepts
+    # 1-255 characters measured after it trims the value — 255, not 256 — and
+    # answers anything else with 400 invalid_idempotency_key. Only
+    # POST /emails, POST /emails/batch, and received-email reply/forward read the header; every other endpoint
+    # ignores it, so a retry there creates a second resource.
+    #
+    # Exposed for discoverability only: the SDK sends the key as given and lets
+    # the server be the authority.
+    IDEMPOTENCY_KEY_MAX_LENGTH = 255
+
+    # Perform an API request and return the parsed JSON body (a Hash/Array),
+    # or the raw body String when `raw: true` (binary download endpoints).
+    # Raises SendPing::Error on any non-2xx response.
+    def request(verb, path, body: nil, query: nil, options: {}, raw: false)
+      key = SendPing.api_key
+      if key.nil? || key.to_s.strip.empty?
+        raise SendPing::Error.new(
+          'SendPing.api_key is not set. Configure it first: SendPing.api_key = "mb_xxxxxxxxx"',
+          error_name: "missing_api_key"
+        )
+      end
+
+      uri = URI.parse("#{SendPing.base_url.to_s.sub(%r{/+\z}, '')}#{path}")
+      if query && !query.empty?
+        uri.query = [uri.query, URI.encode_www_form(query)].compact.reject(&:empty?).join("&")
+      end
+
+      req = build_request(verb, uri, body, options, key)
+      handle_response(deliver_with_retries(req, uri), raw: raw)
+    end
+
+    # The single request chokepoint: both the JSON and raw/binary paths funnel
+    # through here, so both get the timeout (applied inside deliver) and the
+    # bounded 429/503 retry loop. Non-retryable responses return immediately;
+    # network/timeout errors are NOT caught here (they propagate as before).
+    def deliver_with_retries(req, uri)
+      max = SendPing.max_retries.to_i
+      attempt = 0
+      loop do
+        resp = deliver(req, uri)
+        code = resp.code.to_i
+        return resp unless RETRYABLE_STATUSES.include?(code) && attempt < max && retry_allowed?(req, uri, code, resp.body)
+
+        wait = retry_after_seconds(response_header(resp, "Retry-After"))
+        wait ||= [MAX_BACKOFF_SECONDS, 0.5 * (2**attempt)].min
+        backoff_sleep(wait) if wait.positive?
+        attempt += 1
+      end
+    end
+
+    def retry_allowed?(req, uri, status, raw)
+      body = begin
+        JSON.parse(raw.to_s)
+      rescue JSON::ParserError
+        {}
+      end
+      body = {} unless body.is_a?(Hash)
+      return false if (body["id"].is_a?(String) && !body["id"].empty?) ||
+                      (body["sent_count"].is_a?(Numeric) && body["sent_count"].positive?) ||
+                      (body["sent"].is_a?(Array) && !body["sent"].empty?) ||
+                      (body["reserved"].is_a?(Array) && !body["reserved"].empty?) ||
+                      body["name"] == "batch_incomplete"
+      return true if status != 503 || %w[GET HEAD].include?(req.method)
+      return true if %w[service_unavailable sending_service_unavailable sending_configuration_unavailable contacts_busy contacts_timeout].include?(body["name"])
+
+      req.method == "POST" && !req["Idempotency-Key"].to_s.strip.empty? &&
+        %r{/emails(?:/batch|/receiving/[^/]+/(?:reply|forward))?\z}.match?(uri.path)
+    end
+
+    # Wraps Kernel#sleep so tests can stub out the wait. Extracted so the
+    # retry loop stays deterministic under test.
+    def backoff_sleep(seconds)
+      sleep(seconds)
+    end
+
+    # Read a response header without assuming the response object shape
+    # (Net::HTTPResponse supports #[]; test doubles may not).
+    def response_header(resp, name)
+      return nil unless resp.respond_to?(:[])
+
+      resp[name]
+    rescue StandardError
+      nil
+    end
+
+    # Parse a Retry-After header into a number of seconds to wait:
+    # a numeric delta-seconds value, or an HTTP-date to wait until.
+    # Negative is treated as 0, and the wait is capped at 30 seconds.
+    # Returns nil when the header is absent or unparseable.
+    def retry_after_seconds(value)
+      return nil if value.nil?
+
+      str = value.to_s.strip
+      return nil if str.empty?
+
+      seconds =
+        begin
+          Float(str)
+        rescue ArgumentError, TypeError
+          begin
+            Time.httpdate(str) - Time.now
+          rescue ArgumentError
+            return nil
+          end
+        end
+
+      return nil unless seconds.finite?
+      seconds = 0.0 if seconds.negative?
+      [seconds.to_f, MAX_BACKOFF_SECONDS].min
+    end
+
+    def build_request(verb, uri, body, options, key)
+      klass = VERBS.fetch(verb) { raise ArgumentError, "unsupported HTTP verb: #{verb.inspect}" }
+      req = klass.new(uri)
+      req["Authorization"] = "Bearer #{key}"
+      req["User-Agent"] = "sendping-ruby/#{SendPing::VERSION}"
+      req["Accept"] = "application/json"
+      idem = idempotency_key(opt(options, :idempotency_key))
+      req["Idempotency-Key"] = idem if idem
+      unless body.nil?
+        req["Content-Type"] = "application/json"
+        req.body = JSON.generate(body)
+      end
+      req
+    end
+
+    # The single seam that touches the network (stub me in tests).
+    # Applies the configured open/read timeout; 0 or nil means "no timeout".
+    def deliver(req, uri)
+      opts = { use_ssl: uri.scheme == "https" }
+      t = SendPing.timeout
+      if !t.nil? && t.to_f > 0
+        opts[:open_timeout] = t
+        opts[:read_timeout] = t
+      end
+      Net::HTTP.start(uri.host, uri.port, **opts) do |http|
+        http.request(req)
+      end
+    end
+
+    def handle_response(resp, raw: false)
+      code = resp.code.to_i
+      body = resp.body
+
+      if code >= 200 && code < 300
+        return body if raw
+        return nil if body.nil? || body.empty?
+
+        begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          body
+        end
+      else
+        parsed = begin
+          JSON.parse(body.to_s)
+        rescue JSON::ParserError, TypeError
+          nil
+        end
+        parsed = {} unless parsed.is_a?(Hash)
+        # The whole body rides along: plan/quota errors add `limit`, reputation
+        # gates add `reputation`, and a partial batch failure adds
+        # `sent`/`sent_count` (see SendPing::Error).
+        raise SendPing::Error.new(
+          parsed["message"] || "Request failed with status #{code}",
+          status_code: code,
+          error_name: parsed["name"] || "application_error",
+          body: parsed
+        )
+      end
+    end
+
+    # Percent-encode one path segment so an id like "../api-keys" cannot
+    # traverse the URL path (spaces become %20, "/" becomes %2F).
+    def path_escape(value)
+      CGI.escape(value.to_s).gsub("+", "%20")
+    end
+
+    # Normalize an `idempotency_key` option into the header value. nil/absent or
+    # an empty string means "no header"; anything else is sent VERBATIM.
+    #
+    # The 1-255 bound (IDEMPOTENCY_KEY_MAX_LENGTH) is the server's to enforce —
+    # it trims the value and answers an out-of-range key with
+    # 400 invalid_idempotency_key. Checking here would only risk drifting from
+    # the server, and would disagree with the other SendPing SDKs.
+    def idempotency_key(value)
+      return nil if value.nil?
+
+      key = value.to_s
+      key.empty? ? nil : key
+    end
+
+    # Read a hash param by symbol or string key.
+    def opt(params, key)
+      return nil unless params.is_a?(Hash)
+
+      params.key?(key) ? params[key] : params[key.to_s]
+    end
+
+    # A copy of `params` without the given keys (symbol or string forms).
+    def without(params, *keys)
+      strs = keys.map(&:to_s)
+      params.reject { |k, _| strs.include?(k.to_s) }
+    end
+
+    # Extract the cursor-pagination params ({ limit, after, before }).
+    def pagination(params)
+      q = {}
+      %i[limit after before].each do |k|
+        v = opt(params, k)
+        q[k] = v unless v.nil?
+      end
+      q
+    end
+
+    # Copy the given keys out of `params` into a query hash, skipping the
+    # ones the caller left out. Used to expose an endpoint's server-side
+    # filters without forwarding unrelated params.
+    def filters(params, *keys)
+      keys.each_with_object({}) do |k, q|
+        v = opt(params, k)
+        q[k] = v unless v.nil?
+      end
+    end
+
+    # Domain-first guard: several resources require the sending domain.
+    def require_domain!(params, context)
+      v = opt(params, :domain)
+      if v.nil? || v.to_s.strip.empty?
+        raise ArgumentError,
+              "#{context} requires `domain` — the sending domain whose contact pool it targets, " \
+              'e.g. { domain: "yourdomain.com", ... }'
+      end
+      v
+    end
+  end
+end

data/lib/sendping/contact_properties.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Custom contact fields, usable as {{merge_tags}}.
+  module ContactProperties
+    class << self
+      # POST /contact-properties — params: { key:, type: "string"|"number", fallback_value: }
+      def create(params)
+        Client.request(:post, "/contact-properties", body: params)
+      end
+
+      # GET /contact-properties/:id
+      def get(property_id)
+        Client.request(:get, "/contact-properties/#{Client.path_escape(property_id)}")
+      end
+
+      # GET /contact-properties
+      def list(params = {})
+        Client.request(:get, "/contact-properties", query: Client.pagination(params))
+      end
+
+      # PATCH /contact-properties/:id — only fallback_value is mutable.
+      def update(property_id, params)
+        Client.request(:patch, "/contact-properties/#{Client.path_escape(property_id)}", body: params)
+      end
+
+      # DELETE /contact-properties/:id
+      def delete(property_id)
+        Client.request(:delete, "/contact-properties/#{Client.path_escape(property_id)}")
+      end
+    end
+  end
+end

data/lib/sendping/contacts.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module SendPing
+  # Contacts are DOMAIN-FIRST: each sending domain has its own contact pool,
+  # so the flat /contacts API takes `domain` (required on create/list). The
+  # nested audience variants (`audience_id:`) derive the pool from the path.
+  module Contacts
+    class << self
+      # Create a contact. POST /contacts (flat, `domain` required) or
+      # POST /audiences/:id/contacts when `audience_id` is given.
+      #   SendPing::Contacts.create({ domain: "yourdomain.com", email: "a@b.com" })
+      #   SendPing::Contacts.create({ audience_id: "aud_1", email: "a@b.com" })
+      def create(params)
+        audience_id = Client.opt(params, :audience_id)
+        if audience_id
+          body = Client.without(params, :audience_id, :domain)
+          Client.request(:post, "/audiences/#{Client.path_escape(audience_id)}/contacts", body: body)
+        else
+          Client.require_domain!(params, "Contacts.create (flat /contacts API)")
+          Client.request(:post, "/contacts", body: Client.without(params, :audience_id))
+        end
+      end
+
+      # Retrieve a contact by id (exact) or by email. An email can exist in
+      # several domains' pools, so pass `domain` to pick the pool.
+      #   Contacts.get({ id: "cont_1" })
+      #   Contacts.get({ id: "a@b.com", domain: "yourdomain.com" })
+      #   Contacts.get({ id: "cont_1", audience_id: "aud_1" })
+      def get(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        return Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}") if audience_id
+
+        domain = Client.opt(params, :domain)
+        query = domain ? { domain: domain } : nil
+        Client.request(:get, "/contacts/#{id}", query: query)
+      end
+
+      # List contacts. Flat /contacts requires `domain` (names the pool);
+      # pass `audience_id` instead to use the nested API. `segment_id`
+      # filters either variant; limit/after/before paginate.
+      def list(params = {})
+        audience_id = Client.opt(params, :audience_id)
+        query = Client.pagination(params)
+        segment_id = Client.opt(params, :segment_id)
+        query[:segment_id] = segment_id if segment_id
+
+        if audience_id
+          Client.request(:get, "/audiences/#{Client.path_escape(audience_id)}/contacts", query: query)
+        else
+          query = { domain: Client.require_domain!(params, "Contacts.list (flat /contacts API)") }.merge(query)
+          Client.request(:get, "/contacts", query: query)
+        end
+      end
+
+      # Update a contact (id or email). PATCH /contacts/:id, or the nested
+      # route when `audience_id` is given. On the flat API pass `domain` when
+      # `id` is an email (disambiguates across pools).
+      #   Contacts.update({ id: "cont_1", unsubscribed: true })
+      def update(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        if audience_id
+          body = Client.without(params, :audience_id, :domain, :id)
+          Client.request(:patch, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}", body: body)
+        else
+          Client.request(:patch, "/contacts/#{id}", body: Client.without(params, :audience_id, :id))
+        end
+      end
+
+      # Delete a contact. DELETE /contacts/:id (pass `domain` when `id` is an
+      # email), or the nested route when `audience_id` is given.
+      def delete(params)
+        id = Client.path_escape(Client.opt(params, :id))
+        audience_id = Client.opt(params, :audience_id)
+        return Client.request(:delete, "/audiences/#{Client.path_escape(audience_id)}/contacts/#{id}") if audience_id
+
+        domain = Client.opt(params, :domain)
+        query = domain ? { domain: domain } : nil
+        Client.request(:delete, "/contacts/#{id}", query: query)
+      end
+
+      # Bulk-import contacts from an array (upsert by email; max 10,000).
+      #
+      # Domain-first, like .create: pass :domain for the flat
+      # POST /contacts/batch, or :audience_id for POST /audiences/:id/contacts/batch.
+      # Prefer this over a .create loop for many contacts — one batch takes the
+      # account's contact-limit lock once, a loop takes it per contact.
+      #   Contacts.batch({ domain: "yourdomain.com", contacts: [{ email: "a@b.com" }] })
+      #   Contacts.batch({ audience_id: "aud_1", contacts: [{ email: "a@b.com" }], on_conflict: "skip" })
+      def batch(params)
+        audience_id = Client.opt(params, :audience_id)
+        # "" is truthy in Ruby but names no audience — treat it as absent and
+        # take the flat route, matching the other SendPing SDKs.
+        audience_id = nil if audience_id == ""
+        query = {}
+        on_conflict = Client.opt(params, :on_conflict)
+        query[:on_conflict] = on_conflict if on_conflict
+        body = { contacts: Client.opt(params, :contacts) }
+        return Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/batch",
+          body: body,
+          query: query
+        ) if audience_id
+
+        # The nested route derives its pool from the path; only the flat route
+        # takes :domain (in the body, same as POST /contacts).
+        domain = Client.opt(params, :domain)
+        body[:domain] = domain unless domain.nil?
+        Client.request(:post, "/contacts/batch", body: body, query: query)
+      end
+
+      # Bulk-import contacts from CSV (header row optional; upsert by email).
+      # Non-builtin columns auto-register as custom properties unless
+      # `create_properties: false`. Pass `segment_id` to also add every
+      # imported email to one of this audience's segments.
+      # POST /audiences/:id/contacts/import
+      #
+      # Inline CSV text (capped at 5 MB and 10,000 rows):
+      #   Contacts.import({ audience_id: "aud_1", csv: "email\na@b.com" })
+      # Or a file already uploaded via create_import_upload (no row cap — the
+      # overflow past your contact limit comes back as `limit_skipped`):
+      #   Contacts.import({ audience_id: "aud_1", storage_key: key })
+      def import(params)
+        audience_id = Client.opt(params, :audience_id)
+        query = Client.filters(params, :on_conflict, :segment_id)
+        query[:create_properties] = "false" if Client.opt(params, :create_properties) == false
+        body = Client.filters(params, :csv, :file_name, :storage_key)
+        Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/import",
+          body: body,
+          query: query
+        )
+      end
+
+      # Mint a presigned direct-upload URL for a CSV too large to inline
+      # (up to 256 MB). Upload the file to `upload_url`, then pass the returned
+      # `storage_key` to Contacts.import.
+      # POST /audiences/:id/contacts/import/upload — params: { filename:, size: }
+      # The `upload_url` is a bearer credential — do not log it.
+      def create_import_upload(params)
+        audience_id = Client.opt(params, :audience_id)
+        Client.request(
+          :post,
+          "/audiences/#{Client.path_escape(audience_id)}/contacts/import/upload",
+          body: Client.without(params, :audience_id)
+        )
+      end
+
+      # Add a contact to a segment. POST /contacts/:id/segments/:segment_id
+      def add_to_segment(contact_id, segment_id)
+        Client.request(:post, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
+      end
+
+      # Remove a contact from a segment. DELETE /contacts/:id/segments/:segment_id
+      def remove_from_segment(contact_id, segment_id)
+        Client.request(:delete, "/contacts/#{Client.path_escape(contact_id)}/segments/#{Client.path_escape(segment_id)}")
+      end
+
+      # List the segments a contact belongs to — items carry id/name/created_at
+      # only, not the full segment object. GET /contacts/:id/segments
+      def list_segments(contact_id, params = {})
+        Client.request(
+          :get,
+          "/contacts/#{Client.path_escape(contact_id)}/segments",
+          query: Client.pagination(params)
+        )
+      end
+
+      # Get a contact's topic subscriptions. GET /contacts/:id/topics
+      def get_topics(contact_id, params = {})
+        Client.request(
+          :get,
+          "/contacts/#{Client.path_escape(contact_id)}/topics",
+          query: Client.pagination(params)
+        )
+      end
+
+      # Update a contact's topic subscriptions. PATCH /contacts/:id/topics
+      #   Contacts.update_topics("cont_1", { topics: [{ id: "top_1", subscription: "opt_in" }] })
+      def update_topics(contact_id, params)
+        Client.request(:patch, "/contacts/#{Client.path_escape(contact_id)}/topics", body: params)
+      end
+    end
+  end
+end

data/lib/sendping/domains.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module SendPing
+  module Domains
+    class << self
+      # HTTPS readiness; an unavailable host schedules server-side repair.
+      def tracking_health(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/tracking-health")
+      end
+
+      # Register a sending domain. POST /domains
+      def create(params)
+        Client.request(:post, "/domains", body: params)
+      end
+
+      # GET /domains/:id
+      def get(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}")
+      end
+
+      # GET /domains — with no pagination params one page carries up to 1,000
+      # domains and `has_more` reports any truncation; pass `limit` and walk
+      # `after` to read past that. Rows still pending a DNS-TXT ownership claim
+      # are excluded; read those through get_claim instead.
+      def list(params = {})
+        Client.request(:get, "/domains", query: Client.pagination(params))
+      end
+
+      # Check a domain's live MX records before adding receiving.
+      # `ours` is true only when every MX host is SendPing's. A DNS failure
+      # answers { has_mx: false, ours: false, records: [] }, not an error.
+      # GET /domains/mx-check?name=
+      def mx_check(name)
+        Client.request(:get, "/domains/mx-check", query: { name: name })
+      end
+
+      # Download the domain's DNS records as CSV text (a String, not JSON).
+      # GET /domains/:id/records.csv
+      def records_csv(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/records.csv", raw: true)
+      end
+
+      # PATCH /domains/:id (returns the slim ack { object: "domain", id }).
+      def update(domain_id, params)
+        Client.request(:patch, "/domains/#{Client.path_escape(domain_id)}", body: params)
+      end
+
+      # Trigger DNS verification. POST /domains/:id/verify
+      def verify(domain_id)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/verify")
+      end
+
+      # Claim a domain already verified in another account. POST /domains/claim
+      def claim(params)
+        Client.request(:post, "/domains/claim", body: params)
+      end
+
+      # Retrieve a domain's claim record. GET /domains/:id/claim
+      def get_claim(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/claim")
+      end
+
+      # Verify a domain claim's TXT record. POST /domains/:id/claim/verify
+      def verify_claim(domain_id)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/claim/verify")
+      end
+
+      # Detect the DNS provider and available one-click apply methods.
+      # GET /domains/:id/dns/detect
+      def detect_dns(domain_id)
+        Client.request(:get, "/domains/#{Client.path_escape(domain_id)}/dns/detect")
+      end
+
+      # Apply DNS records via the Cloudflare API, then auto-verify.
+      # POST /domains/:id/dns/cloudflare — params: { token: "..." }
+      def apply_cloudflare_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/cloudflare", body: params)
+      end
+
+      # Apply DNS records via the GoDaddy API, then auto-verify.
+      # POST /domains/:id/dns/godaddy — params: { key: "...", secret: "..." }
+      def apply_godaddy_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/godaddy", body: params)
+      end
+
+      # Apply DNS records via the Namecheap API (existing records preserved),
+      # then auto-verify. POST /domains/:id/dns/namecheap
+      # params: { apiUser: "...", apiKey: "...", userName: "..." } — camelCase,
+      # the same spelling every SendPing SDK uses. `api_user` and `api_key`
+      # are accepted aliases, and the optional username may also be spelled
+      # `username`, but there is NO `user_name` alias: the API ignores that key,
+      # so a username sent under it is silently dropped.
+      def apply_namecheap_dns(domain_id, params)
+        Client.request(:post, "/domains/#{Client.path_escape(domain_id)}/dns/namecheap", body: params)
+      end
+
+      # DELETE /domains/:id
+      def delete(domain_id)
+        Client.request(:delete, "/domains/#{Client.path_escape(domain_id)}")
+      end
+    end
+  end
+end