attio 0.1.1 → 0.1.3

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,39 +1,30 @@
+# 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
-
-      # 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 = {})
+      private def request(method, path, params = {})
         case method
         when :get
           client.connection.get(path, params)
@@ -49,7 +40,6 @@ module Attio
           raise ArgumentError, "Unsupported HTTP method: #{method}"
         end
       end
-
     end
   end
-end
+end

data/lib/attio/resources/lists.rb

@@ -1,5 +1,16 @@
+# 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)
@@ -33,24 +44,22 @@ module Attio
         request(:delete, "lists/#{list_id}/entries/#{entry_id}")
       end
 
-      private
-
-      def validate_id!(id)
+      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)
+      private 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)
+      private 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_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/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

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',
@@ -48,13 +50,13 @@ module Attio
       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:)
@@ -64,13 +66,13 @@ module Attio
       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',
@@ -87,14 +89,14 @@ module Attio
       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',
@@ -109,13 +111,13 @@ module Attio
       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:)
@@ -124,35 +126,28 @@ module Attio
         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)
+      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)
+      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_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/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.1.3"
 end

data/lib/attio.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "typhoeus"
 
 require "attio/version"
@@ -14,32 +16,32 @@ require "attio/resources/attributes"
 require "attio/resources/users"
 
 # 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 +49,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:)