authensure 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d146da491c0a18038f9afd386e8619e76c8a8428a416a2d8e41c24229296134
+  data.tar.gz: a887fbe309338a80b927202d8219cf39d44e7cab0a48c8e8c31d9deb5261bacc
+SHA512:
+  metadata.gz: 8ab836a8d17e538a691cd90b563b271c17c00a0fd930b54d9802f25bec46e543294bc47d085d9cba48edc6362f63757222c381b5b62f8eaf4e05f0568d6fa56f
+  data.tar.gz: bea6f9edb526acb83a69b8afbf279d7b35c193fdef9e703439d279e03f41c9b9d9e9fa21b85fa67b3c538deca311f1421147887086ec047c10c9e2e4031a162f

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/CONTRIBUTING.md

@@ -0,0 +1,75 @@
+# Contributing to Authensure Ruby SDK
+
+Thank you for your interest in contributing to the Authensure Ruby SDK!
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/authensure-ruby.git
+   cd authensure-ruby
+   ```
+3. Install dependencies:
+   ```bash
+   bundle install
+   ```
+4. Run tests:
+   ```bash
+   bundle exec rspec
+   ```
+
+## Development Workflow
+
+1. Create a feature branch:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. Make your changes following the code style guidelines
+
+3. Write tests for your changes
+
+4. Run the test suite:
+   ```bash
+   bundle exec rspec
+   ```
+
+5. Run the linter:
+   ```bash
+   bundle exec rubocop
+   ```
+
+6. Commit your changes:
+   ```bash
+   git commit -m "feat: Add your feature description"
+   ```
+
+7. Push and create a Pull Request
+
+## Code Style
+
+- Follow the Ruby Style Guide
+- Use RuboCop for linting
+- Write YARD documentation for public methods
+- Use `frozen_string_literal: true` in all files
+
+## Testing
+
+- Write RSpec tests for all new functionality
+- Use WebMock for HTTP stubbing
+- Aim for high test coverage
+
+## Commit Messages
+
+Use conventional commits:
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation
+- `test:` Tests
+- `refactor:` Refactoring
+- `chore:` Maintenance
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Authensure
+
+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,274 @@
+# Authensure Ruby SDK
+
+[![Gem Version](https://img.shields.io/gem/v/authensure)](https://rubygems.org/gems/authensure)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.0-ruby.svg)](https://www.ruby-lang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Official Ruby SDK for [Authensure](https://authensure.app) - the electronic signature and document authentication platform.
+
+## Features
+
+- **Full API Coverage** - Access all Authensure API endpoints
+- **Ruby 3.0+** - Modern Ruby with full type annotations via YARD
+- **Automatic Retries** - Built-in exponential backoff for transient errors
+- **Rate Limit Handling** - Automatic rate limit detection and backoff
+- **Webhook Verification** - Easy webhook signature verification
+- **File Uploads** - Simplified document upload handling
+- **Debug Mode** - Detailed logging for development
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'authensure'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install authensure
+```
+
+## Quick Start
+
+```ruby
+require 'authensure'
+
+# Initialize with API key
+client = Authensure::Client.new(api_key: 'your_api_key')
+
+# Or use class methods
+client = Authensure::Client.with_api_key('your_api_key')
+
+# Create an envelope
+envelope = client.envelopes.create(
+  name: 'Contract Agreement',
+  message: 'Please review and sign this document'
+)
+
+puts "Created envelope: #{envelope[:id]}"
+```
+
+## Configuration
+
+### Global Configuration
+
+```ruby
+Authensure.configure do |config|
+  config.api_key = 'your_api_key'
+  config.base_url = 'https://api.authensure.app/api'  # Optional
+  config.timeout = 30                                   # Optional
+  config.retry_attempts = 3                             # Optional
+  config.debug = false                                  # Optional
+end
+
+client = Authensure.client
+```
+
+### Per-Client Configuration
+
+```ruby
+client = Authensure::Client.new(
+  api_key: 'your_api_key',
+  base_url: 'https://api.authensure.app/api',
+  timeout: 30,
+  retry_attempts: 3,
+  debug: true
+)
+```
+
+### Using Access Token
+
+```ruby
+client = Authensure::Client.with_access_token('your_access_token')
+```
+
+## API Reference
+
+### Envelopes
+
+```ruby
+# List envelopes
+envelopes = client.envelopes.list(status: 'DRAFT')
+
+# Get an envelope
+envelope = client.envelopes.get('envelope_id')
+
+# Create an envelope
+envelope = client.envelopes.create(name: 'My Contract', message: 'Please sign')
+
+# Add a recipient
+recipient = client.envelopes.add_recipient(
+  'envelope_id',
+  email: 'signer@example.com',
+  name: 'John Doe',
+  role: 'signer'
+)
+
+# Send for signing
+envelope = client.envelopes.send_envelope('envelope_id')
+
+# Void an envelope
+envelope = client.envelopes.void('envelope_id', reason: 'Contract cancelled')
+```
+
+### Documents
+
+```ruby
+# Upload a document
+document = client.documents.upload(
+  envelope_id: 'envelope_id',
+  file: File.read('contract.pdf'),
+  filename: 'contract.pdf'
+)
+
+# Get signed document URL
+result = client.documents.get_signed_url('document_id')
+puts result[:url]
+
+# Download a document
+content = client.documents.download('document_id')
+```
+
+### Templates
+
+```ruby
+# List templates
+templates = client.templates.list
+
+# Create from template
+envelope = client.templates.use(
+  'template_id',
+  name: 'New Contract',
+  recipients: [
+    { roleId: 'role_1', email: 'signer@example.com', name: 'John Doe' }
+  ]
+)
+```
+
+### Contacts
+
+```ruby
+# List contacts
+contacts = client.contacts.list(search: 'acme', limit: 20)
+
+# Create a contact
+contact = client.contacts.create(
+  email: 'contact@example.com',
+  name: 'Jane Smith',
+  company: 'Acme Inc'
+)
+```
+
+### Webhooks
+
+```ruby
+# Create a webhook
+webhook = client.webhooks.create(
+  url: 'https://your-app.com/webhooks/authensure',
+  events: ['envelope.signed', 'envelope.completed']
+)
+
+# Verify webhook signature
+is_valid = Authensure::Resources::Webhooks.verify_signature(
+  payload,
+  signature,
+  'your_webhook_secret'
+)
+
+# Construct verified event
+event = Authensure::Resources::Webhooks.construct_event(
+  payload,
+  signature,
+  'your_webhook_secret'
+)
+puts "Event type: #{event[:event]}"
+```
+
+## Error Handling
+
+```ruby
+begin
+  envelope = client.envelopes.get('invalid_id')
+rescue Authensure::NotFoundError
+  puts 'Envelope not found'
+rescue Authensure::AuthenticationError
+  puts 'Invalid API key'
+rescue Authensure::RateLimitError => e
+  puts "Rate limited, retry after: #{e.retry_after} seconds"
+rescue Authensure::ValidationError => e
+  puts "Validation errors: #{e.validation_errors}"
+rescue Authensure::Error => e
+  puts "API error: #{e.message} (code: #{e.code})"
+end
+```
+
+## Rails Integration
+
+Add to your `config/initializers/authensure.rb`:
+
+```ruby
+Authensure.configure do |config|
+  config.api_key = Rails.application.credentials.authensure_api_key
+  config.debug = Rails.env.development?
+end
+```
+
+Use in your controllers:
+
+```ruby
+class EnvelopesController < ApplicationController
+  def create
+    envelope = authensure_client.envelopes.create(
+      name: params[:name],
+      message: params[:message]
+    )
+    render json: envelope
+  end
+
+  private
+
+  def authensure_client
+    @authensure_client ||= Authensure.client
+  end
+end
+```
+
+## Development
+
+After checking out the repo:
+
+```bash
+bundle install
+```
+
+Run the tests:
+
+```bash
+bundle exec rspec
+```
+
+Run the linter:
+
+```bash
+bundle exec rubocop
+```
+
+## Resources
+
+- [Documentation](https://authensure.app/docs/sdk/ruby)
+- [API Reference](https://authensure.app/dashboard/developers)
+- [GitHub Repository](https://github.com/Authensure/authensure-ruby)
+- [RubyGems](https://rubygems.org/gems/authensure)
+- [Report Issues](https://github.com/Authensure/authensure-ruby/issues)
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/authensure.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/authensure/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "authensure"
+  spec.version = Authensure::VERSION
+  spec.authors = ["Authensure"]
+  spec.email = ["support@authensure.app"]
+
+  spec.summary = "Official Authensure SDK for Ruby"
+  spec.description = "Ruby SDK for Authensure - the electronic signature and document authentication platform. " \
+                     "Provides a simple interface to create envelopes, manage documents, handle signatures, " \
+                     "and integrate webhooks."
+  spec.homepage = "https://authensure.app"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/Authensure/authensure-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/Authensure/authensure-ruby/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://authensure.app/docs/sdk/ruby"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/Authensure/authensure-ruby/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "faraday", ">= 1.0", "< 3.0"
+  spec.add_dependency "faraday-multipart", "~> 1.0"
+  spec.add_dependency "faraday-retry", "~> 2.0"
+
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.0"
+  spec.add_development_dependency "rubocop-rspec", "~> 2.0"
+  spec.add_development_dependency "simplecov", "~> 0.22"
+  spec.add_development_dependency "webmock", "~> 3.0"
+  spec.add_development_dependency "yard", "~> 0.9"
+end

data/examples/basic_usage.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "authensure"
+
+api_key = ENV.fetch("AUTHENSURE_API_KEY", nil)
+unless api_key
+  puts "Error: AUTHENSURE_API_KEY environment variable not set"
+  puts "Set it with: export AUTHENSURE_API_KEY='your_api_key_here'"
+  exit 1
+end
+
+client = Authensure::Client.new(api_key: api_key)
+
+puts "=== Authensure Ruby SDK Basic Usage ==="
+puts
+
+puts "Creating envelope..."
+envelope = client.envelopes.create(
+  name: "Contract Agreement",
+  message: "Please review and sign this contract at your earliest convenience."
+)
+puts "Created envelope: #{envelope[:id]}"
+puts "  Name: #{envelope[:name]}"
+puts "  Status: #{envelope[:status]}"
+
+puts
+puts "Adding recipient..."
+recipient = client.envelopes.add_recipient(
+  envelope[:id],
+  email: "signer@example.com",
+  name: "John Doe",
+  role: "signer"
+)
+puts "Added recipient: #{recipient[:id]}"
+puts "  Email: #{recipient[:email]}"
+puts "  Name: #{recipient[:name]}"
+
+puts
+puts "Fetching envelope details..."
+envelope = client.envelopes.get(envelope[:id])
+puts "Envelope has #{envelope[:recipients]&.length || 0} recipient(s)"
+
+puts
+puts "Listing all envelopes..."
+envelopes = client.envelopes.list
+puts "Found #{envelopes.length} envelope(s)"
+
+puts
+puts "Cleaning up..."
+client.envelopes.delete(envelope[:id])
+puts "Deleted test envelope"
+
+puts
+puts "=== Example Complete ==="

data/examples/webhook_handler.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "authensure"
+require "sinatra"
+require "json"
+
+WEBHOOK_SECRET = ENV.fetch("AUTHENSURE_WEBHOOK_SECRET", "")
+
+post "/webhooks/authensure" do
+  payload = request.body.read
+  signature = request.env["HTTP_X_AUTHENSURE_SIGNATURE"] || ""
+
+  begin
+    event = Authensure::Resources::Webhooks.construct_event(payload, signature, WEBHOOK_SECRET)
+  rescue Authensure::Error => e
+    puts "Webhook signature verification failed: #{e.message}"
+    halt 401, { error: "Invalid signature" }.to_json
+  end
+
+  puts "=" * 50
+  puts "Received webhook event: #{event[:event]}"
+  puts "Timestamp: #{event[:timestamp]}"
+  puts "=" * 50
+
+  case event[:event]
+  when "envelope.created"
+    puts "Envelope created: #{event[:data]["envelopeId"]}"
+  when "envelope.sent"
+    puts "Envelope sent: #{event[:data]["envelopeId"]}"
+  when "envelope.viewed"
+    puts "Envelope viewed by: #{event[:data]["recipientEmail"]}"
+  when "envelope.signed"
+    puts "Envelope signed by: #{event[:data]["recipientName"]}"
+  when "envelope.completed"
+    puts "Envelope completed: #{event[:data]["envelopeId"]}"
+  when "envelope.declined"
+    puts "Envelope declined by: #{event[:data]["recipientEmail"]}"
+    puts "Reason: #{event[:data]["declineReason"]}"
+  when "envelope.voided"
+    puts "Envelope voided: #{event[:data]["envelopeId"]}"
+  else
+    puts "Unhandled event type: #{event[:event]}"
+    puts "Data: #{JSON.pretty_generate(event[:data])}"
+  end
+
+  { received: true }.to_json
+end
+
+get "/health" do
+  { status: "healthy" }.to_json
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting Authensure webhook server..."
+  puts "Listening on: http://localhost:4567/webhooks/authensure"
+  puts "Health check: http://localhost:4567/health"
+  puts
+  puts "Warning: AUTHENSURE_WEBHOOK_SECRET not set" if WEBHOOK_SECRET.empty?
+end

data/lib/authensure/client.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Authensure
+  class Client
+    attr_reader :config, :http
+
+    def initialize(options = {})
+      @config = build_config(options)
+      @http = HttpClient.new(@config)
+    end
+
+    def auth
+      @auth ||= Resources::Auth.new(@http)
+    end
+
+    def envelopes
+      @envelopes ||= Resources::Envelopes.new(@http)
+    end
+
+    def documents
+      @documents ||= Resources::Documents.new(@http)
+    end
+
+    def templates
+      @templates ||= Resources::Templates.new(@http)
+    end
+
+    def contacts
+      @contacts ||= Resources::Contacts.new(@http)
+    end
+
+    def webhooks
+      @webhooks ||= Resources::Webhooks.new(@http)
+    end
+
+    def users
+      @users ||= Resources::Users.new(@http)
+    end
+
+    def organizations
+      @organizations ||= Resources::Organizations.new(@http)
+    end
+
+    def api_keys
+      @api_keys ||= Resources::ApiKeys.new(@http)
+    end
+
+    def teams
+      @teams ||= Resources::Teams.new(@http)
+    end
+
+    def signatures
+      @signatures ||= Resources::Signatures.new(@http)
+    end
+
+    def self.with_api_key(api_key, **options)
+      new(options.merge(api_key: api_key))
+    end
+
+    def self.with_access_token(access_token, **options)
+      new(options.merge(access_token: access_token))
+    end
+
+    private
+
+    def build_config(options)
+      config = Configuration.new
+      config.api_key = options[:api_key] if options[:api_key]
+      config.access_token = options[:access_token] if options[:access_token]
+      config.base_url = options[:base_url] if options[:base_url]
+      config.timeout = options[:timeout] if options[:timeout]
+      config.retry_attempts = options[:retry_attempts] if options[:retry_attempts]
+      config.retry_delay = options[:retry_delay] if options[:retry_delay]
+      config.debug = options[:debug] if options.key?(:debug)
+      config
+    end
+  end
+end

data/lib/authensure/configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Authensure
+  class Configuration
+    attr_accessor :api_key, :access_token, :base_url, :timeout, :retry_attempts, :retry_delay, :debug
+
+    DEFAULT_BASE_URL = "https://api.authensure.app/api"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_RETRY_ATTEMPTS = 3
+    DEFAULT_RETRY_DELAY = 1
+
+    def initialize
+      @api_key = ENV.fetch("AUTHENSURE_API_KEY", nil)
+      @access_token = nil
+      @base_url = ENV.fetch("AUTHENSURE_BASE_URL", DEFAULT_BASE_URL)
+      @timeout = DEFAULT_TIMEOUT
+      @retry_attempts = DEFAULT_RETRY_ATTEMPTS
+      @retry_delay = DEFAULT_RETRY_DELAY
+      @debug = false
+    end
+  end
+end