@mpgd/cli 0.52.0 → 0.54.0

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

@@ -0,0 +1,163 @@
+import { resolveNotificationTopicsForTarget, type NotificationTopicCatalog } from '@mpgd/catalog';
+import type { NotificationTopicDeclaration } from '@mpgd/platform/notifications';
+import type { TargetConfiguredGateway } from '@mpgd/target-config';
+
+import notificationTopicsJson from '../../notifications/topics.json';
+import {
+  createStarterWorkerNotificationBackend,
+  type StarterNotificationBackend,
+} from './notificationBackend';
+import { resolveStarterServerSession } from './serverSession';
+import { routeNotificationOpens, type NotificationOpenRoutes } from './notificationOpens';
+import {
+  createStarterNotificationSettings,
+  type StarterNotificationSettings,
+} from './notificationSettings';
+
+/**
+ * The game's notification topic catalog (`notifications/topics.json`), the
+ * one source for every target's provider, the Apps in Toss wrapper, the
+ * Devvit server, and the game backend (`MPGD_NOTIFICATIONS_CATALOG`).
+ * `pnpm validate:notifications` checks it with `notifications/deployment.json`.
+ *
+ * The starter topics' purposes follow the notifications RFC (open question 1):
+ * `daily-ready` and `streak-at-risk` are `requested` reminders the player
+ * turns on, `friend-challenge` is `service`, and `events` is the sample
+ * `advertising` topic, mapped to iOS only: an Android FCM push cannot carry
+ * the opt-out action the Korean rules require yet. A topic whose copy offers a reward, a benefit, or a
+ * promotion is advertising: declare it so, never `requested`.
+ */
+export const starterNotificationCatalog = notificationTopicsJson as NotificationTopicCatalog;
+
+/** The consent text version recorded with advertising and night consent; bump it when the text changes. */
+export const starterAdvertisingConsentTextVersion = '1';
+
+/** The topics this deployment target maps, each with its mapping, as providers read them. */
+export function starterNotificationTopics(configTarget: string): readonly NotificationTopicDeclaration[] {
+  try {
+    return resolveNotificationTopicsForTarget(starterNotificationCatalog, configTarget);
+  } catch (error) {
+    // A catalog that cannot be read turns notifications off, never the game.
+    console.error('[notifications] the topic catalog could not be read.', error);
+    return [];
+  }
+}
+
+export type { StarterNotificationBackend } from './notificationBackend';
+
+/**
+ * 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.
+ *
+ * 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: TargetConfiguredGateway,
+): StarterNotificationBackend | 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),
+  });
+}
+
+/** 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<TargetConfiguredGateway, Set<string>>();
+
+/**
+ * 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 backend;
+}
+
+/** The settings screen's model for this gateway and locale. */
+export function createStarterNotificationSettingsModel(
+  platform: TargetConfiguredGateway,
+  input: { readonly locale: string },
+): StarterNotificationSettings {
+  const requestUpgrade = platform.identity.requestUpgrade?.bind(platform.identity);
+  const backend = starterNotificationBackend(platform);
+  let agreed = agreements.get(platform);
+  if (agreed === undefined) {
+    agreed = new Set<string>();
+    agreements.set(platform, agreed);
+  }
+  return createStarterNotificationSettings({
+    provider: platform.notificationsV2,
+    runtime: backend?.runtime,
+    ...(backend === undefined ? {} : { listConsent: () => backend.listConsent() }),
+    topics: starterNotificationTopics(platform.configTarget),
+    ...(starterNotificationCatalog.notices === undefined
+      ? {}
+      : { noticeCopy: starterNotificationCatalog.notices.copy }),
+    defaultLocale: starterNotificationCatalog.defaultLocale,
+    consentTextVersion: starterAdvertisingConsentTextVersion,
+    agreedThisSession: agreed,
+    // Devvit: a logged-out player logs in before the opt-in (the gateway's loginPrompt).
+    ...(requestUpgrade === undefined
+      ? {}
+      : { requestLogin: () => requestUpgrade({ reason: 'notifications' }) }),
+    locale: input.locale,
+  });
+}
+
+/**
+ * The game's one listener for notification opens (see
+ * `routeNotificationOpens` in `notificationOpens.ts`), over the runtime when
+ * the game has one, else the provider. Returns the unsubscribe.
+ */
+export function subscribeStarterNotificationOpens(
+  platform: TargetConfiguredGateway,
+  routes: NotificationOpenRoutes,
+): () => void {
+  const source = starterNotificationBackend(platform)?.runtime ?? platform.notificationsV2;
+  return source === undefined ? () => undefined : routeNotificationOpens(source, routes);
+}
+
+export { starterNotificationSettingsRoute } from './notificationOpens';

package/templates/notifications-overlay/common/tools/validate-notifications.ts

@@ -0,0 +1,75 @@
+import { readFileSync } from 'node:fs';
+
+import { validateNotificationTopicCatalog } from '@mpgd/catalog';
+import {
+  assertNotificationDeployment,
+  notificationDeploymentPlaceholders,
+  referenceNotificationProviders,
+  referenceNotificationTargetProviders,
+  type NotificationDeployment,
+} from '@mpgd/platform/notifications';
+
+// Checks notifications/topics.json against the notifications v2 rules, the
+// providers each target enables (android and ios: FCM, ait: Apps in Toss,
+// reddit: Devvit), and notifications/deployment.json, the settings the game
+// backend takes as MPGD_NOTIFICATIONS_DEPLOYMENT. Run it before every
+// release: `pnpm validate:notifications`.
+
+const gameRoot = new URL('../', import.meta.url);
+
+function readJson(relative: string): unknown {
+  return JSON.parse(readFileSync(new URL(relative, gameRoot), 'utf8')) as unknown;
+}
+
+const problems: string[] = [];
+let deployment: NotificationDeployment | undefined;
+try {
+  // Placeholders are reported below, so the catalog is still checked against
+  // the deployment's rules in the same run.
+  deployment = assertNotificationDeployment(readJson('notifications/deployment.json'), {
+    allowPlaceholders: true,
+  });
+} catch (error) {
+  problems.push(
+    `notifications/deployment.json: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+// Under the Korean rules every advertising push names its sender and their
+// phone number or address; the starter ships a placeholder contact. The game
+// backend refuses a placeholder too (`assertNotificationDeployment`), so a
+// Worker given this file would not start its notifications.
+for (const field of deployment === undefined
+  ? []
+  : notificationDeploymentPlaceholders(deployment)) {
+  problems.push(
+    field === 'advertisingSender.contact'
+      ? `notifications/deployment.json: replace the ${field} placeholder with the sender's real contact `
+        + '(a phone number or an address), which every advertising push carries.'
+      : `notifications/deployment.json: replace the ${field} placeholder with the real value.`,
+  );
+}
+const result = validateNotificationTopicCatalog(readJson('notifications/topics.json'), {
+  targetProviders: Object.fromEntries(
+    Object.entries(referenceNotificationTargetProviders).map(([target, provider]) => [
+      target,
+      referenceNotificationProviders[provider],
+    ]),
+  ),
+  ...(deployment === undefined ? {} : { deployment }),
+});
+// A refused deployment is reported above, not again as a missing one.
+problems.unshift(
+  ...result.issues
+    .filter((issue) => deployment !== undefined || !issue.path.startsWith('deployment.'))
+    .map((issue) => `${issue.path}: ${issue.message}`),
+);
+if (!result.valid || problems.length > 0) {
+  console.error(
+    `Notification settings are not ready:\n${problems.map((problem) => `- ${problem}`).join('\n')}`,
+  );
+  process.exitCode = 1;
+} else {
+  console.info(
+    `Notification topics: ${result.catalog.topics.length}; advertising rules: ${deployment?.advertisingRules ?? 'none'}.`,
+  );
+}

package/templates/notifications-overlay/lite/src/lite/notificationSettingsPanel.ts

@@ -0,0 +1,200 @@
+import {
+  starterNotificationLabelsFor,
+  type StarterNotificationSettings,
+  type StarterNotificationSettingsView,
+} from '../platform/notificationSettings';
+import {
+  createStarterNotificationSettingsModel,
+  subscribeStarterNotificationOpens,
+} from '../platform/notifications';
+import type { StarterContext } from '../runtime/gameContext';
+
+/**
+ * A minimal notification settings panel for the lite template: a button over
+ * the game opens a DOM panel with the OS or host permission, reminders, and
+ * the advertising and night consent (`notificationSettings.ts` holds the
+ * logic). Every change is a tap; no switch starts on. A notification open
+ * whose route is the settings screen (the advertising opt-out action, a
+ * consent notice) opens the panel too. Returns the disposer.
+ */
+export function mountNotificationSettingsPanel(mount: HTMLElement, context: StarterContext): () => void {
+  if (context.platform.notificationsV2 === undefined) {
+    // This target has no notifications: no button that opens an empty panel.
+    return () => undefined;
+  }
+  const text = starterNotificationLabelsFor(context.locale);
+  let settings: StarterNotificationSettings | undefined;
+  let busy = false;
+  const panel = document.createElement('div');
+  panel.setAttribute('role', 'dialog');
+  panel.setAttribute('aria-label', text.title);
+  panel.style.cssText = 'position:absolute;inset:8%;overflow:auto;padding:16px;'
+    + 'background:#0b1726;color:#d6dee8;font:14px system-ui,sans-serif;border-radius:12px;display:none;';
+  const openButton = document.createElement('button');
+  openButton.type = 'button';
+  openButton.textContent = text.title;
+  openButton.style.cssText = 'position:absolute;top:8px;right:8px;padding:8px 12px;';
+  // Taps on the panel stay out of the game's own tap handling.
+  for (const element of [panel, openButton]) {
+    element.addEventListener('pointerdown', (event) => event.stopPropagation());
+  }
+
+  const model = (): StarterNotificationSettings => {
+    settings ??= createStarterNotificationSettingsModel(context.platform, {
+      locale: context.locale,
+    });
+    return settings;
+  };
+  const apply = async (action: () => Promise<StarterNotificationSettingsView>): Promise<void> => {
+    if (busy) {
+      return;
+    }
+    busy = true;
+    try {
+      const view = await action();
+      // A panel closed or removed meanwhile shows nothing, so records nothing.
+      if (panel.style.display === 'none' || !panel.isConnected) {
+        return;
+      }
+      render(view);
+      if (view.notices.length > 0) {
+        // Recorded in the background: taps need not wait for it.
+        void model().recordNoticesShown();
+      }
+    } catch (error) {
+      // The model reports its own failures as messages; anything else is logged.
+      console.error('[notifications] settings panel failed.', error);
+    } finally {
+      busy = false;
+    }
+  };
+  const button = (label: string, run: () => Promise<StarterNotificationSettingsView>): HTMLButtonElement => {
+    const element = document.createElement('button');
+    element.type = 'button';
+    element.textContent = label;
+    element.style.display = 'block';
+    element.style.margin = '6px 0';
+    element.addEventListener('click', () => {
+      void apply(run);
+    });
+    return element;
+  };
+  const paragraph = (value: string): HTMLParagraphElement => {
+    const element = document.createElement('p');
+    element.textContent = value;
+    // Notices put their title and body on two lines.
+    element.style.whiteSpace = 'pre-line';
+    return element;
+  };
+  const render = (view: StarterNotificationSettingsView): void => {
+    const current = model();
+    const close = document.createElement('button');
+    close.type = 'button';
+    close.textContent = text.close;
+    close.addEventListener('click', () => {
+      panel.style.display = 'none';
+    });
+    const children: HTMLElement[] = [close];
+    if (!view.available) {
+      children.push(paragraph(view.message ?? text.unavailable));
+      panel.replaceChildren(...children);
+      return;
+    }
+    if (!view.permission.perTopic) {
+      children.push(
+        paragraph(view.permission.state === 'granted' ? text.permissionOn : text.permissionOff),
+      );
+      if (view.permission.canRequest) {
+        // Explain before the one-shot OS prompt; the prompt runs only from the tap below.
+        children.push(paragraph(text.explanation));
+        children.push(button(text.turnOn, () => current.turnOn()));
+      }
+      if (view.permission.canLogin) {
+        children.push(button(text.logIn, () => current.logIn()));
+      }
+      if (view.permission.canOpenSettings) {
+        children.push(button(text.openSettings, () => current.openSettings()));
+      }
+      if (view.permission.canRevoke) {
+        children.push(button(text.turnOff, () => current.turnOff()));
+      }
+    }
+    if (!view.recording && (view.reminders.length > 0 || view.advertising !== undefined)) {
+      // No switch without the player's records: it could not show or change the truth.
+      children.push(
+        paragraph(view.choices === 'unreadable' ? text.choicesUnreadable : text.notConnected),
+      );
+    } else if (view.reminders.length > 0) {
+      children.push(paragraph(text.reminders));
+      for (const reminder of view.reminders) {
+        children.push(
+          button(`${reminder.label}: ${reminder.enabled ? text.on : text.off}`, () =>
+            current.setReminder(reminder.topic, !reminder.enabled),
+          ),
+        );
+      }
+    }
+    if (view.agreements.length > 0) {
+      // Per-topic hosts (Apps in Toss): service messages the player agrees to
+      // one by one; the host's settings withdraw them.
+      children.push(paragraph(text.agreements));
+      for (const agreement of view.agreements) {
+        const state = agreement.state === 'granted' ? text.on : text.off;
+        children.push(
+          agreement.canRequest
+            ? button(`${agreement.label}: ${state} - ${text.agree}`, () =>
+                current.agree(agreement.topic),
+              )
+            : paragraph(`${agreement.label}: ${state}`),
+        );
+      }
+    }
+    if (view.recording && view.advertising !== undefined) {
+      const { granted, night, nightSelectable } = view.advertising;
+      children.push(
+        button(`${text.advertising}: ${granted ? text.on : text.off}`, () =>
+          current.setAdvertising({ advertising: !granted }),
+        ),
+      );
+      children.push(paragraph(text.advertisingHelp));
+      const nightSwitch = button(`${text.night}: ${night ? text.on : text.off}`, () =>
+        current.setAdvertising({ night: !night }),
+      );
+      // Night consent adds to advertising consent: not selectable without it.
+      nightSwitch.disabled = !nightSelectable;
+      children.push(nightSwitch);
+      if (!nightSelectable) {
+        children.push(paragraph(text.nightNeedsAdvertising));
+      }
+    }
+    if (view.notices.length > 0) {
+      children.push(paragraph(text.notices));
+      for (const notice of view.notices) {
+        children.push(paragraph(`${notice.title}\n${notice.body}`));
+      }
+    }
+    if (view.message !== undefined) {
+      children.push(paragraph(view.message));
+    }
+    panel.replaceChildren(...children);
+  };
+
+  const open = (): void => {
+    panel.style.display = 'block';
+    const current = model();
+    void apply(() => current.load());
+  };
+  openButton.addEventListener('click', open);
+  // The game's one listener for opens, which receives a cold-start open:
+  // route your other topics' opens in `other` here.
+  const unsubscribe = subscribeStarterNotificationOpens(context.platform, { settings: open });
+  if (getComputedStyle(mount).position === 'static') {
+    mount.style.position = 'relative';
+  }
+  mount.append(openButton, panel);
+  return () => {
+    unsubscribe();
+    openButton.remove();
+    panel.remove();
+  };
+}