deckle 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37ae8365d9f1406de529662560d15b7f0057e6f1b080b33db0af181804de9b79
+  data.tar.gz: 736dc2a6e9fa3663061ff55d616b6468f51738ba40f24252cd94c7940726b456
+SHA512:
+  metadata.gz: 2a04633e7f070f025b6b58b9909d65c3811baaf7a497c585cdd691de6028c02e919c3c8157f298ba6c3ca9fd0a89b61617230b11bc6f2904180c702985b9aa7c
+  data.tar.gz: ec3ff7534cac1507b357eb5a9b3391cfe14e3d78ba26f4cfd8877c4b9acdcdf0c5adf1efac7ffdaf1b00a2a34127c39defb787054a330a39d79d6247295abbc9

data/README.md

@@ -0,0 +1,84 @@
+# Deckle Ruby SDK
+
+PDF generation API for developers. HTML in, pixel-perfect PDF out.
+
+## Installation
+
+```bash
+gem install deckle
+```
+
+Or in a `Gemfile`:
+
+```ruby
+gem "deckle"
+```
+
+## Quick start
+
+```ruby
+require "deckle"
+
+client = Deckle::Client.new(api_key: ENV["DECKLE_API_KEY"])
+
+pdf = client.generate(html: "<h1>Hello, Deckle!</h1>")
+puts pdf["url"]
+```
+
+## Templates
+
+```ruby
+template = client.templates.create(
+  name: "Invoice",
+  html_content: "<h1>Invoice #{{number}}</h1><p>{{amount}}</p>"
+)
+
+pdf = client.from_template(
+  template: template["id"],
+  data: { "number" => 42, "amount" => "$500" }
+)
+```
+
+## PDF tools
+
+```ruby
+# AES-256 password protect a PDF (AES via qpdf server-side)
+result = client.pdf_protect(
+  pdf: base64_pdf,
+  user_password: "open-me",
+  permissions: { "print" => "low", "modify" => false }
+)
+
+# Cryptographic PAdES signature
+client.pdf_sign_annotation(
+  pdf: base64_pdf,
+  name: "Jane Doe",
+  signature: { "p12" => base64_p12, "password" => "p12-pass" }
+)
+```
+
+## Error handling
+
+```ruby
+begin
+  client.generate(html: "...")
+rescue Deckle::RateLimitError => e
+  puts "rate limited; retry after #{e.retry_after}s"
+rescue Deckle::AuthenticationError => e
+  puts "bad API key: #{e.message}"
+rescue Deckle::Error => e
+  puts "error #{e.code}: #{e.message}"
+end
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec        # run the test suite (Faraday stubbed via Faraday::Adapter::Test)
+bundle exec rake test    # same, via Rakefile
+```
+
+## License
+
+MIT

data/lib/deckle/client.rb

@@ -0,0 +1,386 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+
+module Deckle
+  class Client
+    attr_reader :templates
+
+    # Status codes that are safe to retry.
+    RETRYABLE_STATUS_CODES = [429, 500, 502, 503, 504].freeze
+
+    # Create a new Deckle client.
+    #
+    # @param api_key [String] Your Deckle API key.
+    # @param base_url [String] API base URL.
+    # @param timeout [Integer] Request timeout in seconds.
+    # @param max_retries [Integer] Maximum number of retries for failed requests (default 3).
+    def initialize(api_key:, base_url: "https://api.getdeckle.dev", timeout: 30, max_retries: 3)
+      raise ArgumentError, "Deckle API key is required" if api_key.nil? || api_key.empty?
+
+      @api_key = api_key
+      @base_url = base_url.chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+
+      @conn = Faraday.new(url: @base_url) do |f|
+        f.options.timeout = @timeout
+        f.options.open_timeout = @timeout
+        f.headers["Authorization"] = "Bearer #{@api_key}"
+        f.headers["Content-Type"] = "application/json"
+        f.headers["User-Agent"] = "deckle-ruby/#{Deckle::VERSION}"
+        f.adapter Faraday.default_adapter
+      end
+
+      @templates = Templates.new(self)
+    end
+
+    # Generate a PDF from raw HTML.
+    #
+    # @param html [String] HTML string to convert to PDF.
+    # @param options [Hash, nil] PDF rendering options (format, margin, orientation, etc.).
+    # @param output [String] Output format - "url" or "base64".
+    # @param webhook [String, nil] URL to POST when generation completes.
+    # @return [Hash] Generation response with id, status, url, etc.
+    def generate(html:, options: nil, output: "url", webhook: nil, watermark: nil)
+      body = { "html" => html, "output" => output }
+      body["options"] = options if options
+      body["webhook"] = webhook if webhook
+      body["watermark"] = watermark if watermark
+
+      request(:post, "/v1/generate", body: body)
+    end
+
+    # Generate a PDF from a saved template with dynamic data.
+    #
+    # @param template [String] Template ID (tmpl_xxx).
+    # @param data [Hash] Data to merge into the template.
+    # @param options [Hash, nil] PDF rendering options.
+    # @param output [String] Output format - "url" or "base64".
+    # @return [Hash] Generation response.
+    def from_template(template:, data:, options: nil, output: "url", webhook: nil)
+      body = { "template" => template, "data" => data, "output" => output }
+      body["options"] = options if options
+      body["webhook"] = webhook if webhook
+
+      request(:post, "/v1/generate", body: body)
+    end
+
+    # Generate a PDF from a React component string.
+    #
+    # @param react [String] JSX/TSX component source with default export.
+    # @param data [Hash, nil] Props to pass to the component.
+    # @param styles [String, nil] CSS styles to inject.
+    # @param options [Hash, nil] PDF rendering options.
+    # @param output [String] Output format - "url" or "base64".
+    # @return [Hash] Generation response.
+    def from_react(react:, data: nil, styles: nil, options: nil, output: "url", webhook: nil)
+      body = { "react" => react, "output" => output }
+      body["data"] = data if data
+      body["styles"] = styles if styles
+      body["options"] = options if options
+      body["webhook"] = webhook if webhook
+
+      request(:post, "/v1/generate", body: body)
+    end
+
+    # Submit a batch of PDF generation jobs for async processing.
+    #
+    # @param items [Array<Hash>] List of generation requests.
+    # @param webhook [String, nil] URL to POST when the batch completes.
+    # @return [Hash] Batch response with batch_id, total, and generation IDs.
+    def batch(items:, webhook: nil)
+      body = { "items" => items }
+      body["webhook"] = webhook if webhook
+
+      request(:post, "/v1/generate/batch", body: body)
+    end
+
+    # Get a generation by ID.
+    #
+    # @param id [String] Generation ID.
+    # @return [Hash] Generation details.
+    def get_generation(id)
+      request(:get, "/v1/generations/#{id}")
+    end
+
+    # List recent generations.
+    #
+    # @param limit [Integer] Maximum number of results (default 50).
+    # @param offset [Integer] Offset for pagination (default 0).
+    # @return [Hash] List response with data array.
+    def list_generations(limit: 50, offset: 0)
+      request(:get, "/v1/generations?limit=#{limit}&offset=#{offset}")
+    end
+
+    # Get usage statistics for the current billing period.
+    #
+    # @return [Hash] Usage statistics.
+    def get_usage
+      request(:get, "/v1/usage")
+    end
+
+    # ── PDF tools ──────────────────────────────────────────────────
+    #
+    # NOTE: `sign_annotation` returns `signature_annotation_added: true`
+    # (not `signed:`) so it's clear that this is a visual annotation,
+    # not a cryptographic signature. `protect` uses real AES-256
+    # encryption via qpdf server-side.
+
+    # Merge multiple base64-encoded PDFs into one. Requires >= 2 inputs.
+    def pdf_merge(pdfs:, output: "url")
+      request(:post, "/v1/pdf/merge", body: { "pdfs" => pdfs, "output" => output })
+    end
+
+    # Split a PDF by page ranges. Pass nil ranges to split every page.
+    def pdf_split(pdf:, ranges: nil, output: "url")
+      body = { "pdf" => pdf, "output" => output }
+      body["ranges"] = ranges if ranges
+      request(:post, "/v1/pdf/split", body: body)
+    end
+
+    # Get metadata about a PDF (page count, title, author, etc.).
+    def pdf_info(pdf:)
+      request(:post, "/v1/pdf/info", body: { "pdf" => pdf })
+    end
+
+    # Fill named form fields in an existing AcroForm PDF.
+    def pdf_fill_form(pdf:, fields:, flatten: false, output: "url")
+      request(:post, "/v1/pdf/forms/fill", body: {
+        "pdf" => pdf,
+        "fields" => fields,
+        "flatten" => flatten,
+        "output" => output
+      })
+    end
+
+    # Add text / checkbox / dropdown form fields to a PDF.
+    def pdf_add_form_fields(pdf:, fields:, output: "url")
+      request(:post, "/v1/pdf/forms/add-fields", body: {
+        "pdf" => pdf,
+        "fields" => fields,
+        "output" => output
+      })
+    end
+
+    # List the form fields on a PDF.
+    def pdf_list_form_fields(pdf:)
+      request(:post, "/v1/pdf/forms/list-fields", body: { "pdf" => pdf })
+    end
+
+    # Convert a PDF to PDF/A-1b archival format.
+    def pdf_to_pdfa(pdf:, title: nil, author: nil, subject: nil, output: "url")
+      body = { "pdf" => pdf, "output" => output }
+      body["title"] = title if title
+      body["author"] = author if author
+      body["subject"] = subject if subject
+      request(:post, "/v1/pdf/pdfa", body: body)
+    end
+
+    # Sign a PDF.
+    #
+    # Without :signature → adds a VISUAL annotation only. Response has
+    # signature_annotation_added=true and cryptographically_signed=false.
+    #
+    # With :signature → also embeds a real PAdES-B-B cryptographic
+    # signature. :signature must be a hash with:
+    #   :p12      base64-encoded PKCS#12 (P12/PFX) blob, max 100 KB decoded
+    #   :password P12 passphrase ("" for unprotected P12s)
+    # The P12 is sent over TLS and used ephemerally — never persisted.
+    def pdf_sign_annotation(pdf:, name:, reason: nil, location: nil, contact: nil,
+                            page: nil, x: nil, y: nil, width: nil, height: nil,
+                            output: "url", signature: nil)
+      body = { "pdf" => pdf, "name" => name, "output" => output }
+      body["reason"]    = reason    unless reason.nil?
+      body["location"]  = location  unless location.nil?
+      body["contact"]   = contact   unless contact.nil?
+      body["page"]      = page      unless page.nil?
+      body["x"]         = x         unless x.nil?
+      body["y"]         = y         unless y.nil?
+      body["width"]     = width     unless width.nil?
+      body["height"]    = height    unless height.nil?
+      body["signature"] = signature unless signature.nil?
+      request(:post, "/v1/pdf/sign", body: body)
+    end
+
+    # AES-256 encrypt a PDF. At least one of user_password / owner_password
+    # must be set. If only one is supplied the other is mirrored on the
+    # server so an empty owner password cannot be used to strip restrictions.
+    #
+    # permissions: hash with optional keys :print ("none" | "low" | "full"),
+    # :modify (bool), :copy (bool), :annotate (bool).
+    def pdf_protect(pdf:, user_password: nil, owner_password: nil,
+                    permissions: nil, output: "url")
+      if user_password.nil? && owner_password.nil?
+        raise ArgumentError, "user_password or owner_password is required"
+      end
+      body = { "pdf" => pdf, "output" => output }
+      body["user_password"]  = user_password  unless user_password.nil?
+      body["owner_password"] = owner_password unless owner_password.nil?
+      body["permissions"]    = permissions    unless permissions.nil?
+      request(:post, "/v1/pdf/protect", body: body)
+    end
+
+    # ── Marketplace ────────────────────────────────────────────────
+
+    def marketplace_list
+      request(:get, "/v1/marketplace")
+    end
+
+    def marketplace_get(id)
+      request(:get, "/v1/marketplace/#{id}")
+    end
+
+    def marketplace_clone(id)
+      request(:post, "/v1/marketplace/#{id}/clone")
+    end
+
+    def marketplace_publish(id)
+      request(:post, "/v1/marketplace/#{id}/publish")
+    end
+
+    def marketplace_unpublish(id)
+      request(:post, "/v1/marketplace/#{id}/unpublish")
+    end
+
+    # Report a public marketplace template for moderator review.
+    #
+    # reason: one of "spam", "malicious", "copyright", "inappropriate",
+    # "other". notes: optional, max 1000 chars.
+    #
+    # Returns { "report_id" => ..., "auto_actioned" => bool }.
+    # auto_actioned is true when this report tripped the auto-hide
+    # threshold (3 independent reports). Re-reporting the same template
+    # from the same user yields a 409 (Deckle::Error).
+    def marketplace_report(id, reason:, notes: nil)
+      body = { "reason" => reason }
+      body["notes"] = notes unless notes.nil?
+      request(:post, "/v1/marketplace/#{id}/report", body: body)
+    end
+
+    # ── Starter templates ──────────────────────────────────────────
+
+    def starter_templates_list
+      request(:get, "/v1/starter-templates")
+    end
+
+    def starter_templates_get(slug)
+      request(:get, "/v1/starter-templates/#{slug}")
+    end
+
+    def starter_templates_clone(slug)
+      request(:post, "/v1/starter-templates/#{slug}/clone")
+    end
+
+    # ── Template versions ─────────────────────────────────────────
+
+    def list_template_versions(template_id)
+      request(:get, "/v1/templates/#{template_id}/versions")
+    end
+
+    def get_template_version(template_id, version_id)
+      request(:get, "/v1/templates/#{template_id}/versions/#{version_id}")
+    end
+
+    def restore_template_version(template_id, version_id)
+      request(:post, "/v1/templates/#{template_id}/restore",
+              body: { "version_id" => version_id })
+    end
+
+    # ── AI ────────────────────────────────────────────────────────
+
+    # Generate a template from a natural-language prompt. The HTML
+    # returned has been server-sanitized so it's safe to render.
+    # Requires the server to be configured with ANTHROPIC_API_KEY.
+    def generate_template_from_prompt(prompt:, variables: nil,
+                                      template_type: "other", style: "professional")
+      body = { "prompt" => prompt, "type" => template_type, "style" => style }
+      body["variables"] = variables if variables
+      request(:post, "/v1/ai/generate-template", body: body)
+    end
+
+    # Make an HTTP request and handle errors. Retries on 429/5xx with
+    # exponential backoff.
+    #
+    # NOTE: this method is intentionally public so that Templates (a
+    # separate class) can call `@client.request(...)`. Ruby's `protected`
+    # keyword forbids cross-class invocations, which previously caused
+    # every `templates.*` call to raise NoMethodError.
+    #
+    # @param method [Symbol] HTTP method (:get, :post, :put, :delete).
+    # @param path [String] API path.
+    # @param body [Hash, nil] Request body.
+    # @return [Hash] Parsed JSON response.
+    def request(method, path, body: nil)
+      last_exception = nil
+
+      (@max_retries + 1).times do |attempt|
+        begin
+          response = @conn.run_request(method, path, body ? JSON.generate(body) : nil, nil)
+        rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+          last_exception = e
+          if attempt < @max_retries
+            sleep(2**attempt)
+            next
+          end
+          raise
+        end
+
+        begin
+          data = JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise Error.new(
+            "Non-JSON response from API (status #{response.status})",
+            status_code: response.status,
+            code: "INVALID_RESPONSE"
+          )
+        end
+
+        # Retry on retryable status codes unless exhausted
+        if RETRYABLE_STATUS_CODES.include?(response.status) && attempt < @max_retries
+          delay = if response.status == 429
+                    (response.headers["Retry-After"] || (2**attempt).to_s).to_f
+                  else
+                    2**attempt
+                  end
+          sleep(delay)
+          next
+        end
+
+        if response.status == 401
+          raise AuthenticationError, data.dig("error", "message") || "Unauthorized"
+        end
+
+        if response.status == 403
+          raise UsageLimitError, data.dig("error", "message") || "Forbidden"
+        end
+
+        if response.status == 404
+          raise NotFoundError, data.dig("error", "message") || "Not found"
+        end
+
+        if response.status == 429
+          retry_after = (response.headers["Retry-After"] || "1").to_i
+          raise RateLimitError.new(
+            data.dig("error", "message") || "Rate limit exceeded",
+            retry_after: retry_after
+          )
+        end
+
+        unless response.success?
+          error = data["error"] || {}
+          raise Error.new(
+            error["message"] || "Request failed",
+            status_code: response.status,
+            code: error["code"] || "UNKNOWN"
+          )
+        end
+
+        return data
+      end
+
+      raise last_exception
+    end
+  end
+end

data/lib/deckle/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Deckle
+  class Error < StandardError
+    attr_reader :status_code, :code, :message
+
+    def initialize(message = "Request failed", status_code: 0, code: "UNKNOWN")
+      @message = message
+      @status_code = status_code
+      @code = code
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error
+    def initialize(message = "Invalid API key")
+      super(message, status_code: 401, code: "UNAUTHORIZED")
+    end
+  end
+
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = "Rate limit exceeded", retry_after: 1)
+      @retry_after = retry_after
+      super(message, status_code: 429, code: "RATE_LIMITED")
+    end
+  end
+
+  class ValidationError < Error
+    def initialize(message = "Validation failed")
+      super(message, status_code: 400, code: "VALIDATION_ERROR")
+    end
+  end
+
+  class NotFoundError < Error
+    def initialize(message = "Not found")
+      super(message, status_code: 404, code: "NOT_FOUND")
+    end
+  end
+
+  class UsageLimitError < Error
+    def initialize(message = "Usage limit exceeded")
+      super(message, status_code: 403, code: "USAGE_LIMIT")
+    end
+  end
+end

data/lib/deckle/templates.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Deckle
+  class Templates
+    def initialize(client)
+      @client = client
+    end
+
+    # Create a new template.
+    #
+    # @param name [String] Template name.
+    # @param html_content [String] HTML content of the template.
+    # @param schema [Hash, nil] JSON schema for template data validation.
+    # @param is_public [Boolean] Whether the template is publicly accessible.
+    # @return [Hash] Created template.
+    def create(name:, html_content:, schema: nil, is_public: false)
+      body = { "name" => name, "html_content" => html_content, "is_public" => is_public }
+      body["schema"] = schema if schema
+
+      @client.request(:post, "/v1/templates", body: body)
+    end
+
+    # List all templates.
+    #
+    # @return [Hash] List response with data array.
+    def list
+      @client.request(:get, "/v1/templates")
+    end
+
+    # Get a template by ID.
+    #
+    # @param id [String] Template ID.
+    # @return [Hash] Template details.
+    def get(id)
+      @client.request(:get, "/v1/templates/#{id}")
+    end
+
+    # Update a template.
+    #
+    # @param id [String] Template ID.
+    # @param name [String, nil] New template name.
+    # @param html_content [String, nil] New HTML content.
+    # @param schema [Hash, nil] New JSON schema.
+    # @param is_public [Boolean, nil] New public visibility setting.
+    # @return [Hash] Updated template.
+    def update(id, name: nil, html_content: nil, schema: nil, is_public: nil)
+      body = {}
+      body["name"] = name unless name.nil?
+      body["html_content"] = html_content unless html_content.nil?
+      body["schema"] = schema unless schema.nil?
+      body["is_public"] = is_public unless is_public.nil?
+
+      @client.request(:put, "/v1/templates/#{id}", body: body)
+    end
+
+    # Delete a template.
+    #
+    # @param id [String] Template ID.
+    # @return [Hash] Deletion confirmation.
+    def delete(id)
+      @client.request(:delete, "/v1/templates/#{id}")
+    end
+  end
+end

data/lib/deckle/version.rb

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

data/lib/deckle.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require_relative "deckle/version"
+require_relative "deckle/errors"
+require_relative "deckle/templates"
+require_relative "deckle/client"

data/spec/deckle/client_spec.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+# Deckle Ruby SDK — request shape, error mapping, and namespace
+# coverage. Mirrors packages/sdk-typescript/src/client.test.ts.
+#
+# Faraday::Adapter::Test intercepts every request so no real network
+# is touched.
+
+require "spec_helper"
+
+RSpec.describe Deckle::Client do
+  include DeckleSpecHelpers
+
+  let(:usage_payload) do
+    {
+      "period_start" => "2026-01-01",
+      "period_end"   => "2026-01-31",
+      "generation_count" => 0,
+      "total_pages" => 0,
+      "total_bytes" => 0,
+      "plan" => "free",
+      "limit" => 1000
+    }
+  end
+
+  describe "constructor" do
+    it "refuses an empty api_key" do
+      expect { Deckle::Client.new(api_key: "") }.to raise_error(ArgumentError, /required/)
+    end
+
+    it "refuses a nil api_key" do
+      expect { Deckle::Client.new(api_key: nil) }.to raise_error(ArgumentError, /required/)
+    end
+
+    it "strips trailing slash from base_url" do
+      # We can't read @base_url directly, but the stripped form is
+      # used in @conn — exercising one call confirms the URL is right.
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/usage") { |_env| [200, {}, JSON.generate(usage_payload)] }
+      end
+      # Pass the slash through the real constructor; build_client
+      # rebuilds @conn but we set base_url on the client constructor
+      # so the chomp logic is exercised before our rebuild.
+      client = Deckle::Client.new(
+        api_key: "k", base_url: "#{DeckleSpecHelpers::BASE_URL}/", max_retries: 0
+      )
+      # Replace its conn with the stub adapter.
+      conn = Faraday.new(url: DeckleSpecHelpers::BASE_URL) do |f|
+        f.headers["Authorization"] = "Bearer k"
+        f.adapter(:test, stubs)
+      end
+      client.instance_variable_set(:@conn, conn)
+      expect { client.get_usage }.not_to raise_error
+      stubs.verify_stubbed_calls
+    end
+  end
+
+  describe "request shape" do
+    it "sends Bearer auth and JSON Content-Type on POST" do
+      captured = {}
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/generate") do |env|
+          captured[:auth] = env.request_headers["Authorization"]
+          captured[:content_type] = env.request_headers["Content-Type"]
+          captured[:body] = env.body
+          [200, {}, JSON.generate({ "id" => "gen_1", "status" => "completed", "url" => "x",
+                                    "pages" => 1, "file_size" => 1, "generation_time_ms" => 1 })]
+        end
+      end
+      build_client(stubs).generate(html: "<h1>hi</h1>")
+      expect(captured[:auth]).to eq("Bearer dk_live_test")
+      expect(captured[:content_type]).to eq("application/json")
+      expect(JSON.parse(captured[:body])).to include("html" => "<h1>hi</h1>")
+      stubs.verify_stubbed_calls
+    end
+
+    it "uses the right path for get_generation" do
+      called = false
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/generations/gen_42") do
+          called = true
+          [200, {}, JSON.generate({ "id" => "gen_42", "status" => "completed" })]
+        end
+      end
+      build_client(stubs).get_generation("gen_42")
+      expect(called).to be(true)
+    end
+
+    it "propagates limit and offset on list_generations" do
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/generations") do |env|
+          expect(env.url.query).to include("limit=10").and include("offset=20")
+          [200, {}, JSON.generate({ "data" => [], "has_more" => false })]
+        end
+      end
+      build_client(stubs).list_generations(limit: 10, offset: 20)
+      stubs.verify_stubbed_calls
+    end
+  end
+
+  describe "error handling" do
+    it "raises AuthenticationError on 401" do
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/usage") do
+          [401, {}, JSON.generate({ "error" => { "code" => "UNAUTHORIZED", "message" => "no" } })]
+        end
+      end
+      expect { build_client(stubs).get_usage }.to raise_error(Deckle::AuthenticationError)
+    end
+
+    it "raises RateLimitError on 429 with Retry-After" do
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/usage") do
+          [429, { "Retry-After" => "11" },
+           JSON.generate({ "error" => { "code" => "RATE_LIMITED", "message" => "slow" } })]
+        end
+      end
+      begin
+        build_client(stubs).get_usage
+        raise "should have raised"
+      rescue Deckle::RateLimitError => e
+        expect(e.retry_after).to eq(11)
+      end
+    end
+
+    it "raises a generic Error on a non-retryable 4xx" do
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/generate") do
+          [400, {}, JSON.generate({ "error" => { "code" => "VALIDATION_ERROR", "message" => "bad" } })]
+        end
+      end
+      expect do
+        build_client(stubs).generate(html: "")
+      end.to raise_error(Deckle::Error) { |e|
+        expect(e.status_code).to eq(400)
+        expect(e.code).to eq("VALIDATION_ERROR")
+      }
+    end
+
+    it "raises NotFoundError on 404" do
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/generations/gen_missing") do
+          [404, {}, JSON.generate({ "error" => { "code" => "NOT_FOUND", "message" => "nope" } })]
+        end
+      end
+      expect do
+        build_client(stubs).get_generation("gen_missing")
+      end.to raise_error(Deckle::NotFoundError)
+    end
+
+    it "does not retry when max_retries is zero" do
+      hit = 0
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/usage") do
+          hit += 1
+          [500, {}, JSON.generate({ "error" => {} })]
+        end
+      end
+      expect do
+        build_client(stubs, max_retries: 0).get_usage
+      end.to raise_error(Deckle::Error)
+      expect(hit).to eq(1)
+    end
+  end
+
+  describe "PDF + marketplace + AI namespaces" do
+    it "pdf_merge POSTs to /v1/pdf/merge" do
+      called = false
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/pdf/merge") do
+          called = true
+          [200, {}, JSON.generate({ "url" => "x", "file_size" => 1 })]
+        end
+      end
+      build_client(stubs).pdf_merge(pdfs: %w[a b])
+      expect(called).to be(true)
+    end
+
+    it "pdf_protect raises before sending when no password is supplied" do
+      stubs = Faraday::Adapter::Test::Stubs.new
+      expect do
+        build_client(stubs).pdf_protect(pdf: "abc")
+      end.to raise_error(ArgumentError, /password/)
+    end
+
+    it "pdf_protect forwards passwords and permissions" do
+      captured_body = nil
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/pdf/protect") do |env|
+          captured_body = JSON.parse(env.body)
+          [200, {}, JSON.generate({ "url" => "x", "file_size" => 1, "encrypted" => true, "encryption" => "AES-256" })]
+        end
+      end
+      build_client(stubs).pdf_protect(
+        pdf: "abc",
+        user_password: "reader",
+        owner_password: "owner",
+        permissions: { "print" => "low", "modify" => false, "copy" => true }
+      )
+      expect(captured_body["user_password"]).to eq("reader")
+      expect(captured_body["owner_password"]).to eq("owner")
+      expect(captured_body["permissions"]["print"]).to eq("low")
+    end
+
+    it "pdf_sign_annotation forwards optional signature material" do
+      captured_body = nil
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/pdf/sign") do |env|
+          captured_body = JSON.parse(env.body)
+          [200, {}, JSON.generate({
+                                    "url" => "x", "file_size" => 1,
+                                    "signature_annotation_added" => true,
+                                    "cryptographically_signed" => true,
+                                    "signature_type" => "PAdES-B-B"
+                                  })]
+        end
+      end
+      build_client(stubs).pdf_sign_annotation(
+        pdf: "abc",
+        name: "Test Signer",
+        signature: { "p12" => "base64-blob", "password" => "pw" }
+      )
+      expect(captured_body["signature"]).to eq("p12" => "base64-blob", "password" => "pw")
+    end
+
+    it "marketplace_list hits /v1/marketplace" do
+      called = false
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/marketplace") do
+          called = true
+          [200, {}, JSON.generate({ "data" => [] })]
+        end
+      end
+      build_client(stubs).marketplace_list
+      expect(called).to be(true)
+    end
+
+    it "marketplace_report POSTs reason + notes" do
+      captured = nil
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/marketplace/tmpl_xyz/report") do |env|
+          captured = JSON.parse(env.body)
+          [201, {}, JSON.generate({ "report_id" => "rep_1", "auto_actioned" => false })]
+        end
+      end
+      result = build_client(stubs).marketplace_report("tmpl_xyz", reason: "spam", notes: "repetitive")
+      expect(result["report_id"]).to eq("rep_1")
+      expect(result["auto_actioned"]).to be(false)
+      expect(captured).to eq("reason" => "spam", "notes" => "repetitive")
+    end
+
+    it "starter_templates_list hits /v1/starter-templates" do
+      called = false
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.get("/v1/starter-templates") do
+          called = true
+          [200, {}, JSON.generate({ "data" => [] })]
+        end
+      end
+      build_client(stubs).starter_templates_list
+      expect(called).to be(true)
+    end
+
+    it "generate_template_from_prompt posts to /v1/ai/generate-template" do
+      called = false
+      stubs = Faraday::Adapter::Test::Stubs.new do |s|
+        s.post("/v1/ai/generate-template") do
+          called = true
+          [200, {}, JSON.generate({ "html_content" => "<div>" })]
+        end
+      end
+      build_client(stubs).generate_template_from_prompt(prompt: "an invoice")
+      expect(called).to be(true)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+
+require "deckle"
+require "faraday"
+require "json"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.disable_monkey_patching!
+  config.order = :random
+  Kernel.srand config.seed
+end
+
+module DeckleSpecHelpers
+  BASE_URL = "https://api.test.local"
+
+  # Build a Deckle::Client whose Faraday connection uses the supplied
+  # Faraday::Adapter::Test::Stubs. Real network is never touched.
+  def build_client(stubs, api_key: "dk_live_test", max_retries: 0)
+    client = Deckle::Client.new(
+      api_key: api_key,
+      base_url: BASE_URL,
+      timeout: 5,
+      max_retries: max_retries
+    )
+    test_conn = Faraday.new(url: BASE_URL) do |f|
+      f.headers["Authorization"] = "Bearer #{api_key}"
+      f.headers["Content-Type"] = "application/json"
+      f.headers["User-Agent"] = "deckle-ruby/#{Deckle::VERSION}"
+      f.adapter(:test, stubs)
+    end
+    client.instance_variable_set(:@conn, test_conn)
+    client
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: deckle
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Deckle
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: Generate PDFs from HTML, templates, and React components using the Deckle
+  API.
+email:
+- support@getdeckle.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/deckle.rb
+- lib/deckle/client.rb
+- lib/deckle/errors.rb
+- lib/deckle/templates.rb
+- lib/deckle/version.rb
+- spec/deckle/client_spec.rb
+- spec/spec_helper.rb
+homepage: https://getdeckle.dev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://getdeckle.dev
+  source_code_uri: https://github.com/Yoshyaes/deckle
+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: 4.0.10
+specification_version: 4
+summary: Ruby SDK for the Deckle PDF generation API
+test_files:
+- spec/deckle/client_spec.rb
+- spec/spec_helper.rb