truetrial 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 83e4d15852c9adc42118fa0641acc217e2c36991cf933bcb51545488a7328ef7
+  data.tar.gz: 9581b060426ad8f2e39a581bba1869015b6b38f27574d27376447e437f85f3e9
+SHA512:
+  metadata.gz: 366fb7f35dd26fb7269d621e90b119407219bb4eeaf5f91f4d69d30e56bed72a25146ac707afa6ffb157feb157c92d520eacfd3654c787cc9d4b06899c532c59
+  data.tar.gz: 76f50dcc1ea4195da33a4f21da58845b6ef389a741a00b0ec420b7a3e688d84db9bf264a54c0ad36a4eea01a847b22f0e5c39c321e14d468d0195134f0419edc

data/README.md

@@ -0,0 +1,233 @@
+# TrueTrial Ruby SDK
+
+Official Ruby client for the [TrueTrial](https://truetrial.com) API -- compliance-first trial, warranty, and subscription management.
+
+## Requirements
+
+- Ruby >= 3.1
+- Faraday ~> 2.0
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "truetrial", "~> 1.0"
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install directly:
+
+```sh
+gem install truetrial
+```
+
+## Quick Start
+
+```ruby
+require "truetrial"
+
+client = TrueTrial::Client.new(api_key: "tt_live_your_key_here")
+
+# List orders
+orders = client.orders.list(status: "trial_active", page: 1)
+
+# Create an order
+order = client.orders.create(
+  external_order_id: "ORD-12345",
+  product_type: "physical",
+  total_cents: 4999,
+  currency: "USD"
+)
+
+# Get order details
+order = client.orders.get("01HXYZ...")
+
+# Check order status
+status = client.orders.status("01HXYZ...")
+```
+
+## Configuration
+
+```ruby
+client = TrueTrial::Client.new(
+  api_key: "tt_live_your_key_here",
+  base_url: "https://truetrial.test/api/v1"  # default
+)
+```
+
+## API Reference
+
+### Orders
+
+```ruby
+client.orders.list(status: "delivered", page: 2)
+client.orders.create(external_order_id: "ORD-123", product_type: "physical", total_cents: 2999)
+client.orders.get("01HXYZ")
+client.orders.status("01HXYZ")
+```
+
+### Shipments
+
+```ruby
+client.shipments.create("01ORDER_ID", carrier: "ups", tracking_number: "1Z999AA10123456784")
+client.shipments.list("01ORDER_ID")
+```
+
+### Digital Delivery
+
+```ruby
+client.digital_delivery.confirm("01ORDER_ID", delivered_at: "2026-01-15T10:00:00Z")
+```
+
+### Temporal Elements (Trials, Warranties, etc.)
+
+```ruby
+client.temporal.get("01ORDER_ID")
+client.temporal.extend("01ORDER_ID", duration: 7, unit: "days", reason: "Customer request")
+client.temporal.adjust("01ORDER_ID", begins_at: "2026-01-20T00:00:00Z")
+client.temporal.claim("01ORDER_ID", reason: "Product defect", description: "Screen cracked on arrival")
+client.temporal.resolve_claim("01ORDER_ID", status: "claim_approved", notes: "Replacement shipped")
+```
+
+### Cancellations
+
+```ruby
+client.cancellations.create("01ORDER_ID", reason: "Changed mind")
+client.cancellations.get("01ORDER_ID")
+```
+
+### Webhooks
+
+```ruby
+client.webhooks.list
+client.webhooks.create(url: "https://example.com/webhooks", events: ["order.delivered", "trial.started"])
+client.webhooks.delete("01WEBHOOK_ID")
+```
+
+### System
+
+```ruby
+client.system.carrier_health
+```
+
+## Error Handling
+
+All API errors inherit from `TrueTrial::Error`:
+
+```ruby
+begin
+  client.orders.get("nonexistent")
+rescue TrueTrial::AuthenticationError => e
+  # 401 - Invalid or missing API key
+  puts e.message
+rescue TrueTrial::NotFoundError => e
+  # 404 - Resource not found
+  puts e.message
+rescue TrueTrial::ValidationError => e
+  # 422 - Validation failed
+  puts e.errors  # => { "email" => ["is required"] }
+rescue TrueTrial::RateLimitError => e
+  # 429 - Too many requests
+  puts "Retry after #{e.retry_after} seconds"
+rescue TrueTrial::ServerError => e
+  # 500+ - Server error
+  puts e.status_code
+rescue TrueTrial::Error => e
+  # Catch-all for unexpected errors
+  puts e.message
+end
+```
+
+## Webhook Verification
+
+TrueTrial signs webhook payloads with HMAC SHA-256. Verify incoming webhooks to ensure authenticity:
+
+```ruby
+# In your webhook controller / endpoint
+payload = request.body.read
+signature = request.headers["X-TrueTrial-Signature"]
+timestamp = request.headers["X-TrueTrial-Timestamp"]
+event_name = request.headers["X-TrueTrial-Event"]
+secret = "whsec_your_webhook_secret"
+
+# Simple verification (returns boolean)
+if TrueTrial::Webhook.verify?(payload, signature, secret)
+  event = JSON.parse(payload)
+  # process event...
+end
+
+# Verify with timestamp tolerance (recommended for production)
+if TrueTrial::Webhook.verify?(payload, signature, secret, tolerance: 300, timestamp: timestamp)
+  event = JSON.parse(payload)
+  # process event...
+end
+
+# Or use construct_event to verify and parse in one step (raises on failure)
+begin
+  event = TrueTrial::Webhook.construct_event(payload, signature, secret, tolerance: 300, timestamp: timestamp)
+
+  case event_name
+  when "order.delivered"
+    handle_delivery(event["data"])
+  when "trial.started"
+    handle_trial_start(event["data"])
+  when "trial.expiring"
+    handle_trial_expiring(event["data"])
+  end
+rescue TrueTrial::Error => e
+  # Invalid signature
+  render json: { error: e.message }, status: 400
+end
+```
+
+## Enums
+
+The following string values are used across the API:
+
+**OrderStatus:** `received`, `shipped`, `in_transit`, `delivered`, `trial_active`, `converted`, `returned`, `expired`, `cancelled`
+
+**TemporalType:** `trial`, `evaluation`, `subscription`, `warranty`, `guarantee`
+
+**TemporalStatus:** `pending`, `active`, `expiring`, `expired`, `converted`, `cancelled`, `suspended`, `renewed`, `claimed`, `claim_approved`, `claim_denied`
+
+**ShipmentStatus:** `pending`, `in_transit`, `out_for_delivery`, `delivered`, `failed`, `returned_to_sender`
+
+**ProductType:** `physical`, `digital`
+
+**Carrier:** `ups`, `fedex`, `usps`, `dhl`, `shippo`, `aftership`
+
+**DurationUnit:** `days`, `weeks`, `months`, `years`
+
+**DeliverySource:** `webhook`, `poll`, `manual`, `fallback_carrier`
+
+**WebhookEvent:** `order.created`, `order.delivered`, `trial.started`, `trial.expiring`, `trial.expired`, `trial.converted`, `cancellation.initiated`, `risk_score.changed`, `subscription.renewed`, `warranty.claimed`, `temporal.extended`, `temporal.adjusted`, `warranty.claim_resolved`, `payment.succeeded`, `payment.failed`, `dispute.created`, `dispute.won`, `dispute.lost`
+
+## Type Objects
+
+The SDK provides type classes for deserializing API responses:
+
+```ruby
+data = client.orders.get("01HXYZ")
+order = TrueTrial::Types::Order.from_hash(data)
+puts order.id
+puts order.status
+```
+
+Available types: `Order`, `Shipment`, `TemporalElement`, `Cancellation`, `WebhookSubscription`
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+## License
+
+MIT

data/lib/truetrial/client.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  # Main entry point for interacting with the TrueTrial API.
+  #
+  # @example
+  #   client = TrueTrial::Client.new(api_key: "tt_live_abc123")
+  #   client.orders.list
+  class Client
+    DEFAULT_BASE_URL = "https://truetrial.test/api/v1"
+
+    # @param api_key [String] your TrueTrial API key
+    # @param base_url [String] API base URL (defaults to production)
+    def initialize(api_key:, base_url: DEFAULT_BASE_URL)
+      @http_client = HttpClient.new(api_key: api_key, base_url: base_url)
+    end
+
+    # @return [TrueTrial::Resources::Orders]
+    def orders
+      @orders ||= Resources::Orders.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::Shipments]
+    def shipments
+      @shipments ||= Resources::Shipments.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::DigitalDelivery]
+    def digital_delivery
+      @digital_delivery ||= Resources::DigitalDelivery.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::Temporal]
+    def temporal
+      @temporal ||= Resources::Temporal.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::Cancellations]
+    def cancellations
+      @cancellations ||= Resources::Cancellations.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::Webhooks]
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(@http_client)
+    end
+
+    # @return [TrueTrial::Resources::System]
+    def system
+      @system ||= Resources::System.new(@http_client)
+    end
+  end
+end

data/lib/truetrial/errors.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  # Base error class for all TrueTrial API errors.
+  class Error < StandardError
+    attr_reader :status_code, :response_body
+
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Raised when the API key is missing or invalid (HTTP 401).
+  class AuthenticationError < Error
+    def initialize(message = "Invalid or missing API key", response_body: nil)
+      super(message, status_code: 401, response_body: response_body)
+    end
+  end
+
+  # Raised when request validation fails (HTTP 422).
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = "Validation failed", errors: {}, response_body: nil)
+      @errors = errors
+      super(message, status_code: 422, response_body: response_body)
+    end
+  end
+
+  # Raised when the requested resource is not found (HTTP 404).
+  class NotFoundError < Error
+    def initialize(message = "Resource not found", response_body: nil)
+      super(message, status_code: 404, response_body: response_body)
+    end
+  end
+
+  # Raised when the rate limit is exceeded (HTTP 429).
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: nil, response_body: nil)
+      @retry_after = retry_after
+      super(message, status_code: 429, response_body: response_body)
+    end
+  end
+
+  # Raised when the server returns a 5xx error.
+  class ServerError < Error
+    def initialize(message = "Internal server error", status_code: 500, response_body: nil)
+      super(message, status_code: status_code, response_body: response_body)
+    end
+  end
+end

data/lib/truetrial/http_client.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module TrueTrial
+  # Low-level HTTP client wrapping Faraday for TrueTrial API communication.
+  class HttpClient
+    def initialize(api_key:, base_url:)
+      @connection = Faraday.new(url: base_url) do |conn|
+        conn.headers["X-Api-Key"] = api_key
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.headers["User-Agent"] = "truetrial-ruby/#{TrueTrial::VERSION}"
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    # Performs a GET request.
+    #
+    # @param path [String] the API endpoint path
+    # @param params [Hash] optional query parameters
+    # @return [Hash] parsed JSON response
+    def get(path, params: {})
+      response = @connection.get(path) do |req|
+        req.params = params unless params.empty?
+      end
+      handle_response(response)
+    end
+
+    # Performs a POST request.
+    #
+    # @param path [String] the API endpoint path
+    # @param body [Hash] the request body
+    # @return [Hash] parsed JSON response
+    def post(path, body: {})
+      response = @connection.post(path) do |req|
+        req.body = JSON.generate(body)
+      end
+      handle_response(response)
+    end
+
+    # Performs a DELETE request.
+    #
+    # @param path [String] the API endpoint path
+    # @return [Hash] parsed JSON response
+    def delete(path)
+      response = @connection.delete(path)
+      handle_response(response)
+    end
+
+    private
+
+    # Maps HTTP status codes to appropriate error classes.
+    #
+    # @param response [Faraday::Response]
+    # @return [Hash] parsed response body on success
+    # @raise [TrueTrial::Error] on error responses
+    def handle_response(response)
+      body = parse_body(response.body)
+
+      case response.status
+      when 200..299
+        body
+      when 401
+        raise AuthenticationError.new(
+          error_message(body, "Invalid or missing API key"),
+          response_body: body
+        )
+      when 404
+        raise NotFoundError.new(
+          error_message(body, "Resource not found"),
+          response_body: body
+        )
+      when 422
+        raise ValidationError.new(
+          error_message(body, "Validation failed"),
+          errors: body.is_a?(Hash) ? body.fetch("errors", {}) : {},
+          response_body: body
+        )
+      when 429
+        retry_after = response.headers["Retry-After"]&.to_i
+        raise RateLimitError.new(
+          error_message(body, "Rate limit exceeded"),
+          retry_after: retry_after,
+          response_body: body
+        )
+      when 500..599
+        raise ServerError.new(
+          error_message(body, "Internal server error"),
+          status_code: response.status,
+          response_body: body
+        )
+      else
+        raise Error.new(
+          error_message(body, "Unexpected response"),
+          status_code: response.status,
+          response_body: body
+        )
+      end
+    end
+
+    # Safely parses JSON, returning the raw string on failure.
+    def parse_body(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      raw
+    end
+
+    # Extracts an error message from the response body hash.
+    def error_message(body, default)
+      return default unless body.is_a?(Hash)
+
+      body["message"] || body["error"] || default
+    end
+  end
+end

data/lib/truetrial/resources/cancellations.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to cancellation-related API endpoints.
+    class Cancellations
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Creates a cancellation for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] cancellation attributes (reason, etc.)
+      # @return [Hash] the created cancellation
+      def create(order_id, data)
+        @http.post("/orders/#{order_id}/cancellations", body: data)
+      end
+
+      # Retrieves the cancellation for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @return [Hash] the cancellation
+      def get(order_id)
+        @http.get("/orders/#{order_id}/cancellations")
+      end
+    end
+  end
+end

data/lib/truetrial/resources/digital_delivery.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to digital delivery confirmation endpoints.
+    class DigitalDelivery
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Confirms digital delivery for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] digital delivery confirmation attributes
+      # @return [Hash] the delivery confirmation result
+      def confirm(order_id, data)
+        @http.post("/orders/#{order_id}/digital-delivery", body: data)
+      end
+    end
+  end
+end

data/lib/truetrial/resources/orders.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to order-related API endpoints.
+    class Orders
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Lists orders with optional filters.
+      #
+      # @param filters [Hash] optional query filters (status, page, per_page, etc.)
+      # @return [Hash] paginated list of orders
+      def list(filters = {})
+        @http.get("/orders", params: filters)
+      end
+
+      # Creates a new order.
+      #
+      # @param data [Hash] order attributes
+      # @return [Hash] the created order
+      def create(data)
+        @http.post("/orders", body: data)
+      end
+
+      # Retrieves a single order by ID.
+      #
+      # @param id [String] the order ULID
+      # @return [Hash] the order
+      def get(id)
+        @http.get("/orders/#{id}")
+      end
+
+      # Retrieves the current status of an order.
+      #
+      # @param id [String] the order ULID
+      # @return [Hash] the order status
+      def status(id)
+        @http.get("/orders/#{id}/status")
+      end
+    end
+  end
+end

data/lib/truetrial/resources/shipments.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to shipment-related API endpoints.
+    class Shipments
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Creates a shipment for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] shipment attributes (carrier, tracking_number, etc.)
+      # @return [Hash] the created shipment
+      def create(order_id, data)
+        @http.post("/orders/#{order_id}/shipments", body: data)
+      end
+
+      # Lists all shipments for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @return [Hash] list of shipments
+      def list(order_id)
+        @http.get("/orders/#{order_id}/shipments")
+      end
+    end
+  end
+end

data/lib/truetrial/resources/system.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to system-level API endpoints.
+    class System
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Retrieves carrier health status.
+      #
+      # @return [Hash] carrier health information
+      def carrier_health
+        @http.get("/carrier-health")
+      end
+    end
+  end
+end

data/lib/truetrial/resources/temporal.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to temporal element API endpoints (trials, warranties, etc.).
+    class Temporal
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Retrieves the temporal element for an order.
+      #
+      # @param order_id [String] the order ULID
+      # @return [Hash] the temporal element
+      def get(order_id)
+        @http.get("/orders/#{order_id}/temporal")
+      end
+
+      # Extends a temporal element duration.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] extension attributes (duration, unit, reason)
+      # @return [Hash] the updated temporal element
+      def extend(order_id, data)
+        @http.post("/orders/#{order_id}/temporal/extend", body: data)
+      end
+
+      # Adjusts a temporal element (modify start/end dates).
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] adjustment attributes
+      # @return [Hash] the updated temporal element
+      def adjust(order_id, data)
+        @http.post("/orders/#{order_id}/temporal/adjust", body: data)
+      end
+
+      # Initiates a warranty or guarantee claim.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] claim attributes (reason, description)
+      # @return [Hash] the created claim
+      def claim(order_id, data)
+        @http.post("/orders/#{order_id}/temporal/claim", body: data)
+      end
+
+      # Resolves a warranty or guarantee claim.
+      #
+      # @param order_id [String] the order ULID
+      # @param data [Hash] resolution attributes (status, notes)
+      # @return [Hash] the resolved claim
+      def resolve_claim(order_id, data)
+        @http.post("/orders/#{order_id}/temporal/resolve-claim", body: data)
+      end
+    end
+  end
+end

data/lib/truetrial/resources/webhooks.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Resources
+    # Provides access to webhook subscription management endpoints.
+    class Webhooks
+      def initialize(http_client)
+        @http = http_client
+      end
+
+      # Lists all webhook subscriptions.
+      #
+      # @return [Hash] list of webhook subscriptions
+      def list
+        @http.get("/webhooks")
+      end
+
+      # Creates a new webhook subscription.
+      #
+      # @param data [Hash] webhook attributes (url, events, secret)
+      # @return [Hash] the created webhook subscription
+      def create(data)
+        @http.post("/webhooks", body: data)
+      end
+
+      # Deletes a webhook subscription.
+      #
+      # @param id [String] the webhook subscription ULID
+      # @return [Hash] deletion confirmation
+      def delete(id)
+        @http.delete("/webhooks/#{id}")
+      end
+    end
+  end
+end

data/lib/truetrial/types/cancellation.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Types
+    # Represents a cancellation returned from the TrueTrial API.
+    class Cancellation
+      attr_reader :id, :order_id, :reason, :cancelled_by, :notes,
+                  :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @order_id = attributes["order_id"]
+        @reason = attributes["reason"]
+        @cancelled_by = attributes["cancelled_by"]
+        @notes = attributes["notes"]
+        @created_at = attributes["created_at"]
+        @updated_at = attributes["updated_at"]
+      end
+
+      # Builds a Cancellation from an API response hash.
+      #
+      # @param hash [Hash] raw API response data
+      # @return [Cancellation]
+      def self.from_hash(hash)
+        new(hash)
+      end
+    end
+  end
+end

data/lib/truetrial/types/order.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Types
+    # Represents an order returned from the TrueTrial API.
+    class Order
+      attr_reader :id, :tenant_id, :consumer_id, :external_order_id, :status,
+                  :product_type, :total_cents, :currency, :metadata,
+                  :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @tenant_id = attributes["tenant_id"]
+        @consumer_id = attributes["consumer_id"]
+        @external_order_id = attributes["external_order_id"]
+        @status = attributes["status"]
+        @product_type = attributes["product_type"]
+        @total_cents = attributes["total_cents"]
+        @currency = attributes["currency"]
+        @metadata = attributes["metadata"]
+        @created_at = attributes["created_at"]
+        @updated_at = attributes["updated_at"]
+      end
+
+      # Builds an Order from an API response hash.
+      #
+      # @param hash [Hash] raw API response data
+      # @return [Order]
+      def self.from_hash(hash)
+        new(hash)
+      end
+    end
+  end
+end

data/lib/truetrial/types/shipment.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Types
+    # Represents a shipment returned from the TrueTrial API.
+    class Shipment
+      attr_reader :id, :order_id, :carrier, :tracking_number, :status,
+                  :shipped_at, :delivered_at, :delivery_source,
+                  :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @order_id = attributes["order_id"]
+        @carrier = attributes["carrier"]
+        @tracking_number = attributes["tracking_number"]
+        @status = attributes["status"]
+        @shipped_at = attributes["shipped_at"]
+        @delivered_at = attributes["delivered_at"]
+        @delivery_source = attributes["delivery_source"]
+        @created_at = attributes["created_at"]
+        @updated_at = attributes["updated_at"]
+      end
+
+      # Builds a Shipment from an API response hash.
+      #
+      # @param hash [Hash] raw API response data
+      # @return [Shipment]
+      def self.from_hash(hash)
+        new(hash)
+      end
+    end
+  end
+end

data/lib/truetrial/types/temporal_element.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Types
+    # Represents a temporal element (trial, warranty, subscription, etc.)
+    # returned from the TrueTrial API.
+    class TemporalElement
+      attr_reader :id, :order_id, :type, :status, :duration, :duration_unit,
+                  :begins_at, :expires_at, :converted_at, :cancelled_at,
+                  :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @order_id = attributes["order_id"]
+        @type = attributes["type"]
+        @status = attributes["status"]
+        @duration = attributes["duration"]
+        @duration_unit = attributes["duration_unit"]
+        @begins_at = attributes["begins_at"]
+        @expires_at = attributes["expires_at"]
+        @converted_at = attributes["converted_at"]
+        @cancelled_at = attributes["cancelled_at"]
+        @created_at = attributes["created_at"]
+        @updated_at = attributes["updated_at"]
+      end
+
+      # Builds a TemporalElement from an API response hash.
+      #
+      # @param hash [Hash] raw API response data
+      # @return [TemporalElement]
+      def self.from_hash(hash)
+        new(hash)
+      end
+    end
+  end
+end

data/lib/truetrial/types/webhook_subscription.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module TrueTrial
+  module Types
+    # Represents a webhook subscription returned from the TrueTrial API.
+    class WebhookSubscription
+      attr_reader :id, :url, :events, :secret, :active,
+                  :created_at, :updated_at
+
+      def initialize(attributes = {})
+        @id = attributes["id"]
+        @url = attributes["url"]
+        @events = attributes["events"]
+        @secret = attributes["secret"]
+        @active = attributes["active"]
+        @created_at = attributes["created_at"]
+        @updated_at = attributes["updated_at"]
+      end
+
+      # Builds a WebhookSubscription from an API response hash.
+      #
+      # @param hash [Hash] raw API response data
+      # @return [WebhookSubscription]
+      def self.from_hash(hash)
+        new(hash)
+      end
+    end
+  end
+end

data/lib/truetrial/version.rb

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

data/lib/truetrial/webhook.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "json"
+require "time"
+
+module TrueTrial
+  # Utilities for verifying and parsing incoming TrueTrial webhooks.
+  #
+  # Webhook payloads are signed with HMAC SHA-256. The signature is delivered
+  # in the X-TrueTrial-Signature header and is computed from the raw JSON body
+  # using the webhook secret.
+  module Webhook
+    module_function
+
+    # Verifies that a webhook payload matches its signature.
+    #
+    # @param payload [String] the raw JSON request body
+    # @param signature [String] the value of the X-TrueTrial-Signature header
+    # @param secret [String] the webhook signing secret
+    # @param tolerance [Integer, nil] maximum age of the event in seconds (optional)
+    # @param timestamp [String, nil] the value of the X-TrueTrial-Timestamp header (required when tolerance is set)
+    # @return [Boolean] true if the signature is valid
+    def verify?(payload, signature, secret, tolerance: nil, timestamp: nil)
+      expected = compute_signature(payload, secret)
+      valid = secure_compare(expected, signature)
+
+      if valid && tolerance && timestamp
+        event_time = Time.parse(timestamp)
+        valid = (Time.now - event_time).abs <= tolerance
+      end
+
+      valid
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    # Verifies and parses a webhook payload into a hash.
+    #
+    # @param payload [String] the raw JSON request body
+    # @param signature [String] the value of the X-TrueTrial-Signature header
+    # @param secret [String] the webhook signing secret
+    # @param tolerance [Integer, nil] maximum age of the event in seconds (optional)
+    # @param timestamp [String, nil] the value of the X-TrueTrial-Timestamp header (required when tolerance is set)
+    # @return [Hash] the parsed event data
+    # @raise [TrueTrial::Error] if the signature is invalid
+    def construct_event(payload, signature, secret, tolerance: nil, timestamp: nil)
+      unless verify?(payload, signature, secret, tolerance: tolerance, timestamp: timestamp)
+        raise Error.new("Invalid webhook signature")
+      end
+
+      JSON.parse(payload)
+    end
+
+    # Computes the HMAC SHA-256 hex digest for a payload.
+    #
+    # @param payload [String] the raw payload
+    # @param secret [String] the signing secret
+    # @return [String] hex-encoded HMAC signature
+    def compute_signature(payload, secret)
+      OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+    end
+
+    # Performs a constant-time string comparison to prevent timing attacks.
+    #
+    # @param a [String]
+    # @param b [String]
+    # @return [Boolean]
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    rescue NoMethodError
+      # Fallback for older OpenSSL versions
+      l = a.unpack("C*")
+      r = b.unpack("C*")
+      result = 0
+      l.zip(r) { |x, y| result |= x ^ y }
+      result.zero?
+    end
+  end
+end

data/lib/truetrial.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "truetrial/version"
+require_relative "truetrial/errors"
+require_relative "truetrial/http_client"
+require_relative "truetrial/client"
+require_relative "truetrial/webhook"
+
+require_relative "truetrial/types/order"
+require_relative "truetrial/types/shipment"
+require_relative "truetrial/types/temporal_element"
+require_relative "truetrial/types/cancellation"
+require_relative "truetrial/types/webhook_subscription"
+
+require_relative "truetrial/resources/orders"
+require_relative "truetrial/resources/shipments"
+require_relative "truetrial/resources/digital_delivery"
+require_relative "truetrial/resources/temporal"
+require_relative "truetrial/resources/cancellations"
+require_relative "truetrial/resources/webhooks"
+require_relative "truetrial/resources/system"
+
+module TrueTrial
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: truetrial
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- TrueTrial
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-05-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Official Ruby client for the TrueTrial compliance-first trial and warranty
+  management platform.
+email:
+- support@truetrial.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/truetrial.rb
+- lib/truetrial/client.rb
+- lib/truetrial/errors.rb
+- lib/truetrial/http_client.rb
+- lib/truetrial/resources/cancellations.rb
+- lib/truetrial/resources/digital_delivery.rb
+- lib/truetrial/resources/orders.rb
+- lib/truetrial/resources/shipments.rb
+- lib/truetrial/resources/system.rb
+- lib/truetrial/resources/temporal.rb
+- lib/truetrial/resources/webhooks.rb
+- lib/truetrial/types/cancellation.rb
+- lib/truetrial/types/order.rb
+- lib/truetrial/types/shipment.rb
+- lib/truetrial/types/temporal_element.rb
+- lib/truetrial/types/webhook_subscription.rb
+- lib/truetrial/version.rb
+- lib/truetrial/webhook.rb
+homepage: https://github.com/truetrial/truetrial-ruby-sdk
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/truetrial/truetrial-ruby-sdk
+  source_code_uri: https://github.com/truetrial/truetrial-ruby-sdk
+  changelog_uri: https://github.com/truetrial/truetrial-ruby-sdk/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby SDK for the TrueTrial API
+test_files: []