@intelligo-dev/core 1.0.0-beta.1 → 1.0.0-beta.13

package/src/email/send.ts

@@ -0,0 +1,169 @@
+import { render } from "@react-email/components";
+import type React from "react";
+import { getEmailProvider, type EmailTemplateRef } from "./provider";
+
+// Wraps the provider with the deployment's sender (EMAIL_FROM), React Email
+// rendering, and up to 3 attempts with exponential backoff (1s, 2s, 4s) on
+// 5xx, 429 and network errors. Never throws; returns a result object.
+
+export interface SendEmailParams {
+  to: string | string[];
+  subject: string;
+  html: string;
+  /**
+   * Defaults to the EMAIL_FROM env var. There is no built-in sender: a
+   * provider that needs one refuses the send when neither is set.
+   */
+  from?: string;
+  replyTo?: string;
+  /**
+   * Provider-neutral template descriptor. Required by template-based
+   * providers (Loops); ignored by HTML-capable providers (Resend).
+   */
+  template?: EmailTemplateRef;
+}
+
+export interface SendEmailWithComponentParams {
+  to: string | string[];
+  subject: string;
+  /** A React Email component element. Will be rendered to HTML before sending. */
+  react: React.ReactElement;
+  /**
+   * Defaults to the EMAIL_FROM env var. There is no built-in sender: a
+   * provider that needs one refuses the send when neither is set.
+   */
+  from?: string;
+  replyTo?: string;
+  /**
+   * Provider-neutral template descriptor. Required by template-based
+   * providers (Loops); ignored by HTML-capable providers (Resend).
+   */
+  template?: EmailTemplateRef;
+}
+
+export interface SendEmailResult {
+  success: boolean;
+  id?: string;
+  error?: string;
+}
+
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 1000;
+
+/**
+ * Returns true if the error is a client error (4xx) that should NOT be retried.
+ */
+function isClientError(error: unknown): boolean {
+  if (error && typeof error === "object") {
+    const err = error as Record<string, unknown>;
+
+    // 429 is excluded: rate limits are transient and worth retrying.
+    if (typeof err.statusCode === "number") {
+      return (
+        err.statusCode >= 400 && err.statusCode < 500 && err.statusCode !== 429
+      );
+    }
+
+    if (typeof err.status === "number") {
+      return err.status >= 400 && err.status < 500 && err.status !== 429;
+    }
+
+    // Resend SDK error names that indicate client errors
+    const name = err.name as string | undefined;
+    if (
+      name === "validation_error" ||
+      name === "missing_required_field" ||
+      name === "invalid_api_Key"
+    ) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Sends an email through the configured provider, retrying transient
+ * failures. Takes raw HTML via `{ html }` or a React Email element via
+ * `{ react }`. Never throws: failures return `{ success: false, error }`.
+ */
+export async function sendEmail(
+  params: SendEmailParams | SendEmailWithComponentParams
+): Promise<SendEmailResult> {
+  try {
+    const provider = getEmailProvider();
+    const from = params.from ?? (process.env.EMAIL_FROM?.trim() || undefined);
+
+    const recipient = Array.isArray(params.to)
+      ? params.to.join(", ")
+      : params.to;
+
+    let html: string;
+    if ("react" in params) {
+      try {
+        html = await render(params.react);
+      } catch (renderError) {
+        const message =
+          renderError instanceof Error
+            ? renderError.message
+            : String(renderError);
+        console.error(`[Email] Failed to render React component: ${message}`);
+        return { success: false, error: `Template render failed: ${message}` };
+      }
+    } else {
+      html = params.html;
+    }
+
+    let lastError: unknown;
+
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+      try {
+        const result = await provider.send({
+          to: params.to,
+          subject: params.subject,
+          html,
+          from,
+          replyTo: params.replyTo,
+          template: params.template,
+        });
+
+        return { success: true, id: result.id };
+      } catch (error) {
+        lastError = error;
+        const message = error instanceof Error ? error.message : String(error);
+
+        if (isClientError(error)) {
+          console.error(
+            `[Email] Send failed for ${recipient} (client error, not retrying): ${message}`
+          );
+          return { success: false, error: message };
+        }
+
+        console.warn(
+          `[Email] Send attempt ${attempt}/${MAX_ATTEMPTS} failed for ${recipient}: ${message}`
+        );
+
+        if (attempt < MAX_ATTEMPTS) {
+          await delay(BASE_DELAY_MS * Math.pow(2, attempt - 1));
+        }
+      }
+    }
+
+    const finalMessage =
+      lastError instanceof Error ? lastError.message : String(lastError);
+    console.error(
+      `[Email] All ${MAX_ATTEMPTS} attempts failed for ${recipient}: ${params.subject}`
+    );
+
+    return { success: false, error: finalMessage };
+  } catch (error) {
+    // Catch-all for unexpected errors (e.g., getEmailProvider() failing)
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`[Email] Unexpected error: ${message}`);
+    return { success: false, error: message };
+  }
+}

package/src/email/senders.ts

@@ -0,0 +1,292 @@
+/**
+ * Typed wrappers that render a React Email template and send it. They never
+ * throw; each returns a SendEmailResult.
+ *
+ * Every sender attaches a stable `template` key and flat variables so
+ * template-based providers (Loops) can send the same email; HTML providers
+ * ignore it. Boolean variants use distinct keys (quota-warning /
+ * quota-exceeded, trial-warning / trial-depleted) because template providers
+ * branch per template, not per variable.
+ */
+
+import * as React from "react";
+import { emailBrand } from "./brand";
+import { sendEmail, type SendEmailResult } from "./send";
+import { formatMoney, type Money } from "../money";
+import {
+  WelcomeEmail,
+  VerifyEmailEmail,
+  PasswordResetEmail,
+  WorkspaceInvitationEmail,
+  QuotaWarningEmail,
+  TrialWarningEmail,
+  TrialExpiryEmail,
+  PaymentFailedEmail,
+  SubscriptionConfirmedEmail,
+} from "./templates";
+
+/** The locale the email copy is written in; amounts are formatted to match. */
+const EMAIL_LOCALE = "en";
+
+export async function sendWelcomeEmail(params: {
+  to: string;
+  userName: string;
+  dashboardUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: emailBrand().name
+      ? `Welcome to ${emailBrand().name}!`
+      : "Welcome!",
+    react: React.createElement(WelcomeEmail, {
+      userName: params.userName,
+      dashboardUrl: params.dashboardUrl,
+    }),
+    template: {
+      key: "welcome",
+      variables: {
+        userName: params.userName,
+        dashboardUrl: params.dashboardUrl,
+      },
+    },
+  });
+}
+
+export async function sendVerifyEmail(params: {
+  to: string;
+  userName: string;
+  verificationUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: "Verify your email address",
+    react: React.createElement(VerifyEmailEmail, {
+      userName: params.userName,
+      verificationUrl: params.verificationUrl,
+    }),
+    template: {
+      key: "verify-email",
+      variables: {
+        userName: params.userName,
+        verificationUrl: params.verificationUrl,
+      },
+    },
+  });
+}
+
+export async function sendPasswordResetEmail(params: {
+  to: string;
+  userName: string;
+  resetUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: "Reset your password",
+    react: React.createElement(PasswordResetEmail, {
+      userName: params.userName,
+      resetUrl: params.resetUrl,
+    }),
+    template: {
+      key: "password-reset",
+      variables: {
+        userName: params.userName,
+        resetUrl: params.resetUrl,
+      },
+    },
+  });
+}
+
+export async function sendInvitationEmail(params: {
+  to: string;
+  inviterName: string;
+  workspaceName: string;
+  role: string;
+  acceptUrl: string;
+  declineUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: `${params.inviterName} invited you to ${params.workspaceName}`,
+    react: React.createElement(WorkspaceInvitationEmail, {
+      inviterName: params.inviterName,
+      workspaceName: params.workspaceName,
+      role: params.role,
+      acceptUrl: params.acceptUrl,
+      declineUrl: params.declineUrl,
+    }),
+    template: {
+      key: "workspace-invitation",
+      variables: {
+        inviterName: params.inviterName,
+        workspaceName: params.workspaceName,
+        role: params.role,
+        acceptUrl: params.acceptUrl,
+        declineUrl: params.declineUrl,
+      },
+    },
+  });
+}
+
+/**
+ * Send the allowance warning or used-up email. `used` and `allowance`
+ * are money in the deployment's billing currency; the template and the
+ * provider variables receive them formatted.
+ */
+export async function sendQuotaWarningEmail(params: {
+  to: string;
+  workspaceName: string;
+  percentageUsed: number;
+  used: Money;
+  allowance: Money;
+  upgradeUrl: string;
+  isExceeded: boolean;
+}): Promise<SendEmailResult> {
+  const used = formatMoney(params.used, EMAIL_LOCALE);
+  const allowance = formatMoney(params.allowance, EMAIL_LOCALE);
+
+  return sendEmail({
+    to: params.to,
+    subject: params.isExceeded
+      ? "Monthly allowance used up"
+      : `Monthly allowance at ${params.percentageUsed}%`,
+    react: React.createElement(QuotaWarningEmail, {
+      workspaceName: params.workspaceName,
+      percentageUsed: params.percentageUsed,
+      used,
+      allowance,
+      upgradeUrl: params.upgradeUrl,
+      isExceeded: params.isExceeded,
+    }),
+    template: {
+      key: params.isExceeded ? "quota-exceeded" : "quota-warning",
+      variables: {
+        workspaceName: params.workspaceName,
+        percentageUsed: params.percentageUsed,
+        used,
+        allowance,
+        currency: params.allowance.currency,
+        upgradeUrl: params.upgradeUrl,
+      },
+    },
+  });
+}
+
+/** Send trial warning or depleted email. */
+export async function sendTrialWarningEmail(params: {
+  to: string;
+  workspaceName: string;
+  creditsRemaining: number;
+  totalCredits: number;
+  percentageRemaining: number;
+  upgradeUrl: string;
+  isDepleted: boolean;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: params.isDepleted
+      ? "Trial credits depleted"
+      : "Trial credits running low",
+    react: React.createElement(TrialWarningEmail, {
+      workspaceName: params.workspaceName,
+      creditsRemaining: params.creditsRemaining,
+      totalCredits: params.totalCredits,
+      percentageRemaining: params.percentageRemaining,
+      upgradeUrl: params.upgradeUrl,
+      isDepleted: params.isDepleted,
+    }),
+    template: {
+      key: params.isDepleted ? "trial-depleted" : "trial-warning",
+      variables: {
+        workspaceName: params.workspaceName,
+        creditsRemaining: params.creditsRemaining,
+        totalCredits: params.totalCredits,
+        percentageRemaining: params.percentageRemaining,
+        upgradeUrl: params.upgradeUrl,
+      },
+    },
+  });
+}
+
+export async function sendPaymentFailedEmail(params: {
+  to: string;
+  workspaceName: string;
+  amount: string;
+  updatePaymentUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: `Payment failed for ${params.workspaceName}`,
+    react: React.createElement(PaymentFailedEmail, {
+      workspaceName: params.workspaceName,
+      amount: params.amount,
+      updatePaymentUrl: params.updatePaymentUrl,
+    }),
+    template: {
+      key: "payment-failed",
+      variables: {
+        workspaceName: params.workspaceName,
+        amount: params.amount,
+        updatePaymentUrl: params.updatePaymentUrl,
+      },
+    },
+  });
+}
+
+export async function sendSubscriptionConfirmedEmail(params: {
+  to: string;
+  workspaceName: string;
+  planName: string;
+  amount: string;
+  dashboardUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject: `Subscription confirmed - ${params.planName} plan`,
+    react: React.createElement(SubscriptionConfirmedEmail, {
+      workspaceName: params.workspaceName,
+      planName: params.planName,
+      amount: params.amount,
+      dashboardUrl: params.dashboardUrl,
+    }),
+    template: {
+      key: "subscription-confirmed",
+      variables: {
+        workspaceName: params.workspaceName,
+        planName: params.planName,
+        amount: params.amount,
+        dashboardUrl: params.dashboardUrl,
+      },
+    },
+  });
+}
+
+export async function sendTrialExpiryEmail(params: {
+  to: string;
+  workspaceName: string;
+  expiryDate: string;
+  daysRemaining: number;
+  upgradeUrl: string;
+}): Promise<SendEmailResult> {
+  return sendEmail({
+    to: params.to,
+    subject:
+      params.daysRemaining <= 0
+        ? `Your trial for ${params.workspaceName} has ended`
+        : `Your trial ends in ${params.daysRemaining} day${params.daysRemaining === 1 ? "" : "s"}`,
+    react: React.createElement(TrialExpiryEmail, {
+      workspaceName: params.workspaceName,
+      expiryDate: params.expiryDate,
+      daysRemaining: params.daysRemaining,
+      upgradeUrl: params.upgradeUrl,
+    }),
+    template: {
+      key: "trial-expiry",
+      variables: {
+        workspaceName: params.workspaceName,
+        expiryDate: params.expiryDate,
+        daysRemaining: params.daysRemaining,
+        upgradeUrl: params.upgradeUrl,
+      },
+    },
+  });
+}

package/src/email/templates/base-layout.tsx

@@ -0,0 +1,145 @@
+import {
+  Body,
+  Container,
+  Head,
+  Hr,
+  Html,
+  Link,
+  Preview,
+  Section,
+  Text,
+} from "@react-email/components";
+import * as React from "react";
+
+import { emailBrand } from "../brand";
+
+// Inline styles only: email clients do not reliably support CSS classes.
+// Colors are literal values, not CSS variables, so they survive dark-mode
+// email clients.
+
+export interface BaseLayoutProps {
+  preview: string;
+  children: React.ReactNode;
+}
+
+const colors = {
+  background: "#f4f4f5", // zinc-100
+  container: "#ffffff",
+  text: "#18181b", // zinc-900
+  muted: "#71717a", // zinc-500
+  brand: "#7c3aed", // violet-600
+  border: "#e4e4e7", // zinc-200
+} as const;
+
+export function BaseLayout({ preview, children }: BaseLayoutProps) {
+  const brand = emailBrand();
+  return (
+    <Html lang="en">
+      <Head>
+        <meta charSet="utf-8" />
+      </Head>
+      <Preview>{preview}</Preview>
+      <Body style={bodyStyle}>
+        <Container style={containerStyle}>
+          {brand.name ? (
+            <Section style={headerStyle}>
+              <Text style={logoStyle}>{brand.name}</Text>
+            </Section>
+          ) : null}
+
+          <Hr style={hrStyle} />
+
+          <Section style={contentStyle}>{children}</Section>
+
+          <Hr style={hrStyle} />
+
+          <Section style={footerStyle}>
+            {brand.name ? (
+              <Text style={footerTextStyle}>{brand.name}</Text>
+            ) : null}
+            <Text style={footerMutedStyle}>
+              This is a transactional email
+              {brand.name ? ` from ${brand.name}` : ""}.
+              {brand.supportEmail ? (
+                <>
+                  {" "}
+                  If you believe you received this email in error, please
+                  contact{" "}
+                  <Link
+                    href={`mailto:${brand.supportEmail}`}
+                    style={footerLinkStyle}
+                  >
+                    {brand.supportEmail}
+                  </Link>
+                  .
+                </>
+              ) : null}
+            </Text>
+          </Section>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+const bodyStyle: React.CSSProperties = {
+  backgroundColor: colors.background,
+  fontFamily:
+    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  margin: 0,
+  padding: "40px 0",
+};
+
+const containerStyle: React.CSSProperties = {
+  backgroundColor: colors.container,
+  borderRadius: "8px",
+  maxWidth: "600px",
+  margin: "0 auto",
+  border: `1px solid ${colors.border}`,
+};
+
+const headerStyle: React.CSSProperties = {
+  padding: "32px 40px 16px",
+};
+
+const logoStyle: React.CSSProperties = {
+  color: colors.brand,
+  fontSize: "24px",
+  fontWeight: 700,
+  margin: 0,
+  lineHeight: "32px",
+};
+
+const hrStyle: React.CSSProperties = {
+  borderColor: colors.border,
+  borderTop: "none",
+  margin: 0,
+};
+
+const contentStyle: React.CSSProperties = {
+  padding: "24px 40px",
+};
+
+const footerStyle: React.CSSProperties = {
+  padding: "16px 40px 32px",
+};
+
+const footerTextStyle: React.CSSProperties = {
+  color: colors.muted,
+  fontSize: "13px",
+  lineHeight: "20px",
+  margin: "0 0 8px",
+  fontWeight: 600,
+};
+
+const footerMutedStyle: React.CSSProperties = {
+  color: colors.muted,
+  fontSize: "12px",
+  lineHeight: "18px",
+  margin: 0,
+};
+
+const footerLinkStyle: React.CSSProperties = {
+  color: colors.brand,
+  textDecoration: "underline",
+};

package/src/email/templates/index.ts

@@ -0,0 +1,28 @@
+export { BaseLayout, type BaseLayoutProps } from "./base-layout";
+export { WelcomeEmail, type WelcomeEmailProps } from "./welcome";
+export { VerifyEmailEmail, type VerifyEmailEmailProps } from "./verify-email";
+export {
+  PasswordResetEmail,
+  type PasswordResetEmailProps,
+} from "./password-reset";
+export {
+  WorkspaceInvitationEmail,
+  type WorkspaceInvitationEmailProps,
+} from "./workspace-invitation";
+export {
+  QuotaWarningEmail,
+  type QuotaWarningEmailProps,
+} from "./quota-warning";
+export {
+  TrialWarningEmail,
+  type TrialWarningEmailProps,
+} from "./trial-warning";
+export {
+  PaymentFailedEmail,
+  type PaymentFailedEmailProps,
+} from "./payment-failed";
+export {
+  SubscriptionConfirmedEmail,
+  type SubscriptionConfirmedEmailProps,
+} from "./subscription-confirmed";
+export { TrialExpiryEmail, type TrialExpiryEmailProps } from "./trial-expiry";

package/src/email/templates/password-reset.tsx

@@ -0,0 +1,72 @@
+import { Button, Text } from "@react-email/components";
+import * as React from "react";
+import { BaseLayout } from "./base-layout";
+
+export interface PasswordResetEmailProps {
+  userName: string;
+  resetUrl: string;
+}
+
+export function PasswordResetEmail({
+  userName,
+  resetUrl,
+}: PasswordResetEmailProps) {
+  const text = {
+    preview: "Reset your password",
+    heading: "Reset your password",
+    greeting: "Hi",
+    body: "We received a request to reset your password. Click the button below to choose a new one.",
+    button: "Reset Password",
+    note: "This link expires in 1 hour. If you didn't request a password reset, you can safely ignore this email.",
+  };
+
+  return (
+    <BaseLayout preview={text.preview}>
+      <Text style={headingStyle}>{text.heading}</Text>
+      <Text style={bodyTextStyle}>
+        {text.greeting} {userName},
+      </Text>
+      <Text style={bodyTextStyle}>{text.body}</Text>
+      <Button href={resetUrl} style={buttonStyle}>
+        {text.button}
+      </Button>
+      <Text style={noteStyle}>{text.note}</Text>
+    </BaseLayout>
+  );
+}
+
+const headingStyle: React.CSSProperties = {
+  color: "#18181b",
+  fontSize: "22px",
+  fontWeight: 700,
+  lineHeight: "30px",
+  margin: "0 0 16px",
+};
+
+const bodyTextStyle: React.CSSProperties = {
+  color: "#18181b",
+  fontSize: "15px",
+  lineHeight: "24px",
+  margin: "0 0 12px",
+};
+
+const buttonStyle: React.CSSProperties = {
+  backgroundColor: "#7c3aed",
+  borderRadius: "6px",
+  color: "#ffffff",
+  display: "inline-block",
+  fontSize: "15px",
+  fontWeight: 600,
+  lineHeight: "100%",
+  padding: "12px 24px",
+  textDecoration: "none",
+  textAlign: "center" as const,
+  marginTop: "8px",
+};
+
+const noteStyle: React.CSSProperties = {
+  color: "#71717a",
+  fontSize: "13px",
+  lineHeight: "20px",
+  marginTop: "20px",
+};