Skip to main content

TpaServer

TpaServer is the base class for creating Third Party Application (TPA) servers that handle webhook requests from AugmentOS Cloud to manage TPA sessions.

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

Constructor​

constructor(config: TpaServerConfig)

Parameters:

Methods​

getExpressApp()​

Exposes the internal Express app instance for adding custom routes or middleware.

getExpressApp(): express.Express

Returns: The Express application instance.

onSession() [protected]​

Override this method to handle the initiation of a new TPA session when a user starts your app. Implement your TPA's core logic here (e.g., setting up event listeners).

protected onSession(
  session: TpaSession, 
  sessionId: string, 
  userId: string
): Promise<void>

Parameters:

  • session: The TpaSession instance for this specific user session
  • sessionId: The unique identifier for this session
  • userId: The unique identifier for the user

Returns: A Promise that resolves when session initialization is complete

onStop() [protected]​

Override this method to handle cleanup when a TPA session is stopped by the user or system.

protected onStop(
  sessionId: string, 
  userId: string, 
  reason: string
): Promise<void>

Parameters:

  • sessionId: The unique identifier for the session being stopped
  • userId: The unique identifier for the user
  • reason: The reason the session was stopped ('user_disabled', 'system_stop', 'error')

Returns: A Promise that resolves when session cleanup is complete

onToolCall() [protected]​

Override this method to handle tool calls from Mira AI. This is where you implement your app's tool functionality.

For a comprehensive guide on implementing AI tools, see AI Tools.

protected onToolCall(
  toolCall: ToolCall
): Promise<string | undefined>

Parameters:

  • toolCall: A ToolCall object containing the tool ID, parameters, user ID, and timestamp

Returns: A Promise that resolves to an optional string response that will be sent back to Mira

Example:

protected async onToolCall(toolCall: ToolCall): Promise<string | undefined> {
  console.log(`Tool called: ${toolCall.toolId}`);
  console.log(`Tool call timestamp: ${toolCall.timestamp}`);
  console.log(`Tool call userId: ${toolCall.userId}`);
  
  if (toolCall.toolParameters && Object.keys(toolCall.toolParameters).length > 0) {
    console.log("Tool call parameter values:", toolCall.toolParameters);
  }

  if (toolCall.toolId === "add_todo") {
    const reminder = addReminder(
      toolCall.userId, 
      toolCall.toolParameters.todo_item as string, 
      toolCall.toolParameters.due_date as string | undefined
    );
    return `Added reminder: ${reminder.text}`;
  }

  return undefined;
}

start()​

Starts the TPA server, making it listen for incoming webhook requests.

start(): Promise<void>

Returns: A promise that resolves when the server has successfully started.

stop()​

Gracefully shuts down the TPA server, cleaning up all active sessions and resources.

stop(): void

generateToken() [protected]​

Generates a JWT token suitable for TPA authentication, typically used for webviews. See Token Utilities for more details.

protected generateToken(
  userId: string, 
  sessionId: string, 
  secretKey: string
): string

Parameters:

  • userId: The user's identifier
  • sessionId: The session identifier
  • secretKey: Your TPA's secret key (should match the one configured in AugmentOS Cloud)

Returns: The generated JWT token string

addCleanupHandler() [protected]​

Registers a function to be executed during the server's graceful shutdown process.

protected addCleanupHandler(handler: () => void): void

Parameters:

  • handler: The cleanup function to add

Configuration​

interface TpaServerConfig {
  /** Your unique TPA identifier (e.g., 'org.company.appname'). Must match console.augmentos.org. */
  packageName: string;
  
  /** Your API key obtained from console.augmentos.org for authentication. */
  apiKey: string;
  
  /** The port number the TPA server will listen on. Defaults to 7010. */
  port?: number;
  
  /** [DEPRECATED] The SDK automatically uses '/webhook'. Do not set. */
  webhookPath?: string;
  
  /** Path to a directory for serving static files (e.g., images, logos). Set to `false` to disable. Defaults to `false`. */
  publicDir?: string | false;
  
  /** [DEPRECATED] The WebSocket URL is provided dynamically via webhooks. Do not set. */
  augmentOSWebsocketUrl?: string;
  
  /** Whether to enable the `/health` endpoint for status checks. Defaults to `true`. */
  healthCheck?: boolean;
}