@upyo/jmap 0.4.0-dev.1

package/dist/index.cjs

@@ -0,0 +1,685 @@
+
+//#region src/errors.ts
+/**
+* Error class for JMAP API errors.
+* @since 0.4.0
+*/
+var JmapApiError = class extends Error {
+	statusCode;
+	responseBody;
+	jmapErrorType;
+	constructor(message, statusCode, responseBody, jmapErrorType) {
+		super(message);
+		this.name = "JmapApiError";
+		this.statusCode = statusCode;
+		this.responseBody = responseBody;
+		this.jmapErrorType = jmapErrorType;
+	}
+};
+/**
+* JMAP-specific error types from RFC 8620.
+* @since 0.4.0
+*/
+const JMAP_ERROR_TYPES = {
+	unknownCapability: "urn:ietf:params:jmap:error:unknownCapability",
+	notJSON: "urn:ietf:params:jmap:error:notJSON",
+	notRequest: "urn:ietf:params:jmap:error:notRequest",
+	limit: "urn:ietf:params:jmap:error:limit"
+};
+/**
+* Checks if the given error is a JMAP capability error.
+* @param error The error to check.
+* @returns `true` if the error is a JMAP capability error, `false` otherwise.
+* @since 0.4.0
+*/
+function isCapabilityError(error) {
+	return error instanceof JmapApiError && error.jmapErrorType === JMAP_ERROR_TYPES.unknownCapability;
+}
+
+//#endregion
+//#region src/blob-uploader.ts
+/**
+* Upload a blob to the JMAP server.
+*
+* @param config - The resolved JMAP configuration
+* @param uploadUrl - The upload URL template from the session (e.g., "https://server/upload/{accountId}")
+* @param accountId - The account ID to upload to
+* @param blob - The blob or file to upload
+* @param signal - Optional abort signal
+* @returns The upload response containing the blobId
+*/
+async function uploadBlob(config, uploadUrl, accountId, blob, signal) {
+	signal?.throwIfAborted();
+	const url = uploadUrl.replace("{accountId}", accountId);
+	let authHeader;
+	if (config.bearerToken) authHeader = `Bearer ${config.bearerToken}`;
+	else if (config.basicAuth) {
+		const credentials = btoa(`${config.basicAuth.username}:${config.basicAuth.password}`);
+		authHeader = `Basic ${credentials}`;
+	} else throw new Error("No authentication method configured");
+	const headers = {
+		Authorization: authHeader,
+		"Content-Type": blob.type || "application/octet-stream"
+	};
+	for (const [key, value] of Object.entries(config.headers)) headers[key] = value;
+	const controller = new AbortController();
+	const timeoutId = setTimeout(() => controller.abort(), config.timeout);
+	const combinedSignal = signal ? combineSignals(signal, controller.signal) : controller.signal;
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers,
+			body: blob,
+			signal: combinedSignal
+		});
+		if (!response.ok) {
+			const body = await response.text();
+			throw new JmapApiError(`Blob upload failed: ${response.status} ${response.statusText}`, response.status, body);
+		}
+		const result = await response.json();
+		return result;
+	} finally {
+		clearTimeout(timeoutId);
+	}
+}
+/**
+* Combine multiple abort signals into one.
+*/
+function combineSignals(...signals) {
+	const controller = new AbortController();
+	for (const signal of signals) {
+		if (signal.aborted) {
+			controller.abort(signal.reason);
+			break;
+		}
+		signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+	}
+	return controller.signal;
+}
+
+//#endregion
+//#region src/config.ts
+/**
+* Creates a resolved JMAP configuration with default values applied.
+* @param config The user-provided configuration.
+* @returns The resolved configuration with all fields populated.
+* @throws Error if neither bearerToken nor basicAuth is provided.
+* @since 0.4.0
+*/
+function createJmapConfig(config) {
+	if (!config.bearerToken && !config.basicAuth) throw new Error("Either bearerToken or basicAuth must be provided");
+	return {
+		sessionUrl: config.sessionUrl,
+		bearerToken: config.bearerToken ?? null,
+		basicAuth: config.basicAuth ?? null,
+		accountId: config.accountId ?? null,
+		identityId: config.identityId ?? null,
+		timeout: config.timeout || 3e4,
+		retries: config.retries || 3,
+		headers: config.headers ?? {},
+		sessionCacheTtl: config.sessionCacheTtl || 3e5,
+		baseUrl: config.baseUrl ?? null
+	};
+}
+
+//#endregion
+//#region src/http-client.ts
+/**
+* HTTP client for JMAP API requests.
+* @since 0.4.0
+*/
+var JmapHttpClient = class {
+	config;
+	constructor(config) {
+		this.config = config;
+	}
+	/**
+	* Fetches the JMAP session from the session URL.
+	* @param signal Optional abort signal.
+	* @returns The JMAP session response.
+	* @since 0.4.0
+	*/
+	async fetchSession(signal) {
+		signal?.throwIfAborted();
+		const response = await this.fetchWithAuth(this.config.sessionUrl, { method: "GET" }, signal);
+		if (!response.ok) {
+			const text = await response.text();
+			throw new JmapApiError(`Session fetch failed: ${response.status}`, response.status, text);
+		}
+		return await response.json();
+	}
+	/**
+	* Executes a JMAP API request.
+	* @param apiUrl The JMAP API URL.
+	* @param request The JMAP request payload.
+	* @param signal Optional abort signal.
+	* @returns The JMAP response.
+	* @since 0.4.0
+	*/
+	async executeRequest(apiUrl, request, signal) {
+		signal?.throwIfAborted();
+		let lastError = null;
+		for (let attempt = 0; attempt <= this.config.retries; attempt++) {
+			signal?.throwIfAborted();
+			try {
+				const response = await this.fetchWithAuth(apiUrl, {
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify(request)
+				}, signal);
+				if (!response.ok) {
+					const text = await response.text();
+					const error = new JmapApiError(`JMAP request failed: ${response.status}`, response.status, text);
+					if (response.status >= 400 && response.status < 500) throw error;
+					throw error;
+				}
+				return await response.json();
+			} catch (error) {
+				if (error instanceof Error && error.name === "AbortError") throw error;
+				if (error instanceof JmapApiError && error.statusCode !== void 0) {
+					if (error.statusCode >= 400 && error.statusCode < 500) throw error;
+				}
+				lastError = error instanceof Error ? error : new Error(String(error));
+				if (attempt === this.config.retries) throw error;
+				const delay = Math.pow(2, attempt) * 1e3;
+				await new Promise((resolve) => setTimeout(resolve, delay));
+			}
+		}
+		throw lastError || /* @__PURE__ */ new Error("Request failed after all retries");
+	}
+	/**
+	* Makes an authenticated fetch request.
+	* @param url The URL to fetch.
+	* @param options Fetch options.
+	* @param signal Optional abort signal.
+	* @returns The fetch response.
+	* @since 0.4.0
+	*/
+	async fetchWithAuth(url, options, signal) {
+		const headers = new Headers(options.headers);
+		if (this.config.bearerToken) headers.set("Authorization", `Bearer ${this.config.bearerToken}`);
+		else if (this.config.basicAuth) {
+			const credentials = btoa(`${this.config.basicAuth.username}:${this.config.basicAuth.password}`);
+			headers.set("Authorization", `Basic ${credentials}`);
+		}
+		for (const [key, value] of Object.entries(this.config.headers)) headers.set(key, value);
+		const controller = new AbortController();
+		const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+		let combinedSignal = controller.signal;
+		if (signal) {
+			if (signal.aborted) {
+				clearTimeout(timeoutId);
+				signal.throwIfAborted();
+			}
+			signal.addEventListener("abort", () => controller.abort());
+			combinedSignal = controller.signal;
+		}
+		try {
+			return await globalThis.fetch(url, {
+				...options,
+				headers,
+				signal: combinedSignal
+			});
+		} finally {
+			clearTimeout(timeoutId);
+		}
+	}
+};
+
+//#endregion
+//#region src/message-converter.ts
+/**
+* Formats an Upyo Address to JMAP email address format.
+* @param address The Upyo address to format.
+* @returns The JMAP email address object.
+* @since 0.4.0
+*/
+function formatAddress(address) {
+	const result = { email: address.address };
+	if (address.name) return {
+		...result,
+		name: address.name
+	};
+	return result;
+}
+/**
+* Gets priority headers based on message priority.
+* @param priority The message priority.
+* @returns Array of JMAP headers for priority, or empty array for normal.
+* @since 0.4.0
+*/
+function getPriorityHeaders(priority) {
+	switch (priority) {
+		case "high": return [{
+			name: "X-Priority",
+			value: "1"
+		}, {
+			name: "Importance",
+			value: "high"
+		}];
+		case "low": return [{
+			name: "X-Priority",
+			value: "5"
+		}, {
+			name: "Importance",
+			value: "low"
+		}];
+		default: return [];
+	}
+}
+/**
+* Extracts custom headers from message headers.
+* @param message The message to extract headers from.
+* @returns Array of JMAP headers.
+* @since 0.4.0
+*/
+function extractCustomHeaders(message) {
+	const headers = [];
+	for (const [name, value] of message.headers.entries()) headers.push({
+		name,
+		value
+	});
+	return headers;
+}
+/**
+* Builds body structure for the message content.
+* @param message The message to build body structure for.
+* @param uploadedBlobs Map of contentId to blobId for attachments.
+* @returns Object containing bodyStructure and bodyValues.
+* @since 0.4.0
+*/
+function buildBodyStructure(message, uploadedBlobs) {
+	const bodyValues = {};
+	const parts = [];
+	if ("text" in message.content && message.content.text) {
+		bodyValues["text"] = { value: message.content.text };
+		parts.push({
+			partId: "text",
+			type: "text/plain; charset=utf-8"
+		});
+	}
+	if ("html" in message.content && message.content.html) {
+		bodyValues["html"] = { value: message.content.html };
+		parts.push({
+			partId: "html",
+			type: "text/html; charset=utf-8"
+		});
+	}
+	let contentPart;
+	if (parts.length === 1) contentPart = parts[0];
+	else if (parts.length > 1) contentPart = {
+		type: "multipart/alternative",
+		subParts: parts
+	};
+	else {
+		bodyValues["text"] = { value: "" };
+		contentPart = {
+			partId: "text",
+			type: "text/plain; charset=utf-8"
+		};
+	}
+	const inlineParts = buildInlineAttachmentParts(message.attachments, uploadedBlobs);
+	const attachmentParts = buildAttachmentParts(message.attachments, uploadedBlobs);
+	let mainBodyPart;
+	if (inlineParts.length > 0) mainBodyPart = {
+		type: "multipart/related",
+		subParts: [contentPart, ...inlineParts]
+	};
+	else mainBodyPart = contentPart;
+	let bodyStructure;
+	if (attachmentParts.length > 0) bodyStructure = {
+		type: "multipart/mixed",
+		subParts: [mainBodyPart, ...attachmentParts]
+	};
+	else bodyStructure = mainBodyPart;
+	return {
+		bodyStructure,
+		bodyValues
+	};
+}
+/**
+* Build inline attachment parts from uploaded blobs.
+* @param attachments Array of attachments from the message.
+* @param uploadedBlobs Map of contentId to blobId.
+* @returns Array of JmapBodyPart for inline attachments.
+* @since 0.4.0
+*/
+function buildInlineAttachmentParts(attachments, uploadedBlobs) {
+	const parts = [];
+	for (const attachment of attachments) {
+		const blobId = uploadedBlobs.get(attachment.contentId);
+		if (!blobId) continue;
+		if (attachment.inline) parts.push({
+			type: attachment.contentType,
+			blobId,
+			name: attachment.filename,
+			disposition: "inline",
+			cid: attachment.contentId
+		});
+	}
+	return parts;
+}
+/**
+* Build regular attachment parts from uploaded blobs.
+* @param attachments Array of attachments from the message.
+* @param uploadedBlobs Map of contentId to blobId.
+* @returns Array of JmapBodyPart for regular attachments.
+* @since 0.4.0
+*/
+function buildAttachmentParts(attachments, uploadedBlobs) {
+	const parts = [];
+	for (const attachment of attachments) {
+		const blobId = uploadedBlobs.get(attachment.contentId);
+		if (!blobId) continue;
+		if (!attachment.inline) parts.push({
+			type: attachment.contentType,
+			blobId,
+			name: attachment.filename,
+			disposition: "attachment"
+		});
+	}
+	return parts;
+}
+/**
+* Converts an Upyo Message to JMAP Email/set create format.
+* @param message The Upyo message to convert.
+* @param draftMailboxId The mailbox ID to store the draft in.
+* @param uploadedBlobs Map of contentId to blobId for attachments.
+* @returns The JMAP Email/set create object.
+* @since 0.4.0
+*/
+function convertMessage(message, draftMailboxId, uploadedBlobs) {
+	const { bodyStructure, bodyValues } = buildBodyStructure(message, uploadedBlobs);
+	const headers = [];
+	if (message.priority !== "normal") headers.push(...getPriorityHeaders(message.priority));
+	headers.push(...extractCustomHeaders(message));
+	const email = {
+		mailboxIds: { [draftMailboxId]: true },
+		from: [formatAddress(message.sender)],
+		subject: message.subject,
+		bodyStructure,
+		bodyValues,
+		...message.recipients.length > 0 && { to: message.recipients.map(formatAddress) },
+		...message.ccRecipients.length > 0 && { cc: message.ccRecipients.map(formatAddress) },
+		...message.bccRecipients.length > 0 && { bcc: message.bccRecipients.map(formatAddress) },
+		...message.replyRecipients.length > 0 && { replyTo: message.replyRecipients.map(formatAddress) },
+		...headers.length > 0 && { headers }
+	};
+	return email;
+}
+
+//#endregion
+//#region src/session.ts
+/**
+* Finds the first account with mail capability from a JMAP session.
+* @param session The JMAP session response.
+* @returns The account ID with mail capability, or `null` if none found.
+* @since 0.4.0
+*/
+function findMailAccount(session) {
+	for (const [accountId, account] of Object.entries(session.accounts)) if ("urn:ietf:params:jmap:mail" in account.accountCapabilities) return accountId;
+	return null;
+}
+
+//#endregion
+//#region src/jmap-transport.ts
+/**
+* JMAP capabilities required for email sending.
+* @since 0.4.0
+*/
+const JMAP_CAPABILITIES = {
+	core: "urn:ietf:params:jmap:core",
+	mail: "urn:ietf:params:jmap:mail",
+	submission: "urn:ietf:params:jmap:submission"
+};
+/**
+* JMAP transport for sending emails via JMAP protocol (RFC 8620/8621).
+* @since 0.4.0
+*/
+var JmapTransport = class {
+	config;
+	httpClient;
+	cachedSession = null;
+	/**
+	* Creates a new JMAP transport instance.
+	* @param config The JMAP transport configuration.
+	* @since 0.4.0
+	*/
+	constructor(config) {
+		this.config = createJmapConfig(config);
+		this.httpClient = new JmapHttpClient(this.config);
+	}
+	/**
+	* Sends a single email message.
+	* @param message The message to send.
+	* @param options Optional transport options.
+	* @returns A receipt indicating success or failure.
+	* @since 0.4.0
+	*/
+	async send(message, options) {
+		const signal = options?.signal;
+		try {
+			signal?.throwIfAborted();
+			const session = await this.getSession(signal);
+			signal?.throwIfAborted();
+			const accountId = this.config.accountId ?? findMailAccount(session);
+			if (!accountId) return {
+				successful: false,
+				errorMessages: ["No mail-capable account found in JMAP session"]
+			};
+			const draftsMailboxId = await this.getDraftsMailboxId(session, accountId, signal);
+			signal?.throwIfAborted();
+			const identityId = await this.getIdentityId(session, accountId, message.sender.address, signal);
+			signal?.throwIfAborted();
+			const uploadedBlobs = await this.uploadAttachments(session, accountId, message.attachments, signal);
+			signal?.throwIfAborted();
+			const emailCreate = convertMessage(message, draftsMailboxId, uploadedBlobs);
+			const response = await this.httpClient.executeRequest(session.apiUrl, {
+				using: [
+					JMAP_CAPABILITIES.core,
+					JMAP_CAPABILITIES.mail,
+					JMAP_CAPABILITIES.submission
+				],
+				methodCalls: [[
+					"Email/set",
+					{
+						accountId,
+						create: { draft: emailCreate }
+					},
+					"c0"
+				], [
+					"EmailSubmission/set",
+					{
+						accountId,
+						create: { submission: {
+							identityId,
+							emailId: "#draft"
+						} }
+					},
+					"c1"
+				]]
+			}, signal);
+			return this.parseResponse(response);
+		} catch (error) {
+			if (error instanceof Error && error.name === "AbortError") return {
+				successful: false,
+				errorMessages: [`Request aborted: ${error.message}`]
+			};
+			if (error instanceof JmapApiError) return {
+				successful: false,
+				errorMessages: [error.message]
+			};
+			return {
+				successful: false,
+				errorMessages: [error instanceof Error ? error.message : String(error)]
+			};
+		}
+	}
+	/**
+	* Sends multiple messages sequentially.
+	* @param messages The messages to send.
+	* @param options Optional transport options.
+	* @yields Receipts for each message.
+	* @since 0.4.0
+	*/
+	async *sendMany(messages, options) {
+		for await (const message of messages) yield await this.send(message, options);
+	}
+	/**
+	* Gets or refreshes the JMAP session.
+	* @param signal Optional abort signal.
+	* @returns The JMAP session.
+	* @since 0.4.0
+	*/
+	async getSession(signal) {
+		const now = Date.now();
+		if (this.cachedSession && now - this.cachedSession.fetchedAt < this.config.sessionCacheTtl) return this.cachedSession.session;
+		let session = await this.httpClient.fetchSession(signal);
+		if (this.config.baseUrl) session = this.rewriteSessionUrls(session);
+		this.cachedSession = {
+			session,
+			fetchedAt: now
+		};
+		return session;
+	}
+	/**
+	* Rewrites session URLs to use the configured baseUrl.
+	* @param session The original session from the server.
+	* @returns A new session with rewritten URLs.
+	* @since 0.4.0
+	*/
+	rewriteSessionUrls(session) {
+		const baseUrl = this.config.baseUrl;
+		const rewriteUrl = (url) => {
+			try {
+				const base = new URL(baseUrl);
+				return url.replace(/^(\w+):\/\/[^/]+/, `${base.protocol}//${base.host}`);
+			} catch {
+				return url;
+			}
+		};
+		return {
+			...session,
+			apiUrl: rewriteUrl(session.apiUrl),
+			downloadUrl: rewriteUrl(session.downloadUrl),
+			uploadUrl: rewriteUrl(session.uploadUrl),
+			eventSourceUrl: session.eventSourceUrl ? rewriteUrl(session.eventSourceUrl) : void 0
+		};
+	}
+	/**
+	* Gets the drafts mailbox ID from the session.
+	* @param session The JMAP session.
+	* @param accountId The account ID.
+	* @param signal Optional abort signal.
+	* @returns The drafts mailbox ID.
+	* @since 0.4.0
+	*/
+	async getDraftsMailboxId(session, accountId, signal) {
+		const response = await this.httpClient.executeRequest(session.apiUrl, {
+			using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.mail],
+			methodCalls: [[
+				"Mailbox/get",
+				{
+					accountId,
+					properties: [
+						"id",
+						"role",
+						"name"
+					]
+				},
+				"c0"
+			]]
+		}, signal);
+		const mailboxResponse = response.methodResponses.find((r) => r[0] === "Mailbox/get");
+		if (!mailboxResponse) throw new JmapApiError("No Mailbox/get response received");
+		const mailboxes = mailboxResponse[1].list;
+		if (!mailboxes) throw new JmapApiError("No mailboxes found");
+		const drafts = mailboxes.find((m) => m.role === "drafts");
+		if (!drafts) throw new JmapApiError("No drafts mailbox found");
+		return drafts.id;
+	}
+	/**
+	* Gets the identity ID for the sender.
+	* @param session The JMAP session.
+	* @param accountId The account ID.
+	* @param senderEmail The sender's email address.
+	* @param signal Optional abort signal.
+	* @returns The identity ID.
+	* @since 0.4.0
+	*/
+	async getIdentityId(session, accountId, senderEmail, signal) {
+		if (this.config.identityId) return this.config.identityId;
+		const response = await this.httpClient.executeRequest(session.apiUrl, {
+			using: [JMAP_CAPABILITIES.core, JMAP_CAPABILITIES.submission],
+			methodCalls: [[
+				"Identity/get",
+				{ accountId },
+				"c0"
+			]]
+		}, signal);
+		const identityResponse = response.methodResponses.find((r) => r[0] === "Identity/get");
+		if (!identityResponse) throw new JmapApiError("No Identity/get response received");
+		const identities = identityResponse[1].list;
+		if (!identities || identities.length === 0) throw new JmapApiError("No identities found");
+		const matching = identities.find((i) => i.email.toLowerCase() === senderEmail.toLowerCase());
+		if (matching) return matching.id;
+		return identities[0].id;
+	}
+	/**
+	* Uploads all attachments and returns a map of contentId to blobId.
+	* @param session The JMAP session.
+	* @param accountId The account ID.
+	* @param attachments Array of attachments to upload.
+	* @param signal Optional abort signal.
+	* @returns Map of contentId to blobId.
+	* @since 0.4.0
+	*/
+	async uploadAttachments(session, accountId, attachments, signal) {
+		const uploadedBlobs = /* @__PURE__ */ new Map();
+		for (const attachment of attachments) {
+			signal?.throwIfAborted();
+			const content = await attachment.content;
+			const arrayBuffer = content.buffer.slice(content.byteOffset, content.byteOffset + content.byteLength);
+			const blob = new Blob([arrayBuffer], { type: attachment.contentType });
+			const result = await uploadBlob(this.config, session.uploadUrl, accountId, blob, signal);
+			uploadedBlobs.set(attachment.contentId, result.blobId);
+		}
+		return uploadedBlobs;
+	}
+	/**
+	* Parses the JMAP response to extract receipt information.
+	* @param response The JMAP response.
+	* @returns A receipt indicating success or failure.
+	* @since 0.4.0
+	*/
+	parseResponse(response) {
+		const errors = [];
+		const emailResponse = response.methodResponses.find((r) => r[0] === "Email/set");
+		if (emailResponse) {
+			const emailResult = emailResponse[1];
+			if (emailResult.notCreated) for (const [key, error] of Object.entries(emailResult.notCreated)) errors.push(`Email creation failed (${key}): ${error.type}${error.description ? ` - ${error.description}` : ""}`);
+		}
+		const submissionResponse = response.methodResponses.find((r) => r[0] === "EmailSubmission/set");
+		if (submissionResponse) {
+			const submissionResult = submissionResponse[1];
+			if (submissionResult.notCreated) for (const [key, error] of Object.entries(submissionResult.notCreated)) errors.push(`Email submission failed (${key}): ${error.type}${error.description ? ` - ${error.description}` : ""}`);
+			if (submissionResult.created?.submission) return {
+				successful: true,
+				messageId: submissionResult.created.submission.id
+			};
+		}
+		if (errors.length === 0) errors.push("Unknown error: No submission result received");
+		return {
+			successful: false,
+			errorMessages: errors
+		};
+	}
+};
+
+//#endregion
+exports.JMAP_ERROR_TYPES = JMAP_ERROR_TYPES;
+exports.JmapApiError = JmapApiError;
+exports.JmapTransport = JmapTransport;
+exports.createJmapConfig = createJmapConfig;
+exports.isCapabilityError = isCapabilityError;
+exports.uploadBlob = uploadBlob;