xpt-shared-types 1.0.4 → 1.1.0

package/scripts/sync-from-strapi.js

@@ -0,0 +1,281 @@
+/* eslint-disable no-console */
+/**
+ * Generates the shared API contract from the Strapi content-type schemas.
+ *
+ * `schema.json` is the source of truth — not `types/generated/contentTypes.d.ts`,
+ * which is gitignored in xpt-strapi and only exists after `strapi develop` has run.
+ *
+ *   node scripts/sync-from-strapi.js [pathToStrapiRepo]
+ *
+ * Output is committed to this repo; run this whenever a content type changes.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const STRAPI_ROOT =
+  process.argv[2] ||
+  process.env.XPT_STRAPI_PATH ||
+  path.resolve(__dirname, '../../xpt-strapi');
+const OUT = path.resolve(__dirname, '../src/generated');
+
+const BANNER = [
+  '// AUTO-GENERATED by scripts/sync-from-strapi.js — DO NOT EDIT MANUALLY.',
+  '// Source: xpt-strapi/src/**/content-types/**/schema.json',
+  '// Regenerate with: yarn sync',
+  '',
+].join('\n');
+
+// ── helpers ────────────────────────────────────────────────────────────────
+/** Quote a property name only when it is not a bare identifier. */
+const prop = (name) =>
+  /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(name) ? name : JSON.stringify(name);
+
+const pascal = (s) =>
+  String(s)
+    .replace(/[_-]+([a-zA-Z0-9])/g, (_, c) => c.toUpperCase())
+    .replace(/^([a-z])/, (_, c) => c.toUpperCase())
+    .replace(/[^A-Za-z0-9]/g, '');
+
+/** api::tournament-participant.tournament-participant -> TournamentParticipant */
+function modelNameFromUid(uid) {
+  if (uid === 'plugin::users-permissions.user') return 'User';
+  if (uid === 'plugin::users-permissions.role') return 'UserRole';
+  if (uid === 'plugin::upload.file') return 'StrapiMedia';
+  const m = /^api::[^.]+\.(.+)$/.exec(uid);
+  return m ? pascal(m[1]) : null;
+}
+
+const SCALARS = {
+  string: 'string',
+  text: 'string',
+  richtext: 'string',
+  uid: 'string',
+  email: 'string',
+  password: 'string',
+  datetime: 'string',
+  date: 'string',
+  time: 'string',
+  biginteger: 'string', // Strapi serialises bigint as string
+  integer: 'number',
+  float: 'number',
+  decimal: 'number',
+  boolean: 'boolean',
+  json: 'unknown',
+  blocks: 'BlocksContent',
+};
+
+// ── collect schemas ────────────────────────────────────────────────────────
+function findSchemas(root) {
+  const out = [];
+  const roots = [
+    path.join(root, 'src', 'api'),
+    path.join(root, 'src', 'extensions'),
+  ];
+  for (const base of roots) {
+    if (!fs.existsSync(base)) continue;
+    for (const dir of fs.readdirSync(base)) {
+      const ctDir = path.join(base, dir, 'content-types');
+      if (!fs.existsSync(ctDir)) continue;
+      for (const ct of fs.readdirSync(ctDir)) {
+        const file = path.join(ctDir, ct, 'schema.json');
+        if (fs.existsSync(file)) out.push(file);
+      }
+    }
+  }
+  return out.sort();
+}
+
+const files = findSchemas(STRAPI_ROOT);
+if (!files.length) {
+  console.error(
+    'No schema.json found under ' +
+      STRAPI_ROOT +
+      '. Pass the xpt-strapi path as an argument.'
+  );
+  process.exit(1);
+}
+
+const collected = [];
+for (const file of files) {
+  const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const info = raw.info || {};
+  const singular = info.singularName || path.basename(path.dirname(file));
+  // The users-permissions extension augments the plugin's own user model.
+  const isUserExt = file.split(path.sep).includes('users-permissions');
+  collected.push({
+    name: isUserExt ? 'User' : pascal(singular),
+    singular: isUserExt ? 'user' : singular,
+    attributes: raw.attributes || {},
+  });
+}
+
+// Merge any model declared more than once (e.g. the user extension).
+const byName = new Map();
+for (const m of collected) {
+  if (byName.has(m.name)) {
+    Object.assign(byName.get(m.name).attributes, m.attributes);
+  } else {
+    byName.set(m.name, m);
+  }
+}
+const allModels = [...byName.values()].sort((a, b) =>
+  a.name.localeCompare(b.name)
+);
+
+// ── enums ──────────────────────────────────────────────────────────────────
+const enums = [];
+for (const m of allModels) {
+  for (const [field, def] of Object.entries(m.attributes)) {
+    if (def.type !== 'enumeration' || !Array.isArray(def.enum)) continue;
+    enums.push({
+      name: m.name + pascal(field),
+      values: def.enum,
+      model: m.name,
+      field,
+    });
+  }
+}
+enums.sort((a, b) => a.name.localeCompare(b.name));
+
+let enumsOut = BANNER + '\n';
+for (const e of enums) {
+  enumsOut +=
+    '/** `' +
+    e.model +
+    '.' +
+    e.field +
+    '` */\nexport type ' +
+    e.name +
+    ' =\n' +
+    e.values.map((v) => '  | ' + JSON.stringify(v)).join('\n') +
+    ';\n\n';
+}
+enumsOut +=
+  '/** Readability alias for `tournament.currentStatus`. */\n' +
+  'export type TournamentStatus = TournamentCurrentStatus;\n';
+
+// ── models (read shapes) ───────────────────────────────────────────────────
+const enumLookup = new Map(enums.map((e) => [e.model + '.' + e.field, e.name]));
+const usedEnums = new Set();
+
+function readTypeFor(model, field, def) {
+  if (def.type === 'enumeration') {
+    return enumLookup.get(model.name + '.' + field) || 'string';
+  }
+  if (def.type === 'media') {
+    return def.multiple ? 'StrapiMedia[]' : 'StrapiMedia';
+  }
+  if (def.type === 'relation') {
+    const target = modelNameFromUid(def.target);
+    if (!target) return 'unknown';
+    const many =
+      def.relation === 'oneToMany' || def.relation === 'manyToMany';
+    return many ? target + '[]' : target;
+  }
+  return SCALARS[def.type] || 'unknown';
+}
+
+let modelsBody = '';
+for (const m of allModels) {
+  const lines = [];
+  for (const [field, def] of Object.entries(m.attributes)) {
+    // `private` attributes are never returned by the content API.
+    if (def.private) continue;
+    const t = readTypeFor(m, field, def);
+    if (def.type === 'enumeration') usedEnums.add(t);
+    // Everything except id/documentId is optional, because nothing else is
+    // guaranteed on the wire:
+    //   - relations and media appear only when the query populates them;
+    //   - any scalar disappears when the query uses `fields`, which this
+    //     codebase does pervasively — so even a schema-`required` field like
+    //     user.email is absent from most responses.
+    // The base model is therefore the minimum guarantee; use `Populated<T, K>`
+    // at a call site to record what that particular query actually returned.
+    // Strapi also sends `null` rather than omitting an unset nullable value,
+    // so single-valued optionals are `?: T | null`. Lists come back as `[]`.
+    const isList = t.endsWith('[]');
+    const rendered = isList ? t : t + ' | null';
+    lines.push('  ' + prop(field) + '?: ' + rendered + ';');
+  }
+  modelsBody +=
+    '/** `' +
+    m.singular +
+    '` */\nexport interface ' +
+    m.name +
+    ' extends StrapiDocument {\n' +
+    lines.join('\n') +
+    '\n}\n\n';
+}
+
+const enumImportList = [...usedEnums]
+  .filter((e) => !e.endsWith('[]'))
+  .sort()
+  .map((e) => '  ' + e + ',')
+  .join('\n');
+
+const modelsOut =
+  BANNER +
+  "\nimport type {\n  BlocksContent,\n  StrapiDocument,\n  StrapiMedia,\n  UserRole,\n} from '../contracts';\n" +
+  (enumImportList ? 'import type {\n' + enumImportList + "\n} from './enums';\n" : '') +
+  '\n' +
+  modelsBody;
+
+// ── inputs (write shapes) ──────────────────────────────────────────────────
+// Write payloads differ structurally from read shapes: relations are sent as
+// documentIds or connect/set/disconnect, media as numeric file ids.
+let inputsBody = '';
+for (const m of allModels) {
+  const lines = [];
+  for (const [field, def] of Object.entries(m.attributes)) {
+    if (def.private) continue;
+    let t;
+    if (def.type === 'relation') {
+      const many =
+        def.relation === 'oneToMany' || def.relation === 'manyToMany';
+      t = many ? 'RelationInput | RelationInput[]' : 'RelationInput';
+    } else if (def.type === 'media') {
+      t = def.multiple ? 'MediaInput[]' : 'MediaInput';
+    } else if (def.type === 'enumeration') {
+      t = enumLookup.get(m.name + '.' + field) || 'string';
+    } else {
+      t = SCALARS[def.type] || 'unknown';
+    }
+    lines.push('  ' + prop(field) + '?: ' + t + ';');
+  }
+  inputsBody +=
+    '/** Write payload for `' +
+    m.singular +
+    '`. */\nexport interface ' +
+    m.name +
+    'Input {\n' +
+    lines.join('\n') +
+    '\n}\n\n';
+}
+
+const inputsOut =
+  BANNER +
+  "\nimport type {\n  BlocksContent,\n  MediaInput,\n  RelationInput,\n} from '../contracts';\n" +
+  (enumImportList ? 'import type {\n' + enumImportList + "\n} from './enums';\n" : '') +
+  '\n' +
+  inputsBody;
+
+// ── write ──────────────────────────────────────────────────────────────────
+fs.mkdirSync(OUT, { recursive: true });
+fs.writeFileSync(path.join(OUT, 'enums.ts'), enumsOut);
+fs.writeFileSync(path.join(OUT, 'models.ts'), modelsOut);
+fs.writeFileSync(path.join(OUT, 'inputs.ts'), inputsOut);
+fs.writeFileSync(
+  path.join(OUT, 'index.ts'),
+  BANNER +
+    "\nexport * from './enums';\nexport * from './models';\nexport * from './inputs';\n"
+);
+
+console.log(
+  'Generated ' +
+    allModels.length +
+    ' models and ' +
+    enums.length +
+    ' enums from ' +
+    files.length +
+    ' schemas.'
+);

package/src/contracts/index.ts

@@ -0,0 +1,158 @@
+/**
+ * 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[];
+
+// ── write payloads ─────────────────────────────────────────────────────────
+
+/**
+ * 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;
+
+// ── responses ──────────────────────────────────────────────────────────────
+
+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;
+}
+
+// ── populate awareness ─────────────────────────────────────────────────────
+
+/**
+ * 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;
+}