qarpeo 0.0.0-alpha.10

package/dist/runtime/server/utils/mail-suppression.mjs

@@ -0,0 +1,328 @@
+import { getD1Binding } from "../../db.mjs";
+import { getKVBinding } from "../../kv.mjs";
+function getDevSuppressionStore() {
+  return globalThis.__qarpeo_dev_suppressions__ ||= /* @__PURE__ */ new Map();
+}
+function getDevSoftBounceStore() {
+  return globalThis.__qarpeo_dev_soft_bounces__ ||= /* @__PURE__ */ new Map();
+}
+let _tableEnsured = false;
+export async function ensureMailSuppressionsTable(db) {
+  if (_tableEnsured || !db) return;
+  try {
+    await db.prepare(
+      `CREATE TABLE IF NOT EXISTS _qarpeo_mail_suppressions (
+          id TEXT PRIMARY KEY,
+          email TEXT NOT NULL UNIQUE,
+          reason TEXT NOT NULL,
+          type TEXT NOT NULL,
+          source TEXT,
+          metadata_json TEXT,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        )`
+    ).run();
+    _tableEnsured = true;
+  } catch (err) {
+    _tableEnsured = true;
+  }
+}
+function resolveUnsubscribeSecret(secret) {
+  const procEnv = globalThis.process?.env || {};
+  const runtimeConfig = globalThis.__NUXT_RUNTIME_CONFIG__ || {};
+  return secret || runtimeConfig.qarpeo?.mail?.unsubscribe?.secret || runtimeConfig.qarpeo?.auth?.secret || procEnv.AUTH_SECRET || procEnv.NUXT_SESSION_PASSWORD || "qarpeo_unsubscribe_secret_salt_2026";
+}
+export async function generateUnsubscribeToken(email, secret) {
+  const cleanEmail = email.trim().toLowerCase();
+  const keySecret = resolveUnsubscribeSecret(secret);
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(keySecret);
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const payload = `${cleanEmail}:${Date.now()}`;
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(payload));
+  const sigHex = Array.from(new Uint8Array(signature)).map((b) => b.toString(16).padStart(2, "0")).join("");
+  const tokenRaw = `${payload}:${sigHex}`;
+  return btoa(tokenRaw).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export async function verifyUnsubscribeToken(token, secret) {
+  try {
+    let base64 = token.replace(/-/g, "+").replace(/_/g, "/");
+    while (base64.length % 4) base64 += "=";
+    const decoded = atob(base64);
+    const parts = decoded.split(":");
+    if (parts.length < 3) return null;
+    const email = parts[0];
+    const timestamp = parts[1];
+    const sigHex = parts[2];
+    const payload = `${email}:${timestamp}`;
+    const keySecret = resolveUnsubscribeSecret(secret);
+    const encoder = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(keySecret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["verify"]
+    );
+    const sigBytes = new Uint8Array(
+      sigHex.match(/.{1,2}/g)?.map((byte) => parseInt(byte, 16)) || []
+    );
+    const isValid = await crypto.subtle.verify(
+      "HMAC",
+      cryptoKey,
+      sigBytes,
+      encoder.encode(payload)
+    );
+    return isValid ? email : null;
+  } catch {
+    return null;
+  }
+}
+export async function buildListUnsubscribeHeaders(options) {
+  const { to, baseUrl, config, secret } = options;
+  const cleanEmail = to.trim().toLowerCase();
+  const base = baseUrl.replace(/\/$/, "");
+  const token = await generateUnsubscribeToken(cleanEmail, secret);
+  const unsubsPath = config?.url || `${base}/api/mail/unsubscribe`;
+  const unsubscribeHttpUrl = `${unsubsPath}?token=${encodeURIComponent(token)}`;
+  const mailtoPart = config?.email ? `<mailto:${config.email}?subject=unsubscribe:${encodeURIComponent(cleanEmail)}>` : "";
+  const listUnsubsValue = mailtoPart ? `<${unsubscribeHttpUrl}>, ${mailtoPart}` : `<${unsubscribeHttpUrl}>`;
+  return {
+    "List-Unsubscribe": listUnsubsValue,
+    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click"
+  };
+}
+export async function suppressEmail(event, options) {
+  const cleanEmail = options.email.trim().toLowerCase();
+  const reason = options.reason || "bounce";
+  const type = options.type || "hard_bounce";
+  const source = options.source || "manual";
+  const now = Date.now();
+  const id = `sup_${now}_${Math.random().toString(36).slice(2, 9)}`;
+  const record = {
+    id,
+    email: cleanEmail,
+    reason,
+    type,
+    source,
+    metadata: options.metadata,
+    createdAt: now,
+    updatedAt: now
+  };
+  getDevSuppressionStore().set(cleanEmail, record);
+  try {
+    const kv = getKVBinding("KV", event);
+    if (kv && typeof kv.put === "function") {
+      await kv.put(`mail:suppressed:${cleanEmail}`, JSON.stringify(record));
+    }
+  } catch {
+  }
+  try {
+    const db = getD1Binding("DB", event);
+    if (db && typeof db.prepare === "function") {
+      await ensureMailSuppressionsTable(db);
+      await db.prepare(
+        `INSERT INTO _qarpeo_mail_suppressions (id, email, reason, type, source, metadata_json, created_at, updated_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+           ON CONFLICT(email) DO UPDATE SET
+             reason = excluded.reason,
+             type = excluded.type,
+             source = excluded.source,
+             metadata_json = excluded.metadata_json,
+             updated_at = excluded.updated_at`
+      ).bind(
+        id,
+        cleanEmail,
+        reason,
+        type,
+        source,
+        options.metadata ? JSON.stringify(options.metadata) : null,
+        now,
+        now
+      ).run();
+    }
+  } catch (dbErr) {
+  }
+  const nitroApp = globalThis.useNitroApp?.();
+  if (nitroApp && typeof nitroApp.hooks?.callHook === "function") {
+    await nitroApp.hooks.callHook("qarpeo:mail:suppression", {
+      email: cleanEmail,
+      record,
+      action: "suppressed"
+    });
+  }
+  return record;
+}
+export async function isEmailSuppressed(event, email) {
+  if (!email) return { suppressed: false };
+  const cleanEmail = email.trim().toLowerCase();
+  const devRecord = getDevSuppressionStore().get(cleanEmail);
+  if (devRecord) {
+    return {
+      suppressed: true,
+      reason: devRecord.reason,
+      type: devRecord.type,
+      record: devRecord
+    };
+  }
+  try {
+    const kv = getKVBinding("KV", event);
+    if (kv && typeof kv.get === "function") {
+      const cached = await kv.get(`mail:suppressed:${cleanEmail}`, { type: "json" });
+      if (cached && cached.email) {
+        return {
+          suppressed: true,
+          reason: cached.reason,
+          type: cached.type,
+          record: cached
+        };
+      }
+    }
+  } catch {
+  }
+  try {
+    const db = getD1Binding("DB", event);
+    if (db && typeof db.prepare === "function") {
+      await ensureMailSuppressionsTable(db);
+      const row = await db.prepare(
+        `SELECT id, email, reason, type, source, metadata_json, created_at, updated_at
+           FROM _qarpeo_mail_suppressions
+           WHERE email = ? LIMIT 1`
+      ).bind(cleanEmail).first();
+      if (row) {
+        const record = {
+          id: row.id,
+          email: row.email,
+          reason: row.reason,
+          type: row.type,
+          source: row.source,
+          metadata: row.metadata_json ? JSON.parse(row.metadata_json) : void 0,
+          createdAt: Number(row.created_at),
+          updatedAt: Number(row.updated_at)
+        };
+        return {
+          suppressed: true,
+          reason: record.reason,
+          type: record.type,
+          record
+        };
+      }
+    }
+  } catch {
+  }
+  return { suppressed: false };
+}
+export async function unsuppressEmail(event, email) {
+  const cleanEmail = email.trim().toLowerCase();
+  let removed = false;
+  removed = getDevSuppressionStore().delete(cleanEmail) || removed;
+  try {
+    const kv = getKVBinding("KV", event);
+    if (kv && typeof kv.delete === "function") {
+      await kv.delete(`mail:suppressed:${cleanEmail}`);
+      removed = true;
+    }
+  } catch {
+  }
+  try {
+    const db = getD1Binding("DB", event);
+    if (db && typeof db.prepare === "function") {
+      await ensureMailSuppressionsTable(db);
+      const res = await db.prepare(`DELETE FROM _qarpeo_mail_suppressions WHERE email = ?`).bind(cleanEmail).run();
+      if (res && Number(res?.meta?.changes || 0) > 0) removed = true;
+    }
+  } catch {
+  }
+  const nitroApp = globalThis.useNitroApp?.();
+  if (nitroApp && typeof nitroApp.hooks?.callHook === "function") {
+    await nitroApp.hooks.callHook("qarpeo:mail:suppression", {
+      email: cleanEmail,
+      action: "unsuppressed"
+    });
+  }
+  return removed;
+}
+export async function listSuppressedEmails(event, options = {}) {
+  const limit = Math.min(options.limit || 50, 200);
+  const offset = options.offset || 0;
+  try {
+    const db = getD1Binding("DB", event);
+    if (db && typeof db.prepare === "function") {
+      await ensureMailSuppressionsTable(db);
+      let whereClause = "WHERE 1=1";
+      const params = [];
+      if (options.search) {
+        whereClause += " AND email LIKE ?";
+        params.push(`%${options.search.trim().toLowerCase()}%`);
+      }
+      if (options.type) {
+        whereClause += " AND type = ?";
+        params.push(options.type);
+      }
+      if (options.reason) {
+        whereClause += " AND reason = ?";
+        params.push(options.reason);
+      }
+      const countRow = await db.prepare(`SELECT COUNT(*) as count FROM _qarpeo_mail_suppressions ${whereClause}`).bind(...params).first();
+      const total2 = Number(countRow?.count || 0);
+      const rows = await db.prepare(
+        `SELECT id, email, reason, type, source, metadata_json, created_at, updated_at
+           FROM _qarpeo_mail_suppressions
+           ${whereClause}
+           ORDER BY created_at DESC
+           LIMIT ? OFFSET ?`
+      ).bind(...params, limit, offset).all();
+      const items2 = (rows?.results || []).map((row) => ({
+        id: row.id,
+        email: row.email,
+        reason: row.reason,
+        type: row.type,
+        source: row.source,
+        metadata: row.metadata_json ? JSON.parse(row.metadata_json) : void 0,
+        createdAt: Number(row.created_at),
+        updatedAt: Number(row.updated_at)
+      }));
+      return { items: items2, total: total2 };
+    }
+  } catch {
+  }
+  let devItems = Array.from(getDevSuppressionStore().values());
+  if (options.search) {
+    const q = options.search.trim().toLowerCase();
+    devItems = devItems.filter((i) => i.email.includes(q));
+  }
+  if (options.type) {
+    devItems = devItems.filter((i) => i.type === options.type);
+  }
+  if (options.reason) {
+    devItems = devItems.filter((i) => i.reason === options.reason);
+  }
+  const total = devItems.length;
+  const items = devItems.slice(offset, offset + limit);
+  return { items, total };
+}
+export async function recordSoftBounce(event, email, threshold = 3) {
+  const cleanEmail = email.trim().toLowerCase();
+  const store = getDevSoftBounceStore();
+  const existing = store.get(cleanEmail) || { count: 0, lastAt: 0 };
+  existing.count += 1;
+  existing.lastAt = Date.now();
+  store.set(cleanEmail, existing);
+  if (existing.count >= threshold) {
+    await suppressEmail(event, {
+      email: cleanEmail,
+      reason: "bounce",
+      type: "soft_bounce",
+      source: "soft_bounce_threshold",
+      metadata: { consecutiveCount: existing.count }
+    });
+    return { suppressed: true, count: existing.count };
+  }
+  return { suppressed: false, count: existing.count };
+}

package/dist/runtime/server/utils/mail.d.ts

@@ -0,0 +1,90 @@
+import type { MailResult, SendMailRequest } from "../../../types";
+export interface DevEmailRecord {
+    id: string;
+    to: string | string[];
+    from: string;
+    subject: string;
+    html: string;
+    text: string;
+    timestamp: number;
+    headers?: Record<string, string>;
+    template?: string;
+    queued?: boolean;
+    opened?: boolean;
+    openedAt?: number;
+    openCount?: number;
+    clicks?: Array<{
+        url: string;
+        timestamp: number;
+    }>;
+    bounced?: boolean;
+    bounceReason?: string;
+    metadata?: Record<string, any>;
+}
+/** Access all intercepted emails in local development. */
+export declare function getDevMailbox(): DevEmailRecord[];
+/** Access a specific intercepted email by ID. */
+export declare function getDevEmail(id: string): DevEmailRecord | undefined;
+/** Clear the local development mailbox. */
+export declare function clearDevMailbox(): void;
+/** Record an open tracking event for a message. */
+export declare function recordEmailOpen(id: string): boolean;
+/** Record a link click tracking event for a message. */
+export declare function recordEmailClick(id: string, url: string): boolean;
+/** Record a bounce event for a message. */
+export declare function recordEmailBounce(id: string, reason?: string): boolean;
+/**
+ * Injects open tracking pixel and click tracking redirect URLs into HTML email content.
+ */
+export declare function injectEmailTracking(html: string, options: {
+    messageId: string;
+    baseUrl: string;
+    opens?: boolean;
+    clicks?: boolean;
+}): string;
+/**
+ * Direct delivery executor using Cloudflare send_email binding or external providers.
+ * Used internally for immediate sends, waitUntil backgrounds, and queue consumer workers.
+ */
+export declare function deliverMailDirect(options: {
+    from: string;
+    to: string | string[];
+    subject: string;
+    html: string;
+    text: string;
+    replyTo?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    headers?: Record<string, string>;
+    messageId: string;
+    provider: string;
+    apiKey?: string;
+}, event?: any): Promise<string>;
+/**
+ * High-level transactional mail sender with template rendering, markdown support,
+ * open/click tracking, queue-backed delivery, and dev mailbox capture.
+ *
+ * @example
+ *   // Markdown content:
+ *   await sendMail({
+ *     to: "user@example.com",
+ *     subject: "Welcome to Acme",
+ *     markdown: "# Welcome!\nWe are glad you joined us.\n\n[btn: Go to Dashboard](https://myapp.com)",
+ *   })
+ *
+ *   // Template:
+ *   await sendMail({
+ *     to: "user@example.com",
+ *     template: "welcome",
+ *     data: { name: "Alice", actionUrl: "https://myapp.com/dashboard" },
+ *   })
+ */
+export declare function sendMail(request: SendMailRequest, event?: any): Promise<MailResult>;
+/** Access the Qarpeo Transactional Mail client. */
+export declare function useMail(event?: any): {
+    send: (request: SendMailRequest) => Promise<MailResult>;
+    getMailbox: typeof getDevMailbox;
+    getEmail: typeof getDevEmail;
+    clearMailbox: typeof clearDevMailbox;
+};
+export { suppressEmail, isEmailSuppressed, unsuppressEmail, listSuppressedEmails, recordSoftBounce, generateUnsubscribeToken, verifyUnsubscribeToken, buildListUnsubscribeHeaders, } from "./mail-suppression";