xpt-shared-types 1.19.0 → 1.24.0

package/README.md

@@ -117,6 +117,13 @@ using npm trusted publishing, so no npm token or 2FA prompt is involved.
 2. `yarn version --patch` (or `--minor`), which commits and tags `vX.Y.Z`
 3. `git push --follow-tags`
 
+If the version was bumped by hand instead, commit it and tag with
+`git tag -a vX.Y.Z -m vX.Y.Z` before pushing: `--follow-tags` only sends
+annotated tags, so a plain `git tag vX.Y.Z` (or no tag at all) pushes nothing
+and prints "Everything up-to-date". `git push origin vX.Y.Z` also works.
+After the run succeeds the registry can lag a minute or two; confirm with
+`npm view xpt-shared-types dist-tags.latest` before installing.
+
 The workflow fires on the `v*` tag, refuses to run if the tag and
 `package.json` version disagree, then builds and publishes.
 

package/dist/generated/enums.d.ts

@@ -62,6 +62,8 @@ export type TournamentParticipantStatus = "registered" | "active" | "eliminated"
 export type TournamentRoleRole = "moderator" | "admin";
 /** `Tournament.teamSize` */
 export type TournamentTeamSize = "one" | "two" | "three" | "four" | "five";
+/** `TournamentTemplate.teamSize` */
+export type TournamentTemplateTeamSize = "one" | "two" | "three" | "four" | "five";
 /** `Tournament.type` */
 export type TournamentType = "Single Elimination" | "League" | "Double Elimination";
 /** `Tournament.visibility` */

package/dist/generated/inputs.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, MediaInput, RelationInput } from '../contracts';
-import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserGameAccountVerificationMethod, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentTemplateTeamSize, TournamentType, TournamentVisibility, UserGameAccountVerificationMethod, UserTransactionStripeStatus, UserTransactionType } from './enums';
 /** Write payload for `about`. */
 export interface AboutInput {
     heroTitle?: string;
@@ -77,6 +77,7 @@ export interface GameAccountInput {
     name?: string;
     code?: GameAccountCode;
     verification?: GameAccountVerification;
+    sortOrder?: number;
     tournaments?: RelationInput | RelationInput[];
     user_game_accounts?: RelationInput | RelationInput[];
     imgThumb?: MediaInput;
@@ -170,6 +171,7 @@ export interface MatchInput {
     disputeReason?: MatchDisputeReason;
     disputeNote?: string;
     disputedBy?: RelationInput;
+    resultRecordedBy?: RelationInput;
 }
 /** Write payload for `match-message`. */
 export interface MatchMessageInput {
@@ -336,6 +338,7 @@ export interface TournamentInput {
     rules?: string;
     hasThirdPlace?: boolean;
     hasMatchLobby?: boolean;
+    requireVerifiedAccounts?: boolean;
     visibility?: TournamentVisibility;
     access?: TournamentAccess;
     checkInTime?: number;
@@ -344,6 +347,9 @@ export interface TournamentInput {
     gameAccount?: RelationInput;
     tournament_stages?: unknown;
     prizesDistributed?: boolean;
+    entryFeesCollected?: number;
+    entryFeesSettledAt?: string;
+    hostXpAwarded?: number;
     discordUrl?: string;
     twitterUrl?: string;
     twitchUrl?: string;
@@ -389,6 +395,7 @@ export interface TournamentParticipantInput {
     status?: TournamentParticipantStatus;
     captainUser?: RelationInput;
     membersSnapshot?: unknown;
+    feePaid?: number;
 }
 /** Write payload for `tournament-preset-banner`. */
 export interface TournamentPresetBannerInput {
@@ -400,6 +407,22 @@ export interface TournamentRoleInput {
     users_permissions_user?: RelationInput;
     tournament?: RelationInput;
 }
+/** Write payload for `tournament-template`. */
+export interface TournamentTemplateInput {
+    name?: string;
+    host?: RelationInput;
+    game?: RelationInput;
+    participants?: number;
+    teamSize?: TournamentTemplateTeamSize;
+    entryFee?: number;
+    checkInTime?: number;
+    hasThirdPlace?: boolean;
+    hasMatchLobby?: boolean;
+    rules?: string;
+    isDefault?: boolean;
+    useCount?: number;
+    lastUsedAt?: string;
+}
 /** Write payload for `user`. */
 export interface UserInput {
     username?: string;

package/dist/generated/models.d.ts

@@ -1,5 +1,5 @@
 import type { BlocksContent, StrapiDocument, StrapiMedia, UserRole } from '../contracts';
-import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentType, TournamentVisibility, UserGameAccountVerificationMethod, UserTransactionStripeStatus, UserTransactionType } from './enums';
+import type { AdminActionTargetType, FaqCategory, FriendshipStatus, GameAccountCode, GameAccountVerification, GameGenre, GameRequestCustomLobbies, GameRequestGenre, GameRequestTeamPlay, GameVisibility, MatchDisputeReason, MatchLobbyStatus, MatchResultType, MatchRound, MatchStreamPlatform, MatchWinnerSlot, PlatformCode, PlayerBanScope, ReferralStatus, TeamCurrentStatus, TeamInviteStatus, TeamInviteTeamRole, TeamPlayerTeamRole, TournamentAccess, TournamentCurrentStatus, TournamentInviteStatus, TournamentJoinRequestEntryType, TournamentJoinRequestStatus, TournamentParticipantEntryType, TournamentParticipantStatus, TournamentRoleRole, TournamentTeamSize, TournamentTemplateTeamSize, TournamentType, TournamentVisibility, UserGameAccountVerificationMethod, UserTransactionStripeStatus, UserTransactionType } from './enums';
 /** `about` */
 export interface About extends StrapiDocument {
     heroTitle?: string | null;
@@ -77,6 +77,7 @@ export interface GameAccount extends StrapiDocument {
     name?: string | null;
     code?: GameAccountCode | null;
     verification?: GameAccountVerification | null;
+    sortOrder?: number | null;
     tournaments?: Tournament[];
     user_game_accounts?: UserGameAccount[];
     imgThumb?: StrapiMedia | null;
@@ -170,6 +171,7 @@ export interface Match extends StrapiDocument {
     disputeReason?: MatchDisputeReason | null;
     disputeNote?: string | null;
     disputedBy?: User | null;
+    resultRecordedBy?: User | null;
 }
 /** `match-message` */
 export interface MatchMessage extends StrapiDocument {
@@ -336,6 +338,7 @@ export interface Tournament extends StrapiDocument {
     rules?: string | null;
     hasThirdPlace?: boolean | null;
     hasMatchLobby?: boolean | null;
+    requireVerifiedAccounts?: boolean | null;
     visibility?: TournamentVisibility | null;
     access?: TournamentAccess | null;
     checkInTime?: number | null;
@@ -344,6 +347,9 @@ export interface Tournament extends StrapiDocument {
     gameAccount?: GameAccount | null;
     tournament_stages?: unknown | null;
     prizesDistributed?: boolean | null;
+    entryFeesCollected?: number | null;
+    entryFeesSettledAt?: string | null;
+    hostXpAwarded?: number | null;
     discordUrl?: string | null;
     twitterUrl?: string | null;
     twitchUrl?: string | null;
@@ -389,6 +395,7 @@ export interface TournamentParticipant extends StrapiDocument {
     status?: TournamentParticipantStatus | null;
     captainUser?: User | null;
     membersSnapshot?: unknown | null;
+    feePaid?: number | null;
 }
 /** `tournament-preset-banner` */
 export interface TournamentPresetBanner extends StrapiDocument {
@@ -400,6 +407,22 @@ export interface TournamentRole extends StrapiDocument {
     users_permissions_user?: User | null;
     tournament?: Tournament | null;
 }
+/** `tournament-template` */
+export interface TournamentTemplate extends StrapiDocument {
+    name?: string | null;
+    host?: User | null;
+    game?: Game | null;
+    participants?: number | null;
+    teamSize?: TournamentTemplateTeamSize | null;
+    entryFee?: number | null;
+    checkInTime?: number | null;
+    hasThirdPlace?: boolean | null;
+    hasMatchLobby?: boolean | null;
+    rules?: string | null;
+    isDefault?: boolean | null;
+    useCount?: number | null;
+    lastUsedAt?: string | null;
+}
 /** `user` */
 export interface User extends StrapiDocument {
     username?: string | null;

package/dist/manual/experience.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The experience ladder — EXP, which is **not** XPT.
+ *
+ * XPT is the spendable currency: it lives on the user as `xptCoins`, moves
+ * through `createWalletTransaction`, and leaves a ledger row. EXP is
+ * progression: it lives in `*_exp_earned` columns on the stat tables, is never
+ * spendable, and surfaces only as a level name. Nothing converts one into the
+ * other.
+ *
+ * Three independent ladders share the maths below — a player's
+ * (`user_summary_stat.total_exp_earned`), a host's
+ * (`host_summary_stat.host_exp_earned`) and a team's
+ * (`team_summary_stat.total_exp_earned`) — so a change here moves all three.
+ *
+ * It lives in the shared package because the server needs `getLevelFromExp` to
+ * notice a level *crossing* (the only EXP event worth a notification; see the
+ * note on `getLevelName`), while the client needs the same ladder to render
+ * the level bar. Two copies would drift into telling a user two different
+ * things about the same number.
+ */
+export declare const levelNames: string[];
+export declare const BASE_EXP = 500;
+export declare const EXP_MULTIPLIER = 1.25;
+/** Total EXP needed to have reached `level`. Level 1 is the floor, at 0. */
+export declare const getExpForLevel: (level: number) => number;
+/** 1-based: everyone starts at level 1, which is `levelNames[0]`. */
+export declare const getLevelFromExp: (totalExp: number, maxLevel: number) => number;
+/**
+ * `MAX_LEVEL` is the number of rungs, so every name is reachable. It was 20
+ * against 21 names, which stranded 'Zenith' at the top of a ladder nobody
+ * could finish climbing.
+ */
+export declare const MAX_LEVEL: number;
+/**
+ * `getLevelFromExp` is 1-based and `levelNames` is 0-based, so the index is
+ * `level - 1`. It used to be `levelNames[level]`, which skipped 'Beginner'
+ * entirely and greeted a brand-new account with 0 EXP as 'Novice'.
+ */
+export declare const getLevelName: (totalExp: number, maxLevel?: number) => string;
+/**
+ * Whether adding EXP moved someone up a rung, and to what.
+ *
+ * This is the only EXP event worth a notification. Awards themselves are a
+ * drip — a match is 10 EXP, so a bracket winner would collect five bells on
+ * top of the five they already get for the results — whereas a crossing is
+ * rare and is the thing the ladder exists to celebrate.
+ */
+export declare const levelCrossing: (before: number, after: number) => {
+    crossed: boolean;
+    level: number;
+    name: string;
+};

package/dist/manual/experience.js

@@ -0,0 +1,104 @@
+"use strict";
+/**
+ * The experience ladder — EXP, which is **not** XPT.
+ *
+ * XPT is the spendable currency: it lives on the user as `xptCoins`, moves
+ * through `createWalletTransaction`, and leaves a ledger row. EXP is
+ * progression: it lives in `*_exp_earned` columns on the stat tables, is never
+ * spendable, and surfaces only as a level name. Nothing converts one into the
+ * other.
+ *
+ * Three independent ladders share the maths below — a player's
+ * (`user_summary_stat.total_exp_earned`), a host's
+ * (`host_summary_stat.host_exp_earned`) and a team's
+ * (`team_summary_stat.total_exp_earned`) — so a change here moves all three.
+ *
+ * It lives in the shared package because the server needs `getLevelFromExp` to
+ * notice a level *crossing* (the only EXP event worth a notification; see the
+ * note on `getLevelName`), while the client needs the same ladder to render
+ * the level bar. Two copies would drift into telling a user two different
+ * things about the same number.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.levelCrossing = exports.getLevelName = exports.MAX_LEVEL = exports.getLevelFromExp = exports.getExpForLevel = exports.EXP_MULTIPLIER = exports.BASE_EXP = exports.levelNames = void 0;
+exports.levelNames = [
+    'Beginner',
+    'Novice',
+    'Rookie',
+    'Apprentice',
+    'Initiate',
+    'Trainee',
+    'Competitor',
+    'Contender',
+    'Veteran',
+    'Expert',
+    'Elite',
+    'Master',
+    'Grandmaster',
+    'Champion',
+    'Legend',
+    'Mythic',
+    'Godlike',
+    'Immortal',
+    'Supreme',
+    'Transcendent',
+    'Zenith',
+];
+exports.BASE_EXP = 500;
+exports.EXP_MULTIPLIER = 1.25;
+/** Total EXP needed to have reached `level`. Level 1 is the floor, at 0. */
+const getExpForLevel = (level) => {
+    if (level <= 0)
+        return 0;
+    let total = 0;
+    for (let i = 0; i < level; i++) {
+        total += Math.floor(exports.BASE_EXP * Math.pow(exports.EXP_MULTIPLIER, i));
+    }
+    return total;
+};
+exports.getExpForLevel = getExpForLevel;
+/** 1-based: everyone starts at level 1, which is `levelNames[0]`. */
+const getLevelFromExp = (totalExp, maxLevel) => {
+    let level = 1;
+    while (level < maxLevel && totalExp >= (0, exports.getExpForLevel)(level + 1)) {
+        level++;
+    }
+    return level;
+};
+exports.getLevelFromExp = getLevelFromExp;
+/**
+ * `MAX_LEVEL` is the number of rungs, so every name is reachable. It was 20
+ * against 21 names, which stranded 'Zenith' at the top of a ladder nobody
+ * could finish climbing.
+ */
+exports.MAX_LEVEL = exports.levelNames.length;
+/**
+ * `getLevelFromExp` is 1-based and `levelNames` is 0-based, so the index is
+ * `level - 1`. It used to be `levelNames[level]`, which skipped 'Beginner'
+ * entirely and greeted a brand-new account with 0 EXP as 'Novice'.
+ */
+const getLevelName = (totalExp, maxLevel = exports.MAX_LEVEL) => {
+    var _a;
+    const level = (0, exports.getLevelFromExp)(totalExp, maxLevel);
+    return (_a = exports.levelNames[level - 1]) !== null && _a !== void 0 ? _a : 'Unknown';
+};
+exports.getLevelName = getLevelName;
+/**
+ * Whether adding EXP moved someone up a rung, and to what.
+ *
+ * This is the only EXP event worth a notification. Awards themselves are a
+ * drip — a match is 10 EXP, so a bracket winner would collect five bells on
+ * top of the five they already get for the results — whereas a crossing is
+ * rare and is the thing the ladder exists to celebrate.
+ */
+const levelCrossing = (before, after) => {
+    var _a;
+    const from = (0, exports.getLevelFromExp)(before, exports.MAX_LEVEL);
+    const to = (0, exports.getLevelFromExp)(after, exports.MAX_LEVEL);
+    return {
+        crossed: to > from,
+        level: to,
+        name: (_a = exports.levelNames[to - 1]) !== null && _a !== void 0 ? _a : 'Unknown',
+    };
+};
+exports.levelCrossing = levelCrossing;

package/dist/manual/index.d.ts

@@ -2,6 +2,7 @@
  * Hand-written types that are not derived from a Strapi content type.
  */
 export * from './country';
+export * from './experience';
 export * from './gameAccountHandle';
 export * from './lobby';
 export * from './notification';
@@ -10,3 +11,5 @@ export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';
 export * from './tournamentStaff';
+export * from './tournamentTemplate';
+export * from './userUiState';

package/dist/manual/index.js

@@ -18,6 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
  * Hand-written types that are not derived from a Strapi content type.
  */
 __exportStar(require("./country"), exports);
+__exportStar(require("./experience"), exports);
 __exportStar(require("./gameAccountHandle"), exports);
 __exportStar(require("./lobby"), exports);
 __exportStar(require("./notification"), exports);
@@ -26,3 +27,5 @@ __exportStar(require("./tournamentEntry"), exports);
 __exportStar(require("./tournamentInvite"), exports);
 __exportStar(require("./tournamentJoinRequest"), exports);
 __exportStar(require("./tournamentStaff"), exports);
+__exportStar(require("./tournamentTemplate"), exports);
+__exportStar(require("./userUiState"), exports);

package/dist/manual/tournamentEntry.d.ts

@@ -33,4 +33,8 @@ export interface TournamentTeamJoinInput {
  * `error.details.name` values the entry endpoints raise that a client is
  * expected to branch on. Anything else is a plain message.
  */
-export type TournamentEntryErrorName = 'NotEntryLeader' | 'MembersMissingGameAccount' | 'InsufficientCoins' | 'GameAccountRequired' | 'TeamEntryRequired';
+export type TournamentEntryErrorName = 'NotEntryLeader' | 'MembersMissingGameAccount' | 'InsufficientCoins' | 'GameAccountRequired' | 'TeamEntryRequired'
+/** The tournament admits only accounts verified by signing in; yours is typed. */
+ | 'GameAccountUnverified'
+/** Same, for the named players on a team roster. */
+ | 'MembersUnverifiedGameAccount';

package/dist/manual/tournamentTemplate.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Tournament templates — the contract between `utils/tournamentTemplate.ts`
+ * in xpt-strapi and the create dialog's setup step, the post-publish
+ * "Save as template" prompt and the Settings → Templates page in xpt-client.
+ *
+ * A template holds settings only: never entries, dates or results. A null
+ * setting means the host chose not to save it and the XPT default applies
+ * (`resolveSetup`). Alongside the host's templates, the API derives their
+ * **last tournament per game** — the newest one taken out of draft in the
+ * last `LAST_RUN_WINDOW_DAYS` — so a host can repeat a night without ever
+ * having saved anything.
+ *
+ * Routes (all scoped to the caller):
+ *  - `GET /tournament-templates/setups` → `{ data: TournamentSetupsResponse }`
+ *  - `POST /tournament-templates` with `SaveTemplateBody` → `{ data: TournamentTemplateSummary }`
+ *  - `PUT /tournament-templates/:id/default` → `{ data: TournamentTemplateSummary }`
+ *  - `DELETE /tournament-templates/:id`
+ *  - `POST /tournaments` accepts `entryFee`, `checkInTime`, `rules` and
+ *    `template` (the documentId, for usage meta) alongside the usual fields.
+ */
+import type { StrapiMedia } from '../contracts';
+import type { TournamentTeamSize } from '../generated/enums';
+/** How far back the automatic "last tournament" looks. */
+export declare const LAST_RUN_WINDOW_DAYS = 30;
+/** Templates a host may keep; the save route refuses the next one. */
+export declare const MAX_TEMPLATES_PER_HOST = 20;
+/** The settings a host may leave out of a template — the "Also copied" rows. */
+export declare const TEMPLATE_COPY_KEYS: readonly ["entryFee", "checkInTime", "hasMatchLobby", "hasThirdPlace", "rules"];
+export type TemplateCopyKey = (typeof TEMPLATE_COPY_KEYS)[number];
+export type TemplateIncludeFlags = Record<TemplateCopyKey, boolean>;
+export interface TournamentSetupFields {
+    participants: number;
+    teamSize: TournamentTeamSize;
+    /** Null: not saved, XPT default applies. */
+    entryFee: number | null;
+    /** Minutes; 0 is "no check-in". Null: not saved. */
+    checkInTime: number | null;
+    hasThirdPlace: boolean | null;
+    hasMatchLobby: boolean | null;
+    rules: string | null;
+}
+/** What a blank tournament starts from, and what a null setting falls back to. */
+export declare const TOURNAMENT_SETUP_DEFAULTS: TournamentSetupFields;
+/** Enough of a game for the client to open the create dialog on it. */
+export interface SetupGame {
+    id: number;
+    documentId: string;
+    title: string | null;
+    slug: string | null;
+    imgThumb: StrapiMedia | null;
+}
+/** A saved template as the routes return it. */
+export interface TournamentTemplateSummary extends TournamentSetupFields {
+    documentId: string;
+    name: string;
+    game: SetupGame | null;
+    isDefault: boolean;
+    useCount: number;
+    lastUsedAt: string | null;
+    createdAt: string | null;
+}
+/** The host's last tournament for one game, derived at read time. */
+export interface LastRunSummary extends TournamentSetupFields {
+    documentId: string;
+    title: string;
+    slug: string;
+    game: SetupGame | null;
+    dateTime: string | null;
+    createdAt: string | null;
+}
+/** `GET /tournament-templates/setups` — templates default first, runs newest first. */
+export interface TournamentSetupsResponse {
+    templates: TournamentTemplateSummary[];
+    lastRuns: LastRunSummary[];
+}
+/** `POST /tournament-templates`. Missing include flags read as ticked. */
+export interface SaveTemplateBody {
+    tournamentDocumentId: string;
+    name: string;
+    include?: Partial<TemplateIncludeFlags>;
+    isDefault?: boolean;
+}
+/** What the setup step offers, and what the details step was prefilled from. */
+export type SetupChoice = {
+    kind: 'template';
+    template: TournamentTemplateSummary;
+} | {
+    kind: 'lastRun';
+    lastRun: LastRunSummary;
+} | {
+    kind: 'blank';
+};
+/** Every setting resolved: nulls replaced by the XPT default. */
+export declare function resolveSetup(fields: Partial<TournamentSetupFields> | null | undefined): TournamentSetupFields;
+/**
+ * The name a tournament started from a setup gets: a trailing `#N` is bumped
+ * (`Friday Night Ops #3` → `Friday Night Ops #4`); anything else is copied
+ * verbatim.
+ */
+export declare function nextTournamentName(name: string): string;
+/** A template name from a tournament title: the trailing `#N`, if any, dropped. */
+export declare function templateNameFrom(title: string): string;
+/** The setups offered for one game: its templates and, if any, its last run. */
+export declare function setupsForGame(setups: TournamentSetupsResponse | null | undefined, gameDocumentId: string | null | undefined): {
+    templates: TournamentTemplateSummary[];
+    lastRun: LastRunSummary | null;
+};
+/** Badge counts for the game grid: templates for the game plus its last run. */
+export declare function setupCountByGame(setups: TournamentSetupsResponse | null | undefined): Record<string, number>;
+/**
+ * What the setup step starts on: the default template if the game has one,
+ * else the game's last run, else blank — so Continue is a single tap.
+ */
+export declare function preselectSetup(templates: TournamentTemplateSummary[], lastRun: LastRunSummary | null | undefined): SetupChoice;
+/** The setup fields of a choice, or null for blank. */
+export declare function setupOfChoice(choice: SetupChoice): TournamentSetupFields | null;
+/** The name a choice was made under, for the provenance strip. */
+export declare function nameOfChoice(choice: SetupChoice): string | null;
+export interface DescribeSetupOptions {
+    /** `players` or `teams` for the team size. */
+    entryNoun: (teamSize: TournamentTeamSize) => string;
+    /** `1v1` … `5v5`. */
+    teamSizeLabel: (teamSize: TournamentTeamSize) => string;
+    /** `Free entry`, `50 XPT` — the app's own money formatting. */
+    feeLabel: (fee: number) => string;
+    /** Mention rules when the setup carries them. Default true. */
+    withRules?: boolean;
+}
+/**
+ * The detail line under a setup: `16 teams · 2v2 · 50 XPT · check-in 30 min
+ * · rules`. Nulls read as their defaults. The labels come from the caller
+ * so this package does not carry the app's copy.
+ */
+export declare function describeSetup(fields: Partial<TournamentSetupFields> | null | undefined, options: DescribeSetupOptions): string;

package/dist/manual/tournamentTemplate.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Tournament templates — the contract between `utils/tournamentTemplate.ts`
+ * in xpt-strapi and the create dialog's setup step, the post-publish
+ * "Save as template" prompt and the Settings → Templates page in xpt-client.
+ *
+ * A template holds settings only: never entries, dates or results. A null
+ * setting means the host chose not to save it and the XPT default applies
+ * (`resolveSetup`). Alongside the host's templates, the API derives their
+ * **last tournament per game** — the newest one taken out of draft in the
+ * last `LAST_RUN_WINDOW_DAYS` — so a host can repeat a night without ever
+ * having saved anything.
+ *
+ * Routes (all scoped to the caller):
+ *  - `GET /tournament-templates/setups` → `{ data: TournamentSetupsResponse }`
+ *  - `POST /tournament-templates` with `SaveTemplateBody` → `{ data: TournamentTemplateSummary }`
+ *  - `PUT /tournament-templates/:id/default` → `{ data: TournamentTemplateSummary }`
+ *  - `DELETE /tournament-templates/:id`
+ *  - `POST /tournaments` accepts `entryFee`, `checkInTime`, `rules` and
+ *    `template` (the documentId, for usage meta) alongside the usual fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TOURNAMENT_SETUP_DEFAULTS = exports.TEMPLATE_COPY_KEYS = exports.MAX_TEMPLATES_PER_HOST = exports.LAST_RUN_WINDOW_DAYS = void 0;
+exports.resolveSetup = resolveSetup;
+exports.nextTournamentName = nextTournamentName;
+exports.templateNameFrom = templateNameFrom;
+exports.setupsForGame = setupsForGame;
+exports.setupCountByGame = setupCountByGame;
+exports.preselectSetup = preselectSetup;
+exports.setupOfChoice = setupOfChoice;
+exports.nameOfChoice = nameOfChoice;
+exports.describeSetup = describeSetup;
+/** How far back the automatic "last tournament" looks. */
+exports.LAST_RUN_WINDOW_DAYS = 30;
+/** Templates a host may keep; the save route refuses the next one. */
+exports.MAX_TEMPLATES_PER_HOST = 20;
+/** The settings a host may leave out of a template — the "Also copied" rows. */
+exports.TEMPLATE_COPY_KEYS = [
+    'entryFee',
+    'checkInTime',
+    'hasMatchLobby',
+    'hasThirdPlace',
+    'rules',
+];
+/** What a blank tournament starts from, and what a null setting falls back to. */
+exports.TOURNAMENT_SETUP_DEFAULTS = {
+    participants: 8,
+    teamSize: 'one',
+    entryFee: 0,
+    checkInTime: 0,
+    hasThirdPlace: false,
+    hasMatchLobby: true,
+    rules: null,
+};
+/** Every setting resolved: nulls replaced by the XPT default. */
+function resolveSetup(fields) {
+    var _a, _b, _c, _d, _e, _f;
+    const source = fields !== null && fields !== void 0 ? fields : {};
+    return {
+        participants: source.participants || exports.TOURNAMENT_SETUP_DEFAULTS.participants,
+        teamSize: (_a = source.teamSize) !== null && _a !== void 0 ? _a : exports.TOURNAMENT_SETUP_DEFAULTS.teamSize,
+        entryFee: (_b = source.entryFee) !== null && _b !== void 0 ? _b : exports.TOURNAMENT_SETUP_DEFAULTS.entryFee,
+        checkInTime: (_c = source.checkInTime) !== null && _c !== void 0 ? _c : exports.TOURNAMENT_SETUP_DEFAULTS.checkInTime,
+        hasThirdPlace: (_d = source.hasThirdPlace) !== null && _d !== void 0 ? _d : exports.TOURNAMENT_SETUP_DEFAULTS.hasThirdPlace,
+        hasMatchLobby: (_e = source.hasMatchLobby) !== null && _e !== void 0 ? _e : exports.TOURNAMENT_SETUP_DEFAULTS.hasMatchLobby,
+        rules: (_f = source.rules) !== null && _f !== void 0 ? _f : exports.TOURNAMENT_SETUP_DEFAULTS.rules,
+    };
+}
+const TRAILING_COUNTER = /\s*#(\d+)$/;
+/**
+ * The name a tournament started from a setup gets: a trailing `#N` is bumped
+ * (`Friday Night Ops #3` → `Friday Night Ops #4`); anything else is copied
+ * verbatim.
+ */
+function nextTournamentName(name) {
+    const match = TRAILING_COUNTER.exec(name);
+    if (!match)
+        return name;
+    const next = Number(match[1]) + 1;
+    return `${name.slice(0, match.index).trimEnd()} #${next}`;
+}
+/** A template name from a tournament title: the trailing `#N`, if any, dropped. */
+function templateNameFrom(title) {
+    return title.replace(TRAILING_COUNTER, '').trim();
+}
+/** The setups offered for one game: its templates and, if any, its last run. */
+function setupsForGame(setups, gameDocumentId) {
+    var _a;
+    if (!setups || !gameDocumentId)
+        return { templates: [], lastRun: null };
+    return {
+        templates: setups.templates.filter((t) => { var _a; return ((_a = t.game) === null || _a === void 0 ? void 0 : _a.documentId) === gameDocumentId; }),
+        lastRun: (_a = setups.lastRuns.find((r) => { var _a; return ((_a = r.game) === null || _a === void 0 ? void 0 : _a.documentId) === gameDocumentId; })) !== null && _a !== void 0 ? _a : null,
+    };
+}
+/** Badge counts for the game grid: templates for the game plus its last run. */
+function setupCountByGame(setups) {
+    var _a, _b, _c, _d;
+    const counts = {};
+    if (!setups)
+        return counts;
+    for (const t of setups.templates) {
+        const id = (_a = t.game) === null || _a === void 0 ? void 0 : _a.documentId;
+        if (id)
+            counts[id] = ((_b = counts[id]) !== null && _b !== void 0 ? _b : 0) + 1;
+    }
+    for (const r of setups.lastRuns) {
+        const id = (_c = r.game) === null || _c === void 0 ? void 0 : _c.documentId;
+        if (id)
+            counts[id] = ((_d = counts[id]) !== null && _d !== void 0 ? _d : 0) + 1;
+    }
+    return counts;
+}
+/**
+ * What the setup step starts on: the default template if the game has one,
+ * else the game's last run, else blank — so Continue is a single tap.
+ */
+function preselectSetup(templates, lastRun) {
+    var _a;
+    const preferred = (_a = templates.find((t) => t.isDefault)) !== null && _a !== void 0 ? _a : templates[0];
+    if (preferred)
+        return { kind: 'template', template: preferred };
+    if (lastRun)
+        return { kind: 'lastRun', lastRun };
+    return { kind: 'blank' };
+}
+/** The setup fields of a choice, or null for blank. */
+function setupOfChoice(choice) {
+    if (choice.kind === 'template')
+        return choice.template;
+    if (choice.kind === 'lastRun')
+        return choice.lastRun;
+    return null;
+}
+/** The name a choice was made under, for the provenance strip. */
+function nameOfChoice(choice) {
+    if (choice.kind === 'template')
+        return choice.template.name;
+    if (choice.kind === 'lastRun')
+        return choice.lastRun.title;
+    return null;
+}
+/**
+ * The detail line under a setup: `16 teams · 2v2 · 50 XPT · check-in 30 min
+ * · rules`. Nulls read as their defaults. The labels come from the caller
+ * so this package does not carry the app's copy.
+ */
+function describeSetup(fields, options) {
+    var _a;
+    const setup = resolveSetup(fields);
+    const parts = [
+        `${setup.participants} ${options.entryNoun(setup.teamSize)}`,
+        options.teamSizeLabel(setup.teamSize),
+        options.feeLabel((_a = setup.entryFee) !== null && _a !== void 0 ? _a : 0),
+        setup.checkInTime ? `check-in ${setup.checkInTime} min` : 'no check-in',
+    ];
+    if (options.withRules !== false && setup.rules)
+        parts.push('rules');
+    return parts.join(' · ');
+}

package/dist/manual/userUiState.d.ts

@@ -0,0 +1,29 @@
+/**
+ * A user's UI state: small per-user flags that steer the interface — which
+ * hints are still showing, which onboarding steps are done.
+ *
+ * Stored as the private `uiState` JSON on the user, so it never appears on a
+ * user record. Read with GET /user/ui-state and written with
+ * PATCH /user/ui-state, which merges key by key: a patch naming one key never
+ * clears another. The server drops unknown keys and malformed values.
+ */
+export interface UserUiState {
+    /**
+     * Tournaments (documentId) whose host closed the publish success dialog
+     * without going to Manage, so the next-steps panel still shows. Cleared
+     * per tournament on Dismiss or when Manage is opened. Newest last, capped
+     * at {@link POST_PUBLISH_PENDING_LIMIT}.
+     */
+    postPublishPending?: string[];
+    /**
+     * Tournaments (documentId) whose host answered "Not now" to the
+     * save-as-template prompt, or saved a template from it, so the prompt does
+     * not show again. Newest last, capped at
+     * {@link TEMPLATE_PROMPT_DISMISSED_LIMIT}.
+     */
+    templatePromptDismissed?: string[];
+}
+/** How many tournaments `postPublishPending` remembers; oldest drop first. */
+export declare const POST_PUBLISH_PENDING_LIMIT = 20;
+/** How many tournaments `templatePromptDismissed` remembers; oldest drop first. */
+export declare const TEMPLATE_PROMPT_DISMISSED_LIMIT = 20;

package/dist/manual/userUiState.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEMPLATE_PROMPT_DISMISSED_LIMIT = exports.POST_PUBLISH_PENDING_LIMIT = void 0;
+/** How many tournaments `postPublishPending` remembers; oldest drop first. */
+exports.POST_PUBLISH_PENDING_LIMIT = 20;
+/** How many tournaments `templatePromptDismissed` remembers; oldest drop first. */
+exports.TEMPLATE_PROMPT_DISMISSED_LIMIT = 20;

package/package.json

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

package/src/generated/enums.ts

@@ -244,6 +244,14 @@ export type TournamentTeamSize =
   | "four"
   | "five";
 
+/** `TournamentTemplate.teamSize` */
+export type TournamentTemplateTeamSize =
+  | "one"
+  | "two"
+  | "three"
+  | "four"
+  | "five";
+
 /** `Tournament.type` */
 export type TournamentType =
   | "Single Elimination"

package/src/generated/inputs.ts

@@ -40,6 +40,7 @@ import type {
   TournamentParticipantStatus,
   TournamentRoleRole,
   TournamentTeamSize,
+  TournamentTemplateTeamSize,
   TournamentType,
   TournamentVisibility,
   UserGameAccountVerificationMethod,
@@ -132,6 +133,7 @@ export interface GameAccountInput {
   name?: string;
   code?: GameAccountCode;
   verification?: GameAccountVerification;
+  sortOrder?: number;
   tournaments?: RelationInput | RelationInput[];
   user_game_accounts?: RelationInput | RelationInput[];
   imgThumb?: MediaInput;
@@ -231,6 +233,7 @@ export interface MatchInput {
   disputeReason?: MatchDisputeReason;
   disputeNote?: string;
   disputedBy?: RelationInput;
+  resultRecordedBy?: RelationInput;
 }
 
 /** Write payload for `match-message`. */
@@ -416,6 +419,7 @@ export interface TournamentInput {
   rules?: string;
   hasThirdPlace?: boolean;
   hasMatchLobby?: boolean;
+  requireVerifiedAccounts?: boolean;
   visibility?: TournamentVisibility;
   access?: TournamentAccess;
   checkInTime?: number;
@@ -424,6 +428,9 @@ export interface TournamentInput {
   gameAccount?: RelationInput;
   tournament_stages?: unknown;
   prizesDistributed?: boolean;
+  entryFeesCollected?: number;
+  entryFeesSettledAt?: string;
+  hostXpAwarded?: number;
   discordUrl?: string;
   twitterUrl?: string;
   twitchUrl?: string;
@@ -472,6 +479,7 @@ export interface TournamentParticipantInput {
   status?: TournamentParticipantStatus;
   captainUser?: RelationInput;
   membersSnapshot?: unknown;
+  feePaid?: number;
 }
 
 /** Write payload for `tournament-preset-banner`. */
@@ -486,6 +494,23 @@ export interface TournamentRoleInput {
   tournament?: RelationInput;
 }
 
+/** Write payload for `tournament-template`. */
+export interface TournamentTemplateInput {
+  name?: string;
+  host?: RelationInput;
+  game?: RelationInput;
+  participants?: number;
+  teamSize?: TournamentTemplateTeamSize;
+  entryFee?: number;
+  checkInTime?: number;
+  hasThirdPlace?: boolean;
+  hasMatchLobby?: boolean;
+  rules?: string;
+  isDefault?: boolean;
+  useCount?: number;
+  lastUsedAt?: string;
+}
+
 /** Write payload for `user`. */
 export interface UserInput {
   username?: string;

package/src/generated/models.ts

@@ -41,6 +41,7 @@ import type {
   TournamentParticipantStatus,
   TournamentRoleRole,
   TournamentTeamSize,
+  TournamentTemplateTeamSize,
   TournamentType,
   TournamentVisibility,
   UserGameAccountVerificationMethod,
@@ -133,6 +134,7 @@ export interface GameAccount extends StrapiDocument {
   name?: string | null;
   code?: GameAccountCode | null;
   verification?: GameAccountVerification | null;
+  sortOrder?: number | null;
   tournaments?: Tournament[];
   user_game_accounts?: UserGameAccount[];
   imgThumb?: StrapiMedia | null;
@@ -232,6 +234,7 @@ export interface Match extends StrapiDocument {
   disputeReason?: MatchDisputeReason | null;
   disputeNote?: string | null;
   disputedBy?: User | null;
+  resultRecordedBy?: User | null;
 }
 
 /** `match-message` */
@@ -417,6 +420,7 @@ export interface Tournament extends StrapiDocument {
   rules?: string | null;
   hasThirdPlace?: boolean | null;
   hasMatchLobby?: boolean | null;
+  requireVerifiedAccounts?: boolean | null;
   visibility?: TournamentVisibility | null;
   access?: TournamentAccess | null;
   checkInTime?: number | null;
@@ -425,6 +429,9 @@ export interface Tournament extends StrapiDocument {
   gameAccount?: GameAccount | null;
   tournament_stages?: unknown | null;
   prizesDistributed?: boolean | null;
+  entryFeesCollected?: number | null;
+  entryFeesSettledAt?: string | null;
+  hostXpAwarded?: number | null;
   discordUrl?: string | null;
   twitterUrl?: string | null;
   twitchUrl?: string | null;
@@ -473,6 +480,7 @@ export interface TournamentParticipant extends StrapiDocument {
   status?: TournamentParticipantStatus | null;
   captainUser?: User | null;
   membersSnapshot?: unknown | null;
+  feePaid?: number | null;
 }
 
 /** `tournament-preset-banner` */
@@ -487,6 +495,23 @@ export interface TournamentRole extends StrapiDocument {
   tournament?: Tournament | null;
 }
 
+/** `tournament-template` */
+export interface TournamentTemplate extends StrapiDocument {
+  name?: string | null;
+  host?: User | null;
+  game?: Game | null;
+  participants?: number | null;
+  teamSize?: TournamentTemplateTeamSize | null;
+  entryFee?: number | null;
+  checkInTime?: number | null;
+  hasThirdPlace?: boolean | null;
+  hasMatchLobby?: boolean | null;
+  rules?: string | null;
+  isDefault?: boolean | null;
+  useCount?: number | null;
+  lastUsedAt?: string | null;
+}
+
 /** `user` */
 export interface User extends StrapiDocument {
   username?: string | null;

package/src/manual/experience.ts

@@ -0,0 +1,107 @@
+/**
+ * The experience ladder — EXP, which is **not** XPT.
+ *
+ * XPT is the spendable currency: it lives on the user as `xptCoins`, moves
+ * through `createWalletTransaction`, and leaves a ledger row. EXP is
+ * progression: it lives in `*_exp_earned` columns on the stat tables, is never
+ * spendable, and surfaces only as a level name. Nothing converts one into the
+ * other.
+ *
+ * Three independent ladders share the maths below — a player's
+ * (`user_summary_stat.total_exp_earned`), a host's
+ * (`host_summary_stat.host_exp_earned`) and a team's
+ * (`team_summary_stat.total_exp_earned`) — so a change here moves all three.
+ *
+ * It lives in the shared package because the server needs `getLevelFromExp` to
+ * notice a level *crossing* (the only EXP event worth a notification; see the
+ * note on `getLevelName`), while the client needs the same ladder to render
+ * the level bar. Two copies would drift into telling a user two different
+ * things about the same number.
+ */
+
+export const levelNames = [
+  'Beginner',
+  'Novice',
+  'Rookie',
+  'Apprentice',
+  'Initiate',
+  'Trainee',
+  'Competitor',
+  'Contender',
+  'Veteran',
+  'Expert',
+  'Elite',
+  'Master',
+  'Grandmaster',
+  'Champion',
+  'Legend',
+  'Mythic',
+  'Godlike',
+  'Immortal',
+  'Supreme',
+  'Transcendent',
+  'Zenith',
+];
+
+export const BASE_EXP = 500;
+export const EXP_MULTIPLIER = 1.25;
+
+/** Total EXP needed to have reached `level`. Level 1 is the floor, at 0. */
+export const getExpForLevel = (level: number): number => {
+  if (level <= 0) return 0;
+  let total = 0;
+  for (let i = 0; i < level; i++) {
+    total += Math.floor(BASE_EXP * Math.pow(EXP_MULTIPLIER, i));
+  }
+  return total;
+};
+
+/** 1-based: everyone starts at level 1, which is `levelNames[0]`. */
+export const getLevelFromExp = (totalExp: number, maxLevel: number): number => {
+  let level = 1;
+  while (level < maxLevel && totalExp >= getExpForLevel(level + 1)) {
+    level++;
+  }
+  return level;
+};
+
+/**
+ * `MAX_LEVEL` is the number of rungs, so every name is reachable. It was 20
+ * against 21 names, which stranded 'Zenith' at the top of a ladder nobody
+ * could finish climbing.
+ */
+export const MAX_LEVEL = levelNames.length;
+
+/**
+ * `getLevelFromExp` is 1-based and `levelNames` is 0-based, so the index is
+ * `level - 1`. It used to be `levelNames[level]`, which skipped 'Beginner'
+ * entirely and greeted a brand-new account with 0 EXP as 'Novice'.
+ */
+export const getLevelName = (
+  totalExp: number,
+  maxLevel = MAX_LEVEL
+): string => {
+  const level = getLevelFromExp(totalExp, maxLevel);
+  return levelNames[level - 1] ?? 'Unknown';
+};
+
+/**
+ * Whether adding EXP moved someone up a rung, and to what.
+ *
+ * This is the only EXP event worth a notification. Awards themselves are a
+ * drip — a match is 10 EXP, so a bracket winner would collect five bells on
+ * top of the five they already get for the results — whereas a crossing is
+ * rare and is the thing the ladder exists to celebrate.
+ */
+export const levelCrossing = (
+  before: number,
+  after: number
+): { crossed: boolean; level: number; name: string } => {
+  const from = getLevelFromExp(before, MAX_LEVEL);
+  const to = getLevelFromExp(after, MAX_LEVEL);
+  return {
+    crossed: to > from,
+    level: to,
+    name: levelNames[to - 1] ?? 'Unknown',
+  };
+};

package/src/manual/index.ts

@@ -2,6 +2,7 @@
  * Hand-written types that are not derived from a Strapi content type.
  */
 export * from './country';
+export * from './experience';
 export * from './gameAccountHandle';
 export * from './lobby';
 export * from './notification';
@@ -10,3 +11,5 @@ export * from './tournamentEntry';
 export * from './tournamentInvite';
 export * from './tournamentJoinRequest';
 export * from './tournamentStaff';
+export * from './tournamentTemplate';
+export * from './userUiState';

package/src/manual/tournamentEntry.ts

@@ -51,4 +51,8 @@ export type TournamentEntryErrorName =
   | 'MembersMissingGameAccount'
   | 'InsufficientCoins'
   | 'GameAccountRequired'
-  | 'TeamEntryRequired';
+  | 'TeamEntryRequired'
+  /** The tournament admits only accounts verified by signing in; yours is typed. */
+  | 'GameAccountUnverified'
+  /** Same, for the named players on a team roster. */
+  | 'MembersUnverifiedGameAccount';

package/src/manual/tournamentTemplate.ts

@@ -0,0 +1,243 @@
+/**
+ * Tournament templates — the contract between `utils/tournamentTemplate.ts`
+ * in xpt-strapi and the create dialog's setup step, the post-publish
+ * "Save as template" prompt and the Settings → Templates page in xpt-client.
+ *
+ * A template holds settings only: never entries, dates or results. A null
+ * setting means the host chose not to save it and the XPT default applies
+ * (`resolveSetup`). Alongside the host's templates, the API derives their
+ * **last tournament per game** — the newest one taken out of draft in the
+ * last `LAST_RUN_WINDOW_DAYS` — so a host can repeat a night without ever
+ * having saved anything.
+ *
+ * Routes (all scoped to the caller):
+ *  - `GET /tournament-templates/setups` → `{ data: TournamentSetupsResponse }`
+ *  - `POST /tournament-templates` with `SaveTemplateBody` → `{ data: TournamentTemplateSummary }`
+ *  - `PUT /tournament-templates/:id/default` → `{ data: TournamentTemplateSummary }`
+ *  - `DELETE /tournament-templates/:id`
+ *  - `POST /tournaments` accepts `entryFee`, `checkInTime`, `rules` and
+ *    `template` (the documentId, for usage meta) alongside the usual fields.
+ */
+
+import type { StrapiMedia } from '../contracts';
+import type { TournamentTeamSize } from '../generated/enums';
+
+/** How far back the automatic "last tournament" looks. */
+export const LAST_RUN_WINDOW_DAYS = 30;
+
+/** Templates a host may keep; the save route refuses the next one. */
+export const MAX_TEMPLATES_PER_HOST = 20;
+
+/** The settings a host may leave out of a template — the "Also copied" rows. */
+export const TEMPLATE_COPY_KEYS = [
+  'entryFee',
+  'checkInTime',
+  'hasMatchLobby',
+  'hasThirdPlace',
+  'rules',
+] as const;
+
+export type TemplateCopyKey = (typeof TEMPLATE_COPY_KEYS)[number];
+export type TemplateIncludeFlags = Record<TemplateCopyKey, boolean>;
+
+export interface TournamentSetupFields {
+  participants: number;
+  teamSize: TournamentTeamSize;
+  /** Null: not saved, XPT default applies. */
+  entryFee: number | null;
+  /** Minutes; 0 is "no check-in". Null: not saved. */
+  checkInTime: number | null;
+  hasThirdPlace: boolean | null;
+  hasMatchLobby: boolean | null;
+  rules: string | null;
+}
+
+/** What a blank tournament starts from, and what a null setting falls back to. */
+export const TOURNAMENT_SETUP_DEFAULTS: TournamentSetupFields = {
+  participants: 8,
+  teamSize: 'one',
+  entryFee: 0,
+  checkInTime: 0,
+  hasThirdPlace: false,
+  hasMatchLobby: true,
+  rules: null,
+};
+
+/** Enough of a game for the client to open the create dialog on it. */
+export interface SetupGame {
+  id: number;
+  documentId: string;
+  title: string | null;
+  slug: string | null;
+  imgThumb: StrapiMedia | null;
+}
+
+/** A saved template as the routes return it. */
+export interface TournamentTemplateSummary extends TournamentSetupFields {
+  documentId: string;
+  name: string;
+  game: SetupGame | null;
+  isDefault: boolean;
+  useCount: number;
+  lastUsedAt: string | null;
+  createdAt: string | null;
+}
+
+/** The host's last tournament for one game, derived at read time. */
+export interface LastRunSummary extends TournamentSetupFields {
+  documentId: string;
+  title: string;
+  slug: string;
+  game: SetupGame | null;
+  dateTime: string | null;
+  createdAt: string | null;
+}
+
+/** `GET /tournament-templates/setups` — templates default first, runs newest first. */
+export interface TournamentSetupsResponse {
+  templates: TournamentTemplateSummary[];
+  lastRuns: LastRunSummary[];
+}
+
+/** `POST /tournament-templates`. Missing include flags read as ticked. */
+export interface SaveTemplateBody {
+  tournamentDocumentId: string;
+  name: string;
+  include?: Partial<TemplateIncludeFlags>;
+  isDefault?: boolean;
+}
+
+/** What the setup step offers, and what the details step was prefilled from. */
+export type SetupChoice =
+  | { kind: 'template'; template: TournamentTemplateSummary }
+  | { kind: 'lastRun'; lastRun: LastRunSummary }
+  | { kind: 'blank' };
+
+/** Every setting resolved: nulls replaced by the XPT default. */
+export function resolveSetup(
+  fields: Partial<TournamentSetupFields> | null | undefined
+): TournamentSetupFields {
+  const source = fields ?? {};
+  return {
+    participants: source.participants || TOURNAMENT_SETUP_DEFAULTS.participants,
+    teamSize: source.teamSize ?? TOURNAMENT_SETUP_DEFAULTS.teamSize,
+    entryFee: source.entryFee ?? TOURNAMENT_SETUP_DEFAULTS.entryFee,
+    checkInTime: source.checkInTime ?? TOURNAMENT_SETUP_DEFAULTS.checkInTime,
+    hasThirdPlace: source.hasThirdPlace ?? TOURNAMENT_SETUP_DEFAULTS.hasThirdPlace,
+    hasMatchLobby: source.hasMatchLobby ?? TOURNAMENT_SETUP_DEFAULTS.hasMatchLobby,
+    rules: source.rules ?? TOURNAMENT_SETUP_DEFAULTS.rules,
+  };
+}
+
+const TRAILING_COUNTER = /\s*#(\d+)$/;
+
+/**
+ * The name a tournament started from a setup gets: a trailing `#N` is bumped
+ * (`Friday Night Ops #3` → `Friday Night Ops #4`); anything else is copied
+ * verbatim.
+ */
+export function nextTournamentName(name: string): string {
+  const match = TRAILING_COUNTER.exec(name);
+  if (!match) return name;
+  const next = Number(match[1]) + 1;
+  return `${name.slice(0, match.index).trimEnd()} #${next}`;
+}
+
+/** A template name from a tournament title: the trailing `#N`, if any, dropped. */
+export function templateNameFrom(title: string): string {
+  return title.replace(TRAILING_COUNTER, '').trim();
+}
+
+/** The setups offered for one game: its templates and, if any, its last run. */
+export function setupsForGame(
+  setups: TournamentSetupsResponse | null | undefined,
+  gameDocumentId: string | null | undefined
+): { templates: TournamentTemplateSummary[]; lastRun: LastRunSummary | null } {
+  if (!setups || !gameDocumentId) return { templates: [], lastRun: null };
+  return {
+    templates: setups.templates.filter(
+      (t) => t.game?.documentId === gameDocumentId
+    ),
+    lastRun:
+      setups.lastRuns.find((r) => r.game?.documentId === gameDocumentId) ??
+      null,
+  };
+}
+
+/** Badge counts for the game grid: templates for the game plus its last run. */
+export function setupCountByGame(
+  setups: TournamentSetupsResponse | null | undefined
+): Record<string, number> {
+  const counts: Record<string, number> = {};
+  if (!setups) return counts;
+  for (const t of setups.templates) {
+    const id = t.game?.documentId;
+    if (id) counts[id] = (counts[id] ?? 0) + 1;
+  }
+  for (const r of setups.lastRuns) {
+    const id = r.game?.documentId;
+    if (id) counts[id] = (counts[id] ?? 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * What the setup step starts on: the default template if the game has one,
+ * else the game's last run, else blank — so Continue is a single tap.
+ */
+export function preselectSetup(
+  templates: TournamentTemplateSummary[],
+  lastRun: LastRunSummary | null | undefined
+): SetupChoice {
+  const preferred = templates.find((t) => t.isDefault) ?? templates[0];
+  if (preferred) return { kind: 'template', template: preferred };
+  if (lastRun) return { kind: 'lastRun', lastRun };
+  return { kind: 'blank' };
+}
+
+/** The setup fields of a choice, or null for blank. */
+export function setupOfChoice(
+  choice: SetupChoice
+): TournamentSetupFields | null {
+  if (choice.kind === 'template') return choice.template;
+  if (choice.kind === 'lastRun') return choice.lastRun;
+  return null;
+}
+
+/** The name a choice was made under, for the provenance strip. */
+export function nameOfChoice(choice: SetupChoice): string | null {
+  if (choice.kind === 'template') return choice.template.name;
+  if (choice.kind === 'lastRun') return choice.lastRun.title;
+  return null;
+}
+
+export interface DescribeSetupOptions {
+  /** `players` or `teams` for the team size. */
+  entryNoun: (teamSize: TournamentTeamSize) => string;
+  /** `1v1` … `5v5`. */
+  teamSizeLabel: (teamSize: TournamentTeamSize) => string;
+  /** `Free entry`, `50 XPT` — the app's own money formatting. */
+  feeLabel: (fee: number) => string;
+  /** Mention rules when the setup carries them. Default true. */
+  withRules?: boolean;
+}
+
+/**
+ * The detail line under a setup: `16 teams · 2v2 · 50 XPT · check-in 30 min
+ * · rules`. Nulls read as their defaults. The labels come from the caller
+ * so this package does not carry the app's copy.
+ */
+export function describeSetup(
+  fields: Partial<TournamentSetupFields> | null | undefined,
+  options: DescribeSetupOptions
+): string {
+  const setup = resolveSetup(fields);
+  const parts = [
+    `${setup.participants} ${options.entryNoun(setup.teamSize)}`,
+    options.teamSizeLabel(setup.teamSize),
+    options.feeLabel(setup.entryFee ?? 0),
+    setup.checkInTime ? `check-in ${setup.checkInTime} min` : 'no check-in',
+  ];
+  if (options.withRules !== false && setup.rules) parts.push('rules');
+  return parts.join(' · ');
+}

package/src/manual/userUiState.ts

@@ -0,0 +1,31 @@
+/**
+ * A user's UI state: small per-user flags that steer the interface — which
+ * hints are still showing, which onboarding steps are done.
+ *
+ * Stored as the private `uiState` JSON on the user, so it never appears on a
+ * user record. Read with GET /user/ui-state and written with
+ * PATCH /user/ui-state, which merges key by key: a patch naming one key never
+ * clears another. The server drops unknown keys and malformed values.
+ */
+export interface UserUiState {
+  /**
+   * Tournaments (documentId) whose host closed the publish success dialog
+   * without going to Manage, so the next-steps panel still shows. Cleared
+   * per tournament on Dismiss or when Manage is opened. Newest last, capped
+   * at {@link POST_PUBLISH_PENDING_LIMIT}.
+   */
+  postPublishPending?: string[];
+  /**
+   * Tournaments (documentId) whose host answered "Not now" to the
+   * save-as-template prompt, or saved a template from it, so the prompt does
+   * not show again. Newest last, capped at
+   * {@link TEMPLATE_PROMPT_DISMISSED_LIMIT}.
+   */
+  templatePromptDismissed?: string[];
+}
+
+/** How many tournaments `postPublishPending` remembers; oldest drop first. */
+export const POST_PUBLISH_PENDING_LIMIT = 20;
+
+/** How many tournaments `templatePromptDismissed` remembers; oldest drop first. */
+export const TEMPLATE_PROMPT_DISMISSED_LIMIT = 20;