flodesk 0.1.0

data/sig/flodesk/objects.rbs

@@ -0,0 +1,137 @@
+# Immutable response value objects.
+#
+# Every object exposes `raw` / `#to_h` returning the payload exactly as the API
+# sent it, so a field Flodesk adds is reachable without a gem release.
+module Flodesk
+  class Subscriber
+    attr_reader id: String?
+    attr_reader status: enum_value
+    attr_reader email: String?
+    attr_reader source: enum_value
+    attr_reader first_name: String?
+    attr_reader last_name: String?
+    attr_reader segments: Array[Segment]
+    attr_reader custom_fields: Hash[String, String?]
+    attr_reader optin_ip: String?
+    attr_reader optin_timestamp: timestamp
+    attr_reader created_at: timestamp
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> Subscriber?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+    def active?: () -> bool
+  end
+
+  class Segment
+    attr_reader id: String?
+    attr_reader name: String?
+    attr_reader color: String?
+    attr_reader total_active_subscribers: Integer?
+    attr_reader created_at: timestamp
+    # "static" or "dynamic"; not symbolized, as the spec declares no enum.
+    attr_reader segment_type: String?
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> Segment?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  class CustomField
+    attr_reader key: String?
+    attr_reader label: String?
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> CustomField?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  class Workflow
+    attr_reader id: String?
+    attr_reader name: String?
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> Workflow?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  class Webhook
+    attr_reader id: String?
+    attr_reader post_url: String?
+    attr_reader events: Array[String]
+    attr_reader created_at: timestamp
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> Webhook?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  class Campaign
+    attr_reader id: String?
+    attr_reader name: String?
+    attr_reader subject: String?
+    attr_reader status: enum_value
+    attr_reader created_at: timestamp
+    attr_reader updated_at: timestamp
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> Campaign?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  # A single record's failure within a batch operation.
+  class BatchItemError
+    attr_reader index: Integer?
+    attr_reader email: String?
+    attr_reader id: String?
+    attr_reader code: String?
+    attr_reader message: String?
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> BatchItemError?
+    def self.members: () -> Array[Symbol]
+    def to_h: () -> payload
+  end
+
+  # The outcome of a batch operation, which may be a partial success.
+  class BatchResult
+    attr_reader successes: Array[Subscriber]
+    attr_reader failures: Array[BatchItemError]
+    attr_reader raw: payload
+
+    def self.from: (payload?) -> BatchResult
+    def self.members: () -> Array[Symbol]
+    def success?: () -> bool
+    def size: () -> Integer
+    def failed_emails: () -> Array[String]
+    def to_h: () -> payload
+  end
+
+  # One page of a list response.
+  class Page
+    include Enumerable[untyped]
+
+    attr_reader items: Array[untyped]
+    attr_reader page: Integer?
+    attr_reader per_page: Integer?
+    attr_reader total_pages: Integer?
+    attr_reader total_items: Integer?
+    attr_reader raw: payload
+    attr_reader fetcher: ^(Integer) -> Page?
+
+    def self.from: (payload?, klass: untyped, ?fetcher: (^(Integer) -> Page?)?) -> Page
+    def self.members: () -> Array[Symbol]
+    def each: () { (untyped) -> void } -> void
+            | () -> Enumerator[untyped, void]
+    def empty?: () -> bool
+    def more_pages?: () -> bool
+    def to_h: () -> payload
+    def auto_paging_each: () { (untyped) -> void } -> void
+                        | () -> Enumerator[untyped, void]
+  end
+end

data/sig/flodesk/resources.rbs

@@ -0,0 +1,129 @@
+module Flodesk
+  module Resources
+    # Shared behavior for resource namespaces.
+    class Base
+      MAX_PER_PAGE: Integer
+      UNRESERVED: Regexp
+
+      def initialize: (Client) -> void
+    end
+
+    class Subscribers < Base
+      PATH: String
+      MAX_SEGMENTS: Integer
+      MAX_BATCH_SIZE: Integer
+
+      def list: (
+        ?page: Integer?, ?per_page: Integer?,
+        ?status: (Symbol | String)?, ?segment_id: String?
+      ) -> Page
+
+      def auto_paging_each: (
+        ?page: Integer?, ?per_page: Integer?,
+        ?status: (Symbol | String)?, ?segment_id: String?
+      ) { (Subscriber) -> void } -> void
+        | (
+        ?page: Integer?, ?per_page: Integer?,
+        ?status: (Symbol | String)?, ?segment_id: String?
+      ) -> Enumerator[Subscriber, void]
+
+      def retrieve: (String) -> Subscriber?
+      def upsert: (**untyped) -> Subscriber?
+      def batch_upsert: (
+        Array[Hash[untyped, untyped]], ?raise_on_failure: bool
+      ) -> BatchResult
+      def add_to_segments: (String, Array[String]) -> Subscriber?
+      def remove_from_segments: (String, Array[String]) -> Subscriber?
+      def unsubscribe: (String) -> Subscriber?
+    end
+
+    class Segments < Base
+      PATH: String
+
+      def list: (?page: Integer?, ?per_page: Integer?) -> Page
+      def auto_paging_each: (?page: Integer?, ?per_page: Integer?) { (Segment) -> void } -> void
+                          | (?page: Integer?, ?per_page: Integer?) -> Enumerator[Segment, void]
+      def retrieve: (String) -> Segment?
+      def create: (name: String, ?color: String?) -> Segment?
+      def colors: () -> untyped
+    end
+
+    class CustomFields < Base
+      PATH: String
+
+      def list: (?page: Integer?, ?per_page: Integer?) -> Page
+      def auto_paging_each: (?page: Integer?, ?per_page: Integer?) { (CustomField) -> void } -> void
+                          | (?page: Integer?, ?per_page: Integer?) -> Enumerator[CustomField, void]
+      def list_all: () -> Array[CustomField]
+      def create: (label: String) -> CustomField?
+    end
+
+    class Workflows < Base
+      PATH: String
+      # This endpoint alone spells its page-size parameter `perPage`.
+      PER_PAGE_KEY: String
+
+      def list: (
+        ?page: Integer?, ?per_page: Integer?,
+        ?statuses: (String | Symbol | Array[String | Symbol])?
+      ) -> Page
+
+      def auto_paging_each: (
+        ?page: Integer?, ?per_page: Integer?,
+        ?statuses: (String | Symbol | Array[String | Symbol])?
+      ) { (Workflow) -> void } -> void
+        | (
+        ?page: Integer?, ?per_page: Integer?,
+        ?statuses: (String | Symbol | Array[String | Symbol])?
+      ) -> Enumerator[Workflow, void]
+
+      # Returns nil: the endpoint responds 204.
+      def add_subscriber: (String, ?id: String?, ?email: String?) -> nil
+      # Returns nil: the endpoint responds 204.
+      def remove_subscriber: (String, String) -> nil
+    end
+
+    class Webhooks < Base
+      PATH: String
+
+      def list: (?page: Integer?, ?per_page: Integer?) -> Page
+      def auto_paging_each: (?page: Integer?, ?per_page: Integer?) { (Webhook) -> void } -> void
+                          | (?page: Integer?, ?per_page: Integer?) -> Enumerator[Webhook, void]
+      def retrieve: (String) -> Webhook?
+      def create: (
+        name: String, post_url: String, events: (String | Array[String])
+      ) -> Webhook?
+      def update: (
+        String, ?name: String?, ?post_url: String?,
+        ?events: (String | Array[String])?
+      ) -> Webhook?
+      # Returns nil: the endpoint responds 204.
+      def delete: (String) -> nil
+    end
+
+    class Campaigns < Base
+      PATH: String
+      # This endpoint's filters are PascalCase, unlike anything else in the API.
+      FILTER_KEYS: Hash[Symbol, String]
+
+      def list: (?page: Integer?, ?per_page: Integer?, **untyped) -> Page
+      def auto_paging_each: (
+        ?page: Integer?, ?per_page: Integer?, **untyped
+      ) { (Campaign) -> void } -> void
+        | (?page: Integer?, ?per_page: Integer?, **untyped) -> Enumerator[Campaign, void]
+
+      # NEVER retried: a retry could send the campaign to the whole list twice.
+      def publish_canva: (
+        ?bundle_url: String?, ?title: String?, ?design_token: String?,
+        ?page_id: String?, ?campaign_id: String?
+      ) -> untyped
+
+      # NEVER retried, for the same reason as publish_canva.
+      def publish_studio: (
+        ?html: String?, ?title: String?, ?campaign_id: String?, ?asset_id: String?
+      ) -> untyped
+
+      def canva_design_state: () -> untyped
+    end
+  end
+end

data/sig/flodesk/webhooks.rbs

@@ -0,0 +1,57 @@
+module Flodesk
+  # Handling of inbound webhook deliveries.
+  #
+  # Flodesk signs nothing, so a verification strategy is mandatory.
+  module Webhooks
+    STRATEGIES: Array[Symbol]
+
+    class VerificationError < Error
+      def initialize: (?String) -> void
+    end
+
+    class InvalidPayloadError < Error
+    end
+
+    module Verification
+      MIN_TOKEN_LENGTH: Integer
+      TOKEN_BYTES: Integer
+
+      def self.generate_token: () -> String
+      def self.secure_compare: (String?, String?) -> bool
+    end
+
+    # A verified inbound webhook event.
+    class Event
+      attr_reader event_name: String?
+      attr_reader event_time: timestamp
+      attr_reader subscriber: Subscriber?
+      attr_reader segment: Segment?
+      attr_reader webhook_id: String?
+      attr_reader raw: payload
+
+      def self.from: (payload, ?subscriber: Subscriber?) -> Event
+      def self.members: () -> Array[Symbol]
+      def to_h: () -> payload
+      def known?: () -> bool
+      # SHA-256 of the composed identity, since events carry no unique id.
+      def dedupe_key: () -> String
+      def inspect: () -> String
+      def to_s: () -> String
+    end
+
+    class Handler
+      def self.generate_token: () -> String
+
+      def initialize: (
+        ?token: String?, ?verify: Symbol?, ?client: Client?
+      ) -> void
+
+      def call: (body: String?, ?token: String?) -> Event
+
+      # Returns a Rack triple: [status, headers, body].
+      def respond: (
+        body: String?, ?token: String?, ?on_error: (^(Exception) -> void)?
+      ) ?{ (Event) -> void } -> [Integer, Hash[String, String], Array[String]]
+    end
+  end
+end

data/sig/flodesk.rbs

@@ -0,0 +1,61 @@
+# Core module, configuration constants, and shared type aliases.
+module Flodesk
+  VERSION: String
+  DEFAULT_BASE_URL: String
+  MAX_BACKOFF_SECONDS: Integer
+
+  # A parsed JSON object as received from the API.
+  type payload = Hash[String, untyped]
+
+  # An enum value: a Symbol when documented, otherwise the raw String.
+  type enum_value = Symbol | String | nil
+
+  # An ISO 8601 timestamp: a Time when parseable, otherwise the raw String.
+  type timestamp = Time | String | nil
+
+  # Closed enumerations documented by the API description.
+  module Enums
+    SUBSCRIBER_STATUSES: Array[String]
+    SUBSCRIBER_SOURCES: Array[String]
+    WORKFLOW_STATUSES: Array[String]
+    CAMPAIGN_STATUSES: Array[String]
+    WEBHOOK_EVENTS: Array[String]
+  end
+
+  module Coercion
+    def self.enum: (untyped, Array[String]) -> enum_value
+    def self.time: (untyped) -> timestamp
+    def self.array_of: (untyped, untyped) -> Array[untyped]
+    def self.string_hash: (untyped) -> Hash[String, String?]
+    def self.snapshot: (untyped) -> untyped
+  end
+
+  module Redaction
+    SENSITIVE_KEYS: Array[String]
+    PLACEHOLDER: String
+    EMAIL_IN_SEGMENT: Regexp
+
+    def self.path: (untyped) -> String
+    def self.payload: (untyped) -> untyped
+  end
+
+  module Instrumentation
+    EVENT_NAME: String
+
+    def self.available?: () -> bool
+    def self.request: (
+      method: Symbol, path: String, status: Integer,
+      duration: Float, attempt: Integer, rate_limit_remaining: Integer?
+    ) -> void
+  end
+
+  module RateLimit
+    class State
+      attr_reader limit: Integer?
+      attr_reader remaining: Integer?
+    end
+
+    def self.record: (Client, Response) -> void
+    def self.last: (Client) -> State?
+  end
+end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: flodesk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jim
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  A dependency-free Ruby client for the Flodesk API, built for Rails apps.
+  Covers subscribers, segments, custom fields, workflows, webhooks and
+  campaigns, and hides the API's rough edges: non-uniform pagination
+  parameters, batch responses that report partial failure inside a 200, and
+  per-endpoint retry safety.
+email:
+- jim@mymat.yoga
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/flodesk.rb
+- lib/flodesk/auth.rb
+- lib/flodesk/client.rb
+- lib/flodesk/coercion.rb
+- lib/flodesk/connection.rb
+- lib/flodesk/enums.rb
+- lib/flodesk/errors.rb
+- lib/flodesk/instrumentation.rb
+- lib/flodesk/objects/batch_item_error.rb
+- lib/flodesk/objects/batch_result.rb
+- lib/flodesk/objects/campaign.rb
+- lib/flodesk/objects/custom_field.rb
+- lib/flodesk/objects/page.rb
+- lib/flodesk/objects/segment.rb
+- lib/flodesk/objects/subscriber.rb
+- lib/flodesk/objects/webhook.rb
+- lib/flodesk/objects/workflow.rb
+- lib/flodesk/rails.rb
+- lib/flodesk/rails/railtie.rb
+- lib/flodesk/rate_limit.rb
+- lib/flodesk/redaction.rb
+- lib/flodesk/resources/base.rb
+- lib/flodesk/resources/campaigns.rb
+- lib/flodesk/resources/custom_fields.rb
+- lib/flodesk/resources/segments.rb
+- lib/flodesk/resources/subscribers.rb
+- lib/flodesk/resources/webhooks.rb
+- lib/flodesk/resources/workflows.rb
+- lib/flodesk/response.rb
+- lib/flodesk/retry_policy.rb
+- lib/flodesk/test_helpers.rb
+- lib/flodesk/version.rb
+- lib/flodesk/webhooks/event.rb
+- lib/flodesk/webhooks/handler.rb
+- lib/flodesk/webhooks/verification.rb
+- lib/generators/flodesk/install_generator.rb
+- lib/generators/flodesk/templates/initializer.rb.tt
+- sig/flodesk.rbs
+- sig/flodesk/client.rbs
+- sig/flodesk/errors.rbs
+- sig/flodesk/objects.rbs
+- sig/flodesk/resources.rbs
+- sig/flodesk/webhooks.rbs
+homepage: https://github.com/mymat-yoga/flodesk-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mymat-yoga/flodesk-rb
+  source_code_uri: https://github.com/mymat-yoga/flodesk-rb
+  changelog_uri: https://github.com/mymat-yoga/flodesk-rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Ruby client for the Flodesk API
+test_files: []