### Creating an App Server

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/sdk/getting-started.mdx

Example of creating a custom AppServer class and instantiating it with configuration.

```typescript
import { AppServer, AppSession } from '@mentraos/sdk';

// Extend AppServer to create your app
class MyAppServer extends AppServer {
  // Override onSession to handle new user sessions
  protected async onSession(
    session: AppSession,
    sessionId: string,  // Format: "userId-packageName" 
    userId: string      // User's email address
  ): Promise<void> {
    // Your app logic goes here
    console.log(`New session ${sessionId} for user ${userId}`);
  }
}

// Create instance with configuration
const server = new MyAppServer({
  packageName: 'com.yourcompany.yourapp',  // Your app's unique identifier
  apiKey: process.env.MENTRAOS_API_KEY!,    // Your API key from dev portal
  port: 3000,                               // Port to listen on (default: 7010)
  publicDir: './public'                     // Optional: static files directory
});
```

--------------------------------

### Handling Sessions

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/sdk/getting-started.mdx

Example of handling new user sessions, setting up event handlers, and showing initial UI.

```typescript
protected async onSession(
  session: AppSession,    // Session instance for this user
  sessionId: string,      // Session ID (format: "userId-packageName")
  userId: string          // User's email address
): Promise<void> {
  console.log(`New session ${sessionId} for user ${userId}`);
  
  // Set up event handlers
  session.events.onTranscription((data) => {
    // Handle speech-to-text
  });
  
  session.events.onButtonPress((data) => {
    // Handle button presses
  });
  
  // Show initial UI
  await session.layouts.showTextWall('Welcome!');
}
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/QUICK-START.md

Copies the example environment file and instructs to add the API key.

```bash
cp .env.example .env
```

```env
PORT=3333
PACKAGE_NAME=com.mentra.captions
MNTRAOS_API_KEY=your_api_key_here
NODE_ENV=development
```

--------------------------------

### TypeScript Configuration

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/sdk/getting-started.mdx

Example tsconfig.json for strict TypeScript.

```json
// tsconfig.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "lib": ["ES2022"],
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "allowJs": false,
    "types": ["bun-types"]
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}
```

--------------------------------

### Install and Run iOS Example

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/examples.mdx

Navigate to the iOS examples directory, install pods, and open the workspace.

```bash
cd examples/ios
pod install
open MentraExample.xcworkspace
```

--------------------------------

### Install and Run Android Example

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/examples.mdx

Navigate to the Android examples directory and install the debug build.

```bash
cd examples/android
./gradlew installDebug
```

--------------------------------

### Cloud Setup Commands

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/development/local-setup.mdx

Commands to install dependencies and start the cloud service locally using Bun and Docker.

```bash
cd MentraOS/cloud/
bun install
bun run dev
```

--------------------------------

### Install the SDK

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/quickstart.mdx

Install the MentraOS SDK using Bun.

```bash
bun add @mentraos/sdk
```

--------------------------------

### Install and Run React Native / Expo Example

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/examples.mdx

Navigate to the React Native examples directory, install dependencies, and run the app on iOS or Android.

```bash
cd examples/react-native
bun install
bunx expo prebuild
bunx expo run:ios
# or
bun run android:dev
```

--------------------------------

### Basic Bluetooth Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/asg_client/app/src/main/java/com/mentra/asg_client/io/bluetooth/README.md

Demonstrates how to get a Bluetooth manager, initialize it, register for state changes, and start advertising.

```java
// Get the appropriate Bluetooth manager for the device
IBluetoothManager bluetoothManager = BluetoothManagerFactory.getBluetoothManager(context);

// Initialize the manager
bluetoothManager.initialize();

// Register a listener for state changes
bluetoothManager.addBluetoothListener(new BluetoothStateListener() {
    @Override
    public void onConnectionStateChanged(boolean connected) {
        if (connected) {
            Log.d("Bluetooth", "Connected to companion device");
        } else {
            Log.d("Bluetooth", "Disconnected from companion device");
        }
    }

    @Override
    public void onDataReceived(byte[] data) {
        Log.d("Bluetooth", "Received " + data.length + " bytes");
        // Process received data
    }
});

// Start advertising (for non-K900 devices)
bluetoothManager.startAdvertising();
```

--------------------------------

### Install Pods (iOS)

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/quickstart.mdx

Install the CocoaPods for your iOS project after adding the Mentra Bluetooth SDK.

```bash
pod install
```

--------------------------------

### Install App

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/cloud-architecture/data-models/user-model.mdx

Example of how to install an application for the user.

```typescript
await user.installApp('com.translator.app');
```

--------------------------------

### Ngrok Example for Production Testing

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/AUTH-GUIDE.md

Provides bash commands to start the development server and expose it using ngrok, enabling testing of the OAuth flow before full production deployment.

```bash
# Start your app
bun run dev

# In another terminal, expose it
ngrok http 3333

# Visit the ngrok URL
https://your-subdomain.ngrok.app/mentra-auth
```

--------------------------------

### Install Dependencies

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/development/local-setup.mdx

Installs all dependencies for the cloud packages.

```bash
bun install
```

--------------------------------

### Install ngrok

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/hono-example-app/README.md

Command to install ngrok using Homebrew.

```bash
brew install ngrok
```

--------------------------------

### Install Dependencies in Workspace

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Command to install all project dependencies after setting up the workspace.

```bash
cd cloud
bun install
```

--------------------------------

### Cloud Import Example

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of how the cloud service should import types from the @mentra/types package.

```typescript
import { AppletInterface } from '@mentra/types'
```

--------------------------------

### Quick Start Example

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/cloud-client/docs/README.md

Demonstrates basic usage of the MentraClient for connecting, interacting with apps, and handling audio.

```typescript
import { MentraClient } from '@augmentos/cloud-client';

const client = new MentraClient({
  email: 'user@example.com',
  serverUrl: 'ws://localhost:3001'
});

// Connect and interact
await client.connect();
await client.startApp('com.augmentos.translator');
client.lookUp();
await client.startSpeakingFromFile('./audio/hello-world.wav');
client.lookDown();
await client.disconnect();
```

--------------------------------

### Local Demo Helper Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/camera-streaming.mdx

Commands to clone the starter kit repository and run the local demo helper server.

```bash
git clone https://github.com/Mentra-Community/Mentra-Bluetooth-SDK-Starter-Kit.git
cd Mentra-Bluetooth-SDK-Starter-Kit
python3 examples/local-demo-cloud/server.py
```

--------------------------------

### Cloud Backend Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/os-devs/contributing/overview.mdx

Commands to set up the cloud backend, including dependency installation, Docker network setup, and starting the development environment.

```bash
cd MentraOS/cloud

# Install dependencies
bun install

# Setup Docker network
bun run dev:setup-network

# Start development environment
./scripts/docker-setup.sh
# or
bun run setup-deps
bun run dev
```

--------------------------------

### Local Development Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/livekit-grpc/README.md

Commands to install dependencies and start the local development environment.

```bash
cd MentraOS-2/cloud/packages/cloud && bun install
cd ../.. && docker-compose -f docker-compose.dev.yml up
```

--------------------------------

### Getting All Auth Information

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/AUTH-GUIDE.md

Example of using `getAuthInfo` to retrieve all authentication-related details at once.

```typescript
const {userId, hasSession, isAuthenticated} = getAuthInfo(req)
return Response.json({userId, hasSession, isAuthenticated})
```

--------------------------------

### Customize the Webview

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/QUICK-START.md

Example of customizing the React webview component.

```typescript
export function App() {
  return (
    <div className="container mx-auto p-8">
      <h1 className="text-3xl font-bold">My Custom App!</h1>
    </div>
  )
}
```

--------------------------------

### Clone the Starter Kit

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/examples.mdx

Clone the Mentra Bluetooth SDK Starter Kit repository and navigate into the directory.

```bash
git clone https://github.com/Mentra-Community/Mentra-Bluetooth-SDK-Starter-Kit.git
cd Mentra-Bluetooth-SDK-Starter-Kit
```

--------------------------------

### Troubleshooting: Build Fails

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of a TypeScript build error and its potential cause.

```bash
error TS2304: Cannot find name 'HardwareType'
```

```bash
# Fix: Ensure all imports in `src/index.ts` are correct and files exist.
```

--------------------------------

### Basic Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/app-devs/core-concepts/app-server.mdx

This is the basic setup for a MiniAppServer, including importing necessary components, creating an instance, registering callbacks, and starting the server.

```typescript
import { MiniAppServer, type MentraSession } from "@mentra/sdk";

const app = new MiniAppServer({
  packageName: "com.example.myapp",
  apiKey: process.env.API_KEY!,
  port: 3000,
});

app.onSession((session: MentraSession) => {
  // Your app logic goes here - this runs once per user
});

await app.start();
```

--------------------------------

### Set Your API Key

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/quickstart.mdx

Create a .env file to store your MentraOS API key.

```bash
MENTRAOS_API_KEY=your_api_key_here
```

--------------------------------

### List MentraOS Packages

Source: https://github.com/mentra-community/mentraos/blob/dev/asg_client/ota_updater/README.md

Lists all installed packages on the Mentra Glasses that are related to 'augmentos'.

```bash
adb -s {GLASSES_IP} shell pm list packages | grep augmentos
```

--------------------------------

### Run Your App

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/quickstart.mdx

Run the MentraOS application using Bun.

```bash
bun run app.ts
```

--------------------------------

### Mobile Development Setup

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/os-devs/contributing/overview.mdx

Commands to clone the repository, install dependencies, and start the development server for the mobile application.

```bash
git clone https://github.com/Mentra-Community/MentraOS.git
cd MentraOS/mobile

npm install

# For iOS
cd ios && pod install && cd ..

# Start the development server
npm start

# Run on Android/iOS
npm run android
# or
npm run ios
```

--------------------------------

### Run Local Demo Cloud Helper

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/bluetooth-sdk/examples.mdx

Run the local demo cloud helper script from the repository root.

```bash
python3 examples/local-demo-cloud/server.py
```

--------------------------------

### Handle Glasses Sessions

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/QUICK-START.md

Example of handling sessions and transcriptions in the Captions App.

```typescript
protected async onSession(session: AppSession, sessionId: string, userId: string) {
  // Display text on glasses
  session.layouts.showTextWall("Hello from Captions!")

  // Subscribe to transcription
  session.subscribe("transcription")

  // Handle transcriptions
  session.events.onTranscription((data) => {
    console.log("Caption:", data.text)
    session.layouts.updateText({ text: data.text })
  })
}
```

--------------------------------

### MentraOS Store - Development Server

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/development/local-setup.mdx

Commands to navigate to the store directory, install dependencies, and start the development server.

```bash
# Navigate to store directory
cd cloud/websites/store

# Install dependencies
bun install

# Start development server
bun run dev

# Opens at http://localhost:5173
```

--------------------------------

### Install Dependencies and Test

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/app-devs/getting-started/deployment/ubuntu-deployment.mdx

Navigates to the app directory, installs dependencies using Bun, copies the environment file, and starts the app for testing.

```bash
# Change to your app directory
cd /opt/myapp

# Install all dependencies
bun install

# Create your environment file from the example
cp .env.example .env

# Edit the environment file with your production values
nano .env

# Start your app in development mode
bun run src/index.ts
```

--------------------------------

### Build and Link Package

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/example-implementation.md

Commands to build and link the @mentra/types package.

```bash
# Build the types package
cd cloud/packages/types
bun run build

# Verify Bun compatibility
bun run src/index.ts  # Should output nothing (no errors)

# Link in workspace
cd ../..
bun install
```

--------------------------------

### Verification: Test Published Package

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/SDK-BUNDLING-SETUP.md

Steps to build, pack, and locally install the SDK to test the published package.

```bash
# Build and pack
bun run build
npm pack

# Install locally and test
npm install -g ./mentra-sdk-2.1.27.tgz
node -e "const { HardwareType } = require('@mentra/sdk'); console.log(HardwareType);"
```

--------------------------------

### Developer Console - Development Server

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/development/local-setup.mdx

Commands to navigate to the developer console directory, install dependencies, and start the development server.

```bash
# Navigate to developer portal
cd cloud/websites/console

# Install dependencies
bun install

# Start development server
bun run dev

# Opens at http://localhost:5174
```

--------------------------------

### Project Setup from Scratch (Android)

Source: https://github.com/mentra-community/mentraos/blob/dev/mobile/AGENTS.md

Commands to install dependencies and run the app on Android.

```bash
bun install
bun android
```

--------------------------------

### Migration Strategy: Phase 3 - Verify and Publish

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/SDK-BUNDLING-SETUP.md

Steps to verify bundling and publish the SDK.

```bash
1. Build SDK: `bun run build`
2. Verify bundling: `grep "@mentra/types" dist/index.js` (should be empty)
3. Test locally: `npm pack && npm install -g ./mentra-sdk-*.tgz`
4. Publish: `npm publish`
```

--------------------------------

### Importing Types in Cloud Services

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of how to import types from the @mentra/types package within cloud services.

```typescript
import {
  AppletInterface,
  HardwareRequirement,
  Capabilities,
} from "@mentra/types";

export class ClientAppsService {
  static async getAppsForHomeScreen(
    userId: string,
  ): Promise<AppletInterface[]> {
    // Implementation
  }
}
```

--------------------------------

### Mobile Type Imports

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of replacing local type definitions with imports from the @mentra/types package in the mobile app.

```typescript
// mobile/src/types/AppletTypes.ts
// Replace local definitions with imports
export { AppletInterface, AppletPermission, AppletType } from "@mentra/types";

// Keep mobile-specific utilities
export const isOfflineApp = (app: AppletInterface): boolean => {
  return app.isOffline === true;
};
```

--------------------------------

### Quick Start Example

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/cloud-client/README.md

Connect to the AugmentOS cloud, start an app, and play audio from a file.

```typescript
import { MentraClient } from '@augmentos/cloud-client';

const client = new MentraClient({
  email: 'user@example.com',
  serverUrl: 'ws://localhost:3001'
});

await client.connect();
await client.startApp('com.augmentos.translator');
client.lookUp();
await client.startSpeakingFromFile('./audio/hello-world.wav');
client.lookDown();
await client.disconnect();
```

--------------------------------

### Cloud Service App Mapping

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of mapping internal App model to client-facing AppletInterface in the cloud service.

```typescript
// packages/cloud/src/services/client/apps.service.ts
import { AppletInterface } from "@mentra/types";
import App from "../../models/app.model";

export class ClientAppsService {
  static async getAppsForHomeScreen(
    userId: string,
  ): Promise<AppletInterface[]> {
    const apps = await App.find({
      /* ... */
    });

    // Map AppI (internal) to AppletInterface (client-facing)
    return apps.map((app) => ({
      packageName: app.packageName,
      name: app.name,
      webviewUrl: app.webviewURL || "",
      logoUrl: app.logoURL,
      type: app.appType as AppletType,
      permissions: app.permissions || [],
      running: false, // From session
      healthy: true, // From cache
      hardwareRequirements: app.hardwareRequirements || [],
    }));
  }
}
```

--------------------------------

### Create Your App

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/quickstart.mdx

Example TypeScript code for a basic MentraOS application that displays a welcome message, listens for transcriptions, and responds to button presses.

```typescript
import { AppServer, AppSession } from '@mentraos/sdk';

// Extend AppServer and override onSession
class MyAppServer extends AppServer {
  protected async onSession(
    session: AppSession,
    sessionId: string, // Format: "userId-packageName"
    userId: string
  ): Promise<void> {
    console.log(`New session: ${sessionId} for user: ${userId}`);
    
    // Show welcome message
    await session.layouts.showTextWall('Hello from MentraOS!');
    
    // Listen for transcriptions
    session.events.onTranscription((data) => {
      console.log(`User said: ${data.text}`);
      
      // Respond to "hello"
      if (data.text.toLowerCase().includes('hello')) {
        session.layouts.showReferenceCard({
          title: 'Greeting',
          text: 'Hello! How can I help you today?'
        });
      }
    });
    
    // Listen for button presses
    session.events.onButtonPress((data) => {
      console.log(`Button pressed: ${data.buttonId}`);
      session.layouts.showTextWall('Button pressed!');
    });
  }
}

// Create and start the server
const server = new MyAppServer({
  packageName: 'com.example.myapp',
  apiKey: process.env.MENTRAOS_API_KEY!,
  port: 3000
});

await server.start();
console.log('App server running on port 3000');

```

--------------------------------

### Troubleshooting: Import Not Found

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Error message and fix for 'Cannot find module "@mentra/types"' by running `bun install`.

```bash
Cannot find module '@mentra/types'
```

```bash
# Fix: Run `bun install` in cloud root to link workspace packages.
```

--------------------------------

### Project Setup from Scratch (iOS)

Source: https://github.com/mentra-community/mentraos/blob/dev/mobile/AGENTS.md

Commands to install dependencies and run the app on iOS.

```bash
bun install
bun ios
```

--------------------------------

### Add Your Own API Routes - Express Routes

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/QUICK-START.md

Example of adding a new API route using Express, requiring a restart.

```typescript
expressApp.get("/api/my-endpoint", (req, res) => {
  const authReq = req as any
  if (!authReq.authUserId) {
    return res.status(401).json({error: "Not authenticated"})
  }
  res.json({message: "Hello!", userId: authReq.authUserId})
})
```

--------------------------------

### Add Your Own API Routes - Bun Routes

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/apps/captions/QUICK-START.md

Example of adding a new API route using Bun, with hot reload.

```typescript
import {requireAuth} from "./auth-helpers"

export const routes = {
  "/api/my-endpoint": requireAuth(async (req, userId) => {
    return Response.json({
      message: "Hello!",
      userId,
    })
  }),
}
```

--------------------------------

### Quick Example

Source: https://github.com/mentra-community/mentraos/blob/dev/docs/app-devs/core-concepts/led/overview.mdx

A basic example demonstrating how to import the SDK, initialize the MiniAppServer, and set the LED color on session start.

```typescript
import { MiniAppServer, type MentraSession } from "@mentra/sdk";

const app = new MiniAppServer({
  packageName: "com.example.led-demo",
  apiKey: process.env.API_KEY!,
  port: 3000,
});

app.onSession((session: MentraSession) => {
  // Green LED for 2 seconds
  session.led.setColor("green", 2000);
});

await app.start();
```

--------------------------------

### Quick Start

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/packages/sdk/README.md

Example of how to set up a basic MiniAppServer to receive and display transcribed text.

```typescript
import { MiniAppServer } from "@mentra/sdk";

const app = new MiniAppServer({
  packageName: "com.example.myapp",
  apiKey: process.env.API_KEY!,
  port: 3000,
});

app.onSession((session) => {
  session.transcription.on((data) => {
    session.display.showTextWall(data.text);
  });
});

await app.start();
```

--------------------------------

### Importing Types in Mobile Code

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Example of importing types from @mentra/types in mobile code, emphasizing the removal of local type definitions.

```typescript
import { AppletInterface, AppletPermission } from "@mentra/types";

// Remove old local type definitions
// export interface AppletInterface { ... } // DELETE THIS
```

--------------------------------

### Example Usage for Enhanced Script

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/udp-loadbalancer/setup-udp-service-script.md

Examples demonstrating the usage of the enhanced script with new flags for setting environment variables.

```bash
# Create UDP service + set env vars in both Porter and Doppler
./setup-udp-service.sh --app cloud-dev --cluster 4689 --set-env

# Create UDP service + only set in Porter (e.g., for debug)
./setup-udp-service.sh --app cloud-debug --cluster 4689 --set-porter-env

# Create UDP service + set in Doppler only (preparing for migration)
./setup-udp-service.sh --app cloud-prod --cluster 4696 --set-doppler-env

# Dry run to preview actions
./setup-udp-service.sh --app cloud-prod --cluster 4689 --set-env --dry-run

# Set env vars but don't trigger redeploy
./setup-udp-service.sh --app cloud-dev --cluster 4689 --set-porter-env --skip-redeploys
```

--------------------------------

### Deploy Backend

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/cli/IMPLEMENTATION.md

Steps to build and deploy the backend.

```bash
cd cloud/packages/cloud
bun run build
# Deploy to production

```

--------------------------------

### Example 2: Pre-flight Check

Source: https://github.com/mentra-community/mentraos/blob/dev/agents/tpa_triggers_wifi_setup_plan.md

Shows how to perform a pre-flight check for WiFi connectivity before attempting to start a stream, prompting the user to set up WiFi if necessary.

```typescript
const session = new AppSession({
  packageName: "com.example.streaming-app",
  apiKey: "your-key",
  userId: "user@example.com",
  appServer: myAppServer,
})

await session.connect("session-123")
await session.subscribe([StreamType.GLASSES_CONNECTION_STATE])

// Track WiFi state
let wifiConnected = session.getWifiStatus()?.connected || false

session.onGlassesConnectionState((state) => {
  wifiConnected = state.wifi?.connected || false
  updateUI({wifiConnected})
})

// On user clicking "Start Stream"
async function handleStartStream() {
  // Pre-flight check
  if (session.capabilities?.hasWifi && !wifiConnected) {
    const userWantsSetup = await showConfirmDialog({
      title: "WiFi Required",
      message: "Live streaming requires WiFi. Set up WiFi now?",
    })

    if (userWantsSetup) {
      session.requestWifiSetup("Required for RTMP streaming")
      return // Don't proceed - user will retry after setup
    } else {
      return // User canceled
    }
  }

  // Proceed with streaming
  try {
    await session.camera.startStream({
      rtmpUrl: getRtmpUrl(),
      video: getVideoSettings(),
    })
    showSuccess("Stream started!")
  } catch (error) {
    showError("Failed to start stream: " + error.message)
  }
}
```

--------------------------------

### PlayAudio (Server Streaming) - Go Server

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/livekit-grpc/proto-usage.md

Example of a Go server implementing the PlayAudio gRPC method, sending STARTED, PROGRESS, and COMPLETED events to the client.

```go
func (s *Service) PlayAudio(
    req *pb.PlayAudioRequest,
    stream pb.LiveKitBridge_PlayAudioServer,
) error {
    // Send STARTED event
    stream.Send(&pb.PlayAudioEvent{
        Type:      pb.PlayAudioEvent_STARTED,
        RequestId: req.RequestId,
    })

    // Download and decode audio
    // ...

    // Send PROGRESS events periodically
    stream.Send(&pb.PlayAudioEvent{
        Type:       pb.PlayAudioEvent_PROGRESS,
        RequestId:  req.RequestId,
        PositionMs: currentPos,
        DurationMs: totalDuration,
    })

    // Send COMPLETED event
    return stream.Send(&pb.PlayAudioEvent{
        Type:       pb.PlayAudioEvent_COMPLETED,
        RequestId:  req.RequestId,
        DurationMs: totalDuration,
    })
}
```

--------------------------------

### Environment Variables

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/sdk/getting-started.mdx

Recommended environment variables for MentraOS apps.

```bash
# Required
MENTRAOS_API_KEY=your_api_key_here

# Optional
PORT=3000
LOG_LEVEL=info
```

--------------------------------

### Semver Type Versioning Example

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/issues/complete/client-apps-api/types-package-guide.md

Illustrates semantic versioning for type changes, showing minor (optional fields) and major (breaking changes) bumps.

```typescript
// v1.0.0 → v1.1.0 (non-breaking)
export interface AppletInterface {
  // ... existing fields
  installedDate?: Date; // New optional field - MINOR bump
}

// v1.1.0 → v2.0.0 (breaking)
export interface AppletInterface {
  // ... existing fields
  webviewUrl: string | null; // Changed from string - MAJOR bump
}
```

--------------------------------

### Get All Apps - Response Example

Source: https://github.com/mentra-community/mentraos/blob/dev/cloud/docs/api-reference/rest/app-management.mdx

Example JSON response for Get All Apps.

```json
{
  "success": true,
  "data": [
    {
      "_id": "app123",
      "packageName": "com.example.app",
      "name": "Example App",
      "description": "An example app",
      "logoURL": "https://cdn.example.com/icon.png",
      "appType": "STANDARD",
      "featured": false,
      "published": true,
      "minHardwareVersion": "1.0.0",
      "requiredHardware": ["CAMERA", "DISPLAY"],
      "is_running": false,
      "lastActiveAt": "2024-01-20T10:30:00Z",
      "compatibility": {
        "isCompatible": true,
        "missingRequired": [],
        "missingOptional": [],
        "message": "Compatible with your device"
      }
    }
  ]
}
```