sevk 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c7f36600a0d24e9b0125300b35f125d85c3c2d116902386c4336c1969c539b3
-  data.tar.gz: 99ca2a8b06fba11e1d604ea021cd8664b5cd5cd48a01eaef4a0fd38219acf9d2
+  metadata.gz: 75681328c3b453118de3b5624ab68540a11b0d2af7ce42470b83f1cdc9735cf9
+  data.tar.gz: 2e9af383dc99a61c39337dcef817b34949fa05fc162b2304aa3c20e88a5bf74f
 SHA512:
-  metadata.gz: ede0ed66474c75ed2544e0e5c1d41013946af97d81728ecdccedc7b1022a2d9ccd5bc8a47f67c99bc5b8a1038f4bb1fb84983024a12d8f08e070565f61bcb70b
-  data.tar.gz: eab455f069c6d246b19385ca7842c66f14d16781fd837d0c5d05c2bcf894973b81eee0ff1d96886c1a4a2e4c6b9b6cad18062ca8a5c87b26c5a2937f2923fbfb
+  metadata.gz: 549a3cc87a0f01185a81d5e773a55dd7e777a36268f578853a136e9e80f7af8080f2fe70bfe34368d706f50759a28158218549cf3f88b6cf09e67cb3e5254fb1
+  data.tar.gz: bc2f63abfc1cf26c0202b4aa2d99b4a3aae126768ac332d6e00e80b702016aab7b03ccb73f420c65c9da9cf85e3a2924b39393a2c567db83fa4eabd84036c7d3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sevk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,15 +1,11 @@
-> [!WARNING]
-> Sevk is currently in private beta. This SDK is not yet available for public use.
-> Join the waitlist at [sevk.io](https://sevk.io) to get early access.
-
 <p align="center">
-  <img src="https://sevk.io/logo.png" alt="Sevk" width="120" />
+  <img src="https://sevk.io/logo.png" alt="sevk" width="120" />
 </p>
 
-<h1 align="center">Sevk Ruby SDK</h1>
+<h1 align="center">sevk Ruby SDK</h1>
 
 <p align="center">
-  Official Ruby SDK for <a href="https://sevk.io">Sevk</a> email platform.
+  Official Ruby SDK for <a href="https://sevk.io">sevk</a> email platform.
 </p>
 
 <p align="center">
@@ -28,12 +24,12 @@ gem install sevk
 ```ruby
 require 'sevk'
 
-client = Sevk::Client.new('your-api-key')
+client = Sevk::Client.new(api_key: 'your-api-key')
 
 client.emails.send(
   to: 'recipient@example.com',
   from: 'hello@yourdomain.com',
-  subject: 'Hello from Sevk!',
+  subject: 'Hello from sevk!',
   html: '<h1>Welcome!</h1>'
 )
 ```
@@ -43,7 +39,7 @@ client.emails.send(
 ```ruby
 require 'sevk'
 
-client = Sevk::Client.new('your-api-key')
+client = Sevk::Client.new(api_key: 'your-api-key')
 
 html = Sevk::Markup.render(<<~MARKUP
   <section padding="40px 20px" background-color="#f8f9fa">

data/lib/sevk/client.rb

@@ -2,11 +2,12 @@
 
 module Sevk
   class Client
-    attr_reader :api_key, :base_url
+    attr_reader :api_key, :base_url, :timeout
 
-    def initialize(api_key:, base_url: nil)
+    def initialize(api_key:, base_url: nil, timeout: 30)
       @api_key = api_key
       @base_url = base_url || DEFAULT_BASE_URL
+      @timeout = timeout
     end
 
     def contacts
@@ -45,12 +46,32 @@ module Sevk
       @emails ||= Resources::Emails.new(self)
     end
 
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(self)
+    end
+
+    def activity
+      @activity ||= Resources::Activity.new(self)
+    end
+
+    def inbound
+      @inbound ||= Resources::Inbound.new(self)
+    end
+
+    def outbound
+      @outbound ||= Resources::Outbound.new(self)
+    end
+
+    def usage
+      @usage ||= Resources::Usage.new(self)
+    end
+
     def get(path, params = {})
       request(:get, path, params)
     end
 
-    def post(path, body = {})
-      request(:post, path, body)
+    def post(path, body = {}, headers: nil)
+      request(:post, path, body, headers: headers)
     end
 
     def patch(path, body = {})
@@ -70,95 +91,164 @@ module Sevk
     def connection
       @connection ||= Faraday.new do |conn|
         conn.request :json
-        conn.response :json, content_type: /\bjson$/
-        conn.request :retry, max: 2, interval: 0.5, backoff_factor: 2
-        conn.headers["Authorization"] = "Bearer #{api_key}"
-        conn.headers["Content-Type"] = "application/json"
-        conn.headers["Accept"] = "application/json"
+        conn.options.timeout = timeout
+        conn.options.open_timeout = timeout
+        conn.headers['Authorization'] = "Bearer #{api_key}"
+        conn.headers['Content-Type'] = 'application/json'
+        conn.headers['Accept'] = 'application/json'
+        conn.headers['User-Agent'] = "sevk-ruby/#{VERSION}"
         conn.adapter Faraday.default_adapter
       end
     end
 
     def build_url(path)
-      # Ensure base_url ends without slash and path starts with slash
-      base = base_url.chomp("/")
-      path = "/#{path}" unless path.start_with?("/")
+      base = base_url.sub(%r{/+\z}, '')
+      path = "/#{path}" unless path.start_with?('/')
       "#{base}#{path}"
     end
 
-    def request(method, path, body = nil)
+    def request(method, path, body = nil, headers: nil)
       url = build_url(path)
+      body = encode_body(body) if !body.nil? && %i[post patch put].include?(method)
       response = case method
                  when :get
                    connection.get(url, body)
                  when :post
-                   connection.post(url, body)
+                   connection.post(url, body) { |req| apply_extra_headers(req, headers) }
                  when :patch
-                   connection.patch(url, body)
+                   connection.patch(url, body) { |req| apply_extra_headers(req, headers) }
                  when :put
-                   connection.put(url, body)
+                   connection.put(url, body) { |req| apply_extra_headers(req, headers) }
                  when :delete
                    connection.delete(url)
                  end
 
       handle_response(response)
+    rescue Faraday::TimeoutError => e
+      raise Error.new(e.message, status_code: 0, code: 'TIMEOUT')
+    rescue Faraday::ConnectionFailed => e
+      code = e.wrapped_exception.is_a?(Net::OpenTimeout) ? 'TIMEOUT' : 'NETWORK_ERROR'
+      raise Error.new(e.message, status_code: 0, code: code)
+    rescue Faraday::Error => e
+      raise Error.new(e.message, status_code: 0, code: 'NETWORK_ERROR')
+    end
+
+    def encode_body(body)
+      JSON.generate(body)
+    rescue JSON::GeneratorError, JSON::NestingError => e
+      raise Error.new("Request body cannot be JSON encoded: #{e.message}", status_code: 0, code: 'SERIALIZATION_ERROR')
+    end
+
+    def apply_extra_headers(req, headers)
+      return unless headers
+
+      headers.each { |k, v| req.headers[k.to_s] = v.to_s }
     end
 
     def handle_response(response)
-      case response.status
-      when 200..299
-        response.body
+      return {} if response.status == 204
+
+      if (200..299).cover?(response.status)
+        raw_body = response.body
+        body = decode_json_body(raw_body)
+        unless body.is_a?(Hash)
+          raise Error.new(
+            'Expected a JSON response body but received an empty or non-JSON response',
+            status_code: response.status,
+            code: 'INVALID_RESPONSE',
+            response: raw_body
+          )
+        end
+
+        return body
+      end
+
+      raise_response_error(response.status, response.body, response.headers)
+    end
+
+    def raise_response_error(response_status, response_body, response_headers)
+      decoded_body = decode_json_body(response_body)
+      payload = error_payload(decoded_body)
+      fields = normalize_fields(payload['fields'])
+      status = response_status
+      code = payload['code']
+      code = 'UNKNOWN_ERROR' unless code.is_a?(String) && !code.empty?
+      attrs = {
+        status_code: status,
+        code: code,
+        fields: fields,
+        retry_after: parse_retry_after(response_headers['Retry-After']),
+        response: decoded_body,
+        details: payload['details']
+      }
+      message = error_message(status, payload, decoded_body)
+
+      case status
       when 400
-        raise ValidationError.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        klass = fields.empty? && payload['code'] != 'VALIDATION_ERROR' ? BadRequestError : ValidationError
+        raise klass.new(message, **attrs)
       when 401
-        raise AuthenticationError.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise UnauthorizedError.new(message, **attrs)
       when 403
-        raise Error.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise ForbiddenError.new(message, **attrs)
       when 404
-        raise NotFoundError.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise NotFoundError.new(message, **attrs)
+      when 409
+        raise ConflictError.new(message, **attrs)
+      when 422
+        raise ValidationError.new(message, **attrs)
       when 429
-        raise RateLimitError.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise RateLimitError.new(message, **attrs)
       when 500..599
-        raise ServerError.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise InternalServerError.new(message, **attrs)
       else
-        raise Error.new(
-          error_message(response),
-          status_code: response.status,
-          response: response.body
-        )
+        raise Error.new(message, **attrs)
       end
     end
 
-    def error_message(response)
-      if response.body.is_a?(Hash) && response.body["message"]
-        "#{response.status}: #{response.body['message']}"
+    def decode_json_body(body)
+      return body unless body.is_a?(String)
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      body
+    end
+
+    # Unwrap the nested `{ "error": { ... } }` envelope when present.
+    def error_payload(body)
+      return {} unless body.is_a?(Hash)
+
+      nested = body['error']
+      nested.is_a?(Hash) ? nested : body
+    end
+
+    def error_message(status, payload, body)
+      message = payload['message']
+      raw = body.is_a?(String) ? body.strip : ''
+      if message.is_a?(String) && !message.empty?
+        message
       else
-        "#{response.status}: #{response.body}"
+        (raw.empty? ? "HTTP #{status}" : raw)
       end
     end
+
+    # Coerce each field value (a string or list of strings on the wire) into a
+    # list of strings.
+    def normalize_fields(raw)
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) do |(key, value), acc|
+        acc[key.to_s] = value.is_a?(Array) ? value.map(&:to_s) : [value.to_s]
+      end
+    end
+
+    # Integer-seconds Retry-After only; HTTP-date forms are ignored (nil).
+    def parse_retry_after(value)
+      text = value.to_s.strip
+      return nil unless text.match?(/\A\d+\z/)
+
+      seconds = text.to_i
+      seconds <= 2_147_483_647 ? seconds : nil
+    end
   end
 end

data/lib/sevk/error.rb

@@ -2,12 +2,23 @@
 
 module Sevk
   class Error < StandardError
-    attr_reader :status_code, :code, :response
+    attr_reader :status_code, :code, :fields, :retry_after, :response, :details
 
-    def initialize(message = nil, status_code: nil, code: nil, response: nil)
+    def initialize(
+      message = nil,
+      status_code: nil,
+      code: nil,
+      fields: nil,
+      retry_after: nil,
+      response: nil,
+      details: nil
+    )
       @status_code = status_code
       @code = code
+      @fields = fields || {}
+      @retry_after = retry_after
       @response = response
+      @details = details
       super(message)
     end
 
@@ -27,14 +38,36 @@ module Sevk
       status_code == 400
     end
 
+    def conflict?
+      status_code == 409
+    end
+
+    def validation_error?
+      status_code == 422 ||
+        (status_code == 400 && (code == 'VALIDATION_ERROR' || !fields.empty?))
+    end
+
+    def rate_limited?
+      status_code == 429
+    end
+
     def server_error?
       status_code.to_i >= 500 && status_code.to_i < 600
     end
   end
 
-  class AuthenticationError < Error; end
+  class BadRequestError < Error; end
+  class UnauthorizedError < Error; end
+  class ForbiddenError < Error; end
   class NotFoundError < Error; end
-  class ValidationError < Error; end
+  class ConflictError < Error; end
+
+  class ValidationError < Error
+    def initialize(message = nil, status_code: 0, code: 'VALIDATION_ERROR', **attributes)
+      super
+    end
+  end
+
   class RateLimitError < Error; end
-  class ServerError < Error; end
+  class InternalServerError < Error; end
 end

data/lib/sevk/markup/document_parser.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Sevk
+  module Markup
+    module DocumentParser
+      private
+
+      def extract_body_content(markup)
+        unless sevk_document?(markup)
+          body = get_first_tag_content(markup, 'body') || markup
+          preview = hidden_preview(markup)
+          body = body.sub(preview[0], '') if preview
+          return body.strip
+        end
+
+        body = (get_first_tag_content(markup, 'body') || '').strip
+        return body unless body.empty?
+
+        stripped = replace_self_closing(markup, 'email') { '' }
+        stripped = replace_self_closing(stripped, 'mail') { '' }.gsub(%r{</(?:email|mail)>}i, '')
+        %w[head title preview style].each { |tag| stripped = strip_tag_pairs(stripped, tag) }
+        replace_self_closing(stripped, 'font') { '' }.gsub(%r{</font>}i, '').strip
+      end
+
+      def sevk_document?(markup)
+        markup.match?(/<(?:email|mail)[\s>]/i)
+      end
+
+      def hidden_preview(html)
+        find_hidden_preview_div(html)
+      end
+
+      def parse_head_settings(markup)
+        return parse_html_head_settings(markup) unless sevk_document?(markup)
+
+        root_attrs = get_tag_attributes(markup, 'email').first || get_tag_attributes(markup, 'mail').first
+        if root_attrs
+          if (lang_match = root_attrs.match(/lang=["']([^"']*)["']/i))
+            @head_settings.lang = lang_match[1]
+          end
+          if (dir_match = root_attrs.match(/dir=["']([^"']*)["']/i))
+            @head_settings.dir = dir_match[1]
+          end
+        end
+
+        @head_settings.title = (get_first_tag_content(markup, 'title') || '').strip
+        @head_settings.preview_text = (get_first_tag_content(markup, 'preview') || '').strip
+        @head_settings.styles = (get_first_tag_content(markup, 'style') || '').strip
+
+        seen_urls = {}
+        get_tag_attributes(markup, 'font').each do |attributes|
+          name = attributes.match(/name=["']([^"']*)["']/i)
+          url = attributes.match(/url=["']([^"']*)["']/i)
+          next if name.nil? || url.nil? || seen_urls[url[1]]
+
+          seen_urls[url[1]] = true
+          @head_settings.fonts << FontConfig.new(
+            id: "font-#{@head_settings.fonts.length}", name: name[1], url: url[1]
+          )
+        end
+      end
+
+      def parse_html_head_settings(html)
+        @head_settings.title = (get_first_tag_content(html, 'title') || '').strip
+        @head_settings.styles = get_all_tag_contents(html, 'style').join("\n")
+
+        get_tag_attributes(html, 'link').each do |attributes|
+          href = attributes.match(/href=["']([^"']*)["']/i)
+          next if href.nil? || !href[1].downcase.include?('fonts')
+
+          family = href[1].match(/family=([^:&]+)/)
+          index = @head_settings.fonts.length
+          @head_settings.fonts << FontConfig.new(
+            id: "font-#{index}", name: family ? family[1].tr('+', ' ') : "Font #{index + 1}", url: href[1]
+          )
+        end
+
+        preview = hidden_preview(html)
+        @head_settings.preview_text = preview[1].strip if preview
+      end
+    end
+  end
+end

data/lib/sevk/markup/html_document.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Sevk
+  module Markup
+    module HtmlDocument
+      private
+
+      def generate_html(content)
+        lang = @head_settings.lang.empty? ? 'en' : @head_settings.lang
+        dir = @head_settings.dir.empty? ? 'ltr' : @head_settings.dir
+
+        title = @head_settings.title.empty? ? '' : "<title>#{@head_settings.title}</title>"
+
+        font_links = @head_settings.fonts.map do |font|
+          %(<link href="#{font.url}" rel="stylesheet" type="text/css" />)
+        end.join("\n")
+
+        styles = @head_settings.styles.empty? ? '' : %(<style type="text/css">#{@head_settings.styles}</style>)
+
+        gap_rules = @gap_rules || []
+        gap_style_tag =
+          if gap_rules.empty?
+            ''
+          else
+            %(<style type="text/css">@media only screen and (max-width:479px){#{gap_rules.join}}</style>)
+          end
+
+        preview_text = ''
+        unless @head_settings.preview_text.empty?
+          preview_style =
+            'display:none;font-size:1px;color:#ffffff;line-height:1px;' \
+            'max-height:0px;max-width:0px;opacity:0;overflow:hidden;'
+          preview_text = %(<div style="#{preview_style}">#{@head_settings.preview_text}</div>)
+        end
+
+        <<~HTML.chomp
+          <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+          <html lang="#{lang}" dir="#{dir}" xmlns="http://www.w3.org/1999/xhtml" xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+          <head>
+          <meta content="text/html; charset=UTF-8" http-equiv="Content-Type"/>
+          <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+          <meta name="x-apple-disable-message-reformatting"/>
+          <meta content="IE=edge" http-equiv="X-UA-Compatible"/>
+          <meta name="format-detection" content="telephone=no,address=no,email=no,date=no,url=no"/>
+          <!--[if mso]>
+          <noscript>
+          <xml>
+          <o:OfficeDocumentSettings>
+          <o:AllowPNG/>
+          <o:PixelsPerInch>96</o:PixelsPerInch>
+          </o:OfficeDocumentSettings>
+          </xml>
+          </noscript>
+          <![endif]-->
+          <style type="text/css">
+          #outlook a { padding: 0; }
+          body { margin: 0; padding: 0; -webkit-text-size-adjust: 100%; -ms-text-size-adjust: 100%; }
+          table, td { border-collapse: collapse; mso-table-lspace: 0pt; mso-table-rspace: 0pt; }
+          .sevk-row-table { border-collapse: separate !important; }
+          img { border: 0; height: auto; line-height: 100%; outline: none; text-decoration: none; -ms-interpolation-mode: bicubic; }
+          @media only screen and (max-width: 479px) {
+            .sevk-row-table { width: 100% !important; }
+            .sevk-column { display: block !important; width: 100% !important; max-width: 100% !important; box-sizing: border-box !important; }
+          }
+          </style>
+          #{gap_style_tag}
+          #{title}
+          #{font_links}
+          #{styles}
+          </head>
+          <body style="margin:0;padding:0;word-spacing:normal;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%;font-family:ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;">
+          <div aria-roledescription="email" role="article">
+          #{preview_text}
+          #{content}
+          </div>
+          </body>
+          </html>
+        HTML
+      end
+    end
+  end
+end

data/lib/sevk/markup/number_formatting.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Sevk
+  module Markup
+    module NumberFormatting
+      def js_number(value)
+        return '0' if value.zero?
+        return value.to_s unless value.finite?
+
+        digits, point = decimal_digits(value.abs)
+        text = if point.between?(digits.length, 21)
+                 digits + ('0' * (point - digits.length))
+               elsif point.positive? && point <= 21
+                 "#{digits[0...point]}.#{digits[point..]}"
+               elsif point > -6 && point <= 0
+                 "0.#{'0' * -point}#{digits}"
+               else
+                 exponent_notation(digits, point - 1)
+               end
+        value.negative? ? "-#{text}" : text
+      end
+
+      private
+
+      def decimal_digits(magnitude)
+        mantissa, exponent = magnitude.to_s.split('e')
+        integer_part, fraction_part = mantissa.split('.')
+        digits = integer_part + fraction_part.to_s.sub(/0+\z/, '')
+        leading_zeros = digits[/\A0*/].length
+        [digits[leading_zeros..], integer_part.length + exponent.to_i - leading_zeros]
+      end
+
+      def exponent_notation(digits, power)
+        sign = power.negative? ? '-' : '+'
+        mantissa = digits.length == 1 ? digits : "#{digits[0]}.#{digits[1..]}"
+        "#{mantissa}e#{sign}#{power.abs}"
+      end
+    end
+  end
+end

data/lib/sevk/markup/render_limits.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Sevk
+  module Markup
+    module RenderLimits
+      MAX_MARKUP_DEPTH = 64
+      MAX_TAG_ITERATIONS = 200
+      MAX_RENDER_OUTPUT = 5_000_000
+      MAX_TAG_SCAN_WORK = 30_000_000
+      TOO_COMPLEX = 'Email markup is too complex to render'
+
+      DEPTH_TAGS = %w[
+        block section column row container heading paragraph text button link sevk-link list li codeblock
+      ].freeze
+
+      private
+
+      def charge_scan_work(work)
+        @scan_work += work
+        raise ArgumentError, TOO_COMPLEX if @scan_work > MAX_TAG_SCAN_WORK
+      end
+
+      def assert_markup_depth(content)
+        depths = Hash.new(0)
+        index = 0
+
+        while (open = content.index('<', index))
+          close = content.index('>', open + 1)
+          break unless close
+
+          index = close + 1
+          position = open + 1
+          closing = content[position] == '/'
+          position += 1 if closing
+          name_end = position
+          name_end += 1 while name_end < close && content[name_end].match?(/[A-Za-z-]/)
+          name = content[position...name_end].downcase
+          next unless DEPTH_TAGS.include?(name)
+
+          if closing
+            depths[name] -= 1 if depths[name].positive?
+          elsif content[close - 1] != '/'
+            depths[name] += 1
+            if depths[name] > MAX_MARKUP_DEPTH
+              raise ArgumentError, "Email markup nesting exceeds the maximum depth of #{MAX_MARKUP_DEPTH}"
+            end
+          end
+        end
+      end
+    end
+  end
+end