Adding OneSignal push notifications to a Codex-built web app with WebViewGold

## Push notifications (OneSignal via WebViewGold)
- Native side: OneSignal is enabled in the WebViewGold projects
  (iOS: kPushEnabled + oneSignalID; Android: PUSH_ENABLED + ONE_SIGNAL_APP_ID).
  The first-run prompt is OFF (askforpushpermissionatfirstrun / requirePush = false).
- Never add the OneSignal Web SDK, a web push service worker or
  Notification.requestPermission(). In the app, permission is requested only by
  navigating to registerpush://, always behind isNativeApp().
- Permission status: checkNativePushPermissions:// sets window.nativePushEnabled
  (asynchronously). If false, offer a button that navigates to settingsapp://.
- Device identity: getonesignalplayerid:// sets window.onesignalplayerid
  (asynchronously; may be empty before the user allows push). Poll with a timeout.
  On iOS, combine data calls: multiapicall://getonesignalplayerid,getappversion
- Storage: pushDevices/{subscriptionId} = { uid, platform, updatedAt }.
  One user can have many devices. Delete the row on logout.
- Sending happens only on the server (server/push/send.js), with ONESIGNAL_API_KEY
  from the environment. Deep links go in data.url (opens inside the app).
  Never set OneSignal's top-level url field: that is the Launch URL and opens the browser.
- Promotional pushes need explicit opt-in in our UI and an opt-out in settings.

## Review guidelines
- P1: ONESIGNAL_API_KEY, or any call to api.onesignal.com, in client code.
- P1: a notification payload with a top-level url instead of data.url.
- P1: registerpush:// or getonesignalplayerid:// without an isNativeApp() check.

// server/push/index.js (Express + firebase-admin, Node 18+ for global fetch)
import express from "express";
import { getFirestore, FieldValue } from "firebase-admin/firestore";
import { requireUser } from "../auth/requireUser.js"; // verifies the Firebase ID token, sets req.uid

const db = getFirestore();
export const pushRouter = express.Router();

// One row per device. The document ID is the OneSignal subscription ID, so a phone
// that changes hands (logout, login as someone else) simply moves to the new user.
pushRouter.post("/api/push/devices", requireUser, express.json(), async (req, res) => {
  const { subscriptionId, platform } = req.body || {};
  if (!subscriptionId) return res.status(400).json({ error: "subscriptionId required" });
  await db.collection("pushDevices").doc(subscriptionId).set({
    uid: req.uid, platform: platform || "unknown", updatedAt: FieldValue.serverTimestamp()
  });
  res.status(204).end();
});

pushRouter.delete("/api/push/devices/:id", requireUser, async (req, res) => {
  const ref = db.collection("pushDevices").doc(req.params.id);
  const snap = await ref.get();
  if (snap.exists && snap.get("uid") === req.uid) await ref.delete();
  res.status(204).end();
});

export async function sendPushToUser(uid, { title, body, path }) {
  const devices = await db.collection("pushDevices").where("uid", "==", uid).get();
  const ids = devices.docs.map((d) => d.id);
  if (ids.length === 0) return 0;

  const res = await fetch("https://api.onesignal.com/notifications?c=push", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: "Key " + process.env.ONESIGNAL_API_KEY // server only
    },
    body: JSON.stringify({
      app_id: process.env.ONESIGNAL_APP_ID,
      target_channel: "push",
      include_subscription_ids: ids,
      headings: { en: title },
      contents: { en: body },
      // WebViewGold opens this inside the app. Not the top-level "url" (Launch URL).
      data: { url: "https://app.example.com" + path }
    })
  });
  if (!res.ok) throw new Error("OneSignal " + res.status + ": " + (await res.text()));
  return ids.length;
}