> ## Documentation Index
> Fetch the complete documentation index at: https://cloud-docs.mentra.glass/llms.txt
> Use this file to discover all available pages before exploring further.

# App Service

> Core service for managing third-party applications in MentraOS

## Overview

The AppService (`app.service.ts`) is the central registry and management system for all third-party applications (TPAs) in MentraOS. It handles app discovery, authentication, webhook interactions, and maintains the app ecosystem.

## Location

`packages/cloud/src/services/core/app.service.ts`

## 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)`

Retrieves all available apps for a user, combining:

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

```typescript theme={null}
const apps = await appService.getAllApps('user@example.com');
// Returns array of AppI objects
```

### `getApp(packageName: string)`

Fetches a specific app by its package name.

```typescript theme={null}
const app = await appService.getApp('com.translator.app');
```

### `validateApiKey(packageName: string, apiKey: string)`

Validates an app's API key for authentication.

```typescript theme={null}
const isValid = await appService.validateApiKey(
  'com.translator.app',
  'app_api_key_here'
);
```

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

Creates a JWT token for app authentication.

```typescript theme={null}
const token = await appService.generateAppToken(
  'com.translator.app',
  'user@example.com',
  'session-123'
);
```

## Webhook System

### Session Webhooks

Apps can register webhooks to be notified of session events:

#### Start Webhook

```typescript theme={null}
// 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

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

### Tool Call Webhooks

Apps can expose tools that the system can call:

```typescript theme={null}
// 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

The service manages different app installation tiers:

### Production Apps

```typescript theme={null}
const PRE_INSTALLED = [
  "com.augmentos.livecaptions",
  "cloud.augmentos.notify", 
  "cloud.augmentos.mira"
];
```

### Debug/Development Apps

Additional apps loaded in development mode:

* Testing apps
* Developer tools
* Experimental features

## App State Tracking

The service maintains in-memory app states:

```typescript theme={null}
// Structure: userId -> packageName -> AppState
private appStates = new Map<string, Map<string, AppState>>();
```

States include:

* `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

Currently hardcoded for reliability, includes:

* 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

```typescript theme={null}
// 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