flodesk 0.1.0

data/lib/flodesk/connection.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module Flodesk
+  # Executes HTTP requests against the Flodesk API.
+  #
+  # A Connection holds no per-request mutable state, so one instance is safe to
+  # share across threads. Each request opens its own `Net::HTTP` session rather
+  # than reusing a socket: simple, and correct under concurrency. Connection
+  # pooling is a possible later optimization, not a v1 requirement.
+  class Connection
+    # Exceptions Net::HTTP raises when a request never completed.
+    TIMEOUT_ERRORS = [Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout].freeze
+
+    CONNECTION_ERRORS = [
+      EOFError, Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH,
+      Errno::ENETUNREACH, IOError, SocketError
+    ].freeze
+
+    def initialize(client)
+      @client = client
+      freeze
+    end
+
+    # Issues a request and returns a Response, retrying per the retry policy.
+    #
+    # `idempotent` declares whether repeating this operation is safe.
+    #
+    # For POST it must be stated explicitly and defaults to false, because in
+    # this API retry safety is a property of the endpoint rather than the verb:
+    # POST /subscribers and POST /subscribers/batch are upserts and safe to
+    # repeat, while POST /segments, POST /custom-fields, POST /webhooks and
+    # POST /campaigns/canva all create, so repeating them duplicates a record or
+    # sends a campaign twice. Assuming POST is retryable is the single most
+    # damaging mistake a client of this API can make.
+    #
+    # GET, PUT and DELETE are idempotent by HTTP definition and default to true.
+    def request(method, path, query: nil, body: nil, idempotent: nil, retry_rate_limit: true)
+      policy = RetryPolicy.new(
+        idempotent: idempotent.nil? ? method != :post : idempotent,
+        retry_rate_limit: retry_rate_limit,
+        max_retries: @client.max_retries
+      )
+      attempt = 0
+
+      loop do
+        attempt += 1
+        error = attempt_once(method, path, query, body, attempt) { |response| return response }
+
+        raise error unless policy.retry?(error, attempt)
+
+        backoff(attempt)
+      end
+    end
+
+    private
+
+    # Yields the response to the caller's block on success. Returns the error to
+    # weigh for retry on failure, rather than raising, so the retry decision is
+    # made in one place.
+    def attempt_once(method, path, query, body, attempt)
+      response = execute(method, path, query, body, attempt)
+      if response.status < 400
+        yield response
+        return nil
+      end
+
+      Error.from_response(
+        status: response.status, body: response.body, headers: response.headers
+      )
+    rescue *TIMEOUT_ERRORS => e
+      TimeoutError.new("#{method.to_s.upcase} #{Redaction.path(path)} timed out (#{e.class})")
+    rescue *CONNECTION_ERRORS => e
+      ConnectionError.new("#{method.to_s.upcase} #{Redaction.path(path)} failed (#{e.class})")
+    end
+
+    def execute(method, path, query, body, attempt)
+      uri = build_uri(path, query)
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      raw = http_for(uri).request(build_request(method, uri, body))
+      response = to_response(raw)
+
+      Instrumentation.request(
+        method: method,
+        path: path,
+        status: response.status,
+        duration: Process.clock_gettime(Process::CLOCK_MONOTONIC) - started,
+        attempt: attempt,
+        rate_limit_remaining: response.rate_limit_remaining
+      )
+      RateLimit.record(@client, response)
+      response
+    end
+
+    def build_uri(path, query)
+      uri = URI.parse("#{@client.base_url}#{path}")
+      uri.query = URI.encode_www_form(query) if query && !query.empty?
+      uri
+    end
+
+    def build_request(method, uri, body)
+      request = Net::HTTP.const_get(method.to_s.capitalize).new(uri)
+
+      request["Accept"] = "application/json"
+      request["User-Agent"] = @client.user_agent
+      @client.auth.apply(request)
+
+      if body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+
+      request
+    end
+
+    def http_for(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @client.open_timeout
+      http.read_timeout = @client.read_timeout
+      http
+    end
+
+    def to_response(raw)
+      status = raw.code.to_i
+
+      Response.new(
+        status: status,
+        headers: raw.each_header.to_h { |k, v| [k.to_s.downcase, v] },
+        body: parse_body(raw, status)
+      )
+    end
+
+    # 204 responses carry no body, and several endpoints use them; parsing one
+    # as JSON would raise on an empty string.
+    def parse_body(raw, status)
+      return nil if status == 204
+
+      text = raw.body
+      return nil if text.nil? || text.strip.empty?
+
+      begin
+        JSON.parse(text)
+      rescue JSON::ParserError
+        # A 2xx that is not parseable is a genuine failure. An error response
+        # with an HTML body (from an edge proxy, say) must still become a typed
+        # error, so hand the raw text through for the error to carry.
+        raise Error, "Malformed JSON in #{status} response" if status < 400
+
+        text
+      end
+    end
+
+    def backoff(attempt)
+      delay = backoff_delay(attempt)
+      sleep(delay) if delay
+    end
+
+    # Exponential backoff with jitter, capped at the rate-limit window length.
+    #
+    # Flodesk sends no rate-limit reset header, so no correct wait is
+    # computable; this is a documented heuristic. Returns nil when backoff is
+    # disabled. Kept pure and separate from the sleep so it can be asserted
+    # directly without a timing-dependent test.
+    def backoff_delay(attempt)
+      base = @client.backoff_base
+      return nil if base.nil? || base.zero?
+
+      capped = [base * (2**(attempt - 1)), MAX_BACKOFF_SECONDS].min
+      # Jitter over the lower half, so concurrent callers desynchronize instead
+      # of retrying in lockstep.
+      capped * (0.5 + (Kernel.rand * 0.5))
+    end
+  end
+end

data/lib/flodesk/enums.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Closed enumerations documented by the API description.
+  #
+  # These live in one namespace rather than on the individual value objects for
+  # two reasons. Constants assigned inside a `Data.define do ... end` block bind
+  # to the *enclosing lexical scope*, not to the resulting class — so a
+  # `STATUSES` written inside two such blocks silently defines and then clobbers
+  # a single `Flodesk::STATUSES`. Collecting them here also gives the contract
+  # spec one place to verify against `openapi.json`.
+  module Enums
+    # `SubscriberRes.status`. `bounced`, `complained` and `cleaned` are terminal
+    # delivery states rather than subscriber actions; `archived` is an action
+    # the account owner took on the record.
+    #
+    # Order is significant: the contract spec compares this against the
+    # specification's enum array for equality, not as a set.
+    SUBSCRIBER_STATUSES = %w[
+      active unsubscribed unconfirmed bounced complained cleaned archived
+    ].freeze
+
+    # `SubscriberRes.source`.
+    SUBSCRIBER_SOURCES = %w[manual csv form_optin integration checkout].freeze
+
+    # The `statuses` filter on `GET /workflows`. Note that the workflow response
+    # schema exposes no status field, so these are only ever sent, never parsed.
+    WORKFLOW_STATUSES = %w[active paused draft].freeze
+
+    # `CampaignItem.status`, also accepted as the `Status` list filter.
+    CAMPAIGN_STATUSES = %w[
+      draft pending scheduled composing sending done failed
+    ].freeze
+
+    # The only events Flodesk can deliver to a webhook.
+    WEBHOOK_EVENTS = %w[
+      subscriber.created
+      subscriber.added_to_segment
+      subscriber.unsubscribed
+    ].freeze
+  end
+end

data/lib/flodesk/errors.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Base class for everything this gem raises. Rescue this to catch any Flodesk
+  # failure, including transport-level ones.
+  class Error < StandardError
+    # Maps an HTTP response to the appropriate error instance.
+    #
+    # The Flodesk OpenAPI description declares *no* schema for any error
+    # response — every 4xx documents only an empty description. The
+    # `{"code": ..., "message": ...}` envelope parsed here was established by
+    # probing the live API, so it is not contract-verifiable and must never be
+    # assumed present. An unexpected body degrades to a status-derived message
+    # rather than raising while building the error.
+    def self.from_response(status:, body: nil, headers: {})
+      klass_for(status).new(status: status, body: body, headers: headers)
+    end
+
+    def self.klass_for(status)
+      case status
+      when 400 then BadRequestError
+      when 401, 403 then AuthenticationError
+      when 404 then NotFoundError
+      when 429 then RateLimitError
+      when 500..599 then ServerError
+      else APIError
+      end
+    end
+    private_class_method :klass_for
+  end
+
+  # Raised when Flodesk returns an HTTP error response, as opposed to the
+  # request failing before a response was received.
+  class APIError < Error
+    # The HTTP status code of the response.
+    attr_reader :status
+
+    # The `code` field from the error envelope, or nil when absent.
+    attr_reader :code
+
+    # The response body exactly as parsed, for debugging unexpected shapes.
+    attr_reader :raw_body
+
+    def initialize(status:, body: nil, headers: {})
+      @status = status
+      @raw_body = body
+      @headers = normalize_headers(headers)
+      @code = extract(body, "code")
+
+      super(extract(body, "message") || "HTTP #{status}")
+    end
+
+    # Value of `X-Fd-RateLimit-Limit`, or nil when the header was absent.
+    def rate_limit
+      integer_header("x-fd-ratelimit-limit")
+    end
+
+    # Value of `X-Fd-RateLimit-Remaining`, or nil when the header was absent.
+    def rate_limit_remaining
+      integer_header("x-fd-ratelimit-remaining")
+    end
+
+    private
+
+    # Reads a field from the envelope, tolerating any body shape. A body may be
+    # a parsed Hash, an HTML string from an edge proxy, or nil.
+    def extract(body, key)
+      return nil unless body.is_a?(Hash)
+
+      value = body[key] || body[key.to_sym]
+      value.is_a?(String) && !value.empty? ? value : nil
+    end
+
+    def normalize_headers(headers)
+      return {} unless headers.respond_to?(:each_pair)
+
+      headers.each_pair.to_h { |k, v| [k.to_s.downcase, v] }
+    end
+
+    def integer_header(name)
+      value = @headers[name]
+      value = value.first if value.is_a?(Array)
+      return nil if value.nil? || value.to_s.empty?
+
+      Integer(value, exception: false)
+    end
+  end
+
+  # 400 — the request payload was rejected. Never retried: the same payload
+  # cannot succeed on a second attempt.
+  class BadRequestError < APIError; end
+
+  # 401 or 403 — the API key was missing, malformed, or not accepted.
+  class AuthenticationError < APIError; end
+
+  # 404 — the addressed resource does not exist.
+  class NotFoundError < APIError; end
+
+  # 5xx — Flodesk failed to process an otherwise valid request.
+  class ServerError < APIError; end
+
+  # 429 — the rate limit was exceeded.
+  #
+  # Flodesk returns `X-Fd-RateLimit-Limit` and `X-Fd-RateLimit-Remaining` but
+  # *no reset header*, so there is no way to compute when the window reopens.
+  # `retry_after` therefore always returns nil, and any backoff this gem applies
+  # is a documented heuristic rather than a computed wait.
+  class RateLimitError < APIError
+    # Always nil: the API exposes no reset time. Present so callers can ask
+    # without special-casing, and to document the absence explicitly.
+    def retry_after
+      nil
+    end
+  end
+
+  # The request failed before a response was received.
+  class ConnectionError < Error; end
+
+  # The request exceeded a configured connect or read timeout.
+  #
+  # For non-idempotent operations a timeout is genuinely ambiguous: the write
+  # may have been applied. Such operations are never retried.
+  class TimeoutError < Error; end
+
+  # Raised when a batch operation returns 200 while reporting per-record
+  # failures. Carries the complete result, so records that succeeded remain
+  # available to the caller and no work is lost by raising.
+  class PartialFailureError < Error
+    # The BatchResult describing both successes and failures.
+    attr_reader :result
+
+    def initialize(result:)
+      @result = result
+
+      super("#{result.failures.size} of " \
+            "#{result.failures.size + result.successes.size} records failed")
+    end
+  end
+end

data/lib/flodesk/instrumentation.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Emits `flodesk.request` notifications when ActiveSupport is available.
+  #
+  # One event is emitted per *attempt*, not per logical call, so retries are
+  # visible in whatever collects them. Payloads carry no PII: no request body, no
+  # response body, no API key, and any email embedded in a path is redacted.
+  module Instrumentation
+    EVENT_NAME = "flodesk.request"
+
+    module_function
+
+    # True when ActiveSupport::Notifications can be published to. Checked per
+    # call rather than cached, since a host application may load ActiveSupport
+    # after this gem.
+    def available?
+      defined?(ActiveSupport::Notifications) ? true : false
+    end
+
+    def request(method:, path:, status:, duration:, attempt:, rate_limit_remaining:)
+      return unless available?
+
+      ActiveSupport::Notifications.instrument(
+        EVENT_NAME,
+        method: method.to_s.upcase,
+        endpoint: Redaction.path(path),
+        status: status,
+        duration: duration,
+        attempt: attempt,
+        rate_limit_remaining: rate_limit_remaining
+      )
+    end
+  end
+end

data/lib/flodesk/objects/batch_item_error.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A single record's failure within a batch operation.
+  #
+  # `index` is the zero-based position in the submitted array, which is what
+  # makes a failure actionable: it identifies which of your inputs was rejected
+  # even when neither `id` nor `email` came back.
+  BatchItemError = Data.define(:index, :email, :id, :code, :message, :raw) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(
+        index: payload["index"],
+        email: payload["email"],
+        id: payload["id"],
+        code: payload["code"],
+        message: payload["message"],
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end

data/lib/flodesk/objects/batch_result.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # The outcome of a batch operation.
+  #
+  # `POST /subscribers/batch` is the only endpoint in this API where success and
+  # failure arrive in the *same* 200 response. A client that treats 2xx as
+  # success silently drops subscribers, which is why this is a first-class object
+  # with an explicit {#success?} rather than a bare hash, and why
+  # `batch_upsert` raises {PartialFailureError} unless told not to.
+  BatchResult = Data.define(:successes, :failures, :raw) do
+    def self.from(payload)
+      payload ||= {}
+
+      new(
+        successes: Coercion.array_of(Subscriber, payload["successes"]),
+        failures: Coercion.array_of(BatchItemError, payload["failures"]),
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # True when every submitted record was accepted.
+    def success?
+      failures.empty?
+    end
+
+    # Total records accounted for in the response.
+    def size
+      successes.size + failures.size
+    end
+
+    # Emails of the records that failed, for assembling a retry batch. Failures
+    # that carry no email — matched by id — are omitted.
+    def failed_emails
+      failures.filter_map(&:email)
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end

data/lib/flodesk/objects/campaign.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # An email campaign.
+  Campaign = Data.define(:id, :name, :subject, :status, :created_at, :updated_at, :raw) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        name: payload["name"],
+        subject: payload["subject"],
+        # Coerced to a symbol like the subscriber enums, despite the list
+        # endpoint spelling its filter parameter `Status`.
+        status: Coercion.enum(payload["status"], Enums::CAMPAIGN_STATUSES),
+        created_at: Coercion.time(payload["created_at"]),
+        updated_at: Coercion.time(payload["updated_at"]),
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end

data/lib/flodesk/objects/custom_field.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A custom field definition.
+  #
+  # The API identifies custom fields by `key`, not by an id. Values stored
+  # against a field are always strings.
+  CustomField = Data.define(:key, :label, :raw) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(key: payload["key"], label: payload["label"], raw: Coercion.snapshot(payload))
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end

data/lib/flodesk/objects/page.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # One page of a list response.
+  #
+  # Holds the items plus the `meta` block the API returns. A Page never fetches
+  # anything by itself: `list` issues exactly one request, and traversing
+  # further pages is the explicit opt-in of `auto_paging_each`. Walking a large
+  # collection can consume the whole 100-requests-per-minute budget, and that
+  # cost should be visible at the call site rather than hidden behind `each`.
+  Page = Data.define(
+    :items, :page, :per_page, :total_pages, :total_items, :raw, :fetcher
+  ) do
+    include Enumerable
+
+    # `fetcher` is a callable taking a page number and returning the next Page.
+    # It is supplied by the resource that built this Page, and is what
+    # `auto_paging_each` walks.
+    def self.from(payload, klass:, fetcher: nil)
+      payload ||= {}
+      meta = payload["meta"] || {}
+
+      new(
+        items: Coercion.array_of(klass, payload["data"]),
+        page: meta["page"],
+        per_page: meta["per_page"],
+        total_pages: meta["total_pages"],
+        total_items: meta["total_items"],
+        raw: Coercion.snapshot(payload),
+        fetcher: fetcher
+      )
+    end
+
+    def each(&)
+      items.each(&)
+    end
+
+    def empty?
+      items.empty?
+    end
+
+    # True when the metadata shows a page after this one. False when metadata is
+    # absent, since nothing then indicates another page exists.
+    def more_pages?
+      return false if page.nil? || total_pages.nil?
+
+      page < total_pages
+    end
+
+    # The payload exactly as the API sent it.
+    def to_h
+      raw
+    end
+
+    # Walks this page and every page after it, fetching each on demand.
+    #
+    # Returns a lazy Enumerator, so `.first(5)` fetches only what it needs
+    # instead of the whole collection. Deliberately not the behavior of `each`.
+    def auto_paging_each(&block)
+      return to_enum(:auto_paging_each) unless block_given?
+
+      current = self
+      loop do
+        current.items.each(&block)
+        break unless current.more_pages? && current.fetcher
+
+        current = current.fetcher.call(current.page + 1)
+        break if current.nil?
+      end
+    end
+  end
+end

data/lib/flodesk/objects/segment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A segment.
+  #
+  # Covers both `SegmentRes` and the smaller `SegmentMini` the API nests inside
+  # subscriber payloads: fields absent from the narrower shape simply read nil.
+  #
+  # `segment_type` is `"static"` or `"dynamic"`. It is deliberately not coerced
+  # to a Symbol: the specification documents those two values in prose only and
+  # declares no enum array, so there is nothing to validate against and
+  # inventing a closed set here would be a guess.
+  Segment = Data.define(
+    :id, :name, :color, :total_active_subscribers, :created_at, :segment_type, :raw
+  ) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        name: payload["name"],
+        color: payload["color"],
+        total_active_subscribers: payload["total_active_subscribers"],
+        created_at: Coercion.time(payload["created_at"]),
+        segment_type: payload["segment_type"],
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end

data/lib/flodesk/objects/subscriber.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A subscriber.
+  Subscriber = Data.define(
+    :id, :status, :email, :source, :first_name, :last_name,
+    :segments, :custom_fields, :optin_ip, :optin_timestamp, :created_at, :raw
+  ) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        status: Coercion.enum(payload["status"], Enums::SUBSCRIBER_STATUSES),
+        email: payload["email"],
+        source: Coercion.enum(payload["source"], Enums::SUBSCRIBER_SOURCES),
+        first_name: payload["first_name"],
+        last_name: payload["last_name"],
+        segments: Coercion.array_of(Segment, payload["segments"]),
+        custom_fields: Coercion.string_hash(payload["custom_fields"]),
+        optin_ip: payload["optin_ip"],
+        optin_timestamp: Coercion.time(payload["optin_timestamp"]),
+        created_at: Coercion.time(payload["created_at"]),
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+
+    # True when this subscriber can receive marketing email.
+    def active?
+      status == :active
+    end
+  end
+end

data/lib/flodesk/objects/webhook.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A registered webhook.
+  Webhook = Data.define(:id, :post_url, :events, :created_at, :raw) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(
+        id: payload["id"],
+        post_url: payload["post_url"],
+        events: Coercion.snapshot(payload["events"] || []),
+        created_at: Coercion.time(payload["created_at"]),
+        raw: Coercion.snapshot(payload)
+      )
+    end
+
+    # The payload exactly as the API sent it, including any field this gem does
+    # not declare.
+    def to_h
+      raw
+    end
+  end
+end