attio 0.1.1 → 0.2.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

@@ -1,51 +1,53 @@
+# frozen_string_literal: true
+
+# The main client class for interacting with the Attio API.
+#
+# This class provides access to all Attio API resources and handles
+# authentication, connection management, and request routing.
+#
+# @example Basic client creation
+#   client = Attio::Client.new(api_key: 'your-api-key')
+#
+# @example Custom timeout
+#   client = Attio::Client.new(api_key: 'your-api-key', timeout: 60)
+#
+# @author Ernest Sim
+# @since 1.0.0
 module Attio
-  # The main client class for interacting with the Attio API.
-  # 
-  # This class provides access to all Attio API resources and handles
-  # authentication, connection management, and request routing.
-  # 
-  # @example Basic client creation
-  #   client = Attio::Client.new(api_key: 'your-api-key')
-  # 
-  # @example Custom timeout
-  #   client = Attio::Client.new(api_key: 'your-api-key', timeout: 60)
-  # 
-  # @author Ernest Sim
-  # @since 1.0.0
   class Client
     # The base URL for the Attio API v2
-    API_BASE_URL = "https://api.attio.com/v2".freeze
-    
+    API_BASE_URL = "https://api.attio.com/v2"
+
     # Default request timeout in seconds
     DEFAULT_TIMEOUT = 30
 
     # @return [String] The API key used for authentication
     attr_reader :api_key
-    
+
     # @return [Integer] The request timeout in seconds
     attr_reader :timeout
 
     # Initialize a new Attio API client.
-    # 
+    #
     # @param api_key [String] Your Attio API key (required)
     # @param timeout [Integer] Request timeout in seconds (default: 30)
     # @raise [ArgumentError] if api_key is nil or empty
-    # 
+    #
     # @example
     #   client = Attio::Client.new(api_key: 'sk-...your-key...')
     def initialize(api_key:, timeout: DEFAULT_TIMEOUT)
       raise ArgumentError, "API key is required" if api_key.nil? || api_key.empty?
-      
+
       @api_key = api_key
       @timeout = timeout
     end
 
     # Returns the HTTP connection instance for making API requests.
-    # 
+    #
     # This method creates and configures the HTTP client with proper
     # authentication headers and settings. The connection is cached
     # for subsequent requests.
-    # 
+    #
     # @return [HttpClient] The configured HTTP client instance
     # @api private
     def connection
@@ -55,14 +57,14 @@ module Attio
           "Authorization" => "Bearer #{api_key}",
           "Accept" => "application/json",
           "Content-Type" => "application/json",
-          "User-Agent" => "Attio Ruby Client/#{VERSION}"
+          "User-Agent" => "Attio Ruby Client/#{VERSION}",
         },
         timeout: timeout
       )
     end
 
     # Access to the Records API resource.
-    # 
+    #
     # @return [Resources::Records] Records resource instance
     # @example
     #   records = client.records.list(object: 'people')
@@ -71,7 +73,7 @@ module Attio
     end
 
     # Access to the Objects API resource.
-    # 
+    #
     # @return [Resources::Objects] Objects resource instance
     # @example
     #   objects = client.objects.list
@@ -80,7 +82,7 @@ module Attio
     end
 
     # Access to the Lists API resource.
-    # 
+    #
     # @return [Resources::Lists] Lists resource instance
     # @example
     #   lists = client.lists.list
@@ -89,7 +91,7 @@ module Attio
     end
 
     # Access to the Workspaces API resource.
-    # 
+    #
     # @return [Resources::Workspaces] Workspaces resource instance
     # @example
     #   workspaces = client.workspaces.list
@@ -98,7 +100,7 @@ module Attio
     end
 
     # Access to the Attributes API resource.
-    # 
+    #
     # @return [Resources::Attributes] Attributes resource instance
     # @example
     #   attributes = client.attributes.list
@@ -107,12 +109,48 @@ module Attio
     end
 
     # Access to the Users API resource.
-    # 
+    #
     # @return [Resources::Users] Users resource instance
     # @example
     #   users = client.users.list
     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
   end
-end
+end

data/lib/attio/connection_pool.rb

@@ -1,6 +1,18 @@
-require 'thread'
+# frozen_string_literal: true
 
 module Attio
+  # Thread-safe connection pool for managing HTTP connections
+  #
+  # This class provides a pool of connections that can be shared
+  # across threads for improved performance and resource management.
+  #
+  # @example Creating a connection pool
+  #   pool = ConnectionPool.new(size: 10) { HttpClient.new }
+  #
+  # @example Using a connection from the pool
+  #   pool.with_connection do |conn|
+  #     conn.get("/endpoint")
+  #   end
   class ConnectionPool
     DEFAULT_POOL_SIZE = 5
     DEFAULT_TIMEOUT = 5 # seconds to wait for connection
@@ -14,7 +26,7 @@ module Attio
       @key = :"#{object_id}_connection"
       @block = block
       @mutex = Mutex.new
-      
+
       size.times { @available << create_connection }
     end
 
@@ -29,14 +41,12 @@ module Attio
 
     def checkout
       deadline = Time.now + timeout
-      
+
       loop do
-        return @available.pop(true) if @available.size > 0
-        
-        if Time.now >= deadline
-          raise TimeoutError, "Couldn't acquire connection within #{timeout} seconds"
-        end
-        
+        return @available.pop(true) if @available.size.positive?
+
+        raise TimeoutError, "Couldn't acquire connection within #{timeout} seconds" if Time.now >= deadline
+
         sleep(0.01)
       end
     rescue ThreadError
@@ -52,18 +62,20 @@ module Attio
     def shutdown
       @mutex.synchronize do
         @available.close
-        while connection = @available.pop(true) rescue nil
+        while (connection = begin
+          @available.pop(true)
+        rescue StandardError
+          nil
+        end)
           connection.close if connection.respond_to?(:close)
         end
       end
     end
 
-    private
-
-    def create_connection
+    private def create_connection
       @block.call
     end
 
     class TimeoutError < StandardError; end
   end
-end
+end

data/lib/attio/errors.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
+
 module Attio
   class Error < StandardError; end
-  
+
   class AuthenticationError < Error; end
   class NotFoundError < Error; end
   class ValidationError < Error; end
   class RateLimitError < Error; end
   class ServerError < Error; end
-end
+end

data/lib/attio/http_client.rb

@@ -1,7 +1,15 @@
-require 'typhoeus'
-require 'json'
+# frozen_string_literal: true
+
+require "typhoeus"
+require "json"
 
 module Attio
+  # HTTP client for making API requests to Attio
+  #
+  # This class handles the low-level HTTP communication with the Attio API,
+  # including request execution, response parsing, and error handling.
+  #
+  # @api private
   class HttpClient
     DEFAULT_TIMEOUT = 30
 
@@ -13,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 = {})
@@ -29,20 +41,22 @@ 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 = {})
+    private def execute_request(method, path, options = {})
       url = "#{base_url}/#{path}"
-      
+
       request_options = {
         method: method,
-        headers: headers.merge('Content-Type' => 'application/json'),
+        headers: headers.merge("Content-Type" => "application/json"),
         timeout: timeout,
-        connecttimeout: timeout
+        connecttimeout: timeout,
       }.merge(options)
 
       request = Typhoeus::Request.new(url, request_options)
@@ -51,42 +65,57 @@ module Attio
       handle_response(response)
     end
 
-    def handle_response(response)
-      case response.code
-      when 0
-        # Timeout or connection error
-        if response.timed_out?
-          raise TimeoutError, "Request timed out"
-        else
-          raise ConnectionError, "Connection failed: #{response.return_message}"
-        end
-      when 200..299
-        parse_json(response.body)
-      when 401
-        raise AuthenticationError, parse_error_message(response)
-      when 404
-        raise NotFoundError, parse_error_message(response)
-      when 422
-        raise ValidationError, parse_error_message(response)
-      when 429
-        raise RateLimitError, parse_error_message(response)
-      when 500..599
-        raise ServerError, parse_error_message(response)
-      else
-        raise Error, "Request failed with status #{response.code}: #{parse_error_message(response)}"
-      end
+    private def handle_response(response)
+      return handle_connection_error(response) if response.code == 0
+      return parse_json(response.body) if (200..299).cover?(response.code)
+
+      handle_error_response(response)
+    end
+
+    private def handle_connection_error(response)
+      raise TimeoutError, "Request timed out" if response.timed_out?
+
+      raise ConnectionError, "Connection failed: #{response.return_message}"
+    end
+
+    private def handle_error_response(response)
+      error_class = error_class_for_status(response.code)
+      message = parse_error_message(response)
+
+      # Add status code to message for generic errors
+      message = "Request failed with status #{response.code}: #{message}" if error_class == Error
+
+      raise error_class, message
     end
 
-    def parse_json(body)
+    private def error_class_for_status(status)
+      error_map = {
+        401 => AuthenticationError,
+        404 => NotFoundError,
+        422 => ValidationError,
+        429 => RateLimitError,
+      }
+      return error_map[status] if error_map.key?(status)
+      return ServerError if (500..599).cover?(status)
+
+      Error
+    end
+
+    private def parse_json(body)
       return {} if body.nil? || body.empty?
+
       JSON.parse(body)
     rescue JSON::ParserError => e
       raise Error, "Invalid JSON response: #{e.message}"
     end
 
-    def parse_error_message(response)
-      body = parse_json(response.body) rescue response.body
-      
+    private def parse_error_message(response)
+      body = begin
+        parse_json(response.body)
+      rescue StandardError
+        response.body
+      end
+
       if body.is_a?(Hash)
         body["error"] || body["message"] || body.to_s
       else
@@ -97,4 +126,4 @@ module Attio
     class TimeoutError < Error; end
     class ConnectionError < Error; end
   end
-end
+end