@bernierllc/email-batch-sender 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/

package/README.md

@@ -1,45 +1,83 @@
 # @bernierllc/email-batch-sender
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+Batch email sending with concurrency control, rate limiting, retry strategies, and failure handling. Provides a unified batch API across all email providers, using native provider batch endpoints where available and falling back to sequential sending otherwise.
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+## Installation
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+```bash
+npm install @bernierllc/email-batch-sender
+```
 
-## Purpose
+## Usage
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@bernierllc/email-batch-sender`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+```typescript
+import { createBatchSender } from '@bernierllc/email-batch-sender';
 
-## What is OIDC Trusted Publishing?
+const sender = createBatchSender(emailSenderInstance, {
+  concurrency: 5,
+  rateLimit: { tokensPerInterval: 10, interval: 1000 },
+  retry: { maxRetries: 3, backoffMs: 1000 },
+});
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+const result = await sender.sendBatch([
+  { to: 'alice@example.com', subject: 'Hello', html: '<p>Hi Alice</p>' },
+  { to: 'bob@example.com', subject: 'Hello', html: '<p>Hi Bob</p>' },
+]);
 
-## Setup Instructions
+console.log(`Sent: ${result.succeeded} / ${result.total}`);
+```
 
-To properly configure OIDC trusted publishing for this package:
+## Exports
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+- `BatchSender` -- main class for batch operations
+- `createBatchSender()` -- factory function
+- `TokenBucketRateLimiter` -- rate limiter used internally
+- `BatchSenderError` -- custom error class with error codes
+- Types: `BatchSenderOptions`, `RateLimitOptions`, `BatchRetryOptions`, `BatchResult`, `BatchEmailResult`, `BatchProgress`, `BatchEmailInput`
 
-## DO NOT USE THIS PACKAGE
+## Provider Capability Support
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+This section documents how batch sending behaves across email providers, based on the canonical `CAPABILITY_MATRIX` in `@bernierllc/email-manager`.
 
-## More Information
+### Capability Levels by Provider
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+| Provider | Capability Level | Notes |
+|----------|-----------------|-------|
+| SendGrid | **provider** | Native batch API via personalizations; the provider handles batching server-side |
+| Mailgun | **provider** | Native batch send via recipient variables |
+| Postmark | **provider** | Native batch API endpoint (`/email/batch`) |
+| SES | **provider** | Native `SendBulkEmail` API |
+| SMTP | **platform** | No native batch support; this package sends emails sequentially over the SMTP connection |
 
----
+### How It Works
 
-**Maintained for OIDC setup purposes only**
+- **Provider-level** (SendGrid, Mailgun, Postmark, SES): The email manager delegates to the provider's native batch endpoint. This package orchestrates the calls, handles rate limiting, and manages retries. The provider may process the batch as a single API call (SendGrid personalizations, Postmark batch endpoint) or as optimized bulk operations (SES `SendBulkEmail`).
+
+- **Platform-level** (SMTP): Since SMTP has no native batch support, this package sends emails sequentially over the SMTP connection. Concurrency, rate limiting, and retry logic are all handled at the platform level by this package.
+
+### Degradation Behavior
+
+When used with a provider that lacks native batch support (currently only SMTP):
+
+- **Strategy**: `sequential-batch`
+- **Behavior**: Emails are sent one at a time over the SMTP connection, respecting the configured concurrency limit and rate limiter
+- **Performance**: Slower than native batch APIs; throughput depends on SMTP server response times and the configured concurrency/rate-limit settings
+- **Reliability**: Full retry support with configurable backoff; individual message failures do not block the rest of the batch
+
+### Override Options
+
+The batch send capability is marked `overridable: true` for all providers with native support, meaning you can force platform-level sequential sending even when a native batch API is available. This can be useful for debugging or when provider batch endpoints have temporary issues.
+
+```typescript
+// Force sequential sending regardless of provider
+const sender = createBatchSender(emailSenderInstance, {
+  forceSequential: true,
+  concurrency: 3,
+});
+```
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.
+
+This package is licensed to the client under a limited-use license. The client may use and modify this code only within the scope of the project it was delivered for. Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.

package/dist/batch-sender.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Batch email sender with concurrency control, rate limiting, and failure strategies
+ */
+import { BatchSenderOptions, BatchResult, BatchEmailInput } from './types';
+/**
+ * Interface for the underlying email sender.
+ * Matches the shape of @bernierllc/email-sender's EmailSender.sendEmail() return type.
+ */
+export interface EmailSenderInterface {
+    send(message: {
+        toEmail: string;
+        toName?: string;
+        subject: string;
+        htmlContent?: string;
+        textContent?: string;
+        headers?: Record<string, string>;
+        attachments?: readonly {
+            filename: string;
+            content: string;
+            contentType?: string;
+        }[];
+        metadata?: Record<string, unknown>;
+    }): Promise<{
+        success: boolean;
+        messageId?: string;
+        errorMessage?: string;
+        provider?: string;
+    }>;
+}
+export declare class BatchSender {
+    private readonly sender;
+    private readonly options;
+    private aborted;
+    private readonly concurrency;
+    private readonly maxRetries;
+    private readonly backoffMs;
+    private readonly backoffMultiplier;
+    private readonly rateLimiter;
+    constructor(sender: EmailSenderInterface, options?: BatchSenderOptions);
+    /**
+     * Send a batch of emails with concurrency control, rate limiting, and retry.
+     */
+    send(emails: readonly BatchEmailInput[]): Promise<BatchResult>;
+    /**
+     * Abort the current batch send. In-flight emails will finish, remaining will be skipped.
+     */
+    abort(): void;
+    private sendWithRetry;
+    private buildSuccessResult;
+    private shouldAbortOnThreshold;
+    private emitProgress;
+    private validateEmails;
+    private sleep;
+}
+/**
+ * Factory function to create a BatchSender instance.
+ */
+export declare function createBatchSender(sender: EmailSenderInterface, options?: BatchSenderOptions): BatchSender;
+//# sourceMappingURL=batch-sender.d.ts.map

package/dist/batch-sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-sender.d.ts","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,OAAO,EACL,kBAAkB,EAClB,WAAW,EAGX,eAAe,EAChB,MAAM,SAAS,CAAC;AAIjB;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,OAAO,EAAE;QACZ,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,WAAW,CAAC,EAAE,SAAS;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,WAAW,CAAC,EAAE,MAAM,CAAA;SAAE,EAAE,CAAC;QACrF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACpC,GAAG,OAAO,CAAC;QACV,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC,CAAC;CACJ;AAOD,qBAAa,WAAW;IASpB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAT1B,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqC;gBAG9C,MAAM,EAAE,oBAAoB,EAC5B,OAAO,GAAE,kBAAuB;IAgDnD;;OAEG;IACG,IAAI,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAoHpE;;OAEG;IACH,KAAK,IAAI,IAAI;YAIC,aAAa;IA2E3B,OAAO,CAAC,kBAAkB;IAmB1B,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,YAAY;IAyBpB,OAAO,CAAC,cAAc;IA8BtB,OAAO,CAAC,KAAK;CAGd;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,OAAO,CAAC,EAAE,kBAAkB,GAC3B,WAAW,CAEb"}

package/dist/batch-sender.js

@@ -0,0 +1,293 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchSender = void 0;
+exports.createBatchSender = createBatchSender;
+const errors_1 = require("./errors");
+const rate_limiter_1 = require("./rate-limiter");
+const DEFAULT_CONCURRENCY = 5;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_BACKOFF_MS = 1000;
+const DEFAULT_BACKOFF_MULTIPLIER = 2;
+class BatchSender {
+    constructor(sender, options = {}) {
+        this.sender = sender;
+        this.options = options;
+        this.aborted = false;
+        this.concurrency = options.concurrency ?? DEFAULT_CONCURRENCY;
+        this.maxRetries = options.retryOptions?.maxRetries ?? DEFAULT_MAX_RETRIES;
+        this.backoffMs = options.retryOptions?.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.backoffMultiplier =
+            options.retryOptions?.backoffMultiplier ?? DEFAULT_BACKOFF_MULTIPLIER;
+        if (options.rateLimit) {
+            this.rateLimiter = new rate_limiter_1.TokenBucketRateLimiter(options.rateLimit);
+        }
+        if (this.concurrency < 1) {
+            throw new errors_1.BatchSenderError('Concurrency must be at least 1', {
+                code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                context: { concurrency: this.concurrency },
+            });
+        }
+        if (options.failureStrategy === 'abort-on-threshold' &&
+            (options.failureThreshold === undefined ||
+                options.failureThreshold === null)) {
+            throw new errors_1.BatchSenderError('failureThreshold is required when using abort-on-threshold strategy', {
+                code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                context: { failureStrategy: options.failureStrategy },
+            });
+        }
+        if (options.failureThreshold !== undefined &&
+            options.failureThreshold !== null &&
+            (options.failureThreshold < 0 || options.failureThreshold > 100)) {
+            throw new errors_1.BatchSenderError('failureThreshold must be between 0 and 100', {
+                code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                context: { failureThreshold: options.failureThreshold },
+            });
+        }
+    }
+    /**
+     * Send a batch of emails with concurrency control, rate limiting, and retry.
+     */
+    async send(emails) {
+        if (emails.length === 0) {
+            return {
+                total: 0,
+                succeeded: 0,
+                failed: 0,
+                results: [],
+                duration: 0,
+                aborted: false,
+            };
+        }
+        this.validateEmails(emails);
+        this.aborted = false;
+        const startTime = Date.now();
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        let aborted = false;
+        // Promise pool pattern for concurrency control
+        const queue = [...emails];
+        let queueIndex = 0;
+        const activePromises = [];
+        const processNext = async () => {
+            while (queueIndex < queue.length) {
+                if (this.aborted) {
+                    break;
+                }
+                // Check threshold abort
+                if (this.shouldAbortOnThreshold(failed, results.length, emails.length)) {
+                    this.aborted = true;
+                    break;
+                }
+                const currentIndex = queueIndex;
+                queueIndex++;
+                const email = queue[currentIndex];
+                if (!email) {
+                    break;
+                }
+                // Rate limiting
+                if (this.rateLimiter) {
+                    await this.rateLimiter.acquire();
+                }
+                if (this.aborted) {
+                    break;
+                }
+                const result = await this.sendWithRetry(email);
+                results.push(result);
+                if (result.success) {
+                    succeeded++;
+                }
+                else {
+                    failed++;
+                    // Check abort-on-first
+                    if (this.options.failureStrategy === 'abort-on-first') {
+                        this.aborted = true;
+                    }
+                    // Check abort-on-threshold after each failure
+                    if (this.shouldAbortOnThreshold(failed, results.length, emails.length)) {
+                        this.aborted = true;
+                    }
+                }
+                this.emitProgress(emails.length, results.length, succeeded, failed, startTime);
+            }
+        };
+        // Launch workers up to concurrency limit
+        const workerCount = Math.min(this.concurrency, emails.length);
+        for (let i = 0; i < workerCount; i++) {
+            activePromises.push(processNext());
+        }
+        await Promise.all(activePromises);
+        aborted = this.aborted;
+        // Mark remaining emails as skipped if aborted
+        if (aborted) {
+            for (let i = results.length; i < emails.length; i++) {
+                const email = emails[i];
+                if (email) {
+                    results.push({
+                        recipient: email.toEmail,
+                        success: false,
+                        error: 'Batch aborted',
+                        attempts: 0,
+                    });
+                    failed++;
+                }
+            }
+        }
+        const duration = Date.now() - startTime;
+        return {
+            total: emails.length,
+            succeeded,
+            failed,
+            results,
+            duration,
+            aborted,
+        };
+    }
+    /**
+     * Abort the current batch send. In-flight emails will finish, remaining will be skipped.
+     */
+    abort() {
+        this.aborted = true;
+    }
+    async sendWithRetry(email) {
+        let lastError;
+        let attempts = 0;
+        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+            attempts = attempt + 1;
+            if (this.aborted && attempt > 0) {
+                return {
+                    recipient: email.toEmail,
+                    success: false,
+                    error: 'Batch aborted during retry',
+                    attempts,
+                };
+            }
+            try {
+                const sendMessage = {
+                    toEmail: email.toEmail,
+                    subject: email.subject,
+                };
+                if (email.toName !== undefined) {
+                    sendMessage.toName = email.toName;
+                }
+                if (email.htmlContent !== undefined) {
+                    sendMessage.htmlContent = email.htmlContent;
+                }
+                if (email.textContent !== undefined) {
+                    sendMessage.textContent = email.textContent;
+                }
+                if (email.headers !== undefined) {
+                    sendMessage.headers = email.headers;
+                }
+                if (email.attachments !== undefined) {
+                    sendMessage.attachments = email.attachments;
+                }
+                if (email.metadata !== undefined) {
+                    sendMessage.metadata = email.metadata;
+                }
+                const result = await this.sender.send(sendMessage);
+                if (result.success) {
+                    return this.buildSuccessResult(email.toEmail, attempts, result.messageId, result.provider);
+                }
+                lastError = result.errorMessage ?? 'Send failed without error message';
+            }
+            catch (error) {
+                lastError =
+                    error instanceof Error ? error.message : 'Unknown send error';
+            }
+            // Wait before retry (skip wait on last attempt)
+            if (attempt < this.maxRetries) {
+                const delay = this.backoffMs * Math.pow(this.backoffMultiplier, attempt);
+                await this.sleep(delay);
+            }
+        }
+        const failResult = {
+            recipient: email.toEmail,
+            success: false,
+            attempts,
+        };
+        if (lastError !== undefined) {
+            return { ...failResult, error: lastError };
+        }
+        return failResult;
+    }
+    buildSuccessResult(recipient, attempts, messageId, provider) {
+        const base = { recipient, success: true, attempts };
+        if (messageId !== undefined && provider !== undefined) {
+            return { ...base, messageId, provider };
+        }
+        if (messageId !== undefined) {
+            return { ...base, messageId };
+        }
+        if (provider !== undefined) {
+            return { ...base, provider };
+        }
+        return base;
+    }
+    shouldAbortOnThreshold(failedCount, completedCount, _totalCount) {
+        if (this.options.failureStrategy !== 'abort-on-threshold') {
+            return false;
+        }
+        if (completedCount === 0) {
+            return false;
+        }
+        const failurePercentage = (failedCount / completedCount) * 100;
+        return failurePercentage >= (this.options.failureThreshold ?? 100);
+    }
+    emitProgress(total, completed, succeededCount, failedCount, startTime) {
+        if (!this.options.onProgress) {
+            return;
+        }
+        const elapsed = (Date.now() - startTime) / 1000;
+        const currentRate = elapsed > 0 ? completed / elapsed : 0;
+        const progress = {
+            total,
+            completed,
+            succeeded: succeededCount,
+            failed: failedCount,
+            currentRate,
+        };
+        this.options.onProgress(progress);
+    }
+    validateEmails(emails) {
+        for (let i = 0; i < emails.length; i++) {
+            const email = emails[i];
+            if (!email) {
+                throw new errors_1.BatchSenderError(`Email at index ${i} is undefined`, {
+                    code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                    context: { index: i },
+                });
+            }
+            if (!email.toEmail) {
+                throw new errors_1.BatchSenderError(`Email at index ${i} is missing required field: toEmail`, {
+                    code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                    context: { index: i },
+                });
+            }
+            if (!email.subject) {
+                throw new errors_1.BatchSenderError(`Email at index ${i} is missing required field: subject`, {
+                    code: errors_1.BatchSenderErrorCode.INVALID_INPUT,
+                    context: { index: i },
+                });
+            }
+        }
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.BatchSender = BatchSender;
+/**
+ * Factory function to create a BatchSender instance.
+ */
+function createBatchSender(sender, options) {
+    return new BatchSender(sender, options);
+}
+//# sourceMappingURL=batch-sender.js.map

package/dist/batch-sender.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-sender.js","sourceRoot":"","sources":["../src/batch-sender.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAiZF,8CAKC;AAzYD,qCAAkE;AAClE,iDAAwD;AAwBxD,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,mBAAmB,GAAG,CAAC,CAAC;AAC9B,MAAM,kBAAkB,GAAG,IAAI,CAAC;AAChC,MAAM,0BAA0B,GAAG,CAAC,CAAC;AAErC,MAAa,WAAW;IAQtB,YACmB,MAA4B,EAC5B,UAA8B,EAAE;QADhC,WAAM,GAAN,MAAM,CAAsB;QAC5B,YAAO,GAAP,OAAO,CAAyB;QAT3C,YAAO,GAAG,KAAK,CAAC;QAWtB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,mBAAmB,CAAC;QAC9D,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,YAAY,EAAE,UAAU,IAAI,mBAAmB,CAAC;QAC1E,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,YAAY,EAAE,SAAS,IAAI,kBAAkB,CAAC;QACvE,IAAI,CAAC,iBAAiB;YACpB,OAAO,CAAC,YAAY,EAAE,iBAAiB,IAAI,0BAA0B,CAAC;QAExE,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;YACtB,IAAI,CAAC,WAAW,GAAG,IAAI,qCAAsB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACnE,CAAC;QAED,IAAI,IAAI,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,yBAAgB,CAAC,gCAAgC,EAAE;gBAC3D,IAAI,EAAE,6BAAoB,CAAC,aAAa;gBACxC,OAAO,EAAE,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE;aAC3C,CAAC,CAAC;QACL,CAAC;QAED,IACE,OAAO,CAAC,eAAe,KAAK,oBAAoB;YAChD,CAAC,OAAO,CAAC,gBAAgB,KAAK,SAAS;gBACrC,OAAO,CAAC,gBAAgB,KAAK,IAAI,CAAC,EACpC,CAAC;YACD,MAAM,IAAI,yBAAgB,CACxB,qEAAqE,EACrE;gBACE,IAAI,EAAE,6BAAoB,CAAC,aAAa;gBACxC,OAAO,EAAE,EAAE,eAAe,EAAE,OAAO,CAAC,eAAe,EAAE;aACtD,CACF,CAAC;QACJ,CAAC;QAED,IACE,OAAO,CAAC,gBAAgB,KAAK,SAAS;YACtC,OAAO,CAAC,gBAAgB,KAAK,IAAI;YACjC,CAAC,OAAO,CAAC,gBAAgB,GAAG,CAAC,IAAI,OAAO,CAAC,gBAAgB,GAAG,GAAG,CAAC,EAChE,CAAC;YACD,MAAM,IAAI,yBAAgB,CACxB,4CAA4C,EAC5C;gBACE,IAAI,EAAE,6BAAoB,CAAC,aAAa;gBACxC,OAAO,EAAE,EAAE,gBAAgB,EAAE,OAAO,CAAC,gBAAgB,EAAE;aACxD,CACF,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,MAAkC;QAC3C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO;gBACL,KAAK,EAAE,CAAC;gBACR,SAAS,EAAE,CAAC;gBACZ,MAAM,EAAE,CAAC;gBACT,OAAO,EAAE,EAAE;gBACX,QAAQ,EAAE,CAAC;gBACX,OAAO,EAAE,KAAK;aACf,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;QAC5B,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QAErB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAuB,EAAE,CAAC;QACvC,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,IAAI,MAAM,GAAG,CAAC,CAAC;QACf,IAAI,OAAO,GAAG,KAAK,CAAC;QAEpB,+CAA+C;QAC/C,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;QAC1B,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,MAAM,cAAc,GAAoB,EAAE,CAAC;QAE3C,MAAM,WAAW,GAAG,KAAK,IAAmB,EAAE;YAC5C,OAAO,UAAU,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;gBACjC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACjB,MAAM;gBACR,CAAC;gBAED,wBAAwB;gBACxB,IAAI,IAAI,CAAC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;oBACvE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;oBACpB,MAAM;gBACR,CAAC;gBAED,MAAM,YAAY,GAAG,UAAU,CAAC;gBAChC,UAAU,EAAE,CAAC;gBACb,MAAM,KAAK,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;gBAElC,IAAI,CAAC,KAAK,EAAE,CAAC;oBACX,MAAM;gBACR,CAAC;gBAED,gBAAgB;gBAChB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;oBACrB,MAAM,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACnC,CAAC;gBAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;oBACjB,MAAM;gBACR,CAAC;gBAED,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;gBAC/C,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAErB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBACnB,SAAS,EAAE,CAAC;gBACd,CAAC;qBAAM,CAAC;oBACN,MAAM,EAAE,CAAC;oBAET,uBAAuB;oBACvB,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,KAAK,gBAAgB,EAAE,CAAC;wBACtD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;oBACtB,CAAC;oBAED,8CAA8C;oBAC9C,IAAI,IAAI,CAAC,sBAAsB,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;wBACvE,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;oBACtB,CAAC;gBACH,CAAC;gBAED,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;YACjF,CAAC;QACH,CAAC,CAAC;QAEF,yCAAyC;QACzC,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QAC9D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;YACrC,cAAc,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;QACrC,CAAC;QAED,MAAM,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;QAElC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAEvB,8CAA8C;QAC9C,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACpD,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;gBACxB,IAAI,KAAK,EAAE,CAAC;oBACV,OAAO,CAAC,IAAI,CAAC;wBACX,SAAS,EAAE,KAAK,CAAC,OAAO;wBACxB,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,eAAe;wBACtB,QAAQ,EAAE,CAAC;qBACZ,CAAC,CAAC;oBACH,MAAM,EAAE,CAAC;gBACX,CAAC;YACH,CAAC;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;QAExC,OAAO;YACL,KAAK,EAAE,MAAM,CAAC,MAAM;YACpB,SAAS;YACT,MAAM;YACN,OAAO;YACP,QAAQ;YACR,OAAO;SACR,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;IAEO,KAAK,CAAC,aAAa,CAAC,KAAsB;QAChD,IAAI,SAA6B,CAAC;QAClC,IAAI,QAAQ,GAAG,CAAC,CAAC;QAEjB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;YAC5D,QAAQ,GAAG,OAAO,GAAG,CAAC,CAAC;YAEvB,IAAI,IAAI,CAAC,OAAO,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;gBAChC,OAAO;oBACL,SAAS,EAAE,KAAK,CAAC,OAAO;oBACxB,OAAO,EAAE,KAAK;oBACd,KAAK,EAAE,4BAA4B;oBACnC,QAAQ;iBACT,CAAC;YACJ,CAAC;YAED,IAAI,CAAC;gBACH,MAAM,WAAW,GASb;oBACF,OAAO,EAAE,KAAK,CAAC,OAAO;oBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;iBACvB,CAAC;gBAEF,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;gBAAC,CAAC;gBACtE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;gBAAC,CAAC;gBACrF,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;gBAAC,CAAC;gBACrF,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;gBAAC,CAAC;gBACzE,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;gBAAC,CAAC;gBACrF,IAAI,KAAK,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;oBAAC,WAAW,CAAC,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;gBAAC,CAAC;gBAE5E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAEnD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;oBACnB,OAAO,IAAI,CAAC,kBAAkB,CAC5B,KAAK,CAAC,OAAO,EACb,QAAQ,EACR,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,QAAQ,CAChB,CAAC;gBACJ,CAAC;gBAED,SAAS,GAAG,MAAM,CAAC,YAAY,IAAI,mCAAmC,CAAC;YACzE,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,SAAS;oBACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,oBAAoB,CAAC;YAClE,CAAC;YAED,gDAAgD;YAChD,IAAI,OAAO,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;gBAC9B,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAAC,CAAC;gBACzE,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,MAAM,UAAU,GAAqB;YACnC,SAAS,EAAE,KAAK,CAAC,OAAO;YACxB,OAAO,EAAE,KAAK;YACd,QAAQ;SACT,CAAC;QAEF,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,EAAE,GAAG,UAAU,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAC7C,CAAC;QAED,OAAO,UAAU,CAAC;IACpB,CAAC;IAEO,kBAAkB,CACxB,SAAiB,EACjB,QAAgB,EAChB,SAA6B,EAC7B,QAA4B;QAE5B,MAAM,IAAI,GAAqB,EAAE,SAAS,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACtE,IAAI,SAAS,KAAK,SAAS,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YACtD,OAAO,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC;QAC1C,CAAC;QACD,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;YAC5B,OAAO,EAAE,GAAG,IAAI,EAAE,SAAS,EAAE,CAAC;QAChC,CAAC;QACD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC/B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,sBAAsB,CAC5B,WAAmB,EACnB,cAAsB,EACtB,WAAmB;QAEnB,IAAI,IAAI,CAAC,OAAO,CAAC,eAAe,KAAK,oBAAoB,EAAE,CAAC;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,cAAc,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO,KAAK,CAAC;QACf,CAAC;QAED,MAAM,iBAAiB,GAAG,CAAC,WAAW,GAAG,cAAc,CAAC,GAAG,GAAG,CAAC;QAC/D,OAAO,iBAAiB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,IAAI,GAAG,CAAC,CAAC;IACrE,CAAC;IAEO,YAAY,CAClB,KAAa,EACb,SAAiB,EACjB,cAAsB,EACtB,WAAmB,EACnB,SAAiB;QAEjB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC;YAC7B,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC,GAAG,IAAI,CAAC;QAChD,MAAM,WAAW,GAAG,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;QAE1D,MAAM,QAAQ,GAAkB;YAC9B,KAAK;YACL,SAAS;YACT,SAAS,EAAE,cAAc;YACzB,MAAM,EAAE,WAAW;YACnB,WAAW;SACZ,CAAC;QAEF,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;IACpC,CAAC;IAEO,cAAc,CAAC,MAAkC;QACvD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YACxB,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,yBAAgB,CAAC,kBAAkB,CAAC,eAAe,EAAE;oBAC7D,IAAI,EAAE,6BAAoB,CAAC,aAAa;oBACxC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;iBACtB,CAAC,CAAC;YACL,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,IAAI,yBAAgB,CACxB,kBAAkB,CAAC,qCAAqC,EACxD;oBACE,IAAI,EAAE,6BAAoB,CAAC,aAAa;oBACxC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;iBACtB,CACF,CAAC;YACJ,CAAC;YACD,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBACnB,MAAM,IAAI,yBAAgB,CACxB,kBAAkB,CAAC,qCAAqC,EACxD;oBACE,IAAI,EAAE,6BAAoB,CAAC,aAAa;oBACxC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE;iBACtB,CACF,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,EAAU;QACtB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;CACF;AAjWD,kCAiWC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAC/B,MAA4B,EAC5B,OAA4B;IAE5B,OAAO,IAAI,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAC1C,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Batch sender error classes with ES2022 Error.cause support
+ */
+export declare const BatchSenderErrorCode: {
+    readonly INVALID_INPUT: "INVALID_INPUT";
+    readonly RATE_LIMIT_EXCEEDED: "RATE_LIMIT_EXCEEDED";
+    readonly BATCH_ABORTED: "BATCH_ABORTED";
+    readonly SEND_FAILED: "SEND_FAILED";
+};
+export type BatchSenderErrorCodeType = (typeof BatchSenderErrorCode)[keyof typeof BatchSenderErrorCode];
+export interface BatchSenderErrorOptions {
+    cause?: Error;
+    code?: BatchSenderErrorCodeType;
+    context?: Record<string, unknown>;
+}
+export declare class BatchSenderError extends Error {
+    readonly code: BatchSenderErrorCodeType;
+    readonly context: Record<string, unknown> | undefined;
+    constructor(message: string, options?: BatchSenderErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,eAAO,MAAM,oBAAoB;;;;;CAKvB,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEnE,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,wBAAwB,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;gBAE1C,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,uBAAuB;CAY/D"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BatchSenderError = exports.BatchSenderErrorCode = void 0;
+/**
+ * Batch sender error classes with ES2022 Error.cause support
+ */
+exports.BatchSenderErrorCode = {
+    INVALID_INPUT: 'INVALID_INPUT',
+    RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+    BATCH_ABORTED: 'BATCH_ABORTED',
+    SEND_FAILED: 'SEND_FAILED',
+};
+class BatchSenderError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'BatchSenderError';
+        this.code = options?.code ?? exports.BatchSenderErrorCode.SEND_FAILED;
+        this.context = options?.context;
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        Error.captureStackTrace?.(this, this.constructor);
+    }
+}
+exports.BatchSenderError = BatchSenderError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAEF;;GAEG;AAEU,QAAA,oBAAoB,GAAG;IAClC,aAAa,EAAE,eAAe;IAC9B,mBAAmB,EAAE,qBAAqB;IAC1C,aAAa,EAAE,eAAe;IAC9B,WAAW,EAAE,aAAa;CAClB,CAAC;AAWX,MAAa,gBAAiB,SAAQ,KAAK;IAIzC,YAAY,OAAe,EAAE,OAAiC;QAC5D,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,IAAI,4BAAoB,CAAC,WAAW,CAAC;QAC9D,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QAEhC,IAAI,OAAO,EAAE,KAAK,EAAE,CAAC;YAClB,IAAoC,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QAC9D,CAAC;QAED,KAAK,CAAC,iBAAiB,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;IACpD,CAAC;CACF;AAhBD,4CAgBC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { BatchSenderOptions, RateLimitOptions, BatchRetryOptions, BatchResult, BatchEmailResult, BatchProgress, BatchEmailInput, } from './types';
+export { BatchSenderError, BatchSenderErrorCode, BatchSenderErrorCodeType, BatchSenderErrorOptions, } from './errors';
+export { TokenBucketRateLimiter } from './rate-limiter';
+export { BatchSender, EmailSenderInterface, createBatchSender, } from './batch-sender';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,gBAAgB,EAChB,oBAAoB,EACpB,wBAAwB,EACxB,uBAAuB,GACxB,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD,OAAO,EACL,WAAW,EACX,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createBatchSender = exports.BatchSender = exports.TokenBucketRateLimiter = exports.BatchSenderErrorCode = exports.BatchSenderError = void 0;
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "BatchSenderError", { enumerable: true, get: function () { return errors_1.BatchSenderError; } });
+Object.defineProperty(exports, "BatchSenderErrorCode", { enumerable: true, get: function () { return errors_1.BatchSenderErrorCode; } });
+var rate_limiter_1 = require("./rate-limiter");
+Object.defineProperty(exports, "TokenBucketRateLimiter", { enumerable: true, get: function () { return rate_limiter_1.TokenBucketRateLimiter; } });
+var batch_sender_1 = require("./batch-sender");
+Object.defineProperty(exports, "BatchSender", { enumerable: true, get: function () { return batch_sender_1.BatchSender; } });
+Object.defineProperty(exports, "createBatchSender", { enumerable: true, get: function () { return batch_sender_1.createBatchSender; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;EAME;;;AAYF,mCAKkB;AAJhB,0GAAA,gBAAgB,OAAA;AAChB,8GAAA,oBAAoB,OAAA;AAKtB,+CAAwD;AAA/C,sHAAA,sBAAsB,OAAA;AAE/B,+CAIwB;AAHtB,2GAAA,WAAW,OAAA;AAEX,iHAAA,iBAAiB,OAAA"}

package/dist/rate-limiter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Token bucket rate limiter for controlling email send rates
+ */
+import { RateLimitOptions } from './types';
+export declare class TokenBucketRateLimiter {
+    private readonly maxPerSecond;
+    private readonly maxPerMinute;
+    private secondTokens;
+    private minuteTokens;
+    private lastSecondRefill;
+    private lastMinuteRefill;
+    constructor(options: RateLimitOptions);
+    /**
+     * Acquire a token, waiting if necessary until one is available.
+     */
+    acquire(): Promise<void>;
+    private refill;
+    private calculateWaitTime;
+    private sleep;
+}
+//# sourceMappingURL=rate-limiter.d.ts.map

package/dist/rate-limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAE3C,qBAAa,sBAAsB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,gBAAgB,CAAS;gBAErB,OAAO,EAAE,gBAAgB;IASrC;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgB9B,OAAO,CAAC,MAAM;IA0Bd,OAAO,CAAC,iBAAiB;IAgBzB,OAAO,CAAC,KAAK;CAGd"}

package/dist/rate-limiter.js

@@ -0,0 +1,71 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBucketRateLimiter = void 0;
+class TokenBucketRateLimiter {
+    constructor(options) {
+        this.maxPerSecond = options.maxPerSecond ?? Infinity;
+        this.maxPerMinute = options.maxPerMinute ?? Infinity;
+        this.secondTokens = this.maxPerSecond;
+        this.minuteTokens = this.maxPerMinute;
+        this.lastSecondRefill = Date.now();
+        this.lastMinuteRefill = Date.now();
+    }
+    /**
+     * Acquire a token, waiting if necessary until one is available.
+     */
+    async acquire() {
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            this.refill();
+            if (this.secondTokens >= 1 && this.minuteTokens >= 1) {
+                this.secondTokens -= 1;
+                this.minuteTokens -= 1;
+                return;
+            }
+            const waitMs = this.calculateWaitTime();
+            await this.sleep(waitMs);
+        }
+    }
+    refill() {
+        const now = Date.now();
+        // Refill second bucket
+        const secondsElapsed = (now - this.lastSecondRefill) / 1000;
+        if (secondsElapsed >= 1) {
+            const tokensToAdd = Math.floor(secondsElapsed) * this.maxPerSecond;
+            this.secondTokens = Math.min(this.maxPerSecond, this.secondTokens + tokensToAdd);
+            this.lastSecondRefill = now - ((secondsElapsed % 1) * 1000);
+        }
+        // Refill minute bucket
+        const minutesElapsed = (now - this.lastMinuteRefill) / 60000;
+        if (minutesElapsed >= 1) {
+            const tokensToAdd = Math.floor(minutesElapsed) * this.maxPerMinute;
+            this.minuteTokens = Math.min(this.maxPerMinute, this.minuteTokens + tokensToAdd);
+            this.lastMinuteRefill = now - ((minutesElapsed % 1) * 60000);
+        }
+    }
+    calculateWaitTime() {
+        if (this.secondTokens < 1 && this.maxPerSecond !== Infinity) {
+            const elapsed = (Date.now() - this.lastSecondRefill) / 1000;
+            const remaining = Math.max(0, 1 - elapsed);
+            return Math.ceil(remaining * 1000);
+        }
+        if (this.minuteTokens < 1 && this.maxPerMinute !== Infinity) {
+            const elapsed = (Date.now() - this.lastMinuteRefill) / 60000;
+            const remaining = Math.max(0, 1 - elapsed);
+            return Math.ceil(remaining * 60000);
+        }
+        return 10;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+}
+exports.TokenBucketRateLimiter = TokenBucketRateLimiter;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/rate-limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Batch email sender type definitions
+ */
+export interface BatchSenderOptions {
+    readonly concurrency?: number;
+    readonly rateLimit?: RateLimitOptions;
+    readonly retryOptions?: BatchRetryOptions;
+    readonly onProgress?: (progress: BatchProgress) => void;
+    readonly failureStrategy?: 'continue' | 'abort-on-first' | 'abort-on-threshold';
+    readonly failureThreshold?: number;
+}
+export interface RateLimitOptions {
+    readonly maxPerSecond?: number;
+    readonly maxPerMinute?: number;
+}
+export interface BatchRetryOptions {
+    readonly maxRetries?: number;
+    readonly backoffMs?: number;
+    readonly backoffMultiplier?: number;
+}
+export interface BatchResult {
+    readonly total: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly results: readonly BatchEmailResult[];
+    readonly duration: number;
+    readonly aborted: boolean;
+}
+export interface BatchEmailResult {
+    readonly recipient: string;
+    readonly success: boolean;
+    readonly messageId?: string;
+    readonly provider?: string;
+    readonly error?: string;
+    readonly attempts: number;
+}
+export interface BatchProgress {
+    readonly total: number;
+    readonly completed: number;
+    readonly succeeded: number;
+    readonly failed: number;
+    readonly currentRate: number;
+}
+export interface BatchEmailInput {
+    readonly toEmail: string;
+    readonly toName?: string;
+    readonly subject: string;
+    readonly htmlContent?: string;
+    readonly textContent?: string;
+    readonly headers?: Record<string, string>;
+    readonly attachments?: readonly {
+        filename: string;
+        content: string;
+        contentType?: string;
+    }[];
+    readonly metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAQA;;GAEG;AAEH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC;IAC1C,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,QAAQ,EAAE,aAAa,KAAK,IAAI,CAAC;IACxD,QAAQ,CAAC,eAAe,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,oBAAoB,CAAC;IAChF,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS;QAC9B,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;IACJ,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC7C"}

package/dist/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;EAME"}

package/package.json

@@ -1,10 +1,55 @@
 {
   "name": "@bernierllc/email-batch-sender",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @bernierllc/email-batch-sender",
+  "version": "0.1.0",
+  "description": "Batch email sending with concurrency control, rate limiting, retry strategies, and failure handling",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "email",
+    "batch",
+    "sender",
+    "concurrency",
+    "rate-limiting",
+    "retry",
+    "typescript"
+  ],
+  "author": "Bernier LLC",
+  "license": "PROPRIETARY",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bernier-llc/tools"
+  },
+  "dependencies": {
+    "@bernierllc/email-sender": "5.0.0",
+    "@bernierllc/retry-policy": "0.3.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "test:run": "jest --watchAll=false --forceExit",
+    "test:coverage": "jest --coverage",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "clean": "rm -rf dist",
+    "prebuild": "npm run clean"
+  }
+}