Unified Navigation

Overview

The Butler provides a unified navigation interface where users can see and jump to all their Butlers (both built-in and custom). Your Butler must register itself with The Butler to appear in this navigation, provide metadata for display, and handle deep links when users navigate to your Butler.

Butler Registration

To appear in The Butler's unified navigation, your Butler must register itself with the platform. This registration happens during Butler installation and includes metadata about your Butler.

Manifest Configuration

Declare your Butler's navigation metadata in the manifest file:

{
  "id": "my-butler",
  "name": "My Butler",
  "shortDescription": "A brief description of what your Butler does",
  "category": "Finance",
  "icon": "/butler-icon.png",
  "iconAlt": "Description of your Butler icon",
  "entryPoint": "/butlers/my-butler",
  "navigation": {
    "displayOrder": 5,
    "badge": null,
    "requiresAuth": false
  }
}

Registration API

During initialization, register your Butler with The Butler:

// Register Butler with navigation system
await window.lifeButler.registerButler({
  id: 'my-butler',
  name: 'My Butler',
  shortDescription: 'A brief description',
  category: 'Finance',
  icon: '/butler-icon.png',
  entryPoint: '/butlers/my-butler'
});

Deep Link Handling

When users navigate to your Butler from The Butler's unified interface, The Butler will open your Butler with a deep link. Your Butler must handle these navigation events.

Handle Navigation Events

// Listen for navigation events
window.lifeButler.onNavigate((path, params) => {
  // Handle navigation to specific screens within your Butler
  if (path === '/butlers/my-butler/details') {
    showDetailsScreen(params.id);
  } else {
    showHomeScreen();
  }
});

// Navigate within your Butler
window.lifeButler.navigate('/butlers/my-butler/details', { id: '123' });

Initial Context

When your Butler loads, check for initial navigation context:

window.lifeButler.onReady((context) => {
  const { initialPath, initialParams } = context;
  // Navigate to the requested screen if provided
  if (initialPath) {
    handleNavigation(initialPath, initialParams);
  }
});

Navigation Badges

Display badges on your Butler's navigation item to show unread counts, pending actions, or other status indicators.

// Update navigation badge
await window.lifeButler.updateNavigationBadge({
  butlerId: 'my-butler',
  badge: {
    count: 5,
    type: 'number' // 'number' | 'dot' | null
  }
});

// Clear badge
await window.lifeButler.updateNavigationBadge({
  butlerId: 'my-butler',
  badge: null
});

Requirements

• Register on install: Your Butler must register itself with The Butler during installation or first load.
• Handle deep links: Support navigation to specific screens within your Butler via deep links.
• Provide metadata: Include name, description, category, and icon for display in navigation.
• Update badges: Keep navigation badges up to date to reflect current state (unread counts, pending items, etc.).