lettermint 0.1.0 → 0.2.1

data/lib/lettermint/http_client.rb

@@ -4,7 +4,7 @@ require 'faraday'
 
 module Lettermint
   class HttpClient
-    def initialize(api_token:, base_url:, timeout:)
+    def initialize(api_token:, base_url:, timeout:, auth_scheme: :project)
       normalized_url = "#{base_url.chomp('/')}/"
       @connection = Faraday.new(url: normalized_url) do |f|
         f.request :json
@@ -14,7 +14,7 @@ module Lettermint
         f.headers = {
           'Content-Type' => 'application/json',
           'Accept' => 'application/json',
-          'x-lettermint-token' => api_token,
+          **auth_headers(api_token, auth_scheme),
           'User-Agent' => "Lettermint/#{Lettermint::VERSION} (Ruby; ruby #{RUBY_VERSION})"
         }
       end
@@ -57,46 +57,67 @@ module Lettermint
 
     private
 
+    def auth_headers(token, scheme)
+      case scheme.to_sym
+      when :project then { 'x-lettermint-token' => token }
+      when :team    then { 'Authorization' => "Bearer #{token}" }
+      else raise ArgumentError, "Unknown auth_scheme: #{scheme}"
+      end
+    end
+
     def with_error_handling
       response = yield
       handle_response(response)
     rescue Faraday::TimeoutError, Timeout::Error
       raise Lettermint::TimeoutError, "Request timeout after #{@connection.options.timeout}s"
+    rescue Faraday::SSLError => e
+      raise Lettermint::ConnectionError.new(message: "SSL error: #{e.message}", original_exception: e)
     rescue Faraday::ConnectionFailed => e
-      raise Lettermint::Error, e.message
+      raise Lettermint::ConnectionError.new(message: e.message, original_exception: e)
+    rescue Faraday::ParsingError => e
+      raise Lettermint::ResponseParsingError.new(message: "API response parsing failed: #{e.message}",
+                                                 original_exception: e)
     end
 
     def handle_response(response)
       return response.body if response.success?
 
-      body = response.body.is_a?(Hash) ? response.body : nil
-      raise_api_error(response.status, body, response.headers)
+      raise build_error(response.status, normalize_body(response.body), response.headers)
     end
 
-    def raise_api_error(status, body, headers)
-      raise build_error(status, body, headers)
+    # Hash stays Hash; String is stripped (nil when empty); anything else passes through as parsed.
+    def normalize_body(body)
+      return body unless body.is_a?(String)
+
+      stripped = body.strip
+      stripped.empty? ? nil : stripped
     end
 
-    def build_error(status, body, headers) # rubocop:disable Metrics
-      msg = ->(key, fallback) { body&.dig(key) || fallback }
+    def build_error(status, body, headers)
+      message, code, details = ErrorBody.parse(status, body)
+      common = { message: message, response_body: body, code: code, details: details }
 
       case status
-      when 401, 403
-        AuthenticationError.new(message: msg['message', "HTTP #{status}"],
-                                status_code: status, response_body: body)
-      when 400
-        ClientError.new(message: msg['error', 'Unknown client error'], response_body: body)
-      when 422
-        ValidationError.new(message: msg['message', 'Validation error'],
-                            error_type: msg['error', 'ValidationError'], response_body: body)
-      when 429
-        retry_after = headers && headers['Retry-After'] && Integer(headers['Retry-After'], exception: false)
-        RateLimitError.new(message: msg['message', 'Rate limit exceeded'],
-                           retry_after: retry_after, response_body: body)
-      else
-        HttpRequestError.new(message: msg['message', "HTTP #{status}"],
-                             status_code: status, response_body: body)
+      when 401, 403 then AuthenticationError.new(status_code: status, **common)
+      when 400 then ClientError.new(**common)
+      when 404 then NotFoundError.new(**common)
+      when 422 then ValidationError.new(error_type: validation_error_type(body, code), **common)
+      when 429 then RateLimitError.new(retry_after: retry_after_from(headers), **common)
+      else HttpRequestError.new(status_code: status, **common)
       end
     end
+
+    # A String `error` is kept verbatim; a Hash `error` contributes its code.
+    def validation_error_type(body, code)
+      error = body.is_a?(Hash) ? body['error'] : nil
+      return error if error.is_a?(String)
+
+      code || 'ValidationError'
+    end
+
+    def retry_after_from(headers)
+      value = headers && headers['Retry-After']
+      value && Integer(value, exception: false)
+    end
   end
 end

data/lib/lettermint/resources/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Base class for Team API resources providing shared functionality.
+    class Base
+      def initialize(http_client:)
+        @http_client = http_client
+      end
+
+      private
+
+      # Builds query parameters for list endpoints.
+      # @param page_size [Integer, nil] Number of items per page
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field (prefix with - for descending)
+      # @param include [String, nil] Related resources to include
+      # @param filters [Hash] Filter parameters (converted to filter[key]=value)
+      # @return [Hash, nil] Query parameters hash or nil if empty
+      def build_params(page_size: nil, page_cursor: nil, sort: nil, include: nil, **filters)
+        params = {
+          'page[size]' => page_size,
+          'page[cursor]' => page_cursor,
+          'sort' => sort,
+          'include' => include
+        }.compact
+
+        filters.each { |k, v| params["filter[#{k}]"] = v unless v.nil? }
+        params.empty? ? nil : params
+      end
+    end
+  end
+end

data/lib/lettermint/resources/domains.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Domains resource for managing sending domains and DNS verification.
+    class Domains < Base
+      # List all domains.
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: domain, created_at, status_changed_at (prefix - for desc)
+      # @param status [String, nil] Filter by status (verified, partially_verified, etc.)
+      # @param domain [String, nil] Filter by domain (partial match)
+      # @return [Hash] Paginated list of domains
+      def list(page_size: nil, page_cursor: nil, sort: nil, status: nil, domain: nil)
+        params = build_params(page_size:, page_cursor:, sort:, status:, domain:)
+        @http_client.get(path: '/domains', params: params)
+      end
+
+      # Create a new domain.
+      # @param domain [String] Domain name (max 255 chars)
+      # @return [Hash] Created domain data
+      def create(domain:)
+        @http_client.post(path: '/domains', data: { domain: domain })
+      end
+
+      # Get domain details.
+      # @param id [String] Domain ID
+      # @param include [String, nil] Related data to include (dnsRecords, dnsRecordsCount, dnsRecordsExists)
+      # @return [Hash] Domain data with optional includes
+      def find(id, include: nil)
+        params = build_params(include: include)
+        @http_client.get(path: "/domains/#{id}", params: params)
+      end
+
+      # Delete a domain.
+      # @param id [String] Domain ID
+      # @return [Hash] Confirmation message
+      def delete(id)
+        @http_client.delete(path: "/domains/#{id}")
+      end
+
+      # Verify all DNS records for a domain.
+      # @param id [String] Domain ID
+      # @return [Hash] Verification result
+      def verify_dns(id)
+        @http_client.post(path: "/domains/#{id}/dns-records/verify")
+      end
+
+      # Verify a specific DNS record.
+      # @param domain_id [String] Domain ID
+      # @param record_id [String] DNS record ID
+      # @return [Hash] Verification result
+      def verify_dns_record(domain_id, record_id)
+        @http_client.post(path: "/domains/#{domain_id}/dns-records/#{record_id}/verify")
+      end
+
+      # Update projects associated with a domain.
+      # @param id [String] Domain ID
+      # @param project_ids [Array<String>] Array of project UUIDs
+      # @return [Hash] Updated domain data
+      def update_projects(id, project_ids:)
+        @http_client.put(path: "/domains/#{id}/projects", data: { project_ids: project_ids })
+      end
+    end
+  end
+end

data/lib/lettermint/resources/messages.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Messages resource for viewing sent and received messages.
+    class Messages < Base
+      # List messages.
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: type, status, from_email, subject, created_at, status_changed_at
+      # @param type [String, nil] Filter: inbound, outbound
+      # @param status [String, nil] Filter by status
+      # @param route_id [String, nil] Filter by route ID
+      # @param domain_id [String, nil] Filter by domain ID
+      # @param tag [String, nil] Filter by tag
+      # @param from_email [String, nil] Filter by sender email
+      # @param subject [String, nil] Filter by subject
+      # @param from_date [String, nil] Filter from date (Y-m-d)
+      # @param to_date [String, nil] Filter to date (Y-m-d)
+      # @return [Hash] Paginated list of messages
+      # rubocop:disable-next Metrics/ParameterLists
+      def list(page_size: nil, page_cursor: nil, sort: nil, type: nil, status: nil,
+               route_id: nil, domain_id: nil, tag: nil, from_email: nil, subject: nil,
+               from_date: nil, to_date: nil)
+        params = build_params(
+          page_size: page_size,
+          page_cursor: page_cursor,
+          sort: sort,
+          type: type,
+          status: status,
+          route_id: route_id,
+          domain_id: domain_id,
+          tag: tag,
+          from_email: from_email,
+          subject: subject,
+          from_date: from_date,
+          to_date: to_date
+        )
+        @http_client.get(path: '/messages', params: params)
+      end
+
+      # Get message details.
+      # @param id [String] Message ID
+      # @return [Hash] Message data
+      def find(id)
+        @http_client.get(path: "/messages/#{id}")
+      end
+
+      # Get message events (delivery history).
+      # @param id [String] Message ID
+      # @param sort [String, nil] Sort field: timestamp, event
+      # @return [Hash] List of message events
+      def events(id, sort: nil)
+        params = sort ? { 'sort' => sort } : nil
+        @http_client.get(path: "/messages/#{id}/events", params: params)
+      end
+
+      # Get raw message source (RFC822 format).
+      # @param id [String] Message ID
+      # @return [String] Raw message source (message/rfc822)
+      def source(id)
+        @http_client.get(path: "/messages/#{id}/source", headers: { 'Accept' => 'message/rfc822' })
+      end
+
+      # Get message HTML body.
+      # @param id [String] Message ID
+      # @return [String] HTML content (text/html)
+      def html(id)
+        @http_client.get(path: "/messages/#{id}/html", headers: { 'Accept' => 'text/html' })
+      end
+
+      # Get message plain text body.
+      # @param id [String] Message ID
+      # @return [String] Plain text content (text/plain)
+      def text(id)
+        @http_client.get(path: "/messages/#{id}/text", headers: { 'Accept' => 'text/plain' })
+      end
+    end
+  end
+end

data/lib/lettermint/resources/projects.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Projects resource for managing projects, members, and accessing routes.
+    class Projects < Base
+      # List all projects.
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: name, created_at (prefix - for desc)
+      # @param search [String, nil] Search filter
+      # @return [Hash] Paginated list of projects
+      def list(page_size: nil, page_cursor: nil, sort: nil, search: nil)
+        params = build_params(page_size: page_size, page_cursor: page_cursor, sort: sort, search: search)
+        @http_client.get(path: '/projects', params: params)
+      end
+
+      # Create a new project.
+      # @param name [String] Project name (max 255 chars)
+      # @param smtp_enabled [Boolean, nil] Enable SMTP (default: false)
+      # @param initial_routes [String, nil] Initial routes: both, transactional, broadcast (default: both)
+      # @return [Hash] Created project data including api_token
+      def create(name:, smtp_enabled: nil, initial_routes: nil)
+        data = { name: name }
+        data[:smtp_enabled] = smtp_enabled unless smtp_enabled.nil?
+        data[:initial_routes] = initial_routes if initial_routes
+        @http_client.post(path: '/projects', data: data)
+      end
+
+      # Get project details.
+      #
+      # Note: Returns a Hash, not a resource object. To access routes for a project,
+      # use `projects.routes(project_id)` rather than chaining on the find result.
+      #
+      # @param id [String] Project ID
+      # @param include [String, nil] Related data: routes, domains, teamMembers, messageStats (+ Count/Exists variants)
+      # @return [Hash] Project data with optional includes
+      def find(id, include: nil)
+        params = include ? { 'include' => include } : nil
+        @http_client.get(path: "/projects/#{id}", params: params)
+      end
+
+      # Update a project.
+      # @param id [String] Project ID
+      # @param name [String, nil] New project name
+      # @param smtp_enabled [Boolean, nil] Enable/disable SMTP
+      # @param default_route_id [String, nil] Default route UUID
+      # @return [Hash] Updated project data
+      def update(id, name: nil, smtp_enabled: nil, default_route_id: nil)
+        data = {}
+        data[:name] = name if name
+        data[:smtp_enabled] = smtp_enabled unless smtp_enabled.nil?
+        data[:default_route_id] = default_route_id if default_route_id
+        @http_client.put(path: "/projects/#{id}", data: data)
+      end
+
+      # Delete a project.
+      # @param id [String] Project ID
+      # @return [Hash] Confirmation message
+      def delete(id)
+        @http_client.delete(path: "/projects/#{id}")
+      end
+
+      # Rotate the project API token.
+      # @param id [String] Project ID
+      # @return [Hash] Contains new_token
+      def rotate_token(id)
+        @http_client.post(path: "/projects/#{id}/rotate-token")
+      end
+
+      # Update project members (replace all).
+      # @param id [String] Project ID
+      # @param team_member_ids [Array<String>] Array of team member IDs
+      # @return [Hash] Confirmation
+      def update_members(id, team_member_ids:)
+        @http_client.put(path: "/projects/#{id}/members", data: { team_member_ids: team_member_ids })
+      end
+
+      # Add a member to the project.
+      # @param project_id [String] Project ID
+      # @param member_id [String] Team member ID
+      # @return [Hash] Confirmation
+      def add_member(project_id, member_id)
+        @http_client.post(path: "/projects/#{project_id}/members/#{member_id}")
+      end
+
+      # Remove a member from the project.
+      # @param project_id [String] Project ID
+      # @param member_id [String] Team member ID
+      # @return [Hash] Confirmation
+      def remove_member(project_id, member_id)
+        @http_client.delete(path: "/projects/#{project_id}/members/#{member_id}")
+      end
+
+      # Get a routes accessor scoped to this project.
+      # @param project_id [String] Project ID
+      # @return [Routes] Routes resource scoped to the project
+      def routes(project_id)
+        Routes.new(http_client: @http_client, project_id: project_id)
+      end
+    end
+  end
+end

data/lib/lettermint/resources/routes.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Routes resource for managing project routes (transactional, broadcast, inbound).
+    # Can be instantiated with a project_id for scoped operations or without for direct route access.
+    class Routes < Base
+      # @param http_client [HttpClient] HTTP client instance
+      # @param project_id [String, nil] Optional project ID for scoped operations
+      def initialize(http_client:, project_id: nil)
+        super(http_client: http_client)
+        @project_id = project_id
+      end
+
+      # List routes for a project.
+      # Requires project_id to be set (via constructor or projects.routes(id)).
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: name, slug, created_at (prefix - for desc)
+      # @param route_type [String, nil] Filter: transactional, broadcast, inbound
+      # @param is_default [Boolean, nil] Filter by default route status
+      # @param search [String, nil] Search filter
+      # @return [Hash] Paginated list of routes
+      # rubocop:disable-next Metrics/ParameterLists
+      def list(page_size: nil, page_cursor: nil, sort: nil, route_type: nil,
+               is_default: nil, search: nil)
+        raise ArgumentError, 'project_id required for listing routes' unless @project_id
+
+        params = build_params(
+          page_size: page_size,
+          page_cursor: page_cursor,
+          sort: sort,
+          route_type: route_type,
+          is_default: is_default,
+          search: search
+        )
+        @http_client.get(path: "/projects/#{@project_id}/routes", params: params)
+      end
+
+      # Create a new route in a project.
+      # Requires project_id to be set.
+      # @param name [String] Route name (max 255 chars)
+      # @param route_type [String] Type: transactional, broadcast, inbound
+      # @param slug [String, nil] Optional slug (max 255 chars)
+      # @return [Hash] Created route data
+      def create(name:, route_type:, slug: nil)
+        raise ArgumentError, 'project_id required for creating routes' unless @project_id
+
+        data = { name: name, route_type: route_type }
+        data[:slug] = slug if slug
+        @http_client.post(path: "/projects/#{@project_id}/routes", data: data)
+      end
+
+      # Get route details.
+      # @param id [String] Route ID
+      # @param include [String, nil] Related data: project, statistics
+      # @return [Hash] Route data
+      def find(id, include: nil)
+        params = include ? { 'include' => include } : nil
+        @http_client.get(path: "/routes/#{id}", params: params)
+      end
+
+      # Update a route.
+      # @param id [String] Route ID
+      # @param name [String, nil] New route name
+      # @param settings [Hash, nil] Route settings (track_opens, track_clicks, disable_hosted_unsubscribe)
+      # @param inbound_settings [Hash, nil] Inbound settings (inbound_domain, spam_threshold, etc.)
+      # @return [Hash] Updated route data
+      def update(id, name: nil, settings: nil, inbound_settings: nil)
+        data = {}
+        data[:name] = name if name
+        data[:settings] = settings if settings
+        data[:inbound_settings] = inbound_settings if inbound_settings
+        @http_client.put(path: "/routes/#{id}", data: data)
+      end
+
+      # Delete a route.
+      # @param id [String] Route ID
+      # @return [Hash] Confirmation message
+      def delete(id)
+        @http_client.delete(path: "/routes/#{id}")
+      end
+
+      # Verify inbound domain for a route.
+      # @param id [String] Route ID
+      # @return [Hash] Verification result
+      def verify_inbound_domain(id)
+        @http_client.post(path: "/routes/#{id}/verify-inbound-domain")
+      end
+    end
+  end
+end

data/lib/lettermint/resources/stats.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Stats resource for retrieving email statistics.
+    class Stats < Base
+      # Get statistics for a date range.
+      # @param from [String] Start date (Y-m-d format, required)
+      # @param to [String] End date (Y-m-d format, required, max 90 days from start)
+      # @param project_id [String, nil] Filter by project ID
+      # @param route_id [String, nil] Filter by a single route ID
+      # @param route_ids [Array<String>, String, nil] Filter by multiple route IDs
+      # @return [Hash] Stats data with totals and daily breakdown
+      def get(from:, to:, project_id: nil, route_id: nil, route_ids: nil)
+        params = { 'from' => from, 'to' => to }
+        params['project_id'] = project_id if project_id
+        params['route_id'] = route_id if route_id
+        params['route_ids'] = route_ids if route_ids
+        @http_client.get(path: '/stats', params: params)
+      end
+    end
+  end
+end

data/lib/lettermint/resources/suppressions.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Suppressions resource for managing email suppression lists.
+    class Suppressions < Base
+      # List suppressions.
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: value, created_at, reason
+      # @param scope [String, nil] Filter: team, project, route
+      # @param route_id [String, nil] Filter by route ID
+      # @param project_id [String, nil] Filter by project ID
+      # @param value [String, nil] Filter by suppression value (email/domain/extension)
+      # @param reason [String, nil] Filter: spam_complaint, hard_bounce, unsubscribe, manual
+      # @return [Hash] Paginated list of suppressions
+      # rubocop:disable-next Metrics/ParameterLists
+      def list(page_size: nil, page_cursor: nil, sort: nil, scope: nil,
+               route_id: nil, project_id: nil, value: nil, reason: nil)
+        params = build_params(
+          page_size: page_size,
+          page_cursor: page_cursor,
+          sort: sort,
+          scope: scope,
+          route_id: route_id,
+          project_id: project_id,
+          value: value,
+          reason: reason
+        )
+        @http_client.get(path: '/suppressions', params: params)
+      end
+
+      # Create a suppression entry.
+      # @param reason [String] Reason: spam_complaint, hard_bounce, unsubscribe, manual
+      # @param scope [String] Scope: team, project, route
+      # @param email [String, nil] Single email to suppress (max 255 chars)
+      # @param emails [Array<String>, nil] Multiple emails to suppress (max 1000)
+      # @param route_id [String, nil] Route ID (required if scope is route)
+      # @param project_id [String, nil] Project ID (required if scope is project)
+      # @return [Hash] Created suppression data
+      def create(reason:, scope:, email: nil, emails: nil, route_id: nil, project_id: nil) # rubocop:disable Metrics/ParameterLists
+        data = { reason: reason, scope: scope }
+        data[:email] = email if email
+        data[:emails] = emails if emails
+        data[:route_id] = route_id if route_id
+        data[:project_id] = project_id if project_id
+        @http_client.post(path: '/suppressions', data: data)
+      end
+
+      # Delete a suppression entry.
+      # @param id [String] Suppression ID
+      # @return [Hash] Confirmation message
+      def delete(id)
+        @http_client.delete(path: "/suppressions/#{id}")
+      end
+    end
+  end
+end

data/lib/lettermint/resources/team.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Team resource for managing team settings, usage, and members.
+    class Team < Base
+      # Get team details.
+      # @param include [String, nil] Related data to include (features, featuresCount, featuresExists)
+      # @return [Hash] Team data
+      def get(include: nil)
+        params = include ? { 'include' => include } : nil
+        @http_client.get(path: '/team', params: params)
+      end
+
+      # Update team settings.
+      # @param name [String] New team name (max 255 chars)
+      # @return [Hash] Updated team data
+      def update(name:)
+        @http_client.put(path: '/team', data: { name: name })
+      end
+
+      # Get team usage statistics.
+      # @return [Hash] Current period and up to 12 historical periods
+      def usage
+        @http_client.get(path: '/team/usage')
+      end
+
+      # List team members.
+      # @param page_size [Integer, nil] Number of items per page (default: 30)
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @return [Hash] Paginated list of team members
+      def members(page_size: nil, page_cursor: nil)
+        params = build_params(page_size: page_size, page_cursor: page_cursor)
+        @http_client.get(path: '/team/members', params: params)
+      end
+    end
+  end
+end