Kappapps SDK

Appearance

Abstract Class: App ​

Abstract base class for every app or widget execution on the platform. It is the global object accessible everywhere via k / kapp: it carries the execution lifecycle (display, finish, abort, exit hooks) and exposes all of the SDK's services (chat, viewers, medias, overlay, API, etc.) as public properties.

Remarks ​

You never instantiate this class yourself: the SDK builds an Appli or a Widget (which inherit from App) at startup, then exposes it globally. From an app's code you therefore access everything via k.xxx or kapp.xxx (both refer to the same object).

Example ​

ts
// React to a command, play a media, then finish the app cleanly
k.chat.onCommand('go', async () => {
    await k.medias.play('intro');
    k.finish();
});

Extended by ​

Implements ​

Properties ​

ai ​

ts
ai: AiService;

The AI service: calls to artificial intelligence models (text generation, etc.). See AiService.

Announce ​

ts
Announce: typeof AnnounceModel = AnnounceModel;

Reference to the AnnounceModel model class (shortcut k.Announce).

announces ​

ts
announces: AnnounceService;

The announces service: displaying visual announcements on the overlay. See AnnounceService.

api ​

ts
api: ApiService;

The API service: authenticated HTTP calls to the Kappapps backend. See ApiService.

app_type ​

ts
app_type: AppType;

apps ​

ts
apps: AppsService;

The apps service: launch another installed app (by slug) or a widget (by id) and await the data it returns when it finishes. Use runApp / runWidget, or the generic run(target). See AppsService.

arguments ​

ts
arguments: Record<string, any>;

Configuration arguments passed to the app/widget at launch (values entered by the streamer for this trigger). Arguments of type Player are automatically converted into User instances.

channel ​

ts
channel: ChannelService;

The channel service: information about the installed Twitch Channel (streamer, preferences, theme). See ChannelService.

chat ​

ts
chat: ChatService;

The Twitch chat service: sending messages and announcements, listening to viewers' messages and commands. See ChatService.

dashboard ​

ts
dashboard: DashboardService;

The dashboard service: integration with the streamer dashboard. See DashboardService.

discord ​

ts
discord: DiscordService;

The Discord service: sending messages/notifications to Discord. See DiscordService.

dom ​

ts
dom: DomService;

The DOM service: manipulating the app's document (loading scripts, DOM helpers). See DomService.

DOMPurify ​

ts
DOMPurify: DOMPurify;

Reference to the DOMPurify HTML sanitization library (shortcut k.DOMPurify).

emotes ​

ts
emotes: EmoteService;

The emotes service: fetching and rendering Twitch/third-party emotes. See EmoteService.

gameEngines ​

ts
gameEngines: GameEngineService;

The game engine service: Phaser integration for game-type apps. See GameEngineService.

ImageAtlas ​

ts
ImageAtlas: typeof KappappsImageAtlas = KappappsImageAtlas;

Standalone-compatible image atlas loader (shortcut k.ImageAtlas). Use k.ImageAtlas.load(url) to load atlases generated by the DEV HUB.

items ​

ts
items: ItemService;

The items service: rewards/objects purchasable with the Players' currency. See ItemService.

KAudio ​

ts
KAudio: typeof KAudio;

Reference to the KAudio audio media class (shortcut k.KAudio).

KImage ​

ts
KImage: typeof KImage;

Reference to the KImage image media class (shortcut k.KImage).

KMedia ​

ts
KMedia: typeof KMedia;

Reference to the KMedia generic media class (shortcut k.KMedia).

KVideo ​

ts
KVideo: typeof KVideo;

Reference to the KVideo video media class (shortcut k.KVideo).

localFiles ​

ts
localFiles: LocalFilesService;

Read files and directory indexes from the streamer's local HUB folder.

medias ​

ts
medias: MediaService;

The medias service: playback of images, sounds and videos on the overlay. See MediaService.

name ​

ts
name: string;

Name of the app/widget currently running.

overlay ​

ts
overlay: OverlayService;

The overlay service: controls the display (position, dimensions, OBS scenes) and communication with the display layer. See OverlayService.

poll ​

ts
poll: PollService;

The Kappapps polls service: platform-independent polls with chat and in-app voting. See PollService.

PQueue ​

ts
PQueue: typeof default;

Reference to the PQueue queue class (shortcut k.PQueue).

prediction ​

ts
prediction: PredictionService;

The Kappapps predictions service: viewers bet the channel currency on an outcome, winners share the pot. See PredictionService.

rcon ​

ts
rcon: RconService;

The RCON service: remote control of a game server via the RCON protocol. See RconService.

services ​

ts
services: AppServiceService;

The app services API: implement named functions and call services exposed by running apps or widgets on the same Channel. See AppServiceService.

statuses ​

ts
statuses: StatusService;

The stream statuses service: runtime state shared between apps during a live. See StatusService.

stream ​

ts
stream: StreamService;

The current stream service: identifier and start time of the live. See StreamService.

streamlabs ​

ts
streamlabs: StreamlabsService;

The Streamlabs service: integration with Streamlabs events. See StreamlabsService.

teams ​

ts
teams: TeamsService;

The channel's Kappapps teams and their members. See TeamsService.

textToSpeech ​

ts
textToSpeech: TextToSpeechService;

The text-to-speech service: have a text read aloud. See TextToSpeechService.

triggerRequest ​

ts
triggerRequest: TriggerRequest;

The trigger request that started this execution: who (the setter) and which event launched the app/widget.

twitch ​

ts
twitch: TwitchService;

The Twitch service: stream information (title, category…) and Twitch interactions. See TwitchService.

User ​

ts
User: typeof User;

Reference to the User model class (shortcut k.User).

users ​

ts
users: UserService;

The viewers / Players service: fetching and managing the channel's users (currency, ranking, inventory). See UserService.

Utils ​

ts
Utils: typeof Utils;

Reference to the Utils utility collection (shortcut k.Utils).

uuid ​

ts
uuid: string;

Unique identifier of this app/widget execution.

youtube ​

ts
youtube: YoutubeService;

The YouTube service: playback/embedding of YouTube content. See YoutubeService.

Methods ​

_setGlobalVariables() ​

ts
protected _setGlobalVariables(): void;

Returns ​

void

abort() ​

ts
abort(reason?): Promise<void>;

Interrupts the app/widget execution (abnormal or forced end): runs the exit hooks registered for an abort, then signals the abort to the overlay.

Parameters ​

reason? ​

string = null

Reason for the interruption, forwarded to the overlay (for logging/diagnostic purposes).

Returns ​

Promise<void>

A promise resolved once all asynchronous onBeforeAbort / onBeforeExit hooks have completed.

Default Value ​

null

Remarks ​

Unlike finish, abort does not explicitly hide the display before notifying the end. Reserve it for error cases or manual stops.

Example ​

ts
try {
    await playTheGame();
    k.finish();
} catch (err) {
    k.abort(String(err));
}

See ​

display() ​

ts
display(): void;

Displays the app/widget on the overlay (makes its display window visible).

Returns ​

void

Example ​

ts
k.display();

See ​

undisplay to hide it.

finish() ​

ts
finish(result?): Promise<void>;

Ends the app/widget execution cleanly: hides the display, runs the exit hooks registered for a normal finish, then signals the finish to the overlay.

Parameters ​

result? ​

any = undefined

Optional data returned to the app/widget that launched this one via `k.apps.run` (or runApp/runWidget). Ignored for a normally-started app. Can be any JSON-serializable value.

Returns ​

Promise<void>

A promise resolved once all asynchronous onBeforeFinish / onBeforeExit hooks have completed.

Remarks ​

Use this when the app has finished its work normally. For an abnormal interruption, use abort instead.

Example ​

ts
// Close the app once the game has been won
await k.finish();

// Close and return data to the caller (when launched via k.apps.run)
await k.finish({ winner: 'alice' });

See ​

isApp() ​

ts
isApp(): boolean;

Indicates whether this execution is an app (as opposed to a widget).

Returns ​

boolean

true if it is an app.

See ​

isWidget

isWidget() ​

ts
isWidget(): boolean;

Indicates whether this execution is a widget (as opposed to an app).

Returns ​

boolean

true if it is a widget.

See ​

isApp

onBeforeAbort() ​

ts
onBeforeAbort(handler): void;

Registers a hook run only on an abort (abort).

Parameters ​

handler ​

BeforeExitHandler

Cleanup function (synchronous or asynchronous) to run before the abort.

Returns ​

void

See ​

onBeforeExit() ​

ts
onBeforeExit(status?, handler): void;

Registers an exit hook called just before the execution ends, triggered according to the exit type (normal finish, abort, or both).

Parameters ​

status? ​

BeforeExitStatus = App.BEFORE_EXIT_STATUS_ALL

Exit type that triggers the hook: 'finish' (normal finish), 'abort' (interruption) or '*' (both).

handler ​

BeforeExitHandler

Cleanup function to run. Can be synchronous or asynchronous; asynchronous handlers are awaited before the exit completes.

Returns ​

void

Default Value ​

'*'

Remarks ​

To target a single exit type, prefer the shortcuts onBeforeFinish and onBeforeAbort.

Example ​

ts
// Save some state before any exit (finish or abort)
k.onBeforeExit('*', async () => {
    await k.dataStorage.set('lastRun', Date.now());
});

onBeforeFinish() ​

ts
onBeforeFinish(handler): void;

Registers a hook run only on a normal finish (finish).

Parameters ​

handler ​

BeforeExitHandler

Cleanup function (synchronous or asynchronous) to run before the finish.

Returns ​

void

See ​

undisplay() ​

ts
undisplay(): void;

Hides the app/widget on the overlay (makes its display window invisible) without ending the execution.

Returns ​

void

Remarks ​

Called automatically by finish before closing the execution.

See ​

display to show it again.