xpt-shared-types 1.11.0 → 1.12.0

package/dist/manual/index.d.ts

@@ -6,3 +6,4 @@ export * from './lobby';
 export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';
+export * from './tournamentStaff';

package/dist/manual/index.js

@@ -22,3 +22,4 @@ __exportStar(require("./lobby"), exports);
 __exportStar(require("./tournamentEntry"), exports);
 __exportStar(require("./tournamentInvite"), exports);
 __exportStar(require("./tournamentJoinRequest"), exports);
+__exportStar(require("./tournamentStaff"), exports);

package/dist/manual/tournamentStaff.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Tournament staff — who runs a tournament and what each of them may do.
+ *
+ * Three roles. The **owner** is the tournament's `users_permissions_user`
+ * and never a row; **admin** and **moderator** are `tournament-role` rows
+ * (the `TournamentRoleRole` enum is generated from the schema). A row with
+ * no role value is read as a moderator, the least the row can mean.
+ *
+ * The capability table is the contract between the server's guards and the
+ * client's buttons: both resolve the viewer's role with
+ * `resolveTournamentStaffRole` and ask `canTournamentStaff`, so a control is
+ * never offered for a request the server would refuse. Money and the
+ * irreversible lifecycle steps stay with the owner; admins run the event;
+ * moderators run matches.
+ */
+import type { TournamentRoleRole } from '../generated/enums';
+export type TournamentStaffRole = 'owner' | TournamentRoleRole;
+/** The roles the owner can hand out — everything but their own. */
+export type TournamentAppointedRole = TournamentRoleRole;
+export declare const APPOINTABLE_STAFF_ROLES: readonly ["admin", "moderator"];
+export type TournamentStaffAction = 
+/** Appoint, re-role or remove admins and moderators. */
+'manageStaff'
+/** `PUT /tournaments/:id` — info, rules, stages, links. */
+ | 'editTournament'
+/** Draft → open; debits the prize pool. */
+ | 'publish'
+/** Drafts only. */
+ | 'delete'
+/** The forward transitions: checkIn, seeding, live, completed. */
+ | 'changeStatus'
+/** Refunds every entrant. */
+ | 'cancel' | 'distributePrizes' | 'manageInvites' | 'reviewJoinRequests' | 'resolveDispute'
+/** Seed, initialise the bracket, place players in slots. */
+ | 'seedBracket'
+/** Record scores, start matches, edit match details. */
+ | 'manageMatches'
+/** Watch any lobby and post as staff in its chat. */
+ | 'enterLobby';
+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;
+/** Only what the resolver reads; both apps' tournament shapes satisfy it. */
+export interface TournamentStaffLike {
+    users_permissions_user?: {
+        id?: number | string | null;
+    } | null;
+    tournament_roles?: Array<{
+        role?: string | null;
+        users_permissions_user?: {
+            id?: number | string | null;
+        } | null;
+    }> | null;
+}
+/** An appointed row's role, defaulting an unset value to the least it can mean. */
+export declare const appointedRoleOf: (role: string | null | undefined) => TournamentAppointedRole;
+/**
+ * The viewer's staff role on a tournament, or null for everyone else. The
+ * owner wins over any row they might also hold.
+ */
+export declare function resolveTournamentStaffRole(tournament: TournamentStaffLike | null | undefined, userId: number | string | null | undefined): TournamentStaffRole | null;
+export declare const canTournamentStaff: (role: TournamentStaffRole | null | undefined, action: TournamentStaffAction) => boolean;
+/** `canTournamentStaff` for a viewer, resolving their role first. */
+export declare const tournamentStaffCan: (tournament: TournamentStaffLike | null | undefined, userId: number | string | null | undefined, action: TournamentStaffAction) => boolean;
+/** Staff can be changed until the tournament is settled. */
+export declare const STAFF_EDITABLE_STATUSES: readonly ["draft", "open", "checkIn", "seeding", "live"];
+export declare const isTournamentStaffEditable: (status: string | null | undefined) => boolean;
+/** One appointee as the owner's dialog sends it. */
+export interface TournamentStaffMemberInput {
+    /** The user's documentId — what the search results carry. */
+    userDocumentId: string;
+    role: TournamentAppointedRole;
+}
+/** The whole appointed list; the server diffs it against the rows. */
+export interface UpdateTournamentStaffBody {
+    data: {
+        staff: TournamentStaffMemberInput[];
+    };
+}
+/** `error.details.name` values the staff routes raise. */
+export type TournamentStaffErrorName = 'NotTournamentStaff';

package/dist/manual/tournamentStaff.js

@@ -0,0 +1,83 @@
+"use strict";
+/**
+ * Tournament staff — who runs a tournament and what each of them may do.
+ *
+ * Three roles. The **owner** is the tournament's `users_permissions_user`
+ * and never a row; **admin** and **moderator** are `tournament-role` rows
+ * (the `TournamentRoleRole` enum is generated from the schema). A row with
+ * no role value is read as a moderator, the least the row can mean.
+ *
+ * The capability table is the contract between the server's guards and the
+ * client's buttons: both resolve the viewer's role with
+ * `resolveTournamentStaffRole` and ask `canTournamentStaff`, so a control is
+ * never offered for a request the server would refuse. Money and the
+ * irreversible lifecycle steps stay with the owner; admins run the event;
+ * moderators run matches.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTournamentStaffEditable = exports.STAFF_EDITABLE_STATUSES = exports.tournamentStaffCan = exports.canTournamentStaff = exports.appointedRoleOf = exports.tournamentStaffRoleLabel = exports.TOURNAMENT_STAFF_ROLE_LABELS = exports.TOURNAMENT_STAFF_CAPABILITIES = exports.APPOINTABLE_STAFF_ROLES = void 0;
+exports.resolveTournamentStaffRole = resolveTournamentStaffRole;
+exports.APPOINTABLE_STAFF_ROLES = [
+    'admin',
+    'moderator',
+];
+const OWNER_ONLY = ['owner'];
+const ADMIN_UP = ['owner', 'admin'];
+const ALL_STAFF = ['owner', 'admin', 'moderator'];
+exports.TOURNAMENT_STAFF_CAPABILITIES = {
+    manageStaff: OWNER_ONLY,
+    publish: OWNER_ONLY,
+    delete: OWNER_ONLY,
+    cancel: OWNER_ONLY,
+    distributePrizes: OWNER_ONLY,
+    editTournament: ADMIN_UP,
+    changeStatus: ADMIN_UP,
+    manageInvites: ADMIN_UP,
+    reviewJoinRequests: ADMIN_UP,
+    resolveDispute: ADMIN_UP,
+    seedBracket: ADMIN_UP,
+    manageMatches: ALL_STAFF,
+    enterLobby: ALL_STAFF,
+};
+exports.TOURNAMENT_STAFF_ROLE_LABELS = {
+    owner: 'Owner',
+    admin: 'Admin',
+    moderator: 'Moderator',
+};
+const tournamentStaffRoleLabel = (role) => {
+    var _a, _b;
+    return (_b = exports.TOURNAMENT_STAFF_ROLE_LABELS[(_a = role) !== null && _a !== void 0 ? _a : 'moderator']) !== null && _b !== void 0 ? _b : 'Moderator';
+};
+exports.tournamentStaffRoleLabel = tournamentStaffRoleLabel;
+const sameId = (a, b) => a != null && b != null && String(a) === String(b);
+/** An appointed row's role, defaulting an unset value to the least it can mean. */
+const appointedRoleOf = (role) => (role === 'admin' ? 'admin' : 'moderator');
+exports.appointedRoleOf = appointedRoleOf;
+/**
+ * The viewer's staff role on a tournament, or null for everyone else. The
+ * owner wins over any row they might also hold.
+ */
+function resolveTournamentStaffRole(tournament, userId) {
+    var _a, _b;
+    if (!tournament || userId == null)
+        return null;
+    if (sameId((_a = tournament.users_permissions_user) === null || _a === void 0 ? void 0 : _a.id, userId))
+        return 'owner';
+    const row = ((_b = tournament.tournament_roles) !== null && _b !== void 0 ? _b : []).find((r) => { var _a; return sameId((_a = r === null || r === void 0 ? void 0 : r.users_permissions_user) === null || _a === void 0 ? void 0 : _a.id, userId); });
+    return row ? (0, exports.appointedRoleOf)(row.role) : null;
+}
+const canTournamentStaff = (role, action) => role != null && exports.TOURNAMENT_STAFF_CAPABILITIES[action].includes(role);
+exports.canTournamentStaff = canTournamentStaff;
+/** `canTournamentStaff` for a viewer, resolving their role first. */
+const tournamentStaffCan = (tournament, userId, action) => (0, exports.canTournamentStaff)(resolveTournamentStaffRole(tournament, userId), action);
+exports.tournamentStaffCan = tournamentStaffCan;
+/** Staff can be changed until the tournament is settled. */
+exports.STAFF_EDITABLE_STATUSES = [
+    'draft',
+    'open',
+    'checkIn',
+    'seeding',
+    'live',
+];
+const isTournamentStaffEditable = (status) => exports.STAFF_EDITABLE_STATUSES.includes(status !== null && status !== void 0 ? status : '');
+exports.isTournamentStaffEditable = isTournamentStaffEditable;

package/package.json

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

package/src/manual/index.ts

@@ -6,3 +6,4 @@ export * from './lobby';
 export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';
+export * from './tournamentStaff';

package/src/manual/tournamentStaff.ts

@@ -0,0 +1,169 @@
+/**
+ * Tournament staff — who runs a tournament and what each of them may do.
+ *
+ * Three roles. The **owner** is the tournament's `users_permissions_user`
+ * and never a row; **admin** and **moderator** are `tournament-role` rows
+ * (the `TournamentRoleRole` enum is generated from the schema). A row with
+ * no role value is read as a moderator, the least the row can mean.
+ *
+ * The capability table is the contract between the server's guards and the
+ * client's buttons: both resolve the viewer's role with
+ * `resolveTournamentStaffRole` and ask `canTournamentStaff`, so a control is
+ * never offered for a request the server would refuse. Money and the
+ * irreversible lifecycle steps stay with the owner; admins run the event;
+ * moderators run matches.
+ */
+
+import type {
+  TournamentCurrentStatus,
+  TournamentRoleRole,
+} from '../generated/enums';
+
+export type TournamentStaffRole = 'owner' | TournamentRoleRole;
+
+/** The roles the owner can hand out — everything but their own. */
+export type TournamentAppointedRole = TournamentRoleRole;
+
+export const APPOINTABLE_STAFF_ROLES = [
+  'admin',
+  'moderator',
+] as const satisfies readonly TournamentAppointedRole[];
+
+export type TournamentStaffAction =
+  /** Appoint, re-role or remove admins and moderators. */
+  | 'manageStaff'
+  /** `PUT /tournaments/:id` — info, rules, stages, links. */
+  | 'editTournament'
+  /** Draft → open; debits the prize pool. */
+  | 'publish'
+  /** Drafts only. */
+  | 'delete'
+  /** The forward transitions: checkIn, seeding, live, completed. */
+  | 'changeStatus'
+  /** Refunds every entrant. */
+  | 'cancel'
+  | 'distributePrizes'
+  | 'manageInvites'
+  | 'reviewJoinRequests'
+  | 'resolveDispute'
+  /** Seed, initialise the bracket, place players in slots. */
+  | 'seedBracket'
+  /** Record scores, start matches, edit match details. */
+  | 'manageMatches'
+  /** Watch any lobby and post as staff in its chat. */
+  | 'enterLobby';
+
+const OWNER_ONLY = ['owner'] as const;
+const ADMIN_UP = ['owner', 'admin'] as const;
+const ALL_STAFF = ['owner', 'admin', 'moderator'] as const;
+
+export const TOURNAMENT_STAFF_CAPABILITIES: Record<
+  TournamentStaffAction,
+  readonly TournamentStaffRole[]
+> = {
+  manageStaff: OWNER_ONLY,
+  publish: OWNER_ONLY,
+  delete: OWNER_ONLY,
+  cancel: OWNER_ONLY,
+  distributePrizes: OWNER_ONLY,
+  editTournament: ADMIN_UP,
+  changeStatus: ADMIN_UP,
+  manageInvites: ADMIN_UP,
+  reviewJoinRequests: ADMIN_UP,
+  resolveDispute: ADMIN_UP,
+  seedBracket: ADMIN_UP,
+  manageMatches: ALL_STAFF,
+  enterLobby: ALL_STAFF,
+};
+
+export const TOURNAMENT_STAFF_ROLE_LABELS: Record<TournamentStaffRole, string> =
+  {
+    owner: 'Owner',
+    admin: 'Admin',
+    moderator: 'Moderator',
+  };
+
+export const tournamentStaffRoleLabel = (
+  role: string | null | undefined
+): string =>
+  TOURNAMENT_STAFF_ROLE_LABELS[(role as TournamentStaffRole) ?? 'moderator'] ??
+  'Moderator';
+
+/** Only what the resolver reads; both apps' tournament shapes satisfy it. */
+export interface TournamentStaffLike {
+  users_permissions_user?: { id?: number | string | null } | null;
+  tournament_roles?: Array<{
+    role?: string | null;
+    users_permissions_user?: { id?: number | string | null } | null;
+  }> | null;
+}
+
+const sameId = (
+  a: number | string | null | undefined,
+  b: number | string | null | undefined
+): boolean => a != null && b != null && String(a) === String(b);
+
+/** An appointed row's role, defaulting an unset value to the least it can mean. */
+export const appointedRoleOf = (
+  role: string | null | undefined
+): TournamentAppointedRole => (role === 'admin' ? 'admin' : 'moderator');
+
+/**
+ * The viewer's staff role on a tournament, or null for everyone else. The
+ * owner wins over any row they might also hold.
+ */
+export function resolveTournamentStaffRole(
+  tournament: TournamentStaffLike | null | undefined,
+  userId: number | string | null | undefined
+): TournamentStaffRole | null {
+  if (!tournament || userId == null) return null;
+  if (sameId(tournament.users_permissions_user?.id, userId)) return 'owner';
+  const row = (tournament.tournament_roles ?? []).find((r) =>
+    sameId(r?.users_permissions_user?.id, userId)
+  );
+  return row ? appointedRoleOf(row.role) : null;
+}
+
+export const canTournamentStaff = (
+  role: TournamentStaffRole | null | undefined,
+  action: TournamentStaffAction
+): boolean =>
+  role != null && TOURNAMENT_STAFF_CAPABILITIES[action].includes(role);
+
+/** `canTournamentStaff` for a viewer, resolving their role first. */
+export const tournamentStaffCan = (
+  tournament: TournamentStaffLike | null | undefined,
+  userId: number | string | null | undefined,
+  action: TournamentStaffAction
+): boolean =>
+  canTournamentStaff(resolveTournamentStaffRole(tournament, userId), action);
+
+/** Staff can be changed until the tournament is settled. */
+export const STAFF_EDITABLE_STATUSES = [
+  'draft',
+  'open',
+  'checkIn',
+  'seeding',
+  'live',
+] as const satisfies readonly TournamentCurrentStatus[];
+
+export const isTournamentStaffEditable = (
+  status: string | null | undefined
+): boolean => (STAFF_EDITABLE_STATUSES as readonly string[]).includes(status ?? '');
+
+// ─── `PUT /tournaments/:id/staff` ────────────────────────────────────────────
+
+/** One appointee as the owner's dialog sends it. */
+export interface TournamentStaffMemberInput {
+  /** The user's documentId — what the search results carry. */
+  userDocumentId: string;
+  role: TournamentAppointedRole;
+}
+
+/** The whole appointed list; the server diffs it against the rows. */
+export interface UpdateTournamentStaffBody {
+  data: { staff: TournamentStaffMemberInput[] };
+}
+
+/** `error.details.name` values the staff routes raise. */
+export type TournamentStaffErrorName = 'NotTournamentStaff';