@rx-ted/packages-honest-plugins 1.0.1

package/mail/.turbo/turbo-test.log

@@ -0,0 +1,12 @@
+$ vitest run
+
+ RUN  v4.1.8 /Users/ben/projects/app/packages/honest-plugins/mail
+
+ ✓ src/rate-limiter.test.ts (8 tests) 7ms
+ ✓ src/plugin.test.ts (16 tests) 5ms
+
+ Test Files  2 passed (2)
+      Tests  24 passed (24)
+   Start at  14:17:13
+   Duration  137ms (transform 69ms, setup 0ms, import 91ms, tests 12ms, environment 0ms)
+

package/mail/.turbo/turbo-typecheck.log

@@ -0,0 +1 @@
+$ tsc -p tsconfig.json --noEmit

package/mail/CHANGELOG.md

@@ -0,0 +1,25 @@
+# @rx-ted/packages-honest-plugins-mail
+
+## 1.0.1
+
+### Patch Changes
+
+- 11bbae7: Remove defunct packages (web-admin, auth, http-client, search) and introduce barrel packages for consolidated exports. Migrate all internal imports from scoped plugin names (`@rx-ted/packages-honest-plugins-db`) to path-based barrel imports (`@rx-ted/packages-honest-plugins/db`). Reset all package versions to 1.0.0 with consolidated changelogs. Clean up obsolete documentation across the monorepo.
+- Updated dependencies [11bbae7]
+  - @rx-ted/packages-core@1.0.1
+  - @rx-ted/packages-honest@1.0.1
+
+## 1.0.0
+
+Initial consolidated release.
+
+### Features
+
+- Mail plugin for @rx-ted/packages-honest
+- Multiple mail providers (Resend, Brevo, SMTP, Custom)
+- Rate limiting, health check, and quota management
+- `warmUp(provider)` — eagerly establishes SMTP connection before first send
+- `failedProviders` Set — tracks providers that failed warmUp/health check
+- `runHealthChecks()` — periodic background health check for all providers
+- `warmUpTimeout` / `sendTimeout` config options
+- Pull-based configuration from ComponentManager caches

package/mail/README.md

@@ -0,0 +1,214 @@
+# @rx-ted/packages-honest-plugins-mail
+
+Mail plugin for [@rx-ted/packages-honest](https://github.com/rx-ted/honest). Supports multiple email providers with automatic failover, per-provider daily rate limiting, and health checks.
+
+## Features
+
+- **Multi-provider**: Resend, Brevo, SMTP, or custom — up to 2 providers
+- **Auto-failover**: tries the next provider if the primary fails
+- **Rate limiting**: per-provider daily quota via cache (`incr`/`expire`)
+- **Health checks**: verifies each provider once per day with configurable retries
+- **Runtime-agnostic**: works on Node.js, Bun, Deno, and Cloudflare Workers
+- **Lazy imports**: optional SDKs (`resend`, `@getbrevo/brevo`, `sently`) are loaded only when needed
+
+## Installation
+
+```bash
+pnpm add @rx-ted/packages-honest-plugins-mail
+```
+
+Peer dependencies: `@rx-ted/packages-honest`, `hono`
+
+Optional SDKs (install only the providers you need):
+```bash
+pnpm add resend              # for Resend provider
+pnpm add sently              # for SMTP provider
+pnpm add @getbrevo/brevo     # for Brevo provider
+```
+
+## Usage
+
+### Register as a plugin
+
+```ts
+import { MailPlugin } from '@rx-ted/packages-honest-plugins-mail';
+import type { MailPluginOptions } from '@rx-ted/packages-honest-plugins-mail';
+
+const plugin = new MailPlugin({
+  providers: [
+    {
+      name: 'primary',
+      provider: 'resend',
+      fromEmail: 'noreply@example.com',
+      resend: { apiKey: 're_xxx' },
+      limits: { dailyQuota: 100 },
+    },
+    {
+      name: 'fallback',
+      provider: 'smtp',
+      fromEmail: 'noreply@example.com',
+      smtp: {
+        host: 'smtp.example.com',
+        port: 465,
+        user: 'user',
+        pass: 'pass',
+        secure: true,
+      },
+    },
+  ],
+  healthCheck: {
+    intervalMs: 300_000,   // check every 5 minutes
+    maxRetries: 3,
+    retryDelayMs: 1000,
+  },
+});
+```
+
+Then pass the plugin to `Application.create`:
+
+```ts
+const { hono } = await Application.create(AppModule, {
+  plugins: [plugin],
+  // ...
+});
+```
+
+### Send an email
+
+The primary provider is registered under `'mail'` in `ComponentManager`. Individual providers are registered under `'mail:<name>'`.
+
+```ts
+import { ComponentManager } from '@rx-ted/packages-honest';
+import type { MailProvider } from '@rx-ted/packages-honest-plugins-mail';
+
+const provider = ComponentManager.getPlugin<MailProvider>('mail');
+const result = await provider.send({
+  from: 'noreply@example.com',
+  to: 'user@example.com',
+  subject: 'Hello',
+  html: '<h1>Hello</h1>',
+  text: 'Hello',
+});
+// { id: '...', provider: 'primary' }
+```
+
+### Get a specific provider
+
+```ts
+const provider = mailPlugin.getClient('brevo-provider');
+```
+
+## Provider Configuration
+
+### Resend
+
+```ts
+{
+  name: 'resend',
+  provider: 'resend',
+  fromEmail: 'noreply@example.com',
+  fromName: 'My App',     // optional
+  resend: { apiKey: 're_xxx' },
+}
+```
+
+### Brevo
+
+```ts
+{
+  name: 'brevo',
+  provider: 'brevo',
+  fromEmail: 'noreply@example.com',
+  brevo: { apiKey: 'xxx' },
+}
+```
+
+### SMTP
+
+```ts
+{
+  name: 'smtp',
+  provider: 'smtp',
+  fromEmail: 'noreply@example.com',
+  smtp: {
+    host: 'smtp.example.com',
+    port: 465,
+    user: 'username',
+    pass: 'password',
+    secure: true,     // false for port 587 (STARTTLS)
+  },
+}
+```
+
+> **Note on Cloudflare Workers:** SMTP uses `sently` which relies on `cloudflare:sockets` TCP API. Port 25 is blocked; use 465 or 587.
+
+### Custom
+
+```ts
+import { CustomMailProvider } from '@rx-ted/packages-honest-plugins-mail';
+
+{
+  name: 'custom',
+  provider: 'custom',
+  custom: myCustomMailProvider,  // any MailProvider instance
+}
+```
+
+## Rate Limiting
+
+When a cache driver is available (e.g., `RedisPlugin`), the `RateLimiter` enforces daily quotas via cache `incr`/`expire`. If no cache is registered, rate limiting is disabled.
+
+```ts
+{
+  name: 'resend',
+  provider: 'resend',
+  fromEmail: '...',
+  resend: { apiKey: '...' },
+  limits: { dailyQuota: 1000 },
+}
+```
+
+## Health Checks
+
+The plugin runs health checks in `afterModulesRegistered` with configurable retries. Each provider is checked once per day (tracked via cache).
+
+## API
+
+### `MailPlugin`
+
+| Method | Description |
+|--------|-------------|
+| `getClient(name?)` | Returns the primary provider or a named provider |
+| `beforeModulesRegistered(app, hono)` | Registers providers in ComponentManager |
+| `afterModulesRegistered(app, hono)` | Runs initial health checks |
+| `close()` | Closes all provider connections |
+
+### Types
+
+```ts
+interface MailProvider {
+  readonly name: string;
+  send(options: SendMailOptions): Promise<SendMailResult>;
+  healthCheck(): Promise<boolean>;
+  close(): Promise<void>;
+}
+
+interface SendMailOptions {
+  from: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  replyTo?: string;
+  subject: string;
+  text?: string;
+  html?: string;
+  attachments?: Attachment[];
+  headers?: Record<string, string>;
+  tags?: Record<string, string>;
+}
+
+interface SendMailResult {
+  id: string;
+  provider: string;
+}
+```

package/mail/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { MailPlugin, MAIL_GLOBAL_KEY, MAIL_DISABLED_MSG } from './plugin';
+export type { MailPluginOptions } from './plugin';
+export type { MailProvider, SendMailOptions, SendMailResult, Attachment } from './types';
+export { MailQuotaExceededError } from './types';

package/mail/dist/index.js

@@ -0,0 +1,2 @@
+export { MailPlugin, MAIL_GLOBAL_KEY, MAIL_DISABLED_MSG } from './plugin';
+export { MailQuotaExceededError } from './types';

package/mail/dist/plugin.d.ts

@@ -0,0 +1,64 @@
+import { type ILogger } from '@rx-ted/packages-core';
+import type { Application, IPlugin } from '@rx-ted/packages-honest';
+import type { SendMailOptions, SendMailResult } from './types';
+import type { MailProvider } from './types';
+export declare const MAIL_GLOBAL_KEY = "app:mail";
+export interface MailPluginOptions {
+    resend?: {
+        apiKey?: string;
+        fromEmail?: string;
+        fromName?: string;
+        dailyQuota?: number;
+    };
+    brevo?: {
+        apiKey?: string;
+        fromEmail?: string;
+        fromName?: string;
+        dailyQuota?: number;
+    };
+    smtp?: {
+        host?: string;
+        port?: number;
+        user?: string;
+        pass?: string;
+        fromEmail?: string;
+        fromName?: string;
+        secure?: boolean;
+        dailyQuota?: number;
+    };
+    fromEmail?: string;
+    fromName?: string;
+    healthCheck?: {
+        enabled?: boolean;
+        intervalMs?: number;
+        maxRetries?: number;
+        retryDelayMs?: number;
+    };
+    warmUpTimeout?: number;
+    sendTimeout?: number;
+}
+export declare const MAIL_DISABLED_MSG = "Mail service is not configured. Configure resend, brevo, or smtp provider.";
+export declare class MailPlugin implements IPlugin, MailProvider {
+    readonly name = "app:mail";
+    readonly version = "0.0.1";
+    logger?: ILogger;
+    private providers;
+    private rateLimiters;
+    private readonly options;
+    private failedProviders;
+    private isWarming;
+    constructor(options?: MailPluginOptions);
+    getClient(name?: string): MailProvider | undefined;
+    warmUp(): Promise<void>;
+    send(options: SendMailOptions, providerName?: string): Promise<SendMailResult>;
+    healthCheck(): Promise<boolean>;
+    private tryInitResend;
+    private tryInitBrevo;
+    private tryInitSmtp;
+    beforeModulesRegistered(app: Application, _hono: unknown): Promise<void>;
+    afterModulesRegistered(_app: Application, _hono: unknown): Promise<void>;
+    runHealthChecks(): Promise<void>;
+    close(): Promise<void>;
+    private getCacheDriver;
+    private getEnv;
+}

package/mail/dist/plugin.js

@@ -0,0 +1,232 @@
+import { ENV_SYMBOL } from '@rx-ted/packages-core';
+import { ComponentManager, resolvePluginLogger } from '@rx-ted/packages-honest';
+import { RateLimiter } from './rate-limiter';
+import { ResendMailProvider } from './providers/resend.provider';
+import { BrevoMailProvider } from './providers/brevo.provider';
+import { SmtpMailProvider } from './providers/smtp.provider';
+export const MAIL_GLOBAL_KEY = 'app:mail';
+export const MAIL_DISABLED_MSG = 'Mail service is not configured. Configure resend, brevo, or smtp provider.';
+export class MailPlugin {
+    name = MAIL_GLOBAL_KEY;
+    version = '0.0.1';
+    logger;
+    providers = [];
+    rateLimiters = new Map();
+    options;
+    failedProviders = new Set();
+    isWarming = false;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    getClient(name) {
+        if (name)
+            return this.providers.find((p) => p.name === name);
+        return this.providers[0];
+    }
+    async warmUp() {
+        if (this.isWarming)
+            return;
+        this.isWarming = true;
+        const timeout = this.options.warmUpTimeout ?? 10_000;
+        const relevant = this.providers.filter((p) => typeof p.warmUp === 'function');
+        if (relevant.length === 0) {
+            this.isWarming = false;
+            return;
+        }
+        const results = await Promise.allSettled(relevant.map((p) => (async () => {
+            try {
+                await Promise.race([
+                    p.warmUp(),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error('Warm-up timeout')), timeout)),
+                ]);
+                this.logger?.info('[mail] Provider warmed up', { provider: p.name });
+            }
+            catch (err) {
+                this.failedProviders.add(p.name);
+                this.logger?.warn('[mail] Provider warm-up failed or timed out', {
+                    provider: p.name,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        })()));
+        const succeeded = results.filter((r) => r.status === 'fulfilled').length;
+        this.logger?.info('[mail] Warm-up completed', { total: relevant.length, succeeded });
+        this.isWarming = false;
+    }
+    async send(options, providerName) {
+        if (this.providers.length === 0) {
+            throw new Error(MAIL_DISABLED_MSG);
+        }
+        if (providerName) {
+            const provider = this.providers.find((p) => p.name === providerName);
+            if (!provider)
+                throw new Error(`Unknown provider "${providerName}"`);
+            if (this.failedProviders.has(providerName)) {
+                throw new Error(`Provider "${providerName}" unavailable (warm-up failed)`);
+            }
+            const limiter = this.rateLimiters.get(providerName);
+            if (limiter)
+                await limiter.checkAndIncrement();
+            return provider.send(options);
+        }
+        const errors = [];
+        for (const provider of this.providers) {
+            if (this.failedProviders.has(provider.name))
+                continue;
+            try {
+                const limiter = this.rateLimiters.get(provider.name);
+                if (limiter)
+                    await limiter.checkAndIncrement();
+                return await provider.send(options);
+            }
+            catch (err) {
+                errors.push(err);
+                this.logger?.warn?.('Provider failed, trying next', {
+                    provider: provider.name,
+                    error: err,
+                });
+            }
+        }
+        throw new Error(`All providers failed: ${errors.map((e) => e.message).join('; ')}`);
+    }
+    healthCheck() {
+        if (this.providers.length === 0)
+            return Promise.resolve(false);
+        return this.providers[0].healthCheck();
+    }
+    tryInitResend(cfg, cacheDrv, appEnv) {
+        const apiKey = cfg.apiKey ?? appEnv?.get('MAIL_RESEND_API_KEY');
+        if (!apiKey)
+            return;
+        const fromEmail = cfg.fromEmail ??
+            appEnv?.var('MAIL_RESEND_FROM_EMAIL', 'noreply@19981204.xyz') ??
+            'noreply@19981204.xyz';
+        const fromName = cfg.fromName ?? appEnv?.var('MAIL_RESEND_FROM_NAME', 'noreply') ?? 'noreply';
+        this.providers.push(new ResendMailProvider('resend', { apiKey }, fromEmail, fromName));
+        this.rateLimiters.set('resend', new RateLimiter(cfg.dailyQuota ?? Infinity, 'resend', cacheDrv, this.logger));
+        this.logger?.info('Mail provider registered', { name: 'resend' });
+    }
+    tryInitBrevo(cfg, cacheDrv, appEnv) {
+        const apiKey = cfg.apiKey ?? appEnv?.get('MAIL_BREVO_API_KEY');
+        if (!apiKey)
+            return;
+        const fromEmail = cfg.fromEmail ??
+            appEnv?.var('MAIL_BREVO_FROM_EMAIL', 'noreply@19981204.xyz') ??
+            'noreply@19981204.xyz';
+        const fromName = cfg.fromName ?? appEnv?.var('MAIL_BREVO_FROM_NAME', 'noreply') ?? 'noreply';
+        this.providers.push(new BrevoMailProvider('brevo', { apiKey }, fromEmail, fromName));
+        this.rateLimiters.set('brevo', new RateLimiter(cfg.dailyQuota ?? Infinity, 'brevo', cacheDrv, this.logger));
+        this.logger?.info('Mail provider registered', { name: 'brevo' });
+    }
+    tryInitSmtp(cfg, cacheDrv, appEnv) {
+        const host = cfg.host ?? appEnv?.get('MAIL_SMTP_HOST');
+        const user = cfg.user ?? appEnv?.get('MAIL_SMTP_USER');
+        const pass = cfg.pass ?? appEnv?.get('MAIL_SMTP_PASS');
+        const port = cfg.port ?? appEnv?.get('MAIL_SMTP_PORT', 'number') ?? 587;
+        if (!host || !user || !pass)
+            return;
+        const fromEmail = (cfg.fromEmail ?? appEnv?.var('MAIL_SMTP_FROM_EMAIL')) || user;
+        const fromName = cfg.fromName ?? appEnv?.var('MAIL_SMTP_FROM_NAME', 'rx-ted') ?? 'rx-ted';
+        this.providers.push(new SmtpMailProvider('smtp', { host, port, user, pass, secure: cfg.secure }, fromEmail, fromName));
+        this.rateLimiters.set('smtp', new RateLimiter(cfg.dailyQuota ?? Infinity, 'smtp', cacheDrv, this.logger));
+        this.logger?.info('Mail provider registered', { name: 'smtp' });
+    }
+    async beforeModulesRegistered(app, _hono) {
+        this.logger ??= resolvePluginLogger(this.name);
+        const cacheDrv = this.getCacheDriver(app);
+        const appEnv = this.getEnv();
+        this.tryInitResend(this.options.resend ?? {}, cacheDrv, appEnv);
+        this.tryInitBrevo(this.options.brevo ?? {}, cacheDrv, appEnv);
+        this.tryInitSmtp(this.options.smtp ?? {}, cacheDrv, appEnv);
+        if (this.providers.length === 0) {
+            this.logger.warn(MAIL_DISABLED_MSG);
+        }
+        else {
+            for (const p of this.providers) {
+                ComponentManager.registerPlugin(`mail:${p.name}`, p);
+            }
+        }
+        ComponentManager.registerPlugin(MAIL_GLOBAL_KEY, this);
+    }
+    async afterModulesRegistered(_app, _hono) {
+        if (this.providers.length === 0 || !this.logger)
+            return;
+        if (this.options.healthCheck?.enabled === false) {
+            this.logger.info('Health check disabled by config');
+            return;
+        }
+        this.logger.info('Health check deferred to background (will run via waitUntil)');
+    }
+    async runHealthChecks() {
+        if (this.providers.length === 0 || !this.logger)
+            return;
+        if (this.options.healthCheck?.enabled === false)
+            return;
+        const maxRetries = this.options.healthCheck?.maxRetries ?? 3;
+        const retryDelay = this.options.healthCheck?.retryDelayMs ?? 1000;
+        for (const provider of this.providers) {
+            const limiter = this.rateLimiters.get(provider.name);
+            if (!limiter)
+                continue;
+            const done = await limiter.wasHealthCheckDoneToday();
+            if (done) {
+                this.logger.info('Health check already done today', { provider: provider.name });
+                continue;
+            }
+            let success = false;
+            for (let attempt = 1; attempt <= maxRetries; attempt++) {
+                this.logger.info('Running health check', { provider: provider.name, attempt });
+                success = await provider.healthCheck();
+                if (success)
+                    break;
+                if (attempt < maxRetries)
+                    await sleep(retryDelay);
+            }
+            if (success) {
+                await limiter.markHealthCheckDone();
+                this.logger.info('Health check passed', { provider: provider.name });
+            }
+            else {
+                this.logger.warn('Health check failed after retries', {
+                    provider: provider.name,
+                    maxRetries,
+                });
+            }
+        }
+    }
+    async close() {
+        for (const provider of this.providers) {
+            try {
+                await provider.close();
+            }
+            catch (e) {
+                this.logger?.error?.('Error closing provider', { provider: provider.name, error: e });
+            }
+        }
+    }
+    getCacheDriver(_app) {
+        try {
+            if (ComponentManager.hasPlugin('cache')) {
+                return ComponentManager.getPlugin('cache');
+            }
+        }
+        catch {
+            return null;
+        }
+        return null;
+    }
+    getEnv() {
+        try {
+            if (ComponentManager.hasPlugin(ENV_SYMBOL)) {
+                return ComponentManager.getPlugin(ENV_SYMBOL);
+            }
+        }
+        catch {
+            return undefined;
+        }
+        return undefined;
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/mail/dist/providers/brevo.provider.d.ts

@@ -0,0 +1,15 @@
+import type { MailProvider, SendMailOptions, SendMailResult } from '../types';
+export declare class BrevoMailProvider implements MailProvider {
+    private config;
+    private fromEmail;
+    private fromName?;
+    readonly name: string;
+    private client;
+    constructor(name: string, config: {
+        apiKey: string;
+    }, fromEmail: string, fromName?: string | undefined);
+    private ensureInit;
+    send(options: SendMailOptions, _providerName?: string): Promise<SendMailResult>;
+    healthCheck(): Promise<boolean>;
+    close(): Promise<void>;
+}

package/mail/dist/providers/brevo.provider.js

@@ -0,0 +1,75 @@
+import { BrevoClient } from '@getbrevo/brevo';
+export class BrevoMailProvider {
+    config;
+    fromEmail;
+    fromName;
+    name;
+    client = null;
+    constructor(name, config, fromEmail, fromName) {
+        this.config = config;
+        this.fromEmail = fromEmail;
+        this.fromName = fromName;
+        this.name = name;
+    }
+    async ensureInit() {
+        if (this.client)
+            return;
+        this.client = new BrevoClient({ apiKey: this.config.apiKey });
+    }
+    async send(options, _providerName) {
+        await this.ensureInit();
+        const to = (Array.isArray(options.to) ? options.to : [options.to]).map((e) => ({
+            email: e,
+        }));
+        const payload = {
+            sender: { name: this.fromName ?? '', email: options.from || this.fromEmail },
+            to,
+            subject: options.subject,
+        };
+        if (options.html)
+            payload.htmlContent = options.html;
+        if (options.text)
+            payload.textContent = options.text;
+        if (options.cc)
+            payload.cc = (Array.isArray(options.cc) ? options.cc : [options.cc]).map((e) => ({
+                email: e,
+            }));
+        if (options.bcc)
+            payload.bcc = (Array.isArray(options.bcc) ? options.bcc : [options.bcc]).map((e) => ({
+                email: e,
+            }));
+        if (options.attachments?.length) {
+            payload.attachment = options.attachments.map((a) => ({
+                name: a.filename,
+                content: a.content instanceof Uint8Array ? uint8ArrayToBase64(a.content) : a.content,
+            }));
+        }
+        const result = await this.client.transactionalEmails.sendTransacEmail(payload);
+        return { id: result?.messageId ?? 'unknown', provider: this.name };
+    }
+    async healthCheck() {
+        try {
+            await this.ensureInit();
+            await this.client.transactionalEmails.sendTransacEmail({
+                sender: { name: this.fromName ?? '', email: this.fromEmail },
+                to: [{ email: this.fromEmail }],
+                subject: 'Health check',
+                textContent: 'This is a health check email from Brevo provider.',
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async close() {
+        this.client = null;
+    }
+}
+function uint8ArrayToBase64(u8) {
+    let binary = '';
+    for (let i = 0; i < u8.length; i++) {
+        binary += String.fromCharCode(u8[i]);
+    }
+    return btoa(binary);
+}

package/mail/dist/providers/custom.provider.d.ts

@@ -0,0 +1,9 @@
+import type { MailProvider, SendMailOptions, SendMailResult } from '../types';
+export declare class CustomMailProvider implements MailProvider {
+    private impl;
+    readonly name: string;
+    constructor(name: string, impl: MailProvider);
+    send(options: SendMailOptions, providerName?: string): Promise<SendMailResult>;
+    healthCheck(): Promise<boolean>;
+    close(): Promise<void>;
+}

package/mail/dist/providers/custom.provider.js

@@ -0,0 +1,22 @@
+export class CustomMailProvider {
+    impl;
+    name;
+    constructor(name, impl) {
+        this.impl = impl;
+        this.name = name;
+    }
+    async send(options, providerName) {
+        return this.impl.send(options, providerName);
+    }
+    async healthCheck() {
+        if (typeof this.impl.healthCheck === 'function') {
+            return this.impl.healthCheck();
+        }
+        return true;
+    }
+    async close() {
+        if (typeof this.impl.close === 'function') {
+            await this.impl.close();
+        }
+    }
+}