attio 0.2.0 → 0.3.0

data/lib/attio/client.rb

@@ -152,5 +152,55 @@ module Attio
     def threads
       @threads ||= Resources::Threads.new(self)
     end
+
+    # Access to the Workspace Members API resource.
+    #
+    # @return [Resources::WorkspaceMembers] Workspace Members resource instance
+    # @example
+    #   members = client.workspace_members.list
+    def workspace_members
+      @workspace_members ||= Resources::WorkspaceMembers.new(self)
+    end
+
+    # Access to the Deals API resource.
+    #
+    # @return [Resources::Deals] Deals resource instance
+    # @example
+    #   deals = client.deals.list
+    def deals
+      @deals ||= Resources::Deals.new(self)
+    end
+
+    # Access to the Meta API resource.
+    #
+    # @return [Resources::Meta] Meta resource instance
+    # @example
+    #   info = client.meta.identify
+    def meta
+      @meta ||= Resources::Meta.new(self)
+    end
+
+    # Access to the Bulk Operations API resource.
+    #
+    # @return [Resources::Bulk] Bulk operations resource instance
+    # @example
+    #   client.bulk.create_records(object: 'companies', records: [...])
+    def bulk
+      @bulk ||= Resources::Bulk.new(self)
+    end
+
+    # Get or set the rate limiter for this client.
+    #
+    # @param limiter [RateLimiter] Optional rate limiter to set
+    # @return [RateLimiter] The rate limiter instance
+    # @example
+    #   client.rate_limiter = Attio::RateLimiter.new(max_requests: 100)
+    def rate_limiter(limiter = nil)
+      if limiter
+        @rate_limiter = limiter
+      else
+        @rate_limiter ||= RateLimiter.new
+      end
+    end
   end
 end

data/lib/attio/errors.rb

@@ -1,11 +1,39 @@
 # frozen_string_literal: true
 
 module Attio
-  class Error < StandardError; end
+  # Base error class for all Attio errors
+  class Error < StandardError
+    attr_reader :response, :code
 
+    def initialize(message = nil, response: nil, code: nil)
+      @response = response
+      @code = code
+      super(message)
+    end
+  end
+
+  # Raised when authentication fails (401)
   class AuthenticationError < Error; end
+
+  # Raised when a resource is not found (404)
   class NotFoundError < Error; end
+
+  # Raised when validation fails (400/422)
   class ValidationError < Error; end
-  class RateLimitError < Error; end
+
+  # Raised when rate limit is exceeded (429)
+  class RateLimitError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **options)
+      @retry_after = retry_after
+      super(message, **options)
+    end
+  end
+
+  # Raised when server error occurs (5xx)
   class ServerError < Error; end
+
+  # Raised for generic API errors
+  class APIError < Error; end
 end

data/lib/attio/http_client.rb

@@ -57,6 +57,10 @@ module Attio
         headers: headers.merge("Content-Type" => "application/json"),
         timeout: timeout,
         connecttimeout: timeout,
+        # SSL/TLS security settings
+        ssl_verifypeer: true,
+        ssl_verifyhost: 2,
+        followlocation: false, # Prevent following redirects for security
       }.merge(options)
 
       request = Typhoeus::Request.new(url, request_options)

data/lib/attio/rate_limiter.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Attio
+  # Rate limiter with intelligent retry and backoff strategies
+  #
+  # @example Using the rate limiter
+  #   limiter = Attio::RateLimiter.new(
+  #     max_requests: 100,
+  #     window_seconds: 60,
+  #     max_retries: 3
+  #   )
+  #
+  #   limiter.execute { client.records.list }
+  class RateLimiter
+    attr_reader :max_requests, :window_seconds, :max_retries
+    attr_accessor :current_limit, :remaining, :reset_at
+
+    # Initialize a new rate limiter
+    #
+    # @param max_requests [Integer] Maximum requests per window
+    # @param window_seconds [Integer] Time window in seconds
+    # @param max_retries [Integer] Maximum retry attempts
+    # @param enable_jitter [Boolean] Add jitter to backoff delays
+    def initialize(max_requests: 1000, window_seconds: 3600, max_retries: 3, enable_jitter: true)
+      @max_requests = max_requests
+      @window_seconds = window_seconds
+      @max_retries = max_retries
+      @enable_jitter = enable_jitter
+
+      @current_limit = max_requests
+      @remaining = max_requests
+      @reset_at = Time.now + window_seconds
+
+      @mutex = Mutex.new
+      @request_queue = []
+      @request_times = []
+    end
+
+    # Execute a block with rate limiting
+    #
+    # @yield The block to execute
+    # @return The result of the block
+    def execute
+      raise ArgumentError, "Block required" unless block_given?
+
+      @mutex.synchronize do
+        wait_if_needed
+        track_request
+      end
+
+      attempt = 0
+      begin
+        result = yield
+        # Thread-safe header update
+        @mutex.synchronize do
+          update_from_headers(result) if result.is_a?(Hash) && result["_headers"]
+        end
+        result
+      rescue Attio::RateLimitError => e
+        attempt += 1
+        raise e unless attempt <= @max_retries
+
+        wait_time = calculate_backoff(attempt, e)
+        sleep(wait_time)
+        retry
+      end
+    end
+
+    # Check if rate limit is exceeded
+    #
+    # @return [Boolean] True if rate limit would be exceeded
+    def rate_limited?
+      @mutex.synchronize do
+        cleanup_old_requests
+        @request_times.size >= @max_requests
+      end
+    end
+
+    # Get current rate limit status
+    #
+    # @return [Hash] Current status
+    def status
+      @mutex.synchronize do
+        cleanup_old_requests
+        {
+          limit: @current_limit,
+          remaining: [@remaining, @max_requests - @request_times.size].min,
+          reset_at: @reset_at,
+          reset_in: [@reset_at - Time.now, 0].max.to_i,
+          current_usage: @request_times.size,
+        }
+      end
+    end
+
+    # Update rate limit info from response headers
+    # NOTE: This method should be called within a mutex lock
+    #
+    # @param response [Hash] Response containing headers
+    private def update_from_headers(response)
+      return unless response.is_a?(Hash)
+
+      headers = response["_headers"] || {}
+
+      @current_limit = headers["x-ratelimit-limit"].to_i if headers["x-ratelimit-limit"]
+      @remaining = headers["x-ratelimit-remaining"].to_i if headers["x-ratelimit-remaining"]
+      @reset_at = Time.at(headers["x-ratelimit-reset"].to_i) if headers["x-ratelimit-reset"]
+    end
+
+    # Reset the rate limiter
+    def reset!
+      @mutex.synchronize do
+        @request_times.clear
+        @remaining = @max_requests
+        @reset_at = Time.now + @window_seconds
+      end
+    end
+
+    # Queue a request for later execution
+    #
+    # @param priority [Integer] Priority (lower = higher priority)
+    # @yield Block to execute
+    def queue_request(priority: 5, &block)
+      @mutex.synchronize do
+        @request_queue << { priority: priority, block: block, queued_at: Time.now }
+        @request_queue.sort_by! { |r| [r[:priority], r[:queued_at]] }
+      end
+    end
+
+    # Process queued requests
+    #
+    # @param max_per_batch [Integer] Maximum requests to process
+    # @return [Array] Results from processed requests
+    def process_queue(max_per_batch: 10)
+      results = []
+      processed = 0
+
+      while processed < max_per_batch
+        request = @mutex.synchronize { @request_queue.shift }
+        break unless request
+
+        begin
+          result = execute(&request[:block])
+          results << { success: true, result: result }
+        rescue StandardError => e
+          results << { success: false, error: e }
+        end
+
+        processed += 1
+      end
+
+      results
+    end
+
+    private def wait_if_needed
+      cleanup_old_requests
+
+      if @request_times.size >= @max_requests
+        wait_time = @request_times.first + @window_seconds - Time.now
+        if wait_time > 0
+          sleep(wait_time)
+          cleanup_old_requests
+        end
+      end
+
+      return unless @remaining <= 0 && @reset_at > Time.now
+
+      wait_time = @reset_at - Time.now
+      sleep(wait_time) if wait_time > 0
+    end
+
+    private def track_request
+      @request_times << Time.now
+      @remaining = [@remaining - 1, 0].max
+    end
+
+    private def cleanup_old_requests
+      cutoff = Time.now - @window_seconds
+      @request_times.reject! { |time| time < cutoff }
+    end
+
+    private def calculate_backoff(attempt, error = nil)
+      base_wait = 2**attempt
+
+      # Use server-provided retry-after if available
+      base_wait = error.retry_after if error && error.respond_to?(:retry_after) && error.retry_after
+
+      # Add jitter to prevent thundering herd
+      if @enable_jitter
+        jitter = rand * base_wait * 0.1
+        base_wait + jitter
+      else
+        base_wait
+      end
+    end
+  end
+
+  # Middleware for automatic rate limiting
+  class RateLimitMiddleware
+    def initialize(app, rate_limiter)
+      @app = app
+      @rate_limiter = rate_limiter
+    end
+
+    def call(env)
+      @rate_limiter.execute do
+        response = @app.call(env)
+        # Headers are automatically updated within execute block
+        response
+      end
+    end
+  end
+end

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,6 +97,10 @@ 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

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