attio 0.1.3 → 0.3.0

data/examples/notes_and_tasks.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "attio"
+require "date"
+
+# Example demonstrating Notes and Tasks functionality
+#
+# This example shows how to:
+# - Create and manage notes on records
+# - Create and manage tasks
+# - Work with task assignments and due dates
+# - Track task completion
+
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "📓 Attio Notes and Tasks Example"
+puts "=" * 50
+
+begin
+  # First, find or create a person to work with
+  puts "\n👤 Setting up test person..."
+  test_person = client.records.create(
+    object: "people",
+    data: {
+      name: "Jane Smith",
+      email: "jane.smith@example.com",
+      title: "Product Manager",
+    }
+  )
+  person_id = test_person["data"]["id"]
+  puts "  Created test person: Jane Smith (#{person_id})"
+
+  # Working with Notes
+  puts "\n📝 Creating Notes:"
+
+  # Create a meeting note
+  meeting_note = client.notes.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Initial Meeting - Product Requirements",
+    content: <<~MARKDOWN
+      ## Meeting Summary
+      **Date:** #{Date.today}
+      **Attendees:** Jane Smith, Development Team
+
+      ### Discussion Points:
+      1. **Q1 Product Roadmap**
+         - Feature A: User authentication improvements
+         - Feature B: New dashboard design
+         - Feature C: API v2 development
+
+      2. **Timeline**
+         - Sprint 1: Jan 15-29
+         - Sprint 2: Jan 30-Feb 12
+         - Release: Feb 15
+
+      3. **Action Items**
+         - [ ] Create detailed specs for Feature A
+         - [ ] Schedule design review for Feature B
+         - [ ] Allocate resources for API development
+
+      ### Next Steps:
+      Follow-up meeting scheduled for next week.
+    MARKDOWN
+  )
+  puts "  ✅ Created meeting note: #{meeting_note['data']['title']}"
+
+  # Create a follow-up note
+  followup_note = client.notes.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Follow-up: Action Items",
+    content: "Confirmed timeline and resource allocation. Jane will provide detailed specs by EOW."
+  )
+  puts "  ✅ Created follow-up note"
+
+  # List all notes for the person
+  notes = client.notes.list(
+    parent_object: "people",
+    parent_record_id: person_id
+  )
+  puts "\n  📋 Notes for Jane Smith:"
+  notes["data"].each do |note|
+    puts "    - #{note['title']} (created: #{note['created_at']})"
+  end
+
+  # Working with Tasks
+  puts "\n✅ Creating Tasks:"
+
+  # Create tasks based on action items
+  task1 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Create detailed specs for Feature A",
+    description: "Write comprehensive specifications for the user authentication improvements",
+    due_date: (Date.today + 7).iso8601,
+    priority: 1,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task1['data']['title']}"
+
+  task2 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Schedule design review for Feature B",
+    description: "Coordinate with design team and schedule review meeting",
+    due_date: (Date.today + 3).iso8601,
+    priority: 2,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task2['data']['title']}"
+
+  task3 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Allocate resources for API development",
+    description: "Determine team members and timeline for API v2",
+    due_date: (Date.today + 10).iso8601,
+    priority: 3,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task3['data']['title']}"
+
+  # List pending tasks
+  puts "\n  📋 Pending Tasks:"
+  pending_tasks = client.tasks.list(
+    status: "pending",
+    parent_object: "people",
+    parent_record_id: person_id
+  )
+  pending_tasks["data"].each do |task|
+    puts "    - #{task['title']} (due: #{task['due_date']})"
+  end
+
+  # Complete a task
+  puts "\n  ✅ Completing task..."
+  completed_task = client.tasks.complete(
+    id: task2["data"]["id"],
+    completed_at: DateTime.now.iso8601
+  )
+  puts "    Task completed: #{completed_task['data']['title']}"
+
+  # Update a task
+  puts "\n  📝 Updating task..."
+  updated_task = client.tasks.update(
+    id: task1["data"]["id"],
+    description: "Updated: Include security requirements in the specifications",
+    priority: 1
+  )
+  puts "    Task updated: #{updated_task['data']['title']}"
+
+  # Get task details
+  puts "\n  🔍 Task Details:"
+  task_detail = client.tasks.get(id: task1["data"]["id"])
+  puts "    Title: #{task_detail['data']['title']}"
+  puts "    Description: #{task_detail['data']['description']}"
+  puts "    Due Date: #{task_detail['data']['due_date']}"
+  puts "    Status: #{task_detail['data']['status']}"
+
+  # Update a note
+  puts "\n  📝 Updating note..."
+  client.notes.update(
+    id: followup_note["data"]["id"],
+    content: "Updated: Specs delivered. Design review scheduled for Friday."
+  )
+  puts "    Note updated successfully"
+
+  # Cleanup
+  puts "\n🧹 Cleaning up..."
+
+  # Delete tasks
+  [task1, task2, task3].each do |task|
+    client.tasks.delete(id: task["data"]["id"])
+  end
+  puts "  ✅ Deleted tasks"
+
+  # Delete notes
+  [meeting_note, followup_note].each do |note|
+    client.notes.delete(id: note["data"]["id"])
+  end
+  puts "  ✅ Deleted notes"
+
+  # Delete test person
+  client.records.delete(object: "people", id: person_id)
+  puts "  ✅ Deleted test person"
+rescue Attio::Error => e
+  puts "❌ Error: #{e.message}"
+  # Cleanup on error
+  if defined?(person_id)
+    begin
+      client.records.delete(object: "people", id: person_id)
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+puts "\n✨ Example completed!"

data/lib/attio/client.rb

@@ -116,5 +116,91 @@ module Attio
     def users
       @users ||= Resources::Users.new(self)
     end
+
+    # Access to the Notes API resource.
+    #
+    # @return [Resources::Notes] Notes resource instance
+    # @example
+    #   notes = client.notes.list(parent_object: 'people', parent_record_id: 'rec_123')
+    def notes
+      @notes ||= Resources::Notes.new(self)
+    end
+
+    # Access to the Tasks API resource.
+    #
+    # @return [Resources::Tasks] Tasks resource instance
+    # @example
+    #   tasks = client.tasks.list(status: 'pending')
+    def tasks
+      @tasks ||= Resources::Tasks.new(self)
+    end
+
+    # Access to the Comments API resource.
+    #
+    # @return [Resources::Comments] Comments resource instance
+    # @example
+    #   comments = client.comments.list(thread_id: 'thread_123')
+    def comments
+      @comments ||= Resources::Comments.new(self)
+    end
+
+    # Access to the Threads API resource.
+    #
+    # @return [Resources::Threads] Threads resource instance
+    # @example
+    #   threads = client.threads.list(parent_object: 'companies', parent_record_id: 'rec_456')
+    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

@@ -21,8 +21,12 @@ module Attio
       @timeout = timeout
     end
 
-    def get(path, params = {})
-      execute_request(:get, path, params: params)
+    def get(path, params = nil)
+      if params && !params.empty?
+        execute_request(:get, path, params: params)
+      else
+        execute_request(:get, path)
+      end
     end
 
     def post(path, body = {})
@@ -37,8 +41,12 @@ module Attio
       execute_request(:put, path, body: body.to_json)
     end
 
-    def delete(path)
-      execute_request(:delete, path)
+    def delete(path, params = nil)
+      if params
+        execute_request(:delete, path, body: params.to_json)
+      else
+        execute_request(:delete, path)
+      end
     end
 
     private def execute_request(method, path, options = {})
@@ -49,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

@@ -24,22 +24,86 @@ module Attio
         @client = client
       end
 
-      private def request(method, path, params = {})
+      # Common validation methods that can be used by all resource classes
+
+      # Validates that an ID parameter is present and not empty
+      # @param id [String] The ID to validate
+      # @param resource_name [String] The resource name for the error message
+      # @raise [ArgumentError] if id is nil or empty
+      private def validate_id!(id, resource_name = "Resource")
+        return unless id.nil? || id.to_s.strip.empty?
+
+        raise ArgumentError, "#{resource_name} ID is required"
+      end
+
+      # Validates that data is not empty
+      # @param data [Hash] The data to validate
+      # @param operation [String] The operation name for the error message
+      # @raise [ArgumentError] if data is empty
+      private def validate_data!(data, operation = "Operation")
+        raise ArgumentError, "#{operation} data is required" if data.nil? || data.empty?
+      end
+
+      # Validates that a string parameter is present and not empty
+      # @param value [String] The value to validate
+      # @param field_name [String] The field name for the error message
+      # @raise [ArgumentError] if value is nil or empty
+      private def validate_required_string!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        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
+      # @raise [ArgumentError] if either is missing
+      private def validate_parent!(parent_object, parent_record_id)
+        validate_required_string!(parent_object, "Parent object")
+        validate_required_string!(parent_record_id, "Parent record ID")
+      end
+
+      private def request(method, path, params = {}, _headers = {})
+        # Path is already safely constructed by the resource methods
+        connection = client.connection
+
         case method
         when :get
-          client.connection.get(path, params)
+          handle_get_request(connection, path, params)
         when :post
-          client.connection.post(path, params)
+          handle_post_request(connection, path, params)
         when :patch
-          client.connection.patch(path, params)
+          connection.patch(path, params)
         when :put
-          client.connection.put(path, params)
+          connection.put(path, params)
         when :delete
-          client.connection.delete(path)
+          handle_delete_request(connection, path, params)
         else
           raise ArgumentError, "Unsupported HTTP method: #{method}"
         end
       end
+
+      private def handle_get_request(connection, path, params)
+        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
     end
   end
 end