laneful-ruby 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3b7c5f86e1e341b49312a27486067c2427323569459dba65f8fb2b247629a1fb
-  data.tar.gz: 649ca87028b16f0ede2b1e063390fe13043e12401e70e4637d6c69922d7b415e
+  metadata.gz: ed5ff94086f558d6ea4bad6c914ec22cbc7b8d012cc27fc3d385d3cbc05c5c49
+  data.tar.gz: 02a6ba4d5c4dbee58809d4e15214623fc273770b3779d73fe6ae25b61de75252
 SHA512:
-  metadata.gz: 1d0b108965868436f5b4cbdc6208891bfa51b877a3ec7b70cc4bf13745b793aeb8676d284e010e446acd27de221637c38e005d8399dde5a60adfaf3bf2ae9749
-  data.tar.gz: a50c27e76b6f4b47a8cc6ecee7e5b863bc6f3106127ba9e22e9e822e3b803c809c42202e78412b4b2afe5ab5afcafcbcb2f10c16d78dc923f57e453ca8b14c6b
+  metadata.gz: cc30d8a4112104938f451247b7c24654365f4bb6f8efb5dbeacff4947b00841115563bc7e93d4e36b2eb17e3f115a3616d91a99ebff081d0f322fc9ebdca2060
+  data.tar.gz: 560628e6bd7d5cefa3b9e3229c4be1806d8703d6a7c61e919b94d386b9b3e4a27f1ea95602096e5783236489f4c234233676ebeadf42591eb3db767ec4cf6875

data/lib/laneful/client.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
+require 'cgi'
+require 'json'
+
 module Laneful
-  # Main client for communicating with the Laneful email API
+  # Main client for communicating with the Laneful API.
+  # Email sending uses a send host (https://your-endpoint.send.laneful.net).
+  # Domain, unsubscribe-group, and analytics endpoints use the organization
+  # API host (https://api.laneful.net).
   class Client
     include HTTParty
 
-    # Default timeout in seconds
     DEFAULT_TIMEOUT = 30
 
+    # Repeat array keys as workspace_ids=1&workspace_ids=2 (not workspace_ids[]=).
+    query_string_normalizer HTTParty::Request::NON_RAILS_QUERY_STRING_NORMALIZER
+
     attr_reader :base_url, :auth_token, :timeout
 
     def initialize(base_url, auth_token, timeout: DEFAULT_TIMEOUT)
@@ -16,26 +24,112 @@ module Laneful
       @timeout = timeout
 
       validate_configuration!
-
-      # Configure HTTParty
-      self.class.base_uri @base_url
-      self.class.default_timeout @timeout
-      self.class.headers default_headers
     end
 
     # Sends a single email
-    def send_email(email)
-      send_emails([email])
+    def send_email(email, mail_settings = nil)
+      send_emails([email], mail_settings)
     end
 
     # Sends multiple emails
-    def send_emails(emails)
+    def send_emails(emails, mail_settings = nil)
       validate_emails!(emails)
 
       request_data = { 'emails' => emails.map(&:to_hash) }
-      response = self.class.post("/#{API_VERSION}/email/send", body: request_data.to_json)
+      request_data['mail_settings'] = mail_settings.to_hash if mail_settings
 
-      handle_response(response)
+      request('POST', '/email/send', request_data)
+    end
+
+    # List unsubscribe groups for a workspace.
+    # Uses the organization API host (https://api.laneful.net).
+    def list_unsubscribe_groups(workspace_id, params = nil)
+      ListUnsubscribeGroupsResponse.from_hash(
+        request('GET', "/workspaces/#{workspace_id}/unsubscribe-groups", nil, params&.to_query)
+      )
+    end
+
+    # Create an unsubscribe group in a workspace.
+    def create_unsubscribe_group(workspace_id, name)
+      data = request('POST', "/workspaces/#{workspace_id}/unsubscribe-groups", { 'name' => name })
+      UnsubscribeGroup.from_hash(data['unsubscribe_group'] || data)
+    end
+
+    # Update an unsubscribe group.
+    def update_unsubscribe_group(workspace_id, unsubscribe_group_id, name)
+      data = request(
+        'PATCH',
+        "/workspaces/#{workspace_id}/unsubscribe-groups/#{unsubscribe_group_id}",
+        { 'name' => name }
+      )
+      UnsubscribeGroup.from_hash(data['unsubscribe_group'] || data)
+    end
+
+    # List sending domains for a workspace.
+    def list_domains(workspace_id, params = nil)
+      ListDomainsResponse.from_hash(
+        request('GET', "/workspaces/#{workspace_id}/domains", nil, params&.to_query)
+      )
+    end
+
+    # Get a single sending domain by name.
+    def get_domain(workspace_id, domain)
+      Domain.from_hash(
+        request('GET', "/workspaces/#{workspace_id}/domains/#{encode_path(domain)}")
+      )
+    end
+
+    # Create a sending domain in a workspace.
+    def create_domain(workspace_id, create_request)
+      Domain.from_hash(
+        request('POST', "/workspaces/#{workspace_id}/domains", create_request.to_hash)
+      )
+    end
+
+    # Update a domain's mutable settings (currently the email track).
+    def update_domain(workspace_id, domain, update_request)
+      Domain.from_hash(
+        request(
+          'PATCH',
+          "/workspaces/#{workspace_id}/domains/#{encode_path(domain)}",
+          update_request.to_hash
+        )
+      )
+    end
+
+    # Trigger DNS verification for a domain.
+    def verify_domain(workspace_id, domain)
+      Domain.from_hash(
+        request('POST', "/workspaces/#{workspace_id}/domains/#{encode_path(domain)}/verify")
+      )
+    end
+
+    # Delete a sending domain from a workspace.
+    def delete_domain(workspace_id, domain)
+      SuccessResponse.from_hash(
+        request('DELETE', "/workspaces/#{workspace_id}/domains/#{encode_path(domain)}")
+      )
+    end
+
+    # List domains whose spam complaint ratio reached a critical level.
+    def list_domain_spam_ratio_radar(params = nil)
+      ListDomainSpamRatioRadarResponse.from_hash(
+        request('GET', '/analytics/radar/domain-spam-ratio', nil, params&.to_query)
+      )
+    end
+
+    # List daily Google Postmaster Tools spam-rate reports.
+    def list_google_postmaster_spam_reports(params = nil)
+      ListGooglePostmasterSpamReportsResponse.from_hash(
+        request('GET', '/analytics/google-postmaster/spam-reports', nil, params&.to_query)
+      )
+    end
+
+    # List daily Microsoft SNDS reports for the organization's sending IPs.
+    def list_snds_reports(params = nil)
+      ListSndsReportsResponse.from_hash(
+        request('GET', '/analytics/microsoft-snds/reports', nil, params&.to_query)
+      )
     end
 
     private
@@ -45,7 +139,6 @@ module Laneful
 
       raise ValidationException, 'Auth token cannot be empty' if auth_token.nil? || auth_token.empty?
 
-      # Basic URL validation
       return if base_url.match?(%r{^https?://})
 
       raise ValidationException, 'Base URL must be a valid HTTP/HTTPS URL'
@@ -59,18 +152,46 @@ module Laneful
       end
     end
 
-    def default_headers
-      {
+    def default_headers(with_json: true)
+      headers = {
         'Authorization' => "Bearer #{auth_token}",
-        'Content-Type' => 'application/json',
         'Accept' => 'application/json',
         'User-Agent' => USER_AGENT
       }
+      headers['Content-Type'] = 'application/json' if with_json
+      headers
+    end
+
+    def build_url(path)
+      "#{base_url.chomp('/')}/#{API_VERSION}/#{path.sub(%r{\A/}, '')}"
+    end
+
+    def encode_path(value)
+      CGI.escape(value.to_s).gsub('+', '%20')
+    end
+
+    def request(method, path, json = nil, query = nil)
+      url = build_url(path)
+
+      options = {
+        headers: default_headers(with_json: !json.nil?),
+        timeout: timeout
+      }
+      options[:query] = query unless query.nil? || query.empty?
+      options[:body] = json.to_json unless json.nil?
+
+      begin
+        response = self.class.send(method.downcase, url, options)
+      rescue StandardError => e
+        raise HttpException.new("HTTP request failed: #{e.message}", 0, e)
+      end
+
+      handle_response(response)
     end
 
     def handle_response(response)
       case response.code
-      when 200, 201, 202
+      when 200, 201, 202, 204
         parse_success_response(response)
       when 404
         raise HttpException.new(

data/lib/laneful/models.rb

@@ -59,12 +59,15 @@ module Laneful
 
   # Configuration for email tracking settings
   class TrackingSettings
-    attr_reader :opens, :clicks, :unsubscribes
+    attr_reader :opens, :clicks, :unsubscribes, :unsubscribe_group_id, :unsubscribe_group_name
 
-    def initialize(opens: false, clicks: false, unsubscribes: false)
+    def initialize(opens: false, clicks: false, unsubscribes: false,
+                   unsubscribe_group_id: nil, unsubscribe_group_name: nil)
       @opens = opens
       @clicks = clicks
       @unsubscribes = unsubscribes
+      @unsubscribe_group_id = unsubscribe_group_id
+      @unsubscribe_group_name = unsubscribe_group_name
     end
 
     # Creates tracking settings from a hash representation
@@ -72,22 +75,31 @@ module Laneful
       new(
         opens: data['opens'] || false,
         clicks: data['clicks'] || false,
-        unsubscribes: data['unsubscribes'] || false
+        unsubscribes: data['unsubscribes'] || false,
+        unsubscribe_group_id: data['unsubscribe_group_id'],
+        unsubscribe_group_name: data['unsubscribe_group_name']
       )
     end
 
     def to_hash
-      {
+      hash = {
         'opens' => opens,
         'clicks' => clicks,
         'unsubscribes' => unsubscribes
       }
+      hash['unsubscribe_group_id'] = unsubscribe_group_id unless unsubscribe_group_id.nil?
+      hash['unsubscribe_group_name'] = unsubscribe_group_name unless unsubscribe_group_name.nil?
+      hash
     end
 
     def ==(other)
       return false unless other.is_a?(TrackingSettings)
 
-      opens == other.opens && clicks == other.clicks && unsubscribes == other.unsubscribes
+      opens == other.opens &&
+        clicks == other.clicks &&
+        unsubscribes == other.unsubscribes &&
+        unsubscribe_group_id == other.unsubscribe_group_id &&
+        unsubscribe_group_name == other.unsubscribe_group_name
     end
 
     def eql?(other)
@@ -95,7 +107,7 @@ module Laneful
     end
 
     def hash
-      [opens, clicks, unsubscribes].hash
+      [opens, clicks, unsubscribes, unsubscribe_group_id, unsubscribe_group_name].hash
     end
 
     def to_s
@@ -103,14 +115,53 @@ module Laneful
     end
   end
 
+  # Request-level mail settings (sandbox mode, return message IDs)
+  class MailSettings
+    attr_reader :sandbox_mode, :return_message_ids
+
+    def initialize(sandbox_mode: nil, return_message_ids: nil)
+      @sandbox_mode = sandbox_mode
+      @return_message_ids = return_message_ids
+    end
+
+    def self.from_hash(data)
+      new(
+        sandbox_mode: data['sandbox_mode'],
+        return_message_ids: data['return_message_ids']
+      )
+    end
+
+    def to_hash
+      hash = {}
+      hash['sandbox_mode'] = sandbox_mode unless sandbox_mode.nil?
+      hash['return_message_ids'] = return_message_ids unless return_message_ids.nil?
+      hash
+    end
+
+    def ==(other)
+      return false unless other.is_a?(MailSettings)
+
+      sandbox_mode == other.sandbox_mode && return_message_ids == other.return_message_ids
+    end
+
+    def eql?(other)
+      self == other
+    end
+
+    def hash
+      [sandbox_mode, return_message_ids].hash
+    end
+  end
+
   # Represents a file attachment for an email
   class Attachment
-    attr_reader :filename, :content_type, :content
+    attr_reader :filename, :content_type, :content, :inline_id
 
-    def initialize(filename, content_type, content)
+    def initialize(filename, content_type, content, inline_id = nil)
       @filename = filename
       @content_type = content_type
       @content = content
+      @inline_id = inline_id
       validate!
     end
 
@@ -124,21 +175,27 @@ module Laneful
 
     # Creates an attachment from a hash representation
     def self.from_hash(data)
-      new(data['filename'], data['content_type'], data['content'])
+      filename = data['file_name'] || data['filename']
+      new(filename, data['content_type'], data['content'], data['inline_id'])
     end
 
     def to_hash
-      {
-        'filename' => filename,
+      hash = {
+        'file_name' => filename,
         'content_type' => content_type,
         'content' => content
       }
+      hash['inline_id'] = inline_id if inline_id && !inline_id.empty?
+      hash
     end
 
     def ==(other)
       return false unless other.is_a?(Attachment)
 
-      filename == other.filename && content_type == other.content_type && content == other.content
+      filename == other.filename &&
+        content_type == other.content_type &&
+        content == other.content &&
+        inline_id == other.inline_id
     end
 
     def eql?(other)
@@ -146,7 +203,7 @@ module Laneful
     end
 
     def hash
-      [filename, content_type, content].hash
+      [filename, content_type, content, inline_id].hash
     end
 
     def to_s
@@ -192,12 +249,13 @@ module Laneful
 
   # Represents a single email to be sent
   class Email
-    attr_reader :from, :to, :cc, :bcc, :subject, :text_content, :html_content,
+    attr_reader :from, :from_header, :to, :cc, :bcc, :subject, :text_content, :html_content,
                 :template_id, :template_data, :attachments, :headers, :reply_to,
                 :send_time, :webhook_data, :tag, :tracking
 
     def initialize(builder)
       @from = builder.instance_variable_get(:@from)
+      @from_header = builder.instance_variable_get(:@from_header)
       @to = builder.instance_variable_get(:@to).dup.freeze
       @cc = builder.instance_variable_get(:@cc).dup.freeze
       @bcc = builder.instance_variable_get(:@bcc).dup.freeze
@@ -221,6 +279,7 @@ module Laneful
       builder = Builder.new
 
       builder.from(Address.from_hash(data['from'])) if data && data['from']
+      builder.from_header(Address.from_hash(data['from_header'])) if data && data['from_header']
 
       data['to'].each { |to_data| builder.to(Address.from_hash(to_data)) } if data && data['to']
 
@@ -252,6 +311,7 @@ module Laneful
 
       # Required fields
       hash['from'] = from.to_hash
+      hash['from_header'] = from_header.to_hash if from_header
       hash['to'] = to.map(&:to_hash)
       hash['subject'] = subject if subject
 
@@ -277,6 +337,7 @@ module Laneful
       return false unless other.is_a?(Email)
 
       from == other.from &&
+        from_header == other.from_header &&
         to == other.to &&
         cc == other.cc &&
         bcc == other.bcc &&
@@ -299,7 +360,7 @@ module Laneful
     end
 
     def hash
-      [from, to, cc, bcc, subject, text_content, html_content, template_id,
+      [from, from_header, to, cc, bcc, subject, text_content, html_content, template_id,
        template_data, attachments, headers, reply_to, send_time, webhook_data, tag, tracking].hash
     end
 
@@ -339,6 +400,15 @@ module Laneful
         raise ValidationException, 'Email must have either content (text/HTML) or a template ID'
       end
 
+      if webhook_data
+        raise ValidationException, 'Webhook data cannot have more than 20 keys' if webhook_data.size > 20
+
+        webhook_data.each do |key, value|
+          raise ValidationException, 'Webhook data keys cannot exceed 50 characters' if key.to_s.length > 50
+          raise ValidationException, 'Webhook data values cannot exceed 100 characters' if value.to_s.length > 100
+        end
+      end
+
       # Validate send time
       return unless send_time && send_time <= Time.now.to_i
 
@@ -359,6 +429,11 @@ module Laneful
         self
       end
 
+      def from_header(address)
+        @from_header = address
+        self
+      end
+
       def to(address)
         @to << address
         self