@mpgd/cli 0.57.0 → 0.58.0

package/templates/phaser-game/src/platform/sessionGatedServices.ts

@@ -0,0 +1,217 @@
+import type {
+  GameServicesClient,
+  GameServicesPurchaseResult,
+  GameServicesRewardedAdResult,
+  GameServicesRuntime,
+} from '@mpgd/game-services';
+
+/** The diagnostic of a purchase refused because the run is not signed in yet (retryable). */
+export const starterSessionRequiredCode = 'STARTER_SESSION_REQUIRED';
+
+function sessionRequiredPurchase(): GameServicesPurchaseResult {
+  return {
+    status: 'failed',
+    purchase: {
+      status: 'failed',
+      entitlementIds: [],
+      diagnostic: { code: starterSessionRequiredCode, retryable: true },
+    },
+  };
+}
+
+function sessionRequiredReward(): GameServicesRewardedAdResult {
+  return { status: 'unavailable', reward: { status: 'unavailable', rewardGranted: false } };
+}
+
+/** A purchase, restore, or reward claim was asked for before the guest sign-in succeeded. */
+export class StarterSessionRequiredError extends Error {
+  readonly code = 'STARTER_SESSION_REQUIRED';
+
+  constructor() {
+    super('The game is not signed in to its identity service yet; try again when it is online.');
+    this.name = 'StarterSessionRequiredError';
+  }
+}
+
+/** The game services of a run that booted before its guest sign-in succeeded. */
+export type StarterSessionGatedServices = GameServicesRuntime & {
+  /**
+   * Signs in now if needed (once more before a purchase or restore); `true`
+   * when the services are up. Absent when the configuration has no client.
+   */
+  readonly ensureSession?: () => Promise<boolean>;
+  /**
+   * Calls `listener` once the services came up for the signed-in player
+   * (not for the services of an earlier sign-in); returns the unsubscribe.
+   * Delete account uses it to appear in a run that signed in late.
+   */
+  readonly onReady: (listener: () => void) => () => void;
+};
+
+/**
+ * Game services that come up when the player is signed in, for a run whose
+ * boot-time sign-in failed (offline, an outage). The real services are bound
+ * to a player id for their whole life (the purchase journal and the backend
+ * ledger are keyed by it), so they are created only once the server player
+ * is known (`create`), never with the platform's local placeholder:
+ *
+ * - `client` is present from the start, so the game action coordinator
+ *   exists for the run. A purchase or reward claim signs in first
+ *   (`ensurePlayer`); when that still fails it answers a plain refusal
+ *   before any store UI opens (`failed` with the retryable diagnostic
+ *   `STARTER_SESSION_REQUIRED`; a reward `unavailable`), never a thrown
+ *   error, which would latch the action coordinator into
+ *   `reconciliation-required` for the rest of the run. A leaderboard
+ *   submission throws `StarterSessionRequiredError`.
+ * - `monetizationRecovery` is `undefined` until then, and the Restore
+ *   Purchases control signs in first through `ensureSession`. Rewarded ads
+ *   stay off for the whole run (`main.ts` `canShow`, `PlayScene`): the
+ *   runtime binds its late reward evidence recovery at boot.
+ * - When the player becomes known, the services are created once; the
+ *   caller runs the game runtime's `reconcile()` from `onActivated` (the
+ *   startup recovery, with the action coordinator's). A later sign-in naming another player
+ *   (not expected within one run) is ignored with a warning.
+ * - `accountDeletion` is `undefined` until then, and the services' after
+ *   (read live); `onReady` tells Delete account to appear then.
+ * - `ensureSession` is present only when the configuration has a client
+ *   (a disabled configuration has nothing a sign-in could bring up).
+ *
+ * `probe` is a runtime built from the same configuration with a placeholder
+ * player; only its `mode`, `reason`, `baseUrl`, `target`, and whether it has
+ * a client are read.
+ */
+export function createSessionGatedGameServices(input: {
+  readonly probe: GameServicesRuntime;
+  readonly ensurePlayer: () => Promise<string | undefined>;
+  readonly onPlayer: (listener: (playerId: string) => void) => () => void;
+  readonly create: (playerId: string) => GameServicesRuntime;
+  /**
+   * Called once, when the services were created (by a background sign-in or
+   * one a purchase or restore started): run the game runtime's `reconcile()`.
+   */
+  readonly onActivated?: () => void;
+  readonly warn?: (message: string, error?: unknown) => void;
+}): StarterSessionGatedServices {
+  const warn = input.warn ?? ((message: string, error?: unknown) => console.warn(message, error ?? ''));
+  let inner: GameServicesRuntime | undefined;
+  let innerPlayer: string | undefined;
+  const readyListeners = new Set<() => void>();
+
+  const activate = (playerId: string): void => {
+    if (inner !== undefined) {
+      if (playerId !== innerPlayer) {
+        warn(
+          '[game-services] a later sign-in named another player; the services keep the first until restart.',
+        );
+      }
+      return;
+    }
+    try {
+      inner = input.create(playerId);
+      innerPlayer = playerId;
+    } catch (error) {
+      // Stays gated: purchases keep answering the session refusal, never a raw error.
+      warn('[game-services] the services could not be created after sign-in', error);
+      return;
+    }
+    try {
+      input.onActivated?.();
+    } catch (error) {
+      // The services are up; only the caller's follow-up failed.
+      warn('[game-services] the activation callback failed', error);
+    }
+    for (const listener of [...readyListeners]) {
+      readyListeners.delete(listener);
+      try {
+        listener();
+      } catch (error) {
+        warn('[game-services] a ready listener failed', error);
+      }
+    }
+  };
+  input.onPlayer(activate);
+
+  const ready = async (): Promise<GameServicesRuntime> => {
+    if (inner === undefined) {
+      const playerId = await input.ensurePlayer();
+      if (playerId !== undefined) {
+        activate(playerId);
+      }
+    }
+    if (inner === undefined) {
+      throw new StarterSessionRequiredError();
+    }
+    return inner;
+  };
+  const readyClientOrUndefined = async (): Promise<GameServicesClient | undefined> => {
+    try {
+      return await readyClient();
+    } catch (error) {
+      if (error instanceof StarterSessionRequiredError) {
+        return undefined;
+      }
+      throw error;
+    }
+  };
+  const readyClient = async (): Promise<GameServicesClient> => {
+    const client = (await ready()).client;
+    if (client === undefined) {
+      throw new StarterSessionRequiredError();
+    }
+    return client;
+  };
+
+  let client: GameServicesClient | undefined;
+  if (input.probe.client !== undefined) {
+    client = {
+      purchase: async (purchase, options) => {
+        const ready = await readyClientOrUndefined();
+        return ready === undefined ? sessionRequiredPurchase() : ready.purchase(purchase, options);
+      },
+      claimRewardedAd: async (reward, options) => {
+        const ready = await readyClientOrUndefined();
+        return ready === undefined ? sessionRequiredReward() : ready.claimRewardedAd(reward, options);
+      },
+      submitLeaderboardScore: async (score) => (await readyClient()).submitLeaderboardScore(score),
+    };
+    // Read live: the reconciler of the services created after sign-in.
+    Object.defineProperty(client, 'commerceReconciler', {
+      enumerable: true,
+      get: () => inner?.client?.commerceReconciler,
+    });
+  }
+
+  const services = {
+    onReady(listener: () => void) {
+      readyListeners.add(listener);
+      return () => {
+        readyListeners.delete(listener);
+      };
+    },
+    ...(input.probe.reason === undefined ? {} : { reason: input.probe.reason }),
+    ...(input.probe.baseUrl === undefined ? {} : { baseUrl: input.probe.baseUrl }),
+    ...(input.probe.target === undefined ? {} : { target: input.probe.target }),
+    ...(client === undefined
+      ? {}
+      : {
+          client,
+          // Only a configuration with a client can come up; a disabled one offers nothing to retry.
+          async ensureSession() {
+            try {
+              await ready();
+              return true;
+            } catch {
+              return false;
+            }
+          },
+        }),
+  } as StarterSessionGatedServices;
+  // Read live: `undefined` until the player is known, so rewarded ads stay off until then,
+  // and Delete account appears once there is an account (the lobby's next visit).
+  Object.defineProperties(services, {
+    mode: { enumerable: true, get: () => inner?.mode ?? input.probe.mode },
+    monetizationRecovery: { enumerable: true, get: () => inner?.monetizationRecovery },
+    accountDeletion: { enumerable: true, get: () => inner?.accountDeletion },
+  });
+  return services;
+}

package/templates/phaser-game/src/scenes/LobbyScene.ts

@@ -1,14 +1,31 @@
 import Phaser from 'phaser';
 
 import { t } from '../i18n/messages';
+import {
+  createStarterAccountDeletion,
+  deleteAccountConfirmText,
+  deleteAccountOutcomeText,
+  starterAccountDeletionConfirmation,
+  type StarterDeleteAccountOutcome,
+} from '../platform/deleteAccount';
+import {
+  createStarterRestorePurchases,
+  restoreOutcomeText,
+  type StarterRestoreOutcome,
+} from '../platform/restorePurchases';
+import { resolveStarterServerSession } from '../platform/serverSession';
 import { starterContextKey, type StarterContext } from '../runtime/gameContext';
 
 export class LobbyScene extends Phaser.Scene {
+  /** True while the Delete account panel is open; Enter then does not start the game. */
+  private deleteAccountOpen = false;
+
   constructor() {
     super('LobbyScene');
   }
 
   create(): void {
+    this.deleteAccountOpen = false;
     const rawContext = this.registry.get(starterContextKey);
 
     if (rawContext === undefined || rawContext === null) {
@@ -92,7 +109,243 @@ export class LobbyScene extends Phaser.Scene {
       })
       .setOrigin(0.5);
 
+    this.addRestorePurchasesButton(context);
+    this.addDeleteAccountEntry(context);
+
     this.input.once('pointerdown', () => this.scene.start('PlayScene'));
-    this.input.keyboard?.once('keydown-ENTER', () => this.scene.start('PlayScene'));
+    const onEnter = (): void => {
+      if (!this.deleteAccountOpen) {
+        this.input.keyboard?.off('keydown-ENTER', onEnter);
+        this.scene.start('PlayScene');
+      }
+    };
+    this.input.keyboard?.on('keydown-ENTER', onEnter);
+  }
+
+  /**
+   * Restore Purchases, shown where the target sells through a store. App
+   * Review expects it while the catalog sells a non-consumable (REMOVE_ADS).
+   * Its tap stops propagation so it does not also start the game.
+   */
+  private addRestorePurchasesButton(context: StarterContext): void {
+    const services = context.gameServices;
+    const restore = createStarterRestorePurchases({
+      gateway: context.platform,
+      // Read at tap time: a run that signs in late gets its recovery client then.
+      monetizationRecovery: () => services.monetizationRecovery,
+      ...(services.ensureSession === undefined ? {} : { ensureSession: services.ensureSession }),
+    });
+    if (!restore.available) {
+      return;
+    }
+    const locale = context.locale;
+    const status = this.add
+      .text(480, 500, '', {
+        color: '#d6dee8',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '16px',
+      })
+      .setOrigin(0.5);
+    this.add
+      .text(480, 456, t(locale, 'restorePurchases'), {
+        color: '#5eead4',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '20px',
+      })
+      .setOrigin(0.5)
+      .setPadding(16, 10, 16, 10)
+      .setInteractive({ useHandCursor: true })
+      .on(
+        'pointerdown',
+        (
+          _pointer: Phaser.Input.Pointer,
+          _x: number,
+          _y: number,
+          event: Phaser.Types.Input.EventData,
+        ) => {
+          event.stopPropagation();
+          status.setText(t(locale, 'restoreWorking'));
+          void restore.restore()
+            .catch((): StarterRestoreOutcome => ({ outcome: 'failed' }))
+            .then((result) => {
+              if (status.active) {
+                status.setText(restoreOutcomeText(locale, result));
+              }
+            });
+        },
+      );
+  }
+  /**
+   * Delete account, shown where the game has a game-services backend (App
+   * Store guideline 5.1.1(v) and Google Play require deletion in the app).
+   * The first tap explains what is deleted and kept; only the second,
+   * "Delete permanently", deletes. Taps stop propagation so they do not
+   * also start the game.
+   */
+  private addDeleteAccountEntry(context: StarterContext): void {
+    // No backend yet: read no session, which `once` would pin. A run whose guest sign-in
+    // failed at boot gets the backend after a later sign-in (`onReady`); add the entry then.
+    if (context.gameServices.accountDeletion === undefined) {
+      const onReady = (context.gameServices as { readonly onReady?: (listener: () => void) => () => void })
+        .onReady;
+      if (onReady !== undefined) {
+        const stop = onReady(() => {
+          stop();
+          if (this.scene.isActive()) {
+            this.addDeleteAccountEntry(context);
+          }
+        });
+        this.events.once('shutdown', stop);
+      }
+      return;
+    }
+    // The commerce client's session (`once`), so the entry and the request agree.
+    const session = resolveStarterServerSession({ once: true });
+    const confirmation = starterAccountDeletionConfirmation(session);
+    const deletion = createStarterAccountDeletion({
+      ...(context.gameServices.accountDeletion === undefined
+        ? {}
+        : { client: context.gameServices.accountDeletion }),
+      storage: context.platform.storage,
+      ...(context.platform.secureCredentials === undefined
+        ? {}
+        : { secureCredentials: context.platform.secureCredentials }),
+      signedIn: () => session?.current() !== undefined,
+      // The identity service's confirmation, so an access token alone cannot delete the account.
+      ...(confirmation === undefined ? {} : { requestConfirmation: confirmation }),
+    });
+    if (!deletion.available) {
+      if (context.gameServices.accountDeletion !== undefined && session !== undefined) {
+        // Signed in later (a guest session starts in the background): add it then.
+        const stop = session.onAuthenticated(() => {
+          stop();
+          if (this.scene.isActive()) {
+            this.addDeleteAccountEntry(context);
+          }
+        });
+        this.events.once('shutdown', stop);
+      }
+      return;
+    }
+    const locale = context.locale;
+    const swallow = (
+      _pointer: Phaser.Input.Pointer,
+      _x: number,
+      _y: number,
+      event: Phaser.Types.Input.EventData,
+    ): void => {
+      event.stopPropagation();
+    };
+    const entry = this.add
+      .text(944, 16, t(locale, 'deleteAccount'), {
+        color: '#fca5a5',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '16px',
+      })
+      .setOrigin(1, 0)
+      .setPadding(12, 8, 12, 8)
+      .setInteractive({ useHandCursor: true });
+    const panel = this.add.container(0, 0).setVisible(false).setDepth(10);
+    const backdrop = this.add
+      .rectangle(480, 270, 960, 540, 0x020617, 0.92)
+      .setInteractive()
+      .on('pointerdown', swallow);
+    const message = this.add
+      .text(480, 200, '', {
+        align: 'center',
+        color: '#ffffff',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '18px',
+        wordWrap: { width: 760 },
+      })
+      .setOrigin(0.5);
+    const status = this.add
+      .text(480, 470, '', {
+        color: '#d6dee8',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '16px',
+      })
+      .setOrigin(0.5);
+    const confirm = this.add
+      .text(360, 400, t(locale, 'deleteAccountConfirmButton'), {
+        backgroundColor: '#b91c1c',
+        color: '#ffffff',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '20px',
+      })
+      .setOrigin(0.5)
+      .setPadding(16, 10, 16, 10)
+      .setInteractive({ useHandCursor: true });
+    const cancel = this.add
+      .text(600, 400, t(locale, 'deleteAccountCancel'), {
+        color: '#ffffff',
+        fontFamily: 'Arial, sans-serif',
+        fontSize: '20px',
+      })
+      .setOrigin(0.5)
+      .setPadding(16, 10, 16, 10)
+      .setInteractive({ useHandCursor: true });
+    panel.add([backdrop, message, status, confirm, cancel]);
+    let deleting = false;
+    let signedOut = false;
+    entry.on('pointerdown', (...args: Parameters<typeof swallow>) => {
+      swallow(...args);
+      if (deleting) {
+        return;
+      }
+      this.deleteAccountOpen = true;
+      status.setText('');
+      confirm.setVisible(true);
+      cancel.setText(t(locale, 'deleteAccountCancel'));
+      message.setText(deleteAccountConfirmText(locale, false));
+      panel.setVisible(true);
+      void deletion.hasPendingPurchase().then((pending) => {
+        if (pending && message.active) {
+          message.setText(deleteAccountConfirmText(locale, true));
+        }
+      });
+    });
+    cancel.on('pointerdown', (...args: Parameters<typeof swallow>) => {
+      swallow(...args);
+      if (deleting) {
+        return;
+      }
+      if (signedOut) {
+        // A fresh start drops every in-memory trace of the deleted player
+        // (the session, the reconciler, the notifications runtime).
+        globalThis.location.reload();
+        return;
+      }
+      this.deleteAccountOpen = false;
+      panel.setVisible(false);
+    });
+    confirm.on('pointerdown', (...args: Parameters<typeof swallow>) => {
+      swallow(...args);
+      if (deleting) {
+        return;
+      }
+      deleting = true;
+      confirm.setAlpha(0.5);
+      cancel.setAlpha(0.5);
+      status.setText(t(locale, 'deleteAccountWorking'));
+      void deletion.deleteAccount()
+        .catch((): StarterDeleteAccountOutcome => ({ outcome: 'failed', retryable: true }))
+        .then((result) => {
+          deleting = false;
+          if (!status.active) {
+            return;
+          }
+          confirm.setAlpha(1);
+          cancel.setAlpha(1);
+          status.setText(deleteAccountOutcomeText(locale, result));
+          if (result.outcome === 'deleted' || result.outcome === 'session-ended') {
+            // Signed out: the entry goes; Close restarts the game.
+            signedOut = true;
+            confirm.setVisible(false);
+            entry.setVisible(false);
+            cancel.setText(t(locale, 'deleteAccountClose'));
+          }
+        });
+    });
   }
 }

package/templates/phaser-game/src/scenes/PlayScene.ts

@@ -9,6 +9,7 @@ import { createStarterRunState, stepStarterRunState, type StarterRunState } from
 import { t } from '../i18n/messages';
 import { starterContextKey, type StarterContext } from '../runtime/gameContext';
 import { createClientId } from '../runtime/id';
+import { starterRunKey } from '../platform/deleteAccount';
 
 const rewardedPlacementId = 'CONTINUE_AFTER_FAIL' satisfies LogicalAdPlacementId;
 
@@ -33,7 +34,7 @@ export class PlayScene extends Phaser.Scene {
     const checkpoint = () => {
       try {
         this.context.platform.storage.saveSync?.({
-          key: 'starter-run',
+          key: starterRunKey,
           value: this.state,
         });
       } catch (error) {
@@ -114,10 +115,20 @@ export class PlayScene extends Phaser.Scene {
     }
   }
 
-  private rewardHint(): string {
-    const rewardedAds = this.context.runtime.features.rewardedAds;
+  /**
+   * Rewarded ads need the target feature and the recovery client, and a run
+   * that booted before its guest sign-in (session-gated services) shows none,
+   * matching the runtime's `canShow` in `main.ts`.
+   */
+  private rewardedAdsAvailable(): boolean {
+    const services = this.context.gameServices;
+    return this.context.runtime.features.rewardedAds.enabled
+      && services.monetizationRecovery !== undefined
+      && services.ensureSession === undefined;
+  }
 
-    if (!rewardedAds.enabled || this.context.gameServices.client === undefined || this.context.gameServices.monetizationRecovery === undefined) {
+  private rewardHint(): string {
+    if (!this.rewardedAdsAvailable() || this.context.gameServices.client === undefined) {
       return t(this.context.locale, 'rewardUnavailable');
     }
 
@@ -125,10 +136,9 @@ export class PlayScene extends Phaser.Scene {
   }
 
   private async requestRewardedAd(): Promise<void> {
-    const rewardedAds = this.context.runtime.features.rewardedAds;
     const action = this.rewardedAction;
 
-    if (!rewardedAds.enabled || action === undefined || this.context.gameServices.monetizationRecovery === undefined) {
+    if (!this.rewardedAdsAvailable() || action === undefined) {
       this.rewardText.setText(t(this.context.locale, 'rewardUnavailable'));
       return;
     }