@parsrun/email 0.1.30 → 0.1.31

package/dist/index.d.ts

@@ -38,27 +38,64 @@ export { EmailConfig, EmailSendResult, EmailAddress as ParsEmailAddress, EmailAt
 
 /**
  * Email Service
- * High-level email service with provider abstraction
+ *
+ * High-level email service that provides a unified interface for sending emails
+ * through various providers (Resend, SendGrid, Postmark, or Console for development).
+ *
+ * @example
+ * ```typescript
+ * const service = new EmailService({
+ *   provider: 'resend',
+ *   apiKey: 'your-api-key',
+ *   fromEmail: 'hello@example.com',
+ *   fromName: 'My App',
+ * });
+ *
+ * await service.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   html: '<p>Welcome!</p>',
+ * });
+ * ```
  */
 declare class EmailService {
     private provider;
     private debug;
+    /**
+     * Creates a new EmailService instance.
+     *
+     * @param config - The email service configuration including provider type, API key, and default sender info
+     */
     constructor(config: EmailServiceConfig);
     private createProvider;
     /**
-     * Get the provider type
+     * Gets the type of email provider being used.
+     *
+     * @returns The provider type identifier (e.g., 'resend', 'sendgrid', 'postmark', 'console')
      */
     get providerType(): EmailProviderType;
     /**
-     * Send a single email
+     * Sends a single email through the configured provider.
+     *
+     * @param options - The email options including recipient, subject, and content
+     * @returns A promise that resolves to the result of the send operation
+     * @throws {EmailError} If the email send fails due to provider error
      */
     send(options: EmailOptions): Promise<EmailResult>;
     /**
-     * Send multiple emails
+     * Sends multiple emails in a batch.
+     *
+     * If the provider supports native batch sending, it will be used. Otherwise,
+     * emails are sent sequentially.
+     *
+     * @param options - The batch email options including array of emails and error handling config
+     * @returns A promise that resolves to the batch result with success/failure counts
      */
     sendBatch(options: BatchEmailOptions): Promise<BatchEmailResult>;
     /**
-     * Verify provider configuration
+     * Verifies the provider configuration by testing the API connection.
+     *
+     * @returns A promise that resolves to true if the configuration is valid, false otherwise
      */
     verify(): Promise<boolean>;
 }
@@ -91,7 +128,28 @@ declare class EmailService {
  */
 declare function createEmailService(config: EmailServiceConfig): EmailService;
 /**
- * Create an email provider directly
+ * Creates an email provider instance directly.
+ *
+ * Use this when you need direct access to a provider without the EmailService wrapper.
+ *
+ * @param type - The type of email provider to create
+ * @param config - The provider configuration including API key and sender info
+ * @returns A new email provider instance
+ * @throws {EmailError} If an unknown provider type is specified
+ *
+ * @example
+ * ```typescript
+ * const provider = createEmailProvider('resend', {
+ *   apiKey: 'your-api-key',
+ *   fromEmail: 'hello@example.com',
+ * });
+ *
+ * await provider.send({
+ *   to: 'user@example.com',
+ *   subject: 'Hello',
+ *   html: '<p>Hi!</p>',
+ * });
+ * ```
  */
 declare function createEmailProvider(type: EmailProviderType, config: EmailProviderConfig): EmailProvider;
 declare const _default: {

package/dist/index.js

@@ -14,6 +14,13 @@ import {
   emailConfig
 } from "@parsrun/types";
 var EmailError = class extends Error {
+  /**
+   * Creates a new EmailError instance.
+   *
+   * @param message - Human-readable error description
+   * @param code - Error code from EmailErrorCodes for programmatic handling
+   * @param cause - The underlying error that caused this error, if any
+   */
   constructor(message, code, cause) {
     super(message);
     this.code = code;
@@ -34,11 +41,17 @@ var EmailErrorCodes = {
 
 // src/providers/resend.ts
 var ResendProvider = class {
+  /** Provider type identifier */
   type = "resend";
   apiKey;
   fromEmail;
   fromName;
   baseUrl = "https://api.resend.com";
+  /**
+   * Creates a new ResendProvider instance.
+   *
+   * @param config - The provider configuration including API key and sender info
+   */
   constructor(config) {
     this.apiKey = config.apiKey;
     this.fromEmail = config.fromEmail;
@@ -59,6 +72,13 @@ var ResendProvider = class {
     }
     return [this.formatAddress(addresses)];
   }
+  /**
+   * Sends an email via the Resend API.
+   *
+   * @param options - The email options including recipient, subject, and content
+   * @returns A promise that resolves to the send result with message ID if successful
+   * @throws {EmailError} If the Resend API request fails
+   */
   async send(options) {
     const from = options.from ? this.formatAddress(options.from) : this.fromName ? `${this.fromName} <${this.fromEmail}>` : this.fromEmail;
     const payload = {
@@ -111,6 +131,12 @@ var ResendProvider = class {
       );
     }
   }
+  /**
+   * Sends multiple emails via the Resend API sequentially.
+   *
+   * @param options - The batch email options containing emails and error handling config
+   * @returns A promise that resolves to the batch result with success/failure counts
+   */
   async sendBatch(options) {
     const results = [];
     let successful = 0;
@@ -141,6 +167,11 @@ var ResendProvider = class {
       results
     };
   }
+  /**
+   * Verifies the Resend API key by checking configured domains.
+   *
+   * @returns A promise that resolves to true if the API key is valid, false otherwise
+   */
   async verify() {
     try {
       const response = await fetch(`${this.baseUrl}/domains`, {
@@ -153,6 +184,14 @@ var ResendProvider = class {
       return false;
     }
   }
+  /**
+   * Converts a Uint8Array to a base64-encoded string.
+   *
+   * Edge-compatible base64 encoding that works in all JavaScript runtimes.
+   *
+   * @param data - The binary data to encode
+   * @returns The base64-encoded string
+   */
   uint8ArrayToBase64(data) {
     let binary = "";
     for (let i = 0; i < data.length; i++) {
@@ -170,11 +209,17 @@ function createResendProvider(config) {
 
 // src/providers/sendgrid.ts
 var SendGridProvider = class {
+  /** Provider type identifier */
   type = "sendgrid";
   apiKey;
   fromEmail;
   fromName;
   baseUrl = "https://api.sendgrid.com/v3";
+  /**
+   * Creates a new SendGridProvider instance.
+   *
+   * @param config - The provider configuration including API key and sender info
+   */
   constructor(config) {
     this.apiKey = config.apiKey;
     this.fromEmail = config.fromEmail;
@@ -192,6 +237,13 @@ var SendGridProvider = class {
     }
     return [this.formatAddress(addresses)];
   }
+  /**
+   * Sends an email via the SendGrid API.
+   *
+   * @param options - The email options including recipient, subject, and content
+   * @returns A promise that resolves to the send result with message ID if successful
+   * @throws {EmailError} If the SendGrid API request fails
+   */
   async send(options) {
     const from = options.from ? this.formatAddress(options.from) : this.fromName ? { email: this.fromEmail, name: this.fromName } : { email: this.fromEmail };
     const personalization = {
@@ -266,6 +318,15 @@ var SendGridProvider = class {
       );
     }
   }
+  /**
+   * Sends multiple emails via the SendGrid API sequentially.
+   *
+   * Note: SendGrid does not support true batch sending via the standard API,
+   * so emails are sent one at a time.
+   *
+   * @param options - The batch email options containing emails and error handling config
+   * @returns A promise that resolves to the batch result with success/failure counts
+   */
   async sendBatch(options) {
     const results = [];
     let successful = 0;
@@ -296,6 +357,11 @@ var SendGridProvider = class {
       results
     };
   }
+  /**
+   * Verifies the SendGrid API key by checking API scopes.
+   *
+   * @returns A promise that resolves to true if the API key is valid, false otherwise
+   */
   async verify() {
     try {
       const response = await fetch(`${this.baseUrl}/scopes`, {
@@ -308,6 +374,12 @@ var SendGridProvider = class {
       return false;
     }
   }
+  /**
+   * Converts a Uint8Array to a base64-encoded string.
+   *
+   * @param data - The binary data to encode
+   * @returns The base64-encoded string
+   */
   uint8ArrayToBase64(data) {
     let binary = "";
     for (let i = 0; i < data.length; i++) {
@@ -325,11 +397,17 @@ function createSendGridProvider(config) {
 
 // src/providers/postmark.ts
 var PostmarkProvider = class {
+  /** Provider type identifier */
   type = "postmark";
   apiKey;
   fromEmail;
   fromName;
   baseUrl = "https://api.postmarkapp.com";
+  /**
+   * Creates a new PostmarkProvider instance.
+   *
+   * @param config - The provider configuration including API key (server token) and sender info
+   */
   constructor(config) {
     this.apiKey = config.apiKey;
     this.fromEmail = config.fromEmail;
@@ -350,6 +428,13 @@ var PostmarkProvider = class {
     }
     return this.formatAddress(addresses);
   }
+  /**
+   * Sends an email via the Postmark API.
+   *
+   * @param options - The email options including recipient, subject, and content
+   * @returns A promise that resolves to the send result with message ID if successful
+   * @throws {EmailError} If the Postmark API request fails
+   */
   async send(options) {
     const from = options.from ? this.formatAddress(options.from) : this.fromName ? `${this.fromName} <${this.fromEmail}>` : this.fromEmail;
     const payload = {
@@ -411,6 +496,15 @@ var PostmarkProvider = class {
       );
     }
   }
+  /**
+   * Sends multiple emails via Postmark's batch API.
+   *
+   * Postmark supports native batch sending of up to 500 emails in a single request.
+   *
+   * @param options - The batch email options containing emails and error handling config
+   * @returns A promise that resolves to the batch result with success/failure counts
+   * @throws {EmailError} If the Postmark batch API request fails
+   */
   async sendBatch(options) {
     const batchPayload = options.emails.map((email) => {
       const from = email.from ? this.formatAddress(email.from) : this.fromName ? `${this.fromName} <${this.fromEmail}>` : this.fromEmail;
@@ -459,6 +553,11 @@ var PostmarkProvider = class {
       );
     }
   }
+  /**
+   * Verifies the Postmark server token by checking server info.
+   *
+   * @returns A promise that resolves to true if the server token is valid, false otherwise
+   */
   async verify() {
     try {
       const response = await fetch(`${this.baseUrl}/server`, {
@@ -472,6 +571,12 @@ var PostmarkProvider = class {
       return false;
     }
   }
+  /**
+   * Converts a Uint8Array to a base64-encoded string.
+   *
+   * @param data - The binary data to encode
+   * @returns The base64-encoded string
+   */
   uint8ArrayToBase64(data) {
     let binary = "";
     for (let i = 0; i < data.length; i++) {
@@ -489,10 +594,16 @@ function createPostmarkProvider(config) {
 
 // src/providers/console.ts
 var ConsoleProvider = class {
+  /** Provider type identifier */
   type = "console";
   fromEmail;
   fromName;
   messageCounter = 0;
+  /**
+   * Creates a new ConsoleProvider instance.
+   *
+   * @param config - The provider configuration (apiKey is not required for console provider)
+   */
   constructor(config) {
     this.fromEmail = config.fromEmail;
     this.fromName = config.fromName;
@@ -512,6 +623,12 @@ var ConsoleProvider = class {
     }
     return this.formatAddress(addresses);
   }
+  /**
+   * Logs an email to the console instead of sending it.
+   *
+   * @param options - The email options to log
+   * @returns A promise that resolves to a successful result with a generated message ID
+   */
   async send(options) {
     this.messageCounter++;
     const messageId = `console-${Date.now()}-${this.messageCounter}`;
@@ -566,6 +683,12 @@ ${separator}`);
       messageId
     };
   }
+  /**
+   * Logs multiple emails to the console.
+   *
+   * @param options - The batch email options containing emails to log
+   * @returns A promise that resolves to the batch result with success/failure counts
+   */
   async sendBatch(options) {
     const results = [];
     let successful = 0;
@@ -600,6 +723,13 @@ ${separator}`);
       results
     };
   }
+  /**
+   * Verifies the provider configuration.
+   *
+   * For the console provider, this always returns true and logs a message.
+   *
+   * @returns A promise that always resolves to true
+   */
   async verify() {
     console.log("\u{1F4E7} Console email provider verified (always returns true)");
     return true;
@@ -1010,6 +1140,11 @@ var renderFunctions = {
 var EmailService = class {
   provider;
   debug;
+  /**
+   * Creates a new EmailService instance.
+   *
+   * @param config - The email service configuration including provider type, API key, and default sender info
+   */
   constructor(config) {
     this.debug = config.debug ?? false;
     this.provider = this.createProvider(config);
@@ -1038,13 +1173,19 @@ var EmailService = class {
     }
   }
   /**
-   * Get the provider type
+   * Gets the type of email provider being used.
+   *
+   * @returns The provider type identifier (e.g., 'resend', 'sendgrid', 'postmark', 'console')
    */
   get providerType() {
     return this.provider.type;
   }
   /**
-   * Send a single email
+   * Sends a single email through the configured provider.
+   *
+   * @param options - The email options including recipient, subject, and content
+   * @returns A promise that resolves to the result of the send operation
+   * @throws {EmailError} If the email send fails due to provider error
    */
   async send(options) {
     if (this.debug) {
@@ -1061,7 +1202,13 @@ var EmailService = class {
     return result;
   }
   /**
-   * Send multiple emails
+   * Sends multiple emails in a batch.
+   *
+   * If the provider supports native batch sending, it will be used. Otherwise,
+   * emails are sent sequentially.
+   *
+   * @param options - The batch email options including array of emails and error handling config
+   * @returns A promise that resolves to the batch result with success/failure counts
    */
   async sendBatch(options) {
     if (this.debug) {
@@ -1111,7 +1258,9 @@ var EmailService = class {
     };
   }
   /**
-   * Verify provider configuration
+   * Verifies the provider configuration by testing the API connection.
+   *
+   * @returns A promise that resolves to true if the configuration is valid, false otherwise
    */
   async verify() {
     if (this.provider.verify) {