@diffenderfer-games/hub-contract 2.0.0-next.0 → 2.0.0-next.2

package/src/api/auth.ts

@@ -1,77 +1,77 @@
-/**
- * Accounts and sessions: guests, claiming, sign-up, log-in, log-out, and the
- * current user (`/me`). Sessions ride the `hub_session` cookie.
- */
-import { z } from 'zod';
-import { Ok, Slug } from '../common';
-import { AuthUser, SessionUser } from '../entities';
-import { ContentRejected, ErrorBody } from '../errors';
-import { requireUser, session } from '../middleware';
-
-/**
- * A credential field, read like the hub's `String(x ?? '')`: a missing field
- * is empty text (the hub then answers with its own rule, or a failed log-in)
- * and a number becomes text. Clients should send a string.
- */
-function credentialText(message: string) {
-  return z.union([z.string(), z.number()], { error: message }).nullish().transform((value) => String(value ?? ''));
-}
-
-/** Username + password, as the sign-up, claim and log-in forms send them. */
-export const Credentials = z.object({
-  /** 2 to 24 characters: letters, digits, `_`, `-` and spaces. */
-  username: credentialText('Username can use letters, numbers, _, -, and spaces.'),
-  /** At least 6 characters. */
-  password: credentialText('Password must be at least 6 characters.'),
-});
-
-/** `{ user }`: the session's account after an auth call. */
-export const AuthResult = z.object({ user: AuthUser });
-
-/** A 400 from sign-up or claim: a bad name or password, or a name the filter rejects. */
-const CredentialsError = z.union([ContentRejected, ErrorBody]);
-
-/** The auth endpoints. */
-export const authEndpoints = {
-  ...session.group({
-    /**
-     * Make sure a session exists. Idempotent: returns the current user if
-     * signed in (the full {@link SessionUser}), else creates a guest.
-     */
-    ensureGuestSession: {
-      method: 'POST', path: '/auth/guest',
-      response: z.object({ user: z.union([SessionUser, AuthUser]) }),
-      doc: { summary: 'Ensure a session (creates a guest if needed)', tags: ['auth'] },
-    },
-    signUpWithPassword: {
-      method: 'POST', path: '/auth/signup', body: Credentials, response: AuthResult,
-      errors: { 400: CredentialsError, 409: ErrorBody, 429: ErrorBody },
-      doc: { summary: 'Create an account and sign in', tags: ['auth'] },
-    },
-    logInWithPassword: {
-      method: 'POST', path: '/auth/login', body: Credentials, response: AuthResult,
-      errors: { 401: ErrorBody, 429: ErrorBody },
-      doc: { summary: 'Sign in; a guest session on this device is merged into the account', tags: ['auth'] },
-    },
-    logOut: {
-      method: 'POST', path: '/auth/logout', response: Ok,
-      doc: { summary: 'Sign out and clear the session cookie', tags: ['auth'] },
-    },
-    getCurrentUser: {
-      method: 'GET', path: '/me',
-      response: z.object({
-        user: SessionUser.nullable(),
-        /** Games the user has a profile in. */
-        profiles: z.array(z.object({ game: Slug, displayName: z.string().nullable() })),
-      }),
-      doc: { summary: 'The current user (or null) and their game profiles', tags: ['auth'] },
-    },
-  }),
-  ...requireUser.group({
-    claimGuestAccount: {
-      method: 'POST', path: '/auth/claim', body: Credentials, response: AuthResult,
-      errors: { 400: CredentialsError, 401: ErrorBody, 409: ErrorBody, 429: ErrorBody },
-      doc: { summary: 'Turn the current guest into an account, keeping its progress', tags: ['auth'] },
-    },
-  }),
-};
+/**
+ * Accounts and sessions: guests, claiming, sign-up, log-in, log-out, and the
+ * current user (`/me`). Sessions ride the `hub_session` cookie.
+ */
+import { z } from 'zod';
+import { Ok, Slug } from '../common';
+import { AuthUser, SessionUser } from '../entities';
+import { ContentRejected, ErrorBody } from '../errors';
+import { requireUser, session } from '../middleware';
+
+/**
+ * A credential field, read like the hub's `String(x ?? '')`: a missing field
+ * is empty text (the hub then answers with its own rule, or a failed log-in)
+ * and a number becomes text. Clients should send a string.
+ */
+function credentialText(message: string) {
+  return z.union([z.string(), z.number()], { error: message }).nullish().transform((value) => String(value ?? ''));
+}
+
+/** Username + password, as the sign-up, claim and log-in forms send them. */
+export const Credentials = z.object({
+  /** 2 to 24 characters: letters, digits, `_`, `-` and spaces. */
+  username: credentialText('Username can use letters, numbers, _, -, and spaces.'),
+  /** At least 6 characters. */
+  password: credentialText('Password must be at least 6 characters.'),
+});
+
+/** `{ user }`: the session's account after an auth call. */
+export const AuthResult = z.object({ user: AuthUser });
+
+/** A 400 from sign-up or claim: a bad name or password, or a name the filter rejects. */
+const CredentialsError = z.union([ContentRejected, ErrorBody]);
+
+/** The auth endpoints. */
+export const authEndpoints = {
+  ...session.group({
+    /**
+     * Make sure a session exists. Idempotent: returns the current user if
+     * signed in (the full {@link SessionUser}), else creates a guest.
+     */
+    ensureGuestSession: {
+      method: 'POST', path: '/auth/guest',
+      response: z.object({ user: z.union([SessionUser, AuthUser]) }),
+      doc: { summary: 'Ensure a session (creates a guest if needed)', tags: ['auth'] },
+    },
+    signUpWithPassword: {
+      method: 'POST', path: '/auth/signup', body: Credentials, response: AuthResult,
+      errors: { 400: CredentialsError, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Create an account and sign in', tags: ['auth'] },
+    },
+    logInWithPassword: {
+      method: 'POST', path: '/auth/login', body: Credentials, response: AuthResult,
+      errors: { 401: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Sign in; a guest session on this device is merged into the account', tags: ['auth'] },
+    },
+    logOut: {
+      method: 'POST', path: '/auth/logout', response: Ok,
+      doc: { summary: 'Sign out and clear the session cookie', tags: ['auth'] },
+    },
+    getCurrentUser: {
+      method: 'GET', path: '/me',
+      response: z.object({
+        user: SessionUser.nullable(),
+        /** Games the user has a profile in. */
+        profiles: z.array(z.object({ game: Slug, displayName: z.string().nullable() })),
+      }),
+      doc: { summary: 'The current user (or null) and their game profiles', tags: ['auth'] },
+    },
+  }),
+  ...requireUser.group({
+    claimGuestAccount: {
+      method: 'POST', path: '/auth/claim', body: Credentials, response: AuthResult,
+      errors: { 400: CredentialsError, 401: ErrorBody, 409: ErrorBody, 429: ErrorBody },
+      doc: { summary: 'Turn the current guest into an account, keeping its progress', tags: ['auth'] },
+    },
+  }),
+};

package/src/api/catalog-activity.ts

@@ -0,0 +1,66 @@
+/**
+ * Who is in each game right now (aggregate head counts only: never who), and
+ * the signed-in player's own activity in one game. The catalog's cards, the
+ * menu's game list and the game sheet show them.
+ */
+import { use } from '@ayepi/core';
+import { z } from 'zod';
+import { Millis, Slug } from '../common';
+import { ErrorBody } from '../errors';
+import { game, requireUser, session } from '../middleware';
+
+/** A non-negative head count. */
+const HeadCount = z.number().int().nonnegative();
+
+/**
+ * How many people have a game open right now: claimed accounts and guests.
+ * Counts only, so no player is ever identified.
+ */
+export const GamePlayerCount = z.object({
+  accounts: HeadCount,
+  guests: HeadCount,
+});
+
+/** How many people have a game open right now. */
+export type GamePlayerCount = z.infer<typeof GamePlayerCount>;
+
+/** Head counts per game slug; games nobody has open are absent. */
+export const GamePlayerCounts = z.record(Slug, GamePlayerCount);
+
+/** Head counts per game slug. */
+export type GamePlayerCounts = z.infer<typeof GamePlayerCounts>;
+
+/** The caller's activity in one game, within the analytics retention window. */
+export const MyGameActivity = z.object({
+  /** Times the game was opened. */
+  plays: HeadCount,
+  /** Minutes with the game open and visible (one heartbeat a minute). */
+  minutesPlayed: HeadCount,
+  /** The first and latest event in the window, epoch ms; `null` when there are none. */
+  firstPlayedAt: Millis.nullable(),
+  lastPlayedAt: Millis.nullable(),
+  /** How many days back the counts reach. */
+  windowDays: z.number().int().positive(),
+});
+
+/** The caller's activity in one game. */
+export type MyGameActivity = z.infer<typeof MyGameActivity>;
+
+/** The activity endpoints (part of the catalog area). */
+export const catalogActivityEndpoints = {
+  ...session.group({
+    getGamePlayerCounts: {
+      method: 'GET', path: '/catalog/players',
+      response: z.object({ games: GamePlayerCounts }),
+      doc: { summary: 'How many accounts and guests have each game open right now (counts only)', tags: ['catalog'] },
+    },
+  }),
+  ...use(requireUser, game).path('/games/:slug').group({
+    getMyGameActivity: {
+      method: 'GET', path: '/me/activity',
+      response: MyGameActivity,
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "The caller's plays and time played in this game", tags: ['catalog'] },
+    },
+  }),
+};

package/src/api/catalog.ts

@@ -1,171 +1,177 @@
-/**
- * The game catalog, favorites and What's new notes.
- */
-import { z } from 'zod';
-import { Millis, Slug } from '../common';
-import { ErrorBody } from '../errors';
-import { requireUser, session } from '../middleware';
-import { RaceStatFormat } from '../manifest/race';
-import { RaceParamValue } from './mp/races';
-import { LooseNumber, LooseText, Truthy } from '../coerce';
-
-/** A `[min, max]` player count, each 1 to 8. */
-export const PlayerRange = z.tuple([z.number().int().min(1).max(8), z.number().int().min(1).max(8)]);
-
-/**
- * What the menu needs to know about an online game (invite picker, Join and
- * Watch buttons, the catalog's Online tag), not the full manifest.
- */
-export const MultiplayerSummary = z.object({
-  /** `own-server` only for process apps that run their own game server. */
-  transport: z.enum(['hub-rooms', 'own-server']),
-  players: PlayerRange,
-  invites: z.boolean(),
-  join: z.boolean(),
-  spectate: z.boolean(),
-  modes: z.array(z.object({ key: z.string(), title: z.string() })),
-  /** Present (and `true`) when the block was made for a race-only game. */
-  raceOnly: z.literal(true).optional(),
-});
-
-/** An online game's capabilities. */
-export type MultiplayerSummary = z.infer<typeof MultiplayerSummary>;
-
-/** A race game's manifest summary (players, the creator's param choices, the stats the HUD shows). */
-export const RaceSummary = z.object({
-  /** Each 2 to 8. */
-  players: PlayerRange,
-  /** Up to 6 choices the race creator picks. */
-  params: z.array(z.object({
-    key: z.string(),
-    title: z.string(),
-    /** Up to 12. */
-    options: z.array(z.object({ value: RaceParamValue, title: z.string() })),
-    /** One of the options' values. */
-    default: RaceParamValue,
-  })),
-  /** Up to 8 stats the race HUD and history show. */
-  stats: z.array(z.object({
-    key: z.string(),
-    title: z.string(),
-    format: RaceStatFormat,
-  })),
-});
-
-/** A race game's manifest summary. */
-export type RaceSummary = z.infer<typeof RaceSummary>;
-
-/** A listed game, as the menu's game list and the catalog show it. Broken apps are left out. */
-export const GameInfo = z.object({
-  slug: Slug,
-  title: z.string(),
-  /** Its URL path, e.g. `/duel`. */
-  path: z.string(),
-  /** `process` apps run their own server behind the host. */
-  kind: z.enum(['static', 'process']),
-  hasImage: z.boolean(),
-  /** `false` when the game opted out of the injected hub menu. */
-  hubEnabled: z.boolean(),
-  /** `null` for single-player games. */
-  multiplayer: MultiplayerSummary.nullable(),
-  /** `null` unless the game supports races. */
-  race: RaceSummary.nullable(),
-});
-
-/** A listed game. */
-export type GameInfo = z.infer<typeof GameInfo>;
-
-/** `{ games }`: the caller's starred slugs, oldest star first. */
-const Favorites = z.object({ games: z.array(Slug) });
-
-/** One What's new note. */
-export const ChangeNote = z.object({
-  id: z.number().int().positive(),
-  /** The game's slug, or `_hub` for the site's own notes. */
-  game: Slug,
-  /** The game's title, or `diffenderfer.games` for the site's own notes. */
-  title: z.string(),
-  text: z.string(),
-  /** When the note went live (the deploy that first saw it), epoch ms. */
-  at: Millis,
-  /** Not yet seen by this player (or since `?since=` when signed out). */
-  new: z.boolean(),
-});
-
-/** A What's new note. */
-export type ChangeNote = z.infer<typeof ChangeNote>;
-
-/** The catalog endpoints. */
-export const catalogEndpoints = {
-  ...session.group({
-    listGames: {
-      method: 'GET', path: '/games',
-      response: z.object({ games: z.array(GameInfo) }),
-      doc: { summary: 'The game catalog, sorted by title', tags: ['catalog'] },
-    },
-    /**
-     * Notes from the last 30 days, newest first (at most 6 per game and 30
-     * in all). In a game, `?game=` limits them to that game's and the site's.
-     */
-    listWhatsNewNotes: {
-      method: 'GET', path: '/changes',
-      query: z.object({
-        /** A game's slug. Empty means everything; an unknown one lists only the site's notes. */
-        game: z.string().optional(),
-        /**
-         * Signed out only: the device's last-cleared time (epoch ms); without
-         * it (or when it isn't a number) nothing is new.
-         */
-        since: z.preprocess((value: number | string | undefined) => (value === '' ? undefined : value), LooseNumber.optional()).catch(undefined),
-      }),
-      response: z.object({
-        items: z.array(ChangeNote),
-        /** How many of `items` are new. */
-        unseen: z.number().int().nonnegative(),
-        signedIn: z.boolean(),
-      }),
-      doc: { summary: "What's new: recent change notes", tags: ['catalog'] },
-    },
-  }),
-  ...requireUser.group({
-    listFavoriteGames: {
-      method: 'GET', path: '/favorites', response: Favorites,
-      errors: { 401: ErrorBody },
-      doc: { summary: "The caller's starred games", tags: ['catalog'] },
-    },
-    /**
-     * Star or unstar a game (idempotent). Starring needs a known game (404);
-     * unstarring any slug succeeds.
-     */
-    setGameFavorite: {
-      method: 'PUT', path: '/favorites/:slug',
-      params: z.object({ slug: Slug }),
-      body: z.object({
-        /** `true` stars, `false` (or missing) unstars. */
-        on: Truthy.optional(),
-      }),
-      response: Favorites,
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: 'Star or unstar a game', tags: ['catalog'] },
-    },
-    /**
-     * Mark notes seen now. With `game`: that game's and the site's. With
-     * `all` (or neither): everything.
-     */
-    markWhatsNewSeen: {
-      method: 'POST', path: '/changes/seen',
-      body: z.object({
-        /** A game's slug, read as text; an unknown one is a 404. Ignored with `all`. */
-        game: LooseText.nullish(),
-        all: Truthy.optional(),
-      }),
-      response: z.object({
-        ok: z.literal(true),
-        /** The seen mark stored, epoch ms. */
-        seenAt: Millis,
-      }),
-      errors: { 401: ErrorBody, 404: ErrorBody },
-      doc: { summary: "Mark What's new notes seen", tags: ['catalog'] },
-    },
-  }),
-};
+/**
+ * The game catalog, favorites, What's new notes, and who is playing what (counts only).
+ */
+import { z } from 'zod';
+import { Millis, Slug } from '../common';
+import { ErrorBody } from '../errors';
+import { requireUser, session } from '../middleware';
+import { RaceStatFormat } from '../manifest/race';
+import { RaceParamValue } from './mp/races';
+import { LooseNumber, LooseText, Truthy } from '../coerce';
+import { catalogActivityEndpoints } from './catalog-activity';
+
+export * from './catalog-activity';
+
+/** A `[min, max]` player count, each 1 to 8. */
+export const PlayerRange = z.tuple([z.number().int().min(1).max(8), z.number().int().min(1).max(8)]);
+
+/**
+ * What the menu needs to know about an online game (invite picker, Join and
+ * Watch buttons, the catalog's Online tag), not the full manifest.
+ */
+export const MultiplayerSummary = z.object({
+  /** `own-server` only for process apps that run their own game server. */
+  transport: z.enum(['hub-rooms', 'own-server']),
+  players: PlayerRange,
+  invites: z.boolean(),
+  join: z.boolean(),
+  spectate: z.boolean(),
+  modes: z.array(z.object({ key: z.string(), title: z.string() })),
+  /** Present (and `true`) when the block was made for a race-only game. */
+  raceOnly: z.literal(true).optional(),
+});
+
+/** An online game's capabilities. */
+export type MultiplayerSummary = z.infer<typeof MultiplayerSummary>;
+
+/** A race game's manifest summary (players, the creator's param choices, the stats the HUD shows). */
+export const RaceSummary = z.object({
+  /** Each 2 to 8. */
+  players: PlayerRange,
+  /** Up to 6 choices the race creator picks. */
+  params: z.array(z.object({
+    key: z.string(),
+    title: z.string(),
+    /** Up to 12. */
+    options: z.array(z.object({ value: RaceParamValue, title: z.string() })),
+    /** One of the options' values. */
+    default: RaceParamValue,
+  })),
+  /** Up to 8 stats the race HUD and history show. */
+  stats: z.array(z.object({
+    key: z.string(),
+    title: z.string(),
+    format: RaceStatFormat,
+  })),
+});
+
+/** A race game's manifest summary. */
+export type RaceSummary = z.infer<typeof RaceSummary>;
+
+/** A listed game, as the menu's game list and the catalog show it. Broken apps are left out. */
+export const GameInfo = z.object({
+  slug: Slug,
+  title: z.string(),
+  /** Its URL path, e.g. `/duel`. */
+  path: z.string(),
+  /** `process` apps run their own server behind the host. */
+  kind: z.enum(['static', 'process']),
+  hasImage: z.boolean(),
+  /** `false` when the game opted out of the injected hub menu. */
+  hubEnabled: z.boolean(),
+  /** `null` for single-player games. */
+  multiplayer: MultiplayerSummary.nullable(),
+  /** `null` unless the game supports races. */
+  race: RaceSummary.nullable(),
+  /** Present (and `true`) when tournaments can be played in this game: it races, or declares `multiplayer.tournaments`. */
+  tournaments: z.literal(true).optional(),
+});
+
+/** A listed game. */
+export type GameInfo = z.infer<typeof GameInfo>;
+
+/** `{ games }`: the caller's starred slugs, oldest star first. */
+const Favorites = z.object({ games: z.array(Slug) });
+
+/** One What's new note. */
+export const ChangeNote = z.object({
+  id: z.number().int().positive(),
+  /** The game's slug, or `_hub` for the site's own notes. */
+  game: Slug,
+  /** The game's title, or `diffenderfer.games` for the site's own notes. */
+  title: z.string(),
+  text: z.string(),
+  /** When the note went live (the deploy that first saw it), epoch ms. */
+  at: Millis,
+  /** Not yet seen by this player (or since `?since=` when signed out). */
+  new: z.boolean(),
+});
+
+/** A What's new note. */
+export type ChangeNote = z.infer<typeof ChangeNote>;
+
+/** The catalog endpoints. */
+export const catalogEndpoints = {
+  ...catalogActivityEndpoints,
+  ...session.group({
+    listGames: {
+      method: 'GET', path: '/games',
+      response: z.object({ games: z.array(GameInfo) }),
+      doc: { summary: 'The game catalog, sorted by title', tags: ['catalog'] },
+    },
+    /**
+     * Notes from the last 30 days, newest first (at most 6 per game and 30
+     * in all). In a game, `?game=` limits them to that game's and the site's.
+     */
+    listWhatsNewNotes: {
+      method: 'GET', path: '/changes',
+      query: z.object({
+        /** A game's slug. Empty means everything; an unknown one lists only the site's notes. */
+        game: z.string().optional(),
+        /**
+         * Signed out only: the device's last-cleared time (epoch ms); without
+         * it (or when it isn't a number) nothing is new.
+         */
+        since: z.preprocess((value: number | string | undefined) => (value === '' ? undefined : value), LooseNumber.optional()).catch(undefined),
+      }),
+      response: z.object({
+        items: z.array(ChangeNote),
+        /** How many of `items` are new. */
+        unseen: z.number().int().nonnegative(),
+        signedIn: z.boolean(),
+      }),
+      doc: { summary: "What's new: recent change notes", tags: ['catalog'] },
+    },
+  }),
+  ...requireUser.group({
+    listFavoriteGames: {
+      method: 'GET', path: '/favorites', response: Favorites,
+      errors: { 401: ErrorBody },
+      doc: { summary: "The caller's starred games", tags: ['catalog'] },
+    },
+    /**
+     * Star or unstar a game (idempotent). Starring needs a known game (404);
+     * unstarring any slug succeeds.
+     */
+    setGameFavorite: {
+      method: 'PUT', path: '/favorites/:slug',
+      params: z.object({ slug: Slug }),
+      body: z.object({
+        /** `true` stars, `false` (or missing) unstars. */
+        on: Truthy.optional(),
+      }),
+      response: Favorites,
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: 'Star or unstar a game', tags: ['catalog'] },
+    },
+    /**
+     * Mark notes seen now. With `game`: that game's and the site's. With
+     * `all` (or neither): everything.
+     */
+    markWhatsNewSeen: {
+      method: 'POST', path: '/changes/seen',
+      body: z.object({
+        /** A game's slug, read as text; an unknown one is a 404. Ignored with `all`. */
+        game: LooseText.nullish(),
+        all: Truthy.optional(),
+      }),
+      response: z.object({
+        ok: z.literal(true),
+        /** The seen mark stored, epoch ms. */
+        seenAt: Millis,
+      }),
+      errors: { 401: ErrorBody, 404: ErrorBody },
+      doc: { summary: "Mark What's new notes seen", tags: ['catalog'] },
+    },
+  }),
+};