xpt-shared-types 1.16.0 → 1.19.0

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,
 };