From 21c0c5db432c92dbeb7e24d395070af406db2ed0 Mon Sep 17 00:00:00 2001 From: qwerinope Date: Sat, 12 Apr 2025 19:18:58 +0200 Subject: [PATCH] Add basic documentation for helper functions --- src/lib/items.ts | 4 +++- src/lib/lootboxes.ts | 5 +++-- src/lib/timeoutHelper.ts | 5 +++++ src/lib/userHelper.ts | 18 +++++++++++++++--- 4 files changed, 26 insertions(+), 6 deletions(-) diff --git a/src/lib/items.ts b/src/lib/items.ts index 00bdad9..7a4a42f 100644 --- a/src/lib/items.ts +++ b/src/lib/items.ts @@ -8,7 +8,9 @@ interface itemChangeResult { count: number, inv?: inventory } - +/** Check if the target user can use/lose item(s) and return the new inventory + * @param [amount=-1] If not specified, reduce count by one + * @param [preconfirmed=false] If it is confirmed that the change is allowed, update the inventory immediately */ export async function changeItemCount(user: HelixUser, item: string, amount = -1, preconfirmed = false): Promise { if (!ITEMS.includes(item)) return { result: false, reason: 'noexist', count: 0 } let inv = await getInventory(user) diff --git a/src/lib/lootboxes.ts b/src/lib/lootboxes.ts index 2750a07..b06c1b7 100644 --- a/src/lib/lootboxes.ts +++ b/src/lib/lootboxes.ts @@ -8,13 +8,14 @@ interface lootboxReadyResult { lastlootbox: number, DBuser: User } - -export async function lootboxReady(user: HelixUser | null): Promise { +/** Check if the lootbox is ready for specified user */ +export async function lootboxReady(user: HelixUser): Promise { const DBuser = await pb.collection('users').getFirstListItem(`id="${user!.id}"`) if ((Date.parse(DBuser.lastlootbox) + COOLDOWN) > Date.now()) return { result: false, lastlootbox: Date.parse(DBuser.lastlootbox), DBuser } return { result: true, lastlootbox: 0, DBuser } } +/** Set the time for last time user got lootbox to now */ export async function resetLootboxTimer(user: User) { const data = { lastlootbox: new Date(Date.now()).toISOString() } await pb.collection('users').update(user.id, data) diff --git a/src/lib/timeoutHelper.ts b/src/lib/timeoutHelper.ts index 8382c8f..2d03bd2 100644 --- a/src/lib/timeoutHelper.ts +++ b/src/lib/timeoutHelper.ts @@ -10,6 +10,9 @@ interface statusmessage { reason: string } +/** Ban a specific user out by another user for specified amout of time, with specific reason + * If the user does not exist or is already banned return status: false + * If the user is a moderator, make sure they get their status back after timeout has elapsed */ export async function timeout(broadcasterid: string, target: HelixUser, duration: number, reason: string): Promise { if (!target) return { status: false, reason: 'noexist' } const tmpapi = broadcasterApi ?? api @@ -30,6 +33,7 @@ export async function timeout(broadcasterid: string, target: HelixUser, duration } } +/** Add an entry to the timeouts table */ export async function addTimeoutToDB(attacker: HelixUser, target: HelixUser, source: shooter) { // This has passed the existance check so there's no need to check if the users exist (twitch) const timeoutobj = { @@ -42,6 +46,7 @@ export async function addTimeoutToDB(attacker: HelixUser, target: HelixUser, sou await pb.collection('timeouts').create(timeoutobj) } +/** Give the target mod status back after timeout */ function remodMod(broadcasterid: string, target: HelixUser, duration: number, api: ApiClient) { setTimeout(async () => { const bandata = await api.moderation.getBannedUsers(broadcasterid, { userId: target.id }) diff --git a/src/lib/userHelper.ts b/src/lib/userHelper.ts index a1e65cb..9e57b3e 100644 --- a/src/lib/userHelper.ts +++ b/src/lib/userHelper.ts @@ -16,6 +16,8 @@ type balanceGetResult = { data: User } +/** Ensures that the user exists in the database + * Returns an object with balance as well as the entire user entry from the database */ export async function getBalance(user: HelixUser): Promise { await DBValidation(user) const data = await pb.collection('users').getFirstListItem(`id="${user!.id}"`) @@ -28,6 +30,7 @@ type balanceChangeResult = { count: number } +/** Changes the balance of the current user by the requested amount */ export async function changeBalance(user: HelixUser, amount: number): Promise { let { balance, data } = await getBalance(user) if (amount < 0 && balance - amount < 0) return { result: false, reason: 'negative', count: balance } @@ -49,6 +52,8 @@ interface timeoutsGetResult { const BLASTERS = ['blaster', 'grenade', 'tnt'] +/** Get the amount of times the user has (been) shot (by) another user + * The 'blaster' data is all timeouts excluding silver bullets */ async function getTimeouts(userId: string, monthdata?: string): Promise { let monthquery = '' if (monthdata) monthquery = ` && created~"${monthdata}"` @@ -72,6 +77,8 @@ async function getTimeouts(userId: string, monthdata?: string): Promise { let monthquery = '' if (monthdata) monthquery = ` && created~"${monthdata}"` @@ -82,6 +89,7 @@ async function getItemUses(userId: string, monthdata?: string): Promise { await DBValidation(user) const data = await pb.collection('users').getFirstListItem(`id="${user.id}"`) @@ -92,6 +100,8 @@ interface statsGetResult extends timeoutsGetResult { used: inventory } +/** Get the hits, shoot and used item stats from specific user + * The monthdata should be something like "2025-01" if specified */ export async function getStats(user: HelixUser, monthdata?: string): Promise { await DBValidation(user) const { hit, shot } = await getTimeouts(user.id, monthdata) @@ -99,18 +109,21 @@ export async function getStats(user: HelixUser, monthdata?: string): Promise