anvil-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 35685b6026edc34da7112bf2148651c92eb600741ebe34db0837cc83ef767754
+  data.tar.gz: 0b1cf1ec708c52f2820b6ad09423285d861fb2df103cc4122d5753fc1d42f11a
+SHA512:
+  metadata.gz: eb8601c7824304fedc9d6be300dfc593ed764fccf9cc529b9b7cf283fee6a5bce85f4ff9e9e07573fd3dc496ea97a8c18379eb38bbbbe9e3455b198e6e127396
+  data.tar.gz: 8fcb0f0e5c1d3662b7dbc79391cadda9962c52723803027cdd19b8dc655944acadf34baff6333fe8baa3dcb9404d4eb46735f0c553ecda6f1ce701fe2619a6b0

data/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md
+
+## Project Overview
+
+**anvil-ruby** is a Ruby gem providing a client for the [Anvil API](https://www.useanvil.com/docs/) — a document automation platform for PDF filling, PDF generation, e-signatures, and webhooks.
+
+- **Version:** 0.1.0
+- **Ruby:** >= 2.5.0 (developed on 3.4.8 via rbenv)
+- **License:** MIT
+- **Repo:** https://github.com/nickMarz/Ruby-Anvil
+- **API coverage:** ~30% implemented
+
+## Commands
+
+```bash
+bundle install                # Install dependencies
+bundle exec rspec             # Run tests
+bundle exec rspec --format documentation  # Verbose test output
+bundle exec rubocop           # Lint / style check
+bundle exec rake install      # Install gem locally
+gem build anvil-ruby.gemspec  # Build the gem
+```
+
+Always run `bundle exec rubocop` and `bundle exec rspec` before committing.
+
+## Architecture
+
+```
+lib/
+  anvil.rb                    # Entry point, module-level configuration
+  anvil/
+    version.rb                # VERSION constant
+    configuration.rb          # Configuration class (api_key, environment, timeouts)
+    client.rb                 # HTTP client (Net::HTTP), auth, request building
+    errors.rb                 # Error hierarchy (APIError, ValidationError, etc.)
+    rate_limiter.rb           # Retry with exponential backoff
+    response.rb               # Response wrapper (JSON parsing, rate-limit headers)
+    env_loader.rb             # Custom .env file parser (no dotenv dependency)
+    resources/
+      base.rb                 # Base resource class (ActiveRecord-like attributes)
+      pdf.rb                  # PDF.fill, PDF.generate, PDF.generate_from_html/markdown
+      signature.rb            # Signature packets (create, find, list) via GraphQL
+      webhook.rb              # Webhook parsing, token verification, decryption
+```
+
+### Key patterns
+
+- **Resource-based architecture** — resources inherit from `Resources::Base` which provides attribute accessors via `method_missing`, serialization, and a class-level `client`.
+- **Zero runtime dependencies** — only Ruby stdlib (`net/http`, `json`, `base64`, `uri`, `openssl`). The `base64` gem is added for Ruby 3.4+ compatibility.
+- **GraphQL for signatures** — `Signature` resource posts to `https://graphql.useanvil.com/` (full URL, not relative path).
+- **REST for PDFs** — `PDF` resource uses REST endpoints at `https://app.useanvil.com/api/v1/`.
+- **Multi-tenancy** — per-request `api_key:` override on resource methods.
+- **Configuration** — three methods: `Anvil.configure` block, `Anvil.api_key=`, or `ANVIL_API_KEY` env var.
+
+## Testing
+
+- **Framework:** RSpec (with `--format documentation` and `--color` via `.rspec`)
+- **HTTP mocking:** WebMock + VCR (optional; loaded if available)
+- **Spec structure** mirrors `lib/` — e.g., `spec/anvil/resources/pdf_spec.rb`
+- Config is reset before each test; `ANVIL_API_KEY` is stubbed to `'test_api_key'`
+- Use `:configured` metadata tag for tests that need `Anvil.configure` called
+
+## Code Style
+
+- **RuboCop** with `rubocop-rspec` (see `.rubocop.yml`)
+- Single quotes for strings
+- `frozen_string_literal: true` in every file
+- Max line length: 120
+- Max method length: 25
+- No `Style/Documentation` enforcement
+- Idiomatic Ruby: predicate methods (`complete?`, `draft?`), bang methods (`reload!`, `save_as!`)
+
+## Error Hierarchy
+
+```
+Anvil::Error
+├── ConfigurationError
+├── APIError
+│   ├── ValidationError
+│   ├── AuthenticationError
+│   ├── RateLimitError
+│   ├── NotFoundError
+│   └── ServerError
+├── NetworkError
+│   ├── TimeoutError
+│   └── ConnectionError
+├── FileError
+│   ├── FileNotFoundError
+│   └── FileTooLargeError
+└── WebhookError
+    └── WebhookVerificationError
+```
+
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `ANVIL_API_KEY` | API key for Anvil |
+| `ANVIL_WEBHOOK_TOKEN` | Token for webhook verification |
+| `ANVIL_TEMPLATE_ID` | Template EID for testing |
+| `ANVIL_ENV` | Environment override (`development` / `production`) |
+| `ANVIL_RSA_PRIVATE_KEY_PATH` | RSA key for webhook decryption |
+
+## CI/CD
+
+- **GitHub Actions** — CI pipeline in `.github/workflows/ci.yml` (tests, lint, security)
+- **Gem publishing** — `.github/workflows/gem-push.yml` (triggered by version tags like `v0.2.0`)
+- **Dependabot** — weekly dependency updates
+
+## Releasing
+
+1. Update `lib/anvil/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit and tag: `git tag v0.x.x`
+4. Push: `git push origin main --tags`
+
+## Conventions
+
+- Zero runtime dependencies — use only Ruby stdlib
+- Rails-friendly but framework-agnostic
+- Semantic versioning; all new features are additive (no breaking changes)
+- Document new features in CHANGELOG.md and API_COVERAGE.md
+- Write RSpec tests for all new functionality

data/API_COVERAGE.md

@@ -0,0 +1,294 @@
+# Anvil API Coverage Documentation
+
+## Overview
+This document tracks the implementation status of Anvil API features in the anvil-ruby gem.
+
+**Current Coverage: ~30%** of Anvil's API surface
+
+## Implementation Status
+
+### ✅ Implemented Features
+
+#### PDF Operations
+- [x] `PDF.fill` - Fill PDF templates with JSON data
+- [x] `PDF.generate` - Generate PDFs from HTML/CSS or Markdown
+- [x] `PDF.save_as` - Save PDF to file
+- [x] `PDF.to_base64` - Convert to base64 encoding
+
+#### E-Signatures (Basic)
+- [x] `Signature.create` - Create signature packets
+- [x] `Signature.find` - Find packet by ID
+- [x] `Signature.list` - List signature packets
+- [x] `signing_url` - Generate signing URLs for signers
+- [x] Draft mode support
+
+#### Webhooks
+- [x] `Webhook.new` - Parse webhook payloads
+- [x] `Webhook.valid?` - Verify webhook authenticity
+- [x] Token validation with constant-time comparison
+- [x] Basic webhook action detection
+
+#### Core Infrastructure
+- [x] API key configuration (multiple methods)
+- [x] Environment management (development/production)
+- [x] Rate limiting with exponential backoff
+- [x] Error handling with specific exception types
+- [x] .env file support
+
+### ❌ Missing Features
+
+#### 1. Workflows API (Priority: HIGH)
+**Purpose:** Automate document workflows combining forms, PDFs, and signatures
+
+Missing endpoints:
+- [ ] `createWeld` - Create workflow
+- [ ] `updateWeld` - Update workflow configuration
+- [ ] `duplicateWeld` - Clone workflow
+- [ ] `publishWeld` - Publish workflow
+- [ ] `mergeWelds` - Merge multiple workflows
+- [ ] `weld` query - Get workflow details
+- [ ] `weldData` query - Get workflow submission data
+
+Proposed Ruby interface:
+```ruby
+Anvil::Workflow.create(name:, forges:, casts:)
+Anvil::Workflow.find(id)
+Anvil::Workflow.start(workflow_id, data: {})
+Anvil::Workflow.submissions(workflow_id)
+```
+
+#### 2. Webforms/Forge API (Priority: HIGH)
+**Purpose:** Create and manage data collection forms
+
+Missing endpoints:
+- [ ] `createForge` - Create webform
+- [ ] `updateForge` - Update webform
+- [ ] `forge` query - Get form configuration
+- [ ] `createSubmission` - Submit form data
+- [ ] `updateSubmission` - Update submission
+- [ ] `submission` query - Get submission data
+
+Proposed Ruby interface:
+```ruby
+Anvil::Webform.create(name:, fields:)
+Anvil::Webform.find(id)
+Anvil::Webform.submit(form_id, data:)
+Anvil::Webform.submissions(form_id)
+```
+
+#### 3. Document AI / OCR (Priority: MEDIUM)
+**Purpose:** Extract data from documents using AI/OCR
+
+Missing capabilities:
+- [ ] Text extraction from PDFs
+- [ ] Field detection and labeling
+- [ ] Document classification
+- [ ] Structured data extraction
+
+Proposed Ruby interface:
+```ruby
+Anvil::DocumentAI.extract_text(file:)
+Anvil::DocumentAI.identify_fields(file:)
+Anvil::DocumentAI.extract_data(file:, schema:)
+```
+
+#### 4. Cast (PDF Template) Management (Priority: MEDIUM)
+**Purpose:** Programmatically manage PDF templates
+
+Missing endpoints:
+- [ ] `createCast` - Create template
+- [ ] `updateCast` - Update template
+- [ ] `duplicateCast` - Clone template
+- [ ] `publishCast` - Publish template
+- [ ] `cast` query - Get template details
+
+Proposed Ruby interface:
+```ruby
+Anvil::Cast.create(file:, fields:)
+Anvil::Cast.update(id, fields:)
+Anvil::Cast.duplicate(id)
+Anvil::Cast.list
+```
+
+#### 5. Advanced E-Signature Features (Priority: HIGH)
+**Purpose:** Complete signature packet management
+
+Missing endpoints:
+- [ ] `updateEtchPacket` - Update packet
+- [ ] `sendEtchPacket` - Send packet (from draft)
+- [ ] `removeEtchPacket` - Delete packet
+- [ ] `skipSigner` - Skip a signer
+- [ ] `notifySigner` - Send reminder
+- [ ] `updateEtchTemplate` - Update template
+- [ ] `voidDocumentGroup` - Void signed documents
+- [ ] `expireSignerTokens` - Expire signing sessions
+
+Proposed Ruby interface:
+```ruby
+packet.update(name:, signers:)
+packet.send!
+packet.delete!
+packet.skip_signer(signer_id)
+packet.notify_signer(signer_id)
+packet.void!
+```
+
+#### 6. Organization Management (Priority: LOW)
+**Purpose:** Manage organization settings and users
+
+Missing endpoints:
+- [ ] `organization` query - Get org details
+- [ ] `updateOrganization` - Update settings
+- [ ] `updateOrganizationUser` - Manage users
+- [ ] `currentUser` query - Get current user
+
+Proposed Ruby interface:
+```ruby
+Anvil::Organization.get
+Anvil::Organization.update(settings:)
+Anvil::Organization.users
+Anvil::Organization.add_user(email:, role:)
+```
+
+#### 7. Embedded Builders (Priority: LOW)
+**Purpose:** Embed Anvil UI builders in your application
+
+Missing endpoints:
+- [ ] `generateEmbedURL` - Create embed session
+- [ ] Session management
+
+Proposed Ruby interface:
+```ruby
+Anvil::EmbeddedBuilder.generate_url(type:, options:)
+Anvil::EmbeddedBuilder.create_session
+```
+
+#### 8. Webhook Management (Priority: MEDIUM)
+**Purpose:** Programmatically manage webhooks
+
+Missing endpoints:
+- [ ] `createWebhook` - Create webhook
+- [ ] `updateWebhook` - Update webhook
+- [ ] `removeWebhook` - Delete webhook
+- [ ] `createWebhookAction` - Create webhook action
+- [ ] `removeWebhookAction` - Remove action
+- [ ] `webhookLog` query - Get webhook logs
+- [ ] `retryWebhookLog` - Retry failed webhook
+
+Proposed Ruby interface:
+```ruby
+Anvil::Webhook.create(url:, events:)
+Anvil::Webhook.update(id, url:)
+Anvil::Webhook.delete(id)
+Anvil::WebhookLog.list
+Anvil::WebhookLog.retry(id)
+```
+
+#### 9. Generic GraphQL Support (Priority: HIGH)
+**Purpose:** Allow custom GraphQL queries/mutations
+
+Proposed Ruby interface:
+```ruby
+Anvil::Client.query(graphql_string, variables: {})
+Anvil::Client.mutation(graphql_string, variables: {})
+```
+
+## GraphQL Operations Summary
+
+### Available Queries (9 total)
+- `cast` - PDF template details
+- `currentUser` - User info
+- `etchPacket` - Signature packet
+- `forge` - Webform config
+- `organization` - Org details
+- `signer` - Signer info
+- `submission` - Form submission
+- `webhookLog` - Webhook history
+- `weld` - Workflow config
+- `weldData` - Workflow data
+
+### Available Mutations (35 total)
+
+**Document Operations (11):**
+- createCast, updateCast, duplicateCast, publishCast
+- createWeld, updateWeld, duplicateWeld, publishWeld, mergeWelds
+- createForge, updateForge
+
+**E-Signature (6):**
+- createEtchPacket, updateEtchPacket, sendEtchPacket
+- removeEtchPacket, generateEtchSignURL, updateEtchTemplate
+
+**Workflow Data (6):**
+- createWeldData, updateWeldData, removeWeldData
+- createSubmission, updateSubmission, destroySubmission
+
+**Configuration (7):**
+- createWebhook, updateWebhook, removeWebhook
+- createWebhookAction, removeWebhookAction
+- updateOrganization, updateOrganizationUser
+
+**Utilities (5):**
+- generateEmbedURL, expireSessionToken, expireSignerTokens
+- notifySigner, skipSigner, retryWebhookLog
+- disconnectDocusign, voidDocumentGroup
+
+## Implementation Phases
+
+### Phase 1: Core Features (v0.2.0)
+1. Generic GraphQL support
+2. Complete e-signature features
+3. Basic workflow support
+4. Basic webform support
+
+### Phase 2: Advanced Features (v0.3.0)
+1. Full workflow implementation
+2. Full webform implementation
+3. Cast management
+4. Webhook management
+
+### Phase 3: AI & Enterprise (v0.4.0)
+1. Document AI/OCR
+2. Organization management
+3. Embedded builders
+4. Advanced utilities
+
+## Testing Requirements
+
+Each feature implementation should include:
+1. Unit tests (RSpec)
+2. Integration tests (with VCR cassettes)
+3. Documentation (YARD comments)
+4. Usage examples
+5. Error handling tests
+
+## Dependencies
+
+Current gem has zero runtime dependencies (except base64 for Ruby 3.4+).
+We should maintain this approach where possible.
+
+Optional dependencies to consider:
+- `multipart-post` - For file uploads (already optional)
+- `marcel` - For MIME type detection (if needed)
+
+## Breaking Changes
+
+None expected. All new features will be additive.
+
+## Notes for Implementation
+
+1. Maintain consistent API design with existing patterns
+2. Use resource-based architecture (ActiveResource-like)
+3. Keep methods idiomatic Ruby (predicates, bang methods)
+4. Provide both simple and advanced interfaces
+5. Handle errors consistently with existing error classes
+6. Support per-request API key overrides for multi-tenancy
+
+## References
+
+- [Anvil API Documentation](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)
+
+---
+*Last Updated: January 2024*
+*Current Gem Version: 0.1.0*

data/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2024-01-15
+
+### Added
+- Initial release of the Anvil Ruby gem
+- PDF filling support via `Anvil::PDF.fill`
+- PDF generation from HTML/CSS via `Anvil::PDF.generate_from_html`
+- PDF generation from Markdown via `Anvil::PDF.generate_from_markdown`
+- E-signature packet creation and management via `Anvil::Signature`
+- Webhook verification and handling via `Anvil::Webhook`
+- Flexible API key configuration (Rails initializer, environment variable, direct assignment)
+- Multi-tenant support with per-request API key override
+- Automatic rate limiting with exponential backoff
+- Comprehensive error handling with specific exception types
+- Zero runtime dependencies - uses only Ruby standard library
+- Rails-friendly design while remaining framework agnostic
+- Full RSpec test suite
+- Extensive documentation and examples
+
+### Security
+- Secure webhook token verification with constant-time comparison
+- Support for RSA-encrypted webhook payloads
+- MFA required for RubyGems publishing
+
+[Unreleased]: https://github.com/nickMarz/Ruby-Anvil/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/nickMarz/Ruby-Anvil/releases/tag/v0.1.0

data/CLAUDE_README.md

@@ -0,0 +1,98 @@
+# Instructions for Claude
+
+## 🚀 Quick Start for New Sessions
+
+When starting a new session with this project, please:
+
+1. **Read the project notes**:
+   ```
+   Read .claude-project-notes.md
+   ```
+
+2. **Check current status**:
+   ```bash
+   git status
+   git log -1
+   ```
+
+3. **Understand the project**:
+   - This is the Anvil Ruby gem for document automation
+   - GitHub Actions are fully configured for CI/CD
+   - Tests should always pass before committing
+
+## 📝 Important Context
+
+### GitHub Actions Setup (Completed Jan 15, 2024)
+- ✅ CI pipeline (`.github/workflows/ci.yml`)
+- ✅ Gem publishing (`.github/workflows/gem-push.yml`)
+- ✅ Dependabot configuration
+- ✅ Full documentation in `.github/workflows/README.md`
+
+### Required Secrets
+- `RUBYGEM_API_KEY` - Must be added to GitHub for gem publishing
+- `ANVIL_API_KEY` - Optional, for running tests
+
+### Project Conventions
+- Use RuboCop for style (`bundle exec rubocop`)
+- Write tests for all new features (`bundle exec rspec`)
+- Zero runtime dependencies (except base64 for Ruby 3.4+)
+- Follow semantic versioning
+
+## 🎯 Common Tasks
+
+### Before ANY commit:
+```bash
+bundle exec rubocop
+bundle exec rspec
+```
+
+### To release a new version:
+1. Update `lib/anvil/version.rb`
+2. Update `CHANGELOG.md`
+3. Commit and tag: `git tag v0.x.x`
+4. Push: `git push origin main --tags`
+
+### To run CI locally:
+```bash
+bundle exec rubocop           # Linting
+bundle exec rspec             # Tests
+bundle-audit check --update   # Security
+gem build *.gemspec          # Build
+```
+
+## 🔧 Development Workflow
+
+1. **Always use TodoWrite tool** for multi-step tasks
+2. **Run tests** before committing changes
+3. **Check CI status** after pushing
+4. **Document** any new features or changes
+
+## 👤 User Preferences (Nick Marazzo)
+
+- Prefers practical, working solutions
+- Values comprehensive documentation
+- Likes Ruby best practices and idiomatic code
+- Appreciates proactive error handling
+- Wants CI/CD automation for everything
+
+## 📁 Key Files
+
+- `.github/workflows/` - GitHub Actions workflows
+- `lib/anvil/` - Main gem code
+- `spec/` - Test files
+- `examples/` - Usage examples
+- `.rubocop.yml` - Style configuration
+- `anvil-ruby.gemspec` - Gem specification
+
+## 🚨 Important Reminders
+
+1. **Never** commit without running tests
+2. **Always** update CHANGELOG.md for new features
+3. **Check** GitHub Actions after pushing
+4. **Update** documentation for API changes
+5. **Test** against multiple Ruby versions locally if possible
+
+---
+
+*This file helps Claude understand the project context in new sessions.*
+*Last updated: January 15, 2024*