@visulima/notification 0.0.1 → 1.0.0-alpha.1

package/README.md

@@ -1,12 +1,302 @@
-# @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
+
+### 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/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};

package/dist/index.d.ts

@@ -0,0 +1,174 @@
+export { type M as Middleware, type S as SendContext, type a as SendFunction, c as composeMiddleware } from "./packem_shared/types.d-CximoA8M.js";
+import { C as ChannelPayloadMap, a as NotificationMessage } from "./packem_shared/notification.d-BBLyVuqi.js";
+export { N as Notification, type b as NotificationProviders, type S as SendManyOptions, c as createNotification } from "./packem_shared/notification.d-BBLyVuqi.js";
+export { type P as Provider, type a as ProviderFactory, d as defineProvider } from "./packem_shared/provider.d-BQAGriz6.js";
+export type { d as BaseConfig, B as BaseNotificationPayload, C as ChannelType, b as ChatPayload, f as EmailAddressLike, E as EmailChannelPayload, g as FailureReceipt, F as FeatureFlags, I as InAppPayload, M as MaybePromise, N as NotificationEvent, e as NotificationEventType, h as NotificationPayload, a as NotificationResult, P as PushPayload, c as Receipt, i as RecipientResult, R as Result, S as SmsPayload, j as SuccessReceipt, W as WebhookPayload } from "./packem_shared/types.d-GUzX1jTk.js";
+interface ErrorProperties {
+  cause?: unknown;
+  hint?: ErrorHint;
+  location?: ErrorLocation;
+  message?: string;
+  name: string;
+  stack?: string;
+  title?: string;
+}
+interface ErrorLocation {
+  column?: number;
+  file?: string;
+  line?: number;
+}
+/**
+* A message that explains to the user how they can fix the error.
+* @example
+* ```ts
+* const error = new VisulimaError({
+*    hint: "Try running `npm install` to install missing dependencies.",
+*    location: {
+*    file: "src/index.ts",
+*    line: 1,
+*    column: 1,
+*    },
+*    message: "Cannot find module 'react'",
+*    name: "ModuleNotFoundError",
+* });
+* ```
+*
+* For more complex hints, you can pass an array of strings or a single string in markdown format.
+*/
+type ErrorHint = string[] | string;
+declare class VisulimaError extends Error {
+  loc: ErrorLocation | undefined;
+  title: string | undefined;
+  /**
+  * A message that explains to the user how they can fix the error.
+  */
+  hint: ErrorHint | undefined;
+  type: string;
+  constructor({
+    cause,
+    hint,
+    location,
+    message,
+    name,
+    stack,
+    title
+  }: ErrorProperties);
+  setLocation(location: ErrorLocation): void;
+  setName(name: string): void;
+  setMessage(message: string): void;
+  setHint(hint: ErrorHint): void;
+}
+/**
+* Will return an array of all causes in the error in the order they occurred.
+*/
+/**
+* Base error class for notification package operations.
+* @param component The component name where the error occurred.
+* @param message The error message describing what went wrong.
+* @param options Optional error options including cause, code, and hint.
+*/
+declare class NotificationError extends VisulimaError {
+  readonly component: string;
+  readonly code?: string;
+  constructor(component: string, message: string, options?: {
+    cause?: Error | unknown;
+    code?: string;
+    hint?: string | string[];
+  });
+}
+/**
+* Error for missing required options.
+* @param component The component name where the error occurred.
+* @param name The name(s) of the missing required option(s).
+*/
+declare class RequiredOptionError extends NotificationError {
+  constructor(component: string, name: string | string[]);
+}
+/**
+* Fluent builder for assembling a multi-channel {@link NotificationMessage}.
+*
+* Mirrors the ergonomics of `@visulima/email`'s `MailMessage`: chainable, per-channel
+* setters that accumulate a plain message object. It is a thin convenience over the
+* existing `NotificationMessage` shape and does not change the facade — `build()`
+* returns the exact object `Notification.send()` already accepts.
+* @example
+* ```ts
+* const message = createNotificationMessage()
+*   .sms({ text: "your code is 123", to: "+15555550100" })
+*   .push({ body: "deploy finished", title: "CI", to: "device-token" })
+*   .idempotencyKey("deploy-42")
+*   .build();
+*
+* await createNotification({ sms, push }).send(message);
+* ```
+*/
+declare class NotificationMessageBuilder {
+  #private;
+  /**
+  * Sets the SMS payload for the message.
+  * @param payload The SMS channel payload.
+  * @returns This instance for method chaining.
+  */
+  sms(payload: ChannelPayloadMap["sms"]): this;
+  /**
+  * Sets the push payload for the message.
+  * @param payload The push channel payload.
+  * @returns This instance for method chaining.
+  */
+  push(payload: ChannelPayloadMap["push"]): this;
+  /**
+  * Sets the chat payload for the message.
+  * @param payload The chat channel payload.
+  * @returns This instance for method chaining.
+  */
+  chat(payload: ChannelPayloadMap["chat"]): this;
+  /**
+  * Sets the in-app inbox payload for the message.
+  * @param payload The in-app channel payload.
+  * @returns This instance for method chaining.
+  */
+  inApp(payload: ChannelPayloadMap["inapp"]): this;
+  /**
+  * Sets the outbound webhook payload for the message.
+  * @param payload The webhook channel payload.
+  * @returns This instance for method chaining.
+  */
+  webhook(payload: ChannelPayloadMap["webhook"]): this;
+  /**
+  * Sets the email payload for the message.
+  * @param payload The email channel payload.
+  * @returns This instance for method chaining.
+  */
+  email(payload: ChannelPayloadMap["email"]): this;
+  /**
+  * Sets metadata applied to every present channel payload at build time.
+  *
+  * Per-channel `metadata` already set on a payload takes precedence over these
+  * builder-level values (the builder values are spread first).
+  * @param metadata Arbitrary metadata to attach.
+  * @returns This instance for method chaining.
+  */
+  metadata(metadata: Record<string, unknown>): this;
+  /**
+  * Sets an idempotency key applied to every present channel payload at build time.
+  *
+  * A per-channel `idempotencyKey` already set on a payload takes precedence.
+  * @param key The idempotency key used to dedupe retried sends.
+  * @returns This instance for method chaining.
+  */
+  idempotencyKey(key: string): this;
+  /**
+  * Builds the plain {@link NotificationMessage}.
+  *
+  * Applies builder-level `metadata` / `idempotencyKey` to each present channel
+  * payload without overriding values already set on the individual payloads.
+  * @returns The assembled multi-channel message.
+  */
+  build(): NotificationMessage;
+}
+/**
+* Creates a new {@link NotificationMessageBuilder}.
+* @returns A fresh fluent message builder.
+*/
+declare const createNotificationMessage: () => NotificationMessageBuilder;
+export { type ChannelPayloadMap, NotificationError, type NotificationMessage, NotificationMessageBuilder, RequiredOptionError, createNotificationMessage };

package/dist/index.js

@@ -0,0 +1 @@
+import{default as r}from"./packem_shared/NotificationError-DVfMJQ1u.js";import{default as t}from"./packem_shared/RequiredOptionError-CuL42XRq.js";import{composeMiddleware as f}from"./packem_shared/composeMiddleware-D6dR8DUS.js";import{Notification as d,createNotification as p}from"./packem_shared/Notification-D1YeYxrQ.js";import{NotificationMessageBuilder as n,createNotificationMessage as s}from"./packem_shared/NotificationMessageBuilder-Br_aZusY.js";import{defineProvider as N}from"./packem_shared/defineProvider-C9q-7iwt.js";export{d as Notification,r as NotificationError,n as NotificationMessageBuilder,t as RequiredOptionError,f as composeMiddleware,p as createNotification,s as createNotificationMessage,N as defineProvider};