@upyo/logtape 0.6.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,58 @@
+<!-- deno-fmt-ignore-file -->
+
+@upyo/logtape
+=============
+
+*@upyo/logtape* records Upyo email delivery lifecycle events through
+[LogTape].  It can act as a log-only transport during local development or
+decorate another transport while preserving its delivery behavior.
+
+[LogTape]: https://logtape.org/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@upyo/logtape jsr:@logtape/logtape
+pnpm add @upyo/logtape @logtape/logtape
+~~~~
+
+
+Usage
+-----
+
+Configure LogTape in your application, then create a log-only transport:
+
+~~~~ typescript
+import { configure, getConsoleSink } from "@logtape/logtape";
+import { LogTapeTransport } from "@upyo/logtape";
+
+await configure({
+  sinks: { console: getConsoleSink() },
+  loggers: [
+    { category: ["upyo"], lowestLevel: "debug", sinks: ["console"] },
+  ],
+});
+
+const transport = new LogTapeTransport();
+const receipt = await transport.send(message);
+~~~~
+
+To deliver messages through another transport, pass it in the options object:
+
+~~~~ typescript
+const transport = new LogTapeTransport({
+  transport: smtpTransport,
+  category: ["application", "email"],
+  levels: {
+    sending: "debug",
+    sent: "info",
+    failed: "error",
+  },
+});
+~~~~
+
+Complete messages are excluded from structured logs by default.  Set
+`recordMessage: true` only when the configured sinks and redaction rules can
+safely handle addresses, bodies, headers, and attachment data.

package/dist/index.cjs

@@ -0,0 +1,329 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __logtape_logtape = __toESM(require("@logtape/logtape"));
+
+//#region src/config.ts
+/**
+* Resolves LogTape transport options with their defaults.
+*
+* @param options User-provided transport options.
+* @returns Fully resolved transport options.
+* @since 0.6.0
+*/
+function resolveLogTapeTransportOptions(options) {
+	const category = options.category ?? ["upyo"];
+	return {
+		transport: options.transport,
+		category: typeof category === "string" ? [category] : [...category],
+		recordMessage: options.recordMessage ?? false,
+		levels: {
+			sending: options.levels?.sending ?? "debug",
+			sent: options.levels?.sent ?? "info",
+			failed: options.levels?.failed ?? "error"
+		}
+	};
+}
+
+//#endregion
+//#region src/pending-queue.ts
+/**
+* Internal linked FIFO queue for messages awaiting delivery receipts.
+*
+* Both enqueue and dequeue operations take constant time, without retaining
+* references to values that have already been dequeued.
+*
+* @typeParam T The queued value type.
+* @since 0.6.0
+*/
+var PendingQueue = class {
+	head;
+	tail;
+	valueCount = 0;
+	/** Number of values waiting in the queue. */
+	get size() {
+		return this.valueCount;
+	}
+	/**
+	* Adds a value to the end of the queue.
+	*
+	* @param value The value to enqueue.
+	*/
+	enqueue(value) {
+		const node = { value };
+		if (this.tail == null) this.head = node;
+		else this.tail.next = node;
+		this.tail = node;
+		this.valueCount++;
+	}
+	/**
+	* Removes and returns the value at the front of the queue.
+	*
+	* @returns The first queued value, or `undefined` when the queue is empty.
+	*/
+	dequeue() {
+		const node = this.head;
+		if (node == null) return void 0;
+		this.head = node.next;
+		node.next = void 0;
+		this.valueCount--;
+		if (this.head == null) this.tail = void 0;
+		return node.value;
+	}
+	/** Iterates over queued values without removing them. */
+	*[Symbol.iterator]() {
+		let node = this.head;
+		while (node != null) {
+			yield node.value;
+			node = node.next;
+		}
+	}
+};
+
+//#endregion
+//#region src/logtape-transport.ts
+/**
+* Transport that records email delivery lifecycle events through LogTape.
+*
+* With no wrapped transport, this class acts as a log-only transport and
+* returns synthetic successful receipts.  When a transport is supplied, it
+* decorates that transport without changing its receipts or thrown errors.
+*
+* @typeParam TProviderId The provider id of the wrapped transport, or
+*                        `"logtape"` in log-only mode.
+* @since 0.6.0
+*/
+var LogTapeTransport = class {
+	/** Provider id used by receipts from this transport. */
+	id;
+	/** Fully resolved transport options. */
+	config;
+	logger;
+	wrappedTransport;
+	/**
+	* Creates a LogTape transport.
+	*
+	* @param options Logging and optional wrapped transport configuration.
+	*/
+	constructor(...[options]) {
+		this.config = resolveLogTapeTransportOptions(options ?? {});
+		this.wrappedTransport = this.config.transport;
+		this.id = this.wrappedTransport?.id ?? "logtape";
+		this.logger = (0, __logtape_logtape.getLogger)(this.config.category);
+	}
+	/**
+	* Sends one email while recording its delivery lifecycle.
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options, including cancellation.
+	* @returns The wrapped transport receipt, or a synthetic successful receipt
+	*          in log-only mode.
+	* @throws {DOMException} If the operation is aborted.
+	* @throws {Error} If the wrapped transport throws an error.
+	*/
+	send(message, options) {
+		return this.sendOne(message, options, "send");
+	}
+	/**
+	* Sends multiple emails while recording each delivery lifecycle.
+	*
+	* A wrapped transport's `sendMany()` implementation is used directly so
+	* provider-specific batching and streaming behavior are preserved.
+	*
+	* @param messages Email messages to send.
+	* @param options Optional transport options, including cancellation.
+	* @returns An async iterable of unmodified delivery receipts.
+	* @throws {DOMException} If the operation is aborted.
+	* @throws {Error} If the wrapped transport throws an error.
+	*/
+	async *sendMany(messages, options) {
+		options?.signal?.throwIfAborted();
+		if (this.wrappedTransport == null) {
+			for await (const message of messages) yield await this.sendOne(message, options, "sendMany");
+			return;
+		}
+		const pending = new PendingQueue();
+		const batchStartedAt = performance.now();
+		let consumedCount = 0;
+		let completedCount = 0;
+		const observedMessages = this.observeMessages(messages, pending, options, () => consumedCount++);
+		try {
+			for await (const receipt of this.wrappedTransport.sendMany(observedMessages, options)) {
+				const current = pending.dequeue();
+				completedCount++;
+				this.logReceipt(receipt, current, "sendMany");
+				yield receipt;
+			}
+		} catch (error) {
+			const batchProperties = {
+				consumedCount,
+				completedCount,
+				pendingCount: pending.size
+			};
+			if (pending.size < 1) this.logThrownError(error, void 0, "sendMany", batchStartedAt, batchProperties);
+			else for (const pendingMessage of pending) this.logThrownError(error, pendingMessage.message, "sendMany", pendingMessage.startedAt, batchProperties);
+			throw error;
+		}
+	}
+	/**
+	* Disposes the wrapped transport when it supports explicit resource
+	* management.
+	*/
+	async [Symbol.asyncDispose]() {
+		const transport = this.wrappedTransport;
+		if (transport == null) return;
+		if (isAsyncDisposable(transport)) {
+			await transport[Symbol.asyncDispose]();
+			return;
+		}
+		if (isDisposable(transport)) transport[Symbol.dispose]();
+	}
+	async sendOne(message, options, operation) {
+		options?.signal?.throwIfAborted();
+		const startedAt = performance.now();
+		this.logSending(message, operation);
+		try {
+			const receipt = this.wrappedTransport == null ? this.createSyntheticReceipt() : await this.wrappedTransport.send(message, options);
+			this.logReceipt(receipt, {
+				message,
+				startedAt
+			}, operation);
+			return receipt;
+		} catch (error) {
+			this.logThrownError(error, message, operation, startedAt);
+			throw error;
+		}
+	}
+	async *observeMessages(messages, pending, options, onConsume) {
+		for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			const startedAt = performance.now();
+			this.logSending(message, "sendMany");
+			pending.enqueue({
+				message,
+				startedAt
+			});
+			onConsume();
+			yield message;
+		}
+	}
+	createSyntheticReceipt() {
+		return {
+			successful: true,
+			messageId: `logtape-${crypto.randomUUID()}`,
+			provider: this.id,
+			attempts: 1,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	logSending(message, operation) {
+		this.log(this.config.levels.sending, "Sending email.", {
+			...this.getMessageProperties(message),
+			event: "email.sending",
+			operation,
+			transportId: this.id
+		});
+	}
+	logReceipt(receipt, pending, operation) {
+		const durationMilliseconds = pending == null ? void 0 : performance.now() - pending.startedAt;
+		const messageProperties = pending == null ? {} : this.getMessageProperties(pending.message);
+		if (receipt.successful) {
+			this.log(this.config.levels.sent, "Email sent.", {
+				...messageProperties,
+				event: "email.sent",
+				operation,
+				transportId: this.id,
+				durationMilliseconds,
+				messageId: receipt.messageId,
+				provider: receipt.provider ?? this.id,
+				receipt
+			});
+			return;
+		}
+		this.log(this.config.levels.failed, "Failed to send email.", {
+			...messageProperties,
+			event: "email.failed",
+			operation,
+			transportId: this.id,
+			durationMilliseconds,
+			errorMessages: receipt.errorMessages,
+			errors: receipt.errors,
+			retryable: receipt.retryable,
+			provider: receipt.provider ?? this.id,
+			attempts: receipt.attempts,
+			receipt
+		});
+	}
+	logThrownError(error, message, operation, startedAt, extraProperties = {}) {
+		this.log(this.config.levels.failed, "Failed to send email: {error}", {
+			...message == null ? {} : this.getMessageProperties(message),
+			...extraProperties,
+			event: "email.failed",
+			operation,
+			transportId: this.id,
+			durationMilliseconds: performance.now() - startedAt,
+			error
+		});
+	}
+	getMessageProperties(message) {
+		return {
+			recipientCount: message.recipients.length,
+			ccRecipientCount: message.ccRecipients.length,
+			bccRecipientCount: message.bccRecipients.length,
+			attachmentCount: message.attachments.length,
+			priority: message.priority,
+			...this.config.recordMessage ? { message } : {}
+		};
+	}
+	log(level, message, properties) {
+		switch (level) {
+			case "trace":
+				this.logger.trace(message, properties);
+				break;
+			case "debug":
+				this.logger.debug(message, properties);
+				break;
+			case "info":
+				this.logger.info(message, properties);
+				break;
+			case "warning":
+				this.logger.warning(message, properties);
+				break;
+			case "error":
+				this.logger.error(message, properties);
+				break;
+			case "fatal":
+				this.logger.fatal(message, properties);
+				break;
+		}
+	}
+};
+function isAsyncDisposable(value) {
+	return Symbol.asyncDispose in value && typeof value[Symbol.asyncDispose] === "function";
+}
+function isDisposable(value) {
+	return Symbol.dispose in value && typeof value[Symbol.dispose] === "function";
+}
+
+//#endregion
+exports.LogTapeTransport = LogTapeTransport;

package/dist/index.d.cts

@@ -0,0 +1,157 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+import { LogLevel } from "@logtape/logtape";
+
+//#region src/config.d.ts
+
+/**
+ * Log levels used for email delivery lifecycle events.
+ *
+ * @since 0.6.0
+ */
+interface LogTapeTransportLevels {
+  /**
+   * Level used before an email is handed to the transport.
+   *
+   * @default "debug"
+   */
+  readonly sending?: LogLevel;
+  /**
+   * Level used after an email is sent successfully.
+   *
+   * @default "info"
+   */
+  readonly sent?: LogLevel;
+  /**
+   * Level used when a transport returns a failed receipt or throws.
+   *
+   * @default "error"
+   */
+  readonly failed?: LogLevel;
+}
+/**
+ * Options for {@link LogTapeTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ * @since 0.6.0
+ */
+interface LogTapeTransportOptions<TProviderId extends string = "logtape"> {
+  /**
+   * Transport that performs the actual delivery.
+   *
+   * When omitted, the LogTape transport only logs the delivery and returns a
+   * synthetic successful receipt.
+   */
+  readonly transport?: Transport<TProviderId>;
+  /**
+   * LogTape category used for delivery logs.
+   *
+   * @default ["upyo"]
+   */
+  readonly category?: string | readonly string[];
+  /**
+   * Whether to include the complete email message in structured log
+   * properties.
+   *
+   * Messages may contain sensitive or large values, including email bodies,
+   * headers, and attachment data.
+   *
+   * @default false
+   */
+  readonly recordMessage?: boolean;
+  /**
+   * Levels used for delivery lifecycle events.
+   */
+  readonly levels?: LogTapeTransportLevels;
+}
+/**
+ * Fully resolved options used by {@link LogTapeTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ * @since 0.6.0
+ */
+interface ResolvedLogTapeTransportOptions<TProviderId extends string = "logtape"> {
+  /** Transport that performs the actual delivery, if configured. */
+  readonly transport?: Transport<TProviderId>;
+  /** Resolved LogTape category. */
+  readonly category: readonly string[];
+  /** Whether complete messages are included in structured logs. */
+  readonly recordMessage: boolean;
+  /** Resolved delivery lifecycle log levels. */
+  readonly levels: Required<LogTapeTransportLevels>;
+}
+/**
+ * Resolves LogTape transport options with their defaults.
+ *
+ * @param options User-provided transport options.
+ * @returns Fully resolved transport options.
+ * @since 0.6.0
+ */
+//#endregion
+//#region src/logtape-transport.d.ts
+type LogTapeTransportConstructorArguments<TProviderId extends string> = [TProviderId] extends ["logtape"] ? [options?: LogTapeTransportOptions<TProviderId>] : [options: LogTapeTransportOptions<TProviderId> & {
+  readonly transport: Transport<TProviderId>;
+}];
+/**
+ * Transport that records email delivery lifecycle events through LogTape.
+ *
+ * With no wrapped transport, this class acts as a log-only transport and
+ * returns synthetic successful receipts.  When a transport is supplied, it
+ * decorates that transport without changing its receipts or thrown errors.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport, or
+ *                        `"logtape"` in log-only mode.
+ * @since 0.6.0
+ */
+declare class LogTapeTransport<TProviderId extends string = "logtape"> implements Transport<TProviderId>, AsyncDisposable {
+  /** Provider id used by receipts from this transport. */
+  readonly id: TProviderId;
+  /** Fully resolved transport options. */
+  readonly config: ResolvedLogTapeTransportOptions<TProviderId>;
+  private readonly logger;
+  private readonly wrappedTransport?;
+  /**
+   * Creates a LogTape transport.
+   *
+   * @param options Logging and optional wrapped transport configuration.
+   */
+  constructor(...[options]: LogTapeTransportConstructorArguments<TProviderId>);
+  /**
+   * Sends one email while recording its delivery lifecycle.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns The wrapped transport receipt, or a synthetic successful receipt
+   *          in log-only mode.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends multiple emails while recording each delivery lifecycle.
+   *
+   * A wrapped transport's `sendMany()` implementation is used directly so
+   * provider-specific batching and streaming behavior are preserved.
+   *
+   * @param messages Email messages to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns An async iterable of unmodified delivery receipts.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports explicit resource
+   * management.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  private sendOne;
+  private observeMessages;
+  private createSyntheticReceipt;
+  private logSending;
+  private logReceipt;
+  private logThrownError;
+  private getMessageProperties;
+  private log;
+}
+//#endregion
+export { LogTapeTransport, LogTapeTransportLevels, LogTapeTransportOptions, ResolvedLogTapeTransportOptions };

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+import { LogLevel } from "@logtape/logtape";
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Log levels used for email delivery lifecycle events.
+ *
+ * @since 0.6.0
+ */
+interface LogTapeTransportLevels {
+  /**
+   * Level used before an email is handed to the transport.
+   *
+   * @default "debug"
+   */
+  readonly sending?: LogLevel;
+  /**
+   * Level used after an email is sent successfully.
+   *
+   * @default "info"
+   */
+  readonly sent?: LogLevel;
+  /**
+   * Level used when a transport returns a failed receipt or throws.
+   *
+   * @default "error"
+   */
+  readonly failed?: LogLevel;
+}
+/**
+ * Options for {@link LogTapeTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ * @since 0.6.0
+ */
+interface LogTapeTransportOptions<TProviderId extends string = "logtape"> {
+  /**
+   * Transport that performs the actual delivery.
+   *
+   * When omitted, the LogTape transport only logs the delivery and returns a
+   * synthetic successful receipt.
+   */
+  readonly transport?: Transport<TProviderId>;
+  /**
+   * LogTape category used for delivery logs.
+   *
+   * @default ["upyo"]
+   */
+  readonly category?: string | readonly string[];
+  /**
+   * Whether to include the complete email message in structured log
+   * properties.
+   *
+   * Messages may contain sensitive or large values, including email bodies,
+   * headers, and attachment data.
+   *
+   * @default false
+   */
+  readonly recordMessage?: boolean;
+  /**
+   * Levels used for delivery lifecycle events.
+   */
+  readonly levels?: LogTapeTransportLevels;
+}
+/**
+ * Fully resolved options used by {@link LogTapeTransport}.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport.
+ * @since 0.6.0
+ */
+interface ResolvedLogTapeTransportOptions<TProviderId extends string = "logtape"> {
+  /** Transport that performs the actual delivery, if configured. */
+  readonly transport?: Transport<TProviderId>;
+  /** Resolved LogTape category. */
+  readonly category: readonly string[];
+  /** Whether complete messages are included in structured logs. */
+  readonly recordMessage: boolean;
+  /** Resolved delivery lifecycle log levels. */
+  readonly levels: Required<LogTapeTransportLevels>;
+}
+/**
+ * Resolves LogTape transport options with their defaults.
+ *
+ * @param options User-provided transport options.
+ * @returns Fully resolved transport options.
+ * @since 0.6.0
+ */
+//#endregion
+//#region src/logtape-transport.d.ts
+type LogTapeTransportConstructorArguments<TProviderId extends string> = [TProviderId] extends ["logtape"] ? [options?: LogTapeTransportOptions<TProviderId>] : [options: LogTapeTransportOptions<TProviderId> & {
+  readonly transport: Transport<TProviderId>;
+}];
+/**
+ * Transport that records email delivery lifecycle events through LogTape.
+ *
+ * With no wrapped transport, this class acts as a log-only transport and
+ * returns synthetic successful receipts.  When a transport is supplied, it
+ * decorates that transport without changing its receipts or thrown errors.
+ *
+ * @typeParam TProviderId The provider id of the wrapped transport, or
+ *                        `"logtape"` in log-only mode.
+ * @since 0.6.0
+ */
+declare class LogTapeTransport<TProviderId extends string = "logtape"> implements Transport<TProviderId>, AsyncDisposable {
+  /** Provider id used by receipts from this transport. */
+  readonly id: TProviderId;
+  /** Fully resolved transport options. */
+  readonly config: ResolvedLogTapeTransportOptions<TProviderId>;
+  private readonly logger;
+  private readonly wrappedTransport?;
+  /**
+   * Creates a LogTape transport.
+   *
+   * @param options Logging and optional wrapped transport configuration.
+   */
+  constructor(...[options]: LogTapeTransportConstructorArguments<TProviderId>);
+  /**
+   * Sends one email while recording its delivery lifecycle.
+   *
+   * @param message The email message to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns The wrapped transport receipt, or a synthetic successful receipt
+   *          in log-only mode.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt<TProviderId>>;
+  /**
+   * Sends multiple emails while recording each delivery lifecycle.
+   *
+   * A wrapped transport's `sendMany()` implementation is used directly so
+   * provider-specific batching and streaming behavior are preserved.
+   *
+   * @param messages Email messages to send.
+   * @param options Optional transport options, including cancellation.
+   * @returns An async iterable of unmodified delivery receipts.
+   * @throws {DOMException} If the operation is aborted.
+   * @throws {Error} If the wrapped transport throws an error.
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt<TProviderId>>;
+  /**
+   * Disposes the wrapped transport when it supports explicit resource
+   * management.
+   */
+  [Symbol.asyncDispose](): Promise<void>;
+  private sendOne;
+  private observeMessages;
+  private createSyntheticReceipt;
+  private logSending;
+  private logReceipt;
+  private logThrownError;
+  private getMessageProperties;
+  private log;
+}
+//#endregion
+export { LogTapeTransport, LogTapeTransportLevels, LogTapeTransportOptions, ResolvedLogTapeTransportOptions };

package/dist/index.js

@@ -0,0 +1,306 @@
+import { getLogger } from "@logtape/logtape";
+
+//#region src/config.ts
+/**
+* Resolves LogTape transport options with their defaults.
+*
+* @param options User-provided transport options.
+* @returns Fully resolved transport options.
+* @since 0.6.0
+*/
+function resolveLogTapeTransportOptions(options) {
+	const category = options.category ?? ["upyo"];
+	return {
+		transport: options.transport,
+		category: typeof category === "string" ? [category] : [...category],
+		recordMessage: options.recordMessage ?? false,
+		levels: {
+			sending: options.levels?.sending ?? "debug",
+			sent: options.levels?.sent ?? "info",
+			failed: options.levels?.failed ?? "error"
+		}
+	};
+}
+
+//#endregion
+//#region src/pending-queue.ts
+/**
+* Internal linked FIFO queue for messages awaiting delivery receipts.
+*
+* Both enqueue and dequeue operations take constant time, without retaining
+* references to values that have already been dequeued.
+*
+* @typeParam T The queued value type.
+* @since 0.6.0
+*/
+var PendingQueue = class {
+	head;
+	tail;
+	valueCount = 0;
+	/** Number of values waiting in the queue. */
+	get size() {
+		return this.valueCount;
+	}
+	/**
+	* Adds a value to the end of the queue.
+	*
+	* @param value The value to enqueue.
+	*/
+	enqueue(value) {
+		const node = { value };
+		if (this.tail == null) this.head = node;
+		else this.tail.next = node;
+		this.tail = node;
+		this.valueCount++;
+	}
+	/**
+	* Removes and returns the value at the front of the queue.
+	*
+	* @returns The first queued value, or `undefined` when the queue is empty.
+	*/
+	dequeue() {
+		const node = this.head;
+		if (node == null) return void 0;
+		this.head = node.next;
+		node.next = void 0;
+		this.valueCount--;
+		if (this.head == null) this.tail = void 0;
+		return node.value;
+	}
+	/** Iterates over queued values without removing them. */
+	*[Symbol.iterator]() {
+		let node = this.head;
+		while (node != null) {
+			yield node.value;
+			node = node.next;
+		}
+	}
+};
+
+//#endregion
+//#region src/logtape-transport.ts
+/**
+* Transport that records email delivery lifecycle events through LogTape.
+*
+* With no wrapped transport, this class acts as a log-only transport and
+* returns synthetic successful receipts.  When a transport is supplied, it
+* decorates that transport without changing its receipts or thrown errors.
+*
+* @typeParam TProviderId The provider id of the wrapped transport, or
+*                        `"logtape"` in log-only mode.
+* @since 0.6.0
+*/
+var LogTapeTransport = class {
+	/** Provider id used by receipts from this transport. */
+	id;
+	/** Fully resolved transport options. */
+	config;
+	logger;
+	wrappedTransport;
+	/**
+	* Creates a LogTape transport.
+	*
+	* @param options Logging and optional wrapped transport configuration.
+	*/
+	constructor(...[options]) {
+		this.config = resolveLogTapeTransportOptions(options ?? {});
+		this.wrappedTransport = this.config.transport;
+		this.id = this.wrappedTransport?.id ?? "logtape";
+		this.logger = getLogger(this.config.category);
+	}
+	/**
+	* Sends one email while recording its delivery lifecycle.
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options, including cancellation.
+	* @returns The wrapped transport receipt, or a synthetic successful receipt
+	*          in log-only mode.
+	* @throws {DOMException} If the operation is aborted.
+	* @throws {Error} If the wrapped transport throws an error.
+	*/
+	send(message, options) {
+		return this.sendOne(message, options, "send");
+	}
+	/**
+	* Sends multiple emails while recording each delivery lifecycle.
+	*
+	* A wrapped transport's `sendMany()` implementation is used directly so
+	* provider-specific batching and streaming behavior are preserved.
+	*
+	* @param messages Email messages to send.
+	* @param options Optional transport options, including cancellation.
+	* @returns An async iterable of unmodified delivery receipts.
+	* @throws {DOMException} If the operation is aborted.
+	* @throws {Error} If the wrapped transport throws an error.
+	*/
+	async *sendMany(messages, options) {
+		options?.signal?.throwIfAborted();
+		if (this.wrappedTransport == null) {
+			for await (const message of messages) yield await this.sendOne(message, options, "sendMany");
+			return;
+		}
+		const pending = new PendingQueue();
+		const batchStartedAt = performance.now();
+		let consumedCount = 0;
+		let completedCount = 0;
+		const observedMessages = this.observeMessages(messages, pending, options, () => consumedCount++);
+		try {
+			for await (const receipt of this.wrappedTransport.sendMany(observedMessages, options)) {
+				const current = pending.dequeue();
+				completedCount++;
+				this.logReceipt(receipt, current, "sendMany");
+				yield receipt;
+			}
+		} catch (error) {
+			const batchProperties = {
+				consumedCount,
+				completedCount,
+				pendingCount: pending.size
+			};
+			if (pending.size < 1) this.logThrownError(error, void 0, "sendMany", batchStartedAt, batchProperties);
+			else for (const pendingMessage of pending) this.logThrownError(error, pendingMessage.message, "sendMany", pendingMessage.startedAt, batchProperties);
+			throw error;
+		}
+	}
+	/**
+	* Disposes the wrapped transport when it supports explicit resource
+	* management.
+	*/
+	async [Symbol.asyncDispose]() {
+		const transport = this.wrappedTransport;
+		if (transport == null) return;
+		if (isAsyncDisposable(transport)) {
+			await transport[Symbol.asyncDispose]();
+			return;
+		}
+		if (isDisposable(transport)) transport[Symbol.dispose]();
+	}
+	async sendOne(message, options, operation) {
+		options?.signal?.throwIfAborted();
+		const startedAt = performance.now();
+		this.logSending(message, operation);
+		try {
+			const receipt = this.wrappedTransport == null ? this.createSyntheticReceipt() : await this.wrappedTransport.send(message, options);
+			this.logReceipt(receipt, {
+				message,
+				startedAt
+			}, operation);
+			return receipt;
+		} catch (error) {
+			this.logThrownError(error, message, operation, startedAt);
+			throw error;
+		}
+	}
+	async *observeMessages(messages, pending, options, onConsume) {
+		for await (const message of messages) {
+			options?.signal?.throwIfAborted();
+			const startedAt = performance.now();
+			this.logSending(message, "sendMany");
+			pending.enqueue({
+				message,
+				startedAt
+			});
+			onConsume();
+			yield message;
+		}
+	}
+	createSyntheticReceipt() {
+		return {
+			successful: true,
+			messageId: `logtape-${crypto.randomUUID()}`,
+			provider: this.id,
+			attempts: 1,
+			timestamp: (/* @__PURE__ */ new Date()).toISOString()
+		};
+	}
+	logSending(message, operation) {
+		this.log(this.config.levels.sending, "Sending email.", {
+			...this.getMessageProperties(message),
+			event: "email.sending",
+			operation,
+			transportId: this.id
+		});
+	}
+	logReceipt(receipt, pending, operation) {
+		const durationMilliseconds = pending == null ? void 0 : performance.now() - pending.startedAt;
+		const messageProperties = pending == null ? {} : this.getMessageProperties(pending.message);
+		if (receipt.successful) {
+			this.log(this.config.levels.sent, "Email sent.", {
+				...messageProperties,
+				event: "email.sent",
+				operation,
+				transportId: this.id,
+				durationMilliseconds,
+				messageId: receipt.messageId,
+				provider: receipt.provider ?? this.id,
+				receipt
+			});
+			return;
+		}
+		this.log(this.config.levels.failed, "Failed to send email.", {
+			...messageProperties,
+			event: "email.failed",
+			operation,
+			transportId: this.id,
+			durationMilliseconds,
+			errorMessages: receipt.errorMessages,
+			errors: receipt.errors,
+			retryable: receipt.retryable,
+			provider: receipt.provider ?? this.id,
+			attempts: receipt.attempts,
+			receipt
+		});
+	}
+	logThrownError(error, message, operation, startedAt, extraProperties = {}) {
+		this.log(this.config.levels.failed, "Failed to send email: {error}", {
+			...message == null ? {} : this.getMessageProperties(message),
+			...extraProperties,
+			event: "email.failed",
+			operation,
+			transportId: this.id,
+			durationMilliseconds: performance.now() - startedAt,
+			error
+		});
+	}
+	getMessageProperties(message) {
+		return {
+			recipientCount: message.recipients.length,
+			ccRecipientCount: message.ccRecipients.length,
+			bccRecipientCount: message.bccRecipients.length,
+			attachmentCount: message.attachments.length,
+			priority: message.priority,
+			...this.config.recordMessage ? { message } : {}
+		};
+	}
+	log(level, message, properties) {
+		switch (level) {
+			case "trace":
+				this.logger.trace(message, properties);
+				break;
+			case "debug":
+				this.logger.debug(message, properties);
+				break;
+			case "info":
+				this.logger.info(message, properties);
+				break;
+			case "warning":
+				this.logger.warning(message, properties);
+				break;
+			case "error":
+				this.logger.error(message, properties);
+				break;
+			case "fatal":
+				this.logger.fatal(message, properties);
+				break;
+		}
+	}
+};
+function isAsyncDisposable(value) {
+	return Symbol.asyncDispose in value && typeof value[Symbol.asyncDispose] === "function";
+}
+function isDisposable(value) {
+	return Symbol.dispose in value && typeof value[Symbol.dispose] === "function";
+}
+
+//#endregion
+export { LogTapeTransport };

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@upyo/logtape",
+  "version": "0.6.0-dev.0",
+  "description": "LogTape observability transport for Upyo email library",
+  "keywords": [
+    "email",
+    "mail",
+    "logtape",
+    "logging",
+    "observability"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://upyo.org/transports/logtape",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/upyo.git",
+    "directory": "packages/logtape/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/upyo/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "peerDependencies": {
+    "@logtape/logtape": "^2.2.4",
+    "@upyo/core": "0.6.0"
+  },
+  "devDependencies": {
+    "@logtape/logtape": "^2.2.4",
+    "@logtape/testing": "^2.2.4",
+    "tsdown": "^0.12.7",
+    "typescript": "5.8.3"
+  },
+  "scripts": {
+    "prepublish": "mise run --no-deps :build"
+  }
+}