RubyGems - anvil-ruby - Versions diffs - 0.1.0 - Mend

anvil-ruby 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

checksums.yaml +7 -0
data/AGENTS.md +123 -0
data/API_COVERAGE.md +294 -0
data/CHANGELOG.md +34 -0
data/CLAUDE_README.md +98 -0
data/GITHUB_ACTIONS_QUICKREF.md +174 -0
data/Gemfile.lock +112 -0
data/Gemfile.minimal +9 -0
data/LICENSE +21 -0
data/PROJECT_CONTEXT.md +196 -0
data/README.md +445 -0
data/anvil-ruby.gemspec +66 -0
data/bin/console +14 -0
data/bin/setup +8 -0
data/create_signature_direct.rb +142 -0
data/create_signature_packet.rb +232 -0
data/debug_env.rb +28 -0
data/examples/create_signature.rb +194 -0
data/examples/fill_pdf.rb +89 -0
data/examples/generate_pdf.rb +347 -0
data/examples/verify_webhook.rb +281 -0
data/lib/anvil/client.rb +216 -0
data/lib/anvil/configuration.rb +87 -0
data/lib/anvil/env_loader.rb +30 -0
data/lib/anvil/errors.rb +95 -0
data/lib/anvil/rate_limiter.rb +66 -0
data/lib/anvil/resources/base.rb +100 -0
data/lib/anvil/resources/pdf.rb +171 -0
data/lib/anvil/resources/signature.rb +517 -0
data/lib/anvil/resources/webform.rb +154 -0
data/lib/anvil/resources/webhook.rb +201 -0
data/lib/anvil/resources/workflow.rb +169 -0
data/lib/anvil/response.rb +98 -0
data/lib/anvil/version.rb +5 -0
data/lib/anvil.rb +88 -0
data/quickstart_signature.rb +220 -0
data/test_api_connection.rb +143 -0
data/test_etch_signature.rb +230 -0
data/test_gem.rb +72 -0
data/test_signature.rb +281 -0
data/test_signature_with_template.rb +112 -0
metadata +247 -0

data/create_signature_packet.rb ADDED Viewed

@@ -0,0 +1,232 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# Create an Anvil E-Signature Packet
+# Based on the official Anvil API documentation
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+require 'anvil'
+require 'anvil/env_loader'
+require 'net/http'
+require 'uri'
+require 'json'
+require 'base64'
+# Load .env file
+Anvil::EnvLoader.load(File.expand_path('.env', __dir__))
+puts '=' * 50
+puts 'Anvil E-Signature Packet Creation'
+puts '=' * 50
+api_key = ENV.fetch('ANVIL_API_KEY', nil)
+puts "\nUsing API Key: #{api_key[0..10]}..."
+# Step 1: Create a simple PDF to use for signing
+def create_test_pdf(api_key)
+  puts "\n📄 Creating a test PDF document..."
+  uri = URI('https://app.useanvil.com/api/v1/generate-pdf')
+  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'
+  html = <<~HTML
+    <!DOCTYPE html>
+    <html>
+    <body style="padding: 40px; font-family: Arial;">
+      <h1>Test Agreement</h1>
+      <p>This is a test document for e-signature.</p>
+      <p>I, the undersigned, agree to the terms of this test agreement.</p>
+      <div style="margin-top: 100px; border-top: 2px solid black; width: 300px; padding-top: 10px;">
+        Signature
+      </div>
+      <div style="margin-top: 50px; border-top: 2px solid black; width: 300px; padding-top: 10px;">
+        Date
+      </div>
+    </body>
+    </html>
+  HTML
+  request.body = {
+    type: 'html',
+    data: {
+      html: html,
+      css: 'body { font-size: 14px; }'
+    }
+  }.to_json
+  response = http.request(request)
+  if response.code == '200'
+    puts '   ✅ PDF created successfully'
+    response.body # Return the PDF binary data
+  else
+    puts "   ❌ Failed to create PDF: #{response.code}"
+    nil
+  end
+end
+# Step 2: Create an e-signature packet using REST API (simpler than GraphQL)
+def create_etch_packet_rest(api_key, _pdf_data = nil)
+  puts "\n📝 Creating e-signature packet via REST API..."
+  # For now, create a simple packet without a file
+  # In production, you'd upload the PDF or use a template
+  uri = URI('https://app.useanvil.com/api/v1/etch-packets')
+  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'
+  # Basic packet structure
+  packet_data = {
+    name: "Test Agreement #{Time.now.strftime('%Y-%m-%d %H:%M')}",
+    isDraft: false,
+    isTest: true, # Test mode - won't send real emails
+    signers: [
+      {
+        id: 'signer1',
+        name: 'Test User',
+        email: 'test@example.com',
+        signerType: 'email'
+      }
+    ]
+  }
+  request.body = packet_data.to_json
+  response = http.request(request)
+  result = begin
+    JSON.parse(response.body)
+  rescue StandardError
+    response.body
+  end
+  if %w[200 201].include?(response.code)
+    puts '   ✅ Packet created successfully!'
+    if result.is_a?(Hash)
+      puts "   Packet ID: #{result['eid'] || result['id']}"
+      puts "   Status: #{result['status']}"
+    end
+    result
+  else
+    puts "   ❌ Failed to create packet: #{response.code}"
+    puts "   Response: #{result}"
+    nil
+  end
+rescue StandardError => e
+  puts "   ❌ Error: #{e.message}"
+  nil
+end
+# Step 3: Try GraphQL mutation with correct structure
+def create_etch_packet_graphql(api_key)
+  puts "\n📝 Creating e-signature packet via GraphQL..."
+  uri = URI('https://app.useanvil.com/graphql')
+  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'
+  # GraphQL mutation based on docs
+  mutation = {
+    query: <<~GRAPHQL,
+      mutation CreateEtchPacket($variables: JSON) {
+        createEtchPacket(variables: $variables) {
+          eid
+          name
+          status
+        }
+      }
+    GRAPHQL
+    variables: {
+      variables: {
+        name: "Test Agreement via GraphQL #{Time.now.to_i}",
+        isDraft: false,
+        isTest: true,
+        signers: [
+          {
+            id: 'signer1',
+            name: 'Test Signer',
+            email: 'test@example.com',
+            signerType: 'email'
+          }
+        ]
+      }
+    }
+  }
+  request.body = mutation.to_json
+  response = http.request(request)
+  result = begin
+    JSON.parse(response.body)
+  rescue StandardError
+    response.body
+  end
+  if response.code == '200'
+    if result['data'] && result['data']['createEtchPacket']
+      packet = result['data']['createEtchPacket']
+      puts '   ✅ Packet created via GraphQL!'
+      puts "   EID: #{packet['eid']}"
+      puts "   Name: #{packet['name']}"
+      puts "   Status: #{packet['status']}"
+      packet
+    else
+      puts '   ⚠️  GraphQL returned no data'
+      puts "   Errors: #{result['errors']}" if result['errors']
+      nil
+    end
+  else
+    puts "   ❌ GraphQL request failed: #{response.code}"
+    puts "   Response: #{result}"
+    nil
+  end
+rescue StandardError => e
+  puts "   ❌ Error: #{e.message}"
+  nil
+end
+# Main execution
+puts "\nAttempting to create an e-signature packet..."
+# Try REST API first (usually simpler)
+packet = create_etch_packet_rest(api_key)
+# Also try GraphQL
+graphql_packet = create_etch_packet_graphql(api_key)
+puts "\n#{'=' * 50}"
+puts 'Summary'
+puts '=' * 50
+if packet || graphql_packet
+  puts '✅ Successfully created e-signature packet!'
+  puts "\n📚 Next steps:"
+  puts '1. Log into Anvil: https://app.useanvil.com'
+  puts '2. Navigate to the Etch section'
+  puts '3. View your test packets'
+  puts '4. Get signing URLs for the signers'
+  puts "\n💡 Note: Since we used isTest: true, no emails were sent"
+else
+  puts "⚠️  Couldn't create a signature packet"
+  puts "\n💡 Troubleshooting:"
+  puts '1. Check if your API key has e-signature permissions'
+  puts '2. Try creating a packet manually in the Anvil UI first'
+  puts '3. Check the Anvil documentation for required fields'
+  puts '   https://www.useanvil.com/docs/api/e-signatures'
+end

data/debug_env.rb ADDED Viewed

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+$LOAD_PATH.unshift File.expand_path('lib', __dir__)
+require 'anvil/env_loader'
+puts 'Before loading .env:'
+puts "ANVIL_API_KEY = #{ENV['ANVIL_API_KEY'].inspect}"
+path = File.expand_path('.env', __dir__)
+puts "\nLoading from: #{path}"
+puts "File exists? #{File.exist?(path)}"
+if File.exist?(path)
+  puts "\n.env contents:"
+  File.readlines(path).each_with_index do |line, i|
+    puts "  Line #{i + 1}: #{line.inspect}"
+    if line =~ /\A([A-Z_][A-Z0-9_]*)\s*=\s*(.*)\z/
+      puts "    -> Matched! Key: #{Regexp.last_match(1)}, Value: #{Regexp.last_match(2)[0..20]}..."
+    end
+  end
+end
+puts "\nCalling Anvil::EnvLoader.load..."
+Anvil::EnvLoader.load(path)
+puts "\nAfter loading .env:"
+puts "ANVIL_API_KEY = #{ENV['ANVIL_API_KEY'] ? "#{ENV['ANVIL_API_KEY'][0..15]}..." : 'NOT SET'}"

data/examples/create_signature.rb ADDED Viewed

@@ -0,0 +1,194 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+require 'bundler/setup'
+require 'anvil'
+# Example: Create and manage e-signature packets
+#
+# This example demonstrates how to:
+# 1. Create an e-signature packet
+# 2. Add signers
+# 3. Generate signing URLs
+# 4. Check signature status
+# Configure Anvil
+Anvil.configure do |config|
+  config.api_key = ENV.fetch('ANVIL_API_KEY', nil)
+  config.environment = :development
+end
+# Example: Create a signature packet for an employment agreement
+def create_employment_agreement
+  puts '📝 Creating e-signature packet for employment agreement...'
+  # Create the signature packet
+  packet = Anvil::Signature.create(
+    name: 'Employment Agreement - John Doe',
+    # Define signers
+    signers: [
+      {
+        name: 'John Doe',
+        email: 'john.doe@example.com',
+        role: 'employee',
+        signer_type: 'email' # Email-based signing
+      },
+      {
+        name: 'Jane Smith',
+        email: 'jane.smith@company.com',
+        role: 'hr_manager',
+        signer_type: 'email'
+      }
+    ],
+    # Specify files to sign (using a PDF template)
+    files: [
+      {
+        type: :pdf,
+        id: 'your_template_id_here' # Replace with your PDF template ID
+      }
+    ],
+    # Optional: Set as draft first (signers won't be notified yet)
+    is_draft: true,
+    # Optional: Custom email settings
+    email_subject: 'Please sign your employment agreement',
+    email_body: 'Dear {{signerName}}, Please review and sign the attached employment agreement. Thank you!',
+    # Optional: Webhook URL for status updates
+    webhook_url: 'https://yourapp.com/webhooks/anvil'
+  )
+  puts '✅ Signature packet created!'
+  puts "📋 Packet ID: #{packet.eid}"
+  puts "📊 Status: #{packet.status}"
+  puts "👥 Signers: #{packet.signers.count}"
+  packet
+end
+# Example: Get signing URLs for signers
+def generate_signing_urls(packet)
+  puts "\n🔗 Generating signing URLs..."
+  packet.signers.each do |signer|
+    url = signer.signing_url(
+      client_user_id: "user_#{signer.email}" # Optional: Your internal user ID
+    )
+    puts "\n👤 Signer: #{signer.name} (#{signer.email})"
+    puts "📊 Status: #{signer.status}"
+    puts "🔗 Signing URL: #{url}"
+    puts '   Send this URL to the signer to complete their signature'
+  end
+end
+# Example: Check signature packet status
+def check_packet_status(packet_eid)
+  puts "\n🔍 Checking packet status..."
+  # Reload the packet to get latest status
+  packet = Anvil::Signature.find(packet_eid)
+  puts "📋 Packet: #{packet.name}"
+  puts "📊 Overall Status: #{packet.status}"
+  # Check individual signer status
+  packet.signers.each do |signer|
+    status_emoji = case signer.status
+                   when 'complete' then '✅'
+                   when 'sent' then '📧'
+                   when 'viewed' then '👀'
+                   else '⏳'
+                   end
+    puts "#{status_emoji} #{signer.name}: #{signer.status}"
+    puts "   Completed at: #{signer.completed_at}" if signer.complete?
+  end
+  # Check if entire packet is complete
+  if packet.complete?
+    puts "\n🎉 All signatures collected!"
+    # You can now download the signed documents
+  elsif packet.partially_complete?
+    puts "\n⏳ Waiting for remaining signatures..."
+  end
+  packet
+end
+# Example: List all signature packets
+def list_signature_packets
+  puts "\n📑 Listing signature packets..."
+  packets = Anvil::Signature.list(
+    limit: 10,
+    status: 'sent' # Filter by status (optional)
+  )
+  if packets.empty?
+    puts 'No signature packets found'
+  else
+    packets.each do |packet|
+      puts "\n📋 #{packet.name}"
+      puts "   ID: #{packet.eid}"
+      puts "   Status: #{packet.status}"
+      puts "   Created: #{packet.created_at}"
+    end
+  end
+end
+# Example: Send reminders (by recreating signing URLs)
+def send_reminder(packet)
+  puts "\n📧 Sending reminders to incomplete signers..."
+  packet.signers.each do |signer|
+    next if signer.complete?
+    url = signer.signing_url
+    puts "🔔 Reminder for #{signer.name} (#{signer.email})"
+    puts "   Signing URL: #{url}"
+    # In a real application, you would send an email here
+    # using your email service (ActionMailer, SendGrid, etc.)
+  end
+end
+# Run the example
+begin
+  puts '=' * 50
+  puts 'Anvil E-Signature Example'
+  puts '=' * 50
+  # Create a new signature packet
+  packet = create_employment_agreement
+  # Generate signing URLs
+  generate_signing_urls(packet)
+  # Simulate checking status after some time
+  puts "\n⏰ (In a real app, you'd check this later...)"
+  check_packet_status(packet.eid)
+  # List all packets
+  list_signature_packets
+  # Send reminders if needed
+  send_reminder(packet) if packet.in_progress?
+  puts "\n✅ E-signature example completed!"
+rescue Anvil::ValidationError => e
+  puts "❌ Validation error: #{e.message}"
+  puts "Errors: #{e.errors.inspect}" if e.errors.any?
+rescue Anvil::AuthenticationError => e
+  puts "❌ Authentication failed: #{e.message}"
+  puts 'Please check your API key'
+rescue Anvil::Error => e
+  puts "❌ Anvil error: #{e.message}"
+rescue StandardError => e
+  puts "❌ Unexpected error: #{e.message}"
+  puts e.backtrace.first(5)
+end

data/examples/fill_pdf.rb ADDED Viewed

@@ -0,0 +1,89 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+# Add lib to the load path if running directly
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'anvil'
+# Example: Fill a PDF template with data
+#
+# This example demonstrates how to fill a PDF template with JSON data.
+# You'll need:
+# 1. An Anvil API key (set as ANVIL_API_KEY environment variable)
+# 2. A PDF template ID from your Anvil account
+# Configure Anvil (optional if using ENV var)
+Anvil.configure do |config|
+  config.api_key = ENV.fetch('ANVIL_API_KEY', nil)
+  config.environment = :development # Use development for testing
+end
+# Template ID - replace with your actual template ID
+TEMPLATE_ID = 'your_template_id_here'
+# Sample data to fill the PDF
+# Keys should match the field aliases in your PDF template
+pdf_data = {
+  # Basic fields
+  name: 'John Doe',
+  email: 'john.doe@example.com',
+  phone: '(555) 123-4567',
+  # Address
+  address: '123 Main Street',
+  city: 'San Francisco',
+  state: 'CA',
+  zip_code: '94102',
+  # Date fields
+  date: Date.today.strftime('%B %d, %Y'),
+  # Checkboxes (use true/false)
+  agree_to_terms: true,
+  subscribe_newsletter: false,
+  # Additional fields (customize based on your template)
+  company: 'Acme Corp',
+  position: 'Software Engineer',
+  salary: '$120,000',
+  start_date: '2024-02-01'
+}
+begin
+  puts "Filling PDF template: #{TEMPLATE_ID}"
+  puts "With data: #{pdf_data.keys.join(', ')}"
+  # Fill the PDF
+  pdf = Anvil::PDF.fill(
+    template_id: TEMPLATE_ID,
+    data: pdf_data,
+    # Optional parameters
+    title: 'Employment Agreement',
+    font_size: 10,
+    text_color: '#333333'
+  )
+  # Save the filled PDF
+  filename = "filled_pdf_#{Time.now.to_i}.pdf"
+  pdf.save_as(filename)
+  puts '✅ PDF filled successfully!'
+  puts "📄 Saved as: #{filename}"
+  puts "📏 Size: #{pdf.size_human}"
+  # You can also get the PDF as base64 for storing in a database
+  # base64_pdf = pdf.to_base64
+  # puts "Base64 length: #{base64_pdf.length}" if base64_pdf
+rescue Anvil::ValidationError => e
+  puts "❌ Validation error: #{e.message}"
+  puts "Errors: #{e.errors.inspect}" if e.errors.any?
+rescue Anvil::AuthenticationError => e
+  puts "❌ Authentication failed: #{e.message}"
+  puts 'Please check your API key'
+rescue Anvil::Error => e
+  puts "❌ Anvil error: #{e.message}"
+rescue StandardError => e
+  puts "❌ Unexpected error: #{e.message}"
+  puts e.backtrace.first(5)
+end