attio 0.1.1 → 0.2.0

data/lib/attio/resources/records.rb

@@ -1,41 +1,43 @@
+# frozen_string_literal: true
+
+# Handles all record-related API operations.
+#
+# Records are the main data entities in Attio, representing things like
+# people, companies, deals, etc. This class provides methods to create,
+# read, update, delete, and query records.
+#
+# @example List records
+#   records = client.records.list(object: 'people', filters: { name: 'John' })
+#
+# @example Create a record
+#   record = client.records.create(
+#     object: 'people',
+#     data: { name: 'Jane Doe', email: 'jane@example.com' }
+#   )
+#
+# @author Ernest Sim
+# @since 1.0.0
 module Attio
   module Resources
-    # Handles all record-related API operations.
-    # 
-    # Records are the main data entities in Attio, representing things like
-    # people, companies, deals, etc. This class provides methods to create,
-    # read, update, delete, and query records.
-    # 
-    # @example List records
-    #   records = client.records.list(object: 'people', filters: { name: 'John' })
-    # 
-    # @example Create a record
-    #   record = client.records.create(
-    #     object: 'people',
-    #     data: { name: 'Jane Doe', email: 'jane@example.com' }
-    #   )
-    # 
-    # @author Ernest Sim
-    # @since 1.0.0
     class Records < Base
       # Query and list records for a specific object type.
-      # 
+      #
       # This method allows you to retrieve records with optional filtering,
       # sorting, and pagination parameters.
-      # 
+      #
       # @param object [String] The object type to query (e.g., 'people', 'companies')
       # @param params [Hash] Query parameters including filters, sorts, and pagination
       # @option params [Hash] :filters Filtering criteria
       # @option params [Array] :sorts Sorting options
       # @option params [Integer] :limit Number of records to return
       # @option params [String] :cursor Pagination cursor for next page
-      # 
+      #
       # @return [Hash] API response containing records and pagination info
       # @raise [ArgumentError] if object is nil or empty
-      # 
+      #
       # @example Basic listing
       #   records = client.records.list(object: 'people')
-      # 
+      #
       # @example With filters
       #   records = client.records.list(
       #     object: 'people',
@@ -43,34 +45,34 @@ module Attio
       #     limit: 50
       #   )
       def list(object:, **params)
-        validate_object!(object)
+        validate_required_string!(object, "Object type")
         request(:post, "objects/#{object}/records/query", params)
       end
 
       # Retrieve a specific record by ID.
-      # 
+      #
       # @param object [String] The object type (e.g., 'people', 'companies')
       # @param id [String] The record ID
-      # 
+      #
       # @return [Hash] The record data
       # @raise [ArgumentError] if object or id is nil or empty
-      # 
+      #
       # @example
       #   record = client.records.get(object: 'people', id: 'abc123')
       def get(object:, id:)
-        validate_object!(object)
-        validate_id!(id)
+        validate_required_string!(object, "Object type")
+        validate_id!(id, "Record")
         request(:get, "objects/#{object}/records/#{id}")
       end
 
       # Create a new record.
-      # 
+      #
       # @param object [String] The object type to create the record in
       # @param data [Hash] The record data to create
-      # 
+      #
       # @return [Hash] The created record data
       # @raise [ArgumentError] if object is nil/empty or data is invalid
-      # 
+      #
       # @example Create a person
       #   record = client.records.create(
       #     object: 'people',
@@ -81,20 +83,20 @@ module Attio
       #     }
       #   )
       def create(object:, data:)
-        validate_object!(object)
-        validate_data!(data)
+        validate_required_string!(object, "Object type")
+        validate_record_data!(data)
         request(:post, "objects/#{object}/records", data)
       end
 
       # Update an existing record.
-      # 
+      #
       # @param object [String] The object type
       # @param id [String] The record ID to update
       # @param data [Hash] The updated record data
-      # 
+      #
       # @return [Hash] The updated record data
       # @raise [ArgumentError] if object, id, or data is invalid
-      # 
+      #
       # @example Update a person's name
       #   record = client.records.update(
       #     object: 'people',
@@ -102,57 +104,37 @@ module Attio
       #     data: { name: 'Jane Smith' }
       #   )
       def update(object:, id:, data:)
-        validate_object!(object)
-        validate_id!(id)
-        validate_data!(data)
+        validate_required_string!(object, "Object type")
+        validate_id!(id, "Record")
+        validate_record_data!(data)
         request(:patch, "objects/#{object}/records/#{id}", data)
       end
 
       # Delete a record.
-      # 
+      #
       # @param object [String] The object type
       # @param id [String] The record ID to delete
-      # 
+      #
       # @return [Hash] Deletion confirmation
       # @raise [ArgumentError] if object or id is nil or empty
-      # 
+      #
       # @example
       #   client.records.delete(object: 'people', id: 'abc123')
       def delete(object:, id:)
-        validate_object!(object)
-        validate_id!(id)
+        validate_required_string!(object, "Object type")
+        validate_id!(id, "Record")
         request(:delete, "objects/#{object}/records/#{id}")
       end
 
-      private
-
-      # Validates that the object parameter is present and not empty.
-      # 
-      # @param object [String, nil] The object type to validate
-      # @raise [ArgumentError] if object is nil or empty
-      # @api private
-      def validate_object!(object)
-        raise ArgumentError, "Object type is required" if object.nil? || object.to_s.strip.empty?
-      end
-
-      # Validates that the ID parameter is present and not empty.
-      # 
-      # @param id [String, nil] The record ID to validate
-      # @raise [ArgumentError] if id is nil or empty
-      # @api private
-      def validate_id!(id)
-        raise ArgumentError, "Record ID is required" if id.nil? || id.to_s.strip.empty?
-      end
-
       # Validates that the data parameter is present and is a hash.
-      # 
+      #
       # @param data [Hash, nil] The data to validate
       # @raise [ArgumentError] if data is nil or not a hash
       # @api private
-      def validate_data!(data)
+      private def validate_record_data!(data)
         raise ArgumentError, "Data is required" if data.nil?
         raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
       end
     end
   end
-end
+end

data/lib/attio/resources/tasks.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # API resource for managing tasks in Attio
+    #
+    # Tasks help track action items and to-dos associated with records.
+    #
+    # @example Creating a task
+    #   client.tasks.create(
+    #     parent_object: "people",
+    #     parent_record_id: "person_123",
+    #     title: "Follow up on proposal",
+    #     due_date: "2025-02-01",
+    #     assignee_id: "user_456"
+    #   )
+    #
+    # @example Listing tasks with filters
+    #   client.tasks.list(
+    #     status: "pending",
+    #     assignee_id: "user_456"
+    #   )
+    class Tasks < Base
+      # List tasks with optional filters
+      #
+      # @param params [Hash] Query parameters
+      # @option params [String] :parent_object Filter by parent object type
+      # @option params [String] :parent_record_id Filter by parent record
+      # @option params [String] :status Filter by status (pending, completed)
+      # @option params [String] :assignee_id Filter by assignee
+      # @option params [Integer] :limit Number of tasks to return
+      # @option params [String] :cursor Pagination cursor
+      #
+      # @return [Hash] API response containing tasks
+      def list(**params)
+        request(:get, "tasks", params)
+      end
+
+      # Get a specific task by ID
+      #
+      # @param id [String] The task ID
+      #
+      # @return [Hash] The task data
+      # @raise [ArgumentError] if id is nil or empty
+      def get(id:)
+        validate_id!(id, "Task")
+        request(:get, "tasks/#{id}")
+      end
+
+      # Create a new task
+      #
+      # @param parent_object [String] The parent object type
+      # @param parent_record_id [String] The ID of the parent record
+      # @param title [String] The task title
+      # @param data [Hash] Additional task data
+      # @option data [String] :description Task description
+      # @option data [String] :due_date Due date (ISO 8601 format)
+      # @option data [String] :assignee_id User ID to assign the task to
+      # @option data [String] :status Task status (pending, completed)
+      # @option data [Integer] :priority Task priority (1-5)
+      #
+      # @return [Hash] The created task
+      # @raise [ArgumentError] if required parameters are missing
+      def create(parent_object:, parent_record_id:, title:, **data)
+        validate_parent!(parent_object, parent_record_id)
+        validate_required_string!(title, "Task title")
+
+        request(:post, "tasks", data.merge(
+                                  parent_object: parent_object,
+                                  parent_record_id: parent_record_id,
+                                  title: title
+                                ))
+      end
+
+      # Update an existing task
+      #
+      # @param id [String] The task ID
+      # @param data [Hash] The fields to update
+      # @option data [String] :title New title
+      # @option data [String] :description New description
+      # @option data [String] :due_date New due date
+      # @option data [String] :assignee_id New assignee
+      # @option data [String] :status New status
+      # @option data [Integer] :priority New priority
+      #
+      # @return [Hash] The updated task
+      # @raise [ArgumentError] if id is invalid
+      def update(id:, **data)
+        validate_id!(id, "Task")
+        validate_data!(data, "Update")
+        request(:patch, "tasks/#{id}", data)
+      end
+
+      # Mark a task as completed
+      #
+      # @param id [String] The task ID
+      # @param completed_at [String] Optional completion timestamp (defaults to now)
+      #
+      # @return [Hash] The updated task
+      # @raise [ArgumentError] if id is nil or empty
+      def complete(id:, completed_at: nil)
+        validate_id!(id, "Task")
+        data = { status: "completed" }
+        data[:completed_at] = completed_at if completed_at
+        request(:patch, "tasks/#{id}", data)
+      end
+
+      # Reopen a completed task
+      #
+      # @param id [String] The task ID
+      #
+      # @return [Hash] The updated task
+      # @raise [ArgumentError] if id is nil or empty
+      def reopen(id:)
+        validate_id!(id, "Task")
+        request(:patch, "tasks/#{id}", { status: "pending", completed_at: nil })
+      end
+
+      # Delete a task
+      #
+      # @param id [String] The task ID to delete
+      #
+      # @return [Hash] Deletion confirmation
+      # @raise [ArgumentError] if id is nil or empty
+      def delete(id:)
+        validate_id!(id, "Task")
+        request(:delete, "tasks/#{id}")
+      end
+    end
+  end
+end

data/lib/attio/resources/threads.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # API resource for managing threads in Attio
+    #
+    # Threads represent conversations or discussion topics related to records.
+    #
+    # @example Listing threads for a record
+    #   client.threads.list(
+    #     parent_object: "companies",
+    #     parent_record_id: "company_123"
+    #   )
+    #
+    # @example Getting a specific thread
+    #   client.threads.get(id: "thread_456")
+    class Threads < Base
+      # List threads for a parent record
+      #
+      # @param parent_object [String] The parent object type
+      # @param parent_record_id [String] The parent record ID
+      # @param params [Hash] Additional query parameters
+      # @option params [Integer] :limit Number of threads to return
+      # @option params [String] :cursor Pagination cursor
+      # @option params [String] :status Filter by status (open, closed)
+      #
+      # @return [Hash] API response containing threads
+      # @raise [ArgumentError] if parent_object or parent_record_id is missing
+      def list(parent_object:, parent_record_id:, **params)
+        validate_parent!(parent_object, parent_record_id)
+        request(:get, "threads", params.merge(
+                                   parent_object: parent_object,
+                                   parent_record_id: parent_record_id
+                                 ))
+      end
+
+      # Get a specific thread by ID
+      #
+      # @param id [String] The thread ID
+      # @param include_comments [Boolean] Whether to include comments in the response
+      #
+      # @return [Hash] The thread data
+      # @raise [ArgumentError] if id is nil or empty
+      def get(id:, include_comments: false)
+        validate_id!(id, "Thread")
+        params = include_comments ? { include: "comments" } : {}
+        request(:get, "threads/#{id}", params)
+      end
+
+      # Create a new thread
+      #
+      # @param parent_object [String] The parent object type
+      # @param parent_record_id [String] The parent record ID
+      # @param title [String] The thread title
+      # @param data [Hash] Additional thread data
+      # @option data [String] :description Thread description
+      # @option data [String] :status Thread status (open, closed)
+      # @option data [Array<String>] :participant_ids User IDs of participants
+      #
+      # @return [Hash] The created thread
+      # @raise [ArgumentError] if required parameters are missing
+      def create(parent_object:, parent_record_id:, title:, **data)
+        validate_parent!(parent_object, parent_record_id)
+        validate_required_string!(title, "Thread title")
+
+        request(:post, "threads", data.merge(
+                                    parent_object: parent_object,
+                                    parent_record_id: parent_record_id,
+                                    title: title
+                                  ))
+      end
+
+      # Update an existing thread
+      #
+      # @param id [String] The thread ID
+      # @param data [Hash] The fields to update
+      # @option data [String] :title New title
+      # @option data [String] :description New description
+      # @option data [String] :status New status (open, closed)
+      #
+      # @return [Hash] The updated thread
+      # @raise [ArgumentError] if id is invalid
+      def update(id:, **data)
+        validate_id!(id, "Thread")
+        validate_data!(data, "Update")
+        request(:patch, "threads/#{id}", data)
+      end
+
+      # Close a thread
+      #
+      # @param id [String] The thread ID
+      #
+      # @return [Hash] The updated thread
+      # @raise [ArgumentError] if id is nil or empty
+      def close(id:)
+        validate_id!(id, "Thread")
+        request(:patch, "threads/#{id}", { status: "closed" })
+      end
+
+      # Reopen a closed thread
+      #
+      # @param id [String] The thread ID
+      #
+      # @return [Hash] The updated thread
+      # @raise [ArgumentError] if id is nil or empty
+      def reopen(id:)
+        validate_id!(id, "Thread")
+        request(:patch, "threads/#{id}", { status: "open" })
+      end
+
+      # Delete a thread
+      #
+      # @param id [String] The thread ID to delete
+      #
+      # @return [Hash] Deletion confirmation
+      # @raise [ArgumentError] if id is nil or empty
+      def delete(id:)
+        validate_id!(id, "Thread")
+        request(:delete, "threads/#{id}")
+      end
+
+      # Add participants to a thread
+      #
+      # @param id [String] The thread ID
+      # @param user_ids [Array<String>] User IDs to add as participants
+      #
+      # @return [Hash] The updated thread
+      # @raise [ArgumentError] if id or user_ids is invalid
+      def add_participants(id:, user_ids:)
+        validate_id!(id, "Thread")
+        validate_user_ids!(user_ids)
+        request(:post, "threads/#{id}/participants", { user_ids: user_ids })
+      end
+
+      # Remove participants from a thread
+      #
+      # @param id [String] The thread ID
+      # @param user_ids [Array<String>] User IDs to remove
+      #
+      # @return [Hash] The updated thread
+      # @raise [ArgumentError] if id or user_ids is invalid
+      def remove_participants(id:, user_ids:)
+        validate_id!(id, "Thread")
+        validate_user_ids!(user_ids)
+        request(:delete, "threads/#{id}/participants", { user_ids: user_ids })
+      end
+
+      private def validate_user_ids!(user_ids)
+        raise ArgumentError, "User IDs are required" if user_ids.nil? || user_ids.empty?
+        raise ArgumentError, "User IDs must be an array" unless user_ids.is_a?(Array)
+      end
+    end
+  end
+end

data/lib/attio/resources/users.rb

@@ -1,5 +1,13 @@
+# frozen_string_literal: true
+
 module Attio
   module Resources
+    # API resource for managing workspace users
+    #
+    # Users are people who have access to your Attio workspace.
+    #
+    # @example Listing all users
+    #   client.users.list
     class Users < Base
       def list(**params)
         request(:get, "users", params)
@@ -10,11 +18,9 @@ module Attio
         request(:get, "users/#{id}")
       end
 
-      private
-
-      def validate_id!(id)
+      private def validate_id!(id)
         raise ArgumentError, "User ID is required" if id.nil? || id.to_s.strip.empty?
       end
     end
   end
-end
+end

data/lib/attio/resources/workspaces.rb

@@ -1,5 +1,13 @@
+# frozen_string_literal: true
+
 module Attio
   module Resources
+    # API resource for managing workspace information
+    #
+    # Workspaces are the top-level organizational unit in Attio.
+    #
+    # @example Getting workspace information
+    #   client.workspaces.get
     class Workspaces < Base
       def get
         request(:get, "workspace")
@@ -10,4 +18,4 @@ module Attio
       end
     end
   end
-end
+end

data/lib/attio/retry_handler.rb

@@ -1,4 +1,14 @@
+# frozen_string_literal: true
+
 module Attio
+  # Handles automatic retry logic for failed API requests
+  #
+  # This class implements exponential backoff retry strategy for
+  # transient errors like timeouts and rate limits.
+  #
+  # @example Using the retry handler
+  #   handler = RetryHandler.new(max_retries: 5)
+  #   handler.with_retry { api_client.get("/endpoint") }
   class RetryHandler
     DEFAULT_MAX_RETRIES = 3
     DEFAULT_RETRY_DELAY = 1 # seconds
@@ -7,12 +17,12 @@ module Attio
       HttpClient::TimeoutError,
       HttpClient::ConnectionError,
       ServerError,
-      RateLimitError
+      RateLimitError,
     ].freeze
 
     attr_reader :max_retries, :retry_delay, :backoff_factor, :logger
 
-    def initialize(max_retries: DEFAULT_MAX_RETRIES, 
+    def initialize(max_retries: DEFAULT_MAX_RETRIES,
                    retry_delay: DEFAULT_RETRY_DELAY,
                    backoff_factor: DEFAULT_BACKOFF_FACTOR,
                    logger: nil)
@@ -22,7 +32,7 @@ module Attio
       @logger = logger
     end
 
-    def with_retry(&block)
+    def with_retry
       retries = 0
       delay = retry_delay
 
@@ -30,7 +40,7 @@ module Attio
         yield
       rescue *RETRIABLE_ERRORS => e
         retries += 1
-        
+
         if retries <= max_retries
           log_retry(e, retries, delay)
           sleep(delay)
@@ -43,11 +53,9 @@ module Attio
       end
     end
 
-    private
-
-    def log_retry(error, attempt, delay)
+    private def log_retry(error, attempt, delay)
       return unless logger
-      
+
       logger.warn(
         "Retry attempt #{attempt}/#{max_retries}",
         error: error.class.name,
@@ -56,9 +64,9 @@ module Attio
       )
     end
 
-    def log_failure(error, attempts)
+    private def log_failure(error, attempts)
       return unless logger
-      
+
       logger.error(
         "Max retries exceeded",
         error: error.class.name,
@@ -67,4 +75,4 @@ module Attio
       )
     end
   end
-end
+end

data/lib/attio/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Attio
-  VERSION = "0.1.1"
+  VERSION = "0.2.0"
 end

data/lib/attio.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "typhoeus"
 
 require "attio/version"
@@ -12,34 +14,38 @@ require "attio/resources/lists"
 require "attio/resources/workspaces"
 require "attio/resources/attributes"
 require "attio/resources/users"
+require "attio/resources/notes"
+require "attio/resources/tasks"
+require "attio/resources/comments"
+require "attio/resources/threads"
 
 # The main Attio module provides access to the Attio API client.
-# 
+#
 # This is the primary entry point for interacting with the Attio API.
-# 
+#
 # @example Basic usage
 #   client = Attio.client(api_key: 'your-api-key')
-#   
+#
 # @example Working with records
 #   # List records for a specific object type
 #   records = client.records.list(object: 'people', filters: { name: 'John' })
-#   
+#
 #   # Create a new record
 #   new_record = client.records.create(
 #     object: 'people',
 #     data: { name: 'Jane Doe', email: 'jane@example.com' }
 #   )
-#   
+#
 #   # Get a specific record
 #   record = client.records.get(object: 'people', id: 'record-id')
-#   
+#
 #   # Update a record
 #   updated = client.records.update(
 #     object: 'people',
 #     id: 'record-id',
 #     data: { name: 'Jane Smith' }
 #   )
-#   
+#
 #   # Delete a record
 #   client.records.delete(object: 'people', id: 'record-id')
 #
@@ -47,11 +53,11 @@ require "attio/resources/users"
 # @since 1.0.0
 module Attio
   # Creates a new Attio API client instance.
-  # 
+  #
   # @param api_key [String] Your Attio API key
   # @return [Client] A new client instance configured with the provided API key
   # @raise [ArgumentError] if api_key is nil or empty
-  # 
+  #
   # @example Create a client
   #   client = Attio.client(api_key: 'your-api-key-here')
   def self.client(api_key:)