attio 0.1.3 → 0.3.0

data/lib/attio/resources/bulk.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # Bulk operations for efficient batch processing
+    #
+    # @example Bulk create records
+    #   client.bulk.create_records(
+    #     object: "companies",
+    #     records: [
+    #       { name: "Acme Corp", domain: "acme.com" },
+    #       { name: "Tech Co", domain: "techco.com" }
+    #     ]
+    #   )
+    #
+    # @example Bulk update records
+    #   client.bulk.update_records(
+    #     object: "people",
+    #     updates: [
+    #       { id: "person_123", data: { title: "CEO" } },
+    #       { id: "person_456", data: { title: "CTO" } }
+    #     ]
+    #   )
+    class Bulk < Base
+      # Maximum number of records per bulk operation
+      MAX_BATCH_SIZE = 100
+
+      # Bulk create multiple records
+      #
+      # @param object [String] The object type (companies, people, etc.)
+      # @param records [Array<Hash>] Array of record data to create
+      # @param options [Hash] Additional options
+      # @option options [Boolean] :partial_success Allow partial success (default: false)
+      # @option options [Boolean] :return_records Return created records (default: true)
+      # @return [Hash] Results including created records and any errors
+      def create_records(object:, records:, options: {})
+        validate_required_string!(object, "Object type")
+        validate_bulk_records!(records, "create")
+
+        batches = records.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            records: batch.map { |record| { data: record } },
+            partial_success: options.fetch(:partial_success, false),
+            return_records: options.fetch(:return_records, true),
+          }
+
+          result = request(:post, "objects/#{object}/records/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      # Bulk update multiple records
+      #
+      # @param object [String] The object type
+      # @param updates [Array<Hash>] Array of updates with :id and :data keys
+      # @param options [Hash] Additional options
+      # @option options [Boolean] :partial_success Allow partial success (default: false)
+      # @option options [Boolean] :return_records Return updated records (default: true)
+      # @return [Hash] Results including updated records and any errors
+      def update_records(object:, updates:, options: {})
+        validate_required_string!(object, "Object type")
+        validate_bulk_updates!(updates)
+
+        batches = updates.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            updates: batch,
+            partial_success: options.fetch(:partial_success, false),
+            return_records: options.fetch(:return_records, true),
+          }
+
+          result = request(:patch, "objects/#{object}/records/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      # Bulk delete multiple records
+      #
+      # @param object [String] The object type
+      # @param ids [Array<String>] Array of record IDs to delete
+      # @param options [Hash] Additional options
+      # @option options [Boolean] :partial_success Allow partial success (default: false)
+      # @return [Hash] Results including deletion confirmations and any errors
+      def delete_records(object:, ids:, options: {})
+        validate_required_string!(object, "Object type")
+        validate_bulk_ids!(ids)
+
+        batches = ids.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            ids: batch,
+            partial_success: options.fetch(:partial_success, false),
+          }
+
+          result = request(:delete, "objects/#{object}/records/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      # Bulk upsert records (create or update based on matching criteria)
+      #
+      # @param object [String] The object type
+      # @param records [Array<Hash>] Records to upsert
+      # @param match_attribute [String] Attribute to match on (e.g., "email", "domain")
+      # @param options [Hash] Additional options
+      # @return [Hash] Results including created/updated records
+      def upsert_records(object:, records:, match_attribute:, options: {})
+        validate_required_string!(object, "Object type")
+        validate_required_string!(match_attribute, "Match attribute")
+        validate_bulk_records!(records, "upsert")
+
+        batches = records.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            records: batch.map { |record| { data: record } },
+            match_attribute: match_attribute,
+            partial_success: options.fetch(:partial_success, false),
+            return_records: options.fetch(:return_records, true),
+          }
+
+          result = request(:put, "objects/#{object}/records/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      # Bulk add entries to a list
+      #
+      # @param list_id [String] The list ID
+      # @param entries [Array<Hash>] Array of entries to add
+      # @param options [Hash] Additional options
+      # @return [Hash] Results including added entries
+      def add_list_entries(list_id:, entries:, options: {})
+        validate_id!(list_id, "List")
+        validate_bulk_records!(entries, "add to list")
+
+        batches = entries.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            entries: batch,
+            partial_success: options.fetch(:partial_success, false),
+          }
+
+          result = request(:post, "lists/#{list_id}/entries/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      # Bulk remove entries from a list
+      #
+      # @param list_id [String] The list ID
+      # @param entry_ids [Array<String>] Array of entry IDs to remove
+      # @param options [Hash] Additional options
+      # @return [Hash] Results including removal confirmations
+      def remove_list_entries(list_id:, entry_ids:, options: {})
+        validate_id!(list_id, "List")
+        validate_bulk_ids!(entry_ids)
+
+        batches = entry_ids.each_slice(MAX_BATCH_SIZE).to_a
+        results = []
+
+        batches.each_with_index do |batch, index|
+          body = {
+            entry_ids: batch,
+            partial_success: options.fetch(:partial_success, false),
+          }
+
+          result = request(:delete, "lists/#{list_id}/entries/bulk", body)
+          results << result.merge("batch" => index + 1)
+        end
+
+        merge_batch_results(results)
+      end
+
+      private def validate_bulk_records!(records, operation)
+        raise ArgumentError, "Records array is required for bulk #{operation}" if records.nil?
+        raise ArgumentError, "Records must be an array for bulk #{operation}" unless records.is_a?(Array)
+        raise ArgumentError, "Records array cannot be empty for bulk #{operation}" if records.empty?
+        raise ArgumentError, "Too many records (max #{MAX_BATCH_SIZE * 10})" if records.size > MAX_BATCH_SIZE * 10
+
+        records.each_with_index do |record, index|
+          raise ArgumentError, "Record at index #{index} must be a hash" unless record.is_a?(Hash)
+        end
+      end
+
+      private def validate_bulk_updates!(updates)
+        validate_array!(updates, "Updates", "bulk update")
+        validate_max_size!(updates, "updates")
+
+        updates.each_with_index do |update, index|
+          validate_update_item!(update, index)
+        end
+      end
+
+      private def validate_update_item!(update, index)
+        raise ArgumentError, "Update at index #{index} must be a hash" unless update.is_a?(Hash)
+        raise ArgumentError, "Update at index #{index} must have an :id" unless update[:id]
+        raise ArgumentError, "Update at index #{index} must have :data" unless update[:data]
+      end
+
+      private def validate_bulk_ids!(ids)
+        validate_array!(ids, "IDs", "bulk operation")
+        validate_max_size!(ids, "IDs")
+
+        ids.each_with_index do |id, index|
+          validate_id_item!(id, index)
+        end
+      end
+
+      private def validate_id_item!(id, index)
+        return unless id.nil? || id.to_s.strip.empty?
+
+        raise ArgumentError, "ID at index #{index} cannot be nil or empty"
+      end
+
+      private def validate_array!(array, name, operation)
+        raise ArgumentError, "#{name} array is required for #{operation}" if array.nil?
+        raise ArgumentError, "#{name} must be an array for #{operation}" unless array.is_a?(Array)
+        raise ArgumentError, "#{name} array cannot be empty for #{operation}" if array.empty?
+      end
+
+      private def validate_max_size!(array, name)
+        max = MAX_BATCH_SIZE * 10
+        return unless array.size > max
+
+        raise ArgumentError, "Too many #{name} (max #{max})"
+      end
+
+      private def merge_batch_results(results)
+        merged = initialize_merged_result(results.size)
+
+        results.each do |result|
+          merge_single_result!(merged, result)
+        end
+
+        merged
+      end
+
+      private def initialize_merged_result(batch_count)
+        {
+          "success" => true,
+          "total_batches" => batch_count,
+          "records" => [],
+          "errors" => [],
+          "statistics" => {
+            "created" => 0,
+            "updated" => 0,
+            "deleted" => 0,
+            "failed" => 0,
+          },
+        }
+      end
+
+      private def merge_single_result!(merged, result)
+        merged["records"].concat(result["records"] || [])
+        merged["errors"].concat(result["errors"] || [])
+        merge_statistics!(merged["statistics"], result["statistics"])
+        merged["success"] &&= result["success"] != false
+      end
+
+      private def merge_statistics!(target, source)
+        return unless source
+
+        %w[created updated deleted failed].each do |key|
+          target[key] += source[key] || 0
+        end
+      end
+    end
+  end
+end

data/lib/attio/resources/comments.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # API resource for managing comments in Attio
+    #
+    # Comments can be added to records and threads for collaboration.
+    #
+    # @example Creating a comment on a record
+    #   client.comments.create(
+    #     parent_object: "people",
+    #     parent_record_id: "person_123",
+    #     content: "Just had a great call with this lead!"
+    #   )
+    #
+    # @example Creating a comment in a thread
+    #   client.comments.create(
+    #     thread_id: "thread_456",
+    #     content: "Following up on our discussion..."
+    #   )
+    class Comments < Base
+      # List comments for a parent record or thread
+      #
+      # @param params [Hash] Query parameters
+      # @option params [String] :parent_object Parent object type
+      # @option params [String] :parent_record_id Parent record ID
+      # @option params [String] :thread_id Thread ID
+      # @option params [Integer] :limit Number of comments to return
+      # @option params [String] :cursor Pagination cursor
+      #
+      # @return [Hash] API response containing comments
+      def list(**params)
+        validate_list_params!(params)
+        request(:get, "comments", params)
+      end
+
+      # Get a specific comment by ID
+      #
+      # @param id [String] The comment ID
+      #
+      # @return [Hash] The comment data
+      # @raise [ArgumentError] if id is nil or empty
+      def get(id:)
+        validate_id!(id, "Comment")
+        request(:get, "comments/#{id}")
+      end
+
+      # Create a new comment
+      #
+      # @param content [String] The comment content (supports markdown)
+      # @param parent_object [String] Parent object type (required if no thread_id)
+      # @param parent_record_id [String] Parent record ID (required if no thread_id)
+      # @param thread_id [String] Thread ID (required if no parent_object/parent_record_id)
+      # @param data [Hash] Additional comment data
+      #
+      # @return [Hash] The created comment
+      # @raise [ArgumentError] if required parameters are missing
+      def create(content:, parent_object: nil, parent_record_id: nil, thread_id: nil, **data)
+        validate_required_string!(content, "Comment content")
+        validate_create_params!(parent_object, parent_record_id, thread_id)
+
+        params = data.merge(content: content)
+
+        if thread_id
+          params[:thread_id] = thread_id
+        else
+          params[:parent_object] = parent_object
+          params[:parent_record_id] = parent_record_id
+        end
+
+        request(:post, "comments", params)
+      end
+
+      # Update an existing comment
+      #
+      # @param id [String] The comment ID
+      # @param content [String] The new content
+      #
+      # @return [Hash] The updated comment
+      # @raise [ArgumentError] if id or content is invalid
+      def update(id:, content:)
+        validate_id!(id, "Comment")
+        validate_required_string!(content, "Comment content")
+        request(:patch, "comments/#{id}", { content: content })
+      end
+
+      # Delete a comment
+      #
+      # @param id [String] The comment ID to delete
+      #
+      # @return [Hash] Deletion confirmation
+      # @raise [ArgumentError] if id is nil or empty
+      def delete(id:)
+        validate_id!(id, "Comment")
+        request(:delete, "comments/#{id}")
+      end
+
+      # React to a comment with an emoji
+      #
+      # @param id [String] The comment ID
+      # @param emoji [String] The emoji reaction (e.g., "👍", "❤️")
+      #
+      # @return [Hash] The updated comment with reaction
+      # @raise [ArgumentError] if id or emoji is invalid
+      def react(id:, emoji:)
+        validate_id!(id, "Comment")
+        validate_required_string!(emoji, "Emoji")
+        request(:post, "comments/#{id}/reactions", { emoji: emoji })
+      end
+
+      # Remove a reaction from a comment
+      #
+      # @param id [String] The comment ID
+      # @param emoji [String] The emoji reaction to remove
+      #
+      # @return [Hash] The updated comment
+      # @raise [ArgumentError] if id or emoji is invalid
+      def unreact(id:, emoji:)
+        validate_id!(id, "Comment")
+        validate_required_string!(emoji, "Emoji")
+        request(:delete, "comments/#{id}/reactions/#{CGI.escape(emoji)}")
+      end
+
+      private def validate_list_params!(params)
+        has_parent = params[:parent_object] && params[:parent_record_id]
+        has_thread = params[:thread_id]
+
+        return if has_parent || has_thread
+
+        raise ArgumentError, "Must provide either parent_object/parent_record_id or thread_id"
+      end
+
+      private def validate_create_params!(parent_object, parent_record_id, thread_id)
+        has_parent = parent_object && parent_record_id
+        has_thread = thread_id
+
+        unless has_parent || has_thread
+          raise ArgumentError, "Must provide either parent_object/parent_record_id or thread_id"
+        end
+
+        return unless has_parent && has_thread
+
+        raise ArgumentError, "Cannot provide both parent and thread parameters"
+      end
+    end
+  end
+end

data/lib/attio/resources/deals.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # Deals resource for managing sales opportunities
+    #
+    # @example List all deals
+    #   client.deals.list
+    #
+    # @example Create a new deal
+    #   client.deals.create(
+    #     data: {
+    #       name: "Enterprise Contract",
+    #       value: 50000,
+    #       stage_id: "stage_123",
+    #       company_id: "company_456"
+    #     }
+    #   )
+    #
+    # @example Update deal stage
+    #   client.deals.update_stage(id: "deal_123", stage_id: "stage_won")
+    class Deals < Base
+      # List all deals
+      #
+      # @param params [Hash] Optional query parameters
+      # @option params [Hash] :filter Filter conditions
+      # @option params [Array<Hash>] :sorts Sort criteria
+      # @option params [Integer] :limit Maximum number of results
+      # @option params [String] :offset Pagination offset
+      # @return [Hash] The API response
+      def list(params = {})
+        request(:get, "objects/deals/records", params)
+      end
+
+      # Get a specific deal
+      #
+      # @param id [String] The deal ID
+      # @return [Hash] The deal data
+      def get(id:)
+        validate_id!(id, "Deal")
+        request(:get, "objects/deals/records/#{id}")
+      end
+
+      # Create a new deal
+      #
+      # @param data [Hash] The deal data
+      # @option data [String] :name The deal name (required)
+      # @option data [Float] :value The deal value
+      # @option data [String] :stage_id The stage ID
+      # @option data [String] :company_id Associated company ID
+      # @option data [String] :owner_id The owner user ID
+      # @option data [Date] :close_date Expected close date
+      # @option data [String] :currency Currency code (USD, EUR, etc.)
+      # @option data [Float] :probability Win probability (0-100)
+      # @return [Hash] The created deal
+      def create(data:)
+        validate_required_hash!(data, "Data")
+        validate_required_string!(data[:name], "Deal name")
+
+        request(:post, "objects/deals/records", { data: data })
+      end
+
+      # Update a deal
+      #
+      # @param id [String] The deal ID to update
+      # @param data [Hash] The data to update
+      # @return [Hash] The updated deal
+      def update(id:, data:)
+        validate_id!(id, "Deal")
+        validate_required_hash!(data, "Data")
+
+        request(:patch, "objects/deals/records/#{id}", { data: data })
+      end
+
+      # Delete a deal
+      #
+      # @param id [String] The deal ID to delete
+      # @return [Hash] Confirmation of deletion
+      def delete(id:)
+        validate_id!(id, "Deal")
+        request(:delete, "objects/deals/records/#{id}")
+      end
+
+      # Update a deal's stage
+      #
+      # @param id [String] The deal ID
+      # @param stage_id [String] The new stage ID
+      # @return [Hash] The updated deal
+      def update_stage(id:, stage_id:)
+        validate_id!(id, "Deal")
+        validate_required_string!(stage_id, "Stage")
+
+        update(id: id, data: { stage_id: stage_id })
+      end
+
+      # Mark a deal as won
+      #
+      # @param id [String] The deal ID
+      # @param won_date [Date, String] The date the deal was won (defaults to today)
+      # @param actual_value [Float] The actual value (optional, defaults to deal value)
+      # @return [Hash] The updated deal
+      def mark_won(id:, won_date: nil, actual_value: nil)
+        validate_id!(id, "Deal")
+
+        data = { status: "won" }
+        data[:won_date] = won_date if won_date
+        data[:actual_value] = actual_value if actual_value
+
+        update(id: id, data: data)
+      end
+
+      # Mark a deal as lost
+      #
+      # @param id [String] The deal ID
+      # @param lost_reason [String] The reason for losing the deal
+      # @param lost_date [Date, String] The date the deal was lost (defaults to today)
+      # @return [Hash] The updated deal
+      def mark_lost(id:, lost_reason: nil, lost_date: nil)
+        validate_id!(id, "Deal")
+
+        data = { status: "lost" }
+        data[:lost_reason] = lost_reason if lost_reason
+        data[:lost_date] = lost_date if lost_date
+
+        update(id: id, data: data)
+      end
+
+      # List deals by stage
+      #
+      # @param stage_id [String] The stage ID to filter by
+      # @param params [Hash] Additional query parameters
+      # @return [Hash] Deals in the specified stage
+      def list_by_stage(stage_id:, params: {})
+        validate_required_string!(stage_id, "Stage")
+
+        filter = { stage_id: { "$eq" => stage_id } }
+        merged_params = params.merge(filter: filter)
+        list(merged_params)
+      end
+
+      # List deals by company
+      #
+      # @param company_id [String] The company ID to filter by
+      # @param params [Hash] Additional query parameters
+      # @return [Hash] Deals for the specified company
+      def list_by_company(company_id:, params: {})
+        validate_required_string!(company_id, "Company")
+
+        filter = { company_id: { "$eq" => company_id } }
+        merged_params = params.merge(filter: filter)
+        list(merged_params)
+      end
+
+      # List deals by owner
+      #
+      # @param owner_id [String] The owner user ID to filter by
+      # @param params [Hash] Additional query parameters
+      # @return [Hash] Deals owned by the specified user
+      def list_by_owner(owner_id:, params: {})
+        validate_required_string!(owner_id, "Owner")
+
+        filter = { owner_id: { "$eq" => owner_id } }
+        merged_params = params.merge(filter: filter)
+        list(merged_params)
+      end
+
+      # Calculate pipeline value
+      #
+      # @param stage_id [String] Optional stage ID to filter by
+      # @param owner_id [String] Optional owner ID to filter by
+      # @return [Hash] Pipeline statistics including total value, count, and average
+      def pipeline_value(stage_id: nil, owner_id: nil)
+        params = { filter: {} }
+        params[:filter][:stage_id] = { "$eq" => stage_id } if stage_id
+        params[:filter][:owner_id] = { "$eq" => owner_id } if owner_id
+
+        # This would typically be a specialized endpoint, but we'll use list
+        # and let the client calculate the statistics
+        list(params)
+      end
+    end
+  end
+end

data/lib/attio/resources/lists.rb

@@ -17,46 +17,34 @@ module Attio
       end
 
       def get(id:)
-        validate_id!(id)
+        validate_id!(id, "List")
         request(:get, "lists/#{id}")
       end
 
       def entries(id:, **params)
-        validate_id!(id)
+        validate_id!(id, "List")
         request(:get, "lists/#{id}/entries", params)
       end
 
       def create_entry(id:, data:)
-        validate_id!(id)
-        validate_data!(data)
+        validate_id!(id, "List")
+        validate_list_entry_data!(data)
         request(:post, "lists/#{id}/entries", data)
       end
 
       def get_entry(list_id:, entry_id:)
-        validate_list_id!(list_id)
-        validate_entry_id!(entry_id)
+        validate_id!(list_id, "List")
+        validate_id!(entry_id, "Entry")
         request(:get, "lists/#{list_id}/entries/#{entry_id}")
       end
 
       def delete_entry(list_id:, entry_id:)
-        validate_list_id!(list_id)
-        validate_entry_id!(entry_id)
+        validate_id!(list_id, "List")
+        validate_id!(entry_id, "Entry")
         request(:delete, "lists/#{list_id}/entries/#{entry_id}")
       end
 
-      private def validate_id!(id)
-        raise ArgumentError, "List ID is required" if id.nil? || id.to_s.strip.empty?
-      end
-
-      private def validate_list_id!(list_id)
-        raise ArgumentError, "List ID is required" if list_id.nil? || list_id.to_s.strip.empty?
-      end
-
-      private def validate_entry_id!(entry_id)
-        raise ArgumentError, "Entry ID is required" if entry_id.nil? || entry_id.to_s.strip.empty?
-      end
-
-      private def validate_data!(data)
+      private def validate_list_entry_data!(data)
         raise ArgumentError, "Data is required" if data.nil?
         raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
       end