@marktiderman/genesis-native 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marktiderman/genesis-native",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
@@ -42,6 +42,11 @@
       "react-native": "./src/push/index.ts",
       "import": "./dist/push.js"
     },
+    "./push-payload": {
+      "types": "./dist/push-payload.d.ts",
+      "import": "./dist/push-payload.js",
+      "default": "./dist/push-payload.js"
+    },
     "./observability": {
       "types": "./dist/observability.d.ts",
       "react-native": "./src/observability/index.ts",
@@ -56,11 +61,17 @@
       "types": "./dist/dev-warnings.d.ts",
       "react-native": "./src/dev-warnings.ts",
       "import": "./dist/dev-warnings.js"
+    },
+    "./rich-push-plugin": {
+      "types": "./dist/rich-push-plugin.d.ts",
+      "import": "./dist/rich-push-plugin.js",
+      "default": "./dist/rich-push-plugin.js"
     }
   },
   "files": [
     "dist",
     "src",
+    "ios",
     "!src/**/__tests__",
     "README.md"
   ],
@@ -68,12 +79,13 @@
     "@marktiderman/genesis-core": "^1.7.0",
     "@marktiderman/genesis-design-system": "^1.5.0",
     "@marktiderman/genesis-features": "^0.3.0",
-    "@marktiderman/genesis-ui-native": "^2.3.0"
+    "@marktiderman/genesis-ui-native": "^2.4.0"
   },
   "peerDependencies": {
     "@tanstack/query-async-storage-persister": "^5.0.0",
     "@tanstack/query-persist-client-core": "^5.0.0",
     "@tanstack/react-query": "^5.0.0",
+    "expo": ">=54",
     "react": "^19.0.0",
     "react-native": ">=0.76.0",
     "react-native-safe-area-context": ">=4.0.0"
@@ -88,9 +100,15 @@
     "@tanstack/query-persist-client-core": {
       "optional": true
     },
+    "expo": {
+      "optional": true
+    },
     "expo-application": {
       "optional": true
     },
+    "expo-notifications": {
+      "optional": true
+    },
     "expo-observe": {
       "optional": true
     },
@@ -99,9 +117,6 @@
     },
     "expo-updates": {
       "optional": true
-    },
-    "expo-notifications": {
-      "optional": true
     }
   },
   "devDependencies": {
@@ -111,6 +126,7 @@
     "@tanstack/react-query": "^5.75.0",
     "@testing-library/react": "^16.3.2",
     "@types/react": "^19.2.14",
+    "expo": "~58.0.19",
     "happy-dom": "^20.9.0",
     "react": "^19.2.5",
     "react-dom": "^19.2.5",

package/src/plugin/rich-push.ts

@@ -0,0 +1,312 @@
+/**
+ * `@marktiderman/genesis-native/rich-push-plugin`: the Expo config plugin for
+ * iOS rich push. It adds a Notification Service Extension target (the Swift in
+ * `ios/notification-service/`) that downloads `data.image` / `data.senderAvatar`
+ * and turns `messages` pushes into Communication Notifications (the sender's
+ * photo, Focus treats them as messages), and it sets what they need:
+ *
+ * - the app: `com.apple.developer.usernotifications.communication` and
+ *   `NSUserActivityTypes: [INSendMessageIntent]`;
+ * - the extension: its own bundle id (`<app>.NotificationService`), Info.plist
+ *   and entitlements, embedded in the app;
+ * - EAS: `extra.eas.build.experimental.ios.appExtensions`, so EAS Build makes
+ *   the extension's provisioning profile with the app's.
+ *
+ *   plugins: [..., "@marktiderman/genesis-cli", "@marktiderman/genesis-native/rich-push-plugin"]
+ *
+ * List it after any plugin that changes the bundle id (the Genesis plugin's
+ * APP_VARIANT suffix): the extension's id is the app's plus a suffix, read
+ * when this plugin runs. Running it twice changes nothing.
+ */
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+// Expo's own copy (the app's `expo`), so the mods run on the same config-plugins as prebuild.
+import { withDangerousMod, withXcodeProject, type ConfigPlugin } from "expo/config-plugins";
+import type { ExpoConfig } from "expo/config";
+
+export const COMMUNICATION_ENTITLEMENT = "com.apple.developer.usernotifications.communication";
+export const SEND_MESSAGE_INTENT = "INSendMessageIntent";
+export const DEFAULT_TARGET_NAME = "GenesisNotificationService";
+export const DEFAULT_BUNDLE_SUFFIX = "NotificationService";
+const SWIFT_FILE = "NotificationService.swift";
+
+export interface RichPushPluginOptions {
+  /** The extension's Xcode target and folder under ios/. Default `GenesisNotificationService`. */
+  targetName?: string;
+  /** Appended to the app's bundle id with a dot. Default `NotificationService`. */
+  bundleIdSuffix?: string;
+  /**
+   * Communication Notifications (the sender's photo, Focus): the entitlement and
+   * `NSUserActivityTypes`. Default true; false keeps image attachments only.
+   */
+  communication?: boolean;
+  /** The extension's minimum iOS. Default: the app target's. */
+  deploymentTarget?: string;
+  /**
+   * The hosts images may be downloaded from (`cdn.example.com`, or `example.com`
+   * for it and its subdomains). Unset, any https host: a sender who puts a URL
+   * a person chose (their avatar) in a push lets that host see each delivery.
+   */
+  imageHosts?: string[];
+}
+
+interface Resolved {
+  targetName: string;
+  bundleIdSuffix: string;
+  communication: boolean;
+  deploymentTarget: string | undefined;
+  imageHosts: string[];
+}
+
+function resolve(options: RichPushPluginOptions | undefined): Resolved {
+  const targetName = options?.targetName ?? DEFAULT_TARGET_NAME;
+  const bundleIdSuffix = options?.bundleIdSuffix ?? DEFAULT_BUNDLE_SUFFIX;
+  if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(targetName)) throw new Error(`rich-push-plugin: targetName "${targetName}" must be letters, digits and _`);
+  if (!/^[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)*$/.test(bundleIdSuffix)) throw new Error(`rich-push-plugin: bundleIdSuffix "${bundleIdSuffix}" isn't a bundle id part`);
+  const imageHosts = (options?.imageHosts ?? []).map((h) => h.trim().toLowerCase());
+  for (const h of imageHosts) if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(h)) throw new Error(`rich-push-plugin: imageHosts "${h}" isn't a host name`);
+  return { targetName, bundleIdSuffix, communication: options?.communication ?? true, deploymentTarget: options?.deploymentTarget, imageHosts };
+}
+
+/** The extension's bundle id: the app's plus the suffix. */
+export function extensionBundleId(appBundleId: string, suffix = DEFAULT_BUNDLE_SUFFIX): string {
+  return `${appBundleId}.${suffix}`;
+}
+
+/** The extension's entitlements (also what EAS provisions it with). */
+export function extensionEntitlements(communication: boolean): Record<string, unknown> {
+  return communication ? { [COMMUNICATION_ENTITLEMENT]: true } : {};
+}
+
+/**
+ * The config-time part, visible in `expo config`: the app's entitlement and
+ * `NSUserActivityTypes`, and the extension for EAS. Fills gaps and appends;
+ * never removes what the app set.
+ */
+export function applyRichPushConfig(config: ExpoConfig, options?: RichPushPluginOptions): ExpoConfig {
+  const o = resolve(options);
+  const bundleId = config.ios?.bundleIdentifier;
+  if (!bundleId) throw new Error("rich-push-plugin: ios.bundleIdentifier is required (the extension's id is built from it)");
+  const ios = { ...config.ios };
+  if (o.communication) {
+    ios.entitlements = { ...ios.entitlements, [COMMUNICATION_ENTITLEMENT]: true };
+    const types = Array.isArray(ios.infoPlist?.NSUserActivityTypes) ? (ios.infoPlist!.NSUserActivityTypes as unknown[]) : [];
+    ios.infoPlist = { ...ios.infoPlist, NSUserActivityTypes: types.includes(SEND_MESSAGE_INTENT) ? types : [...types, SEND_MESSAGE_INTENT] };
+  }
+  const extra = { ...config.extra };
+  const eas = { ...(extra.eas as Record<string, unknown> | undefined) };
+  const build = { ...(eas.build as Record<string, unknown> | undefined) };
+  const experimental = { ...(build.experimental as Record<string, unknown> | undefined) };
+  const easIos = { ...(experimental.ios as Record<string, unknown> | undefined) };
+  const existing = Array.isArray(easIos.appExtensions) ? (easIos.appExtensions as { targetName?: string }[]) : [];
+  const entry = { targetName: o.targetName, bundleIdentifier: extensionBundleId(bundleId, o.bundleIdSuffix), entitlements: extensionEntitlements(o.communication) };
+  easIos.appExtensions = [...existing.filter((e) => e?.targetName !== o.targetName), entry];
+  extra.eas = { ...eas, build: { ...build, experimental: { ...experimental, ios: easIos } } };
+  return { ...config, ios, extra };
+}
+
+/** The extension's Info.plist. Versions follow the app's (App Store Connect rejects a mismatch). */
+export function extensionInfoPlist(displayName: string, options: { communication?: boolean; imageHosts?: string[] } = {}): string {
+  const esc = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleDevelopmentRegion</key>
+  <string>$(DEVELOPMENT_LANGUAGE)</string>
+  <key>CFBundleDisplayName</key>
+  <string>${esc(displayName)}</string>
+  <key>CFBundleExecutable</key>
+  <string>$(EXECUTABLE_NAME)</string>
+  <key>CFBundleIdentifier</key>
+  <string>$(PRODUCT_BUNDLE_IDENTIFIER)</string>
+  <key>CFBundleInfoDictionaryVersion</key>
+  <string>6.0</string>
+  <key>CFBundleName</key>
+  <string>$(PRODUCT_NAME)</string>
+  <key>CFBundlePackageType</key>
+  <string>$(PRODUCT_BUNDLE_PACKAGE_TYPE)</string>
+  <key>CFBundleShortVersionString</key>
+  <string>$(MARKETING_VERSION)</string>
+  <key>CFBundleVersion</key>
+  <string>$(CURRENT_PROJECT_VERSION)</string>
+  <key>NSExtension</key>
+  <dict>
+    <key>NSExtensionPointIdentifier</key>
+    <string>com.apple.usernotifications.service</string>
+    <key>NSExtensionPrincipalClass</key>
+    <string>$(PRODUCT_MODULE_NAME).NotificationService</string>${
+      options.communication
+        ? `
+    <key>NSExtensionAttributes</key>
+    <dict>
+      <key>IntentsSupported</key>
+      <array>
+        <string>${SEND_MESSAGE_INTENT}</string>
+      </array>
+    </dict>`
+        : ""
+    }
+  </dict>${
+    options.imageHosts?.length
+      ? `
+  <key>GenesisRichPushImageHosts</key>
+  <array>
+${options.imageHosts.map((h) => `    <string>${esc(h)}</string>`).join("\n")}
+  </array>`
+      : ""
+  }
+</dict>
+</plist>
+`;
+}
+
+export function entitlementsPlist(entitlements: Record<string, unknown>): string {
+  const body = Object.entries(entitlements)
+    .map(([k, v]) => `  <key>${k}</key>\n  <${v ? "true" : "false"}/>`)
+    .join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+${body}
+</dict>
+</plist>
+`;
+}
+
+/** This package's root, found from this file (src/plugin in tests, dist when built). */
+export function packageRoot(from = path.dirname(fileURLToPath(import.meta.url))): string {
+  let dir = from;
+  for (;;) {
+    const pkg = path.join(dir, "package.json");
+    if (existsSync(pkg) && (JSON.parse(readFileSync(pkg, "utf8")) as { name?: string }).name === "@marktiderman/genesis-native") return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new Error("rich-push-plugin: can't find @marktiderman/genesis-native's folder");
+    dir = parent;
+  }
+}
+
+/** The extension's Swift source, shipped in this package. */
+export function serviceSwiftPath(root = packageRoot()): string {
+  return path.join(root, "ios", "notification-service", SWIFT_FILE);
+}
+
+/** Writes the extension's folder under ios/: the Swift, its Info.plist and its entitlements. */
+export function writeExtensionFiles(
+  iosRoot: string,
+  options: { targetName: string; displayName: string; communication: boolean; imageHosts?: string[]; swiftSource?: string },
+): void {
+  const dir = path.join(iosRoot, options.targetName);
+  mkdirSync(dir, { recursive: true });
+  copyFileSync(options.swiftSource ?? serviceSwiftPath(), path.join(dir, SWIFT_FILE));
+  writeFileSync(path.join(dir, "Info.plist"), extensionInfoPlist(options.displayName, { communication: options.communication, imageHosts: options.imageHosts ?? [] }));
+  writeFileSync(path.join(dir, `${options.targetName}.entitlements`), entitlementsPlist(extensionEntitlements(options.communication)));
+}
+
+/** The parts of the `xcode` package's project this uses. */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type XcodeProject = any;
+
+const unquote = (v: unknown) => (typeof v === "string" ? v.replace(/^"(.*)"$/, "$1") : v);
+
+/** The app target's build setting (its first configuration that has it). */
+function appSetting(project: XcodeProject, key: string): string | undefined {
+  const app = project.getFirstTarget();
+  const listId = app?.firstTarget?.buildConfigurationList;
+  const lists = project.pbxXCConfigurationList();
+  const configs = project.pbxXCBuildConfigurationSection();
+  for (const ref of lists[listId]?.buildConfigurations ?? []) {
+    const value = configs[ref.value]?.buildSettings?.[key];
+    if (value !== undefined) return String(unquote(value));
+  }
+  return undefined;
+}
+
+/**
+ * Adds the extension target to the project (once): its group and files, the
+ * sources, frameworks and resources phases, its build settings, a dependency
+ * from the app and the app's phase that embeds it.
+ */
+export function addNotificationServiceTarget(
+  project: XcodeProject,
+  options: { targetName: string; bundleId: string; deploymentTarget?: string; developmentTeam?: string; marketingVersion?: string; buildNumber?: string },
+): { added: boolean } {
+  const { targetName } = options;
+  if (project.pbxTargetByName(targetName) || project.pbxTargetByName(`"${targetName}"`)) return { added: false };
+
+  const objects = project.hash.project.objects;
+  // The xcode package assumes these sections exist; Expo's template has none.
+  objects.PBXTargetDependency ??= {};
+  objects.PBXContainerItemProxy ??= {};
+
+  const deploymentTarget = options.deploymentTarget ?? appSetting(project, "IPHONEOS_DEPLOYMENT_TARGET") ?? "15.1";
+  const marketingVersion = options.marketingVersion ?? appSetting(project, "MARKETING_VERSION") ?? "1.0";
+  const buildNumber = options.buildNumber ?? appSetting(project, "CURRENT_PROJECT_VERSION") ?? "1";
+  const developmentTeam = options.developmentTeam ?? appSetting(project, "DEVELOPMENT_TEAM");
+
+  // The Swift is compiled; the Info.plist and entitlements are build settings, so they are in the group only.
+  const group = project.addPbxGroup([SWIFT_FILE], targetName, targetName);
+  project.addFile("Info.plist", group.uuid, { lastKnownFileType: "text.plist.xml" });
+  project.addFile(`${targetName}.entitlements`, group.uuid, { lastKnownFileType: "text.plist.entitlements" });
+  const mainGroup = project.getFirstProject().firstProject.mainGroup;
+  project.addToPbxGroup(group.uuid, mainGroup);
+
+  const target = project.addTarget(targetName, "app_extension", targetName, options.bundleId);
+  project.addBuildPhase([SWIFT_FILE], "PBXSourcesBuildPhase", "Sources", target.uuid);
+  project.addBuildPhase([], "PBXFrameworksBuildPhase", "Frameworks", target.uuid);
+  project.addBuildPhase([], "PBXResourcesBuildPhase", "Resources", target.uuid);
+
+  const configs = project.pbxXCBuildConfigurationSection();
+  const listId = target.pbxNativeTarget.buildConfigurationList;
+  for (const ref of project.pbxXCConfigurationList()[listId].buildConfigurations) {
+    const settings = configs[ref.value].buildSettings;
+    Object.assign(settings, {
+      INFOPLIST_FILE: `${targetName}/Info.plist`,
+      CODE_SIGN_ENTITLEMENTS: `${targetName}/${targetName}.entitlements`,
+      CODE_SIGN_STYLE: "Automatic",
+      IPHONEOS_DEPLOYMENT_TARGET: deploymentTarget,
+      TARGETED_DEVICE_FAMILY: '"1,2"',
+      SWIFT_VERSION: "5.0",
+      MARKETING_VERSION: marketingVersion,
+      CURRENT_PROJECT_VERSION: buildNumber,
+      GENERATE_INFOPLIST_FILE: "NO",
+      PRODUCT_BUNDLE_IDENTIFIER: `"${options.bundleId}"`,
+      SDKROOT: "iphoneos",
+      CLANG_ENABLE_MODULES: "YES",
+      SWIFT_EMIT_LOC_STRINGS: "YES",
+      ...(developmentTeam ? { DEVELOPMENT_TEAM: developmentTeam } : {}),
+    });
+  }
+  if (developmentTeam) project.addTargetAttribute("DevelopmentTeam", developmentTeam, target);
+  return { added: true };
+}
+
+const withRichPush: ConfigPlugin<RichPushPluginOptions | void> = (config, options) => {
+  const o = resolve(options ?? undefined);
+  config = applyRichPushConfig(config, o);
+  const bundleId = extensionBundleId(config.ios!.bundleIdentifier!, o.bundleIdSuffix);
+
+  config = withDangerousMod(config, [
+    "ios",
+    (c) => {
+      writeExtensionFiles(c.modRequest.platformProjectRoot, { targetName: o.targetName, displayName: c.name, communication: o.communication, imageHosts: o.imageHosts });
+      return c;
+    },
+  ]);
+  config = withXcodeProject(config, (c) => {
+    addNotificationServiceTarget(c.modResults, {
+      targetName: o.targetName,
+      bundleId,
+      ...(o.deploymentTarget ? { deploymentTarget: o.deploymentTarget } : {}),
+      ...(c.ios?.appleTeamId ? { developmentTeam: c.ios.appleTeamId } : {}),
+      ...(c.version ? { marketingVersion: c.version } : {}),
+      ...(c.ios?.buildNumber ? { buildNumber: c.ios.buildNumber } : {}),
+    });
+    return c;
+  });
+  return config;
+};
+
+export default withRichPush;

package/src/push/backend.ts

@@ -31,8 +31,16 @@ export const DEFAULT_PREFERENCES: NotificationPreferences = {
 };
 
 export interface PushBackend {
-  /** Keep this device's token against the signed-in person. */
-  register(token: string, platform: string, appVersion: string | null): Promise<void>;
+  /**
+   * Keep this device's token against the signed-in person. `installationId`
+   * is this install's random id (kept on the phone across sign-ins): a
+   * backend that checks it moves a token another login holds only when the
+   * id matches (the same phone). `supabasePushBackend` (migration 0005)
+   * doesn't send it; genesis-notifications' backend does.
+   */
+  register(token: string, platform: string, appVersion: string | null, installationId?: string): Promise<void>;
+  /** Send `installationId` to `register` (the block makes and keeps one). Default false. */
+  readonly usesInstallationId?: boolean;
   /** Forget this device's token; works signed out (holding the token is the proof). */
   forget(token: string): Promise<void>;
   /** The signed-in person's preferences, or `null` before they have saved any. */

package/src/push/block.tsx

@@ -65,6 +65,20 @@ export interface PushChannel {
   importance?: ChannelImportance;
 }
 
+/** A notification category and its buttons. */
+export interface PushDeviceCategory {
+  identifier: string;
+  actions: readonly {
+    id: string;
+    title: string;
+    textInput?: { placeholder?: string; submitTitle?: string };
+    opensApp?: boolean;
+    destructive?: boolean;
+    requiresAuth?: boolean;
+  }[];
+  previewPlaceholder?: string;
+}
+
 // A type, not an interface, so it fits the slots contract's Record constraint.
 export type PushSlots = {
   /** The soft pre-prompt, shown after `usePushPrompt().offer()`. Default `PushPromptSheet`. */
@@ -86,6 +100,15 @@ export interface PushOptions {
   categories?: readonly NotificationCategory[];
   /** More Android channels. A `default` channel is always made. */
   channels?: readonly PushChannel[];
+  /**
+   * Notification categories with action buttons (Reply, Mark as read),
+   * registered on the device when the block starts. A push names one in its
+   * `categoryId`; a tap on a button reaches `onResponse` (`notificationAction`
+   * reads it). genesis-notifications' registry makes these (`deviceCategories()`).
+   */
+  deviceCategories?: readonly PushDeviceCategory[];
+  /** Makes this install's id, for a backend that uses one (`usesInstallationId`). Default `crypto.randomUUID`; pass expo-crypto's on Hermes. */
+  randomUUID?: () => string;
   /** AsyncStorage: this device's token (to forget it after sign-out), the prompt's "Not now"s. */
   storage?: PushStorageLike;
   /** `AppState`: read the permission again on coming to the front (the person may have changed it in Settings). */
@@ -195,6 +218,31 @@ export function createPush(options: PushOptions): PushBlock {
     return channelsMade;
   };
 
+  let categoriesMade = false;
+  const registerDeviceCategories = async () => {
+    const set = notifications?.setNotificationCategoryAsync;
+    if (categoriesMade || !notifications || !set || !options.deviceCategories?.length) return;
+    categoriesMade = true;
+    for (const c of options.deviceCategories) {
+      try {
+        await set.call(
+          notifications,
+          c.identifier,
+          c.actions.map((a) => ({
+            identifier: a.id,
+            buttonTitle: a.title,
+            ...(a.textInput ? { textInput: { placeholder: a.textInput.placeholder ?? "", submitButtonTitle: a.textInput.submitTitle ?? a.title } } : {}),
+            options: { opensAppToForeground: a.opensApp ?? false, isDestructive: a.destructive ?? false, isAuthenticationRequired: a.requiresAuth ?? false },
+          })),
+          c.previewPlaceholder ? { previewPlaceholder: c.previewPlaceholder } : undefined,
+        );
+      } catch (error) {
+        categoriesMade = false;
+        report(onError, error, "categories");
+      }
+    }
+  };
+
   const permission = createPermissionStore({ notifications, request: options.permissions, beforeRequest: ensureChannels, onError });
   const registration = createRegistration({
     notifications,
@@ -207,6 +255,7 @@ export function createPush(options: PushOptions): PushBlock {
     ensureChannels,
     isCurrent: (id) => userId === id,
     now,
+    randomUUID: options.randomUUID,
     onError,
   });
   const preferences = createPreferencesStore({ backend: options.backend, categories, onError });
@@ -334,9 +383,19 @@ export function createPush(options: PushOptions): PushBlock {
       });
       void registration.flush();
       void permission.refresh();
-      const tokenSubscription = notifications.addPushTokenListener(() => {
+      void registerDeviceCategories();
+      // Fetching the Expo token fetches the device token, and expo-notifications tells this listener
+      // every time, changed or not: forcing a registration on each one re-registered in a loop. The
+      // same token again is ignored; the first one seen only confirms the registration (which
+      // registers when the token differs from the saved one); a different one is a rotation.
+      let deviceToken: unknown;
+      const tokenSubscription = notifications.addPushTokenListener((token) => {
+        const next = (token as { data?: unknown } | null)?.data;
+        const seen = deviceToken;
+        deviceToken = next;
+        if (!userId || next === seen) return;
         // The OS rotated the device token: fetch the Expo token again and register it.
-        if (userId) void registration.sync(userId, { force: true });
+        void registration.sync(userId, { force: seen !== undefined });
       });
       const appSubscription = options.appState?.addEventListener("change", (state) => {
         if (state !== "active") return;

package/src/push/index.ts

@@ -28,6 +28,7 @@ export {
   useSuppressNotifications,
   type PushBlock,
   type PushChannel,
+  type PushDeviceCategory,
   type PushOptions,
   type PushRootProps,
   type PushSlots,
@@ -84,12 +85,14 @@ export {
   type PreferencesStatus,
   type PreferencesStore,
 } from "./preferences";
-export { pathForResponse, notificationData } from "./routing";
+export { richPushMessage, isRichPushUrl, RICH_PUSH_IMAGE_FIELDS, type RichPushData, type RichPushMessageLike } from "./payload";
+export { pathForResponse, notificationData, notificationAction, type NotificationAction } from "./routing";
 export { parseClock, formatClock, clockOf, dateAt, deviceTimeZone, minutesIn, isQuietAt } from "./quiet-hours";
 export type {
   ChannelInputLike,
   NotificationBehaviorLike,
   NotificationLike,
+  NotificationActionLike,
   NotificationResponseLike,
   NotificationsModuleLike,
   PermissionRequestLike,

package/src/push/modules.ts

@@ -37,6 +37,16 @@ export interface NotificationLike {
 export interface NotificationResponseLike {
   notification: NotificationLike;
   actionIdentifier: string;
+  /** What the person typed, for an action with a text input (Reply). */
+  userText?: string;
+}
+
+/** `NotificationAction` (expo-notifications 58): one button of a notification category. */
+export interface NotificationActionLike {
+  identifier: string;
+  buttonTitle: string;
+  textInput?: { placeholder: string; submitButtonTitle: string };
+  options?: { isAuthenticationRequired?: boolean; isDestructive?: boolean; opensAppToForeground?: boolean };
 }
 
 /** `NotificationBehavior` without the deprecated `shouldShowAlert`. */
@@ -73,6 +83,8 @@ export interface NotificationsModuleLike {
   getLastNotificationResponse(): NotificationResponseLike | null;
   clearLastNotificationResponse(): void;
   setBadgeCountAsync(count: number): Promise<boolean>;
+  /** Registers a notification category (its action buttons). Optional: older fakes leave it out. */
+  setNotificationCategoryAsync?(identifier: string, actions: NotificationActionLike[], options?: { previewPlaceholder?: string }): Promise<unknown>;
   getBadgeCountAsync(): Promise<number>;
   /** `"expo.modules.notifications.actions.DEFAULT"`: the person tapped the notification itself. */
   DEFAULT_ACTION_IDENTIFIER: string;
@@ -91,7 +103,7 @@ export interface PushAppStateLike {
 }
 
 /** Where a reported error came from. */
-export type PushErrorSource = "permission" | "register" | "forget" | "preferences" | "badge" | "channels" | "routing" | "storage" | "setup";
+export type PushErrorSource = "permission" | "register" | "forget" | "preferences" | "badge" | "channels" | "categories" | "routing" | "storage" | "setup";
 
 export type PushOnError = (error: Error, source: PushErrorSource) => void;
 

package/src/push/payload.ts

@@ -0,0 +1,61 @@
+/**
+ * Rich push payloads: what a sender adds to an Expo push message so the iOS
+ * Notification Service Extension (`@marktiderman/genesis-native/rich-push-plugin`)
+ * runs on it. No React, no React Native, no Node APIs: a server, an edge
+ * function or Deno imports it from `@marktiderman/genesis-native/push-payload`.
+ *
+ *   await expo.send([richPushMessage({ to, title, body, data: { url } }, { image })]);
+ *
+ * iOS runs the extension only when the push says `mutable-content: 1`, which
+ * Expo's push service sets from `mutableContent: true`. Without it the
+ * notification arrives as sent and the extension never sees it.
+ */
+
+/** The image fields the extension reads from `data`. */
+export interface RichPushData {
+  /** An https image to attach (a photo in the message). Anything but https is dropped. */
+  image?: string | null | undefined;
+  /** The sender's photo, https. On a `messages` push it is the sender's avatar; on any other it is attached. */
+  senderAvatar?: string | null | undefined;
+}
+
+/** The part of an Expo push message this touches. */
+export interface RichPushMessageLike {
+  data?: Record<string, unknown> | undefined;
+  mutableContent?: boolean | undefined;
+}
+
+export const RICH_PUSH_IMAGE_FIELDS = ["image", "senderAvatar"] as const;
+
+/**
+ * The extension downloads only https URLs (no credentials, at most 1024
+ * characters: APNs takes 4 KB in all); this is the same check. The plugin's
+ * `imageHosts`, when set, narrows it on the phone.
+ */
+export function isRichPushUrl(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > 1024) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" && url.hostname.length > 0 && !url.username && !url.password;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * The message with `mutableContent: true` and the image fields in its `data`.
+ * A field given in `rich` replaces the one in `data`; one that isn't an https
+ * URL is left out (the extension would ignore it). `data`'s other fields are
+ * kept as they are.
+ */
+export function richPushMessage<M extends RichPushMessageLike>(
+  message: M,
+  rich: RichPushData = {},
+): Omit<M, "mutableContent" | "data"> & { mutableContent: true; data: Record<string, unknown> } {
+  const data: Record<string, unknown> = { ...(message.data ?? {}) };
+  for (const key of RICH_PUSH_IMAGE_FIELDS) {
+    if (key in rich) data[key] = rich[key];
+    if (key in data && !isRichPushUrl(data[key])) delete data[key];
+  }
+  return { ...message, mutableContent: true, data };
+}