xpt-shared-types 1.16.0 → 1.18.0

package/dist/generated/enums.d.ts

@@ -4,6 +4,10 @@ export type AdminActionTargetType = "user" | "tournament" | "match" | "transacti
 export type FaqCategory = "gettingStarted" | "tournamentsMatches" | "hosting" | "walletCoins" | "account";
 /** `Friendship.status` */
 export type FriendshipStatus = "pending" | "accepted";
+/** `GameAccount.code` */
+export type GameAccountCode = "steam" | "psn" | "xbox" | "battlenet" | "riot" | "epic" | "ea" | "activision" | "ubisoft" | "nintendo" | "fightcade" | "apple" | "googleplay";
+/** `GameAccount.verification` */
+export type GameAccountVerification = "none" | "format";
 /** `Game.genre` */
 export type GameGenre = "FPS" | "MOBA" | "Battle Royale" | "Fighting (FGC)" | "Sports" | "Strategy/RTS" | "Sim Racing" | "Card Game" | "Retro" | "Other";
 /** `GameRequest.customLobbies` */
@@ -28,6 +32,8 @@ export type MatchStreamPlatform = "twitch" | "youtube" | "kick" | "other";
 export type MatchWinnerSlot = "home" | "away";
 /** `Platform.code` */
 export type PlatformCode = "pc" | "playstation" | "xbox" | "nintendo" | "mobile";
+/** `PlayerBan.scope` */
+export type PlayerBanScope = "tournament" | "host";
 /** `Referral.status` */
 export type ReferralStatus = "pending" | "completed";
 /** `Team.current_status` */

package/dist/generated/inputs.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, MediaInput, RelationInput } from '../contracts';
-import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserTransactionStripeStatus, UserTransactionType } from './enums';
 /** Write payload for `about`. */
 export interface AboutInput {
     heroTitle?: string;
@@ -75,6 +75,8 @@ export interface GameInput {
 /** Write payload for `game-account`. */
 export interface GameAccountInput {
     name?: string;
+    code?: GameAccountCode;
+    verification?: GameAccountVerification;
     tournaments?: RelationInput | RelationInput[];
     user_game_accounts?: RelationInput | RelationInput[];
     imgThumb?: MediaInput;
@@ -187,6 +189,18 @@ export interface PlatformInput {
     games?: RelationInput | RelationInput[];
     game_accounts?: RelationInput | RelationInput[];
 }
+/** Write payload for `player-ban`. */
+export interface PlayerBanInput {
+    scope?: PlayerBanScope;
+    tournament?: RelationInput;
+    host?: RelationInput;
+    users_permissions_user?: RelationInput;
+    bannedBy?: RelationInput;
+    reason?: string;
+    expiresAt?: string;
+    liftedAt?: string;
+    liftedBy?: RelationInput;
+}
 /** Write payload for `preset-avatar`. */
 export interface PresetAvatarInput {
     image?: MediaInput;

package/dist/generated/models.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, StrapiDocument, StrapiMedia, UserRole } from '../contracts';
-import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserTransactionStripeStatus, UserTransactionType } from './enums';
 /** `about` */
 export interface About extends StrapiDocument {
     heroTitle?: string | null;
@@ -75,6 +75,8 @@ export interface Game extends StrapiDocument {
 /** `game-account` */
 export interface GameAccount extends StrapiDocument {
     name?: string | null;
+    code?: GameAccountCode | null;
+    verification?: GameAccountVerification | null;
     tournaments?: Tournament[];
     user_game_accounts?: UserGameAccount[];
     imgThumb?: StrapiMedia | null;
@@ -187,6 +189,18 @@ export interface Platform extends StrapiDocument {
     games?: Game[];
     game_accounts?: GameAccount[];
 }
+/** `player-ban` */
+export interface PlayerBan extends StrapiDocument {
+    scope?: PlayerBanScope | null;
+    tournament?: Tournament | null;
+    host?: User | null;
+    users_permissions_user?: User | null;
+    bannedBy?: User | null;
+    reason?: string | null;
+    expiresAt?: string | null;
+    liftedAt?: string | null;
+    liftedBy?: User | null;
+}
 /** `preset-avatar` */
 export interface PresetAvatar extends StrapiDocument {
     image?: StrapiMedia | null;

package/dist/manual/gameAccountHandle.d.ts

@@ -0,0 +1,90 @@
+/**
+ * What a player's handle on each account network looks like.
+ *
+ * A handle is the one thing opponents actually exchange — the PSN ID, the
+ * BattleTag, the Riot ID — so a typo in it is a match that cannot start. Until
+ * these rules existed one regex covered every network, and it happily accepted
+ * `Name#1234` for PSN (where `#` is not allowed) while rejecting nothing that a
+ * real PSN or Xbox rule would.
+ *
+ * None of this proves ownership. A network whose handles can be linked by
+ * OAuth (Steam, Battle.net, Xbox) gets a `linked` tier later; this file is the
+ * `format` tier that every network can have today. Which tier applies is a
+ * property of the catalogue row (`GameAccount.verification`), set by editors,
+ * so a rule that turns out wrong for some network can be switched off without a
+ * deploy: set the row to `none` and the generic rule applies.
+ *
+ * Lives here because the settings page validates as the player types and the
+ * backend validates again on write. Two copies of a regex is two chances for a
+ * handle to pass one and fail the other.
+ *
+ * Pure on purpose: no I/O, no profanity list (each app keeps its own), so the
+ * rules are unit-tested directly (xpt-strapi
+ * `tests/unit/utils/gameAccountHandle.test.ts`).
+ */
+import type { GameAccountCode, GameAccountVerification } from '../generated/enums';
+export interface HandleRule {
+    /** The network this rule is for; absent on the generic fallback. */
+    code?: GameAccountCode;
+    /** What the field is called in copy: "PSN online ID", "BattleTag". */
+    label: string;
+    /** The field's placeholder. */
+    placeholder: string;
+    /** One sentence under the field saying what a valid value looks like. */
+    hint: string;
+    /** Applied to the normalized value. */
+    pattern: RegExp;
+    min: number;
+    max: number;
+    /**
+     * Rewrites the trimmed input before `pattern` is applied: a Steam profile
+     * URL down to its id, a bare Nintendo friend code into `SW-xxxx-xxxx-xxxx`.
+     * The result is what gets stored.
+     */
+    normalize?: (value: string) => string;
+}
+export type HandleCheck = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    message: string;
+};
+/** `error.details.name` values the game-account write endpoints raise. */
+export type GameAccountErrorName = 'HandleInvalid' | 'HandleTaken';
+/**
+ * The rule every network gets when it has no stricter one. Also the backstop
+ * the backend applies to every write regardless of network, so every rule
+ * below must produce a value that passes this one.
+ *
+ * Letters are `\p{L}` rather than `A-Z`: BattleTags and Riot IDs allow accented
+ * names, and a rule that rejected "Ærøn#1234" would be wrong, not strict.
+ */
+export declare const GENERIC_HANDLE_RULE: HandleRule;
+/**
+ * Per-network rules. Initial values, and product decisions rather than facts:
+ * each is the documented shape as of writing, kept a little looser than the
+ * network's own signup validator so a real handle is never refused.
+ */
+export declare const HANDLE_RULES: Partial<Record<GameAccountCode, HandleRule>>;
+/**
+ * The rule a network's handles are checked against: its own when the
+ * catalogue row asks for format checks and a rule exists for its code,
+ * otherwise the generic one.
+ */
+export declare function handleRuleFor(network: {
+    code?: GameAccountCode | string | null;
+    verification?: GameAccountVerification | string | null;
+} | null | undefined): HandleRule;
+/** True when the code has a rule of its own, so `format` means something. */
+export declare function hasHandleRule(code: string | null | undefined): boolean;
+/**
+ * Checks `raw` against `rule` and returns the value to store: trimmed, runs of
+ * whitespace collapsed to one space, then the rule's own normalization.
+ *
+ * The message is the one the player reads, so it says what a valid value looks
+ * like rather than which check failed.
+ */
+export declare function checkHandle(raw: string | null | undefined, rule: HandleRule): HandleCheck;
+/** The key two handles are compared on: same network, same letters, any case. */
+export declare function normalizeHandleKey(value: string): string;

package/dist/manual/gameAccountHandle.js

@@ -0,0 +1,203 @@
+"use strict";
+/**
+ * What a player's handle on each account network looks like.
+ *
+ * A handle is the one thing opponents actually exchange — the PSN ID, the
+ * BattleTag, the Riot ID — so a typo in it is a match that cannot start. Until
+ * these rules existed one regex covered every network, and it happily accepted
+ * `Name#1234` for PSN (where `#` is not allowed) while rejecting nothing that a
+ * real PSN or Xbox rule would.
+ *
+ * None of this proves ownership. A network whose handles can be linked by
+ * OAuth (Steam, Battle.net, Xbox) gets a `linked` tier later; this file is the
+ * `format` tier that every network can have today. Which tier applies is a
+ * property of the catalogue row (`GameAccount.verification`), set by editors,
+ * so a rule that turns out wrong for some network can be switched off without a
+ * deploy: set the row to `none` and the generic rule applies.
+ *
+ * Lives here because the settings page validates as the player types and the
+ * backend validates again on write. Two copies of a regex is two chances for a
+ * handle to pass one and fail the other.
+ *
+ * Pure on purpose: no I/O, no profanity list (each app keeps its own), so the
+ * rules are unit-tested directly (xpt-strapi
+ * `tests/unit/utils/gameAccountHandle.test.ts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HANDLE_RULES = exports.GENERIC_HANDLE_RULE = void 0;
+exports.handleRuleFor = handleRuleFor;
+exports.hasHandleRule = hasHandleRule;
+exports.checkHandle = checkHandle;
+exports.normalizeHandleKey = normalizeHandleKey;
+/**
+ * The rule every network gets when it has no stricter one. Also the backstop
+ * the backend applies to every write regardless of network, so every rule
+ * below must produce a value that passes this one.
+ *
+ * Letters are `\p{L}` rather than `A-Z`: BattleTags and Riot IDs allow accented
+ * names, and a rule that rejected "Ærøn#1234" would be wrong, not strict.
+ */
+exports.GENERIC_HANDLE_RULE = {
+    label: 'Game ID',
+    placeholder: 'Game ID',
+    hint: 'Enter your ID exactly as it appears in-game. Letters, numbers, spaces and _ . # - are allowed.',
+    pattern: /^[\p{L}\p{N}_ .#-]+$/u,
+    min: 3,
+    max: 32,
+};
+const STEAM_PROFILE_URL = /^(?:https?:\/\/)?(?:www\.)?steamcommunity\.com\/(?:id|profiles)\/([^/?#\s]+)\/?(?:[?#].*)?$/i;
+/**
+ * Per-network rules. Initial values, and product decisions rather than facts:
+ * each is the documented shape as of writing, kept a little looser than the
+ * network's own signup validator so a real handle is never refused.
+ */
+exports.HANDLE_RULES = {
+    psn: {
+        code: 'psn',
+        label: 'PSN online ID',
+        placeholder: 'PSN online ID',
+        hint: '3 to 16 letters, numbers, hyphens or underscores, starting with a letter. No # tag.',
+        pattern: /^[A-Za-z][A-Za-z0-9_-]{2,15}$/,
+        min: 3,
+        max: 16,
+    },
+    xbox: {
+        code: 'xbox',
+        label: 'Gamertag',
+        placeholder: 'Gamertag or Gamertag#1234',
+        hint: 'Letters, numbers and single spaces, with the #1234 suffix if your gamertag has one.',
+        pattern: /^[A-Za-z0-9]+(?: [A-Za-z0-9]+)*(?:#\d{3,4})?$/,
+        min: 3,
+        max: 20,
+    },
+    battlenet: {
+        code: 'battlenet',
+        label: 'BattleTag',
+        placeholder: 'Name#1234',
+        hint: 'Your BattleTag including the number, e.g. Name#1234.',
+        pattern: /^\p{L}[\p{L}\p{N}]{2,11}#\d{4,7}$/u,
+        min: 8,
+        max: 20,
+    },
+    riot: {
+        code: 'riot',
+        label: 'Riot ID',
+        placeholder: 'GameName#TAG',
+        hint: 'Your Riot ID including the tagline, e.g. GameName#TAG.',
+        pattern: /^[\p{L}\p{N}](?:[\p{L}\p{N} ]{1,14}[\p{L}\p{N}])?#[\p{L}\p{N}]{3,5}$/u,
+        min: 7,
+        max: 22,
+    },
+    epic: {
+        code: 'epic',
+        label: 'Epic display name',
+        placeholder: 'Epic display name',
+        hint: '3 to 16 letters, numbers, spaces or - _ . as shown on your Epic account.',
+        pattern: /^[\p{L}\p{N}][\p{L}\p{N} ._-]{1,14}[\p{L}\p{N}._-]$/u,
+        min: 3,
+        max: 16,
+    },
+    ea: {
+        code: 'ea',
+        label: 'EA ID',
+        placeholder: 'EA ID',
+        hint: '4 to 16 letters, numbers, hyphens or underscores.',
+        pattern: /^[A-Za-z0-9_-]{4,16}$/,
+        min: 4,
+        max: 16,
+    },
+    activision: {
+        code: 'activision',
+        label: 'Activision ID',
+        placeholder: 'Name#1234567',
+        hint: 'Your Activision ID including the number, e.g. Name#1234567.',
+        pattern: /^[A-Za-z0-9 _-]{2,16}#\d{4,8}$/,
+        min: 7,
+        max: 25,
+    },
+    ubisoft: {
+        code: 'ubisoft',
+        label: 'Ubisoft username',
+        placeholder: 'Ubisoft username',
+        hint: '3 to 15 letters, numbers or - _ . as shown in Ubisoft Connect.',
+        pattern: /^[A-Za-z0-9._-]{3,15}$/,
+        min: 3,
+        max: 15,
+    },
+    steam: {
+        code: 'steam',
+        label: 'Steam ID',
+        placeholder: 'Friend code or profile URL',
+        hint: 'Your Steam friend code (Friends > Add a Friend), your SteamID64, or your steamcommunity.com profile URL.',
+        // A profile URL is the easiest thing for a player to paste; what gets
+        // stored is the id or custom name at the end of it.
+        normalize: (value) => value.replace(STEAM_PROFILE_URL, '$1'),
+        pattern: /^[A-Za-z0-9_-]{3,32}$/,
+        min: 3,
+        max: 32,
+    },
+    nintendo: {
+        code: 'nintendo',
+        label: 'Nintendo friend code',
+        placeholder: 'SW-0000-0000-0000',
+        hint: 'Your 12-digit Switch friend code, e.g. SW-1234-5678-9012.',
+        normalize: (value) => {
+            const digits = value.replace(/^sw/i, '').replace(/[\s-]/g, '');
+            return /^\d{12}$/.test(digits)
+                ? `SW-${digits.slice(0, 4)}-${digits.slice(4, 8)}-${digits.slice(8)}`
+                : value;
+        },
+        pattern: /^SW-\d{4}-\d{4}-\d{4}$/,
+        min: 17,
+        max: 17,
+    },
+    // fightcade, apple and googleplay have no documented handle shape and stay
+    // on the generic rule.
+};
+/**
+ * The rule a network's handles are checked against: its own when the
+ * catalogue row asks for format checks and a rule exists for its code,
+ * otherwise the generic one.
+ */
+function handleRuleFor(network) {
+    var _a;
+    if ((network === null || network === void 0 ? void 0 : network.verification) !== 'format' || !network.code) {
+        return exports.GENERIC_HANDLE_RULE;
+    }
+    return (_a = exports.HANDLE_RULES[network.code]) !== null && _a !== void 0 ? _a : exports.GENERIC_HANDLE_RULE;
+}
+/** True when the code has a rule of its own, so `format` means something. */
+function hasHandleRule(code) {
+    return !!code && Object.prototype.hasOwnProperty.call(exports.HANDLE_RULES, code);
+}
+/**
+ * Checks `raw` against `rule` and returns the value to store: trimmed, runs of
+ * whitespace collapsed to one space, then the rule's own normalization.
+ *
+ * The message is the one the player reads, so it says what a valid value looks
+ * like rather than which check failed.
+ */
+function checkHandle(raw, rule) {
+    const collapsed = (raw !== null && raw !== void 0 ? raw : '').trim().replace(/\s+/g, ' ');
+    if (!collapsed) {
+        return { ok: false, message: `Please enter your ${rule.label}` };
+    }
+    const value = rule.normalize ? rule.normalize(collapsed) : collapsed;
+    if (value.length < rule.min) {
+        return { ok: false, message: `${rule.label} is too short. ${rule.hint}` };
+    }
+    if (value.length > rule.max) {
+        return { ok: false, message: `${rule.label} is too long. ${rule.hint}` };
+    }
+    if (!rule.pattern.test(value)) {
+        return {
+            ok: false,
+            message: `That doesn't look like a valid ${rule.label}. ${rule.hint}`,
+        };
+    }
+    return { ok: true, value };
+}
+/** The key two handles are compared on: same network, same letters, any case. */
+function normalizeHandleKey(value) {
+    return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}

package/dist/manual/index.d.ts

@@ -2,8 +2,10 @@
  * Hand-written types that are not derived from a Strapi content type.
  */
 export * from './country';
+export * from './gameAccountHandle';
 export * from './lobby';
 export * from './notification';
+export * from './playerBan';
 export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';

package/dist/manual/index.js

@@ -18,8 +18,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Hand-written types that are not derived from a Strapi content type.
  */
 __exportStar(require("./country"), exports);
+__exportStar(require("./gameAccountHandle"), exports);
 __exportStar(require("./lobby"), exports);
 __exportStar(require("./notification"), exports);
+__exportStar(require("./playerBan"), exports);
 __exportStar(require("./tournamentEntry"), exports);
 __exportStar(require("./tournamentInvite"), exports);
 __exportStar(require("./tournamentJoinRequest"), exports);

package/dist/manual/playerBan.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Player bans — the contract between `utils/playerBan.ts` in xpt-strapi and
+ * the ban dialog, ban list and host-bans page in xpt-client.
+ *
+ * Two scopes (`PlayerBanScope`, generated): **tournament** keeps a player out
+ * of one event and is set by its owner or an admin; **host** keeps them out
+ * of every tournament one host owns, now and later, and only that host sets
+ * it. The platform level is the account block, not a ban.
+ *
+ * A ban is active until it is lifted or its `expiresAt` passes; `null` is
+ * permanent. Lifted bans are kept, so a list can show history.
+ *
+ * Routes:
+ *  - `GET|POST /tournaments/:id/bans`, `DELETE /tournaments/:id/bans/:userId`
+ *  - `GET|POST /host-bans`, `DELETE /host-bans/:userId`
+ * Both GETs take `?includeLifted=true`.
+ */
+import type { PlayerBanScope } from '../generated/enums';
+export declare const MAX_BAN_REASON_LENGTH = 500;
+/** A ban as the list and ban routes return it. */
+export interface PlayerBanSummary {
+    documentId: string;
+    scope: PlayerBanScope;
+    reason: string | null;
+    createdAt: string | null;
+    /** Null for a permanent ban. */
+    expiresAt: string | null;
+    liftedAt: string | null;
+    /** Not lifted and not expired. */
+    active: boolean;
+    users_permissions_user: {
+        id: number;
+        documentId: string | null;
+        username: string | null;
+        image: unknown;
+    } | null;
+    bannedBy: {
+        id: number;
+        username: string | null;
+    } | null;
+    liftedBy: {
+        id: number;
+        username: string | null;
+    } | null;
+    /** Set on tournament-scope bans. */
+    tournament: {
+        documentId: string;
+        title: string | null;
+    } | null;
+    /**
+     * Whether the viewer may lift it. On a tournament's list a host ban is
+     * liftable only by the owner — an admin sees it but cannot lift it.
+     */
+    canLift: boolean;
+}
+/** `POST /tournaments/:id/bans` and `POST /host-bans`. */
+export interface BanPlayerBody {
+    userId: number;
+    reason?: string | null;
+    /** ISO date in the future; omit or null for permanent. */
+    expiresAt?: string | null;
+    /**
+     * Also withdraw the entry the player registered (with its refund), while
+     * the tournament still takes entries. Host bans apply it across all of the
+     * host's open tournaments.
+     */
+    removeEntry?: boolean;
+}
+/** Why `removeEntry` left an entry where it was. */
+export type BanRemovalSkip = 
+/** No entry in this tournament. Never returned for host bans. */
+'notRegistered'
+/** On a team someone else registered: the team's leader must swap them out. */
+ | 'notRegistrant'
+/** Past check-in; the bracket is seeded. */
+ | 'entryLocked'
+/** The withdrawal refused; `message` says why. */
+ | 'failed';
+export interface BanRemoval {
+    tournamentDocumentId: string;
+    tournamentTitle: string | null;
+    removed: boolean;
+    /** Coins returned to whoever paid. */
+    refunded: number;
+    skipped?: BanRemovalSkip;
+    message?: string;
+}
+/** The `data` of a successful ban. */
+export interface BanResult {
+    ban: PlayerBanSummary;
+    /** Pending join requests declined and refunded because of the ban. */
+    declinedRequests: number;
+    /** Empty unless `removeEntry` was asked for. */
+    removals: BanRemoval[];
+}
+/** The durations the ban dialog offers. */
+export declare const BAN_DURATIONS: readonly [{
+    readonly key: "1d";
+    readonly label: "24 hours";
+    readonly days: 1;
+}, {
+    readonly key: "7d";
+    readonly label: "7 days";
+    readonly days: 7;
+}, {
+    readonly key: "30d";
+    readonly label: "30 days";
+    readonly days: 30;
+}, {
+    readonly key: "permanent";
+    readonly label: "Permanent";
+    readonly days: null;
+}];
+export type BanDurationKey = (typeof BAN_DURATIONS)[number]['key'];
+/** `expiresAt` for a duration, or null for permanent. */
+export declare function banExpiryFor(key: BanDurationKey, now?: Date): string | null;
+export declare function isBanActive(ban: {
+    liftedAt?: string | null;
+    expiresAt?: string | null;
+}, now?: Date): boolean;

package/dist/manual/playerBan.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Player bans — the contract between `utils/playerBan.ts` in xpt-strapi and
+ * the ban dialog, ban list and host-bans page in xpt-client.
+ *
+ * Two scopes (`PlayerBanScope`, generated): **tournament** keeps a player out
+ * of one event and is set by its owner or an admin; **host** keeps them out
+ * of every tournament one host owns, now and later, and only that host sets
+ * it. The platform level is the account block, not a ban.
+ *
+ * A ban is active until it is lifted or its `expiresAt` passes; `null` is
+ * permanent. Lifted bans are kept, so a list can show history.
+ *
+ * Routes:
+ *  - `GET|POST /tournaments/:id/bans`, `DELETE /tournaments/:id/bans/:userId`
+ *  - `GET|POST /host-bans`, `DELETE /host-bans/:userId`
+ * Both GETs take `?includeLifted=true`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BAN_DURATIONS = exports.MAX_BAN_REASON_LENGTH = void 0;
+exports.banExpiryFor = banExpiryFor;
+exports.isBanActive = isBanActive;
+exports.MAX_BAN_REASON_LENGTH = 500;
+/** The durations the ban dialog offers. */
+exports.BAN_DURATIONS = [
+    { key: '1d', label: '24 hours', days: 1 },
+    { key: '7d', label: '7 days', days: 7 },
+    { key: '30d', label: '30 days', days: 30 },
+    { key: 'permanent', label: 'Permanent', days: null },
+];
+/** `expiresAt` for a duration, or null for permanent. */
+function banExpiryFor(key, now = new Date()) {
+    var _a, _b;
+    const days = (_b = (_a = exports.BAN_DURATIONS.find((d) => d.key === key)) === null || _a === void 0 ? void 0 : _a.days) !== null && _b !== void 0 ? _b : null;
+    return days == null
+        ? null
+        : new Date(now.getTime() + days * 86400000).toISOString();
+}
+function isBanActive(ban, now = new Date()) {
+    if (ban.liftedAt)
+        return false;
+    if (!ban.expiresAt)
+        return true;
+    return new Date(ban.expiresAt).getTime() > now.getTime();
+}

package/dist/manual/tournamentStaff.d.ts

@@ -36,7 +36,9 @@ export type TournamentStaffAction =
 /** Record scores, start matches, edit match details. */
  | 'manageMatches'
 /** Watch any lobby and post as staff in its chat. */
- | 'enterLobby';
+ | 'enterLobby'
+/** Ban players from this tournament and lift those bans. */
+ | 'manageBans';
 export declare const TOURNAMENT_STAFF_CAPABILITIES: Record<TournamentStaffAction, readonly TournamentStaffRole[]>;
 export declare const TOURNAMENT_STAFF_ROLE_LABELS: Record<TournamentStaffRole, string>;
 export declare const tournamentStaffRoleLabel: (role: string | null | undefined) => string;

package/dist/manual/tournamentStaff.js

@@ -36,6 +36,7 @@ exports.TOURNAMENT_STAFF_CAPABILITIES = {
     reviewJoinRequests: ADMIN_UP,
     resolveDispute: ADMIN_UP,
     seedBracket: ADMIN_UP,
+    manageBans: ADMIN_UP,
     manageMatches: ALL_STAFF,
     enterLobby: ALL_STAFF,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xpt-shared-types",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Shared types and data for XPT projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/generated/enums.ts

@@ -22,6 +22,27 @@ export type FriendshipStatus =
   | "pending"
   | "accepted";
 
+/** `GameAccount.code` */
+export type GameAccountCode =
+  | "steam"
+  | "psn"
+  | "xbox"
+  | "battlenet"
+  | "riot"
+  | "epic"
+  | "ea"
+  | "activision"
+  | "ubisoft"
+  | "nintendo"
+  | "fightcade"
+  | "apple"
+  | "googleplay";
+
+/** `GameAccount.verification` */
+export type GameAccountVerification =
+  | "none"
+  | "format";
+
 /** `Game.genre` */
 export type GameGenre =
   | "FPS"
@@ -126,6 +147,11 @@ export type PlatformCode =
   | "nintendo"
   | "mobile";
 
+/** `PlayerBan.scope` */
+export type PlayerBanScope =
+  | "tournament"
+  | "host";
+
 /** `Referral.status` */
 export type ReferralStatus =
   | "pending"

package/src/generated/inputs.ts

@@ -11,6 +11,8 @@ import type {
   AdminActionTargetType,
   FaqCategory,
   FriendshipStatus,
+  GameAccountCode,
+  GameAccountVerification,
   GameGenre,
   GameRequestCustomLobbies,
   GameRequestGenre,
@@ -23,6 +25,7 @@ import type {
   MatchStreamPlatform,
   MatchWinnerSlot,
   PlatformCode,
+  PlayerBanScope,
   ReferralStatus,
   TeamCurrentStatus,
   TeamInviteStatus,
@@ -126,6 +129,8 @@ export interface GameInput {
 /** Write payload for `game-account`. */
 export interface GameAccountInput {
   name?: string;
+  code?: GameAccountCode;
+  verification?: GameAccountVerification;
   tournaments?: RelationInput | RelationInput[];
   user_game_accounts?: RelationInput | RelationInput[];
   imgThumb?: MediaInput;
@@ -247,6 +252,19 @@ export interface PlatformInput {
   game_accounts?: RelationInput | RelationInput[];
 }
 
+/** Write payload for `player-ban`. */
+export interface PlayerBanInput {
+  scope?: PlayerBanScope;
+  tournament?: RelationInput;
+  host?: RelationInput;
+  users_permissions_user?: RelationInput;
+  bannedBy?: RelationInput;
+  reason?: string;
+  expiresAt?: string;
+  liftedAt?: string;
+  liftedBy?: RelationInput;
+}
+
 /** Write payload for `preset-avatar`. */
 export interface PresetAvatarInput {
   image?: MediaInput;

package/src/generated/models.ts

@@ -12,6 +12,8 @@ import type {
   AdminActionTargetType,
   FaqCategory,
   FriendshipStatus,
+  GameAccountCode,
+  GameAccountVerification,
   GameGenre,
   GameRequestCustomLobbies,
   GameRequestGenre,
@@ -24,6 +26,7 @@ import type {
   MatchStreamPlatform,
   MatchWinnerSlot,
   PlatformCode,
+  PlayerBanScope,
   ReferralStatus,
   TeamCurrentStatus,
   TeamInviteStatus,
@@ -127,6 +130,8 @@ export interface Game extends StrapiDocument {
 /** `game-account` */
 export interface GameAccount extends StrapiDocument {
   name?: string | null;
+  code?: GameAccountCode | null;
+  verification?: GameAccountVerification | null;
   tournaments?: Tournament[];
   user_game_accounts?: UserGameAccount[];
   imgThumb?: StrapiMedia | null;
@@ -248,6 +253,19 @@ export interface Platform extends StrapiDocument {
   game_accounts?: GameAccount[];
 }
 
+/** `player-ban` */
+export interface PlayerBan extends StrapiDocument {
+  scope?: PlayerBanScope | null;
+  tournament?: Tournament | null;
+  host?: User | null;
+  users_permissions_user?: User | null;
+  bannedBy?: User | null;
+  reason?: string | null;
+  expiresAt?: string | null;
+  liftedAt?: string | null;
+  liftedBy?: User | null;
+}
+
 /** `preset-avatar` */
 export interface PresetAvatar extends StrapiDocument {
   image?: StrapiMedia | null;

package/src/manual/gameAccountHandle.ts

@@ -0,0 +1,250 @@
+/**
+ * What a player's handle on each account network looks like.
+ *
+ * A handle is the one thing opponents actually exchange — the PSN ID, the
+ * BattleTag, the Riot ID — so a typo in it is a match that cannot start. Until
+ * these rules existed one regex covered every network, and it happily accepted
+ * `Name#1234` for PSN (where `#` is not allowed) while rejecting nothing that a
+ * real PSN or Xbox rule would.
+ *
+ * None of this proves ownership. A network whose handles can be linked by
+ * OAuth (Steam, Battle.net, Xbox) gets a `linked` tier later; this file is the
+ * `format` tier that every network can have today. Which tier applies is a
+ * property of the catalogue row (`GameAccount.verification`), set by editors,
+ * so a rule that turns out wrong for some network can be switched off without a
+ * deploy: set the row to `none` and the generic rule applies.
+ *
+ * Lives here because the settings page validates as the player types and the
+ * backend validates again on write. Two copies of a regex is two chances for a
+ * handle to pass one and fail the other.
+ *
+ * Pure on purpose: no I/O, no profanity list (each app keeps its own), so the
+ * rules are unit-tested directly (xpt-strapi
+ * `tests/unit/utils/gameAccountHandle.test.ts`).
+ */
+
+import type {
+  GameAccountCode,
+  GameAccountVerification,
+} from '../generated/enums';
+
+export interface HandleRule {
+  /** The network this rule is for; absent on the generic fallback. */
+  code?: GameAccountCode;
+  /** What the field is called in copy: "PSN online ID", "BattleTag". */
+  label: string;
+  /** The field's placeholder. */
+  placeholder: string;
+  /** One sentence under the field saying what a valid value looks like. */
+  hint: string;
+  /** Applied to the normalized value. */
+  pattern: RegExp;
+  min: number;
+  max: number;
+  /**
+   * Rewrites the trimmed input before `pattern` is applied: a Steam profile
+   * URL down to its id, a bare Nintendo friend code into `SW-xxxx-xxxx-xxxx`.
+   * The result is what gets stored.
+   */
+  normalize?: (value: string) => string;
+}
+
+export type HandleCheck =
+  | { ok: true; value: string }
+  | { ok: false; message: string };
+
+/** `error.details.name` values the game-account write endpoints raise. */
+export type GameAccountErrorName = 'HandleInvalid' | 'HandleTaken';
+
+/**
+ * The rule every network gets when it has no stricter one. Also the backstop
+ * the backend applies to every write regardless of network, so every rule
+ * below must produce a value that passes this one.
+ *
+ * Letters are `\p{L}` rather than `A-Z`: BattleTags and Riot IDs allow accented
+ * names, and a rule that rejected "Ærøn#1234" would be wrong, not strict.
+ */
+export const GENERIC_HANDLE_RULE: HandleRule = {
+  label: 'Game ID',
+  placeholder: 'Game ID',
+  hint: 'Enter your ID exactly as it appears in-game. Letters, numbers, spaces and _ . # - are allowed.',
+  pattern: /^[\p{L}\p{N}_ .#-]+$/u,
+  min: 3,
+  max: 32,
+};
+
+const STEAM_PROFILE_URL =
+  /^(?:https?:\/\/)?(?:www\.)?steamcommunity\.com\/(?:id|profiles)\/([^/?#\s]+)\/?(?:[?#].*)?$/i;
+
+/**
+ * Per-network rules. Initial values, and product decisions rather than facts:
+ * each is the documented shape as of writing, kept a little looser than the
+ * network's own signup validator so a real handle is never refused.
+ */
+export const HANDLE_RULES: Partial<Record<GameAccountCode, HandleRule>> = {
+  psn: {
+    code: 'psn',
+    label: 'PSN online ID',
+    placeholder: 'PSN online ID',
+    hint: '3 to 16 letters, numbers, hyphens or underscores, starting with a letter. No # tag.',
+    pattern: /^[A-Za-z][A-Za-z0-9_-]{2,15}$/,
+    min: 3,
+    max: 16,
+  },
+  xbox: {
+    code: 'xbox',
+    label: 'Gamertag',
+    placeholder: 'Gamertag or Gamertag#1234',
+    hint: 'Letters, numbers and single spaces, with the #1234 suffix if your gamertag has one.',
+    pattern: /^[A-Za-z0-9]+(?: [A-Za-z0-9]+)*(?:#\d{3,4})?$/,
+    min: 3,
+    max: 20,
+  },
+  battlenet: {
+    code: 'battlenet',
+    label: 'BattleTag',
+    placeholder: 'Name#1234',
+    hint: 'Your BattleTag including the number, e.g. Name#1234.',
+    pattern: /^\p{L}[\p{L}\p{N}]{2,11}#\d{4,7}$/u,
+    min: 8,
+    max: 20,
+  },
+  riot: {
+    code: 'riot',
+    label: 'Riot ID',
+    placeholder: 'GameName#TAG',
+    hint: 'Your Riot ID including the tagline, e.g. GameName#TAG.',
+    pattern: /^[\p{L}\p{N}](?:[\p{L}\p{N} ]{1,14}[\p{L}\p{N}])?#[\p{L}\p{N}]{3,5}$/u,
+    min: 7,
+    max: 22,
+  },
+  epic: {
+    code: 'epic',
+    label: 'Epic display name',
+    placeholder: 'Epic display name',
+    hint: '3 to 16 letters, numbers, spaces or - _ . as shown on your Epic account.',
+    pattern: /^[\p{L}\p{N}][\p{L}\p{N} ._-]{1,14}[\p{L}\p{N}._-]$/u,
+    min: 3,
+    max: 16,
+  },
+  ea: {
+    code: 'ea',
+    label: 'EA ID',
+    placeholder: 'EA ID',
+    hint: '4 to 16 letters, numbers, hyphens or underscores.',
+    pattern: /^[A-Za-z0-9_-]{4,16}$/,
+    min: 4,
+    max: 16,
+  },
+  activision: {
+    code: 'activision',
+    label: 'Activision ID',
+    placeholder: 'Name#1234567',
+    hint: 'Your Activision ID including the number, e.g. Name#1234567.',
+    pattern: /^[A-Za-z0-9 _-]{2,16}#\d{4,8}$/,
+    min: 7,
+    max: 25,
+  },
+  ubisoft: {
+    code: 'ubisoft',
+    label: 'Ubisoft username',
+    placeholder: 'Ubisoft username',
+    hint: '3 to 15 letters, numbers or - _ . as shown in Ubisoft Connect.',
+    pattern: /^[A-Za-z0-9._-]{3,15}$/,
+    min: 3,
+    max: 15,
+  },
+  steam: {
+    code: 'steam',
+    label: 'Steam ID',
+    placeholder: 'Friend code or profile URL',
+    hint: 'Your Steam friend code (Friends > Add a Friend), your SteamID64, or your steamcommunity.com profile URL.',
+    // A profile URL is the easiest thing for a player to paste; what gets
+    // stored is the id or custom name at the end of it.
+    normalize: (value) => value.replace(STEAM_PROFILE_URL, '$1'),
+    pattern: /^[A-Za-z0-9_-]{3,32}$/,
+    min: 3,
+    max: 32,
+  },
+  nintendo: {
+    code: 'nintendo',
+    label: 'Nintendo friend code',
+    placeholder: 'SW-0000-0000-0000',
+    hint: 'Your 12-digit Switch friend code, e.g. SW-1234-5678-9012.',
+    normalize: (value) => {
+      const digits = value.replace(/^sw/i, '').replace(/[\s-]/g, '');
+      return /^\d{12}$/.test(digits)
+        ? `SW-${digits.slice(0, 4)}-${digits.slice(4, 8)}-${digits.slice(8)}`
+        : value;
+    },
+    pattern: /^SW-\d{4}-\d{4}-\d{4}$/,
+    min: 17,
+    max: 17,
+  },
+  // fightcade, apple and googleplay have no documented handle shape and stay
+  // on the generic rule.
+};
+
+/**
+ * The rule a network's handles are checked against: its own when the
+ * catalogue row asks for format checks and a rule exists for its code,
+ * otherwise the generic one.
+ */
+export function handleRuleFor(
+  network:
+    | {
+        code?: GameAccountCode | string | null;
+        verification?: GameAccountVerification | string | null;
+      }
+    | null
+    | undefined
+): HandleRule {
+  if (network?.verification !== 'format' || !network.code) {
+    return GENERIC_HANDLE_RULE;
+  }
+  return HANDLE_RULES[network.code as GameAccountCode] ?? GENERIC_HANDLE_RULE;
+}
+
+/** True when the code has a rule of its own, so `format` means something. */
+export function hasHandleRule(code: string | null | undefined): boolean {
+  return !!code && Object.prototype.hasOwnProperty.call(HANDLE_RULES, code);
+}
+
+/**
+ * Checks `raw` against `rule` and returns the value to store: trimmed, runs of
+ * whitespace collapsed to one space, then the rule's own normalization.
+ *
+ * The message is the one the player reads, so it says what a valid value looks
+ * like rather than which check failed.
+ */
+export function checkHandle(
+  raw: string | null | undefined,
+  rule: HandleRule
+): HandleCheck {
+  const collapsed = (raw ?? '').trim().replace(/\s+/g, ' ');
+  if (!collapsed) {
+    return { ok: false, message: `Please enter your ${rule.label}` };
+  }
+
+  const value = rule.normalize ? rule.normalize(collapsed) : collapsed;
+
+  if (value.length < rule.min) {
+    return { ok: false, message: `${rule.label} is too short. ${rule.hint}` };
+  }
+  if (value.length > rule.max) {
+    return { ok: false, message: `${rule.label} is too long. ${rule.hint}` };
+  }
+  if (!rule.pattern.test(value)) {
+    return {
+      ok: false,
+      message: `That doesn't look like a valid ${rule.label}. ${rule.hint}`,
+    };
+  }
+
+  return { ok: true, value };
+}
+
+/** The key two handles are compared on: same network, same letters, any case. */
+export function normalizeHandleKey(value: string): string {
+  return value.trim().replace(/\s+/g, ' ').toLowerCase();
+}

package/src/manual/index.ts

@@ -2,8 +2,10 @@
  * Hand-written types that are not derived from a Strapi content type.
  */
 export * from './country';
+export * from './gameAccountHandle';
 export * from './lobby';
 export * from './notification';
+export * from './playerBan';
 export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';

package/src/manual/playerBan.ts

@@ -0,0 +1,123 @@
+/**
+ * Player bans — the contract between `utils/playerBan.ts` in xpt-strapi and
+ * the ban dialog, ban list and host-bans page in xpt-client.
+ *
+ * Two scopes (`PlayerBanScope`, generated): **tournament** keeps a player out
+ * of one event and is set by its owner or an admin; **host** keeps them out
+ * of every tournament one host owns, now and later, and only that host sets
+ * it. The platform level is the account block, not a ban.
+ *
+ * A ban is active until it is lifted or its `expiresAt` passes; `null` is
+ * permanent. Lifted bans are kept, so a list can show history.
+ *
+ * Routes:
+ *  - `GET|POST /tournaments/:id/bans`, `DELETE /tournaments/:id/bans/:userId`
+ *  - `GET|POST /host-bans`, `DELETE /host-bans/:userId`
+ * Both GETs take `?includeLifted=true`.
+ */
+
+import type { PlayerBanScope } from '../generated/enums';
+
+export const MAX_BAN_REASON_LENGTH = 500;
+
+/** A ban as the list and ban routes return it. */
+export interface PlayerBanSummary {
+  documentId: string;
+  scope: PlayerBanScope;
+  reason: string | null;
+  createdAt: string | null;
+  /** Null for a permanent ban. */
+  expiresAt: string | null;
+  liftedAt: string | null;
+  /** Not lifted and not expired. */
+  active: boolean;
+  users_permissions_user: {
+    id: number;
+    documentId: string | null;
+    username: string | null;
+    image: unknown;
+  } | null;
+  bannedBy: { id: number; username: string | null } | null;
+  liftedBy: { id: number; username: string | null } | null;
+  /** Set on tournament-scope bans. */
+  tournament: { documentId: string; title: string | null } | null;
+  /**
+   * Whether the viewer may lift it. On a tournament's list a host ban is
+   * liftable only by the owner — an admin sees it but cannot lift it.
+   */
+  canLift: boolean;
+}
+
+/** `POST /tournaments/:id/bans` and `POST /host-bans`. */
+export interface BanPlayerBody {
+  userId: number;
+  reason?: string | null;
+  /** ISO date in the future; omit or null for permanent. */
+  expiresAt?: string | null;
+  /**
+   * Also withdraw the entry the player registered (with its refund), while
+   * the tournament still takes entries. Host bans apply it across all of the
+   * host's open tournaments.
+   */
+  removeEntry?: boolean;
+}
+
+/** Why `removeEntry` left an entry where it was. */
+export type BanRemovalSkip =
+  /** No entry in this tournament. Never returned for host bans. */
+  | 'notRegistered'
+  /** On a team someone else registered: the team's leader must swap them out. */
+  | 'notRegistrant'
+  /** Past check-in; the bracket is seeded. */
+  | 'entryLocked'
+  /** The withdrawal refused; `message` says why. */
+  | 'failed';
+
+export interface BanRemoval {
+  tournamentDocumentId: string;
+  tournamentTitle: string | null;
+  removed: boolean;
+  /** Coins returned to whoever paid. */
+  refunded: number;
+  skipped?: BanRemovalSkip;
+  message?: string;
+}
+
+/** The `data` of a successful ban. */
+export interface BanResult {
+  ban: PlayerBanSummary;
+  /** Pending join requests declined and refunded because of the ban. */
+  declinedRequests: number;
+  /** Empty unless `removeEntry` was asked for. */
+  removals: BanRemoval[];
+}
+
+/** The durations the ban dialog offers. */
+export const BAN_DURATIONS = [
+  { key: '1d', label: '24 hours', days: 1 },
+  { key: '7d', label: '7 days', days: 7 },
+  { key: '30d', label: '30 days', days: 30 },
+  { key: 'permanent', label: 'Permanent', days: null },
+] as const;
+
+export type BanDurationKey = (typeof BAN_DURATIONS)[number]['key'];
+
+/** `expiresAt` for a duration, or null for permanent. */
+export function banExpiryFor(
+  key: BanDurationKey,
+  now: Date = new Date()
+): string | null {
+  const days = BAN_DURATIONS.find((d) => d.key === key)?.days ?? null;
+  return days == null
+    ? null
+    : new Date(now.getTime() + days * 86_400_000).toISOString();
+}
+
+export function isBanActive(
+  ban: { liftedAt?: string | null; expiresAt?: string | null },
+  now: Date = new Date()
+): boolean {
+  if (ban.liftedAt) return false;
+  if (!ban.expiresAt) return true;
+  return new Date(ban.expiresAt).getTime() > now.getTime();
+}

package/src/manual/tournamentStaff.ts

@@ -51,7 +51,9 @@ export type TournamentStaffAction =
   /** Record scores, start matches, edit match details. */
   | 'manageMatches'
   /** Watch any lobby and post as staff in its chat. */
-  | 'enterLobby';
+  | 'enterLobby'
+  /** Ban players from this tournament and lift those bans. */
+  | 'manageBans';
 
 const OWNER_ONLY = ['owner'] as const;
 const ADMIN_UP = ['owner', 'admin'] as const;
@@ -72,6 +74,7 @@ export const TOURNAMENT_STAFF_CAPABILITIES: Record<
   reviewJoinRequests: ADMIN_UP,
   resolveDispute: ADMIN_UP,
   seedBracket: ADMIN_UP,
+  manageBans: ADMIN_UP,
   manageMatches: ALL_STAFF,
   enterLobby: ALL_STAFF,
 };