patch_retention 0.2.2 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff39a288451016541c8a8f63aca54115fb7f2a4e6a83daea5b503ebe7956fb5
-  data.tar.gz: 6046dfe6d5692149f069ce54f14fd84bffb9139f3403710eb12c3050619f5130
+  metadata.gz: 109e3aa27d410ae2245f0b1de8a71a1531951869ff99e1c122e406c172e41c5b
+  data.tar.gz: 6666fdc1241ae1bb07fe9e5a014fd6f8c4950c9e9521ebb1c4d1e036c9135f03
 SHA512:
-  metadata.gz: a3ea0a8fe3c04033678ebd81da8b003a995baa8515ebb2f518c459acf9a2d4d5f97ccb3499143ea4ee2f2595c3cdcad28b19d97620929e3a9834fad27b57d1f6
-  data.tar.gz: d4c4fb944b2412112d19155f1f4bbe1d190fc23e9ff9ea3584a8bf5505668c996a708f5a8dc8174080e4cbaa5c8dced9d53eda0ff4f1f114dd33c27f9f60e3f8
+  metadata.gz: 747343cd474efbbf2e881bf9921cc0b9c4166821a96f2fcf69edcc8effee88481b0f80bcfae9921b631fb66a72df39d2934e4f69424df7c2352d4f2faaf5a28f
+  data.tar.gz: 18b13644f200d75450d070b085a054d02da6aab70d51981cce43126371d50dfe2eefc2c42bf2caa70d9d878cdcc15e18f9337dc7d721d5f1b4c85b6bc0e1ba3e

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [Unreleased]
 
+## [0.3.2] - 2025-01-19
+
+### Added
+- Added `next_billing_at` field support to `Memberships.create` method for setting the next billing date
+
+## [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/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    patch_retention (0.2.2)
+    patch_retention (0.3.1)
       faraday (~> 1.10)
       zeitwerk (~> 2.6)
 

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:
@@ -264,6 +278,7 @@ membership = PatchRetention::Memberships.create(
   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)
+  next_billing_at: (Time.now + 7*24*60*60).xmlschema, # Optional, ISO8601 timestamp for next billing date
   external_id: "MEM123", # Optional
   data: {
     "is_trial" => true,
@@ -290,6 +305,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,14 +3,15 @@
 module PatchRetention
   class Memberships
     class << self
-      def create(contact_id:, product_id:, start_at: nil, end_at: nil, external_id: nil, tags: nil, data: nil,
-        config: nil)
+      def create(contact_id:, product_id:, start_at: nil, end_at: nil, next_billing_at: nil, external_id: nil,
+        tags: nil, data: 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[:next_billing_at] = next_billing_at if next_billing_at
         payload[:external_id] = external_id if external_id
         payload[:tags] = tags if tags
         payload[:data] = data if data

data/lib/patch_retention/version.rb

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

metadata

@@ -1,15 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: patch_retention
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.2
 platform: ruby
 authors:
 - Playbypoint
 - Gerardo Ortega
+- Segundo Rebaza
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-28 00:00:00.000000000 Z
+date: 2025-09-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -67,20 +68,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.9'
-- !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: byebug
   requirement: !ruby/object:Gem::Requirement
@@ -179,6 +166,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
@@ -225,6 +226,7 @@ description: Patch Retention API wrapper.
 email:
 - webmaster@playbypoint.com
 - g3ortega@gmail.com
+- alvaro.rp1593@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -251,6 +253,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