xpt-shared-types 1.16.0 → 1.19.0

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.19.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,28 @@ 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"
+  | "linked";
+
 /** `Game.genre` */
 export type GameGenre =
   | "FPS"
@@ -126,6 +148,11 @@ export type PlatformCode =
   | "nintendo"
   | "mobile";
 
+/** `PlayerBan.scope` */
+export type PlayerBanScope =
+  | "tournament"
+  | "host";
+
 /** `Referral.status` */
 export type ReferralStatus =
   | "pending"
@@ -228,6 +255,10 @@ export type TournamentVisibility =
   | "public"
   | "unlisted";
 
+/** `UserGameAccount.verificationMethod` */
+export type UserGameAccountVerificationMethod =
+  | "linked";
+
 /** `UserTransaction.stripeStatus` */
 export type UserTransactionStripeStatus =
   | "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,
@@ -39,6 +42,7 @@ import type {
   TournamentTeamSize,
   TournamentType,
   TournamentVisibility,
+  UserGameAccountVerificationMethod,
   UserTransactionStripeStatus,
   UserTransactionType,
 } from './enums';
@@ -126,6 +130,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;
@@ -133,6 +139,15 @@ export interface GameAccountInput {
   platforms?: RelationInput | RelationInput[];
 }
 
+/** Write payload for `game-account-link`. */
+export interface GameAccountLinkInput {
+  token?: string;
+  users_permissions_user?: RelationInput;
+  game_account?: RelationInput;
+  expiresAt?: string;
+  returnTo?: string;
+}
+
 /** Write payload for `game-request`. */
 export interface GameRequestInput {
   gameTitle?: string;
@@ -247,6 +262,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;
@@ -494,6 +522,9 @@ export interface UserInput {
 export interface UserGameAccountInput {
   accountId?: string;
   isPrivate?: boolean;
+  verifiedAt?: string;
+  verificationMethod?: UserGameAccountVerificationMethod;
+  providerAccountId?: string;
   users_permissions_user?: RelationInput;
   game_account?: RelationInput;
 }

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,
@@ -40,6 +43,7 @@ import type {
   TournamentTeamSize,
   TournamentType,
   TournamentVisibility,
+  UserGameAccountVerificationMethod,
   UserTransactionStripeStatus,
   UserTransactionType,
 } from './enums';
@@ -127,6 +131,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;
@@ -134,6 +140,15 @@ export interface GameAccount extends StrapiDocument {
   platforms?: Platform[];
 }
 
+/** `game-account-link` */
+export interface GameAccountLink extends StrapiDocument {
+  token?: string | null;
+  users_permissions_user?: User | null;
+  game_account?: GameAccount | null;
+  expiresAt?: string | null;
+  returnTo?: string | null;
+}
+
 /** `game-request` */
 export interface GameRequest extends StrapiDocument {
   gameTitle?: string | null;
@@ -248,6 +263,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;
@@ -495,6 +523,9 @@ export interface User extends StrapiDocument {
 export interface UserGameAccount extends StrapiDocument {
   accountId?: string | null;
   isPrivate?: boolean | null;
+  verifiedAt?: string | null;
+  verificationMethod?: UserGameAccountVerificationMethod | null;
+  providerAccountId?: string | null;
   users_permissions_user?: User | null;
   game_account?: GameAccount | null;
 }

package/src/manual/gameAccountHandle.ts

@@ -0,0 +1,306 @@
+/**
+ * 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 row is verified by a link; unlink before changing the ID. */
+  | 'HandleLocked'
+  /** No configured link provider for this network. */
+  | 'LinkUnavailable'
+  /** The provider account is already linked to another XPT user. */
+  | 'LinkConflict';
+
+/**
+ * Networks whose handles can be verified by signing in to the network. The
+ * catalogue's `verification: 'linked'` is only valid for these; whether a
+ * provider is actually configured on a given environment is answered at
+ * runtime by `GET /user-game-accounts/link/providers`.
+ */
+export const LINK_PROVIDER_CODES = ['steam', 'battlenet'] as const satisfies
+  readonly GameAccountCode[];
+
+export type LinkProviderCode = (typeof LINK_PROVIDER_CODES)[number];
+
+export function isLinkableCode(
+  code: string | null | undefined
+): code is LinkProviderCode {
+  return (LINK_PROVIDER_CODES as readonly string[]).includes(code ?? '');
+}
+
+/**
+ * Why a link attempt came back without a verified account — the `linkError`
+ * query value the callback redirects to the settings page with.
+ */
+export type AccountLinkError =
+  /** The attempt was unknown, already used, or older than its window. */
+  | 'expired'
+  /** The player cancelled at the provider. */
+  | 'denied'
+  /** The provider's answer did not verify. */
+  | 'invalid'
+  /** That provider account is already linked to another XPT user. */
+  | 'taken'
+  /** The provider is not configured, or the network is not linkable. */
+  | 'unavailable'
+  /** Accounts are frozen while the player is in a running tournament. */
+  | 'activeTournament';
+
+/** True when a row's handle was proved by signing in to the network. */
+export function isVerifiedAccount(
+  row:
+    | { verifiedAt?: string | Date | null; verificationMethod?: string | null }
+    | null
+    | undefined
+): boolean {
+  return !!row?.verifiedAt && row.verificationMethod === 'linked';
+}
+
+/**
+ * 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 (or is linkable, which implies them
+ * for anything typed by hand) 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 {
+  const checked =
+    network?.verification === 'format' || network?.verification === 'linked';
+  if (!checked || !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';