@businessdash/sdk 0.9.60 → 0.9.80

package/dist/notifications-core/index.d.ts

@@ -0,0 +1,229 @@
+/**
+ * `@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;
+};
+/**
+ * Build the feed.
+ *
+ * Nothing runs until `start()`, so a controller can be constructed during
+ * render without a component mount kicking off a poll.
+ */
+export declare function createNotificationFeed(options?: NotificationFeedOptions): NotificationFeed;
+/**
+ * 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 declare function pushSource(options?: {
+    closeOsNotificationWhenFocused?: boolean;
+    onError?: (error: Error) => void;
+}): NotificationSource;
+/**
+ * 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 declare function portalSource(options: {
+    portal: PortalController;
+    intervalMs?: number;
+}): NotificationSource;
+/**
+ * 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 declare function toToast(notification: BusinessDashNotification): {
+    title: string;
+    description: string | undefined;
+    variant: "default" | "success" | "warning" | "destructive";
+    action: {
+        label: string;
+        url: string;
+    } | undefined;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/notifications-core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications-core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,gEAAgE;AAChE,MAAM,MAAM,oBAAoB,GAC7B,eAAe,GACf,SAAS,GACT,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,QAAQ,GACR,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEjB;;;;;;;GAOG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACtC;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,0EAA0E;IAC1E,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;IAClC,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,mEAAmE;IACnE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;IACnD,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC9B,CAAC;AAEF,gDAAgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,OAAO,CAAC,wBAAwB,CAAC,GAChE,IAAI,CAAC,wBAAwB,EAAE,OAAO,CAAC,CAAC;AAEzC,MAAM,MAAM,mBAAmB,GAAG,CACjC,YAAY,EAAE,wBAAwB,KAClC,IAAI,CAAC;AAEV;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,CAChC,IAAI,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,KACpC,MAAM,IAAI,CAAC;AAEhB,MAAM,MAAM,uBAAuB,GAAG;IACrC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yCAAyC;IACzC,OAAO,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CACjC,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC9B;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,IAAI,CAAC;IACpD;;;;;OAKG;IACH,IAAI,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACrC,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAC;IACd,0DAA0D;IAC1D,IAAI,IAAI,IAAI,CAAC;IACb,8CAA8C;IAC9C,MAAM,IAAI,wBAAwB,EAAE,CAAC;IACrC,yCAAyC;IACzC,OAAO,IAAI,IAAI,CAAC;CAChB,CAAC;AAuBF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,OAAO,GAAE,uBAA4B,GACnC,gBAAgB,CAkIlB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACzB,OAAO,GAAE;IACR,8BAA8B,CAAC,EAAE,OAAO,CAAC;IACzC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC5B,GACJ,kBAAkB,CAmEpB;AAUD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE;IACrC,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,kBAAkB,CA4IrB;AAiBD;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,YAAY,EAAE,wBAAwB,GAAG;IAChE,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,aAAa,CAAC;IAC3D,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC;CACnD,CAgBA"}

package/dist/notifications-core/index.js

@@ -0,0 +1,445 @@
+/**
+ * `@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
+ */
+/**
+ * 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) {
+    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 = {}) {
+    const handlers = new Set();
+    const history = [];
+    /** id → when it was seen, so the window can be pruned. */
+    const seen = new Map();
+    const teardowns = [];
+    const dedupeWindowMs = options.dedupeWindowMs ?? 5 * 60 * 1000;
+    const historyLimit = options.historyLimit ?? 50;
+    let running = false;
+    let destroyed = false;
+    function fail(cause) {
+        options.onError?.(cause instanceof Error ? cause : new Error(String(cause)));
+    }
+    function deliver(input) {
+        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 = {
+            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 = [
+                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 = {}) {
+    return (emit) => {
+        if (typeof navigator === "undefined" ||
+            !("serviceWorker" in navigator) ||
+            typeof window === "undefined") {
+            return () => undefined;
+        }
+        const listener = (event) => {
+            const message = event.data;
+            if (message?.type !== "businessdash:push" || !message.payload)
+                return;
+            const payload = message.payload;
+            const data = typeof payload.data === "object" && payload.data !== null
+                ? payload.data
+                : {};
+            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));
+            }
+        };
+        navigator.serviceWorker.addEventListener("message", listener);
+        return () => {
+            navigator.serviceWorker.removeEventListener("message", listener);
+        };
+    };
+}
+/**
+ * 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) {
+    // 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 = null;
+        let timer = null;
+        function readWatermark() {
+            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, next) {
+            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() {
+            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) {
+    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) {
+    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,
+    };
+}
+//# sourceMappingURL=index.js.map