patch_retention 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a2a099b064c0ef56c80743759676b3dc37d4de5ee636e0f2cf271ec5e7726c4
-  data.tar.gz: fa4eacdf94682e3156faa8a0580a0afcb803604f13187954bc87de0298726077
+  metadata.gz: 9642c7116bc29f3cc1e9368c861ac11d13b2357ab778b4f9395fa2bb14c3edb3
+  data.tar.gz: 7dc040049c15f9b32eb83d06a986daa0da1c4c881d1dfd2553dc764d9fbba494
 SHA512:
-  metadata.gz: 1eeac799c480635c1120170d0d2bf5c4d44acf34b744e86e652fc4c0dd664d73b6c7523278b338e12aaed419647b6d8c14873269225347cf8b51cd7428020659
-  data.tar.gz: c948d3b077bd7e84c9753a60f1e962d736c5332a2122817caefef16c6be56d499d5037e5de4571f48378c07ee3e4ba4bf65f3a3d47993a940b0718dfe9b43b7d
+  metadata.gz: cd6b62c587f1ad1ed68b579bfcd70403a916de81593248d4850664b4495dc2ff316d279b338952dfb332f038f1c3b63240907345544298becbf14fe749345806
+  data.tar.gz: 82fe4b41064b55979b281ad05e48459ae3230e04d91f32065ecab1bf030e337bc56b791a6786ba09fb6bee7b7ec75a808485b8f986713cb888543248278e43f0

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.3.1] - 2025-09-04
+
+### Added
+- Added `tags` parameter support to `CalendarItems.create` method for categorizing calendar items
+- Added `email` parameter to `Contacts.all` method for filtering contacts by email address
+
+### Changed
+- **BREAKING**: Updated `Contacts.all` method to use keyword arguments (limit:, offset:, email:, config:) instead of positional arguments
+
+## [0.3.0] - 2025-07-27
+
+### Added
+- Calendar Items API support with full CRUD operations:
+  - `create` - Create calendar events for contacts
+  - `update` - Update existing calendar items
+  - `find` - Retrieve a specific calendar item
+  - `delete` - Remove calendar items
+  - `all` - List calendar items with filtering and pagination support
+- Support for calendar item metadata including description, location, external_id, external_data, and tags
+- Comprehensive test coverage for Calendar Items functionality
+
 ## [0.2.0] - 2025-05-26
 
 ### Added

data/CLAUDE.md

@@ -171,6 +171,11 @@ The gem uses dotenv for credential management:
 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
+5. **Time/Date Testing with VCR**: 
+   - Avoid strict time comparisons with `Time.now` as VCR cassettes may be recorded at different times
+   - Instead of `expect(Time.parse(result["date"])).to(be_within(24 * 60 * 60).of(Time.now))`
+   - Use format validation: `expect(result["date"]).to match(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)`
+   - Or simply verify presence: `expect(result["date"]).not_to be_nil`
 
 ### Code Style
 - Using Shopify's Rubocop style guide (`rubocop-shopify` gem)

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    patch_retention (0.2.1)
+    patch_retention (0.3.1)
       faraday (~> 1.10)
       zeitwerk (~> 2.6)
 
@@ -94,7 +94,7 @@ GEM
       rubocop (~> 1.51)
     ruby-progressbar (1.13.0)
     ruby2_keywords (0.0.5)
-    thor (1.3.2)
+    thor (1.4.0)
     unicode-display_width (2.5.0)
     vcr (6.3.1)
       base64
@@ -119,6 +119,7 @@ DEPENDENCIES
   rspec (~> 3.0)
   rubocop (~> 1.21)
   rubocop-shopify (~> 2.15)
+  thor (>= 1.4.0)
   vcr (~> 6.0)
   webmock (~> 3.0)
 

data/README.md

@@ -118,7 +118,21 @@ Then, you can use the gem's methods to interact with the API.
 To retrieve all contacts:
 
 ```ruby
+# Basic usage
 contacts = PatchRetention::Contacts.all
+
+# With pagination (using keyword arguments)
+contacts = PatchRetention::Contacts.all(limit: 10, offset: 0)
+
+# With email filter
+contacts = PatchRetention::Contacts.all(email: 'john.doe@example.com')
+
+# With pagination and email filter
+contacts = PatchRetention::Contacts.all(
+  limit: 50,
+  offset: 0,
+  email: 'john@example.com'
+)
 ```
 
 To retrieve a single contact:
@@ -265,7 +279,10 @@ membership = PatchRetention::Memberships.create(
   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
+  data: {
+    "is_trial" => true,
+    "trial_ends_at" => (Time.now + 15*24*60*60).xmlschema
+  }, # Optional, hash for custom data
   tags: ["trial", "api_created"] # Optional, array of strings
 )
 # => {"id"=>"mem_xxxxxxxxxxxxxx", "contact_id"=>"ct_xxxxxxxxxxxxxx", ...}
@@ -287,6 +304,90 @@ To find a membership:
 membership = PatchRetention::Memberships.find(membership_id: "mem_xxxxxxxxxxxxxx")
 ```
 
+**Calendar Items**
+
+To create a calendar item:
+
+```ruby
+calendar_item = PatchRetention::CalendarItems.create(
+  contact_id: "ct_xxxxxxxxxxxxxx", # Required, ID of the contact
+  title: "Tennis Court Reservation", # Required, title of the event
+  start_at: "2025-02-01T10:00:00Z", # Required, ISO8601 timestamp - when the event starts
+  end_at: "2025-02-01T11:00:00Z", # Required, ISO8601 timestamp - when the event ends
+  run_start_at: "2025-02-01T09:30:00Z", # Optional, ISO8601 - when to run the event for this item (defaults to start_at if not set)
+  run_end_at: "2025-02-01T11:30:00Z", # Optional, ISO8601 - when to run the event for this item (defaults to end_at if not set)
+  data: { # Optional, additional metadata that will be included in the calendar item
+    external_id: "res_123456", # Your system's ID
+    facility_id: "fac_789",
+    court_name: "Court 1",
+    reservation_type: "match"
+  },
+  tags: ["tennis", "premium", "court1"], # Optional, array of tags to categorize the calendar item
+  time_occurred: "2025-01-28T09:00:00Z", # Optional, ISO8601 - past or current time for the event (will default to now)
+  skip_triggers: false # Optional, if set to false or empty, any automation tied to the calendar item will not run
+)
+# => {"id"=>"cal_xxxxxxxxxxxxxx", "contact_id"=>"ct_xxxxxxxxxxxxxx", ...}
+```
+
+To update a calendar item:
+
+```ruby
+calendar_item = PatchRetention::CalendarItems.update(
+  calendar_item_id: "cal_xxxxxxxxxxxxxx",
+  title: "Updated Tennis Match",
+  end_at: "2025-02-01T12:00:00Z", # Extend by 1 hour
+  data: {
+    description: "Match extended due to tie-break"
+  },
+  tags: ["Tennis", "Extended", "Tie-break"] # Tags as separate parameter
+)
+```
+
+To find a calendar item:
+
+```ruby
+calendar_item = PatchRetention::CalendarItems.find(calendar_item_id: "cal_xxxxxxxxxxxxxx")
+```
+
+To delete a calendar item:
+
+```ruby
+result = PatchRetention::CalendarItems.delete(calendar_item_id: "cal_xxxxxxxxxxxxxx")
+# => { success: true }
+```
+
+To list calendar items:
+
+```ruby
+# List all calendar items
+calendar_items = PatchRetention::CalendarItems.all()
+
+# List calendar items for a specific contact
+calendar_items = PatchRetention::CalendarItems.all(contact_id: "ct_xxxxxxxxxxxxxx")
+
+# List calendar items within ID range (MongoDB IDs)
+calendar_items = PatchRetention::CalendarItems.all(
+  min_id: "0123456789abcdefghijklmn", # Get all items on or after this ID
+  max_id: "0123456789abcdefghijklmn"  # Get all items on or before this ID
+)
+
+# List specific calendar items by IDs (comma-separated)
+calendar_items = PatchRetention::CalendarItems.all(
+  id: "0123456789abcdefghijklmn,123456789abcdefghijklmn"
+)
+
+# Filter by date range (predefined options)
+calendar_items = PatchRetention::CalendarItems.all(
+  date_range: "Today"  # Options: "Today", "Yesterday", "Last 7 Days", "This Week", "Last Week", "Last 30 Days"
+)
+
+# With pagination
+calendar_items = PatchRetention::CalendarItems.all(
+  limit: 50,  # Default is 50, max is 100
+  offset: 25  # Skip first 25 results
+)
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies.

data/lib/patch_retention/calendar_items.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module PatchRetention
+  class CalendarItems
+    class << self
+      def create(contact_id:, title:, start_at:, end_at:, run_start_at: nil, run_end_at: nil,
+        data: nil, time_occurred: nil, skip_triggers: false, tags: nil, config: nil)
+        payload = {
+          contact_id: contact_id,
+          title: title,
+          start_at: start_at,
+          end_at: end_at,
+        }
+        payload[:run_start_at] = run_start_at if run_start_at
+        payload[:run_end_at] = run_end_at if run_end_at
+        payload[:data] = data if data
+        payload[:time_occurred] = time_occurred if time_occurred
+        payload[:skip_triggers] = skip_triggers unless skip_triggers.nil?
+        payload[:tags] = tags if tags
+
+        response = PatchRetention.connection(config).post("/v2/calendar_items") 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 create calendar item: #{e.message}"
+      end
+
+      def update(calendar_item_id:, title: nil, start_at: nil, end_at: nil, run_start_at: nil,
+        run_end_at: nil, data: nil, tags: nil, config: nil)
+        payload = {}
+        payload[:title] = title if title
+        payload[:start_at] = start_at if start_at
+        payload[:end_at] = end_at if end_at
+        payload[:run_start_at] = run_start_at if run_start_at
+        payload[:run_end_at] = run_end_at if run_end_at
+        payload[:data] = data if data
+        payload[:tags] = tags if tags
+
+        response = PatchRetention.connection(config).patch("/v2/calendar_items/#{calendar_item_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 calendar item: #{e.message}"
+      end
+
+      def find(calendar_item_id:, config: nil)
+        response = PatchRetention.connection(config).get("/v2/calendar_items/#{calendar_item_id}")
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to find calendar item: #{e.message}"
+      end
+
+      def delete(calendar_item_id:, config: nil)
+        response = PatchRetention.connection(config).delete("/v2/calendar_items/#{calendar_item_id}")
+
+        { success: response.status == 204 }
+      rescue Faraday::Error => e
+        raise Error, "Failed to delete calendar item: #{e.message}"
+      end
+
+      def all(contact_id: nil, min_id: nil, max_id: nil, id: nil, date_range: nil, limit: nil, offset: nil, config: nil)
+        params = {}
+        params[:contact_id] = contact_id if contact_id
+        params[:min_id] = min_id if min_id
+        params[:max_id] = max_id if max_id
+        params[:id] = id if id
+        params[:date_range] = date_range if date_range
+        params[:limit] = limit if limit
+        params[:offset] = offset if offset
+
+        response = PatchRetention.connection(config).get("/v2/calendar_items", params)
+
+        JSON.parse(response.body)
+      rescue Faraday::Error => e
+        raise Error, "Failed to retrieve calendar items: #{e.message}"
+      end
+    end
+  end
+end

data/lib/patch_retention/contacts/find.rb

@@ -29,13 +29,16 @@ module PatchRetention::Contacts::Find
   #
   # @param limit [Integer] The number of contacts to retrieve per page.
   # @param offset [Integer] The number of contacts to skip before starting to collect the result set.
+  # @param email [String] Optional email to filter contacts by.
+  # @param config [Configuration] Optional configuration object.
   # @return [Object] The response from the PatchRetention API.
   # @raise [PatchRetention::Error] If the API returns a status other than 200.
-  def all(limit, offset, config = nil)
+  def all(limit:, offset:, email: nil, config: nil)
     raise_error_if_present do
       PatchRetention.connection(config).get(PatchRetention::Contacts::API_PATH) do |req|
         req.params["limit"] = limit
         req.params["offset"] = offset
+        req.params["email"] = email if email
       end
     end
   end

data/lib/patch_retention/contacts.rb

@@ -8,8 +8,8 @@ class PatchRetention::Contacts
       Find.by_id(id, config)
     end
 
-    def all(limit = 30, offset = 0, config = nil)
-      Find.all(limit, offset, config)
+    def all(limit: 30, offset: 0, email: nil, config: nil)
+      Find.all(limit: limit, offset: offset, email: email, config: config)
     end
 
     def find_or_create_by(contact_params:, query_params: {}, config: nil)

data/lib/patch_retention/memberships.rb

@@ -3,8 +3,8 @@
 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)
+      def create(contact_id:, product_id:, start_at: nil, end_at: nil, external_id: nil, tags: nil, data: nil,
+        config: nil)
         payload = {
           contact_id: contact_id,
           product_id: product_id,
@@ -12,8 +12,8 @@ module PatchRetention
         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[:data] = data if data
 
         response = PatchRetention.connection(config).post("/v2/memberships") do |req|
           req.body = payload.to_json

data/lib/patch_retention/version.rb

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

data/patch_retention.gemspec

@@ -45,6 +45,7 @@ Gem::Specification.new do |spec|
   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("thor", ">= 1.4.0")
   spec.add_development_dependency("vcr", "~> 6.0")
   spec.add_development_dependency("webmock", "~> 3.0")
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patch_retention
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.1
 platform: ruby
 authors:
 - Playbypoint
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-21 00:00:00.000000000 Z
+date: 2025-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -165,6 +165,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.15'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.4.0
 - !ruby/object:Gem::Dependency
   name: vcr
   requirement: !ruby/object:Gem::Requirement
@@ -237,6 +251,7 @@ files:
 - docs/references/troubleshooting.md
 - docs/wip/session-2025-05-26.md
 - lib/patch_retention.rb
+- lib/patch_retention/calendar_items.rb
 - lib/patch_retention/configuration.rb
 - lib/patch_retention/contacts.rb
 - lib/patch_retention/contacts/delete.rb