lettermint 0.1.0 → 0.2.1

data/lib/lettermint/resources/webhooks.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Lettermint
+  module Resources
+    # Webhooks resource for managing webhook endpoints and viewing deliveries.
+    class Webhooks < Base
+      # List all webhooks.
+      # @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, url, created_at (prefix - for desc)
+      # @param enabled [Boolean, nil] Filter by enabled status
+      # @param event [String, nil] Filter by event type
+      # @param route_id [String, nil] Filter by route ID
+      # @param search [String, nil] Search filter
+      # @return [Hash] Paginated list of webhooks
+      # rubocop:disable-next Metrics/ParameterLists
+      def list(page_size: nil, page_cursor: nil, sort: nil, enabled: nil,
+               event: nil, route_id: nil, search: nil)
+        params = build_params(
+          page_size: page_size,
+          page_cursor: page_cursor,
+          sort: sort,
+          enabled: enabled,
+          event: event,
+          route_id: route_id,
+          search: search
+        )
+        @http_client.get(path: '/webhooks', params: params)
+      end
+
+      # Create a new webhook.
+      # @param route_id [String] Route ID to attach webhook to
+      # @param name [String] Webhook name (max 255 chars)
+      # @param url [String] Webhook URL (max 500 chars)
+      # @param events [Array<String>] Event types to subscribe (min 1)
+      # @param enabled [Boolean, nil] Enable webhook (default: true)
+      # @return [Hash] Created webhook data including secret (shown only once)
+      def create(route_id:, name:, url:, events:, enabled: nil)
+        data = { route_id: route_id, name: name, url: url, events: events }
+        data[:enabled] = enabled unless enabled.nil?
+        @http_client.post(path: '/webhooks', data: data)
+      end
+
+      # Get webhook details.
+      # @param id [String] Webhook ID
+      # @return [Hash] Webhook data including secret
+      def find(id)
+        @http_client.get(path: "/webhooks/#{id}")
+      end
+
+      # Update a webhook.
+      # @param id [String] Webhook ID
+      # @param name [String, nil] New webhook name
+      # @param url [String, nil] New webhook URL
+      # @param enabled [Boolean, nil] Enable/disable webhook
+      # @param events [Array<String>, nil] Event types (min 1)
+      # @return [Hash] Updated webhook data
+      def update(id, name: nil, url: nil, enabled: nil, events: nil)
+        data = {}
+        data[:name] = name if name
+        data[:url] = url if url
+        data[:enabled] = enabled unless enabled.nil?
+        data[:events] = events if events
+        @http_client.put(path: "/webhooks/#{id}", data: data)
+      end
+
+      # Delete a webhook.
+      # @param id [String] Webhook ID
+      # @return [Hash] Confirmation message
+      def delete(id)
+        @http_client.delete(path: "/webhooks/#{id}")
+      end
+
+      # Test a webhook by sending a test delivery.
+      # @param id [String] Webhook ID
+      # @return [Hash] Contains delivery_id for tracking
+      def test(id)
+        @http_client.post(path: "/webhooks/#{id}/test")
+      end
+
+      # Regenerate webhook secret.
+      # @param id [String] Webhook ID
+      # @return [Hash] Updated webhook data with new secret
+      def regenerate_secret(id)
+        @http_client.post(path: "/webhooks/#{id}/regenerate-secret")
+      end
+
+      # List webhook deliveries.
+      # @param webhook_id [String] Webhook ID
+      # @param page_size [Integer, nil] Number of items per page
+      # @param page_cursor [String, nil] Cursor for pagination
+      # @param sort [String, nil] Sort field: created_at, attempt_number
+      # @param status [String, nil] Filter: pending, success, failed, client_error, server_error, timeout
+      # @param event_type [String, nil] Filter by event type
+      # @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 deliveries
+      # rubocop:disable-next Metrics/ParameterLists
+      def deliveries(webhook_id, page_size: nil, page_cursor: nil, sort: nil,
+                     status: nil, event_type: nil, from_date: nil, to_date: nil)
+        params = build_params(
+          page_size: page_size,
+          page_cursor: page_cursor,
+          sort: sort,
+          status: status,
+          event_type: event_type,
+          from_date: from_date,
+          to_date: to_date
+        )
+        @http_client.get(path: "/webhooks/#{webhook_id}/deliveries", params: params)
+      end
+
+      # Get a specific delivery.
+      # @param webhook_id [String] Webhook ID
+      # @param delivery_id [String] Delivery ID
+      # @return [Hash] Delivery data including payload and response
+      def delivery(webhook_id, delivery_id)
+        @http_client.get(path: "/webhooks/#{webhook_id}/deliveries/#{delivery_id}")
+      end
+    end
+  end
+end

data/lib/lettermint/sending_api.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Lettermint
+  # Client for the Lettermint Sending API (project-level email sending).
+  # Authenticates with project tokens via x-lettermint-token header.
+  class SendingAPI
+    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,
+        auth_scheme: :project
+      )
+    end
+
+    def email
+      EmailMessage.new(http_client: @http_client)
+    end
+
+    # Makes a GET request to an arbitrary API endpoint.
+    #
+    # @param path [String] The API endpoint path (e.g., '/domains')
+    # @param params [Hash, nil] Query parameters to include in the request
+    # @param headers [Hash, nil] Additional HTTP headers
+    # @return [Hash] The parsed JSON response body
+    def get(path, params: nil, headers: nil)
+      @http_client.get(path: path, params: params, headers: headers)
+    end
+
+    # Makes a POST request to an arbitrary API endpoint.
+    #
+    # @param path [String] The API endpoint path
+    # @param data [Hash, nil] The request body (will be JSON-encoded)
+    # @param headers [Hash, nil] Additional HTTP headers
+    # @return [Hash] The parsed JSON response body
+    def post(path, data: nil, headers: nil)
+      @http_client.post(path: path, data: data, headers: headers)
+    end
+
+    # Makes a PUT request to an arbitrary API endpoint.
+    #
+    # @param path [String] The API endpoint path
+    # @param data [Hash, nil] The request body (will be JSON-encoded)
+    # @param headers [Hash, nil] Additional HTTP headers
+    # @return [Hash] The parsed JSON response body
+    def put(path, data: nil, headers: nil)
+      @http_client.put(path: path, data: data, headers: headers)
+    end
+
+    # Makes a DELETE request to an arbitrary API endpoint.
+    #
+    # @param path [String] The API endpoint path
+    # @param headers [Hash, nil] Additional HTTP headers
+    # @return [Hash] The parsed JSON response body
+    def delete(path, headers: nil)
+      @http_client.delete(path: path, headers: headers)
+    end
+
+    private
+
+    def validate_api_token!(token)
+      raise ArgumentError, 'API token cannot be empty' if token.nil? || token.to_s.strip.empty?
+    end
+  end
+end

data/lib/lettermint/team_api.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Lettermint
+  # Client for the Lettermint Team API (team-level management operations).
+  # Authenticates with team tokens (lm_team_*) via Authorization: Bearer header.
+  class TeamAPI
+    attr_reader :configuration
+
+    def initialize(team_token:, base_url: nil, timeout: nil)
+      validate_team_token!(team_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: team_token,
+        base_url: @configuration.base_url,
+        timeout: @configuration.timeout,
+        auth_scheme: :team
+      )
+    end
+
+    # Health check endpoint (accepts both token types)
+    # @return [Hash] Parsed response body, e.g. { 'ok' => true } on success
+    def ping
+      @http_client.get(path: '/ping')
+    end
+
+    # Team resource accessor
+    # @return [Resources::Team]
+    def team
+      Resources::Team.new(http_client: @http_client)
+    end
+
+    # Domains resource accessor
+    # @return [Resources::Domains]
+    def domains
+      Resources::Domains.new(http_client: @http_client)
+    end
+
+    # Projects resource accessor
+    # @return [Resources::Projects]
+    def projects
+      Resources::Projects.new(http_client: @http_client)
+    end
+
+    # Webhooks resource accessor
+    # @return [Resources::Webhooks]
+    def webhooks
+      Resources::Webhooks.new(http_client: @http_client)
+    end
+
+    # Messages resource accessor
+    # @return [Resources::Messages]
+    def messages
+      Resources::Messages.new(http_client: @http_client)
+    end
+
+    # Suppressions resource accessor
+    # @return [Resources::Suppressions]
+    def suppressions
+      Resources::Suppressions.new(http_client: @http_client)
+    end
+
+    # Stats resource accessor
+    # @return [Resources::Stats]
+    def stats
+      Resources::Stats.new(http_client: @http_client)
+    end
+
+    # Routes resource accessor (top-level for direct route access)
+    # For project-scoped routes, use projects.routes(project_id)
+    # @return [Resources::Routes]
+    def routes
+      Resources::Routes.new(http_client: @http_client)
+    end
+
+    private
+
+    def validate_team_token!(token)
+      raise ArgumentError, 'Team token cannot be empty' if token.nil? || token.to_s.strip.empty?
+      return if token.to_s.start_with?('lm_team_')
+
+      raise ArgumentError, "Invalid team token format (expected 'lm_team_*')"
+    end
+  end
+end

data/lib/lettermint/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lettermint
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/lettermint.rb

@@ -7,6 +7,21 @@ require_relative 'lettermint/configuration'
 require_relative 'lettermint/http_client'
 require_relative 'lettermint/email_message'
 require_relative 'lettermint/webhook'
+
+# Resources (Team API)
+require_relative 'lettermint/resources/base'
+require_relative 'lettermint/resources/team'
+require_relative 'lettermint/resources/domains'
+require_relative 'lettermint/resources/projects'
+require_relative 'lettermint/resources/routes'
+require_relative 'lettermint/resources/webhooks'
+require_relative 'lettermint/resources/messages'
+require_relative 'lettermint/resources/suppressions'
+require_relative 'lettermint/resources/stats'
+
+# API Clients
+require_relative 'lettermint/sending_api'
+require_relative 'lettermint/team_api'
 require_relative 'lettermint/client'
 
 module Lettermint

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lettermint
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Delano
@@ -34,13 +34,25 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
-- lettermint.gemspec
+- docs/api.md
+- docs/sdk.md
 - lib/lettermint.rb
 - lib/lettermint/client.rb
 - lib/lettermint/configuration.rb
 - lib/lettermint/email_message.rb
 - lib/lettermint/errors.rb
 - lib/lettermint/http_client.rb
+- lib/lettermint/resources/base.rb
+- lib/lettermint/resources/domains.rb
+- lib/lettermint/resources/messages.rb
+- lib/lettermint/resources/projects.rb
+- lib/lettermint/resources/routes.rb
+- lib/lettermint/resources/stats.rb
+- lib/lettermint/resources/suppressions.rb
+- lib/lettermint/resources/team.rb
+- lib/lettermint/resources/webhooks.rb
+- lib/lettermint/sending_api.rb
+- lib/lettermint/team_api.rb
 - lib/lettermint/types.rb
 - lib/lettermint/version.rb
 - lib/lettermint/webhook.rb

data/lettermint.gemspec

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'lib/lettermint/version'
-
-Gem::Specification.new do |spec|
-  spec.name = 'lettermint'
-  spec.version = Lettermint::VERSION
-  spec.authors = ['Delano']
-  spec.email = ['gems@onetimesecret.com']
-
-  spec.summary = 'Ruby SDK for the Lettermint transactional email API'
-  spec.description = 'Send transactional emails and verify webhooks with the Lettermint API. ' \
-                     'Provides a fluent builder interface, typed responses, and HMAC-SHA256 webhook verification.'
-  spec.homepage = 'https://github.com/onetimesecret/lettermint-ruby'
-  spec.license = 'MIT'
-  spec.required_ruby_version = '>= 3.2.0'
-
-  spec.metadata['homepage_uri'] = spec.homepage
-  spec.metadata['source_code_uri'] = spec.homepage
-  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
-  spec.metadata['rubygems_mfa_required'] = 'true'
-  spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-
-  spec.files = Dir.chdir(__dir__) do
-    `git ls-files -z`.split("\x0").reject do |f|
-      (File.expand_path(f) == __FILE__) ||
-        f.start_with?('spec/', 'examples/', '.git', '.rubocop', 'Rakefile', 'Gemfile',
-                      'CLAUDE', '.pre-commit', '.rspec')
-    end
-  end
-
-  spec.require_paths = ['lib']
-
-  spec.add_dependency 'faraday', '~> 2.0'
-end