@beignet/core 0.0.1 → 0.0.2

package/dist/mail/index.d.ts

@@ -3,21 +3,65 @@
  *
  * Shared mail port and test adapters for Beignet applications.
  */
+/**
+ * Value or promise of that value.
+ */
 export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Email address accepted by Beignet mail helpers.
+ */
 export type MailAddress = string | {
+    /**
+     * Email address.
+     */
     email: string;
+    /**
+     * Optional display name.
+     */
     name?: string;
 };
+/**
+ * Single address or address list.
+ */
 export type MailAddressList = MailAddress | readonly MailAddress[];
+/**
+ * Common mail message fields shared by all send options.
+ */
 export interface MailBaseMessage {
+    /**
+     * Required recipients.
+     */
     to: MailAddressList;
+    /**
+     * Message subject.
+     */
     subject: string;
+    /**
+     * Sender address. Providers or adapters may supply a default.
+     */
     from?: MailAddress;
+    /**
+     * Carbon-copy recipients.
+     */
     cc?: MailAddressList;
+    /**
+     * Blind-carbon-copy recipients.
+     */
     bcc?: MailAddressList;
+    /**
+     * Reply-to recipients.
+     */
     replyTo?: MailAddressList;
+    /**
+     * Provider-specific message headers.
+     */
     headers?: Record<string, string>;
 }
+/**
+ * Mail send options.
+ *
+ * A message must include at least one body format: `text` or `html`.
+ */
 export type SendMailOptions = MailBaseMessage & ({
     text: string;
     html?: string;
@@ -25,39 +69,123 @@ export type SendMailOptions = MailBaseMessage & ({
     html: string;
     text?: string;
 });
+/**
+ * Normalized mail message with address fields converted to arrays.
+ */
 export interface NormalizedMailMessage extends MailBaseMessage {
+    /**
+     * Normalized recipients.
+     */
     to: readonly MailAddress[];
+    /**
+     * Sender address after applying any default.
+     */
     from?: MailAddress;
+    /**
+     * Normalized carbon-copy recipients.
+     */
     cc?: readonly MailAddress[];
+    /**
+     * Normalized blind-carbon-copy recipients.
+     */
     bcc?: readonly MailAddress[];
+    /**
+     * Normalized reply-to recipients.
+     */
     replyTo?: readonly MailAddress[];
+    /**
+     * Plain text body.
+     */
     text?: string;
+    /**
+     * HTML body.
+     */
     html?: string;
 }
+/**
+ * Result returned by a mail provider.
+ */
 export interface SendMailResult {
+    /**
+     * Provider message ID when available.
+     */
     id?: string;
+    /**
+     * Provider name.
+     */
     provider?: string;
 }
+/**
+ * App-facing mailer port.
+ */
 export interface MailerPort {
+    /**
+     * Send one mail message.
+     */
     send(message: SendMailOptions): Promise<SendMailResult>;
 }
+/**
+ * Delivery captured by the memory mailer.
+ */
 export interface MemoryMailDelivery {
+    /**
+     * Generated delivery ID.
+     */
     id: string;
+    /**
+     * Normalized message that would have been sent.
+     */
     message: NormalizedMailMessage;
+    /**
+     * Timestamp assigned by the memory mailer.
+     */
     sentAt: Date;
 }
+/**
+ * In-memory mailer port for tests and local examples.
+ */
 export interface MemoryMailerPort extends MailerPort {
+    /**
+     * Captured deliveries.
+     */
     readonly deliveries: readonly MemoryMailDelivery[];
+    /**
+     * Clear captured deliveries.
+     */
     clear(): void;
 }
+/**
+ * Options for `createMemoryMailer(...)`.
+ */
 export interface CreateMemoryMailerOptions {
+    /**
+     * Sender used when a message does not specify `from`.
+     */
     defaultFrom?: MailAddress;
+    /**
+     * Clock used for captured deliveries.
+     */
     now?: () => Date;
+    /**
+     * ID factory used for captured deliveries.
+     */
     id?: () => string;
+    /**
+     * Observer called after a delivery is captured.
+     */
     onSend?: (delivery: MemoryMailDelivery) => MaybePromise<void>;
 }
+/**
+ * Error thrown by mail helpers and provider adapters.
+ */
 export declare class MailDeliveryError extends Error {
+    /**
+     * Provider name when known.
+     */
     readonly provider?: string;
+    /**
+     * Original provider error when available.
+     */
     readonly cause?: unknown;
     constructor(args: {
         provider?: string;
@@ -65,11 +193,32 @@ export declare class MailDeliveryError extends Error {
         cause?: unknown;
     });
 }
+/**
+ * Normalize a single address or address list into an array.
+ *
+ * This helper does not validate email syntax.
+ */
 export declare function normalizeMailAddressList(addresses: MailAddressList | undefined): readonly MailAddress[] | undefined;
+/**
+ * Format one address for providers that accept RFC-like address strings.
+ */
 export declare function formatMailAddress(address: MailAddress): string;
+/**
+ * Format one or more addresses for providers that accept string address fields.
+ */
 export declare function formatMailAddressList(addresses: MailAddressList): string | string[];
+/**
+ * Normalize a mail message and apply a default sender.
+ *
+ * Throws when the message has no recipients.
+ */
 export declare function normalizeMailMessage(message: SendMailOptions, options?: {
     defaultFrom?: MailAddress;
 }): NormalizedMailMessage;
+/**
+ * Create an in-memory mailer for tests, local development, and examples.
+ *
+ * The memory mailer does not send real email or validate address syntax.
+ */
 export declare function createMemoryMailer(options?: CreateMemoryMailerOptions): MemoryMailerPort;
 //# sourceMappingURL=index.d.ts.map

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

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

package/dist/mail/index.js

@@ -3,8 +3,17 @@
  *
  * Shared mail port and test adapters for Beignet applications.
  */
+/**
+ * Error thrown by mail helpers and provider adapters.
+ */
 export class MailDeliveryError extends Error {
+    /**
+     * Provider name when known.
+     */
     provider;
+    /**
+     * Original provider error when available.
+     */
     cause;
     constructor(args) {
         super(args.message);
@@ -13,6 +22,11 @@ export class MailDeliveryError extends Error {
         this.cause = args.cause;
     }
 }
+/**
+ * Normalize a single address or address list into an array.
+ *
+ * This helper does not validate email syntax.
+ */
 export function normalizeMailAddressList(addresses) {
     if (addresses === undefined)
         return undefined;
@@ -22,6 +36,9 @@ function normalizeOptionalMailAddressList(addresses) {
     const normalized = normalizeMailAddressList(addresses);
     return normalized && normalized.length > 0 ? normalized : undefined;
 }
+/**
+ * Format one address for providers that accept RFC-like address strings.
+ */
 export function formatMailAddress(address) {
     if (typeof address === "string")
         return address;
@@ -30,11 +47,19 @@ export function formatMailAddress(address) {
     const escapedName = address.name.replace(/"/g, '\\"');
     return `"${escapedName}" <${address.email}>`;
 }
+/**
+ * Format one or more addresses for providers that accept string address fields.
+ */
 export function formatMailAddressList(addresses) {
     const normalized = normalizeMailAddressList(addresses) ?? [];
     const formatted = normalized.map(formatMailAddress);
     return formatted.length === 1 ? formatted[0] : formatted;
 }
+/**
+ * Normalize a mail message and apply a default sender.
+ *
+ * Throws when the message has no recipients.
+ */
 export function normalizeMailMessage(message, options = {}) {
     const to = normalizeMailAddressList(message.to) ?? [];
     if (to.length === 0) {
@@ -53,6 +78,11 @@ export function normalizeMailMessage(message, options = {}) {
         html: "html" in message ? message.html : undefined,
     };
 }
+/**
+ * Create an in-memory mailer for tests, local development, and examples.
+ *
+ * The memory mailer does not send real email or validate address syntax.
+ */
 export function createMemoryMailer(options = {}) {
     const deliveries = [];
     const now = options.now ?? (() => new Date());

package/dist/mail/index.js.map

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

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