xpt-shared-types 1.9.0 → 1.12.0

package/dist/generated/enums.d.ts

@@ -1,3 +1,5 @@
+/** `Faq.category` */
+export type FaqCategory = "gettingStarted" | "tournamentsMatches" | "hosting" | "walletCoins" | "account";
 /** `Friendship.status` */
 export type FriendshipStatus = "pending" | "accepted";
 /** `Game.genre` */
@@ -34,8 +36,16 @@ export type TeamInviteStatus = "pending" | "accepted" | "declined";
 export type TeamInviteTeamRole = "captain" | "co_captain" | "player" | "substitute" | "coach";
 /** `TeamPlayer.team_role` */
 export type TeamPlayerTeamRole = "captain" | "co_captain" | "player" | "substitute" | "coach";
+/** `Tournament.access` */
+export type TournamentAccess = "open" | "inviteOnly" | "approval";
 /** `Tournament.currentStatus` */
 export type TournamentCurrentStatus = "draft" | "open" | "checkIn" | "seeding" | "live" | "completed" | "cancelled";
+/** `TournamentInvite.status` */
+export type TournamentInviteStatus = "active" | "revoked";
+/** `TournamentJoinRequest.entryType` */
+export type TournamentJoinRequestEntryType = "solo" | "team";
+/** `TournamentJoinRequest.status` */
+export type TournamentJoinRequestStatus = "pending" | "approved" | "declined" | "withdrawn" | "expired";
 /** `TournamentParticipant.entryType` */
 export type TournamentParticipantEntryType = "solo" | "team";
 /** `TournamentParticipant.status` */
@@ -46,6 +56,8 @@ export type TournamentRoleRole = "moderator" | "admin";
 export type TournamentTeamSize = "one" | "two" | "three" | "four" | "five";
 /** `Tournament.type` */
 export type TournamentType = "Single Elimination" | "League" | "Double Elimination";
+/** `Tournament.visibility` */
+export type TournamentVisibility = "public" | "unlisted";
 /** `UserTransaction.stripeStatus` */
 export type UserTransactionStripeStatus = "pending" | "completed" | "failed" | "refunded" | "internal";
 /** `UserTransaction.type` */

package/dist/generated/inputs.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, MediaInput, RelationInput } from '../contracts';
-import type { FriendshipStatus, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentCurrentStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { 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';
 /** Write payload for `about`. */
 export interface AboutInput {
     heroTitle?: string;
@@ -18,6 +18,9 @@ export interface DmMessageInput {
 export interface FaqInput {
     question?: string;
     answer?: BlocksContent;
+    category?: FaqCategory;
+    note?: string;
+    order?: number;
 }
 /** Write payload for `featured-game`. */
 export interface FeaturedGameInput {
@@ -297,7 +300,8 @@ export interface TournamentInput {
     rules?: string;
     hasThirdPlace?: boolean;
     hasMatchLobby?: boolean;
-    isPrivate?: boolean;
+    visibility?: TournamentVisibility;
+    access?: TournamentAccess;
     checkInTime?: number;
     region?: RelationInput;
     platform?: RelationInput;
@@ -309,6 +313,32 @@ export interface TournamentInput {
     twitchUrl?: string;
     websiteUrl?: string;
 }
+/** Write payload for `tournament-invite`. */
+export interface TournamentInviteInput {
+    tournament?: RelationInput;
+    createdByUser?: RelationInput;
+    status?: TournamentInviteStatus;
+    expiresAt?: string;
+    revokedAt?: string;
+    useCount?: number;
+    lastUsedAt?: string;
+}
+/** Write payload for `tournament-join-request`. */
+export interface TournamentJoinRequestInput {
+    tournament?: RelationInput;
+    requester?: RelationInput;
+    entryType?: TournamentJoinRequestEntryType;
+    team?: RelationInput;
+    selectedMemberIds?: unknown;
+    membersSnapshot?: unknown;
+    displayName?: string;
+    message?: string;
+    feePaid?: number;
+    status?: TournamentJoinRequestStatus;
+    decidedAt?: string;
+    decidedBy?: RelationInput;
+    decisionReason?: string;
+}
 /** Write payload for `tournament-participant`. */
 export interface TournamentParticipantInput {
     tournament?: RelationInput;

package/dist/generated/models.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, StrapiDocument, StrapiMedia, UserRole } from '../contracts';
-import type { FriendshipStatus, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentCurrentStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { 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';
 /** `about` */
 export interface About extends StrapiDocument {
     heroTitle?: string | null;
@@ -18,6 +18,9 @@ export interface DmMessage extends StrapiDocument {
 export interface Faq extends StrapiDocument {
     question?: string | null;
     answer?: BlocksContent | null;
+    category?: FaqCategory | null;
+    note?: string | null;
+    order?: number | null;
 }
 /** `featured-game` */
 export interface FeaturedGame extends StrapiDocument {
@@ -297,7 +300,8 @@ export interface Tournament extends StrapiDocument {
     rules?: string | null;
     hasThirdPlace?: boolean | null;
     hasMatchLobby?: boolean | null;
-    isPrivate?: boolean | null;
+    visibility?: TournamentVisibility | null;
+    access?: TournamentAccess | null;
     checkInTime?: number | null;
     region?: Region | null;
     platform?: Platform | null;
@@ -309,6 +313,32 @@ export interface Tournament extends StrapiDocument {
     twitchUrl?: string | null;
     websiteUrl?: string | null;
 }
+/** `tournament-invite` */
+export interface TournamentInvite extends StrapiDocument {
+    tournament?: Tournament | null;
+    createdByUser?: User | null;
+    status?: TournamentInviteStatus | null;
+    expiresAt?: string | null;
+    revokedAt?: string | null;
+    useCount?: number | null;
+    lastUsedAt?: string | null;
+}
+/** `tournament-join-request` */
+export interface TournamentJoinRequest extends StrapiDocument {
+    tournament?: Tournament | null;
+    requester?: User | null;
+    entryType?: TournamentJoinRequestEntryType | null;
+    team?: Team | null;
+    selectedMemberIds?: unknown | null;
+    membersSnapshot?: unknown | null;
+    displayName?: string | null;
+    message?: string | null;
+    feePaid?: number | null;
+    status?: TournamentJoinRequestStatus | null;
+    decidedAt?: string | null;
+    decidedBy?: User | null;
+    decisionReason?: string | null;
+}
 /** `tournament-participant` */
 export interface TournamentParticipant extends StrapiDocument {
     tournament?: Tournament | null;

package/dist/manual/index.d.ts

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

package/dist/manual/index.js

@@ -20,3 +20,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./country"), exports);
 __exportStar(require("./lobby"), exports);
 __exportStar(require("./tournamentEntry"), exports);
+__exportStar(require("./tournamentInvite"), exports);
+__exportStar(require("./tournamentJoinRequest"), exports);
+__exportStar(require("./tournamentStaff"), exports);

package/dist/manual/tournamentInvite.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Tournament invite links — the contract between the host's invite dialog,
+ * the invitee's landing page and the five `/tournaments/…/invite(s)` routes.
+ *
+ * The `tournament-invite` content type behind these is generated
+ * (`TournamentInvite` in `generated/models.ts`), but its `token` is a private
+ * attribute the content API never serialises. What the host actually receives
+ * is the summary below, which the service builds by hand and which carries
+ * the token and the ready-made link; what an invitee receives is a fixed,
+ * whitelisted projection of the tournament plus a `state`.
+ */
+import type { TournamentCurrentStatus, TournamentTeamSize, TournamentType } from '../generated/enums';
+import type { StrapiMedia } from '../contracts';
+/**
+ * Statuses in which a host may mint an invite and an invitee may use one.
+ * The same window as joining: a link nobody can use yet is only confusing.
+ */
+export declare const INVITABLE_STATUSES: readonly ["open", "checkIn"];
+export type InvitableStatus = (typeof INVITABLE_STATUSES)[number];
+/** True when `status` still lets a host mint, and a player use, a link. */
+export declare function isTournamentInvitable(status: string | null | undefined): status is InvitableStatus;
+/** How long a freshly minted link stays valid, in days. */
+export declare const TOURNAMENT_INVITE_TTL_DAYS = 30;
+/**
+ * What a link resolves to for one signed-in viewer, from
+ * `GET /tournaments/invites/:token`. Reported in a fixed order — row
+ * problems first, then the tournament's window, then the viewer's own
+ * standing — so a page can branch on it without second-guessing.
+ *
+ * Only `valid` lets the join button through. The join itself re-checks
+ * capacity and duplicates under the tournament row lock, so `full` and
+ * `alreadyRegistered` here are a courtesy, not the guard.
+ */
+export type TournamentInviteState = 'valid' | 'revoked' | 'expired' | 'notOpen' | 'closed' | 'full' | 'alreadyRegistered' | 'host';
+/**
+ * The host's view, from `GET`/`POST`/`DELETE /tournaments/:id/invite`.
+ * `GET` answers `null` when no link has been minted; `DELETE` answers the
+ * revoked row, or `null` when there was nothing to revoke.
+ */
+export interface TournamentInviteSummary {
+    documentId: string;
+    /** The secret. Only ever sent to the host. */
+    token: string;
+    /** The landing URL, minted server-side from `FRONTEND_URL`: `/invite/<token>`. */
+    url: string;
+    status: 'active' | 'revoked';
+    expiresAt: string | null;
+    createdAt: string | null;
+    revokedAt: string | null;
+    /** Successful joins through this link. */
+    useCount: number;
+}
+/**
+ * The slice of a tournament an invitee may see before joining. Nothing here
+ * that the public tournament page does not already show: no participant
+ * list, no host id.
+ */
+export interface TournamentInviteTournament {
+    documentId: string;
+    title: string | null;
+    slug: string | null;
+    currentStatus: TournamentCurrentStatus | null;
+    dateTime: string | null;
+    entryFee: number | null;
+    /** Declared capacity, in entries. */
+    participants: number | null;
+    /** Entries taken so far. */
+    entrantCount: number;
+    teamSize: TournamentTeamSize | null;
+    type: TournamentType | null;
+    imgMain: StrapiMedia | null;
+    game: {
+        documentId?: string;
+        title?: string | null;
+        slug?: string | null;
+    } | null;
+    gameAccount: {
+        documentId?: string;
+        name?: string | null;
+    } | null;
+    platform: {
+        documentId?: string;
+        name?: string | null;
+    } | null;
+    host: {
+        username?: string | null;
+    } | null;
+}
+/** Body of `GET /tournaments/invites/:token` for a signed-in viewer. */
+export interface TournamentInvitePreview {
+    state: TournamentInviteState;
+    expiresAt: string | null;
+    tournament: TournamentInviteTournament;
+}
+/**
+ * Body of `POST /tournaments/invites/:token/join`. Flat, exactly like
+ * `POST /tournaments/:id/join`: omit both for a solo entry, send both for a
+ * team entry.
+ */
+export interface TournamentInviteJoinInput {
+    teamId?: string;
+    selectedMemberIds?: number[];
+}
+/**
+ * `error.details.name` values the invite routes raise. `NotTournamentHost`
+ * arrives as a 403 and `InviteNotFound` as a 404; `InviteUnavailable` is a
+ * 400 whose `details.state` is `revoked` or `expired`. A join through a link
+ * can also raise any `TournamentEntryErrorName`, since it is the same join.
+ */
+export type TournamentInviteErrorName = 'NotTournamentHost' | 'InviteNotFound' | 'InviteUnavailable'
+/** An invite-only tournament was joined without a link (plain `/join`, 400). */
+ | 'InviteRequired'
+/** An approval tournament was joined without a link or the host's yes. */
+ | 'ApprovalRequired';

package/dist/manual/tournamentInvite.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * Tournament invite links — the contract between the host's invite dialog,
+ * the invitee's landing page and the five `/tournaments/…/invite(s)` routes.
+ *
+ * The `tournament-invite` content type behind these is generated
+ * (`TournamentInvite` in `generated/models.ts`), but its `token` is a private
+ * attribute the content API never serialises. What the host actually receives
+ * is the summary below, which the service builds by hand and which carries
+ * the token and the ready-made link; what an invitee receives is a fixed,
+ * whitelisted projection of the tournament plus a `state`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOURNAMENT_INVITE_TTL_DAYS = exports.INVITABLE_STATUSES = void 0;
+exports.isTournamentInvitable = isTournamentInvitable;
+/**
+ * Statuses in which a host may mint an invite and an invitee may use one.
+ * The same window as joining: a link nobody can use yet is only confusing.
+ */
+exports.INVITABLE_STATUSES = ['open', 'checkIn'];
+/** True when `status` still lets a host mint, and a player use, a link. */
+function isTournamentInvitable(status) {
+    return exports.INVITABLE_STATUSES.includes(status !== null && status !== void 0 ? status : '');
+}
+/** How long a freshly minted link stays valid, in days. */
+exports.TOURNAMENT_INVITE_TTL_DAYS = 30;

package/dist/manual/tournamentJoinRequest.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Visibility, access and join requests — the contract between the host's
+ * Info dialog, the Join CTA, the Participants dialog and the
+ * `/tournaments/:id/join-requests` routes.
+ *
+ * The enums themselves are generated (`TournamentVisibility`,
+ * `TournamentAccess`, `TournamentJoinRequestStatus`); this file holds the
+ * response shapes the service builds by hand, the inputs, and the small
+ * predicates both apps branch on so their buttons and the server agree.
+ */
+import type { TournamentAccess, TournamentJoinRequestStatus, TournamentVisibility } from '../generated/enums';
+import type { StrapiMedia } from '../contracts';
+/** Statuses in which a player may request and a host may approve. */
+export declare const REQUESTABLE_STATUSES: readonly ["open", "checkIn"];
+export declare function isTournamentRequestable(status: string | null | undefined): boolean;
+/** Entry needs the host's link — or, on an approval tournament, their yes. */
+export declare const isInviteOnly: (access: string | null | undefined) => boolean;
+export declare const isApprovalAccess: (access: string | null | undefined) => boolean;
+/**
+ * The host's Invite button shows only where the public door is shut: on an
+ * invite-only tournament the link is the only way in, on an approval one it
+ * is a way past the queue. An open tournament has the public Share button.
+ */
+export declare const showsInviteButton: (access: string | null | undefined) => boolean;
+export declare const isUnlistedVisibility: (visibility: string | null | undefined) => boolean;
+/** Copy for the Info card and dialogs. One place, so every surface agrees. */
+export declare const VISIBILITY_LABELS: Record<TournamentVisibility, string>;
+export declare const ACCESS_LABELS: Record<TournamentAccess, string>;
+export declare const visibilityLabel: (visibility: string | null | undefined) => string;
+export declare const accessLabel: (access: string | null | undefined) => string;
+/** What clients see of a request. Nothing the participants list would not show. */
+export interface TournamentJoinRequestSummary {
+    documentId: string;
+    status: TournamentJoinRequestStatus;
+    entryType: 'solo' | 'team';
+    displayName: string | null;
+    message: string | null;
+    /** Held from the requester's wallet until the host decides. */
+    feePaid: number;
+    createdAt: string | null;
+    decidedAt: string | null;
+    requester: {
+        id: number;
+        username: string | null;
+        image: StrapiMedia | null;
+    } | null;
+    team: {
+        documentId: string;
+        name: string | null;
+    } | null;
+    /** The roster as requested; the approval re-reads the live one. */
+    membersSnapshot: unknown;
+    memberCount: number;
+}
+/** Body of `GET /tournaments/:id/join-requests` for a signed-in viewer. */
+export interface TournamentJoinRequestsResponse {
+    /** Pending requests, oldest first. Empty for anyone but the host. */
+    requests: TournamentJoinRequestSummary[];
+    /** The viewer's own most recent request, whatever its status. */
+    mine: TournamentJoinRequestSummary | null;
+    pendingCount: number;
+}
+/**
+ * Body of `POST /tournaments/:id/join-requests` (the generated `TournamentJoinRequestInput` is the row's write shape). Flat, like `/join`: omit
+ * the team fields for a solo entry, send both for a team entry.
+ */
+export interface TournamentJoinRequestBody {
+    teamId?: string;
+    selectedMemberIds?: number[];
+    /** ≤200 characters, shown to the host with the request. */
+    message?: string;
+}
+/**
+ * `error.details.name` values the join-request routes raise. `NotTournamentHost`
+ * is a 403 and `JoinRequestNotFound` a 404; the rest are 400s. A plain `/join`
+ * on an approval tournament raises `ApprovalRequired`. An approval runs the
+ * ordinary join, so it can also raise any `TournamentEntryErrorName`.
+ */
+export type TournamentJoinRequestErrorName = 'ApprovalRequired' | 'JoinRequestNotAllowed' | 'JoinRequestPending' | 'JoinRequestNotFound' | 'JoinRequestNotPending' | 'NotTournamentHost';

package/dist/manual/tournamentJoinRequest.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * Visibility, access and join requests — the contract between the host's
+ * Info dialog, the Join CTA, the Participants dialog and the
+ * `/tournaments/:id/join-requests` routes.
+ *
+ * The enums themselves are generated (`TournamentVisibility`,
+ * `TournamentAccess`, `TournamentJoinRequestStatus`); this file holds the
+ * response shapes the service builds by hand, the inputs, and the small
+ * predicates both apps branch on so their buttons and the server agree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accessLabel = exports.visibilityLabel = exports.ACCESS_LABELS = exports.VISIBILITY_LABELS = exports.isUnlistedVisibility = exports.showsInviteButton = exports.isApprovalAccess = exports.isInviteOnly = exports.REQUESTABLE_STATUSES = void 0;
+exports.isTournamentRequestable = isTournamentRequestable;
+/** Statuses in which a player may request and a host may approve. */
+exports.REQUESTABLE_STATUSES = ['open', 'checkIn'];
+function isTournamentRequestable(status) {
+    return exports.REQUESTABLE_STATUSES.includes(status !== null && status !== void 0 ? status : '');
+}
+/** Entry needs the host's link — or, on an approval tournament, their yes. */
+const isInviteOnly = (access) => access === 'inviteOnly';
+exports.isInviteOnly = isInviteOnly;
+const isApprovalAccess = (access) => access === 'approval';
+exports.isApprovalAccess = isApprovalAccess;
+/**
+ * The host's Invite button shows only where the public door is shut: on an
+ * invite-only tournament the link is the only way in, on an approval one it
+ * is a way past the queue. An open tournament has the public Share button.
+ */
+const showsInviteButton = (access) => access === 'inviteOnly' || access === 'approval';
+exports.showsInviteButton = showsInviteButton;
+const isUnlistedVisibility = (visibility) => visibility === 'unlisted';
+exports.isUnlistedVisibility = isUnlistedVisibility;
+/** Copy for the Info card and dialogs. One place, so every surface agrees. */
+exports.VISIBILITY_LABELS = {
+    public: 'Public',
+    unlisted: 'Unlisted',
+};
+exports.ACCESS_LABELS = {
+    open: 'Open',
+    inviteOnly: 'Invite only',
+    approval: 'Approval required',
+};
+const visibilityLabel = (visibility) => { var _a, _b; return (_b = exports.VISIBILITY_LABELS[(_a = visibility) !== null && _a !== void 0 ? _a : 'public']) !== null && _b !== void 0 ? _b : 'Public'; };
+exports.visibilityLabel = visibilityLabel;
+const accessLabel = (access) => { var _a, _b; return (_b = exports.ACCESS_LABELS[(_a = access) !== null && _a !== void 0 ? _a : 'open']) !== null && _b !== void 0 ? _b : 'Open'; };
+exports.accessLabel = accessLabel;

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.9.0",
+  "version": "1.12.0",
   "description": "Shared types and data for XPT projects",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/generated/enums.ts

@@ -2,6 +2,14 @@
 // Source: xpt-strapi/src/**/content-types/**/schema.json
 // Regenerate with: yarn sync
 
+/** `Faq.category` */
+export type FaqCategory =
+  | "gettingStarted"
+  | "tournamentsMatches"
+  | "hosting"
+  | "walletCoins"
+  | "account";
+
 /** `Friendship.status` */
 export type FriendshipStatus =
   | "pending"
@@ -143,6 +151,12 @@ export type TeamPlayerTeamRole =
   | "substitute"
   | "coach";
 
+/** `Tournament.access` */
+export type TournamentAccess =
+  | "open"
+  | "inviteOnly"
+  | "approval";
+
 /** `Tournament.currentStatus` */
 export type TournamentCurrentStatus =
   | "draft"
@@ -153,6 +167,24 @@ export type TournamentCurrentStatus =
   | "completed"
   | "cancelled";
 
+/** `TournamentInvite.status` */
+export type TournamentInviteStatus =
+  | "active"
+  | "revoked";
+
+/** `TournamentJoinRequest.entryType` */
+export type TournamentJoinRequestEntryType =
+  | "solo"
+  | "team";
+
+/** `TournamentJoinRequest.status` */
+export type TournamentJoinRequestStatus =
+  | "pending"
+  | "approved"
+  | "declined"
+  | "withdrawn"
+  | "expired";
+
 /** `TournamentParticipant.entryType` */
 export type TournamentParticipantEntryType =
   | "solo"
@@ -184,6 +216,11 @@ export type TournamentType =
   | "League"
   | "Double Elimination";
 
+/** `Tournament.visibility` */
+export type TournamentVisibility =
+  | "public"
+  | "unlisted";
+
 /** `UserTransaction.stripeStatus` */
 export type UserTransactionStripeStatus =
   | "pending"

package/src/generated/inputs.ts

@@ -8,6 +8,7 @@ import type {
   RelationInput,
 } from '../contracts';
 import type {
+  FaqCategory,
   FriendshipStatus,
   GameGenre,
   GameRequestCustomLobbies,
@@ -26,12 +27,17 @@ import type {
   TeamInviteStatus,
   TeamInviteTeamRole,
   TeamPlayerTeamRole,
+  TournamentAccess,
   TournamentCurrentStatus,
+  TournamentInviteStatus,
+  TournamentJoinRequestEntryType,
+  TournamentJoinRequestStatus,
   TournamentParticipantEntryType,
   TournamentParticipantStatus,
   TournamentRoleRole,
   TournamentTeamSize,
   TournamentType,
+  TournamentVisibility,
   UserTransactionStripeStatus,
   UserTransactionType,
 } from './enums';
@@ -56,6 +62,9 @@ export interface DmMessageInput {
 export interface FaqInput {
   question?: string;
   answer?: BlocksContent;
+  category?: FaqCategory;
+  note?: string;
+  order?: number;
 }
 
 /** Write payload for `featured-game`. */
@@ -363,7 +372,8 @@ export interface TournamentInput {
   rules?: string;
   hasThirdPlace?: boolean;
   hasMatchLobby?: boolean;
-  isPrivate?: boolean;
+  visibility?: TournamentVisibility;
+  access?: TournamentAccess;
   checkInTime?: number;
   region?: RelationInput;
   platform?: RelationInput;
@@ -376,6 +386,34 @@ export interface TournamentInput {
   websiteUrl?: string;
 }
 
+/** Write payload for `tournament-invite`. */
+export interface TournamentInviteInput {
+  tournament?: RelationInput;
+  createdByUser?: RelationInput;
+  status?: TournamentInviteStatus;
+  expiresAt?: string;
+  revokedAt?: string;
+  useCount?: number;
+  lastUsedAt?: string;
+}
+
+/** Write payload for `tournament-join-request`. */
+export interface TournamentJoinRequestInput {
+  tournament?: RelationInput;
+  requester?: RelationInput;
+  entryType?: TournamentJoinRequestEntryType;
+  team?: RelationInput;
+  selectedMemberIds?: unknown;
+  membersSnapshot?: unknown;
+  displayName?: string;
+  message?: string;
+  feePaid?: number;
+  status?: TournamentJoinRequestStatus;
+  decidedAt?: string;
+  decidedBy?: RelationInput;
+  decisionReason?: string;
+}
+
 /** Write payload for `tournament-participant`. */
 export interface TournamentParticipantInput {
   tournament?: RelationInput;

package/src/generated/models.ts

@@ -9,6 +9,7 @@ import type {
   UserRole,
 } from '../contracts';
 import type {
+  FaqCategory,
   FriendshipStatus,
   GameGenre,
   GameRequestCustomLobbies,
@@ -27,12 +28,17 @@ import type {
   TeamInviteStatus,
   TeamInviteTeamRole,
   TeamPlayerTeamRole,
+  TournamentAccess,
   TournamentCurrentStatus,
+  TournamentInviteStatus,
+  TournamentJoinRequestEntryType,
+  TournamentJoinRequestStatus,
   TournamentParticipantEntryType,
   TournamentParticipantStatus,
   TournamentRoleRole,
   TournamentTeamSize,
   TournamentType,
+  TournamentVisibility,
   UserTransactionStripeStatus,
   UserTransactionType,
 } from './enums';
@@ -57,6 +63,9 @@ export interface DmMessage extends StrapiDocument {
 export interface Faq extends StrapiDocument {
   question?: string | null;
   answer?: BlocksContent | null;
+  category?: FaqCategory | null;
+  note?: string | null;
+  order?: number | null;
 }
 
 /** `featured-game` */
@@ -364,7 +373,8 @@ export interface Tournament extends StrapiDocument {
   rules?: string | null;
   hasThirdPlace?: boolean | null;
   hasMatchLobby?: boolean | null;
-  isPrivate?: boolean | null;
+  visibility?: TournamentVisibility | null;
+  access?: TournamentAccess | null;
   checkInTime?: number | null;
   region?: Region | null;
   platform?: Platform | null;
@@ -377,6 +387,34 @@ export interface Tournament extends StrapiDocument {
   websiteUrl?: string | null;
 }
 
+/** `tournament-invite` */
+export interface TournamentInvite extends StrapiDocument {
+  tournament?: Tournament | null;
+  createdByUser?: User | null;
+  status?: TournamentInviteStatus | null;
+  expiresAt?: string | null;
+  revokedAt?: string | null;
+  useCount?: number | null;
+  lastUsedAt?: string | null;
+}
+
+/** `tournament-join-request` */
+export interface TournamentJoinRequest extends StrapiDocument {
+  tournament?: Tournament | null;
+  requester?: User | null;
+  entryType?: TournamentJoinRequestEntryType | null;
+  team?: Team | null;
+  selectedMemberIds?: unknown | null;
+  membersSnapshot?: unknown | null;
+  displayName?: string | null;
+  message?: string | null;
+  feePaid?: number | null;
+  status?: TournamentJoinRequestStatus | null;
+  decidedAt?: string | null;
+  decidedBy?: User | null;
+  decisionReason?: string | null;
+}
+
 /** `tournament-participant` */
 export interface TournamentParticipant extends StrapiDocument {
   tournament?: Tournament | null;

package/src/manual/index.ts

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

package/src/manual/tournamentInvite.ts

@@ -0,0 +1,133 @@
+/**
+ * Tournament invite links — the contract between the host's invite dialog,
+ * the invitee's landing page and the five `/tournaments/…/invite(s)` routes.
+ *
+ * The `tournament-invite` content type behind these is generated
+ * (`TournamentInvite` in `generated/models.ts`), but its `token` is a private
+ * attribute the content API never serialises. What the host actually receives
+ * is the summary below, which the service builds by hand and which carries
+ * the token and the ready-made link; what an invitee receives is a fixed,
+ * whitelisted projection of the tournament plus a `state`.
+ */
+
+import type {
+  TournamentCurrentStatus,
+  TournamentTeamSize,
+  TournamentType,
+} from '../generated/enums';
+import type { StrapiMedia } from '../contracts';
+
+/**
+ * Statuses in which a host may mint an invite and an invitee may use one.
+ * The same window as joining: a link nobody can use yet is only confusing.
+ */
+export const INVITABLE_STATUSES = ['open', 'checkIn'] as const satisfies
+  readonly TournamentCurrentStatus[];
+
+export type InvitableStatus = (typeof INVITABLE_STATUSES)[number];
+
+/** True when `status` still lets a host mint, and a player use, a link. */
+export function isTournamentInvitable(
+  status: string | null | undefined
+): status is InvitableStatus {
+  return (INVITABLE_STATUSES as readonly string[]).includes(status ?? '');
+}
+
+/** How long a freshly minted link stays valid, in days. */
+export const TOURNAMENT_INVITE_TTL_DAYS = 30;
+
+/**
+ * What a link resolves to for one signed-in viewer, from
+ * `GET /tournaments/invites/:token`. Reported in a fixed order — row
+ * problems first, then the tournament's window, then the viewer's own
+ * standing — so a page can branch on it without second-guessing.
+ *
+ * Only `valid` lets the join button through. The join itself re-checks
+ * capacity and duplicates under the tournament row lock, so `full` and
+ * `alreadyRegistered` here are a courtesy, not the guard.
+ */
+export type TournamentInviteState =
+  | 'valid'
+  | 'revoked'
+  | 'expired'
+  | 'notOpen'
+  | 'closed'
+  | 'full'
+  | 'alreadyRegistered'
+  | 'host';
+
+/**
+ * The host's view, from `GET`/`POST`/`DELETE /tournaments/:id/invite`.
+ * `GET` answers `null` when no link has been minted; `DELETE` answers the
+ * revoked row, or `null` when there was nothing to revoke.
+ */
+export interface TournamentInviteSummary {
+  documentId: string;
+  /** The secret. Only ever sent to the host. */
+  token: string;
+  /** The landing URL, minted server-side from `FRONTEND_URL`: `/invite/<token>`. */
+  url: string;
+  status: 'active' | 'revoked';
+  expiresAt: string | null;
+  createdAt: string | null;
+  revokedAt: string | null;
+  /** Successful joins through this link. */
+  useCount: number;
+}
+
+/**
+ * The slice of a tournament an invitee may see before joining. Nothing here
+ * that the public tournament page does not already show: no participant
+ * list, no host id.
+ */
+export interface TournamentInviteTournament {
+  documentId: string;
+  title: string | null;
+  slug: string | null;
+  currentStatus: TournamentCurrentStatus | null;
+  dateTime: string | null;
+  entryFee: number | null;
+  /** Declared capacity, in entries. */
+  participants: number | null;
+  /** Entries taken so far. */
+  entrantCount: number;
+  teamSize: TournamentTeamSize | null;
+  type: TournamentType | null;
+  imgMain: StrapiMedia | null;
+  game: { documentId?: string; title?: string | null; slug?: string | null } | null;
+  gameAccount: { documentId?: string; name?: string | null } | null;
+  platform: { documentId?: string; name?: string | null } | null;
+  host: { username?: string | null } | null;
+}
+
+/** Body of `GET /tournaments/invites/:token` for a signed-in viewer. */
+export interface TournamentInvitePreview {
+  state: TournamentInviteState;
+  expiresAt: string | null;
+  tournament: TournamentInviteTournament;
+}
+
+/**
+ * Body of `POST /tournaments/invites/:token/join`. Flat, exactly like
+ * `POST /tournaments/:id/join`: omit both for a solo entry, send both for a
+ * team entry.
+ */
+export interface TournamentInviteJoinInput {
+  teamId?: string;
+  selectedMemberIds?: number[];
+}
+
+/**
+ * `error.details.name` values the invite routes raise. `NotTournamentHost`
+ * arrives as a 403 and `InviteNotFound` as a 404; `InviteUnavailable` is a
+ * 400 whose `details.state` is `revoked` or `expired`. A join through a link
+ * can also raise any `TournamentEntryErrorName`, since it is the same join.
+ */
+export type TournamentInviteErrorName =
+  | 'NotTournamentHost'
+  | 'InviteNotFound'
+  | 'InviteUnavailable'
+  /** An invite-only tournament was joined without a link (plain `/join`, 400). */
+  | 'InviteRequired'
+  /** An approval tournament was joined without a link or the host's yes. */
+  | 'ApprovalRequired';

package/src/manual/tournamentJoinRequest.ts

@@ -0,0 +1,118 @@
+/**
+ * Visibility, access and join requests — the contract between the host's
+ * Info dialog, the Join CTA, the Participants dialog and the
+ * `/tournaments/:id/join-requests` routes.
+ *
+ * The enums themselves are generated (`TournamentVisibility`,
+ * `TournamentAccess`, `TournamentJoinRequestStatus`); this file holds the
+ * response shapes the service builds by hand, the inputs, and the small
+ * predicates both apps branch on so their buttons and the server agree.
+ */
+
+import type {
+  TournamentAccess,
+  TournamentCurrentStatus,
+  TournamentJoinRequestStatus,
+  TournamentVisibility,
+} from '../generated/enums';
+import type { StrapiMedia } from '../contracts';
+
+/** Statuses in which a player may request and a host may approve. */
+export const REQUESTABLE_STATUSES = ['open', 'checkIn'] as const satisfies
+  readonly TournamentCurrentStatus[];
+
+export function isTournamentRequestable(
+  status: string | null | undefined
+): boolean {
+  return (REQUESTABLE_STATUSES as readonly string[]).includes(status ?? '');
+}
+
+/** Entry needs the host's link — or, on an approval tournament, their yes. */
+export const isInviteOnly = (access: string | null | undefined): boolean =>
+  access === 'inviteOnly';
+
+export const isApprovalAccess = (access: string | null | undefined): boolean =>
+  access === 'approval';
+
+/**
+ * The host's Invite button shows only where the public door is shut: on an
+ * invite-only tournament the link is the only way in, on an approval one it
+ * is a way past the queue. An open tournament has the public Share button.
+ */
+export const showsInviteButton = (access: string | null | undefined): boolean =>
+  access === 'inviteOnly' || access === 'approval';
+
+export const isUnlistedVisibility = (
+  visibility: string | null | undefined
+): boolean => visibility === 'unlisted';
+
+/** Copy for the Info card and dialogs. One place, so every surface agrees. */
+export const VISIBILITY_LABELS: Record<TournamentVisibility, string> = {
+  public: 'Public',
+  unlisted: 'Unlisted',
+};
+
+export const ACCESS_LABELS: Record<TournamentAccess, string> = {
+  open: 'Open',
+  inviteOnly: 'Invite only',
+  approval: 'Approval required',
+};
+
+export const visibilityLabel = (
+  visibility: string | null | undefined
+): string => VISIBILITY_LABELS[(visibility as TournamentVisibility) ?? 'public'] ?? 'Public';
+
+export const accessLabel = (access: string | null | undefined): string =>
+  ACCESS_LABELS[(access as TournamentAccess) ?? 'open'] ?? 'Open';
+
+/** What clients see of a request. Nothing the participants list would not show. */
+export interface TournamentJoinRequestSummary {
+  documentId: string;
+  status: TournamentJoinRequestStatus;
+  entryType: 'solo' | 'team';
+  displayName: string | null;
+  message: string | null;
+  /** Held from the requester's wallet until the host decides. */
+  feePaid: number;
+  createdAt: string | null;
+  decidedAt: string | null;
+  requester: { id: number; username: string | null; image: StrapiMedia | null } | null;
+  team: { documentId: string; name: string | null } | null;
+  /** The roster as requested; the approval re-reads the live one. */
+  membersSnapshot: unknown;
+  memberCount: number;
+}
+
+/** Body of `GET /tournaments/:id/join-requests` for a signed-in viewer. */
+export interface TournamentJoinRequestsResponse {
+  /** Pending requests, oldest first. Empty for anyone but the host. */
+  requests: TournamentJoinRequestSummary[];
+  /** The viewer's own most recent request, whatever its status. */
+  mine: TournamentJoinRequestSummary | null;
+  pendingCount: number;
+}
+
+/**
+ * Body of `POST /tournaments/:id/join-requests` (the generated `TournamentJoinRequestInput` is the row's write shape). Flat, like `/join`: omit
+ * the team fields for a solo entry, send both for a team entry.
+ */
+export interface TournamentJoinRequestBody {
+  teamId?: string;
+  selectedMemberIds?: number[];
+  /** ≤200 characters, shown to the host with the request. */
+  message?: string;
+}
+
+/**
+ * `error.details.name` values the join-request routes raise. `NotTournamentHost`
+ * is a 403 and `JoinRequestNotFound` a 404; the rest are 400s. A plain `/join`
+ * on an approval tournament raises `ApprovalRequired`. An approval runs the
+ * ordinary join, so it can also raise any `TournamentEntryErrorName`.
+ */
+export type TournamentJoinRequestErrorName =
+  | 'ApprovalRequired'
+  | 'JoinRequestNotAllowed'
+  | 'JoinRequestPending'
+  | 'JoinRequestNotFound'
+  | 'JoinRequestNotPending'
+  | 'NotTournamentHost';

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';