bbs-sdk
Version:
SDK for building apps for the TT-BBS system
252 lines (251 loc) • 6.61 kB
TypeScript
/**
* Type definitions for the TT-BBS App API
*
* These types define the interfaces that BBS apps must implement
* to be compatible with the TT-BBS system.
*/
/**
* BBS App interface
*
* All BBS apps must implement this interface to be loaded by the system.
*/
export interface BbsApp {
/**
* Unique identifier for the app
* Use a short, lowercase string with no spaces
*/
id: string;
/**
* Display name of the app
* This is shown to users in the main menu
*/
name: string;
/**
* Version of the app
* Use semantic versioning (e.g. 1.0.0)
*/
version: string;
/**
* Brief description of the app
* This may be shown to users in the app list or help screens
*/
description: string;
/**
* Author of the app
* Your name or organization
*/
author: string;
/**
* Optional source URL of the app
* This is used for tracking where the app was loaded from (e.g., GitHub URL)
*/
source?: string;
/**
* Get the welcome screen content
* This is displayed when a user first enters the app
*
* @returns A string containing the welcome screen text
*/
getWelcomeScreen: () => string;
/**
* Handle user commands
* This is called whenever a user enters a command while using your app
*
* @param screenId The current screen ID (null for the initial screen)
* @param command The command entered by the user
* @param session The user's session data
* @returns A CommandResult object with the response and navigation info
*/
handleCommand: (screenId: string | null, command: string, session: BbsSession) => CommandResult;
/**
* Get help text for the current screen
* This is called when a user types HELP while using your app
*
* @param screenId The current screen ID
* @returns A string containing help text for the current screen
*/
getHelp: (screenId: string | null) => string;
/**
* (Optional) Initialize the app
* This is called when the app is first loaded by the system
*/
onInit: (injectedServices?: any) => void;
/**
* (Optional) Handle user entry to your app
* This is called when a user first enters your app
*
* @param userId The ID of the user
* @param session The user's session data
*/
onUserEnter?: (userId: string, session: BbsSession) => void;
/**
* (Optional) Handle user exit from your app
* This is called when a user exits your app
*
* @param userId The ID of the user
* @param session The user's session data
*/
onUserExit?: (userId: string, session: BbsSession) => void;
}
/**
* Command Result interface
*
* This is returned by the handleCommand method of BBS apps
* to tell the system how to respond to the user's command.
*/
export interface CommandResult {
/**
* The screen to display next
* - If a string, the system will navigate to that screen within your app
* - If null, the system will exit your app and return to the main menu
*/
screen: string | null;
/**
* Text response to display to the user
*/
response: string;
/**
* Whether to refresh the entire screen
* - true: Replace the entire screen with the response
* - false: Append the response to the current screen
*/
refresh: boolean;
/**
* (Optional) Additional data to pass to the client
* This can be used for custom behavior in the terminal UI
*/
data?: any;
/**
* (Optional) The area to navigate to
* This is used by the system for internal routing between apps/screens
* Apps shouldn't need to set this directly as it's handled by the core system
*/
area?: string;
}
/**
* Session interface
*
* This represents a user's session data.
*/
export interface BbsSession {
/**
* Unique identifier for the session
*/
sessionId: string;
/**
* User ID, if the user is logged in
*/
userId?: string;
/**
* Username, if the user is logged in
*/
username?: string;
/**
* Current area in the format "appId:screenId" or "main"
*/
currentArea: string;
/**
* Command history for this session
*/
commandHistory: string[];
/**
* Custom session data that apps can use
*/
data: Record<string, any>;
}
/**
* User interface
*
* This represents a user of the BBS system.
*/
export interface BbsUser {
/**
* Unique identifier for the user
*/
id: string;
/**
* Username
*/
username: string;
/**
* Display name
*/
displayName: string;
/**
* Email address
*/
email?: string;
/**
* Bio or about text
*/
bio?: string;
/**
* Join date
*/
joinDate: string;
/**
* Last login date
*/
lastLogin: string;
}
/**
* Configuration for custom data persistence
*
* Apps can implement this interface to store custom data.
*/
export interface BbsStorage {
/**
* Get data from storage
*
* @param key The key to retrieve
* @returns The data or null if not found
*/
getData: (key: string) => Promise<any | null>;
/**
* Set data in storage
*
* @param key The key to store under
* @param data The data to store
* @returns Whether the operation was successful
*/
setData: (key: string, data: any) => Promise<boolean>;
/**
* Delete data from storage
*
* @param key The key to delete
* @returns Whether the operation was successful
*/
deleteData: (key: string) => Promise<boolean>;
}
/**
* Utility functions and helpers for BBS apps
*/
export interface BbsUtils {
/**
* Format a date string
*
* @param date The date to format
* @param format The format string
* @returns Formatted date string
*/
formatDate: (date: Date | string, format?: string) => string;
/**
* Generate ASCII art for text
*
* @param text The text to convert to ASCII art
* @returns ASCII art string
*/
generateAsciiArt: (text: string) => string;
/**
* Create a horizontal rule/separator line
*
* @param char The character to use (default: ▄)
* @param width The width of the line (default: 80)
* @returns The separator string
*/
createSeparator: (char?: string, width?: number) => string;
}
export interface CommandRequest {
sessionId: string;
command: string;
}