attio 0.1.3 → 0.3.0

data/lib/attio/resources/meta.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # Meta resource for API metadata and identification
+    #
+    # @example Identify the current API key
+    #   client.meta.identify
+    #   # => { "workspace" => { "id" => "...", "name" => "..." }, "user" => { ... } }
+    #
+    # @example Get API status
+    #   client.meta.status
+    #   # => { "status" => "operational", "version" => "v2" }
+    class Meta < Base
+      # Identify the current API key and get workspace/user information
+      #
+      # @return [Hash] Information about the authenticated workspace and user
+      def identify
+        request(:get, "meta/identify")
+      end
+
+      # Get API status and version information
+      #
+      # @return [Hash] API status and version details
+      def status
+        request(:get, "meta/status")
+      end
+
+      # Get rate limit information for the current API key
+      #
+      # @return [Hash] Current rate limit status
+      def rate_limits
+        request(:get, "meta/rate_limits")
+      end
+
+      # Get workspace configuration and settings
+      #
+      # @return [Hash] Workspace configuration details
+      def workspace_config
+        request(:get, "meta/workspace_config")
+      end
+
+      # Validate an API key without making changes
+      #
+      # @return [Hash] Validation result with key permissions
+      def validate_key
+        request(:post, "meta/validate", {})
+      end
+
+      # Get available API endpoints and their documentation
+      #
+      # @return [Hash] List of available endpoints with descriptions
+      def endpoints
+        request(:get, "meta/endpoints")
+      end
+
+      # Get workspace usage statistics
+      #
+      # @return [Hash] Usage statistics including record counts, API calls, etc.
+      def usage_stats
+        request(:get, "meta/usage")
+      end
+
+      # Get feature flags and capabilities for the workspace
+      #
+      # @return [Hash] Enabled features and capabilities
+      def features
+        request(:get, "meta/features")
+      end
+    end
+  end
+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/resources/workspace_members.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Attio
+  module Resources
+    # Workspace Members resource for managing workspace member access
+    #
+    # @example List all workspace members
+    #   client.workspace_members.list
+    #
+    # @example Get a specific member
+    #   client.workspace_members.get(member_id: "user_123")
+    #
+    # @example Invite a new member
+    #   client.workspace_members.invite(
+    #     email: "new.member@example.com",
+    #     role: "member"
+    #   )
+    class WorkspaceMembers < Base
+      # List all workspace members
+      #
+      # @param params [Hash] Optional query parameters
+      # @option params [Integer] :limit Maximum number of results
+      # @option params [String] :offset Pagination offset
+      # @return [Hash] The API response
+      def list(params = {})
+        request(:get, "workspace_members", params)
+      end
+
+      # Get a specific workspace member
+      #
+      # @param member_id [String] The member ID
+      # @return [Hash] The member data
+      def get(member_id:)
+        validate_id!(member_id, "Member")
+        request(:get, "workspace_members/#{member_id}")
+      end
+
+      # Invite a new member to the workspace
+      #
+      # @param email [String] The email address to invite
+      # @param role [String] The role to assign (admin, member, guest)
+      # @param data [Hash] Additional member data
+      # @return [Hash] The created invitation
+      def invite(email:, role: "member", data: {})
+        validate_required_string!(email, "Email")
+        validate_required_string!(role, "Role")
+
+        raise ArgumentError, "Role must be one of: admin, member, guest" unless %w[admin member guest].include?(role)
+
+        body = data.merge(email: email, role: role)
+        request(:post, "workspace_members/invitations", body)
+      end
+
+      # Update a workspace member's role or permissions
+      #
+      # @param member_id [String] The member ID to update
+      # @param data [Hash] The data to update
+      # @option data [String] :role The new role
+      # @option data [Hash] :permissions Custom permissions
+      # @return [Hash] The updated member
+      def update(member_id:, data:)
+        validate_id!(member_id, "Member")
+        validate_required_hash!(data, "Data")
+
+        request(:patch, "workspace_members/#{member_id}", data)
+      end
+
+      # Remove a member from the workspace
+      #
+      # @param member_id [String] The member ID to remove
+      # @return [Hash] Confirmation of removal
+      def remove(member_id:)
+        validate_id!(member_id, "Member")
+        request(:delete, "workspace_members/#{member_id}")
+      end
+
+      # Accept a workspace invitation
+      #
+      # @param invitation_token [String] The invitation token
+      # @return [Hash] The workspace member data
+      def accept_invitation(invitation_token:)
+        validate_required_string!(invitation_token, "Invitation token")
+        request(:post, "workspace_members/invitations/#{invitation_token}/accept")
+      end
+
+      # Resend an invitation
+      #
+      # @param member_id [String] The member ID with pending invitation
+      # @return [Hash] Confirmation of resent invitation
+      def resend_invitation(member_id:)
+        validate_id!(member_id, "Member")
+        request(:post, "workspace_members/#{member_id}/resend_invitation")
+      end
+
+      # Get current member (self)
+      #
+      # @return [Hash] The current authenticated member's data
+      def me
+        request(:get, "workspace_members/me")
+      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.3.0"
 end

data/lib/attio.rb

@@ -14,6 +14,15 @@ 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"
+require "attio/resources/workspace_members"
+require "attio/resources/deals"
+require "attio/resources/meta"
+require "attio/resources/bulk"
+require "attio/rate_limiter"
 
 # The main Attio module provides access to the Attio API client.
 #