App Service

​

Overview

​

Location

​

Key Responsibilities

​

1. App Registry Management

• Maintains both system apps and user-installed apps
• Provides app discovery and retrieval
• Manages app metadata and configurations

​

2. App Authentication

• Validates API keys for app connections
• Generates and manages app tokens
• Handles app-specific security

​

3. Webhook Orchestration

• Manages webhook endpoints for apps
• Handles session lifecycle webhooks (start/stop)
• Implements retry logic for failed webhooks
• Supports tool call webhooks for app interactions

​

4. App State Management

• Tracks app states across user sessions
• Manages app installation and permissions
• Handles pre-installed app configurations

​

Core Methods

​

getAllApps(userId?: string)

• System apps (hardcoded for reliability)
• User-installed apps from MongoDB
• Pre-installed apps based on environment

const apps = await appService.getAllApps('user@example.com');
// Returns array of AppI objects

​

getApp(packageName: string)

const app = await appService.getApp('com.translator.app');

​

validateApiKey(packageName: string, apiKey: string)

const isValid = await appService.validateApiKey(
  'com.translator.app',
  'app_api_key_here'
);

​

generateAppToken(packageName: string, userId: string, sessionId: string)

const token = await appService.generateAppToken(
  'com.translator.app',
  'user@example.com',
  'session-123'
);

​

Webhook System

​

Session Webhooks

​

Start Webhook

// Called when app starts
{
  url: 'https://app.example.com/webhook/start',
  headers: { 'X-App-Secret': 'secret' }
}

// Payload sent:
{
  type: 'session.start',
  sessionId: 'session-123',
  userId: 'user@example.com',
  capabilities: { /* device capabilities */ }
}

​

Stop Webhook

// Called when app stops
{
  type: 'session.stop',
  sessionId: 'session-123',
  reason: 'user_requested' | 'session_ended' | 'error'
}

​

Tool Call Webhooks

// Tool webhook request
{
  type: 'tool.call',
  toolName: 'translate',
  parameters: {
    text: 'Hello',
    targetLanguage: 'es'
  },
  sessionId: 'session-123'
}

// Expected response
{
  success: true,
  result: 'Hola'
}

​

Pre-installed Apps

​

Production Apps

const PRE_INSTALLED = [
  "com.augmentos.livecaptions",
  "cloud.augmentos.notify", 
  "cloud.augmentos.mira"
];

​

Debug/Development Apps

• Testing apps
• Developer tools
• Experimental features

​

App State Tracking

// Structure: userId -> packageName -> AppState
private appStates = new Map<string, Map<string, AppState>>();

• INITIALIZING: App is starting up
• CONNECTED: App is ready
• RESURRECTING: App is reconnecting
• STOPPED: App has been terminated

​

Integration with Other Services

​

With AppManager

• AppService provides app metadata
• AppManager handles runtime lifecycle

​

With SessionService

• Apps are associated with user sessions
• Session events trigger app webhooks

​

With MongoDB

• App definitions stored in apps collection
• User app installations tracked in users collection

​

Configuration

​

Environment Variables

• SYSTEM_DASHBOARD_PACKAGE_NAME: Package name for system dashboard
• NODE_ENV: Determines if debug apps are loaded
• DEBUG_APPS: Force load debug apps in production

​

System Apps

• Dashboard app
• System utilities
• Core functionality apps

​

Security Considerations

1. API Key Hashing: All API keys are hashed before storage
2. Webhook Secrets: Optional endpoint secrets for webhook verification
3. Token Expiration: App tokens have limited lifetime
4. Permission Validation: Apps must declare required permissions

​

Future Improvements

1. Database Migration: Move system apps to database
2. Service Splitting: Separate into:
   • appstore.service.ts: App store functionality
   • developer.service.ts: Developer portal features
   • tools.service.ts: Tool execution system
3. Caching Layer: Add Redis for app metadata caching
4. Webhook Queue: Implement proper webhook queue with retries

​

Usage Example

// In AppManager when app connects
const app = await appService.getApp(packageName);
if (!app) {
  throw new Error('App not found');
}

// Validate API key
const valid = await appService.validateApiKey(packageName, apiKey);
if (!valid) {
  throw new Error('Invalid API key');
}

// Generate session token
const token = await appService.generateAppToken(
  packageName,
  userId,
  sessionId
);

// Send start webhook
await appService.sendWebhook(app.webhooks?.start, {
  type: 'session.start',
  sessionId,
  userId
});

​

Best Practices

1. Always validate app existence before operations
2. Use try-catch for webhook calls - they can fail
3. Log webhook failures but don’t crash the session
4. Cache app metadata when possible
5. Validate permissions before granting access