xpt-shared-types 1.20.0 → 1.25.0

package/dist/manual/tournamentTemplate.js

@@ -0,0 +1,215 @@
+"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.
+ *
+ * What a setup carries is close to the whole publish checklist: the catalogue
+ * choice (platform and account network), the region, the banner and the prize
+ * amounts ride along with the shape and the rules. Only the date is left out,
+ * because it belongs to one event rather than to the setup.
+ *
+ * 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`, `region`,
+ *    `platform`, `gameAccount`, `imgMain`, `prizes` and `template` (the
+ *    documentId, for usage meta) alongside the usual fields.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_TOURNAMENT_NAME = exports.setupPrizePot = exports.TOURNAMENT_SETUP_DEFAULTS = exports.TEMPLATE_COPY_KEYS = exports.MAX_TEMPLATES_PER_HOST = exports.LAST_RUN_WINDOW_DAYS = void 0;
+exports.resolveSetup = resolveSetup;
+exports.copyableSetupKeys = copyableSetupKeys;
+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 setup — the "Also copied" rows.
+ * `platform` covers the account network too: the two are chosen together and
+ * publish readiness counts them as one detail.
+ */
+exports.TEMPLATE_COPY_KEYS = [
+    'entryFee',
+    'prizes',
+    'checkInTime',
+    'platform',
+    'region',
+    'hasMatchLobby',
+    'hasThirdPlace',
+    'rules',
+    'imgMain',
+];
+/** 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,
+    platform: null,
+    gameAccount: null,
+    region: null,
+    imgMain: null,
+    prizes: [],
+};
+/** Every setting resolved: nulls replaced by the XPT default. */
+function resolveSetup(fields) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
+    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,
+        platform: (_g = source.platform) !== null && _g !== void 0 ? _g : null,
+        gameAccount: (_h = source.gameAccount) !== null && _h !== void 0 ? _h : null,
+        region: (_j = source.region) !== null && _j !== void 0 ? _j : null,
+        imgMain: (_k = source.imgMain) !== null && _k !== void 0 ? _k : null,
+        prizes: (_l = source.prizes) !== null && _l !== void 0 ? _l : [],
+    };
+}
+/**
+ * The copy keys this setup actually has something for. A setting the host
+ * unticked when saving, or never set on the tournament, carries nothing — so
+ * the "Also copied" list offers it no row rather than a tickable blank.
+ */
+function copyableSetupKeys(fields) {
+    var _a;
+    const setup = fields !== null && fields !== void 0 ? fields : {};
+    const has = {
+        entryFee: setup.entryFee != null,
+        prizes: ((_a = setup.prizes) !== null && _a !== void 0 ? _a : []).length > 0,
+        checkInTime: setup.checkInTime != null,
+        platform: setup.platform != null,
+        region: setup.region != null,
+        hasMatchLobby: setup.hasMatchLobby != null,
+        hasThirdPlace: setup.hasThirdPlace != null,
+        rules: !!setup.rules,
+        imgMain: setup.imgMain != null,
+    };
+    return exports.TEMPLATE_COPY_KEYS.filter((key) => has[key]);
+}
+/** The total a setup's prize amounts add up to. */
+const setupPrizePot = (prizes) => (prizes !== null && prizes !== void 0 ? prizes : []).reduce((sum, prize) => sum + (Number(prize.value) || 0), 0);
+exports.setupPrizePot = setupPrizePot;
+const TRAILING_COUNTER = /\s*#(\d+)$/;
+/** The tournament title rules' limit; a bumped name has to stay inside it. */
+exports.MAX_TOURNAMENT_NAME = 50;
+/**
+ * The name a tournament started from a setup gets. A trailing `#N` is bumped
+ * (`Friday Night Ops #3` → `Friday Night Ops #4`); a name without one is
+ * treated as the first of its series and becomes `#2`. Either way the host
+ * sees a name they can keep or type over, and never one that silently
+ * duplicates the tournament it came from.
+ */
+function nextTournamentName(name) {
+    const match = TRAILING_COUNTER.exec(name);
+    const base = (match ? name.slice(0, match.index) : name).trim();
+    if (!base)
+        return name;
+    const suffix = ` #${match ? Number(match[1]) + 1 : 2}`;
+    const room = exports.MAX_TOURNAMENT_NAME - suffix.length;
+    return `${base.length > room ? base.slice(0, room).trim() : base}${suffix}`;
+}
+/** 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.20.0",
+  "version": "1.25.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`. */
@@ -425,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;
@@ -473,6 +479,7 @@ export interface TournamentParticipantInput {
   status?: TournamentParticipantStatus;
   captainUser?: RelationInput;
   membersSnapshot?: unknown;
+  feePaid?: number;
 }
 
 /** Write payload for `tournament-preset-banner`. */
@@ -487,6 +494,28 @@ 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;
+  platform?: RelationInput;
+  gameAccount?: RelationInput;
+  region?: RelationInput;
+  imgMain?: MediaInput;
+  prizes?: unknown;
+  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` */
@@ -426,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;
@@ -474,6 +480,7 @@ export interface TournamentParticipant extends StrapiDocument {
   status?: TournamentParticipantStatus | null;
   captainUser?: User | null;
   membersSnapshot?: unknown | null;
+  feePaid?: number | null;
 }
 
 /** `tournament-preset-banner` */
@@ -488,6 +495,28 @@ 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;
+  platform?: Platform | null;
+  gameAccount?: GameAccount | null;
+  region?: Region | null;
+  imgMain?: StrapiMedia | null;
+  prizes?: unknown | 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';