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

package/src/core/hub-economy.ts

@@ -1,179 +1,216 @@
-/**
- * Analytics, the catalog, favorites, records, inventory and trades. Analytics
- * calls are fire-and-forget and never throw (telemetry must not break a game);
- * offline they are buffered and sent when the hub is back. Method names are
- * the v1 client's, unchanged.
- */
-import { HubProgress } from './hub-progress';
-import { readLocalFavorites, writeLocalFavorites } from './offline/favorites';
-import { HubError } from './errors';
-import type { EndpointFields, EndpointReply } from './rest/endpoint-types';
-import type { GameAnalytics, GameInfo, GlobalAnalytics, InventorySnapshot } from './types';
-
-/** Goods to grant: item key to quantity, and coins. */
-export type GrantBundle = Omit<EndpointFields<'grantInventoryItems'>, 'slug'>;
-
-/** Goods taken or given in an exchange or a trade. */
-export type TradeBundle = EndpointFields<'exchangeInventoryItems'>['take'];
-
-/** A trade offer's id, as a number or its text. */
-export type TradeId = number | string;
-
-/** Extras for creating or countering a trade. */
-export interface TradeNoteOptions {
-  /** A short note to the other player (moderated). */
-  readonly note?: string;
-}
-
-/** Which trades `listTrades` lists. */
-export type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
-
-/** Analytics, catalog, favorites, records, inventory and trades. */
-export class HubEconomy extends HubProgress {
-  /** Record a "play". Call once when the game starts. */
-  recordPlay(): Promise<void> {
-    return this.event('play');
-  }
-
-  /** Record a "heartbeat". Call periodically while the game is active. */
-  heartbeat(): Promise<void> {
-    return this.event('heartbeat');
-  }
-
-  /** Record a custom event. Never throws; offline, events are buffered and sent on reconnect. */
-  async event(type: string): Promise<void> {
-    if (this.slug === null) {
-      return;
-    }
-    if (this.isOffline) {
-      this.store.bufferEvent(type);
-      this.notifyStatus();
-      return;
-    }
-    try {
-      await this.rest.call('recordGameEvent', { ...this.gameFields(), type });
-    } catch (failure) {
-      if (failure instanceof HubError && failure.isOffline) {
-        this.setReachable(false);
-        this.store.bufferEvent(type);
-      }
-    }
-  }
-
-  /** This game's play counts. */
-  analytics(): Promise<GameAnalytics> {
-    return this.withFallback(() => this.rest.call('getGameAnalytics', this.gameFields()), () => ({ slug: this.slug ?? 'app', totalPlays: 0, uniquePlayers: 0, activeNow: 0 }));
-  }
-
-  /** Catalog-wide play counts with a per-game breakdown. */
-  globalAnalytics(): Promise<GlobalAnalytics> {
-    return this.withFallback(() => this.rest.call('getSiteAnalytics'), () => ({ global: { totalPlays: 0, uniquePlayers: 0, activeNow: 0 }, games: [] }));
-  }
-
-  /** The listed games, for "jump to another game" navigation. */
-  listGames(): Promise<{ games: GameInfo[] }> {
-    return this.withFallback(() => this.rest.call('listGames'), () => ({ games: [] }));
-  }
-
-  /** Every board of every game, each with its top `top` entries (default 5). */
-  allLeaderboards(top = 5): Promise<EndpointReply<'listTopOfEveryLeaderboard'>> {
-    return this.withFallback(() => this.rest.call('listTopOfEveryLeaderboard', { top }), () => ({ games: [] }));
-  }
-
-  /**
-   * The starred games (slugs), shown first in the menu's game list. Kept per
-   * account by the hub and mirrored to `localStorage`, so it shows offline.
-   */
-  favorites(): Promise<{ games: string[] }> {
-    return this.withFallback(async () => {
-      const reply = await this.rest.call('listFavoriteGames');
-      writeLocalFavorites(reply.games);
-      return reply;
-    }, () => ({ games: readLocalFavorites() }));
-  }
-
-  /** Star (`isOn = true`) or unstar a game. Needs a connection. */
-  async setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
-    const reply = await this.rest.call('setGameFavorite', { slug, on: isOn });
-    writeLocalFavorites(reply.games);
-    return reply;
-  }
-
-  /** The player's leaderboard standings, grouped by game (every game, or one via `forSlug`). Empty offline or signed out. */
-  myRecords(forSlug?: string): Promise<EndpointReply<'listMyLeaderboardRecords'>> {
-    return this.withFallback(
-      () => this.rest.call('listMyLeaderboardRecords', forSlug === undefined || forSlug === '' ? {} : { game: forSlug }),
-      () => ({ games: [] }),
-    );
-  }
-
-  /** This game's inventory and coin balance for the current user. */
-  getInventory(): Promise<InventorySnapshot> {
-    return this.withFallback(() => this.rest.call('getMyInventory', this.gameFields()), () => ({ items: [], coins: 0 }));
-  }
-
-  /** Another player's available holdings (to compose a trade). */
-  playerInventory(userId: number): Promise<InventorySnapshot> {
-    return this.withFallback(() => this.rest.call('getPlayerInventory', { ...this.gameFields(), userId }), () => ({ items: [], coins: 0 }));
-  }
-
-  /** Add goods to the player (gameplay rewards); answers the new holdings. */
-  grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>> {
-    return this.rest.call('grantInventoryItems', { ...this.gameFields(), ...bundle });
-  }
-
-  /** An atomic swap with the house: remove `take`, add `give`. */
-  exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>> {
-    return this.rest.call('exchangeInventoryItems', { ...this.gameFields(), ...(take === undefined ? {} : { take }), ...(give === undefined ? {} : { give }) });
-  }
-
-  /** Sell items to the house for coins. */
-  sell(items: Record<string, number>, coins: number): Promise<EndpointReply<'exchangeInventoryItems'>> {
-    return this.exchange({ items }, { coins });
-  }
-
-  /** Buy items from the house with coins. */
-  buy(coins: number, items: Record<string, number>): Promise<EndpointReply<'exchangeInventoryItems'>> {
-    return this.exchange({ coins }, { items });
-  }
-
-  /** Wipe the player's progress in this game (saves, stats, inventory and coins). */
-  resetGame(): Promise<{ ok: true }> {
-    return this.rest.call('resetMyGameProgress', this.gameFields());
-  }
-
-  /** Players this player can trade with in this game. */
-  listPlayers(): Promise<EndpointReply<'listTradePartners'>> {
-    return this.withFallback(() => this.rest.call('listTradePartners', this.gameFields()), () => ({ players: [] }));
-  }
-
-  /** The player's trades (`box`: `incoming` or `outgoing`; `status` filters). */
-  listTrades(opts: TradeListOptions = {}): Promise<EndpointReply<'listMyTrades'>> {
-    return this.withFallback(() => this.rest.call('listMyTrades', { ...this.gameFields(), ...opts }), () => ({ offers: [] }));
-  }
-
-  /** Offer a trade to another player (by id or name). */
-  createTrade(toUser: number | string, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'createTrade'>> {
-    return this.rest.call('createTrade', { ...this.gameFields(), toUser: String(toUser), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
-  }
-
-  /** Accept a trade offered to the player. */
-  acceptTrade(id: TradeId): Promise<EndpointReply<'acceptTrade'>> {
-    return this.rest.call('acceptTrade', { ...this.gameFields(), id: Number(id) });
-  }
-
-  /** Decline a trade offered to the player. */
-  declineTrade(id: TradeId): Promise<EndpointReply<'declineTrade'>> {
-    return this.rest.call('declineTrade', { ...this.gameFields(), id: Number(id) });
-  }
-
-  /** Cancel a trade the player offered. */
-  cancelTrade(id: TradeId): Promise<EndpointReply<'cancelTrade'>> {
-    return this.rest.call('cancelTrade', { ...this.gameFields(), id: Number(id) });
-  }
-
-  /** Answer a trade with a counter-offer. */
-  counterTrade(id: TradeId, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'counterTradeOffer'>> {
-    return this.rest.call('counterTradeOffer', { ...this.gameFields(), id: Number(id), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
-  }
-}
+/**
+ * Analytics, the catalog, favorites, records, inventory and trades. Analytics
+ * calls are fire-and-forget and never throw (telemetry must not break a game);
+ * offline they are buffered and sent when the hub is back. Method names are
+ * the v1 client's, unchanged.
+ */
+import type { Json } from '@diffenderfer-games/hub-contract';
+import { HubProgress } from './hub-progress';
+import { readLocalFavorites, writeLocalFavorites } from './offline/favorites';
+import { ECONOMY_KINDS, type ExchangePayload } from './offline/hub-kinds';
+import { readInventory, withGoods, withoutGoods, type GoodsPayload } from './offline/local-inventory';
+import { HubError } from './errors';
+import { isRecord, stringsIn } from './storage/json-guards';
+import type { EndpointFields, EndpointReply } from './rest/endpoint-types';
+import type { GameAnalytics, GameInfo, GlobalAnalytics, InventorySnapshot } from './types';
+
+/** Goods to grant: item key to quantity, and coins. */
+export type GrantBundle = Omit<EndpointFields<'grantInventoryItems'>, 'slug'>;
+
+/** Goods taken or given in an exchange or a trade. */
+export type TradeBundle = EndpointFields<'exchangeInventoryItems'>['take'];
+
+/** A trade offer's id, as a number or its text. */
+export type TradeId = number | string;
+
+/** Extras for creating or countering a trade. */
+export interface TradeNoteOptions {
+  /** A short note to the other player (moderated). */
+  readonly note?: string;
+}
+
+/** Goods as queued: `null` parts left out. */
+function goodsOf(bundle: TradeBundle | GrantBundle | undefined): GoodsPayload {
+  const items = bundle?.items ?? undefined;
+  const coins = bundle?.coins ?? undefined;
+  return { ...(items === undefined ? {} : { items }), ...(coins === undefined ? {} : { coins }) };
+}
+
+/** The holdings in a grant or exchange reply, or `undefined` when it doesn't read as one. */
+function inventoryReply(result: Json | undefined): InventorySnapshot | undefined {
+  return readInventory(result) ?? undefined;
+}
+
+/** Which trades `listTrades` lists. */
+export type TradeListOptions = Omit<EndpointFields<'listMyTrades'>, 'slug'>;
+
+/** Analytics, catalog, favorites, records, inventory and trades. */
+export class HubEconomy extends HubProgress {
+  /** Record a "play". Call once when the game starts. */
+  recordPlay(): Promise<void> {
+    return this.event('play');
+  }
+
+  /** Record a "heartbeat". Call periodically while the game is active. */
+  heartbeat(): Promise<void> {
+    return this.event('heartbeat');
+  }
+
+  /** Record a custom event. Never throws; offline, events are buffered and sent on reconnect. */
+  async event(type: string): Promise<void> {
+    if (this.slug === null) {
+      return;
+    }
+    if (this.isOffline) {
+      this.store.bufferEvent(type);
+      this.notifyStatus();
+      return;
+    }
+    try {
+      await this.rest.call('recordGameEvent', { ...this.gameFields(), type });
+    } catch (failure) {
+      if (failure instanceof HubError && failure.isOffline) {
+        this.setReachable(false);
+        this.store.bufferEvent(type);
+      }
+    }
+  }
+
+  /** This game's play counts. */
+  analytics(): Promise<GameAnalytics> {
+    return this.withFallback(() => this.rest.call('getGameAnalytics', this.gameFields()), () => ({ slug: this.slug ?? 'app', totalPlays: 0, uniquePlayers: 0, activeNow: 0 }));
+  }
+
+  /** Catalog-wide play counts with a per-game breakdown. */
+  globalAnalytics(): Promise<GlobalAnalytics> {
+    return this.withFallback(() => this.rest.call('getSiteAnalytics'), () => ({ global: { totalPlays: 0, uniquePlayers: 0, activeNow: 0 }, games: [] }));
+  }
+
+  /** The listed games, for "jump to another game" navigation. */
+  listGames(): Promise<{ games: GameInfo[] }> {
+    return this.withFallback(() => this.rest.call('listGames'), () => ({ games: [] }));
+  }
+
+  /** Every board of every game, each with its top `top` entries (default 5). */
+  allLeaderboards(top = 5): Promise<EndpointReply<'listTopOfEveryLeaderboard'>> {
+    return this.withFallback(() => this.rest.call('listTopOfEveryLeaderboard', { top }), () => ({ games: [] }));
+  }
+
+  /**
+   * The starred games (slugs), shown first in the menu's game list. Kept per
+   * account by the hub and mirrored to `localStorage`, so it shows offline.
+   */
+  favorites(): Promise<{ games: string[] }> {
+    return this.withFallback(async () => {
+      const reply = await this.rest.call('listFavoriteGames');
+      writeLocalFavorites(reply.games);
+      return reply;
+    }, () => ({ games: readLocalFavorites() }));
+  }
+
+  /** Star (`isOn = true`) or unstar a game. Offline, the local list changes at once and the hub's when it is back. */
+  setFavorite(slug: string, isOn: boolean): Promise<{ games: string[] }> {
+    return this.mutateOffline(ECONOMY_KINDS.favorite, { slug, on: isOn }, () => {
+      const others = readLocalFavorites().filter((starred) => starred !== slug);
+      const games = isOn ? [...others, slug] : others;
+      writeLocalFavorites(games);
+      return { games };
+    }, (result) => (isRecord(result) ? { games: stringsIn(result.games) } : undefined));
+  }
+
+  /** The player's leaderboard standings, grouped by game (every game, or one via `forSlug`). Empty offline or signed out. */
+  myRecords(forSlug?: string): Promise<EndpointReply<'listMyLeaderboardRecords'>> {
+    return this.withFallback(
+      () => this.rest.call('listMyLeaderboardRecords', forSlug === undefined || forSlug === '' ? {} : { game: forSlug }),
+      () => ({ games: [] }),
+    );
+  }
+
+  /** This game's inventory and coin balance for the current user. */
+  getInventory(): Promise<InventorySnapshot> {
+    return this.withFallback(async () => this.store.setInventory(await this.rest.call('getMyInventory', this.gameFields())), () => this.store.getInventory());
+  }
+
+  /** Another player's available holdings (to compose a trade). */
+  playerInventory(userId: number): Promise<InventorySnapshot> {
+    return this.withFallback(() => this.rest.call('getPlayerInventory', { ...this.gameFields(), userId }), () => ({ items: [], coins: 0 }));
+  }
+
+  /**
+   * Add goods to the player (gameplay rewards); answers the new holdings.
+   * Offline, the cached holdings change at once and the grant replays later.
+   */
+  grant(bundle: GrantBundle): Promise<EndpointReply<'grantInventoryItems'>> {
+    const goods = goodsOf(bundle);
+    return this.mutateOffline(ECONOMY_KINDS.grant, goods, () => this.store.setInventory(withGoods(this.store.getInventory(), goods)), inventoryReply);
+  }
+
+  /**
+   * An atomic swap with the house: remove `take`, add `give`. Offline it is
+   * checked against the cached holdings (409 when they can't cover `take`),
+   * applied to them at once, and replayed later; the hub has the last word.
+   */
+  exchange(take?: TradeBundle, give?: TradeBundle): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    const payload: ExchangePayload = { ...(take === undefined ? {} : { take: goodsOf(take) }), ...(give === undefined ? {} : { give: goodsOf(give) }) };
+    return this.mutateOffline(ECONOMY_KINDS.exchange, payload, () => {
+      const remaining = withoutGoods(this.store.getInventory(), payload.take ?? {});
+      if (typeof remaining === 'string') {
+        if (this.isOffline) {
+          throw new HubError(remaining, 409);
+        }
+        return this.store.getInventory();
+      }
+      return this.store.setInventory(withGoods(remaining, payload.give ?? {}));
+    }, inventoryReply);
+  }
+
+  /** Sell items to the house for coins. */
+  sell(items: Record<string, number>, coins: number): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    return this.exchange({ items }, { coins });
+  }
+
+  /** Buy items from the house with coins. */
+  buy(coins: number, items: Record<string, number>): Promise<EndpointReply<'exchangeInventoryItems'>> {
+    return this.exchange({ coins }, { items });
+  }
+
+  /** Wipe the player's progress in this game (saves, stats, inventory and coins). */
+  resetGame(): Promise<{ ok: true }> {
+    return this.rest.call('resetMyGameProgress', this.gameFields());
+  }
+
+  /** Players this player can trade with in this game. */
+  listPlayers(): Promise<EndpointReply<'listTradePartners'>> {
+    return this.withFallback(() => this.rest.call('listTradePartners', this.gameFields()), () => ({ players: [] }));
+  }
+
+  /** The player's trades (`box`: `incoming` or `outgoing`; `status` filters). */
+  listTrades(opts: TradeListOptions = {}): Promise<EndpointReply<'listMyTrades'>> {
+    return this.withFallback(() => this.rest.call('listMyTrades', { ...this.gameFields(), ...opts }), () => ({ offers: [] }));
+  }
+
+  /** Offer a trade to another player (by id or name). */
+  createTrade(toUser: number | string, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'createTrade'>> {
+    return this.rest.call('createTrade', { ...this.gameFields(), toUser: String(toUser), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
+  }
+
+  /** Accept a trade offered to the player. */
+  acceptTrade(id: TradeId): Promise<EndpointReply<'acceptTrade'>> {
+    return this.rest.call('acceptTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Decline a trade offered to the player. */
+  declineTrade(id: TradeId): Promise<EndpointReply<'declineTrade'>> {
+    return this.rest.call('declineTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Cancel a trade the player offered. */
+  cancelTrade(id: TradeId): Promise<EndpointReply<'cancelTrade'>> {
+    return this.rest.call('cancelTrade', { ...this.gameFields(), id: Number(id) });
+  }
+
+  /** Answer a trade with a counter-offer. */
+  counterTrade(id: TradeId, give?: TradeBundle, want?: TradeBundle, opts: TradeNoteOptions = {}): Promise<EndpointReply<'counterTradeOffer'>> {
+    return this.rest.call('counterTradeOffer', { ...this.gameFields(), id: Number(id), ...(give === undefined ? {} : { give }), ...(want === undefined ? {} : { want }), ...opts });
+  }
+}