cekat-event-sdk 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2916e118d56407e2f21b5e4520936221b46bc3d46a5744e24c1612f8b755a2ca
+  data.tar.gz: 206f9d1eb0068e404d1f1b510c767be62889b8de15877dace4b73320f3b9d05b
+SHA512:
+  metadata.gz: f33ec335fe1a10dcd10272a112ce49f80e2253dc786c9d8aeb1b7c51fb7df260ec9195fee184a6e4fafa2b7870d9c04744d1856cf6f2badeb5c3c9aee4d21700
+  data.tar.gz: b305914695eaaf96983c1b2ced8f4f5c78ead1d9b27f52b58c9afc0b330c21499e1de0ed240349e3736f8853ad3a7b195e44e81a6a8bd74ee6eb77a3809962c5

data/COMPATIBILITY.md

@@ -0,0 +1,48 @@
+# Ruby SDK compatibility evidence
+
+Retrieved: 2026-09-13 (UTC).
+
+## Official sources
+
+- Ruby maintenance branches: <https://www.ruby-lang.org/en/downloads/branches/> and <https://endoflife.date/api/v1/products/ruby/>
+- Rails maintenance policy: <https://rubyonrails.org/maintenance> and <https://endoflife.date/api/v1/products/rails/>
+- RubyGems metadata: `https://rubygems.org/api/v1/gems/<gem>.json`, `https://rubygems.org/api/v1/versions/<gem>.json`, and `https://rubygems.org/api/v2/rubygems/<gem>/versions/<version>.json`
+- Security advisories: `bundle-audit check --update` (ruby-advisory-db)
+
+## Ruby
+
+| Line | Status | End of life | Observed patch | `Fiber[]` / `Fiber[]=` |
+| --- | --- | --- | --- | --- |
+| 4.0 | normal maintenance | 2029-03-31 | 4.0.6 | available |
+| 3.4 | normal maintenance | 2028-03-31 | 3.4.10 | available |
+| 3.3 | security maintenance | 2027-03-31 | 3.3.12 | available |
+| 3.2 | end of life | 2026-03-31 | 3.2.11 | — |
+
+`required_ruby_version` is `>= 3.3.0`: the oldest maintained line. The visitor scope requires the fiber storage API (`Fiber[]`, Ruby 3.2+), verified on every tested interpreter.
+
+## Frameworks
+
+| Framework | Supported | Evidence |
+| --- | --- | --- |
+| Rails | 8.0, 8.1 | 8.1.3.1 (security support until 2027-10-10); 8.0.5.1 (security support until **2026-11-07**); both require Ruby >= 3.2.0. Rails 7.2 reached end of life on 2026-08-09. |
+| Rack | 2.2, 3.1, 3.2 | 3.2.7, 3.1.22, and 2.2.24 were all released 2026-08-13. The middleware uses only the Rack env protocol, so the gem declares no Rack dependency. |
+
+The gem has no runtime dependencies: it uses Ruby's default `json`, `net-http`, `securerandom`, `time`, and `uri` gems.
+
+## Development dependencies (latest observed)
+
+rspec 3.13.2, rubocop 1.91.0, json_schemer 2.5.0, bundler-audit 0.9.3, rake 13.4.2. Bundler 2.5.22 ships with Ruby 3.3.12 and 4.0.16 with Ruby 4.0.6.
+
+## Execution matrix (2026-09-13)
+
+Every row ran `rake spec` (core, Rack, transport, packaging, and Rails specs), RuboCop, and the shared conformance suite against `conformance/mock-ingest-server`: 54 cases passed and the 3 caller-cancellation cases were reported `not_applicable`.
+
+| Ruby | Rails | Rack | json | Specs |
+| --- | --- | --- | --- | --- |
+| 3.3.12 | 8.0.5.1 | 2.2.24 | 2.21.2 | 65 core + 6 Rails passed |
+| 3.4.10 | 8.1.3.1 | 3.1.22 | 3.0.2 | 65 core + 6 Rails passed |
+| 4.0.6 | 8.1.3.1 | 3.2.7 | 3.0.2 | 65 core + 6 Rails passed |
+
+The Rails 8.0 row pins `json` to 2.x (`JSON_VERSION="~> 2.7"`). Rails 8.0.5.1's `render json:` raises `ArgumentError: unknown keyword: quirks_mode` with json 3.0; this is a Rails 8.0/json 3 incompatibility, not an SDK constraint, and Rails 8.0 applications lock json 2.x. The SDK itself passes with json 2.21 and 3.0.
+
+`scripts/package` passed on Ruby 4.0.6, including `bundle-audit check --update` with no vulnerabilities found.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cekat AI
+
+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

@@ -0,0 +1,138 @@
+# Cekat Ruby Event SDK
+
+`cekat-event-sdk` submits identity-bearing Cekat events from Ruby backends and automatically attaches the browser visitor ID (from the `X-Cekat-Visitor-ID` header or `_cekat_visitor_id` cookie) of the request being handled.
+
+Requires Ruby 3.3 or newer. No runtime gem dependencies. Integrations: Rack middleware (Rack 2.2 and 3) and Rails 8.0–8.1.
+
+```ruby
+gem "cekat-event-sdk"
+```
+
+## Construct a client and submit events
+
+Construct one client and reuse it; it is thread-safe. Only the access token is required.
+
+```ruby
+require "cekat_event_sdk"
+
+CEKAT = CekatEventSdk::Client.new(access_token: ENV.fetch("CEKAT_ACCESS_TOKEN"))
+
+CEKAT.user_registration(email: "person@example.com", contact_name: "Person")
+CEKAT.user_login(phone_number: "+628123456789")
+CEKAT.order_created(email: "person@example.com", properties: { order_id: "o-1" })
+CEKAT.order_paid(email: "person@example.com", properties: { order_id: "o-1" }, amount: 125_000, currency: "IDR")
+ack = CEKAT.custom_event("wishlist_updated", email: "person@example.com")
+```
+
+Every event method also accepts a `CekatEventSdk::EventInput` or a Hash instead of keyword attributes. `order_paid` additionally requires a finite `amount:` (Integer, Float, BigDecimal, or Rational) and a nonblank `currency:`, sent as the `amount` and `currency` properties; do not also put those keys in `properties`.
+
+An `Acknowledgement` means Cekat accepted the event for **asynchronous processing**. It does not confirm durable storage, identity resolution, delivery completion, or analytics availability.
+
+At least one of `email` or `phone_number` must be nonblank. Identity and contact strings are sent unchanged. `properties` is `nil` (omitted) or a Hash with String or Symbol keys; values may be `nil`, `true`, `false`, UTF-8 Strings, Symbols (sent as strings), finite numbers, Arrays, and Hashes. Integers must be within ±9,007,199,254,740,991; BigDecimal and Rational are sent as floats. Other objects (including `Time` — use `time.iso8601`), cycles, non-String keys, and duplicate keys after Symbol conversion raise `CekatEventSdk::ValidationError` before any request.
+
+## Event IDs and timestamps
+
+Every event carries an `event_id` and an `occurred_at` timestamp. When `event_id` is blank the SDK generates a random UUID, and when `occurred_at` (a `Time`, `DateTime`, or `ActiveSupport::TimeWithZone`) is omitted it uses the time of the call. Both are fixed before the first attempt and reused by every retry, so Cekat can recognize retried deliveries. Supply your own `event_id` when the same business event may be sent more than once:
+
+```ruby
+CEKAT.order_paid(email: order.email, event_id: "order-paid-#{order.id}", occurred_at: order.paid_at,
+                 amount: order.total, currency: order.currency)
+```
+
+## Request visitor context
+
+Install the integration at the request boundary. While the request is handled, event calls attach its visitor ID automatically. A nonblank explicit `visitor_id:` takes precedence; a blank one falls back to the request. Visitor IDs are untrusted correlation data: never use them for authentication or authorization.
+
+### Rails
+
+The Railtie inserts `CekatEventSdk::Rails::Middleware` automatically. The request visitor is available to the client and as `CekatEventSdk::Rails::Current.visitor_id`. To insert the middleware yourself, set `config.cekat_event_sdk.insert_middleware = false` and add it where you want in the stack.
+
+```ruby
+# config/initializers/cekat.rb
+CEKAT = CekatEventSdk::Client.new(access_token: Rails.application.credentials.cekat_access_token)
+```
+
+### Rack (Sinatra, Hanami, Roda, and others)
+
+```ruby
+use CekatEventSdk::Rack::Middleware
+```
+
+The middleware also exposes the value as `env["cekat_event_sdk.visitor_id"]`. It reads the raw `Cookie` header and never modifies the request, response, or cookies.
+
+### Without middleware
+
+```ruby
+CEKAT.with_visitor_id(visitor_id) do
+  CEKAT.user_login(email: "person@example.com")
+end
+```
+
+### Scope and concurrency
+
+The visitor scope lives in fiber storage (`Fiber[]`), so it is isolated per request under threaded servers (Puma) and fiber-based servers (Falcon). Every scope restores the previous visitor when it ends, including when it raises, so long-running workers never leak a visitor ID between requests. Threads and fibers started inside a request begin with a copy of its scope. The scope ends when the middleware returns, so events emitted while a streaming response body is iterated must pass `visitor_id:` explicitly.
+
+## Keep tracking off the request's critical path
+
+Calls are synchronous, so each event adds its round-trip to the request. To send in the background, capture the visitor ID while the request scope is active and pass it explicitly:
+
+```ruby
+visitor_id = CekatEventSdk::VisitorContext.current_visitor_id
+TrackLoginJob.perform_later(user.email, visitor_id)
+
+class TrackLoginJob < ApplicationJob
+  def perform(email, visitor_id)
+    CEKAT.user_login(email: email, visitor_id: visitor_id)
+  end
+end
+```
+
+Jobs run outside the request, so they never see its scope; later events that carry the contact's email or phone number do not need a visitor ID. Rescue and log errors in background work.
+
+## Errors and retries
+
+All errors inherit from `CekatEventSdk::Error`, which exposes `attempts` and `delivery_outcome_unknown?`:
+
+| Error | Meaning |
+| --- | --- |
+| `ValidationError` | Invalid configuration or event input; nothing was sent. |
+| `AuthenticationError` | HTTP 401. Inherits from `ApiError`. |
+| `EventDefinitionNotFoundError` | HTTP 404. Inherits from `ApiError`. |
+| `ApiError` | Any other non-200 response: `status`, `code`, bounded `raw_body`. |
+| `ResponseDecodeError` | HTTP 200 whose body was invalid, over 65,536 bytes, or unreadable. The event was received. |
+| `TransportError` | No response after all attempts. `delivery_outcome_unknown?` is `true`: Cekat may have received it. |
+
+```ruby
+begin
+  CEKAT.order_paid(email: email, amount: 125_000, currency: "IDR")
+rescue CekatEventSdk::TransportError => e
+  Rails.logger.warn("Cekat unreachable after #{e.attempts} attempts; delivery outcome unknown")
+rescue CekatEventSdk::ApiError => e
+  Rails.logger.error("Cekat rejected the event (#{e.status}): #{e.message}")
+end
+```
+
+Response bodies retained in errors are capped at 65,536 bytes. Error messages never include request headers, and `Client#inspect` omits the access token.
+
+Transport failures, timeouts, and HTTP 429, 500, 502, 503, and 504 are retried, up to `retry_count` retries (default 2). Delays use capped exponential full jitter (up to 100ms, 200ms, 400ms, 800ms, then 1s). A valid `Retry-After` header raises the delay to the server's value; above 5 seconds the SDK raises immediately instead of blocking. Other statuses, including 400, 401, and 404, are not retried, and a received 200 is never retried. A retry after an unknown outcome can create a **duplicate** event; retries reuse the same `event_id`, but the SDK does not guarantee server-side deduplication.
+
+## Configuration
+
+```ruby
+CekatEventSdk::Client.new(access_token: token, base_url: "https://server.cekat.ai", timeout: 3, retry_count: 2)
+```
+
+`base_url` must be an absolute HTTP(S) origin without credentials, path, query, or fragment; the SDK always posts to `/api/events/ingest`. Requests send `User-Agent: cekat-event-sdk-ruby/<version>`.
+
+The Net::HTTP transport opens a fresh connection per attempt, never follows redirects, reads at most 65,537 response bytes, and applies `timeout` to connecting, writing, waiting for the response, and reading the body. Ruby has no portable caller cancellation, so bound each call with `timeout` and `retry_count`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake            # core, Rack, and Rails specs plus RuboCop
+RAILS_VERSION="~> 8.0.0" RACK_VERSION="~> 2.2" bundle update && bundle exec rake spec
+./scripts/package --version 0.1.0 --output /absolute/empty-directory
+```
+
+`scripts/package` runs the specs, RuboCop, and `bundle-audit`, then builds the gem and a SHA-256 `manifest.json`. It never pushes, signs, or tags; releases to RubyGems run from the repository's `release-ruby.yml` workflow when a `ruby/vX.Y.Z` tag is pushed. `scripts/conformance` runs the shared conformance fixtures (see `conformance/README.md`); the three caller-cancellation cases are reported as `not_applicable` for Ruby.

data/lib/cekat-event-sdk.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "cekat_event_sdk"

data/lib/cekat_event_sdk/acknowledgement.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  # Cekat accepted the event for asynchronous processing. This does not confirm durable
+  # storage, identity resolution, delivery completion, or analytics availability.
+  Acknowledgement = Data.define(:success, :message, :event_key, :validated_properties, :raw_body)
+end

data/lib/cekat_event_sdk/client.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module CekatEventSdk
+  # Submits Cekat events synchronously. Construct one client and reuse it; it is thread-safe.
+  #
+  # Each method returns an Acknowledgement (accepted for asynchronous processing) or raises:
+  # ValidationError before any request; AuthenticationError (401), EventDefinitionNotFoundError
+  # (404), or ApiError for other non-200 responses; ResponseDecodeError for an invalid or
+  # unreadable 200; TransportError when no response was received. Retries can create duplicate
+  # events; every retry reuses the call's event_id.
+  class Client
+    attr_reader :base_url, :timeout, :retry_count
+
+    # sleeper, random, and payload_builder are test seams.
+    def initialize(access_token:, base_url: DEFAULT_BASE_URL, timeout: 3, retry_count: 2, transport: Transport.new,
+                   visitor_context: VisitorContext, sleeper: ->(seconds) { sleep(seconds) }, random: Random.new,
+                   payload_builder: PayloadBuilder.new)
+      raise ValidationError, "access token must not be blank" unless access_token.is_a?(String) && !access_token.strip.empty?
+      unless timeout.is_a?(Numeric) && timeout.real? && timeout.to_f.finite? && timeout.positive?
+        raise ValidationError, "timeout must be a finite number of seconds greater than zero"
+      end
+      raise ValidationError, "retry count must be a nonnegative Integer" unless retry_count.is_a?(Integer) && !retry_count.negative?
+
+      @access_token = access_token
+      @base_url = normalize_origin(base_url)
+      @timeout = timeout
+      @retry_count = retry_count
+      @transport = transport
+      @visitor_context = visitor_context
+      @sleeper = sleeper
+      @random = random
+      @payload_builder = payload_builder
+    end
+
+    # Each event method accepts an EventInput, a Hash, or keyword attributes:
+    #   client.user_login(email: "person@example.com", properties: { plan: "pro" })
+    def user_registration(event = nil, **attributes)
+      track("user_registration", true, event_from(event, attributes))
+    end
+
+    def user_login(event = nil, **attributes)
+      track("user_login", true, event_from(event, attributes))
+    end
+
+    def order_created(event = nil, **attributes)
+      track("order_created", true, event_from(event, attributes))
+    end
+
+    # The required finite amount and nonblank currency are sent as the "amount" and "currency"
+    # properties; the event's properties must not already contain either key.
+    def order_paid(event = nil, amount:, currency:, **attributes)
+      track("order_paid", true, PayloadBuilder.with_order_paid_properties(amount, currency, event_from(event, attributes)))
+    end
+
+    def custom_event(event_key, event = nil, **attributes)
+      track(event_key, false, event_from(event, attributes))
+    end
+
+    # Runs the block with visitor_id as the current visitor (see VisitorContext.with).
+    def with_visitor_id(visitor_id, &)
+      VisitorContext.with(visitor_id, &)
+    end
+
+    def inspect
+      "#<#{self.class.name} base_url=#{@base_url.inspect} timeout=#{@timeout} retry_count=#{@retry_count}>"
+    end
+    alias to_s inspect
+
+    private
+
+    def event_from(event, attributes)
+      raise ValidationError, "pass an event or keyword attributes, not both" if event && !attributes.empty?
+
+      case event
+      when EventInput then event
+      when nil then EventInput.new(**attributes)
+      when Hash then EventInput.new(**event.transform_keys(&:to_sym))
+      else raise ValidationError, "event must be a CekatEventSdk::EventInput or Hash"
+      end
+    rescue ArgumentError => e
+      raise ValidationError, "invalid event attributes: #{e.message}"
+    end
+
+    def track(event_key, is_common, event)
+      # Encoded once so every retry sends the same event ID and timestamp.
+      body = @payload_builder.build(event_key, is_common, event, @visitor_context.current_visitor_id)
+      headers = {
+        "Authorization" => "Bearer #{@access_token}",
+        "Content-Type" => "application/json",
+        "User-Agent" => "cekat-event-sdk-ruby/#{VERSION} ruby/#{RUBY_VERSION}"
+      }
+      deliver("#{@base_url}#{INGEST_PATH}", headers, body)
+    end
+
+    def deliver(url, headers, body)
+      maximum_attempts = @retry_count + 1
+      attempt = 0
+      loop do
+        attempt += 1
+        begin
+          response = @transport.post(uri: url, headers: headers, body: body, timeout: @timeout)
+        rescue Transport::Failure
+          raise TransportError.new("Cekat API request failed before a response was received", attempts: attempt) if attempt >= maximum_attempts
+
+          backoff(attempt, nil)
+          next
+        end
+
+        # Retry is decided by status alone, even when the body read failed.
+        if attempt < maximum_attempts && RetryPolicy.retryable_status?(response.status)
+          retry_after = RetryPolicy.parse_retry_after_ms(response.header("Retry-After"), (Time.now.to_r * 1_000).to_i)
+          if retry_after.nil? || retry_after <= RetryPolicy::MAXIMUM_RETRY_AFTER_MS
+            backoff(attempt, retry_after)
+            next
+          end
+          # The server asked for a longer pause than a caller should wait: report it now.
+        end
+
+        return ResponseDecoder.decode(response, attempt)
+      end
+    end
+
+    def backoff(retry_number, retry_after_ms)
+      jitter = @random.rand(RetryPolicy.delay_bound_ms(retry_number) + 1)
+      @sleeper.call([jitter, retry_after_ms || 0].max / 1000.0)
+    end
+
+    def normalize_origin(base_url)
+      invalid = ValidationError.new("base URL must be an absolute HTTP(S) origin without credentials, path, query, or fragment")
+      raise invalid unless base_url.is_a?(String) && !base_url.match?(/[\s?#]/)
+
+      uri = URI.parse(base_url)
+      unless %w[http https].include?(uri.scheme&.downcase) && uri.host && !uri.host.empty? && uri.userinfo.nil? &&
+             ["", "/"].include?(uri.path)
+        raise invalid
+      end
+
+      default_port = uri.scheme.casecmp?("https") ? 443 : 80
+      "#{uri.scheme.downcase}://#{uri.host.downcase}#{":#{uri.port}" if uri.port != default_port}"
+    rescue URI::InvalidURIError
+      raise invalid
+    end
+  end
+end

data/lib/cekat_event_sdk/errors.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  # Base class for every error raised by the SDK.
+  class Error < StandardError
+    # Number of HTTP attempts made; zero when nothing was sent.
+    attr_reader :attempts
+
+    def initialize(message = nil, attempts: 0)
+      super(message)
+      @attempts = attempts
+    end
+
+    # Whether Cekat may have received the event even though no response was seen.
+    def delivery_outcome_unknown?
+      false
+    end
+  end
+
+  # Invalid configuration or event input, detected before any request.
+  class ValidationError < Error; end
+
+  # Cekat returned a non-200 response. The delivery outcome is known.
+  class ApiError < Error
+    attr_reader :status, :code, :raw_body
+
+    # raw_body holds at most the first 65,536 response bytes.
+    def initialize(message, status:, code:, raw_body:, attempts:)
+      super(message, attempts: attempts)
+      @status = status
+      @code = code
+      @raw_body = raw_body
+    end
+  end
+
+  # HTTP 401: Cekat rejected the access token.
+  class AuthenticationError < ApiError; end
+
+  # HTTP 404: the tenant has no definition for the event key.
+  class EventDefinitionNotFoundError < ApiError; end
+
+  # No response was received after all attempts. Cekat may have received the event,
+  # so resending it can create a duplicate.
+  class TransportError < Error
+    def delivery_outcome_unknown?
+      true
+    end
+  end
+
+  # HTTP 200 whose body was invalid, over 65,536 bytes, or unreadable. The event was received.
+  class ResponseDecodeError < Error
+    attr_reader :raw_body
+
+    def initialize(message, raw_body:, attempts:)
+      super(message, attempts: attempts)
+      @raw_body = raw_body
+    end
+
+    def status
+      200
+    end
+  end
+end

data/lib/cekat_event_sdk/event_input.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  # An identity-bearing event. At least one of email or phone_number must be nonblank.
+  #
+  # properties is nil (omitted) or a Hash with String or Symbol keys. Values may be nil, true,
+  # false, Strings, Symbols, finite numbers (Integer, Float, BigDecimal, Rational), Arrays, and
+  # Hashes of those. event_id deduplicates retried deliveries and defaults to a random UUID;
+  # occurred_at (a Time or DateTime) defaults to the time of the call.
+  EventInput = Data.define(:email, :phone_number, :contact_name, :visitor_id, :properties, :event_id, :occurred_at) do
+    def initialize(email: nil, phone_number: nil, contact_name: nil, visitor_id: nil, properties: nil, event_id: nil, occurred_at: nil)
+      super
+    end
+  end
+end

data/lib/cekat_event_sdk/payload_builder.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module CekatEventSdk
+  # Validates event input and builds the JSON request body.
+  # @api private
+  class PayloadBuilder
+    MAX_SAFE_INTEGER = 9_007_199_254_740_991
+    MAX_DEPTH = 256
+    STRING_FIELDS = %i[email phone_number contact_name visitor_id event_id].freeze
+
+    def initialize(clock: -> { Time.now }, id_generator: -> { SecureRandom.uuid })
+      @clock = clock
+      @id_generator = id_generator
+    end
+
+    # Returns a copy of event whose properties include the required order_paid arguments.
+    def self.with_order_paid_properties(amount, currency, event)
+      raise ValidationError, "amount must be a finite number" unless amount.is_a?(Numeric) && amount.real? && (amount.is_a?(Integer) || amount.to_f.finite?)
+      raise ValidationError, "currency must not be blank" unless currency.is_a?(String) && !currency.strip.empty?
+      return event unless event.is_a?(EventInput) && (event.properties.nil? || event.properties.is_a?(Hash))
+
+      properties = event.properties || {}
+      %w[amount currency].each do |reserved|
+        if properties.key?(reserved) || properties.key?(reserved.to_sym)
+          raise ValidationError, "properties must not contain #{reserved.inspect}; pass it as the order_paid argument"
+        end
+      end
+      event.with(properties: properties.merge("amount" => amount, "currency" => currency))
+    end
+
+    def build(event_key, is_common, event, ambient_visitor_id)
+      raise ValidationError, "event key must not be blank" unless event_key.is_a?(String) && !event_key.strip.empty?
+      raise ValidationError, "event must be a CekatEventSdk::EventInput" unless event.is_a?(EventInput)
+
+      STRING_FIELDS.each do |field|
+        value = event.public_send(field)
+        raise ValidationError, "#{field} must be a String" unless value.nil? || value.is_a?(String)
+      end
+      raise ValidationError, "event must include a nonblank email or phone number" if blank?(event.email) && blank?(event.phone_number)
+
+      payload = {
+        "event_key" => utf8(event_key, "event_key"),
+        "event_id" => VisitorIdResolver.normalize(event.event_id) || @id_generator.call,
+        "occurred_at" => occurred_at(event.occurred_at),
+        "is_common" => is_common
+      }
+      payload["email"] = utf8(event.email, "email") unless event.email.nil?
+      payload["phone_number"] = utf8(event.phone_number, "phone_number") unless event.phone_number.nil?
+      payload["contact_name"] = utf8(event.contact_name, "contact_name") unless event.contact_name.nil?
+      visitor_id = VisitorIdResolver.normalize(event.visitor_id) || VisitorIdResolver.normalize(ambient_visitor_id)
+      payload["visitor_id"] = utf8(visitor_id, "visitor_id") if visitor_id
+      unless event.properties.nil?
+        raise ValidationError, "properties must be a Hash" unless event.properties.is_a?(Hash)
+
+        payload["properties"] = normalize(event.properties, "properties", {}.compare_by_identity, 0)
+      end
+
+      JSON.generate(payload)
+    rescue JSON::GeneratorError
+      raise ValidationError, "event is not JSON-compatible"
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || value.strip.empty?
+    end
+
+    def occurred_at(value)
+      time = value.nil? ? @clock.call : value
+      raise ValidationError, "occurred_at must be a Time or DateTime" unless time.is_a?(Time) || (defined?(::DateTime) && time.is_a?(::DateTime))
+
+      utc = time.is_a?(Time) ? time.getutc : time.to_time.utc
+      raise ValidationError, "occurred_at must be between years 0001 and 9999" unless (1..9999).cover?(utc.year)
+
+      utc.strftime("%Y-%m-%dT%H:%M:%S.%LZ")
+    end
+
+    def utf8(value, path)
+      string = value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding(Encoding::UTF_8)
+      raise ValidationError, "#{path} must be valid UTF-8" unless string.valid_encoding?
+
+      string
+    end
+
+    def normalize(value, path, ancestors, depth)
+      raise ValidationError, "#{path} is nested too deeply" if depth > MAX_DEPTH
+
+      case value
+      when nil, true, false then value
+      when String then utf8(value, path)
+      when Symbol then utf8(value.to_s, path)
+      when Integer
+        raise invalid(path) unless value.between?(-MAX_SAFE_INTEGER, MAX_SAFE_INTEGER)
+
+        value
+      when Float then portable_float(value, path)
+      when Numeric
+        raise invalid(path) unless value.real?
+
+        portable_float(value.to_f, path)
+      when Array
+        within(value, path, ancestors) do
+          value.each_with_index.map { |item, index| normalize(item, "#{path}[#{index}]", ancestors, depth + 1) }
+        end
+      when Hash
+        within(value, path, ancestors) do
+          value.each_with_object({}) do |(key, item), object|
+            raise ValidationError, "#{path} has a #{key.class} key; property keys must be Strings or Symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+
+            name = utf8(key.to_s, path)
+            raise ValidationError, "#{path} has duplicate key #{name.inspect}" if object.key?(name)
+
+            object[name] = normalize(item, name.empty? ? "#{path}[\"\"]" : "#{path}.#{name}", ancestors, depth + 1)
+          end
+        end
+      else
+        raise invalid(path)
+      end
+    end
+
+    def portable_float(value, path)
+      raise invalid(path) unless value.finite?
+      raise invalid(path) if value == value.truncate && value.abs > MAX_SAFE_INTEGER
+
+      value
+    end
+
+    def within(container, path, ancestors)
+      raise ValidationError, "#{path} contains a cycle" if ancestors.key?(container)
+
+      # Only containers on the current path are tracked, so repeated references are allowed.
+      ancestors[container] = true
+      result = yield
+      ancestors.delete(container)
+      result
+    end
+
+    def invalid(path)
+      ValidationError.new("#{path} is not a JSON-compatible value")
+    end
+  end
+end

data/lib/cekat_event_sdk/rack/middleware.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  module Rack
+    # Rack middleware (Sinatra, Hanami, Roda, and other Rack apps) that scopes the request's
+    # visitor ID while the downstream app runs. It exposes the value as
+    # env["cekat_event_sdk.visitor_id"] and never changes headers, cookies, or the response.
+    #
+    # The scope ends when call returns, so events emitted while a streaming body is iterated
+    # must pass visitor_id explicitly.
+    class Middleware
+      ENV_KEY = "cekat_event_sdk.visitor_id"
+
+      def initialize(app, visitor_context: VisitorContext)
+        @app = app
+        @visitor_context = visitor_context
+      end
+
+      def call(env)
+        had_previous = env.key?(ENV_KEY)
+        previous = env[ENV_KEY]
+        visitor_id = VisitorIdResolver.from_rack_env(env)
+        visitor_id ? env[ENV_KEY] = visitor_id : env.delete(ENV_KEY)
+        begin
+          @visitor_context.with(visitor_id) { @app.call(env) }
+        ensure
+          had_previous ? env[ENV_KEY] = previous : env.delete(ENV_KEY)
+        end
+      end
+    end
+  end
+end

data/lib/cekat_event_sdk/rails.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_support"
+require "active_support/current_attributes"
+require "rails/railtie"
+
+module CekatEventSdk
+  # Rails integration. The Railtie inserts CekatEventSdk::Rails::Middleware, which exposes the
+  # request visitor as CekatEventSdk::Rails::Current.visitor_id and scopes it for the client.
+  module Rails
+    # Request-scoped attributes; visitor_id is set by Middleware for each request.
+    class Current < ActiveSupport::CurrentAttributes
+      attribute :visitor_id
+    end
+
+    # Reads the visitor from CurrentAttributes; pass as a client's visitor_context when code
+    # sets Current.visitor_id itself (for example in a job).
+    module VisitorContext
+      module_function
+
+      def current_visitor_id
+        Current.visitor_id || CekatEventSdk::VisitorContext.current_visitor_id
+      end
+    end
+
+    # Scopes the request visitor for Current and for CekatEventSdk::VisitorContext.
+    class Middleware
+      def initialize(app)
+        @app = app
+      end
+
+      # Current.set restores the previous attributes when the block exits, and Rails resets
+      # CurrentAttributes after each request, so no state crosses requests.
+      def call(env)
+        visitor_id = VisitorIdResolver.from_rack_env(env)
+        Current.set(visitor_id: visitor_id) do
+          CekatEventSdk::VisitorContext.with(visitor_id) { @app.call(env) }
+        end
+      end
+    end
+
+    # Inserts Middleware unless config.cekat_event_sdk.insert_middleware is false.
+    class Railtie < ::Rails::Railtie
+      config.cekat_event_sdk = ActiveSupport::OrderedOptions.new
+      config.cekat_event_sdk.insert_middleware = true
+
+      initializer "cekat_event_sdk.middleware" do |app|
+        app.middleware.use CekatEventSdk::Rails::Middleware if app.config.cekat_event_sdk.insert_middleware
+      end
+    end
+  end
+end

data/lib/cekat_event_sdk/response_decoder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+
+module CekatEventSdk
+  # Maps a received response to an Acknowledgement or a typed error.
+  # @api private
+  module ResponseDecoder
+    STATUS_TEXT = {
+      400 => "Bad Request", 401 => "Unauthorized", 403 => "Forbidden", 404 => "Not Found",
+      405 => "Method Not Allowed", 408 => "Request Timeout", 409 => "Conflict", 413 => "Content Too Large",
+      415 => "Unsupported Media Type", 418 => "I'm a teapot", 422 => "Unprocessable Content", 429 => "Too Many Requests",
+      500 => "Internal Server Error", 501 => "Not Implemented", 502 => "Bad Gateway",
+      503 => "Service Unavailable", 504 => "Gateway Timeout"
+    }.freeze
+
+    module_function
+
+    def decode(response, attempts)
+      return acknowledgement(response, attempts) if response.status == 200
+
+      message, code = error_envelope(response.body) || [fallback_message(response), nil]
+      error_class = { 401 => AuthenticationError, 404 => EventDefinitionNotFoundError }.fetch(response.status, ApiError)
+      raise error_class.new(message, status: response.status, code: code, raw_body: response.body, attempts: attempts)
+    end
+
+    def acknowledgement(response, attempts)
+      body = response.body
+      if response.body_read_failure
+        raise ResponseDecodeError.new("response body could not be read", raw_body: body, attempts: attempts),
+              cause: response.body_read_failure
+      end
+      raise ResponseDecodeError.new("response body exceeds #{MAXIMUM_RESPONSE_BODY_BYTES} bytes", raw_body: body, attempts: attempts) if response.body_truncated
+
+      envelope = parse(body)
+      data = envelope.is_a?(Hash) ? envelope["data"] : nil
+      properties = data.is_a?(Hash) ? data["validated_properties"] : nil
+      valid = envelope.is_a?(Hash) && envelope["success"] == true && data.is_a?(Hash) && data["success"] == true &&
+              nonempty_string?(data["message"]) && nonempty_string?(data["event_key"]) &&
+              properties.is_a?(Array) && properties.all?(String)
+      raise ResponseDecodeError.new("response body is not a valid success envelope", raw_body: body, attempts: attempts) unless valid
+
+      Acknowledgement.new(success: true, message: data["message"], event_key: data["event_key"],
+                          validated_properties: properties.freeze, raw_body: body)
+    rescue JSON::ParserError, EncodingError
+      raise ResponseDecodeError.new("response body is not valid JSON", raw_body: body, attempts: attempts)
+    end
+
+    def error_envelope(body)
+      envelope = parse(body)
+      return nil unless envelope.is_a?(Hash) && envelope["success"] == false && nonempty_string?(envelope["error"])
+      return [envelope["error"], nil] unless envelope.key?("code")
+
+      envelope["code"].is_a?(String) ? [envelope["error"], envelope["code"]] : nil
+    rescue JSON::ParserError, EncodingError
+      nil
+    end
+
+    def fallback_message(response)
+      reason = response.reason.to_s.strip
+      reason.empty? ? STATUS_TEXT.fetch(response.status, "HTTP #{response.status}") : reason
+    end
+
+    def parse(body)
+      JSON.parse(body)
+    end
+
+    def nonempty_string?(value)
+      value.is_a?(String) && !value.empty?
+    end
+  end
+end

data/lib/cekat_event_sdk/retry_policy.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "time"
+
+module CekatEventSdk
+  # @api private
+  module RetryPolicy
+    MAXIMUM_RETRY_AFTER_MS = 5_000
+    RETRYABLE_STATUSES = [429, 500, 502, 503, 504].freeze
+    HTTP_DATE = /\A(?:
+      [A-Za-z]{3},\ \d{2}\ [A-Za-z]{3}\ \d{4}\ \d{2}:\d{2}:\d{2}\ GMT |   # IMF-fixdate
+      [A-Za-z]{6,9},\ \d{2}-[A-Za-z]{3}-\d{2}\ \d{2}:\d{2}:\d{2}\ GMT |  # RFC 850
+      [A-Za-z]{3}\ [A-Za-z]{3}\ [\ \d]\d\ \d{2}:\d{2}:\d{2}\ \d{4}       # asctime
+    )\z/x
+
+    module_function
+
+    def retryable_status?(status)
+      RETRYABLE_STATUSES.include?(status)
+    end
+
+    # Full-jitter upper bound before one-indexed retry: 100ms doubling to a 1s cap.
+    def delay_bound_ms(retry_number)
+      [100 * (2**(retry_number.clamp(1, 5) - 1)), 1_000].min
+    end
+
+    # Parses Retry-After delta-seconds or an HTTP-date; nil when absent or invalid.
+    def parse_retry_after_ms(value, now_ms)
+      trimmed = value.to_s.strip
+      return nil if trimmed.empty?
+      return trimmed.length > 9 ? Float::INFINITY : Integer(trimmed, 10) * 1_000 if trimmed.match?(/\A\d+\z/)
+      return nil unless trimmed.match?(HTTP_DATE)
+
+      [(Time.parse("#{trimmed} UTC").to_r * 1_000).to_i - now_ms, 0].max
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/cekat_event_sdk/transport.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "uri"
+
+module CekatEventSdk
+  # Default Net::HTTP transport. Each attempt opens a fresh connection (so nothing is silently
+  # resent on a stale keep-alive connection), never follows redirects, bounds connect, write,
+  # header, and body time by the timeout, and reads at most 65,537 body bytes.
+  class Transport
+    # Raised when no response status was received. The message never contains request headers.
+    class Failure < StandardError
+      def self.from(error)
+        new("#{error.class}: #{error.message}")
+      end
+    end
+
+    # A received response. body holds at most 65,536 bytes; body_read_failure is set when
+    # the status arrived but the body could not be read.
+    Response = Data.define(:status, :reason, :headers, :body, :body_truncated, :observed_body_bytes, :body_read_failure) do
+      def header(name)
+        headers.each { |key, values| return values.first if key.casecmp?(name) }
+        nil
+      end
+    end
+
+    class BodyDeadlineExceeded < StandardError; end
+    private_constant :BodyDeadlineExceeded
+
+    def post(uri:, headers:, body:, timeout:)
+      uri = URI(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.ssl_timeout = timeout if http.use_ssl?
+      http.max_retries = 0
+      # Net::HTTP defaults to treating a connection closed before Content-Length as a complete
+      # body; a truncated response must be reported as a body read failure instead.
+      http.ignore_eof = false
+
+      request = Net::HTTP::Post.new(uri.request_uri, headers)
+      request.body = body
+      deadline = monotonic + timeout
+      state = { head: nil, buffer: +"", failure: nil }
+
+      catch(:body_limit) do
+        http.start do |connection|
+          connection.request(request) do |response|
+            state[:head] = response
+            response.read_body do |chunk|
+              room = MAXIMUM_RESPONSE_BODY_BYTES + 1 - state[:buffer].bytesize
+              state[:buffer] << chunk.byteslice(0, room) if room.positive?
+              throw :body_limit if state[:buffer].bytesize > MAXIMUM_RESPONSE_BODY_BYTES
+              raise BodyDeadlineExceeded, "response body exceeded the #{timeout}s timeout" if monotonic > deadline
+            end
+          end
+        end
+      end
+      response_from(state)
+    rescue StandardError => e
+      raise Failure.from(e) if state.nil? || state[:head].nil?
+
+      state[:failure] = Failure.from(e)
+      response_from(state)
+    end
+
+    private
+
+    def response_from(state)
+      head = state[:head]
+      buffer = state[:buffer]
+      Response.new(
+        status: head.code.to_i,
+        reason: head.message.to_s,
+        headers: head.to_hash,
+        body: buffer.byteslice(0, MAXIMUM_RESPONSE_BODY_BYTES).force_encoding(Encoding::UTF_8),
+        body_truncated: buffer.bytesize > MAXIMUM_RESPONSE_BODY_BYTES,
+        observed_body_bytes: buffer.bytesize,
+        body_read_failure: buffer.bytesize > MAXIMUM_RESPONSE_BODY_BYTES ? nil : state[:failure]
+      )
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/cekat_event_sdk/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  VERSION = "0.1.0"
+end

data/lib/cekat_event_sdk/visitor_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  # Request-local visitor scope stored in fiber storage (Fiber[]), so it is isolated per
+  # request fiber under threaded (Puma) and fiber-based (Falcon) servers. Fibers and threads
+  # created inside a scope start with a copy of it. Visitor IDs are untrusted correlation data:
+  # never use them for authentication or authorization.
+  module VisitorContext
+    STORAGE_KEY = :cekat_event_sdk_visitor_id
+
+    module_function
+
+    def current_visitor_id
+      Fiber[STORAGE_KEY]
+    end
+
+    # Runs the block with visitor_id (trimmed; blank means none) as the current visitor and
+    # restores the previous value afterwards, including when the block raises.
+    def with(visitor_id)
+      previous = Fiber[STORAGE_KEY]
+      Fiber[STORAGE_KEY] = VisitorIdResolver.normalize(visitor_id)
+      begin
+        yield
+      ensure
+        Fiber[STORAGE_KEY] = previous
+      end
+    end
+  end
+end

data/lib/cekat_event_sdk/visitor_id_resolver.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module CekatEventSdk
+  # Resolves the browser visitor ID: a nonblank X-Cekat-Visitor-ID header wins over a nonblank
+  # _cekat_visitor_id cookie. Values are trimmed and otherwise not decoded.
+  module VisitorIdResolver
+    module_function
+
+    # Trims a visitor ID; blank or non-String values become nil.
+    def normalize(visitor_id)
+      return nil unless visitor_id.is_a?(String)
+
+      trimmed = visitor_id.strip
+      trimmed.empty? ? nil : trimmed
+    end
+
+    def from_header_and_cookie(header:, cookie:)
+      normalize(header) || normalize(cookie)
+    end
+
+    # Returns the first nonblank _cekat_visitor_id value in a raw Cookie header.
+    def from_cookie_header(cookie_header)
+      return nil unless cookie_header.is_a?(String)
+
+      cookie_header.split(";").each do |pair|
+        name, separator, value = pair.partition("=")
+        next if separator.empty? || name.strip != VISITOR_COOKIE
+
+        visitor_id = normalize(value)
+        return visitor_id if visitor_id
+      end
+      nil
+    end
+
+    # Resolves from a Rack env. The raw Cookie header is used so values are never unescaped.
+    def from_rack_env(env)
+      from_header_and_cookie(header: env["HTTP_X_CEKAT_VISITOR_ID"], cookie: from_cookie_header(env["HTTP_COOKIE"]))
+    end
+  end
+end

data/lib/cekat_event_sdk.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "cekat_event_sdk/version"
+
+# Cekat event SDK: submit identity-bearing events and correlate them with the browser visitor.
+module CekatEventSdk
+  DEFAULT_BASE_URL = "https://server.cekat.ai"
+  INGEST_PATH = "/api/events/ingest"
+  VISITOR_HEADER = "X-Cekat-Visitor-ID"
+  VISITOR_COOKIE = "_cekat_visitor_id"
+  MAXIMUM_RESPONSE_BODY_BYTES = 65_536
+end
+
+require_relative "cekat_event_sdk/errors"
+require_relative "cekat_event_sdk/event_input"
+require_relative "cekat_event_sdk/acknowledgement"
+require_relative "cekat_event_sdk/visitor_id_resolver"
+require_relative "cekat_event_sdk/visitor_context"
+require_relative "cekat_event_sdk/payload_builder"
+require_relative "cekat_event_sdk/retry_policy"
+require_relative "cekat_event_sdk/transport"
+require_relative "cekat_event_sdk/response_decoder"
+require_relative "cekat_event_sdk/client"
+require_relative "cekat_event_sdk/rack/middleware"
+require_relative "cekat_event_sdk/rails" if defined?(Rails::Railtie)

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: cekat-event-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Cekat
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Synchronous Cekat event client with Rack middleware and a Rails integration
+  that attach the browser visitor ID of the current request automatically.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- COMPATIBILITY.md
+- LICENSE
+- README.md
+- lib/cekat-event-sdk.rb
+- lib/cekat_event_sdk.rb
+- lib/cekat_event_sdk/acknowledgement.rb
+- lib/cekat_event_sdk/client.rb
+- lib/cekat_event_sdk/errors.rb
+- lib/cekat_event_sdk/event_input.rb
+- lib/cekat_event_sdk/payload_builder.rb
+- lib/cekat_event_sdk/rack/middleware.rb
+- lib/cekat_event_sdk/rails.rb
+- lib/cekat_event_sdk/response_decoder.rb
+- lib/cekat_event_sdk/retry_policy.rb
+- lib/cekat_event_sdk/transport.rb
+- lib/cekat_event_sdk/version.rb
+- lib/cekat_event_sdk/visitor_context.rb
+- lib/cekat_event_sdk/visitor_id_resolver.rb
+homepage: https://github.com/cekataiofficial/cekat-event-sdk
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cekataiofficial/cekat-event-sdk/tree/main/ruby
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Submit identity-bearing Cekat events from Ruby backends with browser visitor
+  correlation.
+test_files: []