Examples & Tutorials

Quick Start Example

Scenario: Search for a File on Your Device

Goal: Find a file named "resume.pdf" on your local device from the Sulala dashboard.

Steps:

1. Start the device agent

   # JavaScript agent
   cd device-agent
   npm start
   
   # Or Flutter agent
   cd sulala_device_agent
   flutter run
   

2. Enter your API key in the agent interface
3. Verify device is online
   • Go to Dashboard → Devices
   • Your device should show as "Online" (green badge)
4. Initiate search from dashboard
   • Go to Dashboard → Search
   • Type "resume.pdf"
   • Select your device
   • Click "Search"
5. Wait for results (typically 30-60 seconds)
   • Device agent polls for search requests
   • Executes local search
   • Returns results to cloud
   • Results appear in dashboard

Example 1: Testing File Search

Setup

1. Create a test file on your device:

   echo "Test content" > ~/Documents/test-file.txt
   

2. Start your device agent with API key
3. Verify device is online in dashboard

Test Steps

1. Search for the file:
   • Query: test-file.txt
   • Scope: files
   • Device: Your device
2. Expected Result:

   {
     "files": [
       {
         "path": "/Users/yourname/Documents/test-file.txt",
         "name": "test-file.txt",
         "size": 13,
         "modified": "2025-02-20T10:00:00Z"
       }
     ]
   }
   

3. Verify:
   • File path is correct
   • File name matches
   • Timestamp is recent

Example 2: Testing App Discovery

Setup

1. Ensure you have some applications installed (e.g., Chrome, VS Code)
2. Start device agent

Test Steps

1. Search for an app:
   • Query: Chrome
   • Scope: apps
   • Device: Your device
2. Expected Result:

   {
     "apps": [
       {
         "name": "Google Chrome",
         "path": "/Applications/Google Chrome.app",
         "running": false
       }
     ]
   }
   

3. Verify:
   • App name is correct
   • Path is valid
   • Running status is accurate

Example 3: Testing System Information

Setup

1. Start device agent

Test Steps

1. Search for system info:
   • Query: system
   • Scope: system
   • Device: Your device
2. Expected Result:

   {
     "system": {
       "os": "macOS",
       "version": "14.0",
       "cpu": "Apple M1",
       "memory": "16 GB",
       "disk": "500 GB"
     }
   }
   

Example 4: Testing File Upload

Setup

1. Create a test file to upload:

   echo "Upload test" > ~/Documents/upload-test.txt
   

2. Start device agent

Test Steps

1. Request file upload from dashboard:
   • Select file: upload-test.txt
   • Destination: Cloud storage
   • Device: Your device
2. Device agent process:
   • Polls for upload requests
   • Finds pending request
   • Uploads file to cloud
   • Reports success
3. Verify:
   • File appears in cloud storage
   • File content is correct
   • Upload timestamp is recent

Example 5: Testing Multiple Devices

Setup

1. Install device agent on multiple devices:
   • Device 1: Your laptop (macOS)
   • Device 2: Your desktop (Windows)
2. Register both devices in dashboard
3. Start both device agents

Test Steps

1. Search across all devices:
   • Query: important document
   • Scope: files
   • Devices: All devices
2. Expected Result:

   {
     "results": [
       {
         "device": { "name": "My Laptop" },
         "files": [
           { "path": "/Users/name/Documents/doc1.pdf" }
         ]
       },
       {
         "device": { "name": "My Desktop" },
         "files": [
           { "path": "C:\\Users\\name\\Documents\\doc2.pdf" }
         ]
       }
     ]
   }
   

3. Verify:
   • Results from both devices
   • Correct file paths for each platform
   • All devices responded

Example 6: Testing Error Handling

Setup

1. Start device agent
2. Simulate network issues or invalid API key

Test Scenarios

Scenario A: Invalid API Key

1. Change API key in agent to invalid value
2. Observe behavior:
   • Agent should log authentication error
   • Device shows as "Offline" in dashboard
   • No searches are processed
3. Fix: Restore correct API key

Scenario B: Network Interruption

1. Disconnect internet temporarily
2. Observe behavior:
   • Agent logs connection errors
   • Device shows as "Offline"
   • Agent retries with exponential backoff
3. Reconnect: Agent should automatically reconnect

Scenario C: Server Unavailable

1. Stop Sulala server (if testing locally)
2. Observe behavior:
   • Agent logs server errors
   • Device shows as "Offline"
   • Agent continues retrying
3. Restart server: Agent should reconnect automatically

Example 7: Custom Search Implementation

JavaScript Agent Custom Search

// Custom search function in device agent
async function customSearch(query, scope) {
  const results = {
    files: [],
    apps: [],
    system: {}
  };
  
  if (scope.includes('files')) {
    // Custom file search logic
    results.files = await searchFiles(query);
  }
  
  if (scope.includes('apps')) {
    // Custom app search logic
    results.apps = await searchApps(query);
  }
  
  return results;
}

Flutter Agent Custom Search

// Custom search function in Flutter agent
Future<SearchResults> customSearch(String query, List<String> scope) async {
  final results = SearchResults();
  
  if (scope.contains('files')) {
    results.files = await searchFiles(query);
  }
  
  if (scope.contains('apps')) {
    results.apps = await searchApps(query);
  }
  
  return results;
}

Example 8: Testing Performance

Measure Search Latency

1. Start agent and dashboard
2. Initiate search and measure:
   • Time from search request to device polling
   • Time for device to execute search
   • Time for results to appear in dashboard
3. Expected Performance:
   • Polling delay: ~30 seconds (normal)
   • Search execution: < 5 seconds (depends on query)
   • Total time: ~35-60 seconds

Optimize Performance

1. Reduce polling interval (more battery usage):

   // Change from 30s to 10s
   setInterval(pollForSearches, 10000);
   

2. Limit search scope for faster results:

   {
     "scope": ["files"]  // Only search files, not apps/system
   }
   

Example 9: Integration Testing

Test Complete Workflow

1. Setup:
   • Start device agent
   • Create test files
   • Register device in dashboard
2. Test Sequence:

   1. Send heartbeat → Verify device online
   2. Create search query → Verify pending status
   3. Device polls → Verify query received
   4. Device searches → Verify local search works
   5. Device reports results → Verify results stored
   6. Dashboard polls → Verify results displayed
   

3. Verify Each Step:
   • Check logs at each step
   • Verify API responses
   • Check dashboard updates

Example 10: Production Testing

Pre-Production Checklist

• Device agent runs on startup
• Device stays online consistently
• Searches return accurate results
• File uploads work correctly
• Error handling works properly
• Logs are properly configured
• API keys are secure
• Network interruptions handled gracefully

Production Monitoring

1. Monitor device status:
   • Check dashboard for offline devices
   • Review agent logs for errors
   • Monitor heartbeat frequency
2. Monitor search performance:
   • Track search success rate
   • Monitor search latency
   • Review error rates
3. Monitor system resources:
   • CPU usage
   • Memory usage
   • Network bandwidth

Troubleshooting Examples

Example: Device Shows Offline

Problem: Device appears offline in dashboard

Debug Steps:

1. Check agent is running: ps aux | grep agent
2. Check API key is correct
3. Check network connectivity: curl https://sulala.ai/api/health
4. Review agent logs for errors
5. Verify heartbeat is being sent

Example: Search Returns No Results

Problem: Search completes but returns empty results

Debug Steps:

1. Verify search scope is correct
2. Check file permissions
3. Verify search paths are correct
4. Test search locally first
5. Review agent search logs

Next Steps

• API Reference - Complete API documentation
• Architecture - How the system works
• Troubleshooting - Common issues and solutions