Add TemplatesAPI for the paginated /api/templates endpoints

README.md

@@ -211,7 +211,8 @@ General:
 - API Tokens API – [`api_tokens_api.rb`](examples/api_tokens_api.rb)
 - Billing API – [`billing_api.rb`](examples/billing_api.rb)
 - Permissions API – [`permissions_api.rb`](examples/permissions_api.rb)
-- Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
+- Templates API (experimental) – [`templates_api.rb`](examples/templates_api.rb)
+- Email Templates API – [`email_templates_api.rb`](examples/email_templates_api.rb)
 - Action Mailer – [`action_mailer.rb`](examples/action_mailer.rb)
 - Verifying webhook signatures – [`webhooks_signature_verification.ru`](examples/webhooks_signature_verification.ru)
 

examples/templates_api.rb

@@ -0,0 +1,45 @@
+require 'mailtrap'
+
+account_id = 3229
+client = Mailtrap::Client.new(api_key: 'your-api-key')
+templates = Mailtrap::TemplatesAPI.new(account_id, client)
+
+# Set your API credentials as environment variables
+# export MAILTRAP_API_KEY='your-api-key'
+# export MAILTRAP_ACCOUNT_ID=your-account-id
+#
+# templates = Mailtrap::TemplatesAPI.new
+
+# Create a new Template
+template = templates.create(
+  name: 'Welcome Email',
+  subject: 'Welcome to Acme!',
+  category: 'Welcome',
+  body_html: '<div>Welcome, {{name}}!</div>',
+  body_text: 'Welcome, {{name}}!'
+)
+# => #<struct Mailtrap::Template id=26730, name="Welcome Email", subject="Welcome to Acme!", ...>
+
+# Get all Templates (paginated)
+list = templates.list(per_page: 50, token: 1)
+# => #<struct Mailtrap::TemplatesListResponse data=[#<struct Mailtrap::Template ...>], pagination={...}>
+list.data
+# => [#<struct Mailtrap::Template id=26730, name="Welcome Email", ...>]
+list.pagination
+# => {:token=>1, :prev_token=>nil, :next_token=>2, ...}
+
+# Follow the pagination to the next page
+templates.list(per_page: 50, token: list.pagination[:next_token]) if list.pagination[:next_token]
+# => #<struct Mailtrap::TemplatesListResponse data=[...], pagination={...}>
+
+# Get a single Template
+template = templates.get(template.id)
+# => #<struct Mailtrap::Template id=26730, name="Welcome Email", ...>
+
+# Update a Template (partial)
+template = templates.update(template.id, subject: 'Welcome aboard!')
+# => #<struct Mailtrap::Template id=26730, subject="Welcome aboard!", ...>
+
+# Delete a Template (returns nil)
+templates.delete(template.id)
+# => nil

lib/mailtrap.rb

@@ -11,6 +11,7 @@
 require_relative 'mailtrap/sub_accounts_api'
 require_relative 'mailtrap/billing_api'
 require_relative 'mailtrap/email_templates_api'
+require_relative 'mailtrap/templates_api'
 require_relative 'mailtrap/contacts_api'
 require_relative 'mailtrap/contact_lists_api'
 require_relative 'mailtrap/contact_fields_api'

lib/mailtrap/template.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Mailtrap
+  # Data Transfer Object for Template
+  # @attr_reader id [Integer] The template ID
+  # @attr_reader uuid [String] The template UUID
+  # @attr_reader name [String] The template name
+  # @attr_reader subject [String] The email subject
+  # @attr_reader category [String] The template category
+  # @attr_reader body_html [String] The HTML content
+  # @attr_reader body_text [String] The plain text content
+  # @attr_reader created_at [String] The creation timestamp
+  # @attr_reader updated_at [String] The last update timestamp
+  Template = Struct.new(
+    :id,
+    :uuid,
+    :name,
+    :subject,
+    :category,
+    :body_html,
+    :body_text,
+    :created_at,
+    :updated_at,
+    keyword_init: true
+  )
+
+  # Response from listing templates (paginated)
+  # @attr_reader data [Array<Template>] Page of templates
+  # @attr_reader pagination [Hash] Page-token pagination metadata
+  #   (+token+, +prev_token+, +next_token+, +first_url+, +prev_url+, +current_url+, +next_url+)
+  TemplatesListResponse = Struct.new(
+    :data,
+    :pagination,
+    keyword_init: true
+  )
+end

lib/mailtrap/templates_api.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative 'base_api'
+require_relative 'template'
+
+module Mailtrap
+  # @note Experimental: the +/api/templates+ endpoints may change their request and response
+  #   shapes before general availability.
+  class TemplatesAPI
+    include BaseAPI
+
+    self.supported_options = %i[name subject category body_html body_text]
+
+    self.response_class = Template
+
+    # Lists templates for the account, one page at a time. Unlike {EmailTemplatesAPI#list}, it does
+    # not return every template: pass +pagination[:next_token]+ with the same +per_page+ to get the
+    # next page.
+    # @param per_page [Integer, nil] Number of templates per page (max 100, default 50)
+    # @param token [Integer, nil] Page number to retrieve (page-token pagination, default 1)
+    # @return [TemplatesListResponse] The page of templates and pagination metadata
+    # @!macro api_errors
+    def list(per_page: nil, token: nil)
+      query_params = {}
+      query_params[:per_page] = per_page unless per_page.nil?
+      query_params[:token] = token unless token.nil?
+
+      response = client.get(base_path, query_params)
+
+      TemplatesListResponse.new(
+        data: Array(response[:data]).map { |item| build_entity(item, response_class) },
+        pagination: response[:pagination]
+      )
+    end
+
+    # Retrieves a specific template
+    # @param template_id [Integer] The template ID
+    # @return [Template] Template object
+    # @!macro api_errors
+    def get(template_id)
+      base_get(template_id)
+    end
+
+    # Creates a new template
+    # @param [Hash] options The parameters to create
+    # @option options [String] :name The template name (required)
+    # @option options [String] :subject The email subject (required)
+    # @option options [String] :category The template category (required)
+    # @option options [String, nil] :body_html The HTML content. Default: nil.
+    # @option options [String, nil] :body_text The plain text content. Default: nil.
+    # @return [Template] Created template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def create(options)
+      base_create(options)
+    end
+
+    # Updates an existing template. Only the provided attributes are changed.
+    # @param template_id [Integer] The template ID
+    # @param [Hash] options The parameters to update
+    # @option options [String] :name The template name
+    # @option options [String] :subject The email subject
+    # @option options [String] :category The template category
+    # @option options [String, nil] :body_html The HTML content
+    # @option options [String, nil] :body_text The plain text content
+    # @return [Template] Updated template object
+    # @!macro api_errors
+    # @raise [ArgumentError] If invalid options are provided
+    def update(template_id, options)
+      base_update(template_id, options)
+    end
+
+    # Deletes a template
+    # @param template_id [Integer] The template ID
+    # @return [nil]
+    # @!macro api_errors
+    def delete(template_id)
+      base_delete(template_id)
+    end
+
+    private
+
+    def base_path
+      "/api/accounts/#{account_id}/templates"
+    end
+
+    def handle_response(response)
+      build_entity(response[:data], response_class)
+    end
+  end
+end

spec/mailtrap/template_spec.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+RSpec.describe Mailtrap::Template do
+  describe '#initialize' do
+    subject(:template) { described_class.new(attributes) }
+
+    let(:attributes) do
+      {
+        id: 26_730,
+        uuid: '018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132',
+        name: 'My Template',
+        subject: 'My Subject',
+        category: 'My Category',
+        body_html: '<div>HTML</div>',
+        body_text: 'Text',
+        created_at: '2021-01-01T00:00:00Z',
+        updated_at: '2021-01-01T00:00:00Z'
+      }
+    end
+
+    it 'creates a template with all attributes' do
+      expect(template).to have_attributes(attributes)
+    end
+  end
+
+  describe Mailtrap::TemplatesListResponse do
+    subject(:response) { described_class.new(data: [template], pagination: { token: 1 }) }
+
+    let(:template) { Mailtrap::Template.new(id: 1) }
+
+    it 'exposes the page and its pagination' do
+      expect(response).to have_attributes(data: [template], pagination: { token: 1 })
+    end
+  end
+end