@beignet/core 0.0.33 → 0.0.34

package/src/notifications/index.ts

@@ -1,4 +1,13 @@
 import type { StandardSchemaV1 } from "@standard-schema/spec";
+import {
+  createJobs,
+  type JobDef,
+  type JobDispatcher,
+  type JobHook,
+  type JobRetryOptions,
+  type JobTimeoutDuration,
+  retry,
+} from "../jobs/index.js";
 import type { SendMailOptions } from "../mail/index.js";
 import type { ProviderInstrumentationTarget } from "../providers/index.js";
 import {
@@ -60,7 +69,7 @@ export interface NotificationChannelResult {
   /**
    * Delivery outcome for this channel.
    */
-  status: "sent" | "skipped" | "failed";
+  status: "queued" | "sent" | "skipped" | "failed";
   /**
    * Provider delivery ID when available.
    */
@@ -79,6 +88,14 @@ export interface NotificationChannelResult {
   details?: Record<string, unknown>;
 }
 
+/**
+ * Original error captured for one failed notification channel.
+ */
+export interface NotificationChannelError {
+  channel: string;
+  error: unknown;
+}
+
 /**
  * Arguments passed to a notification channel handler.
  */
@@ -119,6 +136,45 @@ export type NotificationChannels<Payload extends StandardSchema, Ctx> = Record<
   NotificationChannelHandler<Payload, Ctx>
 >;
 
+/**
+ * Arguments passed to an app-owned notification preference evaluator.
+ */
+export interface NotificationPreferenceArgs<
+  Payload extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+> extends NotificationChannelHandleArgs<Payload, Ctx> {
+  /**
+   * Optional metadata supplied by the notification sender.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * App-owned decision for one notification channel.
+ */
+export interface NotificationPreferenceDecision {
+  /**
+   * Whether this channel should deliver.
+   */
+  deliver: boolean;
+  /**
+   * Optional reason recorded when delivery is skipped.
+   */
+  reason?: string;
+}
+
+/**
+ * Optional app-facing port for notification channel preferences and opt-outs.
+ */
+export interface NotificationPreferencesPort<Ctx = unknown> {
+  /**
+   * Evaluate the current preference immediately before channel delivery.
+   */
+  evaluate(
+    args: NotificationPreferenceArgs<StandardSchema, Ctx>,
+  ): MaybePromise<NotificationPreferenceDecision>;
+}
+
 /**
  * Notification definition created by `defineNotification(...)`.
  */
@@ -237,13 +293,23 @@ export interface InlineNotificationDispatcherOptions<Ctx> {
    */
   ctx?: Ctx | (() => MaybePromise<Ctx>);
   /**
-   * Called when a channel handler fails. When omitted, errors are rethrown to
-   * the caller as `NotificationDeliveryError`.
+   * Called when a channel handler or preference check fails. A returned result
+   * replaces the default failed result. Observer failures are ignored so the
+   * remaining channels still run.
    */
   onError?: (
     error: unknown,
     args: NotificationChannelHandleArgs<StandardSchema, Ctx>,
   ) => MaybePromise<NotificationChannelResult | undefined>;
+  /**
+   * How completed channel failures are surfaced. Defaults to `"report"`.
+   * `"throw"` still runs every selected channel before rejecting.
+   */
+  failureMode?: "report" | "throw";
+  /**
+   * Optional app-owned notification preference evaluator.
+   */
+  preferences?: NotificationPreferencesPort<Ctx>;
   /**
    * Optional devtools/provider instrumentation target.
    */
@@ -349,6 +415,102 @@ export interface Notifications<Ctx> {
   ): NotificationDef<Name, Payload, Ctx>;
 }
 
+/**
+ * Notification definitions available to durable delivery workers.
+ */
+export interface NotificationRegistry<Ctx = unknown> {
+  /**
+   * Registered definitions in declaration order.
+   */
+  readonly definitions: readonly NotificationDef<string, StandardSchema, Ctx>[];
+  /**
+   * Resolve a notification definition by its stable name.
+   */
+  get(name: string): NotificationDef<string, StandardSchema, Ctx> | undefined;
+}
+
+/**
+ * Payload carried by the first-party notification delivery job.
+ */
+export interface NotificationDeliveryJobPayload {
+  notificationName: string;
+  channel: string;
+  payload: unknown;
+  options: Omit<SendNotificationOptions, "channels">;
+}
+
+type NotificationDeliveryPayloadSchema = StandardSchemaV1<
+  unknown,
+  NotificationDeliveryJobPayload
+>;
+
+/**
+ * Job definition used by queued notification dispatchers and workers.
+ */
+export interface NotificationDeliveryJob<
+  Name extends string = string,
+  Ctx = unknown,
+> extends JobDef<Name, NotificationDeliveryPayloadSchema, Ctx> {
+  /**
+   * Registry used by both enqueue-time checks and worker delivery.
+   */
+  readonly registry: NotificationRegistry<Ctx>;
+}
+
+/**
+ * Options for the first-party notification delivery job.
+ */
+export interface DefineNotificationDeliveryJobOptions<
+  Name extends string,
+  Ctx,
+> {
+  /**
+   * Stable job name. Defaults to `"notifications.deliver"`.
+   */
+  name?: Name;
+  /**
+   * Notification definitions available to the worker.
+   */
+  registry: NotificationRegistry<Ctx>;
+  /**
+   * Optional app-owned preferences evaluated when the job runs.
+   */
+  preferences?: NotificationPreferencesPort<Ctx>;
+  /**
+   * Retry policy. Defaults to exponential backoff with three attempts.
+   */
+  retry?: JobRetryOptions;
+  /**
+   * Optional maximum duration for each channel delivery attempt.
+   */
+  timeout?: JobTimeoutDuration;
+  /**
+   * Optional execution hooks applied to each delivery attempt.
+   */
+  hooks?: readonly JobHook<
+    JobDef<Name, NotificationDeliveryPayloadSchema, Ctx>,
+    Ctx
+  >[];
+}
+
+/**
+ * Options for a notification dispatcher backed by Beignet jobs.
+ */
+export interface QueuedNotificationDispatcherOptions<Name extends string, Ctx> {
+  /**
+   * Job dispatcher used to enqueue one delivery job per channel.
+   */
+  jobs: JobDispatcher;
+  /**
+   * Registered notification delivery job.
+   */
+  deliveryJob: NotificationDeliveryJob<Name, Ctx>;
+  /**
+   * Optional devtools/provider instrumentation target.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
 /**
  * Error thrown when notification payload validation fails.
  */
@@ -379,28 +541,57 @@ export class NotificationDeliveryError extends Error {
    */
   readonly notificationName: string;
   /**
-   * Channel that failed.
+   * First channel that failed, retained for concise error handling.
    */
   readonly channel: string;
   /**
-   * Original channel error.
+   * Original error for the first failed channel when available.
    */
   readonly cause: unknown;
+  /**
+   * Complete notification result after every selected channel ran.
+   */
+  readonly result: SendNotificationResult;
+  /**
+   * Failed channel results.
+   */
+  readonly failures: readonly NotificationChannelResult[];
+  /**
+   * Original channel errors in delivery order.
+   */
+  readonly errors: readonly NotificationChannelError[];
 
   constructor(args: {
-    notificationName: string;
-    channel: string;
-    cause: unknown;
+    result: SendNotificationResult;
+    errors?: readonly NotificationChannelError[];
   }) {
+    const failures = args.result.results.filter(
+      (result) => result.status === "failed",
+    );
+    const firstFailure = failures[0];
+    const errors = args.errors ?? [];
     super(
-      `Notification "${args.notificationName}" failed on channel "${args.channel}": ${
-        args.cause instanceof Error ? args.cause.message : String(args.cause)
-      }`,
+      `Notification "${args.result.notificationName}" failed on ${failures.length} channel${failures.length === 1 ? "" : "s"}: ${failures.map((failure) => failure.channel).join(", ")}.`,
     );
     this.name = "NotificationDeliveryError";
-    this.notificationName = args.notificationName;
-    this.channel = args.channel;
-    this.cause = args.cause;
+    this.notificationName = args.result.notificationName;
+    this.channel = firstFailure?.channel ?? "unknown";
+    this.cause = errors.find(
+      (entry) => entry.channel === firstFailure?.channel,
+    )?.error;
+    this.result = args.result;
+    this.failures = failures;
+    this.errors = errors;
+  }
+}
+
+/**
+ * Error thrown when a notification registry cannot safely resolve a delivery.
+ */
+export class NotificationRegistryError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "NotificationRegistryError";
   }
 }
 
@@ -471,7 +662,7 @@ function resolveChannelNames(
   const selected = options?.channels ?? available;
 
   for (const channel of selected) {
-    if (!notification.channels[channel]) {
+    if (typeof notification.channels[channel] !== "function") {
       throw new Error(
         `Notification "${notification.name}" does not define channel "${channel}".`,
       );
@@ -482,13 +673,75 @@ function resolveChannelNames(
 }
 
 function summarizeResults(results: readonly NotificationChannelResult[]) {
+  const queued = results.filter((result) => result.status === "queued").length;
   const sent = results.filter((result) => result.status === "sent").length;
   const skipped = results.filter(
     (result) => result.status === "skipped",
   ).length;
   const failed = results.filter((result) => result.status === "failed").length;
 
-  return { sent, skipped, failed };
+  return { queued, sent, skipped, failed };
+}
+
+function resultSummary(results: readonly NotificationChannelResult[]): string {
+  const summary = summarizeResults(results);
+  const parts = [
+    summary.queued ? `${summary.queued} queued` : undefined,
+    `${summary.sent} sent`,
+    `${summary.skipped} skipped`,
+    `${summary.failed} failed`,
+  ].filter((part): part is string => Boolean(part));
+
+  return parts.join(", ");
+}
+
+function recordChannelResult(
+  instrumentation: ReturnType<typeof createProviderInstrumentation>,
+  notificationName: string,
+  result: NotificationChannelResult,
+  options: SendNotificationOptions,
+): void {
+  instrumentation.custom({
+    name: `notification.channel.${result.status}`,
+    label: `Notification channel ${result.status}`,
+    summary: `${notificationName} (${result.channel})`,
+    requestId: options.requestId,
+    traceId: options.traceId,
+    spanId: options.spanId,
+    parentSpanId: options.parentSpanId,
+    traceparent: options.traceparent,
+    details: {
+      notificationName,
+      channel: result.channel,
+      status: result.status,
+      id: result.id,
+      provider: result.provider,
+      reason: result.reason,
+      resultDetails: result.details,
+      metadata: options.metadata,
+    },
+  });
+}
+
+async function failedChannelResult<Ctx>(
+  error: unknown,
+  args: NotificationChannelHandleArgs<StandardSchema, Ctx>,
+  onError: InlineNotificationDispatcherOptions<Ctx>["onError"],
+): Promise<NotificationChannelResult> {
+  if (onError) {
+    try {
+      const handled = await onError(error, args);
+      if (handled) return { ...handled, channel: args.channel };
+    } catch {
+      // Error observers cannot interrupt delivery of the remaining channels.
+    }
+  }
+
+  return {
+    channel: args.channel,
+    status: "failed",
+    reason: error instanceof Error ? error.message : String(error),
+  };
 }
 
 function defineNotificationImpl<
@@ -508,6 +761,171 @@ function defineNotificationImpl<
   };
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function contextInstrumentationTarget(
+  ctx: unknown,
+): ProviderInstrumentationTarget {
+  if (!isRecord(ctx)) return undefined;
+  return isRecord(ctx.ports) ? ctx.ports : ctx;
+}
+
+const notificationDeliveryPayloadSchema: NotificationDeliveryPayloadSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "beignet",
+    validate(value: unknown) {
+      if (!isRecord(value)) {
+        return { issues: [{ message: "Expected an object." }] };
+      }
+
+      const issues: StandardSchemaV1.Issue[] = [];
+      if (
+        typeof value.notificationName !== "string" ||
+        value.notificationName.length === 0
+      ) {
+        issues.push({
+          message: "Expected a non-empty string.",
+          path: ["notificationName"],
+        });
+      }
+      if (typeof value.channel !== "string" || value.channel.length === 0) {
+        issues.push({
+          message: "Expected a non-empty string.",
+          path: ["channel"],
+        });
+      }
+      if (!("payload" in value)) {
+        issues.push({ message: "Required.", path: ["payload"] });
+      }
+      if (!isRecord(value.options)) {
+        issues.push({ message: "Expected an object.", path: ["options"] });
+      }
+
+      const deliveryOptions = isRecord(value.options) ? value.options : {};
+      const correlationFields = [
+        "requestId",
+        "traceId",
+        "spanId",
+        "parentSpanId",
+        "traceparent",
+      ] as const;
+      for (const field of correlationFields) {
+        if (
+          deliveryOptions[field] !== undefined &&
+          typeof deliveryOptions[field] !== "string"
+        ) {
+          issues.push({
+            message: "Expected a string.",
+            path: ["options", field],
+          });
+        }
+      }
+      if (
+        deliveryOptions.metadata !== undefined &&
+        !isRecord(deliveryOptions.metadata)
+      ) {
+        issues.push({
+          message: "Expected an object.",
+          path: ["options", "metadata"],
+        });
+      }
+
+      if (issues.length > 0) return { issues };
+
+      return {
+        value: {
+          notificationName: value.notificationName as string,
+          channel: value.channel as string,
+          payload: value.payload,
+          options: queuedSendOptions(deliveryOptions),
+        },
+      };
+    },
+  },
+};
+
+/**
+ * Define the notification catalog available to durable delivery workers.
+ * Duplicate names throw because queued delivery resolves definitions by name.
+ */
+export function defineNotificationRegistry<Ctx>(
+  definitions: readonly NotificationDef<string, StandardSchema, Ctx>[],
+): NotificationRegistry<Ctx> {
+  const byName = new Map<
+    string,
+    NotificationDef<string, StandardSchema, Ctx>
+  >();
+
+  for (const notification of definitions) {
+    if (byName.has(notification.name)) {
+      throw new NotificationRegistryError(
+        `Duplicate notification definition "${notification.name}" in notification registry.`,
+      );
+    }
+    byName.set(notification.name, notification);
+  }
+
+  return {
+    definitions: [...definitions],
+    get(name) {
+      return byName.get(name);
+    },
+  };
+}
+
+/**
+ * Define the generic job that resolves and delivers one notification channel.
+ * Register the returned job with every worker or outbox registry that can
+ * receive queued notifications.
+ */
+export function defineNotificationDeliveryJob<
+  Ctx,
+  Name extends string = "notifications.deliver",
+>(
+  options: DefineNotificationDeliveryJobOptions<Name, Ctx>,
+): NotificationDeliveryJob<Name, Ctx> {
+  const name = (options.name ?? "notifications.deliver") as Name;
+  const { defineJob } = createJobs<Ctx>();
+  const job = defineJob(name, {
+    payload: notificationDeliveryPayloadSchema,
+    description: "Deliver one notification channel.",
+    retry: options.retry ?? retry.exponential({ attempts: 3 }),
+    timeout: options.timeout,
+    hooks: options.hooks,
+    async handle({ payload, ctx }) {
+      const notification = options.registry.get(payload.notificationName);
+      if (!notification) {
+        throw new NotificationRegistryError(
+          `Notification "${payload.notificationName}" is not registered for queued delivery.`,
+        );
+      }
+      if (!notification.channels[payload.channel]) {
+        throw new NotificationRegistryError(
+          `Notification "${payload.notificationName}" does not define queued channel "${payload.channel}".`,
+        );
+      }
+
+      const dispatcher = createInlineNotificationDispatcher<Ctx>({
+        ctx,
+        preferences: options.preferences,
+        failureMode: "throw",
+        instrumentation: contextInstrumentationTarget(ctx),
+      });
+      await dispatcher.send(notification as NotificationDef, payload.payload, {
+        ...payload.options,
+        channels: [payload.channel],
+      });
+    },
+  });
+
+  return Object.assign(job, {
+    registry: options.registry,
+  });
+}
+
 /**
  * Validate and parse a notification payload with the notification's Standard
  * Schema.
@@ -524,8 +942,9 @@ export async function parseNotificationPayload<
  * Create an inline notification dispatcher.
  *
  * The dispatcher validates payloads and runs selected channel handlers
- * immediately. Use this directly in tests and local apps, or wrap it in jobs
- * and outbox delivery for production background execution.
+ * immediately. Channel failures are isolated and reported after every selected
+ * channel runs. Use this directly in tests and local apps, or use
+ * `createQueuedNotificationDispatcher(...)` for background execution.
  */
 export function createInlineNotificationDispatcher<Ctx>(
   options: InlineNotificationDispatcherOptions<Ctx> = {},
@@ -548,6 +967,7 @@ export function createInlineNotificationDispatcher<Ctx>(
       const channels = resolveChannelNames(notification, sendOptions);
       const ctx = await resolveCtx(options.ctx);
       const results: NotificationChannelResult[] = [];
+      const errors: NotificationChannelError[] = [];
 
       instrumentation.custom({
         name: "notification.send.started",
@@ -567,64 +987,80 @@ export function createInlineNotificationDispatcher<Ctx>(
 
       for (const channel of channels) {
         const handler = notification.channels[channel];
+        const args = {
+          notification,
+          payload: parsed,
+          ctx,
+          channel,
+        } satisfies NotificationChannelHandleArgs<StandardSchema, Ctx>;
 
         try {
-          const result = await handler({
-            notification,
-            payload: parsed,
-            ctx,
-            channel,
+          const preference = await options.preferences?.evaluate({
+            ...args,
+            metadata: sendOptions.metadata,
           });
-
-          results.push(
-            result ?? {
+          if (preference && !preference.deliver) {
+            const result = {
               channel,
-              status: "sent",
-            },
-          );
-        } catch (error) {
-          const args = {
-            notification,
-            payload: parsed,
-            ctx,
-            channel,
-          } satisfies NotificationChannelHandleArgs<StandardSchema, Ctx>;
-          const handled = await options.onError?.(error, args);
-          if (handled) {
-            results.push(handled);
+              status: "skipped",
+              reason:
+                preference.reason ?? "Disabled by notification preferences.",
+              details: {
+                source: "preferences",
+              },
+            } satisfies NotificationChannelResult;
+            results.push(result);
+            recordChannelResult(
+              instrumentation,
+              notification.name,
+              result,
+              sendOptions,
+            );
             continue;
           }
 
-          instrumentation.custom({
-            name: "notification.send.failed",
-            label: "Notification failed",
-            summary: `${notification.name} (${channel})`,
-            requestId: sendOptions.requestId,
-            traceId: sendOptions.traceId,
-            spanId: sendOptions.spanId,
-            parentSpanId: sendOptions.parentSpanId,
-            traceparent: sendOptions.traceparent,
-            details: {
-              notificationName: notification.name,
-              channel,
-              error: error instanceof Error ? error.message : String(error),
-              metadata: sendOptions.metadata,
-            },
-          });
-
-          throw new NotificationDeliveryError({
-            notificationName: notification.name,
-            channel,
-            cause: error,
-          });
+          const handled = await handler(args);
+          const result = handled
+            ? { ...handled, channel }
+            : ({
+                channel,
+                status: "sent",
+              } satisfies NotificationChannelResult);
+
+          results.push(result);
+          recordChannelResult(
+            instrumentation,
+            notification.name,
+            result,
+            sendOptions,
+          );
+        } catch (error) {
+          errors.push({ channel, error });
+          const result = await failedChannelResult(
+            error,
+            args,
+            options.onError,
+          );
+          results.push(result);
+          recordChannelResult(
+            instrumentation,
+            notification.name,
+            result,
+            sendOptions,
+          );
         }
       }
 
-      const summary = summarizeResults(results);
+      const result = {
+        notificationName: notification.name,
+        payload: parsed,
+        channels,
+        results,
+      } satisfies SendNotificationResult;
       instrumentation.custom({
         name: "notification.send.completed",
-        label: "Notification sent",
-        summary: `${notification.name} (${summary.sent} sent, ${summary.skipped} skipped, ${summary.failed} failed)`,
+        label: "Notification completed",
+        summary: `${notification.name} (${resultSummary(results)})`,
         requestId: sendOptions.requestId,
         traceId: sendOptions.traceId,
         spanId: sendOptions.spanId,
@@ -638,12 +1074,14 @@ export function createInlineNotificationDispatcher<Ctx>(
         },
       });
 
-      return {
-        notificationName: notification.name,
-        payload: parsed,
-        channels,
-        results,
-      };
+      if (
+        options.failureMode === "throw" &&
+        results.some((channelResult) => channelResult.status === "failed")
+      ) {
+        throw new NotificationDeliveryError({ result, errors });
+      }
+
+      return result;
     },
   };
 }
@@ -705,6 +1143,176 @@ export function createInlineNotificationsProvider(
   });
 }
 
+function queuedSendOptions(
+  options: Partial<Record<keyof SendNotificationOptions, unknown>>,
+): Omit<SendNotificationOptions, "channels"> {
+  const queued: Omit<SendNotificationOptions, "channels"> = {};
+  if (isRecord(options.metadata)) queued.metadata = options.metadata;
+  if (typeof options.requestId === "string")
+    queued.requestId = options.requestId;
+  if (typeof options.traceId === "string") queued.traceId = options.traceId;
+  if (typeof options.spanId === "string") queued.spanId = options.spanId;
+  if (typeof options.parentSpanId === "string") {
+    queued.parentSpanId = options.parentSpanId;
+  }
+  if (typeof options.traceparent === "string")
+    queued.traceparent = options.traceparent;
+  return queued;
+}
+
+/**
+ * Create a notification dispatcher that enqueues one delivery job per channel.
+ * Separate jobs keep provider retries from resending channels that already
+ * completed successfully.
+ */
+export function createQueuedNotificationDispatcher<Name extends string, Ctx>(
+  options: QueuedNotificationDispatcherOptions<Name, Ctx>,
+): NotificationPort {
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "queued-notifications",
+      watcher: "notifications",
+    },
+  );
+
+  return {
+    async send<N extends NotificationDef>(
+      notification: N,
+      payload: InferNotificationPayload<N>,
+      sendOptions: SendNotificationOptions = {},
+    ) {
+      const registered = options.deliveryJob.registry.get(notification.name);
+      if (!registered) {
+        throw new NotificationRegistryError(
+          `Notification "${notification.name}" is not registered for queued delivery.`,
+        );
+      }
+
+      const parsed = await parseNotificationPayload(registered, payload);
+      const channels = resolveChannelNames(registered, sendOptions);
+      const results: NotificationChannelResult[] = [];
+
+      instrumentation.custom({
+        name: "notification.enqueue.started",
+        label: "Notification enqueue started",
+        summary: notification.name,
+        requestId: sendOptions.requestId,
+        traceId: sendOptions.traceId,
+        spanId: sendOptions.spanId,
+        parentSpanId: sendOptions.parentSpanId,
+        traceparent: sendOptions.traceparent,
+        details: {
+          notificationName: notification.name,
+          channels,
+          metadata: sendOptions.metadata,
+          jobName: options.deliveryJob.name,
+        },
+      });
+
+      for (const channel of channels) {
+        let result: NotificationChannelResult;
+        try {
+          await options.jobs.dispatch(options.deliveryJob, {
+            notificationName: notification.name,
+            channel,
+            payload: parsed,
+            options: queuedSendOptions(sendOptions),
+          });
+          result = {
+            channel,
+            status: "queued",
+            provider: "jobs",
+            details: {
+              jobName: options.deliveryJob.name,
+            },
+          };
+        } catch (error) {
+          result = {
+            channel,
+            status: "failed",
+            reason: error instanceof Error ? error.message : String(error),
+            details: {
+              phase: "enqueue",
+              jobName: options.deliveryJob.name,
+            },
+          };
+        }
+
+        results.push(result);
+        recordChannelResult(
+          instrumentation,
+          notification.name,
+          result,
+          sendOptions,
+        );
+      }
+
+      const result = {
+        notificationName: notification.name,
+        payload: parsed,
+        channels,
+        results,
+      } satisfies SendNotificationResult;
+      instrumentation.custom({
+        name: "notification.enqueue.completed",
+        label: "Notification enqueue completed",
+        summary: `${notification.name} (${resultSummary(results)})`,
+        requestId: sendOptions.requestId,
+        traceId: sendOptions.traceId,
+        spanId: sendOptions.spanId,
+        parentSpanId: sendOptions.parentSpanId,
+        traceparent: sendOptions.traceparent,
+        details: {
+          notificationName: notification.name,
+          channels,
+          results,
+          metadata: sendOptions.metadata,
+          jobName: options.deliveryJob.name,
+        },
+      });
+
+      return result;
+    },
+  };
+}
+
+/**
+ * Options for the queued notifications provider.
+ */
+export interface QueuedNotificationsProviderOptions<Name extends string, Ctx> {
+  /**
+   * Registered notification delivery job.
+   */
+  deliveryJob: NotificationDeliveryJob<Name, Ctx>;
+  /**
+   * Provider name. Defaults to `"queued-notifications"`.
+   */
+  name?: string;
+}
+
+/**
+ * Create a provider that contributes a job-backed notification dispatcher.
+ */
+export function createQueuedNotificationsProvider<Name extends string, Ctx>(
+  options: QueuedNotificationsProviderOptions<Name, Ctx>,
+) {
+  return createProvider<{ jobs: JobDispatcher }>()({
+    name: options.name ?? "queued-notifications",
+    setup({ ports }) {
+      return {
+        ports: {
+          notifications: createQueuedNotificationDispatcher({
+            jobs: ports.jobs,
+            deliveryJob: options.deliveryJob,
+            instrumentation: ports,
+          }),
+        } satisfies InlineNotificationsProviderPorts,
+      };
+    },
+  });
+}
+
 /**
  * Define a mail-backed notification channel.
  *