lettermint 0.1.0 → 0.2.1

data/docs/sdk.md

@@ -0,0 +1,510 @@
+# Lettermint Ruby SDK Reference
+
+`gem 'lettermint'` v0.2.1 · Ruby >= 3.2
+
+---
+
+## Quick Start
+
+```ruby
+require 'lettermint'
+
+# Sending API (project-level email sending)
+client = Lettermint::SendingAPI.new(api_token: 'lm_project_xxx')
+
+# Team API (team-level management)
+team = Lettermint::TeamAPI.new(team_token: 'lm_team_xxx')
+```
+
+---
+
+## Authentication
+
+| API | Token Format | Header |
+|-----|--------------|--------|
+| SendingAPI | `lm_project_*` | `x-lettermint-token` |
+| TeamAPI | `lm_team_*` | `Authorization: Bearer` |
+
+```ruby
+# Global configuration (optional)
+Lettermint.configure do |config|
+  config.base_url = 'https://api.lettermint.co/v1'
+  config.timeout = 30
+end
+
+# Instance-level configuration
+client = Lettermint::SendingAPI.new(api_token: 'xxx', base_url: 'https://...', timeout: 60)
+```
+
+---
+
+## Sending Emails
+
+```ruby
+client = Lettermint::SendingAPI.new(api_token: 'lm_project_xxx')
+
+# Fluent builder API
+response = client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Hello')
+  .html('<h1>Hello World</h1>')
+  .text('Hello World')
+  .deliver
+
+response.message_id  # => "msg_xxx"
+response.status      # => "queued"
+```
+
+### EmailMessage Methods
+
+| Method | Description |
+|--------|-------------|
+| `from(email)` | Sender address (required) |
+| `to(*emails)` | Recipient(s) (required, accepts array) |
+| `subject(str)` | Subject line (required) |
+| `html(str)` | HTML body |
+| `text(str)` | Plain text body |
+| `cc(*emails)` | CC recipients |
+| `bcc(*emails)` | BCC recipients |
+| `reply_to(*emails)` | Reply-to addresses |
+| `route(slug)` | Route slug |
+| `tag(str)` | Message tag |
+| `headers(hash)` | Custom headers |
+| `metadata(hash)` | Custom metadata |
+| `attach(filename, content, content_id:)` | Add attachment |
+| `idempotency_key(key)` | Idempotency key header |
+| `deliver` | Send the email, returns `SendEmailResponse` |
+
+### Attachments
+
+```ruby
+# Simple attachment
+client.email
+  .from('sender@example.com')
+  .to('recipient@example.com')
+  .subject('Report')
+  .html('<p>See attached</p>')
+  .attach('report.pdf', Base64.strict_encode64(pdf_data))
+  .deliver
+
+# With content ID (for inline images)
+client.email
+  .attach('logo.png', base64_data, content_id: 'logo')
+  .html('<img src="cid:logo">')
+  ...
+
+# Using EmailAttachment type
+attachment = Lettermint::EmailAttachment.new(
+  filename: 'doc.pdf',
+  content: base64_data,
+  content_id: nil
+)
+client.email.attach(attachment)...
+```
+
+---
+
+## Team API Resources
+
+```ruby
+team = Lettermint::TeamAPI.new(team_token: 'lm_team_xxx')
+```
+
+### Generic
+
+```ruby
+team.ping  # => { 'ok' => true }
+```
+
+### Team
+
+```ruby
+# Get team details
+team.team.get                                    # => Hash
+team.team.get(include: 'features,featuresCount') # with includes
+
+# Update team
+team.team.update(name: 'New Name')
+
+# Usage statistics
+team.team.usage  # => { current_period: ..., historical_usage: [...] }
+
+# List members (paginated)
+team.team.members(page_size: 50, page_cursor: 'cursor_xxx')
+```
+
+### Domains
+
+```ruby
+# List domains
+team.domains.list
+team.domains.list(status: 'verified', sort: '-created_at', page_size: 10)
+
+# Create domain
+team.domains.create(domain: 'mail.example.com')
+
+# Get domain
+team.domains.find('dom_xxx')
+team.domains.find('dom_xxx', include: 'dnsRecords')
+
+# Delete domain
+team.domains.delete('dom_xxx')
+
+# Verify DNS records
+team.domains.verify_dns('dom_xxx')                      # all records
+team.domains.verify_dns_record('dom_xxx', 'rec_xxx')   # single record
+
+# Update associated projects
+team.domains.update_projects('dom_xxx', project_ids: ['proj_1', 'proj_2'])
+```
+
+### Projects
+
+```ruby
+# List projects
+team.projects.list
+team.projects.list(search: 'api', sort: 'name')
+
+# Create project
+team.projects.create(
+  name: 'My Project',
+  smtp_enabled: true,
+  initial_routes: 'transactional'  # both, transactional, broadcast
+)
+# => { ..., 'api_token' => 'lm_project_xxx' }
+
+# Get project
+team.projects.find('proj_xxx')
+team.projects.find('proj_xxx', include: 'routes,domains,messageStats')
+
+# Update project
+team.projects.update('proj_xxx',
+  name: 'Renamed',
+  smtp_enabled: false,
+  default_route_id: 'route_xxx'
+)
+
+# Delete project
+team.projects.delete('proj_xxx')
+
+# Rotate API token
+team.projects.rotate_token('proj_xxx')  # => { 'new_token' => '...' }
+
+# Manage members
+team.projects.update_members('proj_xxx', team_member_ids: ['mem_1', 'mem_2'])
+team.projects.add_member('proj_xxx', 'mem_xxx')
+team.projects.remove_member('proj_xxx', 'mem_xxx')
+```
+
+### Routes
+
+```ruby
+# Project-scoped routes
+routes = team.projects.routes('proj_xxx')
+
+routes.list
+routes.list(route_type: 'transactional', is_default: true, sort: '-created_at')
+
+routes.create(
+  name: 'Notifications',
+  route_type: 'transactional',  # transactional, broadcast, inbound
+  slug: 'notifications'
+)
+
+# Direct route access (any route by ID)
+team.routes.find('route_xxx')
+team.routes.find('route_xxx', include: 'project,statistics')
+
+team.routes.update('route_xxx',
+  name: 'Renamed',
+  settings: { track_opens: true, track_clicks: true },
+  inbound_settings: { inbound_domain: 'in.example.com', inbound_spam_threshold: 5 }
+)
+
+team.routes.delete('route_xxx')
+team.routes.verify_inbound_domain('route_xxx')
+```
+
+### Messages
+
+```ruby
+# List messages
+team.messages.list
+team.messages.list(
+  type: 'outbound',
+  status: 'delivered',
+  route_id: 'route_xxx',
+  from_date: '2024-01-01',
+  to_date: '2024-01-31',
+  sort: '-created_at'
+)
+
+# Get message
+team.messages.find('msg_xxx')
+
+# Message events (delivery history)
+team.messages.events('msg_xxx')
+team.messages.events('msg_xxx', sort: '-timestamp')
+
+# Message content
+team.messages.source('msg_xxx')  # RFC822 format
+team.messages.html('msg_xxx')    # HTML body
+team.messages.text('msg_xxx')    # Plain text body
+```
+
+### Webhooks
+
+```ruby
+# List webhooks
+team.webhooks.list
+team.webhooks.list(enabled: true, event: 'message.delivered', route_id: 'route_xxx')
+
+# Create webhook (returns secret once)
+result = team.webhooks.create(
+  route_id: 'route_xxx',
+  name: 'Delivery notifications',
+  url: 'https://example.com/webhooks',
+  events: ['message.delivered', 'message.hard_bounced'],
+  enabled: true
+)
+secret = result['secret']  # Store this securely
+
+# Get webhook
+team.webhooks.find('wh_xxx')
+
+# Update webhook
+team.webhooks.update('wh_xxx', name: 'Renamed', enabled: false)
+
+# Delete webhook
+team.webhooks.delete('wh_xxx')
+
+# Test webhook
+team.webhooks.test('wh_xxx')  # => { 'delivery_id' => '...' }
+
+# Regenerate secret
+team.webhooks.regenerate_secret('wh_xxx')  # => { 'secret' => '...' }
+
+# Webhook deliveries
+team.webhooks.deliveries('wh_xxx')
+team.webhooks.deliveries('wh_xxx', status: 'failed', from_date: '2024-01-01')
+team.webhooks.delivery('wh_xxx', 'del_xxx')  # Full delivery details
+```
+
+### Suppressions
+
+```ruby
+# List suppressions
+team.suppressions.list
+team.suppressions.list(scope: 'team', reason: 'hard_bounce')
+
+# Create suppression
+team.suppressions.create(
+  reason: 'manual',      # spam_complaint, hard_bounce, unsubscribe, manual
+  scope: 'team',         # global, team, project, route
+  email: 'bad@example.com'
+)
+
+# Bulk suppress (up to 1000)
+team.suppressions.create(
+  reason: 'manual',
+  scope: 'project',
+  project_id: 'proj_xxx',
+  emails: ['a@example.com', 'b@example.com']
+)
+
+# Delete suppression
+team.suppressions.delete('sup_xxx')
+```
+
+### Stats
+
+```ruby
+# Get statistics (max 90 day range)
+team.stats.get(from: '2024-01-01', to: '2024-03-31')
+team.stats.get(from: '2024-01-01', to: '2024-01-31', project_id: 'proj_xxx')
+team.stats.get(from: '2024-01-01', to: '2024-01-31', route_ids: ['r1', 'r2'])
+
+# Returns:
+# {
+#   'from' => '2024-01-01',
+#   'to' => '2024-01-31',
+#   'totals' => { 'sent' => 1000, 'delivered' => 980, ... },
+#   'daily' => [{ 'date' => '2024-01-01', 'sent' => 50, ... }, ...]
+# }
+```
+
+---
+
+## Webhook Verification
+
+Standalone module, no client dependency.
+
+```ruby
+# Instance-based
+webhook = Lettermint::Webhook.new(secret: 'whsec_xxx', tolerance: 300)
+
+# Verify from headers (recommended)
+payload = webhook.verify_headers(request.headers, request.raw_body)
+# => parsed JSON hash
+
+# Verify from signature string
+payload = webhook.verify(raw_body, signature_header)
+
+# Class method (one-shot)
+payload = Lettermint::Webhook.verify_signature(
+  raw_body,
+  signature_header,
+  secret: 'whsec_xxx',
+  tolerance: 300
+)
+```
+
+### Signature Format
+
+Header: `x-lettermint-signature: t=<unix_ts>,v1=<hex_hmac>`
+Timestamp: `x-lettermint-delivery: <unix_ts>`
+
+---
+
+## Error Handling
+
+```ruby
+begin
+  client.email.from('x').to('y').subject('z').html('...').deliver
+rescue Lettermint::ValidationError => e
+  e.message        # Error message
+  e.status_code    # 422
+  e.error_type     # Validation error type (same as e.code for ApiError bodies)
+  e.response_body  # Raw response
+rescue Lettermint::ClientError => e
+  e.status_code    # 400
+rescue Lettermint::AuthenticationError => e
+  e.status_code    # 401 or 403
+rescue Lettermint::NotFoundError => e
+  e.status_code    # 404
+  e.code           # e.g. "RESOURCE_NOT_FOUND" (may be nil)
+  e.details        # Hash, Array or nil; shape depends on code
+rescue Lettermint::RateLimitError => e
+  e.retry_after    # Seconds to wait (may be nil)
+rescue Lettermint::TimeoutError
+  # Request timed out
+rescue Lettermint::ConnectionError => e
+  e.original_exception  # Underlying Faraday error
+rescue Lettermint::ResponseParsingError => e
+  e.original_exception  # Faraday::ParsingError
+rescue Lettermint::HttpRequestError => e
+  # Catch-all for HTTP errors
+  e.status_code    # Integer
+  e.code           # API error code string (may be nil)
+  e.details        # Hash, Array or nil
+  e.response_body  # Hash (JSON), String (non-JSON) or nil (empty)
+rescue Lettermint::Error => e
+  # Catch-all for SDK errors
+end
+```
+
+### Webhook Errors
+
+```ruby
+begin
+  webhook.verify_headers(headers, body)
+rescue Lettermint::InvalidSignatureError
+  # HMAC mismatch
+rescue Lettermint::TimestampToleranceError
+  # Timestamp too old or future
+rescue Lettermint::WebhookJsonDecodeError => e
+  e.original_exception  # JSON::ParserError
+rescue Lettermint::WebhookVerificationError
+  # Catch-all for webhook errors
+end
+```
+
+---
+
+## Error Hierarchy
+
+```
+Lettermint::Error
+├── HttpRequestError (status_code, response_body, code, details)
+│   ├── ValidationError (422, error_type)
+│   ├── ClientError (400)
+│   ├── AuthenticationError (401/403)
+│   ├── NotFoundError (404)
+│   └── RateLimitError (429, retry_after)
+├── TimeoutError
+├── ConnectionError (original_exception)
+├── ResponseParsingError (original_exception)
+└── WebhookVerificationError
+    ├── InvalidSignatureError
+    ├── TimestampToleranceError
+    └── WebhookJsonDecodeError (original_exception)
+```
+
+### Error Bodies
+
+`HttpRequestError` and its subclasses read three JSON body shapes, matching the official Lettermint SDKs:
+
+| Body | Sets |
+|------|------|
+| `{"error":{"code":"...","message":"...","details":...}}` | `code`, `message`, `details` |
+| `{"error":"<string>"}` | `code` |
+| `{"message":"<string>"}` | `message` |
+
+`message` resolves in order: `error.message`, top-level `message`, then `"HTTP <status>"`.
+
+`response_body` is the parsed Hash for JSON responses, the stripped String for non-JSON responses (for example an HTML 404 page from a proxy), and nil for an empty body.
+
+Limitation: a non-JSON body served with a JSON Content-Type raises `ResponseParsingError` before status mapping, so such a proxy 404 is not a `NotFoundError`.
+
+---
+
+## Types
+
+```ruby
+# SendEmailResponse (Data.define, frozen)
+response = client.email...deliver
+response.message_id  # String
+response.status      # String
+
+# EmailAttachment (Data.define, frozen)
+attachment = Lettermint::EmailAttachment.new(
+  filename: 'report.pdf',
+  content: Base64.strict_encode64(data),
+  content_id: nil  # optional
+)
+attachment.to_h  # => { filename: ..., content: ... }
+```
+
+---
+
+## Pagination
+
+All list methods support cursor-based pagination:
+
+```ruby
+# First page
+result = team.domains.list(page_size: 10)
+items = result['data']
+cursor = result.dig('meta', 'cursor')
+
+# Next page
+if cursor
+  result = team.domains.list(page_size: 10, page_cursor: cursor)
+end
+```
+
+---
+
+## Raw HTTP Access
+
+For endpoints not yet wrapped in typed methods:
+
+```ruby
+client = Lettermint::SendingAPI.new(api_token: 'xxx')
+
+client.get('/some/endpoint', params: { key: 'value' })
+client.post('/some/endpoint', data: { key: 'value' })
+client.put('/some/endpoint', data: { key: 'value' })
+client.delete('/some/endpoint')
+```

data/lib/lettermint/client.rb

@@ -1,33 +1,7 @@
 # frozen_string_literal: true
 
 module Lettermint
-  class Client
-    attr_reader :configuration
-
-    def initialize(api_token:, base_url: nil, timeout: nil)
-      validate_api_token!(api_token)
-
-      @configuration = Configuration.new
-      @configuration.base_url = base_url || Lettermint.configuration.base_url
-      @configuration.timeout = timeout || Lettermint.configuration.timeout
-
-      yield @configuration if block_given?
-
-      @http_client = HttpClient.new(
-        api_token: api_token,
-        base_url: @configuration.base_url,
-        timeout: @configuration.timeout
-      )
-    end
-
-    def email
-      EmailMessage.new(http_client: @http_client)
-    end
-
-    private
-
-    def validate_api_token!(token)
-      raise ArgumentError, 'API token cannot be empty' if token.nil? || token.to_s.strip.empty?
-    end
-  end
+  # Backward compatibility: Client is an alias for SendingAPI.
+  # Use Lettermint::SendingAPI explicitly for clarity.
+  Client = SendingAPI
 end

data/lib/lettermint/email_message.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Lettermint
-  class EmailMessage
+  class EmailMessage # rubocop:disable Metrics/ClassLength
     def initialize(http_client:)
       @http_client = http_client
       reset
@@ -108,7 +108,8 @@ module Lettermint
 
     def validate_required_fields
       missing = %i[from subject].select { |f| blank?(f) }
-      missing << :to if @payload[:to].nil? || @payload[:to].none? { |e| e.is_a?(String) && !e.strip.empty? }
+      missing << :to unless valid_recipients?
+      missing << :body unless body?
       return if missing.empty?
 
       raise ArgumentError, "Missing required field(s): #{missing.join(', ')}"
@@ -118,6 +119,14 @@ module Lettermint
       @payload[field].nil? || @payload[field].to_s.strip.empty?
     end
 
+    def valid_recipients?
+      @payload[:to]&.any? { |e| e.is_a?(String) && !e.strip.empty? }
+    end
+
+    def body?
+      !blank?(:html) || !blank?(:text)
+    end
+
     def reset
       @payload = {}
       @idempotency_key = nil

data/lib/lettermint/errors.rb

@@ -4,11 +4,15 @@ module Lettermint
   class Error < StandardError; end
 
   class HttpRequestError < Error
-    attr_reader :status_code, :response_body
+    # code: the API error code string, when the response carried one.
+    # details: Hash, Array or nil; the shape depends on code.
+    attr_reader :status_code, :response_body, :code, :details
 
-    def initialize(message:, status_code:, response_body: nil)
+    def initialize(message:, status_code:, response_body: nil, code: nil, details: nil)
       @status_code = status_code
       @response_body = response_body
+      @code = code
+      @details = details
       super(message)
     end
   end
@@ -16,20 +20,26 @@ module Lettermint
   class ValidationError < HttpRequestError
     attr_reader :error_type
 
-    def initialize(message:, error_type:, response_body: nil)
+    def initialize(message:, error_type:, response_body: nil, code: nil, details: nil)
       @error_type = error_type
-      super(message: message, status_code: 422, response_body: response_body)
+      super(message: message, status_code: 422, response_body: response_body, code: code, details: details)
     end
   end
 
   class ClientError < HttpRequestError
-    def initialize(message:, response_body: nil)
-      super(message: message, status_code: 400, response_body: response_body)
+    def initialize(message:, response_body: nil, code: nil, details: nil)
+      super(message: message, status_code: 400, response_body: response_body, code: code, details: details)
+    end
+  end
+
+  class NotFoundError < HttpRequestError
+    def initialize(message:, response_body: nil, code: nil, details: nil)
+      super(message: message, status_code: 404, response_body: response_body, code: code, details: details)
     end
   end
 
   class AuthenticationError < HttpRequestError
-    def initialize(message:, status_code:, response_body: nil)
+    def initialize(message:, status_code:, response_body: nil, code: nil, details: nil)
       super
     end
   end
@@ -37,14 +47,70 @@ module Lettermint
   class RateLimitError < HttpRequestError
     attr_reader :retry_after
 
-    def initialize(message:, retry_after: nil, response_body: nil)
+    def initialize(message:, retry_after: nil, response_body: nil, code: nil, details: nil)
       @retry_after = retry_after
-      super(message: message, status_code: 429, response_body: response_body)
+      super(message: message, status_code: 429, response_body: response_body, code: code, details: details)
+    end
+  end
+
+  # Extracts [message, code, details] from an error response body, mirroring the
+  # official Node and Python SDKs. Only a Hash body is inspected; any other body
+  # yields "HTTP <status>" with no code or details.
+  # @api private
+  module ErrorBody
+    module_function
+
+    def parse(status, body)
+      message, code, details = body.is_a?(Hash) ? fields_from(body) : []
+      message = "HTTP #{status}" if blank?(message)
+      [message, code, details]
+    end
+
+    def fields_from(body)
+      error = body['error']
+      message, code, details = fields_from_error(error)
+      message = body['message'] if blank?(message) && body['message'].is_a?(String)
+      [message, code, details]
+    end
+
+    # A String `error` is a code, never a message.
+    def fields_from_error(error)
+      case error
+      when Hash then [string_or_nil(error['message']), string_or_nil(error['code']), error['details']]
+      when String then [nil, error, nil]
+      else []
+      end
+    end
+
+    def string_or_nil(value)
+      value.is_a?(String) ? value : nil
+    end
+
+    def blank?(value)
+      value.nil? || value.strip.empty?
     end
   end
 
   class TimeoutError < Error; end
 
+  class ConnectionError < Error
+    attr_reader :original_exception
+
+    def initialize(message:, original_exception: nil)
+      @original_exception = original_exception
+      super(message)
+    end
+  end
+
+  class ResponseParsingError < Error
+    attr_reader :original_exception
+
+    def initialize(message:, original_exception: nil)
+      @original_exception = original_exception
+      super(message)
+    end
+  end
+
   class WebhookVerificationError < Error; end
 
   class InvalidSignatureError < WebhookVerificationError; end