@diffenderfer-games/hub 2.0.0-next.4 → 2.0.0-next.5

package/src/core/offline/hub-kinds/progress-kinds.ts

@@ -12,6 +12,14 @@ import type { RegisteredKind } from '../outbox-kinds';
 import { betterScore } from '../queue';
 import type { GameFieldsSource } from './game-fields';
 
+/** What the save kind reads and records about the hub's copy of a slot (`LocalStore`). */
+export interface CloudSaveTracker {
+  /** The hub's `updatedAt` for `slot` as this device last saw it (`null`: empty), or `undefined` when it doesn't know. */
+  cloudSave(slot: string): number | null | undefined;
+  /** Note the hub's copy of `slot` after a write landed: its `updatedAt`, or `null` once deleted. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void;
+}
+
 /** A save slot write: new contents, or a delete. */
 export type SavePayload =
   | { readonly slot: string; readonly data: Json; readonly label: string | null }
@@ -109,8 +117,14 @@ export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPay
   }
 }
 
-/** The progress kinds, by name. */
-export function progressKinds(game: GameFieldsSource): Record<string, RegisteredKind> {
+/**
+ * The progress kinds, by name. A save write replayed from the queue sends
+ * the hub's `updatedAt` this device last saw for the slot (`null` when it
+ * saw it empty or never saw it), so the hub refuses it (409 `save_conflict`,
+ * dropped and reported as a conflict) when another device saved since. A
+ * write sent at once, online, always lands, as before.
+ */
+export function progressKinds(game: GameFieldsSource, cloudSaves: CloudSaveTracker): Record<string, RegisteredKind> {
   return {
     [PROGRESS_KINDS.save]: checkedKind(readSave, {
       mergeKey: (save) => save.slot,
@@ -118,9 +132,12 @@ export function progressKinds(game: GameFieldsSource): Record<string, Registered
       run: async (save, context) => {
         if ('deleted' in save) {
           await context.call('deleteSave', { ...game(), slot: save.slot });
-        } else {
-          await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label });
+          cloudSaves.rememberCloudSave(save.slot, null);
+          return;
         }
+        const base = context.isReplay ? { base: cloudSaves.cloudSave(save.slot) ?? null } : {};
+        const written = await context.call('writeSave', { ...game(), slot: save.slot, data: save.data, label: save.label, ...base });
+        cloudSaves.rememberCloudSave(save.slot, written.updatedAt);
       },
     }),
     [PROGRESS_KINDS.stat]: checkedKind(readStat, {

package/src/core/offline/local-store.ts

@@ -10,6 +10,7 @@ import type { Board, Inventory, Json, SortDir, Stats } from '@diffenderfer-games
 import { isJson, isNullableString, isNumberRecord, isRecord, optionalNumber, optionalString, parseJsonText } from '../storage/json-guards';
 import { createPageStore, type KeyValueStore } from '../storage/key-value';
 import type { Profile, Save, SaveMeta, SnapshotResponse, User } from '../types';
+import { cloudSaveOf, readCloudSaveIndex, withCloudSave, type CloudSaveIndex } from './cloud-saves';
 import { appendEvent, readEvents, type BufferedEvent } from './events';
 import { EMPTY_INVENTORY, readInventory } from './local-inventory';
 import { betterScore, readQueue, type QueueOp, type QueuedScoreOptions } from './queue';
@@ -159,6 +160,37 @@ export class LocalStore {
     this.store.remove(`${this.prefix}save:${slot}`);
   }
 
+  /**
+   * The hub's `updatedAt` for `slot` as the current user last saw it (`null`:
+   * the slot was empty), or `undefined` when this device doesn't know.
+   */
+  cloudSave(slot: string): number | null | undefined {
+    const user = this.getUser();
+    return user === null ? undefined : cloudSaveOf(this.readCloudSaves(this.prefix), user.id, slot);
+  }
+
+  /** Note the hub's copy of `slot` (just read or written) for the current user: its `updatedAt`, or `null` when empty. */
+  rememberCloudSave(slot: string, updatedAt: number | null): void {
+    const user = this.getUser();
+    if (user !== null) {
+      this.writeStored(`${this.prefix}cloud-saves`, withCloudSave(this.readCloudSaves(this.prefix), user.id, slot, updatedAt));
+    }
+  }
+
+  /** Cache a slot as read from the hub (forgetting it when the hub has none), and note the hub's copy. */
+  cacheCloudSave(slot: string, save: Save | null): void {
+    if (save === null) {
+      this.deleteSave(slot);
+    } else {
+      this.writeStored(`${this.prefix}save:${slot}`, save);
+    }
+    this.rememberCloudSave(slot, save?.updatedAt ?? null);
+  }
+
+  private readCloudSaves(gamePrefix: string): CloudSaveIndex | null {
+    return readCloudSaveIndex(this.readStored(`${gamePrefix}cloud-saves`));
+  }
+
   /** This game's cached stats. */
   getStats(): Stats {
     const stored = this.readStored(`${this.prefix}stats`);
@@ -232,11 +264,20 @@ export class LocalStore {
     this.setEvents(appendEvent(this.getEvents(), { type, ts: Date.now() }));
   }
 
-  /** Fan a `/me/snapshot` reply out across every game's cache keys. */
+  /**
+   * Fan a `/me/snapshot` reply out across every game's cache keys. It lists
+   * every save slot of every game the player has played, so each game's
+   * slots on the hub become known (and this game's are all empty when it
+   * isn't listed).
+   */
   hydrate(snapshot: SnapshotResponse): void {
     if (snapshot.user !== null) {
       this.writeStored(USER_KEY, snapshot.user);
     }
+    const userId = snapshot.user?.id;
+    if (userId !== undefined && !Object.keys(snapshot.games).some((slug) => `hub:${slug}:` === this.prefix)) {
+      this.writeStored(`${this.prefix}cloud-saves`, { userId, complete: true, saves: {} } satisfies CloudSaveIndex);
+    }
     for (const [slug, game] of Object.entries(snapshot.games)) {
       const gamePrefix = `hub:${slug}:`;
       if (game.profile !== null) {
@@ -245,6 +286,10 @@ export class LocalStore {
       for (const save of game.saves) {
         this.writeStored(`${gamePrefix}save:${save.slot}`, save);
       }
+      if (userId !== undefined) {
+        const saves = Object.fromEntries(game.saves.map((save) => [save.slot, save.updatedAt]));
+        this.writeStored(`${gamePrefix}cloud-saves`, { userId, complete: true, saves } satisfies CloudSaveIndex);
+      }
       this.writeStored(`${gamePrefix}stats`, game.stats);
       this.writeStored(`${gamePrefix}inventory`, game.inventory);
     }

package/src/core/version/client-version.gen.ts

@@ -1,3 +1,3 @@
 // Generated by tools/hub-client/generate.ts. Do not edit; run `npm run gen:hub-client` in next/.
 /** This client's package version, sent as `x-hub-client` on REST calls and `client` in `hello`. */
-export const HUB_CLIENT_VERSION = '2.0.0-next.4';
+export const HUB_CLIENT_VERSION = '2.0.0-next.5';

package/src/index.ts

@@ -28,6 +28,7 @@ export {
   ContentRejectedError,
   HubError,
   OfflineError,
+  SAVE_UNKNOWN_CODE,
   UNSUPPORTED_BY_HUB,
   type HubErrorCode,
   type HubErrorDetails,