@rx-ted/packages-honest-plugins 1.0.1

package/mail/src/providers/resend.provider.ts

@@ -0,0 +1,74 @@
+import type { MailProvider, SendMailOptions, SendMailResult } from '../types';
+
+export class ResendMailProvider implements MailProvider {
+  readonly name: string;
+  private client: any = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(
+    name: string,
+    private config: { apiKey: string },
+    private fromEmail: string,
+    private fromName?: string,
+  ) {
+    this.name = name;
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (this.client) return;
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = (async () => {
+      const { Resend } = await import('resend');
+      this.client = new Resend(this.config.apiKey);
+    })();
+    return this.initPromise;
+  }
+
+  async send(options: SendMailOptions, _providerName?: string): Promise<SendMailResult> {
+    await this.ensureInit();
+    const payload: Record<string, unknown> = {
+      from: this.fromName
+        ? `${this.fromName} <${options.from || this.fromEmail}>`
+        : options.from || this.fromEmail,
+      to: Array.isArray(options.to) ? options.to : [options.to],
+      subject: options.subject,
+    };
+    if (options.cc) payload.cc = Array.isArray(options.cc) ? options.cc : [options.cc];
+    if (options.bcc) payload.bcc = Array.isArray(options.bcc) ? options.bcc : [options.bcc];
+    if (options.html) payload.html = options.html;
+    if (options.text) payload.text = options.text;
+    if (options.attachments?.length) {
+      payload.attachments = options.attachments.map((a) => ({
+        filename: a.filename,
+        content: a.content,
+        path: a.path,
+        content_type: a.contentType,
+      }));
+    }
+    if (options.headers) payload.headers = options.headers;
+    if (options.tags)
+      payload.tags = Object.entries(options.tags).map(([key, value]) => ({ name: key, value }));
+    const { data, error } = await this.client.emails.send(payload);
+    if (error) throw new Error(`Resend send failed: ${error.message}`);
+    return { id: data?.id ?? 'unknown', provider: this.name };
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      await this.ensureInit();
+      await this.client.emails.send({
+        from: this.fromName ? `${this.fromName} <${this.fromEmail}>` : this.fromEmail,
+        to: [this.fromEmail],
+        subject: 'Health check',
+        text: 'This is a health check email from Resend provider.',
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async close(): Promise<void> {
+    this.client = null;
+  }
+}

package/mail/src/providers/smtp.provider.ts

@@ -0,0 +1,85 @@
+import type { MailProvider, SendMailOptions, SendMailResult } from '../types';
+
+export class SmtpMailProvider implements MailProvider {
+  readonly name: string;
+  private mailer: any = null;
+  private initPromise: Promise<void> | null = null;
+
+  constructor(
+    name: string,
+    private config: { host: string; port: number; user: string; pass: string; secure?: boolean },
+    private fromEmail: string,
+    private fromName?: string,
+  ) {
+    this.name = name;
+  }
+
+  private async ensureInit(): Promise<void> {
+    if (this.mailer) return;
+    if (this.initPromise) return this.initPromise;
+    this.initPromise = (async () => {
+      const { createSMTPMailer } = await import('sently/smtp');
+      this.mailer = await createSMTPMailer({
+        host: this.config.host,
+        port: this.config.port,
+        secure: this.config.secure,
+        auth: {
+          user: this.config.user,
+          pass: this.config.pass,
+        },
+      });
+    })();
+    return this.initPromise;
+  }
+
+  async send(options: SendMailOptions, _providerName?: string): Promise<SendMailResult> {
+    await this.ensureInit();
+    const email = options.from || this.fromEmail;
+    const payload: Record<string, unknown> = {
+      from: this.fromName ? { name: this.fromName, address: email } : email,
+      to: Array.isArray(options.to) ? options.to.join(', ') : options.to,
+      subject: options.subject,
+    };
+    if (options.html) payload.html = options.html;
+    if (options.text) payload.text = options.text;
+    if (options.cc) payload.cc = Array.isArray(options.cc) ? options.cc.join(', ') : options.cc;
+    if (options.bcc)
+      payload.bcc = Array.isArray(options.bcc) ? options.bcc.join(', ') : options.bcc;
+    if (options.replyTo) payload.replyTo = options.replyTo;
+    if (options.attachments?.length) {
+      payload.attachments = options.attachments.map((a) => ({
+        filename: a.filename,
+        content: a.content,
+        path: a.path,
+        contentType: a.contentType,
+      }));
+    }
+    const info = await this.mailer.send(payload);
+    return { id: info.messageId ?? 'unknown', provider: this.name };
+  }
+
+  async warmUp(): Promise<void> {
+    await this.ensureInit();
+    await this.mailer.verify();
+  }
+
+  async healthCheck(): Promise<boolean> {
+    try {
+      await this.warmUp();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.mailer) {
+      try {
+        await this.mailer.close();
+      } catch {
+        /* ignore */
+      }
+      this.mailer = null;
+    }
+  }
+}

package/mail/src/rate-limiter.test.ts

@@ -0,0 +1,81 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { RateLimiter, type MailCacheDriver } from './rate-limiter';
+
+describe('RateLimiter', () => {
+  let cache: MailCacheDriver & { store: Map<string, number> };
+  let limiter: RateLimiter;
+
+  beforeEach(() => {
+    cache = {
+      store: new Map(),
+      async incr(key: string) {
+        const next = (this.store.get(key) ?? 0) + 1;
+        this.store.set(key, next);
+        return next;
+      },
+      async expire(_key: string, _ttl: number) {
+        return true;
+      },
+      async get(key: string) {
+        return this.store.get(key) ?? null;
+      },
+    };
+  });
+
+  describe('with cache', () => {
+    it('passes check when quota is not exceeded', async () => {
+      limiter = new RateLimiter(5, 'test', cache);
+      await expect(limiter.checkAndIncrement()).resolves.toBeUndefined();
+    });
+
+    it('throws when quota is exceeded', async () => {
+      limiter = new RateLimiter(2, 'test', cache);
+      await limiter.checkAndIncrement();
+      await limiter.checkAndIncrement();
+      await expect(limiter.checkAndIncrement()).rejects.toThrow(/quota exceeded/i);
+    });
+
+    it('increments the cache key on each check', async () => {
+      limiter = new RateLimiter(10, 'test', cache);
+      await limiter.checkAndIncrement();
+      await limiter.checkAndIncrement();
+      await limiter.checkAndIncrement();
+      const key = `mail:quota:test:${new Date().toISOString().slice(0, 10)}`;
+      expect(cache.store.get(key)).toBe(3);
+    });
+  });
+
+  describe('without cache', () => {
+    it('always passes when no cache is provided', async () => {
+      limiter = new RateLimiter(1, 'test', null);
+      await limiter.checkAndIncrement();
+      await limiter.checkAndIncrement();
+      await limiter.checkAndIncrement();
+    });
+  });
+
+  describe('health check tracking', () => {
+    it('markHealthCheckDone sets a cache key', async () => {
+      limiter = new RateLimiter(100, 'test', cache);
+      await limiter.markHealthCheckDone();
+      const key = `mail:healthcheck:test:${new Date().toISOString().slice(0, 10)}`;
+      expect(cache.store.get(key)).toBe(1);
+    });
+
+    it('wasHealthCheckDoneToday returns true after marking done', async () => {
+      limiter = new RateLimiter(100, 'test', cache);
+      await limiter.markHealthCheckDone();
+      await expect(limiter.wasHealthCheckDoneToday()).resolves.toBe(true);
+    });
+
+    it('wasHealthCheckDoneToday returns false before any check', async () => {
+      limiter = new RateLimiter(100, 'test', cache);
+      await expect(limiter.wasHealthCheckDoneToday()).resolves.toBe(false);
+    });
+
+    it('returns false when no cache', async () => {
+      limiter = new RateLimiter(100, 'test', null);
+      await expect(limiter.wasHealthCheckDoneToday()).resolves.toBe(false);
+    });
+  });
+});

package/mail/src/rate-limiter.ts

@@ -0,0 +1,54 @@
+import type { ILogger } from '@rx-ted/packages-core';
+
+export interface MailCacheDriver {
+  incr(key: string): Promise<number>;
+  expire(key: string, ttl: number): Promise<boolean>;
+  get?(key: string): Promise<unknown>;
+}
+
+export class RateLimiter {
+  constructor(
+    private quota: number,
+    private providerName: string,
+    private cache?: MailCacheDriver | null,
+    private logger?: ILogger,
+  ) {}
+
+  async checkAndIncrement(): Promise<void> {
+    if (!this.cache) return;
+    const key = `mail:quota:${this.providerName}:${today()}`;
+    const count = await this.cache.incr(key);
+    if (count === 1) {
+      await this.cache.expire(key, 86400);
+    }
+    if (count > this.quota) {
+      this.logger?.warn?.('Daily quota exceeded', {
+        provider: this.providerName,
+        quota: this.quota,
+      });
+      const { MailQuotaExceededError } = await import('./types');
+      throw new MailQuotaExceededError(this.providerName, this.quota);
+    }
+  }
+
+  async markHealthCheckDone(): Promise<void> {
+    if (!this.cache) return;
+    const key = `mail:healthcheck:${this.providerName}:${today()}`;
+    await this.cache.incr(key);
+    await this.cache.expire(key, 86400);
+  }
+
+  async wasHealthCheckDoneToday(): Promise<boolean> {
+    if (!this.cache) return false;
+    const key = `mail:healthcheck:${this.providerName}:${today()}`;
+    if (typeof this.cache.get === 'function') {
+      const val = await this.cache.get(key);
+      return val !== null && val !== undefined;
+    }
+    return false;
+  }
+}
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}

package/mail/src/types.ts

@@ -0,0 +1,81 @@
+export interface Attachment {
+  filename: string;
+  content?: string | Uint8Array;
+  path?: string;
+  contentType?: string;
+}
+
+export interface SendMailOptions {
+  from?: string;
+  to: string | string[];
+  cc?: string | string[];
+  bcc?: string | string[];
+  subject: string;
+  text?: string;
+  html?: string;
+  replyTo?: string;
+  attachments?: Attachment[];
+  headers?: Record<string, string>;
+  tags?: Record<string, string>;
+}
+
+export interface SendMailResult {
+  id: string;
+  provider: string;
+}
+
+export interface MailProvider {
+  readonly name: string;
+  send(options: SendMailOptions, providerName?: string): Promise<SendMailResult>;
+  healthCheck(): Promise<boolean>;
+  close(): Promise<void>;
+  warmUp?(): Promise<void>;
+}
+
+export interface ResendProviderConfig {
+  apiKey: string;
+}
+
+export interface BrevoProviderConfig {
+  apiKey: string;
+}
+
+export interface SmtpProviderConfig {
+  host: string;
+  port: number;
+  user: string;
+  pass: string;
+  secure?: boolean;
+}
+
+export type ProviderType = 'resend' | 'brevo' | 'smtp' | 'custom';
+
+export interface MailProviderConfigEntry {
+  name: string;
+  provider: ProviderType;
+  fromEmail: string;
+  fromName?: string;
+  limits?: {
+    dailyQuota?: number;
+  };
+  resend?: ResendProviderConfig;
+  brevo?: BrevoProviderConfig;
+  smtp?: SmtpProviderConfig;
+  custom?: MailProvider;
+}
+
+export interface MailPluginOptions {
+  providers: MailProviderConfigEntry[];
+  healthCheck?: {
+    intervalMs?: number;
+    maxRetries?: number;
+    retryDelayMs?: number;
+  };
+}
+
+export class MailQuotaExceededError extends Error {
+  constructor(providerName: string, quota: number) {
+    super(`Mail quota exceeded for provider "${providerName}": ${quota}/day`);
+    this.name = 'MailQuotaExceededError';
+  }
+}

package/mail/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "declaration": true,
+    "sourceMap": false,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "types": ["node"],
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src"],
+  "exclude": ["**/*.test.ts"]
+}

package/mail/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+import { getWorkspaceAliases } from '../../../vitest.workspace-aliases';
+
+export default defineConfig({
+  resolve: {
+    alias: getWorkspaceAliases(),
+  },
+  test: {
+    globals: true,
+    environment: 'node',
+    exclude: ['**/node_modules/**'],
+  },
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@rx-ted/packages-honest-plugins",
+  "version": "1.0.1",
+  "private": false,
+  "type": "module",
+  "description": "HonestJS plugins — db, cache, mail, s3, api-doc",
+  "exports": {
+    "./db": {
+      "types": "./db/dist/index.d.ts",
+      "default": "./db/dist/index.js"
+    },
+    "./cache": {
+      "types": "./cache/dist/index.d.ts",
+      "default": "./cache/dist/index.js"
+    },
+    "./mail": {
+      "types": "./mail/dist/index.d.ts",
+      "default": "./mail/dist/index.js"
+    },
+    "./s3": {
+      "types": "./s3/dist/index.d.ts",
+      "default": "./s3/dist/index.js"
+    },
+    "./api-doc": {
+      "types": "./api-doc/dist/index.d.ts",
+      "default": "./api-doc/dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@rx-ted/packages-honest-plugins-db": "workspace:^",
+    "@rx-ted/packages-honest-plugins-cache": "workspace:^",
+    "@rx-ted/packages-honest-plugins-mail": "workspace:^",
+    "@rx-ted/packages-honest-plugins-s3": "workspace:^",
+    "@rx-ted/packages-honest-plugins-api-doc": "workspace:^"
+  }
+}

package/s3/.turbo/turbo-build.log

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

package/s3/.turbo/turbo-test.log

@@ -0,0 +1,11 @@
+$ vitest run
+
+ RUN  v4.1.8 /Users/ben/projects/app/packages/honest-plugins/s3
+
+ ✓ src/index.test.ts (4 tests) 1ms
+
+ Test Files  1 passed (1)
+      Tests  4 passed (4)
+   Start at  14:17:13
+   Duration  194ms (transform 103ms, setup 0ms, import 134ms, tests 1ms, environment 0ms)
+

package/s3/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @rx-ted/packages-honest-plugins-s3
+
+## 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
+
+- S3 plugin for @rx-ted/packages-honest
+- AWS S3 client integration (`@aws-sdk/client-s3`)
+- S3 request presigner for temporary URLs

package/s3/README.md

@@ -0,0 +1,90 @@
+# @rx-ted/packages-honest-plugins-s3
+
+S3 object storage plugin for [@rx-ted/packages-honest](https://github.com/rx-ted/honest). Supports AWS S3 and S3-compatible services.
+
+## Features
+
+- **AWS S3**: full S3 API support via `@aws-sdk/client-s3`
+- **Presigned URLs**: generate presigned upload/download URLs
+- **File metadata**: track file type, size, and custom metadata
+- **Runtime-agnostic**: works on Node.js, Bun, Deno
+
+## Installation
+
+```bash
+pnpm add @rx-ted/packages-honest-plugins-s3
+```
+
+Peer dependencies: `@rx-ted/packages-honest`, `hono`
+
+## Usage
+
+### Register as a plugin
+
+```ts
+import { S3Plugin } from '@rx-ted/packages-honest-plugins/s3';
+
+const plugin = new S3Plugin({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+const { hono } = await Application.create(AppModule, {
+  plugins: [plugin],
+});
+```
+
+### Access S3 service
+
+```ts
+import { ComponentManager } from '@rx-ted/packages-honest';
+import { S3Service } from '@rx-ted/packages-honest-plugins/s3';
+
+const s3 = ComponentManager.getPlugin<S3Service>('s3');
+
+// Upload
+await s3.upload(file, { key: 'uploads/image.png', contentType: 'image/png' });
+
+// Get presigned URL
+const url = await s3.getPresignedUrl('uploads/image.png', { expiresIn: 3600 });
+```
+
+### Driver options
+
+```ts
+import { createS3Driver } from '@rx-ted/packages-honest-plugins/s3';
+
+const driver = createS3Driver({
+  endpoint: 'https://s3.amazonaws.com',
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: '...',
+    secretAccessKey: '...',
+  },
+  forcePathStyle: false, // true for MinIO
+});
+```
+
+## Types
+
+```ts
+interface FileDriver {
+  upload(key: string, body: Buffer, options?: FileUploadOptions): Promise<FileMetadata>;
+  download(key: string): Promise<Buffer>;
+  delete(key: string): Promise<void>;
+  getPresignedUrl(key: string, options?: S3Options): Promise<string>;
+  list(prefix: string): Promise<FileMetadata[]>;
+}
+```
+
+## Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm test` | Run tests |
+| `pnpm build` | Build |

package/s3/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { S3Plugin, S3_CONTEXT_KEY, S3_GLOBAL_KEY } from './s3.plugin';
+export type { S3PluginOptions } from './s3.plugin';
+export { createS3Driver } from './s3.driver';
+export type { S3DriverOptions } from './s3.driver';
+export type { FileDriver, FileMetadata, FileUploadOptions, S3Options, } from './types';
+export { S3Service } from './s3-service';

package/s3/dist/index.js

@@ -0,0 +1,4 @@
+export { S3Plugin, S3_CONTEXT_KEY, S3_GLOBAL_KEY } from './s3.plugin';
+export { createS3Driver } from './s3.driver';
+// DI service
+export { S3Service } from './s3-service';

package/s3/dist/s3-service.d.ts

@@ -0,0 +1,7 @@
+import type { FileDriver } from './types';
+declare class S3Service {
+    constructor();
+}
+interface S3Service extends FileDriver {
+}
+export { S3Service };

package/s3/dist/s3-service.js

@@ -0,0 +1,21 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Service, ComponentManager } from '@rx-ted/packages-honest';
+import { S3_GLOBAL_KEY } from './s3.plugin';
+let S3Service = class S3Service {
+    constructor() {
+        return ComponentManager.getPlugin(S3_GLOBAL_KEY);
+    }
+};
+S3Service = __decorate([
+    Service(),
+    __metadata("design:paramtypes", [])
+], S3Service);
+export { S3Service };

package/s3/dist/s3.driver.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from '@rx-ted/packages-core';
+import type { FileDriver, S3Options } from './types';
+export type S3DriverOptions = S3Options & {
+    logger?: Logger;
+};
+export declare function createS3Driver(options: S3DriverOptions): Promise<FileDriver>;