@nebutra/email 0.1.0 → 0.1.2

package/README.md

@@ -1,12 +1,14 @@
 # @nebutra/email
 
-> Transactional email service powered by Resend with branded HTML templates.
+Multi-provider transactional email for Nebutra products.
+
+The package auto-detects Resend, Nodemailer SMTP, or a console development
+provider, then sends branded HTML templates through a single API.
 
 ## Installation
 
 ```bash
-# Internal monorepo dependency
-pnpm add @nebutra/email@workspace:*
+pnpm add @nebutra/email
 ```
 
 ## Usage
@@ -53,5 +55,20 @@ await sendApiKeyCreatedEmail({
 
 | Environment Variable | Description |
 |---------------------|-------------|
+| `EMAIL_PROVIDER` | Optional explicit provider: `resend`, `nodemailer`, or `console` |
 | `RESEND_API_KEY` | Resend API key from https://resend.com/api-keys |
-| `EMAIL_FROM` | Verified sender address (default: `Nebutra <noreply@nebutra.ai>`) |
+| `SMTP_HOST` | Enables Nodemailer SMTP provider when Resend is not configured |
+| `SMTP_PORT` / `SMTP_USER` / `SMTP_PASS` / `SMTP_SECURE` | SMTP provider settings |
+| `EMAIL_FROM` | Verified sender address (default: `Nebutra <noreply@nebutra.com>`) |
+
+## Providers
+
+| Provider | Selection |
+| --- | --- |
+| `resend` | `EMAIL_PROVIDER=resend` or `RESEND_API_KEY` present |
+| `nodemailer` | `EMAIL_PROVIDER=nodemailer` or `SMTP_HOST` present |
+| `console` | Explicit `EMAIL_PROVIDER=console` or development/test fallback |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,415 @@
+/**
+ * @nebutra/email — Provider abstraction
+ *
+ * Supports multiple email providers via auto-detection:
+ *   1. EMAIL_PROVIDER env var (explicit)
+ *   2. RESEND_API_KEY → Resend
+ *   3. SMTP_HOST → Nodemailer
+ *   4. Fallback → Console (dev/test)
+ */
+interface SendOptions {
+    to: string | string[];
+    subject: string;
+    html: string;
+    from: string;
+    replyTo?: string;
+    tags?: {
+        name: string;
+        value: string;
+    }[];
+}
+interface SendResult {
+    id: string;
+}
+interface EmailProvider {
+    readonly name: string;
+    send(opts: SendOptions): Promise<SendResult>;
+}
+type EmailProviderType = "resend" | "nodemailer" | "console";
+declare function getEmailProvider(): EmailProvider;
+declare function resetEmailProvider(): void;
+
+/**
+ * Console email provider — prints email details to stdout.
+ * Perfect for local development and testing without API keys.
+ */
+
+declare class ConsoleEmailProvider implements EmailProvider {
+    readonly name: "console";
+    send(opts: SendOptions): Promise<SendResult>;
+}
+
+/**
+ * Nodemailer email provider — SMTP-based, self-hosted fallback.
+ * Requires SMTP_HOST (+ optional SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE).
+ */
+
+interface NodemailerConfig {
+    host: string;
+    port: number;
+    secure: boolean;
+    auth?: {
+        user: string;
+        pass: string;
+    } | undefined;
+}
+declare class NodemailerEmailProvider implements EmailProvider {
+    readonly name: "nodemailer";
+    private config;
+    private transporter;
+    constructor(config: NodemailerConfig);
+    private getTransporter;
+    send(opts: SendOptions): Promise<SendResult>;
+}
+
+/**
+ * Resend email provider — production-grade transactional email.
+ * Requires RESEND_API_KEY environment variable.
+ */
+
+declare class ResendEmailProvider implements EmailProvider {
+    readonly name: "resend";
+    private client;
+    constructor(apiKey: string);
+    send(opts: SendOptions): Promise<SendResult>;
+}
+
+/**
+ * ReceiptEmail — payment confirmation with billing period and invoice download.
+ *
+ * react-email is not installed; this module exposes the same
+ * `{ subject, preview, render }` contract using a plain template literal so the
+ * catalog can be migrated to React Email later without changing call sites.
+ */
+interface ReceiptEmailProps {
+    customerName: string;
+    invoiceNumber: string;
+    amount: string;
+    currency: string;
+    periodStart: string;
+    periodEnd: string;
+    downloadUrl: string;
+    brandName: string;
+}
+declare function subject$3(props: ReceiptEmailProps): string;
+declare function preview$3(props: ReceiptEmailProps): string;
+declare function render$3(props: ReceiptEmailProps): string;
+declare const receiptEmail: {
+    readonly subject: typeof subject$3;
+    readonly preview: typeof preview$3;
+    readonly render: typeof render$3;
+};
+
+/**
+ * InvitationEmail — workspace member invitation with role and expiry.
+ *
+ * react-email is not installed; this module exposes the same
+ * `{ subject, preview, render }` contract using a plain template literal so the
+ * catalog can be migrated to React Email later without changing call sites.
+ */
+interface InvitationEmailProps {
+    inviterName: string;
+    organizationName: string;
+    role: string;
+    acceptUrl: string;
+    expiresAt: string;
+    brandName: string;
+}
+declare function subject$2(props: InvitationEmailProps): string;
+declare function preview$2(props: InvitationEmailProps): string;
+declare function render$2(props: InvitationEmailProps): string;
+declare const invitationEmail: {
+    readonly subject: typeof subject$2;
+    readonly preview: typeof preview$2;
+    readonly render: typeof render$2;
+};
+
+/**
+ * PasswordResetEmail — secure password reset link with expiry.
+ *
+ * react-email is not installed; this module exposes the same
+ * `{ subject, preview, render }` contract using a plain template literal so the
+ * catalog can be migrated to React Email later without changing call sites.
+ */
+interface PasswordResetEmailProps {
+    userName: string;
+    resetUrl: string;
+    expiresInMinutes: number;
+    brandName: string;
+}
+declare function subject$1(props: PasswordResetEmailProps): string;
+declare function preview$1(props: PasswordResetEmailProps): string;
+declare function render$1(props: PasswordResetEmailProps): string;
+declare const passwordResetEmail: {
+    readonly subject: typeof subject$1;
+    readonly preview: typeof preview$1;
+    readonly render: typeof render$1;
+};
+
+/**
+ * WelcomeEmail — onboarding welcome message for new accounts.
+ *
+ * react-email is not installed; this module exposes the same
+ * `{ subject, preview, render }` contract using a plain template literal so the
+ * catalog can be migrated to React Email later without changing call sites.
+ */
+interface WelcomeEmailProps {
+    userName: string;
+    loginUrl: string;
+    brandName: string;
+}
+declare function subject(props: WelcomeEmailProps): string;
+declare function preview(_props: WelcomeEmailProps): string;
+declare function render(props: WelcomeEmailProps): string;
+declare const welcomeEmail: {
+    readonly subject: typeof subject;
+    readonly preview: typeof preview;
+    readonly render: typeof render;
+};
+
+/**
+ * Shared HTML layout for the React Email-style template catalog.
+ *
+ * NOTE: react-email is NOT installed in this workspace. This module ships a
+ * plain template literal layout instead so the templates remain framework-free
+ * and can be rendered without a React runtime. The contract still mirrors a
+ * future React Email migration: each template module exports
+ * `{ subject, preview, render }` and the renderer returns a complete HTML
+ * document.
+ */
+interface RenderedEmail {
+    html: string;
+    subject: string;
+    preview: string;
+}
+
+/**
+ * Stable shape of a registered template entry for the React Email-style
+ * catalog. Distinct from `EMAIL_TEMPLATE_CATALOG` in `../index.ts` which tracks
+ * the legacy `send*Email` helper surface.
+ */
+interface ReactEmailTemplate<P> {
+    id: string;
+    label: string;
+    description: string;
+    fileName: string;
+    subject: (props: P) => string;
+    preview: (props: P) => string;
+    render: (props: P) => string;
+}
+declare const REACT_EMAIL_TEMPLATES: {
+    readonly welcome: {
+        readonly subject: typeof subject;
+        readonly preview: typeof preview;
+        readonly render: typeof render;
+        readonly id: "welcome-react";
+        readonly label: "Welcome (React Email)";
+        readonly description: "Account onboarding welcome message";
+        readonly fileName: "welcome-react-email.html";
+    };
+    readonly passwordReset: {
+        readonly subject: typeof subject$1;
+        readonly preview: typeof preview$1;
+        readonly render: typeof render$1;
+        readonly id: "password-reset";
+        readonly label: "Password Reset";
+        readonly description: "Secure password reset link with expiry";
+        readonly fileName: "password-reset-email.html";
+    };
+    readonly invitation: {
+        readonly subject: typeof subject$2;
+        readonly preview: typeof preview$2;
+        readonly render: typeof render$2;
+        readonly id: "invitation";
+        readonly label: "Invitation";
+        readonly description: "Workspace invitation with role and expiry";
+        readonly fileName: "invitation-email.html";
+    };
+    readonly receipt: {
+        readonly subject: typeof subject$3;
+        readonly preview: typeof preview$3;
+        readonly render: typeof render$3;
+        readonly id: "receipt";
+        readonly label: "Receipt";
+        readonly description: "Payment receipt with billing period and PDF link";
+        readonly fileName: "receipt-email.html";
+    };
+};
+
+/**
+ * @nebutra/email — Multi-provider transactional email
+ *
+ * Provider-agnostic email system with auto-detection:
+ *   1. EMAIL_PROVIDER env var (explicit: "resend" | "nodemailer" | "console")
+ *   2. RESEND_API_KEY present → Resend
+ *   3. SMTP_HOST present → Nodemailer (SMTP)
+ *   4. Fallback → Console (dev/test, no API key needed)
+ *
+ * Usage:
+ *   import { sendWelcomeEmail, sendApiKeyCreatedEmail } from "@nebutra/email";
+ *   await sendWelcomeEmail({ to: "user@example.com", orgName: "Acme Corp" });
+ *
+ * Environment variables:
+ *   EMAIL_PROVIDER  — explicit provider override (optional)
+ *   EMAIL_FROM      — verified sender (e.g. getBrandMailFrom() example)
+ *   RESEND_API_KEY  — for Resend provider
+ *   SMTP_HOST       — for Nodemailer provider (+ SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_SECURE)
+ */
+
+interface EmailTemplateCatalogEntry {
+    id: string;
+    label: string;
+    description: string;
+    sendHelper: string;
+    fileName: string;
+}
+declare const EMAIL_TEMPLATE_CATALOG: readonly [{
+    readonly id: "welcome";
+    readonly label: "Welcome";
+    readonly description: "Workspace provisioning welcome email";
+    readonly sendHelper: "sendWelcomeEmail";
+    readonly fileName: "welcome-email.html";
+}, {
+    readonly id: "order-confirmation";
+    readonly label: "Order Confirmation";
+    readonly description: "Commerce order receipt with line items";
+    readonly sendHelper: "sendOrderConfirmationEmail";
+    readonly fileName: "order-confirmation-email.html";
+}, {
+    readonly id: "magic-link";
+    readonly label: "Magic Link";
+    readonly description: "Passwordless sign-in link";
+    readonly sendHelper: "sendMagicLinkEmail";
+    readonly fileName: "magic-link-email.html";
+}, {
+    readonly id: "email-change";
+    readonly label: "Email Change";
+    readonly description: "Confirm a new account email address";
+    readonly sendHelper: "sendEmailChangeEmail";
+    readonly fileName: "email-change-email.html";
+}, {
+    readonly id: "contact-form-received";
+    readonly label: "Contact Form Received";
+    readonly description: "Contact form acknowledgement";
+    readonly sendHelper: "sendContactFormReceivedEmail";
+    readonly fileName: "contact-form-received-email.html";
+}, {
+    readonly id: "license-created";
+    readonly label: "License Created";
+    readonly description: "License key delivery email";
+    readonly sendHelper: "sendLicenseCreatedEmail";
+    readonly fileName: "license-created-email.html";
+}, {
+    readonly id: "welcome-react";
+    readonly label: "Welcome (React Email)";
+    readonly description: "Account onboarding welcome message";
+    readonly sendHelper: "sendWelcomeReactEmail";
+    readonly fileName: "welcome-react-email.html";
+}, {
+    readonly id: "password-reset";
+    readonly label: "Password Reset";
+    readonly description: "Secure password reset link with expiry";
+    readonly sendHelper: "sendPasswordResetEmail";
+    readonly fileName: "password-reset-email.html";
+}, {
+    readonly id: "invitation";
+    readonly label: "Invitation";
+    readonly description: "Workspace invitation with role and expiry";
+    readonly sendHelper: "sendInvitationEmail";
+    readonly fileName: "invitation-email.html";
+}, {
+    readonly id: "receipt";
+    readonly label: "Receipt";
+    readonly description: "Payment receipt with billing period and PDF link";
+    readonly sendHelper: "sendReceiptEmail";
+    readonly fileName: "receipt-email.html";
+}];
+/**
+ * Welcome email sent when a new organization is provisioned.
+ */
+declare function sendWelcomeEmail(opts: {
+    to: string;
+    firstName: string;
+    orgName: string;
+    dashboardUrl?: string;
+}): Promise<SendResult>;
+/**
+ * Order confirmation email sent when an order successfully completes.
+ */
+declare function sendOrderConfirmationEmail(opts: {
+    to: string;
+    orderId: string;
+    /** Order total in minor units (integer cents). */
+    totalAmount: number;
+    /** ISO 4217 currency code (default "USD"). */
+    currency?: string;
+    /** BCP 47 locale tag (default "en-US"). */
+    locale?: string;
+    items: Array<{
+        productId: string;
+        quantity: number | string;
+    }>;
+}): Promise<SendResult>;
+/**
+ * Shipfast-style Magic Link Email for 1-click Authentication.
+ */
+declare function sendMagicLinkEmail(opts: {
+    to: string;
+    magicLinkUrl: string;
+}): Promise<SendResult>;
+/**
+ * Email-change verification sent to the *new* address (TODO #126).
+ * Confirming the link flips the account email.
+ */
+declare function sendEmailChangeEmail(opts: {
+    to: string;
+    confirmUrl: string;
+    /** Optional display name for the new address (defaults to `to`). */
+    newEmail?: string;
+}): Promise<SendResult>;
+/**
+ * Contact Form Receipt (Sent to the User)
+ */
+declare function sendContactFormReceivedEmail(opts: {
+    to: string;
+    name: string;
+    subject: string;
+}): Promise<SendResult>;
+/**
+ * License created email sent when a user claims their OPC/STARTUP license.
+ */
+declare function sendLicenseCreatedEmail(opts: {
+    to: string;
+    firstName: string;
+    licenseKey: string;
+    tier: string;
+}): Promise<SendResult>;
+
+/**
+ * Send the React Email-style welcome message. Mirrors `WelcomeEmailProps`
+ * exactly so callers can compose messages without depending on the legacy
+ * `sendWelcomeEmail` signature.
+ */
+declare function sendWelcomeReactEmail(opts: {
+    to: string;
+} & WelcomeEmailProps): Promise<SendResult>;
+/**
+ * Send a password reset email with a tokenized link and expiry note.
+ */
+declare function sendPasswordResetEmail(opts: {
+    to: string;
+} & PasswordResetEmailProps): Promise<SendResult>;
+/**
+ * Send a workspace invitation with role and accept link.
+ */
+declare function sendInvitationEmail(opts: {
+    to: string;
+} & InvitationEmailProps): Promise<SendResult>;
+/**
+ * Send a payment receipt with billing period and PDF download URL.
+ */
+declare function sendReceiptEmail(opts: {
+    to: string;
+} & ReceiptEmailProps): Promise<SendResult>;
+
+export { ConsoleEmailProvider, EMAIL_TEMPLATE_CATALOG, type EmailProvider, type EmailProviderType, type EmailTemplateCatalogEntry, type InvitationEmailProps, NodemailerEmailProvider, type PasswordResetEmailProps, REACT_EMAIL_TEMPLATES, type ReactEmailTemplate, type ReceiptEmailProps, type RenderedEmail, ResendEmailProvider, type SendOptions, type SendResult, type WelcomeEmailProps, getEmailProvider, invitationEmail, passwordResetEmail, receiptEmail, render$2 as renderInvitationEmail, render$1 as renderPasswordResetEmail, render$3 as renderReceiptEmail, render as renderWelcomeEmail, resetEmailProvider, sendContactFormReceivedEmail, sendEmailChangeEmail, sendInvitationEmail, sendLicenseCreatedEmail, sendMagicLinkEmail, sendOrderConfirmationEmail, sendPasswordResetEmail, sendReceiptEmail, sendWelcomeEmail, sendWelcomeReactEmail, welcomeEmail };