patch_retention 0.1.5 → 0.2.0

data/README.md

@@ -1,5 +1,8 @@
 # Patch Retention API Wrapper
 
+[![CI](https://github.com/[USERNAME]/patch_retention/actions/workflows/ci.yml/badge.svg)](https://github.com/[USERNAME]/patch_retention/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/patch_retention.svg)](https://badge.fury.io/rb/patch_retention)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -18,7 +21,30 @@ $ gem install patch_retention
 
 ### Configuration
 
-For local environment, you can set the following environment variables:
+#### Using Environment Files (Recommended for Development)
+
+This gem uses dotenv for managing environment variables in development and test environments. Copy the example file and add your credentials:
+
+```bash
+# For development
+cp .env.example .env.development.local
+# Edit .env.development.local with your credentials
+
+# For running tests
+cp .env.test.example .env.test
+# Edit .env.test with your test credentials
+```
+
+The following files are used:
+- `.env.test` - Test environment (gitignored - copy from `.env.test.example`)
+- `.env.test.example` - Test environment template (committed)
+- `.env.development` - Development defaults (committed)
+- `.env.development.local` - Your local development credentials (gitignored)
+- `.env.example` - Example configuration (committed)
+
+#### Using Environment Variables
+
+For production or CI environments, you can set the following environment variables:
 
 ```bash
 PATCH_RETENTION_API_URL='your_custom_api_url' # Optional, by default is set to: https://api.patchretention.com/v2
@@ -38,9 +64,52 @@ PatchRetention.configure do |config|
 end
 ```
 
+### Using a Custom Configuration per Call
+
+While you can configure the gem globally, there might be scenarios where you need to use a different set of credentials or API endpoint for a specific API call. All API call methods (e.g., `PatchRetention::Products.create`, `PatchRetention::Memberships.create`, `PatchRetention::Events.create`, `PatchRetention::Contacts.find_or_create_by`, etc.) accept an optional `config:` parameter.
+
+This parameter expects an instance of `PatchRetention::Configuration`.
+
+**Example: Creating a call with a custom `PatchRetention::Configuration` Object:**
+
+If you want to use different configuration values for a specific call, you can create a new `PatchRetention::Configuration` object, populate it, and pass it to the desired method.
+
+```ruby
+# Create a custom configuration instance
+custom_config = PatchRetention::Configuration.new
+custom_config.client_id = "your_other_client_id"
+custom_config.client_secret = "your_other_client_secret"
+custom_config.api_url = "https://specific-instance.patchretention.com/v2"
+# custom_config.proxy_url = "http://your.other.proxy.com:8080" # Optional
+
+# Use this custom configuration for an API call
+begin
+  product_details = {
+    name: "Special Product",
+    price: 1500,
+    status: "PUBLISHED"
+  }
+  new_product = PatchRetention::Products.create(**product_details, config: custom_config)
+  puts "Created product with custom config: #{new_product}"
+
+  membership_payload = {
+    contact_id: "ct_somecontact",
+    product_id: new_product["id"], # Assuming new_product is a hash with an "id" key
+    start_at: Time.now.xmlschema
+  }
+  new_membership = PatchRetention::Memberships.create(**membership_payload, config: custom_config)
+  puts "Created membership with custom config: #{new_membership}"
+
+rescue PatchRetention::Error => e
+  puts "Error with custom config: #{e.message}"
+end
+```
+
+This approach allows you to maintain multiple configurations if needed, for example, when interacting with different Patch Retention accounts or environments within the same application. If you need to use a highly customized Faraday connection (e.g., with special middleware), you would need to ensure the `PatchRetention.connection` method can accommodate this through the `Configuration` object, potentially by enhancing the `Configuration` class or the `PatchRetention.connection` method itself to interpret more advanced settings from the `Configuration` object.
+
 ### Usage
 
-First, you need to configure the gem with your API credentials.
+First, you need to configure the gem with your API credentials globally (if not providing custom configurations per call).
 
 Then, you can use the gem's methods to interact with the API.
 
@@ -148,9 +217,126 @@ event = PatchRetention::Events.create(
 )
 ```
 
+**Products**
+
+To create a product:
+
+```ruby
+product = PatchRetention::Products.create(
+  name: "Test Product",
+  price: 999, # Price in Cents
+  status: "PUBLISHED", # or "UNPUBLISHED"
+  description: "This is a product for testing purposes.", # Optional
+  membership: true, # Optional, boolean
+  tags: ["test", "new_product"], # Optional, array of strings
+  external_id: "SKU12345", # Optional
+  external_data: { "custom_key": "custom_value" } # Optional, hash
+)
+# => {"id"=>"prod_xxxxxxxxxxxxxx", "name"=>"Test Product", ...}
+```
+
+To update a product:
+
+```ruby
+product = PatchRetention::Products.update(
+  product_id: "prod_xxxxxxxxxxxxxx",
+  name: "Updated Product Name",
+  price: 1299,
+  status: "UNPUBLISHED"
+)
+```
+
+To find a product:
+
+```ruby
+product = PatchRetention::Products.find(product_id: "prod_xxxxxxxxxxxxxx")
+```
+
+**Memberships**
+
+To create a membership:
+
+```ruby
+require 'time'
+
+membership = PatchRetention::Memberships.create(
+  contact_id: "68273ecd9xxxxxxxxxxxx", # Required, ID of the contact
+  product_id: "65de5xxxxxxxxxxxxx", # Required, ID of the product (e.g., from product creation)
+  start_at: Time.now.xmlschema, # Optional, ISO8601 timestamp
+  end_at: (Time.now + 30*24*60*60).xmlschema, # Optional, ISO8601 timestamp (e.g., 30 days from now)
+  external_id: "MEM123", # Optional
+  external_data: { "notes": "Trial membership" }, # Optional, hash
+  tags: ["trial", "api_created"] # Optional, array of strings
+)
+# => {"id"=>"mem_xxxxxxxxxxxxxx", "contact_id"=>"ct_xxxxxxxxxxxxxx", ...}
+```
+
+To update a membership:
+
+```ruby
+membership = PatchRetention::Memberships.update(
+  membership_id: "mem_xxxxxxxxxxxxxx",
+  end_at: (Time.now + 60*24*60*60).xmlschema, # Extend to 60 days
+  tags: ["extended", "premium"]
+)
+```
+
+To find a membership:
+
+```ruby
+membership = PatchRetention::Memberships.find(membership_id: "mem_xxxxxxxxxxxxxx")
+```
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+
+### Setting up Test Environment
+
+To run tests, you'll need to set up test credentials. The test credentials should NOT be committed to the repository.
+
+1. **Using environment variables (recommended):**
+   ```bash
+   export PATCH_RETENTION_TEST_CLIENT_ID=your_test_client_id
+   export PATCH_RETENTION_TEST_CLIENT_SECRET=your_test_client_secret
+   ```
+
+2. **Using the setup script:**
+   ```bash
+   # This will create .env.test from your environment variables
+   ./script/setup_test_env
+   ```
+
+3. **Manual setup:**
+   Create a `.env.test` file with:
+   ```
+   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
+   ```
+
+**Note:** The `.env.test` file is gitignored and should never be committed.
+
+### Running Tests
+
+Once your test environment is set up:
+```bash
+bundle exec rake spec
+```
+
+#### VCR Recording Modes
+
+By default, VCR runs in `:once` mode, which only records HTTP interactions once. To re-record cassettes:
+
+```bash
+# Re-record all cassettes
+VCR_RECORD_MODE=new_episodes bundle exec rake spec
+
+# Never make real HTTP calls (useful for CI)
+VCR_RECORD_MODE=none bundle exec rake spec
+```
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 

data/Rakefile

@@ -9,4 +9,4 @@ require "rubocop/rake_task"
 
 RuboCop::RakeTask.new
 
-task default: %i[spec rubocop]
+task default: [:spec, :rubocop]

data/docs/decisions/001-api-implementation.md

@@ -0,0 +1,66 @@
+# API Implementation Decisions
+
+## Date: 2025-05-26
+
+### Context
+During the implementation of Products and Memberships endpoints for the Patch Retention API v2, several important decisions were made based on API behavior discoveries.
+
+### Key Decisions
+
+#### 1. ID Format Handling
+- **Decision**: Use flexible ID validation instead of expecting specific prefixes
+- **Rationale**: The API returns IDs in MongoDB format (e.g., `6833ef45d8ebcbe4774efb98`) rather than prefixed formats like `prod_xxx` or `mem_xxx`
+- **Implementation**: Changed tests from `expect(result["id"]).to match(/^prod_/)` to `expect(result["id"]).to be_a(String)`
+
+#### 2. Contact ID Field Naming
+- **Decision**: Handle both `_id` and `id` fields for contacts
+- **Rationale**: Contacts API returns `_id` as the primary identifier, while other endpoints use `id`
+- **Implementation**: Use `contact["_id"] || contact["id"]` pattern throughout tests
+
+#### 3. External Data Handling
+- **Decision**: Don't expect `external_data` to be returned in responses
+- **Rationale**: The API accepts `external_data` but doesn't always return it in the response
+- **Implementation**: Removed assertions for `external_data` in test expectations
+
+#### 4. Tag Capitalization
+- **Decision**: Expect tags to be capitalized by the API
+- **Rationale**: The API automatically capitalizes tags (e.g., "test" becomes "Test")
+- **Implementation**: Updated test data to use capitalized tags
+
+#### 5. Membership Status Updates
+- **Decision**: Remove `cancel` and `expire` convenience methods
+- **Rationale**: Based on Excel documentation and API testing, only create and update operations are supported
+- **Implementation**: Removed these methods and updated documentation accordingly
+
+### API Response Patterns Discovered
+
+1. **Products Response Structure**:
+   ```json
+   {
+     "account_id": 654173,
+     "name": "Test Widget",
+     "price": 799,
+     "status": "PUBLISHED",
+     "_id": "6833ef45...",
+     "id": "6833ef45...",
+     "created_at": "2025-05-26T04:34:13.503Z",
+     "updated_at": "2025-05-26T04:34:13.503Z"
+   }
+   ```
+
+2. **Memberships Response Structure**:
+   ```json
+   {
+     "account_id": 654173,
+     "contact_id": "6833ef45...",
+     "product_id": "6833ef45...",
+     "status": "PENDING",
+     "_id": "6833ef45...",
+     "id": "6833ef45..."
+   }
+   ```
+
+### Future Considerations
+- Monitor if API adds support for prefixed IDs
+- Watch for changes in external_data handling
+- Consider adding response object wrappers to normalize field names

data/docs/patterns/testing-patterns.md

@@ -0,0 +1,152 @@
+# Testing Patterns for Patch Retention Gem
+
+## VCR Configuration
+
+### Setup
+```ruby
+VCR.configure do |config|
+  config.cassette_library_dir = "spec/fixtures/vcr_cassettes"
+  config.hook_into :webmock
+  config.configure_rspec_metadata!
+  config.default_cassette_options = {
+    record: :new_episodes,
+    match_requests_on: [:method, :uri, :body]
+  }
+  
+  # Filter sensitive data
+  config.filter_sensitive_data('<CLIENT_ID>') { '654173' }
+  config.filter_sensitive_data('<CLIENT_SECRET>') { 'secret_...' }
+end
+```
+
+### Usage in Specs
+Tag specs with `:vcr` to automatically record/replay HTTP interactions:
+```ruby
+describe ".create", :vcr do
+  # test implementation
+end
+```
+
+## Debugging Failed Specs
+
+### Using Debug Output
+When specs fail, add debug output to understand API responses:
+
+```ruby
+it "creates a product successfully" do
+  result = create_product
+  puts "DEBUG: Product creation result: #{result.inspect}"
+  
+  # assertions...
+end
+```
+
+### Common Debugging Patterns
+
+1. **Inspect Full Response**:
+   ```ruby
+   puts "DEBUG: API Response: #{result.inspect}"
+   ```
+
+2. **Check Specific Fields**:
+   ```ruby
+   puts "DEBUG: Contact ID used: #{contact['_id'] || contact['id']}"
+   puts "DEBUG: Product ID used: #{product['id']}"
+   ```
+
+3. **Conditional Debugging**:
+   ```ruby
+   if result["error"]
+     puts "DEBUG: Error response: #{result.inspect}"
+   end
+   ```
+
+## Test Data Patterns
+
+### Creating Test Objects
+Always create fresh test data for each test to avoid dependencies:
+
+```ruby
+let(:contact) do
+  PatchRetention::Contacts.find_or_create_by(
+    contact_params: {
+      first_name: "Test",
+      last_name: "User",
+      email: "test.user@example.com",
+      phone: "1234567890"
+    },
+    query_params: {
+      email: "test.user@example.com"
+    }
+  )
+end
+```
+
+### Handling API Quirks
+
+1. **Tag Capitalization**:
+   ```ruby
+   let(:tags) { ["Test", "Widget", "Api_created"] } # API capitalizes tags
+   ```
+
+2. **Optional Field Validation**:
+   ```ruby
+   # Only check if field exists in response
+   if result["tags"]
+     expect(result["tags"]).to eq(expected_tags)
+   end
+   ```
+
+3. **Flexible ID Validation**:
+   ```ruby
+   expect(result["id"]).to be_a(String)
+   expect(result["id"].length).to be > 0
+   ```
+
+## Custom Configuration Testing
+
+Always test that methods accept custom configuration:
+
+```ruby
+context "with custom configuration" do
+  let(:custom_config) do
+    PatchRetention::Configuration.new.tap do |config|
+      config.client_id = '654173'
+      config.client_secret = 'secret_...'
+    end
+  end
+
+  it "uses the custom configuration" do
+    result = described_class.create(
+      # params...
+      config: custom_config
+    )
+    
+    expect(result).to be_a(Hash)
+  end
+end
+```
+
+## Error Testing Patterns
+
+### Required Parameter Validation
+```ruby
+context "missing required fields" do
+  it "raises an error when name is missing" do
+    expect {
+      described_class.create(price: 999, status: "PUBLISHED")
+    }.to raise_error(ArgumentError, /missing keyword: :?name/)
+  end
+end
+```
+
+### API Error Handling
+```ruby
+context "with invalid data" do
+  it "raises PatchRetention::Error" do
+    expect {
+      described_class.update(membership_id: "invalid_id")
+    }.to raise_error(PatchRetention::Error, /Failed to update membership/)
+  end
+end
+```

data/docs/references/github-actions.md

@@ -0,0 +1,100 @@
+# GitHub Actions CI/CD Setup
+
+## Overview
+This gem uses GitHub Actions for continuous integration and deployment. The workflows ensure code quality, test coverage, and security.
+
+## Workflows
+
+### 1. CI Workflow (`.github/workflows/ci.yml`)
+**Triggers**: Push to main/master, Pull requests
+
+**Jobs**:
+- **Test Matrix**: Runs tests on Ruby 3.1, 3.2, and 3.3
+- **Minimum Version Test**: Ensures compatibility with Ruby 3.1
+- **Security Audit**: Checks for known vulnerabilities using bundler-audit
+
+**Steps**:
+1. Run RSpec tests
+2. Run RuboCop for code style
+3. Build the gem
+4. Security audit
+
+### 2. PR Test Workflow (`.github/workflows/pr-test.yml`)
+**Triggers**: Pull request events
+
+**Features**:
+- Runs tests with VCR in playback-only mode
+- Checks for sensitive data in VCR cassettes
+- Uses dummy credentials for testing
+
+**Security Check**:
+```bash
+grep -r "654173\|secret_A654173" spec/fixtures/vcr_cassettes/
+```
+
+### 3. Release Workflow (`.github/workflows/release.yml`)
+**Triggers**: Push of version tags (v*)
+
+**Process**:
+1. Run tests and linting
+2. Build gem
+3. Create GitHub release
+4. Upload gem artifact
+5. (Optional) Publish to RubyGems
+
+## Local Testing
+
+Run the test script to validate CI locally:
+```bash
+./.github/test-workflow.sh
+```
+
+This script runs:
+- All tests
+- RuboCop
+- Gem build
+- Sensitive data check
+- Security audit
+
+## Maintaining CI
+
+### Adding Ruby Versions
+Edit `.github/workflows/ci.yml`:
+```yaml
+strategy:
+  matrix:
+    ruby-version: ['3.1', '3.2', '3.3']
+```
+
+### Updating Dependencies
+The workflows use `bundler-cache: true` which automatically:
+- Runs `bundle install`
+- Caches dependencies
+- Restores cache on subsequent runs
+
+### Security Considerations
+1. **Never commit real API credentials**
+2. **VCR cassettes are checked for sensitive data**
+3. **Use environment variables for secrets**
+4. **Regular security audits via bundler-audit**
+
+### Troubleshooting
+
+**Tests fail in CI but pass locally**:
+- Check Ruby version differences
+- Ensure VCR cassettes are committed
+- Verify environment variables
+
+**RuboCop failures**:
+- Run `bundle exec rubocop -A` locally
+- Commit the fixes
+
+**Security audit failures**:
+- Update affected gems: `bundle update [gem_name]`
+- Check advisory details in output
+
+## Badge
+Add to README:
+```markdown
+[![CI](https://github.com/[USERNAME]/patch_retention/actions/workflows/ci.yml/badge.svg)](https://github.com/[USERNAME]/patch_retention/actions/workflows/ci.yml)
+```

data/docs/references/troubleshooting.md

@@ -0,0 +1,122 @@
+# Troubleshooting Guide
+
+## Common Issues and Solutions
+
+### 1. Contact ID Not Found
+**Problem**: Membership creation fails with "Invalid contact_id specified"
+
+**Cause**: Contacts API returns `_id` field, not `id`
+
+**Solution**:
+```ruby
+contact_id = contact["_id"] || contact["id"]
+```
+
+### 2. Tags Don't Match Expected Values
+**Problem**: Test assertions fail because tags don't match
+
+**Cause**: API automatically capitalizes all tags
+
+**Solution**:
+```ruby
+# Use capitalized tags in tests
+let(:tags) { ["Test", "Widget", "Premium"] }
+```
+
+### 3. External Data Not Returned
+**Problem**: `external_data` is nil in API response
+
+**Cause**: API accepts but doesn't always return external_data
+
+**Solution**:
+```ruby
+# Don't assert on external_data in responses
+# Or make it conditional:
+expect(result["external_data"]).to eq(data) if result["external_data"]
+```
+
+### 4. JSON Parse Error on Update
+**Problem**: `JSON::ParserError: unexpected token at 'Not Found'`
+
+**Cause**: Invalid ID format or non-existent resource
+
+**Solution**:
+```ruby
+# Ensure you're using the correct ID from creation
+membership_id = membership["id"]  # not "_id" for memberships
+```
+
+### 5. VCR Cassette Mismatch
+**Problem**: Tests fail with VCR errors about request not matching
+
+**Cause**: Request body or headers changed
+
+**Solution**:
+```bash
+# Delete the cassette and re-record
+rm spec/fixtures/vcr_cassettes/[cassette_name].yml
+bundle exec rspec [spec_file]
+```
+
+### 6. Debugging API Responses
+
+**Add debug output to specs**:
+```ruby
+it "creates a resource" do
+  result = create_resource
+  puts "DEBUG: API Response: #{result.inspect}"
+  
+  # This helps identify:
+  # - Actual field names returned
+  # - Data transformations by API
+  # - Error messages
+end
+```
+
+### 7. Phone Number Formatting
+**Problem**: Phone numbers have unexpected format
+
+**Cause**: API may prepend country code (e.g., "1234567890" becomes "11234567890")
+
+**Solution**: Be flexible with phone number assertions or normalize before comparison
+
+### 8. Timestamp Precision
+**Problem**: Time comparisons fail by small amounts
+
+**Solution**:
+```ruby
+expect(Time.parse(result["start_at"])).to be_within(60).of(Time.parse(expected_time))
+```
+
+### 9. Status Field Values
+**Note**: Memberships have a `status` field that defaults to "PENDING"
+
+### 10. Missing Methods After Updates
+**Problem**: NoMethodError for cancel/expire methods
+
+**Cause**: These methods were removed as they're not supported by the API
+
+**Solution**: Use the `update` method with status parameter if needed
+
+## Debug Checklist
+
+When a test fails:
+1. ✓ Add debug output to see actual API response
+2. ✓ Check if field names match (id vs _id)
+3. ✓ Verify data transformations (capitalization, formatting)
+4. ✓ Ensure test data is valid for the API
+5. ✓ Check VCR cassettes are up to date
+6. ✓ Verify API credentials are correct
+
+## Useful Debug Commands
+
+```bash
+# Run specific test with output
+bundle exec rspec spec/path/to/spec.rb:line_number --format documentation
+
+# Clear VCR cassettes
+rm -rf spec/fixtures/vcr_cassettes/
+
+# Run tests without VCR (live API calls)
+VCR=off bundle exec rspec
+```