unitpost 0.0.0 → 0.1.0

data/lib/unitpost/http_client.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require_relative "errors"
+require_relative "generated/operations"
+
+module Unitpost
+  # HTTP transport — the one place that talks to the Unitpost API.
+  #
+  # Hand-written (not generated): auth, the required User-Agent, idempotency,
+  # query building, JSON encode/decode, and turning a non-2xx response into a
+  # typed Unitpost::Error. Resource methods (resources.rb) call through here.
+  class HttpClient
+    SDK_VERSION = Unitpost::VERSION
+    # The live API host. Matches the OpenAPI servers[].url and the app's own
+    # brand.ts FALLBACK_APP_ORIGIN. SINGLE HOST: the API lives on the same origin
+    # as the app (www.unitpost.com) under /api/v1 — no api. subdomain. Override
+    # per-client with base_url / UNITPOST_BASE_URL.
+    DEFAULT_BASE_URL = "https://www.unitpost.com"
+
+    def initialize(api_key: nil, base_url: nil, timeout: 30, headers: {}, adapter: nil, stubs: nil,
+                   max_retries: 2, retry_base_delay: 0.5, max_retry_delay: 20.0, sleeper: nil)
+      key = api_key || ENV.fetch("UNITPOST_API_KEY", nil)
+      if key.nil? || key.empty?
+        raise Unitpost::Error.new(
+          code: "missing_api_key",
+          message: "No API key provided. Pass Unitpost::Client.new(api_key:) or set the UNITPOST_API_KEY environment variable. Create a key at https://www.unitpost.com → Settings → API keys. Full reference: https://www.unitpost.com/docs",
+          status: 0
+        )
+      end
+      @api_key = key
+      base = (base_url || ENV["UNITPOST_BASE_URL"] || DEFAULT_BASE_URL).sub(%r{/\z}, "")
+      @prefix = "/api/#{Unitpost::Generated::API_VERSION}"
+      @extra_headers = headers
+      # Automatic retry policy for transient failures (429, 5xx, timeouts,
+      # network errors). max_retries: 0 disables it. See SECURITY.md §6.
+      @max_retries = [max_retries, 0].max
+      @retry_base_delay = retry_base_delay
+      @max_retry_delay = max_retry_delay
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+
+      @conn = Faraday.new(url: base) do |f|
+        f.options.timeout = timeout
+        if stubs
+          f.adapter(:test, stubs)
+        else
+          f.adapter(adapter || Faraday.default_adapter)
+        end
+      end
+    end
+
+    # Make a request, retrying transient failures (429, 5xx, timeouts, network
+    # errors) with backoff. A 429/503 Retry-After is honored (clamped to
+    # max_retry_delay); otherwise exponential backoff with full jitter. 4xx
+    # (other than 429) is never retried. A request is only retried when it's safe
+    # to replay: a GET, or a write carrying an Idempotency-Key (deduped
+    # server-side). A keyless write is never auto-retried, so a lost response
+    # can't double-send.
+    def request(http_method, path, query: nil, body: nil, idempotency_key: nil)
+      retry_safe = http_method == "GET" || !idempotency_key.nil?
+      attempt = 0
+      loop do
+        result, retry_after = attempt_request(
+          http_method, path, query: query, body: body, idempotency_key: idempotency_key
+        )
+        err = result.error
+        retryable = !err.nil? && (err.status.zero? || retryable_status?(err.status))
+        return result if err.nil? || !retryable || !retry_safe || attempt >= @max_retries
+
+        @sleeper.call(backoff_delay(attempt, retry_after))
+        attempt += 1
+      end
+    end
+
+    private
+
+    def retryable_status?(status)
+      status == 429 || (status >= 500 && status <= 599)
+    end
+
+    def backoff_delay(attempt, retry_after)
+      return [retry_after, @max_retry_delay].min unless retry_after.nil?
+
+      ceiling = [@retry_base_delay * (2**attempt), @max_retry_delay].min
+      rand * ceiling
+    end
+
+    # Parse a Retry-After header (delta-seconds or HTTP-date) into seconds.
+    def parse_retry_after(value)
+      return nil if value.nil? || value.to_s.empty?
+
+      stripped = value.to_s.strip
+      return [stripped.to_f, 0.0].max if stripped.match?(/\A\d+(\.\d+)?\z/)
+
+      begin
+        delta = Time.httpdate(stripped).to_f - Time.now.to_f
+        [delta, 0.0].max
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def attempt_request(http_method, path, query: nil, body: nil, idempotency_key: nil)
+      headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "User-Agent" => "unitpost-ruby/#{SDK_VERSION}",
+        "Accept" => "application/json"
+      }.merge(@extra_headers)
+      headers["Idempotency-Key"] = idempotency_key if idempotency_key
+
+      params = (query || {}).reject { |_, v| v.nil? }
+
+      begin
+        response = @conn.run_request(http_method.downcase.to_sym, "#{@prefix}#{path}", nil, headers) do |req|
+          req.params.update(params) unless params.empty?
+          if body && http_method != "GET"
+            req.headers["Content-Type"] = "application/json"
+            req.body = JSON.generate(body)
+          end
+        end
+      rescue Faraday::TimeoutError
+        return [Result.new(error: Unitpost::Error.new(code: "timeout", message: "Request timed out.", status: 0)), nil]
+      rescue Faraday::Error => e
+        return [Result.new(error: Unitpost::Error.new(code: "network_error", message: e.message, status: 0)), nil]
+      end
+
+      request_id = response.headers["x-request-id"]
+      parsed = parse_body(response.body)
+
+      unless (200..299).cover?(response.status)
+        err = parsed.is_a?(Hash) ? (parsed["error"] || {}) : {}
+        details = err["details"].is_a?(Array) ? err["details"] : nil
+        return [
+          Result.new(
+            error: Unitpost::Error.new(
+              code: err["code"] || "http_error",
+              message: err["message"] || "Request failed with status #{response.status}.",
+              status: response.status,
+              request_id: request_id,
+              details: details
+            )
+          ),
+          parse_retry_after(response.headers["retry-after"])
+        ]
+      end
+
+      [Result.new(data: parsed), nil]
+    end
+
+    def parse_body(raw)
+      return nil if raw.nil? || raw.to_s.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/unitpost/resources.rb

@@ -0,0 +1,464 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "securerandom"
+
+module Unitpost
+  # Resource surface — the hand-written, ergonomic layer (our own style).
+  #
+  # Each resource is a small class with explicit methods mirroring the Node and
+  # Python SDKs (emails.send, contacts.list/create/get/update/delete, ...). The
+  # codegen "surface coverage" check fails CI if a spec operation has no method
+  # here. Every method returns a Unitpost::Result and never raises for an API
+  # error. Bodies/params are plain Hashes.
+  module Resources
+    class Base
+      def initialize(http)
+        @http = http
+      end
+
+      private
+
+      def enc(segment)
+        CGI.escape(segment.to_s)
+      end
+
+      def list_params(limit:, after:, before:, **extra)
+        { limit: limit, after: after, before: before }.merge(extra)
+      end
+
+      def paginate(path, params)
+        Enumerator.new do |yielder|
+          after = params[:after]
+          loop do
+            page_params = params.merge(after: after)
+            result = @http.request("GET", path, query: page_params)
+            raise result.error if result.error
+
+            page = result.data || {}
+            rows = page["data"] || []
+            rows.each { |row| yielder << row }
+            break if !page["has_more"] || rows.empty?
+
+            after = rows.last["id"]
+          end
+        end
+      end
+    end
+
+    class Emails < Base
+      # Send or schedule a transactional email. When no idempotency_key is
+      # given the SDK generates one so a transient retry can't double-send; pass
+      # your own to dedupe across separate send calls.
+      def send(body, idempotency_key: nil)
+        @http.request("POST", "/emails", body: body, idempotency_key: idempotency_key || SecureRandom.uuid)
+      end
+
+      # Send up to 100 emails in one request (all-or-nothing validation). Like
+      # +send+, when no idempotency_key is given the SDK generates one so a
+      # transient retry is safe: the server dedupes the batch on the key and
+      # replays the original result instead of re-sending. Pass your own to
+      # dedupe across separate batch calls.
+      def batch(body, idempotency_key: nil)
+        @http.request("POST", "/emails/batch", body: body, idempotency_key: idempotency_key || SecureRandom.uuid)
+      end
+
+      def get_batch(id)
+        @http.request("GET", "/emails/batches/#{enc(id)}")
+      end
+
+      def cancel_batch(id)
+        @http.request("POST", "/emails/batches/#{enc(id)}/cancel")
+      end
+
+      def list(limit: nil, after: nil, before: nil, **filters)
+        @http.request("GET", "/emails", query: list_params(limit: limit, after: after, before: before, **filters))
+      end
+
+      def list_all(**params)
+        paginate("/emails", params)
+      end
+
+      def get(id)
+        @http.request("GET", "/emails/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/emails/#{enc(id)}", body: body)
+      end
+
+      # Deliverability/engagement aggregates over a rolling window (days: 1–365,
+      # defaults to 30 server-side).
+      def stats(days: nil)
+        @http.request("GET", "/emails/stats", query: { days: days })
+      end
+
+      def received_list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/emails/received", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def received_get(id)
+        @http.request("GET", "/emails/received/#{enc(id)}")
+      end
+
+      def received_attachment_url(id, attachment_id)
+        @http.request("GET", "/emails/received/#{enc(id)}/attachments/#{enc(attachment_id)}")
+      end
+    end
+
+    class Contacts < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/contacts", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/contacts", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/contacts", body: body)
+      end
+
+      def get(id_or_email)
+        @http.request("GET", "/contacts/#{enc(id_or_email)}")
+      end
+
+      def update(id_or_email, body)
+        @http.request("PATCH", "/contacts/#{enc(id_or_email)}", body: body)
+      end
+
+      def delete(id_or_email)
+        @http.request("DELETE", "/contacts/#{enc(id_or_email)}")
+      end
+
+      def import(body)
+        @http.request("POST", "/contacts/imports", body: body)
+      end
+
+      def list_imports(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/contacts/imports", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def get_import(id)
+        @http.request("GET", "/contacts/imports/#{enc(id)}")
+      end
+    end
+
+    class ContactFields < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/contact-fields", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/contact-fields", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/contact-fields", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/contact-fields/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/contact-fields/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/contact-fields/#{enc(id)}")
+      end
+
+      def rename(id, body)
+        @http.request("POST", "/contact-fields/#{enc(id)}/rename", body: body)
+      end
+    end
+
+    class Segments < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/segments", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/segments", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/segments", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/segments/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/segments/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/segments/#{enc(id)}")
+      end
+
+      def list_members(id, limit: nil, after: nil, before: nil)
+        @http.request("GET", "/segments/#{enc(id)}/contacts", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def add_member(id, body)
+        @http.request("POST", "/segments/#{enc(id)}/contacts", body: body)
+      end
+
+      def remove_member(id, contact)
+        @http.request("DELETE", "/segments/#{enc(id)}/contacts/#{enc(contact)}")
+      end
+    end
+
+    class Topics < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/topics", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/topics", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/topics", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/topics/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/topics/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/topics/#{enc(id)}")
+      end
+
+      def list_topics(contact_id, limit: nil, after: nil, before: nil)
+        @http.request("GET", "/contacts/#{enc(contact_id)}/topics", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def set_topic(contact_id, body)
+        @http.request("POST", "/contacts/#{enc(contact_id)}/topics", body: body)
+      end
+    end
+
+    class Campaigns < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/campaigns", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/campaigns", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/campaigns", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/campaigns/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/campaigns/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/campaigns/#{enc(id)}")
+      end
+
+      def send(id)
+        @http.request("POST", "/campaigns/#{enc(id)}/send")
+      end
+
+      def cancel(id)
+        @http.request("POST", "/campaigns/#{enc(id)}/cancel")
+      end
+
+      def pause(id)
+        @http.request("POST", "/campaigns/#{enc(id)}/pause")
+      end
+
+      def resume(id)
+        @http.request("POST", "/campaigns/#{enc(id)}/resume")
+      end
+
+      def reschedule(id, body)
+        @http.request("POST", "/campaigns/#{enc(id)}/reschedule", body: body)
+      end
+
+      def validate(id)
+        @http.request("GET", "/campaigns/#{enc(id)}/validate")
+      end
+    end
+
+    class Templates < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/templates", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/templates", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/templates", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/templates/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/templates/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/templates/#{enc(id)}")
+      end
+    end
+
+    # Read-only Brand Kit profiles (voice, colors, pinned /img/{id} graphics).
+    class BrandKits < Base
+      def list(name: nil)
+        query = {}
+        query[:name] = name unless name.nil?
+        @http.request("GET", "/brand-kits", query: query.empty? ? nil : query)
+      end
+
+      def get(id)
+        @http.request("GET", "/brand-kits/#{enc(id)}")
+      end
+    end
+
+    class Domains < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/domains", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/domains", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/domains", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/domains/#{enc(id)}")
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/domains/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/domains/#{enc(id)}", body: body)
+      end
+
+      def verify(id)
+        @http.request("POST", "/domains/#{enc(id)}/verify")
+      end
+    end
+
+    class Webhooks < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/webhooks", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/webhooks", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/webhooks", body: body)
+      end
+
+      def get(id)
+        @http.request("GET", "/webhooks/#{enc(id)}")
+      end
+
+      def update(id, body)
+        @http.request("PATCH", "/webhooks/#{enc(id)}", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/webhooks/#{enc(id)}")
+      end
+
+      def test(id)
+        @http.request("POST", "/webhooks/#{enc(id)}/test")
+      end
+
+      # Verify a delivery's signature and return the parsed event. Alias of
+      # Unitpost.verify_webhook / Unitpost::Webhooks.verify for a Resend-style
+      # client.webhooks.verify(...). Raises Unitpost::WebhookVerificationError on
+      # a missing/invalid/stale signature.
+      def verify(payload:, secret:, headers:, tolerance_seconds: 300)
+        Unitpost::Webhooks.verify(
+          payload: payload,
+          secret: secret,
+          headers: headers,
+          tolerance_seconds: tolerance_seconds,
+        )
+      end
+    end
+
+    class ApiKeys < Base
+      def list(limit: nil, after: nil, before: nil)
+        @http.request("GET", "/api-keys", query: list_params(limit: limit, after: after, before: before))
+      end
+
+      def list_all(**params)
+        paginate("/api-keys", params)
+      end
+
+      def create(body)
+        @http.request("POST", "/api-keys", body: body)
+      end
+
+      def delete(id)
+        @http.request("DELETE", "/api-keys/#{enc(id)}")
+      end
+    end
+
+    class Suppressions < Base
+      def list(limit: nil, after: nil, before: nil, **filters)
+        @http.request("GET", "/suppressions", query: list_params(limit: limit, after: after, before: before, **filters))
+      end
+
+      def list_all(**params)
+        paginate("/suppressions", params)
+      end
+
+      # Single (`{ email: ... }`) or bulk (`{ emails: [...] }`). Idempotent.
+      def create(body)
+        @http.request("POST", "/suppressions", body: body)
+      end
+
+      def get(id_or_email)
+        @http.request("GET", "/suppressions/#{enc(id_or_email)}")
+      end
+
+      def delete(id_or_email)
+        @http.request("DELETE", "/suppressions/#{enc(id_or_email)}")
+      end
+    end
+
+    # NOTE (pre-launch): the Events resource (POST /v1/events) is intentionally
+    # absent while the automations/custom-events surface is behind the launch
+    # gate. Restore it (class Events + client wiring) when the surface ships.
+
+    class Usage < Base
+      # Current billing-period snapshot: plan, period window, emails sent, and
+      # (paid plans) the dollar sending wallet in integer USD cents.
+      def get
+        @http.request("GET", "/usage")
+      end
+    end
+  end
+end

data/lib/unitpost/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Unitpost
-  VERSION = "0.0.0"
+  VERSION = "0.1.0"
 end

data/lib/unitpost/webhooks.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+require "json"
+require_relative "errors"
+
+module Unitpost
+  # Webhook signature verification (svix-compatible). Mirrors the engine signer:
+  #   signed content: "<svix-id>.<svix-timestamp>.<raw-body>"
+  #   signature:      base64( HMAC_SHA256(secret_bytes, signed_content) )
+  #   header:         svix-signature = "v1,<base64>" (space-separated list allowed)
+  #   secret:         "whsec_<base64url>" — bytes after the prefix are the key.
+  #
+  # Verify the RAW request body string (not a re-serialized hash).
+  module Webhooks
+    SECRET_PREFIX = "whsec_"
+
+    module_function
+
+    def verify(payload:, secret:, headers:, tolerance_seconds: 300)
+      msg_id = header(headers, "svix-id")
+      timestamp = header(headers, "svix-timestamp")
+      signature = header(headers, "svix-signature")
+
+      if msg_id.nil? || timestamp.nil? || signature.nil?
+        raise WebhookVerificationError, "Missing svix-id, svix-timestamp, or svix-signature header."
+      end
+
+      ts = Integer(timestamp, exception: false)
+      raise WebhookVerificationError, "Invalid svix-timestamp header." if ts.nil?
+
+      now = Time.now.to_i
+      if (now - ts).abs > tolerance_seconds
+        raise WebhookVerificationError, "Webhook timestamp is outside the tolerance window (possible replay)."
+      end
+
+      signed_content = "#{msg_id}.#{ts}.#{payload}"
+      expected = Base64.strict_encode64(
+        OpenSSL::HMAC.digest("SHA256", secret_key_bytes(secret), signed_content)
+      )
+
+      matched = signature.split(" ").any? do |part|
+        _, sig = part.split(",", 2)
+        sig && secure_compare(sig, expected)
+      end
+      raise WebhookVerificationError, "Webhook signature verification failed." unless matched
+
+      begin
+        JSON.parse(payload)
+      rescue JSON::ParserError
+        raise WebhookVerificationError, "Webhook payload is not valid JSON."
+      end
+    end
+
+    def header(headers, name)
+      headers[name] || headers[name.downcase] || headers[name.split("-").map(&:capitalize).join("-")]
+    end
+
+    def secret_key_bytes(secret)
+      raw = secret.start_with?(SECRET_PREFIX) ? secret[SECRET_PREFIX.length..] : secret
+      Base64.urlsafe_decode64(raw + ("=" * ((4 - (raw.length % 4)) % 4)))
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    rescue StandardError
+      # Fallback for older OpenSSL without fixed_length_secure_compare.
+      res = 0
+      a.bytes.zip(b.bytes) { |x, y| res |= x ^ y }
+      res.zero?
+    end
+  end
+end