Kappapps SDK

Appearance

Class: UserService ​

Service for accessing the channel's viewers / Players: retrieve one or more users (by login or by id), list active viewers, and manage their currency, role, moderation and inventory through dedicated sub-services.

Remarks ​

Accessible everywhere via k.users. You never have to instantiate this service yourself — it is created by the SDK when the app/widget starts.

The sub-services are available as properties:

Example ​

ts
// Retrieve a viewer by their login, then read their currency
const user = await k.users.get('twitchdev');
if (user) {
    const balance = await k.users.currency.get(user.login);
    console.log(`${user.display_name} has ${balance} coins`);
}

Implements ​

Properties ​

currency ​

ts
currency: UserCurrencyService;

Sub-service for managing viewers' internal currency.

item ​

ts
item: UserItemService;

Sub-service for managing viewers' inventory / items.

moderation ​

ts
moderation: UserModerationService;

Moderation sub-service (timeout, ban, VIP, mod, blacklist…).

role ​

ts
role: UserRoleService;

Sub-service for managing viewers' Kappapps roles.

Methods ​

get() ​

Retrieves one or more viewers, by login (default) or by Twitch id.

Param ​

The identifier(s) to search for. A single value returns a User or null; an array returns an array of User.

Param ​

Search mode: 'login' (username, case-insensitive) or 'id' (numeric Twitch id).

Default Value ​

'login'

Remarks ​

Requests are grouped into batches (up to 100 identifiers) and sent in the background at a regular interval, to keep network calls to a minimum. The result is resolved through a promise as soon as the corresponding batch comes back.

With method: 'id', identifiers that are not finite numbers are discarded before any request: a single invalid id resolves to null, invalid entries of an array are ignored (a warning is logged to the console).

Example ​

ts
// By login (default)
const user = await k.users.get('twitchdev');

// Several viewers at once
const users = await k.users.get(['alice', 'bob']);

// By Twitch id
const byId = await k.users.get(123456, 'id');

Call Signature ​

ts
get(values, method?): Promise<User>;

Retrieves a viewer by their login (Twitch username).

Parameters ​
values ​

string

The login to search for (case-insensitive).

method? ​

"login"

Search mode ('login').

Returns ​

Promise<User>

The matching User, or null if not found.

Default Value ​

'login'

Call Signature ​

ts
get(values, method?): Promise<User[]>;

Retrieves several viewers by their logins.

Parameters ​
values ​

string[]

The list of logins to search for (case-insensitive).

method? ​

"login"

Search mode ('login').

Returns ​

Promise<User[]>

An array of User (only the viewers that were found are included).

Default Value ​

'login'

Call Signature ​

ts
get(values, method): Promise<User>;

Retrieves a viewer by their Twitch id.

Parameters ​
values ​

number

The Twitch id to search for.

method ​

"id"

Search mode ('id').

Returns ​

Promise<User>

The matching User, or null if not found — or if the id is not a finite number (no request is sent in that case).

Call Signature ​

ts
get(values, method): Promise<User[]>;

Retrieves several viewers by their Twitch ids.

Parameters ​
values ​

number[]

The list of Twitch ids to search for. Non-finite entries (NaN, undefined…) are ignored.

method ​

"id"

Search mode ('id').

Returns ​

Promise<User[]>

An array of User (only the viewers that were found are included).

getActiveUsers() ​

ts
getActiveUsers(options): User[];

Returns the list of active viewers (those who have written in the chat recently).

Parameters ​

options ​

GetActiveUsersOptions

Filters and sorting applied to the selection — see GetActiveUsersOptions for the details of each field (time, excludes, count, randomize, property).

Returns ​

User[]

An array of active User (empty if no one has spoken recently).

Remarks ​

A simple shortcut to k.chat.getActiveUsers: the list is kept up to date by the chat service.

Example ​

ts
const active = k.users.getActiveUsers({ time: 300, count: 10 });

getViewersDashboardUrl() ​

ts
getViewersDashboardUrl(): string;

Builds the URL of the channel's public viewers dashboard.

Returns ​

string

The absolute URL of the viewers page (e.g. https://…/viewers/MyChannel).

Example ​

ts
const url = k.users.getViewersDashboardUrl();
await k.chat.say(`See your ranking here: ${url}`);