@upyo/opentelemetry 0.2.0-dev.24

package/dist/index.js

@@ -0,0 +1,1092 @@
+import { SpanKind, SpanStatusCode, context, metrics, trace } from "@opentelemetry/api";
+
+//#region src/config.ts
+/**
+* Default configuration values.
+*/
+const DEFAULT_CONFIG = {
+	metrics: {
+		enabled: true,
+		samplingRate: 1,
+		prefix: "upyo",
+		durationBuckets: [
+			.001,
+			.005,
+			.01,
+			.05,
+			.1,
+			.5,
+			1,
+			5,
+			10
+		]
+	},
+	tracing: {
+		enabled: true,
+		samplingRate: 1,
+		recordSensitiveData: false,
+		spanPrefix: "email"
+	}
+};
+/**
+* Creates a resolved OpenTelemetry configuration with defaults applied.
+*
+* @param config The input configuration options.
+* @returns A resolved configuration with all defaults applied.
+* @throws {Error} When tracing is enabled but no TracerProvider is provided.
+* @throws {Error} When metrics are enabled but no MeterProvider is provided.
+* @since 0.2.0
+*/
+function createOpenTelemetryConfig(config = {}) {
+	const resolvedConfig = {
+		tracerProvider: config.tracerProvider,
+		meterProvider: config.meterProvider,
+		metrics: {
+			...DEFAULT_CONFIG.metrics,
+			...config.metrics
+		},
+		tracing: {
+			...DEFAULT_CONFIG.tracing,
+			...config.tracing
+		},
+		attributeExtractor: config.attributeExtractor,
+		errorClassifier: config.errorClassifier
+	};
+	if (resolvedConfig.tracing.enabled && !resolvedConfig.tracerProvider) throw new Error("TracerProvider is required when tracing is enabled. Provide tracerProvider in config or use auto-configuration.");
+	if (resolvedConfig.metrics.enabled && !resolvedConfig.meterProvider) throw new Error("MeterProvider is required when metrics are enabled. Provide meterProvider in config or use auto-configuration.");
+	return resolvedConfig;
+}
+/**
+* Default error classifier that categorizes errors into standard types.
+*
+* @example
+* ```typescript
+* import { defaultErrorClassifier } from "@upyo/opentelemetry";
+*
+* console.log(defaultErrorClassifier(new Error("401 Unauthorized"))); // "auth"
+* console.log(defaultErrorClassifier(new Error("Rate limit exceeded"))); // "rate_limit"
+* console.log(defaultErrorClassifier(new Error("Connection timeout"))); // "network"
+* console.log(defaultErrorClassifier(new Error("Invalid email format"))); // "validation"
+* console.log(defaultErrorClassifier(new Error("500 Internal Server Error"))); // "server_error"
+* console.log(defaultErrorClassifier(new Error("Something else"))); // "unknown"
+* ```
+*
+* @param error The error to classify.
+* @returns A string category such as `"auth"`, `"rate_limit"`, `"network"`,
+*          `"validation"`, `"server_error"`, or `"unknown"`.
+* @since 0.2.0
+*/
+function defaultErrorClassifier(error) {
+	if (error instanceof Error) {
+		const message = error.message.toLowerCase();
+		const name$1 = error.name.toLowerCase();
+		if (message.includes("auth") || message.includes("unauthorized") || message.includes("invalid api key") || message.includes("403")) return "auth";
+		if (message.includes("rate limit") || message.includes("429") || message.includes("quota exceeded") || message.includes("throttle")) return "rate_limit";
+		if (message.includes("500") || message.includes("502") || message.includes("504") || message.includes("internal server error")) return "server_error";
+		if (name$1.includes("network") || message.includes("connect") || message.includes("timeout") || message.includes("dns") || name$1 === "aborterror") return "network";
+		if (message.includes("invalid") || message.includes("malformed") || message.includes("validation") || message.includes("400")) return "validation";
+		if (message.includes("503") || message.includes("service unavailable") || message.includes("temporarily unavailable")) return "service_unavailable";
+	}
+	return "unknown";
+}
+
+//#endregion
+//#region package.json
+var name = "@upyo/opentelemetry";
+var version = "0.2.0-dev.24+97755606";
+var description = "OpenTelemetry observability transport for Upyo email library";
+var keywords = [
+	"email",
+	"mail",
+	"sendmail",
+	"opentelemetry",
+	"observability",
+	"tracing",
+	"metrics",
+	"monitoring"
+];
+var license = "MIT";
+var author = {
+	"name": "Hong Minhee",
+	"email": "hong@minhee.org",
+	"url": "https://hongminhee.org/"
+};
+var homepage = "https://upyo.org/transports/opentelemetry";
+var repository = {
+	"type": "git",
+	"url": "git+https://github.com/dahlia/upyo.git",
+	"directory": "packages/opentelemetry/"
+};
+var bugs = { "url": "https://github.com/dahlia/upyo/issues" };
+var funding = ["https://github.com/sponsors/dahlia"];
+var engines = {
+	"node": ">=20.0.0",
+	"bun": ">=1.2.0",
+	"deno": ">=2.3.0"
+};
+var files = [
+	"dist/",
+	"package.json",
+	"README.md"
+];
+var type = "module";
+var module = "./dist/index.js";
+var main = "./dist/index.cjs";
+var types = "./dist/index.d.ts";
+var exports = {
+	".": {
+		"types": {
+			"import": "./dist/index.d.ts",
+			"require": "./dist/index.d.cts"
+		},
+		"import": "./dist/index.js",
+		"require": "./dist/index.cjs"
+	},
+	"./package.json": "./package.json"
+};
+var sideEffects = false;
+var peerDependencies = {
+	"@opentelemetry/api": "catalog:",
+	"@upyo/core": "workspace:*"
+};
+var devDependencies = {
+	"@dotenvx/dotenvx": "catalog:",
+	"@opentelemetry/api": "catalog:",
+	"@opentelemetry/context-async-hooks": "^1.25.1",
+	"@opentelemetry/resources": "catalog:",
+	"@opentelemetry/sdk-metrics": "catalog:",
+	"@opentelemetry/sdk-trace-base": "catalog:",
+	"@opentelemetry/semantic-conventions": "catalog:",
+	"tsdown": "catalog:",
+	"typescript": "catalog:"
+};
+var scripts = {
+	"build": "tsdown",
+	"prepack": "tsdown",
+	"prepublish": "tsdown",
+	"test": "tsdown && dotenvx run --ignore=MISSING_ENV_FILE -- node --experimental-transform-types --test",
+	"test:bun": "tsdown && bun test --timeout=30000 --env-file=.env",
+	"test:deno": "deno test --allow-env --allow-net --env-file=.env"
+};
+var package_default = {
+	name,
+	version,
+	description,
+	keywords,
+	license,
+	author,
+	homepage,
+	repository,
+	bugs,
+	funding,
+	engines,
+	files,
+	type,
+	module,
+	main,
+	types,
+	exports,
+	sideEffects,
+	peerDependencies,
+	devDependencies,
+	scripts
+};
+
+//#endregion
+//#region src/metrics.ts
+/**
+* Manages OpenTelemetry metrics collection for email operations.
+*/
+var MetricsCollector = class {
+	meter;
+	config;
+	attemptCounter;
+	messageCounter;
+	durationHistogram;
+	messageSizeHistogram;
+	attachmentCountHistogram;
+	activeSendsGauge;
+	constructor(meterProvider, config) {
+		this.config = config;
+		this.meter = meterProvider.getMeter(package_default.name, package_default.version);
+		this.attemptCounter = this.meter.createCounter(`${config.prefix}_email_attempts_total`, {
+			description: "Total number of email send attempts",
+			unit: "1"
+		});
+		this.messageCounter = this.meter.createCounter(`${config.prefix}_email_messages_total`, {
+			description: "Total number of email messages processed",
+			unit: "1"
+		});
+		this.durationHistogram = this.meter.createHistogram(`${config.prefix}_email_duration_seconds`, {
+			description: "Duration of email send operations",
+			unit: "s"
+		});
+		this.messageSizeHistogram = this.meter.createHistogram(`${config.prefix}_email_message_size_bytes`, {
+			description: "Size of email messages in bytes",
+			unit: "By"
+		});
+		this.attachmentCountHistogram = this.meter.createHistogram(`${config.prefix}_email_attachments_count`, {
+			description: "Number of attachments per email",
+			unit: "1"
+		});
+		this.activeSendsGauge = this.meter.createUpDownCounter(`${config.prefix}_email_active_sends`, {
+			description: "Number of currently active email send operations",
+			unit: "1"
+		});
+	}
+	/**
+	* Records the start of an email send operation.
+	*/
+	recordSendStart(transport, messageCount = 1) {
+		if (!this.shouldSample()) return;
+		const labels = { transport };
+		this.activeSendsGauge.add(1, labels);
+		this.messageCounter.add(messageCount, {
+			...labels,
+			priority: "normal"
+		});
+	}
+	/**
+	* Records the completion of an email send operation.
+	*/
+	recordSendComplete(transport, duration, success, errorType) {
+		if (!this.shouldSample()) return;
+		const labels = {
+			transport,
+			status: success ? "success" : "failure",
+			...errorType && { error_type: errorType }
+		};
+		this.activeSendsGauge.add(-1, { transport });
+		this.attemptCounter.add(1, labels);
+		this.durationHistogram.record(duration, labels);
+	}
+	/**
+	* Records metrics for individual messages.
+	*/
+	recordMessage(message, transport) {
+		if (!this.shouldSample()) return;
+		const labels = {
+			transport,
+			priority: message.priority,
+			content_type: this.getContentType(message)
+		};
+		const messageSize = this.estimateMessageSize(message);
+		this.messageSizeHistogram.record(messageSize, labels);
+		this.attachmentCountHistogram.record(message.attachments.length, labels);
+	}
+	/**
+	* Records metrics for batch operations.
+	*/
+	recordBatch(messages, transport, duration, successCount, failureCount) {
+		if (!this.shouldSample()) return;
+		const _totalMessages = messages.length;
+		const labels = { transport };
+		this.attemptCounter.add(1, {
+			...labels,
+			status: failureCount === 0 ? "success" : "partial_failure",
+			operation: "batch"
+		});
+		this.durationHistogram.record(duration, {
+			...labels,
+			operation: "batch"
+		});
+		for (const message of messages) this.recordMessage(message, transport);
+		if (successCount > 0) this.messageCounter.add(successCount, {
+			...labels,
+			status: "success"
+		});
+		if (failureCount > 0) this.messageCounter.add(failureCount, {
+			...labels,
+			status: "failure"
+		});
+	}
+	/**
+	* Records an error for metrics classification.
+	*/
+	recordError(transport, errorType, operation = "send") {
+		if (!this.shouldSample()) return;
+		this.attemptCounter.add(1, {
+			transport,
+			status: "failure",
+			error_type: errorType,
+			operation
+		});
+	}
+	shouldSample() {
+		return Math.random() < this.config.samplingRate;
+	}
+	getContentType(message) {
+		if ("html" in message.content) return message.content.text ? "multipart" : "html";
+		return "text";
+	}
+	estimateMessageSize(message) {
+		let size = 0;
+		size += 500;
+		size += message.subject.length;
+		if ("html" in message.content) {
+			size += message.content.html.length;
+			if (message.content.text) size += message.content.text.length;
+		} else size += message.content.text.length;
+		size += message.attachments.length * 100;
+		return size;
+	}
+};
+
+//#endregion
+//#region src/attributes.ts
+/**
+* Email attribute extractor class for generating OpenTelemetry attributes.
+* Handles extraction of message metadata, error information, and transport details
+* while respecting privacy settings for sensitive data.
+*
+* This class provides methods for extracting attributes from email messages,
+* batch operations, and errors, making them suitable for use in OpenTelemetry
+* spans and metrics.
+*
+* @example
+* ```typescript
+* import { EmailAttributeExtractor } from "@upyo/opentelemetry";
+*
+* const extractor = new EmailAttributeExtractor(
+*   "smtp",           // transport name
+*   false,            // don't record sensitive data
+*   "2.1.0"          // transport version
+* );
+*
+* // Extract attributes from a message
+* const messageAttrs = extractor.extractMessageAttributes(message);
+*
+* // Extract attributes from batch operations
+* const batchAttrs = extractor.extractBatchAttributes(messages, batchSize);
+*
+* // Extract attributes from errors
+* const errorAttrs = extractor.extractErrorAttributes(error, "network");
+* ```
+*
+* @since 0.2.0
+*/
+var EmailAttributeExtractor = class {
+	recordSensitiveData;
+	transportName;
+	transportVersion;
+	constructor(transportName, recordSensitiveData = false, transportVersion) {
+		this.transportName = transportName;
+		this.recordSensitiveData = recordSensitiveData;
+		this.transportVersion = transportVersion;
+	}
+	/**
+	* Extracts attributes for a single message send operation.
+	*/
+	extractMessageAttributes(message) {
+		const attributes = {
+			"operation.name": "email.send",
+			"operation.type": "email",
+			"email.to.count": message.recipients.length,
+			"email.cc.count": message.ccRecipients.length,
+			"email.bcc.count": message.bccRecipients.length,
+			"email.attachments.count": message.attachments.length,
+			"email.priority": message.priority,
+			"email.tags": JSON.stringify(message.tags),
+			"upyo.transport.name": this.transportName,
+			"upyo.retry.count": 0,
+			"upyo.batch.size": 1
+		};
+		if (this.transportVersion) attributes["upyo.transport.version"] = this.transportVersion;
+		if (this.recordSensitiveData) {
+			attributes["email.from.address"] = message.sender.address;
+			attributes["email.subject.length"] = message.subject.length;
+		} else {
+			attributes["email.from.domain"] = this.extractDomain(message.sender.address);
+			attributes["email.subject.length"] = message.subject.length;
+		}
+		attributes["email.content.type"] = this.detectContentType(message);
+		attributes["email.message.size"] = this.estimateMessageSize(message);
+		return attributes;
+	}
+	/**
+	* Extracts attributes for batch send operations.
+	*/
+	extractBatchAttributes(messages, batchSize) {
+		const totalAttachments = messages.reduce((sum, msg) => sum + msg.attachments.length, 0);
+		const totalSize = messages.reduce((sum, msg) => sum + this.estimateMessageSize(msg), 0);
+		const attributes = {
+			"operation.name": "email.send_batch",
+			"operation.type": "email",
+			"email.batch.size": batchSize,
+			"email.batch.total_recipients": messages.reduce((sum, msg) => sum + msg.recipients.length + msg.ccRecipients.length + msg.bccRecipients.length, 0),
+			"email.batch.total_attachments": totalAttachments,
+			"email.batch.total_size": totalSize,
+			"upyo.transport.name": this.transportName,
+			"upyo.batch.size": batchSize
+		};
+		if (this.transportVersion) attributes["upyo.transport.version"] = this.transportVersion;
+		return attributes;
+	}
+	/**
+	* Extracts network-related attributes from transport configuration.
+	*/
+	extractNetworkAttributes(protocol, serverAddress, serverPort) {
+		const attributes = { "network.protocol.name": protocol };
+		if (serverAddress) attributes["server.address"] = serverAddress;
+		if (serverPort) attributes["server.port"] = serverPort;
+		return attributes;
+	}
+	/**
+	* Extracts error-related attributes.
+	*/
+	extractErrorAttributes(error, errorCategory) {
+		const attributes = { "error.type": errorCategory };
+		if (error instanceof Error) {
+			attributes["error.name"] = error.name;
+			if (this.recordSensitiveData || this.isSafeErrorMessage(error.message)) attributes["error.message"] = error.message;
+		}
+		return attributes;
+	}
+	detectContentType(message) {
+		if (message.attachments.length > 0) return "multipart";
+		if ("html" in message.content) return "html";
+		return "text";
+	}
+	estimateMessageSize(message) {
+		let size = 0;
+		size += 500;
+		size += message.subject.length;
+		if ("html" in message.content) {
+			size += message.content.html.length;
+			if (message.content.text) size += message.content.text.length;
+		} else size += message.content.text.length;
+		size += message.attachments.length * 100;
+		return size;
+	}
+	extractDomain(email) {
+		const atIndex = email.lastIndexOf("@");
+		return atIndex > 0 ? email.substring(atIndex + 1) : "unknown";
+	}
+	isSafeErrorMessage(message) {
+		const safePatterns = [
+			/^timeout/i,
+			/^connection/i,
+			/^network/i,
+			/^dns/i,
+			/^rate limit/i,
+			/^quota exceeded/i,
+			/^service unavailable/i,
+			/^internal server error/i,
+			/^bad gateway/i,
+			/^gateway timeout/i
+		];
+		return safePatterns.some((pattern) => pattern.test(message));
+	}
+};
+
+//#endregion
+//#region src/tracing.ts
+/**
+* Manages OpenTelemetry tracing for email operations.
+*/
+var TracingCollector = class {
+	tracer;
+	config;
+	attributeExtractor;
+	constructor(tracerProvider, config, transportName, transportVersion) {
+		this.config = config;
+		this.tracer = tracerProvider.getTracer(package_default.name, package_default.version);
+		this.attributeExtractor = new EmailAttributeExtractor(transportName, config.recordSensitiveData, transportVersion);
+	}
+	/**
+	* Creates a span for a single email send operation.
+	*/
+	createSendSpan(message, networkAttributes) {
+		if (!this.shouldSample()) return new NoOpEmailSpan();
+		const spanName = `${this.config.spanPrefix} send`;
+		const span = this.tracer.startSpan(spanName, { kind: SpanKind.CLIENT }, context.active());
+		const messageAttributes = this.attributeExtractor.extractMessageAttributes(message);
+		span.setAttributes(messageAttributes);
+		if (networkAttributes) span.setAttributes(networkAttributes);
+		return new LiveEmailSpan(span, this.attributeExtractor);
+	}
+	/**
+	* Creates a span for a batch email send operation.
+	*/
+	createBatchSpan(messages, batchSize, networkAttributes) {
+		if (!this.shouldSample()) return new NoOpEmailSpan();
+		const spanName = `${this.config.spanPrefix} send_batch`;
+		const span = this.tracer.startSpan(spanName, { kind: SpanKind.CLIENT }, context.active());
+		const batchAttributes = this.attributeExtractor.extractBatchAttributes(messages, batchSize);
+		span.setAttributes(batchAttributes);
+		if (networkAttributes) span.setAttributes(networkAttributes);
+		return new LiveEmailSpan(span, this.attributeExtractor);
+	}
+	shouldSample() {
+		return Math.random() < this.config.samplingRate;
+	}
+};
+/**
+* Live implementation of EmailSpan that delegates to OpenTelemetry Span.
+*/
+var LiveEmailSpan = class {
+	constructor(span, attributeExtractor) {
+		this.span = span;
+		this.attributeExtractor = attributeExtractor;
+	}
+	addEvent(name$1, attributes) {
+		this.span.addEvent(name$1, attributes);
+	}
+	setAttributes(attributes) {
+		this.span.setAttributes(attributes);
+	}
+	recordError(error, errorCategory) {
+		this.span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: error instanceof Error ? error.message : "Unknown error"
+		});
+		const errorAttributes = this.attributeExtractor.extractErrorAttributes(error, errorCategory);
+		this.span.setAttributes(errorAttributes);
+		this.span.addEvent("exception", {
+			"exception.type": error instanceof Error ? error.constructor.name : "unknown",
+			"exception.message": error instanceof Error ? error.message : String(error)
+		});
+	}
+	recordRetry(attempt, reason) {
+		this.span.setAttributes({ "upyo.retry.count": attempt });
+		this.span.addEvent("retry", {
+			"retry.attempt": attempt,
+			...reason && { "retry.reason": reason }
+		});
+	}
+	recordSuccess(messageId) {
+		this.span.setStatus({ code: SpanStatusCode.OK });
+		if (messageId) this.span.setAttributes({ "upyo.message.id": messageId });
+		this.span.addEvent("email.sent", { ...messageId && { "message.id": messageId } });
+	}
+	recordFailure(errorMessages) {
+		this.span.setStatus({
+			code: SpanStatusCode.ERROR,
+			message: errorMessages[0] || "Send failed"
+		});
+		this.span.setAttributes({ "email.error.count": errorMessages.length });
+		this.span.addEvent("email.send_failed", {
+			"error.count": errorMessages.length,
+			"error.messages": JSON.stringify(errorMessages)
+		});
+	}
+	end() {
+		this.span.end();
+	}
+};
+/**
+* No-op implementation for when sampling is disabled.
+*/
+var NoOpEmailSpan = class {
+	addEvent() {}
+	setAttributes() {}
+	recordError() {}
+	recordRetry() {}
+	recordSuccess() {}
+	recordFailure() {}
+	end() {}
+};
+
+//#endregion
+//#region src/opentelemetry-transport.ts
+/**
+* OpenTelemetry decorator transport that adds observability to any existing transport.
+*
+* This transport wraps another transport implementation to provide automatic
+* OpenTelemetry metrics and tracing without requiring changes to existing code.
+* It follows the decorator pattern, accepting any transport and adding standardized
+* observability features including email delivery metrics, latency histograms,
+* error classification, and distributed tracing support.
+*
+* The transport also supports automatic resource cleanup by implementing
+* AsyncDisposable and properly disposing wrapped transports that support
+* either Disposable or AsyncDisposable interfaces.
+*
+* @example Basic usage with explicit providers
+* ```typescript
+* import { OpenTelemetryTransport } from "@upyo/opentelemetry";
+* import { createSmtpTransport } from "@upyo/smtp";
+* import { trace, metrics } from "@opentelemetry/api";
+*
+* const baseTransport = createSmtpTransport({
+*   host: "smtp.example.com",
+*   port: 587,
+* });
+*
+* const transport = new OpenTelemetryTransport(baseTransport, {
+*   tracerProvider: trace.getTracerProvider(),
+*   meterProvider: metrics.getMeterProvider(),
+*   tracing: {
+*     enabled: true,
+*     samplingRate: 1.0,
+*     recordSensitiveData: false,
+*   },
+*   metrics: {
+*     enabled: true,
+*   },
+* });
+*
+* // Use the transport normally - it will automatically create spans and metrics
+* await transport.send(message);
+* ```
+*
+* @example With custom error classification and attribute extraction
+* ```typescript
+* const transport = new OpenTelemetryTransport(baseTransport, {
+*   tracerProvider: trace.getTracerProvider(),
+*   meterProvider: metrics.getMeterProvider(),
+*   errorClassifier: (error) => {
+*     if (error.message.includes("spam")) return "spam";
+*     if (error.message.includes("bounce")) return "bounce";
+*     return "unknown";
+*   },
+*   attributeExtractor: (operation, transportName) => ({
+*     "service.environment": process.env.NODE_ENV,
+*     "transport.type": transportName,
+*   }),
+* });
+* ```
+*
+* @since 0.2.0
+*/
+var OpenTelemetryTransport = class {
+	/**
+	* The resolved OpenTelemetry configuration.
+	*/
+	config;
+	wrappedTransport;
+	metricsCollector;
+	tracingCollector;
+	transportName;
+	transportVersion;
+	/**
+	* Creates a new OpenTelemetry transport that wraps an existing transport.
+	*
+	* @param transport The base transport to wrap with observability.
+	* @param config OpenTelemetry configuration options.
+	*/
+	constructor(transport, config = {}) {
+		this.wrappedTransport = transport;
+		this.config = createOpenTelemetryConfig(config);
+		this.transportName = this.extractTransportName(transport);
+		this.transportVersion = this.extractTransportVersion(transport);
+		if (this.config.metrics.enabled && this.config.meterProvider) this.metricsCollector = new MetricsCollector(this.config.meterProvider, this.config.metrics);
+		if (this.config.tracing.enabled && this.config.tracerProvider) this.tracingCollector = new TracingCollector(this.config.tracerProvider, this.config.tracing, this.transportName, this.transportVersion);
+	}
+	/**
+	* Sends a single email message with OpenTelemetry observability.
+	*
+	* @param message The email message to send.
+	* @param options Optional transport options including abort signal.
+	* @returns A promise that resolves to a receipt indicating success or failure.
+	*/
+	async send(message, options) {
+		const startTime = performance.now();
+		const span = this.tracingCollector?.createSendSpan(message, this.extractNetworkAttributes());
+		this.metricsCollector?.recordSendStart(this.transportName, 1);
+		this.metricsCollector?.recordMessage(message, this.transportName);
+		try {
+			if (this.config.attributeExtractor && span) {
+				const customAttributes = this.config.attributeExtractor("send", this.transportName, 1, this.estimateMessageSize(message));
+				span.setAttributes(customAttributes);
+			}
+			const receipt = await this.wrappedTransport.send(message, options);
+			const duration = (performance.now() - startTime) / 1e3;
+			if (receipt.successful) {
+				span?.recordSuccess(receipt.messageId);
+				this.metricsCollector?.recordSendComplete(this.transportName, duration, true);
+			} else {
+				const errorCategory = this.classifyErrors(receipt.errorMessages);
+				span?.recordFailure(receipt.errorMessages);
+				this.metricsCollector?.recordSendComplete(this.transportName, duration, false, errorCategory);
+			}
+			return receipt;
+		} catch (error) {
+			const duration = (performance.now() - startTime) / 1e3;
+			const errorCategory = this.classifyError(error);
+			span?.recordError(error, errorCategory);
+			this.metricsCollector?.recordSendComplete(this.transportName, duration, false, errorCategory);
+			throw error;
+		} finally {
+			span?.end();
+		}
+	}
+	/**
+	* Sends multiple email messages with OpenTelemetry observability.
+	*
+	* @param messages An iterable or async iterable of messages to send.
+	* @param options Optional transport options including abort signal.
+	* @returns An async iterable that yields receipts for each sent message.
+	*/
+	async *sendMany(messages, options) {
+		const startTime = performance.now();
+		const messageArray = [];
+		for await (const message of messages) messageArray.push(message);
+		const batchSize = messageArray.length;
+		const span = this.tracingCollector?.createBatchSpan(messageArray, batchSize, this.extractNetworkAttributes());
+		this.metricsCollector?.recordSendStart(this.transportName, batchSize);
+		let successCount = 0;
+		let failureCount = 0;
+		const receipts = [];
+		try {
+			if (this.config.attributeExtractor && span) {
+				const totalSize = messageArray.reduce((sum, msg) => sum + this.estimateMessageSize(msg), 0);
+				const customAttributes = this.config.attributeExtractor("send_batch", this.transportName, batchSize, totalSize);
+				span.setAttributes(customAttributes);
+			}
+			for await (const receipt of this.wrappedTransport.sendMany(messageArray, options)) {
+				receipts.push(receipt);
+				if (receipt.successful) successCount++;
+				else failureCount++;
+				yield receipt;
+			}
+			const duration = (performance.now() - startTime) / 1e3;
+			this.metricsCollector?.recordBatch(messageArray, this.transportName, duration, successCount, failureCount);
+			if (failureCount === 0) span?.recordSuccess();
+			else if (successCount > 0) span?.addEvent("partial_success", {
+				"success_count": successCount,
+				"failure_count": failureCount
+			});
+			else {
+				const allErrorMessages = receipts.filter((r) => !r.successful).flatMap((r) => r.errorMessages);
+				span?.recordFailure(allErrorMessages);
+			}
+		} catch (error) {
+			const _duration = (performance.now() - startTime) / 1e3;
+			const errorCategory = this.classifyError(error);
+			span?.recordError(error, errorCategory);
+			this.metricsCollector?.recordError(this.transportName, errorCategory, "send_batch");
+			throw error;
+		} finally {
+			span?.end();
+		}
+	}
+	/**
+	* Cleanup resources if the wrapped transport supports Disposable or AsyncDisposable.
+	*/
+	async [Symbol.asyncDispose]() {
+		if (!this.wrappedTransport) return;
+		if (typeof this.wrappedTransport[Symbol.asyncDispose] === "function") {
+			await this.wrappedTransport[Symbol.asyncDispose]();
+			return;
+		}
+		if (typeof this.wrappedTransport[Symbol.dispose] === "function") this.wrappedTransport[Symbol.dispose]();
+	}
+	extractTransportName(transport) {
+		const constructorName = transport.constructor.name;
+		if (constructorName && constructorName !== "Object") return constructorName.toLowerCase().replace("transport", "");
+		if ("config" in transport && transport.config && typeof transport.config === "object") {
+			if ("domain" in transport.config) return "mailgun";
+			if ("apiKey" in transport.config && "region" in transport.config) return "sendgrid";
+			if ("accessKeyId" in transport.config) return "ses";
+			if ("host" in transport.config) return "smtp";
+		}
+		return "unknown";
+	}
+	extractTransportVersion(transport) {
+		if ("config" in transport && transport.config && typeof transport.config === "object") {
+			if ("version" in transport.config) return String(transport.config.version);
+		}
+		return void 0;
+	}
+	extractNetworkAttributes() {
+		const transport = this.wrappedTransport;
+		if ("config" in transport && transport.config && typeof transport.config === "object") {
+			const config = transport.config;
+			if ("host" in config && "port" in config) return {
+				"network.protocol.name": "smtp",
+				"server.address": String(config.host),
+				"server.port": Number(config.port)
+			};
+			if ("baseUrl" in config || "endpoint" in config || "domain" in config) {
+				const url = config.baseUrl || config.endpoint || config.domain && `https://api.${config.region === "eu" ? "eu." : ""}mailgun.net`;
+				if (url && typeof url === "string") try {
+					const parsedUrl = new URL(url);
+					return {
+						"network.protocol.name": parsedUrl.protocol.replace(":", ""),
+						"server.address": parsedUrl.hostname,
+						...parsedUrl.port && { "server.port": parseInt(parsedUrl.port) }
+					};
+				} catch {}
+			}
+		}
+		return void 0;
+	}
+	classifyError(error) {
+		const classifier = this.config.errorClassifier || defaultErrorClassifier;
+		return classifier(error);
+	}
+	classifyErrors(errorMessages) {
+		if (errorMessages.length === 0) return "unknown";
+		const syntheticError = new Error(errorMessages[0]);
+		return this.classifyError(syntheticError);
+	}
+	estimateMessageSize(message) {
+		let size = 0;
+		size += 500;
+		size += message.subject.length;
+		if ("html" in message.content) {
+			size += message.content.html.length;
+			if (message.content.text) size += message.content.text.length;
+		} else size += message.content.text.length;
+		size += message.attachments.length * 100;
+		return size;
+	}
+};
+
+//#endregion
+//#region src/index.ts
+/**
+* Creates an OpenTelemetry transport for email operations with comprehensive
+* observability features.
+*
+* This function wraps an existing email transport with OpenTelemetry tracing
+* and metrics collection, providing automatic instrumentation for email sending
+* operations. It supports both single message and batch operations with
+* configurable sampling, error classification, and attribute extraction.
+* The function simplifies setup by automatically configuring providers when
+* they're not explicitly provided, using global `TracerProvider` and
+* `MeterProvider` from OpenTelemetry API as fallbacks.
+*
+* @param baseTransport The underlying email transport to wrap with
+*                      OpenTelemetry instrumentation.
+* @param config Configuration options for OpenTelemetry setup including
+*               providers, sampling rates, and custom extractors.
+* @param config.serviceName Service name for OpenTelemetry resource attributes.
+*                           Defaults to "email-service".
+* @param config.serviceVersion Service version for OpenTelemetry resource
+*                              attributes.
+* @param config.tracerProvider Custom TracerProvider instance. Uses global
+*                              provider if not specified.
+* @param config.meterProvider Custom MeterProvider instance. Uses global
+*                             provider if not specified.
+* @param config.auto Auto-configuration options for setting up exporters and
+*                    processors.
+* @param config.tracing Tracing configuration including sampling rates and
+*                       span settings.
+* @param config.metrics Metrics configuration including histogram boundaries
+*                       and collection settings.
+* @param config.attributeExtractor Custom function for extracting attributes
+*                                  from operations.
+* @param config.errorClassifier Custom function for categorizing errors into
+*                               types.
+* @returns An OpenTelemetry-enabled transport that instruments all email
+*          operations with traces and metrics.
+*
+* @example With minimal configuration
+* ```typescript
+* import { createOpenTelemetryTransport } from "@upyo/opentelemetry";
+* import { createSmtpTransport } from "@upyo/smtp";
+*
+* const smtpTransport = createSmtpTransport({
+*   host: "smtp.example.com",
+*   port: 587,
+* });
+*
+* const transport = createOpenTelemetryTransport(smtpTransport, {
+*   serviceName: "email-service",
+*   serviceVersion: "1.0.0",
+* });
+* ```
+*
+* @example With explicit providers
+* ```typescript
+* import { createOpenTelemetryTransport } from "@upyo/opentelemetry";
+* import { trace, metrics } from "@opentelemetry/api";
+*
+* const transport = createOpenTelemetryTransport(baseTransport, {
+*   tracerProvider: trace.getTracerProvider(),
+*   meterProvider: metrics.getMeterProvider(),
+*   serviceName: "my-email-service",
+*   tracing: {
+*     enabled: true,
+*     samplingRate: 0.1,
+*     recordSensitiveData: false,
+*   },
+*   metrics: {
+*     enabled: true,
+*     histogramBoundaries: [10, 50, 100, 500, 1000, 5000],
+*   },
+* });
+* ```
+*
+* @example With auto-configuration
+* ```typescript
+* const transport = createOpenTelemetryTransport(baseTransport, {
+*   serviceName: "email-service",
+*   auto: {
+*     tracing: { endpoint: "http://jaeger:14268/api/traces" },
+*     metrics: { endpoint: "http://prometheus:9090/api/v1/write" }
+*   }
+* });
+* ```
+*
+* @since 0.2.0
+*/
+function createOpenTelemetryTransport(baseTransport, config = {}) {
+	const { serviceName = "email-service", serviceVersion, auto,...otherConfig } = config;
+	const finalConfig = {
+		tracerProvider: otherConfig.tracerProvider || trace.getTracerProvider(),
+		meterProvider: otherConfig.meterProvider || metrics.getMeterProvider(),
+		...otherConfig,
+		...auto && { auto: {
+			serviceName,
+			serviceVersion,
+			...auto
+		} }
+	};
+	return new OpenTelemetryTransport(baseTransport, finalConfig);
+}
+/**
+* Creates a custom email attribute extractor function for OpenTelemetry
+* spans and metrics.
+*
+* This function creates a reusable attribute extractor that can be used to
+* generate consistent attributes for OpenTelemetry traces and metrics across
+* different email operations.  It supports both basic transport information
+* and custom attribute generation based on operation context.
+*
+* @param transportName The name of the email transport
+*                      (e.g., `"smtp"`, `"mailgun"`, `"sendgrid"`).
+* @param options Configuration options for customizing attribute extraction
+*                behavior.
+* @param options.recordSensitiveData Whether to include sensitive data like
+*                                    email addresses in attributes.
+*                                    Defaults to false for security.
+* @param options.transportVersion The version of the transport implementation
+*                                 for better observability.
+* @param options.customAttributes A function to generate custom attributes
+*                                 based on operation context.
+* @returns A function that extracts attributes from email operations,
+*          suitable for use with OpenTelemetry spans and metrics.
+*
+* @example Basic usage
+* ```typescript
+* import { createEmailAttributeExtractor } from "@upyo/opentelemetry";
+*
+* const extractor = createEmailAttributeExtractor("smtp", {
+*   transportVersion: "2.1.0",
+* });
+*
+* const transport = createOpenTelemetryTransport(baseTransport, {
+*   attributeExtractor: extractor,
+* });
+* ```
+*
+* @example With custom attributes
+* ```typescript
+* import { createEmailAttributeExtractor } from "@upyo/opentelemetry";
+*
+* const extractor = createEmailAttributeExtractor("smtp", {
+*   recordSensitiveData: false,
+*   transportVersion: "2.1.0",
+*   customAttributes: (operation, transportName, messageCount, totalSize) => ({
+*     "service.environment": process.env.NODE_ENV || "development",
+*     "email.batch.size": messageCount || 1,
+*     "email.total.bytes": totalSize || 0,
+*     "transport.type": transportName,
+*   }),
+* });
+*
+* const transport = createOpenTelemetryTransport(baseTransport, {
+*   attributeExtractor: extractor,
+* });
+* ```
+*
+* @since 0.2.0
+*/
+function createEmailAttributeExtractor(_transportName, options = {}) {
+	return (operation, transport, messageCount, totalSize) => {
+		const baseAttributes = {
+			"operation.name": operation === "send" ? "email.send" : "email.send_batch",
+			"operation.type": "email",
+			"upyo.transport.name": transport
+		};
+		if (options.transportVersion) baseAttributes["upyo.transport.version"] = options.transportVersion;
+		if (operation === "send_batch") {
+			baseAttributes["upyo.batch.size"] = messageCount;
+			if (totalSize !== void 0) baseAttributes["email.batch.total_size"] = totalSize;
+		}
+		const customAttributes = options.customAttributes?.(operation, transport, messageCount, totalSize) || {};
+		return {
+			...baseAttributes,
+			...customAttributes
+		};
+	};
+}
+/**
+* Creates a custom error classifier function for categorizing email sending
+* errors.
+*
+* This function creates an error classifier that categorizes errors into
+* meaningful groups for better observability and alerting.  It supports custom
+* regex patterns for domain-specific error classification while falling back
+* to the default classifier for common error types.  The classifier is used to
+* tag metrics and traces with error categories, enabling better
+* monitoring and debugging of email delivery issues.
+*
+* @param options Configuration options for error classification behavior.
+* @param options.patterns A record of category names mapped to regex patterns
+*                         for custom error classification.
+* @param options.fallback The fallback category to use when no patterns match
+*                         and the default classifier returns "unknown".
+*                         Defaults to "unknown".
+* @returns A function that classifies errors into string categories for use
+*          in OpenTelemetry attributes and metrics.
+*
+* @example Basic usage with common patterns
+* ```typescript
+* import { createErrorClassifier } from "@upyo/opentelemetry";
+*
+* const classifier = createErrorClassifier({
+*   patterns: {
+*     spam: /blocked.*spam|spam.*detected/i,
+*     bounce: /bounce|undeliverable|invalid.*recipient/i,
+*   },
+*   fallback: "email_error",
+* });
+*
+* const transport = createOpenTelemetryTransport(baseTransport, {
+*   errorClassifier: classifier,
+* });
+* ```
+*
+* @example Advanced patterns for specific email providers
+* ```typescript
+* import { createErrorClassifier } from "@upyo/opentelemetry";
+*
+* const classifier = createErrorClassifier({
+*   patterns: {
+*     spam: /blocked.*spam|spam.*detected|reputation/i,
+*     bounce: /bounce|undeliverable|invalid.*recipient/i,
+*     quota: /quota.*exceeded|mailbox.*full/i,
+*     reputation: /reputation|blacklist|blocked.*ip/i,
+*     temporary: /temporary.*failure|try.*again.*later/i,
+*     authentication: /authentication.*failed|invalid.*credentials/i,
+*   },
+*   fallback: "email_error",
+* });
+*
+* // The classifier will categorize errors like:
+* // new Error("Message blocked as spam") -> "spam"
+* // new Error("Mailbox quota exceeded") -> "quota"
+* // new Error("Authentication failed") -> "auth" (from default classifier)
+* // new Error("Unknown error") -> "email_error" (fallback)
+* ```
+*
+* @since 0.2.0
+*/
+function createErrorClassifier(options = {}) {
+	const { patterns = {}, fallback = "unknown" } = options;
+	return (error) => {
+		if (error instanceof Error) {
+			const message = error.message.toLowerCase();
+			for (const [category, pattern] of Object.entries(patterns)) if (pattern.test(message)) return category;
+		}
+		const defaultCategory = defaultErrorClassifier(error);
+		return defaultCategory === "unknown" ? fallback : defaultCategory;
+	};
+}
+
+//#endregion
+export { OpenTelemetryTransport, createEmailAttributeExtractor, createErrorClassifier, createOpenTelemetryTransport, defaultErrorClassifier };