Kappapps SDK

Appearance

Class: AppsService ​

Service for launching another app or widget and waiting for its result.

Remarks ​

Available everywhere via k.apps. You never instantiate it yourself — the SDK creates it when the app/widget starts.

Unlike AppServiceService.call | `k.services.call` (which calls a function of an app that is already running), this service launches a target, lets it live (it can show UI, interact with viewers…), and resolves with the data the target returns when it calls kapp.finish(result).

Two kinds of target can be launched:

  • an installed app, identified by its slug — `runApp`;
  • a channel widget, identified by its numeric id — `runWidget`.

`run` is the generic launcher: it takes a discriminated target { type:'app', slug } | { type:'widget', id } and dispatches to the right one — handy to consume a target chosen by the streamer through a preference input.

Every launcher never throws: it always resolves a RunResult — on success { resolved: true, data }, otherwise { resolved: false, reason }.

Example ​

ts
// generic: target comes from a preference, no manual branching
const r = await k.apps.run(myPrefTarget, { question: 'Pick a color' });

// explicit shortcuts:
await k.apps.runApp('color-picker', { question: 'Pick a color' });
await k.apps.runWidget(42, { foo: 'bar' });

Implements ​

Methods ​

list() ​

ts
list(): Promise<Runnable[]>;

Liste toutes les cibles lançables du channel (applis et widgets), chaque entrée taguée par son type ('app' / 'widget') — même forme discriminée que `run`. Sert à découvrir d'un coup tout ce qu'on peut lancer ; filtre par type au besoin.

Returns ​

Promise<Runnable[]>

La liste unifiée des Runnable (vide si aucune).

Example ​

ts
const all = await k.apps.list();
const apps    = all.filter(x => x.type === 'app');
const widgets = all.filter(x => x.type === 'widget');

See ​

listApps / listWidgets pour les listes typées par type.

listApps() ​

ts
listApps(): Promise<AppRunnable[]>;

Liste les applis installées sur le channel et appelables via `runApp`, avec leur schéma d'arguments et de sortie déclaré. Sert à découvrir le slug et le contrat d'une appli plutôt que de les coder en dur.

Returns ​

Promise<AppRunnable[]>

La liste des AppRunnable (vide si aucune).

Example ​

ts
const apps = await k.apps.listApps();
const draw = apps.find(a => a.title === 'Tirage');
if (draw) await k.apps.runApp(draw.slug, { count: 3 });

See ​

runApp pour lancer une appli.

listWidgets() ​

ts
listWidgets(): Promise<WidgetRunnable[]>;

Liste les widgets activés du channel et lançables via `runWidget`, avec leur schéma d'arguments déclaré. Sert à découvrir l'id et les arguments d'un widget plutôt que de les coder en dur (l'id est numérique et local au channel).

Returns ​

Promise<WidgetRunnable[]>

La liste des WidgetRunnable (vide si aucun).

Example ​

ts
const widgets = await k.apps.listWidgets();
const w = widgets.find(x => x.name === 'Tirage');
if (w) await k.apps.runWidget(w.id, { count: 3 });

See ​

runWidget pour lancer un widget.

run() ​

ts
run(
   target, 
   args?, 
options?): Promise<RunResult>;

Generic launcher: launches an app or a widget depending on the target shape, and waits for the data it returns when it finishes.

Parameters ​

target ​

RunTarget

The target to launch — a discriminated union: { type: 'app', slug } (app by slug) or { type: 'widget', id } (widget by id). This is the shape produced by a runapp/runwidget preference input, so you can pass it straight from your preferences without branching on the type yourself.

args? ​

Record<string, any> = {}

Free data passed to the launched target, available there via kapp.arguments.

options? ​

RunOptions

Optional call options — see RunOptions.

Returns ​

Promise<RunResult>

A RunResult. Never rejects.

Remarks ​

If target is malformed (unknown type, missing slug/id), resolves { resolved: false, reason: 'invalid_target' }. A numeric widget id given as a string is coerced automatically (preference/form values are strings).

See ​

runApp / runWidget for the explicit, typed shortcuts.

runApp() ​

ts
runApp(
   appliSlug, 
   args?, 
options?): Promise<AppRunResult>;

Launches an installed app (by its slug) and waits for the data it returns when it finishes.

Parameters ​

appliSlug ​

string

Slug of the app to launch (its stable public identifier, the same value returned by `listApps`). The app must be installed on the channel and support overlay execution.

args? ​

Record<string, any> = {}

Free data passed to the launched app, available there via kapp.arguments.

options? ​

AppRunOptions

Optional call options — see AppRunOptions.

Returns ​

Promise<AppRunResult>

An AppRunResult. Never rejects.

Remarks ​

If an instance of the target app is already running, the call resolves { resolved: false, reason: 'busy' }. If the app finishes without returning data, { resolved: false, reason: 'no_result' }. If it does not finish within the timeout, { resolved: false, reason: 'timeout' }. The timeout ends the wait; it does not close the launched app.

See ​

AppServiceService.call | k.services.call to call an already-running app.

runWidget() ​

ts
runWidget(
   widgetId, 
   args?, 
options?): Promise<WidgetRunResult>;

Launches a widget (by its numeric id) and waits for the data it returns when it finishes.

Parameters ​

widgetId ​

number

Id of the widget to launch (numeric, local to the channel — the same value returned by `listWidgets`).

args? ​

Record<string, any> = {}

Free data passed to the launched widget, available there via kapp.arguments.

options? ​

WidgetRunOptions

Optional call options — see WidgetRunOptions.

Returns ​

Promise<WidgetRunResult>

A WidgetRunResult. Never rejects.

Remarks ​

If the widget finishes without returning data, resolves { resolved: false, reason: 'no_result' }. If it does not finish within the timeout, { resolved: false, reason: 'timeout' }. Several instances of the same widget can run concurrently — each call waits for its own.

See ​

runApp to launch an app instead.