@upyo/core 0.1.0-dev.9 → 0.1.1

package/README.md

@@ -3,9 +3,18 @@
 @upyo/core
 ==========
 
-Shared types and interfaces for Upyo, a simple and cross-runtime library for
+[![JSR][JSR badge]][JSR]
+[![npm][npm badge]][npm]
+
+Shared types and interfaces for [Upyo], a simple and cross-runtime library for
 sending email messages.
 
+[JSR]: https://jsr.io/@upyo/core
+[JSR badge]: https://jsr.io/badges/@upyo/core
+[npm]: https://www.npmjs.com/package/@upyo/core
+[npm badge]: https://img.shields.io/npm/v/@upyo/core?logo=npm
+[Upyo]: https://upyo.org/
+
 
 Installation
 ------------

package/dist/attachment.cjs

@@ -0,0 +1,13 @@
+
+//#region src/attachment.ts
+/**
+* Checks if the provided value is an {@link Attachment} object.
+* @param attachment The value to check.
+* @return `true` if the value is an {@link Attachment}, otherwise `false`.
+*/
+function isAttachment(attachment) {
+	return typeof attachment === "object" && attachment !== null && "inline" in attachment && "filename" in attachment && "content" in attachment && "contentType" in attachment && "contentId" in attachment && typeof attachment.inline === "boolean" && typeof attachment.filename === "string" && (attachment.content instanceof Uint8Array || attachment.content instanceof Promise && typeof attachment.content.then === "function") && typeof attachment.contentType === "string" && typeof attachment.contentId === "string";
+}
+
+//#endregion
+exports.isAttachment = isAttachment;

package/dist/attachment.d.cts

@@ -13,9 +13,11 @@ interface Attachment {
    */
   readonly filename: string;
   /**
-   * The content of the attachment as a byte array.
+   * The content of the attachment as a byte array.  It can be a `Promise`
+   * that resolves to a `Uint8Array`, allowing for asynchronous loading
+   * of the attachment content.
    */
-  readonly content: Uint8Array;
+  readonly content: Uint8Array | Promise<Uint8Array>;
   /**
    * The media type of the attachment, which indicates the type of content
    * and how it should be handled by email clients.
@@ -27,5 +29,11 @@ interface Attachment {
    */
   readonly contentId: string;
 }
+/**
+ * Checks if the provided value is an {@link Attachment} object.
+ * @param attachment The value to check.
+ * @return `true` if the value is an {@link Attachment}, otherwise `false`.
+ */
+declare function isAttachment(attachment: unknown): attachment is Attachment;
 //#endregion
-export { Attachment };
+export { Attachment, isAttachment };

package/dist/attachment.d.ts

@@ -13,9 +13,11 @@ interface Attachment {
    */
   readonly filename: string;
   /**
-   * The content of the attachment as a byte array.
+   * The content of the attachment as a byte array.  It can be a `Promise`
+   * that resolves to a `Uint8Array`, allowing for asynchronous loading
+   * of the attachment content.
    */
-  readonly content: Uint8Array;
+  readonly content: Uint8Array | Promise<Uint8Array>;
   /**
    * The media type of the attachment, which indicates the type of content
    * and how it should be handled by email clients.
@@ -27,5 +29,11 @@ interface Attachment {
    */
   readonly contentId: string;
 }
+/**
+ * Checks if the provided value is an {@link Attachment} object.
+ * @param attachment The value to check.
+ * @return `true` if the value is an {@link Attachment}, otherwise `false`.
+ */
+declare function isAttachment(attachment: unknown): attachment is Attachment;
 //#endregion
-export { Attachment };
+export { Attachment, isAttachment };

package/dist/attachment.js

@@ -0,0 +1,12 @@
+//#region src/attachment.ts
+/**
+* Checks if the provided value is an {@link Attachment} object.
+* @param attachment The value to check.
+* @return `true` if the value is an {@link Attachment}, otherwise `false`.
+*/
+function isAttachment(attachment) {
+	return typeof attachment === "object" && attachment !== null && "inline" in attachment && "filename" in attachment && "content" in attachment && "contentType" in attachment && "contentId" in attachment && typeof attachment.inline === "boolean" && typeof attachment.filename === "string" && (attachment.content instanceof Uint8Array || attachment.content instanceof Promise && typeof attachment.content.then === "function") && typeof attachment.contentType === "string" && typeof attachment.contentId === "string";
+}
+
+//#endregion
+export { isAttachment };

package/dist/index.cjs

@@ -1,6 +1,10 @@
 const require_address = require('./address.cjs');
+const require_attachment = require('./attachment.cjs');
+const require_message = require('./message.cjs');
 const require_priority = require('./priority.cjs');
 
 exports.comparePriority = require_priority.comparePriority;
+exports.createMessage = require_message.createMessage;
 exports.formatAddress = require_address.formatAddress;
+exports.isAttachment = require_attachment.isAttachment;
 exports.parseAddress = require_address.parseAddress;

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { Address, formatAddress, parseAddress } from "./address.cjs";
-import { Attachment } from "./attachment.cjs";
+import { Attachment, isAttachment } from "./attachment.cjs";
 import { Priority, comparePriority } from "./priority.cjs";
-import { ImmutableHeaders, Message, MessageContent } from "./message.cjs";
+import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.cjs";
 import { Receipt } from "./receipt.cjs";
 import { Transport, TransportOptions } from "./transport.cjs";
-export { Address, Attachment, ImmutableHeaders, Message, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, formatAddress, parseAddress };
+export { Address, Attachment, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, parseAddress };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { Address, formatAddress, parseAddress } from "./address.js";
-import { Attachment } from "./attachment.js";
+import { Attachment, isAttachment } from "./attachment.js";
 import { Priority, comparePriority } from "./priority.js";
-import { ImmutableHeaders, Message, MessageContent } from "./message.js";
+import { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage } from "./message.js";
 import { Receipt } from "./receipt.js";
 import { Transport, TransportOptions } from "./transport.js";
-export { Address, Attachment, ImmutableHeaders, Message, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, formatAddress, parseAddress };
+export { Address, Attachment, ImmutableHeaders, Message, MessageConstructor, MessageContent, Priority, Receipt, Transport, TransportOptions, comparePriority, createMessage, formatAddress, isAttachment, parseAddress };

package/dist/index.js

@@ -1,4 +1,6 @@
 import { formatAddress, parseAddress } from "./address.js";
+import { isAttachment } from "./attachment.js";
+import { createMessage } from "./message.js";
 import { comparePriority } from "./priority.js";
 
-export { comparePriority, formatAddress, parseAddress };
+export { comparePriority, createMessage, formatAddress, isAttachment, parseAddress };

package/dist/message.cjs

@@ -0,0 +1,62 @@
+const require_address = require('./address.cjs');
+const require_attachment = require('./attachment.cjs');
+
+//#region src/message.ts
+/**
+* Creates a new email {@link Message} based on the provided constructor
+* parameters.  This function provides a more convenient API for creating
+* messages compared to constructing a {@link Message} object directly.
+*
+* @example
+* ```typescript
+* const message = createMessage({
+*   from: "sender@example.com",
+*   to: "recipient1@example.com",
+*   subject: "Hello World",
+*   content: { text: "This is a test message" }
+* });
+* ```
+*
+* @param constructor The constructor parameters for the message. Uses more
+*                    user-friendly types like accepting strings for email
+*                    addresses and `File` objects for attachments.
+* @returns A new {@link Message} object with all properties normalized and
+*          validated.
+* @throws {TypeError} When any email address string cannot be parsed or when
+*                     an attachment object is invalid.
+*/
+function createMessage(constructor) {
+	const sender = typeof constructor.from === "string" ? require_address.parseAddress(constructor.from) ?? throwTypeError(`Invalid sender address: ${JSON.stringify(constructor.from)}`) : constructor.from;
+	return {
+		sender,
+		recipients: esureArray(constructor.to).map((to) => typeof to === "string" ? require_address.parseAddress(to) ?? throwTypeError(`Invalid recipient address: ${JSON.stringify(to)}`) : to),
+		ccRecipients: esureArray(constructor.cc).map((cc) => typeof cc === "string" ? require_address.parseAddress(cc) ?? throwTypeError(`Invalid CC address: ${JSON.stringify(cc)}`) : cc),
+		bccRecipients: esureArray(constructor.bcc).map((bcc) => typeof bcc === "string" ? require_address.parseAddress(bcc) ?? throwTypeError(`Invalid BCC address: ${JSON.stringify(bcc)}`) : bcc),
+		replyRecipients: esureArray(constructor.replyTo).map((replyTo) => typeof replyTo === "string" ? require_address.parseAddress(replyTo) ?? throwTypeError(`Invalid reply-to address: ${JSON.stringify(replyTo)}`) : replyTo),
+		attachments: esureArray(constructor.attachments).map((attachment) => {
+			if (attachment instanceof File) return {
+				inline: false,
+				filename: attachment.name,
+				content: attachment.arrayBuffer().then((b) => new Uint8Array(b)),
+				contentType: attachment.type == null || attachment.type === "" ? "application/octet-stream" : attachment.type,
+				contentId: `${crypto.randomUUID()}@${sender.address.replace(/^[^@]*@/, "")}`
+			};
+			else if (require_attachment.isAttachment(attachment)) return attachment;
+			else throwTypeError(`Invalid attachment: ${JSON.stringify(attachment)}`);
+		}),
+		subject: constructor.subject,
+		content: constructor.content,
+		priority: constructor.priority ?? "normal",
+		tags: esureArray(constructor.tags),
+		headers: new Headers(constructor.headers ?? {})
+	};
+}
+function throwTypeError(message) {
+	throw new TypeError(message);
+}
+function esureArray(value) {
+	return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+
+//#endregion
+exports.createMessage = createMessage;

package/dist/message.d.cts

@@ -7,6 +7,10 @@ import { Priority } from "./priority.cjs";
 /**
  * Represents an email message with various properties such as
  * sender, recipients, subject, content, and attachments.
+ *
+ * You wouldn't typically create this type directly.  Instead, you probably
+ * want to use the {@link createMessage} function, which provides a more
+ * convenient API for creating messages.
  */
 interface Message {
   /**
@@ -107,5 +111,101 @@ type MessageContent = {
  * read-only access to the headers of an email message.
  */
 type ImmutableHeaders = Omit<Headers, "append" | "delete" | "set">;
+/**
+ * A constructor interface for creating a new email message using
+ * the {@link createMessage} function.
+ */
+interface MessageConstructor {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly from: Address | string;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly to: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   * @default `[]`
+   */
+  readonly cc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   * @default `[]`
+   */
+  readonly bcc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   * @default `[]`
+   */
+  readonly replyTo?: Address | string | (Address | string)[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment can be represented by an {@link Attachment}
+   * or a `File` object, which contains information about the attachment such as
+   * its filename and content type.
+   * @default `[]`
+   */
+  readonly attachments?: Attachment | File | (Attachment | File)[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   * @default `"normal"`
+   */
+  readonly priority?: Priority;
+  /**
+   * The tags associated with the email message.
+   * @default `[]`
+   */
+  readonly tags?: string[];
+  /**
+   * The headers of the email message.
+   * @default `{}`
+   */
+  readonly headers?: ImmutableHeaders | Record<string, string>;
+}
+/**
+ * Creates a new email {@link Message} based on the provided constructor
+ * parameters.  This function provides a more convenient API for creating
+ * messages compared to constructing a {@link Message} object directly.
+ *
+ * @example
+ * ```typescript
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient1@example.com",
+ *   subject: "Hello World",
+ *   content: { text: "This is a test message" }
+ * });
+ * ```
+ *
+ * @param constructor The constructor parameters for the message. Uses more
+ *                    user-friendly types like accepting strings for email
+ *                    addresses and `File` objects for attachments.
+ * @returns A new {@link Message} object with all properties normalized and
+ *          validated.
+ * @throws {TypeError} When any email address string cannot be parsed or when
+ *                     an attachment object is invalid.
+ */
+declare function createMessage(constructor: MessageConstructor): Message;
 //#endregion
-export { ImmutableHeaders, Message, MessageContent };
+export { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage };

package/dist/message.d.ts

@@ -7,6 +7,10 @@ import { Priority } from "./priority.js";
 /**
  * Represents an email message with various properties such as
  * sender, recipients, subject, content, and attachments.
+ *
+ * You wouldn't typically create this type directly.  Instead, you probably
+ * want to use the {@link createMessage} function, which provides a more
+ * convenient API for creating messages.
  */
 interface Message {
   /**
@@ -107,5 +111,101 @@ type MessageContent = {
  * read-only access to the headers of an email message.
  */
 type ImmutableHeaders = Omit<Headers, "append" | "delete" | "set">;
+/**
+ * A constructor interface for creating a new email message using
+ * the {@link createMessage} function.
+ */
+interface MessageConstructor {
+  /**
+   * The email address of the sender of the message.
+   */
+  readonly from: Address | string;
+  /**
+   * The email addresses of the recipient of the message.
+   */
+  readonly to: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the carbon copy (CC) recipients of the message.
+   * @default `[]`
+   */
+  readonly cc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the blind carbon copy (BCC) recipients of the message.
+   * @default `[]`
+   */
+  readonly bcc?: Address | string | (Address | string)[];
+  /**
+   * The email addresses of the reply-to recipients of the message.
+   * @default `[]`
+   */
+  readonly replyTo?: Address | string | (Address | string)[];
+  /**
+   * The attachments included in the email message.  These are files that
+   * are sent along with the email, such as documents, images, or other
+   * media files.  Each attachment can be represented by an {@link Attachment}
+   * or a `File` object, which contains information about the attachment such as
+   * its filename and content type.
+   * @default `[]`
+   */
+  readonly attachments?: Attachment | File | (Attachment | File)[];
+  /**
+   * The subject of the email message.  This is typically a brief summary
+   * of the content of the email, and is used to help the recipient identify
+   * the purpose of the message.
+   */
+  readonly subject: string;
+  /**
+   * The content of the email message, which can be either HTML or plain text.
+   * This property is represented by the {@link MessageContent} type, which
+   * includes both HTML and plain text content.  The HTML content is typically
+   * used for rich formatting and layout, while the plain text content is
+   * used for simple text emails or for compatibility with email clients
+   * that do not support HTML.
+   */
+  readonly content: MessageContent;
+  /**
+   * The priority of the email message, which indicates its importance
+   * relative to other messages.  The priority can be one of three
+   * levels: `"high"`, `"normal"`, or `"low"`.  This is represented by
+   * the {@link Priority} type, which is a string literal type that
+   * allows only these three values.
+   * @default `"normal"`
+   */
+  readonly priority?: Priority;
+  /**
+   * The tags associated with the email message.
+   * @default `[]`
+   */
+  readonly tags?: string[];
+  /**
+   * The headers of the email message.
+   * @default `{}`
+   */
+  readonly headers?: ImmutableHeaders | Record<string, string>;
+}
+/**
+ * Creates a new email {@link Message} based on the provided constructor
+ * parameters.  This function provides a more convenient API for creating
+ * messages compared to constructing a {@link Message} object directly.
+ *
+ * @example
+ * ```typescript
+ * const message = createMessage({
+ *   from: "sender@example.com",
+ *   to: "recipient1@example.com",
+ *   subject: "Hello World",
+ *   content: { text: "This is a test message" }
+ * });
+ * ```
+ *
+ * @param constructor The constructor parameters for the message. Uses more
+ *                    user-friendly types like accepting strings for email
+ *                    addresses and `File` objects for attachments.
+ * @returns A new {@link Message} object with all properties normalized and
+ *          validated.
+ * @throws {TypeError} When any email address string cannot be parsed or when
+ *                     an attachment object is invalid.
+ */
+declare function createMessage(constructor: MessageConstructor): Message;
 //#endregion
-export { ImmutableHeaders, Message, MessageContent };
+export { ImmutableHeaders, Message, MessageConstructor, MessageContent, createMessage };

package/dist/message.js

@@ -0,0 +1,62 @@
+import { parseAddress } from "./address.js";
+import { isAttachment } from "./attachment.js";
+
+//#region src/message.ts
+/**
+* Creates a new email {@link Message} based on the provided constructor
+* parameters.  This function provides a more convenient API for creating
+* messages compared to constructing a {@link Message} object directly.
+*
+* @example
+* ```typescript
+* const message = createMessage({
+*   from: "sender@example.com",
+*   to: "recipient1@example.com",
+*   subject: "Hello World",
+*   content: { text: "This is a test message" }
+* });
+* ```
+*
+* @param constructor The constructor parameters for the message. Uses more
+*                    user-friendly types like accepting strings for email
+*                    addresses and `File` objects for attachments.
+* @returns A new {@link Message} object with all properties normalized and
+*          validated.
+* @throws {TypeError} When any email address string cannot be parsed or when
+*                     an attachment object is invalid.
+*/
+function createMessage(constructor) {
+	const sender = typeof constructor.from === "string" ? parseAddress(constructor.from) ?? throwTypeError(`Invalid sender address: ${JSON.stringify(constructor.from)}`) : constructor.from;
+	return {
+		sender,
+		recipients: esureArray(constructor.to).map((to) => typeof to === "string" ? parseAddress(to) ?? throwTypeError(`Invalid recipient address: ${JSON.stringify(to)}`) : to),
+		ccRecipients: esureArray(constructor.cc).map((cc) => typeof cc === "string" ? parseAddress(cc) ?? throwTypeError(`Invalid CC address: ${JSON.stringify(cc)}`) : cc),
+		bccRecipients: esureArray(constructor.bcc).map((bcc) => typeof bcc === "string" ? parseAddress(bcc) ?? throwTypeError(`Invalid BCC address: ${JSON.stringify(bcc)}`) : bcc),
+		replyRecipients: esureArray(constructor.replyTo).map((replyTo) => typeof replyTo === "string" ? parseAddress(replyTo) ?? throwTypeError(`Invalid reply-to address: ${JSON.stringify(replyTo)}`) : replyTo),
+		attachments: esureArray(constructor.attachments).map((attachment) => {
+			if (attachment instanceof File) return {
+				inline: false,
+				filename: attachment.name,
+				content: attachment.arrayBuffer().then((b) => new Uint8Array(b)),
+				contentType: attachment.type == null || attachment.type === "" ? "application/octet-stream" : attachment.type,
+				contentId: `${crypto.randomUUID()}@${sender.address.replace(/^[^@]*@/, "")}`
+			};
+			else if (isAttachment(attachment)) return attachment;
+			else throwTypeError(`Invalid attachment: ${JSON.stringify(attachment)}`);
+		}),
+		subject: constructor.subject,
+		content: constructor.content,
+		priority: constructor.priority ?? "normal",
+		tags: esureArray(constructor.tags),
+		headers: new Headers(constructor.headers ?? {})
+	};
+}
+function throwTypeError(message) {
+	throw new TypeError(message);
+}
+function esureArray(value) {
+	return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+
+//#endregion
+export { createMessage };

package/dist/receipt.d.cts

@@ -1,21 +1,30 @@
 //#region src/receipt.d.ts
 /**
  * The response from the email service after sending an email message.
+ *
+ * This type uses a discriminated union to ensure type safety:
+ *
+ * - Successful sends have a `messageId` but no `errorMessages`
+ * - Failed sends have `errorMessages` but no `messageId`
  */
-interface Receipt {
+type Receipt = {
+  /**
+   * Indicates that the email was sent successfully.
+   */
+  readonly successful: true;
   /**
    * The unique identifier for the message that was sent.
    */
   readonly messageId: string;
+} | {
   /**
-   * An array of error messages that occurred during the sending process,
-   * if any. If the email was sent successfully, this array will be empty.
+   * Indicates that the email failed to send.
    */
-  readonly errorMessages: string[];
+  readonly successful: false;
   /**
-   * Indicates whether the email was sent successfully.
+   * An array of error messages that occurred during the sending process.
    */
-  readonly successful: boolean;
-}
+  readonly errorMessages: readonly string[];
+};
 //#endregion
 export { Receipt };

package/dist/receipt.d.ts

@@ -1,21 +1,30 @@
 //#region src/receipt.d.ts
 /**
  * The response from the email service after sending an email message.
+ *
+ * This type uses a discriminated union to ensure type safety:
+ *
+ * - Successful sends have a `messageId` but no `errorMessages`
+ * - Failed sends have `errorMessages` but no `messageId`
  */
-interface Receipt {
+type Receipt = {
+  /**
+   * Indicates that the email was sent successfully.
+   */
+  readonly successful: true;
   /**
    * The unique identifier for the message that was sent.
    */
   readonly messageId: string;
+} | {
   /**
-   * An array of error messages that occurred during the sending process,
-   * if any. If the email was sent successfully, this array will be empty.
+   * Indicates that the email failed to send.
    */
-  readonly errorMessages: string[];
+  readonly successful: false;
   /**
-   * Indicates whether the email was sent successfully.
+   * An array of error messages that occurred during the sending process.
    */
-  readonly successful: boolean;
-}
+  readonly errorMessages: readonly string[];
+};
 //#endregion
 export { Receipt };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upyo/core",
-  "version": "0.1.0-dev.9+a57dde18",
+  "version": "0.1.1",
   "description": "Simple email sending library for Node.js, Deno, Bun, and edge functions",
   "keywords": [
     "email",
@@ -102,7 +102,7 @@
   "sideEffects": false,
   "devDependencies": {
     "tsdown": "^0.12.7",
-    "typescript": "^5.8.3"
+    "typescript": "5.8.3"
   },
   "scripts": {
     "build": "tsdown",