@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.10

package/src/core/hub-progress.ts

@@ -1,205 +1,269 @@
-/**
- * Accounts and the player's progress in this game: sign-in, the profile,
- * saves, stats and leaderboards. Reads fall back to the offline cache; writes
- * apply to the cache at once and are queued while offline. Method names are
- * the v1 client's, unchanged.
- */
-import type { Board, Json, Stats } from '@diffenderfer-games/hub-contract';
-import { HubConnection } from './connection';
-import { toGameData, toStoredJson, type GamePayload } from './game-data';
-import type { ProfilePatch, QueuedScoreOptions } from './offline/queue';
-import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
-
-/** A signed-in user, as the auth calls answer. */
-export interface AuthResponse {
-  /** The signed-in user. */
-  readonly user: User;
-}
-
-/** A stat's new value, as the stat calls answer. */
-export interface StatResult {
-  /** The stat key. */
-  readonly key: string;
-  /** Its value after the update. */
-  readonly value: number;
-}
-
-/** A profile change with the game's own data typed as `TData`. */
-export interface ProfileUpdate<TData extends GamePayload = Json> {
-  /** Shown to other players; `null` clears it. */
-  readonly displayName?: string | null;
-  /** The game's own profile data. */
-  readonly data?: TData;
-}
-
-/** A profile with the game's own data typed as `TData`. */
-function typedProfile<TData>(profile: Profile | null): Profile<TData> | null {
-  return profile === null ? null : { ...profile, data: toGameData<TData>(profile.data) };
-}
-
-/** A save with the game's own data typed as `TData`. */
-function typedSave<TData>(save: Save | null): Save<TData> | null {
-  return save === null ? null : { ...save, data: toGameData<TData>(save.data) };
-}
-
-/** Accounts, profile, saves, stats and leaderboards. */
-export class HubProgress extends HubConnection {
-  /** The current user (or `null`) and the games they have a profile in. */
-  me(): Promise<MeResponse> {
-    return this.withFallback(() => this.rest.call('getCurrentUser'), () => {
-      const profile = this.store.getProfile();
-      return { user: this.store.getUser(), profiles: profile === null ? [] : [{ game: profile.game, displayName: profile.displayName }] };
-    });
-  }
-
-  /**
-   * Make sure a session exists, creating a guest (a random name, no
-   * password) when the player isn't signed in, so progress saves without a
-   * sign-in. Idempotent. Offline, a local guest is used.
-   */
-  ensureGuest(): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('ensureGuestSession'), () => {
-      const known = this.store.getUser();
-      if (known !== null) {
-        return { user: known };
-      }
-      const guest: User = { id: 0, username: 'Guest-local', guest: true };
-      this.store.setUser(guest);
-      return { user: guest };
-    });
-  }
-
-  /**
-   * Turn the current guest into a registered account (the same identity, so
-   * all progress carries over). Rejects with 409 when already registered or
-   * the name is taken; the player should `login` instead.
-   */
-  claim(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('claimGuestAccount', { username, password }), () => this.signInLocally({ id: 0, username, guest: false }));
-  }
-
-  /** Create an account and sign in. (Offline: a local user is stored.) */
-  signup(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('signUpWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
-  }
-
-  /** Sign in. (Offline: a local user is stored so signed-in flows work.) */
-  login(username: string, password: string): Promise<AuthResponse> {
-    return this.withFallback<AuthResponse>(() => this.rest.call('logInWithPassword', { username, password }), () => this.signInLocally({ id: 0, username }));
-  }
-
-  /** Sign out (ends the session shared by every game). */
-  logout(): Promise<{ ok: true }> {
-    return this.withFallback(() => this.rest.call('logOut'), () => {
-      this.store.clearUser();
-      return { ok: true } as const;
-    });
-  }
-
-  private signInLocally(user: User): AuthResponse {
-    this.store.setUser(user);
-    return { user };
-  }
-
-  /** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
-  getProfile<TData = Json>(): Promise<{ profile: Profile<TData> | null }> {
-    return this.withFallback(
-      async () => ({ profile: typedProfile<TData>((await this.rest.call('getGameProfile', this.gameFields())).profile) }),
-      () => ({ profile: typedProfile<TData>(this.store.getProfile()) }),
-    );
-  }
-
-  /** Create or update this game's profile for the current user. */
-  setProfile<TData extends GamePayload = Json>(patch: ProfileUpdate<TData>): Promise<{ profile: Profile<TData> }> {
-    const queued: ProfilePatch = {};
-    if (patch.displayName !== undefined) {
-      queued.displayName = patch.displayName;
-    }
-    if (patch.data !== undefined) {
-      queued.data = toStoredJson(patch.data);
-    }
-    return this.mutateQueued({ kind: 'setProfile', patch: queued }, () => {
-      const stored = this.store.setProfile(this.slug ?? 'app', patch.displayName ?? null, queued.data ?? {});
-      return { profile: { ...stored, data: toGameData<TData>(stored.data) } };
-    });
-  }
-
-  /** Metadata for every save slot (no payloads), newest first. */
-  listSaves(): Promise<{ saves: SaveMeta[] }> {
-    return this.withFallback(() => this.rest.call('listSaves', this.gameFields()), () => ({ saves: this.store.listSaves() }));
-  }
-
-  /** One slot's contents, or `save: null` when the slot is empty. `TData` is the game's own save type. */
-  getSave<TData = Json>(slot: string): Promise<{ save: Save<TData> | null }> {
-    return this.withFallback(
-      async () => ({ save: typedSave<TData>((await this.rest.call('getSave', { ...this.gameFields(), slot })).save) }),
-      () => ({ save: typedSave<TData>(this.store.getSave(slot)) }),
-    );
-  }
-
-  /** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- kept so v1 calls such as putSave<MySave>(...) still compile
-  putSave<TData extends GamePayload = Json>(slot: string, saveData: TData, label?: string): Promise<{ ok: true; updatedAt: number }> {
-    const stored = toStoredJson(saveData);
-    return this.mutateQueued({ kind: 'putSave', slot, data: stored, label: label ?? null }, () => ({ ok: true as const, updatedAt: this.store.putSave(slot, stored, label ?? null) }));
-  }
-
-  /** Delete a save slot. */
-  deleteSave(slot: string): Promise<{ ok: true }> {
-    return this.mutateQueued({ kind: 'deleteSave', slot }, () => {
-      this.store.deleteSave(slot);
-      return { ok: true as const };
-    });
-  }
-
-  /** Numeric stats for the current user, or another player's via `userId`. */
-  getStats(userId?: number): Promise<{ stats: Stats }> {
-    return this.withFallback(
-      () => this.rest.call('getGameStats', { ...this.gameFields(), ...(userId === undefined ? {} : { user: userId }) }),
-      () => ({ stats: this.store.getStats() }),
-    );
-  }
-
-  /** Overwrite a stat. */
-  setStat(key: string, value: number): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'setStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'set') }));
-  }
-
-  /** Add to a stat (creating it at `amount` when absent). */
-  incrStat(key: string, amount = 1): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'incrStat', key, amount }, () => ({ key, value: this.store.updateStat(key, amount, 'incr') }));
-  }
-
-  /** Keep the larger of the stored and the given value. */
-  maxStat(key: string, value: number): Promise<StatResult> {
-    return this.mutateQueued({ kind: 'maxStat', key, value }, () => ({ key, value: this.store.updateStat(key, value, 'max') }));
-  }
-
-  /** Submit a score. The board is created on first use; only a player's best score sticks. */
-  submitScore<TMeta extends GamePayload = Json>(boardKey: string, score: number, opts: SubmitScoreOptions<TMeta> = {}): Promise<SubmitScoreResult> {
-    const queued: QueuedScoreOptions = {
-      ...(opts.title === undefined ? {} : { title: opts.title }),
-      ...(opts.sort === undefined ? {} : { sort: opts.sort }),
-      ...(opts.meta === undefined ? {} : { meta: toStoredJson(opts.meta) }),
-    };
-    return this.mutateQueued({ kind: 'submitScore', key: boardKey, score, opts: queued }, () => ({ ...this.store.submitScore(boardKey, score, queued), rank: 1 }));
-  }
-
-  /** One board's ranked entries (top `limit`, default 50). Offline: only the player's own best. */
-  getLeaderboard(boardKey: string, limit = 50): Promise<LeaderboardResult> {
-    return this.withFallback(() => this.rest.call('getLeaderboard', { ...this.gameFields(), key: boardKey, limit }), () => {
-      const local = this.store.getBoard(boardKey);
-      if (local === null) {
-        return { board: { key: boardKey, title: boardKey, sortDir: 'desc' }, entries: [] };
-      }
-      const user = this.store.getUser();
-      return { board: local.board, entries: [{ rank: 1, userId: user?.id ?? 0, username: user?.username ?? 'you', score: local.best, meta: null }] };
-    });
-  }
-
-  /** The boards this game owns (keys and titles, no entries). */
-  listLeaderboards(): Promise<{ boards: Board[] }> {
-    return this.withFallback(() => this.rest.call('listGameLeaderboards', this.gameFields()), () => ({ boards: this.store.listBoards() }));
-  }
-
-}
+/**
+ * Accounts and the player's progress in this game: sign-in, the profile,
+ * saves, stats and leaderboards. Reads fall back to the offline cache; writes
+ * apply to the cache at once and are queued while offline. Method names are
+ * the v1 client's, unchanged.
+ */
+import type { Board, Json, Stats } from '@diffenderfer-games/hub-contract';
+import { HubConnection } from './connection';
+import { HubError, SAVE_UNKNOWN_CODE } from './errors';
+import { toGameData, toStoredJson, type GamePayload } from './game-data';
+import { PROGRESS_KINDS, type ProfilePayload, type ScorePayload } from './offline/hub-kinds';
+import { pageAccount, toPageUser } from './page-account';
+import { isRecord } from './storage/json-guards';
+import type { LeaderboardResult, MeResponse, Profile, Save, SaveMeta, SubmitScoreOptions, SubmitScoreResult, User } from './types';
+
+/** A signed-in user, as the auth calls answer. */
+export interface AuthResponse {
+  /** The signed-in user. */
+  readonly user: User;
+}
+
+/** A stat's new value, as the stat calls answer. */
+export interface StatResult {
+  /** The stat key. */
+  readonly key: string;
+  /** Its value after the update. */
+  readonly value: number;
+}
+
+/** A profile change with the game's own data typed as `TData`. */
+export interface ProfileUpdate<TData extends GamePayload = Json> {
+  /** Shown to other players; `null` clears it. */
+  readonly displayName?: string | null;
+  /** The game's own profile data. */
+  readonly data?: TData;
+}
+
+/** A profile with the game's own data typed as `TData`. */
+function typedProfile<TData>(profile: Profile | null): Profile<TData> | null {
+  return profile === null ? null : { ...profile, data: toGameData<TData>(profile.data) };
+}
+
+/** A save with the game's own data typed as `TData`. */
+function typedSave<TData>(save: Save | null): Save<TData> | null {
+  return save === null ? null : { ...save, data: toGameData<TData>(save.data) };
+}
+
+/** Accounts, profile, saves, stats and leaderboards. */
+export class HubProgress extends HubConnection {
+  /** Who the page is signed in as, as the hub's events and this client's sign-ins tell it. */
+  protected readonly account = pageAccount();
+
+  /**
+   * Your user id, or `null` when nobody is signed in (also before an offline
+   * first visit has an account). Synchronous, and it follows the account as
+   * the hub changes it (a new guest's account made by the menu, sign-in,
+   * sign-out) with no `hub.me()` needed. Compare it with a seat's `userId`
+   * to find yours.
+   */
+  userId(): number | null {
+    const heard = this.account.user;
+    const id = heard === undefined ? this.store.getUser()?.id ?? null : heard?.id ?? null;
+    // 0 is an offline local guest: no account on the hub yet.
+    return id === 0 ? null : id;
+  }
+
+  /** The current user (or `null`) and the games they have a profile in. */
+  me(): Promise<MeResponse> {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('getCurrentUser');
+      this.account.note(reply.user === null ? null : toPageUser(reply.user));
+      return reply;
+    }, () => {
+      const profile = this.store.getProfile();
+      return { user: this.store.getUser(), profiles: profile === null ? [] : [{ game: profile.game, displayName: profile.displayName }] };
+    });
+  }
+
+  /**
+   * Make sure a session exists, creating a guest (a random name, no
+   * password) when the player isn't signed in, so progress saves without a
+   * sign-in. Idempotent. Offline, a local guest is used.
+   */
+  ensureGuest(): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('ensureGuestSession')), () => {
+      const known = this.store.getUser();
+      if (known !== null) {
+        return { user: known };
+      }
+      return this.signInLocally({ id: 0, username: 'Guest-local', guest: true });
+    });
+  }
+
+  /**
+   * Turn the current guest into a registered account (the same identity, so
+   * all progress carries over). Rejects with 409 when already registered or
+   * the name is taken; the player should `login` instead.
+   */
+  claim(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('claimGuestAccount', { username, password })), () => this.signInLocally({ id: 0, username, guest: false }));
+  }
+
+  /** Create an account and sign in. (Offline: a local user is stored.) */
+  signup(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('signUpWithPassword', { username, password })), () => this.signInLocally({ id: 0, username }));
+  }
+
+  /** Sign in. (Offline: a local user is stored so signed-in flows work.) */
+  login(username: string, password: string): Promise<AuthResponse> {
+    return this.withFallback<AuthResponse>(async () => this.signedIn(await this.rest.call('logInWithPassword', { username, password })), () => this.signInLocally({ id: 0, username }));
+  }
+
+  /** Sign out (ends the session shared by every game). */
+  logout(): Promise<{ ok: true }> {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('logOut');
+      this.signedOut();
+      return reply;
+    }, () => {
+      this.signedOut();
+      return { ok: true } as const;
+    });
+  }
+
+  private signInLocally(user: User): AuthResponse {
+    this.remember(user);
+    return { user };
+  }
+
+  /** Remember who the hub signed in, so the cache's notes about the hub's copies are read for the right player. */
+  private signedIn(reply: AuthResponse): AuthResponse {
+    this.remember(reply.user);
+    return reply;
+  }
+
+  /** The cache and the page (`hub.userId()`, `hub.avatar`) learn who is signed in. */
+  private remember(user: User): void {
+    this.store.setUser(user);
+    this.account.note(toPageUser(user));
+  }
+
+  private signedOut(): void {
+    this.store.clearUser();
+    this.account.note(null);
+  }
+
+  /** This game's profile for the current user, or `profile: null`. `TData` is the game's own data type. */
+  getProfile<TData = Json>(): Promise<{ profile: Profile<TData> | null }> {
+    return this.withFallback(
+      async () => ({ profile: typedProfile<TData>((await this.rest.call('getGameProfile', this.gameFields())).profile) }),
+      () => ({ profile: typedProfile<TData>(this.store.getProfile()) }),
+    );
+  }
+
+  /** Create or update this game's profile for the current user. */
+  setProfile<TData extends GamePayload = Json>(patch: ProfileUpdate<TData>): Promise<{ profile: Profile<TData> }> {
+    const queued: ProfilePayload = {
+      ...(patch.displayName === undefined ? {} : { displayName: patch.displayName }),
+      ...(patch.data === undefined ? {} : { data: toStoredJson(patch.data) }),
+    };
+    return this.mutateOffline(PROGRESS_KINDS.profile, queued, () => {
+      const stored = this.store.setProfile(this.slug ?? 'app', patch.displayName ?? null, queued.data ?? {});
+      return { profile: { ...stored, data: toGameData<TData>(stored.data) } };
+    });
+  }
+
+  /** Metadata for every save slot (no payloads), newest first. */
+  listSaves(): Promise<{ saves: SaveMeta[] }> {
+    return this.withFallback(() => this.rest.call('listSaves', this.gameFields()), () => ({ saves: this.store.listSaves() }));
+  }
+
+  /**
+   * One slot's contents, or `save: null` when the slot is empty. `TData` is
+   * the game's own save type. Offline it answers from the device's copy, but
+   * only when the device knows the hub's copy of the slot; otherwise (a fresh
+   * device or cleared browser) it rejects with a {@link HubError} whose
+   * `code` is `save_unknown` (`isOffline` is `true`), never a false "empty".
+   */
+  getSave<TData = Json>(slot: string): Promise<{ save: Save<TData> | null }> {
+    return this.withFallback(
+      async () => {
+        const { save } = await this.rest.call('getSave', { ...this.gameFields(), slot });
+        if (this.outbox.count() === 0) {
+          this.store.cacheCloudSave(slot, save);
+        }
+        return { save: typedSave<TData>(save) };
+      },
+      () => ({ save: typedSave<TData>(this.offlineSave(slot)) }),
+    );
+  }
+
+  /** The device's copy of `slot`, when it can be trusted offline (see {@link getSave}). */
+  private offlineSave(slot: string): Save | null {
+    // Trusted: a slot whose hub copy the device has seen, a slot it wrote itself and hasn't sent
+    // yet, or any slot of a player signed in only on this device (offline, never reached the hub).
+    const isLocalOnly = this.store.getUser()?.id === 0;
+    const hasQueuedWrite = this.outbox.pending().some((op) => op.kind === PROGRESS_KINDS.save && isRecord(op.payload) && op.payload.slot === slot);
+    if (!isLocalOnly && !hasQueuedWrite && this.store.cloudSave(slot) === undefined) {
+      throw new HubError(`Hub: offline, and this device hasn't seen save "${slot}" yet.`, undefined, { code: SAVE_UNKNOWN_CODE });
+    }
+    return this.store.getSave(slot);
+  }
+
+  /** Create or overwrite a save slot. `saveData` is any JSON up to 64 KB. */
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- kept so v1 calls such as putSave<MySave>(...) still compile
+  putSave<TData extends GamePayload = Json>(slot: string, saveData: TData, label?: string): Promise<{ ok: true; updatedAt: number }> {
+    const stored = toStoredJson(saveData);
+    return this.mutateOffline(PROGRESS_KINDS.save, { slot, data: stored, label: label ?? null }, () => ({ ok: true as const, updatedAt: this.store.putSave(slot, stored, label ?? null) }));
+  }
+
+  /** Delete a save slot. */
+  deleteSave(slot: string): Promise<{ ok: true }> {
+    return this.mutateOffline(PROGRESS_KINDS.save, { slot, deleted: true }, () => {
+      this.store.deleteSave(slot);
+      return { ok: true as const };
+    });
+  }
+
+  /** Numeric stats for the current user, or another player's via `userId`. */
+  getStats(userId?: number): Promise<{ stats: Stats }> {
+    return this.withFallback(
+      () => this.rest.call('getGameStats', { ...this.gameFields(), ...(userId === undefined ? {} : { user: userId }) }),
+      () => ({ stats: this.store.getStats() }),
+    );
+  }
+
+  /** Overwrite a stat. */
+  setStat(key: string, value: number): Promise<StatResult> {
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'set', value }, () => ({ key, value: this.store.updateStat(key, value, 'set') }));
+  }
+
+  /** Add to a stat (creating it at `amount` when absent). */
+  incrStat(key: string, amount = 1): Promise<StatResult> {
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'incr', value: amount }, () => ({ key, value: this.store.updateStat(key, amount, 'incr') }));
+  }
+
+  /** Keep the larger of the stored and the given value. */
+  maxStat(key: string, value: number): Promise<StatResult> {
+    return this.mutateOffline(PROGRESS_KINDS.stat, { key, mode: 'max', value }, () => ({ key, value: this.store.updateStat(key, value, 'max') }));
+  }
+
+  /** Submit a score. The board is created on first use; only a player's best score sticks. */
+  submitScore<TMeta extends GamePayload = Json>(boardKey: string, score: number, opts: SubmitScoreOptions<TMeta> = {}): Promise<SubmitScoreResult> {
+    const queued: ScorePayload['opts'] = {
+      ...(opts.title === undefined ? {} : { title: opts.title }),
+      ...(opts.sort === undefined ? {} : { sort: opts.sort }),
+      ...(opts.meta === undefined ? {} : { meta: toStoredJson(opts.meta) }),
+    };
+    return this.mutateOffline(PROGRESS_KINDS.score, { key: boardKey, score, opts: queued }, () => ({ ...this.store.submitScore(boardKey, score, queued), rank: 1 }));
+  }
+
+  /** One board's ranked entries (top `limit`, default 50). Offline: only the player's own best. */
+  getLeaderboard(boardKey: string, limit = 50): Promise<LeaderboardResult> {
+    return this.withFallback(() => this.rest.call('getLeaderboard', { ...this.gameFields(), key: boardKey, limit }), () => {
+      const local = this.store.getBoard(boardKey);
+      if (local === null) {
+        return { board: { key: boardKey, title: boardKey, sortDir: 'desc' }, entries: [] };
+      }
+      const user = this.store.getUser();
+      return { board: local.board, entries: [{ rank: 1, userId: user?.id ?? 0, username: user?.username ?? 'you', score: local.best, meta: null }] };
+    });
+  }
+
+  /** The boards this game owns (keys and titles, no entries). */
+  listLeaderboards(): Promise<{ boards: Board[] }> {
+    return this.withFallback(() => this.rest.call('listGameLeaderboards', this.gameFields()), () => ({ boards: this.store.listBoards() }));
+  }
+
+}