sevk 1.0.0 → 1.1.0

data/lib/sevk/markup/template_engine.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Sevk
+  module Markup
+    module TemplateEngine
+      MAX_IF_PASSES = 2000
+      MAX_EACH_ITEMS = 1000
+      MAX_EACH_OUTPUT = 2_000_000
+      MAX_TEMPLATE_WORK = 20_000_000
+      OUTPUT_EXCEEDED = 'Email block exceeds the maximum template output size'
+
+      private
+
+      def truthy?(val)
+        return false if val.nil?
+        return false if val == false
+        return false if val.is_a?(Numeric) && val.zero?
+        return false if val.is_a?(String) && val.empty?
+        return false if val.is_a?(Array) && val.empty?
+
+        true
+      end
+
+      def evaluate_condition(expr, config)
+        trimmed = expr.strip
+
+        return trimmed.split('||').any? { |part| evaluate_condition(part, config) } if trimmed.include?('||')
+
+        return trimmed.split('&&').all? { |part| evaluate_condition(part, config) } if trimmed.include?('&&')
+
+        if (eq_match = trimmed.match(/^(\w+)\s*==\s*"([^"]*)"$/))
+          return template_text(config[eq_match[1]]) == eq_match[2]
+        end
+
+        if (neq_match = trimmed.match(/^(\w+)\s*!=\s*"([^"]*)"$/))
+          return template_text(config[neq_match[1]]) != neq_match[2]
+        end
+
+        truthy?(config[trimmed])
+      end
+
+      def render_template(template, config)
+        @template_rendered = 0
+        result = render_conditionals(template, config)
+        result = render_loops(result, config)
+
+        result = result.gsub(/\{%(\w+)\s*\?\?([^%]+)%\}/) do
+          value = config[Regexp.last_match(1)]
+          charge_template_output(value.nil? || value == '' ? Regexp.last_match(2).strip : template_text(value))
+        end
+
+        result.gsub(/\{%(\w+)%\}/) { charge_template_output(template_text(config[Regexp.last_match(1)])) }
+      end
+
+      def charge_template_output(value)
+        raise ArgumentError, OUTPUT_EXCEEDED if @template_rendered + value.length > MAX_EACH_OUTPUT
+
+        @template_rendered += value.length
+        value
+      end
+
+      def render_conditionals(template, config)
+        result = template
+        pattern = %r{\{%#if\s+([^%]+)%\}((?:(?!\{%#if\s)[\s\S])*?)\{%/if%\}}
+        work = 0
+
+        MAX_IF_PASSES.times do
+          work += result.length
+          raise ArgumentError, RenderLimits::TOO_COMPLEX if work > MAX_TEMPLATE_WORK
+
+          replaced = result.sub(pattern) do
+            condition = Regexp.last_match(1)
+            body = Regexp.last_match(2)
+            else_index = body.index('{%else%}')
+            if else_index.nil?
+              evaluate_condition(condition, config) ? body : ''
+            else
+              evaluate_condition(condition, config) ? body[0...else_index] : body[(else_index + 8)..]
+            end
+          end
+          break if replaced == result
+
+          result = replaced
+        end
+
+        result
+      end
+
+      def render_loops(template, config)
+        return template unless template.include?('{%/each%}')
+
+        output = +''
+        from = 0
+        work = 0
+
+        while from <= template.length
+          open = template.match(/\{%#each\s+(\w+)(?:\s+as\s+(\w+))?%\}/, from)
+          if open.nil?
+            output << template[from..]
+            break
+          end
+
+          body_start = open.end(0)
+          close_index = template.index('{%/each%}', body_start)
+          if close_index.nil?
+            output << template[from..]
+            break
+          end
+
+          output << template[from...open.begin(0)]
+          items = config[open[1]]
+
+          if items.is_a?(Array) && !items.empty?
+            if items.length > MAX_EACH_ITEMS
+              raise ArgumentError, "Email block exceeds the maximum of #{MAX_EACH_ITEMS} loop items"
+            end
+
+            alias_name = open[2] || 'this'
+            body = template[body_start...close_index]
+            property_pattern = /\{%#{Regexp.escape(alias_name)}\.(\w+)%\}/
+
+            items.each do |item|
+              work += body.length + 16
+              raise ArgumentError, RenderLimits::TOO_COMPLEX if work > MAX_TEMPLATE_WORK
+
+              output << render_loop_item(body, item, config, property_pattern)
+            end
+          end
+
+          from = close_index + 9
+        end
+
+        output
+      end
+
+      def item_property(item, name)
+        return item[name] if item.is_a?(Hash)
+        return nil unless name == 'length'
+
+        case item
+        when String then item.encode('UTF-16LE').bytesize / 2
+        when Array then item.length
+        end
+      end
+
+      def render_loop_item(body, item, config, property_pattern)
+        item_out = 0
+        charge = lambda do |value|
+          raise ArgumentError, OUTPUT_EXCEEDED if @template_rendered + item_out + value.length > MAX_EACH_OUTPUT
+
+          item_out += value.length
+          value
+        end
+
+        rendered = body.gsub(property_pattern) { charge.call(template_text(item_property(item, Regexp.last_match(1)))) }
+        rendered = rendered.gsub(/\{%(\w+)%\}/) { charge.call(template_text(config[Regexp.last_match(1)])) }
+        @template_rendered += rendered.length
+        raise ArgumentError, OUTPUT_EXCEEDED if @template_rendered > MAX_EACH_OUTPUT
+
+        rendered
+      end
+
+      def template_text(value)
+        case value
+        when nil then ''
+        when true then 'true'
+        when false then 'false'
+        when Integer, Float then js_number(value.to_f)
+        when Hash then '[object Object]'
+        when Array then value.map { |item| item.is_a?(Hash) ? '[object Object]' : template_text(item) }.join(',')
+        else value.to_s
+        end
+      end
+
+      def process_block_tag(attrs, inner = '')
+        template = inner.strip.empty? ? (attrs['template'] || '') : inner.strip
+        return '' if template.empty?
+
+        config_str = (attrs['config'] || '{}').gsub(/&(?:amp|quot|apos|lt|gt|#39|#x27|#34|#x22);/i) do |entity|
+          {
+            '&amp;' => '&', '&quot;' => '"', '&#34;' => '"', '&#x22;' => '"',
+            '&apos;' => "'", '&#39;' => "'", '&#x27;' => "'", '&lt;' => '<', '&gt;' => '>'
+          }.fetch(entity.downcase)
+        end
+        config = begin
+          JSON.parse(config_str)
+        rescue JSON::ParserError
+          begin
+            JSON.parse(config_str.gsub("'", '"'))
+          rescue JSON::ParserError
+            {}
+          end
+        end
+        render_template(template, config.is_a?(Hash) ? config : {})
+      end
+
+      def parse_padding(style)
+        pt = pr = pb = pl = 0
+        if style['padding']
+          parts = style['padding'].split
+          case parts.length
+          when 1
+            val = parse_px(parts[0])
+            pt = pr = pb = pl = val
+          when 2
+            vertical = parse_px(parts[0])
+            horizontal = parse_px(parts[1])
+            pt = vertical
+            pr = horizontal
+            pb = vertical
+            pl = horizontal
+          when 3
+            pt = parse_px(parts[0])
+            pr = parse_px(parts[1])
+            pb = parse_px(parts[2])
+            pl = parse_px(parts[1])
+          when 4
+            pt = parse_px(parts[0])
+            pr = parse_px(parts[1])
+            pb = parse_px(parts[2])
+            pl = parse_px(parts[3])
+          end
+        end
+        pt = parse_px(style['padding-top']) if style['padding-top']
+        pr = parse_px(style['padding-right']) if style['padding-right']
+        pb = parse_px(style['padding-bottom']) if style['padding-bottom']
+        pl = parse_px(style['padding-left']) if style['padding-left']
+        [pt, pr, pb, pl]
+      end
+
+      def parse_px(value)
+        value.to_s[/\A\s*[+-]?\d+/].to_i
+      end
+
+      def px_to_pt(pixels)
+        ((pixels * 3) + 2) / 4
+      end
+
+      def compute_font_width_and_space_count(expected_width)
+        return [0, 0] unless expected_width.positive?
+
+        space_count = (expected_width / 10.0).ceil.clamp(1, 1000)
+        [expected_width.to_f / space_count / 2.0, space_count]
+      end
+    end
+  end
+end

data/lib/sevk/resources/activity.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Sevk
+  module Resources
+    class Activity < Base
+      # Lists project activity with optional pagination and filtering.
+      def list(page: nil, limit: nil, after: nil, before: nil, category: nil, type: nil, days: nil, search: nil)
+        type = type.join(',') if type.is_a?(Array)
+        params = { page: page, limit: limit, after: after, before: before, category: category, type: type, days: days,
+                   search: search }
+
+        client.get("/activity#{build_query_string(params)}")
+      end
+
+      # Returns aggregate counts and rates for recent project activity.
+      def stats
+        client.get('/activity/stats')
+      end
+    end
+  end
+end

data/lib/sevk/resources/audiences.rb

@@ -1,46 +1,57 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Audiences < Base
-      def list(page: nil, limit: nil)
-        params = { page: page, limit: limit }
+      # Lists audiences with optional pagination and search.
+      def list(page: nil, limit: nil, after: nil, before: nil, search: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search }
+
         client.get("/audiences#{build_query_string(params)}")
       end
 
+      # Retrieves an audience by id.
       def get(id)
         client.get("/audiences/#{id}")
       end
 
-      def create(name:, description: nil, users_can_see: nil)
+      # Creates an audience for organizing contacts, topics, and segments.
+      def create(name:, description: nil, visibility: nil)
         body = { name: name }
-        body[:description] = description if description
-        body[:usersCanSee] = users_can_see if users_can_see
-        client.post("/audiences", body)
+        body[:description] = description unless description.nil?
+        body[:visibility] = visibility unless visibility.nil?
+
+        client.post('/audiences', body)
       end
 
-      def update(id, name: nil, description: nil, users_can_see: nil)
+      # Updates an audience while preserving omitted fields.
+      def update(id, name: nil, description: nil, visibility: nil)
         body = {}
-        body[:name] = name if name
-        body[:description] = description if description
-        body[:usersCanSee] = users_can_see if users_can_see
+        body[:name] = name unless name.nil?
+        body[:description] = description unless description.nil?
+        body[:visibility] = visibility unless visibility.nil?
+
         client.put("/audiences/#{id}", body)
       end
 
+      # Deletes an audience without deleting its contacts.
       def delete(id)
         client.delete("/audiences/#{id}")
       end
 
+      # Adds contacts to an audience, ignoring memberships that already exist.
       def add_contacts(audience_id, contact_ids)
         client.post("/audiences/#{audience_id}/contacts", { contactIds: contact_ids })
       end
 
+      # Lists contacts attached to an audience with optional filtering.
       def list_contacts(audience_id, params = {})
         client.get("/audiences/#{audience_id}/contacts#{build_query_string(params)}")
       end
 
+      # Removes a contact from the audience without deleting the contact.
       def remove_contact(audience_id, contact_id)
         client.delete("/audiences/#{audience_id}/contacts/#{contact_id}")
       end

data/lib/sevk/resources/base.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module Sevk
   module Resources
     class Base
@@ -12,10 +14,20 @@ module Sevk
       private
 
       def build_query_string(params)
-        return "" if params.nil? || params.empty?
+        return '' if params.nil? || params.empty?
+
+        compacted = wire_keys(params).compact
+        return '' if compacted.empty?
+
+        "?#{URI.encode_www_form(compacted)}"
+      end
+
+      def wire_keys(params)
+        params.transform_keys { |key| wire_key(key) }
+      end
 
-        query = params.compact.map { |k, v| "#{k}=#{v}" }.join("&")
-        query.empty? ? "" : "?#{query}"
+      def wire_key(key)
+        key.to_s.gsub(/_([a-z0-9])/) { Regexp.last_match(1).upcase }.to_sym
       end
     end
   end

data/lib/sevk/resources/broadcasts.rb

@@ -1,61 +1,105 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Broadcasts < Base
-      def list(page: nil, limit: nil, search: nil, status: nil)
-        params = { page: page, limit: limit, search: search, status: status }
+      # Lists broadcasts with optional pagination, search, and status filtering.
+      def list(page: nil, limit: nil, after: nil, before: nil, search: nil, status: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search, status: status }
+
         client.get("/broadcasts#{build_query_string(params)}")
       end
 
+      # Retrieves a broadcast by id and includes its current delivery state.
       def get(id)
         client.get("/broadcasts/#{id}")
       end
 
+      # Creates a draft or scheduled broadcast for a target group.
       def create(params)
-        client.post("/broadcasts", params)
+        client.post('/broadcasts', broadcast_body(params))
       end
 
+      # Updates a broadcast while preserving omitted fields. The response includes
+      # variants and abTest when this mutation touched experiment state.
       def update(id, params)
-        client.put("/broadcasts/#{id}", params)
+        client.put("/broadcasts/#{id}", broadcast_body(params))
       end
 
+      # Deletes a broadcast that has not been sent.
       def delete(id)
         client.delete("/broadcasts/#{id}")
       end
 
+      # Queues a prepared broadcast for delivery.
       def send(id)
         client.post("/broadcasts/#{id}/send")
       end
 
+      # Cancels a broadcast when its state still allows cancellation.
       def cancel(id)
         client.post("/broadcasts/#{id}/cancel")
       end
 
-      def send_test(id, params)
-        client.post("/broadcasts/#{id}/test", params)
+      # Sends the broadcast to test recipients without starting the campaign.
+      def test(id, params, options: nil)
+        client.post("/broadcasts/#{id}/test", wire_keys(params), headers: idempotency_headers(options))
       end
 
-      def get_analytics(id)
+      # Returns aggregate delivery and engagement analytics for a broadcast.
+      def analytics(id)
         client.get("/broadcasts/#{id}/analytics")
       end
 
-      def get_status(id)
+      # Returns live scheduling and delivery progress for a broadcast.
+      def status(id)
         client.get("/broadcasts/#{id}/status")
       end
 
-      def get_emails(id, params = {})
+      # Lists email deliveries created for a broadcast.
+      def emails(id, params = {})
         client.get("/broadcasts/#{id}/emails#{build_query_string(params)}")
       end
 
+      # Estimates delivery cost without sending the broadcast.
       def estimate_cost(id)
         client.get("/broadcasts/#{id}/estimate-cost")
       end
 
-      def list_active
-        client.get("/broadcasts/active")
+      # Resolves the subscribed recipient count for a broadcast target.
+      def estimate_recipients(params)
+        client.post('/broadcasts/estimate-recipients', wire_keys(params))
+      end
+
+      # Lists broadcasts that are currently scheduled or processing.
+      def active
+        client.get('/broadcasts/active')
+      end
+
+      private
+
+      def broadcast_body(params)
+        body = wire_keys(params)
+
+        if body[:variants].is_a?(Array)
+          body[:variants] = body[:variants].map { |variant| variant.is_a?(Hash) ? wire_keys(variant) : variant }
+        end
+
+        body[:abTest] = wire_keys(body[:abTest]) if body[:abTest].is_a?(Hash)
+
+        body
+      end
+
+      def idempotency_headers(options)
+        return nil unless options
+
+        return nil unless options.key?(:idempotency_key) || options.key?('idempotency_key')
+
+        key = options.key?(:idempotency_key) ? options[:idempotency_key] : options['idempotency_key']
+
+        { 'Idempotency-Key' => key.to_s }
       end
     end
   end

data/lib/sevk/resources/contacts.rb

@@ -1,51 +1,66 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Contacts < Base
-      def list(page: nil, limit: nil, search: nil)
-        params = { page: page, limit: limit, search: search }
+      UNSET = Object.new
+      private_constant :UNSET
+
+      # Lists contacts with optional pagination, search, and subscription filters.
+      def list(page: nil, limit: nil, after: nil, before: nil, search: nil, exclude_audience: nil, subscribed: nil)
+        params = { page: page, limit: limit, after: after, before: before, search: search,
+                   excludeAudience: exclude_audience }
+        params[:subscribed] = subscribed unless subscribed.nil?
+
         client.get("/contacts#{build_query_string(params)}")
       end
 
+      # Retrieves a contact by id.
       def get(id)
         client.get("/contacts/#{id}")
       end
 
-      def create(email:, first_name: nil, last_name: nil, subscribed: nil, metadata: nil)
+      # Creates a contact and optionally attaches custom metadata.
+      def create(email:, subscribed: nil, data: nil)
         body = { email: email }
-        body[:firstName] = first_name if first_name
-        body[:lastName] = last_name if last_name
         body[:subscribed] = subscribed unless subscribed.nil?
-        body[:metadata] = metadata if metadata
-        client.post("/contacts", body)
+        body[:data] = data unless data.nil?
+
+        client.post('/contacts', body)
       end
 
-      def update(id, first_name: nil, last_name: nil, subscribed: nil, metadata: nil)
+      # Updates a contact. Explicit nil clears metadata; omitted data preserves it.
+      def update(id, email: nil, subscribed: nil, data: UNSET)
         body = {}
-        body[:firstName] = first_name if first_name
-        body[:lastName] = last_name if last_name
+        body[:email] = email unless email.nil?
         body[:subscribed] = subscribed unless subscribed.nil?
-        body[:metadata] = metadata if metadata
+        body[:data] = data unless data.equal?(UNSET)
+
         client.put("/contacts/#{id}", body)
       end
 
+      # Deletes a contact and removes its audience and topic memberships.
       def delete(id)
         client.delete("/contacts/#{id}")
       end
 
+      # Updates multiple contacts by email and reports entries that were not found.
       def bulk_update(updates)
-        client.put("/contacts/bulk-update", updates)
+        client.put('/contacts/bulk-update', updates)
       end
 
-      def import_csv(params)
-        client.post("/contacts/import", params)
+      # Imports contacts in one request, optionally attaching them to a group.
+      def bulk_import(params)
+        client.post('/contacts/import', wire_keys(params))
       end
 
-      def get_events(id)
-        client.get("/contacts/#{id}/events")
+      # Lists delivery and engagement activity for a contact.
+      def activity(id, page: nil, limit: nil, after: nil, before: nil)
+        params = { page: page, limit: limit, after: after, before: before }
+
+        client.get("/contacts/#{id}/activity#{build_query_string(params)}")
       end
     end
   end

data/lib/sevk/resources/domains.rb

@@ -1,41 +1,55 @@
 # frozen_string_literal: true
 
-require_relative "base"
+require_relative 'base'
 
 module Sevk
   module Resources
     class Domains < Base
-      def list(verified: nil)
-        params = { verified: verified }
+      # Lists sending domains, optionally filtered by verification state.
+      def list(verified: nil, page: nil, limit: nil, after: nil, before: nil)
+        params = { verified: verified, page: page, limit: limit, after: after, before: before }
+
         client.get("/domains#{build_query_string(params)}")
       end
 
+      # Retrieves a domain and its current verification state.
       def get(id)
         client.get("/domains/#{id}")
       end
 
+      # registers an exact domain claim; dns fields depend on domain:dns-read.
       def create(params)
-        client.post("/domains", params)
+        client.post('/domains', wire_keys(params))
       end
 
+      # Updates sending, tracking, TLS, or inbound settings for a domain.
       def update(id, params)
-        client.put("/domains/#{id}", params)
+        client.put("/domains/#{id}", wire_keys(params))
       end
 
+      # Deletes a domain after the API confirms it is safe to remove.
       def delete(id)
         client.delete("/domains/#{id}")
       end
 
+      # Rechecks sending DNS records and returns the updated domain state.
       def verify(id)
         client.post("/domains/#{id}/verify", {})
       end
 
-      def get_dns_records(id)
+      # Checks the inbound MX record and returns details useful for DNS diagnosis.
+      def verify_inbound(id)
+        client.post("/domains/#{id}/inbound/verify", {})
+      end
+
+      # Returns the DNS records required for sending and inbound mail.
+      def dns_records(id)
         client.get("/domains/#{id}/dns-records")
       end
 
-      def get_regions
-        client.get("/domains/regions")
+      # Lists region identifiers accepted when registering a domain.
+      def regions
+        client.get('/domains/regions')
       end
     end
   end