flodesk 0.1.0

data/lib/flodesk/objects/workflow.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # A workflow.
+  #
+  # The API description declares only `id` and `name`. The list endpoint accepts
+  # a `statuses` filter, but the response schema exposes no status field, so any
+  # status the API happens to return is reachable through {#to_h}.
+  Workflow = Data.define(:id, :name, :raw) do
+    def self.from(payload)
+      return nil if payload.nil?
+
+      new(id: payload["id"], name: payload["name"], 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/rails/railtie.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Rails
+    # Registers the gem's Rails integration.
+    #
+    # Deliberately minimal: it makes the generator discoverable and nothing else.
+    # There is no initializer hook that configures the gem, because the gem holds
+    # no global state — `rails g flodesk:install` scaffolds a client constant in
+    # the host application instead.
+    class Railtie < ::Rails::Railtie
+      railtie_name "flodesk"
+
+      generators do
+        require_relative "../../generators/flodesk/install_generator"
+      end
+    end
+  end
+end

data/lib/flodesk/rails.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# Optional Rails integration.
+#
+# Loaded automatically when Rails is present, and never otherwise: the gem must
+# work in a plain Ruby process and declares no runtime dependency on Rails or
+# ActiveSupport.
+require_relative "rails/railtie" if defined?(Rails::Railtie)

data/lib/flodesk/rate_limit.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Records the rate-limit state observed on the most recent response.
+  #
+  # Storage is thread-local by design. A client is frozen and shared across
+  # threads, so it cannot hold this as mutable state; and a caller pacing itself
+  # wants the limit state for *its own* requests, not whatever another thread
+  # last saw.
+  #
+  # Flodesk sends no reset header, so `remaining` is the only actionable signal
+  # available and the gem cannot guarantee staying within quota.
+  module RateLimit
+    State = Data.define(:limit, :remaining)
+
+    def self.record(client, response)
+      limit = response.rate_limit
+      remaining = response.rate_limit_remaining
+      return if limit.nil? && remaining.nil?
+
+      Thread.current[key(client)] = State.new(limit: limit, remaining: remaining)
+    end
+
+    # The rate-limit state from this thread's most recent request through
+    # `client`, or nil if none has been observed.
+    def self.last(client)
+      Thread.current[key(client)]
+    end
+
+    def self.key(client)
+      :"flodesk_rate_limit_#{client.object_id}"
+    end
+    private_class_method :key
+  end
+end

data/lib/flodesk/redaction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Flodesk
+  # Strips personally identifiable information from anything the gem logs or
+  # instruments.
+  #
+  # Two facts make this necessary rather than optional. Several paths accept an
+  # email address in place of an id, so the request path itself can carry PII.
+  # And webhook payloads embed both `email` and `optin_ip`.
+  module Redaction
+    # Fields that must never appear in log or instrumentation output.
+    SENSITIVE_KEYS = %w[email custom_fields optin_ip].freeze
+
+    PLACEHOLDER = "[REDACTED]"
+
+    # A path segment holding an email address, standing in for an id.
+    #
+    # Matches both the literal "@" and its percent-encoded form. By the time a
+    # path reaches here the segment has usually been encoded already, so
+    # checking only for "@" would let `a%40b.com` through — which is exactly how
+    # an email address ends up in a log.
+    EMAIL_IN_SEGMENT = /@|%40/i
+
+    def self.path(path)
+      path.to_s
+          .split("/")
+          .map { |segment| segment.match?(EMAIL_IN_SEGMENT) ? PLACEHOLDER : segment }
+          .join("/")
+    end
+
+    # Recursively removes sensitive values, preserving structure so the shape of
+    # a payload stays debuggable.
+    def self.payload(value)
+      case value
+      when Hash
+        value.to_h do |k, v|
+          SENSITIVE_KEYS.include?(k.to_s) ? [k, PLACEHOLDER] : [k, payload(v)]
+        end
+      when Array
+        value.map { |v| payload(v) }
+      else
+        value
+      end
+    end
+  end
+end

data/lib/flodesk/resources/base.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Shared behavior for resource namespaces.
+    #
+    # Subclasses stay thin: they translate idiomatic Ruby arguments into the
+    # shape each endpoint wants, declare whether the operation is safe to retry,
+    # and hand the parsed body to a value object.
+    class Base
+      # The API rejects `per_page` above 100.
+      MAX_PER_PAGE = 100
+
+      # Characters left unescaped in a path segment, per RFC 3986 "unreserved".
+      UNRESERVED = /[^A-Za-z0-9\-._~]/n
+
+      def initialize(client)
+        @client = client
+        freeze
+      end
+
+      private
+
+      def get(path, query: nil)
+        @client.request(:get, path, query: query, idempotent: true).body
+      end
+
+      def post(path, body: nil, query: nil, idempotent: false, retry_rate_limit: true)
+        @client.request(
+          :post, path,
+          body: body, query: query, idempotent: idempotent, retry_rate_limit: retry_rate_limit
+        ).body
+      end
+
+      def put(path, body: nil)
+        # PUT replaces the resource's state, so repeating it is safe.
+        @client.request(:put, path, body: body, idempotent: true).body
+      end
+
+      def delete(path, body: nil)
+        @client.request(:delete, path, body: body, idempotent: true).body
+      end
+
+      # Fetches one page and wraps it in a Page.
+      #
+      # The Page is given a fetcher closing over this call's path, filters and
+      # page size, which is what lets `auto_paging_each` walk forward without
+      # the caller restating any of it.
+      def paginated_list(path, klass:, page: nil, per_page: nil,
+                         per_page_key: "per_page", filters: {})
+        query = pagination(page: page, per_page: per_page, per_page_key: per_page_key)
+                .merge(filters.compact)
+
+        Page.from(
+          get(path, query: query),
+          klass: klass,
+          fetcher: lambda { |next_page|
+            paginated_list(
+              path, klass: klass, page: next_page, per_page: per_page,
+                    per_page_key: per_page_key, filters: filters
+            )
+          }
+        )
+      end
+
+      # Walks every page of a list operation, fetching each on demand.
+      #
+      # Returns a lazy Enumerator when no block is given, so nothing is
+      # requested until iteration begins and each traversal re-fetches.
+      def each_page_item(path, **, &block)
+        return to_enum(:each_page_item, path, **) unless block
+
+        paginated_list(path, **).auto_paging_each(&block)
+      end
+
+      # Builds the pagination query for an endpoint, translating the uniform
+      # caller-facing arguments into whatever spelling the endpoint expects.
+      # Most take `per_page`; GET /workflows takes `perPage`.
+      def pagination(page:, per_page:, per_page_key: "per_page")
+        validate_per_page!(per_page)
+
+        query = {}
+        query["page"] = page unless page.nil?
+        query[per_page_key] = per_page unless per_page.nil?
+        query
+      end
+
+      def validate_per_page!(per_page)
+        return if per_page.nil?
+
+        return if per_page.is_a?(Integer) && per_page.between?(1, MAX_PER_PAGE)
+
+        raise ArgumentError,
+              "per_page must be an Integer between 1 and #{MAX_PER_PAGE}, got #{per_page.inspect}"
+      end
+
+      # Validates a value against a closed enum from the API description.
+      # Filters are rejected before a request is made, since the API would only
+      # reject them after a round trip.
+      def validate_enum!(name, value, allowed)
+        return nil if value.nil?
+
+        normalized = value.to_s
+        unless allowed.include?(normalized)
+          raise ArgumentError,
+                "#{name} must be one of #{allowed.join(", ")}, got #{value.inspect}"
+        end
+
+        normalized
+      end
+
+      # Path segments may be an id or an email address, and several endpoints
+      # accept either. Emails need percent-encoding so "+" survives the round
+      # trip rather than being read as a space.
+      def encode_segment(value)
+        raise ArgumentError, "identifier cannot be blank" if value.nil? || value.to_s.empty?
+
+        value.to_s.b.gsub(UNRESERVED) { |c| format("%%%02X", c.ord) }
+      end
+    end
+  end
+end

data/lib/flodesk/resources/campaigns.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Campaign` tag of the Flodesk API.
+    #
+    # These endpoints cannot be safely exercised against a live account during
+    # development, so they are covered only by specification-derived stubs and
+    # are less battle-tested than the subscriber and segment operations.
+    class Campaigns < Base
+      PATH = "/campaigns"
+
+      # This endpoint's filters are PascalCase, unlike anything else in the API.
+      # Its pagination parameters, confusingly, remain snake_case. Callers use
+      # idiomatic snake_case throughout and this map does the translating.
+      FILTER_KEYS = {
+        search: "Search",
+        order_by: "OrderBy",
+        sort: "Sort",
+        status: "Status",
+        shared_as_template: "SharedAsTemplate"
+      }.freeze
+
+      # GET /campaigns
+      def list(page: nil, per_page: nil, **filters)
+        paginated_list(
+          PATH, klass: Campaign, page: page, per_page: per_page,
+                filters: list_filters(**filters)
+        )
+      end
+
+      # Walks every campaign across all pages, fetching each page on demand.
+      def auto_paging_each(page: nil, per_page: nil, **filters, &)
+        each_page_item(
+          PATH, klass: Campaign, page: page, per_page: per_page,
+                filters: list_filters(**filters), &
+        )
+      end
+
+      # POST /campaigns/canva — publishes an email campaign. Returns 201.
+      #
+      # ---------------------------------------------------------------------
+      # NEVER RETRIED. NOT ON 5xx, NOT ON TIMEOUT, NOT ON 429.
+      #
+      # This operation sends an email campaign to the subscriber list. A retry
+      # can deliver it a second time, which is unrecoverable and visible to
+      # every recipient. No response code — including a timeout or a 429 —
+      # proves the campaign was not accepted, so the only safe policy is to
+      # surface the failure and let a human decide.
+      # ---------------------------------------------------------------------
+      #
+      # Returns the raw response body: the `PublishCanvaRes` schema declares
+      # only `id` and `url`, which is not a Campaign.
+      def publish_canva(bundle_url: nil, title: nil, design_token: nil,
+                        page_id: nil, campaign_id: nil)
+        post(
+          "#{PATH}/canva",
+          body: {
+            "bundle_url" => bundle_url,
+            "title" => title,
+            "design_token" => design_token,
+            "page_id" => page_id,
+            "campaign_id" => campaign_id
+          }.compact,
+          idempotent: false,
+          retry_rate_limit: false
+        )
+      end
+
+      # POST /campaigns/studio — publishes an email campaign. Returns 201.
+      #
+      # ---------------------------------------------------------------------
+      # NEVER RETRIED. Same policy as {#publish_canva}, for the same reason.
+      #
+      # Both endpoints are summarized upstream as publishing a *draft*, which
+      # is a weaker hazard than an immediate send. The policy does not lean on
+      # that distinction: "draft" is a one-line summary in the specification,
+      # not a guarantee, and the failure it would license is unrecoverable and
+      # visible to every recipient. Retrying is the bet that cannot be unmade,
+      # so it is not taken.
+      # ---------------------------------------------------------------------
+      #
+      # Returns the raw response body: the `PublishStudioRes` schema declares
+      # only `id` and `url`, which is not a Campaign.
+      def publish_studio(html: nil, title: nil, campaign_id: nil, asset_id: nil)
+        post(
+          "#{PATH}/studio",
+          body: {
+            "html" => html,
+            "title" => title,
+            "campaign_id" => campaign_id,
+            "asset_id" => asset_id
+          }.compact,
+          idempotent: false,
+          retry_rate_limit: false
+        )
+      end
+
+      # GET /campaigns/canva/design-state
+      #
+      # Returns the raw response body: `CanvaDesignStateRes` declares only
+      # `design_id` and `campaign_id`.
+      def canva_design_state
+        get("#{PATH}/canva/design-state")
+      end
+
+      private
+
+      def list_filters(search: nil, order_by: nil, sort: nil, status: nil,
+                       shared_as_template: nil)
+        {
+          FILTER_KEYS[:search] => search,
+          FILTER_KEYS[:order_by] => order_by,
+          FILTER_KEYS[:sort] => sort,
+          FILTER_KEYS[:status] => validate_enum!("status", status, Enums::CAMPAIGN_STATUSES),
+          FILTER_KEYS[:shared_as_template] => shared_as_template
+        }
+      end
+    end
+  end
+end

data/lib/flodesk/resources/custom_fields.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Custom Field` tag of the Flodesk API.
+    #
+    # Custom fields are identified by `key`, which the API derives from the
+    # `label` given at creation. Values stored against a field are always
+    # strings; see {Subscribers#upsert} for how non-string values are handled.
+    class CustomFields < Base
+      PATH = "/custom-fields"
+
+      # GET /custom-fields — paginated.
+      #
+      # Distinct from {#list_all}, which returns every field in one unpaginated
+      # response. The two endpoints are easy to confuse.
+      def list(page: nil, per_page: nil)
+        paginated_list(PATH, klass: CustomField, page: page, per_page: per_page)
+      end
+
+      # Walks every custom field across all pages, fetching each on demand.
+      def auto_paging_each(page: nil, per_page: nil, &)
+        each_page_item(PATH, klass: CustomField, page: page, per_page: per_page, &)
+      end
+
+      # GET /custom-fields/all — every field in one response.
+      #
+      # Returns a plain Array rather than a {Page}, because this endpoint is not
+      # paginated and has no `meta` block to report.
+      def list_all
+        body = get("#{PATH}/all")
+
+        Coercion.array_of(CustomField, body.is_a?(Hash) ? body["data"] : body)
+      end
+
+      # POST /custom-fields — returns 201 with the created field.
+      #
+      # NOT idempotent: this creates a new record and the API offers no
+      # idempotency key, so a retry could leave a duplicate field behind.
+      def create(label:)
+        raise ArgumentError, "label is required" if label.nil? || label.to_s.empty?
+
+        CustomField.from(post(PATH, body: { "label" => label.to_s }, idempotent: false))
+      end
+    end
+  end
+end

data/lib/flodesk/resources/segments.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Flodesk
+  module Resources
+    # Operations under the `Segment` tag of the Flodesk API.
+    class Segments < Base
+      PATH = "/segments"
+
+      # GET /segments
+      def list(page: nil, per_page: nil)
+        paginated_list(PATH, klass: Segment, page: page, per_page: per_page)
+      end
+
+      # Walks every segment across all pages, fetching each page on demand.
+      def auto_paging_each(page: nil, per_page: nil, &)
+        each_page_item(PATH, klass: Segment, page: page, per_page: per_page, &)
+      end
+
+      # GET /segments/{id}
+      def retrieve(id)
+        Segment.from(get("#{PATH}/#{encode_segment(id)}"))
+      end
+
+      # POST /segments — returns 201 with the created segment.
+      #
+      # NOT idempotent. This endpoint creates a new record and the API offers no
+      # idempotency key, so a retry after a timeout or 5xx would leave a second,
+      # duplicate segment behind. Failures are surfaced to the caller instead.
+      def create(name:, color: nil)
+        raise ArgumentError, "name is required" if name.nil? || name.to_s.empty?
+
+        Segment.from(
+          post(
+            PATH,
+            body: { "name" => name.to_s, "color" => color }.compact,
+            idempotent: false
+          )
+        )
+      end
+
+      # GET /segments/colors — the palette available for segment colors.
+      #
+      # The only error this endpoint documents is 401.
+      def colors
+        get("#{PATH}/colors")
+      end
+    end
+  end
+end