anvil-ruby 0.1.0

data/GITHUB_ACTIONS_QUICKREF.md

@@ -0,0 +1,174 @@
+# GitHub Actions Quick Reference
+
+## 🚀 Common Tasks
+
+### Publishing a New Version
+
+```bash
+# 1. Update version in lib/anvil/version.rb
+# 2. Update CHANGELOG.md
+# 3. Commit and tag
+git add -A
+git commit -m "Release v0.2.0"
+git tag v0.2.0
+git push origin main --tags
+
+# The gem will automatically be published to RubyGems
+```
+
+### Running CI Locally
+
+```bash
+# Run all checks that CI runs
+bundle exec rubocop           # Linting
+bundle exec rspec             # Tests
+bundle-audit check --update   # Security audit
+gem build *.gemspec          # Build gem
+```
+
+### Debugging Failed Builds
+
+```bash
+# View GitHub Actions logs
+# 1. Go to: https://github.com/nickMarz/Ruby-Anvil/actions
+# 2. Click on the failed workflow run
+# 3. Click on the failed job to see logs
+
+# Run specific Ruby version locally (using rbenv)
+rbenv install 3.2.0
+rbenv local 3.2.0
+bundle install
+bundle exec rspec
+
+# Run with verbose output
+bundle exec rspec --format documentation --backtrace
+```
+
+### Manual Workflow Triggers
+
+```bash
+# Using GitHub CLI
+gh workflow run ci.yml --ref main
+gh workflow run gem-push.yml --ref main
+
+# Or use the GitHub UI:
+# Actions tab → Select workflow → Run workflow
+```
+
+## 📋 Required Secrets
+
+| Secret | Where to Get | Required For |
+|--------|--------------|--------------|
+| `RUBYGEM_API_KEY` | [rubygems.org/profile/api_keys](https://rubygems.org/profile/api_keys) | Publishing gems |
+| `ANVIL_API_KEY` | Anvil Dashboard | Running tests (optional) |
+
+## 🔧 Workflow Files
+
+| File | Purpose | Triggers |
+|------|---------|----------|
+| `.github/workflows/ci.yml` | Tests, linting, security | Push, PR |
+| `.github/workflows/gem-push.yml` | Publish to RubyGems | Version tags |
+| `.github/dependabot.yml` | Dependency updates | Weekly |
+
+## 🏷️ Version Tags
+
+```bash
+# Create a version tag
+git tag v0.2.0
+
+# Push tag to trigger gem publication
+git push origin v0.2.0
+
+# List all tags
+git tag -l
+
+# Delete a tag (if needed)
+git tag -d v0.2.0
+git push origin :refs/tags/v0.2.0
+```
+
+## 🔍 Status Checks
+
+Before merging PRs, ensure these checks pass:
+- ✅ Lint (RuboCop)
+- ✅ Test (Ruby 2.7, 3.0, 3.1, 3.2, 3.3)
+- ✅ Build
+- ✅ Security
+
+## 🆘 Troubleshooting
+
+### RubyGems Publication Failed
+```bash
+# Check if secret is set
+# Settings → Secrets → Actions → RUBYGEM_API_KEY
+
+# Verify API key permissions at rubygems.org
+# Should have "Push rubygems" scope
+
+# Test locally
+gem push *.gem --key your_api_key
+```
+
+### Tests Pass Locally but Fail in CI
+```bash
+# Check Ruby version
+ruby -v
+
+# Check for environment variables
+env | grep ANVIL
+
+# Use same bundler version
+gem install bundler -v $(grep -A 1 "BUNDLED WITH" Gemfile.lock | tail -1 | tr -d ' ')
+```
+
+### Rate Limiting Issues
+```yaml
+# Add to workflow if experiencing issues
+- name: Wait to avoid rate limits
+  run: sleep 60
+```
+
+## 📊 Monitoring
+
+- **Actions Dashboard**: [github.com/nickMarz/Ruby-Anvil/actions](https://github.com/nickMarz/Ruby-Anvil/actions)
+- **Workflow Usage**: Settings → Billing & plans → Usage this month
+- **Dependabot PRs**: Pull requests → Filter: `author:app/dependabot`
+
+## 🔐 Security
+
+```bash
+# Run security audit locally
+bundle-audit check --update
+
+# Update vulnerable gems
+bundle update gem_name
+
+# Check for leaked secrets
+# Never commit .env or credentials files!
+git secrets --scan
+```
+
+## 📝 Useful Commands
+
+```bash
+# See all GitHub CLI workflow commands
+gh workflow --help
+
+# List all workflows
+gh workflow list
+
+# View recent runs
+gh run list
+
+# Watch a run in progress
+gh run watch
+
+# View workflow file
+gh workflow view ci.yml
+
+# Download artifacts
+gh run download [run-id]
+```
+
+---
+*For detailed documentation, see [.github/workflows/README.md](.github/workflows/README.md)*

data/Gemfile.lock

@@ -0,0 +1,112 @@
+PATH
+  remote: .
+  specs:
+    anvil-ruby (0.1.0)
+      base64
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.8)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.0.1)
+    crack (1.0.1)
+      bigdecimal
+      rexml
+    diff-lcs (1.6.2)
+    docile (1.4.1)
+    hashdiff (1.2.1)
+    json (2.18.0)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    multipart-post (2.4.1)
+    parallel (1.27.0)
+    parser (3.3.10.1)
+      ast (~> 2.4.1)
+      racc
+    prism (1.8.0)
+    public_suffix (5.1.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rexml (3.4.4)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.7)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.6)
+    rubocop (1.82.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.48.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-capybara (2.22.1)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-factory_bot (2.28.0)
+      lint_roller (~> 1.1)
+      rubocop (~> 1.72, >= 1.72.1)
+    rubocop-rspec (2.31.0)
+      rubocop (~> 1.40)
+      rubocop-capybara (~> 2.17)
+      rubocop-factory_bot (~> 2.22)
+      rubocop-rspec_rails (~> 2.28)
+    rubocop-rspec_rails (2.29.1)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.13.2)
+    simplecov_json_formatter (0.1.4)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    vcr (6.4.0)
+    webmock (3.26.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.38)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  anvil-ruby!
+  bundler (>= 1.17)
+  multipart-post (~> 2.3)
+  public_suffix (~> 5.0)
+  rake (>= 10.0)
+  rspec (~> 3.12)
+  rubocop (~> 1.50)
+  rubocop-rspec (~> 2.20)
+  simplecov (~> 0.22)
+  vcr (~> 6.1)
+  webmock (~> 3.18)
+  yard (~> 0.9)
+
+BUNDLED WITH
+   2.3.27

data/Gemfile.minimal

@@ -0,0 +1,9 @@
+source 'https://rubygems.org'
+
+# Just the gem itself - no dev dependencies for now
+gemspec
+
+# Minimal test dependencies
+group :test do
+  gem 'rspec', '~> 3.0'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nick Marazzo
+
+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/PROJECT_CONTEXT.md

@@ -0,0 +1,196 @@
+# Anvil Ruby Gem - Project Context
+
+## 🎯 Project Overview
+Building a Ruby gem for the Anvil API (document automation and e-signatures) following Ruby best practices inspired by DHH and Matz.
+
+**Repository:** https://github.com/nickMarz/Ruby-Anvil
+**Current Version:** 0.1.0
+**API Coverage:** ~30% implemented
+**Ruby Version:** 3.4.8 (via rbenv)
+**Development Approach:** Zero runtime dependencies using Net::HTTP
+
+## 📁 Key Files & Locations
+
+### Core Files
+- `/Users/Nick.Marazzo/Documents/GitHub/anvil-ruby/` - Project root
+- `.env` - Contains `ANVIL_API_KEY` and `ANVIL_TEMPLATE_ID`
+- `.ruby-version` - Ruby 3.4.8
+- `API_COVERAGE.md` - Comprehensive feature tracking (70% missing features documented)
+- `PROJECT_CONTEXT.md` - This file (project reference)
+
+### Implementation Files
+- `lib/anvil.rb` - Main entry point with configuration
+- `lib/anvil/resources/pdf.rb` - PDF operations (fill, generate)
+- `lib/anvil/resources/signature.rb` - E-signature implementation with GraphQL
+- `lib/anvil/resources/webhook.rb` - Webhook parsing and verification
+- `lib/anvil/env_loader.rb` - Custom .env loader (avoiding dependencies)
+- `lib/anvil/client.rb` - HTTP client with rate limiting
+
+### Test Scripts
+- `create_signature_direct.rb` - Direct GraphQL test (successfully created packet)
+- `test_signature_with_template.rb` - Template-based signature test
+- `test_etch_signature.rb` - E-signature connection testing
+
+## 🚀 Current Implementation Status
+
+### ✅ Implemented (30% of API)
+1. **PDF Operations**
+   - `PDF.fill` - Fill templates with JSON data
+   - `PDF.generate` - Generate from HTML/CSS or Markdown
+   - Save as file or base64
+
+2. **E-Signatures (Basic)**
+   - `Signature.create` - Create packets
+   - `Signature.find` - Find by ID
+   - `Signature.list` - List packets
+   - Signing URL generation
+   - Draft mode support
+
+3. **Webhooks**
+   - `Webhook.new` - Parse payloads
+   - `Webhook.valid?` - Verify authenticity
+   - Constant-time token validation
+
+4. **Infrastructure**
+   - Flexible API key configuration (3 methods)
+   - Rate limiting with exponential backoff
+   - Environment management (dev/production)
+   - Error handling with specific exception types
+
+### ❌ Missing (70% of API) - Tracked in GitHub
+
+## 📋 GitHub Organization
+
+### Milestones (3 phases)
+1. **Phase 1: Core Features (v0.2.0)** - Essential functionality
+2. **Phase 2: Advanced Features (v0.3.0)** - Advanced capabilities
+3. **Phase 3: AI & Enterprise (v0.4.0)** - AI and enterprise features
+
+### Issues Created (20 total)
+- **8 parent issues** (#1-8) - High-level features
+- **12 sub-issues** (#9-20) - Detailed implementation tasks
+
+### Project Board
+- **URL:** https://github.com/users/nickMarz/projects/1
+- **Name:** Anvil Ruby Gem Roadmap
+- Linked to Ruby-Anvil repository
+- Contains all 20 issues for tracking
+
+### Issue Breakdown
+
+#### Phase 1 Issues
+- #1: Generic GraphQL support
+- #2: Complete e-signature features
+  - #9: Update packet mutation
+  - #10: Send packet from draft
+  - #11: Delete packet
+  - #12: Signer management
+  - #13: Void and expire operations
+- #3: Basic workflow support
+  - #17: Workflow creation and retrieval
+  - #18: Workflow data submission
+- #4: Basic webform support
+  - #19: Form creation and configuration
+  - #20: Form submission handling
+
+#### Phase 2 Issues
+- #5: Cast (PDF Template) management
+- #6: Webhook management API
+  - #14: Webhook CRUD operations
+  - #15: Webhook actions management
+  - #16: Webhook logs and retry
+
+#### Phase 3 Issues
+- #7: Document AI/OCR capabilities
+- #8: Organization management features
+
+## 🔧 Technical Details
+
+### API Endpoints
+- REST API: `https://app.useanvil.com/api/v1/`
+- GraphQL: `https://graphql.useanvil.com/` (NOTE: Full URL required, not just `/graphql`)
+
+### Authentication
+- Basic Auth with API key as username, empty password
+- Per-request API key override supported for multi-tenancy
+
+### Key Implementation Patterns
+```ruby
+# Resource-based architecture (ActiveResource style)
+class Signature < Resources::Base
+  def self.create(name:, signers:, files:, **options)
+    # GraphQL mutation implementation
+  end
+end
+
+# Flexible API key configuration
+Anvil.api_key = "key"                    # Direct
+ENV['ANVIL_API_KEY'] = "key"            # Environment
+config.api_key = "key"                   # Rails initializer
+
+# Zero dependencies approach
+# Using Net::HTTP instead of external HTTP gems
+# Custom .env loader instead of dotenv gem
+```
+
+### GraphQL Mutations Structure
+```ruby
+# Direct mutation parameters (not nested variables)
+mutation = {
+  query: <<~GRAPHQL
+    mutation {
+      createEtchPacket(
+        name: "Test",
+        isDraft: true,
+        signers: [...]
+      ) { ... }
+    }
+  GRAPHQL
+}
+```
+
+## 🐛 Known Issues & Fixes Applied
+
+1. **Ruby 3.4+ base64 extraction** - Added as explicit dependency
+2. **EnvLoader regex bug** - Fixed with `line.chomp`
+3. **GraphQL endpoint** - Must use full URL: `https://graphql.useanvil.com/`
+4. **HTTP path issue** - Include trailing slash in URI
+5. **Bundler compatibility** - Changed from `~> 2.0` to `>= 1.17`
+
+## 📝 Environment Variables
+- `ANVIL_API_KEY` - Your Anvil API key
+- `ANVIL_TEMPLATE_ID` - Template EID for testing (JlLOtzZKVNA1Mljsu999od)
+
+## 🎯 Next Steps
+1. Start with Issue #1 (Generic GraphQL support) as foundation
+2. Work through Phase 1 issues to reach v0.2.0
+3. Each sub-issue can be a separate PR
+4. Maintain zero dependencies principle
+5. Keep idiomatic Ruby style (predicates, bang methods)
+
+## 💡 Important Notes
+- Gem follows Rails conventions but doesn't require Rails
+- Emphasizes developer happiness (Matz's philosophy)
+- Progressive disclosure: simple things simple, complex possible
+- All new features should be additive (no breaking changes)
+- Maintain comprehensive tests with RSpec
+- Document with YARD comments
+
+## 📚 References
+- [Anvil API Docs](https://www.useanvil.com/docs/)
+- [GraphQL Reference](https://www.useanvil.com/docs/api/graphql/reference/)
+- [GraphQL Schema](https://app.useanvil.com/graphql/sdl) (requires auth)
+- [Ruby Gems Guide](https://guides.rubygems.org/make-your-own-gem/)
+
+## 🔄 Session Start Checklist
+When starting a new session:
+1. Check this file for context
+2. Review `API_COVERAGE.md` for missing features
+3. Check GitHub project board for current status
+4. Verify environment with `ruby -v` (should be 3.4.8)
+5. Ensure .env has API keys loaded
+6. Run `bundle install` if needed
+
+---
+*Last Updated: January 2024*
+*Created for quick context when starting new Claude sessions*