flodesk 0.1.0

data/lib/flodesk/webhooks/event.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Flodesk
+  module Webhooks
+    # A verified inbound webhook event.
+    #
+    # `subscriber` is a {Flodesk::Subscriber}. Under the refetch strategy it is
+    # the authoritative record read back from the API rather than the copy in the
+    # payload.
+    # Declared with a real class body rather than `Data.define(...) do ... end`,
+    # because this class owns a constant. Constants assigned inside that block
+    # form bind to the *enclosing lexical scope* — they would land on
+    # Flodesk::Webhooks, not on Event. Subclassing opens a proper namespace.
+    #
+    # Style/DataInheritance is disabled deliberately: following it here would
+    # reintroduce exactly that scoping bug.
+    class Event < Data.define(:event_name, :event_time, :subscriber, :segment, # rubocop:disable Style/DataInheritance
+                              :webhook_id, :raw)
+      # Field separator for the composed dedupe key.
+      #
+      # NUL rather than a space, because it cannot occur inside any of the joined
+      # values. A printable separator would let distinct events collide: with a
+      # space, ["a b", "c"] and ["a", "b c"] both join to "a b c".
+      #
+      # Written as an escape deliberately — an earlier automated edit left a raw
+      # NUL byte here, which made git treat this source file as binary.
+      KEY_SEPARATOR = "\0"
+
+      def self.from(payload, subscriber: nil)
+        new(
+          event_name: payload["event_name"],
+          event_time: Coercion.time(payload["event_time"]),
+          subscriber: subscriber || Subscriber.from(payload["subscriber"]),
+          segment: Segment.from(payload["segment"]),
+          webhook_id: payload["webhook_id"],
+          raw: Coercion.snapshot(payload)
+        )
+      end
+
+      # The payload exactly as delivered, including any field this gem does not
+      # declare — so a newly introduced Flodesk event stays usable.
+      def to_h
+        raw
+      end
+
+      # True when `event_name` is one of the three events Flodesk documents.
+      def known?
+        Enums::WEBHOOK_EVENTS.include?(event_name)
+      end
+
+      # A stable key for rejecting duplicate deliveries.
+      #
+      # Flodesk's event schemas define no unique event id, so the key is composed
+      # from the fields that together identify one delivery. It is hashed for two
+      # reasons: it is a fixed-length string regardless of input, and it carries
+      # no raw email or IP address into whatever store the application persists
+      # it in.
+      #
+      # The gem does not deduplicate. Only the application has storage, so
+      # rejecting replays is its responsibility.
+      def dedupe_key
+        Digest::SHA256.hexdigest(
+          [webhook_id, event_name, subscriber&.id, raw["event_time"]].join(KEY_SEPARATOR)
+        )
+      end
+
+      # Redacted: events carry `email` and `optin_ip`, and inspect output reaches
+      # logs and error pages.
+      def inspect
+        "#<#{self.class.name} event_name=#{event_name.inspect} " \
+          "webhook_id=#{webhook_id.inspect} subscriber_id=#{subscriber&.id.inspect}>"
+      end
+      alias to_s inspect
+    end
+  end
+end

data/lib/flodesk/webhooks/handler.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module Flodesk
+  # Handling of inbound webhook deliveries from Flodesk.
+  module Webhooks
+    # The verification strategies a handler can be built with.
+    STRATEGIES = %i[token refetch].freeze
+
+    # Verifies and parses inbound webhook deliveries.
+    #
+    # A verification strategy is **mandatory**. Flodesk signs nothing, so a
+    # handler that accepted any POST would let anyone who learns the callback URL
+    # forge subscriber events. Constructing without choosing a strategy raises
+    # rather than defaulting to trust.
+    #
+    # Token in the callback path — cheap, no extra API call:
+    #
+    #   token   = Flodesk::Webhooks::Handler.generate_token
+    #   handler = Flodesk::Webhooks::Handler.new(token: token)
+    #   # register post_url "https://app.example.com/flodesk/#{token}"
+    #   event = handler.call(body: request.raw_post, token: params[:token])
+    #
+    # Note that the token then appears in server access logs and Rails request
+    # logs, so filter that route.
+    #
+    # Re-fetch — forgery-proof, costs one API call per event against the
+    # 100-per-minute budget:
+    #
+    #   handler = Flodesk::Webhooks::Handler.new(verify: :refetch, client: FLODESK)
+    #   event   = handler.call(body: request.raw_post)
+    class Handler
+      # A URL-safe random token suitable for embedding in a callback path.
+      def self.generate_token
+        Verification.generate_token
+      end
+
+      def initialize(token: nil, verify: nil, client: nil)
+        @strategy = resolve_strategy(token: token, verify: verify)
+        validate_strategy!(token: token, client: client)
+
+        @token = token
+        @client = client
+        freeze
+      end
+
+      # Verifies `body` and returns a parsed {Event}.
+      #
+      # Raises {VerificationError} if authenticity cannot be established, before
+      # the body is parsed. Raises {InvalidPayloadError} if a verified body
+      # cannot be understood.
+      def call(body:, token: nil)
+        verify_token!(token) if @strategy == :token
+
+        payload = parse!(body)
+
+        if @strategy == :refetch
+          Event.from(payload, subscriber: refetch!(payload))
+        else
+          Event.from(payload)
+        end
+      end
+
+      # Verifies, parses, dispatches, and maps the outcome to a Rack triple.
+      #
+      # Flodesk treats any 2XX as "delivered" and anything else as "retry
+      # later", so the status is the only backpressure signal available. An
+      # exception from the application's block therefore becomes a 500: the
+      # event was not processed, and Flodesk should try again rather than
+      # consider it delivered.
+      #
+      #   post "/flodesk/:token" do
+      #     status, headers, body = HANDLER.respond(
+      #       body: request.raw_post, token: params[:token]
+      #     ) { |event| SubscriberSync.perform_later(event.subscriber.id) }
+      #   end
+      #
+      # `on_error` receives any exception raised by the block, so the
+      # application can report its own failures rather than have them swallowed.
+      def respond(body:, token: nil, on_error: nil)
+        event = call(body: body, token: token)
+        yield event if block_given?
+        rack(200, "ok")
+      rescue VerificationError
+        rack(401, "unauthorized")
+      rescue InvalidPayloadError
+        rack(400, "bad request")
+      rescue StandardError => e
+        on_error&.call(e)
+        rack(500, "error")
+      end
+
+      private
+
+      # Response bodies are deliberately bare: the request payload holds PII and
+      # the token is a secret, so neither may be echoed back.
+      def rack(status, text)
+        [status, { "content-type" => "text/plain" }, [text]]
+      end
+
+      def resolve_strategy(token:, verify:)
+        return verify.to_sym if verify
+
+        return :token if token
+
+        raise ArgumentError,
+              "a verification strategy is required: pass token: for token-in-path " \
+              "verification, or verify: :refetch with a client. Flodesk does not sign " \
+              "webhooks, so unverified payloads cannot be trusted."
+      end
+
+      def validate_strategy!(token:, client:)
+        raise ArgumentError, "unknown verification strategy #{@strategy.inspect}" unless STRATEGIES.include?(@strategy)
+
+        validate_token!(token) if @strategy == :token
+
+        return unless @strategy == :refetch && client.nil?
+
+        raise ArgumentError, "verify: :refetch requires a client to re-fetch the subscriber"
+      end
+
+      def validate_token!(token)
+        return unless token.nil? || token.to_s.length < Verification::MIN_TOKEN_LENGTH
+
+        raise ArgumentError,
+              "token must be at least #{Verification::MIN_TOKEN_LENGTH} characters; " \
+              "use #{self.class.name}.generate_token"
+      end
+
+      # Raises before parsing, so a forged request's body is never interpreted.
+      def verify_token!(supplied)
+        raise VerificationError unless Verification.secure_compare(@token, supplied)
+      end
+
+      def parse!(body)
+        raise InvalidPayloadError, "webhook body was empty" if body.nil? || body.to_s.strip.empty?
+
+        payload = begin
+          JSON.parse(body)
+        rescue JSON::ParserError
+          # The message deliberately omits the body, which holds PII.
+          raise InvalidPayloadError, "webhook body was not valid JSON"
+        end
+
+        raise InvalidPayloadError, "webhook body was not a JSON object" unless payload.is_a?(Hash)
+
+        payload
+      end
+
+      # Treats the payload as an untrusted hint: takes only the subscriber id and
+      # reads the authoritative record back from the API.
+      def refetch!(payload)
+        id = payload.dig("subscriber", "id")
+        raise VerificationError if id.nil? || id.to_s.empty?
+
+        begin
+          @client.subscribers.retrieve(id)
+        rescue Flodesk::NotFoundError
+          # A subscriber that does not exist means the payload was not genuine.
+          raise VerificationError
+        end
+      end
+    end
+  end
+end

data/lib/flodesk/webhooks/verification.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Flodesk
+  module Webhooks
+    # Raised when an inbound request cannot be established as genuine.
+    #
+    # Messages deliberately carry no detail: the payload holds PII and the
+    # comparison involves a secret, neither of which may reach a log.
+    class VerificationError < Error
+      def initialize(msg = "Webhook verification failed")
+        super
+      end
+    end
+
+    # Raised when a verified request's body cannot be understood.
+    class InvalidPayloadError < Error; end
+
+    # Helpers for establishing that an inbound webhook is genuine.
+    #
+    # Flodesk signs nothing. The API description declares `security: []` on all
+    # three webhook events, so there is no signature header to check and anyone
+    # who learns a callback URL can forge a delivery. The two viable defenses are
+    # a secret embedded in the callback path, and re-fetching the subscriber and
+    # trusting only that. IP allowlisting is not viable: Flodesk publishes no
+    # ranges.
+    module Verification
+      # Minimum acceptable length for a path token. 32 characters of the
+      # generated alphabet is comfortably beyond guessing.
+      MIN_TOKEN_LENGTH = 32
+
+      # Bytes of entropy for a generated token.
+      TOKEN_BYTES = 32
+
+      module_function
+
+      # A URL-safe random token suitable for embedding in a callback path.
+      def generate_token
+        SecureRandom.urlsafe_base64(TOKEN_BYTES).delete("=")
+      end
+
+      # Compares two strings in constant time, so response timing cannot be used
+      # to recover the expected value one character at a time.
+      def secure_compare(expected, supplied)
+        return false if expected.nil? || supplied.nil?
+
+        expected = expected.to_s.b
+        supplied = supplied.to_s.b
+
+        # Comparing digests rather than the raw strings keeps the comparison
+        # constant-time even when the lengths differ, which a plain byte-wise
+        # loop cannot do without leaking length.
+        expected_digest = OpenSSL::Digest::SHA256.digest(expected)
+        supplied_digest = OpenSSL::Digest::SHA256.digest(supplied)
+
+        OpenSSL.secure_compare(expected_digest, supplied_digest) && expected.bytesize == supplied.bytesize
+      end
+    end
+  end
+end

data/lib/flodesk.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+# Ruby client for the Flodesk API (https://developers.flodesk.com).
+#
+# The gem holds no global mutable configuration: construct a client explicitly
+# and pass it around, or assign one to a constant in your application.
+#
+#   client = Flodesk::Client.new(
+#     api_key:  ENV.fetch("FLODESK_API_KEY"),
+#     app_name: "MyApp (myapp.com)"
+#   )
+#
+# A single client is safe to share across threads.
+module Flodesk
+  # The production API root. Every request is issued relative to this.
+  DEFAULT_BASE_URL = "https://api.flodesk.com/v1"
+
+  # Ceiling for retry backoff, in seconds.
+  #
+  # Set to the rate-limit window length. Flodesk returns no rate-limit reset
+  # header, so there is no correct wait to compute; this is a documented
+  # heuristic and the gem makes no promise of staying within quota.
+  MAX_BACKOFF_SECONDS = 60
+end
+
+require_relative "flodesk/version"
+require_relative "flodesk/errors"
+require_relative "flodesk/redaction"
+require_relative "flodesk/instrumentation"
+require_relative "flodesk/enums"
+require_relative "flodesk/coercion"
+require_relative "flodesk/objects/segment"
+require_relative "flodesk/objects/subscriber"
+require_relative "flodesk/objects/custom_field"
+require_relative "flodesk/objects/workflow"
+require_relative "flodesk/objects/webhook"
+require_relative "flodesk/objects/campaign"
+require_relative "flodesk/objects/page"
+require_relative "flodesk/objects/batch_item_error"
+require_relative "flodesk/objects/batch_result"
+require_relative "flodesk/response"
+require_relative "flodesk/rate_limit"
+require_relative "flodesk/auth"
+require_relative "flodesk/retry_policy"
+require_relative "flodesk/connection"
+require_relative "flodesk/resources/base"
+require_relative "flodesk/resources/subscribers"
+require_relative "flodesk/resources/segments"
+require_relative "flodesk/resources/custom_fields"
+require_relative "flodesk/resources/workflows"
+require_relative "flodesk/resources/webhooks"
+require_relative "flodesk/resources/campaigns"
+require_relative "flodesk/client"
+require_relative "flodesk/webhooks/verification"
+require_relative "flodesk/webhooks/event"
+require_relative "flodesk/webhooks/handler"
+
+# Self-guarding: loads the Railtie only when Rails is already present.
+require_relative "flodesk/rails"

data/lib/generators/flodesk/install_generator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Flodesk
+  module Generators
+    # Scaffolds `config/initializers/flodesk.rb`.
+    #
+    # The initializer builds a client and assigns it to a constant in the *host
+    # application*, rather than configuring the gem. The gem holds no global
+    # mutable state, which keeps per-tenant API keys trivial and leaves nothing
+    # process-wide to leak between tests.
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates config/initializers/flodesk.rb wired to Rails credentials."
+
+      class_option :force, type: :boolean, default: false,
+                           desc: "Overwrite an existing config/initializers/flodesk.rb"
+
+      INITIALIZER_PATH = "config/initializers/flodesk.rb"
+
+      # Refuses to clobber an existing initializer rather than relying on Thor's
+      # collision prompt, which resolves to "overwrite" on a non-interactive
+      # shell. This file typically holds hand-tuned client configuration, and
+      # re-running the generator should never silently discard it.
+      def create_initializer
+        if File.exist?(File.join(destination_root, INITIALIZER_PATH)) && !options[:force]
+          say_status :skip, "#{INITIALIZER_PATH} already exists (pass --force to replace)", :yellow
+          @skipped = true
+          return
+        end
+
+        template "initializer.rb", INITIALIZER_PATH
+      end
+
+      def report_next_steps
+        return if @skipped
+
+        say ""
+        say "Add your Flodesk API key to credentials:", :green
+        say "  bin/rails credentials:edit"
+        say "  flodesk_api_key: fd_your_key_here"
+        say ""
+        say "Create and manage API keys at:", :green
+        say "  https://app.flodesk.com/account/integration/api"
+        say ""
+      end
+
+      private
+
+      # Used by the template to identify the application to Flodesk, which asks
+      # integrations to send a descriptive User-Agent.
+      def application_name
+        ::Rails.application.class.module_parent_name
+      rescue StandardError
+        "MyApp"
+      end
+    end
+  end
+end

data/lib/generators/flodesk/templates/initializer.rb.tt

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Flodesk API client.
+#
+# The gem holds no global configuration, so the client lives here as an
+# application constant. That keeps ownership visible and greppable, and leaves
+# per-tenant API keys straightforward: build another client where you need one.
+#
+#   FLODESK.subscribers.upsert(email: "a@b.com")
+#
+# A single client is frozen and safe to share across request threads.
+FLODESK = Flodesk::Client.new(
+  api_key: Rails.application.credentials.flodesk_api_key,
+
+  # Flodesk asks integrations to identify themselves in the User-Agent.
+  app_name: "<%= application_name %> (#{Rails.env})",
+
+  # Retries apply only to operations that are safe to repeat. Creating a
+  # segment, custom field or webhook, and publishing a campaign, are never
+  # retried, because repeating them would duplicate a record or send an email
+  # twice.
+  max_retries: 2
+)
+
+# Rate limits are 100 requests/minute overall and 20/minute for
+# POST /subscribers/batch. Flodesk sends no rate-limit reset header, so the gem
+# cannot guarantee staying within quota; check FLODESK.rate_limit&.remaining if
+# you need to pace a bulk job yourself.

data/sig/flodesk/client.rbs

@@ -0,0 +1,91 @@
+module Flodesk
+  # Authentication strategies. Only API-key (HTTP Basic) auth is implemented.
+  module Auth
+    class ApiKey
+      def initialize: (String) -> void
+      def apply: (untyped) -> untyped
+      def inspect: () -> String
+      def to_s: () -> String
+    end
+  end
+
+  # A completed HTTP response.
+  class Response
+    attr_reader status: Integer
+    attr_reader headers: Hash[String, untyped]
+    attr_reader body: untyped
+
+    def rate_limit: () -> Integer?
+    def rate_limit_remaining: () -> Integer?
+    # Always nil: the API sends no rate-limit reset header.
+    def rate_limit_reset: () -> nil
+  end
+
+  # Decides whether a failed request may be retried.
+  class RetryPolicy
+    attr_reader idempotent: bool
+    attr_reader retry_rate_limit: bool
+    attr_reader max_retries: Integer
+
+    def initialize: (
+      idempotent: bool, retry_rate_limit: bool, max_retries: Integer
+    ) -> void
+
+    def retry?: (Exception, Integer) -> bool
+  end
+
+  # Executes HTTP requests. Safe to share across threads.
+  class Connection
+    TIMEOUT_ERRORS: Array[Class]
+    CONNECTION_ERRORS: Array[Class]
+
+    def initialize: (Client) -> void
+
+    def request: (
+      Symbol, String,
+      ?query: Hash[String, untyped]?,
+      ?body: Hash[String, untyped]?,
+      ?idempotent: bool?,
+      ?retry_rate_limit: bool
+    ) -> Response
+  end
+
+  # Entry point to the Flodesk API. Frozen at construction.
+  class Client
+    DEFAULT_OPEN_TIMEOUT: Integer
+    DEFAULT_READ_TIMEOUT: Integer
+    DEFAULT_MAX_RETRIES: Integer
+    DEFAULT_BACKOFF_BASE: Float
+
+    attr_reader api_key: String
+    attr_reader app_name: String?
+    attr_reader base_url: String
+    attr_reader open_timeout: Numeric
+    attr_reader read_timeout: Numeric
+    attr_reader max_retries: Integer
+    attr_reader backoff_base: Numeric
+    attr_reader auth: Auth::ApiKey
+    attr_reader subscribers: Resources::Subscribers
+    attr_reader segments: Resources::Segments
+    attr_reader custom_fields: Resources::CustomFields
+    attr_reader workflows: Resources::Workflows
+    attr_reader webhooks: Resources::Webhooks
+    attr_reader campaigns: Resources::Campaigns
+
+    def initialize: (
+      ?api_key: String?,
+      ?app_name: String?,
+      ?base_url: String,
+      ?open_timeout: Numeric,
+      ?read_timeout: Numeric,
+      ?max_retries: Integer,
+      ?backoff_base: Numeric
+    ) -> void
+
+    def user_agent: () -> String
+    def rate_limit: () -> RateLimit::State?
+    def request: (*untyped, **untyped) -> Response
+    def inspect: () -> String
+    def to_s: () -> String
+  end
+end

data/sig/flodesk/errors.rbs

@@ -0,0 +1,51 @@
+module Flodesk
+  class Error < StandardError
+    def self.from_response: (
+      status: Integer, ?body: untyped, ?headers: Hash[untyped, untyped]
+    ) -> APIError
+  end
+
+  # An error carrying an HTTP response.
+  class APIError < Error
+    attr_reader status: Integer
+    attr_reader code: String?
+    attr_reader raw_body: untyped
+
+    def initialize: (
+      status: Integer, ?body: untyped, ?headers: Hash[untyped, untyped]
+    ) -> void
+
+    def rate_limit: () -> Integer?
+    def rate_limit_remaining: () -> Integer?
+  end
+
+  class BadRequestError < APIError
+  end
+
+  class AuthenticationError < APIError
+  end
+
+  class NotFoundError < APIError
+  end
+
+  class ServerError < APIError
+  end
+
+  class RateLimitError < APIError
+    # Always nil: the API sends no rate-limit reset header.
+    def retry_after: () -> nil
+  end
+
+  class ConnectionError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  # Raised when a batch operation reports per-record failures inside a 200.
+  class PartialFailureError < Error
+    attr_reader result: BatchResult
+
+    def initialize: (result: BatchResult) -> void
+  end
+end