Attio Ruby Client

gem 'attio'

require 'attio'

# Initialize the client with your API key
client = Attio.client(api_key: 'your-api-key-here')

# List people records
people = client.records.list(object: 'people', limit: 10)

# Create a new person
person = client.records.create(
  object: 'people',
  data: {
    name: 'Jane Doe',
    email: 'jane@example.com',
    phone: '+1-555-0123'
  }
)

# Get a specific person
person = client.records.get(object: 'people', id: person['id'])

# Update a person
updated_person = client.records.update(
  object: 'people',
  id: person['id'],
  data: { name: 'Jane Smith' }
)

# Delete a person
client.records.delete(object: 'people', id: person['id'])

# Basic client with default timeout (30 seconds)
client = Attio.client(api_key: 'your-api-key')

# Client with custom timeout
client = Attio::Client.new(api_key: 'your-api-key', timeout: 60)

# List all people
people = client.records.list(object: 'people')

# List with filtering and sorting
filtered_people = client.records.list(
  object: 'people',
  filter: {
    name: { $contains: 'John' }
  },
  sort: 'created_at.desc',
  limit: 50,
  offset: 0
)

# List all records with automatic pagination
client.records.list_all(object: 'people', page_size: 50).each do |person|
  puts person['name']
end

# Create a person
person = client.records.create(
  object: 'people',
  data: {
    name: 'John Doe',
    email: 'john@example.com',
    phone: '+1-555-0123',
    company: {
      target_object: 'companies',
      target_record_id: 'company-123'
    }
  }
)

# Create a company
company = client.records.create(
  object: 'companies',
  data: {
    name: 'Acme Corp',
    domain: 'acme.com',
    industry: 'Technology'
  }
)

# Update a person's email
client.records.update(
  object: 'people',
  id: 'person-123',
  data: { email: 'newemail@example.com' }
)

# Update multiple fields
client.records.update(
  object: 'people',
  id: 'person-123',
  data: {
    name: 'John Smith',
    phone: '+1-555-9999',
    notes: 'Updated contact information'
  }
)

# 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')

# 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')

# 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')

# 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')

# List all object types
objects = client.objects.list

# Get a specific object schema
people_object = client.objects.get(id_or_slug: 'people')

# Create a custom object
custom_object = client.objects.create(
  api_slug: 'projects',
  singular_noun: 'Project',
  plural_noun: 'Projects'
)

# Update a custom object
client.objects.update(
  id_or_slug: 'projects',
  plural_noun: 'Active Projects'
)

# Update multiple fields
client.objects.update(
  id_or_slug: 'projects',
  api_slug: 'active_projects',
  singular_noun: 'Active Project',
  plural_noun: 'Active Projects'
)

# NOTE: The Attio API v2.0.0 does not currently support deleting custom objects
# Calling delete/destroy will raise NotImplementedError with instructions
# To delete objects, use: Settings > Data Model > Objects in the Attio UI

# List all lists
lists = client.lists.list

# Get entries from a specific list
entries = client.lists.entries(id: 'list-123')

# List workspaces
workspaces = client.workspaces.list

# Get current workspace
workspace = client.workspaces.get

# List attributes for an object
attributes = client.attributes.list(object: 'people')

# Create a custom attribute
attribute = client.attributes.create(
  object: 'people',
  data: {
    title: 'Custom Field',
    api_slug: 'custom_field',
    type: 'text'
  }
)

# List workspace users
users = client.users.list

# Get a specific user by ID
user = client.users.get(id: 'user-123')

# Get current token and workspace information
meta = client.meta.identify
# => { "data" => { "active" => true, "workspace_name" => "My Workspace", ... } }

# Check if token is active
if client.meta.active?
  puts "Token is valid and active"
end

# Get workspace details
workspace = client.meta.workspace
# => { "id" => "...", "name" => "My Workspace", "slug" => "my-workspace" }

# Check permissions
if client.meta.permission?("record_permission:read-write")
  puts "Can read and write records"
end

# Get all permissions
permissions = client.meta.permissions
# => ["comment:read-write", "list_configuration:read", ...]

# 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')

# 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 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' }
  ]
)

# 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]}"

# Create an enhanced client with all features
client = Attio.enhanced_client(
  api_key: ENV['ATTIO_API_KEY'],
  connection_pool: {
    size: 10,      # Pool size
    timeout: 5     # Checkout timeout
  },
  circuit_breaker: {
    threshold: 5,   # Failures before opening
    timeout: 30,    # Recovery timeout in seconds
    half_open_requests: 2
  },
  instrumentation: {
    logger: Rails.logger,
    metrics: :datadog,  # or :statsd, :prometheus, :opentelemetry
    traces: :datadog    # or :opentelemetry
  },
  webhook_secret: ENV['ATTIO_WEBHOOK_SECRET']
)

# Use it like a regular client
records = client.records.list(object: 'people')

# Execute with circuit breaker protection
client.execute(endpoint: 'api/records') do
  client.records.create(object: 'people', data: { name: 'John' })
end

# Check health of all components
health = client.health_check
# => { api: true, pool: true, circuit_breaker: :healthy, rate_limiter: true }

# Verify API connectivity and token validity
if client.meta.active?
  puts "API connection healthy, token valid"
end

# Get statistics
stats = client.stats
# => { pool: { size: 10, available: 7 }, circuit_breaker: { state: :closed, requests: 100 } }

pool = Attio::ConnectionPool.new(size: 5, timeout: 2) do
  Attio::HttpClient.new(
    base_url: 'https://api.attio.com/v2',
    headers: { 'Authorization' => "Bearer #{api_key}" }
  )
end

# Use connections from the pool
pool.with do |connection|
  connection.get('records')
end

# Check pool status
stats = pool.stats
# => { size: 5, available: 3, allocated: 2 }

# Graceful shutdown
pool.shutdown

breaker = Attio::CircuitBreaker.new(
  threshold: 5,        # Open after 5 failures
  timeout: 30,         # Reset after 30 seconds
  half_open_requests: 2
)

# Execute with protection
result = breaker.execute do
  risky_api_call
end

# Monitor state changes
breaker.on_state_change = ->(old_state, new_state) {
  puts "Circuit breaker: #{old_state} -> #{new_state}"
}

# Check current state
breaker.state  # => :closed, :open, or :half_open
breaker.stats  # => { requests: 100, failures: 2, success_rate: 0.98 }

# Initialize with your preferred backend
instrumentation = Attio::Observability::Instrumentation.new(
  logger: Logger.new(STDOUT),
  metrics_backend: :datadog,  # :statsd, :prometheus, :memory
  trace_backend: :opentelemetry  # :datadog, :memory
)

# Record API calls
instrumentation.record_api_call(
  method: :post,
  path: '/records',
  duration: 0.125,
  status: 200
)

# Record rate limits
instrumentation.record_rate_limit(
  remaining: 450,
  limit: 500,
  reset_at: Time.now + 3600
)

# Record circuit breaker state changes
instrumentation.record_circuit_breaker(
  endpoint: 'api/records',
  old_state: :closed,
  new_state: :open
)

# Track pool statistics
instrumentation.record_pool_stats(
  size: 10,
  available: 7,
  allocated: 3
)

# Initialize webhook handler
webhooks = Attio::Webhooks.new(secret: ENV['ATTIO_WEBHOOK_SECRET'])

# Register event handlers
webhooks.on('record.created') do |event|
  puts "New record: #{event.data['id']}"
end

webhooks.on_any do |event|
  puts "Event: #{event.type}"
end

# Process incoming webhook
begin
  event = webhooks.process(
    request.body.read,
    request.headers
  )
  render json: { status: 'ok' }
rescue Attio::Webhooks::InvalidSignatureError => e
  render json: { error: 'Invalid signature' }, status: 401
end

# Development webhook server
server = Attio::WebhookServer.new(port: 3001, secret: 'test_secret')
server.webhooks.on('record.created') do |event|
  puts "Received: #{event.inspect}"
end
server.start  # Starts WEBrick server for testing

begin
  client.records.get(object: 'people', id: 'invalid-id')
rescue Attio::NotFoundError => e
  puts "Record not found: #{e.message}"
rescue Attio::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Attio::RateLimitError => e
  puts "Rate limit exceeded. Retry after: #{e.retry_after}"
rescue Attio::APIError => e
  puts "API error: #{e.message}"
end