anypost 1.0.0

data/lib/anypost/http_client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+require "faraday"
+
+module Anypost
+  # Owns a Faraday connection and implements the request loop: header assembly,
+  # retries with full-jitter backoff, idempotency keys, and error mapping.
+  #
+  # @api private
+  class HttpClient
+    RETRYABLE_STATUS = [429, 502, 503].freeze
+    MAX_BACKOFF_SECONDS = 8.0
+    BASE_BACKOFF_SECONDS = 0.5
+
+    # @param sleeper [#call] override the sleep between retries (tests)
+    # @param jitter [#call] override the [0,1) jitter factor (tests)
+    def initialize(api_key:, base_url:, timeout:, max_retries:, default_headers: {},
+      connection: nil, sleeper: nil, jitter: nil)
+      @api_key = api_key
+      @max_retries = max_retries
+      @default_headers = default_headers
+      @connection = connection || build_connection(base_url, timeout)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) if seconds.positive? }
+      @jitter = jitter || -> { rand }
+    end
+
+    # Perform a request and return the decoded JSON body.
+    def request(method, path, body: nil, query: nil, idempotent: false,
+      idempotency_key: nil, max_retries: nil, extra_headers: nil)
+      retries = max_retries.nil? ? @max_retries : max_retries
+      headers = build_headers(
+        has_body: !body.nil?,
+        idempotent: idempotent,
+        idempotency_key: idempotency_key,
+        max_retries: retries,
+        extra_headers: extra_headers
+      )
+      payload = body.nil? ? nil : JSON.generate(body)
+      params = clean_query(query)
+      relative = path.sub(%r{\A/+}, "")
+
+      attempt = 0
+      loop do
+        begin
+          response = @connection.run_request(method, relative, payload, headers) do |req|
+            req.params.update(params) unless params.empty?
+          end
+        rescue Faraday::TimeoutError, Faraday::ConnectionFailed => e
+          raise APIConnectionError.new(connection_message(e), cause: e) unless attempt < retries
+
+          @sleeper.call(backoff(attempt, nil))
+          attempt += 1
+          next
+        end
+
+        status = response.status
+        return decode(response) if status >= 200 && status < 300
+
+        if RETRYABLE_STATUS.include?(status) && attempt < retries
+          @sleeper.call(backoff(attempt, response.headers))
+          attempt += 1
+          next
+        end
+
+        raise Errors.from_response(status, decode(response), response.headers)
+      end
+    end
+
+    def self.user_agent
+      "anypost-ruby/#{Anypost::VERSION} Ruby/#{RUBY_VERSION}"
+    end
+
+    private
+
+    def build_connection(base_url, timeout)
+      url = base_url.end_with?("/") ? base_url : "#{base_url}/"
+      Faraday.new(url: url) do |f|
+        f.options.timeout = timeout
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def build_headers(has_body:, idempotent:, idempotency_key:, max_retries:, extra_headers:)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => self.class.user_agent
+      }.merge(@default_headers)
+
+      headers["Content-Type"] = "application/json" if has_body
+
+      if idempotent
+        if idempotency_key && !idempotency_key.empty?
+          headers["Idempotency-Key"] = idempotency_key
+        elsif max_retries.positive?
+          # Auto-key so built-in retries of a send cannot deliver twice.
+          headers["Idempotency-Key"] = SecureRandom.uuid
+        end
+      end
+
+      headers.merge!(extra_headers) if extra_headers
+      headers
+    end
+
+    def clean_query(query)
+      return {} if query.nil?
+
+      query.each_with_object({}) do |(key, value), out|
+        next if value.nil?
+
+        out[key.to_s] = case value
+        when true then "true"
+        when false then "false"
+        else value.to_s
+        end
+      end
+    end
+
+    def backoff(attempt, headers)
+      unless headers.nil?
+        after = Errors.retry_after_seconds(headers)
+        return [after, MAX_BACKOFF_SECONDS].min if after
+      end
+
+      ceiling = [BASE_BACKOFF_SECONDS * (2**attempt), MAX_BACKOFF_SECONDS].min
+      @jitter.call * ceiling # full jitter
+    end
+
+    def decode(response)
+      return nil if response.status == 204
+
+      body = response.body
+      return nil if body.nil? || (body.respond_to?(:empty?) && body.empty?)
+      return body unless body.is_a?(String)
+
+      begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        body
+      end
+    end
+
+    def connection_message(error)
+      "Could not reach Anypost: #{error.message}"
+    end
+  end
+end

data/lib/anypost/page.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Anypost
+  # One page of a list result.
+  #
+  # Mirrors the wire envelope (`data`, `has_more`, `next_cursor`) and is
+  # enumerable: iterating walks every remaining page automatically, re-fetching
+  # with `after = next_cursor`.
+  #
+  #   page = client.domains.list           # one page
+  #   page.data                            # just this page's items
+  #
+  #   client.domains.list.each do |domain| # every domain, across all pages
+  #     puts domain.name
+  #   end
+  class Page
+    include Enumerable
+
+    # @return [Array<Response>] the items on this page
+    attr_reader :data
+    # @return [Boolean]
+    attr_reader :has_more
+    # @return [String, nil]
+    attr_reader :next_cursor
+
+    # @param response [Hash] the decoded page envelope
+    # @yieldparam cursor [String] fetches and returns the next {Page}
+    def initialize(response, &fetch_next)
+      raw = response.is_a?(Hash) ? response : {}
+      @data = (raw["data"] || []).map { |item| Response.wrap(item) }
+      @has_more = raw["has_more"] || false
+      cursor = raw["next_cursor"]
+      @next_cursor = cursor.is_a?(String) ? cursor : nil
+      @fetch_next = fetch_next
+    end
+
+    # Fetch the next page, or nil when there are no more.
+    # @return [Page, nil]
+    def next_page
+      return nil unless @has_more && @next_cursor
+
+      @fetch_next.call(@next_cursor)
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      page = self
+      while page
+        page.data.each { |item| yield item }
+        page = page.next_page
+      end
+    end
+  end
+end

data/lib/anypost/resources/api_keys.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/api-keys` endpoints.
+    class ApiKeys < Base
+      # List the team's API keys, newest-first.
+      def list(params = {})
+        paginate("/api-keys", {limit: params[:limit], after: params[:after]})
+      end
+
+      # Issue a new API key.
+      #
+      # The plaintext secret is returned only in this response, as `key` — store
+      # it securely; it cannot be retrieved later.
+      def create(params)
+        request_object(:post, "/api-keys", body: params)
+      end
+
+      # Retrieve a single API key's metadata. The secret is never returned.
+      def get(id)
+        request_object(:get, "/api-keys/#{encode(id)}")
+      end
+
+      # Update a key's name, permissions, and restrictions. The secret is not
+      # rotated here. Changes may take up to 5 minutes to propagate.
+      def update(id, params)
+        request_object(:patch, "/api-keys/#{encode(id)}", body: params)
+      end
+
+      # Delete a key. It may keep authenticating for up to 5 minutes (gateway cache).
+      def delete(id)
+        @http.request(:delete, "/api-keys/#{encode(id)}")
+        nil
+      end
+    end
+  end
+end

data/lib/anypost/resources/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "erb"
+
+module Anypost
+  module Resources
+    # Shared base for the API resources: holds the transport, wraps decoded
+    # object responses as {Response} instances, and builds {Page}s.
+    #
+    # @api private
+    class Base
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      def request_object(method, path, **opts)
+        decoded = @http.request(method, path, **opts)
+        Response.new(decoded.is_a?(Hash) ? decoded : {})
+      end
+
+      def paginate(path, query)
+        decoded = @http.request(:get, path, query: query)
+        Page.new(decoded.is_a?(Hash) ? decoded : {}) do |after|
+          paginate(path, query.merge(after: after))
+        end
+      end
+
+      # Percent-encode a path segment (encodes "/", "@", "*", etc.).
+      def encode(segment)
+        ERB::Util.url_encode(segment.to_s)
+      end
+    end
+  end
+end

data/lib/anypost/resources/domains.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/domains` endpoints.
+    class Domains < Base
+      # List the team's domains, newest-first. Returns a {Page}; iterate it to
+      # walk every page, or follow `page.next_cursor` yourself.
+      def list(params = {})
+        paginate("/domains", {limit: params[:limit], after: params[:after]})
+      end
+
+      # Add a sending domain. The returned domain is `pending` until verified.
+      def create(params)
+        request_object(:post, "/domains", body: params)
+      end
+
+      # Retrieve a single domain by id.
+      def get(id)
+        request_object(:get, "/domains/#{encode(id)}")
+      end
+
+      # Update a domain's tracking configuration. The domain `name` is immutable.
+      def update(id, params)
+        request_object(:patch, "/domains/#{encode(id)}", body: params)
+      end
+
+      # Permanently delete a domain and its DKIM keys.
+      def delete(id)
+        @http.request(:delete, "/domains/#{encode(id)}")
+        nil
+      end
+
+      # Trigger a verification check.
+      #
+      # Always returns the current domain — read `status` and
+      # `verification_failure` to learn the outcome; a still-`pending` domain
+      # does not raise. Safe to poll while DNS propagates.
+      def verify(id)
+        request_object(:post, "/domains/#{encode(id)}/verify")
+      end
+    end
+  end
+end

data/lib/anypost/resources/email.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/email` endpoints.
+    #
+    # Attachment `content` is the raw file bytes (e.g. from `File.binread`); the
+    # SDK base64-encodes it for transport. Do not pre-encode it.
+    class Email < Base
+      # Send a single message.
+      #
+      # All addresses in `to`/`cc`/`bcc` share one envelope. Returns the queued
+      # message id; raises an {Anypost::Error} subclass on failure.
+      def send(email, idempotency_key = nil)
+        request_object(:post, "/email",
+          body: encode_attachments(email), idempotent: true, idempotency_key: idempotency_key)
+      end
+
+      # Send 1-100 independent messages in one request.
+      #
+      # A mixed-outcome batch (HTTP 207) returns normally — inspect each entry's
+      # `status` in `data`; it does not raise.
+      def send_batch(batch, idempotency_key = nil)
+        body = batch.dup
+        body[:defaults] = encode_attachments(batch[:defaults]) if batch[:defaults]
+        body[:emails] = Array(batch[:emails]).map { |email| encode_attachments(email) }
+        request_object(:post, "/email/batch",
+          body: body, idempotent: true, idempotency_key: idempotency_key)
+      end
+
+      private
+
+      def encode_attachments(message)
+        attachments = message[:attachments]
+        return message unless attachments.is_a?(Array)
+
+        message = message.dup
+        message[:attachments] = attachments.map do |attachment|
+          content = attachment[:content]
+          next attachment unless content.is_a?(String)
+
+          attachment.merge(content: [content].pack("m0"))
+        end
+        message
+      end
+    end
+  end
+end

data/lib/anypost/resources/events.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Read access to the `/events` stream. List-only — events are not addressable by id.
+    class Events < Base
+      # Page through the team's events, newest-first.
+      #
+      # The window defaults to the last 24 hours and is clamped to the plan's
+      # retention. Filter with `start`, `end`, `event_type`, `recipient`,
+      # `email_id`, `message_id`, `domain`, `topic`, `campaign`, `template_id`,
+      # and `tags` (an array, matched with hasAny).
+      def list(params = {})
+        tags = params[:tags]
+        paginate("/events", {
+          limit: params[:limit],
+          after: params[:after],
+          start: params[:start],
+          end: params[:end],
+          event_type: params[:event_type],
+          recipient: params[:recipient],
+          email_id: params[:email_id],
+          message_id: params[:message_id],
+          domain: params[:domain],
+          topic: params[:topic],
+          campaign: params[:campaign],
+          template_id: params[:template_id],
+          # Sent comma-separated (tags=a,b); the API matches with hasAny.
+          tags: (tags.is_a?(Array) && !tags.empty?) ? tags.join(",") : nil
+        })
+      end
+    end
+  end
+end

data/lib/anypost/resources/identity.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Identity operations (`/whoami`).
+    class Identity < Base
+      # Identify the team and permission level behind the current API key.
+      def whoami
+        request_object(:get, "/whoami")
+      end
+    end
+  end
+end

data/lib/anypost/resources/suppressions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/suppressions` endpoints. Entries key on `(email, topic)`.
+    class Suppressions < Base
+      # List the team's suppressions, newest-first. Expired rows are filtered out.
+      # Filter with `email_contains`, `topic`, `reason`, and `origin`.
+      def list(params = {})
+        paginate("/suppressions", {
+          limit: params[:limit],
+          after: params[:after],
+          email_contains: params[:email_contains],
+          topic: params[:topic],
+          reason: params[:reason],
+          origin: params[:origin]
+        })
+      end
+
+      # Add a manual suppression. Defaults to topic `*` (every topic). Raises
+      # validation_error if an active entry for the same `(email, topic)` exists.
+      def create(params)
+        request_object(:post, "/suppressions", body: params)
+      end
+
+      # Retrieve the suppression for an `(email, topic)` pair. Use `*` as the
+      # topic for the global row. Raises not_found if the pair isn't suppressed.
+      def get(email, topic)
+        request_object(:get, "/suppressions/#{encode(email)}/#{encode(topic)}")
+      end
+
+      # Remove the single `(email, topic)` row. Other topics are untouched.
+      def delete(email, topic)
+        @http.request(:delete, "/suppressions/#{encode(email)}/#{encode(topic)}")
+        nil
+      end
+
+      # List every suppression on file for an address, across all topics. Raises
+      # not_found if the address has no active suppressions.
+      #
+      # @return [Array<Response>]
+      def list_for_email(email)
+        decoded = @http.request(:get, "/suppressions/#{encode(email)}")
+        data = decoded.is_a?(Hash) ? decoded["data"] : nil
+        Array(data).map { |row| Response.wrap(row) }
+      end
+
+      # Remove an address from the suppression list across every topic.
+      def delete_for_email(email)
+        @http.request(:delete, "/suppressions/#{encode(email)}")
+        nil
+      end
+    end
+  end
+end

data/lib/anypost/resources/templates.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/templates` endpoints, including the draft/publish flow.
+    class Templates < Base
+      # List the team's templates, newest-first.
+      def list(params = {})
+        paginate("/templates", {limit: params[:limit], after: params[:after]})
+      end
+
+      # Create a template. It starts unpublished — publish it before sending.
+      def create(params)
+        request_object(:post, "/templates", body: params)
+      end
+
+      # Retrieve a template, including its published content.
+      def get(id)
+        request_object(:get, "/templates/#{encode(id)}")
+      end
+
+      # Update a template's `name`. Body content lives on the draft.
+      def update(id, params)
+        request_object(:patch, "/templates/#{encode(id)}", body: params)
+      end
+
+      # Permanently delete a template.
+      def delete(id)
+        @http.request(:delete, "/templates/#{encode(id)}")
+        nil
+      end
+
+      # Copy a template. The copy starts unpublished with a draft seeded from the
+      # source's current editable content, and must be published before sending.
+      def duplicate(id, params = {})
+        request_object(:post, "/templates/#{encode(id)}/duplicate",
+          body: params.empty? ? nil : params)
+      end
+
+      # Retrieve the template's unpublished draft. Raises not_found if none exists.
+      def get_draft(id)
+        request_object(:get, "/templates/#{encode(id)}/draft")
+      end
+
+      # Create or update the template's draft. Idempotent upsert; published content untouched.
+      def update_draft(id, params)
+        request_object(:patch, "/templates/#{encode(id)}/draft", body: params)
+      end
+
+      # Discard the template's draft without touching published content.
+      def delete_draft(id)
+        @http.request(:delete, "/templates/#{encode(id)}/draft")
+        nil
+      end
+
+      # Promote the draft into the published slot, consuming the draft.
+      def publish(id)
+        request_object(:post, "/templates/#{encode(id)}/publish")
+      end
+    end
+  end
+end

data/lib/anypost/resources/webhooks.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Anypost
+  module Resources
+    # Operations on the `/webhooks` endpoints.
+    class Webhooks < Base
+      # List the team's webhooks, newest-first.
+      def list(params = {})
+        paginate("/webhooks", {limit: params[:limit], after: params[:after]})
+      end
+
+      # Create a webhook. The full `signing_secret` is on the response to this
+      # call only — store it now to verify future deliveries; later reads return
+      # only the prefix.
+      def create(params)
+        request_object(:post, "/webhooks", body: params)
+      end
+
+      # Retrieve a webhook. The signing secret is never returned — only its prefix.
+      def get(id)
+        request_object(:get, "/webhooks/#{encode(id)}")
+      end
+
+      # Update a webhook's name, URL, subscribed events, and status. This does not
+      # rotate the signing secret — use {#rotate_secret}.
+      def update(id, params)
+        request_object(:patch, "/webhooks/#{encode(id)}", body: params)
+      end
+
+      # Permanently delete a webhook.
+      def delete(id)
+        @http.request(:delete, "/webhooks/#{encode(id)}")
+        nil
+      end
+
+      # Send one synthetic `webhook.test` event and report the outcome. One-shot,
+      # not retried, and absent from delivery history. Returns the result even
+      # when the endpoint fails — read `delivered` and `status_code`.
+      def test(id)
+        request_object(:post, "/webhooks/#{encode(id)}/test")
+      end
+
+      # Rotate the signing secret. The new secret is on this response only. The
+      # previous secret stays valid for a 24h grace window. Rotating again before
+      # the window ends raises webhook_rotation_in_progress (a {ConflictError}).
+      def rotate_secret(id)
+        request_object(:post, "/webhooks/#{encode(id)}/rotate-secret")
+      end
+    end
+  end
+end

data/lib/anypost/response.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Anypost
+  # An immutable view over a decoded JSON response object.
+  #
+  # Read fields with either method or bracket syntax — both return the same
+  # value, and nested objects come back as {Response} instances:
+  #
+  #   email = client.email.send(...)
+  #   email.id          # "email_..."
+  #   email[:id]        # same
+  #   email["id"]       # same
+  #
+  # Lists of objects come back as plain Ruby arrays whose object elements are
+  # themselves {Response} instances. Call {#to_h} for the raw decoded hash.
+  class Response
+    # Wrap a decoded JSON value, turning object-shaped hashes into responses.
+    def self.wrap(value)
+      case value
+      when Hash then new(value)
+      when Array then value.map { |element| wrap(element) }
+      else value
+      end
+    end
+
+    # @param attributes [Hash] decoded JSON object (string keys)
+    def initialize(attributes)
+      @attributes = attributes
+    end
+
+    def [](key)
+      Response.wrap(@attributes[key.to_s])
+    end
+
+    def key?(key)
+      @attributes.key?(key.to_s)
+    end
+
+    # The raw decoded response, with no {Response} wrapping at any depth.
+    # @return [Hash]
+    def to_h
+      @attributes
+    end
+    alias_method :to_hash, :to_h
+
+    def ==(other)
+      other.is_a?(Response) ? to_h == other.to_h : @attributes == other
+    end
+
+    def inspect
+      "#<Anypost::Response #{@attributes.inspect}>"
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @attributes.key?(name.to_s) || super
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if @attributes.key?(key)
+        Response.wrap(@attributes[key])
+      else
+        super
+      end
+    end
+  end
+end

data/lib/anypost/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Anypost
+  # The single source of truth for the gem version. Bump this, tag the commit
+  # `vX.Y.Z`, and push — the release workflow builds and pushes to RubyGems.
+  VERSION = "1.0.0"
+end