Skip to main content

TpaSession

TpaSession (also known as TpaClient in older documentation) manages an active WebSocket connection (session) between a TPA 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

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 TPA 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 TPA 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 TPA 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;
}