Kappapps SDK

Appearance

Class: ChatEventArg ​

Represents a chat command argument and provides typed conversions: raw text, number, viewer (User), date or URL.

Remarks ​

A ChatEventArg is obtained via ChatEvent.getArg(n) or ChatEvent.getArgs(); you never have to instantiate it yourself. Each conversion returns null if the argument is missing or does not match the expected format.

Example ​

ts
// !roll 6
k.chat.onCommand('roll', (user, event) => {
    const faces = event.getArg(1).number() ?? 6;
    k.chat.say(`🎲 ${1 + Math.floor(Math.random() * faces)}`);
});

Methods ​

date() ​

ts
date(options?): ArgDate;

Interprets the argument as a date and breaks it down into day / month / year.

Parameters ​

options? ​

Parsing options:

  • locale: 'EU' (day/month) or 'US' (month/day). Defaults to 'EU'.
  • twoDigitYearPivot: pivot used to resolve 2-digit years (≥ pivot → 19xx, otherwise 20xx). Defaults to 50.
locale? ​

"EU" | "US"

twoDigitYearPivot? ​

number

Returns ​

ArgDate

An ArgDate object ({ day, month, year }). If parsing fails, all three fields are null.

Remarks ​

Accepts the / or - separators as well as concatenated formats of 4, 6 or 8 digits (e.g. 0103, 010324, 01032024). The date is validated (days per month, leap years when the year is known).

Example ​

ts
// !birthday 31/12/1999
const d = event.getArg(1).date(); // { day: 31, month: 12, year: 1999 }

number() ​

ts
number(): number;

Returns the argument as a number, only if it consists exclusively of digits.

Returns ​

number

The number, or null if the argument is not a valid integer.

Remarks ​

Only accepts strings of digits (no sign, no decimal): '12' → 12, but '-3' and '1.5' → null.

raw() ​

ts
raw(): string;

Returns the raw value of the argument, exactly as typed in the chat.

Returns ​

string

The raw string, or null if the argument is missing.

See ​

string

string() ​

ts
string(): string;

Returns the argument as a string.

Returns ​

string

The string, or null if the argument is missing or empty.

url() ​

ts
url(): URL;

Interprets the argument as a URL and validates it.

Returns ​

URL

A URL object if the argument is a valid http/https URL (the https:// scheme is added when missing, for a domain, an IP or localhost), otherwise null.

Remarks ​

Only the http: and https: protocols are allowed; any other value (exotic scheme, text that cannot be read as a domain…) returns null.

Example ​

ts
// !link github.com/anthropics
const u = event.getArg(1).url(); // URL("https://github.com/anthropics")

user() ​

ts
user(): Promise<User>;

Resolves the argument as a viewer: interprets the value as a Twitch login and retrieves the matching User.

Returns ​

Promise<User>

The User found, or null if the argument is missing or not found.

Example ​

ts
// !whois @viewer
const target = await event.getArg(1).user();