@beignet/core 0.0.1 → 0.0.2

package/src/notifications/index.ts

@@ -0,0 +1,771 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { SendMailOptions } from "../mail";
+import type { ProviderInstrumentationTarget } from "../providers";
+import { createProviderInstrumentation } from "../providers";
+
+/**
+ * Any Standard Schema compatible validator.
+ */
+export type StandardSchema = StandardSchemaV1<unknown, unknown>;
+
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+
+/**
+ * Infer the parsed output type from a Standard Schema.
+ */
+export type InferSchemaOutput<T extends StandardSchemaV1> =
+  StandardSchemaV1.InferOutput<T>;
+
+/**
+ * Minimal notification definition shape accepted by notification ports.
+ */
+export interface NotificationPayloadDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+> {
+  /**
+   * Stable notification name used by dispatchers, tests, and tooling.
+   */
+  readonly name: Name;
+  /**
+   * Standard Schema payload validator.
+   */
+  readonly payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
+  readonly description?: string;
+}
+
+/**
+ * Infer the parsed payload type for a notification definition.
+ */
+export type InferNotificationPayload<N extends NotificationPayloadDef> =
+  N["payload"] extends StandardSchemaV1<unknown, infer Output> ? Output : never;
+
+/**
+ * Result for one notification channel.
+ */
+export interface NotificationChannelResult {
+  /**
+   * Channel name, such as `email`, `sms`, `push`, or `inApp`.
+   */
+  channel: string;
+  /**
+   * Delivery outcome for this channel.
+   */
+  status: "sent" | "skipped" | "failed";
+  /**
+   * Provider delivery ID when available.
+   */
+  id?: string;
+  /**
+   * Provider name when available.
+   */
+  provider?: string;
+  /**
+   * Human-readable skip or failure reason.
+   */
+  reason?: string;
+  /**
+   * Channel-specific metadata. Dispatchers should keep this safe to log.
+   */
+  details?: Record<string, unknown>;
+}
+
+/**
+ * Arguments passed to a notification channel handler.
+ */
+export interface NotificationChannelHandleArgs<
+  Payload extends StandardSchema,
+  Ctx,
+> {
+  /**
+   * Notification definition being delivered.
+   */
+  notification: NotificationDef<string, Payload, Ctx>;
+  /**
+   * Parsed notification payload.
+   */
+  payload: InferSchemaOutput<Payload>;
+  /**
+   * Handler context.
+   */
+  ctx: Ctx;
+  /**
+   * Channel name being delivered.
+   */
+  channel: string;
+}
+
+/**
+ * Handler for one notification channel.
+ */
+export type NotificationChannelHandler<Payload extends StandardSchema, Ctx> = (
+  args: NotificationChannelHandleArgs<Payload, Ctx>,
+) => MaybePromise<NotificationChannelResult | undefined>;
+
+/**
+ * Notification channel handlers keyed by channel name.
+ */
+export type NotificationChannels<Payload extends StandardSchema, Ctx> = Record<
+  string,
+  NotificationChannelHandler<Payload, Ctx>
+>;
+
+/**
+ * Notification definition created by `defineNotification(...)`.
+ */
+export interface NotificationDef<
+  Name extends string = string,
+  Payload extends StandardSchema = StandardSchema,
+  Ctx = unknown,
+> extends NotificationPayloadDef<Name, Payload> {
+  /**
+   * Discriminator for notification definitions.
+   */
+  readonly kind: "notification";
+  /**
+   * Channel handlers that deliver the notification.
+   */
+  readonly channels: NotificationChannels<Payload, Ctx>;
+}
+
+/**
+ * Options for declaring a typed notification.
+ */
+export interface DefineNotificationOptions<
+  Payload extends StandardSchema,
+  Ctx,
+> {
+  /**
+   * Standard Schema payload validator.
+   */
+  payload: Payload;
+  /**
+   * Optional human-readable description for docs and tooling.
+   */
+  description?: string;
+  /**
+   * Channel handlers that deliver the notification.
+   */
+  channels: NotificationChannels<Payload, Ctx>;
+}
+
+/**
+ * Options passed when sending a notification.
+ */
+export interface SendNotificationOptions {
+  /**
+   * Subset of channels to deliver. Defaults to all channels on the definition.
+   */
+  channels?: readonly string[];
+  /**
+   * Optional app metadata attached to memory deliveries and instrumentation.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Request correlation ID for instrumentation.
+   */
+  requestId?: string;
+  /**
+   * Trace identifier for instrumentation.
+   */
+  traceId?: string;
+  /**
+   * Span identifier for instrumentation.
+   */
+  spanId?: string;
+  /**
+   * Parent span identifier for instrumentation.
+   */
+  parentSpanId?: string;
+  /**
+   * W3C traceparent header value for instrumentation.
+   */
+  traceparent?: string;
+}
+
+/**
+ * Result returned after a notification send attempt.
+ */
+export interface SendNotificationResult {
+  /**
+   * Notification name.
+   */
+  notificationName: string;
+  /**
+   * Parsed notification payload.
+   */
+  payload: unknown;
+  /**
+   * Channels selected for delivery.
+   */
+  channels: readonly string[];
+  /**
+   * Per-channel delivery results.
+   */
+  results: readonly NotificationChannelResult[];
+}
+
+/**
+ * App-facing notification port.
+ */
+export interface NotificationPort {
+  /**
+   * Send a typed notification.
+   */
+  send<N extends NotificationDef>(
+    notification: N,
+    payload: InferNotificationPayload<N>,
+    options?: SendNotificationOptions,
+  ): Promise<SendNotificationResult>;
+}
+
+/**
+ * Options for the inline notification dispatcher.
+ */
+export interface InlineNotificationDispatcherOptions<Ctx> {
+  /**
+   * Static notification context or factory evaluated for each send.
+   */
+  ctx?: Ctx | (() => MaybePromise<Ctx>);
+  /**
+   * Called when a channel handler fails. When omitted, errors are rethrown to
+   * the caller as `NotificationDeliveryError`.
+   */
+  onError?: (
+    error: unknown,
+    args: NotificationChannelHandleArgs<StandardSchema, Ctx>,
+  ) => MaybePromise<NotificationChannelResult | undefined>;
+  /**
+   * Optional devtools/provider instrumentation target.
+   */
+  instrumentation?: ProviderInstrumentationTarget;
+}
+
+/**
+ * Delivery captured by the memory notification port.
+ */
+export interface MemoryNotificationDelivery {
+  /**
+   * Generated delivery ID.
+   */
+  id: string;
+  /**
+   * Notification name.
+   */
+  notificationName: string;
+  /**
+   * Parsed payload that would have been sent.
+   */
+  payload: unknown;
+  /**
+   * Selected channels.
+   */
+  channels: readonly string[];
+  /**
+   * Optional app metadata supplied by the caller.
+   */
+  metadata?: Record<string, unknown>;
+  /**
+   * Timestamp assigned by the memory port.
+   */
+  sentAt: Date;
+}
+
+/**
+ * In-memory notification port for tests and local examples.
+ */
+export interface MemoryNotificationPort extends NotificationPort {
+  /**
+   * Captured notification sends.
+   */
+  readonly deliveries: readonly MemoryNotificationDelivery[];
+  /**
+   * Clear captured notification sends.
+   */
+  clear(): void;
+}
+
+/**
+ * Options for `createMemoryNotificationPort(...)`.
+ */
+export interface CreateMemoryNotificationPortOptions {
+  /**
+   * Clock used for captured deliveries.
+   */
+  now?: () => Date;
+  /**
+   * ID factory used for captured deliveries.
+   */
+  id?: () => string;
+  /**
+   * Observer called after a delivery is captured.
+   */
+  onSend?: (delivery: MemoryNotificationDelivery) => MaybePromise<void>;
+}
+
+/**
+ * Context shape required by `defineMailNotificationChannel(...)`.
+ */
+export interface MailNotificationContext {
+  ports: {
+    mailer: {
+      send(message: SendMailOptions): MaybePromise<{
+        id?: string;
+        provider?: string;
+      }>;
+    };
+  };
+}
+
+/**
+ * Render a mail message for one notification payload.
+ */
+export type MailNotificationRenderer<
+  Payload extends StandardSchema,
+  Ctx extends MailNotificationContext,
+> = (
+  args: NotificationChannelHandleArgs<Payload, Ctx>,
+) => MaybePromise<SendMailOptions | undefined>;
+
+/**
+ * Context-bound notification helper factory.
+ */
+export interface NotificationHandlers<Ctx> {
+  /**
+   * Define a notification with the bound context type.
+   */
+  defineNotification<Name extends string, Payload extends StandardSchema>(
+    name: Name,
+    options: DefineNotificationOptions<Payload, Ctx>,
+  ): NotificationDef<Name, Payload, Ctx>;
+
+  /**
+   * Create an inline dispatcher with the bound context type.
+   */
+  createInlineNotificationDispatcher(
+    options?: InlineNotificationDispatcherOptions<Ctx>,
+  ): NotificationPort;
+}
+
+/**
+ * Error thrown when notification payload validation fails.
+ */
+export class NotificationValidationError extends Error {
+  /**
+   * Raw Standard Schema validation issues.
+   */
+  readonly issues: readonly StandardSchemaV1.Issue[];
+
+  constructor(args: {
+    name: string;
+    issues: readonly StandardSchemaV1.Issue[];
+  }) {
+    super(
+      `Notification "${args.name}" payload validation failed: ${formatIssues(args.issues)}`,
+    );
+    this.name = "NotificationValidationError";
+    this.issues = args.issues;
+  }
+}
+
+/**
+ * Error thrown when notification delivery fails.
+ */
+export class NotificationDeliveryError extends Error {
+  /**
+   * Notification name.
+   */
+  readonly notificationName: string;
+  /**
+   * Channel that failed.
+   */
+  readonly channel: string;
+  /**
+   * Original channel error.
+   */
+  readonly cause: unknown;
+
+  constructor(args: {
+    notificationName: string;
+    channel: string;
+    cause: unknown;
+  }) {
+    super(
+      `Notification "${args.notificationName}" failed on channel "${args.channel}": ${
+        args.cause instanceof Error ? args.cause.message : String(args.cause)
+      }`,
+    );
+    this.name = "NotificationDeliveryError";
+    this.notificationName = args.notificationName;
+    this.channel = args.channel;
+    this.cause = args.cause;
+  }
+}
+
+function formatPath(path: StandardSchemaV1.Issue["path"]): string {
+  if (!path?.length) return "";
+
+  return path
+    .map((segment) =>
+      typeof segment === "object" && segment !== null && "key" in segment
+        ? String(segment.key)
+        : String(segment),
+    )
+    .join(".");
+}
+
+function formatIssues(issues: readonly StandardSchemaV1.Issue[]): string {
+  return issues
+    .map((issue) => {
+      const path = formatPath(issue.path);
+      return path ? `${path}: ${issue.message}` : issue.message;
+    })
+    .join("; ");
+}
+
+async function parsePayload<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  input: unknown,
+  args: { name: string },
+): Promise<InferSchemaOutput<Schema>> {
+  const result = await schema["~standard"].validate(input);
+
+  if (result.issues?.length) {
+    throw new NotificationValidationError({
+      name: args.name,
+      issues: result.issues,
+    });
+  }
+
+  if ("value" in result) {
+    return result.value as InferSchemaOutput<Schema>;
+  }
+
+  throw new Error("Invalid Standard Schema result: missing value");
+}
+
+async function resolveCtx<Ctx>(
+  ctx: Ctx | (() => MaybePromise<Ctx>) | undefined,
+): Promise<Ctx> {
+  if (typeof ctx === "function") {
+    return (ctx as () => MaybePromise<Ctx>)();
+  }
+
+  return ctx as Ctx;
+}
+
+function resolveChannelNames(
+  notification: {
+    name: string;
+    channels: Record<string, unknown>;
+  },
+  options:
+    | {
+        channels?: readonly string[];
+      }
+    | undefined,
+): readonly string[] {
+  const available = Object.keys(notification.channels);
+  const selected = options?.channels ?? available;
+
+  for (const channel of selected) {
+    if (!notification.channels[channel]) {
+      throw new Error(
+        `Notification "${notification.name}" does not define channel "${channel}".`,
+      );
+    }
+  }
+
+  return selected;
+}
+
+function summarizeResults(results: readonly NotificationChannelResult[]) {
+  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 };
+}
+
+/**
+ * Define a typed notification.
+ *
+ * Notifications represent user-facing communication intent. Channel handlers
+ * decide how that intent becomes mail, SMS, push, in-app delivery, or another
+ * app-owned channel.
+ */
+export function defineNotification<
+  Name extends string,
+  Payload extends StandardSchema,
+  Ctx = unknown,
+>(
+  name: Name,
+  options: DefineNotificationOptions<Payload, Ctx>,
+): NotificationDef<Name, Payload, Ctx> {
+  return {
+    kind: "notification",
+    name,
+    payload: options.payload,
+    description: options.description,
+    channels: options.channels,
+  };
+}
+
+/**
+ * Validate and parse a notification payload with the notification's Standard
+ * Schema.
+ */
+export async function parseNotificationPayload<
+  N extends NotificationPayloadDef,
+>(notification: N, payload: unknown): Promise<InferNotificationPayload<N>> {
+  return (await parsePayload(notification.payload, payload, {
+    name: notification.name,
+  })) as InferNotificationPayload<N>;
+}
+
+/**
+ * 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.
+ */
+export function createInlineNotificationDispatcher<Ctx>(
+  options: InlineNotificationDispatcherOptions<Ctx> = {},
+): NotificationPort {
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "notifications",
+      watcher: "notifications",
+    },
+  );
+
+  return {
+    async send<N extends NotificationDef<string, StandardSchema, Ctx>>(
+      notification: N,
+      payload: InferNotificationPayload<N>,
+      sendOptions: SendNotificationOptions = {},
+    ) {
+      const parsed = await parseNotificationPayload(notification, payload);
+      const channels = resolveChannelNames(notification, sendOptions);
+      const ctx = await resolveCtx(options.ctx);
+      const results: NotificationChannelResult[] = [];
+
+      instrumentation.custom({
+        name: "notification.send.started",
+        label: "Notification 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,
+        },
+      });
+
+      for (const channel of channels) {
+        const handler = notification.channels[channel];
+
+        try {
+          const result = await handler({
+            notification,
+            payload: parsed,
+            ctx,
+            channel,
+          });
+
+          results.push(
+            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);
+            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 summary = summarizeResults(results);
+      instrumentation.custom({
+        name: "notification.send.completed",
+        label: "Notification sent",
+        summary: `${notification.name} (${summary.sent} sent, ${summary.skipped} skipped, ${summary.failed} failed)`,
+        requestId: sendOptions.requestId,
+        traceId: sendOptions.traceId,
+        spanId: sendOptions.spanId,
+        parentSpanId: sendOptions.parentSpanId,
+        traceparent: sendOptions.traceparent,
+        details: {
+          notificationName: notification.name,
+          channels,
+          results,
+          metadata: sendOptions.metadata,
+        },
+      });
+
+      return {
+        notificationName: notification.name,
+        payload: parsed,
+        channels,
+        results,
+      };
+    },
+  };
+}
+
+/**
+ * Define a mail-backed notification channel.
+ *
+ * Return `undefined` from the renderer when the channel should be skipped, for
+ * example when a recipient does not have an email address.
+ */
+export function defineMailNotificationChannel<
+  Payload extends StandardSchema,
+  Ctx extends MailNotificationContext,
+>(
+  render: MailNotificationRenderer<Payload, Ctx>,
+): NotificationChannelHandler<Payload, Ctx> {
+  return async (args) => {
+    const message = await render(args);
+    if (!message) {
+      return {
+        channel: args.channel,
+        status: "skipped",
+        reason: "No mail message was returned.",
+      };
+    }
+
+    const result = await args.ctx.ports.mailer.send(message);
+    return {
+      channel: args.channel,
+      status: "sent",
+      id: result.id,
+      provider: result.provider,
+    };
+  };
+}
+
+/**
+ * Create an in-memory notification port for tests and examples.
+ *
+ * The memory port validates payloads and records notification intent without
+ * running channel handlers.
+ */
+export function createMemoryNotificationPort(
+  options: CreateMemoryNotificationPortOptions = {},
+): MemoryNotificationPort {
+  const deliveries: MemoryNotificationDelivery[] = [];
+  const now = options.now ?? (() => new Date());
+  const id = options.id ?? (() => crypto.randomUUID());
+
+  return {
+    get deliveries() {
+      return deliveries;
+    },
+
+    async send<N extends NotificationDef>(
+      notification: N,
+      payload: InferNotificationPayload<N>,
+      sendOptions: SendNotificationOptions = {},
+    ) {
+      const parsed = await parseNotificationPayload(notification, payload);
+      const channels = resolveChannelNames(notification, sendOptions);
+      const delivery: MemoryNotificationDelivery = {
+        id: id(),
+        notificationName: notification.name,
+        payload: parsed,
+        channels,
+        metadata: sendOptions.metadata,
+        sentAt: now(),
+      };
+
+      deliveries.push(delivery);
+      await options.onSend?.(delivery);
+
+      return {
+        notificationName: notification.name,
+        payload: parsed,
+        channels,
+        results: channels.map((channel) => ({
+          channel,
+          status: "sent",
+          id: delivery.id,
+          provider: "memory",
+          details: {
+            mode: "intent",
+          },
+        })),
+      };
+    },
+
+    clear() {
+      deliveries.length = 0;
+    },
+  };
+}
+
+/**
+ * Create notification helper methods bound to an application context type.
+ */
+export function createNotificationHandlers<Ctx>(): NotificationHandlers<Ctx> {
+  return {
+    defineNotification<Name extends string, Payload extends StandardSchema>(
+      name: Name,
+      options: DefineNotificationOptions<Payload, Ctx>,
+    ): NotificationDef<Name, Payload, Ctx> {
+      return defineNotification(name, options);
+    },
+
+    createInlineNotificationDispatcher(
+      options: InlineNotificationDispatcherOptions<Ctx> = {},
+    ): NotificationPort {
+      return createInlineNotificationDispatcher(options);
+    },
+  };
+}