@diffenderfer-games/hub 2.0.0-next.1 → 2.0.0-next.11

package/src/core/offline/hub-kinds/daily-kind.ts

@@ -0,0 +1,68 @@
+/**
+ * The hub's daily kind, a composite op: complete a day with the token the
+ * game started it with; when that token has expired by the time the op
+ * replays (401), start the day again for a fresh token and complete with
+ * that. The completion is replayable, so a retry after a lost reply never
+ * records it twice. A completion sent at once (online) is reported by the
+ * daily system itself; one that replays later is reported here.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { EndpointReply } from '../../rest/endpoint-types';
+import { isJsonObject, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** One daily completion. */
+export type DailyPayload = { readonly day: string; readonly token: string; readonly meta: { readonly [key: string]: Json } };
+
+/** The kind name. */
+export const DAILY_KIND = 'hub.daily';
+
+/** What a completion answers. */
+export type DailyCompletion = EndpointReply<'completeDailyChallenge'>;
+
+function readDaily(stored: Json): DailyPayload | undefined {
+  if (!isRecord(stored) || !isJsonObject(stored.meta)) {
+    return undefined;
+  }
+  const day = optionalString(stored.day);
+  const token = optionalString(stored.token);
+  return day === undefined || token === undefined ? undefined : { day, token, meta: stored.meta };
+}
+
+/** A completion reply read back, or `undefined` when it doesn't read as one. */
+export function readDailyCompletion(result: Json | undefined): DailyCompletion | undefined {
+  if (!isRecord(result) || result.ok !== true) {
+    return undefined;
+  }
+  const day = optionalString(result.day);
+  const count = optionalNumber(result.count);
+  const rank = result.rank === null ? null : optionalNumber(result.rank);
+  return day === undefined || count === undefined || rank === undefined ? undefined : { ok: true, day, count, rank };
+}
+
+/** The daily kind, by name; `onCompleted` hears each completion that lands from the queue. */
+export function dailyKinds(game: GameFieldsSource, onCompleted: (payload: DailyPayload, completion: DailyCompletion) => void): Record<string, RegisteredKind> {
+  return {
+    [DAILY_KIND]: checkedKind(readDaily, {
+      run: async ({ day, token, meta }, context) => {
+        let completion: DailyCompletion;
+        try {
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token, meta });
+        } catch (failure) {
+          if (!(failure instanceof HubError) || failure.status !== 401) {
+            throw failure;
+          }
+          const started = await context.call('startDailyChallenge', { ...game(), day });
+          completion = await context.call('completeDailyChallenge', { ...game(), day, token: started.token, meta });
+        }
+        if (context.isReplay) {
+          onCompleted({ day, token, meta }, completion);
+        }
+        return completion;
+      },
+    }),
+  };
+}

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

@@ -0,0 +1,86 @@
+/**
+ * The hub's economy and catalog kinds: inventory grants and house
+ * exchanges (each one replayable call, never folded: every grant counts),
+ * and starring a game (a game's last star or unstar wins).
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { GoodsPayload } from '../local-inventory';
+import type { RegisteredKind } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** A house exchange: what the player gives up and gets. */
+export type ExchangePayload = { readonly take?: GoodsPayload; readonly give?: GoodsPayload };
+
+/** A star or unstar. */
+export type FavoritePayload = { readonly slug: string; readonly on: boolean };
+
+/** The kind names. */
+export const ECONOMY_KINDS = { grant: 'hub.grant', exchange: 'hub.exchange', favorite: 'hub.favorite' } as const;
+
+/** Goods read back, or `undefined` when malformed. */
+export function readGoods(stored: Json | undefined): GoodsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const coins = stored.coins === undefined ? undefined : optionalNumber(stored.coins);
+  if (stored.coins !== undefined && coins === undefined) {
+    return undefined;
+  }
+  const items: Record<string, number> = {};
+  if (stored.items !== undefined) {
+    if (!isRecord(stored.items)) {
+      return undefined;
+    }
+    for (const [key, qty] of Object.entries(stored.items)) {
+      const count = optionalNumber(qty);
+      if (count === undefined) {
+        return undefined;
+      }
+      items[key] = count;
+    }
+  }
+  return { ...(stored.items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+function readExchange(stored: Json): ExchangePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const take = stored.take === undefined ? undefined : readGoods(stored.take);
+  const give = stored.give === undefined ? undefined : readGoods(stored.give);
+  if ((stored.take !== undefined && take === undefined) || (stored.give !== undefined && give === undefined)) {
+    return undefined;
+  }
+  return { ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) };
+}
+
+function readFavorite(stored: Json): FavoritePayload | undefined {
+  if (!isRecord(stored) || typeof stored.on !== 'boolean') {
+    return undefined;
+  }
+  const slug = optionalString(stored.slug);
+  return slug === undefined ? undefined : { slug, on: stored.on };
+}
+
+/** The economy kinds, by name; `onFavorites` hears the starred list each star answers with. */
+export function economyKinds(game: GameFieldsSource, onFavorites: (games: string[]) => void): Record<string, RegisteredKind> {
+  return {
+    [ECONOMY_KINDS.grant]: checkedKind(readGoods, {
+      run: (goods, context) => context.call('grantInventoryItems', { ...game(), ...goods }),
+    }),
+    [ECONOMY_KINDS.exchange]: checkedKind(readExchange, {
+      run: (exchange, context) => context.call('exchangeInventoryItems', { ...game(), ...exchange }),
+    }),
+    [ECONOMY_KINDS.favorite]: checkedKind(readFavorite, {
+      mergeKey: (favorite) => favorite.slug,
+      replaces: true,
+      run: async (favorite, context) => {
+        const reply = await context.call('setGameFavorite', { slug: favorite.slug, on: favorite.on });
+        onFavorites(reply.games);
+        return reply;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/game-fields.ts

@@ -0,0 +1,2 @@
+/** The `{ slug }` path field the hub kinds' calls need, read when they run (it throws when the slug is unknown). */
+export type GameFieldsSource = () => { readonly slug: string };

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

@@ -0,0 +1,52 @@
+/**
+ * Every kind the hub itself queues offline (`hub.*`), registered on a
+ * client's outbox. The docs' "Offline and replay" table lists them.
+ */
+import type { LocalResumeStore } from '../../resume/local-resume';
+import type { LocalDailyStore } from '../../saved/local-saved';
+import { writeLocalFavorites } from '../favorites';
+import type { Outbox } from '../outbox';
+import { avatarKinds } from './avatar-kind';
+import { dailyKinds, type DailyCompletion, type DailyPayload } from './daily-kind';
+import { economyKinds } from './economy-kinds';
+import type { GameFieldsSource } from './game-fields';
+import { progressKinds, type CloudSaveTracker } from './progress-kinds';
+import { resumeKinds } from './resume-kind';
+import { savedKinds } from './saved-kind';
+
+export { AVATAR_KIND, type AvatarPayload } from './avatar-kind';
+export { DAILY_KIND, type DailyPayload } from './daily-kind';
+export { ECONOMY_KINDS, type ExchangePayload, type FavoritePayload } from './economy-kinds';
+export { legacyOperation } from './legacy-ops';
+export { RESUME_KIND, type ResumePayload } from './resume-kind';
+export { SAVED_KIND, type SavedPayload } from './saved-kind';
+export { PROGRESS_KINDS, type CloudSaveTracker, type ProfilePayload, type SavePayload, type ScorePayload, type StatPayload } from './progress-kinds';
+
+/** What the hub kinds report back to their client. */
+export interface HubKindHooks {
+  /** This game's `{ slug }`. */
+  readonly game: GameFieldsSource;
+  /** A daily completion landed (the menu's calendar listens for `hub:daily-complete`). */
+  readonly onDailyComplete: (payload: DailyPayload, completion: DailyCompletion) => void;
+  /** The device copies of each game's resume slot (`hub.resume`). */
+  readonly resume: LocalResumeStore;
+  /** The device copies of daily challenges in progress (`hub.saved`). */
+  readonly dailies: LocalDailyStore;
+  /** What this device last saw of the game's save slots on the hub. */
+  readonly cloudSaves: CloudSaveTracker;
+}
+
+/** Register every hub kind on `outbox`. */
+export function registerHubKinds(outbox: Outbox, hooks: HubKindHooks): void {
+  const kinds = {
+    ...progressKinds(hooks.game, hooks.cloudSaves),
+    ...dailyKinds(hooks.game, hooks.onDailyComplete),
+    ...economyKinds(hooks.game, writeLocalFavorites),
+    ...resumeKinds(hooks.game, hooks.resume),
+    ...avatarKinds(),
+    ...savedKinds(hooks.dailies),
+  };
+  for (const [kind, definition] of Object.entries(kinds)) {
+    outbox.define(kind, definition);
+  }
+}

package/src/core/offline/hub-kinds/legacy-ops.ts

@@ -0,0 +1,37 @@
+/**
+ * The v1 client's queued writes (`hub:<slug>:queue`) as outbox operations,
+ * so a page upgraded from a vendored copy still replays what that copy queued.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import type { QueueOp } from '../queue';
+import { PROGRESS_KINDS, readProfile, readScoreOptions } from './progress-kinds';
+
+/** One outbox operation, before it is stamped. */
+export interface KindedPayload {
+  readonly kind: string;
+  readonly payload: Json;
+}
+
+/** The outbox operation for a v1 queued write, or `undefined` when it no longer reads as one. */
+export function legacyOperation(op: QueueOp): KindedPayload | undefined {
+  switch (op.kind) {
+    case 'putSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, data: op.data, label: op.label } };
+    case 'deleteSave':
+      return { kind: PROGRESS_KINDS.save, payload: { slot: op.slot, deleted: true } };
+    case 'setStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'set', value: op.value } };
+    case 'maxStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'max', value: op.value } };
+    case 'incrStat':
+      return { kind: PROGRESS_KINDS.stat, payload: { key: op.key, mode: 'incr', value: op.amount } };
+    case 'submitScore': {
+      const opts = readScoreOptions({ ...op.opts });
+      return opts === undefined ? undefined : { kind: PROGRESS_KINDS.score, payload: { key: op.key, score: op.score, opts } };
+    }
+    case 'setProfile': {
+      const patch = readProfile({ ...op.patch });
+      return patch === undefined ? undefined : { kind: PROGRESS_KINDS.profile, payload: patch };
+    }
+  }
+}

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

@@ -0,0 +1,165 @@
+/**
+ * The hub's progress kinds: saves, stats, scores and the game profile. Each
+ * is one replayable call, and each folds new writes into waiting ones so the
+ * backlog stays small: a save slot's last write wins, `incr`s add up, `max`es
+ * keep the largest, `set`s keep the last, a board keeps its best, and profile
+ * patches merge.
+ */
+import type { Json, SortDir } from '@diffenderfer-games/hub-contract';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+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 }
+  | { readonly slot: string; readonly deleted: true };
+
+/** How a stat update combines with the stored value. */
+export type StatMode = 'set' | 'incr' | 'max';
+
+/** One stat update. */
+export type StatPayload = { readonly key: string; readonly mode: StatMode; readonly value: number };
+
+/** A score's board options, as queued. */
+export type ScoreOptionsPayload = { readonly title?: string; readonly sort?: SortDir; readonly meta?: Json };
+
+/** One score submission. */
+export type ScorePayload = { readonly key: string; readonly score: number; readonly opts: ScoreOptionsPayload };
+
+/** A profile change; either part may be left out. */
+export type ProfilePayload = { readonly displayName?: string | null; readonly data?: Json };
+
+/** The kind names. */
+export const PROGRESS_KINDS = { save: 'hub.save', stat: 'hub.stat', score: 'hub.score', profile: 'hub.profile' } as const;
+
+function readSave(stored: Json): SavePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const slot = optionalString(stored.slot);
+  if (slot === undefined) {
+    return undefined;
+  }
+  if (stored.deleted === true) {
+    return { slot, deleted: true };
+  }
+  return isJson(stored.data) && isNullableString(stored.label) ? { slot, data: stored.data, label: stored.label } : undefined;
+}
+
+function readStat(stored: Json): StatPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const value = optionalNumber(stored.value);
+  const mode = stored.mode === 'set' || stored.mode === 'incr' || stored.mode === 'max' ? stored.mode : undefined;
+  return key === undefined || value === undefined || mode === undefined ? undefined : { key, mode, value };
+}
+
+/** Score options read back, or `undefined` when malformed. */
+export function readScoreOptions(stored: Json): ScoreOptionsPayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const title = optionalString(stored.title);
+  const sort = stored.sort === 'asc' || stored.sort === 'desc' ? stored.sort : undefined;
+  if (stored.meta !== undefined && !isJson(stored.meta)) {
+    return undefined;
+  }
+  return { ...(title === undefined ? {} : { title }), ...(sort === undefined ? {} : { sort }), ...(stored.meta === undefined ? {} : { meta: stored.meta }) };
+}
+
+function readScore(stored: Json): ScorePayload | undefined {
+  if (!isRecord(stored) || !isJson(stored.opts)) {
+    return undefined;
+  }
+  const key = optionalString(stored.key);
+  const score = optionalNumber(stored.score);
+  const opts = readScoreOptions(stored.opts);
+  return key === undefined || score === undefined || opts === undefined ? undefined : { key, score, opts };
+}
+
+/** A profile patch read back, or `undefined` when malformed. */
+export function readProfile(stored: Json): ProfilePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  const { displayName, data: profileData } = stored;
+  if ((displayName !== undefined && !isNullableString(displayName)) || (profileData !== undefined && !isJson(profileData))) {
+    return undefined;
+  }
+  return { ...(displayName === undefined ? {} : { displayName }), ...(profileData === undefined ? {} : { data: profileData }) };
+}
+
+/** Two waiting stat updates of one key folded together, or `undefined` when their modes differ. */
+export function mergeStats(waiting: StatPayload, incoming: StatPayload): StatPayload | undefined {
+  if (waiting.mode !== incoming.mode) {
+    return undefined;
+  }
+  switch (incoming.mode) {
+    case 'incr':
+      return { ...waiting, value: waiting.value + incoming.value };
+    case 'max':
+      return { ...waiting, value: Math.max(waiting.value, incoming.value) };
+    case 'set':
+      return incoming;
+  }
+}
+
+/**
+ * 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,
+      replaces: true,
+      run: async (save, context) => {
+        if ('deleted' in save) {
+          await context.call('deleteSave', { ...game(), slot: save.slot });
+          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, {
+      mergeKey: (stat) => stat.key,
+      merge: mergeStats,
+      run: async (stat, context) => {
+        await context.call('updateGameStat', { ...game(), key: stat.key, value: stat.value, mode: stat.mode });
+      },
+    }),
+    [PROGRESS_KINDS.score]: checkedKind(readScore, {
+      mergeKey: (submission) => submission.key,
+      merge: (waiting, incoming) => ({ ...waiting, score: betterScore(waiting.score, incoming.score, incoming.opts.sort), opts: incoming.opts }),
+      run: async (submission, context) => {
+        await context.call('submitScore', { ...game(), key: submission.key, score: submission.score, ...submission.opts });
+      },
+    }),
+    [PROGRESS_KINDS.profile]: checkedKind(readProfile, {
+      mergeKey: () => 'profile',
+      merge: (waiting, incoming) => ({ ...waiting, ...incoming }),
+      run: async (patch, context) => {
+        await context.call('setGameProfile', { ...game(), ...patch });
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/resume-kind.ts

@@ -0,0 +1,108 @@
+/**
+ * The hub's resume kind (`hub.resume`): send a game's saved run, or clear it.
+ * One slot per game, so a new op replaces any waiting one (a clear after a
+ * save drops the save, and the other way round).
+ *
+ * A save op carries only the run's facts and time: when it runs it sends
+ * the newest run in the device copy (`LocalResumeStore`), which keeps the
+ * outbox small. When the device copy couldn't be stored, the op carries the
+ * state itself. A session that lapsed (401) gets a guest session and tries
+ * once more, so a player's very first save can't be lost to it.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalResumeStore } from '../../resume/local-resume';
+import { isJson, isNullableString, isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+import type { GameFieldsSource } from './game-fields';
+
+/** The kind name. */
+export const RESUME_KIND = 'hub.resume';
+
+/** Send the run saved at `savedAt`; `state` only when the device copy couldn't hold it. */
+export type ResumeSavePayload = {
+  readonly action: 'save';
+  readonly savedAt: number;
+  readonly label: string;
+  readonly fraction: number | null;
+  readonly title: string | null;
+  readonly version: number;
+  readonly state?: Json;
+};
+
+/** Clear the run, unless one was saved after `before`. */
+export type ResumeClearPayload = { readonly action: 'clear'; readonly before: number };
+
+/** One resume op. */
+export type ResumePayload = ResumeSavePayload | ResumeClearPayload;
+
+function readResume(stored: Json): ResumePayload | undefined {
+  if (!isRecord(stored)) {
+    return undefined;
+  }
+  if (stored.action === 'clear') {
+    const before = optionalNumber(stored.before);
+    return before === undefined ? undefined : { action: 'clear', before };
+  }
+  const savedAt = optionalNumber(stored.savedAt);
+  const label = optionalString(stored.label);
+  const version = optionalNumber(stored.version);
+  const fraction = stored.fraction === null ? null : optionalNumber(stored.fraction);
+  if (stored.action !== 'save' || savedAt === undefined || label === undefined || version === undefined || fraction === undefined
+    || !isNullableString(stored.title) || (stored.state !== undefined && !isJson(stored.state))) {
+    return undefined;
+  }
+  const base = { action: 'save', savedAt, label, fraction, title: stored.title, version } as const;
+  return stored.state === undefined ? base : { ...base, state: stored.state };
+}
+
+/** The run to send: the device copy when it is at least as new as the op, else the op's own state; `undefined` when there is none. */
+function runToSend(save: ResumeSavePayload, local: LocalResumeStore, slug: string): ResumeSavePayload | undefined {
+  const copy = local.read(slug);
+  if (copy?.status === 'saved' && copy.at >= save.savedAt) {
+    return { action: 'save', savedAt: copy.at, label: copy.label, fraction: copy.fraction, title: copy.title, version: copy.version, state: copy.state };
+  }
+  return save.state === undefined ? undefined : save;
+}
+
+/** Run `call`; on a lapsed session (401) start a guest session and run it once more. */
+async function withSession<Reply>(context: ReplayContext, call: () => Promise<Reply>): Promise<Reply> {
+  try {
+    return await call();
+  } catch (failure) {
+    if (!(failure instanceof HubError) || failure.status !== 401) {
+      throw failure;
+    }
+    await context.call('ensureGuestSession');
+    return call();
+  }
+}
+
+/** The resume kind, by name, over the device copies in `local`. */
+export function resumeKinds(game: GameFieldsSource, local: LocalResumeStore): Record<string, RegisteredKind> {
+  return {
+    [RESUME_KIND]: checkedKind(readResume, {
+      mergeKey: () => 'resume',
+      replaces: true,
+      run: async (op, context) => {
+        const { slug } = game();
+        if (op.action === 'clear') {
+          await withSession(context, () => context.call('clearResumeSlot', { slug, before: op.before }));
+          local.markSynced(slug, op.before);
+          return undefined;
+        }
+        const run = runToSend(op, local, slug);
+        if (run?.state === undefined) {
+          return undefined;
+        }
+        const { state } = run;
+        await withSession(context, () => context.call('saveResumeSlot', {
+          slug, state, progress: { label: run.label, fraction: run.fraction }, title: run.title, version: run.version, savedAt: run.savedAt,
+        }));
+        local.markSynced(slug, run.savedAt);
+        return undefined;
+      },
+    }),
+  };
+}

package/src/core/offline/hub-kinds/saved-kind.ts

@@ -0,0 +1,93 @@
+/**
+ * The hub's saved-games kind (`hub.saved`): send a daily challenge's state,
+ * or discard the day, from the device copy (`LocalDailyStore`). One op per
+ * (game, day): a newer one replaces a waiting one, so a discard after a
+ * save drops the save. The op carries only which day and when; when it runs
+ * it sends the newest state the device holds, so the outbox stays small.
+ *
+ * A day started offline has a device-only id (`local:<slug>:<day>`): the op
+ * first starts the day on the hub, which finds or makes its saved game (one
+ * per player, game and day), then saves to that. A save or discard that
+ * finds the day already finished or discarded elsewhere (409, 404) is done:
+ * the device copy is dropped.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubError } from '../../errors';
+import type { LocalDaily, LocalDailyStore } from '../../saved/local-saved';
+import { isRecord, optionalNumber, optionalString } from '../../storage/json-guards';
+import { checkedKind } from '../kind-adapters';
+import type { RegisteredKind, ReplayContext } from '../outbox-kinds';
+
+/** The kind name. */
+export const SAVED_KIND = 'hub.saved';
+
+/** Send (`save`) or discard a day's saved game; `at` is when the device copy changed. */
+export type SavedPayload = { readonly action: 'save' | 'discard'; readonly game: string; readonly day: string; readonly at: number };
+
+function readSaved(stored: Json): SavedPayload | undefined {
+  if (!isRecord(stored) || (stored.action !== 'save' && stored.action !== 'discard')) {
+    return undefined;
+  }
+  const game = optionalString(stored.game);
+  const day = optionalString(stored.day);
+  const at = optionalNumber(stored.at);
+  return game === undefined || day === undefined || at === undefined ? undefined : { action: stored.action, game, day, at };
+}
+
+/** Whether a failure means the instance is gone or closed on the hub (the change is moot). */
+function isGoneOrClosed(failure: Error): boolean {
+  return failure instanceof HubError && (failure.status === 404 || failure.status === 409);
+}
+
+/** The hub's id for the copy's day: its own, or the one the hub gives the day when it was started offline (`null`: already completed). */
+async function resolveId(copy: LocalDaily, context: ReplayContext): Promise<string | null> {
+  if (!copy.id.startsWith('local:')) {
+    return copy.id;
+  }
+  const started = await context.call('startDailyChallenge', { slug: copy.game, day: copy.day });
+  return started.instanceId;
+}
+
+/** Run one op against the copy it names. */
+async function runSaved(op: SavedPayload, local: LocalDailyStore, context: ReplayContext): Promise<undefined> {
+  const copy = local.read(op.game, op.day);
+  if (copy === null) {
+    return undefined;
+  }
+  try {
+    const id = await resolveId(copy, context);
+    if (id === null) {
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    if (op.action === 'discard') {
+      await context.call('discardSavedGame', { id });
+      local.remove(op.game, op.day);
+      return undefined;
+    }
+    // A null state is sent too: it is hub.resume.clear() during the day (start over from the seed).
+    if (copy.status === 'active') {
+      await context.call('saveSavedGameState', {
+        id, state: copy.state, progress: { label: copy.label, fraction: copy.fraction }, title: copy.title, version: copy.version, savedAt: copy.at,
+      });
+    }
+    local.markSynced(op.game, op.day, copy.at, id);
+  } catch (failure) {
+    if (!(failure instanceof Error) || !isGoneOrClosed(failure)) {
+      throw failure;
+    }
+    local.remove(op.game, op.day);
+  }
+  return undefined;
+}
+
+/** The saved-games kind, by name, over the device copies in `local`. */
+export function savedKinds(local: LocalDailyStore): Record<string, RegisteredKind> {
+  return {
+    [SAVED_KIND]: checkedKind(readSaved, {
+      mergeKey: (op) => `daily:${op.game}#${op.day}`,
+      replaces: true,
+      run: (op, context) => runSaved(op, local, context),
+    }),
+  };
+}

package/src/core/offline/kind-adapters.ts

@@ -0,0 +1,48 @@
+/**
+ * Turning a typed kind definition into the JSON-in, JSON-out form the outbox
+ * runs: the hub's kinds check their stored payloads with a reader; a game's
+ * kinds vouch for their own payload type, as with saves.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { toGameData, toStoredJson, type GamePayload } from '../game-data';
+import type { OfflineHandler, OfflineKindDefinition, RegisteredKind } from './outbox-kinds';
+
+/** Reads a stored payload back, or `undefined` when it is malformed. */
+export type PayloadReader<Payload> = (stored: Json) => Payload | undefined;
+
+/** A kind whose payloads are checked by `read` (the hub's own kinds). */
+export function checkedKind<Payload extends Json>(read: PayloadReader<Payload>, definition: OfflineKindDefinition<Payload>): RegisteredKind {
+  const readOrThrow = (stored: Json): Payload => {
+    const payload = read(stored);
+    if (payload === undefined) {
+      throw new Error('Malformed offline operation payload.');
+    }
+    return payload;
+  };
+  const { mergeKey, merge } = definition;
+  return {
+    run: (stored, context) => definition.run(readOrThrow(stored), context),
+    accepts: (stored) => read(stored) !== undefined,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(readOrThrow(stored)) }),
+    ...(merge === undefined ? {} : { merge: (waiting: Json, incoming: Json) => merge(readOrThrow(waiting), readOrThrow(incoming)) }),
+    replaces: definition.replaces === true,
+  };
+}
+
+/** A game's kind: a bare handler or a full definition, its payload typed by the game. */
+export function gameKind<Payload extends GamePayload>(definition: OfflineHandler<Payload> | OfflineKindDefinition<Payload>): RegisteredKind {
+  const full: OfflineKindDefinition<Payload> = typeof definition === 'function' ? { run: definition } : definition;
+  const { mergeKey, merge } = full;
+  return {
+    run: (stored, context) => full.run(toGameData<Payload>(stored), context),
+    accepts: () => true,
+    ...(mergeKey === undefined ? {} : { mergeKey: (stored: Json) => mergeKey(toGameData<Payload>(stored)) }),
+    ...(merge === undefined ? {} : {
+      merge: (waiting: Json, incoming: Json) => {
+        const merged = merge(toGameData<Payload>(waiting), toGameData<Payload>(incoming));
+        return merged === undefined ? undefined : toStoredJson(merged);
+      },
+    }),
+    replaces: full.replaces === true,
+  };
+}