Skip to main content

TpaSession

TpaSession (also known as TpaClient in older documentation) manages an active WebSocket connection (session) between an app instance and AugmentOS Cloud. It handles event subscriptions, layout display, and connection management for a single user session.

import { TpaSession } from '@augmentos/sdk';

Constructor​

constructor(config: TpaSessionConfig)

Parameters:

Properties​

events​

Provides access to the EventManager for subscribing to real-time events.

readonly events: EventManager

layouts​

Provides access to the LayoutManager for controlling the AR display.

readonly layouts: LayoutManager

settings​

Provides access to the SettingsManager for reading and monitoring app settings.

readonly settings: SettingsManager

Event Handling Methods​

onTranscription()​

Registers a handler for real-time speech transcription events.

onTranscription(handler: (data: TranscriptionData) => void): () => void

Parameters:

Returns: An unsubscribe function to remove the handler

onHeadPosition()​

Registers a handler for head position change events (e.g., 'up', 'down').

onHeadPosition(handler: (data: HeadPosition) => void): () => void

Parameters:

Returns: An unsubscribe function to remove the handler

onButtonPress()​

Registers a handler for hardware button press events on the glasses.

onButtonPress(handler: (data: ButtonPress) => void): () => void

Parameters:

  • handler: Callback function to process ButtonPress data

Returns: An unsubscribe function to remove the handler

onPhoneNotifications()​

Registers a handler for notifications received from the connected phone.

onPhoneNotifications(handler: (data: PhoneNotification) => void): () => void

Parameters:

Returns: An unsubscribe function to remove the handler

Subscription Methods​

subscribe()​

Informs the AugmentOS Cloud that this app session wants to receive events of the specified type.

subscribe(type: StreamType): void

Parameters:

on()​

Generic method to subscribe to any data stream type. Use specific on<EventType> methods where available.

on<T extends StreamType>(
  event: T,
  handler: (data: StreamDataTypes[T]) => void
): () => void

Parameters:

  • event: The StreamType to listen for
  • handler: Callback function to process the data associated with the stream type

Returns: An unsubscribe function to remove the handler

Connection Methods​

connect()​

Establishes the WebSocket connection to AugmentOS Cloud for this session.

connect(sessionId: string): Promise<void>

Parameters:

  • sessionId: The unique identifier for this session (provided by the SESSION_REQUEST webhook)

Returns: A promise that resolves upon successful connection and authentication, or rejects on failure

disconnect()​

Gracefully closes the WebSocket connection and cleans up resources for this session.

disconnect(): void

Settings Methods​

getSettings()​

Retrieves all current application settings for this user session.

getSettings(): AppSettings

Returns: A copy of the current AppSettings

getSetting()​

Retrieves the value of a specific application setting by its key.

getSetting<T>(key: string): T | undefined

Parameters:

  • key: The key of the setting to retrieve

Returns: The value of the setting, or undefined if not found or not set

setSubscriptionSettings()​

Configures the app session to automatically manage subscriptions based on changes to specific settings.

setSubscriptionSettings(options: {
  updateOnChange: string[];
  handler: (settings: AppSettings) => StreamType[];
}): void

Parameters:

  • options: Configuration object
    • options.updateOnChange: An array of setting keys that should trigger a subscription update when their value changes
    • options.handler: A function that takes the current AppSettings and returns an array of StreamType subscriptions that should be active

Configuration​

interface TpaSessionConfig {
  /** Your unique app identifier (e.g., 'org.company.appname'). */
  packageName: string;

  /** Your API key for authentication. */
  apiKey: string;

  /** The WebSocket URL provided by AugmentOS Cloud. Defaults to 'ws://localhost:8002/tpa-ws'. */
  augmentOSWebsocketUrl?: string;

  /** Whether the session should automatically attempt to reconnect if the connection drops. Defaults to `false`. */
  autoReconnect?: boolean;

  /** Maximum number of reconnection attempts if `autoReconnect` is true. Default: 0 (no limit). */
  maxReconnectAttempts?: number;

  /** Initial delay (in ms) before the first reconnection attempt. Delay increases exponentially. Defaults to 1000. */
  reconnectDelay?: number;
}