flodesk 0.1.0

data/lib/flodesk/resources/subscribers.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Subscriber` tag of the Flodesk API.
+    class Subscribers < Base
+      PATH = "/subscribers"
+
+      # The API caps segments per subscriber at 50.
+      MAX_SEGMENTS = 50
+
+      # The API caps a batch at 50 subscribers per request. Combined with the
+      # endpoint's 20-requests-per-minute limit, that is a ceiling of 1,000
+      # upserts per minute.
+      MAX_BATCH_SIZE = 50
+
+      # Every field `CreateOrUpdateSubscriberItem` documents, and the single
+      # source of truth for both building the payload and rejecting unknown
+      # keys — a duplicated list is how a field quietly stops being covered.
+      #
+      # The contract spec asserts this matches the schema exactly. That is what
+      # makes rejecting unknown keys safe rather than brittle: a field Flodesk
+      # adds fails the build here, instead of becoming a runtime ArgumentError
+      # for a value the API would have accepted.
+      SUBSCRIBER_FIELDS = %i[
+        id email first_name last_name custom_fields segment_ids
+        double_optin optin_ip optin_timestamp
+      ].freeze
+
+      # GET /subscribers
+      #
+      # Issues exactly one request. Use {#auto_paging_each} to walk every page.
+      def list(page: nil, per_page: nil, status: nil, segment_id: nil)
+        paginated_list(
+          PATH, klass: Subscriber, page: page, per_page: per_page,
+                filters: list_filters(status: status, segment_id: segment_id)
+        )
+      end
+
+      # Walks every subscriber across all pages, fetching each page on demand.
+      #
+      # Traversing a large list can consume the entire 100-requests-per-minute
+      # budget, which is why this is opt-in rather than the behavior of `list`.
+      def auto_paging_each(page: nil, per_page: nil, status: nil, segment_id: nil, &)
+        each_page_item(
+          PATH, klass: Subscriber, page: page, per_page: per_page,
+                filters: list_filters(status: status, segment_id: segment_id), &
+        )
+      end
+
+      # GET /subscribers/{id_or_email}
+      #
+      # `id_or_email` may be either; an email is percent-encoded into the path.
+      def retrieve(id_or_email)
+        Subscriber.from(get("#{PATH}/#{encode_segment(id_or_email)}"))
+      end
+
+      # POST /subscribers — creates or updates.
+      #
+      # Declared idempotent: repeating it converges on the same state, so it is
+      # safe to retry after a timeout or 5xx.
+      #
+      # The API returns 200 for both a creation and an update and never reports
+      # which occurred, so this cannot tell you whether the subscriber was new.
+      def upsert(**attrs)
+        Subscriber.from(post(PATH, body: subscriber_payload(attrs), idempotent: true))
+      end
+
+      # POST /subscribers/batch — up to 50 records in one request.
+      #
+      # Returns a {BatchResult}. Because the API reports per-record failures
+      # inside a 200 response, this raises {PartialFailureError} when any record
+      # failed — carrying the full result, so successes are not lost. Pass
+      # `raise_on_failure: false` to receive the result quietly instead.
+      def batch_upsert(records, raise_on_failure: true)
+        payload = batch_payload(records)
+        result = BatchResult.from(
+          post("#{PATH}/batch", body: { "subscribers" => payload }, idempotent: true)
+        )
+
+        raise PartialFailureError.new(result: result) if raise_on_failure && !result.success?
+
+        result
+      end
+
+      # POST /subscribers/{id_or_email}/segments
+      #
+      # Idempotent: adding a segment the subscriber already has has no further
+      # effect.
+      def add_to_segments(id_or_email, segment_ids)
+        Subscriber.from(
+          post(
+            "#{PATH}/#{encode_segment(id_or_email)}/segments",
+            body: { "segment_ids" => validate_segment_ids!(segment_ids) },
+            idempotent: true
+          )
+        )
+      end
+
+      # DELETE /subscribers/{id_or_email}/segments
+      #
+      # Idempotent: removing a segment the subscriber does not have has no
+      # further effect.
+      def remove_from_segments(id_or_email, segment_ids)
+        Subscriber.from(
+          delete(
+            "#{PATH}/#{encode_segment(id_or_email)}/segments",
+            body: { "segment_ids" => validate_segment_ids!(segment_ids) }
+          )
+        )
+      end
+
+      # POST /subscribers/{id_or_email}/unsubscribe
+      #
+      # Idempotent: unsubscribing is a terminal state, so repeating it is safe.
+      def unsubscribe(id_or_email)
+        Subscriber.from(
+          post("#{PATH}/#{encode_segment(id_or_email)}/unsubscribe", idempotent: true)
+        )
+      end
+
+      private
+
+      def list_filters(status:, segment_id:)
+        {
+          "status" => validate_enum!("status", status, Enums::SUBSCRIBER_STATUSES),
+          "segment_id" => segment_id
+        }
+      end
+
+      # Builds a `CreateOrUpdateSubscriberItem`. `index` is included in the error
+      # message when validating a batch, so a rejected record is identifiable.
+      def subscriber_payload(attrs, index: nil)
+        attrs = normalize_keys(attrs, index)
+        validate_known_keys!(attrs, index)
+        validate_identifier!(attrs, index)
+
+        SUBSCRIBER_FIELDS.each_with_object({}) do |field, payload|
+          value = coerce_field(field, attrs[field])
+          payload[field.to_s] = value unless value.nil?
+        end
+      end
+
+      # `false` is a meaningful value for `double_optin`, so only `nil` — the
+      # caller having said nothing — omits a field.
+      def coerce_field(field, value)
+        return nil if value.nil?
+
+        case field
+        when :custom_fields then stringify_custom_fields(value)
+        when :segment_ids then validate_segment_ids!(value)
+        else value
+        end
+      end
+
+      def batch_payload(records)
+        # Shape is checked before contents. `each_with_index` over a Hash yields
+        # [[key, value], 0], so a single record passed instead of an array used
+        # to have its *values* parsed as field names — putting a subscriber
+        # email into an error message.
+        unless records.is_a?(Array)
+          raise ArgumentError,
+                "records must be an Array of subscriber attributes, got #{records.class}"
+        end
+
+        raise ArgumentError, "records cannot be empty" if records.empty?
+
+        if records.size > MAX_BATCH_SIZE
+          raise ArgumentError,
+                "a batch accepts at most #{MAX_BATCH_SIZE} records, got #{records.size}"
+        end
+
+        records.each_with_index.map { |record, i| subscriber_payload(record, index: i) }
+      end
+
+      # `to_s.to_sym` rather than `to_sym`: a non-symbolizable key (an Integer,
+      # say) should surface as an unknown field, not a NoMethodError from deep
+      # inside the payload builder.
+      def normalize_keys(attrs, index = nil)
+        return {} if attrs.nil?
+
+        unless attrs.is_a?(Hash)
+          at = index.nil? ? "" : " at index #{index}"
+          raise ArgumentError,
+                "subscriber attributes must be a Hash#{at}, got #{attrs.class}"
+        end
+
+        attrs.to_h { |k, v| [k.to_s.to_sym, v] }
+      end
+
+      # An unrecognized key used to be dropped on the floor, so a misspelled
+      # `frist_name:` vanished and the request reported success. Silence is the
+      # worst outcome here: the caller believes they wrote a field they did not.
+      def validate_known_keys!(attrs, index)
+        unknown = attrs.keys - SUBSCRIBER_FIELDS
+        return if unknown.empty?
+
+        at = index.nil? ? "" : " at index #{index}"
+        noun = unknown.one? ? "field" : "fields"
+        raise ArgumentError,
+              "unknown subscriber #{noun}#{at}: #{unknown.join(", ")}. " \
+              "Accepted: #{SUBSCRIBER_FIELDS.join(", ")}"
+      end
+
+      def validate_identifier!(attrs, index)
+        return if present?(attrs[:id]) || present?(attrs[:email])
+
+        at = index.nil? ? "" : " at index #{index}"
+        raise ArgumentError, "either email or id must be provided#{at}"
+      end
+
+      def validate_segment_ids!(segment_ids)
+        ids = Array(segment_ids)
+        raise ArgumentError, "segment_ids cannot be empty" if ids.empty?
+
+        if ids.size > MAX_SEGMENTS
+          raise ArgumentError,
+                "a subscriber accepts at most #{MAX_SEGMENTS} segments, got #{ids.size}"
+        end
+
+        ids.map(&:to_s)
+      end
+
+      # Custom field values are typed `string` throughout the API, so anything
+      # else would simply be rejected. Coercing is friendlier than raising and
+      # cannot lose information. `nil` is preserved: it means "clear this
+      # field", which is a different instruction from the empty string.
+      def stringify_custom_fields(fields)
+        return nil if fields.nil?
+
+        fields.to_h { |key, value| [key.to_s, value&.to_s] }
+      end
+
+      def present?(value)
+        !value.nil? && !value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/flodesk/resources/webhooks.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Webhook` tag of the Flodesk API.
+    #
+    # Registering a webhook is only half the job. Flodesk signs nothing — the API
+    # description declares `security: []` on all three events — so the endpoint
+    # you register must be able to establish authenticity by other means. See
+    # {Flodesk::Webhooks::Handler} for the two supported strategies, and choose
+    # one before deciding what `post_url` to register here.
+    class Webhooks < Base
+      PATH = "/webhooks"
+
+      # GET /webhooks
+      def list(page: nil, per_page: nil)
+        paginated_list(PATH, klass: Webhook, page: page, per_page: per_page)
+      end
+
+      # Walks every webhook across all pages, fetching each page on demand.
+      def auto_paging_each(page: nil, per_page: nil, &)
+        each_page_item(PATH, klass: Webhook, page: page, per_page: per_page, &)
+      end
+
+      # GET /webhooks/{id}
+      def retrieve(id)
+        Webhook.from(get("#{PATH}/#{encode_segment(id)}"))
+      end
+
+      # POST /webhooks — returns 201 with the created webhook.
+      #
+      # NOT idempotent: this creates a new registration and the API offers no
+      # idempotency key, so a retry could leave a duplicate webhook delivering
+      # every event twice.
+      def create(name:, post_url:, events:)
+        raise ArgumentError, "name is required" if blank?(name)
+        raise ArgumentError, "post_url is required" if blank?(post_url)
+
+        Webhook.from(
+          post(
+            PATH,
+            body: {
+              "name" => name.to_s,
+              "post_url" => post_url.to_s,
+              "events" => validate_events!(events)
+            },
+            idempotent: false
+          )
+        )
+      end
+
+      # PUT /webhooks/{id}
+      #
+      # Idempotent: PUT replaces the registration's state, so repeating it
+      # converges on the same result. Every field is optional; only those
+      # supplied are sent.
+      def update(id, name: nil, post_url: nil, events: nil)
+        body = {
+          "name" => name&.to_s,
+          "post_url" => post_url&.to_s,
+          "events" => events.nil? ? nil : validate_events!(events)
+        }.compact
+
+        raise ArgumentError, "at least one of name, post_url or events is required" if body.empty?
+
+        Webhook.from(put("#{PATH}/#{encode_segment(id)}", body: body))
+      end
+
+      # DELETE /webhooks/{id} — returns 204.
+      #
+      # Idempotent. Returns nil, since a 204 carries no body to parse.
+      def delete(id)
+        super("#{PATH}/#{encode_segment(id)}")
+      end
+
+      private
+
+      # Flodesk delivers exactly three events. Rejecting anything else here
+      # avoids registering a webhook that can never fire.
+      def validate_events!(events)
+        list = Array(events).map(&:to_s)
+        raise ArgumentError, "events cannot be empty" if list.empty?
+
+        list.each { |event| validate_enum!("events", event, Enums::WEBHOOK_EVENTS) }
+        list
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/flodesk/resources/workflows.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Workflow` tag of the Flodesk API.
+    class Workflows < Base
+      PATH = "/workflows"
+
+      # This endpoint spells its page-size parameter `perPage`, unlike every
+      # other list endpoint in the API, which use `per_page`. Callers pass
+      # `per_page:` regardless; the translation happens here.
+      PER_PAGE_KEY = "perPage"
+
+      # GET /workflows
+      #
+      # `statuses` accepts a single value or an array.
+      def list(page: nil, per_page: nil, statuses: nil)
+        paginated_list(
+          PATH, klass: Workflow, page: page, per_page: per_page,
+                per_page_key: PER_PAGE_KEY, filters: status_filter(statuses)
+        )
+      end
+
+      # Walks every workflow across all pages, fetching each page on demand.
+      def auto_paging_each(page: nil, per_page: nil, statuses: nil, &)
+        each_page_item(
+          PATH, klass: Workflow, page: page, per_page: per_page,
+                per_page_key: PER_PAGE_KEY, filters: status_filter(statuses), &
+        )
+      end
+
+      # POST /workflows/{workflow_id}/subscribers — returns 204.
+      #
+      # Idempotent: enrolling an already-enrolled subscriber has no further
+      # effect. Returns nil, since a 204 carries no body to parse.
+      def add_subscriber(workflow_id, id: nil, email: nil)
+        raise ArgumentError, "either id or email must be provided" if blank?(id) && blank?(email)
+
+        post(
+          "#{PATH}/#{encode_segment(workflow_id)}/subscribers",
+          body: { "id" => id, "email" => email }.compact,
+          idempotent: true
+        )
+      end
+
+      # DELETE /workflows/{workflow_id}/subscribers/{id_or_email} — returns 204.
+      #
+      # Idempotent. Returns nil, since a 204 carries no body to parse.
+      def remove_subscriber(workflow_id, id_or_email)
+        delete(
+          "#{PATH}/#{encode_segment(workflow_id)}/subscribers/#{encode_segment(id_or_email)}"
+        )
+      end
+
+      private
+
+      # `statuses` is an array parameter, but the API documents it as
+      # comma-separated (`statuses=active,paused`) rather than repeated keys.
+      # A single value is wrapped so callers can pass either form.
+      def status_filter(statuses)
+        return { "statuses" => nil } if statuses.nil?
+
+        validated = Array(statuses).map do |status|
+          validate_enum!("statuses", status, Enums::WORKFLOW_STATUSES)
+        end
+
+        { "statuses" => validated.join(",") }
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.empty?
+      end
+    end
+  end
+end

data/lib/flodesk/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A completed HTTP response: status, normalized headers, and parsed body.
+  #
+  # Instances are immutable. `body` is nil for 204 responses, which several
+  # endpoints return and which must never be parsed as JSON.
+  Response = Data.define(:status, :headers, :body) do
+    # Value of `X-Fd-RateLimit-Limit`, or nil when absent.
+    def rate_limit
+      integer_header("x-fd-ratelimit-limit")
+    end
+
+    # Value of `X-Fd-RateLimit-Remaining`, or nil when absent.
+    def rate_limit_remaining
+      integer_header("x-fd-ratelimit-remaining")
+    end
+
+    # Flodesk sends no rate-limit reset header, so no reset time exists to
+    # report. Present to make the absence explicit rather than surprising.
+    def rate_limit_reset
+      nil
+    end
+
+    private
+
+    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
+end

data/lib/flodesk/retry_policy.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Decides whether a failed request may be retried.
+  #
+  # This is a distinct concept in this client because Flodesk offers no
+  # idempotency-key header, so the only thing making a retry safe is knowing
+  # that the operation is naturally idempotent. That knowledge lives with each
+  # endpoint, and this class is where it is applied.
+  class RetryPolicy
+    # Whether repeating the operation is safe.
+    attr_reader :idempotent
+
+    # Whether a 429 may be retried. False only for POST /campaigns/canva, where
+    # a 429 cannot prove the campaign was not accepted.
+    attr_reader :retry_rate_limit
+
+    # Maximum retries after the initial attempt.
+    attr_reader :max_retries
+
+    def initialize(idempotent:, retry_rate_limit:, max_retries:)
+      @idempotent = idempotent
+      @retry_rate_limit = retry_rate_limit
+      @max_retries = max_retries
+      freeze
+    end
+
+    # True when `error` may be retried on attempt number `attempt`.
+    def retry?(error, attempt)
+      attempt <= max_retries && retriable_error?(error)
+    end
+
+    private
+
+    def retriable_error?(error)
+      case error
+      when RateLimitError then retry_rate_limit
+      when ServerError, TimeoutError, ConnectionError then idempotent
+      else
+        # Every other 4xx is caused by the request itself and cannot succeed on
+        # a second identical attempt.
+        false
+      end
+    end
+  end
+end

data/lib/flodesk/test_helpers.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "json"
+require "webmock"
+
+module Flodesk
+  # WebMock stubs and fixture payloads for testing Flodesk integrations.
+  #
+  # Opt-in: nothing here is loaded by `require "flodesk"`.
+  #
+  #   require "flodesk/test_helpers"
+  #
+  #   RSpec.configure { |c| c.include Flodesk::TestHelpers }
+  #
+  #   stub_flodesk_upsert(email: "a@b.com")
+  #   stub_flodesk_error(:post, "/subscribers", status: 404)
+  #
+  # Payload shapes follow the API description, so a stub cannot drift toward
+  # whatever the calling code happens to expect — the classic way a green suite
+  # hides a broken integration.
+  module TestHelpers
+    BASE_URL = Flodesk::DEFAULT_BASE_URL
+
+    # A `SubscriberRes` payload with every documented field populated.
+    def flodesk_subscriber(overrides = {})
+      {
+        "id" => "sub_test_1",
+        "status" => "active",
+        "email" => "subscriber@example.com",
+        "source" => "manual",
+        "first_name" => "Test",
+        "last_name" => "Subscriber",
+        "segments" => [],
+        "custom_fields" => {},
+        "optin_ip" => "203.0.113.1",
+        "optin_timestamp" => "2024-01-01T00:00:00.000Z",
+        "created_at" => "2024-01-01T00:00:00.000Z"
+      }.merge(stringify(overrides))
+    end
+
+    # A `SegmentRes` payload.
+    def flodesk_segment(overrides = {})
+      {
+        "id" => "seg_test_1",
+        "name" => "Test Segment",
+        "color" => "#ffeecc",
+        "total_active_subscribers" => 0,
+        "created_at" => "2024-01-01T00:00:00.000Z"
+      }.merge(stringify(overrides))
+    end
+
+    # A `WebhookRes` payload.
+    def flodesk_webhook(overrides = {})
+      {
+        "id" => "wh_test_1",
+        "post_url" => "https://example.com/flodesk",
+        "events" => ["subscriber.created"],
+        "created_at" => "2024-01-01T00:00:00.000Z"
+      }.merge(stringify(overrides))
+    end
+
+    # A paginated list envelope, with `meta` shaped as the API returns it.
+    def flodesk_list(items, page: 1, per_page: 20, total_pages: 1, total_items: nil)
+      {
+        "meta" => {
+          "page" => page, "per_page" => per_page,
+          "total_pages" => total_pages, "total_items" => total_items || items.size
+        },
+        "data" => items
+      }
+    end
+
+    # Stubs a successful subscriber upsert.
+    def stub_flodesk_upsert(email: "subscriber@example.com", **overrides)
+      stub_flodesk(:post, "/subscribers",
+                   response: flodesk_subscriber(email: email, **overrides))
+    end
+
+    # Stubs a subscriber retrieval by id or email.
+    def stub_flodesk_retrieve(id_or_email, **overrides)
+      stub_flodesk(
+        :get, "/subscribers/#{encode(id_or_email)}",
+        response: flodesk_subscriber(id: id_or_email.to_s, **overrides)
+      )
+    end
+
+    # Stubs a subscriber list.
+    def stub_flodesk_list_subscribers(subscribers = [flodesk_subscriber], **pagination)
+      stub_flodesk(:get, "/subscribers", response: flodesk_list(subscribers, **pagination))
+    end
+
+    # Stubs a batch upsert.
+    #
+    # Pass `failures:` to exercise partial failure, which is the case worth
+    # testing: the API reports it inside a 200, and by default the gem raises
+    # {Flodesk::PartialFailureError} for it.
+    def stub_flodesk_batch(successes: [flodesk_subscriber], failures: [])
+      stub_flodesk(
+        :post, "/subscribers/batch",
+        response: { "successes" => successes, "failures" => failures }
+      )
+    end
+
+    # A `BatchItemError` payload.
+    def flodesk_batch_failure(index: 0, code: "invalid_email", **overrides)
+      {
+        "index" => index,
+        "email" => "bad@",
+        "id" => nil,
+        "code" => code,
+        "message" => "Email is invalid"
+      }.merge(stringify(overrides))
+    end
+
+    # Stubs an error response using the live API's `{code, message}` envelope.
+    def stub_flodesk_error(method, path, status:, code: nil, message: nil)
+      stub_flodesk(
+        method, path, status: status,
+                      response: { "code" => code || "error", "message" => message || "Request failed" }
+      )
+    end
+
+    # Stubs a rate-limited response, including the headers the API sends. There
+    # is deliberately no reset header, because the API does not send one.
+    def stub_flodesk_rate_limited(method, path, limit: 100)
+      stub_flodesk(
+        method, path, status: 429,
+                      response: { "code" => "rate_limited", "message" => "Too many requests" },
+                      headers: { "X-Fd-RateLimit-Limit" => limit.to_s, "X-Fd-RateLimit-Remaining" => "0" }
+      )
+    end
+
+    # The general-purpose stub the helpers above are built on.
+    def stub_flodesk(method, path, response: nil, status: 200, headers: {}, base_url: BASE_URL)
+      WebMock::API.stub_request(method, "#{base_url}#{path}").to_return(
+        status: status,
+        body: response.nil? ? "" : JSON.generate(response),
+        headers: { "Content-Type" => "application/json" }.merge(headers)
+      )
+    end
+
+    private
+
+    def stringify(hash)
+      hash.to_h { |k, v| [k.to_s, v] }
+    end
+
+    def encode(value)
+      value.to_s.b.gsub(/[^A-Za-z0-9\-._~]/n) { |c| format("%%%02X", c.ord) }
+    end
+  end
+end

data/lib/flodesk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Flodesk
+  VERSION = "0.1.0"
+end