create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/lib/email-service.ts

@@ -0,0 +1,118 @@
+import 'server-only'
+
+import { render, toPlainText } from '@react-email/render'
+import InvitationEmail, { InvitationEmailProps } from '~/emails/invitation'
+import MagicLinkEmail, { MagicLinkEmailProps } from '~/emails/magic-link'
+import WelcomeEmail, { WelcomeEmailProps } from '~/emails/welcome'
+import { sendEmail } from './nodemailer'
+
+/**
+ * Mapping of template types to their corresponding props
+ */
+type EmailTemplateMap = {
+  welcome: WelcomeEmailProps
+  magicLink: MagicLinkEmailProps
+  invitation: InvitationEmailProps
+}
+
+type EmailTemplateType = keyof EmailTemplateMap
+
+// Map of email template components with proper type safety
+const componentMap: Record<
+  EmailTemplateType,
+  (props: EmailTemplateMap[EmailTemplateType]) => React.ReactElement
+> = {
+  welcome: props => WelcomeEmail(props as WelcomeEmailProps),
+  magicLink: props => MagicLinkEmail(props as MagicLinkEmailProps),
+  invitation: props => InvitationEmail(props as InvitationEmailProps)
+}
+
+/**
+ * Generic email template renderer with type-safe overloads
+ */
+async function renderEmailTemplate<T extends EmailTemplateType>(
+  templateType: T,
+  props: EmailTemplateMap[T]
+): Promise<{ html: string; text: string }>
+
+async function renderEmailTemplate(
+  templateType: EmailTemplateType,
+  props: EmailTemplateMap[EmailTemplateType]
+) {
+  'use step'
+
+  const emailComponent = componentMap[templateType](props)
+
+  const html = await render(emailComponent)
+  const text = toPlainText(html)
+  return { html, text }
+}
+
+/**
+ * Sends welcome email to newly registered users
+ *
+ * @param to - Recipient email address
+ * @param props - Welcome email template props
+ * @returns Promise resolving to SentMessageInfo from nodemailer
+ * @throws Error if sending the email fails
+ */
+export async function sendWelcomeEmail(to: string, props: WelcomeEmailProps) {
+  'use workflow'
+
+  const { html, text } = await renderEmailTemplate('welcome', props)
+
+  return await sendEmail({
+    to,
+    subject: `Welcome to ${props.companyName}! 🎉`,
+    html,
+    text
+  })
+}
+
+/**
+ * Sends magic link email for passwordless authentication
+ *
+ * @param to - Recipient email address
+ * @param props - Magic link email template props
+ * @returns Promise resolving to SentMessageInfo from nodemailer
+ * @throws Error if sending the email fails
+ */
+export async function sendMagicLinkEmail(
+  to: string,
+  props: MagicLinkEmailProps
+) {
+  'use workflow'
+
+  const { html, text } = await renderEmailTemplate('magicLink', props)
+
+  return await sendEmail({
+    to,
+    subject: `Sign in to ${props.companyName}`,
+    html,
+    text
+  })
+}
+
+/**
+ * Sends an organization invitation email
+ *
+ * @param to - Recipient email address
+ * @param props - Invitation email template props
+ * @returns Promise resolving to SentMessageInfo from nodemailer
+ * @throws Error if sending the email fails
+ */
+export async function sendInvitationEmail(
+  to: string,
+  props: InvitationEmailProps
+) {
+  'use workflow'
+
+  const { html, text } = await renderEmailTemplate('invitation', props)
+
+  return await sendEmail({
+    to,
+    subject: `${props.inviterName} invited you to join ${props.organizationName}`,
+    html,
+    text
+  })
+}

package/template/saas-starter/src/lib/errors.ts

@@ -0,0 +1,74 @@
+/**
+ * Expected, user-safe action failures.
+ *
+ * Throw these for domain and authorization failures. The safe-action
+ * `handleServerError` returns {@link AppError.message} to the client and
+ * records the code on the active span. Unexpected errors stay masked.
+ *
+ * Do not put stack traces, SQL, or internal IDs in `message`.
+ */
+export const AppErrorCode = {
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  QUOTA_EXCEEDED: 'QUOTA_EXCEEDED',
+  FEATURE_NOT_INCLUDED: 'FEATURE_NOT_INCLUDED',
+  BAD_REQUEST: 'BAD_REQUEST',
+  INTERNAL: 'INTERNAL'
+} as const
+
+export type AppErrorCode = (typeof AppErrorCode)[keyof typeof AppErrorCode]
+
+export class AppError extends Error {
+  readonly code: AppErrorCode
+  readonly meta?: Record<string, unknown>
+
+  constructor(
+    code: AppErrorCode,
+    message: string,
+    meta?: Record<string, unknown>
+  ) {
+    super(message)
+    this.name = 'AppError'
+    this.code = code
+    this.meta = meta
+  }
+}
+
+export function isAppError(error: unknown): error is AppError {
+  return error instanceof AppError
+}
+
+/**
+ * The Postgres SQLSTATE of a failed query. Drizzle wraps driver errors and
+ * keeps the original on `cause`, so read both.
+ */
+function postgresCode(error: unknown, depth = 0): unknown {
+  // Drizzle adds one layer; the cap stops an error whose cause points back at
+  // itself from looping forever.
+  if (depth > 5 || typeof error !== 'object' || error === null) return undefined
+  if ('code' in error && typeof error.code === 'string') return error.code
+  return 'cause' in error ? postgresCode(error.cause, depth + 1) : undefined
+}
+
+export function isUniqueViolation(error: unknown): boolean {
+  return postgresCode(error) === '23505'
+}
+
+/**
+ * True when a delete or update is refused because another row still points at
+ * the row: a foreign key violation, or a `restrict` violation for keys declared
+ * `onDelete: 'restrict'`.
+ */
+export function isForeignKeyViolation(error: unknown): boolean {
+  const code = postgresCode(error)
+  return code === '23503' || code === '23001'
+}
+
+export function rethrowUniqueViolation(error: unknown, message: string): never {
+  if (isUniqueViolation(error)) {
+    throw new AppError(AppErrorCode.CONFLICT, message)
+  }
+  throw error
+}

package/template/saas-starter/src/lib/format-currency.ts

@@ -0,0 +1,25 @@
+const formatters = new Map<string, Intl.NumberFormat>()
+
+/**
+ * Formats an amount in its currency, such as `$20.00` or `€20.00`.
+ * `Intl` picks the symbol and the minor digits from the ISO currency code.
+ *
+ * @example
+ * formatCurrency('USD', 20) // '$20.00'
+ */
+export function formatCurrency(
+  currencyCode: string,
+  value: number | string
+): string {
+  let formatter = formatters.get(currencyCode)
+  if (!formatter) {
+    formatter = new Intl.NumberFormat('en-US', {
+      style: 'currency',
+      currency: currencyCode,
+      currencyDisplay: 'narrowSymbol',
+      signDisplay: 'negative'
+    })
+    formatters.set(currencyCode, formatter)
+  }
+  return formatter.format(Number(value))
+}

package/template/saas-starter/src/lib/format-date.ts

@@ -0,0 +1,75 @@
+export type DateFormatOptions = {
+  /** Abbreviated month ("Jan") instead of the full name. */
+  short?: boolean
+  /** Append the time of day. */
+  time?: boolean
+  /** Drop the year. */
+  noYear?: boolean
+  /** Render in this IANA zone instead of the viewer's. */
+  timeZone?: string
+}
+
+function asValidDate(
+  date: Date | string | number | null | undefined
+): Date | null {
+  if (date == null) return null
+  const instant = new Date(date)
+  return Number.isFinite(instant.getTime()) ? instant : null
+}
+
+/**
+ * Date and time are formatted separately and joined with a fixed " at ",
+ * because the connector ICU inserts between them changed across versions
+ * (", " in ICU 72 and later). Bun, Node, and each browser ship different ICU
+ * data, so one `toLocaleString` call renders differently per viewer and
+ * breaks hydration.
+ */
+function joinDateAndTime(
+  instant: Date,
+  dateOptions: Intl.DateTimeFormatOptions,
+  timeOptions: Intl.DateTimeFormatOptions,
+  timeZone: string | undefined
+): string {
+  const zone = timeZone ? { timeZone } : {}
+  const datePart = instant.toLocaleDateString('en-US', {
+    ...dateOptions,
+    ...zone
+  })
+  const timePart = instant.toLocaleTimeString('en-US', {
+    ...timeOptions,
+    ...zone
+  })
+  return `${datePart} at ${timePart}`
+}
+
+/**
+ * Formats a date as an `en-US` string, such as "March 3, 2026".
+ * Returns `-` for a missing or invalid date.
+ */
+export const formatDate = (
+  date: Date | string | number | null | undefined,
+  options?: DateFormatOptions
+): string => {
+  const instant = asValidDate(date)
+  if (!instant) return '-'
+
+  const dateOptions: Intl.DateTimeFormatOptions = {
+    ...(options?.noYear ? {} : { year: 'numeric' }),
+    month: options?.short ? 'short' : 'long',
+    day: 'numeric'
+  }
+
+  if (!options?.time) {
+    return instant.toLocaleDateString('en-US', {
+      ...dateOptions,
+      ...(options?.timeZone ? { timeZone: options.timeZone } : {})
+    })
+  }
+
+  return joinDateAndTime(
+    instant,
+    dateOptions,
+    { hour: '2-digit', minute: '2-digit' },
+    options.timeZone
+  )
+}

package/template/saas-starter/src/lib/image-url.ts

@@ -0,0 +1,54 @@
+/**
+ * Image field formats stored on organizations.
+ *
+ * Client-safe: no env, DB, or server-only imports. Zod schemas and
+ * `resolveImageUrl` share these predicates so only R2 keys and data image
+ * URLs reach the renderer.
+ */
+import {
+  R2_UPLOAD_EXTENSION_BY_MIME_TYPE,
+  type R2UploadMimeType
+} from '~/lib/constants'
+
+const IMAGE_EXTENSIONS = Object.values(R2_UPLOAD_EXTENSION_BY_MIME_TYPE)
+const IMAGE_SUBTYPES = (
+  Object.keys(R2_UPLOAD_EXTENSION_BY_MIME_TYPE) as R2UploadMimeType[]
+).map(mime => mime.slice('image/'.length))
+
+const R2_OBJECT_KEY_RE = new RegExp(
+  `^uploads/organizations/[a-z0-9_-]+/[a-zA-Z0-9._-]+\\.(${IMAGE_EXTENSIONS.join('|')})$`
+)
+const DATA_IMAGE_URL_RE = new RegExp(
+  `^data:image/(?:${IMAGE_SUBTYPES.join('|')});base64,[A-Za-z0-9+/]+={0,2}$`
+)
+
+/** True when `value` is an owned-upload key (`uploads/organizations/<id>/<file>.<ext>`). */
+export function isR2ObjectKey(value: string): boolean {
+  return R2_OBJECT_KEY_RE.test(value)
+}
+
+/** True when `value` is a `data:image/*;base64,...` URL of an allowed MIME type. */
+export function isDataImageUrl(value: string): boolean {
+  return DATA_IMAGE_URL_RE.test(value)
+}
+
+/** True when `value` is an R2 object key or a data image URL. */
+export function isStoredImageValue(value: string): boolean {
+  return isR2ObjectKey(value) || isDataImageUrl(value)
+}
+
+/**
+ * Persist rules after format checks.
+ *
+ * R2 keys are always eligible (ownership is a separate DB check). Data URLs
+ * are only eligible when R2 is off; otherwise they skip the upload tracking
+ * and inline megabytes into every page that shows the image.
+ */
+export function canPersistImageValue(
+  value: string,
+  r2Configured: boolean
+): boolean {
+  if (isR2ObjectKey(value)) return true
+  if (isDataImageUrl(value)) return !r2Configured
+  return false
+}

package/template/saas-starter/src/lib/nodemailer.ts

@@ -0,0 +1,67 @@
+import 'server-only'
+
+import nodemailer, { SentMessageInfo } from 'nodemailer'
+import { env } from '~/env'
+import { AppError, AppErrorCode } from './errors'
+
+/**
+ * Configure the email transporter using environment variables.
+ * Uses nodemailer for sending emails via SMTP.
+ */
+const transporter = nodemailer.createTransport({
+  host: env.EMAIL_SERVER_HOST,
+  port: env.EMAIL_SERVER_PORT,
+  secure: env.EMAIL_SERVER_PORT === 465, // Use secure for port 465, false for other ports
+  auth: {
+    user: env.EMAIL_SERVER_USER,
+    pass: env.EMAIL_SERVER_PASSWORD
+  }
+})
+
+/**
+ * Interface for the email payload
+ */
+interface SendEmailParams {
+  to: string
+  subject: string
+  text?: string
+  html?: string
+}
+
+/**
+ * Sends an email using the configured transporter.
+ *
+ * @param {SendEmailParams} params - The email parameters.
+ * @param {string} params.to - The recipient's email address.
+ * @param {string} params.subject - The subject of the email.
+ * @param {string} [params.text] - The plain text content of the email.
+ * @param {string} [params.html] - The HTML content of the email (optional).
+ * @returns {Promise<any>} Resolves when the email is sent successfully.
+ * @throws {Error} If sending the email fails.
+ */
+export const sendEmail = async ({
+  to,
+  subject,
+  text,
+  html
+}: SendEmailParams): Promise<SentMessageInfo> => {
+  'use step'
+
+  try {
+    const info = await transporter.sendMail({
+      from: env.EMAIL_FROM,
+      to,
+      subject,
+      text,
+      html
+    })
+
+    return info
+  } catch (error) {
+    console.error('Error sending email:', error)
+    throw new AppError(
+      AppErrorCode.INTERNAL,
+      'The email was not sent. Try again.'
+    )
+  }
+}

package/template/saas-starter/src/lib/organization-access.ts

@@ -0,0 +1,73 @@
+import 'server-only'
+
+import { and, eq, inArray } from 'drizzle-orm'
+import { db } from '~/db'
+import { membersTable } from '~/db/schema'
+import { AppError, AppErrorCode } from './errors'
+import type { OrganizationRole } from './rbac'
+
+/**
+ * The caller's membership in an organization, or null when they have none.
+ */
+export async function getMembership(organizationId: string, userId: string) {
+  const membership = await db.query.membersTable.findFirst({
+    where: and(
+      eq(membersTable.organizationId, organizationId),
+      eq(membersTable.userId, userId)
+    ),
+    columns: { id: true, role: true }
+  })
+
+  return membership ?? null
+}
+
+/**
+ * Asserts the caller belongs to the organization, in any role.
+ * Throws {@link AppError} with code FORBIDDEN otherwise.
+ */
+export async function assertMember(organizationId: string, userId: string) {
+  const membership = await getMembership(organizationId, userId)
+  if (!membership) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have access to this organization.'
+    )
+  }
+  return membership
+}
+
+/**
+ * Asserts the caller holds one of `allowedRoles` in the organization.
+ */
+export async function assertRole(
+  organizationId: string,
+  userId: string,
+  allowedRoles: ReadonlyArray<OrganizationRole>
+) {
+  const membership = await db.query.membersTable.findFirst({
+    where: and(
+      eq(membersTable.organizationId, organizationId),
+      eq(membersTable.userId, userId),
+      inArray(membersTable.role, [...allowedRoles])
+    ),
+    columns: { id: true, role: true }
+  })
+  if (!membership) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to perform this action.'
+    )
+  }
+  return membership
+}
+
+/**
+ * Asserts the caller can manage the organization (owner or admin). Use it for
+ * settings, billing, members, and uploads.
+ */
+export function assertCanManageOrganization(
+  organizationId: string,
+  userId: string
+) {
+  return assertRole(organizationId, userId, ['owner', 'admin'])
+}

package/template/saas-starter/src/lib/otel.ts

@@ -0,0 +1,117 @@
+import { SpanStatusCode, trace, type Attributes } from '@opentelemetry/api'
+
+const MAX_STRING_ATTR_LENGTH = 256
+const MAX_ARRAY_ATTR_ITEMS = 20
+
+/**
+ * Helper function to retrieve the currently active span from the OpenTelemetry context.
+ * Useful for attaching additional information to the current trace.
+ */
+function getSpan() {
+  const span = trace.getActiveSpan()
+  return span
+}
+
+/**
+ * Records a "wide event" with arbitrary attributes to the current span.
+ * This allows adding high-cardinality data or domain-specific context
+ * to the trace without starting a new child span.
+ *
+ * @param attributes - Key-value pairs of attributes to add to the span
+ */
+export function recordWideEvent(attributes: Attributes) {
+  const span = getSpan()
+  if (!span) return
+
+  span.setAttributes(attributes)
+}
+
+/**
+ * Flatten a value tree into OTEL-safe attributes under `prefix`.
+ * Nested objects use dotted keys; long strings are truncated; large
+ * arrays are capped. Use for action `parsedInput` on wide events.
+ */
+export function flattenForWideEvent(
+  value: unknown,
+  prefix = 'input'
+): Attributes {
+  const out: Attributes = {}
+
+  const visit = (current: unknown, path: string) => {
+    if (current === null || current === undefined) return
+
+    if (typeof current === 'string') {
+      out[path] =
+        current.length > MAX_STRING_ATTR_LENGTH
+          ? `${current.slice(0, MAX_STRING_ATTR_LENGTH)}…`
+          : current
+      return
+    }
+
+    if (typeof current === 'number' || typeof current === 'boolean') {
+      out[path] = current
+      return
+    }
+
+    if (typeof current === 'bigint') {
+      out[path] = current.toString()
+      return
+    }
+
+    if (Array.isArray(current)) {
+      const limited = current.slice(0, MAX_ARRAY_ATTR_ITEMS)
+      const allPrimitive = limited.every(
+        item =>
+          item === null ||
+          item === undefined ||
+          typeof item === 'string' ||
+          typeof item === 'number' ||
+          typeof item === 'boolean'
+      )
+      if (allPrimitive) {
+        out[path] = limited.map(item =>
+          item === null || item === undefined ? '' : String(item)
+        )
+        if (current.length > MAX_ARRAY_ATTR_ITEMS) {
+          out[`${path}.length`] = current.length
+        }
+        return
+      }
+      out[`${path}.length`] = current.length
+      limited.forEach((item, index) => visit(item, `${path}.${index}`))
+      return
+    }
+
+    if (typeof current === 'object') {
+      for (const [key, child] of Object.entries(
+        current as Record<string, unknown>
+      )) {
+        visit(child, path ? `${path}.${key}` : key)
+      }
+    }
+  }
+
+  visit(value, prefix)
+  return out
+}
+
+/**
+ * Records an exception to the current span and sets the span status to ERROR.
+ * captures the error message and stack trace if available.
+ *
+ * @param err - The error to record (can be an Error object or unknown)
+ * @returns The trace ID associated with the error, useful for correlation
+ */
+export function recordError(err: unknown) {
+  const span = getSpan()
+  if (!span) return
+
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: err instanceof Error ? err.message : String(err)
+  })
+
+  span.recordException(err instanceof Error ? err : String(err))
+
+  return span.spanContext().traceId
+}

package/template/saas-starter/src/lib/plan-limits.ts

@@ -0,0 +1,37 @@
+import 'server-only'
+
+import { eq } from 'drizzle-orm'
+import { cache } from 'react'
+import { db } from '~/db'
+import { organizationSubscriptionsTable } from '~/db/schema'
+import { AppError, AppErrorCode } from './errors'
+import { PLANS, isActiveSubscriptionStatus } from './plans'
+
+/**
+ * The plan an organization is entitled to right now, and its subscription row.
+ *
+ * Only a trialing, active, or past-due subscription grants its paid plan;
+ * every other status falls back to the free plan.
+ */
+export const getOrganizationPlan = cache(async (organizationId: string) => {
+  const sub = await db.query.organizationSubscriptionsTable.findFirst({
+    where: eq(organizationSubscriptionsTable.organizationId, organizationId)
+  })
+
+  if (!sub) {
+    throw new AppError(
+      AppErrorCode.NOT_FOUND,
+      'This organization has no subscription record.'
+    )
+  }
+
+  const planId = isActiveSubscriptionStatus(sub.status) ? sub.plan : 'free'
+  const plan = PLANS.find(candidate => candidate.id === planId)
+
+  if (!plan) {
+    // A configuration bug, not a customer error: masked and recorded.
+    throw new Error(`Plan ${planId} is missing from the plan registry.`)
+  }
+
+  return { plan, sub }
+})