@mentra/types

Shared TypeScript types for MentraOS client and cloud.

Purpose

Single source of truth for client-facing types used by both mobile app and cloud backend. Eliminates type drift and duplication.

What's Included

• AppletInterface - Minimal app interface for home screen (8 fields)
• HardwareRequirement - Hardware requirements for apps
• Capabilities - Device hardware capabilities
• AppletPermission - App permission types
• Enums: HardwareType, HardwareRequirementLevel

Installation

Already linked via Bun workspace. Just import:

import { AppletInterface, HardwareType, Capabilities } from "@mentra/types";

Development

# Build (compile TypeScript)
bun run build

# Watch mode
bun run dev

# Type check only
bun run typecheck

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

Bun Compatibility

This package uses explicit exports to work with Bun's runtime TypeScript execution:

// ✅ Types/Interfaces - export type
export type { AppletInterface, Capabilities } from "./applet";

// ✅ Enums (runtime) - export
export { HardwareType } from "./enums";

// ❌ Never use this (breaks Bun)
export * from "./applet";

See cloud/issues/todo/sdk-type-exports/README.md for details.

Usage Examples

In Cloud Services

import { AppletInterface } from "@mentra/types";

export class ClientAppsService {
  static async getAppsForHomeScreen(
    userId: string,
  ): Promise<AppletInterface[]> {
    // Return minimal interface for client
  }
}

In Mobile Client

import { AppletInterface, HardwareType } from "@mentra/types";

function renderAppList(apps: AppletInterface[]) {
  // Render home screen
}

What NOT to Include

• ❌ Internal database models (AppI, UserI)
• ❌ Service logic or business rules
• ❌ Validation schemas
• ❌ Complex SDK types (webhooks, tool schemas)
• ❌ Runtime dependencies

What to Include

• ✅ Client-facing app types
• ✅ Hardware capability types
• ✅ Permission types
• ✅ Shared enums
• ✅ Minimal DTOs

Adding New Types

1. Add type definition in appropriate file (applet.ts, hardware.ts, etc.)

2. Add explicit export in src/index.ts:

   // For types/interfaces
   export type { MyNewType } from "./file";
   
   // For enums/values
   export { MyNewEnum } from "./file";

3. Test Bun compatibility: bun run src/index.ts

4. Build: bun run build

5. Bump version in package.json (semver)

Versioning

• Major: Breaking changes to existing types
• Minor: New optional fields or new types
• Patch: Documentation, internal changes

Files

• src/enums.ts - Runtime enums (HardwareType, etc.)
• src/hardware.ts - Hardware capability types
• src/applet.ts - App/applet types for clients
• src/index.ts - Main export (Bun-compatible)

Links

• Design Docs
• Bun Export Pattern
• SDK Type Export Issue