ridebuilder-affiliate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 421efc119490992dea3cb78e24bb7b0c380ebc458b60f3d4253ac5669e28c429
+  data.tar.gz: 9eb9d1a0ba25f32d74ad6145e6fab9b0c382aacdf2ae539ac1274000c70e4dd1
+SHA512:
+  metadata.gz: 00b8b927dacb04a95ea7bce0e87c55479f73748d884124178db8a9638321bd395e2ddb7746ebb79a6779755441117d40df80ebd3e2613d82c9d07c8bbac474b9
+  data.tar.gz: de5af83438ff7083f3a79fe6688a6c542d8a82a0323493fc719b998445b91aafb2ca76aea679b75c248debe578daba6345ed26eb78b109ff53a2e5280fc4a046

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RideBuilder
+
+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,112 @@
+# ridebuilder-affiliate (Ruby)
+
+Server-side SDK for RideBuilder's FirstParty affiliate program. It does two things:
+
+1. **Capture** the `click_id` a shopper arrives with, so your backend can bind it to the cart/order.
+2. **Report** checkout and return postbacks to RideBuilder (auth, retries, idempotency handled).
+
+Mirrors the Node/.NET/Python/PHP/Java SDKs — same contract, verified by the shared [conformance suite](../conformance).
+
+## Install
+
+```bash
+gem install ridebuilder-affiliate
+```
+
+or in a `Gemfile`: `gem "ridebuilder-affiliate"`. Requires **Ruby 3.0+**. **No runtime dependencies** — the
+default transport uses the stdlib `net/http`.
+
+## The pattern: capture at landing, bind to the order
+
+```ruby
+require "ridebuilder/affiliate"
+
+# 1. On landing, read a validated click_id off the request URL and persist it onto YOUR cart record.
+click_id = RideBuilder::Affiliate::Capture.from_url(request.fullpath)
+cart.ridebuilder_click_id = click_id if click_id
+
+# 2. At order time, send the postback from your backend.
+rb = RideBuilder::Affiliate::Client.new(api_key: ENV.fetch("RIDEBUILDER_API_KEY"))
+rb.report_checkout(
+  order_id: order.id,
+  subtotal: "199.99",   # major units; a string keeps it exact
+  currency: "USD",
+  click_id: order.ridebuilder_click_id
+)
+```
+
+Store the API key server-side (env/secrets) — never in frontend code.
+
+## Decoupled frontend (e.g. React) + separate Ruby backend
+
+The browser **snippet** captures the `click_id` into a first-party cookie; get it to your backend one of two ways:
+
+```ruby
+# Same registrable domain — the cookie rides along; read it off the Cookie header:
+click_id = RideBuilder::Affiliate::Capture.from_cookie_header(request.get_header("HTTP_COOKIE"))
+
+# Cross-domain / mobile — the frontend forwards it in the checkout call:
+click_id = RideBuilder::Affiliate::Capture.from_headers(request.headers)  # default: X-RideBuilder-Click-Id
+```
+
+Either way, `report_checkout` is unchanged — that's the SDK's real value in a decoupled setup.
+
+### Refunds
+
+```ruby
+rb.report_return(return_id: refund.id, order_id: order.id, refund_amount: "49.95", currency: "USD")
+```
+
+## Integration protocol (register / verify / heartbeat)
+
+```ruby
+rb = RideBuilder::Affiliate::Client.new(api_key: api_key, environment: "production") # or "sandbox"
+
+reg = rb.register   # handshake on install/startup; returns a stable integration id
+rb.verify           # deploy/CI self-test — raises RideBuilder::Affiliate::Error on a bad/rotated key
+rb.heartbeat        # periodic liveness (call on a schedule)
+```
+
+The SDK reports its own `type` (`ruby_sdk`), `version`, and default capabilities.
+
+## Capture helpers
+
+All validate `ref == "ridebuilder"` and the UUID-v4 click_id, returning `nil` otherwise:
+
+- `Capture.from_url(url)` — from an absolute or relative URL.
+- `Capture.from_query(hash)` — from a decoded query map.
+- `Capture.from_cookie_header(cookie_header)` — recover it from the `ridebuilder_attribution` cookie.
+- `Capture.from_headers(headers, name = "X-RideBuilder-Click-Id")` — from a forwarding header (decoupled path).
+
+## Client options
+
+```ruby
+RideBuilder::Affiliate::Client.new(
+  api_key:,               # required
+  base_url: nil,          # defaults to https://api.ridebuilder.com/v1
+  max_retries: 3,         # retries on network errors, timeouts, 5xx, 429
+  timeout_ms: 10_000,     # per-attempt timeout
+  environment: "production",
+  transport: nil          # inject an object responding to #call(method, url, headers, body)
+)
+```
+
+`report_checkout` / `report_return` return `PostbackResult` (`.accepted`, `.status`; `202` = accepted,
+validated asynchronously). Invalid input raises a non-retryable `RideBuilder::Affiliate::Error`; auth/size
+failures (`401`, `413`) raise with `.status` and `.error_code`. Amounts must be `> 0` with at most 2 decimal
+places (pass a **string** to avoid float rounding) or the call raises up front.
+
+## Tests
+
+Plain Ruby, no test framework required:
+
+```bash
+ruby test/conformance.rb   # the shared cross-language fixtures
+ruby test/unit.rb          # validation, capture, money, retry/error, identity
+```
+
+## Contract
+
+Wraps the RideBuilder affiliate REST contract — `POST /v1/postback/checkout`, `/postback/return`,
+`/postback/health`, the `/integration/*` endpoints, the `/redirect` link format, and API-key provisioning.
+Verified byte-for-byte against the Node/.NET/Python/PHP/Java SDKs by the shared conformance fixtures.

data/lib/ridebuilder/affiliate/capture.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RideBuilder
+  module Affiliate
+    # Framework-free capture helpers — turn an incoming request into a validated click_id (or nil). Every
+    # helper enforces ref == "ridebuilder" and the UUID-v4 click_id, the same rules the browser snippet uses.
+    module Capture
+      module_function
+
+      # Read a validated click_id from a raw URL (absolute or relative like "/landing?...").
+      def from_url(url)
+        return nil if url.nil? || url.empty?
+
+        query = url.split("?", 2)[1]
+        return nil if query.nil?
+
+        query = query.split("#", 2)[0]
+        from_query(parse_query(query))
+      end
+
+      # Read a validated click_id from a decoded query map.
+      def from_query(query)
+        return nil unless query && query["ref"] == ClickId::REF
+
+        click_id = query["click_id"]
+        ClickId.valid?(click_id) ? click_id : nil
+      end
+
+      # Recover the click_id from the ridebuilder_attribution cookie the browser snippet set.
+      def from_cookie_header(cookie_header)
+        return nil if cookie_header.nil? || cookie_header.empty?
+
+        raw = parse_cookie_header(cookie_header)[ClickId::COOKIE_NAME]
+        return nil if raw.nil? || raw.empty?
+
+        parse_attribution_cookie(raw)&.click_id
+      end
+
+      # Read a validated click_id off a forwarding header (case-insensitive) — the decoupled path.
+      def from_headers(headers, name = "X-RideBuilder-Click-Id")
+        return nil unless headers
+
+        target = name.downcase
+        headers.each do |key, value|
+          next unless key.to_s.downcase == target
+
+          val = value.is_a?(Array) ? value.first : value
+          return ClickId.valid?(val) ? val : nil
+        end
+        nil
+      end
+
+      # Parse the raw ridebuilder_attribution cookie value (URL-encoded JSON the snippet wrote).
+      def parse_attribution_cookie(raw_value)
+        parsed = JSON.parse(CGI.unescape(raw_value))
+        return nil unless parsed.is_a?(Hash) && ClickId.valid?(parsed["click_id"]) && parsed["ref"] == ClickId::REF
+
+        Attribution.new(parsed["click_id"], parsed["ref"], parsed["clicked_at"])
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Split a Cookie header ("a=1; b=2") into a name=>value hash (first '=' separates).
+      def parse_cookie_header(cookie_header)
+        out = {}
+        cookie_header.split(";").each do |part|
+          i = part.index("=")
+          out[part[0...i].strip] = part[(i + 1)..].strip if i && i.positive?
+        end
+        out
+      end
+
+      def parse_query(query)
+        out = {}
+        return out if query.nil? || query.empty?
+
+        query.split("&").each do |pair|
+          next if pair.empty?
+
+          key, value = pair.split("=", 2)
+          key = CGI.unescape(key)
+          out[key] = value.nil? ? "" : CGI.unescape(value) unless out.key?(key)
+        end
+        out
+      end
+    end
+  end
+end

data/lib/ridebuilder/affiliate/click_id.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module RideBuilder
+  module Affiliate
+    # Shared attribution constants and the strict UUID-v4 click_id check the browser snippet also enforces.
+    module ClickId
+      REF = "ridebuilder"
+      COOKIE_NAME = "ridebuilder_attribution"
+      PATTERN = /\A[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+
+      def self.valid?(value)
+        value.is_a?(String) && !(PATTERN =~ value).nil?
+      end
+    end
+  end
+end

data/lib/ridebuilder/affiliate/client.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module RideBuilder
+  module Affiliate
+    # Server-side client for RideBuilder's FirstParty affiliate program: report checkout/return postbacks and
+    # prove integration liveness. Handles auth, per-attempt timeout, retry with exponential backoff + jitter,
+    # and idempotency. Port of the Node RideBuilderClient — same wire contract, verified by sdk/conformance.
+    class Client
+      def initialize(api_key:, base_url: nil, max_retries: 3, timeout_ms: 10_000, environment: "production", transport: nil)
+        raise Error.new("api_key must be a non-empty string", retryable: false) if api_key.nil? || api_key.strip.empty?
+
+        @api_key = api_key
+        @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+        @max_retries = max_retries
+        @environment = environment == "sandbox" ? "sandbox" : "production"
+        @transport = transport || NetHttpTransport.new(timeout_ms)
+      end
+
+      # order_id is the server-side idempotency key, so a retried checkout never double-counts.
+      def report_checkout(order_id:, subtotal:, currency:, click_id:)
+        assert_non_empty(order_id, "order_id")
+        amount = normalize_amount(subtotal, "subtotal")
+        assert_currency(currency)
+        unless ClickId.valid?(click_id)
+          raise Error.new("click_id must be a valid RideBuilder click_id (UUID v4)", retryable: false)
+        end
+
+        res = send_request("POST", "/postback/checkout", {
+          "order_id" => order_id, "order_subtotal" => amount, "currency" => currency,
+          "ref" => ClickId::REF, "click_id" => click_id
+        })
+        PostbackResult.new(true, res.status)
+      end
+
+      # return_id is the server-side idempotency key, so a retried refund never double-counts.
+      def report_return(return_id:, order_id:, refund_amount:, currency:)
+        assert_non_empty(return_id, "return_id")
+        assert_non_empty(order_id, "order_id")
+        amount = normalize_amount(refund_amount, "refund_amount")
+        assert_currency(currency)
+
+        res = send_request("POST", "/postback/return", {
+          "return_id" => return_id, "order_id" => order_id, "refund_amount" => amount, "currency" => currency
+        })
+        PostbackResult.new(true, res.status)
+      end
+
+      # Authenticated liveness ping (legacy alias). Raises a terminal Error on a bad key.
+      def health_check
+        HealthResult.new(true, send_request("POST", "/postback/health").status)
+      end
+
+      # Announce this integration on install/startup — the handshake. Idempotent; returns the integration id.
+      def register(capabilities: nil)
+        res = send_request("POST", "/integration/register", {
+          "type" => SDK_TYPE, "environment" => @environment, "version" => VERSION,
+          "capabilities" => capabilities || DEFAULT_CAPABILITIES
+        })
+        body = res.json.is_a?(Hash) ? res.json : {}
+        RegisterResult.new(body["integrationId"] || "", body["status"] || "connected")
+      end
+
+      # Self-test: verifies the API key is valid + active. Raises a terminal Error on a bad/rotated key.
+      def verify
+        HealthResult.new(true, send_request("GET", "/integration/verify").status)
+      end
+
+      # Periodic liveness. Call on a schedule so RideBuilder can tell "alive" from "went dark".
+      def heartbeat
+        res = send_request("POST", "/integration/heartbeat", {
+          "type" => SDK_TYPE, "environment" => @environment, "version" => VERSION
+        })
+        HealthResult.new(true, res.status)
+      end
+
+      private
+
+      # Shared transport: auth header, retry with backoff on 5xx/429/network, terminal raise on other 4xx.
+      def send_request(method, path, payload = nil)
+        url = @base_url + path
+        body = payload ? JSON.generate(payload) : nil
+        headers = { "Authorization" => "Bearer #{@api_key}" }
+        headers["Content-Type"] = "application/json" if body
+
+        last_error = nil
+        (0..@max_retries).each do |attempt|
+          sleep(backoff_ms(attempt) / 1000.0) if attempt.positive?
+
+          begin
+            res = @transport.call(method, url, headers, body)
+          rescue TransportError => e
+            last_error = Error.new(e.message, retryable: true)
+            next
+          end
+
+          case classify(res.status)
+          when :success
+            return res
+          when :retry
+            last_error = Error.new("RideBuilder request failed with #{res.status}", retryable: true, status: res.status)
+            next
+          else
+            code = error_code(res)
+            message = code ? "RideBuilder request rejected (#{res.status}): #{code}" : "RideBuilder request rejected with #{res.status}"
+            raise Error.new(message, retryable: false, status: res.status, error_code: code)
+          end
+        end
+
+        raise(last_error || Error.new("RideBuilder request failed after retries", retryable: true))
+      end
+
+      def classify(status)
+        return :success if (200..299).cover?(status)
+        return :retry if status >= 500 || status == 429
+
+        :terminal
+      end
+
+      def error_code(res)
+        body = res.json
+        body.is_a?(Hash) && body["error"].is_a?(String) ? body["error"] : nil
+      end
+
+      # 250 * 2^(attempt-1) ms + up to 100 ms jitter — identical to the Node/.NET/Python/PHP/Java backoff.
+      def backoff_ms(attempt)
+        250 * (2**(attempt - 1)) + rand(0..99)
+      end
+
+      def assert_non_empty(value, field)
+        return if value.is_a?(String) && !value.strip.empty?
+
+        raise Error.new("#{field} must be a non-empty string", retryable: false)
+      end
+
+      def assert_currency(value)
+        return if value.is_a?(String) && value.match?(/\A[A-Z]{3}\z/)
+
+        raise Error.new("currency must be a 3-letter uppercase ISO-4217 code", retryable: false)
+      end
+
+      # Validate an amount and return it as a Float for JSON-number emission. Accepts Integer/Float/String;
+      # rejects <= 0 and > 2 decimal places up front (matching the stricter .NET/Python/Java clients).
+      def normalize_amount(value, field)
+        str = case value
+              when Integer, Float then value.to_s
+              when String then value.strip
+              end
+        num = str.nil? ? nil : (Float(str) rescue nil)
+        raise Error.new("#{field} must be a positive number", retryable: false) if num.nil? || num <= 0
+        raise Error.new("#{field} must have at most 2 decimal places", retryable: false) unless str.match?(/\A\d+(\.\d{1,2})?\z/)
+
+        num
+      end
+    end
+  end
+end

data/lib/ridebuilder/affiliate/error.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module RideBuilder
+  module Affiliate
+    # Every failure the SDK raises. +retryable+ is false for input-validation and terminal 4xx errors, true
+    # for 5xx/429/network failures (surfaced only after retries are exhausted). Port of the Node RideBuilderError.
+    class Error < StandardError
+      attr_reader :status, :error_code, :retryable
+
+      def initialize(message, retryable:, status: nil, error_code: nil)
+        super(message)
+        @status = status
+        @error_code = error_code
+        @retryable = retryable
+      end
+    end
+  end
+end

data/lib/ridebuilder/affiliate/models.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module RideBuilder
+  module Affiliate
+    # A 202 status means received, not yet validated — RideBuilder validates asynchronously.
+    PostbackResult = Struct.new(:accepted, :status)
+    HealthResult = Struct.new(:ok, :status)
+    RegisterResult = Struct.new(:integration_id, :status)
+    Attribution = Struct.new(:click_id, :ref, :clicked_at)
+  end
+end

data/lib/ridebuilder/affiliate/transport.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+
+module RideBuilder
+  module Affiliate
+    # A network-level failure (connect/DNS/timeout). Always treated as retryable by the client.
+    class TransportError < StandardError; end
+
+    # A completed HTTP response — any status. Non-2xx is returned here, not raised.
+    Response = Struct.new(:status, :body) do
+      def json
+        return nil if body.nil? || body.empty?
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    # Default transport, backed by the stdlib Net::HTTP — zero third-party dependencies. Inject any object
+    # that responds to #call(method, url, headers, body) to route through your own HTTP client.
+    class NetHttpTransport
+      def initialize(timeout_ms = 10_000)
+        @timeout = timeout_ms / 1000.0
+      end
+
+      def call(method, url, headers, body)
+        uri = URI(url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        request = build_request(method, uri)
+        headers.each { |k, v| request[k] = v }
+        request.body = body if body
+
+        response = http.request(request)
+        Response.new(response.code.to_i, response.body)
+      rescue SocketError, SystemCallError, IOError, Timeout::Error => e
+        raise TransportError, e.message
+      end
+
+      private
+
+      def build_request(method, uri)
+        case method
+        when "GET" then Net::HTTP::Get.new(uri)
+        when "POST" then Net::HTTP::Post.new(uri)
+        when "PUT" then Net::HTTP::Put.new(uri)
+        when "DELETE" then Net::HTTP::Delete.new(uri)
+        else raise ArgumentError, "unsupported method #{method}"
+        end
+      end
+    end
+  end
+end

data/lib/ridebuilder/affiliate/version.rb

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

data/lib/ridebuilder/affiliate.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+require "cgi"
+require "net/http"
+require "uri"
+
+module RideBuilder
+  # Server-side SDK for RideBuilder's FirstParty affiliate program.
+  module Affiliate
+    DEFAULT_BASE_URL = "https://api.ridebuilder.com/v1"
+    SDK_TYPE = "ruby_sdk"
+    DEFAULT_CAPABILITIES = %w[click_capture order_events refund_events].freeze
+  end
+end
+
+require_relative "affiliate/version"
+require_relative "affiliate/error"
+require_relative "affiliate/click_id"
+require_relative "affiliate/models"
+require_relative "affiliate/capture"
+require_relative "affiliate/transport"
+require_relative "affiliate/client"

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: ridebuilder-affiliate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RideBuilder
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-03 00:00:00.000000000 Z
+dependencies: []
+description: Capture click_id and send checkout/return postbacks to RideBuilder. Zero
+  runtime dependencies (stdlib net/http + json).
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ridebuilder/affiliate.rb
+- lib/ridebuilder/affiliate/capture.rb
+- lib/ridebuilder/affiliate/click_id.rb
+- lib/ridebuilder/affiliate/client.rb
+- lib/ridebuilder/affiliate/error.rb
+- lib/ridebuilder/affiliate/models.rb
+- lib/ridebuilder/affiliate/transport.rb
+- lib/ridebuilder/affiliate/version.rb
+homepage: https://ridebuilder.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/RideBuilder/Backend
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Server-side SDK for RideBuilder FirstParty affiliate tracking.
+test_files: []