xpt-shared-types 1.0.4 → 1.3.0

package/README.md

@@ -1,38 +1,121 @@
-# xpt-shared-types
-
-Shared TypeScript types and data for XPT projects.
-
-## Usage
-
-1. Install in your project:
-
-   ```sh
-   yarn add xpt-shared-types
-   # or
-   npm install xpt-shared-types
-   ```
-
-   Or publish to npm/GitHub Packages and install from there.
-
-2. Import types and data:
-   ```ts
-   import { Country, COUNTRIES_LIST } from "xpt-shared-types";
-   ```
-
-## Development
-
-- Edit types in `src/types/`
-- Edit shared data in `src/data/`
-- Run `yarn build` to compile TypeScript
-
-## Publish
-
-1. Run `npm login` to authenticate with npm (if not already logged in)
-2. Run `yarn build` to compile TypeScript
-3. Run `yarn version --patch` to bump the version (e.g. `1.0.4` → `1.0.5`)
-4. Run `npm publish` to publish to npm
-5. Run `git push` to push the version commit and tag to GitHub
-
-## License
-
-MIT
+# xpt-shared-types
+
+The API contract shared by `xpt-strapi` and `xpt-client`.
+
+Strapi's content-type schemas are the single source of truth. This package
+turns them into plain TypeScript so both projects describe the same API, and a
+schema change breaks compilation at every stale usage instead of drifting
+silently.
+
+## Layout
+
+```
+src/
+├── generated/     # DO NOT EDIT — produced by scripts/sync-from-strapi.js
+│   ├── enums.ts   #   one union per `enumeration` attribute
+│   ├── models.ts  #   one interface per content type (read shapes)
+│   └── inputs.ts  #   one interface per content type (write shapes)
+├── contracts/     # hand-written primitives the generated code builds on
+├── manual/        # types with no Strapi content type behind them
+└── data/          # shared runtime data (COUNTRIES_LIST)
+```
+
+Everything is re-exported from the package root:
+
+```ts
+import type { Tournament, TournamentStatus, Populated } from 'xpt-shared-types';
+import { COUNTRIES_LIST } from 'xpt-shared-types';
+```
+
+## Regenerating after a schema change
+
+```sh
+yarn sync     # reads ../xpt-strapi/src/**/content-types/**/schema.json
+yarn build    # tsc only
+```
+
+`sync` is deliberately **not** part of `build`, so publishing does not require a
+sibling `xpt-strapi` checkout. The generated output is committed — treat
+`yarn sync` as something you run and commit, like a lockfile.
+
+Point it elsewhere with an argument or `XPT_STRAPI_PATH`:
+
+```sh
+node scripts/sync-from-strapi.js ../some/other/xpt-strapi
+```
+
+It reads `schema.json`, **not** `xpt-strapi/types/generated/contentTypes.d.ts`.
+The latter is Strapi's own output for its server-side types; it is regenerated
+by `strapi develop` and expressed in `Schema.Attribute.*` wrappers that the
+frontend cannot consume.
+
+## The rules the generator follows
+
+**Everything except `id` and `documentId` is optional.** Not just relations.
+This codebase uses Strapi's `fields` selection pervasively, so even a
+schema-`required` attribute like `user.email` is absent from most responses.
+The base model is the *minimum guarantee*, not the full row.
+
+**Single values are `?: T | null`.** Strapi sends `null` for an unset value
+rather than omitting the key. Lists come back as `[]`, so they are not nullable.
+
+**Relations and media are optional regardless of the schema**, because whether
+they come back depends entirely on the query's `populate`.
+
+**`private` attributes are omitted**, because the content API never returns
+them (for example `user.password`).
+
+**Read and write shapes differ**, so both are generated. On read a relation is
+a nested object; on write it is a documentId or a `connect`/`set` form, and
+media is a numeric file id. Use `models.ts` for responses and `inputs.ts` for
+request payloads — typing a mutation with a read model is a common mistake that
+produces confusing optionality errors.
+
+**Enums are named `<Model><PascalField>`** — `tournament.currentStatus` becomes
+`TournamentCurrentStatus`. `TournamentStatus` is exported as a readability
+alias.
+
+## Narrowing with `Populated<T, K>`
+
+Because relations are always optional, record what a specific query actually
+asked for:
+
+```ts
+const tournament = await getTournament(slug); // Populated<Tournament, 'game' | 'prizes'>
+
+tournament.game.title;   // ok — the annotation says it was populated
+tournament.region?.name; // still optional — this query did not populate it
+```
+
+If the annotation and the query disagree, that is a bug a reader can see. Do
+not reach for a cast: a cast on a schema-backed field is always avoidable, and
+silently disables exactly the checking this package exists to provide.
+
+## Local development
+
+The two apps are on different Yarn majors, so they link differently:
+
+| Repo | Yarn | Dependency |
+| --- | --- | --- |
+| `xpt-strapi` | 1.22.5 (classic) | `"xpt-shared-types": "link:../xpt-shared-types"` |
+| `xpt-client` | 4.1.1 (Berry) | `"xpt-shared-types": "portal:../xpt-shared-types"` |
+
+`portal:` is Berry-only and fails on Yarn 1. Both symlink to this directory, so
+edits are picked up after `yarn build` with no publish step.
+
+> **Before deploying, revert both to the published range (`^1.x`) and publish
+> this package.** The link/portal wiring is for local development only.
+
+## Publishing
+
+`prepublishOnly` runs `yarn build`, so `dist/` cannot go stale.
+
+1. `yarn sync` and commit, if schemas changed
+2. `npm login`
+3. `yarn version --patch`
+4. `npm publish`
+5. `git push --follow-tags`
+
+## License
+
+MIT

package/dist/bracket.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+import type { MatchRound } from './generated';
+/** The largest bracket the round names can describe. */
+export declare const MAX_BRACKET_SIZE = 128;
+export declare function nextPowerOf2(n: number): number;
+export interface BracketRound {
+    name: MatchRound;
+    matchCount: number;
+}
+export declare function buildBracketRounds(bracketSize: number, hasThirdPlace: boolean): BracketRound[];
+/** The rounds a tournament of this many entrants will be played over. */
+export declare function bracketRoundsForParticipants(participants: number, hasThirdPlace: boolean): BracketRound[];
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+export declare function shuffle<T>(items: readonly T[]): T[];
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+export declare function seedOrder(bracketSize: number): number[];
+export interface PlannedMatch {
+    round: MatchRound;
+    matchNumber: number;
+    /** Where this match's winner goes; null for Finals and Third Round. */
+    nextMatchNumber: number | null;
+    winnerSlot: 'home' | 'away' | null;
+    /** First-round matches only: index into the seeded slot array (null = later round). */
+    homeSlot: number | null;
+    awaySlot: number | null;
+}
+export interface BracketPlan {
+    bracketSize: number;
+    rounds: BracketRound[];
+    matches: PlannedMatch[];
+}
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+export declare function buildBracketPlan(bracketSize: number, hasThirdPlace: boolean): BracketPlan;

package/dist/bracket.js

@@ -0,0 +1,144 @@
+"use strict";
+/**
+ * Bracket shape — how many rounds a single-elimination tournament has, what
+ * each is called, how matches are numbered, and where each winner goes.
+ *
+ * This is the single source of truth for both apps: xpt-strapi re-exports it
+ * from `src/utils/bracket.ts` (adding the Strapi-coupled stage sync), and
+ * xpt-client's Storybook fixtures consume it directly — a fixture built any
+ * other way could show a bracket the backend can never produce.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_BRACKET_SIZE = void 0;
+exports.nextPowerOf2 = nextPowerOf2;
+exports.buildBracketRounds = buildBracketRounds;
+exports.bracketRoundsForParticipants = bracketRoundsForParticipants;
+exports.shuffle = shuffle;
+exports.seedOrder = seedOrder;
+exports.buildBracketPlan = buildBracketPlan;
+/** The largest bracket the round names can describe. */
+exports.MAX_BRACKET_SIZE = 128;
+function nextPowerOf2(n) {
+    if (n <= 2)
+        return 2;
+    let p = 2;
+    while (p < n)
+        p *= 2;
+    return p;
+}
+/**
+ * The name of the round that *starts* with this many players left. Halving
+ * from the bracket size down to 2 walks the whole bracket, so there is no
+ * table of per-size name lists to fall out of sync — the one way a size can
+ * go wrong is a size that is not a power of two in range, and that throws.
+ */
+const ROUND_NAME_BY_SIZE = {
+    128: 'Round 128',
+    64: 'Round 64',
+    32: 'Round 32',
+    16: 'Round 16',
+    8: 'Quarter Final',
+    4: 'Semi-Final',
+    2: 'Finals',
+};
+function buildBracketRounds(bracketSize, hasThirdPlace) {
+    // An unrecognised size used to fall back to a single round called "Finals"
+    // holding `bracketSize / 2` matches. An unplayable bracket is worse than no
+    // bracket.
+    if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+        throw new Error(`Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${exports.MAX_BRACKET_SIZE}`);
+    }
+    const rounds = [];
+    for (let size = bracketSize; size >= 2; size /= 2) {
+        rounds.push({ name: ROUND_NAME_BY_SIZE[size], matchCount: size / 2 });
+    }
+    // Inject Third Round slot before Finals when enabled (4+ players)
+    if (hasThirdPlace && bracketSize >= 4) {
+        const finalsIdx = rounds.findIndex((r) => r.name === 'Finals');
+        if (finalsIdx > 0) {
+            rounds.splice(finalsIdx, 0, { name: 'Third Round', matchCount: 1 });
+        }
+    }
+    return rounds;
+}
+/** The rounds a tournament of this many entrants will be played over. */
+function bracketRoundsForParticipants(participants, hasThirdPlace) {
+    return buildBracketRounds(nextPowerOf2(participants), hasThirdPlace);
+}
+/** Uniform Fisher–Yates shuffle. A `sort(() => Math.random() - 0.5)` is
+ * biased — comparison sorts assume a consistent comparator, so some orderings
+ * come up measurably more often than others. */
+function shuffle(items) {
+    const result = [...items];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}
+/**
+ * Standard bracket seed order: which seed (0-based) sits in each first-round
+ * slot. Built by the usual doubling rule — each seed is paired with its
+ * complement, so seed 0 meets seed 1 only in the final.
+ *
+ * This is also the bye-safety property: slots are paired (s, size-1-s), and
+ * byes are the seeds from `checkedIn` upward. Both sides of a pair being byes
+ * would need `checkedIn <= (size-1)/2`, but `nextPowerOf2` guarantees
+ * `checkedIn > size/2` — so a bye always faces a real entrant.
+ */
+function seedOrder(bracketSize) {
+    if (!ROUND_NAME_BY_SIZE[bracketSize]) {
+        throw new Error(`Unsupported bracket size ${bracketSize} — must be a power of two between 2 and ${exports.MAX_BRACKET_SIZE}`);
+    }
+    let order = [0];
+    while (order.length < bracketSize) {
+        const size = order.length * 2;
+        const next = [];
+        for (const seed of order) {
+            next.push(seed, size - 1 - seed);
+        }
+        order = next;
+    }
+    return order;
+}
+/**
+ * The full bracket as data: every match, its number, and where its winner
+ * goes. Numbering is sequential across rounds in bracket order, with Third
+ * Round (when present) sitting before Finals.
+ */
+function buildBracketPlan(bracketSize, hasThirdPlace) {
+    const rounds = buildBracketRounds(bracketSize, hasThirdPlace);
+    let counter = 1;
+    const roundMatchNumbers = rounds.map((round) => Array.from({ length: round.matchCount }, () => counter++));
+    // Winner linkage skips Third Round — it receives losers, not winners.
+    const linkage = {};
+    const nonThirdRounds = rounds
+        .map((round, index) => ({ round, index }))
+        .filter(({ round }) => round.name !== 'Third Round');
+    for (let ri = 0; ri < nonThirdRounds.length - 1; ri++) {
+        const currentNums = roundMatchNumbers[nonThirdRounds[ri].index];
+        const nextNums = roundMatchNumbers[nonThirdRounds[ri + 1].index];
+        currentNums.forEach((num, mi) => {
+            linkage[num] = {
+                nextMatchNumber: nextNums[Math.floor(mi / 2)],
+                winnerSlot: mi % 2 === 0 ? 'home' : 'away',
+            };
+        });
+    }
+    const matches = [];
+    rounds.forEach((round, ri) => {
+        roundMatchNumbers[ri].forEach((num, mi) => {
+            var _a;
+            const link = (_a = linkage[num]) !== null && _a !== void 0 ? _a : { nextMatchNumber: null, winnerSlot: null };
+            matches.push({
+                round: round.name,
+                matchNumber: num,
+                nextMatchNumber: link.nextMatchNumber,
+                winnerSlot: link.winnerSlot,
+                homeSlot: ri === 0 ? mi * 2 : null,
+                awaySlot: ri === 0 ? mi * 2 + 1 : null,
+            });
+        });
+    });
+    return { bracketSize, rounds, matches };
+}

package/dist/contracts/index.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Hand-written contract primitives.
+ *
+ * Everything here is maintained by hand — the generated models in
+ * `src/generated` import from this module, so keep the names stable.
+ */
+/** Strapi 5 returns flat documents: no `attributes` envelope. */
+export interface StrapiDocument {
+    id: number;
+    documentId: string;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    publishedAt?: string | null;
+    locale?: string | null;
+}
+/** A single size variant produced by the upload plugin. */
+export interface StrapiMediaFormat {
+    name: string;
+    hash: string;
+    ext: string;
+    mime: string;
+    width: number;
+    height: number;
+    size: number;
+    url: string;
+    path?: string | null;
+}
+/**
+ * Size variants the upload plugin generates. The four named breakpoints are
+ * Strapi's defaults; the index signature covers custom ones.
+ */
+export interface StrapiMediaFormats {
+    thumbnail?: StrapiMediaFormat;
+    small?: StrapiMediaFormat;
+    medium?: StrapiMediaFormat;
+    large?: StrapiMediaFormat;
+    [breakpoint: string]: StrapiMediaFormat | undefined;
+}
+/** `plugin::upload.file` */
+export interface StrapiMedia {
+    id: number;
+    documentId?: string;
+    name: string;
+    alternativeText?: string | null;
+    caption?: string | null;
+    width?: number | null;
+    height?: number | null;
+    formats?: StrapiMediaFormats | null;
+    hash: string;
+    ext?: string | null;
+    mime: string;
+    size: number;
+    url: string;
+    previewUrl?: string | null;
+    provider?: string;
+    provider_metadata?: unknown;
+    folderPath?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    publishedAt?: string;
+    locale?: string | null;
+}
+/** Rich-text `blocks` payload; shape is defined by the blocks renderer. */
+export type BlocksContent = unknown[];
+/**
+ * How a relation is sent on create/update. Strapi accepts a bare documentId,
+ * a numeric id, or the connect/set/disconnect long form.
+ */
+export type RelationInput = string | number | {
+    id: number;
+} | {
+    documentId: string;
+} | {
+    connect?: Array<string | number>;
+    disconnect?: Array<string | number>;
+} | {
+    set: Array<string | number>;
+};
+/** Media is written as the uploaded file's numeric id. */
+export type MediaInput = number | number[] | null;
+export interface Pagination {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    total: number;
+}
+export interface Meta {
+    pagination?: Pagination;
+    [key: string]: unknown;
+}
+/** Single-entity response. Strapi still sends `meta`, usually `{}`. */
+export interface StrapiResponse<T> {
+    data: T;
+    meta?: Meta;
+}
+/** Collection response. */
+export interface StrapiCollectionResponse<T> {
+    data: T[];
+    meta?: Meta;
+}
+export interface StrapiError {
+    status: number;
+    name: string;
+    message: string;
+    details?: unknown;
+}
+export interface StrapiErrorResponse {
+    data: null;
+    error: StrapiError;
+}
+/**
+ * Marks relations as present.
+ *
+ * Generated models leave every relation optional, because whether one comes
+ * back depends entirely on the query's `populate`. Use this at a call site to
+ * record what that particular query actually asked for:
+ *
+ * ```ts
+ * type WithGame = Populated<Tournament, 'game' | 'prizes'>;
+ * ```
+ *
+ * This is the type-level counterpart to remembering to populate — if the query
+ * and the annotation disagree, that is a bug the reader can see.
+ */
+export type Populated<T, K extends keyof T> = T & {
+    [P in K]-?: NonNullable<T[P]>;
+};
+/** Recursively marks every relation on `T` as optional (the default shape). */
+export type Unpopulated<T> = {
+    [P in keyof T]?: T[P];
+};
+/** `plugin::users-permissions.role` */
+export interface UserRole {
+    id: number;
+    documentId?: string;
+    name: string;
+    description?: string | null;
+    type?: string | null;
+}

package/dist/contracts/index.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * Hand-written contract primitives.
+ *
+ * Everything here is maintained by hand — the generated models in
+ * `src/generated` import from this module, so keep the names stable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/data/countriesList.d.ts

@@ -1,2 +1,2 @@
-import { Country } from "../types/country";
+import { Country } from "../manual/country";
 export declare const COUNTRIES_LIST: Country[];

package/dist/data/countriesList.js

@@ -1090,7 +1090,7 @@ exports.COUNTRIES_LIST = [
     },
     {
         countryName: "United Kingdom",
-        alpha2: "GB-UKM",
+        alpha2: "GB",
         alpha3: "GBR",
         numeric: "826",
     },

package/dist/generated/enums.d.ts

@@ -0,0 +1,48 @@
+/** `Friendship.status` */
+export type FriendshipStatus = "pending" | "accepted";
+/** `GameRequest.customLobbies` */
+export type GameRequestCustomLobbies = "Yes" | "No" | "Not sure";
+/** `GameRequest.genre` */
+export type GameRequestGenre = "FPS" | "MOBA" | "Battle Royale" | "Fighting (FGC)" | "Sports" | "Strategy/RTS" | "Sim Racing" | "Card Game" | "Other";
+/** `GameRequest.teamPlay` */
+export type GameRequestTeamPlay = "No (solo)" | "Yes, 2v2" | "Yes, 3v3" | "Yes, 4v4+" | "Don't know";
+/** `Match.lobbyStatus` */
+export type MatchLobbyStatus = "waiting" | "ready" | "disputed" | "completed";
+/** `Match.round` */
+export type MatchRound = "Round 128" | "Round 64" | "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
+/** `Match.streamPlatform` */
+export type MatchStreamPlatform = "twitch" | "youtube" | "kick" | "other";
+/** `Match.winnerSlot` */
+export type MatchWinnerSlot = "home" | "away";
+/** `Prize.rank` */
+export type PrizeRank = "one" | "two" | "three";
+/** `Referral.status` */
+export type ReferralStatus = "pending" | "completed";
+/** `Team.current_status` */
+export type TeamCurrentStatus = "active" | "disbanded";
+/** `TeamInvite.status` */
+export type TeamInviteStatus = "pending" | "accepted" | "declined";
+/** `TeamInvite.team_role` */
+export type TeamInviteTeamRole = "captain" | "co_captain" | "player" | "substitute" | "coach";
+/** `TeamPlayer.team_role` */
+export type TeamPlayerTeamRole = "captain" | "co_captain" | "player" | "substitute" | "coach";
+/** `Tournament.currentStatus` */
+export type TournamentCurrentStatus = "draft" | "open" | "checkIn" | "seeding" | "live" | "completed" | "cancelled";
+/** `TournamentParticipant.entryType` */
+export type TournamentParticipantEntryType = "solo" | "team";
+/** `TournamentParticipant.status` */
+export type TournamentParticipantStatus = "registered" | "active" | "eliminated" | "completed";
+/** `TournamentRole.role` */
+export type TournamentRoleRole = "moderator" | "admin";
+/** `TournamentStage.stageName` */
+export type TournamentStageStageName = "Round 128" | "Round 64" | "Round 32" | "Round 16" | "Quarter Final" | "Semi-Final" | "Third Round" | "Finals" | "League";
+/** `Tournament.teamSize` */
+export type TournamentTeamSize = "one" | "two" | "three" | "four" | "five";
+/** `Tournament.type` */
+export type TournamentType = "Single Elimination" | "League" | "Double Elimination";
+/** `UserTransaction.stripeStatus` */
+export type UserTransactionStripeStatus = "pending" | "completed" | "failed" | "refunded" | "internal";
+/** `UserTransaction.type` */
+export type UserTransactionType = "purchase" | "debit" | "credit" | "refund" | "test";
+/** Readability alias for `tournament.currentStatus`. */
+export type TournamentStatus = TournamentCurrentStatus;

package/dist/generated/enums.js

@@ -0,0 +1,5 @@
+"use strict";
+// AUTO-GENERATED by scripts/sync-from-strapi.js — DO NOT EDIT MANUALLY.
+// Source: xpt-strapi/src/**/content-types/**/schema.json
+// Regenerate with: yarn sync
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/generated/index.d.ts

@@ -0,0 +1,3 @@
+export * from './enums';
+export * from './models';
+export * from './inputs';

package/dist/generated/index.js

@@ -0,0 +1,22 @@
+"use strict";
+// AUTO-GENERATED by scripts/sync-from-strapi.js — DO NOT EDIT MANUALLY.
+// Source: xpt-strapi/src/**/content-types/**/schema.json
+// Regenerate with: yarn sync
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./enums"), exports);
+__exportStar(require("./models"), exports);
+__exportStar(require("./inputs"), exports);