@nebutra/email 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# @nebutra/email
+
+> Transactional email service powered by Resend with branded HTML templates.
+
+## Installation
+
+```bash
+# Internal monorepo dependency
+pnpm add @nebutra/email@workspace:*
+```
+
+## Usage
+
+```typescript
+import { sendWelcomeEmail, sendApiKeyCreatedEmail } from "@nebutra/email";
+
+await sendWelcomeEmail({
+  to: "user@example.com",
+  firstName: "Jane",
+  orgName: "Acme Corp",
+});
+
+await sendApiKeyCreatedEmail({
+  to: "user@example.com",
+  firstName: "Jane",
+  keyPrefix: "sk_live_abc",
+  keyName: "Production Key",
+  plaintextKey: "sk_live_abc123...",
+});
+```
+
+## API
+
+| Function | Description |
+|----------|-------------|
+| `sendWelcomeEmail` | Welcome email for new organization provisioning |
+| `sendOrderConfirmationEmail` | Order confirmation with line items |
+| `sendApiKeyCreatedEmail` | API key creation notice (shows key once) |
+| `sendQuotaWarningEmail` | Quota usage warning (80%/100% threshold) |
+| `sendInviteEmail` | Team member invitation |
+| `sendMagicLinkEmail` | Passwordless sign-in link |
+| `sendContactFormReceivedEmail` | Contact form acknowledgment |
+| `sendCheckoutCompletedEmail` | Subscription checkout confirmation |
+| `sendTrialEndingEmail` | Trial expiry warning (3 days before) |
+| `sendInvoicePaidEmail` | Payment receipt |
+| `sendPaymentFailedEmail` | Payment failure retry notification |
+| `sendSubscriptionCanceledEmail` | Cancellation confirmation |
+| `sendUpcomingInvoiceEmail` | Upcoming charge notification |
+| `sendPlanChangedEmail` | Plan upgrade/downgrade notice |
+| `sendLicenseCreatedEmail` | License key delivery email |
+
+## Configuration
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `RESEND_API_KEY` | Resend API key from https://resend.com/api-keys |
+| `EMAIL_FROM` | Verified sender address (default: `Nebutra <noreply@nebutra.ai>`) |

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@nebutra/email",
+  "version": "0.1.0",
+  "description": "Multi-provider transactional email (Resend, Nodemailer, Console)",
+  "private": false,
+  "license": "AGPL-3.0",
+  "type": "module",
+  "nebutra": {
+    "featureId": "email",
+    "category": "integrations",
+    "summary": "Multi-provider transactional email (Resend, Nodemailer, Console)"
+  },
+  "main": "./dist/index.js",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "resend": "^4.0.1"
+  },
+  "peerDependencies": {
+    "nodemailer": "^6.9.0"
+  },
+  "peerDependenciesMeta": {
+    "nodemailer": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/integrations/email#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/integrations/email"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist .turbo"
+  }
+}

package/src/__tests__/email-contract.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from "vitest";
+import {
+  EMAIL_TEMPLATE_CATALOG,
+  sendContactFormReceivedEmail,
+  sendInvitationEmail,
+  sendLicenseCreatedEmail,
+  sendMagicLinkEmail,
+  sendOrderConfirmationEmail,
+  sendPasswordResetEmail,
+  sendReceiptEmail,
+  sendWelcomeEmail,
+  sendWelcomeReactEmail,
+} from "../index";
+
+const SEND_HELPERS = {
+  sendContactFormReceivedEmail,
+  sendInvitationEmail,
+  sendLicenseCreatedEmail,
+  sendMagicLinkEmail,
+  sendOrderConfirmationEmail,
+  sendPasswordResetEmail,
+  sendReceiptEmail,
+  sendWelcomeEmail,
+  sendWelcomeReactEmail,
+} satisfies Record<string, unknown>;
+
+describe("@nebutra/email contract", () => {
+  it("keeps every catalog entry backed by a public send helper", () => {
+    expect(EMAIL_TEMPLATE_CATALOG.length).toBeGreaterThanOrEqual(9);
+
+    for (const template of EMAIL_TEMPLATE_CATALOG) {
+      expect(SEND_HELPERS).toHaveProperty(template.sendHelper);
+      expect(template.fileName).toMatch(/-email\.html$/);
+    }
+  });
+
+  it("keeps preview fixture filenames unique and safe for mail-preview exports", () => {
+    const fileNames = EMAIL_TEMPLATE_CATALOG.map((template) => template.fileName);
+    expect(new Set(fileNames).size).toBe(fileNames.length);
+
+    for (const fileName of fileNames) {
+      expect(fileName).not.toContain("/");
+      expect(fileName).not.toContain("\\");
+      expect(fileName).not.toContain("..");
+    }
+  });
+});

package/src/__tests__/provider.test.ts

@@ -0,0 +1,136 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { EmailProvider } from "../provider";
+import { ConsoleEmailProvider } from "../providers/console";
+
+describe("EmailProvider interface", () => {
+  it("defines the correct shape", () => {
+    const provider: EmailProvider = {
+      send: async () => ({ id: "test" }),
+      name: "test",
+    };
+
+    expect(provider.name).toBe("test");
+    expect(typeof provider.send).toBe("function");
+  });
+});
+
+describe("ConsoleEmailProvider", () => {
+  let provider: ConsoleEmailProvider;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let stdoutSpy: any;
+
+  beforeEach(() => {
+    provider = new ConsoleEmailProvider();
+    stdoutSpy = vi.spyOn(process.stdout, "write").mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stdoutSpy.mockRestore();
+  });
+
+  it("has the correct name", () => {
+    expect(provider.name).toBe("console");
+  });
+
+  it("returns a generated id on send", async () => {
+    const result = await provider.send({
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Hello</p>",
+      from: "noreply@nebutra.ai",
+    });
+
+    expect(result.id).toBeDefined();
+    expect(typeof result.id).toBe("string");
+    expect(result.id.length).toBeGreaterThan(0);
+  });
+
+  it("writes email details to stdout", async () => {
+    await provider.send({
+      to: "user@example.com",
+      subject: "Test Subject",
+      html: "<p>Hello</p>",
+      from: "Nebutra <noreply@nebutra.ai>",
+    });
+
+    const output = stdoutSpy.mock.calls.map((c: unknown[]) => c[0]).join("");
+    expect(output).toContain("user@example.com");
+    expect(output).toContain("Test Subject");
+    expect(output).toContain("noreply@nebutra.ai");
+  });
+
+  it("handles array recipients", async () => {
+    await provider.send({
+      to: ["a@test.com", "b@test.com"],
+      subject: "Multi",
+      html: "<p>Hi</p>",
+      from: "noreply@nebutra.ai",
+    });
+
+    const output = stdoutSpy.mock.calls.map((c: unknown[]) => c[0]).join("");
+    expect(output).toContain("a@test.com");
+    expect(output).toContain("b@test.com");
+  });
+
+  it("includes tags when provided", async () => {
+    await provider.send({
+      to: "user@example.com",
+      subject: "Tagged",
+      html: "<p>Hi</p>",
+      from: "noreply@nebutra.ai",
+      tags: [{ name: "type", value: "welcome" }],
+    });
+
+    const output = stdoutSpy.mock.calls.map((c: unknown[]) => c[0]).join("");
+    expect(output).toContain("welcome");
+  });
+});
+
+describe("getEmailProvider (factory)", () => {
+  const originalEnv = process.env;
+
+  beforeEach(async () => {
+    process.env = { ...originalEnv };
+    delete process.env.EMAIL_PROVIDER;
+    delete process.env.RESEND_API_KEY;
+    delete process.env.SMTP_HOST;
+    // Reset cached provider between tests
+    const { resetEmailProvider } = await import("../provider");
+    resetEmailProvider();
+  });
+
+  afterEach(() => {
+    process.env = originalEnv;
+  });
+
+  it("returns console provider when no credentials are set", async () => {
+    const { getEmailProvider } = await import("../provider");
+    const provider = getEmailProvider();
+    expect(provider.name).toBe("console");
+  });
+
+  it("returns console provider when EMAIL_PROVIDER=console", async () => {
+    process.env.EMAIL_PROVIDER = "console";
+    process.env.RESEND_API_KEY = "re_test_123"; // should be ignored
+    const { resetEmailProvider, getEmailProvider } = await import("../provider");
+    resetEmailProvider();
+    const provider = getEmailProvider();
+    expect(provider.name).toBe("console");
+  });
+
+  it("returns resend provider when RESEND_API_KEY is set", async () => {
+    process.env.RESEND_API_KEY = "re_test_123";
+    const { resetEmailProvider, getEmailProvider } = await import("../provider");
+    resetEmailProvider();
+    const provider = getEmailProvider();
+    expect(provider.name).toBe("resend");
+  });
+
+  it("returns nodemailer provider when SMTP_HOST is set", async () => {
+    process.env.SMTP_HOST = "smtp.example.com";
+    const { resetEmailProvider, getEmailProvider } = await import("../provider");
+    resetEmailProvider();
+    const provider = getEmailProvider();
+    expect(provider.name).toBe("nodemailer");
+  });
+});