@eifi1/ui-kit 0.34.0 → 0.36.0

package/src/notifications/unsubscribe-panel.tsx

@@ -0,0 +1,203 @@
+import { useRef, useState } from "react";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+import { CheckCircle2, Link2Off } from "lucide-react";
+
+import type { LabelOverride } from "../i18n/kit-labels";
+import { cn } from "../lib/cn";
+import { errorBodyWithCode, httpStatusOf } from "../auth/auth-errors";
+import { INTRO_CLASS, OUTCOME_CLASS, STATUS_HEADING_CLASS, useFocusWhen } from "../auth/status-parts";
+import type { AuthHeadingLevel } from "../auth/status-parts";
+import { Button } from "../components/button";
+import { EmptyState } from "../components/empty-state";
+import { useMounted } from "../account/account-parts";
+import { FailureLine, useNotificationsLabels } from "./notification-parts";
+import type { NotificationsLabels } from "./notifications-labels";
+
+/** A type id, as the server's registry allows it (§2.1). */
+const TYPE_ID = /^[a-z][a-z0-9_]{1,39}$/;
+/** base64url, unpadded, as the token's `<data>` is written (§3.6). */
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+
+/**
+ * The notification type an unsubscribe token names, read from its `<data>` half —
+ * `v1.<base64url("<user_id>:<type id>")>.<mac>` (docs/notifications-harmonization.md
+ * §3.6) — or `null` for a token that does not parse. Only the claim is read: the MAC is
+ * the server's to check, so a forged token still names a type here and the server
+ * refuses it. For the page's words ("You get e-mails about: Overdue invoices").
+ */
+export function unsubscribeTokenType(token: string): string | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [version, data, mac] = parts;
+  if (version !== "v1" || !BASE64URL.test(data) || !BASE64URL.test(mac) || data.length % 4 === 1) return null;
+  let claim: string;
+  try {
+    claim = atob(data.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (data.length % 4)) % 4));
+  } catch {
+    return null;
+  }
+  const colon = claim.indexOf(":");
+  if (colon < 1) return null;
+  const type = claim.slice(colon + 1);
+  return TYPE_ID.test(type) ? type : null;
+}
+
+/** server-kit's `UnsubscribeTokenError`: 400 `{code: "unsubscribe_invalid"}`. A body
+ *  thrown as it came, with no status, counts on its code. */
+function defaultIsInvalid(error: unknown): boolean {
+  const coded = errorBodyWithCode(error, (code) => code === "unsubscribe_invalid") !== undefined;
+  const status = httpStatusOf(error);
+  return coded && (status === undefined || status === 400);
+}
+
+export interface UnsubscribePanelProps extends Omit<ComponentPropsWithRef<"div">, "children" | "title"> {
+  /** The `token` from the page's query (`/unsubscribe?token=…`). */
+  token: string;
+  /** The app's name, for "Stop all notification e-mails from {app}". */
+  appName: string;
+  /** The type's name in the app's words, from {@link unsubscribeTokenType}. Without it
+   *  the page says only that notification mail comes. */
+  typeLabel?: string;
+  /** `POST /notifications/unsubscribe/{token}`: that type's e-mail off. */
+  onStop: (token: string) => Promise<unknown>;
+  /** `POST /notifications/unsubscribe/{token}/all`: every e-mail switch off. */
+  onStopAll: (token: string) => Promise<unknown>;
+  /** Settings → Notifications, through the provider's link component. */
+  settingsHref: string;
+  /** Whether a rejection means the link is no good. Default: a 400 with
+   *  `code: "unsubscribe_invalid"`. Anything else is "try again". */
+  isInvalid?: (error: unknown) => boolean;
+  /** The heading. Default `labels.unsubscribeTitle`; `null` draws none, for a page that
+   *  puts it in `AuthLayout`'s `title`. */
+  title?: ReactNode;
+  /** The heading's level. Default `h2`, under the page's `h1`. */
+  headingAs?: AuthHeadingLevel;
+  labels?: LabelOverride<NotificationsLabels>;
+}
+
+type Phase = "ready" | "these" | "all" | "stopped-these" | "stopped-all" | "invalid" | "failed";
+
+/**
+ * The body of an app's signed-out `/unsubscribe` page (docs/notifications-harmonization.md
+ * §3.6, §4.2) — the page a notification mail's footer links to. It works signed in or
+ * out (auth §7), and is not a card.
+ *
+ * **Nothing happens on a GET**: link scanners fetch every URL, so the page asks first —
+ * "Stop these e-mails", or "Stop all notification e-mails from {app}" — and only a press
+ * POSTs. A mail client's one-click POST goes to the server's route directly, without
+ * this page. Account mail is not a notification and keeps coming; the page says so, and
+ * then how to turn the mail back on (Settings → Notifications).
+ *
+ * A token that does not parse is "this link doesn't work" at once, with no request; the
+ * server's refusal (`unsubscribe_invalid`) says the same. Any other failure is "try
+ * again", the buttons still there. A valid token always answers 200 — also when the
+ * switch was already off or the account is gone — so the done state reveals nothing.
+ */
+export function UnsubscribePanel({
+  token,
+  appName,
+  typeLabel,
+  onStop,
+  onStopAll,
+  settingsHref,
+  isInvalid = defaultIsInvalid,
+  title,
+  headingAs: Heading = "h2",
+  labels: labelsProp,
+  className,
+  ...rest
+}: UnsubscribePanelProps) {
+  const labels = useNotificationsLabels(labelsProp);
+  const parses = unsubscribeTokenType(token) !== null;
+  const [phase, setPhase] = useState<Phase>("ready");
+  const mounted = useMounted();
+  const outcomeRef = useRef<HTMLDivElement>(null);
+  const shown: Phase = parses ? phase : "invalid";
+  const done = shown === "stopped-these" || shown === "stopped-all";
+  useFocusWhen(done, outcomeRef);
+
+  const stop = (which: "these" | "all") => {
+    if (shown !== "ready" && shown !== "failed") return;
+    setPhase(which);
+    const call = which === "these" ? onStop : onStopAll;
+    call(token).then(
+      () => {
+        if (mounted.current) setPhase(which === "these" ? "stopped-these" : "stopped-all");
+      },
+      (error: unknown) => {
+        if (mounted.current) setPhase(isInvalid(error) ? "invalid" : "failed");
+      },
+    );
+  };
+
+  const settingsLink = (
+    <Button href={settingsHref} variant="secondary">
+      {labels.openSettings}
+    </Button>
+  );
+
+  let body: ReactNode;
+  if (shown === "invalid") {
+    body = (
+      <EmptyState
+        tone="danger"
+        icon={<Link2Off />}
+        title={labels.invalidLink}
+        action={settingsLink}
+        className={OUTCOME_CLASS}
+      />
+    );
+  } else if (done) {
+    body = (
+      <div ref={outcomeRef} tabIndex={-1} className="outline-none">
+        <EmptyState
+          tone="success"
+          icon={<CheckCircle2 />}
+          title={shown === "stopped-these" ? labels.stoppedThese : labels.stoppedAll(appName)}
+          hint={
+            <>
+              {labels.accountMail} {labels.turnBackOn}
+            </>
+          }
+          action={settingsLink}
+          className={OUTCOME_CLASS}
+        />
+      </div>
+    );
+  } else {
+    const working = shown === "these" || shown === "all";
+    body = (
+      <>
+        <p className={INTRO_CLASS}>{typeLabel ? labels.unsubscribeAbout(typeLabel) : labels.unsubscribeGeneric}</p>
+        <p className={INTRO_CLASS}>{labels.accountMail}</p>
+        <div className="flex flex-col gap-2 sm:flex-row sm:flex-wrap">
+          <Button
+            type="button"
+            pending={shown === "these"}
+            disabled={working && shown !== "these"}
+            onClick={() => stop("these")}
+          >
+            {labels.stopThese}
+          </Button>
+          <Button
+            type="button"
+            variant="secondary"
+            pending={shown === "all"}
+            disabled={working && shown !== "all"}
+            onClick={() => stop("all")}
+          >
+            {labels.stopAll(appName)}
+          </Button>
+        </div>
+        {shown === "failed" && <FailureLine>{labels.failed}</FailureLine>}
+      </>
+    );
+  }
+
+  return (
+    <div {...rest} data-state={shown} className={cn("space-y-3", className)}>
+      {title === null ? null : <Heading className={STATUS_HEADING_CLASS}>{title ?? labels.unsubscribeTitle}</Heading>}
+      {body}
+    </div>
+  );
+}

package/src/notifications/use-push-device.ts

@@ -0,0 +1,392 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import { useMediaQuery } from "../hooks/use-media-query";
+import { httpStatusOf } from "../auth/auth-errors";
+
+/**
+ * This browser's Web Push subscription for the signed-in account
+ * (docs/notifications-harmonization.md §2.7, §3.5, §4.2) — keksdose's
+ * `shared/push/use-push.ts`, lifted. The service worker with its `push` and
+ * `notificationclick` handlers stays the app's; this hook owns the browser's side:
+ * permission, subscribe with the server's VAPID key, register the subscription, and
+ * unsubscribe. The kit makes no request of its own: the app hands it one function per
+ * endpoint.
+ */
+
+/** The browser's notification permission, or `"unsupported"` where it has no push. */
+export type PushPermission = NotificationPermission | "unsupported";
+
+/** Why turning push on or off could not finish — a {@link PushDeviceError}'s `code`. */
+export type PushDeviceErrorCode = "no_service_worker" | "push_timeout";
+
+/**
+ * The two failures the card has words of its own for: no service worker registered (or
+ * one not ready in 10 s) — "reload and try again" — and a browser push service that did
+ * not answer in 15 s — "check your connection". Anything else is the app's request
+ * failing, rejected as it came.
+ */
+export class PushDeviceError extends Error {
+  readonly code: PushDeviceErrorCode;
+  constructor(code: PushDeviceErrorCode) {
+    super(code);
+    this.name = "PushDeviceError";
+    this.code = code;
+  }
+}
+
+/** What `register` sends: `POST /notifications/devices` (§3.5). */
+export interface PushSubscriptionInput {
+  endpoint: string;
+  keys: { p256dh: string; auth: string };
+  user_agent: string | null;
+}
+
+export interface UsePushDeviceOptions {
+  /** `GET /notifications/push-key` → its `key`; `""` when push is off on the server. */
+  pushKey: () => Promise<string>;
+  /** `POST /notifications/devices`. A 409 (another account's endpoint) is recovered
+   *  once: the hook unsubscribes and registers a fresh endpoint. */
+  register: (subscription: PushSubscriptionInput) => Promise<unknown>;
+  /** `POST /notifications/devices/unregister {endpoint}` — the endpoint never goes in a
+   *  URL. */
+  unregister: (endpoint: string) => Promise<unknown>;
+  /** `GET /notifications/devices`: the account's own list, which says whether THIS
+   *  account holds this browser's subscription. */
+  devices: () => Promise<readonly { endpoint: string }[]>;
+  /** `POST /notifications/test` → how many devices the push service accepted it for. */
+  test: () => Promise<{ sent: number }>;
+  /** Whether `register` refused another account's endpoint. Default: HTTP 409. */
+  isEndpointTaken?: (error: unknown) => boolean;
+  /** After an enable or a disable: the app refreshes its device queries. */
+  onChange?: () => void;
+}
+
+/** What {@link usePushDevice} answers. */
+export interface PushDevice {
+  /** The browser exposes service workers, `PushManager` and `Notification`. */
+  supported: boolean;
+  /** The server has VAPID keys; `undefined` until `pushKey` answered (or when it failed). */
+  configured: boolean | undefined;
+  /** Running as an installed app: `display-mode: standalone`, or iOS's
+   *  `navigator.standalone`. */
+  installed: boolean;
+  /** iPhone or iPad — where push reaches only the installed app. */
+  ios: boolean;
+  permission: PushPermission;
+  /** THIS account holds this browser's subscription. An unreachable device list falls
+   *  back to the browser's own answer. */
+  subscribed: boolean;
+  /** This browser holds a subscription that belongs to another account (two accounts in
+   *  one browser profile): `subscribed` is false, and turning on mints a fresh one. */
+  foreignSubscription: boolean;
+  /** This browser's subscription endpoint, or `null` — marks "This device" in a list. */
+  currentEndpoint: string | null;
+  /** An enable or a disable is running. */
+  busy: boolean;
+  /** Ask for permission (the browser's one prompt), subscribe and register. `false` when
+   *  the permission was not granted or push is off on the server; rejects with a
+   *  {@link PushDeviceError} or the app's request's error. */
+  enable: () => Promise<boolean>;
+  /** Tell the server first, then the browser, so a dropped device stops at once. */
+  disable: () => Promise<void>;
+  sendTest: () => Promise<{ sent: number }>;
+}
+
+/**
+ * The window event every mounted {@link usePushDevice} re-reads its state on. Fired by
+ * every enable and disable, and by `PushDevicesSetting` when it removes this device — so
+ * an app's own card on the same hook (keksdose's check-up) stays in step. The hook that
+ * fires it does not re-read: it knows what it changed. Namespaced for the kit;
+ * keksdose's was `"keksdose:push-subscription-changed"`.
+ */
+export const PUSH_SUBSCRIPTION_CHANGED = "eifi1:push-subscription-changed";
+
+/** Tell every {@link usePushDevice} that this browser's subscription changed. */
+export function notifyPushSubscriptionChanged(): void {
+  if (typeof window !== "undefined") window.dispatchEvent(new Event(PUSH_SUBSCRIPTION_CHANGED));
+}
+
+/** Whether this browser has the APIs push needs. iOS exposes them only to an INSTALLED
+ *  app (Add to Home Screen). */
+export function pushSupported(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof navigator !== "undefined" &&
+    "serviceWorker" in navigator &&
+    "PushManager" in window &&
+    "Notification" in window
+  );
+}
+
+/** iPhone or iPad. iPadOS 13+ reports itself as a Mac; the touch points tell it apart. */
+function isIos(): boolean {
+  if (typeof navigator === "undefined") return false;
+  const ua = navigator.userAgent;
+  return /iphone|ipad|ipod/i.test(ua) || (/Macintosh/.test(ua) && navigator.maxTouchPoints > 1);
+}
+
+const READY_TIMEOUT_MS = 10_000;
+const PUSH_TIMEOUT_MS = 15_000;
+
+/** `promise`, or a {@link PushDeviceError} after `ms`. The timer is cleared either way. */
+function within<T>(promise: Promise<T>, ms: number, code: PushDeviceErrorCode): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  return Promise.race([
+    promise,
+    new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new PushDeviceError(code)), ms);
+    }),
+  ]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * The active registration. `navigator.serviceWorker.ready` never settles while the origin
+ * has no registration, so a missing one fails at once, and one stuck installing fails
+ * after 10 s (keksdose: enable() hung with the button latched before its worker was
+ * served).
+ */
+async function activeRegistration(): Promise<ServiceWorkerRegistration> {
+  const existing = await navigator.serviceWorker.getRegistration();
+  if (!existing) throw new PushDeviceError("no_service_worker");
+  return within(navigator.serviceWorker.ready, READY_TIMEOUT_MS, "no_service_worker");
+}
+
+/** A VAPID public key (base64url) as the bytes `PushManager.subscribe` wants. */
+function keyBytes(key: string): Uint8Array<ArrayBuffer> {
+  const base64 = key.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (key.length % 4)) % 4);
+  const raw = atob(base64);
+  const bytes = new Uint8Array(new ArrayBuffer(raw.length));
+  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
+  return bytes;
+}
+
+/** A subscription's register body, or `null` when the browser handed back an incomplete
+ *  one. */
+function inputOf(subscription: PushSubscription): PushSubscriptionInput | null {
+  const json = subscription.toJSON();
+  const p256dh = json.keys?.p256dh;
+  const auth = json.keys?.auth;
+  if (!json.endpoint || !p256dh || !auth) return null;
+  return { endpoint: json.endpoint, keys: { p256dh, auth }, user_agent: navigator.userAgent || null };
+}
+
+const defaultEndpointTaken = (error: unknown) => httpStatusOf(error) === 409;
+
+/**
+ * This browser's push for the signed-in account. Hand it one function per endpoint
+ * (§3.8); {@link PushDeviceSetting} draws it, and an app's own card may use it too.
+ *
+ * **"Subscribed" means this account**, not "this browser holds a subscription": a
+ * browser profile's subscription has no account in it, so a second account in the same
+ * profile would read the first's as its own (keksdose). The endpoint is checked against
+ * the account's own `devices()`; when that list cannot be read (offline), the browser's
+ * answer stands — a wrong "on" costs what it did before the check, a wrong "off" invites
+ * re-subscribing a device that is fine.
+ *
+ * **A 409 from `register`** — the endpoint belongs to another account, and the server
+ * will not re-home what it cannot prove this browser holds — unsubscribes and registers
+ * a fresh endpoint, once.
+ *
+ * **Timeouts:** no registration fails at once and a worker not ready in 10 s fails, both
+ * `PushDeviceError("no_service_worker")`; the browser's subscribe and unsubscribe are cut
+ * at 15 s, `PushDeviceError("push_timeout")` — so `busy` can never latch.
+ *
+ * Every mounted hook re-reads its state on {@link PUSH_SUBSCRIPTION_CHANGED}.
+ */
+export function usePushDevice(options: UsePushDeviceOptions): PushDevice {
+  // The app's functions are usually new on every render; the effects read the latest.
+  const latest = useRef(options);
+  useEffect(() => {
+    latest.current = options;
+  });
+
+  const supported = pushSupported();
+  const ios = isIos();
+  const standalone = useMediaQuery("(display-mode: standalone)", false);
+  const installed =
+    standalone ||
+    (typeof navigator !== "undefined" && (navigator as Navigator & { standalone?: boolean }).standalone === true);
+
+  const [permission, setPermission] = useState<PushPermission>(() =>
+    supported ? Notification.permission : "unsupported",
+  );
+  const [configured, setConfigured] = useState<boolean | undefined>(undefined);
+  const [subscribed, setSubscribed] = useState(false);
+  const [foreignSubscription, setForeignSubscription] = useState(false);
+  const [currentEndpoint, setCurrentEndpoint] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+  const mounted = useRef(true);
+  // Set while this hook fires the event itself: it already knows what changed, and a
+  // re-read could only be worse — an app whose `devices()` answers from a cache would
+  // hand back the list from before the change.
+  const announcing = useRef(false);
+  const announce = useCallback(() => {
+    announcing.current = true;
+    try {
+      notifyPushSubscriptionChanged();
+    } finally {
+      announcing.current = false;
+    }
+    latest.current.onChange?.();
+  }, []);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+
+  // Whether the server has keys ("" → push is off there). Once per mount.
+  useEffect(() => {
+    if (!supported) return;
+    let cancelled = false;
+    latest.current.pushKey().then(
+      (key) => {
+        if (!cancelled) setConfigured(key !== "");
+      },
+      () => {
+        /* unknown: the card shows the ordinary states */
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [supported]);
+
+  // What this browser holds, and whether it is this account's — at mount, and whenever
+  // a subscription changes anywhere in the app.
+  useEffect(() => {
+    if (!supported) return;
+    let cancelled = false;
+    const sync = async () => {
+      try {
+        const registration = await activeRegistration();
+        const existing = await registration.pushManager.getSubscription();
+        if (cancelled) return;
+        // Read again: the person may have changed it in the browser's settings.
+        setPermission(Notification.permission);
+        if (!existing) {
+          setSubscribed(false);
+          setForeignSubscription(false);
+          setCurrentEndpoint(null);
+          return;
+        }
+        let mine: boolean;
+        try {
+          const devices = await latest.current.devices();
+          mine = devices.some((device) => device.endpoint === existing.endpoint);
+        } catch {
+          mine = true;
+        }
+        if (cancelled) return;
+        setCurrentEndpoint(existing.endpoint);
+        setSubscribed(mine);
+        setForeignSubscription(!mine);
+      } catch {
+        /* no active service worker yet: not subscribed */
+      }
+    };
+    const heard = () => {
+      if (!announcing.current) void sync();
+    };
+    void sync();
+    window.addEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+    return () => {
+      cancelled = true;
+      window.removeEventListener(PUSH_SUBSCRIPTION_CHANGED, heard);
+    };
+  }, [supported]);
+
+  const enable = useCallback(async (): Promise<boolean> => {
+    if (!supported) return false;
+    const { pushKey, register, isEndpointTaken = defaultEndpointTaken } = latest.current;
+    setBusy(true);
+    try {
+      const granted = await Notification.requestPermission();
+      if (mounted.current) setPermission(granted);
+      if (granted !== "granted") return false;
+
+      const key = await pushKey();
+      if (!key) {
+        if (mounted.current) setConfigured(false);
+        return false;
+      }
+      if (mounted.current) setConfigured(true);
+
+      const registration = await activeRegistration();
+      // The one place the browser is asked for a subscription, so the timeout and the
+      // `{userVisibleOnly, applicationServerKey}` literal are on both paths.
+      const subscribe = (reuse: boolean) =>
+        within(
+          (async () =>
+            (reuse ? await registration.pushManager.getSubscription() : null) ??
+            (await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: keyBytes(key) })))(),
+          PUSH_TIMEOUT_MS,
+          "push_timeout",
+        );
+
+      let subscription = await subscribe(true);
+      let input = inputOf(subscription);
+      if (!input) return false;
+      try {
+        await register(input);
+      } catch (error) {
+        if (!isEndpointTaken(error)) throw error;
+        await within(subscription.unsubscribe(), PUSH_TIMEOUT_MS, "push_timeout");
+        subscription = await subscribe(false);
+        input = inputOf(subscription);
+        if (!input) return false;
+        await register(input);
+      }
+      if (mounted.current) {
+        setSubscribed(true);
+        setForeignSubscription(false);
+        setCurrentEndpoint(input.endpoint);
+      }
+      announce();
+      return true;
+    } finally {
+      if (mounted.current) setBusy(false);
+    }
+  }, [supported, announce]);
+
+  const disable = useCallback(async (): Promise<void> => {
+    if (!supported) return;
+    setBusy(true);
+    try {
+      const registration = await activeRegistration();
+      const subscription = await registration.pushManager.getSubscription();
+      if (subscription) {
+        // The server first: a dropped device stops receiving even if the browser's
+        // unsubscribe below fails.
+        await latest.current.unregister(subscription.endpoint);
+        await within(subscription.unsubscribe(), PUSH_TIMEOUT_MS, "push_timeout");
+      }
+      if (mounted.current) {
+        setSubscribed(false);
+        setForeignSubscription(false);
+        setCurrentEndpoint(null);
+      }
+      announce();
+    } finally {
+      if (mounted.current) setBusy(false);
+    }
+  }, [supported, announce]);
+
+  const sendTest = useCallback(() => latest.current.test(), []);
+
+  return {
+    supported,
+    configured,
+    installed,
+    ios,
+    permission,
+    subscribed,
+    foreignSubscription,
+    currentEndpoint,
+    busy,
+    enable,
+    disable,
+    sendTest,
+  };
+}