postscale 1.0.0

data/lib/postscale/http_client.rb

@@ -0,0 +1,280 @@
+# frozen_string_literal: true
+
+module Postscale
+  class HttpClient
+    IDEMPOTENT_METHODS = %w[GET HEAD OPTIONS].freeze
+    RETRYABLE_ERRORS = [
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT,
+      SocketError,
+      EOFError
+    ].freeze
+
+    USER_AGENT = "postscale-ruby/#{Postscale::VERSION}"
+
+    def initialize(config)
+      @config = config
+      @base_uri = URI.parse(config.base_url)
+    end
+
+    # Perform a GET request.
+    def get(path, params: nil, headers: nil, parse_as: :json)
+      request("GET", path, params: params, headers: headers, parse_as: parse_as)
+    end
+
+    # Perform a POST request with a JSON body.
+    def post(path, json: nil, headers: nil, parse_as: :json)
+      request("POST", path, json: json, headers: headers, parse_as: parse_as)
+    end
+
+    # Perform a PUT request with a JSON body.
+    def put(path, json: nil, headers: nil, parse_as: :json)
+      request("PUT", path, json: json, headers: headers, parse_as: parse_as)
+    end
+
+    # Perform a PATCH request with a JSON body.
+    def patch(path, json: nil, headers: nil, parse_as: :json)
+      request("PATCH", path, json: json, headers: headers, parse_as: parse_as)
+    end
+
+    # Perform a DELETE request.
+    def delete(path, params: nil, headers: nil, parse_as: :json)
+      request("DELETE", path, params: params, headers: headers, parse_as: parse_as)
+    end
+
+    def request(method, path, json: nil, params: nil, headers: nil, parse_as: :json)
+      method = method.to_s.upcase
+      attempts = max_attempts(method)
+      last_error = nil
+
+      attempts.times do |attempt|
+        uri = build_uri(path, params)
+        request = build_request(method, uri, json, headers)
+
+        begin
+          response = perform_request(uri, request)
+        rescue *RETRYABLE_ERRORS => e
+          last_error = network_error(e)
+          if retry_network_error?(method, attempt, attempts)
+            sleep_for(backoff(attempt))
+            next
+          end
+          return failure(last_error)
+        end
+
+        response_headers = headers_from(response)
+        status = response.code.to_i
+
+        if status >= 200 && status < 300
+          return Result.new(data: parse_success(response, parse_as), error: nil, headers: response_headers)
+        end
+
+        body = parse_error_body(response)
+        error = api_error(status, body, response_headers.request_id)
+        last_error = error
+
+        if retry_response?(method, status, attempt, attempts)
+          sleep_for(retry_delay(response, body, attempt))
+          next
+        end
+
+        return Result.new(data: nil, error: error, headers: response_headers)
+      end
+
+      failure(last_error || APIError.new(message: "Postscale API request failed after all retry attempts.", code: "application_error"))
+    end
+
+    private
+
+    def build_uri(path, params = nil)
+      uri = @base_uri.dup
+      base_path = @base_uri.path.to_s.chomp("/")
+      request_path = path.to_s.start_with?("/") ? path.to_s : "/#{path}"
+      uri.path = "#{base_path}#{request_path}"
+      query = query_string(params)
+      uri.query = query unless query.nil? || query.empty?
+      uri
+    end
+
+    def build_request(method, uri, json, headers)
+      request_class = Net::HTTP.const_get(method.capitalize)
+      request = request_class.new(uri)
+      apply_headers(request, headers)
+
+      unless json.nil?
+        request.body = JSON.generate(json)
+        request.content_type = "application/json"
+      end
+
+      request
+    end
+
+    def apply_headers(request, headers)
+      @config.headers.each { |key, value| request[key.to_s] = value.to_s }
+      default_headers.each { |key, value| request[key] = value }
+      (headers || {}).each { |key, value| request[key.to_s] = value.to_s }
+    end
+
+    def default_headers
+      {
+        "Authorization" => "Bearer #{@config.api_key}",
+        "User-Agent"    => USER_AGENT,
+        "Accept"        => "application/json"
+      }
+    end
+
+    def query_string(params)
+      return nil if params.nil? || params.empty?
+
+      pairs = []
+      params.each do |key, value|
+        next if value.nil?
+
+        if value.is_a?(Array)
+          value.each { |item| pairs << [key, item] unless item.nil? }
+        else
+          pairs << [key, value]
+        end
+      end
+      URI.encode_www_form(pairs)
+    end
+
+    def perform_request(uri, request)
+      return @config.transport.call(uri, request) if @config.transport
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = (uri.scheme == "https")
+      http.open_timeout = @config.timeout
+      http.read_timeout = @config.timeout
+      http.write_timeout = @config.timeout
+      http.request(request)
+    end
+
+    def max_attempts(method)
+      return 1 unless IDEMPOTENT_METHODS.include?(method)
+
+      @config.max_retries + 1
+    end
+
+    def retry_network_error?(method, attempt, attempts)
+      IDEMPOTENT_METHODS.include?(method) && attempt + 1 < attempts
+    end
+
+    def retry_response?(method, status, attempt, attempts)
+      attempt + 1 < attempts && IDEMPOTENT_METHODS.include?(method) && (status == 429 || status >= 500)
+    end
+
+    def retry_delay(response, body, attempt)
+      retry_after = response["Retry-After"]
+      parsed = parse_retry_after(retry_after) if retry_after
+      return parsed unless parsed.nil?
+
+      if body.is_a?(Hash)
+        seconds = body["retry_after_seconds"] || body[:retry_after_seconds]
+        return seconds.to_f if seconds.is_a?(Numeric) && seconds.positive?
+      end
+
+      backoff(attempt)
+    end
+
+    def parse_retry_after(value)
+      return nil if value.nil? || value.empty?
+      return value.to_f if value.match?(/\A\d+(\.\d+)?\z/) && value.to_f.positive?
+
+      parsed = Time.httpdate(value)
+      [parsed.to_f - Time.now.to_f, 0.0].max
+    rescue ArgumentError
+      nil
+    end
+
+    def backoff(attempt)
+      [0.25 * (2**attempt), 5.0].min
+    end
+
+    def sleep_for(seconds)
+      @config.sleeper.call(seconds)
+    end
+
+    def parse_success(response, parse_as)
+      body = response.body
+      return body.to_s.b if parse_as == :bytes
+      return body.to_s if parse_as == :text
+      return nil if parse_as == :void || response.code.to_i == 204
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def parse_error_body(response)
+      body = response.body
+      return nil if body.nil? || body.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    def headers_from(response)
+      raw = {}
+      response.each_header { |key, value| raw[key] = value }
+      Headers.new(raw)
+    end
+
+    def api_error(status, body, request_id)
+      code, message = parse_error_envelope(body)
+      APIError.new(
+        message: message || "Postscale API request failed with status #{status}.",
+        code: code || default_error_code(status),
+        status_code: status,
+        request_id: request_id,
+        body: body
+      )
+    end
+
+    def parse_error_envelope(body)
+      return [nil, body] if body.is_a?(String)
+      return [nil, nil] unless body.is_a?(Hash)
+
+      error = body["error"] || body[:error]
+      if error.is_a?(Hash)
+        return [error["code"] || error[:code], error["message"] || error[:message]]
+      end
+      if error.is_a?(String)
+        message = body["message"] || body[:message] || error
+        return [error, message]
+      end
+
+      [body["code"] || body[:code], body["message"] || body[:message]]
+    end
+
+    def default_error_code(status)
+      return "unauthorized" if status == 401
+      return "forbidden" if status == 403
+      return "not_found" if status == 404
+      return "conflict" if status == 409
+      return "unprocessable_entity" if status == 422
+      return "rate_limit_exceeded" if status == 429
+      return "internal_error" if status >= 500
+
+      "api_error"
+    end
+
+    def network_error(error)
+      APIError.new(
+        message: error.message,
+        code: "application_error",
+        status_code: nil
+      )
+    end
+
+    def failure(error)
+      Result.new(data: nil, error: error, headers: Headers.new)
+    end
+  end
+end

data/lib/postscale/resources/aliases.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Aliases < Resource
+      def create(request = nil, **kwargs)
+        @http.post("/v1/aliases", json: request_hash(request, kwargs))
+      end
+
+      def list(params = nil, **kwargs)
+        @http.get("/v1/aliases", params: params_hash(params, kwargs))
+      end
+
+      def get(id)
+        @http.get("/v1/aliases/#{encode(id)}")
+      end
+
+      def update(id, request = nil, **kwargs)
+        @http.patch("/v1/aliases/#{encode(id)}", json: request_hash(request, kwargs))
+      end
+
+      def delete(id)
+        @http.delete("/v1/aliases/#{encode(id)}")
+      end
+    end
+  end
+end

data/lib/postscale/resources/dkim.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class DKIM < Resource
+      def generate(domain_id = nil, request = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.post("/v1/domains/#{encode(domain_id)}/dkim", json: request_hash(request, kwargs))
+      end
+
+      def list(domain_id = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/dkim")
+      end
+
+      def rotate(domain_id = nil, request = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.post("/v1/domains/#{encode(domain_id)}/dkim/rotate", json: request_hash(request, kwargs))
+      end
+
+      def deactivate(domain_id = nil, selector = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        selector = identifier(:selector, selector, kwargs)
+        @http.delete("/v1/domains/#{encode(domain_id)}/dkim/#{encode(selector)}")
+      end
+    end
+  end
+end

data/lib/postscale/resources/domains.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Domains < Resource
+      def create(request = nil, **kwargs)
+        @http.post("/v1/domains", json: request_hash(request, kwargs))
+      end
+
+      def list(params = nil, **kwargs)
+        @http.get("/v1/domains", params: params_hash(params, kwargs))
+      end
+
+      def get(id)
+        @http.get("/v1/domains/#{encode(id)}")
+      end
+
+      def update(id, request = nil, **kwargs)
+        @http.put("/v1/domains/#{encode(id)}", json: request_hash(request, kwargs))
+      end
+
+      def delete(id)
+        @http.delete("/v1/domains/#{encode(id)}")
+      end
+
+      def verify(id)
+        @http.post("/v1/domains/#{encode(id)}/verify")
+      end
+
+      def dns(id)
+        @http.get("/v1/domains/#{encode(id)}/dns")
+      end
+    end
+  end
+end

data/lib/postscale/resources/emails.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Emails < Resource
+      def send(request = nil, **kwargs)
+        body = request_hash(request, kwargs)
+        Attachments.validate(body["attachments"] || body[:attachments])
+        @http.post("/v1/send", json: body)
+      end
+
+      def send_batch(request = nil, **kwargs)
+        body = request.is_a?(Array) ? { "emails" => request } : request_hash(request, kwargs)
+        Array(body["emails"] || body[:emails]).each do |email|
+          Attachments.validate(email["attachments"] || email[:attachments])
+        end
+        @http.post("/v1/send/batch", json: body)
+      end
+      alias batch send_batch
+
+      def list(params = nil, **kwargs)
+        params = params_hash(params, kwargs)
+        @http.get("/v1/emails", params: params)
+      end
+
+      def get(id)
+        @http.get("/v1/emails/#{encode(id)}")
+      end
+
+      def list_events(id)
+        @http.get("/v1/emails/#{encode(id)}/events")
+      end
+      alias events list_events
+    end
+  end
+end

data/lib/postscale/resources/inbound.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Inbound < Resource
+      def list(params = nil, **kwargs)
+        @http.get("/v1/inbound-emails", params: params_hash(params, kwargs))
+      end
+
+      def get(id)
+        @http.get("/v1/inbound-emails/#{encode(id)}")
+      end
+
+      def download_attachment(email_id, attachment_id)
+        @http.get(
+          "/v1/inbound-emails/#{encode(email_id)}/attachments/#{encode(attachment_id)}/download",
+          parse_as: :bytes
+        )
+      end
+    end
+  end
+end

data/lib/postscale/resources/resource.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Resource
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      def encode(value)
+        URI.encode_www_form_component(value.to_s)
+      end
+
+      def request_hash(request = nil, kwargs = {})
+        data = {}
+        data.merge!(request) if request
+        data.merge!(kwargs) unless kwargs.empty?
+        data
+      end
+
+      def params_hash(params = nil, kwargs = {})
+        request_hash(params, kwargs)
+      end
+
+      def identifier(name, value, kwargs = {})
+        found = value || kwargs.delete(name)
+        raise ArgumentError, "#{name} is required" if found.nil? || found.to_s.empty?
+
+        found
+      end
+    end
+  end
+end

data/lib/postscale/resources/stats.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Stats < Resource
+      def aggregate(domain_id = nil, params = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/stats", params: params_hash(params, kwargs))
+      end
+      alias get aggregate
+
+      def daily(domain_id = nil, params = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/stats/daily", params: params_hash(params, kwargs))
+      end
+
+      def hourly(domain_id = nil, params = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/stats/hourly", params: params_hash(params, kwargs))
+      end
+
+      def isp(domain_id = nil, params = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/stats/isp", params: params_hash(params, kwargs))
+      end
+    end
+  end
+end

data/lib/postscale/resources/suppressions.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Suppressions < Resource
+      def list(params = nil, **kwargs)
+        @http.get("/v1/suppressions", params: params_hash(params, kwargs))
+      end
+
+      def add(request = nil, **kwargs)
+        @http.post("/v1/suppressions", json: request_hash(request, kwargs))
+      end
+
+      def check(email = nil, **kwargs)
+        params = email.is_a?(Hash) ? params_hash(email, kwargs) : params_hash({ email: email }, kwargs)
+        @http.get("/v1/suppressions/check", params: params)
+      end
+
+      def remove(identifier)
+        @http.delete("/v1/suppressions/#{encode(identifier)}")
+      end
+
+      def import_preview(request = nil, **kwargs)
+        @http.post("/v1/imports/suppressions/preview", json: request_hash(request, kwargs))
+      end
+
+      def import_job(id)
+        @http.get("/v1/imports/suppressions/jobs/#{encode(id)}")
+      end
+
+      def commit_import(id)
+        @http.post("/v1/imports/suppressions/jobs/#{encode(id)}/commit")
+      end
+    end
+  end
+end

data/lib/postscale/resources/templates.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Templates < Resource
+      def create(request = nil, **kwargs)
+        @http.post("/v1/templates", json: request_hash(request, kwargs))
+      end
+
+      def list(params = nil, **kwargs)
+        @http.get("/v1/templates", params: params_hash(params, kwargs))
+      end
+
+      def get(id)
+        @http.get("/v1/templates/#{encode(id)}")
+      end
+
+      def update(id, request = nil, **kwargs)
+        @http.put("/v1/templates/#{encode(id)}", json: request_hash(request, kwargs))
+      end
+
+      def delete(id)
+        @http.delete("/v1/templates/#{encode(id)}")
+      end
+
+      def preview(id, request = nil, **kwargs)
+        @http.post("/v1/templates/#{encode(id)}/preview", json: request_hash(request, kwargs))
+      end
+    end
+  end
+end

data/lib/postscale/resources/trust.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Trust < Resource
+      def get_review_request
+        @http.get("/v1/trust/review-request")
+      end
+
+      def create_review_request(request = nil, **kwargs)
+        @http.post("/v1/trust/review-request", json: request_hash(request, kwargs))
+      end
+    end
+  end
+end

data/lib/postscale/resources/usage.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Usage < Resource
+      def summary
+        @http.get("/v1/usage/summary")
+      end
+    end
+  end
+end

data/lib/postscale/resources/warming.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Warming < Resource
+      def get_status(domain_id = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/warming")
+      end
+      alias status get_status
+
+      def history(domain_id = nil, params = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.get("/v1/domains/#{encode(domain_id)}/warming/history", params: params_hash(params, kwargs))
+      end
+
+      def start(domain_id = nil, request = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.post("/v1/domains/#{encode(domain_id)}/warming/start", json: request_hash(request, kwargs))
+      end
+
+      def pause(domain_id = nil, request = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.post("/v1/domains/#{encode(domain_id)}/warming/pause", json: request_hash(request, kwargs))
+      end
+
+      def resume(domain_id = nil, **kwargs)
+        domain_id = identifier(:domain_id, domain_id, kwargs)
+        @http.post("/v1/domains/#{encode(domain_id)}/warming/resume")
+      end
+    end
+  end
+end

data/lib/postscale/resources/webhooks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Postscale
+  module Resources
+    class Webhooks < Resource
+      def create(request = nil, **kwargs)
+        @http.post("/v1/webhooks", json: request_hash(request, kwargs))
+      end
+
+      def list(params = nil, **kwargs)
+        @http.get("/v1/webhooks", params: params_hash(params, kwargs))
+      end
+
+      def delete(id)
+        @http.delete("/v1/webhooks/#{encode(id)}")
+      end
+
+      def deliveries(params = nil, **kwargs)
+        @http.get("/v1/webhook-deliveries", params: params_hash(params, kwargs))
+      end
+
+      def endpoint_deliveries(id, params = nil, **kwargs)
+        @http.get("/v1/webhooks/#{encode(id)}/deliveries", params: params_hash(params, kwargs))
+      end
+
+      def rotate_secret(id, request = nil, **kwargs)
+        @http.post("/v1/webhooks/#{encode(id)}/rotate", json: request_hash(request, kwargs))
+      end
+
+      def verify_signature(body, signature_header, secrets, **options)
+        Webhook.verify_signature(body, signature_header, secrets, **options)
+      end
+    end
+  end
+end