praxicraft 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 26c92d762b713245618649e5fe3da4e13edcf98568d5dcfd19d82dd372131c2b
+  data.tar.gz: 6e8b264590158078499b9b9400845f2164b6e288f0220cc52cde6dc3ff5b4c19
+SHA512:
+  metadata.gz: 519a74d3ed0df3cbfa62c4cf3c09b238ca72341af4564ab62a1458ab2eff22f182f5599490a46faf5d58ab6672c5b87c5e75417d74ed05f4ddb5d98894097c08
+  data.tar.gz: c99f3744dd05bab9bee7858565066dc581aa2c1a91b66c3904696c30d6e66b976babb11dac29c723f231a4fafe9c677e29225743c5a3e60ce189bfeff7105f4b

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.1] — 2026-08-21
+
+### Changed
+
+- Align error mapping and retry behaviour with the Node SDK (status-based exceptions, 8s `Retry-After` cap).
+- Fix path-segment encoding so spaces become `%20`.
+
+## [0.1.0] — 2026-08-21
+
+### Added
+
+- Initial Assess Public API SDK.
+- `Client` with Bearer API-key auth (`PRAXICRAFT_API_KEY` / `PRAXICRAFT_API_BASE_URL`).
+- Automatic retries on `429` / `5xx` / transport errors (default 2), honouring `Retry-After`.
+- Typed / mapped errors from `{ error: { code, message } }`.
+- Resources: org, assessments, invites, results, webhooks, pipelines.
+- Webhook signature helper for `X-Praxicraft-Signature`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PraxiCraft
+
+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,233 @@
+# Praxicraft Assess Ruby SDK
+
+Official Ruby client for the **[Praxicraft Assess](https://assess.praxicraft.com)** Public API.
+
+Use it to invite candidates, check invite quota, manage webhooks, enroll hiring pipelines, and fetch results from your ATS, backend, or automation scripts.
+
+```bash
+gem install praxicraft
+```
+
+Until RubyGems publish, install from GitHub:
+
+```ruby
+# Gemfile
+gem "praxicraft", git: "https://github.com/praxicraft-platform/praxicraft-ruby.git"
+```
+
+**Requires Ruby 3.1+.** Full API reference: [docs.praxicraft.com/sdks/ruby](https://docs.praxicraft.com/sdks/ruby)
+
+## Table of Contents
+
+- [Authentication](#authentication)
+- [Quickstart](#quickstart)
+- [What you can do](#what-you-can-do)
+  - [Check invite quota before bulk sends](#check-invite-quota-before-bulk-sends)
+  - [Bulk invites](#bulk-invites)
+  - [Build and activate an assessment via API](#build-and-activate-an-assessment-via-api)
+  - [Register and test a webhook](#register-and-test-a-webhook)
+  - [Enroll into a hiring pipeline](#enroll-into-a-hiring-pipeline)
+  - [Paginate cohort results](#paginate-cohort-results)
+  - [Verify webhook signatures](#verify-webhook-signatures)
+- [Errors](#errors)
+- [Requirements & support](#requirements--support)
+- [License](#license)
+
+---
+
+## Authentication
+
+Create an organisation API key in Assess:
+
+**Assess → Developer → API Keys** → create key → copy `ct_live_…` (shown once).
+
+```bash
+export PRAXICRAFT_API_KEY="ct_live_xxxxxxxxxxxxxxxx"
+```
+
+Or pass the key when constructing the client:
+
+```ruby
+require "praxicraft"
+
+client = Praxicraft::Client.new(api_key: "ct_live_xxxxxxxxxxxxxxxx")
+```
+
+Optional: override the API host with `PRAXICRAFT_API_BASE_URL` or `Praxicraft::Client.new(base_url: "...")`.
+Default host: `https://assess.praxicraft.com`.
+
+Never commit API keys. Prefer environment variables or a secrets manager.
+
+Scopes and rotation: [Authentication](https://docs.praxicraft.com/authentication)
+
+---
+
+## Quickstart
+
+```ruby
+require "praxicraft"
+
+client = Praxicraft::Client.new # reads PRAXICRAFT_API_KEY
+
+page = client.assessments.list
+page.fetch("results", []).each do |assessment|
+  puts "#{assessment["slug"]} #{assessment["status"]}"
+end
+
+# Invite a candidate (idempotent on email — safe to retry)
+invite = client.invites.create(
+  "senior-backend-screen",
+  email: "candidate@example.com",
+  name: "Jane Doe",
+  send_email: true
+)
+puts "#{invite["invite_token"]} #{invite["invite_url"]}"
+
+result = client.results.retrieve(invite["invite_token"])
+p result
+```
+
+Responses are **flat JSON** (same shape as the Public API — no `{ "data": … }` wrapper).
+
+---
+
+## What you can do
+
+| Resource | Common methods |
+|----------|----------------|
+| `client.org` | `retrieve`, `stats` |
+| `client.assessments` | `list`, `retrieve`, `create`, `update`, `activate`, `list_cases`, `attach_cases`, `replace_cases`, `remove_case` |
+| `client.invites` | `create`, `bulk_create`, `list`, `retrieve`, `remind`, `cancel` |
+| `client.results` | `list`, `retrieve`, `iter_all` |
+| `client.webhooks` | `list`, `create`, `retrieve`, `update`, `delete`, `test`, `deliveries` |
+| `client.pipelines` | `list`, `retrieve`, `enroll`, `bulk_enroll`, `list_enrollments`, `get_enrollment` |
+| `Praxicraft::Webhooks.verify_signature` | Verify `X-Praxicraft-Signature` on webhook payloads |
+
+All paths target `/api/v1/public/…` on the Assess host.
+
+### Check invite quota before bulk sends
+
+```ruby
+org = client.org.retrieve
+if (org["invites_remaining"] || 0) < candidates.length
+  abort "Not enough invites remaining this month"
+end
+```
+
+### Bulk invites
+
+```ruby
+client.invites.bulk_create(
+  "senior-backend-screen",
+  [
+    { "email" => "a@example.com", "name" => "Alex" },
+    { "email" => "b@example.com", "name" => "Blair" }
+  ],
+  send_email: true
+)
+```
+
+### Build and activate an assessment via API
+
+```ruby
+assessment = client.assessments.create(title: "Backend screen")
+client.assessments.attach_cases(
+  assessment["slug"],
+  cases: [{ "case_id" => "<platform-or-org-case-uuid>", "source" => "platform" }]
+)
+client.assessments.activate(assessment["slug"])
+```
+
+### Register and test a webhook
+
+```ruby
+hook = client.webhooks.create(
+  url: "https://example.com/hooks/praxicraft",
+  events: ["assessment.completed", "candidate.passed"]
+)
+# Store hook["secret_key"] (whsec_…) — shown once
+client.webhooks.test(hook["id"])
+client.webhooks.update(hook["id"], is_active: true)
+```
+
+### Enroll into a hiring pipeline
+
+```ruby
+enrollment = client.pipelines.enroll(
+  "grad-2025",
+  email: "alex@example.com",
+  name: "Alex Lee",
+  send_email: true
+)
+status = client.pipelines.get_enrollment(enrollment["enrollment_id"])
+```
+
+### Paginate cohort results
+
+```ruby
+client.results.iter_all("senior-backend-screen", page_size: 50) do |row|
+  puts "#{row["email"]} #{row["score_percentage"]} #{row["passed"]}"
+end
+```
+
+### Verify webhook signatures
+
+Assess signs the **raw request body** with your webhook secret (`whsec_…`):
+
+```ruby
+def handle_webhook(raw_body, signature_header, secret)
+  Praxicraft::Webhooks.verify_signature(secret, raw_body, signature_header)
+end
+```
+
+Header format: `X-Praxicraft-Signature: sha256=<hex>`
+
+Event catalog and payload examples: [Webhooks](https://docs.praxicraft.com/webhooks)
+
+---
+
+## Errors
+
+Public API errors look like:
+
+```json
+{
+  "error": {
+    "code": "INSUFFICIENT_SCOPE",
+    "message": "This API key does not have the 'candidates:read' scope."
+  }
+}
+```
+
+The SDK raises typed exceptions. **Branch on `exc.error_code` (or `exc.code`)**, not the message text:
+
+```ruby
+begin
+  client.invites.create("demo", email: "candidate@example.com")
+rescue Praxicraft::ValidationError => exc
+  puts exc.error_code, exc.details
+rescue Praxicraft::InsufficientScopeError => exc
+  puts exc.error_code
+rescue Praxicraft::AuthenticationError => exc
+  puts exc.error_code
+rescue Praxicraft::RateLimitError => exc
+  puts exc.retry_after
+end
+```
+
+Error codes: [Errors](https://docs.praxicraft.com/errors)
+
+---
+
+## Requirements & support
+
+- Ruby **3.1**, **3.2**, or **3.3+**
+- Uses stdlib `Net::HTTP` (no extra runtime gems)
+- Product docs: [docs.praxicraft.com](https://docs.praxicraft.com)
+- Issues: [GitHub Issues](https://github.com/praxicraft-platform/praxicraft-ruby/issues)
+
+---
+
+## License
+
+[MIT](LICENSE)

data/lib/praxicraft/client.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+require "time"
+require "openssl"
+
+module Praxicraft
+  class Client
+    DEFAULT_BASE_URL = "https://assess.praxicraft.com"
+    DEFAULT_API_PREFIX = "/api/v1/public"
+    DEFAULT_TIMEOUT_SECONDS = 30.0
+    DEFAULT_MAX_RETRIES = 2
+
+    attr_reader :api_key, :base_url, :api_prefix, :timeout_seconds, :max_retries
+    attr_reader :org, :assessments, :invites, :results, :webhooks, :pipelines
+
+    # Options keys: :api_key, :base_url, :timeout_seconds, :max_retries, :http_handler
+    # http_handler: callable(method, url, headers, body) -> { status:, headers:, body: }
+    def initialize(options = nil, **kwargs)
+      opts = {}
+      opts.merge!(options.transform_keys(&:to_sym)) if options.is_a?(Hash)
+      opts.merge!(kwargs)
+
+      key = (opts[:api_key] || ENV["PRAXICRAFT_API_KEY"] || "").to_s.strip
+      if key.empty?
+        raise APIError.new(
+          "No API key provided. Pass api_key or set PRAXICRAFT_API_KEY.",
+          "MISSING_API_KEY"
+        )
+      end
+
+      base = (opts[:base_url] || ENV["PRAXICRAFT_API_BASE_URL"] || DEFAULT_BASE_URL).to_s.strip
+      base = base.sub(%r{/*\z}, "")
+      if base.empty?
+        raise APIError.new("baseUrl must be a non-empty URL.", "INVALID_BASE_URL")
+      end
+
+      @api_key = key
+      @base_url = base
+      @api_prefix = DEFAULT_API_PREFIX
+      @timeout_seconds = (opts[:timeout_seconds] || DEFAULT_TIMEOUT_SECONDS).to_f
+      @max_retries = [0, (opts[:max_retries] || DEFAULT_MAX_RETRIES).to_i].max
+      @http_handler = opts[:http_handler]
+
+      @org = Resources::Org.new(self)
+      @assessments = Resources::Assessments.new(self)
+      @invites = Resources::Invites.new(self)
+      @results = Resources::Results.new(self)
+      @webhooks = Resources::Webhooks.new(self)
+      @pipelines = Resources::Pipelines.new(self)
+    end
+
+    def get(path, params = nil)
+      request("GET", path, params: params)
+    end
+
+    def post(path, json = nil)
+      request("POST", path, json: json)
+    end
+
+    def put(path, json = nil)
+      request("PUT", path, json: json)
+    end
+
+    def patch(path, json = nil)
+      request("PATCH", path, json: json)
+    end
+
+    def delete(path, json = nil)
+      request("DELETE", path, json: json)
+    end
+
+    def self.path_segment(value, label = "id")
+      text = value.to_s.strip
+      if text.empty?
+        raise APIError.new("#{label} must be a non-empty string", "INVALID_PATH")
+      end
+
+      # Path-component encoding (spaces as %20), matching Node encodeURIComponent.
+      URI.encode_www_form_component(text).gsub("+", "%20")
+    end
+
+    def path_segment(value, label = "id")
+      self.class.path_segment(value, label)
+    end
+
+    def request(method, path, params: nil, json: nil)
+      attempts = @max_retries + 1
+      last_error = nil
+
+      attempts.times do |attempt|
+        if attempt.positive?
+          retry_after = nil
+          if last_error.is_a?(APIStatusError)
+            retry_after = last_error.headers["retry-after"]
+          end
+          sleep(self.class.retry_delay_seconds(attempt - 1, retry_after))
+        end
+
+        begin
+          return request_once(method, path, params: params, json: json)
+        rescue APIConnectionError => e
+          last_error = e
+          next if attempt < attempts - 1
+
+          raise
+        rescue APIStatusError => e
+          last_error = e
+          next if self.class.should_retry_status?(e.status_code) && attempt < attempts - 1
+
+          raise
+        end
+      end
+
+      raise last_error || APIConnectionError.new
+    end
+
+    RETRY_BASE_SECONDS = 0.5
+    RETRY_CAP_SECONDS = 8.0
+    RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+
+    def self.should_retry_status?(status)
+      RETRYABLE_STATUS_CODES.include?(status)
+    end
+
+    def self.parse_retry_after_seconds(retry_after)
+      return nil if retry_after.nil? || retry_after.to_s.strip.empty?
+
+      text = retry_after.to_s.strip
+      return [0.0, text.to_f].max if text.match?(/\A\d+(\.\d+)?\z/)
+
+      begin
+        when_time = Time.httpdate(text)
+        [0.0, when_time - Time.now].max
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    def self.retry_delay_seconds(retry_index, retry_after)
+      parsed = parse_retry_after_seconds(retry_after)
+      return [parsed, RETRY_CAP_SECONDS].min unless parsed.nil?
+
+      ceiling = [RETRY_CAP_SECONDS, RETRY_BASE_SECONDS * (2**retry_index)].min
+      rand * ceiling
+    end
+
+    def self.raise_for_status(status_code, body, headers, raw)
+      error = {}
+      if body.is_a?(Hash) && body["error"].is_a?(Hash)
+        error = body["error"]
+      end
+
+      code = error["code"].is_a?(String) ? error["code"] : nil
+      message = error["message"].is_a?(String) ? error["message"] : nil
+      details = error["details"]
+      required_plan = error["required_plan"].is_a?(String) ? error["required_plan"] : nil
+
+      if message.nil? || message.empty?
+        trimmed = raw.to_s.strip
+        message = trimmed.empty? ? "API request failed with status #{status_code}." : trimmed[0, 500]
+      end
+
+      retry_after = parse_retry_after_seconds(headers["retry-after"])
+
+      kwargs = {
+        status_code: status_code,
+        error_code: code,
+        details: details,
+        response_body: body,
+        headers: headers,
+        required_plan: required_plan,
+        retry_after: retry_after
+      }
+
+      raise AuthenticationError.new(message, **kwargs) if status_code == 401
+      raise InsufficientScopeError.new(message, **kwargs) if status_code == 403
+      raise NotFoundError.new(message, **kwargs) if status_code == 404
+      raise RateLimitError.new(message, **kwargs) if status_code == 429
+      raise ValidationError.new(message, **kwargs) if status_code >= 400 && status_code < 500
+
+      raise APIStatusError.new(message, **kwargs)
+    end
+
+    private
+
+    def request_once(method, path, params: nil, json: nil)
+      url = "#{@base_url}#{@api_prefix}#{path}"
+      if params && !params.empty?
+        query = URI.encode_www_form(flatten_params(params))
+        url = "#{url}#{url.include?('?') ? '&' : '?'}#{query}" unless query.empty?
+      end
+
+      headers = {
+        "Accept" => "application/json",
+        "Authorization" => "Bearer #{@api_key}",
+        "User-Agent" => "praxicraft-ruby/#{VERSION}"
+      }
+
+      body = nil
+      unless json.nil?
+        body = JSON.generate(json)
+        headers["Content-Type"] = "application/json"
+      end
+
+      begin
+        response = if @http_handler
+                     @http_handler.call(method, url, headers, body)
+                   else
+                     net_http_request(method, url, headers, body)
+                   end
+      rescue APIConnectionError
+        raise
+      rescue StandardError => e
+        raise APIConnectionError, e.message
+      end
+
+      status = response[:status] || response["status"]
+      resp_headers = normalize_headers(response[:headers] || response["headers"] || {})
+      raw = (response[:body] || response["body"] || "").to_s
+
+      decoded = nil
+      unless raw.empty?
+        begin
+          decoded = JSON.parse(raw)
+        rescue JSON::ParserError
+          if status.to_i >= 200 && status.to_i < 300
+            raise APIError.new("Invalid JSON response (HTTP #{status}).", "INVALID_JSON")
+          end
+          decoded = raw
+        end
+      end
+
+      return decoded if status.to_i >= 200 && status.to_i < 300
+
+      self.class.raise_for_status(status.to_i, decoded, resp_headers, raw)
+    end
+
+    def net_http_request(method, url, headers, body)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @timeout_seconds
+      http.read_timeout = @timeout_seconds
+
+      request = Net::HTTPGenericRequest.new(
+        method.upcase,
+        !body.nil?,
+        true,
+        uri.request_uri,
+        headers
+      )
+      request.body = body unless body.nil?
+
+      res = http.request(request)
+      {
+        status: res.code.to_i,
+        headers: res.each_header.to_h,
+        body: res.body.to_s
+      }
+    rescue Timeout::Error, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError, OpenSSL::SSL::SSLError => e
+      raise APIConnectionError, e.message
+    end
+
+    def flatten_params(params)
+      out = {}
+      params.each do |k, v|
+        next if v.nil?
+
+        out[k.to_s] = if v == true
+                        "true"
+                      elsif v == false
+                        "false"
+                      else
+                        v
+                      end
+      end
+      out
+    end
+
+    def normalize_headers(headers)
+      headers.each_with_object({}) do |(k, v), acc|
+        acc[k.to_s.downcase] = v.to_s
+      end
+    end
+  end
+end

data/lib/praxicraft/errors.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  class Error < StandardError
+    attr_reader :error_code
+
+    def initialize(message, error_code = nil)
+      super(message)
+      @error_code = error_code
+    end
+
+    alias code error_code
+  end
+
+  class APIError < Error; end
+
+  class APIConnectionError < APIError
+    def initialize(message = "Failed to connect to the Praxicraft API.")
+      super(message, "CONNECTION_ERROR")
+    end
+  end
+
+  class APIStatusError < APIError
+    attr_reader :status_code, :details, :response_body, :headers, :required_plan, :retry_after
+
+    def initialize(
+      message,
+      status_code:,
+      error_code: nil,
+      details: nil,
+      response_body: nil,
+      headers: {},
+      required_plan: nil,
+      retry_after: nil
+    )
+      super(message, error_code)
+      @status_code = status_code
+      @details = details
+      @response_body = response_body
+      @headers = headers || {}
+      @required_plan = required_plan
+      @retry_after = retry_after
+    end
+  end
+
+  class AuthenticationError < APIStatusError; end
+  class InsufficientScopeError < APIStatusError; end
+  class NotFoundError < APIStatusError; end
+  class ValidationError < APIStatusError; end
+  class RateLimitError < APIStatusError; end
+end

data/lib/praxicraft/resources/assessments.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  module Resources
+    class Assessments
+      def initialize(client)
+        @client = client
+      end
+
+      def list(params = nil)
+        @client.get("/assessments/", normalize(params))
+      end
+
+      def retrieve(assessment)
+        key = Client.path_segment(assessment, "assessment")
+        @client.get("/assessments/#{key}/")
+      end
+
+      def create(fields = nil, **kwargs)
+        body = normalize(fields || kwargs)
+        @client.post("/assessments/create/", body)
+      end
+
+      def update(assessment, fields = nil, **kwargs)
+        body = normalize(fields || kwargs)
+        if body.nil? || body.empty?
+          raise APIError.new("update() requires at least one field to change", "INVALID_ARGUMENT")
+        end
+
+        key = Client.path_segment(assessment, "assessment")
+        @client.patch("/assessments/#{key}/update/", body)
+      end
+
+      def activate(assessment)
+        update(assessment, "status" => "active")
+      end
+
+      def list_cases(assessment, params = nil)
+        key = Client.path_segment(assessment, "assessment")
+        @client.get("/assessments/#{key}/cases/", normalize(params))
+      end
+
+      def attach_cases(assessment, args = nil, **kwargs)
+        body = normalize(args || kwargs)
+        if body.nil? || body.empty?
+          raise APIError.new("attach_cases() requires cases or case_id", "INVALID_ARGUMENT")
+        end
+
+        key = Client.path_segment(assessment, "assessment")
+        @client.post("/assessments/#{key}/cases/attach/", body)
+      end
+
+      def replace_cases(assessment, cases, extra = nil, **kwargs)
+        key = Client.path_segment(assessment, "assessment")
+        body = { "cases" => cases }.merge(normalize(extra || kwargs) || {})
+        @client.put("/assessments/#{key}/cases/replace/", body)
+      end
+
+      def remove_case(assessment, assessment_case_id)
+        key = Client.path_segment(assessment, "assessment")
+        case_id = assessment_case_id.to_s.strip
+        if case_id.empty?
+          raise APIError.new("assessment_case_id must be a non-empty string", "INVALID_ARGUMENT")
+        end
+
+        @client.delete("/assessments/#{key}/cases/remove/", { "assessment_case_id" => case_id })
+      end
+
+      private
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/praxicraft/resources/invites.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  module Resources
+    class Invites
+      def initialize(client)
+        @client = client
+      end
+
+      def list(params = nil)
+        @client.get("/invites/", normalize(params))
+      end
+
+      def retrieve(invite_token)
+        token = Client.path_segment(invite_token, "invite_token")
+        @client.get("/invites/#{token}/")
+      end
+
+      def create(assessment, args = nil, **kwargs)
+        body = normalize(args || kwargs) || {}
+        email = body["email"]
+        if email.nil? || email.to_s.strip.empty?
+          raise APIError.new("email is required", "INVALID_ARGUMENT")
+        end
+
+        key = Client.path_segment(assessment, "assessment")
+        @client.post("/assessments/#{key}/invites/", body)
+      end
+
+      def bulk_create(assessment, candidates, args = nil, **kwargs)
+        key = Client.path_segment(assessment, "assessment")
+        body = { "candidates" => candidates }.merge(normalize(args || kwargs) || {})
+        @client.post("/assessments/#{key}/invites/bulk/", body)
+      end
+
+      def remind(invite_token)
+        token = Client.path_segment(invite_token, "invite_token")
+        @client.post("/invites/#{token}/remind/")
+      end
+
+      def cancel(invite_token)
+        token = Client.path_segment(invite_token, "invite_token")
+        @client.delete("/invites/#{token}/")
+      end
+
+      private
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/praxicraft/resources/org.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  module Resources
+    class Org
+      def initialize(client)
+        @client = client
+      end
+
+      def retrieve
+        @client.get("/org/")
+      end
+
+      def stats(params = nil)
+        @client.get("/org/stats/", normalize(params))
+      end
+
+      private
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/praxicraft/resources/pipelines.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  module Resources
+    class Pipelines
+      def initialize(client)
+        @client = client
+      end
+
+      def list(params = nil)
+        @client.get("/pipelines/", normalize(params))
+      end
+
+      def retrieve(pipeline)
+        key = Client.path_segment(pipeline, "pipeline")
+        @client.get("/pipelines/#{key}/")
+      end
+
+      def enroll(pipeline, args = nil, **kwargs)
+        body = normalize(args || kwargs) || {}
+        email = body["email"]
+        if email.nil? || email.to_s.strip.empty?
+          raise APIError.new("email is required", "INVALID_ARGUMENT")
+        end
+
+        key = Client.path_segment(pipeline, "pipeline")
+        @client.post("/pipelines/#{key}/enroll/", body)
+      end
+
+      def bulk_enroll(pipeline, candidates, args = nil, **kwargs)
+        key = Client.path_segment(pipeline, "pipeline")
+        body = { "candidates" => candidates }.merge(normalize(args || kwargs) || {})
+        @client.post("/pipelines/#{key}/enroll/bulk/", body)
+      end
+
+      def list_enrollments(pipeline, params = nil)
+        key = Client.path_segment(pipeline, "pipeline")
+        @client.get("/pipelines/#{key}/enrollments/", normalize(params))
+      end
+
+      def get_enrollment(enrollment_id)
+        key = Client.path_segment(enrollment_id, "enrollment_id")
+        @client.get("/pipelines/enrollments/#{key}/")
+      end
+
+      private
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/praxicraft/resources/results.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Praxicraft
+  module Resources
+    class Results
+      MAX_RESULT_PAGES = 10_000
+
+      def initialize(client)
+        @client = client
+      end
+
+      # kwargs / hash: cursor, page_size, params
+      def list(assessment, args = nil, **kwargs)
+        opts = symbolize(args || kwargs)
+        query = normalize(opts[:params] || {}) || {}
+        query["cursor"] = opts[:cursor] if opts.key?(:cursor)
+        query["page_size"] = opts[:page_size] if opts.key?(:page_size)
+
+        key = Client.path_segment(assessment, "assessment")
+        @client.get("/assessments/#{key}/results/", query)
+      end
+
+      def retrieve(invite_token)
+        token = Client.path_segment(invite_token, "invite_token")
+        @client.get("/invites/#{token}/result/")
+      end
+
+      def iter_all(assessment, args = nil, **kwargs, &block)
+        opts = symbolize(args || kwargs)
+        return enum_for(:iter_all, assessment, opts) unless block_given?
+
+        cursor = nil
+        seen = {}
+
+        MAX_RESULT_PAGES.times do
+          page_args = opts.dup
+          page_args[:cursor] = cursor unless cursor.nil?
+          page = list(assessment, page_args)
+          return unless page.is_a?(Hash)
+
+          results = page["results"] || page[:results]
+          results.each(&block) if results.is_a?(Array)
+
+          nxt = next_cursor(page)
+          return if nxt.nil? || seen[nxt]
+
+          seen[nxt] = true
+          cursor = nxt
+        end
+      end
+
+      private
+
+      def symbolize(hash)
+        return {} if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+
+      def next_cursor(page)
+        nc = page["next_cursor"] || page[:next_cursor]
+        return nc if nc.is_a?(String) && !nc.empty?
+
+        next_link = page["next"] || page[:next]
+        return nil unless next_link.is_a?(String) && !next_link.empty?
+
+        uri = URI.parse(next_link)
+        return nil if uri.query.nil?
+
+        q = URI.decode_www_form(uri.query).to_h
+        c = q["cursor"]
+        c.is_a?(String) && !c.empty? ? c : nil
+      rescue URI::InvalidURIError
+        nil
+      end
+    end
+  end
+end

data/lib/praxicraft/resources/webhooks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Praxicraft
+  module Resources
+    class Webhooks
+      def initialize(client)
+        @client = client
+      end
+
+      def list(params = nil)
+        @client.get("/webhooks/", normalize(params))
+      end
+
+      def create(args = nil, **kwargs)
+        body = normalize(args || kwargs) || {}
+        url = body["url"]
+        events = body["events"]
+        if url.nil? || url.to_s.strip.empty?
+          raise APIError.new("url is required", "INVALID_ARGUMENT")
+        end
+        if !events.is_a?(Array) || events.empty?
+          raise APIError.new("events must be a non-empty list", "INVALID_ARGUMENT")
+        end
+
+        @client.post("/webhooks/create/", body)
+      end
+
+      def retrieve(webhook_id)
+        key = Client.path_segment(webhook_id, "webhook_id")
+        @client.get("/webhooks/#{key}/")
+      end
+
+      def update(webhook_id, fields = nil, **kwargs)
+        body = normalize(fields || kwargs)
+        if body.nil? || body.empty?
+          raise APIError.new("update() requires at least one field to change", "INVALID_ARGUMENT")
+        end
+
+        key = Client.path_segment(webhook_id, "webhook_id")
+        @client.patch("/webhooks/#{key}/", body)
+      end
+
+      def delete(webhook_id)
+        key = Client.path_segment(webhook_id, "webhook_id")
+        @client.delete("/webhooks/#{key}/")
+      end
+
+      def deliveries(webhook_id)
+        key = Client.path_segment(webhook_id, "webhook_id")
+        @client.get("/webhooks/#{key}/deliveries/")
+      end
+
+      def test(webhook_id)
+        key = Client.path_segment(webhook_id, "webhook_id")
+        @client.post("/webhooks/#{key}/test/")
+      end
+
+      private
+
+      def normalize(hash)
+        return nil if hash.nil?
+
+        hash.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+      end
+    end
+  end
+end

data/lib/praxicraft/version.rb

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

data/lib/praxicraft/webhooks.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Praxicraft
+  module Webhooks
+    module_function
+
+    # Verify an X-Praxicraft-Signature header (sha256=<hex> or legacy bare hex).
+    # +body+ may be nil (treated as empty payload).
+    def verify_signature(secret, body, header_sig)
+      return false if secret.nil? || secret.empty? || header_sig.nil? || header_sig.empty?
+
+      payload = body.nil? ? "" : body.to_s
+      digest = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+      expected = "sha256=#{digest}"
+
+      if header_sig.start_with?("sha256=")
+        secure_compare(expected, header_sig)
+      else
+        secure_compare(digest, header_sig) || secure_compare(expected, header_sig)
+      end
+    end
+
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      OpenSSL.fixed_length_secure_compare(a, b)
+    rescue StandardError
+      false
+    end
+    private_class_method :secure_compare
+  end
+end

data/lib/praxicraft.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative "praxicraft/version"
+require_relative "praxicraft/errors"
+require_relative "praxicraft/webhooks"
+require_relative "praxicraft/resources/org"
+require_relative "praxicraft/resources/assessments"
+require_relative "praxicraft/resources/invites"
+require_relative "praxicraft/resources/results"
+require_relative "praxicraft/resources/webhooks"
+require_relative "praxicraft/resources/pipelines"
+require_relative "praxicraft/client"
+
+module Praxicraft
+end

metadata

@@ -0,0 +1,88 @@
+--- !ruby/object:Gem::Specification
+name: praxicraft
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- PraxiCraft
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Official Ruby client for the Praxicraft Assess Public API.
+email:
+- support@praxicraft.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/praxicraft.rb
+- lib/praxicraft/client.rb
+- lib/praxicraft/errors.rb
+- lib/praxicraft/resources/assessments.rb
+- lib/praxicraft/resources/invites.rb
+- lib/praxicraft/resources/org.rb
+- lib/praxicraft/resources/pipelines.rb
+- lib/praxicraft/resources/results.rb
+- lib/praxicraft/resources/webhooks.rb
+- lib/praxicraft/version.rb
+- lib/praxicraft/webhooks.rb
+homepage: https://docs.praxicraft.com/sdks/ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://docs.praxicraft.com/sdks/ruby
+  source_code_uri: https://github.com/praxicraft-platform/praxicraft-ruby
+  changelog_uri: https://github.com/praxicraft-platform/praxicraft-ruby/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.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: Official Ruby SDK for the Praxicraft Assess Public API
+test_files: []