attio 0.1.1 → 0.2.0

data/lib/attio/logger.rb

@@ -1,7 +1,17 @@
-require 'logger'
-require 'json'
+# frozen_string_literal: true
+
+require "logger"
+require "json"
 
 module Attio
+  # Enhanced logger for structured logging with JSON formatting
+  #
+  # This logger extends Ruby's standard Logger to provide structured
+  # logging with contextual information and JSON output.
+  #
+  # @example Basic usage
+  #   logger = Attio::Logger.new(STDOUT)
+  #   logger.info("API request", method: "GET", path: "/users")
   class Logger < ::Logger
     def initialize(logdev, level: ::Logger::INFO, formatter: nil)
       super(logdev)
@@ -25,23 +35,21 @@ module Attio
       super(format_message(message, context))
     end
 
-    private
-
-    def format_message(message, context)
+    private def format_message(message, context)
       return message if context.empty?
-      
+
       {
         message: message,
-        **context
+        **context,
       }
     end
 
-    def default_formatter
+    private def default_formatter
       proc do |severity, datetime, progname, msg|
         data = {
           timestamp: datetime.iso8601,
           level: severity,
-          progname: progname
+          progname: progname,
         }
 
         if msg.is_a?(Hash)
@@ -55,6 +63,12 @@ module Attio
     end
   end
 
+  # Specialized logger for API request/response logging
+  #
+  # This class provides sanitized logging of HTTP requests and responses,
+  # automatically redacting sensitive information like API keys.
+  #
+  # @api private
   class RequestLogger
     attr_reader :logger, :log_level
 
@@ -67,39 +81,35 @@ module Attio
       return unless logger
 
       logger.send(log_level, "API Request",
-        method: method.to_s.upcase,
-        url: url,
-        headers: sanitize_headers(headers),
-        body: sanitize_body(body)
-      )
+                  method: method.to_s.upcase,
+                  url: url,
+                  headers: sanitize_headers(headers),
+                  body: sanitize_body(body))
     end
 
     def log_response(response, duration)
       return unless logger
 
       logger.send(log_level, "API Response",
-        status: response.code,
-        duration_ms: (duration * 1000).round(2),
-        headers: response.headers,
-        body_size: response.body&.bytesize
-      )
+                  status: response.code,
+                  duration_ms: (duration * 1000).round(2),
+                  headers: response.headers,
+                  body_size: response.body&.bytesize)
     end
 
-    private
-
-    def sanitize_headers(headers)
+    private def sanitize_headers(headers)
       headers.transform_values do |value|
-        if value.include?('Bearer')
-          value.gsub(/Bearer\s+[\w\-]+/, 'Bearer [REDACTED]')
+        if value.include?("Bearer")
+          value.gsub(/Bearer\s+[\w\-]+/, "Bearer [REDACTED]")
         else
           value
         end
       end
     end
 
-    def sanitize_body(body)
+    private def sanitize_body(body)
       return nil unless body
-      
+
       if body.is_a?(String) && body.length > 1000
         "#{body[0..1000]}... (truncated)"
       else
@@ -107,4 +117,4 @@ module Attio
       end
     end
   end
-end
+end

data/lib/attio/resources/attributes.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
+
 module Attio
   module Resources
+    # API resource for managing Attio attributes
+    #
+    # Attributes define custom fields that can be added to objects
+    # and records in your Attio workspace.
+    #
+    # @example Listing attributes
+    #   client.attributes.list(object: "people")
     class Attributes < Base
       def list(object:, **params)
         validate_object!(object)
@@ -12,15 +21,13 @@ module Attio
         request(:get, "objects/#{object}/attributes/#{id_or_slug}")
       end
 
-      private
-
-      def validate_object!(object)
+      private def validate_object!(object)
         raise ArgumentError, "Object type is required" if object.nil? || object.to_s.strip.empty?
       end
 
-      def validate_id_or_slug!(id_or_slug)
+      private def validate_id_or_slug!(id_or_slug)
         raise ArgumentError, "Attribute ID or slug is required" if id_or_slug.nil? || id_or_slug.to_s.strip.empty?
       end
     end
   end
-end
+end

data/lib/attio/resources/base.rb

@@ -1,55 +1,94 @@
+# frozen_string_literal: true
+
+# Base class for all API resource classes.
+#
+# This class provides common functionality and request handling
+# for all Attio API resource implementations.
+#
+# @api private
+# @author Ernest Sim
+# @since 1.0.0
 module Attio
   module Resources
-    # Base class for all API resource classes.
-    # 
-    # This class provides common functionality and request handling
-    # for all Attio API resource implementations.
-    # 
-    # @api private
-    # @author Ernest Sim
-    # @since 1.0.0
     class Base
       # @return [Client] The API client instance
       attr_reader :client
 
       # Initialize a new resource instance.
-      # 
+      #
       # @param client [Client] The API client instance
       # @raise [ArgumentError] if client is nil
       def initialize(client)
         raise ArgumentError, "Client is required" unless client
+
         @client = client
       end
 
-      private
+      # 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 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 = {})
+        connection = client.connection
 
-      # Make an HTTP request to the API.
-      # 
-      # @param method [Symbol] The HTTP method (:get, :post, :patch, :put, :delete)
-      # @param path [String] The API endpoint path
-      # @param params [Hash] Request parameters (default: {})
-      # 
-      # @return [Hash] The API response
-      # @raise [ArgumentError] if method is unsupported
-      # 
-      # @api private
-      def request(method, path, params = {})
         case method
         when :get
-          client.connection.get(path, params)
+          handle_get_request(connection, path, params)
         when :post
-          client.connection.post(path, params)
+          connection.post(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_delete_request(connection, path, params)
+        params.empty? ? connection.delete(path) : connection.delete(path, params)
+      end
     end
   end
-end
+end

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

@@ -1,56 +1,53 @@
+# frozen_string_literal: true
+
 module Attio
   module Resources
+    # API resource for managing Attio lists and list entries
+    #
+    # Lists are custom collections for organizing records in your workspace.
+    #
+    # @example Listing all lists
+    #   client.lists.list
+    #
+    # @example Adding an entry to a list
+    #   client.lists.create_entry(id: "list_id", data: { record_id: "rec_123" })
     class Lists < Base
       def list(**params)
         request(:get, "lists", params)
       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
-
-      def validate_list_id!(list_id)
-        raise ArgumentError, "List ID is required" if list_id.nil? || list_id.to_s.strip.empty?
-      end
-
-      def validate_entry_id!(entry_id)
-        raise ArgumentError, "Entry ID is required" if entry_id.nil? || entry_id.to_s.strip.empty?
-      end
-
-      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
     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/objects.rb

@@ -1,5 +1,14 @@
+# frozen_string_literal: true
+
 module Attio
   module Resources
+    # API resource for managing Attio objects
+    #
+    # Objects define the schema and structure for different types of
+    # records in your Attio workspace (e.g., people, companies).
+    #
+    # @example Listing all objects
+    #   client.objects.list
     class Objects < Base
       def list(**params)
         request(:get, "objects", params)
@@ -10,11 +19,9 @@ module Attio
         request(:get, "objects/#{id_or_slug}")
       end
 
-      private
-
-      def validate_id_or_slug!(id_or_slug)
+      private def validate_id_or_slug!(id_or_slug)
         raise ArgumentError, "Object ID or slug is required" if id_or_slug.nil? || id_or_slug.to_s.strip.empty?
       end
     end
   end
-end
+end