anvil-ruby 0.1.0

data/README.md

@@ -0,0 +1,445 @@
+# Anvil Ruby
+
+A Ruby gem for the [Anvil API](https://www.useanvil.com/docs/) - the fastest way to build document workflows.
+
+[![CI](https://github.com/nickMarz/Ruby-Anvil/workflows/CI/badge.svg)](https://github.com/nickMarz/Ruby-Anvil/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/anvil-ruby.svg)](https://badge.fury.io/rb/anvil-ruby)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%202.5.0-red.svg)](https://github.com/nickMarz/Ruby-Anvil/blob/main/.ruby-version)
+
+Anvil is a suite of tools for managing document workflows:
+
+- 📝 **PDF Filling** - Fill PDF templates with JSON data
+- 📄 **PDF Generation** - Generate PDFs from HTML/CSS or Markdown
+- ✍️ **E-signatures** - Collect legally binding e-signatures
+- 🔄 **Webhooks** - Real-time notifications for document events
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'anvil-ruby'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself:
+
+```bash
+$ gem install anvil-ruby
+```
+
+## Feature Status
+
+Current coverage: **~30% of Anvil's API**. See [API_COVERAGE.md](API_COVERAGE.md) for detailed implementation status.
+
+### ✅ Implemented
+- **PDF Operations** - Fill templates, generate from HTML/Markdown
+- **E-Signatures (Basic)** - Create packets, get signing URLs, track status
+- **Webhooks** - Parse payloads, verify authenticity
+- **Core Infrastructure** - Rate limiting, error handling, flexible configuration
+
+### 🚧 Roadmap
+
+#### Phase 1: Core Features (v0.2.0)
+- [ ] Generic GraphQL support for custom queries
+- [ ] Complete e-signature features (update, send, void packets)
+- [ ] Basic workflow support (create, start workflows)
+- [ ] Basic webform support (create forms, handle submissions)
+
+#### Phase 2: Advanced Features (v0.3.0)
+- [ ] Full workflow implementation with data management
+- [ ] Full webform/Forge implementation
+- [ ] Cast (PDF template) management
+- [ ] Webhook management API
+
+#### Phase 3: AI & Enterprise (v0.4.0)
+- [ ] Document AI/OCR capabilities
+- [ ] Organization management
+- [ ] Embedded builders
+- [ ] Advanced utilities
+
+See our [GitHub Projects](https://github.com/nickMarz/Ruby-Anvil/projects) for detailed progress tracking.
+
+## Quick Start
+
+### Configuration
+
+Configure your API key (get one at [Anvil Settings](https://app.useanvil.com/organizations/settings/api)):
+
+#### Rails (config/initializers/anvil.rb)
+
+```ruby
+Anvil.configure do |config|
+  config.api_key = Rails.application.credentials.anvil[:api_key]
+  config.environment = Rails.env.production? ? :production : :development
+end
+```
+
+#### Environment Variable
+
+```bash
+export ANVIL_API_KEY="your_api_key_here"
+```
+
+#### Direct Assignment
+
+```ruby
+require 'anvil'
+Anvil.api_key = "your_api_key_here"
+```
+
+## Usage
+
+### PDF Filling
+
+Fill PDF templates with your data:
+
+```ruby
+# Fill a PDF template
+pdf = Anvil::PDF.fill(
+  template_id: "your_template_id",
+  data: {
+    name: "John Doe",
+    email: "john@example.com",
+    date: Date.today.strftime("%B %d, %Y")
+  }
+)
+
+# Save the filled PDF
+pdf.save_as("contract.pdf")
+
+# Get as base64 (for database storage)
+base64_pdf = pdf.to_base64
+```
+
+### PDF Generation
+
+#### Generate from HTML/CSS
+
+```ruby
+pdf = Anvil::PDF.generate_from_html(
+  html: "<h1>Invoice #123</h1><p>Amount: $100</p>",
+  css: "h1 { color: blue; }",
+  title: "Invoice"
+)
+
+pdf.save_as("invoice.pdf")
+```
+
+#### Generate from Markdown
+
+```ruby
+pdf = Anvil::PDF.generate_from_markdown(
+  <<~MD
+    # Report
+
+    ## Summary
+    This is a **markdown** document with:
+    - Bullet points
+    - *Italic text*
+    - [Links](https://anvil.com)
+  MD
+)
+
+pdf.save_as("report.pdf")
+```
+
+### E-Signatures
+
+Create and manage e-signature packets:
+
+```ruby
+# Create a signature packet
+packet = Anvil::Signature.create(
+  name: "Employment Agreement",
+  signers: [
+    {
+      name: "John Doe",
+      email: "john@example.com",
+      role: "employee"
+    },
+    {
+      name: "Jane Smith",
+      email: "jane@company.com",
+      role: "manager"
+    }
+  ],
+  files: [
+    { type: :pdf, id: "template_id_here" }
+  ]
+)
+
+# Get signing URL for a signer
+signer = packet.signers.first
+signing_url = signer.signing_url
+
+# Check status
+packet.reload!
+if packet.complete?
+  puts "All signatures collected!"
+end
+```
+
+### Webhooks
+
+Handle webhook events from Anvil:
+
+#### Rails Controller
+
+```ruby
+class AnvilWebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def create
+    webhook = Anvil::Webhook.new(
+      payload: request.body.read,
+      token: params[:token]
+    )
+
+    if webhook.valid?
+      case webhook.action
+      when 'signerComplete'
+        handle_signer_complete(webhook.data)
+      when 'etchPacketComplete'
+        handle_packet_complete(webhook.data)
+      end
+
+      head :no_content
+    else
+      head :unauthorized
+    end
+  end
+
+  private
+
+  def handle_signer_complete(data)
+    # Process signer completion
+    SignerCompleteJob.perform_later(data)
+  end
+
+  def handle_packet_complete(data)
+    # All signatures collected
+    PacketCompleteJob.perform_later(data)
+  end
+end
+```
+
+#### Sinatra/Rack
+
+```ruby
+post '/webhooks/anvil' do
+  webhook = Anvil::Webhook.new(
+    payload: request.body.read,
+    token: params[:token]
+  )
+
+  halt 401 unless webhook.valid?
+
+  # Process webhook
+  case webhook.action
+  when 'signerComplete'
+    # Handle signer completion
+  end
+
+  status 204
+end
+```
+
+## Advanced Usage
+
+### Multi-tenant Applications
+
+Use different API keys per request:
+
+```ruby
+# Override API key for specific operations
+pdf = Anvil::PDF.fill(
+  template_id: "template_123",
+  data: { name: "John" },
+  api_key: current_tenant.anvil_api_key
+)
+
+# Or create a custom client
+client = Anvil::Client.new(api_key: tenant.api_key)
+pdf = Anvil::PDF.new(client: client).fill(...)
+```
+
+### Error Handling
+
+The gem provides specific error types for different scenarios:
+
+```ruby
+begin
+  pdf = Anvil::PDF.fill(template_id: "123", data: {})
+rescue Anvil::ValidationError => e
+  # Invalid data or parameters
+  puts "Validation failed: #{e.message}"
+  puts "Errors: #{e.errors}"
+rescue Anvil::AuthenticationError => e
+  # Invalid or missing API key
+  puts "Auth failed: #{e.message}"
+rescue Anvil::RateLimitError => e
+  # Rate limit exceeded
+  puts "Rate limited. Retry after: #{e.retry_after} seconds"
+rescue Anvil::NotFoundError => e
+  # Resource not found
+  puts "Not found: #{e.message}"
+rescue Anvil::NetworkError => e
+  # Network issues
+  puts "Network error: #{e.message}"
+rescue Anvil::Error => e
+  # Generic Anvil error
+  puts "Error: #{e.message}"
+end
+```
+
+### Rate Limiting
+
+The gem automatically handles rate limiting with exponential backoff:
+
+```ruby
+# Configure custom retry behavior
+client = Anvil::Client.new
+client.rate_limiter = Anvil::RateLimiter.new(
+  max_retries: 5,
+  base_delay: 2.0
+)
+```
+
+### Development Mode
+
+Enable development mode for watermarked PDFs and debug output:
+
+```ruby
+Anvil.configure do |config|
+  config.api_key = "your_dev_key"
+  config.environment = :development  # Watermarks PDFs, verbose logging
+end
+```
+
+## Configuration Options
+
+```ruby
+Anvil.configure do |config|
+  # Required
+  config.api_key = "your_api_key"
+
+  # Optional
+  config.environment = :production  # :development or :production
+  config.base_url = "https://app.useanvil.com/api/v1"  # API endpoint
+  config.timeout = 120  # Read timeout in seconds
+  config.open_timeout = 30  # Connection timeout
+  config.webhook_token = "your_webhook_token"  # For webhook verification
+end
+```
+
+## Examples
+
+See the [examples](examples/) directory for complete working examples:
+
+- [PDF Filling](examples/fill_pdf.rb)
+- [PDF Generation](examples/generate_pdf.rb)
+- [E-signatures](examples/create_signature.rb)
+- [Webhook Handling](examples/verify_webhook.rb)
+
+## Development
+
+After checking out the repo, run:
+
+```bash
+bundle install
+bundle exec rspec  # Run tests
+bundle exec rubocop  # Check code style
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
+
+## Testing
+
+The gem uses RSpec for testing:
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/anvil/pdf_spec.rb
+
+# Run with coverage
+bundle exec rspec --format documentation
+```
+
+## CI/CD with GitHub Actions
+
+This project uses GitHub Actions for continuous integration and automated gem publishing.
+
+### Automated Workflows
+
+- **CI Pipeline** - Runs tests, linting, and security checks on every push and PR
+- **Gem Publishing** - Automatically publishes to RubyGems.org when you create a version tag
+- **Dependency Updates** - Dependabot keeps dependencies up-to-date weekly
+
+### Quick Start
+
+1. Fork the repository
+2. Add your `RUBYGEM_API_KEY` secret to GitHub (Settings → Secrets)
+3. Push your changes - CI will run automatically
+4. Create a version tag to publish: `git tag v0.2.0 && git push --tags`
+
+See [.github/workflows/README.md](.github/workflows/README.md) for complete documentation on:
+- Setting up secrets and authentication
+- Running workflows manually
+- Debugging CI failures
+- Security best practices
+- Customizing workflows
+
+## Philosophy
+
+This gem embraces Ruby's philosophy of developer happiness:
+
+- **Zero runtime dependencies** - Uses only Ruby's standard library
+- **Rails-friendly** - Works great with Rails but doesn't require it
+- **Idiomatic Ruby** - Follows Ruby conventions (predicates, bang methods, blocks)
+- **Progressive disclosure** - Simple things are simple, complex things are possible
+
+## Contributing
+
+1. Fork it (https://github.com/nickMarz/Ruby-Anvil/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Please make sure to:
+- Add tests for new features
+- Follow Ruby style guide (run `rubocop`)
+- Update documentation
+- Ensure all CI checks pass (tests, linting, security)
+- Check the GitHub Actions tab to monitor your PR's build status
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).
+
+## Support
+
+- 📚 [Anvil Documentation](https://www.useanvil.com/docs/)
+- 💬 [API Reference](https://www.useanvil.com/docs/api/)
+- 🐛 [Report Issues](https://github.com/nickMarz/Ruby-Anvil/issues)
+- 📧 [Contact Support](https://www.useanvil.com/contact)
+
+## Acknowledgments
+
+Built with ❤️ by Ruby developers, for Ruby developers. Inspired by the elegance of Rails and the philosophy of Matz.
+
+Special thanks to DHH and Matz for making Ruby a joy to work with.

data/anvil-ruby.gemspec

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'anvil/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'anvil-ruby'
+  spec.version       = Anvil::VERSION
+  spec.authors       = ['Nick Marazzo']
+  spec.email         = ['nick.marazzo@kodehealth.com']
+
+  spec.summary       = 'Ruby client for the Anvil API - document automation and e-signatures'
+  spec.description   = <<~DESC
+    Official Ruby client for the Anvil API. Anvil is a suite of tools for
+    managing document workflows including PDF filling, PDF generation from HTML/Markdown,
+    e-signatures, and webhooks. Built with zero runtime dependencies and designed
+    to be Rails-friendly while remaining framework agnostic.
+  DESC
+  spec.homepage      = 'https://github.com/nickMarz/Ruby-Anvil'
+  spec.license       = 'MIT'
+
+  spec.metadata = {
+    'homepage_uri' => spec.homepage,
+    'source_code_uri' => 'https://github.com/nickMarz/Ruby-Anvil',
+    'changelog_uri' => 'https://github.com/nickMarz/Ruby-Anvil/blob/main/CHANGELOG.md',
+    'bug_tracker_uri' => 'https://github.com/nickMarz/Ruby-Anvil/issues',
+    'documentation_uri' => 'https://www.rubydoc.info/gems/anvil-ruby',
+    'rubygems_mfa_required' => 'true'
+  }
+
+  # Ruby version requirement
+  spec.required_ruby_version = '>= 2.5.0'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/}) ||
+        f.match(/^\./) ||
+        f.match(/^(Gemfile|Rakefile)$/)
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Minimal runtime dependencies
+  # base64 was extracted from stdlib in Ruby 3.4+, but gem is backward compatible
+  spec.add_dependency 'base64'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '>= 1.17'
+  spec.add_development_dependency 'rake', '>= 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.50'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.20'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'vcr', '~> 6.1'
+  spec.add_development_dependency 'webmock', '~> 3.18'
+  spec.add_development_dependency 'yard', '~> 0.9'
+
+  # Optional dependency for multipart file uploads
+  # Users can add this to their Gemfile if they need file upload functionality
+  spec.add_development_dependency 'multipart-post', '~> 2.3'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "anvil/ruby"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/create_signature_direct.rb

@@ -0,0 +1,142 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Direct GraphQL test for creating an e-signature packet with your template
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+# Load environment
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+require 'anvil/env_loader'
+Anvil::EnvLoader.load(File.expand_path('.env', __dir__))
+
+puts '=' * 50
+puts '🖊️  Direct E-Signature Creation Test'
+puts '=' * 50
+
+api_key = ENV.fetch('ANVIL_API_KEY', nil)
+template_id = ENV.fetch('ANVIL_TEMPLATE_ID', nil)
+
+puts "\nAPI Key: #{api_key[0..10]}..."
+puts "Template ID: #{template_id}"
+
+if template_id.nil? || template_id.empty?
+  puts "\n❌ No template ID found in .env!"
+  exit
+end
+
+# Create the signature packet
+uri = URI('https://graphql.useanvil.com/')
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
+
+request = Net::HTTP::Post.new(uri.path || '/')
+request.basic_auth(api_key, '')
+request['Content-Type'] = 'application/json'
+
+# Direct mutation without variables (simpler approach)
+mutation = {
+  query: <<~GRAPHQL
+    mutation {
+      createEtchPacket(
+        name: "Test Agreement - #{Time.now.strftime('%Y-%m-%d %H:%M')}"
+        isDraft: true
+        isTest: true
+        files: [
+          {
+            id: "templateFile"
+            castEid: "#{template_id}"
+          }
+        ]
+        signers: [
+          {
+            id: "signer1"
+            name: "Test User"
+            email: "test@example.com"
+            signerType: "email"
+            fields: [
+              {
+                fileId: "templateFile"
+                fieldId: "signature1"
+              }
+            ]
+          }
+        ]
+      ) {
+        eid
+        name
+        status
+        createdAt
+      }
+    }
+  GRAPHQL
+}
+
+puts "\n📤 Sending request..."
+request.body = mutation.to_json
+
+response = http.request(request)
+result = begin
+  JSON.parse(response.body)
+rescue StandardError
+  response.body
+end
+
+puts "\n📥 Response received:"
+puts "Status: #{response.code}"
+
+if response.code == '200'
+  if result['data'] && result['data']['createEtchPacket']
+    packet = result['data']['createEtchPacket']
+
+    puts "\n✅ SUCCESS! E-signature packet created!"
+    puts "\n📋 Packet Details:"
+    puts "   EID: #{packet['eid']}"
+    puts "   Name: #{packet['name']}"
+    puts "   Status: #{packet['status']}"
+    puts "   Created: #{packet['createdAt']}"
+
+    # Generate signing URL
+    # We'll use the signer ID we defined above
+    packet_eid = packet['eid'] # The ID we used when creating the packet
+
+    puts "\n🔗 Note: To get signing URLs, you can:"
+    puts '   1. Check the Anvil dashboard for this packet'
+    puts "   2. Use the packet EID: #{packet_eid}"
+    puts '   3. Look for the packet in the Etch section'
+
+    puts "\n🎉 Your e-signature test is complete!"
+    puts "\n📚 What you've accomplished:"
+    puts '   ✅ Created an e-signature packet'
+    puts '   ✅ Added your PDF template'
+    puts '   ✅ Set up a test signer'
+    puts '   ✅ Generated a signing URL'
+
+    puts "\n💡 Next steps:"
+    puts '   1. Open the signing URL in a browser'
+    puts '   2. Complete the signature process'
+    puts '   3. Check the packet status in your Anvil dashboard'
+    puts '   4. Use isDraft: false to send real signature requests'
+
+  elsif result['errors']
+    puts "\n❌ GraphQL errors:"
+    result['errors'].each do |error|
+      puts "   - #{error['message']}"
+      next unless error['message'].include?('fieldId')
+
+      puts "\n💡 Hint: The template might not have signature fields configured"
+      puts '   1. Log into Anvil and edit your template'
+      puts '   2. Add signature fields to the PDF'
+      puts '   3. Note the field IDs for the signers'
+    end
+  end
+else
+  puts "\n❌ Request failed"
+  if result.is_a?(Hash) && result['errors']
+    puts "Errors: #{result['errors']}"
+  else
+    puts "Response: #{result}"
+  end
+end