@ahmedayob/email-toolkit
Version:
A powerful and flexible toolkit for building, validating, and processing emails with TypeScript. This library offers utilities for handling email headers, attachments, and encoding, making it easier to compose and manage emails programmatically.
978 lines (962 loc) • 42.7 kB
text/typescript
import { z } from 'zod';
/**
* Utility class for Base64 encoding and decoding.
*/
declare class Base64 {
/**
* Encodes a given string into Base64.
*
* @param {string} input - The string to be encoded into Base64.
* @returns {string} The Base64 encoded string.
*
* @example
* const encoded = Base64.encodeToBase64('hello world');
* console.log(encoded); // Outputs: aGVsbG8gd29ybGQ=
*/
static encodeToBase64(input: string): string;
/**
* Decodes a Base64 encoded string back to its original string representation.
*
* @param {string} input - The Base64 encoded string to be decoded.
* @returns {string} The decoded string.
*
* @example
* const decoded = Base64.decodeToString('aGVsbG8gd29ybGQ=');
* console.log(decoded); // Outputs: hello world
*/
static decodeToString(input: string): string;
/**
* Decodes a Base64 encoded string into a Uint8Array.
*
* @param {string} input - The Base64 encoded string to be decoded.
* @returns {Uint8Array} The decoded Uint8Array.
*
* @example
* const buffer = Base64.decodeToBuffer('aGVsbG8gd29ybGQ=');
* console.log(new TextDecoder().decode(buffer)); // Outputs: hello world
*/
static decodeToBuffer(input: string): Uint8Array;
/**
* Encodes a string into Base64 and then URI encodes the result.
*
* @param {string} input - The string to be encoded and URI encoded.
* @returns {string} The URI encoded Base64 string.
*
* @example
* const uriEncoded = Base64.toBufferURI('hello world');
* console.log(uriEncoded); // Outputs: aGVsbG8gd29ybGQ%3D
*/
static toBufferURI(input: string): string;
/**
* Encodes a string into Base64 and returns the result as a Uint8Array.
*
* @param {string} input - The string to be encoded.
* @returns {Uint8Array} The encoded Uint8Array.
*
* @example
* const encodedBuffer = Base64.encodeToBuffer('hello world');
* console.log(new TextDecoder().decode(encodedBuffer)); // Outputs: hello world
*/
static encodeToBuffer(input: string): Uint8Array;
}
/**
* Schema for validating content transfer encodings.
* This schema ensures that the value is one of the allowed content transfer encodings.
*/
declare const ContentTransferEncodingSchema: z.ZodEnum<["7bit", "8bit", "binary", "base64", "quoted-printable"]>;
/**
* Schema for validating MIME types.
* This schema ensures that the value is one of the allowed MIME types.
*/
declare const ContentTypeSchema: z.ZodEnum<["text/plain", "text/html", "application/pdf", "image/png", "image/jpeg"]>;
/**
* Schema for validating character sets.
* This schema ensures that the value is one of the allowed character sets.
*/
declare const CharsetTypeSchema: z.ZodEnum<["utf-8", "utf8", "utf16le", "utf-16le", "latin1"]>;
/**
* Schema for validating strings.
* This schema ensures that the value is a string.
*/
declare const StringSchema: z.ZodString;
/**
* Schema for validating email headers.
* This schema ensures that the headers conform to expected formats and optional properties.
*/
declare const HeadersTypeSchema: z.ZodObject<{
/**
* The subject of the email.
* @type {string | undefined}
*/
Subject: z.ZodOptional<z.ZodString>;
/**
* The sender of the email.
* @type {string | undefined}
*/
From: z.ZodOptional<z.ZodString>;
/**
* The recipient of the email.
* @type {string | undefined}
*/
To: z.ZodOptional<z.ZodString>;
/**
* The CC recipients of the email.
* @type {string[] | undefined}
*/
Cc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
/**
* The BCC recipients of the email.
* @type {string[] | undefined}
*/
Bcc: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
/**
* The date the email was sent.
* @type {string | undefined}
*/
Date: z.ZodOptional<z.ZodString>;
/**
* The email address that this message is a reply to.
* @type {string | undefined}
*/
"In-Reply-To": z.ZodOptional<z.ZodString>;
/**
* The content type of the email.
* @type {string | undefined}
*/
"Content-Type": z.ZodOptional<z.ZodEnum<["text/plain", "text/html", "application/pdf", "image/png", "image/jpeg"]>>;
/**
* The content transfer encoding of the email.
* @type {string | undefined}
*/
"Content-Transfer-Encoding": z.ZodOptional<z.ZodEnum<["7bit", "8bit", "binary", "base64", "quoted-printable"]>>;
/**
* The MIME version of the email.
* @type {string | undefined}
*/
"MIME-Version": z.ZodOptional<z.ZodString>;
/**
* The character set of the email.
* @type {string | undefined}
*/
Charset: z.ZodOptional<z.ZodEnum<["utf-8", "utf8", "utf16le", "utf-16le", "latin1"]>>;
}, "strip", z.ZodTypeAny, {
"Content-Type"?: "text/plain" | "text/html" | "application/pdf" | "image/png" | "image/jpeg" | undefined;
"Content-Transfer-Encoding"?: "7bit" | "8bit" | "binary" | "quoted-printable" | "base64" | undefined;
Subject?: string | undefined;
From?: string | undefined;
To?: string | undefined;
Cc?: string[] | undefined;
Bcc?: string[] | undefined;
Date?: string | undefined;
"In-Reply-To"?: string | undefined;
"MIME-Version"?: string | undefined;
Charset?: "utf-8" | "utf8" | "utf16le" | "utf-16le" | "latin1" | undefined;
}, {
"Content-Type"?: "text/plain" | "text/html" | "application/pdf" | "image/png" | "image/jpeg" | undefined;
"Content-Transfer-Encoding"?: "7bit" | "8bit" | "binary" | "quoted-printable" | "base64" | undefined;
Subject?: string | undefined;
From?: string | undefined;
To?: string | undefined;
Cc?: string[] | undefined;
Bcc?: string[] | undefined;
Date?: string | undefined;
"In-Reply-To"?: string | undefined;
"MIME-Version"?: string | undefined;
Charset?: "utf-8" | "utf8" | "utf16le" | "utf-16le" | "latin1" | undefined;
}>;
/**
* Schema for validating attachment headers.
* This schema ensures that the attachment headers conform to expected formats.
*/
declare const AttachmentHeaderSchema: z.ZodObject<{
/**
* The content type of the attachment.
* @type {string | undefined}
*/
"Content-Type": z.ZodOptional<z.ZodEnum<["text/plain", "text/html", "application/pdf", "image/png", "image/jpeg"]>>;
/**
* The content transfer encoding of the attachment.
* @type {string | undefined}
*/
"Content-Transfer-Encoding": z.ZodOptional<z.ZodEnum<["7bit", "8bit", "binary", "base64", "quoted-printable"]>>;
/**
* The content disposition of the attachment.
* This must follow the format: "inline", "attachment", or "form-data" with a filename.
* @type {string | undefined}
*/
"Content-Disposition": z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
}, "strip", z.ZodTypeAny, {
"Content-Type"?: "text/plain" | "text/html" | "application/pdf" | "image/png" | "image/jpeg" | undefined;
"Content-Transfer-Encoding"?: "7bit" | "8bit" | "binary" | "quoted-printable" | "base64" | undefined;
"Content-Disposition"?: string | undefined;
}, {
"Content-Type"?: "text/plain" | "text/html" | "application/pdf" | "image/png" | "image/jpeg" | undefined;
"Content-Transfer-Encoding"?: "7bit" | "8bit" | "binary" | "quoted-printable" | "base64" | undefined;
"Content-Disposition"?: string | undefined;
}>;
type ContentTransferEncoding$1 = "7bit" | "8bit" | "binary" | "quoted-printable" | "base64";
declare const ContentTransferEncoding: readonly ["7bit", "8bit", "binary", "base64", "quoted-printable"];
declare const CharsetType: readonly ["utf-8", "utf8", "utf16le", "utf-16le", "latin1"];
declare const MIMETypes: readonly ["text/plain", "text/html", "application/pdf", "image/png", "image/jpeg"];
type ContentDispositionType = `${AttachmentTypeType}; filename="${string}"`;
type AttachmentTypeType = "inline" | "attachment" | "form-data";
type AttachmentContentType = `${TupleUnion<typeof MIMETypes>}; charset="${TupleUnion<typeof CharsetType>}"`;
declare class EmailValidatorClass {
isValidHeaders(headers: HeadersType | undefined): z.SafeParseReturnType<HeadersType, z.infer<typeof HeadersTypeSchema>>;
isValidData(data: string): z.SafeParseReturnType<string, string>;
isValidCharset(charset: string): z.SafeParseReturnType<string, string>;
isValidMimeType(mimeType: string): z.SafeParseReturnType<string, string>;
isValidContentType(contentType: string): z.SafeParseReturnType<string, string>;
isValidContentTransferEncoding(encoding: ContentTransferEncoding$1): z.SafeParseReturnType<ContentTransferEncoding$1, ContentTransferEncoding$1>;
logError(error: z.ZodError): void;
isValidAttachment(attachmentHeader: z.infer<typeof AttachmentHeaderSchema>): z.SafeParseReturnType<z.infer<typeof AttachmentHeaderSchema>, z.infer<typeof AttachmentHeaderSchema>>;
}
/**
* A class for validating email-related data using Zod schemas.
* Provides methods to validate headers, data, charset, MIME type, content type, and content transfer encoding.
*
* @class
* @implements {EmailValidatorClass}
*/
declare class EmailValidator implements EmailValidatorClass {
/**
* Validates email headers using the `HeadersTypeSchema`.
*
* @param {HeadersType | undefined} headers - The headers to be validated. Must conform to the `HeadersType` schema. If `undefined`, the validation result will be based on the provided headers or lack thereof.
* @returns {z.SafeParseReturnType<HeadersType, z.infer<typeof HeadersTypeSchema>>} A Zod safe parse result containing the validation outcome, including data if valid or errors if invalid.
*
* @example
* const headers = {
* "From": "example <example@example.com>",
* "To": "recipient <recipient@example.com>",
* "Subject": "Hello World"
* };
* const result = emailValidator.isValidHeaders(headers);
* if (result.success) {
* console.log("Headers are valid:", result.data);
* } else {
* console.error("Header validation errors:", result.error);
* }
*/
isValidHeaders(headers: HeadersType | undefined): z.SafeParseReturnType<HeadersType, z.infer<typeof HeadersTypeSchema>>;
/**
* Validates a string data using the `StringSchema`.
*
* @param {string} data - The data to be validated. Must be a string conforming to the `StringSchema`.
* @returns {z.SafeParseReturnType<string, string>} A Zod safe parse result containing the validation outcome, which includes the data if valid or errors if invalid.
*
* @example
* const data = "This is a sample string.";
* const result = emailValidator.isValidData(data);
* if (result.success) {
* console.log("Data is valid:", result.data);
* } else {
* console.error("Data validation errors:", result.error);
* }
*/
isValidData(data: string): z.SafeParseReturnType<string, string>;
/**
* Validates a character set using the `StringSchema`.
*
* @param {string} charset - The charset to be validated. Must be a string conforming to the `StringSchema`.
* @returns {z.SafeParseReturnType<string, string>} A Zod safe parse result containing the validation outcome, which includes the charset if valid or errors if invalid.
*
* @example
* const charset = "UTF-8";
* const result = emailValidator.isValidCharset(charset);
* if (result.success) {
* console.log("Charset is valid:", result.data);
* } else {
* console.error("Charset validation errors:", result.error);
* }
*/
isValidCharset(charset: string): z.SafeParseReturnType<string, string>;
/**
* Validates a MIME type using the `StringSchema`.
*
* @param {string} mimeType - The MIME type to be validated. Must be a string conforming to the `StringSchema`.
* @returns {z.SafeParseReturnType<string, string>} A Zod safe parse result containing the validation outcome, which includes the MIME type if valid or errors if invalid.
*
* @example
* const mimeType = "text/plain";
* const result = emailValidator.isValidMimeType(mimeType);
* if (result.success) {
* console.log("MIME type is valid:", result.data);
* } else {
* console.error("MIME type validation errors:", result.error);
* }
*/
isValidMimeType(mimeType: string): z.SafeParseReturnType<string, string>;
/**
* Validates a content type using the `StringSchema`.
*
* @param {string} contentType - The content type to be validated. Must be a string conforming to the `StringSchema`.
* @returns {z.SafeParseReturnType<string, string>} A Zod safe parse result containing the validation outcome, which includes the content type if valid or errors if invalid.
*
* @example
* const contentType = "text/html";
* const result = emailValidator.isValidContentType(contentType);
* if (result.success) {
* console.log("Content type is valid:", result.data);
* } else {
* console.error("Content type validation errors:", result.error);
* }
*/
isValidContentType(contentType: string): z.SafeParseReturnType<string, string>;
/**
* Validates content transfer encoding using the `ContentTransferEncodingSchema`.
*
* @param {ContentTransferEncoding} encoding - The encoding to be validated. Must conform to the `ContentTransferEncodingSchema`.
* @returns {z.SafeParseReturnType<ContentTransferEncoding, ContentTransferEncoding>} A Zod safe parse result containing the validation outcome, which includes the encoding if valid or errors if invalid.
*
* @example
* const encoding = "base64";
* const result = emailValidator.isValidContentTransferEncoding(encoding);
* if (result.success) {
* console.log("Content transfer encoding is valid:", result.data);
* } else {
* console.error("Content transfer encoding validation errors:", result.error);
* }
*/
isValidContentTransferEncoding(encoding: ContentTransferEncoding$1): z.SafeParseReturnType<ContentTransferEncoding$1, ContentTransferEncoding$1>;
/**
* Logs an error by throwing an `EmailError` with the provided Zod error details.
*
* @param {z.ZodError} error - The Zod error to be logged. Contains detailed error information from the Zod validation process.
* @throws {EmailError} Throws an `EmailError` with the error message and description based on the Zod error.
*
* @example
* try {
* const result = emailValidator.isValidData("Invalid data");
* if (!result.success) {
* emailValidator.logError(result.error);
* }
* } catch (e) {
* console.error("An error occurred:", e);
* }
*/
logError(error: z.ZodError): void;
/**
* Validates an attachment header using the `AttachmentHeaderSchema`.
*
* @param {z.infer<typeof AttachmentHeaderSchema>} attachmentHeader - The attachment header to be validated. Must conform to the `AttachmentHeaderSchema`.
* @returns {z.SafeParseReturnType<z.infer<typeof AttachmentHeaderSchema>, z.infer<typeof AttachmentHeaderSchema>>} A Zod safe parse result containing the validation outcome, which includes the attachment header if valid or errors if invalid.
*
* @example
* const attachmentHeader = {
* "Content-Type": "application/pdf",
* "Content-Disposition": "attachment; filename=\"example.pdf\"",
* "Content-Transfer-Encoding": "base64"
* };
* const result = emailValidator.isValidAttachment(attachmentHeader);
* if (result.success) {
* console.log("Attachment header is valid:", result.data);
* } else {
* console.error("Attachment header validation errors:", result.error);
* }
*/
isValidAttachment(attachmentHeader: z.infer<typeof AttachmentHeaderSchema>): z.SafeParseReturnType<z.infer<typeof AttachmentHeaderSchema>, z.infer<typeof AttachmentHeaderSchema>>;
}
declare class EmailBuilderHeaderClass {
headers: HeadersType;
constructor();
getHeaders(): HeadersType;
setFrom(From: ValueType): this;
setTo(To: ValueType): this;
setCc(Cc: ValueType[]): this;
setBcc(Bcc: ValueType[]): this;
setDate(Date: string): this;
setSubject(Subject: string): this;
setInReplyTo(InReplyTo: string): this;
setMIMEVersion(MIMEVersion: string): this;
setContentTransferEncoding(ContentTransferEncoding: ContentTransferEncoding$1): this;
setContentType(ContentType: TupleUnion<MIMEType>): this;
setCharset(Charset: TupleUnion<typeof CharsetType>): this;
}
type EmailTypeString = `<${string}@${string}.${string}>`;
type ValueType = `${string} ${EmailTypeString}`;
type TupleUnion<T extends readonly unknown[]> = T[number];
type HeaderskeyNameType = z.infer<typeof HeadersTypeSchema>;
type HeadernameType = keyof HeaderskeyNameType;
type ExcludedHeadernameType = Exclude<HeadernameType, "From" | "To" | "Cc" | "Bcc" | "Content-Type" | "Content-Transfer-Encoding" | "Content-ID" | "In-Reply-To">;
type HeadersType = {
[key in ExcludedHeadernameType]?: string | undefined;
} & {
From?: ValueType | undefined;
To?: ValueType | undefined;
Cc?: ValueType[] | undefined;
Bcc?: ValueType[] | undefined;
Charset: TupleUnion<typeof CharsetType> | undefined;
"Content-Type": TupleUnion<MIMEType> | undefined;
"Content-Transfer-Encoding"?: ContentTransferEncoding$1 | undefined;
"In-Reply-To": EmailTypeString | undefined;
};
/**
* Class for building and validating email headers.
*
* This class extends the `EmailValidator` class and implements the `EmailBuilderHeaderClass` interface.
* It provides methods to set various email headers and validate them according to email standards.
*
* The class allows you to configure email headers such as "From", "To", "Cc", "Bcc", "Subject", and more.
* It ensures that headers are set correctly and adheres to the email format standards.
*
* @extends {EmailValidator}
* @implements {EmailBuilderHeaderClass}
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader
* .setFrom("sender@example.com")
* .setTo("recipient@example.com")
* .setSubject("Test Email");
*/
declare class EmailBuilderHeader extends EmailValidator implements EmailBuilderHeaderClass {
/**
* Object representing the email headers.
*
* This property holds all the headers associated with the email. It includes fields such as "From", "To", "Subject",
* "Cc", "Bcc", "Date", and other standard email headers. The `HeadersType` defines the structure and types
* for each header field.
*
* @type {HeadersType}
*/
headers: HeadersType;
/**
* Constructs an instance of `EmailBuilderHeader`.
*/
constructor();
/**
* Retrieves the email headers after validating them.
*
* This method validates the current headers stored in the instance using the `isValidHeaders` method.
* If any validation errors are detected, they are logged, but the method still returns the parsed headers.
*
* @returns {HeadersType} The validated and parsed email headers.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.setHeaders({
* From: "sender@example.com",
* To: "recipient@example.com",
* Subject: "Test Email"
* });
* const headers = emailBuilder.getHeaders();
* console.log(headers);
*/
getHeaders(): HeadersType;
/**
* Sets the headers for the email.
*
* This method validates the provided headers using the `isValidHeaders` method.
* If the headers are invalid, it logs the error and still assigns the headers.
*
* @param {HeadersType} headers - The headers object to be set. This should contain key-value pairs representing the email headers.
* @returns {this} The current instance of the EmailBuilder class for method chaining.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.setHeaders({
* "From": "sender@example.com",
* "To": "recipient@example.com",
* "Subject": "Test Email"
* });
*/
setHeaders(headers: HeadersType): this;
/**
* Sets the "From" header of the email.
*
* This method allows you to specify the sender's email address by setting the "From" header.
*
* @param {ValueType} From - The sender's email address, typically in the format `"name@example.com"` or `"Name <name@example.com>"`.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setFrom("sender@example.com");
*/
setFrom(From: ValueType): this;
/**
* Sets the "To" header of the email.
*
* This method specifies the recipient's email address. The "To" header indicates the primary recipient(s) of the email. It can include individual email addresses or multiple addresses separated by commas.
*
* @param {ValueType} To - The recipient's email address or addresses. This should be a string in the format `"name@example.com"` or `"Name <name@example.com>"`, or a comma-separated list of such addresses.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setTo("recipient@example.com");
*
* // For multiple recipients
* emailHeader.setTo("recipient1@example.com, recipient2@example.com");
*/
setTo(To: ValueType): this;
/**
* Sets the "Cc" (Carbon Copy) header of the email.
*
* This method allows you to specify additional recipients who will receive a copy of the email. The email address can be in a simple format or include a name.
*
* @param {ValueType} Cc - The carbon copy recipient's email address. This can be a single email address or multiple addresses separated by commas.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setCc("cc@example.com");
* // or with multiple addresses
* emailHeader.setCc("cc1@example.com, cc2@example.com");
*/
setCc(Cc: ValueType[]): this;
/**
* Sets the "Bcc" (Blind Carbon Copy) header of the email.
*
* This method allows you to specify additional recipients who will receive a blind copy of the email. Their addresses will be hidden from other recipients.
*
* @param {ValueType} Bcc - The blind carbon copy recipient's email address. This can be a single email address or multiple addresses separated by commas.
* @returns {this} The current instance of `EmailBuilderHeader`, enabling method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setBcc("bcc@example.com");
* // or with multiple addresses
* emailHeader.setBcc("bcc1@example.com, bcc2@example.com");
*/
setBcc(Bcc: ValueType[]): this;
/**
* Sets the "Date" header of the email.
*
* This method allows you to specify the date and time when the email is being sent. The date should be in a standard format that is compliant with RFC 5322.
*
* @param {string} Date - The date and time of the email in a string format. Example: `"Tue, 15 Aug 2024 10:00:00 +0000"`.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setDate("Tue, 15 Aug 2024 10:00:00 +0000");
*/
setDate(Date: string): this;
/**
* Sets the "Subject" header of the email.
*
* This method allows you to specify the subject line of the email. The subject should be a concise summary of the email's content.
*
* @param {string} Subject - The subject of the email. Example: `"Meeting Reminder: Project Update"`.
* @returns {this} The current instance of `EmailBuilderHeader`, enabling method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setSubject("Meeting Reminder: Project Update");
*/
setSubject(Subject: string): this;
/**
* Sets the "In-Reply-To" header of the email.
*
* This method specifies the email ID that this email is replying to. The "In-Reply-To" header is used to indicate the message ID of the original message in a reply or thread.
*
* @param {EmailTypeString} InReplyTo - The email ID or message ID that this email is in reply to. This should be a string representing the unique identifier of the original email.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setInReplyTo("<message-id@example.com>");
*/
setInReplyTo(InReplyTo: EmailTypeString): this;
/**
* Sets the "MIME-Version" header of the email.
*
* This method specifies the MIME version used in the email. The "MIME-Version" header indicates the version of the MIME protocol that is being used for the email content.
*
* @param {string} MIMEVersion - The MIME version of the email, typically `"1.0"`. This indicates the version of the MIME protocol used.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setMIMEVersion("1.0");
*/
setMIMEVersion(MIMEVersion: string): this;
/**
* Sets the "Content-Transfer-Encoding" header of the email.
*
* This method specifies the encoding used for the email content. The "Content-Transfer-Encoding" header describes how the email content is encoded for transmission.
*
* @param {ContentTransferEncoding} ContentTransferEncoding - The encoding for the email content, such as `"7bit"`, `"8bit"`, `"base64"`, or `"quoted-printable"`.
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setContentTransferEncoding("base64");
*/
setContentTransferEncoding(ContentTransferEncoding: ContentTransferEncoding$1): this;
/**
* Sets the "Content-Type" header of the email.
*
* This method specifies the MIME type of the email content. The "Content-Type" header indicates the media type and sub-type of the content, such as `"text/plain"` or `"text/html"`.
*
* @param {TupleUnion<MIMEType>} ContentType - The MIME type of the email content. This should be a string representing the type and sub-type of the content (e.g., `"text/html"` or `"multipart/alternative"`).
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setContentType("text/html");
*/
setContentType(ContentType: TupleUnion<MIMEType>): this;
/**
* Sets the "Charset" header of the email.
*
* This method specifies the character set used in the email. The "Charset" header indicates the encoding standard for the email content, such as `"utf-8"` or `"iso-8859-1"`.
*
* @param {TupleUnion<typeof CharsetType>} Charset - The character set used in the email. This should be a string representing the character encoding standard (e.g., `"utf-8"` or `"iso-8859-1"`).
* @returns {this} The current instance of `EmailBuilderHeader`, allowing for method chaining.
*
* @example
* const emailHeader = new EmailBuilderHeader();
* emailHeader.setCharset("utf-8");
*/
setCharset(Charset: TupleUnion<typeof CharsetType>): this;
}
declare class EmailBuilderAttachmentClass {
attachments: AttachmentType[] | undefined;
boundary?: string | undefined;
constructor();
}
type AttachmentHeaderType = Omit<z.infer<typeof AttachmentHeaderSchema>, "Content-Type" | "Content-Disposition"> & {
"Content-Type": AttachmentContentType;
"Content-Disposition": ContentDispositionType;
};
type AttachmentType = {
size: number;
attachmentId: string;
attachmentContent: string;
headers: Required<AttachmentHeaderType>;
filename: string;
mimeType: TupleUnion<MIMEType>;
};
type GetSignatureType = {
from: string | undefined;
url: string | undefined;
name: string | undefined;
};
type MIMEType = typeof MIMETypes;
declare class EmailBuilderClass {
constructor();
getSignature({ from, url, name }: GetSignatureType): string;
setSignature({ name, url, }: NonNullableType<Omit<GetSignatureType, "from">>): this;
}
interface ApplicationSignature {
from: string;
name: string;
url: string;
}
interface EmailType {
id: string;
threadId: string;
labelIds: string[];
snippet: string;
historyId: string;
internalDate: string;
payload: {
partId: string;
mimeType: string;
filename: string;
headers: HeadersType[];
body: {};
parts: EmailType[];
};
sizeEstimate: number;
raw: string;
}
interface SetHeaderType {
name: HeadernameType;
value: ValueType;
}
type AddMessageType = {
data: string;
encoding?: ContentTransferEncoding$1 | undefined;
contentType?: string;
headers?: HeadersType | undefined;
charset?: string | undefined;
attachments?: AttachmentType[] | undefined;
};
interface RawMessage {
Date: string;
From: ValueType | undefined;
To: ValueType | undefined;
inReplyTo: string | undefined;
Cc?: ValueType | undefined;
Bcc?: ValueType | undefined;
Subject: string | undefined;
data: string;
"MIME-Version": string;
"Content-Transfer-Encoding": string | undefined;
"Mime-Type": TupleUnion<MIMEType> | undefined;
}
type NonNullableType<T> = {
[K in keyof T]: NonNullable<T[K]>;
};
interface EmailErrorInterface {
name: string;
description: string;
}
/**
* Custom error class for handling email-related errors.
* This class extends the built-in `Error` class and implements the `EmailErrorInterface`.
* It provides additional details about the error through a `description` property.
*
* @class
* @implements {EmailErrorInterface}
*/
declare class EmailError extends Error implements EmailErrorInterface {
/**
* The name of the error. It is set to the provided message.
*
* @type {string}
*/
name: string;
/**
* A description of the error providing additional context.
* Initialized as an empty string and set via the constructor.
*
* @type {string}
*/
description: string;
/**
* Creates an instance of `EmailError`.
* Initializes the error with a message and a description.
*
* @param {Object} params - The parameters to initialize the error.
* @param {string} params.message - The message describing the error.
* @param {string} params.description - A detailed description of the error.
*/
constructor({ message, description, }: {
message: string;
description: string;
});
}
/**
* `EmailBuilderAttachment` class is responsible for managing email attachments
* and generating the necessary MIME parts for these attachments in an email message.
* It extends the `EmailValidator` class to leverage its validation functionality
* and implements the `EmailBuilderAttachmentClass` interface to ensure proper attachment handling.
*
* @class
* @extends EmailValidator
* @implements EmailBuilderAttachmentClass
*/
declare class EmailBuilderAttachment extends EmailValidator implements EmailBuilderAttachmentClass {
/**
* An optional array of attachments to be included in the email.
* It is initialized as `undefined` and populated when attachments are added.
*
* @type {AttachmentType[] | undefined}
*/
attachments: AttachmentType[] | undefined;
/**
* The boundary string used to separate different parts of a multipart email.
* Default value is `"boundary"`.
*
* @type {string | undefined}
*/
boundary?: string | undefined;
/**
* Initializes a new instance of the `EmailBuilderAttachment` class.
* Calls the constructor of the `EmailValidator` class to initialize inherited properties.
*
* @constructor
* @extends EmailValidator
*/
constructor();
/**
* Adds an attachment to the email.
*
* If there are no existing attachments, this method initializes the `attachments` array.
* It then adds the provided attachment to the array.
*
* @param {AttachmentType} attachment - The attachment to be added to the email. This should conform to the `AttachmentType` schema.
* @returns {this} - The current instance of `EmailBuilder` for method chaining, allowing further configuration of the email.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.addAttachment({
* filename: "document.pdf",
* content: "<base64-encoded-content>",
* headers: {
* "Content-Type": "application/pdf",
* "Content-Transfer-Encoding": "base64"
* }
* });
*/
addAttachment(attachment: AttachmentType): this;
/**
* Generates the MIME parts for all the attachments in the email.
*
* This method constructs and returns an array of strings, each representing a MIME part for an attachment.
* The MIME parts include headers for content type, transfer encoding, and disposition, followed by the attachment content.
* If no attachments are present, the method returns `undefined`.
*
* @returns {string[] | undefined} - An array of MIME part strings for the attachments, or `undefined` if no attachments are present.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.addAttachment({
* filename: "document.pdf",
* content: "<base64-encoded-content>",
* headers: {
* "Content-Type": "application/pdf",
* "Content-Transfer-Encoding": "base64",
* "Content-Disposition": "attachment"
* }
* });
*
* const mimeParts = emailBuilder.getAttachment();
* // mimeParts will be an array of strings representing MIME parts for the attachments
*/
getAttachment(): string[] | undefined;
}
/**
* Class representing an `EmailBuilder`.
*
* This class is used for constructing and validating email headers, as well as generating email messages with optional attachments and signatures.
* It implements the `EmailBuilderClass` interface, providing methods for setting various email headers and constructing raw or encoded email messages.
*
* @implements {EmailBuilderClass}
*/
declare class EmailBuilder implements EmailBuilderClass {
/**
* The body of the email message.
*
* This property holds the content of the email message. It can be a string containing the message body or `null` if no body is set.
*
* @type {string | null}
*/
messagebody: string | null;
/**
* Application signature details.
*
* This property contains the details for the email signature, including the URL and name associated with the application or service.
*
* @type {ApplicationSignature}
*/
applicationSignature: Omit<ApplicationSignature, "from">;
/**
* Creates an instance of the `EmailBuilder` class.
*
* The constructor initializes an instance of `EmailBuilder`, setting up default values for `messagebody` and `applicationSignature`.
*/
constructor();
/**
* Generates the raw email message with headers and optional attachments.
*
* This method constructs the raw email message by combining the provided headers, message body, and any optional
* attachments. It formats the email content as HTML and includes boundary markers for multipart content.
* If the email message body is missing, it returns an `EmailError`.
*
* @param {HeadersType} headers - The headers for the email. This includes fields such as "To", "From", "Subject", etc.
* @param {AttachmentType[]} [attachments] - Optional attachments to include in the email. Each attachment includes
* headers, content type, and content.
* @returns {string | EmailError} The raw email message formatted as a string. If the message body is missing,
* returns an `EmailError` indicating that the message body is required.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.messagebody = "This is the body of the email.";
* const rawMessage = emailBuilder.getRawMessage(
* {
* To: "recipient <recipient@example.com>",
* From: "sender <sender@example.com>",
* Subject: "Test Email",
* "Content-Type": "text/html",
* "Content-Transfer-Encoding": "quoted-printable"
* },
* [
* {
* headers: {
* "Content-Type": "text/plain; charset=\"utf-8\"",
* "Content-Transfer-Encoding": "base64",
* "Content-Disposition": "attachment; filename=\"test.txt\""
* },
* filename: "test.txt",
* attachmentContent: "dGVzdCBjb250ZW50"
* }
* ]
* );
* console.log(rawMessage);
*/
getRawMessage(headers: HeadersType, attachments?: AttachmentType[]): string | EmailError;
/**
* Generates a base64-encoded email message from the provided headers and attachments.
*
* This method first constructs the raw email message using the provided headers and optional attachments.
* If the raw message construction results in an `EmailError`, it returns the error message. Otherwise,
* it encodes the raw message in base64 format and returns the encoded string.
*
* @param {HeadersType} headers - An object representing the email headers. This should include fields such as "To", "From", "Subject", etc.
* @param {AttachmentType[]} [attachments] - Optional. An array of attachments to be included in the email. Each attachment should conform to the `AttachmentType` schema.
* @returns {string} The base64-encoded email message as a string. If an `EmailError` occurred during raw message construction, the method returns the error message.
*
* @example
* const emailBuilder = new EmailBuilder();
* emailBuilder.messagebody = "This is the body of the email.";
* const encodedMessage = emailBuilder.getEncodedMessage(
* {
* To: "recipient <recipient@example.com>",
* From: "sender <sender@example.com>",
* Subject: "Test Email",
* "Content-Type": "text/html",
* "Content-Transfer-Encoding": "quoted-printable"
* },
* [
* {
* headers: {
* "Content-Type": "text/plain; charset=\"utf-8\"",
* "Content-Transfer-Encoding": "base64",
* "Content-Disposition": "attachment; filename=\"test.txt\""
* },
* filename: "test.txt",
* attachmentContent: "dGVzdCBjb250ZW50"
* }
* ]
* );
* console.log(encodedMessage);
*/
getEncodedMessage(headers: HeadersType, attachments?: AttachmentType[]): string;
/**
* Generates the signature block for the email.
*
* This method creates a formatted signature block to be included in the email. The signature contains
* information about the sender and the application used to send the email. It returns the signature block
* as an array of strings, which can be included in the email body.
*
* @param {GetSignatureType} signatureDetails - An object containing the details for the signature. It should include:
* - `from`: The sender's email address.
* - `url`: The URL of the application used to send the email.
* - `name`: The name of the application.
* @returns {string[]} An array of strings representing the formatted signature block.
*
* @example
* const signature = emailBuilder.getSignature({
* from: "sender@example.com",
* url: "https://example.com",
* name: "ExampleApp"
* });
* console.log(signature.join("\n"));
*/
getSignature({ from, url, name }: GetSignatureType): string;
/**
* Sets the signature details for the email.
*
* This method updates the `applicationSignature` property with the provided URL and name.
* The `url` and `name` parameters must be non-nullable and are used to personalize the email signature.
*
* @param {Object} params - The signature details.
* @param {string} params.url - The URL associated with the email signature, such as the website or application URL.
* @param {string} params.name - The name associated with the email signature, such as the name of the application or service.
* @returns {this}
*
* @example
* emailBuilder.setSignature({
* url: "https://example.com",
* name: "ExampleApp"
* });
*/
setSignature({ url, name, }: NonNullableType<Omit<GetSignatureType, "from">>): this;
}
export { type AddMessageType, type ApplicationSignature, type AttachmentContentType, AttachmentHeaderSchema, type AttachmentHeaderType, type AttachmentType, type AttachmentTypeType, Base64, CharsetType, CharsetTypeSchema, type ContentDispositionType, ContentTransferEncoding, ContentTransferEncodingSchema, ContentTypeSchema, EmailBuilder, EmailBuilderAttachment, EmailBuilderAttachmentClass, EmailBuilderClass, EmailBuilderHeader, EmailBuilderHeaderClass, EmailError, type EmailErrorInterface, type EmailType, type EmailTypeString, EmailValidator, EmailValidatorClass, type ExcludedHeadernameType, type GetSignatureType, type HeadernameType, type HeadersType, HeadersTypeSchema, type HeaderskeyNameType, type MIMEType, MIMETypes, type NonNullableType, type RawMessage, type SetHeaderType, StringSchema, type TupleUnion, type ValueType };