attio 0.1.1 → 0.2.0

data/CONCEPTS.md

@@ -0,0 +1,428 @@
+# Attio Ruby Gem - Architectural Concepts
+
+This document explains the key architectural decisions, design patterns, and concepts behind the Attio Ruby gem implementation.
+
+## Table of Contents
+- [Overall Architecture](#overall-architecture)
+- [Template Method Pattern](#template-method-pattern-in-base-class)
+- [DELETE with Body Support](#delete-with-body-support)
+- [URL Encoding for Special Characters](#url-encoding-for-special-characters)
+- [Collaboration Features Workflow](#collaboration-features-workflow)
+- [Error Handling Strategy](#error-handling-strategy)
+- [Testing Strategy](#testing-strategy)
+- [Key Design Decisions](#key-design-decisions-explained)
+
+## Overall Architecture
+
+The Attio Ruby gem follows a modular resource-based architecture with a clear separation of concerns:
+
+```mermaid
+graph TD
+    Client[Attio::Client] --> HttpClient[HTTP Client Layer]
+    Client --> Resources[Resource Classes]
+    
+    Resources --> Base[Base Resource]
+    Resources --> Records[Records]
+    Resources --> Comments[Comments]
+    Resources --> Threads[Threads]
+    Resources --> Tasks[Tasks]
+    Resources --> Notes[Notes]
+    Resources --> Lists[Lists]
+    Resources --> Objects[Objects]
+    Resources --> Attributes[Attributes]
+    Resources --> Users[Users]
+    Resources --> Workspaces[Workspaces]
+    
+    Base --> Validations[Common Validations]
+    Base --> Request[Request Handler]
+    
+    HttpClient --> Typhoeus[Typhoeus HTTP]
+    HttpClient --> ErrorHandling[Error Handling]
+    HttpClient --> ConnectionPool[Connection Pooling]
+```
+
+### Key Components:
+- **Client**: Entry point that initializes all resources and manages configuration
+- **HttpClient**: Handles all HTTP communication, retries, and error responses
+- **Base Resource**: Provides common functionality to all resource classes
+- **Resource Classes**: Implement specific API endpoints for each Attio resource type
+
+## Template Method Pattern in Base Class
+
+We implemented the Template Method pattern to eliminate code duplication across resources:
+
+```mermaid
+classDiagram
+    class Base {
+        -connection
+        +request(method, path, params)
+        #validate_id!(id, resource_name)
+        #validate_required_string!(value, field_name)
+        #validate_required_hash!(value, field_name)
+        #handle_delete_request(connection, path, params)
+    }
+    
+    class Comments {
+        +list(params)
+        +create(data)
+        +react(id, emoji)
+        +unreact(id, emoji)
+    }
+    
+    class Threads {
+        +list(params)
+        +create(data)
+        +add_participant(id, member_id)
+        +remove_participant(id, member_id)
+        +close(id)
+        +reopen(id)
+    }
+    
+    class Tasks {
+        +list(params)
+        +create(data)
+        +complete(id, completed_at)
+        +uncomplete(id)
+    }
+    
+    Base <|-- Comments
+    Base <|-- Threads
+    Base <|-- Tasks
+    Base <|-- Notes
+    Base <|-- Records
+    Base <|-- Lists
+```
+
+### Benefits:
+- **Code Reuse**: ~150 lines of duplicated validation code eliminated
+- **Consistency**: Standardized error messages and validation logic
+- **Maintainability**: Changes to common functionality only need to be made once
+- **Extensibility**: New resources can easily inherit common behavior
+
+## DELETE with Body Support
+
+A key architectural decision for REST compliance when managing thread participants:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Threads
+    participant Base
+    participant HttpClient
+    participant API
+    
+    Client->>Threads: remove_participant(id, member_id)
+    Threads->>Threads: validate_id!(id)
+    Threads->>Threads: validate_required_string!(member_id)
+    Threads->>Base: request(:delete, path, params)
+    Base->>Base: handle_delete_request
+    Base->>HttpClient: delete(path, {member_id: ...})
+    HttpClient->>HttpClient: Check if params exist
+    alt Has Parameters
+        HttpClient->>API: DELETE with JSON body
+        Note over HttpClient,API: Content-Type: application/json
+    else No Parameters
+        HttpClient->>API: DELETE without body
+    end
+    API-->>HttpClient: 200 OK
+    HttpClient-->>Client: Response
+```
+
+### Implementation Details:
+```ruby
+# In HttpClient
+def delete(path, params = nil)
+  if params
+    execute_request(:delete, path, body: params.to_json)
+  else
+    execute_request(:delete, path)
+  end
+end
+
+# In Base
+private def handle_delete_request(connection, path, params)
+  params.empty? ? connection.delete(path) : connection.delete(path, params)
+end
+```
+
+## URL Encoding for Special Characters
+
+Critical for emoji reactions support and other special characters in URLs:
+
+```mermaid
+flowchart LR
+    Input["Emoji Input: 👍"] --> Validate[Validate Required String]
+    Validate --> Encode[CGI.escape emoji]
+    Encode --> Build[Build URL Path]
+    Build --> URL["comments/123/reactions/%F0%9F%91%8D"]
+    URL --> Request[HTTP DELETE Request]
+    Request --> API[Attio API]
+```
+
+### Example Implementation:
+```ruby
+def unreact(id:, emoji:)
+  validate_id!(id, "Comment")
+  validate_required_string!(emoji, "Emoji")
+  
+  # CGI.escape properly encodes the emoji for URL usage
+  request(:delete, "comments/#{id}/reactions/#{CGI.escape(emoji)}")
+end
+```
+
+### Why CGI.escape?
+- Properly handles UTF-8 characters like emojis
+- Converts special characters to percent-encoded format
+- Ensures URL compatibility across different systems
+- Standard Ruby library method, no additional dependencies
+
+## Collaboration Features Workflow
+
+The interconnected nature of collaboration resources in a CRM context:
+
+```mermaid
+graph TB
+    Record[Record<br/>Company/Person] --> Thread[Discussion Thread]
+    Record --> Task[Task]
+    Record --> Note[Note]
+    
+    Thread --> Comment[Comment]
+    Comment --> Reaction[Emoji Reaction]
+    Thread --> Participants[Thread Participants]
+    Thread --> Status[Thread Status<br/>Open/Closed]
+    
+    Task --> Assignment[Task Assignment]
+    Task --> DueDate[Due Date]
+    Task --> Completion[Completion Status]
+    
+    Note --> Title[Note Title]
+    Note --> Content[Rich Text Content]
+    Note --> Timestamps[Created/Updated]
+    
+    style Record fill:#f9f,stroke:#333,stroke-width:2px
+    style Thread fill:#bbf,stroke:#333,stroke-width:2px
+    style Task fill:#bfb,stroke:#333,stroke-width:2px
+    style Note fill:#ffb,stroke:#333,stroke-width:2px
+```
+
+### Resource Relationships:
+- **Records** (Companies/People) serve as parent objects for collaboration features
+- **Threads** enable team discussions with participant management
+- **Comments** support rich text and emoji reactions within threads
+- **Tasks** track actionable items with assignments and due dates
+- **Notes** capture meeting notes and important information
+
+## Error Handling Strategy
+
+Comprehensive error handling with specific exception types and retry logic:
+
+```mermaid
+flowchart TD
+    Request[API Request] --> Response{Response Status}
+    Response -->|200-299| Success[Parse & Return Data]
+    Response -->|400| Validation[ValidationError]
+    Response -->|401| Auth[AuthenticationError]
+    Response -->|404| NotFound[NotFoundError]
+    Response -->|429| RateLimit[RateLimitError]
+    Response -->|500+| Server[ServerError]
+    Response -->|Other| Generic[Attio::Error]
+    
+    Validation --> Details[Extract Error Details]
+    Auth --> Details
+    NotFound --> Details
+    RateLimit --> Details
+    Server --> Details
+    Generic --> Details
+    
+    Details --> Retry{Retryable?}
+    
+    Retry -->|Rate Limit| Backoff[Exponential Backoff]
+    Retry -->|Server Error| Backoff
+    Retry -->|No| Raise[Raise Exception]
+    
+    Backoff --> Wait[Wait Period]
+    Wait --> Request
+    
+    Raise --> Client[Client Handles Error]
+```
+
+### Error Classes:
+```ruby
+module Attio
+  class Error < StandardError; end
+  class ValidationError < Error; end
+  class AuthenticationError < Error; end
+  class NotFoundError < Error; end
+  class RateLimitError < Error; end
+  class ServerError < Error; end
+end
+```
+
+### Retry Logic:
+- **Rate Limits**: Automatic retry with exponential backoff
+- **Server Errors**: Configurable retry attempts (default: 3)
+- **Network Errors**: Automatic retry with connection pooling
+- **Client Errors**: No retry, immediate failure
+
+## Testing Strategy
+
+Our approach to achieving 100% test coverage with semantic correctness:
+
+```mermaid
+graph LR
+    Tests[Test Suite<br/>265 Tests] --> Unit[Unit Tests]
+    Tests --> Integration[Integration Mocks]
+    Tests --> Edge[Edge Cases]
+    
+    Unit --> Doubles[Instance Doubles<br/>Type Safety]
+    Unit --> Stubs[Method Stubs<br/>Behavior Verification]
+    Unit --> Assertions[Response Assertions]
+    
+    Integration --> HTTPMocks[HTTP Response Mocks]
+    Integration --> ErrorSim[Error Simulation]
+    Integration --> Params[Parameter Validation]
+    
+    Edge --> NilValues[Nil/Empty Values]
+    Edge --> Special[Special Characters]
+    Edge --> Boundary[Boundary Conditions]
+    
+    Coverage[SimpleCov] --> Report[100% Coverage<br/>376/376 Lines]
+    
+    style Tests fill:#9f9,stroke:#333,stroke-width:2px
+    style Report fill:#9f9,stroke:#333,stroke-width:2px
+```
+
+### Testing Principles:
+1. **Instance Doubles**: Use RSpec's `instance_double` for type safety
+2. **Semantic Correctness**: Ensure mocks match actual implementation behavior
+3. **Edge Case Coverage**: Test nil values, empty strings, special characters
+4. **Error Simulation**: Test all error paths and exception handling
+5. **Parameter Validation**: Verify both required and optional parameters
+
+### Example Test Pattern:
+```ruby
+RSpec.describe Attio::Resources::Comments do
+  let(:connection) { instance_double(Attio::HttpClient) }
+  let(:comments) { described_class.new(connection) }
+  
+  describe "#unreact" do
+    it "properly encodes emoji in URL" do
+      expect(connection).to receive(:delete)
+        .with("comments/123/reactions/%F0%9F%91%8D")
+        .and_return({ "success" => true })
+      
+      comments.unreact(id: "123", emoji: "👍")
+    end
+  end
+end
+```
+
+## Key Design Decisions Explained
+
+### 1. Base Class Extraction
+**Problem**: Massive code duplication across resource classes (~150 lines per resource)
+
+**Solution**: Extract common validation and request handling into Base class
+
+**Benefits**:
+- Reduced codebase by ~1,500 lines
+- Standardized error messages
+- Single source of truth for validations
+- Easier to add new resources
+
+### 2. DELETE with Body Support
+**Problem**: Thread participant management requires sending data with DELETE requests
+
+**Solution**: Modified HttpClient to optionally accept body parameters for DELETE
+
+**Benefits**:
+- REST-compliant participant removal
+- Consistent with other HTTP methods
+- Clean API interface
+
+### 3. URL Encoding Strategy
+**Problem**: Special characters (emojis) in URL paths causing API errors
+
+**Solution**: Use `CGI.escape` for proper URL encoding
+
+**Benefits**:
+- Full Unicode support
+- Standard library solution
+- Cross-platform compatibility
+
+### 4. Keyword Arguments Correction
+**Problem**: Test mocks used keyword arguments but implementation used positional arguments
+
+**Solution**: Corrected all test mocks to use hash as second positional argument
+
+**Example**:
+```ruby
+# Before (incorrect)
+expect(connection).to receive(:get).with("comments", thread_id: "123")
+
+# After (correct)
+expect(connection).to receive(:get).with("comments", { thread_id: "123" })
+```
+
+### 5. Resource Modularity
+**Problem**: Need to support diverse Attio API resources with different requirements
+
+**Solution**: Each resource is self-contained with specific validations while inheriting common functionality
+
+**Benefits**:
+- Clear separation of concerns
+- Easy to understand each resource
+- Simple to add new endpoints
+- Maintainable and testable
+
+### 6. Comprehensive Error Handling
+**Problem**: Need to handle various API error conditions gracefully
+
+**Solution**: Specific error classes with detailed messages and retry logic
+
+**Benefits**:
+- Clear error messages for debugging
+- Automatic retry for transient failures
+- Proper error propagation to client code
+
+## Performance Considerations
+
+### Connection Pooling
+- Reuses HTTP connections for better performance
+- Configurable pool size based on usage patterns
+- Automatic connection management
+
+### Request Optimization
+- Batch operations where supported by API
+- Efficient parameter serialization
+- Minimal memory footprint
+
+### Caching Strategy
+- Response caching for read-heavy operations (future enhancement)
+- ETag support for conditional requests (future enhancement)
+
+## Future Enhancements
+
+### Planned Improvements
+1. **Webhook Support**: Handle Attio webhook events
+2. **Bulk Operations**: Batch create/update for better performance
+3. **Async Operations**: Non-blocking API calls for long-running operations
+4. **Response Caching**: Intelligent caching with cache invalidation
+5. **Rate Limit Management**: Proactive rate limit handling with queuing
+
+### API Coverage Expansion
+- Custom field types support
+- Advanced query builders
+- Webhook event processing
+- Real-time subscriptions
+
+## Conclusion
+
+The Attio Ruby gem architecture prioritizes:
+- **Maintainability**: Clean, DRY code with clear separation of concerns
+- **Reliability**: Comprehensive error handling and retry logic
+- **Usability**: Intuitive API matching Ruby conventions
+- **Testability**: 100% test coverage with semantic correctness
+- **Extensibility**: Easy to add new features and resources
+
+This architecture provides a solid foundation for building CRM integrations with Attio while maintaining code quality and developer experience.

data/CONTRIBUTING.md

@@ -19,17 +19,17 @@ Thank you for your interest in contributing to the Attio Ruby client! This guide
 1. Fork the repository on GitHub
 2. Clone your fork locally:
    ```bash
-   git clone https://github.com/YOUR_USERNAME/attio-ruby.git
-   cd attio-ruby
+   git clone https://github.com/YOUR_USERNAME/attio.git
+   cd attio
    ```
 3. Add the upstream remote:
    ```bash
-   git remote add upstream https://github.com/idl3/attio-ruby.git
+   git remote add upstream https://github.com/idl3/attio.git
    ```
 
 ## Development Setup
 
-1. Install Ruby 3.0 or higher
+1. Install Ruby 3.0 or higher (tested with Ruby 3.0 - 3.4)
 2. Install dependencies:
    ```bash
    bundle install

data/Gemfile

@@ -1,17 +1,20 @@
+# frozen_string_literal: true
+
 source "https://rubygems.org"
 
 # Specify your gem's dependencies in attio.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
 gem "logger" # Required for Ruby 3.5.0+ compatibility
+gem "rake", "~> 13.0"
 
 group :development, :test do
+  gem "pry", "~> 0.14"
   gem "rspec", "~> 3.12"
-  gem "webmock", "~> 3.18"
-  gem "simplecov", "~> 0.22"
-  gem "simplecov-console", "~> 0.9"
   gem "rubocop", "~> 1.50"
   gem "rubocop-rspec", "~> 2.19"
-  gem "pry", "~> 0.14"
+  gem "simplecov", "~> 0.22"
+  gem "simplecov-console", "~> 0.9"
+  gem "webmock", "~> 3.18"
+  gem "yard", "~> 0.9"
 end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    attio (0.1.0)
+    attio (0.2.0)
       typhoeus (~> 1.4)
 
 GEM
@@ -20,8 +20,8 @@ GEM
     docile (1.4.1)
     ethon (0.16.0)
       ffi (>= 1.15.0)
-    ffi (1.17.2)
     ffi (1.17.2-arm64-darwin)
+    ffi (1.17.2-x86_64-linux-gnu)
     hashdiff (1.2.0)
     json (2.13.2)
     language_server-protocol (3.17.0.5)
@@ -108,7 +108,7 @@ GEM
 
 PLATFORMS
   arm64-darwin-24
-  ruby
+  x86_64-linux
 
 DEPENDENCIES
   attio!
@@ -124,4 +124,4 @@ DEPENDENCIES
   yard (~> 0.9)
 
 BUNDLED WITH
-   2.7.1
+   2.4.22

data/README.md

@@ -1,10 +1,18 @@
 # Attio Ruby Client
 
+[![Tests](https://github.com/idl3/attio/actions/workflows/tests.yml/badge.svg)](https://github.com/idl3/attio/actions/workflows/tests.yml)
+[![Test Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/idl3/attio/tree/master/spec)
 [![Documentation](https://img.shields.io/badge/docs-yard-blue.svg)](https://idl3.github.io/attio)
 [![Gem Version](https://badge.fury.io/rb/attio.svg)](https://badge.fury.io/rb/attio)
+[![RSpec](https://img.shields.io/badge/RSpec-265_tests-green.svg)](https://github.com/idl3/attio/tree/master/spec)
 
 Ruby client for the [Attio CRM API](https://developers.attio.com/). This library provides easy access to the Attio API, allowing you to manage records, objects, lists, and more.
 
+## Requirements
+
+- Ruby 3.0 or higher (tested with Ruby 3.0, 3.1, 3.2, 3.3, and 3.4)
+- Bundler
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -146,6 +154,156 @@ client.records.update(
 
 ### Working with Other Resources
 
+#### Comments
+
+```ruby
+# List comments on a record
+comments = client.comments.list(
+  parent_object: 'people',
+  parent_record_id: 'person-123'
+)
+
+# List comments in a thread
+thread_comments = client.comments.list(thread_id: 'thread-456')
+
+# Create a comment on a record
+comment = client.comments.create(
+  parent_object: 'people',
+  parent_record_id: 'person-123',
+  content: 'This is a comment with **markdown** support!'
+)
+
+# Create a comment in a thread
+thread_comment = client.comments.create(
+  thread_id: 'thread-456',
+  content: 'Following up on this discussion'
+)
+
+# Update a comment
+updated_comment = client.comments.update(
+  id: 'comment-123',
+  content: 'Updated comment content'
+)
+
+# React to a comment
+client.comments.react(id: 'comment-123', emoji: '👍')
+
+# Remove reaction
+client.comments.unreact(id: 'comment-123', emoji: '👍')
+
+# Delete a comment
+client.comments.delete(id: 'comment-123')
+```
+
+#### Threads
+
+```ruby
+# List threads on a record
+threads = client.threads.list(
+  parent_object: 'companies',
+  parent_record_id: 'company-123'
+)
+
+# Get a thread with comments
+thread = client.threads.get(id: 'thread-123', include_comments: true)
+
+# Create a thread
+thread = client.threads.create(
+  parent_object: 'companies',
+  parent_record_id: 'company-123',
+  title: 'Q4 Planning Discussion',
+  description: 'Thread for Q4 planning discussions',
+  participant_ids: ['user-1', 'user-2']
+)
+
+# Update thread title
+client.threads.update(id: 'thread-123', title: 'Updated Q4 Planning')
+
+# Manage participants
+client.threads.add_participants(id: 'thread-123', user_ids: ['user-3', 'user-4'])
+client.threads.remove_participants(id: 'thread-123', user_ids: ['user-2'])
+
+# Close and reopen threads
+client.threads.close(id: 'thread-123')
+client.threads.reopen(id: 'thread-123')
+
+# Delete a thread
+client.threads.delete(id: 'thread-123')
+```
+
+#### Tasks
+
+```ruby
+# List all tasks
+tasks = client.tasks.list
+
+# List tasks with filters
+my_tasks = client.tasks.list(
+  assignee_id: 'user-123',
+  status: 'pending'
+)
+
+# Get a specific task
+task = client.tasks.get(id: 'task-123')
+
+# Create a task
+task = client.tasks.create(
+  parent_object: 'people',
+  parent_record_id: 'person-123',
+  title: 'Follow up with customer',
+  due_date: '2025-02-01',
+  assignee_id: 'user-456'
+)
+
+# Update a task
+client.tasks.update(
+  id: 'task-123',
+  title: 'Updated task title',
+  status: 'in_progress'
+)
+
+# Complete a task
+client.tasks.complete(id: 'task-123', completed_at: Time.now.iso8601)
+
+# Reopen a task
+client.tasks.reopen(id: 'task-123')
+
+# Delete a task
+client.tasks.delete(id: 'task-123')
+```
+
+#### Notes
+
+```ruby
+# List notes on a record
+notes = client.notes.list(
+  parent_object: 'companies',
+  parent_record_id: 'company-123'
+)
+
+# Get a specific note
+note = client.notes.get(id: 'note-123')
+
+# Create a note
+note = client.notes.create(
+  parent_object: 'companies',
+  parent_record_id: 'company-123',
+  title: 'Meeting Notes - Q4 Planning',
+  content: 'Discussed roadmap and resource allocation...',
+  tags: ['important', 'quarterly-planning']
+)
+
+# Update a note
+client.notes.update(
+  id: 'note-123',
+  title: 'Updated Meeting Notes',
+  content: 'Added action items from discussion'
+)
+
+# Delete a note
+client.notes.delete(id: 'note-123')
+```
+
 #### Objects
 
 ```ruby
@@ -232,12 +390,16 @@ end
 
 This client supports all major Attio API endpoints:
 
-- ✅ Records (CRUD operations, querying)
+- ✅ Records (CRUD operations, querying with filters and sorting)
 - ✅ Objects (list, get schema)
-- ✅ Lists (list, get entries)
+- ✅ Lists (list, get entries, manage list entries)
 - ✅ Workspaces (list, get current)
 - ✅ Attributes (list, create, update)
 - ✅ Users (list, get current user)
+- ✅ Comments (CRUD operations, reactions on records and threads)
+- ✅ Threads (CRUD operations, participant management, status control)
+- ✅ Tasks (CRUD operations, assignment, completion tracking)
+- ✅ Notes (CRUD operations on records)
 
 ## Development