patch_retention 0.1.5 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e09da85122b9149656266b2ffb272f51ec729747c97f52287dd5c89b2b26a03c
-  data.tar.gz: 7806f37ed28567871f577c26f8565107d21e65da1dbe58497a177b9920a2222e
+  metadata.gz: 6e16f62b32c1b6105c7635ba9f00ccd20ccb7e59f131ab035ff9033a96224547
+  data.tar.gz: e251e05872d84438356695555fc6ae4ec56949e574e83306389f7de03ab2a310
 SHA512:
-  metadata.gz: e17497a6c6cb6f2e24002a72438689e67d8d862c2b20eb43ffac61ce7427f7a46eef1096e11ef31dd153b1492880fbedfba8c95c24cb4fc29c9ffaa24bd16368
-  data.tar.gz: f674998100632b6e64fcbe01d4af1f828b1636e5fe59e5f797d7287c42d7e013494ac59091eb02415a007fa3818e8698a3bd3cf62cb2ee87475237ce29b98247
+  metadata.gz: c2ca9e71b4a393356b22e8d680cd8a25f95a1cc901de1cdd6a9fdeaebe7a33ae9183af2b76f883058614b5cbd2b3fff97c8a0ef243651e5ebbe20468fae98374
+  data.tar.gz: ef2307ff81839c5343c98e7f03eb7e6c39e77df272524358327fbe7b13b216f7fa7d6b6dd8b834e211a058c7d793c3e1c7cccaa683333cf33a086d95fe5ee701

data/.env.development

@@ -0,0 +1,5 @@
+# Development environment variables
+# Copy this file to .env.development.local and add your real credentials
+PATCH_RETENTION_CLIENT_ID=your_client_id
+PATCH_RETENTION_CLIENT_SECRET=your_client_secret
+PATCH_RETENTION_API_URL=https://api.patchretention.com/v2

data/.env.example

@@ -0,0 +1,5 @@
+# Example environment variables
+PATCH_RETENTION_CLIENT_ID=your_client_id
+PATCH_RETENTION_CLIENT_SECRET=your_client_secret
+PATCH_RETENTION_API_URL=https://api.patchretention.com/v2
+# PATCH_RETENTION_PROXY_URL=http://your-proxy.com:8080  # Optional

data/.env.test.example

@@ -0,0 +1,5 @@
+# Test environment variables
+# These should be set from environment variables or GitHub secrets
+PATCH_RETENTION_CLIENT_ID=your_test_client_id
+PATCH_RETENTION_CLIENT_SECRET=your_test_client_secret
+PATCH_RETENTION_API_URL=https://api.patchretention.com/v2

data/.rubocop.yml

@@ -1,28 +1,40 @@
 AllCops:
-  TargetRubyVersion: 2.6
-
-Style/StringLiterals:
-  Enabled: true
-  EnforcedStyle: double_quotes
+  TargetRubyVersion: 3.1
+  NewCops: enable
+  Exclude:
+    - 'bin/**/*'
+    - 'vendor/**/*'
+    - 'spec/fixtures/**/*'
+    - 'tmp/**/*'
+    - 'pkg/**/*'
+
+inherit_gem:
+  rubocop-shopify: rubocop.yml
+
+# Gem specific overrides
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+# Allow longer lines in specs for readability
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - 'spec/**/*'
 
-Style/StringLiteralsInInterpolation:
-  Enabled: true
-  EnforcedStyle: double_quotes
+# Documentation is good but not required for all classes in a gem
+Style/Documentation:
+  Enabled: false
 
+# Allow compact module/class definitions for simple cases
 Style/ClassAndModuleChildren:
-  EnforcedStyle: compact
-
-Metrics/MethodLength:
-  Max: 30
-
-Style/ModuleFunction:
   Enabled: false
 
-Metrics/AbcSize:
-  Max: 30
-
-Layout/LineLength:
-  Max: 120
+# String literals
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
 
-Style/Documentation:
-  Enabled: false
+# Frozen string literal
+Style/FrozenStringLiteralComment:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.1.6

data/.tool-versions

@@ -1 +1 @@
-ruby 2.7.2
+ruby 3.1.6

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-05-26
+
+### Added
+- Products API support with create, update, and find methods
+- Memberships API support with create, update, and find methods
+- Dotenv integration for environment variable management in development/test
+- GitHub Actions CI/CD workflows for automated testing and releases
+- Rubocop integration with Shopify style guide for code consistency
+- Ruby 3.1+ requirement (minimum Ruby version)
+- Comprehensive RSpec test coverage with VCR for API recording
+
+### Changed
+- Updated all existing code to comply with Shopify's Rubocop style guide
+- Enhanced documentation with detailed usage examples for new endpoints
+- Improved test configuration with environment variable support
+
+### Security
+- Fixed rexml vulnerability by requiring version >= 3.3.9
+- Removed test credentials from repository, using .env.test.example instead
+
 ### [0.1.3] - 2024-02-05
 
 - Support proxying to a different host

data/CLAUDE.md

@@ -0,0 +1,248 @@
+# Patch Retention Ruby Gem - Development Guidelines
+
+## Project Overview
+This is a Ruby gem that provides a wrapper for the Patch Retention API. The gem follows Ruby best practices and uses Zeitwerk for autoloading.
+
+**Ruby Version**: 3.1.6 (minimum 3.1.0)
+**Testing**: RSpec with VCR for HTTP request recording/playback
+
+## About Memory
+
+### Session Knowledge Management
+- **Document discoveries**: During any session, keep files in `/docs` updated with findings and new knowledge acquired about the API, gem patterns, etc. These docs serve as institutional memory for developers and future Claude sessions
+- **Decision logs**: Record architectural decisions, trade-offs made, and rationale behind implementation choices in `/docs/decisions/`
+- **Pattern documentation**: When you discover or establish new patterns, document them in `/docs/patterns/` with examples and use cases
+- **Gotcha tracking**: Maintain a running list of common pitfalls, edge cases, and their solutions in `/docs/references/troubleshooting.md`
+
+### Cross-Session Continuity
+- **Context anchoring**: Start each session by reviewing recent documentation updates to understand what was learned previously
+- **Progress tracking**: Maintain work-in-progress notes in `/docs/wip/` to help future sessions pick up where you left off
+- **Code archaeology**: When working with unfamiliar code, document your understanding of its purpose, history, and dependencies
+- **Test insights**: Document why certain tests exist, what they're protecting against, and any unusual testing strategies discovered
+
+### Institutional Knowledge Capture
+- **Domain expertise**: As you learn about customer retention, membership management, or event tracking patterns, capture this domain knowledge
+- **Integration wisdom**: Document how the Patch Retention API works, its quirks, limitations, and best practices
+- **Performance learnings**: Record performance bottlenecks discovered, optimization strategies that worked, and their impact
+- **Security considerations**: Maintain notes about security patterns, API authentication, and data handling best practices
+
+### Memory Organization Principles
+- **Connect to existing knowledge**: Link new discoveries to established patterns in the gem codebase
+- **Stay organized**: Use consistent file naming and directory structure in `/docs` for easy retrieval
+- **Limit cognitive load**: Break complex topics into digestible chunks with clear hierarchies
+- **Active reinforcement**: Reference and build upon documented knowledge in subsequent sessions
+- **Version awareness**: Note which API version or gem version knowledge applies to, especially during API updates
+
+### Knowledge Sources to Leverage
+- **Code comments**: Read and contribute to inline documentation
+- **Git history**: Use commit messages and PR descriptions to understand the evolution of features
+- **Test suites**: Tests often reveal API behaviors and edge cases not obvious in implementation code
+- **Configuration files**: Environment variables and initializers reveal API capabilities and constraints
+- **External documentation**: Patch Retention API docs, Ruby gem best practices, and HTTP client documentation provide context for implementation decisions
+
+## API Overview
+Patch Retention is a customer retention platform that helps businesses manage contacts, products, memberships, and events. The API uses:
+- Base URL: `https://api.patchretention.com/v2`
+- Authentication: Bearer token (client_secret) with X-Account-Id header (client_id)
+- Content-Type: application/json
+
+## Key Components
+
+### 1. Contacts
+- Manages customer/contact information
+- Supports CRUD operations (Create, Read, Update, Delete)
+- Find or create functionality with query parameters
+- Fields: first_name, last_name, email, phone, address, city, state, zip, country, company, job_title
+
+### 2. Events
+- Tracks customer activities and interactions
+- Event types follow dot notation (e.g., 'order.finished')
+- Supports primary key details for event linking
+- Can upsert contact details when creating events
+- Includes custom data payload
+
+### 3. Products (NEW - Updated)
+- Manages product catalog
+- Required fields: name, price (in cents), status (PUBLISHED/UNPUBLISHED)
+- Optional fields: description, membership (boolean), tags, external_id, external_data
+- Returns product with unique ID (e.g., "prod_xxxxxxxxxxxxxx")
+- **New methods added**:
+  - `update`: PATCH endpoint to modify product details
+  - `find`: GET endpoint to retrieve a specific product
+
+### 4. Memberships (NEW - Updated)
+- Links contacts to products with time boundaries
+- Required fields: contact_id, product_id
+- Optional fields: start_at, end_at (ISO8601 timestamps), external_id, external_data, tags
+- Returns membership with unique ID (e.g., "mem_xxxxxxxxxxxxxx")
+- **New methods added**:
+  - `update`: PATCH endpoint to modify membership details
+  - `find`: GET endpoint to retrieve a specific membership
+
+## Code Structure
+```
+lib/
+├── patch_retention.rb              # Main module with configuration and connection
+├── patch_retention/
+│   ├── configuration.rb           # Configuration management
+│   ├── contacts.rb               # Contacts API wrapper
+│   ├── contacts/                 # Contact sub-operations
+│   │   ├── delete.rb
+│   │   ├── find.rb
+│   │   ├── find_or_create.rb
+│   │   └── update.rb
+│   ├── events.rb                 # Events API wrapper
+│   ├── events/                   # Event sub-operations
+│   │   ├── create.rb
+│   │   └── find.rb
+│   ├── memberships.rb            # NEW: Memberships API wrapper
+│   ├── products.rb               # NEW: Products API wrapper
+│   ├── util.rb                   # Utility methods
+│   └── version.rb                # Gem version
+```
+
+## Configuration
+The gem supports both global and per-call configuration:
+- Global: Environment variables or configure block
+- Per-call: Pass custom Configuration instance to any API method
+
+## Error Handling
+- All API methods rescue Faraday::Error and raise PatchRetention::Error
+- Error messages include context about the operation
+
+## Testing
+- Run tests with: `rake spec`
+- Test files located in `spec/` directory
+
+## Development Notes
+1. The gem uses Faraday for HTTP requests
+2. All API responses are parsed as JSON
+3. Zeitwerk handles autoloading
+4. Follow Ruby conventions (snake_case for methods/variables)
+5. All classes are under PatchRetention module
+6. Always add a newline at the end of text files (POSIX compliance)
+7. Dotenv is used for managing environment variables in development/test
+
+## Environment Setup
+
+### Test Credentials
+Test credentials are managed securely:
+- **Local Development**: Use environment variables or run `./script/setup_test_env`
+- **CI/CD**: GitHub secrets are configured for `PATCH_RETENTION_TEST_CLIENT_ID` and `PATCH_RETENTION_TEST_CLIENT_SECRET`
+- **Security**: Never commit credentials to the repository
+
+### Environment Files
+The gem uses dotenv for credential management:
+- `.env.test` - Test credentials (gitignored - created by setup script)
+- `.env.test.example` - Test environment template (committed without credentials)
+- `.env.development` - Development template (committed)
+- `.env.development.local` - Your local credentials (gitignored)
+- `.env.example` - Example configuration
+
+### Environment Variables
+- `PATCH_RETENTION_CLIENT_ID` - Your API client ID
+- `PATCH_RETENTION_CLIENT_SECRET` - Your API client secret
+- `PATCH_RETENTION_API_URL` - API endpoint (optional, defaults to https://api.patchretention.com/v2)
+- `PATCH_RETENTION_PROXY_URL` - Proxy URL (optional)
+
+## TODO/Improvements
+- [ ] Add response error handling for specific HTTP status codes
+- [ ] Implement pagination for list operations (all contacts, all events)
+- [x] Add support for GET operations on Products and Memberships (find methods added)
+- [x] Add update operations for Products and Memberships (update, cancel, expire methods added)
+- [ ] Add delete operations for Products and Memberships
+- [ ] Implement retry logic for transient failures
+- [ ] Add comprehensive test coverage for new endpoints
+- [ ] Consider adding response object wrappers instead of returning raw hashes
+- [ ] Add list/all methods for Products and Memberships
+
+## Session Findings (2025-05-26)
+
+### API Discoveries
+1. **ID Formats**: API returns MongoDB-style IDs (e.g., `6833ef45...`) not prefixed formats (`prod_xxx`, `mem_xxx`)
+2. **Contact IDs**: Contacts use `_id` field instead of `id` (important for membership creation)
+3. **Tag Capitalization**: API automatically capitalizes all tags (e.g., "test" → "Test")
+4. **External Data**: `external_data` is accepted in requests but not always returned in responses
+5. **Default Values**: New memberships get `status: "PENDING"` by default
+6. **Phone Numbers**: API may modify phone numbers (e.g., prepending country code)
+
+### Testing Best Practices
+1. **Debug Output**: Use `puts "DEBUG: #{result.inspect}"` in specs to debug API responses
+2. **VCR Integration**: All API tests are recorded/replayed using VCR for consistent testing
+3. **Flexible Assertions**: Don't rely on exact field presence, use conditional checks
+4. **Custom Config Testing**: Always test that methods accept custom configuration
+
+### Code Style
+- Using Shopify's Rubocop style guide (`rubocop-shopify` gem)
+- Class methods defined using `class << self` pattern
+- Double quotes for strings
+- Frozen string literals enabled
+
+## Common Tasks
+
+### Setting Up Test Environment
+```bash
+# Using environment variables
+export PATCH_RETENTION_TEST_CLIENT_ID=your_client_id
+export PATCH_RETENTION_TEST_CLIENT_SECRET=your_client_secret
+./script/setup_test_env
+
+# Or manually create .env.test
+```
+
+### Running Tests
+```bash
+bundle exec rake spec
+```
+
+### Running RuboCop
+```bash
+bundle exec rubocop        # Check for issues
+bundle exec rubocop -a     # Auto-fix safe issues
+bundle exec rubocop -A     # Auto-fix all issues
+```
+
+### Debugging Failed Tests
+```ruby
+# Add debug output to see actual API response
+it "creates something" do
+  result = create_something
+  puts "DEBUG: API Response: #{result.inspect}"
+  # assertions...
+end
+```
+
+### Building Gem Locally
+```bash
+bundle exec rake build
+```
+
+### Console for Testing
+```bash
+bin/console
+```
+
+## Session Learnings & Best Practices
+
+### VCR and Test Credentials
+- VCR cassettes should work universally without requiring specific credentials
+- Use VCR's `filter_sensitive_data` to replace actual credentials with placeholders
+- Test credentials should only be available via environment variables, never hardcoded
+- CI/CD should use GitHub secrets for test credentials
+
+### CI/CD Configuration
+- Keep CI workflows simple and consistent
+- Use the same credential management approach across all workflows
+- Add verification steps to help debug CI issues
+- RuboCop compliance is enforced in CI - fix issues before pushing
+
+### Security Best Practices
+- Never commit credentials, even test ones
+- Use environment variables or secure secret management
+- Squash commits if credentials were accidentally exposed
+- Document credential setup clearly but without revealing actual values
+
+### Error Handling
+- The `util.rb` module returns `true` on JSON parse errors - be aware of this pattern
+- VCR cassettes with incomplete recordings (e.g., 401 errors) can cause test failures
+- Always handle both successful and error responses in tests

data/DEPENDENCY_UPDATE_REPORT.md

@@ -0,0 +1,89 @@
+# Dependency Update Report - Patch Retention Gem
+
+## Current Ruby Version Requirement
+- **Minimum**: Ruby >= 2.6.0 (as specified in gemspec)
+
+## Outdated Dependencies Analysis
+
+### Critical Dependencies
+
+#### 1. **Faraday** (HTTP client)
+- Current: 2.7.12
+- Latest: 2.13.1
+- **Recommendation**: ✅ Safe to update
+- **Breaking Changes**: None
+- **Benefits**: Bug fixes, performance improvements, and better HTTP/2 support
+
+#### 2. **Zeitwerk** (Code loader)
+- Current: 2.6.0
+- Latest: 2.7.3
+- **Recommendation**: ⚠️ Do NOT update yet
+- **Breaking Changes**: Requires Ruby >= 3.2
+- **Action**: Pin to `~> 2.6` in Gemfile to prevent accidental updates
+
+### Development Dependencies
+
+#### 3. **Byebug** (Debugger)
+- Current: 11.1.3
+- Latest: 12.0.0
+- **Recommendation**: ⚠️ Do NOT update yet
+- **Breaking Changes**: Requires Ruby >= 3.1
+- **Alternative**: Consider migrating to `debug` gem (Ruby's official debugger)
+
+#### 4. **RSpec** (Testing)
+- Current: 3.12.0
+- Latest: 3.13.0
+- **Recommendation**: ✅ Safe to update
+- **Breaking Changes**: None
+- **Benefits**: Better Ruby 3.x support, improved error messages
+
+#### 5. **RuboCop** (Linter)
+- Current: 1.58.0
+- Latest: 1.75.7
+- **Recommendation**: ✅ Safe to update (but may introduce new cops)
+- **Breaking Changes**: None, but may flag new style violations
+- **Action**: Update and fix any new violations
+
+### Other Notable Updates
+- **Rake**: 13.1.0 → 13.2.1 (✅ Safe)
+- **Pry**: 0.14.2 → 0.15.2 (✅ Safe)
+- **JSON**: 2.7.0 → 2.12.2 (✅ Safe)
+- **REXML**: 3.2.6 → 3.4.1 (✅ Safe - security fixes)
+
+## Recommended Update Strategy
+
+### Immediate Updates (No Breaking Changes)
+```ruby
+# In Gemfile:
+gem "faraday", "~> 2.13"
+gem "rake", "~> 13.2"
+
+group :development do
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.75"
+  gem "pry", "~> 0.15"
+end
+```
+
+### Version Pins (To Prevent Breaking Changes)
+```ruby
+# Add to Gemfile to maintain Ruby 2.6+ compatibility:
+gem "zeitwerk", "~> 2.6"  # Pin to prevent Ruby 3.2+ requirement
+gem "byebug", "~> 11.1"   # Pin to prevent Ruby 3.1+ requirement
+```
+
+### Migration Path for Ruby Version
+To use all latest dependencies, consider:
+1. Update minimum Ruby version to 3.2+ in gemspec
+2. This would allow using latest Zeitwerk and Byebug
+3. Consider replacing Byebug with `debug` gem (built-in for Ruby 3.1+)
+
+## Security Considerations
+- **REXML** update includes security fixes - recommend updating
+- No known vulnerabilities in current versions, but staying updated is good practice
+
+## Testing After Updates
+1. Run full test suite: `bundle exec rake spec`
+2. Run RuboCop: `bundle exec rubocop`
+3. Test in development environment
+4. Verify gem builds correctly: `bundle exec rake build`

data/Gemfile

@@ -4,15 +4,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in patch_retention.gemspec
 gemspec
-
-gem "rake", "~> 13.0"
-
-gem "faraday"
-gem "zeitwerk"
-
-group :development do
-  gem "byebug"
-  gem "pry", require: true
-  gem "rspec", "~> 3.0"
-  gem "rubocop", "~> 1.21"
-end

data/Gemfile.lock

@@ -1,24 +1,41 @@
 PATH
   remote: .
   specs:
-    patch_retention (0.1.3)
+    patch_retention (0.2.0)
+      faraday (~> 2.0)
+      zeitwerk (~> 2.6)
 
 GEM
   remote: https://rubygems.org/
   specs:
+    addressable (2.8.7)
+      public_suffix (>= 2.0.2, < 7.0)
     ast (2.4.2)
     base64 (0.2.0)
+    bigdecimal (3.1.9)
+    bundler-audit (0.9.2)
+      bundler (>= 1.2.0, < 3)
+      thor (~> 1.0)
     byebug (11.1.3)
     coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
     diff-lcs (1.5.0)
-    faraday (2.7.12)
-      base64
-      faraday-net_http (>= 2.0, < 3.1)
-      ruby2_keywords (>= 0.0.4)
-    faraday-net_http (3.0.2)
+    dotenv (2.8.1)
+    faraday (2.13.1)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.0)
+      net-http (>= 0.5.0)
+    hashdiff (1.2.0)
     json (2.7.0)
     language_server-protocol (3.17.0.3)
+    logger (1.7.0)
     method_source (1.0.0)
+    net-http (0.6.0)
+      uri
     parallel (1.23.0)
     parser (3.2.2.4)
       ast (~> 2.4.1)
@@ -26,11 +43,12 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
+    public_suffix (5.1.1)
     racc (1.7.3)
     rainbow (3.1.1)
     rake (13.1.0)
     regexp_parser (2.8.2)
-    rexml (3.2.6)
+    rexml (3.4.1)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
       rspec-expectations (~> 3.12.0)
@@ -57,23 +75,37 @@ GEM
       unicode-display_width (>= 2.4.0, < 3.0)
     rubocop-ast (1.30.0)
       parser (>= 3.2.1.0)
+    rubocop-shopify (2.15.1)
+      rubocop (~> 1.51)
     ruby-progressbar (1.13.0)
-    ruby2_keywords (0.0.5)
+    thor (1.3.2)
     unicode-display_width (2.5.0)
-    zeitwerk (2.6.0)
+    uri (1.0.3)
+    vcr (6.3.1)
+      base64
+    webmock (3.25.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    zeitwerk (2.6.18)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  bundler (~> 2.0)
+  bundler-audit (~> 0.9)
   byebug
-  faraday
+  dotenv (~> 2.8)
   patch_retention!
   pry
   rake (~> 13.0)
+  rexml (>= 3.3.9)
   rspec (~> 3.0)
   rubocop (~> 1.21)
-  zeitwerk
+  rubocop-shopify (~> 2.15)
+  vcr (~> 6.0)
+  webmock (~> 3.0)
 
 BUNDLED WITH
-   2.1.4
+   2.6.9