attio 0.1.3 → 0.2.0

data/examples/full_workflow.rb

@@ -0,0 +1,348 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "attio"
+require "time"
+
+# Example: Complete CRM Workflow
+#
+# This example demonstrates a complete CRM workflow including:
+# - Creating and managing companies and contacts
+# - Working with lists and workspace management
+# - Using collaboration features
+# - Error handling
+
+# Initialize the client
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "Attio Complete CRM Workflow Example"
+puts "=" * 40
+
+# Error handling wrapper
+def safe_execute(description)
+  print "#{description}..."
+  result = yield
+  puts " ✓"
+  result
+rescue Attio::NotFoundError => e
+  puts " ✗ Not found: #{e.message}"
+  nil
+rescue Attio::ValidationError => e
+  puts " ✗ Validation error: #{e.message}"
+  nil
+rescue Attio::Error => e
+  puts " ✗ Error: #{e.message}"
+  nil
+end
+
+# 1. Get workspace information
+puts "\n1. Workspace Information"
+puts "-" * 20
+workspace = safe_execute("Getting current workspace") do
+  client.workspaces.get
+end
+
+if workspace
+  puts "   Workspace: #{workspace.dig('data', 'name')}"
+  puts "   ID: #{workspace.dig('data', 'id', 'workspace_id')}"
+end
+
+# 2. List available objects and attributes
+puts "\n2. Schema Information"
+puts "-" * 20
+objects = safe_execute("Listing objects") do
+  client.objects.list
+end
+
+if objects && objects["data"]
+  puts "   Available objects:"
+  objects["data"].each do |obj|
+    puts "   - #{obj['api_slug']}: #{obj['name']}"
+  end
+end
+
+# 3. Create a sales pipeline workflow
+puts "\n3. Sales Pipeline Setup"
+puts "-" * 20
+
+# Create a company
+company = safe_execute("Creating prospect company") do
+  client.records.create(
+    object: "companies",
+    data: {
+      name: "Innovation Labs Inc",
+      domain: "innovationlabs.example.com",
+      industry: "Technology",
+      description: "Potential enterprise customer",
+    }
+  )
+end
+company_id = company&.dig("data", "id", "record_id")
+
+# Create primary contact
+contact = safe_execute("Creating primary contact") do
+  client.records.create(
+    object: "people",
+    data: {
+      name: "Michael Chen",
+      email: "m.chen@innovationlabs.example.com",
+      title: "CTO",
+      phone: "+1-555-0123",
+    }
+  )
+end
+contact&.dig("data", "id", "record_id")
+
+# Create additional contacts
+if company_id
+  safe_execute("Creating additional contact") do
+    client.records.create(
+      object: "people",
+      data: {
+        name: "Lisa Park",
+        email: "l.park@innovationlabs.example.com",
+        title: "VP of Product",
+      }
+    )
+  end
+end
+
+# 4. Create and manage lists
+puts "\n4. List Management"
+puts "-" * 20
+
+lists = safe_execute("Getting available lists") do
+  client.lists.list
+end
+
+if lists && lists["data"] && !lists["data"].empty?
+  list_id = lists["data"].first["id"]["list_id"]
+
+  # Add company to a list
+  if company_id
+    safe_execute("Adding company to list") do
+      client.lists.create_entry(
+        id: list_id,
+        data: {
+          record_id: company_id,
+          notes: "High priority prospect",
+        }
+      )
+    end
+  end
+
+  # Get list entries
+  entries = safe_execute("Getting list entries") do
+    client.lists.entries(id: list_id, limit: 5)
+  end
+
+  puts "   List has #{entries['data']&.length || 0} entries" if entries
+end
+
+# 5. Collaboration workflow
+puts "\n5. Collaboration Workflow"
+puts "-" * 20
+
+if company_id
+  # Create a discussion thread
+  thread = safe_execute("Creating sales discussion thread") do
+    client.threads.create(
+      parent_object: "companies",
+      parent_record_id: company_id,
+      title: "Sales Opportunity - Innovation Labs",
+      description: "Track all sales activities and discussions"
+    )
+  end
+  thread_id = thread&.dig("data", "id", "thread_id")
+
+  # Add initial comment
+  if thread_id
+    safe_execute("Adding sales strategy comment") do
+      client.comments.create(
+        thread_id: thread_id,
+        content: <<~CONTENT
+          ## Opportunity Overview
+          - **Company**: Innovation Labs Inc
+          - **Potential Value**: $100K ARR
+          - **Timeline**: Q1 2025
+
+          ## Next Steps
+          1. Schedule discovery call
+          2. Prepare custom demo
+          3. Send pricing proposal
+        CONTENT
+      )
+    end
+  end
+
+  # Create tasks
+  safe_execute("Creating discovery call task") do
+    client.tasks.create(
+      parent_object: "companies",
+      parent_record_id: company_id,
+      title: "Schedule discovery call with Michael Chen",
+      due_date: (Date.today + 3).iso8601,
+      description: "Initial discovery call to understand their requirements"
+    )
+  end
+
+  safe_execute("Creating demo prep task") do
+    client.tasks.create(
+      parent_object: "companies",
+      parent_record_id: company_id,
+      title: "Prepare customized product demo",
+      due_date: (Date.today + 7).iso8601
+    )
+  end
+
+  # Create meeting notes
+  safe_execute("Creating initial contact notes") do
+    client.notes.create(
+      parent_object: "companies",
+      parent_record_id: company_id,
+      title: "Initial Contact - #{Date.today}",
+      content: <<~CONTENT
+        ## Contact Method
+        Inbound inquiry via website
+
+        ## Requirements
+        - Looking for enterprise CRM solution
+        - Team size: 200+ employees
+        - Current solution: Spreadsheets
+
+        ## Pain Points
+        - No centralized customer data
+        - Manual reporting processes
+        - Limited collaboration features
+
+        ## Budget
+        Approved budget: $100-150K annually
+
+        ## Decision Timeline
+        Looking to implement in Q1 2025
+      CONTENT
+    )
+  end
+end
+
+# 6. Query and reporting
+puts "\n6. Queries and Reporting"
+puts "-" * 20
+
+# Get all high-priority tasks
+tasks = safe_execute("Getting pending tasks") do
+  client.tasks.list(status: "pending", limit: 5)
+end
+
+if tasks
+  puts "   Pending tasks: #{tasks['data']&.length || 0}"
+  tasks["data"]&.each do |task|
+    puts "   - #{task['title']}"
+  end
+end
+
+# Query recent companies
+recent_companies = safe_execute("Finding recent companies") do
+  client.records.list(
+    object: "companies",
+    sorts: [{ field: "created_at", direction: "desc" }],
+    limit: 5
+  )
+end
+
+puts "   Recent companies: #{recent_companies['data']&.length || 0}" if recent_companies
+
+# 7. User management
+puts "\n7. User Information"
+puts "-" * 20
+
+# Get current user
+me = safe_execute("Getting current user") do
+  client.users.me
+end
+
+if me
+  puts "   Current user: #{me.dig('data', 'name')}"
+  puts "   Email: #{me.dig('data', 'email')}"
+end
+
+# List all users
+users = safe_execute("Listing workspace users") do
+  client.users.list
+end
+
+puts "   Total users: #{users['data']&.length || 0}" if users
+
+# 8. Advanced features
+puts "\n8. Advanced Features"
+puts "-" * 20
+
+# Get custom attributes
+if company_id
+  attributes = safe_execute("Getting company attributes") do
+    client.attributes.list(object: "companies")
+  end
+
+  puts "   Company attributes: #{attributes['data']&.length || 0}" if attributes
+end
+
+# Demonstrate pagination
+puts "   Demonstrating pagination..."
+all_records = []
+cursor = nil
+pages = 0
+
+loop do
+  params = { object: "companies", limit: 2 }
+  params[:cursor] = cursor if cursor
+
+  page = safe_execute("   Fetching page #{pages + 1}") do
+    client.records.list(**params)
+  end
+
+  break unless page && page["data"]
+
+  all_records.concat(page["data"])
+  pages += 1
+
+  cursor = page.dig("pagination", "next_cursor")
+  break unless cursor && pages < 3 # Limit to 3 pages for demo
+end
+
+puts "   Fetched #{all_records.length} records across #{pages} pages"
+
+# 9. Summary
+puts "\n9. Workflow Summary"
+puts "-" * 20
+puts "   ✓ Workspace configured"
+puts "   ✓ Company and contacts created"
+puts "   ✓ Lists managed"
+puts "   ✓ Collaboration tools utilized"
+puts "   ✓ Tasks and notes created"
+puts "   ✓ Queries executed"
+puts "   ✓ User information retrieved"
+
+puts "\n#{'=' * 40}"
+puts "Complete workflow example finished!"
+puts "\nThis example demonstrated:"
+puts "  • Complete CRM setup"
+puts "  • Record creation and management"
+puts "  • List operations"
+puts "  • Collaboration features"
+puts "  • Task management"
+puts "  • Querying and reporting"
+puts "  • User management"
+puts "  • Error handling"
+puts "  • Pagination"
+
+# Optional cleanup
+# if company_id
+#   safe_execute("Cleaning up company") do
+#     client.records.delete(object: "companies", id: company_id)
+#   end
+# end
+# if contact_id
+#   safe_execute("Cleaning up contact") do
+#     client.records.delete(object: "people", id: contact_id)
+#   end
+# end

data/examples/notes_and_tasks.rb

@@ -0,0 +1,200 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "attio"
+require "date"
+
+# Example demonstrating Notes and Tasks functionality
+#
+# This example shows how to:
+# - Create and manage notes on records
+# - Create and manage tasks
+# - Work with task assignments and due dates
+# - Track task completion
+
+client = Attio.client(api_key: ENV.fetch("ATTIO_API_KEY"))
+
+puts "📓 Attio Notes and Tasks Example"
+puts "=" * 50
+
+begin
+  # First, find or create a person to work with
+  puts "\n👤 Setting up test person..."
+  test_person = client.records.create(
+    object: "people",
+    data: {
+      name: "Jane Smith",
+      email: "jane.smith@example.com",
+      title: "Product Manager",
+    }
+  )
+  person_id = test_person["data"]["id"]
+  puts "  Created test person: Jane Smith (#{person_id})"
+
+  # Working with Notes
+  puts "\n📝 Creating Notes:"
+
+  # Create a meeting note
+  meeting_note = client.notes.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Initial Meeting - Product Requirements",
+    content: <<~MARKDOWN
+      ## Meeting Summary
+      **Date:** #{Date.today}
+      **Attendees:** Jane Smith, Development Team
+
+      ### Discussion Points:
+      1. **Q1 Product Roadmap**
+         - Feature A: User authentication improvements
+         - Feature B: New dashboard design
+         - Feature C: API v2 development
+
+      2. **Timeline**
+         - Sprint 1: Jan 15-29
+         - Sprint 2: Jan 30-Feb 12
+         - Release: Feb 15
+
+      3. **Action Items**
+         - [ ] Create detailed specs for Feature A
+         - [ ] Schedule design review for Feature B
+         - [ ] Allocate resources for API development
+
+      ### Next Steps:
+      Follow-up meeting scheduled for next week.
+    MARKDOWN
+  )
+  puts "  ✅ Created meeting note: #{meeting_note['data']['title']}"
+
+  # Create a follow-up note
+  followup_note = client.notes.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Follow-up: Action Items",
+    content: "Confirmed timeline and resource allocation. Jane will provide detailed specs by EOW."
+  )
+  puts "  ✅ Created follow-up note"
+
+  # List all notes for the person
+  notes = client.notes.list(
+    parent_object: "people",
+    parent_record_id: person_id
+  )
+  puts "\n  📋 Notes for Jane Smith:"
+  notes["data"].each do |note|
+    puts "    - #{note['title']} (created: #{note['created_at']})"
+  end
+
+  # Working with Tasks
+  puts "\n✅ Creating Tasks:"
+
+  # Create tasks based on action items
+  task1 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Create detailed specs for Feature A",
+    description: "Write comprehensive specifications for the user authentication improvements",
+    due_date: (Date.today + 7).iso8601,
+    priority: 1,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task1['data']['title']}"
+
+  task2 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Schedule design review for Feature B",
+    description: "Coordinate with design team and schedule review meeting",
+    due_date: (Date.today + 3).iso8601,
+    priority: 2,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task2['data']['title']}"
+
+  task3 = client.tasks.create(
+    parent_object: "people",
+    parent_record_id: person_id,
+    title: "Allocate resources for API development",
+    description: "Determine team members and timeline for API v2",
+    due_date: (Date.today + 10).iso8601,
+    priority: 3,
+    status: "pending"
+  )
+  puts "  ✅ Created task: #{task3['data']['title']}"
+
+  # List pending tasks
+  puts "\n  📋 Pending Tasks:"
+  pending_tasks = client.tasks.list(
+    status: "pending",
+    parent_object: "people",
+    parent_record_id: person_id
+  )
+  pending_tasks["data"].each do |task|
+    puts "    - #{task['title']} (due: #{task['due_date']})"
+  end
+
+  # Complete a task
+  puts "\n  ✅ Completing task..."
+  completed_task = client.tasks.complete(
+    id: task2["data"]["id"],
+    completed_at: DateTime.now.iso8601
+  )
+  puts "    Task completed: #{completed_task['data']['title']}"
+
+  # Update a task
+  puts "\n  📝 Updating task..."
+  updated_task = client.tasks.update(
+    id: task1["data"]["id"],
+    description: "Updated: Include security requirements in the specifications",
+    priority: 1
+  )
+  puts "    Task updated: #{updated_task['data']['title']}"
+
+  # Get task details
+  puts "\n  🔍 Task Details:"
+  task_detail = client.tasks.get(id: task1["data"]["id"])
+  puts "    Title: #{task_detail['data']['title']}"
+  puts "    Description: #{task_detail['data']['description']}"
+  puts "    Due Date: #{task_detail['data']['due_date']}"
+  puts "    Status: #{task_detail['data']['status']}"
+
+  # Update a note
+  puts "\n  📝 Updating note..."
+  client.notes.update(
+    id: followup_note["data"]["id"],
+    content: "Updated: Specs delivered. Design review scheduled for Friday."
+  )
+  puts "    Note updated successfully"
+
+  # Cleanup
+  puts "\n🧹 Cleaning up..."
+
+  # Delete tasks
+  [task1, task2, task3].each do |task|
+    client.tasks.delete(id: task["data"]["id"])
+  end
+  puts "  ✅ Deleted tasks"
+
+  # Delete notes
+  [meeting_note, followup_note].each do |note|
+    client.notes.delete(id: note["data"]["id"])
+  end
+  puts "  ✅ Deleted notes"
+
+  # Delete test person
+  client.records.delete(object: "people", id: person_id)
+  puts "  ✅ Deleted test person"
+rescue Attio::Error => e
+  puts "❌ Error: #{e.message}"
+  # Cleanup on error
+  if defined?(person_id)
+    begin
+      client.records.delete(object: "people", id: person_id)
+    rescue StandardError
+      nil
+    end
+  end
+end
+
+puts "\n✨ Example completed!"

data/lib/attio/client.rb

@@ -116,5 +116,41 @@ module Attio
     def users
       @users ||= Resources::Users.new(self)
     end
+
+    # Access to the Notes API resource.
+    #
+    # @return [Resources::Notes] Notes resource instance
+    # @example
+    #   notes = client.notes.list(parent_object: 'people', parent_record_id: 'rec_123')
+    def notes
+      @notes ||= Resources::Notes.new(self)
+    end
+
+    # Access to the Tasks API resource.
+    #
+    # @return [Resources::Tasks] Tasks resource instance
+    # @example
+    #   tasks = client.tasks.list(status: 'pending')
+    def tasks
+      @tasks ||= Resources::Tasks.new(self)
+    end
+
+    # Access to the Comments API resource.
+    #
+    # @return [Resources::Comments] Comments resource instance
+    # @example
+    #   comments = client.comments.list(thread_id: 'thread_123')
+    def comments
+      @comments ||= Resources::Comments.new(self)
+    end
+
+    # Access to the Threads API resource.
+    #
+    # @return [Resources::Threads] Threads resource instance
+    # @example
+    #   threads = client.threads.list(parent_object: 'companies', parent_record_id: 'rec_456')
+    def threads
+      @threads ||= Resources::Threads.new(self)
+    end
   end
 end

data/lib/attio/http_client.rb

@@ -21,8 +21,12 @@ module Attio
       @timeout = timeout
     end
 
-    def get(path, params = {})
-      execute_request(:get, path, params: params)
+    def get(path, params = nil)
+      if params && !params.empty?
+        execute_request(:get, path, params: params)
+      else
+        execute_request(:get, path)
+      end
     end
 
     def post(path, body = {})
@@ -37,8 +41,12 @@ module Attio
       execute_request(:put, path, body: body.to_json)
     end
 
-    def delete(path)
-      execute_request(:delete, path)
+    def delete(path, params = nil)
+      if params
+        execute_request(:delete, path, body: params.to_json)
+      else
+        execute_request(:delete, path)
+      end
     end
 
     private def execute_request(method, path, options = {})

data/lib/attio/resources/base.rb

@@ -24,22 +24,71 @@ module Attio
         @client = client
       end
 
+      # Common validation methods that can be used by all resource classes
+
+      # Validates that an ID parameter is present and not empty
+      # @param id [String] The ID to validate
+      # @param resource_name [String] The resource name for the error message
+      # @raise [ArgumentError] if id is nil or empty
+      private def validate_id!(id, resource_name = "Resource")
+        return unless id.nil? || id.to_s.strip.empty?
+
+        raise ArgumentError, "#{resource_name} ID is required"
+      end
+
+      # Validates that data is not empty
+      # @param data [Hash] The data to validate
+      # @param operation [String] The operation name for the error message
+      # @raise [ArgumentError] if data is empty
+      private def validate_data!(data, operation = "Operation")
+        raise ArgumentError, "#{operation} data is required" if data.nil? || data.empty?
+      end
+
+      # Validates that a string parameter is present and not empty
+      # @param value [String] The value to validate
+      # @param field_name [String] The field name for the error message
+      # @raise [ArgumentError] if value is nil or empty
+      private def validate_required_string!(value, field_name)
+        return unless value.nil? || value.to_s.strip.empty?
+
+        raise ArgumentError, "#{field_name} is required"
+      end
+
+      # Validates parent object and record ID together
+      # @param parent_object [String] The parent object type
+      # @param parent_record_id [String] The parent record ID
+      # @raise [ArgumentError] if either is missing
+      private def validate_parent!(parent_object, parent_record_id)
+        validate_required_string!(parent_object, "Parent object")
+        validate_required_string!(parent_record_id, "Parent record ID")
+      end
+
       private def request(method, path, params = {})
+        connection = client.connection
+
         case method
         when :get
-          client.connection.get(path, params)
+          handle_get_request(connection, path, params)
         when :post
-          client.connection.post(path, params)
+          connection.post(path, params)
         when :patch
-          client.connection.patch(path, params)
+          connection.patch(path, params)
         when :put
-          client.connection.put(path, params)
+          connection.put(path, params)
         when :delete
-          client.connection.delete(path)
+          handle_delete_request(connection, path, params)
         else
           raise ArgumentError, "Unsupported HTTP method: #{method}"
         end
       end
+
+      private def handle_get_request(connection, path, params)
+        params.empty? ? connection.get(path) : connection.get(path, params)
+      end
+
+      private def handle_delete_request(connection, path, params)
+        params.empty? ? connection.delete(path) : connection.delete(path, params)
+      end
     end
   end
 end