formable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 661116dc7b31f9ec87081b7cd8a217c9af6990a9d2b36155aabb791c1de681fc
+  data.tar.gz: a8a7a898ad4e18b48d2b0662614780e5cc5d6fd59ff1f1bc30ad274148ee04fd
+SHA512:
+  metadata.gz: 78617740a61a52f1df0e1423915e24d1d434a9008a364485418637f9abf35720725da61d8ecbfa57ce3e3f6e227ad1eeb6f1c3c86811d9a5be6724670d703f2f
+  data.tar.gz: fe15e224a3f82d7b3b05185320a27112887467848fc7fa2699c4d73de1fafb5b3831f05262db90a3f87e3ecd51bd17df1bf9c218a9cf4c43b03b35e2ca1dcd82

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Formable
+
+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,158 @@
+# formable-ruby
+
+Official Ruby SDK for the [Formable API](https://api.formabledocs.com) (v1). Covers templates, signature requests, redlining, and billing.
+
+- Faraday HTTP client (injectable)
+- Keyword arguments and snake_case method names
+- Ruby 3.1+
+
+## Installation
+
+```ruby
+# Gemfile
+gem "formable"
+```
+
+```bash
+bundle add formable
+# or
+gem install formable
+```
+
+## Usage
+
+```ruby
+require "formable"
+
+formable = Formable.new(api_key: ENV.fetch("FORMABLE_API_KEY"))
+```
+
+### Templates
+
+```ruby
+result = formable.templates.create(
+  file: "nda.docx",
+  signer_roles: [
+    { name: "Client", order: 0 },
+    { name: "Witness", order: 1 }
+  ]
+)
+
+template_id = result["templateId"]
+
+# Mint a fresh edit URL later (expires after 1 day)
+edit = formable.templates.create_edit_url(template_id)
+puts edit["editUrl"], edit["expiresAt"]
+```
+
+`file` accepts a path, binary string, or IO. Pass `filename:` when `file` is not a path.
+
+### Signature requests
+
+```ruby
+# Formable emails each signer a signing link
+request = formable.signature_requests.create(
+  template_id: template_id,
+  signers: [
+    { email: "jane@example.com", name: "Jane Doe", role: "Client" },
+    { email: "bob@example.com", name: "Bob Smith", role: "Witness" }
+  ]
+)
+
+# Embedded flow: mint signing URLs to embed in an iframe yourself
+embedded = formable.signature_requests.create_embedded(
+  template_id: template_id,
+  signers: [{ email: "jane@example.com", name: "Jane Doe", role: "Client" }],
+  test_mode: true
+)
+
+signer = embedded["signers"].first
+signing = formable.signature_requests.create_signing_url(
+  signer["recipientSignatureId"]
+)
+
+# Track progress
+current = formable.signature_requests.get(embedded["signatureRequestId"])
+all_requests = formable.signature_requests.list(
+  updated_since: Time.utc(2026, 1, 1)
+)
+events = formable.signature_requests.get_events(embedded["signatureRequestId"])
+
+# Download the signed document once completed
+envelope = formable.signature_requests.get_signed_envelope(
+  embedded["signatureRequestId"]
+)
+puts envelope["signedEnvelopePresignedUrl"]
+```
+
+### Redline requests
+
+```ruby
+created = formable.redline_requests.create(
+  template_id: template_id,
+  members: [
+    { email: "us@example.com", display_name: "John Doe", role: "DisclosingParty" },
+    { email: "them@example.com", display_name: "Jane Smith", role: "ReceivingParty" }
+  ],
+  metadata: { subject: "Mutual NDA" }
+)
+
+redline_request_id = created["redlineRequestId"]
+
+# Mint a redline URL for a member (embed in an iframe)
+url = formable.redline_requests.create_url(redline_request_id, "them@example.com")
+
+# Manage members and track progress
+formable.redline_requests.update_members(
+  redline_request_id,
+  [{ email: "counsel@example.com", display_name: "Counsel", role: "ReceivingCounsel" }]
+)
+redline = formable.redline_requests.get(redline_request_id)
+events = formable.redline_requests.get_events(redline_request_id)
+```
+
+### Billing and health
+
+```ruby
+billing = formable.billing
+puts billing["numberOfRedliningSessions"]
+
+health = formable.health
+```
+
+## Error handling
+
+All non-2xx responses raise a `Formable::Error` with the server's error message, HTTP status, and parsed response body.
+
+```ruby
+begin
+  formable.signature_requests.get("missing-id")
+rescue Formable::Error => error
+  warn "#{error.status} #{error.message}"
+end
+```
+
+## Configuration
+
+| Option       | Description                                               | Default                           |
+| ------------ | --------------------------------------------------------- | --------------------------------- |
+| `api_key`    | Your Formable API key (sent as a bearer token). Required. | -                                 |
+| `base_url`   | Override the API base URL.                                | `https://api.formabledocs.com/v1` |
+| `timeout`    | Per-request timeout in seconds.                           | `60`                              |
+| `connection` | Custom `Faraday::Connection`.                             | Built-in client with 60s timeout  |
+
+Request hashes accept snake_case keys (`template_id`, `display_name`, `field_id`). Responses use the API's camelCase field names (`templateId`, `displayName`).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+## Publishing
+
+```bash
+gem build formable.gemspec
+gem push formable-*.gem
+```

data/lib/formable/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Formable
+  class Client
+    attr_reader :templates, :signature_requests, :redline_requests
+
+    def initialize(api_key:, base_url: nil, timeout: 60, connection: nil)
+      @http = Http.new(
+        api_key: api_key,
+        base_url: base_url,
+        timeout: timeout,
+        connection: connection
+      )
+      @templates = Templates.new(@http)
+      @signature_requests = SignatureRequests.new(@http)
+      @redline_requests = RedlineRequests.new(@http)
+    end
+
+    def billing
+      @http.get("/billing")
+    end
+
+    def health
+      @http.get("/health")
+    end
+
+    def close
+      @http.close
+    end
+  end
+end

data/lib/formable/error.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Formable
+  # Raised for any non-2xx response from the Formable API.
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(message, status:, body: nil)
+      super(message)
+      @status = status
+      @body = body
+    end
+  end
+end

data/lib/formable/http.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/multipart"
+require "json"
+
+module Formable
+  class Http
+    def initialize(api_key:, base_url: nil, timeout: 60, connection: nil)
+      raise ArgumentError, "Formable API key is required" if api_key.nil? || api_key.strip.empty?
+
+      @api_key = api_key
+      @base_url = (base_url || DEFAULT_BASE_URL).sub(%r{/+\z}, "")
+      @connection = connection || build_connection(timeout)
+    end
+
+    def get(path, query = {})
+      request(:get, path, query: query)
+    end
+
+    def post(path, body = nil)
+      request(:post, path, json: body)
+    end
+
+    def put(path, body = nil)
+      request(:put, path, json: body)
+    end
+
+    def post_form(path, fields)
+      request(:post, path, form: fields)
+    end
+
+    def close
+      @connection.close if @connection.respond_to?(:close)
+    end
+
+    private
+
+    def build_connection(timeout)
+      Faraday.new do |conn|
+        conn.request :multipart
+        conn.options.timeout = timeout
+        conn.options.open_timeout = timeout
+        conn.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, query: nil, json: nil, form: nil)
+      response = @connection.run_request(method, url(path), nil, headers) do |req|
+        req.params.update(Params.compact(query)) if query
+        if form
+          req.body = form
+        elsif !json.nil?
+          req.headers["Content-Type"] = "application/json"
+          req.body = JSON.generate(json)
+        end
+      end
+      handle(response)
+    end
+
+    def url(path)
+      @base_url + path
+    end
+
+    def headers
+      {
+        "Authorization" => "Bearer #{@api_key}",
+        "Accept" => "application/json",
+        "User-Agent" => "formable-ruby/#{VERSION}"
+      }
+    end
+
+    def handle(response)
+      body = parse_body(response.body)
+      return body if response.success?
+
+      message = body.is_a?(Hash) ? body["error"] : nil
+      raise Error.new(
+        message || "Request failed with status #{response.status}",
+        status: response.status,
+        body: body
+      )
+    end
+
+    def parse_body(text)
+      return if text.nil? || text.empty?
+
+      JSON.parse(text)
+    rescue JSON::ParserError
+      text
+    end
+  end
+end

data/lib/formable/params.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Formable
+  module Params
+    module_function
+
+    def encode_path(value)
+      URI.encode_uri_component(value)
+    end
+
+    def iso8601(value)
+      return if value.nil?
+      return value.iso8601 if value.respond_to?(:iso8601)
+
+      value.to_s
+    end
+
+    def compact(hash)
+      hash.reject { |_, value| value.nil? }
+    end
+
+    def camelize_keys(value)
+      case value
+      when Array
+        value.map { |item| camelize_keys(item) }
+      when Hash
+        value.each_with_object({}) do |(key, item), result|
+          result[camelize_key(key)] = camelize_keys(item)
+        end
+      else
+        value
+      end
+    end
+
+    def json_body(hash)
+      compact(camelize_keys(hash))
+    end
+
+    def camelize_key(key)
+      key.to_s.gsub(/_([a-z\d])/) { ::Regexp.last_match(1).upcase }
+    end
+  end
+end

data/lib/formable/resources/redline_requests.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Formable
+  class RedlineRequests
+    def initialize(http)
+      @http = http
+    end
+
+    def create(template_id:, members:, test_mode: nil, metadata: nil)
+      @http.post("/redline-requests", Params.json_body(
+        template_id: template_id,
+        members: members,
+        test_mode: test_mode,
+        metadata: metadata
+      ))
+    end
+
+    def list(updated_since: nil)
+      @http.get("/redline-requests", "updatedSince" => Params.iso8601(updated_since))
+    end
+
+    def get(redline_request_id)
+      @http.get(path(redline_request_id))
+    end
+
+    def update_members(redline_request_id, members)
+      @http.put(
+        path(redline_request_id, "/members"),
+        Params.json_body(members: members)
+      )
+    end
+
+    def create_url(redline_request_id, member_email)
+      @http.post(
+        path(redline_request_id, "/url"),
+        Params.json_body(member_email: member_email)
+      )
+    end
+
+    def get_events(redline_request_id)
+      @http.get(path(redline_request_id, "/events"))
+    end
+
+    private
+
+    def path(redline_request_id, suffix = "")
+      "/redline-requests/#{Params.encode_path(redline_request_id)}#{suffix}"
+    end
+  end
+end

data/lib/formable/resources/signature_requests.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Formable
+  class SignatureRequests
+    def initialize(http)
+      @http = http
+    end
+
+    def create(template_id:, signers:, sender: nil, test_mode: nil, fields: nil)
+      @http.post("/signature-requests", create_body(
+        template_id: template_id,
+        signers: signers,
+        sender: sender,
+        test_mode: test_mode,
+        fields: fields
+      ))
+    end
+
+    def create_embedded(template_id:, signers:, sender: nil, test_mode: nil, fields: nil)
+      @http.post("/signature-requests/embedded", create_body(
+        template_id: template_id,
+        signers: signers,
+        sender: sender,
+        test_mode: test_mode,
+        fields: fields
+      ))
+    end
+
+    def list(updated_since: nil)
+      @http.get("/signature-requests", "updatedSince" => Params.iso8601(updated_since))
+    end
+
+    def get(signature_request_id)
+      @http.get(path(signature_request_id))
+    end
+
+    def get_events(signature_request_id)
+      @http.get(path(signature_request_id, "/events"))
+    end
+
+    def get_signed_envelope(signature_request_id)
+      @http.get(path(signature_request_id, "/signed-envelope"))
+    end
+
+    def create_signing_url(recipient_signature_id)
+      @http.post("/recipient-signatures/#{Params.encode_path(recipient_signature_id)}/url")
+    end
+
+    private
+
+    def create_body(template_id:, signers:, sender:, test_mode:, fields:)
+      Params.json_body(
+        template_id: template_id,
+        signers: signers,
+        sender: sender,
+        test_mode: test_mode,
+        fields: fields
+      )
+    end
+
+    def path(signature_request_id, suffix = "")
+      "/signature-requests/#{Params.encode_path(signature_request_id)}#{suffix}"
+    end
+  end
+end

data/lib/formable/resources/templates.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+require "stringio"
+
+require "faraday/multipart"
+
+module Formable
+  class Templates
+    def initialize(http)
+      @http = http
+    end
+
+    def create(file:, filename: nil, signer_roles: nil)
+      io_or_path, resolved_filename = normalize_file(file, filename)
+      fields = {
+        "file" => Faraday::Multipart::FilePart.new(
+          io_or_path,
+          "application/octet-stream",
+          resolved_filename
+        ),
+        "filename" => resolved_filename
+      }
+      unless signer_roles.nil?
+        fields["signer_roles"] = JSON.generate(signer_roles)
+      end
+      @http.post_form("/templates", fields)
+    end
+
+    def create_edit_url(template_id)
+      @http.post("/templates/#{Params.encode_path(template_id)}/edit-url")
+    end
+
+    private
+
+    def normalize_file(file, filename)
+      case file
+      when Pathname
+        raise ArgumentError, "Unable to read file: #{file}" unless file.file?
+
+        [file.to_s, filename || file.basename.to_s]
+      when String
+        if File.file?(file)
+          [file, filename || File.basename(file)]
+        else
+          require_filename!(filename, "file is not a path")
+          [StringIO.new(file), filename]
+        end
+      else
+        unless file.respond_to?(:read)
+          raise ArgumentError, "file must be a path, IO, or binary string"
+        end
+
+        require_filename!(filename, "file is an IO")
+        [file, filename]
+      end
+    end
+
+    def require_filename!(filename, reason)
+      return unless filename.nil? || filename.empty?
+
+      raise ArgumentError, "filename is required when #{reason}"
+    end
+  end
+end

data/lib/formable/version.rb

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

data/lib/formable.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "formable/version"
+require_relative "formable/error"
+require_relative "formable/params"
+require_relative "formable/http"
+require_relative "formable/resources/templates"
+require_relative "formable/resources/signature_requests"
+require_relative "formable/resources/redline_requests"
+require_relative "formable/client"
+
+module Formable
+  DEFAULT_BASE_URL = "https://api.formabledocs.com/v1"
+
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: formable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Formable
+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.9'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.9'
+- !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'
+description: Official Ruby SDK for the Formable API. Covers templates, signature requests,
+  redlining, and billing.
+email:
+- matt@formabledocs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/formable.rb
+- lib/formable/client.rb
+- lib/formable/error.rb
+- lib/formable/http.rb
+- lib/formable/params.rb
+- lib/formable/resources/redline_requests.rb
+- lib/formable/resources/signature_requests.rb
+- lib/formable/resources/templates.rb
+- lib/formable/version.rb
+homepage: https://www.formabledocs.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.formabledocs.com
+  source_code_uri: https://github.com/FormableDocs/formable-ruby
+  bug_tracker_uri: https://github.com/FormableDocs/formable-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Official Ruby SDK for the Formable API
+test_files: []