keplars 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 68ef4b129e532343682259d772000266f0ee10b38d22a6520f1991922652ab84
+  data.tar.gz: 2e18e8eb8fe9a28f9e751251db6ff64e29c6f067e7c55e3ba44d7e5d740b8936
+SHA512:
+  metadata.gz: 749cd3e2041498a1b263d2908959d67b65c7b45c09afeaf7f369bf18d546dfc3add1b034b87f19c4201b2c4f3a6d38da1d1bd372bac16c1f3e5a6bb8130ef64b
+  data.tar.gz: b6e1ae77b8959db16134f74e5b146051bfff8536f028e7a063de01f79276702592fbe8294707fb38d36327ad2907891d49f4c243d288f5b7d0ae5050d8beecad

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/README.md

@@ -0,0 +1,179 @@
+# Keplars Email SDK for Ruby
+
+Official Ruby SDK for the Keplars Email API - modern transactional email service with priority-based delivery.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'keplars'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install keplars
+```
+
+## Quick Start
+
+```ruby
+require 'keplars'
+
+client = Keplars::Client.new(api_key: 'kms_<workspaceId>.live_<secret>')
+
+result = client.emails.send_instant(
+  from: 'noreply@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Your verification code is 123456',
+  html: '<p>Your verification code is <strong>123456</strong></p>'
+)
+
+puts result[:data][:job_id]
+```
+
+### API Key Types
+
+| Type | Format | Used for |
+|---|---|---|
+| Regular | `kms_<id>.live_<secret>` | Email sending |
+| Admin | `kms_<id>.adm_<secret>` | Contacts, audiences, automations, domains |
+
+## Email Sending
+
+### Priority Levels
+
+| Method | Delivery | Use case |
+|---|---|---|
+| `send_instant` | 0–5 sec | OTPs, login codes, critical alerts |
+| `send_high` | 0–30 sec | Transactional, notifications |
+| `send_async` / `send` | 0–5 min | General transactional |
+| `send_bulk` | Idle | Newsletters, marketing |
+
+### Send with Recipients
+
+```ruby
+result = client.emails.send_high(
+  from: 'noreply@yourdomain.com',
+  to: [{ email: 'user@example.com', name: 'John Doe' }],
+  cc: [{ email: 'manager@example.com' }],
+  subject: 'Order Confirmation',
+  html: '<p>Your order has been confirmed</p>'
+)
+```
+
+### Response Shape
+
+```ruby
+result[:success]           # true
+result[:message]           # 'Email queued'
+result[:data][:job_id]     # 'job_abc123'
+result[:data][:priority]   # 'high'
+```
+
+### Send with Template
+
+```ruby
+result = client.emails.send(
+  from: 'noreply@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Password Reset',
+  template_id: 'tpl_reset_password',
+  template_data: {
+    name: 'John',
+    reset_link: 'https://example.com/reset/abc'
+  }
+)
+```
+
+### Schedule Email
+
+```ruby
+result = client.emails.schedule(
+  from: 'newsletter@yourdomain.com',
+  to: 'user@example.com',
+  subject: 'Your weekly digest',
+  html: '<p>Here is your weekly digest...</p>',
+  scheduled_for: '2026-06-01T09:00:00Z',
+  priority: 'bulk'
+)
+```
+
+## Contacts (Admin API Key Required)
+
+```ruby
+admin_client = Keplars::Client.new(api_key: 'kms_<workspaceId>.adm_<secret>')
+
+admin_client.contacts.add(email: 'user@example.com', name: 'John Doe', audience_id: 'aud_abc123')
+
+contact = admin_client.contacts.get('user@example.com')
+
+contacts = admin_client.contacts.list(audience_id: 'aud_abc123', page: 1, limit: 20)
+
+admin_client.contacts.update('user@example.com', name: 'Jane Doe')
+
+admin_client.contacts.delete('user@example.com')
+```
+
+## Audiences (Admin API Key Required)
+
+```ruby
+audience = admin_client.audiences.create(name: 'Newsletter Subscribers', description: 'Main list')
+
+audiences = admin_client.audiences.list(page: 1, limit: 20)
+
+audience = admin_client.audiences.get('aud_abc123')
+
+admin_client.audiences.delete('aud_abc123')
+```
+
+## Automations (Admin API Key Required)
+
+```ruby
+automations = admin_client.automations.list
+
+automation = admin_client.automations.get('auto_abc123')
+
+admin_client.automations.enroll('auto_abc123', email: 'user@example.com')
+
+admin_client.automations.unenroll('auto_abc123', email: 'user@example.com')
+```
+
+## Domains (Admin API Key Required)
+
+```ruby
+domain = admin_client.domains.add('mail.yourcompany.com')
+
+domains = admin_client.domains.list
+
+status = admin_client.domains.get_status('dom_abc123')
+
+result = admin_client.domains.verify('dom_abc123')
+
+api_key = admin_client.domains.create_api_key(domain_id: 'dom_abc123', name: 'Production Key')
+
+admin_client.domains.delete('dom_abc123')
+```
+
+## Error Handling
+
+```ruby
+require 'keplars'
+
+begin
+  result = client.emails.send_instant(...)
+rescue Keplars::AuthenticationError => e
+  puts "Invalid API key: #{e.message}"
+rescue Keplars::RateLimitError => e
+  puts "Rate limited"
+rescue Keplars::ValidationError => e
+  puts "Validation error: #{e.message}"
+end
+```

data/lib/keplars/audiences.rb

@@ -0,0 +1,28 @@
+module Keplars
+  module Resources
+    class Audiences < Base
+      def create(name:, description: nil)
+        body = { name: name }
+        body[:description] = description if description
+        @client.request('POST', '/api/v1/public/audiences/add-audience', body: body)[:data]
+      end
+
+      def list(page: nil, limit: nil)
+        params = {}
+        params[:page] = page if page
+        params[:limit] = limit if limit
+
+        query = @client.send(:build_query_string, params)
+        @client.request('GET', "/api/v1/public/audiences/get-audiences#{query}")[:data]
+      end
+
+      def get(id)
+        @client.request('GET', "/api/v1/public/audiences/get-audience?id=#{URI.encode_www_form_component(id)}")[:data]
+      end
+
+      def delete(id)
+        @client.request('DELETE', "/api/v1/public/audiences/delete-audience?id=#{URI.encode_www_form_component(id)}")[:data]
+      end
+    end
+  end
+end

data/lib/keplars/automations.rb

@@ -0,0 +1,26 @@
+module Keplars
+  module Resources
+    class Automations < Base
+      def list(page: nil, limit: nil)
+        params = {}
+        params[:page] = page if page
+        params[:limit] = limit if limit
+
+        query = @client.send(:build_query_string, params)
+        @client.request('GET', "/api/v1/public/automations/get-all#{query}")[:data]
+      end
+
+      def get(id)
+        @client.request('GET', "/api/v1/public/automations/get-automation/#{id}")[:data]
+      end
+
+      def enroll(id, email:)
+        @client.request('POST', "/api/v1/public/automations/add-automation/#{id}/enroll", body: { email: email })[:data]
+      end
+
+      def unenroll(id, email:)
+        @client.request('DELETE', "/api/v1/public/automations/delete-automation/#{id}/subscribers", body: { email: email })[:data]
+      end
+    end
+  end
+end

data/lib/keplars/client.rb

@@ -0,0 +1,154 @@
+require 'net/http'
+require 'json'
+require 'uri'
+
+module Keplars
+  class Client
+    DEFAULT_BASE_URL = 'https://api.keplars.com'
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_RETRY_DELAY = 1
+
+    attr_reader :emails, :contacts, :audiences, :automations, :domains
+
+    def initialize(api_key: nil, base_url: nil, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES, retry_delay: DEFAULT_RETRY_DELAY)
+      @api_key = api_key || ENV['KEPLARS_API_KEY']
+      raise ArgumentError, 'API key is required. Set KEPLARS_API_KEY or pass api_key parameter' if @api_key.nil? || @api_key.empty?
+
+      unless validate_api_key(@api_key)
+        raise ArgumentError, 'Invalid API key format. Expected: kms_<id>.live_<secret> or kms_<id>.adm_<secret>'
+      end
+
+      resolved_base_url = base_url || ENV['KEPLARS_BASE_URL'] || DEFAULT_BASE_URL
+      @base_url = resolved_base_url.sub(/\/$/, '')
+      @timeout = timeout
+      @max_retries = max_retries
+      @retry_delay = retry_delay
+
+      @emails = Resources::Emails.new(self)
+      @contacts = Resources::Contacts.new(self)
+      @audiences = Resources::Audiences.new(self)
+      @automations = Resources::Automations.new(self)
+      @domains = Resources::Domains.new(self)
+    end
+
+    def request(method, path, body: nil, retry_count: 0)
+      uri = URI("#{@base_url}#{path}")
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+
+      request_class = case method.upcase
+                      when 'GET' then Net::HTTP::Get
+                      when 'POST' then Net::HTTP::Post
+                      when 'PUT' then Net::HTTP::Put
+                      when 'PATCH' then Net::HTTP::Patch
+                      when 'DELETE' then Net::HTTP::Delete
+                      else raise ArgumentError, "Unsupported HTTP method: #{method}"
+                      end
+
+      request = request_class.new(uri.request_uri)
+      request['Authorization'] = "Bearer #{@api_key}"
+      request['Content-Type'] = 'application/json'
+      request['User-Agent'] = "keplars-ruby/#{VERSION}"
+
+      request.body = body.to_json if body
+
+      begin
+        response = http.request(request)
+        rate_limit_info = extract_rate_limit_info(response)
+
+        if response.code.to_i >= 400
+          handle_error_response(response, retry_count, method, path, body)
+        end
+
+        result = response.body && !response.body.empty? ? JSON.parse(response.body, symbolize_names: true) : nil
+        { data: result, rate_limit_info: rate_limit_info }
+      rescue StandardError => e
+        if retryable_error?(e) && retry_count < @max_retries
+          delay = calculate_backoff(retry_count)
+          sleep(delay)
+          request(method, path, body: body, retry_count: retry_count + 1)
+        else
+          raise NetworkError.new("Request failed: #{e.message}", original_error: e)
+        end
+      end
+    end
+
+    private
+
+    def extract_rate_limit_info(response)
+      limit = response['X-RateLimit-Limit']
+      remaining = response['X-RateLimit-Remaining']
+      reset = response['X-RateLimit-Reset']
+
+      return nil unless limit && remaining && reset
+
+      {
+        limit: limit.to_i,
+        remaining: remaining.to_i,
+        reset: reset.to_i
+      }
+    end
+
+    def handle_error_response(response, retry_count, method, path, body)
+      error_data = JSON.parse(response.body, symbolize_names: true) rescue {}
+      status_code = response.code.to_i
+      message = error_data[:message] || "HTTP #{status_code}"
+
+      case status_code
+      when 400
+        raise ValidationError.new(message, details: nil, request_id: nil)
+      when 401
+        raise AuthenticationError.new(message, request_id: nil)
+      when 403
+        raise AuthorizationError.new(message, request_id: nil)
+      when 404
+        raise KeplarsError.new(message, code: 'NOT_FOUND', status_code: status_code)
+      when 409
+        raise KeplarsError.new(message, code: 'CONFLICT', status_code: status_code)
+      when 429
+        raise RateLimitError.new(message, retry_after: 60, request_id: nil)
+      else
+        if status_code >= 500
+          if retry_count < @max_retries
+            delay = calculate_backoff(retry_count)
+            sleep(delay)
+          end
+          raise InternalError.new(message, request_id: nil)
+        else
+          raise KeplarsError.new(message, code: 'UNKNOWN_ERROR', status_code: status_code)
+        end
+      end
+    end
+
+    def calculate_backoff(retry_count)
+      exponential_delay = @retry_delay * (2**retry_count)
+      jitter = rand * 0.3 * exponential_delay
+      [exponential_delay + jitter, 30].min
+    end
+
+    def retryable_error?(error)
+      error.is_a?(Timeout::Error) ||
+        error.is_a?(Errno::ECONNRESET) ||
+        error.is_a?(Errno::ETIMEDOUT) ||
+        error.is_a?(Errno::ECONNREFUSED)
+    end
+
+    def build_query_string(params)
+      return '' if params.nil? || params.empty?
+
+      filtered = params.reject { |_, v| v.nil? || v == '' }
+      return '' if filtered.empty?
+
+      query = filtered.map { |k, v| "#{k}=#{URI.encode_www_form_component(v)}" }.join('&')
+      "?#{query}"
+    end
+
+    def validate_api_key(api_key)
+      api_key.match?(/\Akms_[a-f0-9]+\.(live|adm)_[a-f0-9]+\z/)
+    end
+  end
+end

data/lib/keplars/contacts.rb

@@ -0,0 +1,31 @@
+module Keplars
+  module Resources
+    class Contacts < Base
+      def add(**params)
+        @client.request('POST', '/api/v1/public/contacts/add-contact', body: params.compact)[:data]
+      end
+
+      def get(email)
+        @client.request('GET', "/api/v1/public/contacts/get-contact?email=#{URI.encode_www_form_component(email)}")[:data]
+      end
+
+      def list(audience_id: nil, page: nil, limit: nil)
+        params = {}
+        params[:audience_id] = audience_id if audience_id
+        params[:page] = page if page
+        params[:limit] = limit if limit
+
+        query = @client.send(:build_query_string, params)
+        @client.request('GET', "/api/v1/public/contacts/get-contacts#{query}")[:data]
+      end
+
+      def update(email, **params)
+        @client.request('PATCH', "/api/v1/public/contacts/update-contact?email=#{URI.encode_www_form_component(email)}", body: params.compact)[:data]
+      end
+
+      def delete(email)
+        @client.request('DELETE', "/api/v1/public/contacts/delete-contact?email=#{URI.encode_www_form_component(email)}")[:data]
+      end
+    end
+  end
+end

data/lib/keplars/domains.rb

@@ -0,0 +1,29 @@
+module Keplars
+  module Resources
+    class Domains < Base
+      def add(domain)
+        @client.request('POST', '/api/v1/public/domains/add-domain', body: { domain: domain })[:data]
+      end
+
+      def list
+        @client.request('GET', '/api/v1/public/domains/get-domains')[:data]
+      end
+
+      def get_status(domain_id)
+        @client.request('GET', "/api/v1/public/domains/domain-status/#{domain_id}")[:data]
+      end
+
+      def verify(domain_id)
+        @client.request('POST', "/api/v1/public/domains/verify-domain/#{domain_id}")[:data]
+      end
+
+      def delete(domain_id)
+        @client.request('DELETE', "/api/v1/public/domains/delete-domain/#{domain_id}")[:data]
+      end
+
+      def create_api_key(**params)
+        @client.request('POST', '/api/v1/public/domains/api-keys/create', body: params.compact)[:data]
+      end
+    end
+  end
+end

data/lib/keplars/errors.rb

@@ -0,0 +1,65 @@
+module Keplars
+  class KeplarsError < StandardError
+    attr_reader :code, :request_id, :status_code
+
+    def initialize(message, code: nil, request_id: nil, status_code: nil)
+      super(message)
+      @code = code
+      @request_id = request_id
+      @status_code = status_code
+    end
+  end
+
+  class ValidationError < KeplarsError
+    attr_reader :details
+
+    def initialize(message, details: nil, request_id: nil)
+      super(message, code: 'VALIDATION_ERROR', request_id: request_id)
+      @details = details
+    end
+  end
+
+  class AuthenticationError < KeplarsError
+    def initialize(message, request_id: nil)
+      super(message, code: 'AUTHENTICATION_ERROR', request_id: request_id)
+    end
+  end
+
+  class AuthorizationError < KeplarsError
+    def initialize(message, request_id: nil)
+      super(message, code: 'AUTHORIZATION_ERROR', request_id: request_id)
+    end
+  end
+
+  class DomainNotVerifiedError < KeplarsError
+    attr_reader :domain, :verification_status
+
+    def initialize(message, domain:, verification_status:, request_id: nil)
+      super(message, code: 'DOMAIN_NOT_VERIFIED', request_id: request_id)
+      @domain = domain
+      @verification_status = verification_status
+    end
+  end
+
+  class RateLimitError < KeplarsError
+    attr_reader :retry_after
+
+    def initialize(message, retry_after:, request_id: nil)
+      super(message, code: 'RATE_LIMIT_EXCEEDED', request_id: request_id)
+      @retry_after = retry_after
+    end
+  end
+
+  class InternalError < KeplarsError
+    def initialize(message, request_id: nil)
+      super(message, code: 'INTERNAL_ERROR', request_id: request_id)
+    end
+  end
+
+  class NetworkError < KeplarsError
+    def initialize(message, original_error: nil)
+      super(message, code: 'NETWORK_ERROR')
+      @original_error = original_error
+    end
+  end
+end

data/lib/keplars/resources.rb

@@ -0,0 +1,41 @@
+module Keplars
+  module Resources
+    class Base
+      def initialize(client)
+        @client = client
+      end
+    end
+
+    class Emails < Base
+      def send_instant(**args)
+        body = args.compact
+        @client.request('POST', '/api/v1/public/send-email/instant', body: body)[:data]
+      end
+
+      def send_high(**args)
+        body = args.compact
+        @client.request('POST', '/api/v1/public/send-email/high', body: body)[:data]
+      end
+
+      def send_async(**args)
+        body = args.compact
+        @client.request('POST', '/api/v1/public/send-email/async', body: body)[:data]
+      end
+
+      def send_bulk(**args)
+        body = args.compact
+        @client.request('POST', '/api/v1/public/send-email/bulk', body: body)[:data]
+      end
+
+      def send(**args)
+        send_async(**args)
+      end
+
+      def schedule(**args)
+        body = args.compact
+        body[:priority] ||= 'async'
+        @client.request('POST', '/api/v1/public/send-email/schedule', body: body)[:data]
+      end
+    end
+  end
+end

data/lib/keplars/version.rb

@@ -0,0 +1,3 @@
+module Keplars
+  VERSION = "1.0.0"
+end

data/lib/keplars.rb

@@ -0,0 +1,15 @@
+require 'net/http'
+require 'json'
+require 'uri'
+
+require_relative 'keplars/version'
+require_relative 'keplars/errors'
+require_relative 'keplars/resources'
+require_relative 'keplars/contacts'
+require_relative 'keplars/audiences'
+require_relative 'keplars/automations'
+require_relative 'keplars/domains'
+require_relative 'keplars/client'
+
+module Keplars
+end

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: keplars
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Keplars
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-05-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.59'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.59'
+description: Modern transactional email service SDK with priority-based delivery for
+  Ruby
+email:
+- support@keplars.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- README.md
+- lib/keplars.rb
+- lib/keplars/audiences.rb
+- lib/keplars/automations.rb
+- lib/keplars/client.rb
+- lib/keplars/contacts.rb
+- lib/keplars/domains.rb
+- lib/keplars/errors.rb
+- lib/keplars/resources.rb
+- lib/keplars/version.rb
+homepage: https://keplars.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://keplars.com
+  source_code_uri: https://github.com/Swing-Technologies/keplars-email-sdk
+  changelog_uri: https://github.com/Swing-Technologies/keplars-email-sdk/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for Keplars Email API
+test_files: []