xpt-shared-types 1.0.4 → 1.1.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/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/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 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 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);