attio 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c28065cbac5cffee49ef7864e60d19543ab116ef2bea68374ec2b995476efbd9
-  data.tar.gz: 31036f5bd6d0fd23b827176fe6a52f620d17042fe1bc6d55f2c5f86bb03a09c5
+  metadata.gz: f2af7d69dcfda391c606d9d55ea6acfa950a2bce2271d6f867acdfa9b40ce269
+  data.tar.gz: f8387f9aaf8779af723ebe6a30279a0a8affb639e27aad4089f8353a3687f14a
 SHA512:
-  metadata.gz: e0a5e5fb4654d9bbb579babffde8540d6bbd3dc0b1463a22eb8838c42095e8e368fbe3f712a6e85a49bfdaf8d3adeb2386769591c36ebf0bb035b22bdeb407c6
-  data.tar.gz: fe5085f5f9b20e688ff8f4c7e21f42482432c911fe135f9df5f4acab92e101585c5b5d719f78d8fd349e020e038a0f8fd3d144e80816eeabe1b78b25570e7e1d
+  metadata.gz: 11fbb524075e860b1c28e01f11b67ae6c28719f4e54a904fe026feabfd41f3f81ed9fe94b13a32228eb377f7125226fca92eb4cb031b260d283d3a03f67c0c8b
+  data.tar.gz: 4f813c14359415e5ca478ca429e7624798f778d040e2d317a50a4538cc4feffdea0b5b65e9cbe7c98a76a1124cd600bbf5914e0f365bde3dfbd514d6ec0b7414

data/.github/workflows/release.yml

@@ -114,48 +114,4 @@ jobs:
         upload_url: ${{ steps.create_release.outputs.upload_url }}
         asset_path: ${{ env.GEM_FILE }}
         asset_name: ${{ env.GEM_FILE }}
-        asset_content_type: application/x-tar
-
-  update-docs:
-    needs: [test, build-and-publish]
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        token: ${{ secrets.GITHUB_TOKEN }}
-        ref: main
-
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: '3.4'
-        bundler-cache: false
-    
-    - name: Install dependencies
-      run: |
-        gem install bundler -v 2.4.22
-        bundle config set --local deployment false
-        bundle install
-
-    - name: Extract version from tag
-      id: version
-      run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
-
-    - name: Generate documentation
-      run: |
-        bundle exec rake docs:generate
-
-    - name: Commit and push documentation
-      run: |
-        git config --local user.email "action@github.com"
-        git config --local user.name "GitHub Action"
-        git add docs/
-        if ! git diff --staged --quiet; then
-          git commit -m "Update documentation for release ${{ steps.version.outputs.version }}"
-          git push
-        else
-          echo "No documentation changes to commit"
-        fi
+        asset_content_type: application/x-tar

data/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2025-08-11
+
+### Added
+- **Workspace Members** resource for managing workspace access and permissions
+- **Deals** resource for sales pipeline management with win/loss tracking
+- **Meta API** resource for workspace identification and usage statistics
+- **Bulk Operations** with automatic batching (100 records per batch)
+- **Rate Limiting** with exponential backoff and request queuing
+- **SSL/TLS verification** for enhanced security
+- **Enhanced error classes** with proper attributes (retry_after for RateLimitError)
+- **Thread-safe rate limiter** implementation
+- Comprehensive architectural documentation in CONCEPTS.md
+- Development guidelines in CLAUDE.md
+- 116 new tests (392 total, up from 265)
+
+### Improved
+- **Security**: Added explicit SSL verification and disabled automatic redirects
+- **Thread Safety**: Fixed race conditions in rate limiter
+- **Code Quality**: Achieved 0 RuboCop violations (previously 6)
+- **Test Coverage**: 99.86% (718/719 lines)
+- **Performance**: Optimized bulk operations with efficient batching
+- **Validation**: Enhanced input validation to prevent injection attacks
+- **Documentation**: Updated README with comprehensive API coverage
+
+### Fixed
+- Thread safety issues in RateLimiter#update_from_headers
+- Complex validation methods refactored to reduce cyclomatic complexity
+- validate_required_hash now properly handles nil values
+- Removed unused api_key parameter from Meta#validate_key
+- Fixed conditional validation in Deals#create
+
+### Changed
+- **BREAKING**: Error messages for nil validation now say "must be a hash" instead of "is required"
+- RateLimitMiddleware simplified to avoid private method calls
+- Base resource class validation methods extracted for reusability
+
 ## [0.2.0] - 2025-08-11
 
 ### Added

data/CLAUDE.md

@@ -0,0 +1,360 @@
+# Claude Development Guidelines for Attio Ruby Gem
+
+This document contains important guidelines for Claude (or any AI assistant) when working on the Attio Ruby gem. Following these guidelines ensures high-quality, consistent, and production-ready code.
+
+## Pre-Release Checklist
+
+**IMPORTANT**: Before creating any release tag or pushing to master, ALWAYS complete this checklist:
+
+### 1. Code Quality
+- [ ] Run RuboCop and fix all violations: `bundle exec rubocop -A`
+- [ ] Ensure no RuboCop offenses remain
+- [ ] Run all tests: `bundle exec rspec`
+- [ ] Verify 100% test coverage: Check SimpleCov output
+- [ ] Update version in `lib/attio/version.rb`
+- [ ] Update CHANGELOG.md with release date
+
+### 2. Testing Commands
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests with coverage report
+COVERAGE=true bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/attio/resources/comments_spec.rb
+
+# Run RuboCop
+bundle exec rubocop
+
+# Auto-fix RuboCop violations
+bundle exec rubocop -A
+
+# Check for outdated gems
+bundle outdated
+```
+
+### 3. Documentation
+- [ ] Update README.md with new features
+- [ ] Add/update YARD documentation for new methods
+- [ ] Create example files for new features
+- [ ] Update API coverage section in README
+- [ ] Ensure all public methods have proper documentation
+
+### 4. Git Commit Standards
+
+#### Commit Message Format
+```
+<type>: <subject>
+
+<body>
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+#### Commit Types
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only changes
+- `style`: Code style changes (formatting, missing semi-colons, etc)
+- `refactor`: Code refactoring
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+- `ci`: CI/CD changes
+
+#### Examples
+```bash
+git commit -m "feat: Add Comments resource with emoji reactions
+
+- Implement full CRUD operations for comments
+- Add support for emoji reactions with proper URL encoding
+- Include comprehensive test coverage
+
+🤖 Generated with [Claude Code](https://claude.ai/code)
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+## Development Guidelines
+
+### 1. Test-Driven Development (TDD)
+- Write tests FIRST before implementing features
+- Ensure semantic correctness in all tests
+- Use `instance_double` for type safety in RSpec
+- Mock external API calls appropriately
+- Achieve and maintain 100% test coverage
+
+### 2. Code Organization
+```
+lib/attio/
+├── resources/
+│   ├── base.rb          # Base class with common functionality
+│   ├── comments.rb      # Resource-specific implementation
+│   └── ...
+├── client.rb            # Main client class
+├── http_client.rb       # HTTP handling
+├── errors.rb           # Error classes
+└── version.rb          # Version constant
+
+spec/attio/
+├── resources/          # Resource-specific tests
+├── client_spec.rb      # Client tests
+└── http_client_spec.rb # HTTP client tests
+```
+
+### 3. Resource Implementation Pattern
+
+When implementing a new resource:
+
+```ruby
+# lib/attio/resources/new_resource.rb
+module Attio
+  module Resources
+    class NewResource < Base
+      def list(params = {})
+        # Implementation
+      end
+
+      def get(id:)
+        validate_id!(id, "NewResource")
+        # Implementation
+      end
+
+      def create(data:)
+        validate_required_hash!(data, "Data")
+        # Implementation
+      end
+
+      def update(id:, data:)
+        validate_id!(id, "NewResource")
+        validate_required_hash!(data, "Data")
+        # Implementation
+      end
+
+      def delete(id:)
+        validate_id!(id, "NewResource")
+        # Implementation
+      end
+    end
+  end
+end
+```
+
+### 4. Testing Pattern
+
+```ruby
+# spec/attio/resources/new_resource_spec.rb
+RSpec.describe Attio::Resources::NewResource do
+  let(:connection) { instance_double(Attio::HttpClient) }
+  let(:resource) { described_class.new(connection) }
+
+  describe "#list" do
+    it "lists all resources" do
+      expect(connection).to receive(:get)
+        .with("new_resources", {})
+        .and_return({ "data" => [] })
+      
+      result = resource.list
+      expect(result).to eq({ "data" => [] })
+    end
+  end
+
+  # Test all methods with edge cases
+end
+```
+
+### 5. Error Handling
+- Always validate required parameters
+- Use specific error classes (ValidationError, NotFoundError, etc.)
+- Provide clear, actionable error messages
+- Include parameter names in error messages
+
+### 6. API Design Principles
+- Use keyword arguments for clarity
+- Support optional parameters with defaults
+- Return full API response (don't extract data)
+- Maintain consistency across all resources
+
+## Common Pitfalls to Avoid
+
+### 1. Test Mocks
+```ruby
+# WRONG - Using keyword arguments in mock
+expect(connection).to receive(:get).with("comments", thread_id: "123")
+
+# CORRECT - Using hash as second argument
+expect(connection).to receive(:get).with("comments", { thread_id: "123" })
+```
+
+### 2. URL Encoding
+```ruby
+# WRONG - Direct string interpolation
+"comments/#{id}/reactions/#{emoji}"
+
+# CORRECT - Proper encoding for special characters
+"comments/#{id}/reactions/#{CGI.escape(emoji)}"
+```
+
+### 3. Validation
+```ruby
+# WRONG - No validation
+def get(id:)
+  request(:get, "resources/#{id}")
+end
+
+# CORRECT - Validate required parameters
+def get(id:)
+  validate_id!(id, "Resource")
+  request(:get, "resources/#{id}")
+end
+```
+
+## Release Process
+
+### 1. Pre-Release
+```bash
+# 1. Ensure all tests pass
+bundle exec rspec
+
+# 2. Check RuboCop
+bundle exec rubocop
+
+# 3. Update version
+# Edit lib/attio/version.rb
+
+# 4. Update CHANGELOG
+# Add release section with date
+
+# 5. Commit changes
+git add -A
+git commit -m "chore: Prepare release v0.2.0"
+```
+
+### 2. Create Release
+```bash
+# 1. Push to master
+git push origin master
+
+# 2. Create and push tag
+git tag -a v0.2.0 -m "Release v0.2.0"
+git push origin v0.2.0
+```
+
+### 3. Post-Release
+The CI/CD pipeline will automatically:
+- Run tests across Ruby 3.0-3.4
+- Build the gem
+- Publish to RubyGems (requires RUBYGEMS_AUTH_TOKEN secret)
+- Create GitHub release
+
+## RuboCop Configuration
+
+Key rules enforced:
+- Line length: 120 characters
+- Method length: 20 lines
+- Class length: 250 lines
+- Cyclomatic complexity: 10
+- ABC metric: 17
+- Use `dig` for nested hash access (except single argument)
+- Prefer string interpolation over concatenation
+- Use single quotes unless interpolation needed
+
+## Environment Setup
+
+### Ruby Version
+- Minimum: Ruby 3.0
+- Recommended: Ruby 3.4
+- CI tests on: 3.0, 3.1, 3.2, 3.3, 3.4
+
+### Bundler Version
+- Use bundler 2.4.22 for compatibility
+- Set in CI: `gem install bundler -v 2.4.22`
+
+### Development Dependencies
+```ruby
+# Gemfile
+group :development, :test do
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.50"
+  gem "rubocop-rspec", "~> 2.22"
+  gem "simplecov", "~> 0.22"
+  gem "webmock", "~> 3.18"
+  gem "yard", "~> 0.9"
+end
+```
+
+## API Coverage Tracking
+
+Maintain this list in README.md:
+
+- [x] Records - Full CRUD
+- [x] Objects - List, Get
+- [x] Lists - List, Get, Entries, Create/Delete Entry
+- [x] Comments - Full CRUD, Reactions
+- [x] Threads - Full CRUD, Participants, Status
+- [x] Tasks - Full CRUD, Assignment, Completion
+- [x] Notes - Full CRUD
+- [x] Workspaces - List, Get
+- [x] Attributes - List, Create, Update
+- [x] Users - List, Get
+
+## Quality Metrics to Maintain
+
+- **Test Coverage**: 100%
+- **Test Count**: 265+ tests
+- **RuboCop Offenses**: 0
+- **Documentation Coverage**: 100% for public methods
+- **Example Coverage**: Example for each major feature
+
+## Final Reminders
+
+1. **NEVER** push code with failing tests
+2. **NEVER** push code with RuboCop violations
+3. **ALWAYS** update documentation with new features
+4. **ALWAYS** maintain 100% test coverage
+5. **ALWAYS** run the full test suite before committing
+6. **ALWAYS** update the version and CHANGELOG for releases
+7. **NEVER** create git commits without the co-author attribution
+
+## Useful Commands Reference
+
+```bash
+# Build gem locally
+gem build attio.gemspec
+
+# Install gem locally
+gem install ./attio-0.2.0.gem
+
+# Test gem in IRB
+irb -r attio
+
+# Generate YARD documentation
+bundle exec yard doc
+
+# View YARD documentation
+bundle exec yard server
+
+# Run specific test with line number
+bundle exec rspec spec/attio/resources/comments_spec.rb:42
+
+# Check test coverage details
+open coverage/index.html
+
+# List all rake tasks
+bundle exec rake -T
+```
+
+## Contact for Issues
+
+If you encounter any issues or need clarification:
+1. Check existing issues on GitHub
+2. Review test files for usage examples
+3. Consult the API documentation
+4. Create a detailed issue with reproduction steps
+
+---
+
+**Remember**: Quality over speed. It's better to take time and deliver production-ready code than to rush and create technical debt.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    attio (0.2.0)
+    attio (0.3.0)
       typhoeus (~> 1.4)
 
 GEM

data/README.md

@@ -4,7 +4,7 @@
 [![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)
+[![RSpec](https://img.shields.io/badge/RSpec-392_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.
 
@@ -361,6 +361,137 @@ users = client.users.list
 user = client.users.me
 ```
 
+### Advanced Features
+
+#### Workspace Members
+
+```ruby
+# List workspace members
+members = client.workspace_members.list
+
+# Invite a new member
+invitation = client.workspace_members.invite(
+  email: 'new.member@example.com',
+  role: 'member'  # admin, member, or guest
+)
+
+# Update member permissions
+client.workspace_members.update(
+  member_id: 'user-123',
+  data: { role: 'admin' }
+)
+
+# Remove a member
+client.workspace_members.remove(member_id: 'user-123')
+```
+
+#### Deals
+
+```ruby
+# List all deals
+deals = client.deals.list
+
+# Create a new deal
+deal = client.deals.create(
+  data: {
+    name: 'Enterprise Contract',
+    value: 50000,
+    stage_id: 'stage-negotiation',
+    company_id: 'company-123'
+  }
+)
+
+# Update deal stage
+client.deals.update_stage(id: 'deal-123', stage_id: 'stage-won')
+
+# Mark deal as won/lost
+client.deals.mark_won(id: 'deal-123', won_date: Date.today)
+client.deals.mark_lost(id: 'deal-123', lost_reason: 'Budget constraints')
+
+# List deals by various criteria
+pipeline_deals = client.deals.list_by_stage(stage_id: 'stage-proposal')
+company_deals = client.deals.list_by_company(company_id: 'company-123')
+my_deals = client.deals.list_by_owner(owner_id: 'user-456')
+```
+
+#### Bulk Operations
+
+```ruby
+# Bulk create records
+results = client.bulk.create_records(
+  object: 'people',
+  records: [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Smith', email: 'jane@example.com' },
+    # ... up to 100 records per batch
+  ]
+)
+
+# Bulk update records
+results = client.bulk.update_records(
+  object: 'companies',
+  updates: [
+    { id: 'company-1', data: { status: 'active' } },
+    { id: 'company-2', data: { status: 'inactive' } }
+  ]
+)
+
+# Bulk upsert (create or update based on matching)
+results = client.bulk.upsert_records(
+  object: 'people',
+  match_attribute: 'email',
+  records: [
+    { email: 'john@example.com', name: 'John Updated' },
+    { email: 'new@example.com', name: 'New Person' }
+  ]
+)
+```
+
+#### Rate Limiting
+
+```ruby
+# Initialize client with custom rate limiter
+limiter = Attio::RateLimiter.new(
+  max_requests: 100,
+  window_seconds: 60,
+  max_retries: 3
+)
+client.rate_limiter = limiter
+
+# Execute with rate limiting
+limiter.execute { client.records.list(object: 'people') }
+
+# Queue requests for later processing
+limiter.queue_request(priority: 1) { important_operation }
+limiter.queue_request(priority: 5) { less_important_operation }
+
+# Process queued requests
+results = limiter.process_queue(max_per_batch: 10)
+
+# Check rate limit status
+status = limiter.status
+puts "Remaining: #{status[:remaining]}/#{status[:limit]}"
+```
+
+#### Meta API
+
+```ruby
+# Identify current workspace and user
+info = client.meta.identify
+puts "Workspace: #{info['workspace']['name']}"
+puts "User: #{info['user']['email']}"
+
+# Validate API key
+validation = client.meta.validate_key
+puts "Valid: #{validation['valid']}"
+puts "Permissions: #{validation['permissions']}"
+
+# Get usage statistics
+usage = client.meta.usage_stats
+puts "Records: #{usage['records']['total']}"
+puts "API calls today: #{usage['api_calls']['today']}"
+```
+
 ### Error Handling
 
 The client will raise appropriate exceptions for different error conditions:
@@ -390,16 +521,28 @@ end
 
 This client supports all major Attio API endpoints:
 
-- ✅ Records (CRUD operations, querying with filters and sorting)
-- ✅ Objects (list, get schema)
-- ✅ 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)
+### Core Resources
+- ✅ **Records** - Full CRUD operations, querying with filters and sorting
+- ✅ **Objects** - List, get schema information
+- ✅ **Lists** - List, get entries, manage list entries
+- ✅ **Attributes** - List, create, update custom attributes
+- ✅ **Workspaces** - List, get current workspace
+- ✅ **Users** - List, get current user
+
+### Collaboration Features
+- ✅ **Comments** - CRUD operations, emoji reactions on records and threads
+- ✅ **Threads** - CRUD operations, participant management, status control
+- ✅ **Tasks** - CRUD operations, assignment, completion tracking
+- ✅ **Notes** - CRUD operations on records
+
+### Sales & CRM
+- ✅ **Deals** - Pipeline management, stage tracking, win/loss tracking
+- ✅ **Workspace Members** - Member management, invitations, permissions
+
+### Advanced Features
+- ✅ **Bulk Operations** - Batch create/update/delete with automatic batching
+- ✅ **Rate Limiting** - Intelligent retry with exponential backoff and request queuing
+- ✅ **Meta API** - Identify workspace, validate API keys, get usage stats
 
 ## Development