@mpgd/cli 0.53.0 → 0.54.1

package/templates/notifications-overlay/common/src/platform/notificationBackend.ts

@@ -0,0 +1,157 @@
+import {
+  isPublicGameServicesUrl,
+  resolveGameServicesAuthorityMode,
+  type GameServicesHeaderResolver,
+} from '@mpgd/game-services';
+import {
+  createGameServicesNotificationsClient,
+  type GameServicesNotificationIdentity,
+  type GameServicesNotificationsFetch,
+} from '@mpgd/game-services/notifications/client';
+import type {
+  NotificationConsentRecord,
+  NotificationRuntime,
+  NotificationTopicDeclaration,
+} from '@mpgd/platform/notifications';
+import {
+  createNotificationRuntime,
+  createNotificationRuntimeStorage,
+} from '@mpgd/platform/notifications-runtime';
+import type { TargetConfiguredGateway } from '@mpgd/target-config';
+
+/**
+ * The game backend's notifications surface the starter uses: the runtime
+ * (notifications RFC "Runtime"), which composes the target's provider with
+ * the backend that keeps consent records, endpoint registrations, server
+ * reminders, and notices; and the signed-in player's consent records (the
+ * game-services Worker's `GET /consent`), which the settings screen shows.
+ */
+export interface StarterNotificationBackend {
+  readonly runtime: NotificationRuntime;
+  listConsent(): Promise<readonly NotificationConsentRecord[]>;
+}
+
+/** The server-backed session the Worker client needs (see `serverSession.ts`). */
+export interface StarterWorkerSession extends GameServicesNotificationIdentity {
+  readonly getHeaders: GameServicesHeaderResolver;
+}
+
+export interface StarterWorkerNotificationInput {
+  /** `VITE_MPGD_GAME_SERVICES_URL`. */
+  readonly baseUrl: string | undefined;
+  /** The Vite mode (`import.meta.env.MODE`), which decides the production URL rule. */
+  readonly mode: string;
+  readonly session: StarterWorkerSession | undefined;
+  /** This target's topics, each with its mapping. */
+  readonly topics: readonly NotificationTopicDeclaration[];
+  readonly defaultLocale: string;
+  /** Logs a message, once per gateway and message. */
+  readonly log: (message: string, error?: unknown) => void;
+  /** Defaults to `globalThis.fetch`. */
+  readonly fetch?: GameServicesNotificationsFetch;
+}
+
+/**
+ * Config targets whose notifications backend is not the game-services
+ * Worker. A Reddit game's backend is its Devvit server: the opt-in, the
+ * consent records, and the sends live there, and the Worker serves no
+ * `reddit` target. A runtime over the Worker would send the game's session
+ * header to a backend that cannot use it, so Reddit keeps no backend here,
+ * as before R1, until the Devvit server has a runtime client of its own.
+ */
+const targetsWithoutWorkerBackend: ReadonlySet<string> = new Set(['reddit']);
+
+/**
+ * The notifications runtime over the game-services Worker's notification
+ * routes (`@mpgd/game-services/notifications/client`), when the target's
+ * backend is the Worker, the game has a game-services URL and a
+ * server-backed session, and the target exposes a notifications provider.
+ * Otherwise `undefined`.
+ *
+ * The runtime keeps its registration state in the platform storage, starts
+ * here, and compares its provider with the Worker's registry entry for this
+ * target (`GET /providers`), loaded in the background: a Worker it cannot
+ * reach is logged once and the runtime runs without the comparison.
+ */
+export function createStarterWorkerNotificationBackend(
+  platform: TargetConfiguredGateway,
+  input: StarterWorkerNotificationInput,
+): StarterNotificationBackend | undefined {
+  // By platform, and by config target name for a gateway that reports another platform.
+  if (platform.target === 'reddit' || targetsWithoutWorkerBackend.has(platform.configTarget)) {
+    return undefined;
+  }
+  const baseUrl = input.baseUrl?.trim();
+  const provider = platform.notificationsV2;
+  if (baseUrl === undefined || baseUrl === '' || provider === undefined) {
+    return undefined;
+  }
+  const { session } = input;
+  if (session === undefined) {
+    input.log(
+      '[notifications] VITE_MPGD_GAME_SERVICES_URL is set but no server session is: call setStarterServerSession '
+        + '(src/platform/serverSession.ts) before the game starts. The settings screen shows no switch until then.',
+    );
+    return undefined;
+  }
+  try {
+    if (!isAllowedGameServicesUrl(baseUrl, input.mode)) {
+      // The session's credentials never travel in clear text or to a private host in production.
+      input.log(
+        '[notifications] VITE_MPGD_GAME_SERVICES_URL must be an absolute http(s) URL, and a public https URL '
+          + 'without credentials in production; notifications stay off.',
+      );
+      return undefined;
+    }
+    const client = createGameServicesNotificationsClient({
+      baseUrl,
+      identity: session,
+      getHeaders: () => session.getHeaders(),
+      // The catalog target whose mapping applies to this device (android or ios share FCM).
+      target: platform.configTarget,
+      ...(input.fetch === undefined ? {} : { fetch: input.fetch }),
+    });
+    const runtime = createNotificationRuntime({
+      provider,
+      backend: client,
+      catalog: input.topics,
+      defaultLocale: input.defaultLocale,
+      storage: createNotificationRuntimeStorage({ storage: platform.storage }),
+      // This target's entry in the Worker's registry, or none when the Worker does not serve it.
+      async loadRegistryEntry() {
+        const { providers, targets } = await client.getProviders();
+        const id = targets[platform.configTarget];
+        return id === undefined ? undefined : providers.find((entry) => entry.provider === id);
+      },
+      onError(error) {
+        console.error('[notifications]', error);
+      },
+    });
+    // It subscribes to the provider at once; a backend that cannot answer yet does not fail the game.
+    runtime.start().catch((error: unknown) => {
+      console.error('[notifications] the runtime could not start.', error);
+    });
+    return { runtime, listConsent: () => client.listConsent() };
+  } catch (error) {
+    // A configuration the client refuses turns notifications off, never the game.
+    input.log('[notifications] the notifications backend could not be created.', error);
+    return undefined;
+  }
+}
+
+/**
+ * Whether the game-services URL may carry the session's credentials: any
+ * absolute http(s) URL outside production builds, and in production the
+ * public https URL the commerce client requires (`isPublicGameServicesUrl`).
+ */
+function isAllowedGameServicesUrl(baseUrl: string, mode: string): boolean {
+  if (resolveGameServicesAuthorityMode(mode) === 'production') {
+    return isPublicGameServicesUrl(baseUrl);
+  }
+  try {
+    const { protocol } = new URL(baseUrl);
+    return protocol === 'https:' || protocol === 'http:';
+  } catch {
+    return false;
+  }
+}

package/templates/notifications-overlay/common/src/platform/notifications.ts

@@ -1,13 +1,13 @@
 import { resolveNotificationTopicsForTarget, type NotificationTopicCatalog } from '@mpgd/catalog';
-import type { PlatformGateway } from '@mpgd/platform';
+import type { NotificationTopicDeclaration } from '@mpgd/platform/notifications';
 import type { TargetConfiguredGateway } from '@mpgd/target-config';
-import type {
-  NotificationConsentRecord,
-  NotificationRuntime,
-  NotificationTopicDeclaration,
-} from '@mpgd/platform/notifications';
 
 import notificationTopicsJson from '../../notifications/topics.json';
+import {
+  createStarterWorkerNotificationBackend,
+  type StarterNotificationBackend,
+} from './notificationBackend';
+import { resolveStarterServerSession } from './serverSession';
 import { routeNotificationOpens, type NotificationOpenRoutes } from './notificationOpens';
 import {
   createStarterNotificationSettings,
@@ -43,45 +43,77 @@ export function starterNotificationTopics(configTarget: string): readonly Notifi
   }
 }
 
-/**
- * The game backend's notifications surface the starter uses: the runtime
- * (notifications RFC "Runtime"), which composes the target's provider with
- * the backend that keeps consent records, endpoint registrations, server
- * reminders, and notices; and the signed-in player's consent records (the
- * game-services Worker's `GET /consent`), which the settings screen shows.
- */
-export interface StarterNotificationBackend {
-  readonly runtime: NotificationRuntime;
-  listConsent(): Promise<readonly NotificationConsentRecord[]>;
-}
+export type { StarterNotificationBackend } from './notificationBackend';
 
 /**
- * The game's notifications backend.
+ * The game's notifications backend: the notifications runtime over the
+ * game-services Worker's notification routes (see `notificationBackend.ts`),
+ * when the game has both a game-services URL (`VITE_MPGD_GAME_SERVICES_URL`,
+ * as the commerce client uses) and a server-backed session
+ * (`setStarterServerSession` in `serverSession.ts`), and the target exposes
+ * a notifications provider. Otherwise `undefined`: the notification settings
+ * screen then asks only for the OS or host permission and shows no
+ * reminder, advertising, or night switch, because nothing could record them.
  *
- * The kit does not ship that runtime's backend client yet: the game-services
- * Worker's notification routes need a session from the identity side, which
- * comes in a later kit release. Until then this returns `undefined`, and the
- * notification settings screen asks only for the OS or host permission and
- * shows no reminder, advertising, or night switch, because nothing could
- * record them. Return your own runtime and consent reader here when your
- * backend implements those routes.
+ * Reddit gets no Worker backend: its notifications backend is the Devvit
+ * server, which keeps the opt-in, the records, and the sends. The Worker
+ * serves the Android, iOS, and Apps in Toss providers and binds a device to
+ * the session its `Authorization` header names, through its
+ * `GAME_SERVICES_NOTIFICATIONS_AUTH` binding to your identity service
+ * (docs/CLOUDFLARE_WORKER_DEPLOY.md, "Sessions"). Call this through the
+ * settings model or `subscribeStarterNotificationOpens`, which keep one
+ * runtime per gateway: a second call starts a second runtime on the same
+ * provider.
  */
 export function createStarterNotificationBackend(
-  _platform: PlatformGateway,
+  platform: TargetConfiguredGateway,
 ): StarterNotificationBackend | undefined {
-  return undefined;
+  return createStarterWorkerNotificationBackend(platform, {
+    baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL,
+    mode: import.meta.env.MODE,
+    session: resolveStarterServerSession(),
+    topics: starterNotificationTopics(platform.configTarget),
+    defaultLocale: starterNotificationCatalog.defaultLocale,
+    log: (message, error) => warnOnce(platform, message, error),
+  });
 }
 
-const backends = new WeakMap<PlatformGateway, StarterNotificationBackend | undefined>();
+/** Messages already logged per gateway: a screen opened again does not log them again. */
+const warned = new WeakMap<TargetConfiguredGateway, Set<string>>();
+function warnOnce(platform: TargetConfiguredGateway, message: string, error?: unknown): void {
+  let messages = warned.get(platform);
+  if (messages === undefined) {
+    messages = new Set();
+    warned.set(platform, messages);
+  }
+  if (!messages.has(message)) {
+    messages.add(message);
+    if (error === undefined) {
+      console.warn(message);
+    } else {
+      console.error(message, error);
+    }
+  }
+}
+
+const backends = new WeakMap<TargetConfiguredGateway, StarterNotificationBackend>();
 /** Per gateway, for the process: agreements given on a host that gives no read. */
-const agreements = new WeakMap<PlatformGateway, Set<string>>();
+const agreements = new WeakMap<TargetConfiguredGateway, Set<string>>();
 
-/** One backend per gateway: a runtime subscribes to its provider once, for the process. */
-function starterNotificationBackend(platform: PlatformGateway): StarterNotificationBackend | undefined {
-  if (!backends.has(platform)) {
-    backends.set(platform, createStarterNotificationBackend(platform));
+/**
+ * One backend per gateway: a runtime subscribes to its provider once, for the
+ * process. A gateway without one yet (no session set) is asked again on the
+ * next use.
+ */
+function starterNotificationBackend(platform: TargetConfiguredGateway): StarterNotificationBackend | undefined {
+  let backend = backends.get(platform);
+  if (backend === undefined) {
+    backend = createStarterNotificationBackend(platform);
+    if (backend !== undefined) {
+      backends.set(platform, backend);
+    }
   }
-  return backends.get(platform);
+  return backend;
 }
 
 /** The settings screen's model for this gateway and locale. */
@@ -121,7 +153,7 @@ export function createStarterNotificationSettingsModel(
  * the game has one, else the provider. Returns the unsubscribe.
  */
 export function subscribeStarterNotificationOpens(
-  platform: PlatformGateway,
+  platform: TargetConfiguredGateway,
   routes: NotificationOpenRoutes,
 ): () => void {
   const source = starterNotificationBackend(platform)?.runtime ?? platform.notificationsV2;

package/templates/notifications-overlay/phaser/src/scenes/NotificationSettingsScene.ts

@@ -16,8 +16,13 @@ export const notificationSettingsSceneKey = 'NotificationSettingsScene';
 
 const textStyle = { color: '#d6dee8', fontFamily: 'Arial, sans-serif', fontSize: '18px' } as const;
 const buttonStyle = { ...textStyle, color: '#5eead4' } as const;
-/** The list's viewport on the 960x540 game: below the title and the outcome strip, above Back. */
-const list = { top: 110, height: 370, width: 960 } as const;
+/** List rows and the outcome strip share this column (x=60..900) on the 960x540 game. */
+const listTextWidth = 840;
+/** Below the title. The outcome strip grows downward from here. */
+const outcomeTop = 68;
+/** The list ends above the Back button. */
+const listBottom = 480;
+const minListTop = 110;
 
 /**
  * Routes notification opens: one whose route is the settings screen (the
@@ -108,10 +113,17 @@ export class NotificationSettingsScene extends Phaser.Scene {
       this.scene.start('LobbyScene');
     }).setOrigin(0.5);
     this.outcome = this.add
-      .text(480, 88, '', { ...textStyle, color: '#f59e0b', fontSize: '16px' })
-      .setOrigin(0.5);
+      .text(480, outcomeTop, '', {
+        ...textStyle,
+        align: 'center',
+        color: '#f59e0b',
+        fontSize: '16px',
+        wordWrap: { width: listTextWidth },
+      })
+      .setOrigin(0.5, 0);
     this.content = this.add.container(0, 0);
-    this.listCamera = this.cameras.add(0, list.top, list.width, list.height);
+    this.listCamera = this.cameras.add(0, minListTop, 960, listBottom - minListTop);
+    this.placeListBelowOutcome();
     this.listCamera.ignore([title, back, this.outcome]);
     this.cameras.main.ignore(this.content);
     this.enableScroll();
@@ -136,9 +148,15 @@ export class NotificationSettingsScene extends Phaser.Scene {
     });
   }
 
+  private placeListBelowOutcome(): void {
+    const top = Math.max(minListTop, Math.ceil(this.outcome.y + this.outcome.height) + 8);
+    this.listCamera.setPosition(0, top);
+    this.listCamera.setSize(960, Math.max(0, listBottom - top));
+  }
+
   private scrollTo(scrollY: number): void {
     const height = this.content.getBounds().height;
-    this.listCamera.scrollY = Phaser.Math.Clamp(scrollY, 0, Math.max(0, height - list.height));
+    this.listCamera.scrollY = Phaser.Math.Clamp(scrollY, 0, Math.max(0, height - this.listCamera.height));
   }
 
   private async apply(visit: number, action: () => Promise<StarterNotificationSettingsView>): Promise<void> {
@@ -172,7 +190,7 @@ export class NotificationSettingsScene extends Phaser.Scene {
     const visit = this.visit;
     let y = 0;
     const line = (value: string, style: Phaser.Types.GameObjects.Text.TextStyle = textStyle) => {
-      const object = this.add.text(60, y, value, { ...style, wordWrap: { width: 840 } });
+      const object = this.add.text(60, y, value, { ...style, wordWrap: { width: listTextWidth } });
       this.content.add(object);
       y += object.height + 10;
     };
@@ -186,6 +204,7 @@ export class NotificationSettingsScene extends Phaser.Scene {
 
     // The outcome of the last tap stays in view above the list, wherever it is scrolled.
     this.outcome.setText(view.message ?? '');
+    this.placeListBelowOutcome();
     if (!view.available) {
       if (view.message === undefined) {
         line(text.unavailable);

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

@@ -15,6 +15,7 @@ import type { PurchasePresentationEvent } from '@mpgd/game-runtime/ads';
 
 import { resolveStarterCommerceProducts } from './commerceProducts';
 import { createStorageMonetizationOperationStore } from './monetizationJournal';
+import { resolveStarterServerSession } from './serverSession';
 
 const productCatalog = productCatalogJson as ProductCatalog;
 
@@ -47,6 +48,7 @@ export function createStarterGameServices(input: {
   readonly analytics?: AnalyticsSink;
   readonly analyticsSessionId?: string;
 }): StarterGameServices {
+  const session = resolveStarterServerSession({ once: true });
   return createGameServicesRuntime({
     gateway: input.gateway,
     playerId: input.playerId,
@@ -64,5 +66,6 @@ export function createStarterGameServices(input: {
       ? {}
       : { baseUrl: import.meta.env.VITE_MPGD_GAME_SERVICES_URL }),
     transport: resolveGameServicesTransport(import.meta.env.VITE_MPGD_GAME_SERVICES_TRANSPORT),
+    ...(session === undefined ? {} : { getHeaders: () => session.getHeaders() }),
   });
 }

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

@@ -0,0 +1,66 @@
+import type { GameServicesHeaderResolver } from '@mpgd/game-services';
+
+/**
+ * The game's server-backed session: who is signed in to the game backend,
+ * and the `Authorization` header for that session. The starter has none, so
+ * `resolveStarterServerSession` returns `undefined`. Set yours with
+ * `setStarterServerSession`, over your own session holder and identity
+ * service. The commerce client then sends its header. In a game created with
+ * `--providers notifications`, the notifications runtime uses the same
+ * session and header for the game-services Worker's notification routes.
+ *
+ * `sessionId` must be the stable session-family id: the `sessionId` your
+ * identity service answers to the Worker's `authenticateNotificationSession`
+ * for this session's header, the same across token refreshes. Do not pass a
+ * per-token or rotating id: a `GuestSessionCoordinator` view's `sessionId`
+ * may rotate on refresh, so it is not that id.
+ */
+export interface StarterServerSession {
+  /**
+   * The signed-in player and session, or `undefined` while signed out.
+   * `sessionId` is the stable session-family id (see above).
+   */
+  current(): { readonly playerId: string; readonly sessionId: string } | undefined;
+  /** Calls `listener` when a session becomes current (sign-in, restore, account switch); returns the unsubscribe. */
+  onAuthenticated(
+    listener: (session: { readonly playerId: string; readonly sessionId: string }) => void,
+  ): () => void;
+  /** The current session's request headers, such as `{ authorization: 'Bearer …' }`. */
+  readonly getHeaders: GameServicesHeaderResolver;
+}
+
+let serverSession: StarterServerSession | undefined;
+/** Whether the commerce client read the session already: it reads it once. */
+let readOnce = false;
+
+/**
+ * The game's server-backed session; `undefined` until the game sets one with
+ * `setStarterServerSession`. `once` marks a reader that keeps what it reads
+ * (the commerce client), so a later change warns.
+ */
+export function resolveStarterServerSession(
+  options: { readonly once?: boolean } = {},
+): StarterServerSession | undefined {
+  if (options.once === true) {
+    readOnce = true;
+  }
+  return serverSession;
+}
+
+/**
+ * Sets the game's server-backed session. Call it at the top of `main.ts`,
+ * before `bootstrap()`: `createStarterGameServices` reads it once, and the
+ * notification settings and opens read it until a backend exists. Its
+ * `current()` may answer `undefined` until the player signs in. A session
+ * set after the commerce client was created does not reach that client,
+ * which this warns about.
+ */
+export function setStarterServerSession(session: StarterServerSession | undefined): void {
+  if (readOnce && session !== undefined && session !== serverSession) {
+    console.warn(
+      '[game-services] setStarterServerSession ran after the commerce client was created; '
+        + "it does not send this session's header. Call it before bootstrap().",
+    );
+  }
+  serverSession = session;
+}