@businessdash/sdk 0.9.60 → 0.9.80

package/src/portal.ts

@@ -0,0 +1,7 @@
+/**
+ * `@businessdash/sdk/portal` — the framework-agnostic customer-portal core.
+ *
+ * @module
+ */
+
+export * from "./portal-core/index.js";

package/src/push-core/index.ts

@@ -0,0 +1,335 @@
+/**
+ * `@businessdash/sdk/push-core` — browser push, from the org's own site.
+ *
+ * ## The one architectural fact that shapes all of this
+ *
+ * A push subscription belongs to an **origin**. The service worker must be
+ * served from the domain the visitor is actually on, so a subscription minted
+ * on the platform's domain cannot deliver to someone browsing the org's site.
+ * That is why this lives in the SDK rather than in the dashboard: only code
+ * running on the org's own origin can register it.
+ *
+ * What does NOT have to be per-origin is the signing key. `applicationServerKey`
+ * only has to match whatever signs the push, so **one platform VAPID pair
+ * serves every org** — no per-org registration, no per-org credentials, nothing
+ * for an org to configure.
+ *
+ * ## Safari
+ *
+ * Safari 16+ (macOS Ventura) and iOS 16.4+ implement the standard Web Push API
+ * with VAPID — the same one used here. Apple's old Safari Push flow (a Website
+ * Push ID registered in the developer portal, a signed push package listing
+ * allowed domains) applies to macOS Safari 15 and earlier and is not used.
+ *
+ * **iOS has a real constraint though:** push only works when the site has been
+ * added to the Home Screen. A plain Safari tab on iPhone cannot receive push at
+ * all, whatever anyone configures. `pushSupport()` reports that case
+ * specifically so a UI can explain it rather than showing a button that
+ * silently fails.
+ *
+ * ## Permission is a one-shot resource
+ *
+ * A browser asks once per origin. A refusal is sticky and expensive to undo —
+ * the visitor has to find it in site settings — so `subscribeToPush()` must be
+ * called from a user gesture, after the person has been told what they are
+ * agreeing to. Prompting on page load burns the permission for that origin,
+ * permanently, for everyone who says no reflexively.
+ *
+ * @module
+ */
+
+/** What this browser can actually do. */
+export type PushSupport =
+	| { supported: true }
+	| {
+			supported: false;
+			/**
+			 * `unsupported` — no service worker or Push API at all.
+			 * `ios-needs-home-screen` — iOS Safari in a normal tab; the site must
+			 *   be added to the Home Screen first. Worth its own case because it
+			 *   is fixable by the visitor, unlike the others.
+			 * `insecure-context` — not HTTPS (localhost aside).
+			 * `server` — no `window`; nothing to do.
+			 */
+			reason:
+				| "unsupported"
+				| "ios-needs-home-screen"
+				| "insecure-context"
+				| "server";
+			message: string;
+	  };
+
+/** The bits of a `PushSubscription` the server needs, already base64url. */
+export type PushSubscriptionPayload = {
+	endpoint: string;
+	p256dh: string;
+	auth: string;
+	userAgent?: string;
+};
+
+/** A browser this person has registered. */
+export type PushDevice = {
+	id: string;
+	endpoint: string;
+	userAgent: string | null;
+	label: string | null;
+	categories: string[] | null;
+	lastSeenAt: string | null;
+	createdAt: string;
+};
+
+export type PushConfig = {
+	vapidPublicKey: string | null;
+	enabled: boolean;
+	devices: PushDevice[];
+};
+
+/**
+ * Can this browser receive push, and if not, why?
+ *
+ * Checked before rendering anything, so a visitor is never offered a button
+ * that cannot work. The iOS case in particular deserves an explanation rather
+ * than silence — "add this to your Home Screen first" is actionable, a dead
+ * button is not.
+ */
+export function pushSupport(): PushSupport {
+	if (typeof window === "undefined") {
+		return { supported: false, reason: "server", message: "Not in a browser." };
+	}
+	if (!window.isSecureContext) {
+		return {
+			supported: false,
+			reason: "insecure-context",
+			message: "Push needs HTTPS.",
+		};
+	}
+	if (!("serviceWorker" in navigator) || !("PushManager" in window)) {
+		// iOS Safari in a normal tab reports exactly this, so distinguish it —
+		// the visitor can fix theirs, and telling them "unsupported" is wrong.
+		if (isIosSafari() && !isStandalone()) {
+			return {
+				supported: false,
+				reason: "ios-needs-home-screen",
+				message:
+					"On iPhone and iPad, add this site to your Home Screen to turn on notifications.",
+			};
+		}
+		return {
+			supported: false,
+			reason: "unsupported",
+			message: "This browser doesn't support push notifications.",
+		};
+	}
+	if (isIosSafari() && !isStandalone()) {
+		return {
+			supported: false,
+			reason: "ios-needs-home-screen",
+			message:
+				"On iPhone and iPad, add this site to your Home Screen to turn on notifications.",
+		};
+	}
+	return { supported: true };
+}
+
+function isIosSafari(): boolean {
+	const ua = navigator.userAgent;
+	// iPadOS reports as Macintosh, so touch points are the tell.
+	const iOS =
+		/iPad|iPhone|iPod/.test(ua) ||
+		(/Macintosh/.test(ua) && navigator.maxTouchPoints > 1);
+	return iOS && !/CriOS|FxiOS|EdgiOS/.test(ua);
+}
+
+function isStandalone(): boolean {
+	return (
+		window.matchMedia?.("(display-mode: standalone)").matches === true ||
+		(navigator as { standalone?: boolean }).standalone === true
+	);
+}
+
+/** The permission state, without asking for it. */
+export function pushPermission(): NotificationPermission | "unsupported" {
+	if (typeof Notification === "undefined") return "unsupported";
+	return Notification.permission;
+}
+
+/**
+ * VAPID keys are base64url; `applicationServerKey` wants raw bytes.
+ *
+ * Backed by an explicit `ArrayBuffer` rather than `new Uint8Array(length)`:
+ * TypeScript's DOM types want a `BufferSource`, and a `Uint8Array` over the
+ * generic `ArrayBufferLike` (which could be a `SharedArrayBuffer`) does not
+ * satisfy it.
+ */
+function urlBase64ToUint8Array(base64: string): Uint8Array<ArrayBuffer> {
+	const padding = "=".repeat((4 - (base64.length % 4)) % 4);
+	const normalised = (base64 + padding).replace(/-/g, "+").replace(/_/g, "/");
+	const raw = atob(normalised);
+	const out = new Uint8Array(new ArrayBuffer(raw.length));
+	for (let i = 0; i < raw.length; i++) out[i] = raw.charCodeAt(i);
+	return out;
+}
+
+/** …and the reverse, for the keys the browser hands back. */
+function arrayBufferToBase64Url(buffer: ArrayBuffer | null): string {
+	if (!buffer) return "";
+	const bytes = new Uint8Array(buffer);
+	let binary = "";
+	for (const b of bytes) binary += String.fromCharCode(b);
+	return btoa(binary)
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/, "");
+}
+
+/** Flatten a `PushSubscription` into what the API stores. */
+export function toPayload(
+	subscription: PushSubscription,
+): PushSubscriptionPayload {
+	return {
+		endpoint: subscription.endpoint,
+		p256dh: arrayBufferToBase64Url(subscription.getKey("p256dh")),
+		auth: arrayBufferToBase64Url(subscription.getKey("auth")),
+		...(typeof navigator === "undefined"
+			? {}
+			: { userAgent: navigator.userAgent }),
+	};
+}
+
+export type SubscribeOptions = {
+	/** From `GET customer-portal/push`. */
+	vapidPublicKey: string;
+	/**
+	 * Path to the service worker ON YOUR ORIGIN. Defaults to `/biab-sw.js`.
+	 *
+	 * It must be served from your own domain — a worker on someone else's
+	 * cannot receive your visitors' push. Copy the one this SDK ships.
+	 */
+	serviceWorkerPath?: string;
+	/**
+	 * Scope the worker controls. Defaults to `/`.
+	 *
+	 * A worker served from a subdirectory can only claim that subdirectory
+	 * unless the response carries `Service-Worker-Allowed`, which is why the
+	 * default file sits at the root.
+	 */
+	scope?: string;
+};
+
+export type SubscribeResult =
+	| { ok: true; subscription: PushSubscriptionPayload }
+	| {
+			ok: false;
+			/**
+			 * `denied` is the expensive one: the browser will not ask again, and
+			 * the visitor has to undo it in site settings. Say so rather than
+			 * offering the button a second time.
+			 */
+			reason: "unsupported" | "denied" | "dismissed" | "failed";
+			message: string;
+	  };
+
+/**
+ * Register the service worker, ask for permission, and subscribe.
+ *
+ * **Call this from a click**, never on load. Permission is asked once per
+ * origin and a refusal is sticky, so prompting before the visitor knows what
+ * they are agreeing to spends the only chance you get.
+ *
+ * The result is a payload to POST to `customer-portal/push`; this function
+ * deliberately does not send it, so the caller keeps control of the request
+ * (its own auth, its own error handling, its own retry).
+ */
+export async function subscribeToPush(
+	options: SubscribeOptions,
+): Promise<SubscribeResult> {
+	const support = pushSupport();
+	if (!support.supported) {
+		return { ok: false, reason: "unsupported", message: support.message };
+	}
+	if (Notification.permission === "denied") {
+		return {
+			ok: false,
+			reason: "denied",
+			message:
+				"Notifications are blocked for this site. They have to be re-enabled in the browser's site settings.",
+		};
+	}
+
+	try {
+		const registration = await navigator.serviceWorker.register(
+			options.serviceWorkerPath ?? "/biab-sw.js",
+			{ scope: options.scope ?? "/" },
+		);
+		// A worker that is installing cannot take a subscription yet.
+		await navigator.serviceWorker.ready;
+
+		const permission = await Notification.requestPermission();
+		if (permission !== "granted") {
+			return {
+				ok: false,
+				// "default" means dismissed — the browser WILL ask again, so this
+				// is recoverable and should read differently from a block.
+				reason: permission === "denied" ? "denied" : "dismissed",
+				message:
+					permission === "denied"
+						? "Notifications were blocked for this site."
+						: "No answer given — you can turn notifications on any time.",
+			};
+		}
+
+		// An existing subscription is reused rather than replaced: re-subscribing
+		// mints a new endpoint and orphans the old row.
+		const existing = await registration.pushManager.getSubscription();
+		const subscription =
+			existing ??
+			(await registration.pushManager.subscribe({
+				// Required by every browser now — a subscription without it is
+				// rejected outright rather than delivered to nobody.
+				userVisibleOnly: true,
+				applicationServerKey: urlBase64ToUint8Array(options.vapidPublicKey),
+			}));
+
+		return { ok: true, subscription: toPayload(subscription) };
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "failed",
+			message:
+				error instanceof Error ? error.message : "Could not subscribe to push.",
+		};
+	}
+}
+
+/**
+ * Tear the local subscription down and return its endpoint.
+ *
+ * The endpoint is what the server keys on, and a browser unsubscribing itself
+ * knows its endpoint rather than our row id — so hand this to
+ * `DELETE customer-portal/push` to remove the matching row. Dropping only the
+ * local one leaves the server pushing into a dead endpoint until the push
+ * service reports it gone.
+ */
+export async function unsubscribeFromPush(): Promise<{
+	endpoint: string | null;
+}> {
+	if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
+		return { endpoint: null };
+	}
+	const registration = await navigator.serviceWorker.getRegistration();
+	const subscription = await registration?.pushManager.getSubscription();
+	if (!subscription) return { endpoint: null };
+	const { endpoint } = subscription;
+	await subscription.unsubscribe();
+	return { endpoint };
+}
+
+/** The current subscription, if this browser already has one. */
+export async function currentPushSubscription(): Promise<PushSubscriptionPayload | null> {
+	if (typeof navigator === "undefined" || !("serviceWorker" in navigator)) {
+		return null;
+	}
+	const registration = await navigator.serviceWorker.getRegistration();
+	const subscription = await registration?.pushManager.getSubscription();
+	return subscription ? toPayload(subscription) : null;
+}