attio 0.1.3 → 0.3.0

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-147_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.
 
@@ -154,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
@@ -211,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:
@@ -240,12 +521,28 @@ end
 
 This client supports all major Attio API endpoints:
 
-- ✅ Records (CRUD operations, querying)
-- ✅ Objects (list, get schema)
-- ✅ Lists (list, get entries)
-- ✅ Workspaces (list, get current)
-- ✅ Attributes (list, create, update)
-- ✅ Users (list, get current user)
+### 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
 

data/examples/advanced_filtering.rb

@@ -0,0 +1,178 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "attio"
+require "json"
+
+# Example: Advanced Filtering and Querying
+#
+# This example demonstrates how to use advanced filtering and sorting
+# capabilities when querying records in Attio.
+
+# Initialize the client
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "Attio Advanced Filtering Example"
+puts "=" * 40
+
+# 1. Query with simple filters
+puts "\n1. Finding people by email domain..."
+people_from_domain = client.records.list(
+  object: "people",
+  filters: {
+    email: { contains: "@example.com" },
+  },
+  limit: 10
+)
+puts "   Found #{people_from_domain['data']&.length || 0} people from example.com"
+
+# 2. Query with multiple filters (AND condition)
+puts "\n2. Finding high-value companies in technology sector..."
+high_value_tech = client.records.list(
+  object: "companies",
+  filters: {
+    industry: { equals: "Technology" },
+    annual_revenue: { greater_than: 1_000_000 },
+  },
+  sorts: [
+    { field: "annual_revenue", direction: "desc" },
+  ],
+  limit: 5
+)
+puts "   Found #{high_value_tech['data']&.length || 0} high-value tech companies"
+
+# 3. Query with date range filters
+puts "\n3. Finding recently created records..."
+recent_date = (Date.today - 30).iso8601
+recent_records = client.records.list(
+  object: "people",
+  filters: {
+    created_at: { greater_than: recent_date },
+  },
+  sorts: [
+    { field: "created_at", direction: "desc" },
+  ]
+)
+puts "   Found #{recent_records['data']&.length || 0} people created in last 30 days"
+
+# 4. Query with relationship filters
+puts "\n4. Finding people associated with specific companies..."
+# First, get a company
+companies = client.records.list(object: "companies", limit: 1)
+if companies.dig("data", 0)
+  company_id = companies.dig("data", 0, "id", "record_id")
+
+  people_at_company = client.records.list(
+    object: "people",
+    filters: {
+      company: {
+        target_object: "companies",
+        target_record_id: company_id,
+      },
+    }
+  )
+  puts "   Found #{people_at_company['data']&.length || 0} people at the company"
+else
+  puts "   No companies found for demo"
+end
+
+# 5. Query with null/not null filters
+puts "\n5. Finding records with missing data..."
+missing_email = client.records.list(
+  object: "people",
+  filters: {
+    email: { is_null: true },
+  },
+  limit: 10
+)
+puts "   Found #{missing_email['data']&.length || 0} people without email addresses"
+
+# 6. Complex sorting with multiple fields
+puts "\n6. Sorting by multiple criteria..."
+sorted_companies = client.records.list(
+  object: "companies",
+  sorts: [
+    { field: "industry", direction: "asc" },
+    { field: "annual_revenue", direction: "desc" },
+    { field: "name", direction: "asc" },
+  ],
+  limit: 20
+)
+puts "   Retrieved #{sorted_companies['data']&.length || 0} companies sorted by industry, revenue, and name"
+
+# 7. Pagination example
+puts "\n7. Paginating through results..."
+page_size = 5
+total_fetched = 0
+cursor = nil
+
+3.times do |page|
+  params = {
+    object: "people",
+    limit: page_size,
+  }
+  params[:cursor] = cursor if cursor
+
+  page_results = client.records.list(**params)
+  fetched = page_results["data"]&.length || 0
+  total_fetched += fetched
+
+  puts "   Page #{page + 1}: fetched #{fetched} records"
+
+  cursor = page_results.dig("pagination", "next_cursor")
+  break unless cursor
+end
+puts "   Total fetched across pages: #{total_fetched}"
+
+# 8. Query tasks with status filter
+puts "\n8. Finding pending tasks..."
+pending_tasks = client.tasks.list(
+  status: "pending",
+  limit: 10
+)
+puts "   Found #{pending_tasks['data']&.length || 0} pending tasks"
+
+# 9. Query with custom field filters
+puts "\n9. Filtering by custom fields..."
+# This assumes you have custom fields set up
+client.records.list(
+  object: "people",
+  filters: {
+    # Replace with your actual custom field API slug
+    # custom_field: { equals: "some_value" }
+  },
+  limit: 10
+)
+puts "   Custom field filtering available for your specific schema"
+
+# 10. Export query for analysis
+puts "\n10. Exporting query results..."
+export_data = client.records.list(
+  object: "companies",
+  filters: {
+    industry: { not_null: true },
+  },
+  limit: 100
+)
+
+if export_data["data"] && !export_data["data"].empty?
+  # Simple CSV-like export
+  puts "   Sample export (first 3 records):"
+  export_data["data"].take(3).each do |record|
+    name = record.dig("values", "name", 0, "value") || "N/A"
+    industry = record.dig("values", "industry", 0, "value") || "N/A"
+    puts "   - #{name}: #{industry}"
+  end
+end
+
+puts "\n#{'=' * 40}"
+puts "Example completed successfully!"
+puts "\nThis example demonstrated:"
+puts "  • Simple and complex filtering"
+puts "  • Multi-field sorting"
+puts "  • Date range queries"
+puts "  • Relationship filters"
+puts "  • Null/not-null checks"
+puts "  • Pagination"
+puts "  • Task filtering"
+puts "  • Custom field queries"

data/examples/basic_usage.rb

@@ -0,0 +1,110 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "attio"
+
+# Basic usage example for the Attio Ruby gem
+#
+# This example demonstrates:
+# - Client initialization
+# - Working with records (people, companies)
+# - Creating relationships between records
+# - Error handling
+
+# Initialize the client with your API key
+# You can get your API key from: https://app.attio.com/settings/api-keys
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "🚀 Attio Ruby Client - Basic Usage Example"
+puts "=" * 50
+
+begin
+  # List all available objects in your workspace
+  puts "\n📋 Available Objects:"
+  objects = client.objects.list
+  objects["data"].each do |object|
+    puts "  - #{object['name']} (#{object['id']})"
+  end
+
+  # Working with People records
+  puts "\n👥 Working with People:"
+
+  # List existing people (first 5)
+  people = client.records.list(object: "people", limit: 5)
+  puts "  Found #{people['data'].length} people records"
+
+  # Create a new person
+  new_person = client.records.create(
+    object: "people",
+    data: {
+      name: "John Doe",
+      email: "john.doe@example.com",
+      phone: "+1-555-0123",
+      title: "Software Engineer",
+    }
+  )
+  puts "  ✅ Created person: #{new_person['data']['name']} (ID: #{new_person['data']['id']})"
+
+  # Update the person
+  updated_person = client.records.update(
+    object: "people",
+    id: new_person["data"]["id"],
+    data: { title: "Senior Software Engineer" }
+  )
+  puts "  ✅ Updated title to: #{updated_person['data']['title']}"
+
+  # Working with Companies
+  puts "\n🏢 Working with Companies:"
+
+  # Create a company
+  new_company = client.records.create(
+    object: "companies",
+    data: {
+      name: "Acme Corp",
+      domain: "acme.com",
+      employee_count: 100,
+      description: "Leading provider of innovative solutions",
+    }
+  )
+  puts "  ✅ Created company: #{new_company['data']['name']}"
+
+  # Link person to company (create relationship)
+  # Note: This requires the person and company to have a relationship field configured
+  puts "\n🔗 Creating Relationships:"
+  # This would typically be done through a reference field
+  # The exact implementation depends on your Attio workspace configuration
+
+  # Working with Lists
+  puts "\n📝 Working with Lists:"
+  lists = client.lists.list(limit: 5)
+  if lists["data"].any?
+    first_list = lists["data"].first
+    puts "  Found list: #{first_list['name']}"
+
+    # Get entries in the list
+    entries = client.lists.entries(id: first_list["id"], limit: 5)
+    puts "  List has #{entries['data'].length} entries"
+  else
+    puts "  No lists found in workspace"
+  end
+
+  # Cleanup - Delete the test records
+  puts "\n🧹 Cleaning up test data:"
+  client.records.delete(object: "people", id: new_person["data"]["id"])
+  puts "  ✅ Deleted test person record"
+
+  client.records.delete(object: "companies", id: new_company["data"]["id"])
+  puts "  ✅ Deleted test company record"
+rescue Attio::AuthenticationError => e
+  puts "❌ Authentication failed: #{e.message}"
+  puts "   Please check your API key"
+rescue Attio::NotFoundError => e
+  puts "❌ Resource not found: #{e.message}"
+rescue Attio::ValidationError => e
+  puts "❌ Validation error: #{e.message}"
+rescue Attio::Error => e
+  puts "❌ API error: #{e.message}"
+end
+
+puts "\n✨ Example completed!"