risenexa-tracking 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ab27b33f1e1dc89d57f6d1e8801636789b1a5b42ec7310ca06543275699d448
+  data.tar.gz: 236824c91e9e7c55a7df530cb6ae07d09861e0dca28785a7c541c7a963d41723
+SHA512:
+  metadata.gz: 8bb883ccd3d6ee1faba616728a2ce246af0849f6c3a342f4cf024909559fdaacd0e3c29e2a20ec6fb43dca00858cc87d3a000e564f76c0c1ae77a8f1f15d62f2
+  data.tar.gz: 940a0660c24b12564f150f1926a6308d153c7db2200eb06b8683df81b3090e8f031f37e593bc215d8aa0d786a0d37871eea4b6c439c3395472c103c716dcd1d0

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - Unreleased
+
+### Added
+
+- Initial implementation of the `risenexa-tracking` gem
+- Global configuration via `Risenexa::Tracking.configure` block
+- Per-instance `Risenexa::Tracking::Client` for multi-startup use cases
+- `track_registration(user_id:)` convenience method (sends `event_type: "user_registered"`)
+- `track_conversion(user_id:)` convenience method (sends `event_type: "user_converted"`)
+- Low-level `track` method accepting all HTTP contract fields
+- UUID v4 idempotency anchor generated before first attempt, reused across retries
+- Exponential backoff retry with jitter (1s base, 2x multiplier, 30s max, ±20% jitter)
+- `Retry-After` header honoring for 429 rate-limit responses
+- Typed error hierarchy: `AuthenticationError`, `AuthorizationError`, `ValidationError`,
+  `StartupNotFoundError`, `RateLimitError`, `MaxRetriesExceededError`, `ConnectionError`,
+  `ConfigurationError`
+- Zero runtime dependencies (Net::HTTP from Ruby stdlib)
+- 35 compliance tests conforming to SDK-SPEC.md Section 10
+- GitHub Actions CI (Ruby 3.1, 3.2, 3.3, 3.4) and automated gem publishing workflow

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick Espake
+
+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,234 @@
+# risenexa-tracking
+
+Ruby SDK for tracking user events with Risenexa. Report user registrations and conversions to your Risenexa dashboard with a single method call.
+
+- **Zero runtime dependencies** — uses Ruby's built-in `Net::HTTP`
+- **Idempotent retries** — UUID v4 anchor prevents duplicate counts on retry
+- **Typed errors** — distinct error classes for auth, validation, rate limiting, and network failures
+- **Two configuration modes** — global (Rails initializer) or per-instance (multi-startup)
+
+For the full behavioral specification, see [SDK-SPEC.md](https://github.com/envixo/risenexa-tracking-rb/blob/main/SDK-SPEC.md).
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "risenexa-tracking"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install risenexa-tracking
+```
+
+**Requirements:** Ruby >= 3.1.0
+
+---
+
+## Quick Start
+
+### Global Configuration (recommended for Rails)
+
+Create an initializer at `config/initializers/risenexa_tracking.rb`:
+
+```ruby
+Risenexa::Tracking.configure do |config|
+  config.api_key      = ENV["RISENEXA_API_KEY"]        # Bearer token with tracking:write scope
+  config.startup_slug = ENV["RISENEXA_STARTUP_SLUG"]  # Your startup's slug
+end
+```
+
+Then call the module-level convenience methods anywhere in your app:
+
+```ruby
+# After a user signs up
+Risenexa::Tracking.track_registration(user_id: current_user.id.to_s)
+
+# After a user starts paying
+Risenexa::Tracking.track_conversion(user_id: current_user.id.to_s)
+```
+
+### Per-Instance Configuration
+
+Useful when managing multiple startups from a single Rails app:
+
+```ruby
+startup_a = Risenexa::Tracking::Client.new(
+  api_key:      "rxt_live_abc123",
+  startup_slug: "startup-alpha"
+)
+
+startup_b = Risenexa::Tracking::Client.new(
+  api_key:      "rxt_live_xyz789",
+  startup_slug: "startup-beta"
+)
+
+startup_a.track_registration(user_id: "usr_1")
+startup_b.track_conversion(user_id: "usr_2")
+```
+
+Per-instance clients are fully independent — no shared state with global configuration or other instances.
+
+---
+
+## API Reference
+
+### Convenience Methods
+
+#### `track_registration(user_id:, **opts)`
+
+Sends `event_type: "user_registered"`, `action: "add"`.
+
+```ruby
+result = client.track_registration(user_id: "usr_123")
+result.success?    # => true
+result.status_code # => 202
+result.event_id    # => "550e8400-e29b-41d4-a716-446655440000"
+result.body        # => {"status" => "accepted"}
+```
+
+#### `track_conversion(user_id:, **opts)`
+
+Sends `event_type: "user_converted"`, `action: "add"`.
+
+```ruby
+result = client.track_conversion(user_id: "usr_123")
+```
+
+Both methods accept optional keyword arguments:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `event_id:` | String | auto UUID v4 | Idempotency anchor |
+| `occurred_at:` | String | server time | ISO 8601 UTC timestamp |
+| `metadata:` | Hash | `{}` | Arbitrary JSONB payload |
+| `action:` | String | `"add"` | `"add"` or `"remove"` |
+
+### Low-Level `track` Method
+
+Use when you need full control over all HTTP contract fields:
+
+```ruby
+client.track(
+  event_type:  "user_registered",
+  user_id:     "usr_123",
+  event_id:    "550e8400-e29b-41d4-a716-446655440000",  # optional
+  occurred_at: "2026-04-01T12:00:00Z",                  # optional
+  metadata:    { plan: "pro", source: "google" },        # optional
+  action:      "add"                                     # optional
+)
+```
+
+---
+
+## Configuration Options
+
+| Option | Required | Default | Type | Description |
+|--------|----------|---------|------|-------------|
+| `api_key` | Yes | — | String | Bearer token with `tracking:write` scope |
+| `startup_slug` | Yes | — | String | Slug identifying the startup |
+| `base_url` | No | `"https://app.risenexa.com"` | String | API base URL (override for staging) |
+| `timeout` | No | `2000` | Integer | Per-request timeout in milliseconds |
+| `max_retries` | No | `3` | Integer | Maximum retry attempts (0 disables retries) |
+
+---
+
+## Error Handling
+
+All error classes inherit from `Risenexa::Tracking::Error < StandardError`.
+
+```ruby
+begin
+  client.track_registration(user_id: "usr_123")
+rescue Risenexa::Tracking::AuthenticationError => e
+  # HTTP 401 — missing or invalid API key; check your api_key
+  puts e.message
+rescue Risenexa::Tracking::AuthorizationError => e
+  # HTTP 403 — token lacks tracking:write scope
+  puts e.message
+rescue Risenexa::Tracking::StartupNotFoundError => e
+  # HTTP 404 — wrong startup_slug; check your configuration
+  puts e.message
+rescue Risenexa::Tracking::ValidationError => e
+  # HTTP 422 — invalid payload
+  puts e.errors.inspect  # Array of error strings from response body
+rescue Risenexa::Tracking::RateLimitError => e
+  # All retries exhausted on 429
+  puts "Retry after #{e.retry_after} seconds"
+rescue Risenexa::Tracking::MaxRetriesExceededError => e
+  # All retries exhausted on 500/502/503
+  puts "Last response: #{e.last_response.code}"
+rescue Risenexa::Tracking::ConnectionError => e
+  # All retries exhausted due to network/timeout failures
+  puts "Transport error: #{e.cause.class}"
+rescue Risenexa::Tracking::ConfigurationError => e
+  # Missing api_key or startup_slug — caught before any HTTP request
+  puts e.message
+end
+```
+
+### Error Classes
+
+| Class | HTTP Status | Notes |
+|-------|-------------|-------|
+| `AuthenticationError` | 401 | Never retried |
+| `AuthorizationError` | 403 | Never retried |
+| `StartupNotFoundError` | 404 | Never retried |
+| `ValidationError` | 422 | Never retried; `.errors` contains array from response |
+| `RateLimitError` | 429 (exhausted) | `.retry_after` has seconds from `Retry-After` header |
+| `MaxRetriesExceededError` | 5xx (exhausted) | `.last_response` has the last `Net::HTTPResponse` |
+| `ConnectionError` | timeout/refused | `.cause` has the underlying transport exception |
+| `ConfigurationError` | — | Raised before HTTP; missing `api_key` or `startup_slug` |
+
+---
+
+## Retry Behavior
+
+The SDK retries on transient errors (429, 500, 502, 503, timeouts, connection failures) with exponential backoff and ±20% jitter:
+
+| Before Retry | Base Delay | Jitter Range | Actual Range |
+|--------------|------------|--------------|--------------|
+| Retry 1 | 1.0s | ±0.2s | [0.8s, 1.2s] |
+| Retry 2 | 2.0s | ±0.4s | [1.6s, 2.4s] |
+| Retry 3 | 4.0s | ±0.8s | [3.2s, 4.8s] |
+
+**Idempotency:** The SDK generates a UUID v4 `event_id` before the first attempt and reuses it across all retries. This ensures the server counts the event exactly once even if the SDK retries.
+
+**Disabling retries:**
+
+```ruby
+client = Risenexa::Tracking::Client.new(
+  api_key:      "rxt_live_abc123",
+  startup_slug: "my-startup",
+  max_retries:  0  # raise immediately on any retryable error
+)
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/envixo/risenexa-tracking-rb.git
+cd risenexa-tracking-rb
+bundle install
+bundle exec rspec
+```
+
+The test suite includes all 35 compliance tests from the SDK specification.
+
+---
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/risenexa/tracking/client.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Tracking
+    # Per-instance client for the Risenexa Tracking SDK.
+    #
+    # Fully independent of the global configuration — each instance has its own
+    # api_key, startup_slug, and other options. Multiple instances can coexist
+    # without interference.
+    #
+    # @example
+    #   client = Risenexa::Tracking::Client.new(
+    #     api_key: "rxt_live_abc123",
+    #     startup_slug: "my-startup"
+    #   )
+    #   result = client.track_registration(user_id: "usr_456")
+    class Client
+      # @param api_key [String, nil] Bearer token with tracking:write scope
+      # @param startup_slug [String, nil] Slug identifying the startup
+      # @param base_url [String] Base URL for the Risenexa API
+      # @param timeout [Integer] Per-request timeout in milliseconds
+      # @param max_retries [Integer] Maximum retry attempts (0 disables retries)
+      def initialize(api_key: nil, startup_slug: nil, base_url: "https://app.risenexa.com",
+                     timeout: 2000, max_retries: 3)
+        @api_key      = api_key
+        @startup_slug = startup_slug
+        @base_url     = base_url
+        @timeout      = timeout
+        @max_retries  = max_retries
+      end
+
+      # Track a user registration event (event_type: "user_registered", action: "add").
+      #
+      # @param user_id [String] Opaque identifier for the user
+      # @param opts [Hash] Optional fields: event_id, occurred_at, metadata, action
+      # @return [Result] on success
+      # @raise [ConfigurationError] if api_key or startup_slug is missing
+      def track_registration(user_id:, **opts)
+        track(event_type: "user_registered", user_id: user_id, action: "add", **opts)
+      end
+
+      # Track a user conversion event (event_type: "user_converted", action: "add").
+      #
+      # @param user_id [String] Opaque identifier for the user
+      # @param opts [Hash] Optional fields: event_id, occurred_at, metadata, action
+      # @return [Result] on success
+      # @raise [ConfigurationError] if api_key or startup_slug is missing
+      def track_conversion(user_id:, **opts)
+        track(event_type: "user_converted", user_id: user_id, action: "add", **opts)
+      end
+
+      # Low-level track method accepting all HTTP contract fields.
+      #
+      # @param event_type [String] "user_registered" or "user_converted"
+      # @param user_id [String] Opaque identifier for the user
+      # @param opts [Hash] Optional: event_id, occurred_at, metadata, action
+      # @return [Result] on success
+      # @raise [ConfigurationError] if api_key or startup_slug is missing
+      def track(event_type:, user_id:, **opts)
+        validate_configuration!
+
+        payload = build_payload(event_type: event_type, user_id: user_id, **opts)
+        http_client.post(payload)
+      end
+
+      private
+
+      attr_reader :api_key, :startup_slug, :base_url, :timeout, :max_retries
+
+      # Validate that required configuration is present before making HTTP requests.
+      def validate_configuration!
+        raise ConfigurationError, "api_key is required" if @api_key.nil? || @api_key.empty?
+        raise ConfigurationError, "startup_slug is required" if @startup_slug.nil? || @startup_slug.empty?
+      end
+
+      # Build the event payload hash from the provided arguments.
+      def build_payload(event_type:, user_id:, **opts)
+        payload = { event_type: event_type, user_id: user_id }
+
+        payload[:action]      = opts[:action]      if opts.key?(:action)
+        payload[:event_id]    = opts[:event_id]    if opts.key?(:event_id)
+        payload[:occurred_at] = opts[:occurred_at] if opts.key?(:occurred_at)
+        payload[:metadata]    = opts[:metadata]    if opts.key?(:metadata)
+
+        payload
+      end
+
+      # Lazily create the HttpClient for this instance.
+      def http_client
+        @http_client ||= HttpClient.new(
+          api_key: @api_key,
+          base_url: @base_url,
+          startup_slug: @startup_slug,
+          timeout: @timeout,
+          max_retries: @max_retries
+        )
+      end
+    end
+  end
+end

data/lib/risenexa/tracking/configuration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Tracking
+    # Configuration options for the Risenexa Tracking SDK.
+    #
+    # @example Global configuration
+    #   Risenexa::Tracking.configure do |config|
+    #     config.api_key      = "rxt_live_abc123"
+    #     config.startup_slug = "my-startup"
+    #   end
+    class Configuration
+      # @return [String, nil] Bearer token with tracking:write scope (required)
+      attr_accessor :api_key
+
+      # @return [String, nil] Slug identifying the startup (required)
+      attr_accessor :startup_slug
+
+      # @return [String] Base URL for the Risenexa API
+      attr_accessor :base_url
+
+      # @return [Integer] Per-request timeout in milliseconds (default: 2000)
+      attr_accessor :timeout
+
+      # @return [Integer] Maximum retry attempts, 0 disables retries (default: 3)
+      attr_accessor :max_retries
+
+      def initialize
+        @base_url    = "https://app.risenexa.com"
+        @timeout     = 2000
+        @max_retries = 3
+      end
+    end
+  end
+end

data/lib/risenexa/tracking/errors.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Tracking
+    # Base error class for all Risenexa::Tracking errors.
+    class Error < StandardError; end
+
+    # Raised when the API key is missing or invalid (HTTP 401).
+    # Non-retryable — auth failures are permanent with the same token.
+    class AuthenticationError < Error; end
+
+    # Raised when the token lacks the tracking:write scope (HTTP 403).
+    # Non-retryable — scope errors are permanent.
+    class AuthorizationError < Error; end
+
+    # Raised when the request payload is invalid (HTTP 422).
+    # Non-retryable — same payload will always fail.
+    class ValidationError < Error
+      # @return [Array<String>] validation error messages from the response body
+      attr_reader :errors
+
+      def initialize(errors: [])
+        @errors = errors
+        super(errors.first || "Validation failed")
+      end
+    end
+
+    # Raised when the startup is not found for this account (HTTP 404).
+    # Non-retryable — wrong slug/id is a configuration error.
+    class StartupNotFoundError < Error; end
+
+    # Raised when the SDK exhausts retries on 429 responses.
+    class RateLimitError < Error
+      # @return [Integer, nil] seconds from the Retry-After header
+      attr_reader :retry_after
+
+      def initialize(message = "Rate limit exceeded", retry_after: nil)
+        @retry_after = retry_after
+        super(message)
+      end
+    end
+
+    # Raised when all retry attempts are exhausted on retryable HTTP errors.
+    class MaxRetriesExceededError < Error
+      # @return [Net::HTTPResponse] the last HTTP response received
+      attr_reader :last_response
+
+      def initialize(message = "Max retries exceeded", last_response: nil)
+        @last_response = last_response
+        super(message)
+      end
+    end
+
+    # Raised when all retry attempts are exhausted due to transport errors.
+    class ConnectionError < Error
+      # @return [Exception] the underlying transport exception
+      attr_reader :cause
+
+      def initialize(message = "Connection error", cause: nil)
+        @cause = cause
+        super(message)
+      end
+    end
+
+    # Raised when required configuration (api_key, startup_slug) is missing.
+    # Raised before any HTTP request is made.
+    class ConfigurationError < Error; end
+  end
+end

data/lib/risenexa/tracking/http_client.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require "securerandom"
+
+module Risenexa
+  module Tracking
+    # HTTP layer for the Risenexa Tracking SDK.
+    #
+    # Implements the retry algorithm from SDK-SPEC.md Section 4:
+    # - Exponential backoff: BASE_DELAY * (MULTIPLIER ^ attempt), capped at MAX_DELAY
+    # - Jitter: ±JITTER_FACTOR of the capped delay
+    # - Retryable: 429, 500, 502, 503, timeout, connection errors
+    # - Non-retryable: 401, 403, 404, 422 — raise immediately
+    # - Idempotency: UUID v4 generated ONCE before first attempt, reused on all retries
+    class HttpClient
+      BASE_DELAY    = 1.0   # seconds
+      MULTIPLIER    = 2.0
+      MAX_DELAY     = 30.0  # seconds
+      JITTER_FACTOR = 0.20  # ±20% of the capped delay
+
+      RETRYABLE_STATUSES = [429, 500, 502, 503].freeze
+      NON_RETRYABLE_STATUSES = [401, 403, 404, 422].freeze
+
+      TRACK_PATH = "/api/v1/track"
+
+      def initialize(api_key:, base_url:, startup_slug:, timeout:, max_retries:)
+        @api_key      = api_key
+        @base_url     = base_url
+        @startup_slug = startup_slug
+        @timeout      = timeout
+        @max_retries  = max_retries
+      end
+
+      # POST the event payload to the Risenexa tracking endpoint.
+      #
+      # Generates a UUID v4 idempotency anchor before the first attempt and
+      # reuses it across all retry attempts.
+      #
+      # @param payload [Hash] Event fields (event_type, user_id, and optional fields)
+      # @return [Result] on success (HTTP 202)
+      # @raise [AuthenticationError] on HTTP 401
+      # @raise [AuthorizationError] on HTTP 403
+      # @raise [StartupNotFoundError] on HTTP 404
+      # @raise [ValidationError] on HTTP 422
+      # @raise [RateLimitError] when 429 exhausts all retries
+      # @raise [MaxRetriesExceededError] when 500/502/503 exhausts all retries
+      # @raise [ConnectionError] when transport errors exhaust all retries
+      def post(payload)
+        # Use caller-provided event_id if present; otherwise generate a fresh UUID v4.
+        # The event_id is generated ONCE before the first attempt and reused on all retries.
+        event_id     = payload[:event_id] || SecureRandom.uuid
+        full_payload = payload.merge(event_id: event_id)
+
+        attempt = 0
+
+        loop do
+          begin
+            response = perform_request(full_payload)
+          rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED,
+                 SocketError, Errno::EHOSTUNREACH => e
+            if attempt >= @max_retries
+              raise ConnectionError.new("Connection failed after #{attempt + 1} attempt(s): #{e.message}", cause: e)
+            end
+
+            sleep(calculate_backoff(attempt))
+            attempt += 1
+            next
+          end
+
+          case response.code.to_i
+          when 202
+            body = parse_json(response.body)
+            return Result.new(status_code: 202, event_id: event_id, body: body)
+          when *NON_RETRYABLE_STATUSES
+            raise_non_retryable!(response)
+          when *RETRYABLE_STATUSES
+            if attempt >= @max_retries
+              status = response.code.to_i
+              if status == 429
+                raise RateLimitError.new(
+                  "Rate limit exceeded after #{attempt + 1} attempt(s)",
+                  retry_after: parse_retry_after(response)
+                )
+              else
+                raise MaxRetriesExceededError.new(
+                  "Max retries exceeded after #{attempt + 1} attempt(s)",
+                  last_response: response
+                )
+              end
+            end
+
+            delay = if response.code.to_i == 429
+              parse_retry_after(response) || calculate_backoff(attempt)
+            else
+              calculate_backoff(attempt)
+            end
+
+            sleep(delay)
+            attempt += 1
+          else
+            raise Error, "Unexpected response status: #{response.code}"
+          end
+        end
+      end
+
+      private
+
+      # Calculate exponential backoff delay for the given attempt index.
+      #
+      # Formula (from SDK-SPEC.md Section 4):
+      #   raw   = min(BASE_DELAY * (MULTIPLIER ^ attempt), MAX_DELAY)
+      #   jitter = raw * JITTER_FACTOR * rand(-1.0..1.0)
+      #   delay = max(raw + jitter, 0.0)
+      #
+      # @param attempt [Integer] zero-based attempt index (0 = before first retry)
+      # @return [Float] delay in seconds
+      def calculate_backoff(attempt)
+        raw    = [BASE_DELAY * (MULTIPLIER**attempt), MAX_DELAY].min
+        jitter = raw * JITTER_FACTOR * rand(-1.0..1.0)
+        [raw + jitter, 0.0].max
+      end
+
+      # Parse the Retry-After header from a 429 response.
+      #
+      # @param response [Net::HTTPResponse]
+      # @return [Integer, nil] seconds to wait, or nil if header absent/unparseable
+      def parse_retry_after(response)
+        value = response["Retry-After"]
+        return nil if value.nil? || value.empty?
+
+        integer_value = Integer(value, 10)
+        integer_value
+      rescue ArgumentError
+        nil
+      end
+
+      # Raise the appropriate non-retryable error for a given HTTP response.
+      #
+      # @param response [Net::HTTPResponse]
+      # @raise [AuthenticationError, AuthorizationError, StartupNotFoundError, ValidationError]
+      def raise_non_retryable!(response)
+        body = parse_json(response.body)
+
+        case response.code.to_i
+        when 401
+          raise AuthenticationError, body["error"] || "Unauthorized"
+        when 403
+          raise AuthorizationError, body["error"] || "Forbidden"
+        when 404
+          raise StartupNotFoundError, body["error"] || "Startup not found"
+        when 422
+          raise ValidationError.new(errors: body["errors"] || [])
+        end
+      end
+
+      # Perform a single HTTP POST request.
+      #
+      # @param payload [Hash] Full event payload including event_id
+      # @return [Net::HTTPResponse]
+      def perform_request(payload)
+        uri  = URI.parse("#{@base_url}#{TRACK_PATH}")
+        http = Net::HTTP.new(uri.host, uri.port)
+
+        if uri.scheme == "https"
+          require "openssl"
+          http.use_ssl     = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+        end
+
+        # CRITICAL: Set BOTH timeouts — default is 60s which violates the spec
+        timeout_seconds      = @timeout / 1000.0
+        http.open_timeout    = timeout_seconds
+        http.read_timeout    = timeout_seconds
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"]  = "application/json"
+        request["Accept"]        = "application/json"
+        request.body = { event: { startup_slug: @startup_slug, **payload } }.to_json
+
+        http.request(request)
+      end
+
+      # Parse a JSON string safely, returning empty hash on failure.
+      #
+      # @param body [String, nil]
+      # @return [Hash]
+      def parse_json(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/risenexa/tracking/result.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Tracking
+    # Value object returned on successful event tracking (HTTP 202).
+    #
+    # @example
+    #   result = client.track_registration(user_id: "usr_123")
+    #   result.success?    # => true
+    #   result.status_code # => 202
+    #   result.event_id    # => "550e8400-e29b-41d4-a716-446655440000"
+    #   result.body        # => {"status" => "accepted"}
+    class Result
+      # @return [Integer] HTTP status code (202 on success)
+      attr_reader :status_code
+
+      # @return [String] UUID v4 sent in the request (idempotency anchor)
+      attr_reader :event_id
+
+      # @return [Hash] Parsed JSON response body
+      attr_reader :body
+
+      def initialize(status_code:, event_id:, body:)
+        @status_code = status_code
+        @event_id    = event_id
+        @body        = body
+      end
+
+      # @return [Boolean] true when status_code is 202
+      def success?
+        @status_code == 202
+      end
+    end
+  end
+end

data/lib/risenexa/tracking/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Risenexa
+  module Tracking
+    VERSION = "0.1.0"
+  end
+end

data/lib/risenexa/tracking.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "securerandom"
+
+require_relative "tracking/version"
+require_relative "tracking/errors"
+require_relative "tracking/configuration"
+require_relative "tracking/result"
+require_relative "tracking/http_client"
+require_relative "tracking/client"
+
+module Risenexa
+  # The Risenexa Tracking module provides global configuration and module-level
+  # convenience methods that delegate to a lazily-created Client instance.
+  #
+  # @example Global configuration and usage
+  #   Risenexa::Tracking.configure do |config|
+  #     config.api_key      = "rxt_live_abc123"
+  #     config.startup_slug = "my-startup"
+  #   end
+  #
+  #   Risenexa::Tracking.track_registration(user_id: "usr_456")
+  module Tracking
+    class << self
+      # @return [Configuration, nil] the current global configuration
+      attr_accessor :configuration
+
+      # Configure the SDK globally.
+      #
+      # @yieldparam config [Configuration] the configuration object
+      def configure
+        self.configuration ||= Configuration.new
+        yield(configuration)
+        self.configuration
+      end
+
+      # Reset global configuration and the cached client instance.
+      # Useful for test isolation.
+      def reset_configuration!
+        self.configuration = nil
+        @client = nil
+      end
+
+      # Track a user registration event using the global configuration.
+      #
+      # @param user_id [String] Opaque identifier for the user
+      # @param opts [Hash] Optional fields: event_id, occurred_at, metadata, action
+      # @return [Result] on success
+      # @raise [ConfigurationError] if global api_key or startup_slug is missing
+      def track_registration(user_id:, **opts)
+        client.track_registration(user_id: user_id, **opts)
+      end
+
+      # Track a user conversion event using the global configuration.
+      #
+      # @param user_id [String] Opaque identifier for the user
+      # @param opts [Hash] Optional fields: event_id, occurred_at, metadata, action
+      # @return [Result] on success
+      # @raise [ConfigurationError] if global api_key or startup_slug is missing
+      def track_conversion(user_id:, **opts)
+        client.track_conversion(user_id: user_id, **opts)
+      end
+
+      # Low-level track method using the global configuration.
+      #
+      # @param params [Hash] All event fields including event_type, user_id, and optionals
+      # @return [Result] on success
+      # @raise [ConfigurationError] if global api_key or startup_slug is missing
+      def track(**params)
+        client.track(**params)
+      end
+
+      private
+
+      # Lazily create a Client from the current global configuration.
+      def client
+        @client ||= begin
+          cfg = configuration || Configuration.new
+          Client.new(
+            api_key:      cfg.api_key,
+            startup_slug: cfg.startup_slug,
+            base_url:     cfg.base_url,
+            timeout:      cfg.timeout,
+            max_retries:  cfg.max_retries
+          )
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: risenexa-tracking
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Patrick Espake
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A Ruby gem to track user registrations and conversions, sending events
+  to the Risenexa dashboard with zero runtime dependencies.
+email:
+- patrickespake@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/risenexa/tracking.rb
+- lib/risenexa/tracking/client.rb
+- lib/risenexa/tracking/configuration.rb
+- lib/risenexa/tracking/errors.rb
+- lib/risenexa/tracking/http_client.rb
+- lib/risenexa/tracking/result.rb
+- lib/risenexa/tracking/version.rb
+homepage: https://github.com/envixo/risenexa-tracking-rb
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/envixo/risenexa-tracking-rb
+  source_code_uri: https://github.com/envixo/risenexa-tracking-rb
+  changelog_uri: https://github.com/envixo/risenexa-tracking-rb/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby SDK for tracking user events with Risenexa
+test_files: []