procteye 2.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f437f923e995ca9130bcdce2108540800ab2a9009342ea994a01fbcf802dd808
+  data.tar.gz: 6453d38bb38657edd487304f2a4996f81feb14e012dc0776ff83c5679a53af77
+SHA512:
+  metadata.gz: 66d038677bd0b42406a6e2e3c9df828e0a79d21fd2102bb09ad648fdd4b8c96dad03fa13a68983e7a90c52b0b7c149bfcf942a474567c1507c619b55b56967d3
+  data.tar.gz: 346e5693a9fc62a1ab784e3a8d3f8ba66ef9eb3727408c38bff17d45dd07f3a6a3dc6fbb49311fc3e5a0b12ca4f3a8ed5f05145f3dcfbbb0fea8007e4412a8b5

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 2.1.0 (2026-11-13)
+
+- Document the `session.canceled` webhook, sent after a successful cancel, and add a signed test vector for it. Document that canceling a session that is already final returns 409 `session_not_active` as an invalid request error, which is not retried.
+- Correct the `starting_after` docs: the cursor is server-side and returns the sessions created before the given id (older ones). Fix the `launch.mode` example, which showed a mode the API never returns.
+- Load without the base64 gem. Ruby 3.4 made base64 a bundled gem, so `require "procteye"` raised LoadError under Bundler; the webhook verifier now uses `Array#pack("m0")`. CI also runs the specs on Ruby 3.4.
+- Turn off Net::HTTP's own retry, so a timeout with `max_retries: 0` makes exactly one attempt instead of two.
+- Map HTTP 403 (`insufficient_scope`) to the new `Procteye::PermissionError`, a subclass of `AuthenticationError`, instead of `InvalidRequestError`.
+- Retry a 409 `idempotency_request_in_progress` with the same `Idempotency-Key` and the usual backoff, counting toward `max_retries`. Other 409s are not retried.
+- README: fix the billing example that retried forever, describe the `starting_after` cursor correctly, and document which HTTP status maps to which error class.
+- Update the webhook examples to the event types and payloads the API sends.
+- Point the gem homepage at https://docs.procteye.com and drop the source_code_uri for a repository that is not public.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Procteye
+
+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,163 @@
+# procteye (Ruby)
+
+Official **server-side** Ruby SDK for the [Procteye](https://procteye.com) Integrity API. Use it from your backend to create and manage integrity sessions and to verify incoming webhooks.
+
+> This is a secret-key SDK. Never ship your `pe_sk_...` key to a browser or mobile client.
+
+## Install
+
+```bash
+gem install procteye
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "procteye"
+```
+
+Requires Ruby 2.7+. No runtime dependencies (uses only the standard library).
+
+## Quickstart
+
+```ruby
+require "procteye"
+
+client = Procteye::Client.new(ENV["PROCTEYE_API_KEY"])
+
+session = client.sessions.create(
+  assurance_level: "HIGH",
+  external_user_ref: "user_42",
+  candidate_email: "candidate@example.com"
+)
+
+puts session.id            # method access
+puts session["client_secret"] # or hash access -> hand this to the browser
+```
+
+## Configuration
+
+```ruby
+client = Procteye::Client.new(
+  "pe_sk_live_...",                    # or ENV["PROCTEYE_API_KEY"]
+  base_url: "https://api.procteye.com", # or ENV["PROCTEYE_BASE_URL"]
+  timeout: 30.0,                        # per-request timeout (seconds)
+  max_retries: 2                        # retries on 429/5xx + transport errors
+)
+```
+
+## Sessions
+
+Every response is a `Procteye::ProcteyeObject` supporting both `session.id` and `session["id"]` access (`session.to_h` for the raw Hash).
+
+```ruby
+client.sessions.create(assurance_level: "HIGH") # POST /external/v1/sessions
+client.sessions.retrieve(id)                    # GET  /external/v1/sessions/:id
+client.sessions.complete(id)                    # POST .../complete
+client.sessions.cancel(id)                      # POST .../cancel
+
+# A single raw page (the list envelope { object: "list", data: [...] }):
+page = client.sessions.list(limit: 50)
+page.data.each { |s| puts s.id }
+```
+
+### Pagination
+
+The API paginates with a server-side cursor. Sessions come back newest first
+(by creation time, then id), up to 100 per page. Pass `starting_after:` with a
+session id to get the sessions created before it; `has_more` is true while
+more pages exist. An id that is malformed or not visible to your key returns a
+400. `auto_paging_each` follows the cursor for you, passing the last session id
+of each page as `starting_after` until `has_more` is false.
+
+```ruby
+client.sessions.auto_paging_each(limit: 50) do |session|
+  puts "#{session.id} #{session.status}"
+end
+
+# Without a block it returns an Enumerator:
+first_ten = client.sessions.auto_paging_each(limit: 50).first(10)
+```
+
+## Idempotency
+
+Every write automatically carries an `Idempotency-Key` header (a fresh UUID per call). Pass your own to make a retry safe end-to-end:
+
+```ruby
+client.sessions.create(assurance_level: "HIGH", idempotency_key: "order_1234")
+```
+
+Because writes are idempotent, the SDK safely **retries** on `429`/`5xx` and transport errors with exponential backoff and full jitter. It honors `Retry-After` up to a 60-second ceiling so a malformed upstream response cannot suspend the caller indefinitely. A `409` with code `idempotency_request_in_progress` (the first request with the same key is still running) is retried the same way, with the same `Idempotency-Key`, and counts toward `max_retries`. Any other `409`, such as `idempotency_key_in_use`, is not retried. Net::HTTP's own automatic retry is turned off, so `max_retries: 0` means exactly one attempt.
+
+## Errors
+
+All non-2xx responses raise a typed error exposing `code`, `message`, `http_status`, `request_id`, and `doc_url`.
+
+```ruby
+begin
+  client.sessions.create(assurance_level: "HIGH")
+rescue Procteye::BillingError => e
+  # Retrying straight away would fail the same way: top up first.
+  notify_billing(e.request_id) if e.code == "insufficient_credits"
+rescue Procteye::RateLimitError
+  # back off
+rescue Procteye::InvalidRequestError => e
+  warn "#{e.message} (request_id=#{e.request_id})"
+end
+```
+
+| HTTP status | Class | Retried |
+| --- | --- | --- |
+| 400 / 404 / 422 | `Procteye::InvalidRequestError` | no |
+| 401 | `Procteye::AuthenticationError` | no |
+| 402 | `Procteye::BillingError` | no |
+| 403 | `Procteye::PermissionError` (subclass of `AuthenticationError`; code `insufficient_scope`) | no |
+| 409 | `Procteye::InvalidRequestError` (code `idempotency_request_in_progress`, `idempotency_key_in_use`, or `session_not_active` from cancel on a session that is already final) | only `idempotency_request_in_progress` |
+| 429 | `Procteye::RateLimitError` | yes |
+| 5xx | `Procteye::ApiError` | yes |
+| other 4xx | `Procteye::InvalidRequestError` | no |
+| network / timeout | `Procteye::ConnectionError` | yes |
+
+All inherit from `Procteye::ProcteyeError`.
+
+## Webhook verification
+
+Verify webhook signatures with the **raw** request body ([Standard Webhooks](https://www.standardwebhooks.com) compatible). Never pass a re-serialized object — the signature is computed over the exact bytes.
+
+```ruby
+require "procteye"
+
+ENDPOINT_SECRET = ENV["PROCTEYE_WEBHOOK_SECRET"] # whsec_...
+
+post "/webhooks/procteye" do
+  raw = request.body.read # raw bytes/string, not a parsed hash
+  begin
+    event = Procteye::Webhooks.construct_event(raw, request.env, ENDPOINT_SECRET)
+  rescue Procteye::WebhookVerificationError
+    halt 400
+  end
+
+  case event["type"]
+  when "session.completed"
+    # The runtime session ended; finalize the verdict.
+    client.sessions.complete(event["data"]["id"])
+  when "session.canceled"
+    # Sent after a successful cancel.
+    puts "Session canceled: #{event["data"]["id"]}"
+  end
+  status 200
+end
+```
+
+The verifier rejects any request with a missing header, a bad signature, or a timestamp older than 5 minutes (tunable via `tolerance:`). It reads the `webhook-id`, `webhook-timestamp`, and `webhook-signature` headers (case-insensitive) and interoperates with the gateway and the Node/Python SDKs.
+
+See [`examples/`](examples) for a runnable Sinatra webhook handler and a create-session script.
+
+## Links
+
+- Documentation: https://docs.procteye.com
+- RubyGems: https://rubygems.org/gems/procteye
+
+## License
+
+MIT

data/lib/procteye/client.rb

@@ -0,0 +1,303 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "securerandom"
+require "uri"
+
+require_relative "version"
+require_relative "errors"
+require_relative "sessions"
+
+module Procteye
+  DEFAULT_BASE_URL = "https://api.procteye.com"
+  DEFAULT_TIMEOUT = 30.0
+  DEFAULT_MAX_RETRIES = 2
+  # Error code for a 409 the SDK retries: the first request with the same
+  # Idempotency-Key is still in progress.
+  IDEMPOTENCY_IN_PROGRESS = "idempotency_request_in_progress"
+  MAX_RETRY_AFTER_SECONDS = 60.0
+
+  # A thin wrapper over an API JSON object that supports both method-style and
+  # hash-style access:
+  #
+  #   session.id            # => "sess_123"
+  #   session["id"]         # => "sess_123"
+  #   session.launch.mode   # => "browser+mobile"
+  #   session.to_h          # => the underlying Hash
+  #
+  # Nested hashes and arrays are wrapped lazily. Missing keys return +nil+ via
+  # method access; use +key?+ to distinguish absent from nil.
+  class ProcteyeObject
+    def initialize(data)
+      @data = data.is_a?(Hash) ? data : {}
+    end
+
+    # Wrap a raw value: Hash -> ProcteyeObject, Array -> mapped, else as-is.
+    def self.wrap(value)
+      case value
+      when Hash then new(value)
+      when Array then value.map { |v| wrap(v) }
+      else value
+      end
+    end
+
+    def [](key)
+      str_key = key.to_s
+      value = @data.key?(str_key) ? @data[str_key] : @data[key]
+      ProcteyeObject.wrap(value)
+    end
+
+    def key?(key)
+      @data.key?(key.to_s) || @data.key?(key)
+    end
+
+    # The underlying raw Hash (unwrapped, string keys).
+    def to_h
+      @data
+    end
+    alias to_hash to_h
+
+    def keys
+      @data.keys
+    end
+
+    def each(&block)
+      @data.each(&block)
+    end
+
+    def ==(other)
+      other.is_a?(ProcteyeObject) ? to_h == other.to_h : to_h == other
+    end
+
+    def inspect
+      "#<Procteye::ProcteyeObject #{@data.inspect}>"
+    end
+    alias to_s inspect
+
+    def respond_to_missing?(name, include_private = false)
+      key?(name) || super
+    end
+
+    def method_missing(name, *args)
+      key = name.to_s
+      if @data.key?(key)
+        raise ArgumentError, "wrong number of arguments (#{args.length} for 0)" unless args.empty?
+
+        ProcteyeObject.wrap(@data[key])
+      else
+        super
+      end
+    end
+  end
+
+  # Server-side client for the Procteye Integrity API.
+  #
+  # @example
+  #   client = Procteye::Client.new(ENV["PROCTEYE_API_KEY"])
+  #   session = client.sessions.create(assurance_level: "HIGH")
+  #   puts session.id, session.client_secret
+  class Client
+    attr_reader :sessions
+
+    # Rejects any base URL that would send the secret API key over plaintext.
+    # Only +https://+ is accepted, with an exception for loopback hosts
+    # (+localhost+ / +127.0.0.1+ / +::1+) so local development and test
+    # servers keep working over plain +http://+.
+    #
+    # @param base_url [String]
+    # @return [String] the same +base_url+, when valid
+    # @raise [ProcteyeError] when the scheme would leak the API key in cleartext
+    def self.validate_base_url!(base_url)
+      uri = URI.parse(base_url)
+      return base_url if uri.scheme == "https"
+      return base_url if uri.scheme == "http" && %w[localhost 127.0.0.1 ::1].include?(uri.host)
+
+      raise ProcteyeError,
+            "Invalid base_url #{base_url.inspect}: must use https:// " \
+            "(plain http:// is only permitted for localhost). " \
+            "Refusing to send the API key over an unencrypted connection."
+    rescue URI::InvalidURIError => e
+      raise ProcteyeError, "Invalid base_url #{base_url.inspect}: #{e.message}"
+    end
+
+    # @param api_key [String] secret key (+pe_sk_live_...+ / +pe_sk_test_...+).
+    #   Defaults to +ENV["PROCTEYE_API_KEY"]+.
+    # @param base_url [String, nil] API base URL; falls back to
+    #   +ENV["PROCTEYE_BASE_URL"]+ then the production default.
+    # @param timeout [Float] per-request timeout in seconds.
+    # @param max_retries [Integer] retries on 429/5xx and transport errors.
+    # @raise [Procteye::ProcteyeError] no API key can be resolved, or +base_url+ is invalid
+    def initialize(api_key = ENV["PROCTEYE_API_KEY"], base_url: nil, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES)
+      if api_key.nil? || api_key.to_s.empty?
+        raise ProcteyeError, "No API key provided. Pass it as the first argument or set PROCTEYE_API_KEY."
+      end
+
+      @api_key = api_key
+      @base_url = self.class.validate_base_url!(base_url || ENV["PROCTEYE_BASE_URL"] || DEFAULT_BASE_URL)
+                      .sub(%r{/+\z}, "")
+      @timeout = timeout
+      @max_retries = max_retries
+
+      @sessions = SessionsResource.new(self)
+    end
+
+    # Low-level request primitive used by resource classes. Handles auth
+    # headers, idempotency keys, JSON encoding, typed error mapping, and
+    # automatic retries with exponential backoff + full jitter on 429/5xx and
+    # transport errors, honoring +Retry-After+.
+    #
+    # @return [Array(Object, String, Integer)] parsed body, request id, status.
+    # @api private
+    def request(method, path, query: nil, body: nil, idempotency_key: nil, headers: nil)
+      uri = build_uri(path, query)
+      is_write = %w[POST DELETE].include?(method)
+
+      req_headers = {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "PE-Version" => API_VERSION,
+        "User-Agent" => "procteye-ruby/#{VERSION}"
+      }
+      req_headers.merge!(headers) if headers
+
+      body_str = nil
+      unless body.nil?
+        req_headers["Content-Type"] = "application/json"
+        body_str = JSON.generate(body)
+      end
+
+      req_headers["Idempotency-Key"] = idempotency_key || SecureRandom.uuid if is_write
+
+      last_error = nil
+      attempt = 0
+      while attempt <= @max_retries
+        begin
+          status, resp_headers, raw = dispatch(uri, method, req_headers, body_str)
+        rescue ConnectionError => e
+          if attempt < @max_retries
+            last_error = e
+            sleep(backoff(attempt, nil))
+            attempt += 1
+            next
+          end
+          raise
+        end
+
+        request_id = header_value(resp_headers, "x-request-id")
+
+        if status >= 200 && status < 300
+          return [parse_success_json(raw, request_id), request_id, status]
+        end
+
+        error = Procteye.error_from_response(status, parse_json(raw), request_id)
+
+        if retryable?(status, error.code) && attempt < @max_retries
+          last_error = error
+          sleep(backoff(attempt, header_value(resp_headers, "retry-after")))
+          attempt += 1
+          next
+        end
+        raise error
+      end
+
+      raise(last_error || ConnectionError.new("Request failed after retries."))
+    end
+
+    private
+
+    def dispatch(uri, method, headers, body)
+      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 if http.respond_to?(:write_timeout=)
+      # Net::HTTP retries idempotent requests once on its own after a timeout
+      # or a dropped connection. Disable it so only the SDK's retry policy
+      # (max_retries, backoff) applies.
+      http.max_retries = 0 if http.respond_to?(:max_retries=)
+
+      request_class = case method
+                      when "GET" then Net::HTTP::Get
+                      when "POST" then Net::HTTP::Post
+                      when "DELETE" then Net::HTTP::Delete
+                      else raise ProcteyeError, "Unsupported HTTP method: #{method}"
+                      end
+
+      req = request_class.new(uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+
+      response = http.request(req)
+      [response.code.to_i, response.to_hash, response.body]
+    rescue Timeout::Error => e
+      raise ConnectionError.new("Request timed out after #{@timeout}s: #{e.message}")
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise ConnectionError.new("Network error contacting Procteye: #{e.message}")
+    end
+
+    def build_uri(path, query)
+      uri = URI.parse(@base_url + path)
+      if query
+        pairs = query.reject { |_, v| v.nil? }
+        uri.query = URI.encode_www_form(pairs) unless pairs.empty?
+      end
+      uri
+    end
+
+    def parse_json(raw)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Parses a 2xx response body, raising instead of silently returning +nil+
+    # when the body is present but not valid JSON.
+    def parse_success_json(raw, request_id)
+      return nil if raw.nil? || raw.empty?
+
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise ProcteyeError.new(
+        "Procteye returned a successful response with a malformed " \
+        "(non-JSON) body: #{e.message}",
+        request_id: request_id
+      )
+    end
+
+    def retryable?(status, code = nil)
+      # A 409 idempotency_request_in_progress means the first request with
+      # this Idempotency-Key is still running; retrying with the same key
+      # returns its result. Every other 409 (e.g. idempotency_key_in_use) is
+      # final.
+      return code == IDEMPOTENCY_IN_PROGRESS if status == 409
+
+      status == 429 || status >= 500
+    end
+
+    # Exponential backoff with full jitter; honors +Retry-After+ when present,
+    # capped so an untrusted proxy cannot suspend a caller indefinitely.
+    def backoff(attempt, retry_after)
+      if retry_after
+        seconds = Float(retry_after) rescue nil
+        return [seconds, MAX_RETRY_AFTER_SECONDS].min if seconds && seconds >= 0
+      end
+      base = [0.5 * (2**attempt), 8.0].min
+      rand * base
+    end
+
+    # Net::HTTP#to_hash returns lowercased keys mapping to Array<String>.
+    def header_value(headers, name)
+      lower = name.downcase
+      headers.each do |key, value|
+        next unless key.to_s.downcase == lower
+
+        return value.is_a?(Array) ? value.first : value
+      end
+      nil
+    end
+  end
+end

data/lib/procteye/errors.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Procteye
+  # Base class for every error raised by the SDK.
+  #
+  # Each error exposes the machine-readable +code+, the HTTP +http_status+, the
+  # correlation +request_id+, the error +type+, and a +doc_url+ when the API
+  # provides one.
+  class ProcteyeError < StandardError
+    attr_reader :code, :type, :request_id, :http_status, :doc_url
+
+    def initialize(message, code: nil, type: nil, request_id: nil, http_status: nil, doc_url: nil)
+      super(message)
+      @message = message
+      @code = code
+      @type = type
+      @request_id = request_id
+      @http_status = http_status
+      @doc_url = doc_url
+    end
+
+    # A readable one-line summary including the code/request id when present.
+    def to_s
+      parts = [@message]
+      parts << "code=#{@code}" if @code
+      parts << "request_id=#{@request_id}" if @request_id
+      parts.join(" ")
+    end
+  end
+
+  # 401 - the API key is missing, malformed, or revoked.
+  class AuthenticationError < ProcteyeError; end
+
+  # 403 - the API key is valid but lacks the scope for this request
+  # (+code == "insufficient_scope"+). Subclasses AuthenticationError, so an
+  # existing +rescue Procteye::AuthenticationError+ still catches it.
+  class PermissionError < AuthenticationError; end
+
+  # 400 / 404 / 409 / 422 - the request was rejected as invalid.
+  class InvalidRequestError < ProcteyeError; end
+
+  # 402 - a billing problem, e.g. +code == "insufficient_credits"+.
+  class BillingError < ProcteyeError; end
+
+  # 429 - rate limited. Retried automatically up to +max_retries+.
+  class RateLimitError < ProcteyeError; end
+
+  # 5xx - an unexpected error on the Procteye side. Retried automatically.
+  class ApiError < ProcteyeError; end
+
+  # Network failure, timeout, or aborted request (no HTTP response).
+  class ConnectionError < ProcteyeError; end
+
+  # Raised by +Procteye::Webhooks.construct_event+ when a payload cannot be
+  # verified.
+  class WebhookVerificationError < ProcteyeError; end
+
+  # Build the appropriate typed error from an HTTP status + parsed envelope.
+  #
+  # @param status [Integer] the HTTP status code
+  # @param payload [Hash, nil] the parsed JSON body (expects an +"error"+ key)
+  # @param request_id [String, nil] fallback request id from +X-Request-Id+
+  # @return [ProcteyeError]
+  def self.error_from_response(status, payload, request_id)
+    err = payload.is_a?(Hash) ? (payload["error"] || {}) : {}
+    err = {} unless err.is_a?(Hash)
+
+    message = err["message"] || "Procteye request failed with status #{status}"
+    opts = {
+      code: err["code"],
+      type: err["type"],
+      doc_url: err["doc_url"],
+      request_id: err["request_id"] || request_id,
+      http_status: status
+    }
+
+    case status
+    when 401 then AuthenticationError.new(message, **opts)
+    when 403 then PermissionError.new(message, **opts)
+    when 402 then BillingError.new(message, **opts)
+    when 400, 404, 422 then InvalidRequestError.new(message, **opts)
+    when 429 then RateLimitError.new(message, **opts)
+    else
+      status >= 500 ? ApiError.new(message, **opts) : InvalidRequestError.new(message, **opts)
+    end
+  end
+end

data/lib/procteye/sessions.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Procteye
+  # Operations on integrity sessions: the core resource of the API.
+  #
+  # Reachable as +client.sessions+.
+  class SessionsResource
+    # Fields accepted by {#create}; anything else is dropped.
+    CREATE_FIELDS = %i[
+      assurance_level duration_minutes external_user_ref
+      candidate_name candidate_email evidence_mode metadata
+    ].freeze
+
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a new integrity session.
+    #
+    # A fresh +Idempotency-Key+ is sent automatically; pass +idempotency_key:+
+    # to make a retry return the original session.
+    #
+    # @param assurance_level [String, nil] BASIC | STANDARD | HIGH
+    # @param duration_minutes [Integer, nil] 1..600
+    # @param external_user_ref [String, nil]
+    # @param candidate_name [String, nil]
+    # @param candidate_email [String, nil]
+    # @param evidence_mode [String, nil] NONE | THUMBNAILS | CLIPS
+    # @param metadata [Hash, nil]
+    # @param idempotency_key [String, nil]
+    # @return [Procteye::ProcteyeObject]
+    # @raise [Procteye::ProcteyeError] the API rejected the request or an unrecoverable
+    #   transport error occurred
+    def create(idempotency_key: nil, **params)
+      body = {}
+      CREATE_FIELDS.each do |field|
+        value = params[field]
+        body[field.to_s] = value unless value.nil?
+      end
+
+      data, = @client.request("POST", "/external/v1/sessions", body: body, idempotency_key: idempotency_key)
+      ProcteyeObject.wrap(data)
+    end
+
+    # Retrieve a single session by id.
+    # @param id [String] the session id
+    # @return [Procteye::ProcteyeObject]
+    # @raise [Procteye::InvalidRequestError] no session exists with the given id
+    # @raise [Procteye::ProcteyeError] any other API or transport failure
+    def retrieve(id)
+      data, = @client.request("GET", "/external/v1/sessions/#{encode(id)}")
+      ProcteyeObject.wrap(data)
+    end
+
+    # Fetch a single raw page of sessions (the list envelope
+    # +{object: "list", data: [...]}+).
+    #
+    # @param limit [Integer, nil]
+    # @param starting_after [String, nil] cursor: returns the sessions created before this id
+    # @return [Procteye::ProcteyeObject]
+    # @raise [Procteye::ProcteyeError] the API rejected the request or an unrecoverable
+    #   transport error occurred
+    def list(limit: nil, starting_after: nil)
+      data, = @client.request(
+        "GET",
+        "/external/v1/sessions",
+        query: { "limit" => limit, "starting_after" => starting_after }
+      )
+      ProcteyeObject.wrap(data)
+    end
+
+    # Auto-paginating iterator over sessions.
+    #
+    # The API exposes no server-side cursor, so pages are fetched client-side
+    # using the last session id as a +starting_after+ query parameter. Stops
+    # when the API signals +has_more: false+, or when a page returns fewer rows
+    # than +limit+. Returns an +Enumerator+ when no block is given.
+    #
+    # @example
+    #   client.sessions.auto_paging_each(limit: 50) do |session|
+    #     puts session.id, session.status
+    #   end
+    #
+    # @param limit [Integer] page size
+    # @param starting_after [String, nil] initial cursor
+    # @return [Enumerator] when no block is given
+    # @raise [Procteye::ProcteyeError] a page fetch failed with an API or transport error
+    def auto_paging_each(limit: 20, starting_after: nil)
+      return enum_for(:auto_paging_each, limit: limit, starting_after: starting_after) unless block_given?
+
+      cursor = starting_after
+      previous_first_id = nil
+      loop do
+        page = list(limit: limit, starting_after: cursor)
+        rows = page.key?(:data) ? Array(page.to_h["data"]) : []
+
+        return if rows.empty?
+
+        has_more = page.to_h["has_more"]
+        first_row = rows.first
+        first_id = first_row.is_a?(Hash) ? first_row["id"] : nil
+        # A server that predates starting_after support ignores the cursor
+        # and always returns the newest `limit` rows with no has_more field.
+        # For an org with more than `limit` sessions that page is never
+        # shorter than `limit`, so the "fewer rows than limit" stop below
+        # never fires either. Detect the repeat before yielding it so we
+        # never spin on page 1 forever or re-yield the same rows.
+        return if has_more.nil? && !previous_first_id.nil? && first_id == previous_first_id
+
+        previous_first_id = first_id
+
+        rows.each { |row| yield ProcteyeObject.wrap(row) }
+
+        return if has_more == false
+        return if has_more.nil? && rows.length < limit
+
+        cursor = rows.last.is_a?(Hash) ? rows.last["id"] : nil
+        return if cursor.nil? || cursor.to_s.empty?
+      end
+    end
+
+    # Mark a session complete (no further violations accepted).
+    # @param id [String] the session id
+    # @param idempotency_key [String, nil] overrides the auto-generated idempotency key
+    # @return [Procteye::ProcteyeObject]
+    # @raise [Procteye::InvalidRequestError] no session exists with the given id, or it
+    #   cannot be completed from its current state
+    # @raise [Procteye::ProcteyeError] any other API or transport failure
+    def complete(id, idempotency_key: nil)
+      data, = @client.request(
+        "POST", "/external/v1/sessions/#{encode(id)}/complete", body: {}, idempotency_key: idempotency_key
+      )
+      ProcteyeObject.wrap(data)
+    end
+
+    # Cancel a session before it completes. A successful cancel sends the
+    # +session.canceled+ webhook.
+    # @param id [String] the session id
+    # @param idempotency_key [String, nil] overrides the auto-generated idempotency key
+    # @return [Procteye::ProcteyeObject]
+    # @raise [Procteye::InvalidRequestError] no session exists with the given id, or it
+    #   is already final (completed, canceled or expired): HTTP 409 with code
+    #   +session_not_active+, which is not retried
+    # @raise [Procteye::ProcteyeError] any other API or transport failure
+    def cancel(id, idempotency_key: nil)
+      data, = @client.request(
+        "POST", "/external/v1/sessions/#{encode(id)}/cancel", body: {}, idempotency_key: idempotency_key
+      )
+      ProcteyeObject.wrap(data)
+    end
+
+    private
+
+    def encode(value)
+      require "erb"
+      ERB::Util.url_encode(value.to_s)
+    end
+  end
+end

data/lib/procteye/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Procteye
+  VERSION = "2.1.0"
+
+  # The dated API version pinned by this SDK. Sent as the `PE-Version` header.
+  API_VERSION = "2026-07-01"
+end

data/lib/procteye/webhooks.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+require_relative "errors"
+
+module Procteye
+  # Webhook signature verification implementing the Standard Webhooks spec
+  # (https://www.standardwebhooks.com), matching the gateway's
+  # +standardwebhooks+ signer and the Node/Python SDKs.
+  module Webhooks
+    # Default tolerance for the webhook timestamp: 5 minutes.
+    DEFAULT_TOLERANCE_SECONDS = 5 * 60
+
+    module_function
+
+    # Verify a webhook signature and return the parsed event.
+    #
+    # @param payload [String] the exact raw request body. Do NOT pass a
+    #   re-serialized object -- the signature is over the raw bytes.
+    # @param headers [Hash] the incoming request headers. Lookup is
+    #   case-insensitive and accepts +Array+ values (first element is used):
+    #   +webhook-id+, +webhook-timestamp+, +webhook-signature+.
+    # @param secret [String] the endpoint secret, e.g. +whsec_...+.
+    # @param tolerance [Integer] max allowed age of the webhook, in seconds.
+    # @return [Hash] the parsed event.
+    # @raise [WebhookVerificationError] on any missing header, bad signature,
+    #   or a timestamp outside the tolerance window.
+    def construct_event(payload, headers, secret, tolerance: DEFAULT_TOLERANCE_SECONDS)
+      if secret.nil? || !secret.is_a?(String) || secret.strip.empty?
+        raise WebhookVerificationError, "Webhook secret must be a non-empty string."
+      end
+
+      webhook_id = header_value(headers, "webhook-id")
+      timestamp = header_value(headers, "webhook-timestamp")
+      signature_header = header_value(headers, "webhook-signature")
+
+      if webhook_id.to_s.empty? || timestamp.to_s.empty? || signature_header.to_s.empty?
+        raise WebhookVerificationError,
+              "Missing required webhook headers (webhook-id, webhook-timestamp, webhook-signature)."
+      end
+
+      verify_timestamp(timestamp, tolerance)
+
+      body = payload.is_a?(String) ? payload : payload.to_s
+      signed_content = "#{webhook_id}.#{timestamp}.#{body}"
+      expected = sign(signed_content, secret)
+
+      # The header may carry a space-delimited list of `v1,<sig>` versions.
+      passed = signature_header.split(" ").any? do |part|
+        part = part.strip
+        next false if part.empty?
+
+        version, value = part.split(",", 2)
+        next false if version != "v1" || value.to_s.empty?
+
+        secure_compare(value, expected)
+      end
+
+      raise WebhookVerificationError, "Webhook signature verification failed." unless passed
+
+      begin
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise WebhookVerificationError, "Webhook payload is not valid JSON."
+      end
+    end
+
+    # Compute the base64 HMAC-SHA256 of +signed_content+.
+    #
+    # Per Standard Webhooks, the portion after +whsec_+ is base64 and is the
+    # raw HMAC key.
+    def sign(signed_content, secret)
+      if secret.nil? || !secret.is_a?(String) || secret.strip.empty?
+        raise WebhookVerificationError, "Webhook secret must be a non-empty string."
+      end
+      key_b64 = secret.start_with?("whsec_") ? secret[6..] : secret
+      if key_b64.nil? || key_b64.strip.empty?
+        raise WebhookVerificationError, "Webhook secret is invalid or empty."
+      end
+      begin
+        # "m0" is strict base64 (RFC 4648, no line feeds); it raises
+        # ArgumentError on malformed input. Array#pack/String#unpack1 are
+        # core Ruby, so the SDK does not need the base64 gem, which is no
+        # longer a default gem from Ruby 3.4.
+        key = key_b64.unpack1("m0")
+      rescue ArgumentError
+        raise WebhookVerificationError, "Invalid base64 secret."
+      end
+      if key.bytesize < 32
+        raise WebhookVerificationError, "Webhook secret key must be at least 32 bytes."
+      end
+      digest = OpenSSL::HMAC.digest("SHA256", key, signed_content)
+      [digest].pack("m0")
+    end
+
+    def verify_timestamp(timestamp, tolerance)
+      then_ts = Integer(timestamp)
+      now = Time.now.to_i
+      if (now - then_ts).abs > tolerance
+        raise WebhookVerificationError,
+              "Webhook timestamp is outside the allowed tolerance (#{tolerance}s)."
+      end
+    rescue ArgumentError, TypeError
+      raise WebhookVerificationError, "Invalid webhook-timestamp header."
+    end
+
+    # Case-insensitive header lookup returning "" when absent.
+    def header_value(headers, name)
+      lower = name.downcase
+      headers.each do |key, value|
+        next unless key.to_s.downcase == lower
+
+        return value.is_a?(Array) ? value.first.to_s : value.to_s
+      end
+      ""
+    end
+
+    # Constant-time comparison of two signature strings.
+    def secure_compare(a, b)
+      a = a.to_s
+      b = b.to_s
+      if OpenSSL.respond_to?(:fixed_length_secure_compare)
+        return false unless a.bytesize == b.bytesize
+
+        OpenSSL.fixed_length_secure_compare(a, b)
+      else
+        return false unless a.bytesize == b.bytesize
+
+        res = 0
+        a.bytes.zip(b.bytes) { |x, y| res |= x ^ y }
+        res.zero?
+      end
+    end
+  end
+end

data/lib/procteye.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# procteye - official server-side SDK for the Procteye Integrity API.
+#
+# Uses only the Ruby standard library (net/http, openssl, json, securerandom,
+# base64) so there are no runtime dependencies.
+#
+# @example
+#   require "procteye"
+#
+#   client = Procteye::Client.new(ENV["PROCTEYE_API_KEY"])
+#   session = client.sessions.create(assurance_level: "HIGH")
+#   puts session.id, session.client_secret
+module Procteye
+end
+
+require_relative "procteye/version"
+require_relative "procteye/errors"
+require_relative "procteye/sessions"
+require_relative "procteye/client"
+require_relative "procteye/webhooks"

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: procteye
+version: !ruby/object:Gem::Version
+  version: 2.1.0
+platform: ruby
+authors:
+- Procteye
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Create and manage integrity sessions and verify Standard Webhooks signatures.
+  Pure Ruby standard library, no runtime dependencies.
+email:
+- support@procteye.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/procteye.rb
+- lib/procteye/client.rb
+- lib/procteye/errors.rb
+- lib/procteye/sessions.rb
+- lib/procteye/version.rb
+- lib/procteye/webhooks.rb
+homepage: https://docs.procteye.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.procteye.com
+  documentation_uri: https://docs.procteye.com
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.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: Official server-side Ruby SDK for the Procteye Integrity API.
+test_files: []