attio 0.1.3 → 0.2.0

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!"

data/examples/collaboration_example.rb

@@ -0,0 +1,173 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "attio"
+require "time"
+
+# Example: Collaboration Features (Comments, Threads, Tasks, Notes)
+#
+# This example demonstrates how to use Attio's collaboration features
+# to manage team communication and tasks on customer records.
+
+# Initialize the client
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "Attio Collaboration Features Example"
+puts "=" * 40
+
+# 1. Create a company and contact for our example
+puts "\n1. Creating sample company and contact..."
+company = client.records.create(
+  object: "companies",
+  data: {
+    name: "TechCorp Solutions",
+    domain: "techcorp.example.com",
+    industry: "Software Development",
+  }
+)
+puts "   ✓ Created company: #{company.dig('data', 'values', 'name', 0, 'value')}"
+
+contact = client.records.create(
+  object: "people",
+  data: {
+    name: "Sarah Johnson",
+    email: "sarah@techcorp.example.com",
+    title: "VP of Engineering",
+  }
+)
+puts "   ✓ Created contact: #{contact.dig('data', 'values', 'name', 0, 'value')}"
+
+company_id = company.dig("data", "id", "record_id")
+contact_id = contact.dig("data", "id", "record_id")
+
+# 2. Create a thread for discussion
+puts "\n2. Creating a discussion thread..."
+thread = client.threads.create(
+  parent_object: "companies",
+  parent_record_id: company_id,
+  title: "Q1 2025 Contract Renewal Discussion",
+  description: "Thread to track all discussions related to the Q1 2025 contract renewal"
+)
+thread_id = thread.dig("data", "id", "thread_id")
+puts "   ✓ Created thread: #{thread.dig('data', 'title')}"
+
+# 3. Add comments to the thread
+puts "\n3. Adding comments to the thread..."
+client.comments.create(
+  thread_id: thread_id,
+  content: "Initial meeting scheduled for next Monday. Key topics:\n\n" \
+           "- Review current usage metrics\n" \
+           "- Discuss expansion opportunities\n" \
+           "- Address any concerns"
+)
+puts "   ✓ Added initial comment"
+
+comment2 = client.comments.create(
+  thread_id: thread_id,
+  content: "Sarah confirmed attendance. She mentioned interest in our new API features."
+)
+puts "   ✓ Added follow-up comment"
+
+# 4. React to a comment
+puts "\n4. Adding reactions to comments..."
+client.comments.react(id: comment2.dig("data", "id", "comment_id"), emoji: "👍")
+puts "   ✓ Added 👍 reaction"
+
+# 5. Create tasks
+puts "\n5. Creating tasks..."
+task1 = client.tasks.create(
+  parent_object: "companies",
+  parent_record_id: company_id,
+  title: "Prepare renewal proposal",
+  due_date: (Date.today + 7).iso8601,
+  description: "Create comprehensive renewal proposal including pricing and new features"
+)
+puts "   ✓ Created task: #{task1.dig('data', 'title')}"
+
+task2 = client.tasks.create(
+  parent_object: "people",
+  parent_record_id: contact_id,
+  title: "Schedule follow-up call",
+  due_date: (Date.today + 14).iso8601
+)
+puts "   ✓ Created task: #{task2.dig('data', 'title')}"
+
+# 6. Create meeting notes
+puts "\n6. Creating meeting notes..."
+client.notes.create(
+  parent_object: "companies",
+  parent_record_id: company_id,
+  title: "Contract Renewal Meeting - #{Date.today}",
+  content: <<~CONTENT
+    ## Attendees
+    - Sarah Johnson (TechCorp)
+    - Our team: Sales, Customer Success
+
+    ## Key Points Discussed
+    1. Current contract value: $50,000/year
+    2. Usage has grown 40% in last quarter
+    3. Interest in API expansion package
+
+    ## Action Items
+    - [ ] Send updated pricing proposal by EOW
+    - [ ] Schedule technical demo for API features
+    - [ ] Review SLA requirements
+
+    ## Next Steps
+    Follow-up call scheduled for next week
+  CONTENT
+)
+puts "   ✓ Created meeting notes"
+
+# 7. List all collaboration items
+puts "\n7. Listing collaboration items..."
+
+# List threads
+threads = client.threads.list(
+  parent_object: "companies",
+  parent_record_id: company_id
+)
+puts "   Threads on company: #{threads['data']&.length || 0}"
+
+# List comments in thread
+comments = client.comments.list(thread_id: thread_id)
+puts "   Comments in thread: #{comments['data']&.length || 0}"
+
+# List tasks
+all_tasks = client.tasks.list
+puts "   Total tasks: #{all_tasks['data']&.length || 0}"
+
+# List notes
+notes = client.notes.list(
+  parent_object: "companies",
+  parent_record_id: company_id
+)
+puts "   Notes on company: #{notes['data']&.length || 0}"
+
+# 8. Update task status
+puts "\n8. Updating task status..."
+client.tasks.complete(
+  id: task1.dig("data", "id", "task_id"),
+  completed_at: Time.now.iso8601
+)
+puts "   ✓ Marked task as complete"
+
+# 9. Close the thread
+puts "\n9. Closing the discussion thread..."
+client.threads.close(id: thread_id)
+puts "   ✓ Thread closed"
+
+puts "\n#{'=' * 40}"
+puts "Example completed successfully!"
+puts "\nThis example demonstrated:"
+puts "  • Creating and managing discussion threads"
+puts "  • Adding comments and reactions"
+puts "  • Creating and completing tasks"
+puts "  • Creating detailed meeting notes"
+puts "  • Listing collaboration items"
+
+# Clean up (optional - uncomment to delete created records)
+# puts "\nCleaning up..."
+# client.records.delete(object: "companies", id: company_id)
+# client.records.delete(object: "people", id: contact_id)
+# puts "   ✓ Cleanup complete"