attio 0.2.0 → 0.4.0

data/lib/attio/resources/base.rb

@@ -54,6 +54,16 @@ module Attio
         raise ArgumentError, "#{field_name} is required"
       end
 
+      # Validates that a hash parameter is present
+      # @param value [Hash] The hash to validate
+      # @param field_name [String] The field name for the error message
+      # @raise [ArgumentError] if value is nil or not a hash
+      private def validate_required_hash!(value, field_name)
+        return if value.is_a?(Hash) && !value.nil?
+
+        raise ArgumentError, "#{field_name} must be a hash"
+      end
+
       # Validates parent object and record ID together
       # @param parent_object [String] The parent object type
       # @param parent_record_id [String] The parent record ID
@@ -63,14 +73,15 @@ module Attio
         validate_required_string!(parent_record_id, "Parent record ID")
       end
 
-      private def request(method, path, params = {})
+      private def request(method, path, params = {}, _headers = {})
+        # Path is already safely constructed by the resource methods
         connection = client.connection
 
         case method
         when :get
           handle_get_request(connection, path, params)
         when :post
-          connection.post(path, params)
+          handle_post_request(connection, path, params)
         when :patch
           connection.patch(path, params)
         when :put
@@ -86,9 +97,66 @@ module Attio
         params.empty? ? connection.get(path) : connection.get(path, params)
       end
 
+      private def handle_post_request(connection, path, params)
+        params.empty? ? connection.post(path) : connection.post(path, params)
+      end
+
       private def handle_delete_request(connection, path, params)
         params.empty? ? connection.delete(path) : connection.delete(path, params)
       end
+
+      # Paginate through all results for a given endpoint
+      # @param path [String] The API endpoint path
+      # @param params [Hash] Query parameters including filters
+      # @param page_size [Integer] Number of items per page (default: 50)
+      # @return [Enumerator] Yields each item from all pages
+      private def paginate(path, params = {}, page_size: 50)
+        Enumerator.new do |yielder|
+          offset = 0
+          loop do
+            page_params = params.merge(limit: page_size, offset: offset)
+            # Use POST for query endpoints, GET for others
+            method = path.end_with?("/query") ? :post : :get
+            response = request(method, path, page_params)
+
+            data = response["data"] || []
+            data.each { |item| yielder << item }
+
+            # Stop if we got fewer items than requested (last page)
+            break if data.size < page_size
+
+            offset += page_size
+          end
+        end
+      end
+
+      # Build query parameters with filtering and sorting support
+      # @param options [Hash] Options including filter, sort, limit, offset
+      # @return [Hash] Formatted query parameters
+      private def build_query_params(options = {})
+        params = {}
+
+        # Add filtering
+        add_filter_param(params, options[:filter]) if options[:filter]
+
+        # Add standard parameters
+        %i[sort limit offset].each do |key|
+          params[key] = options[key] if options[key]
+        end
+
+        # Add any other parameters
+        options.each do |key, value|
+          next if %i[filter sort limit offset].include?(key)
+
+          params[key] = value
+        end
+
+        params
+      end
+
+      private def add_filter_param(params, filter)
+        params[:filter] = filter.is_a?(String) ? filter : filter.to_json
+      end
     end
   end
 end

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 1000)" 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/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/records.rb

@@ -44,9 +44,36 @@ module Attio
       #     filters: { name: { contains: 'John' } },
       #     limit: 50
       #   )
-      def list(object:, **params)
+      def list(object:, filter: nil, sort: nil, limit: nil, offset: nil, **params)
         validate_required_string!(object, "Object type")
-        request(:post, "objects/#{object}/records/query", params)
+
+        # Build query parameters with filtering and sorting support
+        query_params = build_query_params({
+          filter: filter,
+          sort: sort,
+          limit: limit,
+          offset: offset,
+          **params,
+        })
+
+        request(:post, "objects/#{object}/records/query", query_params)
+      end
+
+      # List all records with automatic pagination
+      # @param object [String] The object type to query
+      # @param filter [Hash] Filtering criteria
+      # @param sort [String] Sorting option
+      # @param page_size [Integer] Number of records per page
+      # @return [Enumerator] Enumerator that yields each record
+      def list_all(object:, filter: nil, sort: nil, page_size: 50)
+        validate_required_string!(object, "Object type")
+
+        query_params = build_query_params({
+          filter: filter,
+          sort: sort,
+        })
+
+        paginate("objects/#{object}/records/query", query_params, page_size: page_size)
       end
 
       # Retrieve a specific record by ID.