Attio Ruby SDK

gem 'attio-ruby'

require 'attio'

# Configure the client
Attio.configure do |config|
  config.api_key = ENV['ATTIO_API_KEY']
end

# Create a person
person = Attio::Person.create(
  first_name: "John",
  last_name: "Doe",
  email: "john@example.com"
)

# Search for companies
companies = Attio::Company.search("tech")

Attio.configure do |config|
  # Required
  config.api_key = "your_api_key"
  
  # Optional
  config.api_base = "https://api.attio.com" # Default
  config.api_version = "v2" # Default
  config.timeout = 30 # Request timeout in seconds
  config.max_retries = 3 # Number of retries for failed requests
  config.debug = false # Enable debug logging
  config.logger = Logger.new(STDOUT) # Custom logger
end

# Override configuration for a single request
person = Attio::Person.create(
  first_name: "Jane",
  last_name: "Doe",
  api_key: "different_api_key"
)

Attio.configure do |config|
  config.api_key = "your_api_key"
end

# Initialize OAuth client
oauth_client = Attio::OAuth::Client.new(
  client_id: ENV['ATTIO_CLIENT_ID'],
  client_secret: ENV['ATTIO_CLIENT_SECRET'],
  redirect_uri: "https://yourapp.com/callback"
)

# Generate authorization URL
auth_data = oauth_client.authorization_url(
  scopes: %w[record:read record:write],
  state: "random_state"
)
redirect_to auth_data[:url]

# Exchange code for token
token = oauth_client.exchange_code_for_token(code: params[:code])

# Use the token
Attio.configure do |config|
  config.api_key = token.access_token
end

# List all objects
objects = Attio::Object.list
objects.each do |object|
  puts "#{object.plural_noun} (#{object.api_slug})"
end

# Get a specific object
people_object = Attio::Object.retrieve("people")
puts people_object.name # => "People"

# The gem handles the complex structure for you
person = Attio::Person.create(
  first_name: "John",
  last_name: "Smith",
  email: "john@example.com",
  phone: "+15558675309",
  job_title: "Developer"
)

company = Attio::Company.create(
  name: "Acme Corp",
  domain: "acme.com",
  employee_count: "50-100"
)

# Names
values: {
  name: [{
    first_name: "John",
    last_name: "Smith",
    full_name: "John Smith"
  }]
}

# Phone Numbers
values: {
  phone_numbers: [{
    original_phone_number: "+15558675309",
    country_code: "US"
  }]
}

# Addresses
values: {
  primary_location: [{
    line_1: "1 Infinite Loop",
    locality: "Cupertino",
    region: "CA",
    postcode: "95014",
    country_code: "US"
  }]
}

# Email addresses and domains (simple arrays)
values: {
  email_addresses: ["john@example.com", "john.smith@company.com"],
  domains: ["example.com", "example.org"]
}

# Create a person
person = Attio::Person.create(
  first_name: "Jane",
  last_name: "Smith",
  email: "jane@example.com",
  phone: "+1-555-0123",
  job_title: "CEO"
)

# Create a company
company = Attio::Company.create(
  name: "Acme Corp",
  domain: "acme.com",
  values: {
    industry: "Technology"
  }
)

# Get a specific person
person = Attio::Person.retrieve("rec_456def789")

# Access attributes using bracket notation
puts person[:name]
puts person[:email_addresses]
puts person[:job_title]

# Note: Attributes can be accessed with bracket notation and symbols

# Update a record using attribute setters
person[:job_title] = "CTO"
person[:tags] = ["vip", "customer"]
person.save

# Or update directly
Attio::Person.update(
  "rec_456def789",
  values: { job_title: "CTO" }
)

# Simple search
people = Attio::Person.search("john")

# Advanced filtering
executives = Attio::Person.list(
  params: {
    filter: {
      job_title: { "$contains": "CEO" }
    },
    sort: [{ attribute: "name", direction: "asc" }],
    limit: 20
  }
)

# Pagination
page = people
while page.has_more?
  page.each do |person|
    puts person[:name]
  end
  page = page.next_page
end

# Auto-pagination
people.auto_paging_each do |person|
  puts person[:name]
end

# Delete a record
person.destroy

# Or delete by ID
Attio::Person.delete("rec_123abc456")  # Replace with actual record ID

person = Attio::Person.retrieve("rec_123")

# Access methods
person.email          # Returns primary email address
person.phone          # Returns primary phone number  
person.first_name     # Returns first name
person.last_name      # Returns last name
person.full_name      # Returns full name

# Modification methods
person.set_name(first: "Jane", last: "Doe")
person.add_email("jane.doe@example.com")
person.add_phone("+14155551234", country_code: "US")

# Search methods - Rails-style find_by
jane = Attio::Person.find_by(email: "jane@example.com")
john = Attio::Person.find_by(name: "John Smith")
# Can combine multiple conditions (uses AND logic)
exec = Attio::Person.find_by(email: "exec@company.com", job_title: "CEO")

company = Attio::Company.retrieve("rec_456")

# Access methods
company.name          # Returns company name
company.domain        # Returns primary domain
company.domains_list  # Returns all domains

# Modification methods
company.name = "New Company Name"
company.add_domain("newdomain.com")
company.add_team_member(person)  # Associate a person with the company

# Search methods - Rails-style find_by
acme = Attio::Company.find_by(name: "Acme Corp")
tech_co = Attio::Company.find_by(domain: "techcompany.com")
# Can combine multiple conditions
big_tech = Attio::Company.find_by(domain: "tech.com", employee_count: "100-500")

# Create a deal (requires name, stage, and owner)
deal = Attio::Deal.create(
  name: "Enterprise Deal",
  value: 50000,
  stage: "In Progress",  # Options: "Lead", "In Progress", "Won 🎉", "Lost"
  owner: "sales@company.com"  # Must be a workspace member email
)

# Access methods
deal.name               # Returns deal name
deal.value              # Returns currency object with currency_value
deal.stage              # Returns status object with nested title
deal.status             # Alias for stage
deal.current_status     # Returns the current status title as a string
deal.status_changed_at  # Returns when the status was last changed

# Update methods
deal.update_stage("Won 🎉")
deal.update_value(75000)

# Search methods
big_deals = Attio::Deal.find_by_value_range(min: 100000)
mid_deals = Attio::Deal.find_by_value_range(min: 50000, max: 100000)
won_deals = Attio::Deal.find_by(stage: "Won 🎉")

# Query by status using convenience methods
won_deals = Attio::Deal.won          # All deals with "Won 🎉" status
lost_deals = Attio::Deal.lost        # All deals with "Lost" status
open_deals = Attio::Deal.open_deals  # All deals with "Lead" or "In Progress"

# Query by custom stages
custom_deals = Attio::Deal.in_stage(stage_names: ["Won 🎉", "Contract Signed"])

# Check deal status (uses configuration)
deal.open?      # true if status is "Lead" or "In Progress"
deal.won?       # true if status is "Won 🎉"
deal.lost?      # true if status is "Lost"
deal.won_at     # timestamp when deal was won (or nil)
deal.closed_at  # timestamp when deal was closed (won or lost)

# Associate with companies and people
deal = Attio::Deal.create(
  name: "Partnership Deal",
  value: 100000,
  stage: "Lead",
  owner: "sales@company.com",
  associated_people: ["contact@partner.com"],
  associated_company: ["partner.com"]  # Uses domain
)

# In config/initializers/attio.rb
Attio.configure do |config|
  config.api_key = ENV["ATTIO_API_KEY"]
  
  # Customize which statuses are considered won, lost, or open
  config.won_statuses = ["Won 🎉", "Contract Signed", "Customer"]
  config.lost_statuses = ["Lost", "Disqualified", "No Budget"]
  config.open_statuses = ["Lead", "Qualified Lead", "Prospect"]
  config.in_progress_statuses = ["In Progress", "Negotiation", "Proposal Sent"]
end

# Now the convenience methods use your custom statuses
won_deals = Attio::Deal.won  # Finds deals with any of your won_statuses
deal.won?  # Returns true if deal status is in your won_statuses

# Search with query string
results = Attio::Person.search("john")

# Find by any attribute using Rails-style syntax
person = Attio::Person.find_by(job_title: "CEO")
# Or find by multiple attributes (AND logic)
person = Attio::Person.find_by(job_title: "CEO", company: "Acme Corp")

# Aliases for common methods
Attio::Person.all == Attio::Person.list
Attio::Person.find("rec_123") == Attio::Person.retrieve("rec_123")

# Create a list
list = Attio::List.create(
  name: "VIP Customers",
  object: "people"
)

# Add records to a list
entry = list.add_record("rec_789def012")  # Replace with actual record ID

# List entries
entries = list.entries
entries.each do |entry|
  puts entry.record_id
end

# Remove from list (requires entry_id, not record_id)
list.remove_record("ent_456ghi789")  # Replace with actual list entry ID

# Delete list
list.destroy

# Create a note
note = Attio::Note.create(
  parent_object: "people",
  parent_record_id: "rec_123abc456",  # Replace with actual record ID
  content: "Had a great meeting about the new project.",
  format: "plaintext" # or "markdown"
)

# List notes for a record
notes = Attio::Note.list(
  parent_object: "people",
  parent_record_id: "rec_123abc456"  # Replace with actual record ID
)

# Notes are immutable - create a new note instead of updating
# To "update" a note, you would delete the old one and create a new one

# Delete a note
note.destroy

# Create a webhook
webhook = Attio::Webhook.create(
  name: "Customer Updates",
  url: "https://yourapp.com/webhooks/attio",
  subscriptions: %w[record.created record.updated]
)

# List webhooks
webhooks = Attio::Webhook.list

# Update webhook
webhook[:active] = false
webhook.save

# Delete webhook
webhook.destroy

# Verify webhook signatures
Attio::Util::WebhookSignature.verify!(
  payload: request.body.read,
  signature: request.headers['Attio-Signature'],
  secret: ENV['WEBHOOK_SECRET']
)

# Initialize client
oauth = Attio::OAuth::Client.new(
  client_id: ENV['CLIENT_ID'],
  client_secret: ENV['CLIENT_SECRET'],
  redirect_uri: "https://yourapp.com/callback"
)

# Authorization
auth_data = oauth.authorization_url(
  scopes: %w[record:read record:write user:read],
  state: SecureRandom.hex(16)
)

# Token exchange
token = oauth.exchange_code_for_token(
  code: params[:code],
  state: params[:state]
)

# Token refresh
new_token = oauth.refresh_token("rtok_xyz789ghi012")  # Replace with actual refresh token

# Token introspection
info = oauth.introspect_token("tok_abc123def456")  # Replace with actual access token
puts info[:active] # => true

# Token revocation
oauth.revoke_token("tok_abc123def456")  # Replace with actual access token

begin
  person = Attio::Person.create(
    email: "invalid-email"
  )
rescue Attio::InvalidRequestError => e
  puts "Validation error: #{e.message}"
  puts "HTTP status: #{e.code}"
  puts "Request ID: #{e.request_id}"
rescue Attio::AuthenticationError => e
  puts "Auth failed: #{e.message}"
  puts "Request ID: #{e.request_id}"
rescue Attio::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Attio::ConnectionError => e
  puts "Network error: #{e.message}"
rescue Attio::Error => e
  puts "API error: #{e.message}"
  puts "HTTP status: #{e.code}"
  puts "Request ID: #{e.request_id}"
end