@visulima/notification 0.0.1 → 1.0.0-alpha.2

package/README.md

@@ -1,12 +1,319 @@
-# @visulima/notification
+<!-- START_PACKAGE_OG_IMAGE_PLACEHOLDER -->
 
-> 🚧 **Placeholder** — this name is reserved. The full multi-channel notification library is coming soon.
+<a href="https://www.anolilab.com/open-source" align="center">
 
-A reusable, ESM-only, edge-ready multi-channel notification library with SMS, push, chat, in-app and webhook providers.
+  <img src="__assets__/package-og.svg" alt="notification" />
 
-- Homepage: https://visulima.com/packages/notification
-- Repository: https://github.com/visulima/visulima/tree/main/packages/notification/notification
+</a>
+
+<h3 align="center">A reusable, ESM-only, edge-ready multi-channel notification library with SMS, push, chat, in-app and webhook providers</h3>
+
+<!-- END_PACKAGE_OG_IMAGE_PLACEHOLDER -->
+
+<br />
+
+<div align="center">
+
+[![typescript-image][typescript-badge]][typescript-url]
+[![mit licence][license-badge]][license]
+[![npm downloads][npm-downloads-badge]][npm-downloads]
+[![Chat][chat-badge]][chat]
+[![PRs Welcome][prs-welcome-badge]][prs-welcome]
+
+</div>
+
+---
+
+<div align="center">
+    <p>
+        <sup>
+            Daniel Bannert's open source work is supported by the community on <a href="https://github.com/sponsors/prisis">GitHub Sponsors</a>
+        </sup>
+    </p>
+</div>
+
+---
+
+`@visulima/notification` is the multi-channel sibling of [`@visulima/email`](https://visulima.com/packages/email): one
+typed facade drives many channel providers (SMS, push, chat, in-app, webhook) and the email channel delegates straight to
+`@visulima/email`. It is **infra-free** (no Redis/Mongo/dashboard required), **ESM-only**, **tree-shakeable** (import only
+the providers you use), and **edge-ready** — every native provider is built on `fetch` with zero Node built-ins, so it
+runs unmodified on Cloudflare Workers, Vercel Edge, Deno and Bun.
+
+## Install
+
+```sh
+npm install @visulima/notification
+```
+
+```sh
+yarn add @visulima/notification
+```
+
+```sh
+pnpm add @visulima/notification
+```
+
+## Usage
+
+> **Every provider is `fetch`-based** — no per-provider SDK to install, and it runs on Node, Cloudflare Workers, Vercel
+> Edge, Deno and Bun. Optional peers are only needed by specific subpaths (e.g. `liquidjs` for `./template/liquid`,
+> `@visulima/workflow` for `./workflow`) — see the [install table](https://visulima.com/docs/packages/notification/installation#optional-peer-dependencies).
+> Beyond sending, the package ships [workflows](https://visulima.com/docs/packages/notification/workflow),
+> [digest](https://visulima.com/docs/packages/notification/digest),
+> [layouts](https://visulima.com/docs/packages/notification/layouts) and
+> [i18n](https://visulima.com/docs/packages/notification/i18n).
+
+### Quick send (one channel, no setup)
+
+```typescript
+import { send } from "@visulima/notification";
+import { twilioProvider } from "@visulima/notification/providers/twilio";
+
+await send("sms", twilioProvider({ accountSid: "AC…", authToken: "…", from: "+15555550100" }), { to: "+15555550100", text: "Your code is 123" });
+```
+
+### Multi-channel send
+
+```typescript
+import { createNotification } from "@visulima/notification";
+import { twilioProvider } from "@visulima/notification/providers/twilio";
+import { slackProvider } from "@visulima/notification/providers/slack";
+import { fcmProvider } from "@visulima/notification/providers/fcm";
+
+const notify = createNotification({
+    sms: twilioProvider({ accountSid: "AC…", authToken: "…", from: "+15555550100" }),
+    chat: slackProvider({ token: "xoxb-…", defaultChannel: "C123" }),
+    push: fcmProvider({ projectId: "my-app", getAccessToken: async () => getGoogleToken() }),
+});
+
+// Each present channel is delivered in parallel; you get one receipt per channel.
+const receipts = await notify.send({
+    sms: { to: "+15555550100", text: "Your code is 123" },
+    chat: { text: "🚀 Deploy finished" },
+    push: { to: ["device-token"], title: "Deploy", body: "Finished" },
+});
+
+for (const receipt of receipts) {
+    if (receipt.successful) {
+        console.log(`${receipt.channel}: ${receipt.messageId}`);
+    } else {
+        console.error(`${receipt.channel} failed:`, receipt.errorMessages);
+    }
+}
+```
+
+### Single-channel send
+
+```typescript
+const receipt = await notify.sendToChannel("sms", { to: "+15555550100", text: "Hi" });
+```
+
+### Batch send with bounded concurrency
+
+```typescript
+for await (const receipts of notify.sendMany(messages, { concurrency: 10 })) {
+    // receipts for one message
+}
+```
+
+## Channels & providers
+
+Providers are imported from `@visulima/notification/providers/<name>` so unused integrations are tree-shaken away.
+
+| Channel      | Providers                                                       |
+| ------------ | --------------------------------------------------------------- |
+| **SMS**      | `twilio`, `vonage`, `plivo`, `messagebird`, `telnyx`, `sns`     |
+| **Push**     | `fcm`, `expo`, `web-push`, `apns`                               |
+| **Chat**     | `slack`, `discord`, `msteams`, `telegram`                       |
+| **In-app**   | `inAppProvider` (memory or unstorage store)                     |
+| **Webhook**  | `webhook`                                                       |
+| **Email**    | `emailChannel(...)` → wraps a `@visulima/email` `Mail` instance |
+| **Wrappers** | `failover`, `roundrobin`, `opentelemetry`, `mock`               |
+
+> **Cloudflare / edge note:** nearly every provider is `fetch` + Web Crypto only and runs on **Cloudflare Workers**,
+> Vercel Edge, Deno and Bun — including **AWS SNS** (Web Crypto SigV4) and **web-push** (Web Crypto VAPID + RFC 8291).
+> FCM accepts a `getAccessToken` callback so you bring your own OAuth token without a Node-only SDK. The only **Node-only**
+> pieces are **APNs** (`node:http2`) and the **bullmq / pg-boss / sqs** queue adapters — import those from a Node runtime.
+> See the [runtime matrix](https://visulima.com/docs/packages/notification/installation#runtime-support).
+
+## Writing a provider
+
+Every provider implements the same contract; author one with `defineProvider`:
+
+```typescript
+import { defineProvider } from "@visulima/notification";
+
+export const myProvider = defineProvider<MyConfig, SmsPayload>((config) => ({
+    id: "my-provider",
+    channel: "sms",
+    features: { batchSending: false },
+    initialize: () => {},
+    isAvailable: () => Boolean(config?.apiKey),
+    send: async (payload) => {
+        // … return { success: true, data: { messageId, channel: "sms", provider: "my-provider", sent: true, timestamp: new Date() } }
+    },
+}));
+```
+
+## Failover & round-robin
+
+Wrap several same-channel providers to gain resilience or load balancing:
+
+```typescript
+import { failoverProvider } from "@visulima/notification/providers/failover";
+import { roundRobinProvider } from "@visulima/notification/providers/roundrobin";
+
+const sms = failoverProvider([twilioProvider({ … }), vonageProvider({ … })]); // try Twilio, fall back to Vonage
+const balanced = roundRobinProvider([plivoProvider({ … }), telnyxProvider({ … })]);
+
+const notify = createNotification({ sms });
+```
+
+## Routing (channel fallback & broadcast)
+
+`route(...)` adds channel-sequence delivery and a gate, on top of per-channel provider failover:
+
+```typescript
+import { route } from "@visulima/notification/routing";
+
+// best-of: try sms, then push, then email — stop at the first success
+await route(notify, message, { order: ["sms", "push", "email"], mode: "best-of" });
+
+// all: broadcast to every present channel in parallel
+await route(notify, message, { mode: "all" });
+```
+
+## Preferences
+
+Honour per-subscriber, per-channel opt-outs (critical sends bypass them):
+
+```typescript
+import { MemoryPreferenceStore, preferencesGate } from "@visulima/notification/preferences";
+
+const prefs = new MemoryPreferenceStore();
+prefs.set("user-1", { channels: { sms: false } });
+
+await route(notify, message, { gate: preferencesGate(prefs) });
+await route(notify, message, { gate: preferencesGate(prefs, { critical: true }) }); // bypasses opt-outs
+```
+
+## Middleware
+
+Cross-cutting concerns compose around every send (first registered = outermost):
+
+```typescript
+import { retryMiddleware, rateLimitMiddleware, circuitBreakerMiddleware, dedupeMiddleware, loggingMiddleware } from "@visulima/notification/middleware";
+
+notify
+    .use(loggingMiddleware())
+    .use(retryMiddleware({ retries: 3 }))
+    .use(rateLimitMiddleware({ rate: 100, interval: 1000 }))
+    .use(circuitBreakerMiddleware({ threshold: 5 }))
+    .use(dedupeMiddleware({ ttl: 60_000 }));
+```
+
+## Queue & worker
+
+Decouple enqueue from delivery with a durable queue and a retrying worker:
+
+```typescript
+import { MemoryQueue, createQueueWorker } from "@visulima/notification/queue";
+
+const queue = new MemoryQueue();
+queue.enqueue({ sms: { to: "+15555550100", text: "Hi" } });
+
+const worker = createQueueWorker(queue, notify, { maxAttempts: 5 });
+worker.start(); // or `await worker.drain()` to process all due jobs once
+```
+
+Back the queue with [unstorage](https://unstorage.unjs.io) for Redis/filesystem/KV persistence:
+
+```typescript
+import { UnstorageQueue } from "@visulima/notification/queue/unstorage";
+import { createStorage } from "unstorage";
+
+const queue = new UnstorageQueue(createStorage());
+```
+
+## In-app inbox
+
+```typescript
+import { inAppProvider } from "@visulima/notification/channels/inapp";
+
+const inapp = inAppProvider();
+const notify = createNotification({ inapp });
+
+await notify.sendToChannel("inapp", { to: "user-1", title: "Welcome", body: "Thanks for joining" });
+
+const store = inapp.getInstance();
+await store.unreadCount("user-1"); // 1
+await store.list("user-1");
+await store.markAllRead("user-1");
+```
+
+## Email channel
+
+The email channel delegates to a configured [`@visulima/email`](https://visulima.com/packages/email) `Mail` instance, so
+you reuse its 29 providers, templates and deliverability tooling:
+
+```typescript
+import { createMail } from "@visulima/email";
+import { resendProvider } from "@visulima/email/providers/resend";
+import { createNotification } from "@visulima/notification";
+import { emailChannel } from "@visulima/notification/channels/email";
+
+const mail = createMail(resendProvider({ apiKey: "re_…" }));
+const notify = createNotification({ email: emailChannel(mail) });
+
+await notify.sendToChannel("email", { from: "noreply@app.com", to: "user@x.com", subject: "Hi", html: "<p>Hello</p>" });
+```
+
+## Events
+
+Subscribe to lifecycle events and build a timeline:
+
+```typescript
+import { NotificationEventBus, MemoryEventStore } from "@visulima/notification/events";
+
+const bus = new NotificationEventBus();
+bus.on("sent", (event) => console.log(event.messageId));
+bus.on("*", (event) => store.append(event));
+```
+
+## Supported Node.js Versions
+
+Libraries in this ecosystem make the best effort to track [Node.js' release schedule](https://github.com/nodejs/release#release-schedule).
+Here's [a post on why we think this is important](https://medium.com/the-node-js-collection/maintainers-should-consider-following-node-js-release-schedule-ab08ed4de71a).
+
+## Contributing
+
+If you would like to help take a look at the [list of issues](https://github.com/visulima/visulima/issues) and check our [Contributing](.github/CONTRIBUTING.md) guidelines.
+
+> **Note:** please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
+
+## Credits
+
+- [Daniel Bannert](https://github.com/prisis)
+- [All Contributors](https://github.com/visulima/visulima/graphs/contributors)
+
+## Made with ❤️ at Anolilab
+
+This is an open source project and will always remain free to use. If you think it's cool, please star it 🌟. [Anolilab](https://www.anolilab.com/open-source) is a Development and AI Studio. Contact us at [hello@anolilab.com](mailto:hello@anolilab.com) if you need any help with these technologies or just want to say hi!
 
 ## License
 
-[MIT](https://github.com/visulima/visulima/blob/main/LICENSE.md) © [Daniel Bannert](https://github.com/prisis)
+The visulima notification is open-sourced software licensed under the [MIT][license]
+
+<!-- badges -->
+
+[license-badge]: https://img.shields.io/npm/l/@visulima/notification?style=for-the-badge
+[license]: https://github.com/visulima/visulima/blob/main/LICENSE
+[npm-downloads-badge]: https://img.shields.io/npm/dm/@visulima/notification?style=for-the-badge
+[npm-downloads]: https://www.npmjs.com/package/@visulima/notification
+[prs-welcome-badge]: https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge
+[prs-welcome]: https://github.com/visulima/visulima/blob/main/.github/CONTRIBUTING.md
+[chat-badge]: https://img.shields.io/discord/932323359193186354.svg?style=for-the-badge
+[chat]: https://discord.gg/TtFJY8xkFK
+[typescript-badge]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]: https://www.typescriptlang.org/

package/dist/channels/email/index.d.ts

@@ -0,0 +1,46 @@
+import { P as Provider } from "../../packem_shared/provider.d-BQAGriz6.js";
+import { E as EmailChannelPayload } from "../../packem_shared/types.d-GUzX1jTk.js";
+/**
+* The result shape returned by `@visulima/email`'s `Mail.send`.
+*/
+interface EmailSendResult {
+  data?: {
+    messageId: string;
+    provider?: string;
+    response?: unknown;
+    sent?: boolean;
+    timestamp?: Date;
+  };
+  error?: unknown;
+  success: boolean;
+}
+/**
+* Structural type for a `@visulima/email` `Mail` instance. Kept structural so the email
+* peer stays optional — pass a configured `createMail(...)` result.
+*/
+interface EmailLike {
+  send: (message: unknown) => Promise<EmailSendResult>;
+}
+interface EmailChannelConfig {
+  /** Provider id reported on results (default `"email"`). */
+  id?: string;
+}
+/**
+* Adapts a configured `@visulima/email` `Mail` instance into a notification channel
+* provider, so email can participate in multi-channel sends and routing.
+* @param mail A `Mail` instance from `createMail(...)`.
+* @param config Optional config.
+* @returns An email-channel provider.
+* @example
+* ```ts
+* import { createMail } from "@visulima/email";
+* import { resendProvider } from "@visulima/email/providers/resend";
+* import { createNotification } from "@visulima/notification";
+* import { emailChannel } from "@visulima/notification/channels/email";
+*
+* const mail = createMail(resendProvider({ apiKey }));
+* const notify = createNotification({ email: emailChannel(mail) });
+* ```
+*/
+declare const emailChannel: (mail: EmailLike, config?: EmailChannelConfig) => Provider<unknown, EmailChannelPayload>;
+export { type EmailChannelConfig, type EmailLike, emailChannel };

package/dist/channels/email/index.js

@@ -0,0 +1 @@
+import{emailChannel as l}from"../../packem_shared/emailChannel-CNDlX96Q.js";export{l as emailChannel};

package/dist/channels/inapp/index.d.ts

@@ -0,0 +1,99 @@
+import { P as Provider } from "../../packem_shared/provider.d-BQAGriz6.js";
+import { I as InAppPayload } from "../../packem_shared/types.d-GUzX1jTk.js";
+import { S as Storage } from "../../packem_shared/unstorage.DqlWKU2I.d-CogP3Etw.js";
+/**
+* A persisted in-app notification.
+*/
+interface StoredNotification {
+  actions?: {
+    label: string;
+    url?: string;
+  }[];
+  body: string;
+  createdAt: number;
+  data?: Record<string, unknown>;
+  id: string;
+  read: boolean;
+  subscriberId: string;
+  title?: string;
+}
+interface ListOptions {
+  /** Max items to return. */
+  limit?: number;
+  /** Only return unread items. */
+  unreadOnly?: boolean;
+}
+/**
+* Backing store for the in-app channel. The default {@link MemoryInAppStore} is
+* in-process; back it with a persistent store for production feeds.
+*/
+interface InAppStore {
+  add: (notification: Omit<StoredNotification, "createdAt" | "id" | "read"> & {
+    id?: string;
+  }) => Promise<StoredNotification>;
+  list: (subscriberId: string, options?: ListOptions) => Promise<StoredNotification[]>;
+  markAllRead: (subscriberId: string) => Promise<void>;
+  markRead: (id: string) => Promise<void>;
+  remove: (id: string) => Promise<void>;
+  unreadCount: (subscriberId: string) => Promise<number>;
+}
+/**
+* In-memory {@link InAppStore}.
+*/
+declare class MemoryInAppStore implements InAppStore {
+  #private;
+  add(notification: Omit<StoredNotification, "createdAt" | "id" | "read"> & {
+    id?: string;
+  }): Promise<StoredNotification>;
+  list(subscriberId: string, options?: ListOptions): Promise<StoredNotification[]>;
+  markRead(id: string): Promise<void>;
+  markAllRead(subscriberId: string): Promise<void>;
+  unreadCount(subscriberId: string): Promise<number>;
+  remove(id: string): Promise<void>;
+}
+interface InAppProviderConfig {
+  /** Provider id reported on results (default `"inapp"`). */
+  id?: string;
+  /** Backing store (default a new {@link MemoryInAppStore}). */
+  store?: InAppStore;
+}
+/**
+* In-app channel provider. Persists notifications to an {@link InAppStore} for a feed/inbox
+* UI to query. Expose the store via `getInstance()` to read/markRead.
+* @param config Provider `id` and the backing {@link InAppStore} (defaults to in-memory).
+* @returns A provider that writes notifications into the configured store.
+*/
+declare const inAppProvider: (config?: InAppProviderConfig) => Provider<InAppProviderConfig, InAppPayload, InAppStore>;
+/**
+* An {@link InAppStore} backed by an [unstorage](https://unstorage.unjs.io) driver, giving durable,
+* multi-backend persistence (Redis, filesystem, Cloudflare KV, ...). `unstorage` is an optional peer
+* dependency — pass a configured `Storage` instance.
+*
+* Each notification is stored under `prefix:item:id`, and a per-subscriber index list is kept under
+* `prefix:index:subscriberId` so `list`/`unreadCount`/`markAllRead` avoid scanning every key.
+*
+* The per-subscriber index is eventually-consistent: the item and index keys are written
+* non-atomically, so a concurrent reader may briefly observe one without the other.
+*
+* Edge-safe: works on Cloudflare KV (and other edge runtimes) via the matching unstorage driver.
+*/
+declare class UnstorageInAppStore implements InAppStore {
+  #private;
+  constructor(storage: Storage, prefix?: string);
+  add(notification: Omit<StoredNotification, "createdAt" | "id" | "read"> & {
+    id?: string;
+  }): Promise<StoredNotification>;
+  list(subscriberId: string, options?: ListOptions): Promise<StoredNotification[]>;
+  markRead(id: string): Promise<void>;
+  markAllRead(subscriberId: string): Promise<void>;
+  unreadCount(subscriberId: string): Promise<number>;
+  remove(id: string): Promise<void>;
+}
+/**
+* Convenience factory for {@link UnstorageInAppStore}.
+* @param storage A configured unstorage `Storage` instance (optional peer).
+* @param prefix Key prefix under which notifications are stored.
+* @returns A new {@link UnstorageInAppStore}.
+*/
+declare const createUnstorageInAppStore: (storage: Storage, prefix?: string) => UnstorageInAppStore;
+export { type InAppProviderConfig, type InAppStore, type ListOptions, MemoryInAppStore, type StoredNotification, UnstorageInAppStore, createUnstorageInAppStore, inAppProvider };

package/dist/channels/inapp/index.js

@@ -0,0 +1 @@
+import{inAppProvider as e}from"../../packem_shared/inAppProvider-ElbahgSj.js";import{MemoryInAppStore as t}from"../../packem_shared/MemoryInAppStore-48qlrDCx.js";import{UnstorageInAppStore as m,createUnstorageInAppStore as A}from"../../packem_shared/UnstorageInAppStore-Bq2LoDMO.js";export{t as MemoryInAppStore,m as UnstorageInAppStore,A as createUnstorageInAppStore,e as inAppProvider};

package/dist/digest/index.d.ts

@@ -0,0 +1,128 @@
+import { M as MaybePromise, D as Duration } from "../packem_shared/types.d-C1GoEAlI.d-Bv3grfyD.js";
+import '@standard-schema/spec';
+/** A single event buffered inside a digest window. */
+interface DigestEvent<PayloadT> {
+  /** Stable id of this event within the window. */
+  id: string;
+  /** The event payload. */
+  payload: PayloadT;
+  /** Epoch ms the event was added. */
+  time: number;
+}
+/** An open digest window: the events collected so far for a key, and when it closes. */
+interface DigestWindow<PayloadT> {
+  events: DigestEvent<PayloadT>[];
+  key: string;
+  /** Epoch ms at which the window is due to flush. */
+  wakeAt: number;
+}
+/**
+* Durability contract for `createDigester`. Implementations own the buffered
+* windows and the "what is due" query; the digester stays storage-agnostic.
+*
+* `read` and `remove` are separate (rather than a single destructive `drain`) so
+* the digester can flush a window's events *before* removing it — a failed flush
+* leaves the window in place to be retried (at-least-once).
+*/
+interface DigestStore<PayloadT> {
+  /**
+  * Append an event to the window for `key`, opening it (with `wakeAt`) if absent.
+  * The window's `wakeAt` is fixed when it opens — later events do not extend it.
+  * @returns `true` if this call opened a new window.
+  */
+  append: (key: string, event: DigestEvent<PayloadT>, wakeAt: number) => Promise<boolean>;
+  /** Keys whose window `wakeAt` is at or before `now`, up to `limit`. */
+  due: (now: number, limit: number) => Promise<string[]>;
+  /** Return the window for `key` without removing it, or `undefined` if none. */
+  read: (key: string) => Promise<DigestWindow<PayloadT> | undefined>;
+  /** Permanently remove the window for `key`. */
+  remove: (key: string) => Promise<void>;
+}
+/** Options for `createDigester`. */
+interface DigesterOptions<PayloadT> {
+  /** Group events into windows by this key (e.g. `subscriberId` or `subscriberId:postId`). */
+  key: (event: PayloadT) => string;
+  /**
+  * Called once per window when it closes, with every event collected. Delivery is
+  * **at-least-once**: the window is removed only after `onFlush` resolves, so a
+  * throwing `onFlush` is retried on the next sweep (and may run again if removal
+  * later fails). Make it idempotent.
+  */
+  onFlush: (events: DigestEvent<PayloadT>[], key: string) => MaybePromise<void>;
+  /** The durable store; defaults to an in-memory store. */
+  store?: DigestStore<PayloadT>;
+  /** How long a window stays open from its first event (a {@link Duration} or a per-event function). */
+  window: ((event: PayloadT) => Duration) | Duration;
+}
+/** Aggregates many events into windowed batches, flushing each as one notification. */
+interface Digester<PayloadT> {
+  /** Buffer an event; returns `true` if it opened a new window for its key. */
+  add: (event: PayloadT) => Promise<boolean>;
+  /** Flush every window whose wake-at has passed; returns the number flushed. */
+  sweep: (now?: number, limit?: number) => Promise<number>;
+}
+/**
+* Create a {@link Digester} that batches events into time/cron windows keyed by
+* `options.key`, flushing each closed window once via `options.onFlush` — turning
+* a burst of N events into a single notification.
+*
+* Windows close on a poll: call {@link Digester.sweep} from a cron job, a
+* Cloudflare alarm, or any timer (alongside a workflow runtime's `sweep`).
+* @param options Key function, window duration, flush handler and optional store.
+* @returns A {@link Digester}.
+* @example
+* ```ts
+* const digester = createDigester<{ subscriberId: string; postId: string }>({
+*     key: (event) => `${event.subscriberId}:${event.postId}`,
+*     window: { amount: 10, unit: "minutes" },
+*     onFlush: (events) => runtime.trigger(summaryWorkflow, { count: events.length, events }),
+* });
+*
+* await digester.add({ subscriberId: "u1", postId: "p1" }); // opens a 10-minute window
+* // …later, on a timer:
+* await digester.sweep();
+* ```
+*/
+declare const createDigester: <PayloadT>(options: DigesterOptions<PayloadT>) => Digester<PayloadT>;
+/**
+* In-process {@link DigestStore}. Ideal for tests and single-instance apps; swap
+* for the unstorage adapter for durability across restarts and instances.
+*/
+declare class MemoryDigestStore<PayloadT> implements DigestStore<PayloadT> {
+  #private;
+  append(key: string, event: DigestEvent<PayloadT>, wakeAt: number): Promise<boolean>;
+  read(key: string): Promise<DigestWindow<PayloadT> | undefined>;
+  remove(key: string): Promise<void>;
+  due(now: number, limit: number): Promise<string[]>;
+}
+/**
+* Minimal structural view of an [unstorage](https://unstorage.unjs.io) instance,
+* declared locally so the package needs no hard `unstorage` dependency.
+*/
+interface UnstorageLike {
+  getItem: <T = unknown>(key: string) => Promise<T | null>;
+  getKeys: (base?: string) => Promise<string[]>;
+  removeItem: (key: string) => Promise<void>;
+  setItem: (key: string, value: unknown) => Promise<void>;
+}
+/**
+* {@link DigestStore} backed by [unstorage](https://unstorage.unjs.io), for durable,
+* edge-friendly digest windows over any unstorage driver.
+*
+* Each window is a single self-contained document keyed by `digest:w:` plus the
+* digest key; there is no shared index, so concurrent `add`s for different keys cannot
+* lose-update each other. `due` scans the window documents under the prefix — fine for the
+* transient, bounded set of open windows. Individual reads/writes are still not
+* transactional, so concurrent writers on the *same* key (or a sweep racing an
+* `add` for that key) can drop an event or double-flush; for that level of
+* contention prefer a store with atomic guarantees, or sweep from one instance.
+*/
+declare class UnstorageDigestStore<PayloadT> implements DigestStore<PayloadT> {
+  #private;
+  constructor(storage: UnstorageLike);
+  append(key: string, event: DigestEvent<PayloadT>, wakeAt: number): Promise<boolean>;
+  read(key: string): Promise<DigestWindow<PayloadT> | undefined>;
+  remove(key: string): Promise<void>;
+  due(now: number, limit: number): Promise<string[]>;
+}
+export { type DigestEvent, type DigestStore, type DigestWindow, type Digester, type DigesterOptions, MemoryDigestStore, UnstorageDigestStore, createDigester };

package/dist/digest/index.js

@@ -0,0 +1 @@
+import{default as r}from"../packem_shared/createDigester-vMNPejGF.js";import{default as a}from"../packem_shared/MemoryDigestStore-Bw-sE5MI.js";import{default as f}from"../packem_shared/UnstorageDigestStore-QAcO3Vb_.js";export{a as MemoryDigestStore,f as UnstorageDigestStore,r as createDigester};

package/dist/events/index.d.ts

@@ -0,0 +1,37 @@
+import { N as NotificationEvent, e as NotificationEventType } from "../packem_shared/types.d-GUzX1jTk.js";
+/**
+* An append-only timeline store for notification events.
+*/
+interface EventStore {
+  append: (event: NotificationEvent) => void | Promise<void>;
+  timeline: (messageId: string) => NotificationEvent[] | Promise<NotificationEvent[]>;
+}
+/**
+* In-memory {@link EventStore} keyed by message id.
+*/
+declare class MemoryEventStore implements EventStore {
+  #private;
+  append(event: NotificationEvent): void;
+  timeline(messageId: string): NotificationEvent[];
+}
+type NotificationEventListener = (event: NotificationEvent) => void;
+/**
+* A tiny synchronous event bus for notification lifecycle events. Listeners can subscribe
+* to a specific {@link NotificationEventType} or to all events with `"*"`.
+*/
+declare class NotificationEventBus {
+  #private;
+  /**
+  * Subscribes to an event type (or `"*"` for all).
+  * @param type A specific {@link NotificationEventType} to listen for, or `"*"` for every event.
+  * @param listener The callback invoked with each matching event.
+  * @returns An unsubscribe function.
+  */
+  on(type: "*" | NotificationEventType, listener: NotificationEventListener): () => void;
+  /**
+  * Emits an event to matching listeners.
+  * @param event The event to emit.
+  */
+  emit(event: NotificationEvent): void;
+}
+export { type EventStore, MemoryEventStore, NotificationEventBus, NotificationEventListener };

package/dist/events/index.js

@@ -0,0 +1 @@
+import{default as f}from"../packem_shared/MemoryEventStore-BGD_xRxu.js";class n{#t=new Map;on(t,e){const o=this.#t.get(t)??new Set;return o.add(e),this.#t.set(t,o),()=>o.delete(e)}emit(t){for(const e of this.#t.get(t.type)??[])e(t);for(const e of this.#t.get("*")??[])e(t)}}export{f as MemoryEventStore,n as NotificationEventBus};