@beignet/core 0.0.1 → 0.0.3

package/dist/notifications/index.d.ts

@@ -0,0 +1,369 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { SendMailOptions } from "../mail";
+import type { ProviderInstrumentationTarget } 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 declare class NotificationValidationError extends Error {
+    /**
+     * Raw Standard Schema validation issues.
+     */
+    readonly issues: readonly StandardSchemaV1.Issue[];
+    constructor(args: {
+        name: string;
+        issues: readonly StandardSchemaV1.Issue[];
+    });
+}
+/**
+ * Error thrown when notification delivery fails.
+ */
+export declare 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;
+    });
+}
+/**
+ * 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 declare function defineNotification<Name extends string, Payload extends StandardSchema, Ctx = unknown>(name: Name, options: DefineNotificationOptions<Payload, Ctx>): NotificationDef<Name, Payload, Ctx>;
+/**
+ * Validate and parse a notification payload with the notification's Standard
+ * Schema.
+ */
+export declare function parseNotificationPayload<N extends NotificationPayloadDef>(notification: N, payload: unknown): Promise<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 declare function createInlineNotificationDispatcher<Ctx>(options?: InlineNotificationDispatcherOptions<Ctx>): NotificationPort;
+/**
+ * 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 declare function defineMailNotificationChannel<Payload extends StandardSchema, Ctx extends MailNotificationContext>(render: MailNotificationRenderer<Payload, Ctx>): NotificationChannelHandler<Payload, Ctx>;
+/**
+ * Create an in-memory notification port for tests and examples.
+ *
+ * The memory port validates payloads and records notification intent without
+ * running channel handlers.
+ */
+export declare function createMemoryNotificationPort(options?: CreateMemoryNotificationPortOptions): MemoryNotificationPort;
+/**
+ * Create notification helper methods bound to an application context type.
+ */
+export declare function createNotificationHandlers<Ctx>(): NotificationHandlers<Ctx>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/notifications/index.ts"],"names":[],"mappings":"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"}

package/dist/notifications/index.js

@@ -0,0 +1,310 @@
+import { createProviderInstrumentation } from "../providers";
+/**
+ * Error thrown when notification payload validation fails.
+ */
+export class NotificationValidationError extends Error {
+    /**
+     * Raw Standard Schema validation issues.
+     */
+    issues;
+    constructor(args) {
+        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.
+     */
+    notificationName;
+    /**
+     * Channel that failed.
+     */
+    channel;
+    /**
+     * Original channel error.
+     */
+    cause;
+    constructor(args) {
+        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) {
+    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) {
+    return issues
+        .map((issue) => {
+        const path = formatPath(issue.path);
+        return path ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+async function parsePayload(schema, input, args) {
+    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;
+    }
+    throw new Error("Invalid Standard Schema result: missing value");
+}
+async function resolveCtx(ctx) {
+    if (typeof ctx === "function") {
+        return ctx();
+    }
+    return ctx;
+}
+function resolveChannelNames(notification, options) {
+    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) {
+    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, options) {
+    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(notification, payload) {
+    return (await parsePayload(notification.payload, payload, {
+        name: notification.name,
+    }));
+}
+/**
+ * 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(options = {}) {
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "notifications",
+        watcher: "notifications",
+    });
+    return {
+        async send(notification, payload, sendOptions = {}) {
+            const parsed = await parseNotificationPayload(notification, payload);
+            const channels = resolveChannelNames(notification, sendOptions);
+            const ctx = await resolveCtx(options.ctx);
+            const results = [];
+            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,
+                    };
+                    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(render) {
+    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 = {}) {
+    const deliveries = [];
+    const now = options.now ?? (() => new Date());
+    const id = options.id ?? (() => crypto.randomUUID());
+    return {
+        get deliveries() {
+            return deliveries;
+        },
+        async send(notification, payload, sendOptions = {}) {
+            const parsed = await parseNotificationPayload(notification, payload);
+            const channels = resolveChannelNames(notification, sendOptions);
+            const delivery = {
+                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() {
+    return {
+        defineNotification(name, options) {
+            return defineNotification(name, options);
+        },
+        createInlineNotificationDispatcher(options = {}) {
+            return createInlineNotificationDispatcher(options);
+        },
+    };
+}
+//# sourceMappingURL=index.js.map