signingstudio 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1cca61538db4db313df61c802371547979134e4884f7862e93921b7b6d26dd7
+  data.tar.gz: ecf355dd098c824253323d377686ffd4a7474f8f9ad5a9799029e9504dd171b8
+SHA512:
+  metadata.gz: dbd5edef52f10caf45ca88379f2ba4b804e47954be9a1ffc5549f4089c7a59410fbd8f5da44630eeaebd32515d88b4718bc806b4acf5cc55a9f3d94f708bf8fb
+  data.tar.gz: 282f51f2d61d5b6ebb0f2fea86085ba32c43ac2b6ab98cb8c83533681280eb86b18af60378c50b069cbadb60142b04eef7a26b79b0e8def650437952ae116b7c

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to `signingstudio` are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] — 2026-07-22
+
+Initial public release. Covers 100% of the Signing Studio v1 REST API.
+
+### Added
+- `Signingstudio::Client` with `documents` and `templates` resources.
+- `Documents`: list, send, get, delete (soft + hard), restore, archive, unarchive, cancel, progress, download_url, download_pdf, activity, remind.
+- `Templates`: list, create (PDF path / IO / bytes), get, update, delete, pdf_url, download_pdf, replace_pdf, set_fields, duplicate, archive, history, history_pdf_url, download_history_pdf.
+- `Signingstudio::Webhooks::Verifier` — constant-time HMAC-SHA256 verification via `OpenSSL.fixed_length_secure_compare`.
+- Typed exception hierarchy: `Signingstudio::Error` → `ApiError` → `AuthenticationError`, `NotFoundError`, `ValidationError`, `RateLimitError`.
+- Bounded retry policy — 429 (with Retry-After ≤ 60s), 5xx, and network errors retried with exponential backoff + jitter.
+- Faraday-based transport with connection pooling suitable for Sidekiq / Rails / cron workloads.
+- RSpec test suite with WebMock covering the transport layer, resource dispatch, and webhook verifier.
+- GitHub Actions CI on Ruby 3.0 – 3.3; release workflow publishes to RubyGems via OIDC trusted publishing.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Signing Studio
+
+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,200 @@
+# Signing Studio Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/signingstudio.svg)](https://rubygems.org/gems/signingstudio)
+[![CI](https://github.com/alyasdds/signingstudio-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/alyasdds/signingstudio-ruby/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Official Ruby client for the **[Signing Studio](https://signingstudio.com)** e-signature API. Covers every public v1 endpoint — send documents from templates, poll signing progress, manage templates and their fields, and verify webhook deliveries.
+
+Requires **Ruby 3.0+**.
+
+## Install
+
+```bash
+gem install signingstudio
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "signingstudio", "~> 1.0"
+```
+
+## Quick start
+
+```ruby
+require "signingstudio"
+
+client = Signingstudio::Client.new(api_key: ENV.fetch("SIGNING_STUDIO_API_KEY"))
+
+doc = client.documents.send(
+  template_id: "11111111-2222-3333-4444-555555555555",
+  title:       "MSA — Acme",
+  recipients:  [{ name: "Alex Doe", email: "alex@acme.com" }],
+)
+
+puts "Sent #{doc["id"]} (#{doc["status"]})"
+```
+
+Get your API key from **Signing Studio → Settings → API Keys**. The plaintext key is shown once at creation — store it in Rails credentials, Vault, or an environment variable.
+
+## Configuration
+
+```ruby
+client = Signingstudio::Client.new(
+  api_key: "sk_live_...",
+  base_url: "https://api.signingstudio.com",   # default
+  max_retries: 3,                              # 429 + 5xx + network
+  request_timeout: 120,                        # seconds
+  user_agent: "my-app/1.4",
+)
+```
+
+**Retry policy** — conservative and predictable:
+- **429** with `Retry-After ≤ 60s` → sleep and retry, up to `max_retries`.
+- **429** with `Retry-After > 60s` (typically monthly quota) → raise `RateLimitError` immediately.
+- **5xx** and **network errors** → exponential backoff (500ms · 1s · 2s · 4s) with jitter.
+
+## Documents
+
+```ruby
+listing = client.documents.list(status: "sent", view: "active", limit: 50)
+
+doc = client.documents.send(
+  template_id: template_id,
+  title: "MSA — Acme",
+  subject: "Please sign",
+  message: "Signing at your convenience",
+  expires_at: "2026-08-01T00:00:00Z",
+  recipients: [
+    { name: "Alex", email: "alex@acme.com", signing_order: 0 },
+    { name: "Bo",   email: "bo@acme.com",   signing_order: 1 },
+  ],
+  prefill_values: [{ field_name: "company", value: "Acme Inc." }],
+)
+
+client.documents.get(doc["id"])
+client.documents.progress(doc["id"])   # cheap; ideal for polling
+client.documents.activity(doc["id"])
+
+client.documents.cancel(doc["id"])
+client.documents.archive(doc["id"])
+client.documents.unarchive(doc["id"])
+client.documents.restore(doc["id"])
+client.documents.delete(doc["id"])                # soft
+client.documents.delete(doc["id"], hard: true)    # hard purge
+
+remind = client.documents.remind(doc["id"], recipient_id)
+fresh_url = remind["signing_url"]
+
+url = client.documents.download_url(doc["id"])["url"]
+bytes = client.documents.download_pdf(doc["id"])
+```
+
+## Templates
+
+```ruby
+templates = client.templates.list
+
+template = client.templates.create(
+  "./msa.pdf",
+  {
+    name: "MSA v2",
+    signer_count: 1,
+    delivery_methods: ["email"],
+    signers: [{ role: "Customer", delivery: ["email"] }],
+  },
+)
+
+client.templates.update(template["id"], name: "MSA v3")
+client.templates.delete(template["id"])
+
+client.templates.replace_pdf(template["id"], "./msa-updated.pdf")
+versions = client.templates.history(template["id"])
+old_pdf_url = client.templates.history_pdf_url(template["id"], versions[0]["id"])["url"]
+
+client.templates.set_fields(template["id"], [
+  { field_type: "signature", page: 1, x: 60, y: 82, width: 30, height: 6, signer_index: 0, required: true },
+  { field_type: "text",      page: 1, x: 10, y: 20, width: 30, height: 4, signer_index: 0, name: "company", label: "Company name", required: true },
+])
+```
+
+### PDF upload constraints
+
+- Max **50 MB** per file.
+- `application/pdf` only.
+- Multipart field name must be `file` — the SDK sets this for you.
+
+## Webhooks
+
+```ruby
+require "sinatra"
+require "json"
+require "signingstudio"
+
+SECRET = ENV.fetch("SIGNING_STUDIO_WEBHOOK_SECRET")
+verifier = Signingstudio::Client.webhook_verifier(SECRET)
+
+post "/webhooks/signing-studio" do
+  raw = request.body.read     # RAW body — do NOT re-serialize
+  sig = request.env["HTTP_X_DDS_SIGNATURE"] || ""
+  halt 401 unless verifier.valid?(raw, sig)
+
+  payload = JSON.parse(raw)
+  # payload["event"] is one of:
+  #   "document.sent" | "document.viewed" | "document.signed"
+  #   | "document.declined" | "document.completed"
+  content_type :json
+  { received: true }.to_json
+end
+```
+
+**Always sign the RAW body**, not a parsed-and-re-serialized body.
+
+## Errors
+
+```ruby
+begin
+  client.documents.send(payload)
+rescue Signingstudio::ValidationError => e
+  # e.errors is Hash{String => Array<String>}
+rescue Signingstudio::RateLimitError => e
+  # e.window is "minute" | "day" | nil
+  # e.retry_after is Integer | nil
+rescue Signingstudio::AuthenticationError
+  # Refresh the API key.
+rescue Signingstudio::NotFoundError
+  # Doesn't exist on this tenant.
+rescue Signingstudio::ApiError => e
+  Rails.logger.error("signingstudio request=#{e.request_id} status=#{e.status_code}")
+end
+```
+
+All SDK-raised exceptions inherit from `Signingstudio::Error`.
+
+## Rate limits
+
+Every response carries:
+
+- `X-RateLimit-Limit-Minute`, `X-RateLimit-Remaining-Minute`
+- `X-RateLimit-Limit-Day`, `X-RateLimit-Remaining-Day`
+
+Platform defaults: **120 req/min** and **20,000 req/day** per API key.
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+CI runs against Ruby 3.0 – 3.3 on every push/PR.
+
+## Versioning
+
+Semantic versioning. `CHANGELOG.md` records every release.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/signingstudio/client.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "signingstudio/configuration"
+require "signingstudio/http_client"
+require "signingstudio/resources/documents"
+require "signingstudio/resources/templates"
+require "signingstudio/webhooks/verifier"
+
+module Signingstudio
+  # Top-level entry point.
+  #
+  #   client = Signingstudio::Client.new(api_key: ENV["SIGNING_STUDIO_API_KEY"])
+  #   doc = client.documents.send(
+  #     template_id: "11111111-2222-3333-4444-555555555555",
+  #     title:       "MSA — Acme",
+  #     recipients:  [{ name: "Alex", email: "alex@acme.com" }],
+  #   )
+  #
+  # Client instances are thread-safe — Faraday keeps a per-host connection
+  # pool internally, so a single instance is the recommended shape for
+  # Sidekiq workers, Rails apps, and cron scripts.
+  class Client
+    attr_reader :documents, :templates, :http
+
+    def initialize(api_key: nil, config: nil, **opts)
+      resolved = config || Configuration.new(api_key: api_key, **opts)
+      @http      = HttpClient.new(resolved)
+      @documents = Resources::Documents.new(@http)
+      @templates = Resources::Templates.new(@http)
+    end
+
+    # Build a webhook verifier. Stand-alone rather than a method on Client
+    # so receivers can construct it without also building an API client.
+    def self.webhook_verifier(secret)
+      Webhooks::Verifier.new(secret)
+    end
+  end
+end

data/lib/signingstudio/configuration.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Signingstudio
+  # Immutable configuration for a Client. Build with keyword args or
+  # populate individual attributes on a fresh instance.
+  class Configuration
+    DEFAULT_BASE_URL        = "https://api.signingstudio.com"
+    DEFAULT_MAX_RETRIES     = 3
+    DEFAULT_REQUEST_TIMEOUT = 120  # seconds
+    DEFAULT_USER_AGENT      = "signingstudio-ruby/1.0"
+
+    attr_reader :api_key, :base_url, :max_retries, :request_timeout, :user_agent
+
+    def initialize(
+      api_key:,
+      base_url: DEFAULT_BASE_URL,
+      max_retries: DEFAULT_MAX_RETRIES,
+      request_timeout: DEFAULT_REQUEST_TIMEOUT,
+      user_agent: DEFAULT_USER_AGENT
+    )
+      raise ArgumentError, "api_key must not be empty" if api_key.nil? || api_key.empty?
+      raise ArgumentError, "max_retries must be non-negative" if max_retries.negative?
+
+      @api_key         = api_key
+      @base_url        = base_url
+      @max_retries     = max_retries
+      @request_timeout = request_timeout
+      @user_agent      = user_agent
+    end
+  end
+end

data/lib/signingstudio/errors.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Signingstudio
+  # Base class for every exception raised by the SDK. Catch this at the
+  # outer boundary of your code and inspect the subclass for specifics.
+  class Error < StandardError; end
+
+  # Non-2xx HTTP response from the API. Specific status codes (401, 404,
+  # 422, 429) are surfaced as dedicated subclasses.
+  class ApiError < Error
+    attr_reader :status_code, :request_id, :body
+
+    def initialize(message, status_code:, request_id: nil, body: nil)
+      super(message)
+      @status_code = status_code
+      @request_id  = request_id
+      @body        = body
+    end
+  end
+
+  # HTTP 401 — API key missing / unknown / account inactive.
+  class AuthenticationError < ApiError; end
+
+  # HTTP 404 — resource doesn't exist under this tenant.
+  class NotFoundError < ApiError; end
+
+  # HTTP 422 — Zod schema or business-rule failure. #errors is the
+  # field-name → messages map from the server.
+  class ValidationError < ApiError
+    attr_reader :errors
+
+    def initialize(message, status_code:, request_id: nil, body: nil, errors: {})
+      super(message, status_code: status_code, request_id: request_id, body: body)
+      @errors = errors || {}
+    end
+  end
+
+  # HTTP 429 — sliding-window rate limit or monthly quota. #retry_after is
+  # populated for sliding-window; nil for quota exhaustion.
+  class RateLimitError < ApiError
+    attr_reader :retry_after, :window
+
+    def initialize(message, status_code:, request_id: nil, body: nil, retry_after: nil, window: nil)
+      super(message, status_code: status_code, request_id: request_id, body: body)
+      @retry_after = retry_after
+      @window      = window
+    end
+  end
+end

data/lib/signingstudio/http_client.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+require "signingstudio/errors"
+
+module Signingstudio
+  # HTTP transport. Wraps Faraday with:
+  #
+  #   - Authorization header injection
+  #   - JSON / multipart body handling
+  #   - Envelope unwrap ({ success, data, meta } → ApiResponse)
+  #   - Status → typed exception mapping
+  #   - Bounded retry on 429 (with Retry-After ≤ 60s), 5xx, and network errors
+  class HttpClient
+    # Result wrapper — data, meta, rate-limit metadata + request id.
+    ApiResponse = Struct.new(:status_code, :data, :meta, :request_id, :rate_limit, keyword_init: true) do
+      def raw_bytes
+        # Populated only for binary requests. #data holds the string body
+        # when the transport is asked for bytes; expose as an alias here for
+        # readability.
+        data
+      end
+    end
+
+    RateLimit = Struct.new(:remaining_minute, :remaining_day, :limit_minute, :limit_day, keyword_init: true)
+
+    def initialize(config)
+      @config = config
+      @faraday = Faraday.new(
+        url: "#{config.base_url.chomp("/")}/api/v1/",
+        request: { timeout: config.request_timeout, open_timeout: 10 },
+      ) do |f|
+        f.request :multipart
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request_json(method, path, query: nil, json: nil, multipart: nil)
+      execute(method, path, query: query, json: json, multipart: multipart, binary: false)
+    end
+
+    def request_binary(method, path, query: nil)
+      execute(method, path, query: query, binary: true)
+    end
+
+    private
+
+    def execute(method, path, query: nil, json: nil, multipart: nil, binary: false)
+      attempt = 0
+      loop do
+        response =
+          begin
+            @faraday.run_request(method, path.sub(%r{^/+}, ""), body_for(json, multipart), headers(binary)) do |req|
+              req.params = normalize_query(query) if query
+            end
+          rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+            raise Error, "Network error contacting Signing Studio: #{e.message}" if attempt >= @config.max_retries
+
+            sleep(backoff_seconds(attempt))
+            attempt += 1
+            next
+          end
+
+        status = response.status
+        return unwrap(response, binary) if status.between?(200, 299)
+
+        if status == 429 && attempt < @config.max_retries
+          retry_after = extract_retry_after(response)
+          if retry_after && retry_after <= 60
+            sleep(retry_after)
+            attempt += 1
+            next
+          end
+        end
+
+        if status >= 500 && attempt < @config.max_retries
+          sleep(backoff_seconds(attempt))
+          attempt += 1
+          next
+        end
+
+        raise build_api_error(response, status)
+      end
+    end
+
+    def body_for(json, multipart)
+      return multipart if multipart
+      return json.to_json if json
+
+      nil
+    end
+
+    def headers(binary)
+      {
+        "Authorization" => "Bearer #{@config.api_key}",
+        "User-Agent"    => @config.user_agent,
+        "Accept"        => binary ? "application/pdf, application/octet-stream, */*" : "application/json",
+        "Content-Type"  => "application/json",
+      }
+    end
+
+    def unwrap(response, binary)
+      request_id = response.headers["x-request-id"]
+      rate_limit = read_rate_limit(response)
+
+      if binary
+        return ApiResponse.new(
+          status_code: response.status,
+          data:        response.body,
+          meta:        {},
+          request_id:  request_id,
+          rate_limit:  rate_limit,
+        )
+      end
+
+      body = response.body
+      envelope = body.nil? || body.empty? ? {} : parse_json(body, response.status)
+      ApiResponse.new(
+        status_code: response.status,
+        data:        envelope["data"],
+        meta:        (envelope["meta"].is_a?(Hash) ? envelope["meta"] : {}),
+        request_id:  request_id,
+        rate_limit:  rate_limit,
+      )
+    end
+
+    def read_rate_limit(response)
+      RateLimit.new(
+        remaining_minute: parse_int(response.headers["x-ratelimit-remaining-minute"]),
+        remaining_day:    parse_int(response.headers["x-ratelimit-remaining-day"]),
+        limit_minute:     parse_int(response.headers["x-ratelimit-limit-minute"]),
+        limit_day:        parse_int(response.headers["x-ratelimit-limit-day"]),
+      )
+    end
+
+    def build_api_error(response, status)
+      body       = safe_parse_json(response.body)
+      message    = body.is_a?(Hash) && body["message"].is_a?(String) ? body["message"] : "Signing Studio API returned HTTP #{status}"
+      request_id = response.headers["x-request-id"] || (body.is_a?(Hash) ? body["requestId"] : nil)
+
+      common = { status_code: status, request_id: request_id, body: body }
+
+      case status
+      when 401
+        AuthenticationError.new(message, **common)
+      when 404
+        NotFoundError.new(message, **common)
+      when 422
+        errors = body.is_a?(Hash) && body["errors"].is_a?(Hash) ? body["errors"] : {}
+        ValidationError.new(message, **common, errors: errors)
+      when 429
+        RateLimitError.new(
+          message,
+          **common,
+          retry_after: extract_retry_after(response),
+          window:      response.headers["x-ratelimit-window"],
+        )
+      else
+        ApiError.new(message, **common)
+      end
+    end
+
+    def parse_json(body, status)
+      JSON.parse(body)
+    rescue JSON::ParserError => e
+      raise Error, "Malformed JSON in server response (HTTP #{status}): #{e.message}"
+    end
+
+    def safe_parse_json(body)
+      JSON.parse(body) unless body.nil? || body.empty?
+    rescue JSON::ParserError
+      nil
+    end
+
+    def parse_int(str)
+      Integer(str)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def extract_retry_after(response)
+      parse_int(response.headers["retry-after"])
+    end
+
+    def normalize_query(query)
+      query.each_with_object({}) do |(k, v), out|
+        next if v.nil?
+
+        out[k.to_s] = case v
+                     when true then "true"
+                     when false then "false"
+                     else v.to_s
+                     end
+      end
+    end
+
+    # Exponential backoff (500ms · 1s · 2s · 4s) plus up to 25% jitter to
+    # avoid herd effects when many callers retry at once.
+    def backoff_seconds(attempt)
+      base = 0.5 * (2**attempt)
+      base + rand * (base / 4.0)
+    end
+  end
+end

data/lib/signingstudio/resources/documents.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Signingstudio
+  module Resources
+    # Documents resource — twelve endpoints under /api/v1/documents.
+    #
+    # Every method returns a plain Ruby Hash matching the shape documented
+    # in the Signing Studio API reference. The SDK does not coerce or
+    # reshape the response.
+    class Documents
+      def initialize(http)
+        @http = http
+      end
+
+      # List documents. All parameters are optional keyword args.
+      #
+      # @param status   [String]   filter by document status (sent/completed/…)
+      # @param view     [String]   'active' (default) | 'archived' | 'deleted' | 'all'
+      # @param limit    [Integer]  page size (server-capped at 200; default 50)
+      # @param offset   [Integer]  zero-based offset
+      #
+      # @return [Hash] { data: [...], meta: { total:, limit:, offset:, view: } }
+      def list(status: nil, view: nil, limit: nil, offset: nil)
+        response = @http.request_json(:get, "documents", query: {
+          status: status, view: view, limit: limit, offset: offset,
+        })
+        { "data" => response.data || [], "meta" => response.meta }
+      end
+
+      # Send a new document from a template.
+      #
+      # Server rules to know about:
+      #   * template_id is required.
+      #   * recipients must have at least one entry.
+      #   * prefill_values need either field_id (uuid) or field_name + value.
+      #   * signature/initials fields cannot be prefilled.
+      #   * required+readonly template fields MUST be prefilled.
+      def send(payload)
+        @http.request_json(:post, "documents", json: payload).data
+      end
+
+      def get(id)
+        @http.request_json(:get, "documents/#{enc(id)}").data
+      end
+
+      # Delete a document. hard: true purges the file from storage. Only
+      # valid on cancelled / completed / declined / expired documents.
+      def delete(id, hard: false)
+        query = hard ? { hard: "true" } : nil
+        @http.request_json(:delete, "documents/#{enc(id)}", query: query).data
+      end
+
+      def restore(id)   = @http.request_json(:post, "documents/#{enc(id)}/restore").data
+      def archive(id)   = @http.request_json(:post, "documents/#{enc(id)}/archive").data
+      def unarchive(id) = @http.request_json(:post, "documents/#{enc(id)}/unarchive").data
+      def cancel(id)    = @http.request_json(:post, "documents/#{enc(id)}/cancel").data
+
+      # Read current signing progress — cheaper than #get when polling.
+      def progress(id)
+        @http.request_json(:get, "documents/#{enc(id)}/progress").data
+      end
+
+      # Presigned download URL. Returns { "url" => "..." }. TTL ~1h.
+      def download_url(id)
+        @http.request_json(:get, "documents/#{enc(id)}/download").data
+      end
+
+      # Fetch the PDF as raw bytes (follows the presigned redirect).
+      def download_pdf(id)
+        @http.request_binary(:get, "documents/#{enc(id)}/download", query: { redirect: "1" }).raw_bytes
+      end
+
+      def activity(id)
+        @http.request_json(:get, "documents/#{enc(id)}/activity").data || []
+      end
+
+      # Re-send the signing invite for a specific recipient. Response
+      # includes a freshly-minted signing URL — capture it if you need to
+      # relay it out-of-band; the URL is not stored server-side.
+      def remind(document_id, recipient_id)
+        @http.request_json(:post,
+          "documents/#{enc(document_id)}/recipients/#{enc(recipient_id)}/remind").data
+      end
+
+      private
+
+      def enc(str)
+        CGI.escape(str.to_s)
+      end
+    end
+  end
+end

data/lib/signingstudio/resources/templates.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "faraday/multipart"
+
+module Signingstudio
+  module Resources
+    # Templates resource — twelve endpoints under /api/v1/templates.
+    #
+    # PDF upload constraints (server-enforced, 400 on violation):
+    #   - Max 50 MB per file
+    #   - application/pdf only
+    #   - Multipart form field must be `file` — the SDK sets this for you
+    class Templates
+      def initialize(http)
+        @http = http
+      end
+
+      def list
+        @http.request_json(:get, "templates").data || []
+      end
+
+      # Create a template from a PDF plus metadata.
+      #
+      # @param pdf       [String, Pathname, IO] path or an open IO/StringIO
+      # @param metadata  [Hash]     template metadata (name required; see README)
+      # @param filename  [String]   override the recorded filename
+      def create(pdf, metadata, filename: nil)
+        body = build_multipart(pdf, filename, metadata)
+        @http.request_json(:post, "templates", multipart: body).data
+      end
+
+      def get(id)
+        @http.request_json(:get, "templates/#{enc(id)}").data
+      end
+
+      def update(id, metadata)
+        @http.request_json(:patch, "templates/#{enc(id)}", json: metadata).data
+      end
+
+      # Soft-delete only. Hard-delete is not exposed on v1.
+      def delete(id)
+        @http.request_json(:delete, "templates/#{enc(id)}").data
+      end
+
+      def pdf_url(id)
+        @http.request_json(:get, "templates/#{enc(id)}/pdf").data
+      end
+
+      def download_pdf(id)
+        @http.request_binary(:get, "templates/#{enc(id)}/pdf", query: { redirect: "1" }).raw_bytes
+      end
+
+      # Replace the PDF backing an existing template. Prior versions stay
+      # accessible via #history and #history_pdf_url.
+      def replace_pdf(id, pdf, filename: nil)
+        body = build_multipart(pdf, filename, nil)
+        @http.request_json(:put, "templates/#{enc(id)}/pdf", multipart: body).data
+      end
+
+      # Full-replace of every field on the template. The server deletes
+      # existing rows and inserts the supplied set; partial updates are
+      # not supported.
+      def set_fields(id, fields)
+        @http.request_json(:put, "templates/#{enc(id)}/fields", json: { fields: fields }).data || []
+      end
+
+      def duplicate(id) = @http.request_json(:post, "templates/#{enc(id)}/duplicate").data
+      def archive(id)   = @http.request_json(:post, "templates/#{enc(id)}/archive").data
+
+      def history(id)
+        @http.request_json(:get, "templates/#{enc(id)}/history").data || []
+      end
+
+      def history_pdf_url(template_id, history_id)
+        @http.request_json(:get, "templates/#{enc(template_id)}/history/#{history_id}/pdf").data
+      end
+
+      def download_history_pdf(template_id, history_id)
+        @http.request_binary(:get,
+          "templates/#{enc(template_id)}/history/#{history_id}/pdf",
+          query: { redirect: "1" }).raw_bytes
+      end
+
+      private
+
+      # Build the multipart hash Faraday expects. Nested arrays/objects go
+      # through JSON.generate so complex fields like `signers` and
+      # `delivery_methods` survive the form-data trip.
+      def build_multipart(pdf, filename, metadata)
+        parts = {}
+        (metadata || {}).each do |key, value|
+          next if value.nil?
+
+          parts[key] = case value
+                      when String, Numeric then value.to_s
+                      when TrueClass then "true"
+                      when FalseClass then "false"
+                      else JSON.generate(value)
+                      end
+        end
+
+        io, resolved_name = resolve_pdf(pdf, filename)
+        parts["file"] = Faraday::Multipart::FilePart.new(io, "application/pdf", resolved_name)
+        parts
+      end
+
+      def resolve_pdf(pdf, override)
+        case pdf
+        when String
+          if File.file?(pdf)
+            [File.open(pdf, "rb"), override || File.basename(pdf)]
+          else
+            # Treat as raw bytes.
+            [StringIO.new(pdf), override || "template.pdf"]
+          end
+        when Pathname
+          [File.open(pdf.to_s, "rb"), override || File.basename(pdf.to_s)]
+        else
+          # Any object that responds to :read — File, StringIO, Tempfile.
+          name = override || (pdf.respond_to?(:path) && pdf.path ? File.basename(pdf.path) : "template.pdf")
+          [pdf, name]
+        end
+      end
+
+      def enc(str)
+        CGI.escape(str.to_s)
+      end
+    end
+  end
+end

data/lib/signingstudio/version.rb

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

data/lib/signingstudio/webhooks/verifier.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Signingstudio
+  module Webhooks
+    # Verify incoming Signing Studio webhook deliveries.
+    #
+    # The server signs the raw JSON body with HMAC-SHA256 keyed on the
+    # webhook's secret and sends it as `X-DDS-Signature: sha256=<hex>`.
+    #
+    # ALWAYS pass the RAW body — a parsed & re-serialized body will fail
+    # verification, even if it looks identical.
+    class Verifier
+      def initialize(secret)
+        raise ArgumentError, "webhook secret must not be empty" if secret.nil? || secret.empty?
+
+        @secret = secret
+      end
+
+      def valid?(raw_body, header)
+        return false if header.nil? || header.empty?
+
+        received = header.start_with?("sha256=") ? header[7..] : header
+        # Hex is length-fixed; fast-fail rejects payloads mangled in transit
+        # before we spend cycles on the HMAC.
+        return false unless received.length == 64 && received.match?(/\A[0-9a-fA-F]+\z/)
+
+        expected = OpenSSL::HMAC.hexdigest("SHA256", @secret, raw_body)
+        secure_compare(expected, received.downcase)
+      end
+
+      private
+
+      # Constant-time string comparison. Falls back to a manual XOR loop
+      # so ancient Ruby installs without OpenSSL#fixed_length_secure_compare
+      # still get timing safety.
+      def secure_compare(a, b)
+        return false unless a.bytesize == b.bytesize
+
+        if OpenSSL.respond_to?(:fixed_length_secure_compare)
+          return OpenSSL.fixed_length_secure_compare(a, b)
+        end
+
+        result = 0
+        a.bytes.zip(b.bytes) { |x, y| result |= (x ^ y) }
+        result.zero?
+      end
+    end
+  end
+end

data/lib/signingstudio.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "signingstudio/version"
+require "signingstudio/errors"
+require "signingstudio/client"
+
+module Signingstudio
+end

data/signingstudio.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/signingstudio/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "signingstudio"
+  spec.version       = Signingstudio::VERSION
+  spec.authors       = ["Signing Studio"]
+  spec.email         = ["contact@signingstudio.com"]
+
+  spec.summary       = "Official Ruby SDK for the Signing Studio e-signature API."
+  spec.description   = "Full coverage of the v1 REST endpoints — send documents, manage templates, verify webhooks — with typed errors, retry-aware transport, and a small dependency footprint."
+  spec.homepage      = "https://signingstudio.com"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"]      = spec.homepage
+  spec.metadata["source_code_uri"]   = "https://github.com/alyasdds/signingstudio-ruby"
+  spec.metadata["documentation_uri"] = "https://signingstudio.com/docs"
+  spec.metadata["changelog_uri"]     = "https://github.com/alyasdds/signingstudio-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"]   = "https://github.com/alyasdds/signingstudio-ruby/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.glob(%w[lib/**/* LICENSE README.md CHANGELOG.md signingstudio.gemspec])
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", "~> 2.7"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+
+  spec.add_development_dependency "rspec",       "~> 3.13"
+  spec.add_development_dependency "webmock",     "~> 3.23"
+  spec.add_development_dependency "rubocop",     "~> 1.65"
+  spec.add_development_dependency "rake",        "~> 13.2"
+end

metadata

@@ -0,0 +1,148 @@
+--- !ruby/object:Gem::Specification
+name: signingstudio
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Signing Studio
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-multipart
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.65'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: Full coverage of the v1 REST endpoints — send documents, manage templates,
+  verify webhooks — with typed errors, retry-aware transport, and a small dependency
+  footprint.
+email:
+- contact@signingstudio.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/signingstudio.rb
+- lib/signingstudio/client.rb
+- lib/signingstudio/configuration.rb
+- lib/signingstudio/errors.rb
+- lib/signingstudio/http_client.rb
+- lib/signingstudio/resources/documents.rb
+- lib/signingstudio/resources/templates.rb
+- lib/signingstudio/version.rb
+- lib/signingstudio/webhooks/verifier.rb
+- signingstudio.gemspec
+homepage: https://signingstudio.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://signingstudio.com
+  source_code_uri: https://github.com/alyasdds/signingstudio-ruby
+  documentation_uri: https://signingstudio.com/docs
+  changelog_uri: https://github.com/alyasdds/signingstudio-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/alyasdds/signingstudio-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Official Ruby SDK for the Signing Studio e-signature API.
+test_files: []