patch_retention 0.1.4 → 0.2.0

data/docs/wip/session-2025-05-26.md

@@ -0,0 +1,66 @@
+# Work Session: 2025-05-26
+
+## Session Overview
+Implemented Products and Memberships endpoints for Patch Retention API v2 gem, including comprehensive test coverage.
+
+## Completed Tasks
+
+### 1. Memberships Implementation
+- ✅ Added `create` method for POST /v2/memberships
+- ✅ Added `update` method for PATCH /v2/memberships/{id}
+- ✅ Added `find` method for GET /v2/memberships/{id}
+- ❌ Removed `cancel` and `expire` methods (not supported by API)
+
+### 2. Products Implementation  
+- ✅ Added `update` method for PATCH /v2/products/{id}
+- ✅ Added `find` method for GET /v2/products/{id}
+- Note: `create` method was already implemented
+
+### 3. Test Infrastructure
+- ✅ Added VCR gem for recording/replaying HTTP interactions
+- ✅ Added WebMock for HTTP stubbing
+- ✅ Configured RSpec with VCR integration
+- ✅ Added sensitive data filtering for credentials
+
+### 4. Comprehensive Test Coverage
+- ✅ Created full test suite for Products (13 examples)
+- ✅ Created full test suite for Memberships (13 examples)
+- ✅ All 28 tests passing
+
+## Key Discoveries
+
+### API Behavior
+1. **ID Format**: API returns MongoDB-style IDs (e.g., `6833ef45...`) not prefixed IDs
+2. **Contact IDs**: Use `_id` field, not `id`
+3. **Tag Processing**: API capitalizes all tags automatically
+4. **External Data**: Accepted in requests but not always returned in responses
+5. **Default Values**: Memberships get `status: "PENDING"` by default
+
+### Test Data Used
+- Client ID: `654173`
+- Client Secret: `secret_A654173_KgaeVLoWzBLYQZ2uE21Du8yrXS7VXRU5e7yy9GYS3wnfPZbGNbYsmTkrmw8Z`
+- Test endpoint: https://api.patchretention.com/v2
+
+## Next Steps
+- [ ] Add Rubocop with Shopify style guide
+- [ ] Add list/all methods for Products and Memberships
+- [ ] Add delete operations if supported by API
+- [ ] Implement pagination for list operations
+- [ ] Add retry logic for transient failures
+
+## Files Modified
+- `lib/patch_retention/memberships.rb` - Added update, find methods
+- `lib/patch_retention/products.rb` - Added update, find methods
+- `spec/patch_retention/memberships_spec.rb` - New comprehensive test suite
+- `spec/patch_retention/products_spec.rb` - New comprehensive test suite
+- `spec/spec_helper.rb` - Added VCR configuration
+- `Gemfile` - Added VCR and WebMock gems
+- `README.md` - Updated with new method documentation
+- `CLAUDE.md` - Updated with findings and removed cancelled/expired references
+
+## Important Notes for Future Sessions
+1. Always use debug output in specs when tests fail
+2. Be aware of API field name differences (_id vs id)
+3. Expect tags to be capitalized
+4. Don't rely on external_data being returned
+5. Use flexible assertions for API responses

data/lib/patch_retention/configuration.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module PatchRetention # rubocop:disable Style/ClassAndModuleChildren
+module PatchRetention
   class Configuration
     attr_accessor :api_url, :proxy_url, :client_id, :client_secret
 

data/lib/patch_retention/contacts/find_or_create.rb

@@ -7,7 +7,10 @@ module PatchRetention::Contacts::FindOrCreate
   def call(contact_params:, query_params:, config: nil)
     raise_error_if_present do
       PatchRetention.connection(config).patch(PatchRetention::Contacts::API_PATH) do |req|
-        req.params["search"] = build_search_string(query_params)
+        build_search_params(query_params).each do |key, value|
+          req.params[key] = value
+        end
+
         req.body = contact_params
       end
     end
@@ -15,11 +18,10 @@ module PatchRetention::Contacts::FindOrCreate
 
   private
 
-  def build_search_string(query_params)
-    query_params = query_params.slice(:email, :phone).compact.map do |key, value|
-      { "search:#{key}" => value }
-    end.reduce(&:merge)
-
-    URI.encode_www_form(query_params)
+  # Returns a hash of search parameters, correctly prefixed
+  def build_search_params(query_params)
+    query_params.slice(:email, :phone).compact.transform_keys do |key|
+      "search:#{key}"
+    end
   end
 end

data/lib/patch_retention/contacts.rb

@@ -16,7 +16,7 @@ class PatchRetention::Contacts
       FindOrCreate.call(
         contact_params: contact_params,
         query_params: query_params,
-        config: config
+        config: config,
       )
     end
 

data/lib/patch_retention/events/create.rb

@@ -12,7 +12,7 @@ module PatchRetention::Events::Create
       primary_key: primary_key_details[:key],
       primary_key_value: primary_key_details[:value],
       data: data,
-      contact_upsert: contact_upsert
+      contact_upsert: contact_upsert,
     }.compact
 
     params.merge!(at: format_datetime(at)) unless at.nil?

data/lib/patch_retention/events.rb

@@ -19,7 +19,7 @@ class PatchRetention::Events
         data: data,
         at: at,
         contact_details: contact_details,
-        config: config
+        config: config,
       )
     end
   end

data/lib/patch_retention/memberships.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PatchRetention
+  class Memberships
+    class << self
+      def create(contact_id:, product_id:, start_at: nil, end_at: nil, external_id: nil, external_data: nil,
+        tags: nil, config: nil)
+        payload = {
+          contact_id: contact_id,
+          product_id: product_id,
+        }
+        payload[:start_at] = start_at if start_at
+        payload[:end_at] = end_at if end_at
+        payload[:external_id] = external_id if external_id
+        payload[:external_data] = external_data if external_data
+        payload[:tags] = tags if tags
+
+        response = PatchRetention.connection(config).post("/v2/memberships") do |req|
+          req.body = payload.to_json
+          req.headers["Content-Type"] = "application/json"
+        end
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        # You might want to handle different types of Faraday errors differently
+        # or raise a custom error class
+        raise Error, "Failed to create membership: #{e.message}"
+      end
+
+      def update(membership_id:, start_at: nil, end_at: nil, external_id: nil, external_data: nil,
+        tags: nil, status: nil, config: nil)
+        payload = {}
+        payload[:start_at] = start_at if start_at
+        payload[:end_at] = end_at if end_at
+        payload[:external_id] = external_id if external_id
+        payload[:external_data] = external_data if external_data
+        payload[:tags] = tags if tags
+        payload[:status] = status if status
+
+        response = PatchRetention.connection(config).patch("/v2/memberships/#{membership_id}") do |req|
+          req.body = payload.to_json
+          req.headers["Content-Type"] = "application/json"
+        end
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to update membership: #{e.message}"
+      end
+
+      def find(membership_id:, config: nil)
+        response = PatchRetention.connection(config).get("/v2/memberships/#{membership_id}")
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to find membership: #{e.message}"
+      end
+    end
+  end
+end

data/lib/patch_retention/products.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module PatchRetention
+  class Products
+    class << self
+      def create(name:, price:, status:, description: nil, membership: nil,
+        tags: nil, external_id: nil, external_data: nil, config: nil)
+        payload = {
+          name: name,
+          price: price,
+          status: status,
+        }
+        payload[:description] = description if description
+        payload[:membership] = membership unless membership.nil?
+        payload[:tags] = tags if tags
+        payload[:external_id] = external_id if external_id
+        payload[:external_data] = external_data if external_data
+
+        response = PatchRetention.connection(config).post("/v2/products") do |req|
+          req.body = payload.to_json
+          req.headers["Content-Type"] = "application/json"
+        end
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        # You might want to handle different types of Faraday errors differently
+        # or raise a custom error class
+        raise Error, "Failed to create product: #{e.message}"
+      end
+
+      def update(product_id:, name: nil, price: nil, status: nil, description: nil,
+        membership: nil, tags: nil, external_id: nil, external_data: nil, config: nil)
+        payload = {}
+        payload[:name] = name if name
+        payload[:price] = price if price
+        payload[:status] = status if status
+        payload[:description] = description if description
+        payload[:membership] = membership unless membership.nil?
+        payload[:tags] = tags if tags
+        payload[:external_id] = external_id if external_id
+        payload[:external_data] = external_data if external_data
+
+        response = PatchRetention.connection(config).patch("/v2/products/#{product_id}") do |req|
+          req.body = payload.to_json
+          req.headers["Content-Type"] = "application/json"
+        end
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to update product: #{e.message}"
+      end
+
+      def find(product_id:, config: nil)
+        response = PatchRetention.connection(config).get("/v2/products/#{product_id}")
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to find product: #{e.message}"
+      end
+    end
+  end
+end

data/lib/patch_retention/util.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module PatchRetention # rubocop:disable Style/ClassAndModuleChildren
+module PatchRetention
   # The Util module provides utility methods used across the PatchRetention library.
   # These methods are designed to handle common tasks such as error handling and response parsing.
   module Util
@@ -25,7 +25,7 @@ module PatchRetention # rubocop:disable Style/ClassAndModuleChildren
     def parse_error_message(response)
       if response.status == 502 && response.body.blank?
         raise PatchRetention::Error,
-              "Internal Server Error: Patch API"
+          "Internal Server Error: Patch API"
       end
 
       JSON.parse(response.body)["error"]

data/lib/patch_retention/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PatchRetention
-  VERSION = "0.1.4"
+  VERSION = "0.2.0"
 end

data/lib/patch_retention.rb

@@ -26,17 +26,17 @@ module PatchRetention
     end
 
     def connection(config = nil)
-      config = config || configuration
+      config ||= configuration
 
       Faraday.new(
         url: config.api_url,
         proxy: config.proxy_url,
         headers: {
           "Authorization" => "Bearer #{config.client_secret}",
-          "X-Account-Id" => config.client_id
-        }
+          "X-Account-Id" => config.client_id,
+        },
       ) do |builder|
-        builder.request :json
+        builder.request(:json)
       end
     end
   end

data/patch_retention.gemspec

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "lib/patch_retention/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "patch_retention"
+  spec.version = PatchRetention::VERSION
+  spec.authors = ["Playbypoint", "Gerardo Ortega"]
+  spec.email = ["webmaster@playbypoint.com", "g3ortega@gmail.com"]
+
+  spec.summary = "Patch Retention API wrapper."
+  spec.description = "Patch Retention API wrapper."
+  spec.homepage = "https://playbypoint.com"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  # spec.metadata["allowed_push_host"] = "Set to your gem server 'https://example.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://playbypoint.com"
+  spec.metadata["changelog_uri"] = "https://playbypoint.com"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    %x(git ls-files -z).split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency("faraday", "~> 2.0")
+  spec.add_dependency("zeitwerk", "~> 2.6")
+
+  # Development dependencies
+  spec.add_development_dependency("bundler", "~> 2.0")
+  spec.add_development_dependency("bundler-audit", "~> 0.9")
+  spec.add_development_dependency("byebug")
+  spec.add_development_dependency("dotenv", "~> 2.8")
+  spec.add_development_dependency("pry")
+  spec.add_development_dependency("rake", "~> 13.0")
+  spec.add_development_dependency("rspec", "~> 3.0")
+  spec.add_development_dependency("rubocop", "~> 1.21")
+  spec.add_development_dependency("rubocop-shopify", "~> 2.15")
+  spec.add_development_dependency("vcr", "~> 6.0")
+  spec.add_development_dependency("webmock", "~> 3.0")
+
+  # Security update for rexml
+  spec.add_development_dependency("rexml", ">= 3.3.9")
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

data/script/setup_test_env

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "fileutils"
+
+puts "Setting up test environment..."
+
+env_file = ".env.test"
+
+# Check if .env.test already exists
+if File.exist?(env_file)
+  print "#{env_file} already exists. Overwrite? (y/n): "
+  response = gets.chomp.downcase
+  exit unless response == "y"
+end
+
+# Check for environment variables
+client_id = ENV["PATCH_RETENTION_TEST_CLIENT_ID"] || ENV["PATCH_RETENTION_CLIENT_ID"]
+client_secret = ENV["PATCH_RETENTION_TEST_CLIENT_SECRET"] || ENV["PATCH_RETENTION_CLIENT_SECRET"]
+
+if client_id.nil? || client_secret.nil?
+  puts "\nError: Test credentials not found in environment variables."
+  puts "\nPlease set the following environment variables:"
+  puts "  PATCH_RETENTION_TEST_CLIENT_ID"
+  puts "  PATCH_RETENTION_TEST_CLIENT_SECRET"
+  puts "\nYou can export them in your shell:"
+  puts "  export PATCH_RETENTION_TEST_CLIENT_ID=your_client_id"
+  puts "  export PATCH_RETENTION_TEST_CLIENT_SECRET=your_client_secret"
+  puts "\nOr create a .env.test file manually with:"
+  puts "  PATCH_RETENTION_CLIENT_ID=your_client_id"
+  puts "  PATCH_RETENTION_CLIENT_SECRET=your_client_secret"
+  puts "  PATCH_RETENTION_API_URL=https://api.patchretention.com/v2"
+  exit 1
+end
+
+# Create .env.test file
+File.open(env_file, "w") do |f|
+  f.puts "PATCH_RETENTION_CLIENT_ID=#{client_id}"
+  f.puts "PATCH_RETENTION_CLIENT_SECRET=#{client_secret}"
+  f.puts "PATCH_RETENTION_API_URL=https://api.patchretention.com/v2"
+end
+
+puts "✓ Created #{env_file} successfully!"
+puts "\nYou can now run tests with: bundle exec rake spec"