castle-rb 8.0.0 → 9.0.0

data/lib/castle/api/lists/create.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    # Namespace for the lists API endpoints
+    module Lists
+      # Sends POST /lists request
+      module Create
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::Create.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/lists/delete.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Lists
+      # Sends DELETE /lists/:list_id request
+      module Delete
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::Delete.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/lists/get.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Lists
+      # Sends GET /lists/:list_id request
+      module Get
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::Get.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/lists/get_all.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Lists
+      # Sends GET /lists request
+      module GetAll
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::GetAll.build, {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/lists/query.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Lists
+      # Sends POST /lists/query request
+      module Query
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::Query.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/lists/update.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Lists
+      # Sends PUT /lists/:list_id request
+      module Update
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Lists::Update.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/log.rb

@@ -18,7 +18,8 @@ module Castle
         rescue Castle::RequestError, Castle::InternalServerError => e
           unless config.failover_strategy == :throw
             strategy = (config || Castle.config).failover_strategy
-            return(Castle::Failover::PrepareResponse.new(options[:user][:id], reason: e.to_s, strategy: strategy).call)
+            user_id = options.dig(:user, :id)
+            return Castle::Failover::PrepareResponse.new(user_id, reason: e.to_s, strategy: strategy).call
           end
 
           raise e

data/lib/castle/api/privacy/delete_data.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Privacy
+      # Sends DELETE /v1/privacy/users — permanently purges a user's data from Castle.
+      # Closes #261 (GDPR Article 17).
+      module DeleteData
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Privacy::DeleteData.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/privacy/request_data.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module API
+    module Privacy
+      # Sends POST /v1/privacy/users — Castle compiles the user's data and emails it
+      # to the configured privacy mailbox. Closes #261 (GDPR Article 15).
+      module RequestData
+        class << self
+          # @param options [Hash]
+          # @return [Hash]
+          def call(options = {})
+            options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
+            http = options.delete(:http)
+            config = options.delete(:config) || Castle.config
+
+            Castle::API.call(Castle::Commands::Privacy::RequestData.build(options), {}, http, config)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/api/risk.rb

@@ -18,7 +18,8 @@ module Castle
         rescue Castle::RequestError, Castle::InternalServerError => e
           unless config.failover_strategy == :throw
             strategy = (config || Castle.config).failover_strategy
-            return(Castle::Failover::PrepareResponse.new(options[:user][:id], reason: e.to_s, strategy: strategy).call)
+            user_id = options.dig(:user, :id)
+            return Castle::Failover::PrepareResponse.new(user_id, reason: e.to_s, strategy: strategy).call
           end
 
           raise e

data/lib/castle/client.rb

@@ -3,6 +3,10 @@
 module Castle
   # Castle's client.
   class Client
+    include Castle::ClientActions::ListItems
+    include Castle::ClientActions::Lists
+    include Castle::ClientActions::Privacy
+
     class << self
       def from_request(request, options = {})
         new(options.merge(context: Castle::Context::Prepare.call(request, options)))
@@ -19,37 +23,11 @@ module Castle
       @context = options.fetch(:context) { {} }
     end
 
-    # @param options [Hash]
-    def authenticate(options = {})
-      options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
-
-      return generate_do_not_track_response(options[:user_id]) unless tracked?
-
-      add_timestamp_if_necessary(options)
-
-      new_context = Castle::Context::Merge.call(@context, options[:context])
-
-      Castle::API::Authenticate.call(options.merge(context: new_context, no_symbolize: true))
-    end
-
-    # @param options [Hash]
-    def track(options = {})
-      options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
-
-      return unless tracked?
-
-      add_timestamp_if_necessary(options)
-
-      new_context = Castle::Context::Merge.call(@context, options[:context])
-
-      Castle::API::Track.call(options.merge(context: new_context, no_symbolize: true))
-    end
-
     # @param options [Hash]
     def filter(options = {})
       options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
 
-      return generate_do_not_track_response(options[:user][:id]) unless tracked?
+      return generate_do_not_track_response(failover_user_id(options)) unless tracked?
 
       add_timestamp_if_necessary(options)
 
@@ -62,7 +40,7 @@ module Castle
     def risk(options = {})
       options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
 
-      return generate_do_not_track_response(options[:user][:id]) unless tracked?
+      return generate_do_not_track_response(failover_user_id(options)) unless tracked?
 
       add_timestamp_if_necessary(options)
 
@@ -75,7 +53,7 @@ module Castle
     def log(options = {})
       options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
 
-      return generate_do_not_track_response(options[:user][:id]) unless tracked?
+      return generate_do_not_track_response(failover_user_id(options)) unless tracked?
 
       add_timestamp_if_necessary(options)
 
@@ -84,28 +62,6 @@ module Castle
       Castle::API::Log.call(options.merge(context: new_context, no_symbolize: true))
     end
 
-    # @param options [Hash]
-    def start_impersonation(options = {})
-      options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
-
-      add_timestamp_if_necessary(options)
-
-      new_context = Castle::Context::Merge.call(@context, options[:context])
-
-      Castle::API::StartImpersonation.call(options.merge(context: new_context, no_symbolize: true))
-    end
-
-    # @param options [Hash]
-    def end_impersonation(options = {})
-      options = Castle::Utils::DeepSymbolizeKeys.call(options || {})
-
-      add_timestamp_if_necessary(options)
-
-      new_context = Castle::Context::Merge.call(@context, options[:context])
-
-      Castle::API::EndImpersonation.call(options.merge(context: new_context, no_symbolize: true))
-    end
-
     def disable_tracking
       @do_not_track = true
     end
@@ -121,11 +77,18 @@ module Castle
 
     private
 
-    # @param user_id [String, Boolean]
+    # @param user_id [String, Boolean, nil]
     def generate_do_not_track_response(user_id)
       Castle::Failover::PrepareResponse.new(user_id, strategy: :allow, reason: 'Castle is set to do not track.').call
     end
 
+    # Safely pull the user identifier for a failover/do-not-track response.
+    # `user` is optional on /v1/filter (#279) and may be omitted entirely on
+    # /v1/log; fall back to `matching_user_id` then nil.
+    def failover_user_id(options)
+      options.dig(:user, :id) || options[:matching_user_id]
+    end
+
     # @param options [Hash]
     def add_timestamp_if_necessary(options)
       options[:timestamp] ||= @timestamp if @timestamp

data/lib/castle/client_actions/list_items.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Castle
+  # Namespace for client actions
+  module ClientActions
+    # Client actions for list items
+    module ListItems
+      # @param options [Hash]
+      def archive_list_item(options = {})
+        Castle::API::ListItems::Archive.call(options)
+      end
+
+      # @param options [Hash]
+      def count_list_items(options = {})
+        Castle::API::ListItems::Count.call(options)
+      end
+
+      # @param options [Hash]
+      def create_list_item(options = {})
+        Castle::API::ListItems::Create.call(options)
+      end
+
+      # @param options [Hash]
+      def create_batch_list_items(options = {})
+        Castle::API::ListItems::CreateBatch.call(options)
+      end
+
+      # @param options [Hash]
+      def get_list_item(options = {})
+        Castle::API::ListItems::Get.call(options)
+      end
+
+      # @param options [Hash]
+      def query_list_items(options = {})
+        Castle::API::ListItems::Query.call(options)
+      end
+
+      # @param options [Hash]
+      def unarchive_list_item(options = {})
+        Castle::API::ListItems::Unarchive.call(options)
+      end
+
+      # @param options [Hash]
+      def update_list_item(options = {})
+        Castle::API::ListItems::Update.call(options)
+      end
+    end
+  end
+end

data/lib/castle/client_actions/lists.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Castle
+  # Namespace for client actions
+  module ClientActions
+    # Client actions for lists
+    module Lists
+      # @param options [Hash]
+      def create_list(options = {})
+        Castle::API::Lists::Create.call(options)
+      end
+
+      # @param options [Hash]
+      def delete_list(options = {})
+        Castle::API::Lists::Delete.call(options)
+      end
+
+      # @param options [Hash]
+      def get_all_lists(options = {})
+        Castle::API::Lists::GetAll.call(options)
+      end
+
+      # @param options [Hash]
+      def get_list(options = {})
+        Castle::API::Lists::Get.call(options)
+      end
+
+      # @param options [Hash]
+      def query_lists(options = {})
+        Castle::API::Lists::Query.call(options)
+      end
+
+      # @param options [Hash]
+      def update_list(options = {})
+        Castle::API::Lists::Update.call(options)
+      end
+    end
+  end
+end

data/lib/castle/client_actions/privacy.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Castle
+  module ClientActions
+    # Client actions for the Privacy API (GDPR Articles 15 & 17).
+    module Privacy
+      # Triggers a "right of access" data export.
+      # @param options [Hash] must include :identifier and :identifier_type ($id or $email)
+      def request_user_data(options = {})
+        Castle::API::Privacy::RequestData.call(options)
+      end
+
+      # Triggers a "right to be forgotten" data purge.
+      # @param options [Hash] must include :identifier and :identifier_type ($id or $email)
+      def delete_user_data(options = {})
+        Castle::API::Privacy::DeleteData.call(options)
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/archive.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    # Commands for list items endpoints
+    module ListItems
+      # Generates the payload for the DELETE /lists/:list_id/items/:item_id/archive request
+      class Archive
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id list_item_id])
+
+            list_id = options.delete(:list_id)
+            list_item_id = options.delete(:list_item_id)
+
+            Castle::Command.new("lists/#{list_id}/items/#{list_item_id}/archive", nil, :delete)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/count.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Generates the payload for the POST /lists/:list_id/items/count request
+      class Count
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id])
+            options[:filters]&.each { |f| Castle::Validators::Present.call(f, %i[field op value]) }
+
+            list_id = options.delete(:list_id)
+
+            Castle::Command.new("lists/#{list_id}/items/count", options, :post)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/create.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to create a list item
+      class Create
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id author primary_value])
+
+            list_id = options.delete(:list_id)
+
+            Castle::Command.new("lists/#{list_id}/items", options, :post)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/create_batch.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to create or update multiple list items in a single call
+      class CreateBatch
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id items])
+
+            list_id = options.delete(:list_id)
+
+            Castle::Command.new("lists/#{list_id}/items/batch", options, :post)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/get.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to get a list item
+      class Get
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id list_item_id])
+
+            list_id = options.delete(:list_id)
+            list_item_id = options.delete(:list_item_id)
+
+            Castle::Command.new("lists/#{list_id}/items/#{list_item_id}", nil, :get)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/query.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to query list items
+      class Query
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id])
+            options[:filters]&.each { |f| Castle::Validators::Present.call(f, %i[field op value]) }
+            Castle::Validators::Present.call(options[:sort], %i[field order]) if options[:sort]
+
+            list_id = options.delete(:list_id)
+
+            Castle::Command.new("lists/#{list_id}/items/query", options, :post)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/unarchive.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to unarchive a list item
+      class Unarchive
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id list_item_id])
+
+            list_id = options.delete(:list_id)
+            list_item_id = options.delete(:list_item_id)
+
+            Castle::Command.new("lists/#{list_id}/items/#{list_item_id}/unarchive", nil, :put)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/list_items/update.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module ListItems
+      # Builds the command to update a list item
+      class Update
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id list_item_id comment])
+            list_id = options.delete(:list_id)
+            list_item_id = options.delete(:list_item_id)
+
+            Castle::Command.new("lists/#{list_id}/items/#{list_item_id}", options, :put)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/lists/create.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    # Commands for lists endpoints
+    module Lists
+      # Builds the command to create a list
+      class Create
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[name color primary_field])
+
+            Castle::Command.new('lists', options, :post)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/castle/commands/lists/delete.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Castle
+  module Commands
+    module Lists
+      # Builds the command to delete a list
+      class Delete
+        class << self
+          # @param options [Hash]
+          # @return [Castle::Command]
+          def build(options = {})
+            Castle::Validators::Present.call(options, %i[list_id])
+
+            Castle::Command.new("lists/#{options[:list_id]}", nil, :delete)
+          end
+        end
+      end
+    end
+  end
+end