patch_retention 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2ff39a288451016541c8a8f63aca54115fb7f2a4e6a83daea5b503ebe7956fb5
-  data.tar.gz: 6046dfe6d5692149f069ce54f14fd84bffb9139f3403710eb12c3050619f5130
+  metadata.gz: 9642c7116bc29f3cc1e9368c861ac11d13b2357ab778b4f9395fa2bb14c3edb3
+  data.tar.gz: 7dc040049c15f9b32eb83d06a986daa0da1c4c881d1dfd2553dc764d9fbba494
 SHA512:
-  metadata.gz: a3ea0a8fe3c04033678ebd81da8b003a995baa8515ebb2f518c459acf9a2d4d5f97ccb3499143ea4ee2f2595c3cdcad28b19d97620929e3a9834fad27b57d1f6
-  data.tar.gz: d4c4fb944b2412112d19155f1f4bbe1d190fc23e9ff9ea3584a8bf5505668c996a708f5a8dc8174080e4cbaa5c8dced9d53eda0ff4f1f114dd33c27f9f60e3f8
+  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/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:
@@ -290,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/version.rb

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

data/patch_retention.gemspec

@@ -0,0 +1,57 @@
+# 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", "~> 1.10")
+  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("thor", ">= 1.4.0")
+  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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: patch_retention
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Playbypoint
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-07-28 00:00:00.000000000 Z
+date: 2025-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -67,20 +67,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 +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
@@ -251,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
@@ -264,6 +265,7 @@ files:
 - lib/patch_retention/products.rb
 - lib/patch_retention/util.rb
 - lib/patch_retention/version.rb
+- patch_retention.gemspec
 - script/setup_test_env
 - sig/patch_retention.rbs
 homepage: https://playbypoint.com