xpt-shared-types 1.20.0 → 1.25.0

package/src/manual/tournamentTemplate.ts

@@ -0,0 +1,326 @@
+/**
+ * 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.
+ */
+
+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 setup — the "Also copied" rows.
+ * `platform` covers the account network too: the two are chosen together and
+ * publish readiness counts them as one detail.
+ */
+export const TEMPLATE_COPY_KEYS = [
+  'entryFee',
+  'prizes',
+  'checkInTime',
+  'platform',
+  'region',
+  'hasMatchLobby',
+  'hasThirdPlace',
+  'rules',
+  'imgMain',
+] as const;
+
+export type TemplateCopyKey = (typeof TEMPLATE_COPY_KEYS)[number];
+export type TemplateIncludeFlags = Record<TemplateCopyKey, boolean>;
+
+/** A catalogue row as a setup names it. */
+export interface SetupRef {
+  documentId: string;
+  name: string | null;
+}
+
+/** One placement's payout. The set of ranks is derived, never carried. */
+export interface SetupPrize {
+  rank: string;
+  value: number | null;
+}
+
+/** The banner, as the media row a new tournament reuses. */
+export interface SetupBanner {
+  id: number;
+  url: string | null;
+}
+
+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;
+  platform: SetupRef | null;
+  /** Rides with `platform`; the create refuses it if the catalogue has moved. */
+  gameAccount: SetupRef | null;
+  region: SetupRef | null;
+  imgMain: SetupBanner | null;
+  prizes: SetupPrize[];
+}
+
+/** 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,
+  platform: null,
+  gameAccount: null,
+  region: null,
+  imgMain: null,
+  prizes: [],
+};
+
+/** 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,
+    platform: source.platform ?? null,
+    gameAccount: source.gameAccount ?? null,
+    region: source.region ?? null,
+    imgMain: source.imgMain ?? null,
+    prizes: source.prizes ?? [],
+  };
+}
+
+/**
+ * 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.
+ */
+export function copyableSetupKeys(
+  fields: Partial<TournamentSetupFields> | null | undefined
+): TemplateCopyKey[] {
+  const setup = fields ?? {};
+  const has: Record<TemplateCopyKey, boolean> = {
+    entryFee: setup.entryFee != null,
+    prizes: (setup.prizes ?? []).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 TEMPLATE_COPY_KEYS.filter((key) => has[key]);
+}
+
+/** The total a setup's prize amounts add up to. */
+export const setupPrizePot = (prizes: SetupPrize[] | null | undefined): number =>
+  (prizes ?? []).reduce((sum, prize) => sum + (Number(prize.value) || 0), 0);
+
+const TRAILING_COUNTER = /\s*#(\d+)$/;
+
+/** The tournament title rules' limit; a bumped name has to stay inside it. */
+export const 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.
+ */
+export function nextTournamentName(name: string): string {
+  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 = 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. */
+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;