@businessdash/sdk 0.9.60 → 0.9.70

package/src/notifications-core/index.ts

@@ -0,0 +1,650 @@
+/**
+ * `@businessdash/sdk/notifications` — one hook, every notification.
+ *
+ * ## The problem this solves
+ *
+ * BusinessDash raises a lot of notifications: an order ships, an invoice is
+ * paid, a technician is dispatched, staff reply to a message, a quote expires.
+ * Before this, a site that wanted to surface any of them had to know each one
+ * existed, find the call that returns it, poll it, diff it, and write a toast —
+ * per event type. Sites did two of them and missed the rest, and every new
+ * platform event was a change every consumer had to make.
+ *
+ * So the SDK inverts it. Attach ONE handler and receive everything, already
+ * normalised to a single shape:
+ *
+ * ```ts
+ * const feed = createNotificationFeed({ portal });
+ * feed.subscribe((n) => toast(n.title, { description: n.body }));
+ * feed.start();
+ * ```
+ *
+ * That is the entire integration. New platform events arrive through the same
+ * handler with no code change, because nothing in the consumer's code names an
+ * event type.
+ *
+ * ## We do not ship a toast
+ *
+ * Deliberately. A notification component is one of the most branded things on a
+ * site — position, motion, stacking, dismiss behaviour, dark mode — and an SDK
+ * that renders its own is one a designer has to fight. This produces normalised
+ * DATA and stops there; the consumer keeps their own component and their own
+ * design. `toToast()` flattens to the shape sonner, react-hot-toast, Vue Toast
+ * and friends all accept, for the common case where a straight mapping is all
+ * anyone wants.
+ *
+ * ## Where notifications actually come from
+ *
+ * Two sources, and they behave differently enough to be worth knowing:
+ *
+ * - **Push** (`pushSource`) — the service worker relays what it received to any
+ *   open tab. Instant, but only while a tab is open; when the site is closed
+ *   the OS notification IS the delivery and no toast is possible or wanted.
+ * - **Polling** (`portalSource`) — watches the signed-in customer's portal and
+ *   raises a notification when something it tracks changes. Works without push
+ *   permission, which matters because most visitors never grant it.
+ *
+ * Both feed one stream, and **the same event routinely arrives twice** — push
+ * is instant, the poll notices the same change seconds later. Toasting it twice
+ * is the obvious bug, so the feed deduplicates on a stable id before any
+ * handler sees it. That deduplication is the main reason this is a shared
+ * component rather than a snippet in a README.
+ *
+ * @module
+ */
+
+import type { PortalController } from "../portal-core/index.js";
+
+/** The six the platform sends. Open, because the list grows. */
+export type NotificationCategory =
+	| "transactional"
+	| "account"
+	| "messages"
+	| "product_updates"
+	| "marketing"
+	| "digest"
+	| (string & {});
+
+/**
+ * One notification, whatever it came from.
+ *
+ * The shape is deliberately small and toast-shaped. Anything specific to an
+ * event type lives in `data` rather than growing this — a consumer that never
+ * looks at `data` still renders every notification correctly, which is the
+ * whole promise.
+ */
+export type BusinessDashNotification = {
+	/**
+	 * Stable across sources. Two deliveries of one event share it, which is
+	 * what makes deduplication work — see `dedupeKey` below for how it is
+	 * derived when the source does not supply one.
+	 */
+	id: string;
+	/** Where this delivery came from. Rarely interesting; occasionally is. */
+	source: "push" | "poll" | "local";
+	category: NotificationCategory;
+	/**
+	 * A dotted event name — `order.shipped`, `invoice.paid`, `message.received`.
+	 *
+	 * Provided so a consumer CAN special-case one event. Nobody has to: the
+	 * title and body are always populated.
+	 */
+	kind: string;
+	title: string;
+	body: string | null;
+	/** Where the notification points. Render as the toast's action. */
+	url: string | null;
+	/**
+	 * Maps to whatever a toast library calls its variants.
+	 *
+	 * `success` is used sparingly — a shipped order is `info`, not a
+	 * celebration. `error` means something needs the customer to act.
+	 */
+	severity: "info" | "success" | "warning" | "error";
+	/** ISO 8601. When the event happened, not when this tab noticed it. */
+	occurredAt: string;
+	/** Which company it came from. Null for platform-level notices. */
+	orgId: string | null;
+	/** Everything event-specific: order id, invoice number, ETA, and so on. */
+	data: Record<string, unknown>;
+};
+
+/** Everything except what the feed fills in. */
+export type NotificationInput = Partial<BusinessDashNotification> &
+	Pick<BusinessDashNotification, "title">;
+
+export type NotificationHandler = (
+	notification: BusinessDashNotification,
+) => void;
+
+/**
+ * A place notifications come from.
+ *
+ * Called with an `emit` and returns its own teardown. Consumers can write one
+ * to bring in a channel the SDK does not know about — a websocket, an SSE
+ * stream, their own backend — and it joins the same deduplicated feed.
+ */
+export type NotificationSource = (
+	emit: (input: NotificationInput) => void,
+) => () => void;
+
+export type NotificationFeedOptions = {
+	/**
+	 * A portal controller to watch. Shorthand for adding `portalSource`.
+	 *
+	 * Optional: a marketing site with no signed-in customer still receives push
+	 * notifications, and still wants them toasted.
+	 */
+	portal?: PortalController;
+	/** How often to poll the portal. Default 60s; floor 15s. */
+	pollIntervalMs?: number;
+	/** Extra sources, including your own. */
+	sources?: NotificationSource[];
+	/**
+	 * How long an id is remembered for deduplication. Default 5 minutes.
+	 *
+	 * Long enough to cover push and the next poll seeing the same event; short
+	 * enough that a genuinely repeated notification hours later still shows.
+	 */
+	dedupeWindowMs?: number;
+	/** How many to keep for `recent()`. Default 50. */
+	historyLimit?: number;
+	/**
+	 * Suppress the OS notification when a tab is already focused.
+	 *
+	 * Off by default. A push MUST show a system notification — browsers revoke
+	 * permission from sites that receive pushes silently — so this closes it
+	 * immediately after, which is a different thing from never showing it and
+	 * is visible as a brief flash on some platforms. Worth it when a toast has
+	 * already said the same thing; not worth it otherwise.
+	 */
+	closeOsNotificationWhenFocused?: boolean;
+	onError?: (error: Error) => void;
+};
+
+export type NotificationFeed = {
+	/**
+	 * Attach a handler. Returns its own unsubscribe.
+	 *
+	 * **Past notifications are NOT replayed.** A toast is a moment, and
+	 * replaying a morning's worth on every mount would fire a stack of stale
+	 * toasts each time someone navigates. Use `recent()` to render a bell or an
+	 * inbox, where showing history is the point.
+	 */
+	subscribe(handler: NotificationHandler): () => void;
+	/**
+	 * Raise a notification from your own code.
+	 *
+	 * It goes through the same deduplication and the same handlers, so an app
+	 * can route its own messages through one component instead of two.
+	 */
+	emit(input: NotificationInput): void;
+	/** Begin listening and polling. Idempotent. */
+	start(): void;
+	/** Stop, without dropping handlers. `start()` resumes. */
+	stop(): void;
+	/** Newest first, capped at `historyLimit`. */
+	recent(): BusinessDashNotification[];
+	/** Stop everything and drop handlers. */
+	destroy(): void;
+};
+
+/**
+ * The id used for deduplication when a source does not supply one.
+ *
+ * Push carries a server-assigned id and this is not needed. Polling has no id
+ * to carry — it inferred the event by noticing a value changed — so the key is
+ * built from what identifies the event rather than the delivery: kind, org, and
+ * whatever the source put in `data.entityId`.
+ *
+ * `occurredAt` is deliberately NOT part of it. A poll timestamps at discovery,
+ * push at send; including either would make two deliveries of one event look
+ * like two events, which is exactly the bug this exists to prevent.
+ */
+function dedupeKey(input: NotificationInput): string {
+	if (input.id) return input.id;
+	const entity =
+		typeof input.data?.entityId === "string" ? input.data.entityId : "";
+	return [input.kind ?? "unknown", input.orgId ?? "", entity, input.title].join(
+		"|",
+	);
+}
+
+/**
+ * Build the feed.
+ *
+ * Nothing runs until `start()`, so a controller can be constructed during
+ * render without a component mount kicking off a poll.
+ */
+export function createNotificationFeed(
+	options: NotificationFeedOptions = {},
+): NotificationFeed {
+	const handlers = new Set<NotificationHandler>();
+	const history: BusinessDashNotification[] = [];
+	/** id → when it was seen, so the window can be pruned. */
+	const seen = new Map<string, number>();
+	const teardowns: Array<() => void> = [];
+
+	const dedupeWindowMs = options.dedupeWindowMs ?? 5 * 60 * 1000;
+	const historyLimit = options.historyLimit ?? 50;
+	let running = false;
+	let destroyed = false;
+
+	function fail(cause: unknown): void {
+		options.onError?.(
+			cause instanceof Error ? cause : new Error(String(cause)),
+		);
+	}
+
+	function deliver(input: NotificationInput): void {
+		if (destroyed) return;
+
+		const key = dedupeKey(input);
+		const now = Date.now();
+
+		// Prune first, so a long-lived page does not accumulate keys forever.
+		for (const [id, at] of seen) {
+			if (now - at > dedupeWindowMs) seen.delete(id);
+		}
+		if (seen.has(key)) return;
+		seen.set(key, now);
+
+		const notification: BusinessDashNotification = {
+			id: input.id ?? key,
+			source: input.source ?? "local",
+			category: input.category ?? "transactional",
+			kind: input.kind ?? "notification",
+			title: input.title,
+			body: input.body ?? null,
+			url: input.url ?? null,
+			severity: input.severity ?? "info",
+			occurredAt: input.occurredAt ?? new Date(now).toISOString(),
+			orgId: input.orgId ?? null,
+			data: input.data ?? {},
+		};
+
+		history.unshift(notification);
+		if (history.length > historyLimit) history.length = historyLimit;
+
+		for (const handler of handlers) {
+			// One handler throwing must not stop the others, or a broken toast
+			// in one component silences every notification on the page.
+			try {
+				handler(notification);
+			} catch (cause) {
+				fail(cause);
+			}
+		}
+	}
+
+	return {
+		subscribe(handler) {
+			handlers.add(handler);
+			return () => {
+				handlers.delete(handler);
+			};
+		},
+
+		emit(input) {
+			deliver({ ...input, source: input.source ?? "local" });
+		},
+
+		start() {
+			if (running || destroyed) return;
+			running = true;
+
+			const sources: NotificationSource[] = [
+				pushSource({
+					...(options.closeOsNotificationWhenFocused === undefined
+						? {}
+						: {
+								closeOsNotificationWhenFocused:
+									options.closeOsNotificationWhenFocused,
+							}),
+					onError: fail,
+				}),
+				...(options.portal
+					? [
+							portalSource({
+								portal: options.portal,
+								...(options.pollIntervalMs === undefined
+									? {}
+									: { intervalMs: options.pollIntervalMs }),
+							}),
+						]
+					: []),
+				...(options.sources ?? []),
+			];
+
+			for (const source of sources) {
+				try {
+					teardowns.push(source(deliver));
+				} catch (cause) {
+					fail(cause);
+				}
+			}
+		},
+
+		stop() {
+			running = false;
+			while (teardowns.length) {
+				try {
+					teardowns.pop()?.();
+				} catch (cause) {
+					fail(cause);
+				}
+			}
+		},
+
+		recent() {
+			return [...history];
+		},
+
+		destroy() {
+			this.stop();
+			destroyed = true;
+			handlers.clear();
+			history.length = 0;
+			seen.clear();
+		},
+	};
+}
+
+/**
+ * Push notifications relayed by the service worker, for tabs that are open.
+ *
+ * The worker shipped at `@businessdash/sdk/biab-sw.js` posts every push to its
+ * clients. A worker written by hand has to do the same — post
+ * `{ type: "businessdash:push", payload }` — or this source hears nothing.
+ */
+export function pushSource(
+	options: {
+		closeOsNotificationWhenFocused?: boolean;
+		onError?: (error: Error) => void;
+	} = {},
+): NotificationSource {
+	return (emit) => {
+		if (
+			typeof navigator === "undefined" ||
+			!("serviceWorker" in navigator) ||
+			typeof window === "undefined"
+		) {
+			return () => undefined;
+		}
+
+		const listener = (event: MessageEvent) => {
+			const message = event.data as
+				| { type?: string; payload?: Record<string, unknown> }
+				| undefined;
+			if (message?.type !== "businessdash:push" || !message.payload) return;
+
+			const payload = message.payload;
+			const data =
+				typeof payload.data === "object" && payload.data !== null
+					? (payload.data as Record<string, unknown>)
+					: {};
+
+			emit({
+				...(typeof payload.id === "string" ? { id: payload.id } : {}),
+				source: "push",
+				...(typeof payload.category === "string"
+					? { category: payload.category }
+					: {}),
+				...(typeof payload.kind === "string" ? { kind: payload.kind } : {}),
+				title:
+					typeof payload.title === "string" ? payload.title : "Notification",
+				body: typeof payload.body === "string" ? payload.body : null,
+				url: typeof payload.url === "string" ? payload.url : null,
+				...(typeof payload.orgId === "string" ? { orgId: payload.orgId } : {}),
+				...(typeof payload.occurredAt === "string"
+					? { occurredAt: payload.occurredAt }
+					: {}),
+				data,
+			});
+
+			if (
+				options.closeOsNotificationWhenFocused &&
+				document.visibilityState === "visible"
+			) {
+				// The system notification has already been shown — required, and
+				// not optional. Closing it here trades a brief flash for not
+				// saying the same thing twice to someone who is looking at the
+				// page. See `closeOsNotificationWhenFocused` for why it is off
+				// by default.
+				navigator.serviceWorker.ready
+					.then((registration) =>
+						registration.getNotifications(
+							typeof payload.tag === "string" ? { tag: payload.tag } : {},
+						),
+					)
+					.then((notifications) => {
+						for (const notification of notifications) notification.close();
+					})
+					.catch((cause) => options.onError?.(cause as Error));
+			}
+		};
+
+		navigator.serviceWorker.addEventListener("message", listener);
+		return () => {
+			navigator.serviceWorker.removeEventListener("message", listener);
+		};
+	};
+}
+
+/** What the poll remembers between ticks, to notice a change. */
+type PortalWatermark = {
+	unreadMessages: number;
+	orderStatuses: Map<string, string>;
+	invoiceStatuses: Map<string, string>;
+	shipmentStatuses: Map<string, string>;
+};
+
+/**
+ * Notifications inferred from the signed-in customer's portal.
+ *
+ * ## Why polling, and why this is not a downgrade
+ *
+ * Push reaches maybe a third of visitors — the rest never grant permission, or
+ * are on an iPhone that has not been added to the Home Screen. A portal that
+ * only notified push subscribers would be silent for most customers. Polling
+ * covers everyone who has the page open, which is exactly the audience a toast
+ * can reach anyway.
+ *
+ * ## The first tick never notifies
+ *
+ * It records a baseline instead. Otherwise opening the portal would toast every
+ * order that ever shipped, which reads as a flood of stale news and trains
+ * people to dismiss without reading.
+ */
+export function portalSource(options: {
+	portal: PortalController;
+	intervalMs?: number;
+}): NotificationSource {
+	// Floored rather than trusted: this runs against a rate-limited API, and a
+	// consumer passing 1000 because it "feels responsive" would spend an org's
+	// quota on a page nobody is looking at.
+	const intervalMs = Math.max(15_000, options.intervalMs ?? 60_000);
+
+	return (emit) => {
+		let stopped = false;
+		let baseline: PortalWatermark | null = null;
+		let timer: ReturnType<typeof setInterval> | null = null;
+
+		function readWatermark(): PortalWatermark {
+			const snapshot = options.portal.snapshot();
+			return {
+				unreadMessages: snapshot.unreadMessageCount,
+				orderStatuses: new Map(
+					(snapshot.orders?.items ?? []).map((o) => [o.id, String(o.status)]),
+				),
+				invoiceStatuses: new Map(
+					(snapshot.invoices?.items ?? []).map((i) => [i.id, String(i.status)]),
+				),
+				shipmentStatuses: new Map(
+					(snapshot.shipments?.items ?? []).map((sh) => [
+						sh.id,
+						String(sh.status ?? "unknown"),
+					]),
+				),
+			};
+		}
+
+		function diff(previous: PortalWatermark, next: PortalWatermark): void {
+			const orgId = options.portal.snapshot().context?.organization?.id ?? null;
+
+			if (next.unreadMessages > previous.unreadMessages) {
+				const delta = next.unreadMessages - previous.unreadMessages;
+				emit({
+					source: "poll",
+					category: "messages",
+					kind: "message.received",
+					title: delta === 1 ? "New message" : `${delta} new messages`,
+					body: "You have a new message from the team.",
+					severity: "info",
+					orgId,
+					// Keyed on the resulting count rather than the delta, so two
+					// tabs polling at different moments agree on the id.
+					data: { entityId: `unread:${next.unreadMessages}` },
+				});
+			}
+
+			for (const [id, status] of next.orderStatuses) {
+				const before = previous.orderStatuses.get(id);
+				// A newly appearing order is not a status CHANGE — it is an order
+				// this tab had not loaded yet, and announcing it would toast the
+				// backlog on first pagination.
+				if (before === undefined || before === status) continue;
+				emit({
+					source: "poll",
+					category: "transactional",
+					kind: `order.${status}`,
+					title: orderTitle(status),
+					body: null,
+					severity: status === "cancelled" ? "warning" : "info",
+					orgId,
+					data: { entityId: `order:${id}:${status}`, orderId: id, status },
+				});
+			}
+
+			for (const [id, status] of next.invoiceStatuses) {
+				const before = previous.invoiceStatuses.get(id);
+				if (before === undefined || before === status) continue;
+				emit({
+					source: "poll",
+					category: "transactional",
+					kind: `invoice.${status}`,
+					title:
+						status === "paid"
+							? "Invoice paid"
+							: status === "overdue"
+								? "Invoice overdue"
+								: "Invoice updated",
+					body: null,
+					severity: status === "overdue" ? "error" : "info",
+					orgId,
+					data: { entityId: `invoice:${id}:${status}`, invoiceId: id, status },
+				});
+			}
+
+			for (const [id, status] of next.shipmentStatuses) {
+				const before = previous.shipmentStatuses.get(id);
+				if (before === undefined || before === status) continue;
+				emit({
+					source: "poll",
+					category: "transactional",
+					kind: `shipment.${status}`,
+					title:
+						status === "delivered"
+							? "Your order was delivered"
+							: status === "out_for_delivery"
+								? "Out for delivery"
+								: "Shipping update",
+					body: null,
+					severity: "info",
+					orgId,
+					data: {
+						entityId: `shipment:${id}:${status}`,
+						shipmentId: id,
+						status,
+					},
+				});
+			}
+		}
+
+		async function tick(): Promise<void> {
+			if (stopped) return;
+			// Refresh only the slices being watched, and settle rather than
+			// race: one failing call must not stop the other three from
+			// noticing their own changes.
+			await Promise.allSettled([
+				options.portal.loadOrders(),
+				options.portal.loadInvoices(),
+				options.portal.loadShipments(),
+				options.portal.loadMessages(),
+			]);
+			if (stopped) return;
+
+			const next = readWatermark();
+			if (baseline) diff(baseline, next);
+			baseline = next;
+		}
+
+		// Baseline immediately from whatever is already loaded, so a change that
+		// happens before the first interval is still caught.
+		baseline = readWatermark();
+		timer = setInterval(() => void tick(), intervalMs);
+
+		return () => {
+			stopped = true;
+			if (timer) clearInterval(timer);
+		};
+	};
+}
+
+function orderTitle(status: string): string {
+	switch (status) {
+		case "shipped":
+			return "Your order shipped";
+		case "delivered":
+			return "Your order was delivered";
+		case "cancelled":
+			return "Your order was cancelled";
+		case "refunded":
+			return "Your refund was issued";
+		default:
+			return "Order updated";
+	}
+}
+
+/**
+ * Flatten to the shape every toast library accepts.
+ *
+ * `sonner`, `react-hot-toast`, `vue-toastification`, `svelte-french-toast` and
+ * shadcn's `useToast` all take some arrangement of title, description, variant
+ * and an action — so this is the mapping most consumers would write by hand,
+ * offered once so they do not have to.
+ *
+ * Rendering stays entirely theirs. This returns data.
+ */
+export function toToast(notification: BusinessDashNotification): {
+	title: string;
+	description: string | undefined;
+	variant: "default" | "success" | "warning" | "destructive";
+	action: { label: string; url: string } | undefined;
+} {
+	return {
+		title: notification.title,
+		description: notification.body ?? undefined,
+		variant:
+			notification.severity === "error"
+				? "destructive"
+				: notification.severity === "warning"
+					? "warning"
+					: notification.severity === "success"
+						? "success"
+						: "default",
+		action: notification.url
+			? { label: "View", url: notification.url }
+			: undefined,
+	};
+}