mailfloss 0.1.0

data/lib/mailfloss/resources.rb

@@ -0,0 +1,294 @@
+# frozen_string_literal: true
+
+module Mailfloss
+  module Resources
+    # @api private
+    class Base
+      def initialize(client)
+        @client = client
+      end
+
+      private
+
+      attr_reader :client
+
+      def encode(segment)
+        URI.encode_www_form_component(segment.to_s)
+      end
+    end
+
+    # POST /batch-verify and its sub-resources.
+    class BatchVerify < Base
+      # POST /batch-verify — submit a batch of emails for verification.
+      #
+      # @param emails [Array<String>]
+      # @param webhook_url [String, nil] optional completion callback URL
+      # @param idempotency_key [String, nil] auto-generated when omitted
+      # @return [Hash] { id: } — the created batch job id
+      def create(emails:, webhook_url: nil, idempotency_key: nil)
+        body = { emails: emails }
+        body[:webhook_url] = webhook_url if webhook_url
+        client.request(:post, "/batch-verify", body: body, idempotency_key: idempotency_key)
+      end
+
+      # GET /batch-verify/{id}/status
+      #
+      # @return [Hash] { status:, progress: }
+      def status(id)
+        client.request(:get, "/batch-verify/#{encode(id)}/status")
+      end
+
+      # GET /batch-verify/{id}/results
+      #
+      # @param per_page [Integer, nil]
+      # @param next_cursor [String, nil] the `next` query param
+      # @return [Hash] { id:, results: [...] }
+      def results(id, per_page: nil, next_cursor: nil)
+        client.request(:get, "/batch-verify/#{encode(id)}/results",
+                       query: { per_page: per_page, next: next_cursor })
+      end
+
+      # POST /batch-verify/{id}/cancel
+      #
+      # @return [Hash] { success: }
+      def cancel(id, idempotency_key: nil)
+        client.request(:post, "/batch-verify/#{encode(id)}/cancel", idempotency_key: idempotency_key)
+      end
+    end
+
+    # GET /jobs
+    class Jobs < Base
+      # GET /jobs — cursor-paginated job history.
+      #
+      # @param per_page [Integer, nil]
+      # @param cursor [String, nil]
+      # @param source [String, nil] api|csv|zapier|widget|input|integration
+      # @param status [String, nil] queued|processing|completed|cancelled
+      # @return [Hash] { data: [Job], pagination: { next_cursor:, has_more: } }
+      def list(per_page: nil, cursor: nil, source: nil, status: nil)
+        client.request(:get, "/jobs",
+                       query: { per_page: per_page, cursor: cursor, source: source, status: status })
+      end
+
+      # GET /jobs/{id}
+      #
+      # @return [Hash] { id:, status:, source:, source_integration:,
+      #                  created_at:, finished_at:, results: }
+      def get(id)
+        client.request(:get, "/jobs/#{encode(id)}")
+      end
+    end
+
+    # GET /users
+    class Users < Base
+      # GET /users — organization members.
+      #
+      # @return [Hash] { data: [User], pagination: { next_cursor:, has_more: } }
+      def list(per_page: nil, cursor: nil)
+        client.request(:get, "/users", query: { per_page: per_page, cursor: cursor })
+      end
+
+      # GET /users/{user_id}
+      #
+      # @return [Hash] { id:, email:, name:, role:, is_primary:, status:, created_at: }
+      def get(user_id)
+        client.request(:get, "/users/#{encode(user_id)}")
+      end
+    end
+
+    # GET /reports/*
+    class Reports < Base
+      # GET /reports/usage — verification usage report.
+      #
+      # @param period [String, nil] this_week|this_month|this_year|lifetime
+      # @param connection_id [String, nil] scope to one ESP connection
+      # @return [Hash] { period:, connection_id:, range:, total:, statuses:, reasons: }
+      def usage(period: nil, connection_id: nil)
+        client.request(:get, "/reports/usage",
+                       query: { period: period, connection_id: connection_id })
+      end
+    end
+
+    # GET/PATCH /account
+    class Account < Base
+      # GET /account — the authenticated account holder.
+      def get
+        client.request(:get, "/account")
+      end
+
+      # PATCH /account — update writable account & settings fields.
+      # Only the provided keys are sent.
+      #
+      # @param name [String, nil]
+      # @param organization [String, nil]
+      # @param phone [String, nil]
+      # @param vat_id [String, nil]
+      # @param country [String, nil]
+      # @param address [Hash, nil] partial { line1:, line2:, city:, state:, postal_code:, country: }
+      # @param notifications [Hash, nil] partial { after_flossing:, weekly_report:,
+      #   monthly_report:, payment_receipts: }
+      # @return [Hash] the full updated account (same shape as #get)
+      def update(name: :__omit__, organization: :__omit__, phone: :__omit__, vat_id: :__omit__,
+                 country: :__omit__, address: :__omit__, notifications: :__omit__)
+        body = {}
+        body[:name] = name unless name == :__omit__
+        body[:organization] = organization unless organization == :__omit__
+        body[:phone] = phone unless phone == :__omit__
+        body[:vat_id] = vat_id unless vat_id == :__omit__
+        body[:country] = country unless country == :__omit__
+        body[:address] = address unless address == :__omit__
+        body[:notifications] = notifications unless notifications == :__omit__
+        client.request(:patch, "/account", body: body)
+      end
+    end
+
+    # GET /organization
+    class Organization < Base
+      # GET /organization — plan, credits, usage, trial and entitlements.
+      def get
+        client.request(:get, "/organization")
+      end
+    end
+
+    # GET /integrations and nested connections/keywords.
+    class Integrations < Base
+      # GET /integrations — all supported ESPs with connection state.
+      #
+      # @return [Hash] { data: [Integration], pagination: { next_cursor:, has_more: } }
+      def list(per_page: nil, cursor: nil)
+        client.request(:get, "/integrations", query: { per_page: per_page, cursor: cursor })
+      end
+
+      # GET /integrations/{type} — detail for a single ESP.
+      #
+      # @return [Hash] { type:, connected:, connection_count:, connections:,
+      #                  disconnected_connections: }
+      def get(type)
+        client.request(:get, "/integrations/#{encode(type)}")
+      end
+
+      def connections
+        @connections ||= Connections.new(client)
+      end
+
+      def keywords
+        @keywords ||= Keywords.new(client)
+      end
+    end
+
+    # /integrations/{type}/connections/*
+    class Connections < Base
+      # POST /integrations/{type}/connections — connect an ESP account.
+      #
+      # @param type [String] ESP slug (e.g. "klaviyo")
+      # @param credentials [Hash] per-ESP credential shape (e.g. { api_key: "..." })
+      # @param name [String, nil] optional display name
+      # @return [Hash] the created connection { id:, name:, status:, created_at:,
+      #                last_synced_at:, settings: }
+      def create(type, credentials:, name: nil, idempotency_key: nil)
+        body = { credentials: credentials }
+        body[:name] = name if name
+        client.request(:post, "/integrations/#{encode(type)}/connections",
+                       body: body, idempotency_key: idempotency_key)
+      end
+
+      # GET /integrations/{type}/connections/{id}
+      def get(type, id)
+        client.request(:get, "/integrations/#{encode(type)}/connections/#{encode(id)}")
+      end
+
+      # PATCH /integrations/{type}/connections/{id} — update floss settings.
+      #
+      # @param aggressiveness [String, nil] normal|aggressive|custom
+      # @param manual_mode [Boolean, nil]
+      # @param autofloss [Boolean, nil]
+      # @param decay_protection [Boolean, nil]
+      # @param action [String, nil] unsubscribe|delete|update_tags|update_custom_fields|do_nothing
+      # @param checks [Hash, nil] partial map of the 12 check gates
+      # @return [Hash] the updated connection
+      def update(type, id, aggressiveness: nil, manual_mode: nil, autofloss: nil,
+                 decay_protection: nil, action: nil, checks: nil)
+        body = {}
+        body[:aggressiveness] = aggressiveness unless aggressiveness.nil?
+        body[:manual_mode] = manual_mode unless manual_mode.nil?
+        body[:autofloss] = autofloss unless autofloss.nil?
+        body[:decay_protection] = decay_protection unless decay_protection.nil?
+        body[:action] = action unless action.nil?
+        body[:checks] = checks unless checks.nil?
+        client.request(:patch, "/integrations/#{encode(type)}/connections/#{encode(id)}", body: body)
+      end
+
+      # DELETE /integrations/{type}/connections/{id} — disconnect (soft-disable).
+      #
+      # @return [Hash] { id:, type:, status:, disconnected_at: }
+      def delete(type, id)
+        client.request(:delete, "/integrations/#{encode(type)}/connections/#{encode(id)}")
+      end
+
+      # POST /integrations/{type}/connections/{id}/sync — trigger a sync.
+      #
+      # @return [Hash] the connection after the sync was queued
+      def sync(type, id, idempotency_key: nil)
+        client.request(:post, "/integrations/#{encode(type)}/connections/#{encode(id)}/sync",
+                       idempotency_key: idempotency_key)
+      end
+
+      # POST /integrations/{type}/connections/{id}/test — test stored credentials.
+      #
+      # @return [Hash] { id:, type:, credential_valid:, tested_at:, reason: }
+      def test(type, id, idempotency_key: nil)
+        client.request(:post, "/integrations/#{encode(type)}/connections/#{encode(id)}/test",
+                       idempotency_key: idempotency_key)
+      end
+    end
+
+    # /integrations/{type}/connections/{id}/keywords/{list}*
+    class Keywords < Base
+      # GET .../keywords/{list} — list keyword rules (blacklist or whitelist).
+      #
+      # @param list [String] "blacklist" or "whitelist"
+      # @return [Hash] { data: [Rule], pagination: { next_cursor:, has_more: } }
+      def list(type, id, list, per_page: nil, cursor: nil)
+        client.request(:get, keywords_path(type, id, list),
+                       query: { per_page: per_page, cursor: cursor })
+      end
+
+      # POST .../keywords/{list} — add keyword rules (1-1000, all-or-nothing).
+      #
+      # @param rules [Array<Hash>] each { keyword:, match: "exact"|"contains",
+      #   applies_to: { localpart:, domain:, email: } }
+      # @return [Hash] { data: [Rule] } — the created rules with ids
+      def add(type, id, list, rules:, idempotency_key: nil)
+        client.request(:post, keywords_path(type, id, list),
+                       body: { rules: rules }, idempotency_key: idempotency_key)
+      end
+
+      # DELETE .../keywords/{list}/{ruleId} — remove a keyword rule.
+      #
+      # @return [Hash] { deleted:, id: }
+      def delete(type, id, list, rule_id)
+        client.request(:delete, "#{keywords_path(type, id, list)}/#{encode(rule_id)}")
+      end
+
+      private
+
+      def keywords_path(type, id, list)
+        "/integrations/#{encode(type)}/connections/#{encode(id)}/keywords/#{encode(list)}"
+      end
+    end
+
+    # POST /erasures
+    class Erasures < Base
+      # POST /erasures — GDPR/CCPA delete-my-data requests.
+      #
+      # @param emails [Array<String>] addresses to erase
+      # @param webhook_url [String, nil] optional completion callback URL
+      # @return [Hash] { success: }
+      def create(emails:, webhook_url: nil, idempotency_key: nil)
+        body = { emails: emails }
+        body[:webhook_url] = webhook_url if webhook_url
+        client.request(:post, "/erasures", body: body, idempotency_key: idempotency_key)
+      end
+    end
+  end
+end

data/lib/mailfloss/transport.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Mailfloss
+  # Low-level HTTP transport. Any object that responds to
+  # +call(method, url, headers, body)+ and returns an object with
+  # +status+, +headers+ and +body+ (or an equivalent Hash) can be injected
+  # into Mailfloss::Client via the +transport:+ kwarg — this is the seam
+  # used by the test suite.
+  class Transport
+    Response = Struct.new(:status, :headers, :body)
+
+    # Errors considered transient connection failures (retried by the client).
+    CONNECTION_ERRORS = [
+      Errno::ECONNREFUSED,
+      Errno::ECONNRESET,
+      Errno::EHOSTUNREACH,
+      Errno::ETIMEDOUT,
+      Errno::EPIPE,
+      SocketError,
+      EOFError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      OpenSSL::SSL::SSLError
+    ].freeze
+
+    def initialize(timeout: 30)
+      @timeout = timeout
+    end
+
+    # @param method [Symbol] :get, :post, :patch, :delete
+    # @param url    [String] absolute URL (query string already appended)
+    # @param headers [Hash{String => String}]
+    # @param body   [String, nil] already-serialized request body
+    # @return [Response]
+    def call(method, url, headers, body)
+      uri = URI.parse(url)
+      request = build_request(method, uri, headers, body)
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout
+      http.read_timeout = @timeout
+      http.write_timeout = @timeout if http.respond_to?(:write_timeout=)
+
+      response = http.start { |conn| conn.request(request) }
+
+      response_headers = {}
+      response.each_header { |key, value| response_headers[key.downcase] = value }
+
+      Response.new(response.code.to_i, response_headers, response.body)
+    end
+
+    private
+
+    def build_request(method, uri, headers, body)
+      klass = case method
+              when :get then Net::HTTP::Get
+              when :post then Net::HTTP::Post
+              when :patch then Net::HTTP::Patch
+              when :delete then Net::HTTP::Delete
+              else
+                raise ArgumentError, "Unsupported HTTP method: #{method.inspect}"
+              end
+      request = klass.new(uri.request_uri)
+      headers.each { |key, value| request[key] = value }
+      request.body = body if body
+      request
+    end
+  end
+end

data/lib/mailfloss/version.rb

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

data/lib/mailfloss.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "json"
+
+require_relative "mailfloss/version"
+require_relative "mailfloss/errors"
+require_relative "mailfloss/transport"
+require_relative "mailfloss/resources"
+require_relative "mailfloss/client"
+
+# Official Ruby SDK for the mailfloss email verification API.
+# https://developers.mailfloss.com
+module Mailfloss
+end

data/sig/mailfloss.rbs

@@ -0,0 +1,77 @@
+module Mailfloss
+  VERSION: String
+
+  class Error < StandardError
+  end
+
+  class ConfigurationError < Error
+  end
+
+  class APIError < Error
+    attr_reader status: Integer
+    attr_reader code: String
+    attr_reader type: String?
+    attr_reader request_id: String?
+
+    def initialize: (status: Integer, ?body: String?) -> void
+  end
+
+  class Transport
+    class Response < Struct[untyped]
+      attr_accessor status: Integer
+      attr_accessor headers: Hash[String, String]
+      attr_accessor body: String?
+    end
+
+    CONNECTION_ERRORS: Array[Class]
+
+    def initialize: (?timeout: Numeric) -> void
+
+    def call: (Symbol method, String url, Hash[String, String] headers, String? body) -> Response
+  end
+
+  # Duck type for injectable transports: anything with
+  # call(method, url, headers, body) returning status/headers/body.
+  interface _Transport
+    def call: (Symbol method, String url, Hash[String, String] headers, String? body) -> untyped
+  end
+
+  interface _Sleeper
+    def call: (Numeric seconds) -> void
+  end
+
+  class Client
+    DEFAULT_BASE_URL: String
+    DEFAULT_MAX_RETRIES: Integer
+    DEFAULT_TIMEOUT: Integer
+    RETRY_BASE_DELAY: Float
+    RETRY_MAX_DELAY: Float
+    USER_AGENT: String
+
+    attr_reader base_url: String
+    attr_reader max_retries: Integer
+    attr_reader timeout: Numeric
+
+    def initialize: (?api_key: String?, ?base_url: String, ?max_retries: Integer,
+                     ?timeout: Numeric, ?transport: _Transport?, ?sleeper: _Sleeper?) -> void
+
+    # GET /verify
+    def verify: (email: String, ?timeout: (Numeric | String)?) -> Types::verify_result
+
+    # GET /check-key
+    def check_key: (?api_key: String?, ?public_key: String?, ?check_plan: boolish?,
+                    ?get_token: boolish?, ?check_credits: boolish?) -> Types::check_key_result
+
+    def batch_verify: () -> Resources::BatchVerify
+    def jobs: () -> Resources::Jobs
+    def users: () -> Resources::Users
+    def reports: () -> Resources::Reports
+    def account: () -> Resources::Account
+    def organization: () -> Resources::Organization
+    def integrations: () -> Resources::Integrations
+    def erasures: () -> Resources::Erasures
+
+    def request: (Symbol method, String path, ?query: Hash[Symbol, untyped]?,
+                  ?body: Hash[Symbol, untyped]?, ?idempotency_key: String?) -> untyped
+  end
+end

data/sig/resources.rbs

@@ -0,0 +1,85 @@
+module Mailfloss
+  module Resources
+    class Base
+      def initialize: (Client client) -> void
+
+      private
+
+      attr_reader client: Client
+
+      def encode: (untyped segment) -> String
+    end
+
+    class BatchVerify < Base
+      def create: (emails: Array[String], ?webhook_url: String?,
+                   ?idempotency_key: String?) -> Types::batch_create_result
+      def status: (String id) -> Types::batch_status_result
+      def results: (String id, ?per_page: Integer?, ?next_cursor: String?) -> Types::batch_results_result
+      def cancel: (String id, ?idempotency_key: String?) -> Types::batch_cancel_result
+    end
+
+    class Jobs < Base
+      def list: (?per_page: Integer?, ?cursor: String?, ?source: String?,
+                 ?status: String?) -> Types::jobs_list
+      def get: (String id) -> Types::job
+    end
+
+    class Users < Base
+      def list: (?per_page: Integer?, ?cursor: String?) -> Types::users_list
+      def get: (String user_id) -> Types::user
+    end
+
+    class Reports < Base
+      def usage: (?period: String?, ?connection_id: String?) -> Types::usage_report
+    end
+
+    class Account < Base
+      def get: () -> Types::account
+      def update: (?name: String?, ?organization: String?, ?phone: String?,
+                   ?vat_id: String?, ?country: String?,
+                   ?address: Hash[Symbol, String?]?,
+                   ?notifications: Hash[Symbol, bool]?) -> Types::account
+    end
+
+    class Organization < Base
+      def get: () -> Types::organization
+    end
+
+    class Integrations < Base
+      def list: (?per_page: Integer?, ?cursor: String?) -> Types::integrations_list
+      def get: (String type) -> Types::integration_detail
+      def connections: () -> Connections
+      def keywords: () -> Keywords
+    end
+
+    class Connections < Base
+      def create: (String type, credentials: Hash[Symbol, String], ?name: String?,
+                   ?idempotency_key: String?) -> Types::connection
+      def get: (String type, String id) -> Types::connection
+      def update: (String type, String id, ?aggressiveness: String?,
+                   ?manual_mode: bool?, ?autofloss: bool?, ?decay_protection: bool?,
+                   ?action: String?, ?checks: Hash[Symbol, bool]?) -> Types::connection
+      def delete: (String type, String id) -> Types::disconnect_result
+      def sync: (String type, String id, ?idempotency_key: String?) -> Types::connection
+      def test: (String type, String id, ?idempotency_key: String?) -> Types::credential_test_result
+    end
+
+    class Keywords < Base
+      def list: (String type, String id, String list, ?per_page: Integer?,
+                 ?cursor: String?) -> Types::keyword_rules_list
+      def add: (String type, String id, String list,
+                rules: Array[Types::keyword_rule_input],
+                ?idempotency_key: String?) -> Types::keyword_rules_created
+      def delete: (String type, String id, String list, String rule_id) -> Types::keyword_rule_deleted
+
+      private
+
+      def keywords_path: (String type, String id, String list) -> String
+    end
+
+    class Erasures < Base
+      def create: (emails: Array[String], ?webhook_url: String?,
+                   ?idempotency_key: String?) -> Types::erasure_result
+    end
+  end
+end