attio 0.1.3 → 0.2.0

data/lib/attio/resources/comments.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # API resource for managing comments in Attio
+    #
+    # Comments can be added to records and threads for collaboration.
+    #
+    # @example Creating a comment on a record
+    #   client.comments.create(
+    #     parent_object: "people",
+    #     parent_record_id: "person_123",
+    #     content: "Just had a great call with this lead!"
+    #   )
+    #
+    # @example Creating a comment in a thread
+    #   client.comments.create(
+    #     thread_id: "thread_456",
+    #     content: "Following up on our discussion..."
+    #   )
+    class Comments < Base
+      # List comments for a parent record or thread
+      #
+      # @param params [Hash] Query parameters
+      # @option params [String] :parent_object Parent object type
+      # @option params [String] :parent_record_id Parent record ID
+      # @option params [String] :thread_id Thread ID
+      # @option params [Integer] :limit Number of comments to return
+      # @option params [String] :cursor Pagination cursor
+      #
+      # @return [Hash] API response containing comments
+      def list(**params)
+        validate_list_params!(params)
+        request(:get, "comments", params)
+      end
+
+      # Get a specific comment by ID
+      #
+      # @param id [String] The comment ID
+      #
+      # @return [Hash] The comment data
+      # @raise [ArgumentError] if id is nil or empty
+      def get(id:)
+        validate_id!(id, "Comment")
+        request(:get, "comments/#{id}")
+      end
+
+      # Create a new comment
+      #
+      # @param content [String] The comment content (supports markdown)
+      # @param parent_object [String] Parent object type (required if no thread_id)
+      # @param parent_record_id [String] Parent record ID (required if no thread_id)
+      # @param thread_id [String] Thread ID (required if no parent_object/parent_record_id)
+      # @param data [Hash] Additional comment data
+      #
+      # @return [Hash] The created comment
+      # @raise [ArgumentError] if required parameters are missing
+      def create(content:, parent_object: nil, parent_record_id: nil, thread_id: nil, **data)
+        validate_required_string!(content, "Comment content")
+        validate_create_params!(parent_object, parent_record_id, thread_id)
+
+        params = data.merge(content: content)
+
+        if thread_id
+          params[:thread_id] = thread_id
+        else
+          params[:parent_object] = parent_object
+          params[:parent_record_id] = parent_record_id
+        end
+
+        request(:post, "comments", params)
+      end
+
+      # Update an existing comment
+      #
+      # @param id [String] The comment ID
+      # @param content [String] The new content
+      #
+      # @return [Hash] The updated comment
+      # @raise [ArgumentError] if id or content is invalid
+      def update(id:, content:)
+        validate_id!(id, "Comment")
+        validate_required_string!(content, "Comment content")
+        request(:patch, "comments/#{id}", { content: content })
+      end
+
+      # Delete a comment
+      #
+      # @param id [String] The comment ID to delete
+      #
+      # @return [Hash] Deletion confirmation
+      # @raise [ArgumentError] if id is nil or empty
+      def delete(id:)
+        validate_id!(id, "Comment")
+        request(:delete, "comments/#{id}")
+      end
+
+      # React to a comment with an emoji
+      #
+      # @param id [String] The comment ID
+      # @param emoji [String] The emoji reaction (e.g., "👍", "❤️")
+      #
+      # @return [Hash] The updated comment with reaction
+      # @raise [ArgumentError] if id or emoji is invalid
+      def react(id:, emoji:)
+        validate_id!(id, "Comment")
+        validate_required_string!(emoji, "Emoji")
+        request(:post, "comments/#{id}/reactions", { emoji: emoji })
+      end
+
+      # Remove a reaction from a comment
+      #
+      # @param id [String] The comment ID
+      # @param emoji [String] The emoji reaction to remove
+      #
+      # @return [Hash] The updated comment
+      # @raise [ArgumentError] if id or emoji is invalid
+      def unreact(id:, emoji:)
+        validate_id!(id, "Comment")
+        validate_required_string!(emoji, "Emoji")
+        request(:delete, "comments/#{id}/reactions/#{CGI.escape(emoji)}")
+      end
+
+      private def validate_list_params!(params)
+        has_parent = params[:parent_object] && params[:parent_record_id]
+        has_thread = params[:thread_id]
+
+        return if has_parent || has_thread
+
+        raise ArgumentError, "Must provide either parent_object/parent_record_id or thread_id"
+      end
+
+      private def validate_create_params!(parent_object, parent_record_id, thread_id)
+        has_parent = parent_object && parent_record_id
+        has_thread = thread_id
+
+        unless has_parent || has_thread
+          raise ArgumentError, "Must provide either parent_object/parent_record_id or thread_id"
+        end
+
+        return unless has_parent && has_thread
+
+        raise ArgumentError, "Cannot provide both parent and thread parameters"
+      end
+    end
+  end
+end

data/lib/attio/resources/lists.rb

@@ -17,46 +17,34 @@ module Attio
       end
 
       def get(id:)
-        validate_id!(id)
+        validate_id!(id, "List")
         request(:get, "lists/#{id}")
       end
 
       def entries(id:, **params)
-        validate_id!(id)
+        validate_id!(id, "List")
         request(:get, "lists/#{id}/entries", params)
       end
 
       def create_entry(id:, data:)
-        validate_id!(id)
-        validate_data!(data)
+        validate_id!(id, "List")
+        validate_list_entry_data!(data)
         request(:post, "lists/#{id}/entries", data)
       end
 
       def get_entry(list_id:, entry_id:)
-        validate_list_id!(list_id)
-        validate_entry_id!(entry_id)
+        validate_id!(list_id, "List")
+        validate_id!(entry_id, "Entry")
         request(:get, "lists/#{list_id}/entries/#{entry_id}")
       end
 
       def delete_entry(list_id:, entry_id:)
-        validate_list_id!(list_id)
-        validate_entry_id!(entry_id)
+        validate_id!(list_id, "List")
+        validate_id!(entry_id, "Entry")
         request(:delete, "lists/#{list_id}/entries/#{entry_id}")
       end
 
-      private def validate_id!(id)
-        raise ArgumentError, "List ID is required" if id.nil? || id.to_s.strip.empty?
-      end
-
-      private def validate_list_id!(list_id)
-        raise ArgumentError, "List ID is required" if list_id.nil? || list_id.to_s.strip.empty?
-      end
-
-      private def validate_entry_id!(entry_id)
-        raise ArgumentError, "Entry ID is required" if entry_id.nil? || entry_id.to_s.strip.empty?
-      end
-
-      private def validate_data!(data)
+      private def validate_list_entry_data!(data)
         raise ArgumentError, "Data is required" if data.nil?
         raise ArgumentError, "Data must be a hash" unless data.is_a?(Hash)
       end

data/lib/attio/resources/notes.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # API resource for managing notes in Attio
+    #
+    # Notes can be attached to records to track important information,
+    # meeting notes, or any other textual data.
+    #
+    # @example Creating a note on a person
+    #   client.notes.create(
+    #     parent_object: "people",
+    #     parent_record_id: "person_123",
+    #     title: "Meeting Notes",
+    #     content: "Discussed Q4 goals..."
+    #   )
+    #
+    # @example Listing notes for a record
+    #   client.notes.list(
+    #     parent_object: "companies",
+    #     parent_record_id: "company_456"
+    #   )
+    class Notes < Base
+      # List notes for a specific parent record
+      #
+      # @param parent_object [String] The parent object type (e.g., "people", "companies")
+      # @param parent_record_id [String] The ID of the parent record
+      # @param params [Hash] Additional query parameters
+      # @option params [Integer] :limit Number of notes to return
+      # @option params [String] :cursor Pagination cursor
+      #
+      # @return [Hash] API response containing notes
+      # @raise [ArgumentError] if parent_object or parent_record_id is nil
+      def list(parent_object:, parent_record_id:, **params)
+        validate_parent!(parent_object, parent_record_id)
+        request(:get, "notes", params.merge(
+                                 parent_object: parent_object,
+                                 parent_record_id: parent_record_id
+                               ))
+      end
+
+      # Get a specific note by ID
+      #
+      # @param id [String] The note ID
+      #
+      # @return [Hash] The note data
+      # @raise [ArgumentError] if id is nil or empty
+      def get(id:)
+        validate_id!(id, "Note")
+        request(:get, "notes/#{id}")
+      end
+
+      # Create a new note
+      #
+      # @param parent_object [String] The parent object type
+      # @param parent_record_id [String] The ID of the parent record
+      # @param title [String] The note title
+      # @param content [String] The note content (supports markdown)
+      # @param data [Hash] Additional note data
+      #
+      # @return [Hash] The created note
+      # @raise [ArgumentError] if required parameters are missing
+      def create(parent_object:, parent_record_id:, title:, content:, **data)
+        validate_parent!(parent_object, parent_record_id)
+        validate_required_string!(title, "Note title")
+        validate_required_string!(content, "Note content")
+
+        request(:post, "notes", data.merge(
+                                  parent_object: parent_object,
+                                  parent_record_id: parent_record_id,
+                                  title: title,
+                                  content: content
+                                ))
+      end
+
+      # Update an existing note
+      #
+      # @param id [String] The note ID
+      # @param data [Hash] The fields to update
+      # @option data [String] :title New title
+      # @option data [String] :content New content
+      #
+      # @return [Hash] The updated note
+      # @raise [ArgumentError] if id or data is invalid
+      def update(id:, **data)
+        validate_id!(id, "Note")
+        validate_note_update_data!(data)
+        request(:patch, "notes/#{id}", data)
+      end
+
+      # Delete a note
+      #
+      # @param id [String] The note ID to delete
+      #
+      # @return [Hash] Deletion confirmation
+      # @raise [ArgumentError] if id is nil or empty
+      def delete(id:)
+        validate_id!(id, "Note")
+        request(:delete, "notes/#{id}")
+      end
+
+      private def validate_note_update_data!(data)
+        raise ArgumentError, "Update data is required" if data.empty?
+        return if data.key?(:title) || data.key?(:content)
+
+        raise ArgumentError, "Must provide title or content to update"
+      end
+    end
+  end
+end

data/lib/attio/resources/records.rb

@@ -45,7 +45,7 @@ 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
 
@@ -60,8 +60,8 @@ module Attio
       # @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
 
@@ -83,8 +83,8 @@ 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
 
@@ -104,9 +104,9 @@ 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
 
@@ -121,30 +121,17 @@ module Attio
       # @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 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
-      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
-      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

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/version.rb

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

data/lib/attio.rb

@@ -14,6 +14,10 @@ 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.
 #