keplars 2.1.0 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cf4cf268e788b45d71a89a6fdeebfc472a8a051e4ef361fc50704445829d784
-  data.tar.gz: a91eb6cc0fd9769f9cc72c79877ea08f60a4711994a4b65bc3ea163e8dbb8a82
+  metadata.gz: 3c9f27c62fc254b42974354edc4e138d253a05b0367eb1276f9999125810e7e9
+  data.tar.gz: 1cc364a65c48a1676b3d0fc82a511cf671efe84aae50127b7017907917ef1bbd
 SHA512:
-  metadata.gz: 43bc8dd44d4000e4faae494f29963016fa10851ae2a70ae71febad694b8fe31bba334af131644103fe8d36e6902ef721cdcc9f65e9755764ba69c8923bb59d71
-  data.tar.gz: 0af7402b88f4a3bbcd13c253174c509d5bf3e5b433256b7851c50a8c9e4e75ef1fb91d3f66fd84e1d2e01fae2f187d7cfcf9df3d5e292237324a70f7b37d3dd1
+  metadata.gz: 2bb04146d158a84e30a28220d06c6ab4308c37aabc4391cd8e9ad3871198e40ea71a92254ef827b1c466237613eee519884217fbfc6f61b8a412aeb5411ddaa9
+  data.tar.gz: 9fd4acb85ed648d3bf8babd7a5f2d345599bcfa9db8091fb1da3e710cd5377e52c7f804d3708468475414de7e45de28e03d440d3fb509b9d08b9d8389518142c

data/README.md

@@ -46,6 +46,26 @@ puts result[:data][:job_id]
 | Regular | `kms_<id>.live_<secret>` | Email sending |
 | Admin | `kms_<id>.adm_<secret>` | Contacts, audiences, automations, domains |
 
+### Using Both Send and Admin Operations
+
+Pass `admin_key:` alongside a live `api_key:` to use a single client for both:
+
+```ruby
+client = Keplars::Client.new(
+  api_key: 'kms_<id>.live_<secret>',
+  admin_key: 'kms_<id>.adm_<secret>'
+)
+
+client.emails.send_instant(...)   # uses api_key
+client.audiences.list             # uses admin_key
+```
+
+If you only have an admin key, pass it as `api_key:` directly:
+
+```ruby
+client = Keplars::Client.new(api_key: 'kms_<id>.adm_<secret>')
+```
+
 ## Email Sending
 
 ### Priority Levels

data/lib/keplars/audiences.rb

@@ -4,24 +4,26 @@ module Keplars
       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]
+        @client.request('POST', '/api/v1/public/audiences/add-audience', body: body, is_admin: true)[:data]
       end
 
-      def list(page: nil, limit: nil)
+      def list(page: nil, limit: nil, sort_by: nil, sort_dir: nil)
         params = {}
         params[:page] = page if page
         params[:limit] = limit if limit
+        params[:sortBy] = sort_by if sort_by
+        params[:sortDir] = sort_dir if sort_dir
 
         query = @client.send(:build_query_string, params)
-        @client.request('GET', "/api/v1/public/audiences/get-audiences#{query}")[:data]
+        @client.request('GET', "/api/v1/public/audiences/get-audiences#{query}", is_admin: true)[:data]
       end
 
       def get(id)
-        @client.request('GET', "/api/v1/public/audiences/get-audience?id=#{URI.encode_www_form_component(id)}")[:data]
+        @client.request('GET', "/api/v1/public/audiences/get-audience?id=#{URI.encode_www_form_component(id)}", is_admin: true)[:data]
       end
 
       def delete(id)
-        @client.request('DELETE', "/api/v1/public/audiences/delete-audience?id=#{URI.encode_www_form_component(id)}")[:data]
+        @client.request('DELETE', "/api/v1/public/audiences/delete-audience?id=#{URI.encode_www_form_component(id)}", is_admin: true)[:data]
       end
     end
   end

data/lib/keplars/automations.rb

@@ -7,19 +7,27 @@ module Keplars
         params[:limit] = limit if limit
 
         query = @client.send(:build_query_string, params)
-        @client.request('GET', "/api/v1/public/automations/get-all#{query}")[:data]
+        @client.request('GET', "/api/v1/public/automations/get-all#{query}", is_admin: true)[:data]
       end
 
       def get(id)
-        @client.request('GET', "/api/v1/public/automations/get-automation/#{id}")[:data]
+        @client.request('GET', "/api/v1/public/automations/get-automation/#{id}", is_admin: true)[:data]
       end
 
-      def enroll(id, email:)
-        @client.request('POST', "/api/v1/public/automations/add-automation/#{id}/enroll", body: { email: email })[:data]
+      def enroll(id, email:, properties: nil)
+        body = { email: email }
+        body[:properties] = properties if properties
+        @client.request('POST', "/api/v1/public/automations/add-automation/#{id}/enroll", body: body, is_admin: true)[:data]
       end
 
       def unenroll(id, email:)
-        @client.request('DELETE', "/api/v1/public/automations/delete-automation/#{id}/subscribers", body: { email: email })[:data]
+        @client.request('DELETE', "/api/v1/public/automations/delete-automation/#{id}/subscribers", body: { email: email }, is_admin: true)[:data]
+      end
+
+      def track_event(email, event_name, event_properties: nil)
+        body = { email: email, event_name: event_name }
+        body[:event_properties] = event_properties if event_properties
+        @client.request('POST', '/api/v1/public/automations/events/track', body: body, is_admin: true)[:data]
       end
     end
   end

data/lib/keplars/client.rb

@@ -11,7 +11,7 @@ module Keplars
 
     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)
+    def initialize(api_key: nil, admin_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?
 
@@ -19,6 +19,11 @@ module Keplars
         raise ArgumentError, 'Invalid API key format. Expected: kms_<id>.live_<secret> or kms_<id>.adm_<secret>'
       end
 
+      if admin_key
+        raise ArgumentError, 'Invalid adminKey format. Expected: kms_<id>.adm_<secret>' unless admin_key.match?(/\Akms_[a-f0-9]+\.adm_[a-f0-9]+\z/)
+        @admin_key = admin_key
+      end
+
       resolved_base_url = base_url || ENV['KEPLARS_BASE_URL'] || DEFAULT_BASE_URL
       @base_url = resolved_base_url.sub(/\/$/, '')
       @timeout = timeout
@@ -32,7 +37,7 @@ module Keplars
       @domains = Resources::Domains.new(self)
     end
 
-    def request(method, path, body: nil, retry_count: 0)
+    def request(method, path, body: nil, retry_count: 0, is_admin: false)
       uri = URI("#{@base_url}#{path}")
 
       http = Net::HTTP.new(uri.host, uri.port)
@@ -50,7 +55,7 @@ module Keplars
                       end
 
       request = request_class.new(uri.request_uri)
-      request['Authorization'] = "Bearer #{@api_key}"
+      request['Authorization'] = "Bearer #{get_auth_key(is_admin)}"
       request['Content-Type'] = 'application/json'
       request['User-Agent'] = "keplars-ruby/#{VERSION}"
 
@@ -66,11 +71,13 @@ module Keplars
 
         result = response.body && !response.body.empty? ? JSON.parse(response.body, symbolize_names: true) : nil
         { data: result, rate_limit_info: rate_limit_info }
+      rescue KeplarsError
+        raise
       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)
+          request(method, path, body: body, retry_count: retry_count + 1, is_admin: is_admin)
         else
           raise NetworkError.new("Request failed: #{e.message}", original_error: e)
         end
@@ -79,6 +86,14 @@ module Keplars
 
     private
 
+    def get_auth_key(is_admin)
+      return @api_key unless is_admin
+      return @admin_key if @admin_key
+      return @api_key if @api_key.match?(/\Akms_[a-f0-9]+\.adm_[a-f0-9]+\z/)
+
+      raise AuthorizationError.new('Admin key required for this operation. Provide admin_key in config.', request_id: nil)
+    end
+
     def extract_rate_limit_info(response)
       limit = response['X-RateLimit-Limit']
       remaining = response['X-RateLimit-Remaining']

data/lib/keplars/contacts.rb

@@ -2,29 +2,45 @@ module Keplars
   module Resources
     class Contacts < Base
       def add(**params)
-        @client.request('POST', '/api/v1/public/contacts/add-contact', body: params.compact)[:data]
+        @client.request('POST', '/api/v1/public/contacts/add-contact', body: params.compact, is_admin: true)[:data]
       end
 
-      def get(email)
-        @client.request('GET', "/api/v1/public/contacts/get-contact?email=#{URI.encode_www_form_component(email)}")[:data]
+      def get(email_or_id)
+        param = email_or_id.include?('@') ? 'email' : 'id'
+        @client.request('GET', "/api/v1/public/contacts/get-contact?#{param}=#{URI.encode_www_form_component(email_or_id)}", is_admin: true)[:data]
       end
 
-      def list(audience_id: nil, page: nil, limit: nil)
+      def list(audience_id: nil, page: nil, limit: nil, sort_by: nil, sort_dir: nil, subscribed_only: nil)
         params = {}
-        params[:audience_id] = audience_id if audience_id
+        params[:audienceId] = audience_id if audience_id
         params[:page] = page if page
         params[:limit] = limit if limit
+        params[:sortBy] = sort_by if sort_by
+        params[:sortDir] = sort_dir if sort_dir
+        params[:subscribedOnly] = subscribed_only.to_s if !subscribed_only.nil?
 
         query = @client.send(:build_query_string, params)
-        @client.request('GET', "/api/v1/public/contacts/get-contacts#{query}")[:data]
+        @client.request('GET', "/api/v1/public/contacts/get-contacts#{query}", is_admin: true)[: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]
+      def update(id_or_email, **params)
+        if id_or_email.include?('@')
+          warn '[Keplars] Deprecated: passing email to update() is deprecated since v2.7.0. Use contact ID instead.'
+          param = 'email'
+        else
+          param = 'id'
+        end
+        @client.request('PATCH', "/api/v1/public/contacts/update-contact?#{param}=#{URI.encode_www_form_component(id_or_email)}", body: params.compact, is_admin: true)[:data]
       end
 
-      def delete(email)
-        @client.request('DELETE', "/api/v1/public/contacts/delete-contact?email=#{URI.encode_www_form_component(email)}")[:data]
+      def delete(id_or_email)
+        if id_or_email.include?('@')
+          warn '[Keplars] Deprecated: passing email to delete() is deprecated since v2.7.0. Use contact ID instead.'
+          param = 'email'
+        else
+          param = 'id'
+        end
+        @client.request('DELETE', "/api/v1/public/contacts/delete-contact?#{param}=#{URI.encode_www_form_component(id_or_email)}", is_admin: true)[:data]
       end
     end
   end

data/lib/keplars/domains.rb

@@ -1,28 +1,35 @@
 module Keplars
   module Resources
     class Domains < Base
-      def add(domain)
-        @client.request('POST', '/api/v1/public/domains/add-domain', body: { domain: domain })[:data]
+      def add(domain, region: nil)
+        body = { domain: domain }
+        body[:region] = region if region
+        @client.request('POST', '/api/v1/public/domains/add-domain', body: body, is_admin: true)[:data]
       end
 
       def list
-        @client.request('GET', '/api/v1/public/domains/get-domains')[:data]
+        @client.request('GET', '/api/v1/public/domains/get-domains', is_admin: true)[:data]
       end
 
       def get_status(domain_id)
-        @client.request('GET', "/api/v1/public/domains/domain-status/#{domain_id}")[:data]
+        @client.request('GET', "/api/v1/public/domains/domain-status/#{domain_id}", is_admin: true)[:data]
       end
 
       def verify(domain_id)
-        @client.request('POST', "/api/v1/public/domains/verify-domain/#{domain_id}")[:data]
+        @client.request('POST', "/api/v1/public/domains/verify-domain/#{domain_id}", is_admin: true)[:data]
       end
 
       def delete(domain_id)
-        @client.request('DELETE', "/api/v1/public/domains/delete-domain/#{domain_id}")[:data]
+        @client.request('DELETE', "/api/v1/public/domains/delete-domain/#{domain_id}", is_admin: true)[:data]
       end
 
       def create_api_key(**params)
-        @client.request('POST', '/api/v1/public/domains/api-keys/create', body: params.compact)[:data]
+        body = params.dup
+        if body.key?(:domain_id) && !body.key?(:custom_domain_id)
+          warn '[Keplars] Deprecated: :domain_id is deprecated since v2.7.0. Use :custom_domain_id instead.'
+          body[:custom_domain_id] = body.delete(:domain_id)
+        end
+        @client.request('POST', '/api/v1/public/domains/api-keys/create', body: body.compact, is_admin: true)[:data]
       end
     end
   end

data/lib/keplars/resources.rb

@@ -8,22 +8,22 @@ module Keplars
 
     class Emails < Base
       def send_instant(**args)
-        body = args.compact
+        body = normalize_email_args(args)
         @client.request('POST', '/api/v1/send-email/instant', body: body)[:data]
       end
 
       def send_high(**args)
-        body = args.compact
+        body = normalize_email_args(args)
         @client.request('POST', '/api/v1/send-email/high', body: body)[:data]
       end
 
       def send_async(**args)
-        body = args.compact
+        body = normalize_email_args(args)
         @client.request('POST', '/api/v1/send-email/async', body: body)[:data]
       end
 
       def send_bulk(**args)
-        body = args.compact
+        body = normalize_email_args(args)
         @client.request('POST', '/api/v1/send-email/bulk', body: body)[:data]
       end
 
@@ -32,9 +32,56 @@ module Keplars
       end
 
       def schedule(**args)
-        body = args.compact
-        body[:priority] ||= 'async'
-        @client.request('POST', '/api/v1/send-email/schedule', body: body)[:data]
+        body = args.dup
+
+        if body.key?(:scheduled_for) && !body.key?(:scheduled_at)
+          warn '[Keplars] Deprecated: :scheduled_for is deprecated since v2.7.0. Use :scheduled_at instead.'
+          body[:scheduled_at] = body.delete(:scheduled_for)
+        end
+
+        scheduled_at = body.delete(:scheduled_at)
+        timezone = body.delete(:timezone)
+        body.delete(:priority)
+
+        raise ArgumentError, 'scheduled_at is required for scheduling emails' unless scheduled_at
+
+        email_body = normalize_email_args(body).compact
+
+        payload = { scheduled_at: scheduled_at, email: email_body }
+        payload[:timezone] = timezone if timezone
+
+        @client.request('POST', '/api/v1/send-email/schedule', body: payload)[:data]
+      end
+
+      private
+
+      def normalize_email_args(args)
+        body = args.dup
+
+        if body.key?(:to) && !body[:to].is_a?(Array)
+          raise ArgumentError, 'to must be an array of email addresses, e.g. to: ["user@example.com"]'
+        end
+
+        if body.key?(:html)
+          warn '[Keplars] Deprecated: :html is deprecated since v2.7.0. Use :body + is_html: true instead.'
+          body[:body] ||= body.delete(:html)
+          body[:is_html] = true unless body.key?(:is_html)
+          body.delete(:html)
+        end
+
+        if body.key?(:text)
+          warn '[Keplars] Deprecated: :text is deprecated since v2.7.0. Use :body instead.'
+          body[:body] ||= body.delete(:text)
+          body.delete(:text)
+        end
+
+        if body.key?(:template_data)
+          warn '[Keplars] Deprecated: :template_data is deprecated since v2.7.0. Use :params instead.'
+          body[:params] ||= body.delete(:template_data)
+          body.delete(:template_data)
+        end
+
+        body.compact
       end
     end
   end

data/lib/keplars/version.rb

@@ -1,3 +1,3 @@
 module Keplars
-  VERSION = "2.1.0"
+  VERSION = "2.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keplars
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.9.0
 platform: ruby
 authors:
 - Keplars
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-20 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday