create-ej-app 26.0.0 → 27.0.0

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

@@ -1,14 +1,27 @@
+import 'server-only'
+
 import { eq } from 'drizzle-orm'
 import { db } from '~/db'
-import { organizationSubscriptionsTable, organizationsTable } from '~/db/schema'
-import { PLANS, type Plan } from './plans'
+import {
+  organizationSubscriptionStatusEnum,
+  organizationSubscriptionsTable,
+  organizationsTable
+} from '~/db/schema'
+import { AppError, AppErrorCode } from './errors'
+import { PLANS, hasLiveSubscription, type PlanId } from './plans'
 import { stripeClient } from './stripe'
 
 type SubscriptionRow = typeof organizationSubscriptionsTable.$inferSelect
+type SubscriptionStatus = SubscriptionRow['status']
+
+const KNOWN_STATUSES = new Set<string>(
+  organizationSubscriptionStatusEnum.enumValues
+)
 
+/** Maps a Stripe price back to the plan and billing interval it belongs to. */
 export const getPlanAndIntervalByPriceId = (
   priceId: string
-): { planId: Plan['id']; interval: 'month' | 'year' } | null => {
+): { planId: PlanId; interval: 'month' | 'year' } | null => {
   for (const plan of PLANS) {
     if (!plan.stripePrice) continue
     if (plan.stripePrice.monthly.id === priceId)
@@ -19,56 +32,71 @@ export const getPlanAndIntervalByPriceId = (
   return null
 }
 
+/** One trial per organization, and only from the free plan. */
 export const canStartTrial = (
   sub: Pick<SubscriptionRow, 'status' | 'hasUsedTrial'>
 ): boolean => sub.status === 'free' && !sub.hasUsedTrial
 
+/**
+ * Returns the organization's Stripe customer, creating one on first checkout.
+ * A billing email is required first so receipts have somewhere to go.
+ */
 export const ensureStripeCustomer = async (
-  organizationId: string
+  sub: SubscriptionRow
 ): Promise<string> => {
-  const sub = await db.query.organizationSubscriptionsTable.findFirst({
-    where: eq(organizationSubscriptionsTable.organizationId, organizationId)
-  })
-
-  if (!sub) {
-    throw new Error('Organization does not have a subscription')
-  }
-
   if (sub.stripeCustomerId) return sub.stripeCustomerId
 
   if (!sub.billingEmail) {
-    throw new Error('Set a billing email before subscribing')
+    throw new AppError(
+      AppErrorCode.BAD_REQUEST,
+      'Add a billing email before you choose a paid plan.'
+    )
   }
 
   const org = await db.query.organizationsTable.findFirst({
-    where: eq(organizationsTable.id, organizationId),
+    where: eq(organizationsTable.id, sub.organizationId),
     columns: { name: true }
   })
 
-  const customer = await stripeClient.customers.create({
-    email: sub.billingEmail,
-    name: org?.name,
-    metadata: { organizationId }
-  })
+  // The idempotency key makes a double-clicked checkout reuse one customer
+  // instead of orphaning the first one's webhooks.
+  const customer = await stripeClient.customers.create(
+    {
+      email: sub.billingEmail,
+      name: org?.name,
+      metadata: { organizationId: sub.organizationId }
+    },
+    { idempotencyKey: `organization-${sub.organizationId}-customer` }
+  )
 
   await db
     .update(organizationSubscriptionsTable)
     .set({ stripeCustomerId: customer.id })
-    .where(eq(organizationSubscriptionsTable.organizationId, organizationId))
+    .where(eq(organizationSubscriptionsTable.id, sub.id))
 
   return customer.id
 }
 
+/**
+ * Copies the customer's latest Stripe subscription onto the organization.
+ *
+ * Webhooks call this for every relevant event, so it reads the current state
+ * from Stripe instead of trusting the event payload, which may arrive out of
+ * order.
+ */
 export const syncSubscriptionFromStripe = async (
   customerId: string
 ): Promise<void> => {
   const subs = await stripeClient.subscriptions.list({
     customer: customerId,
     status: 'all',
-    limit: 1
+    limit: 10
   })
 
-  const sub = subs.data[0]
+  // Newest first. Prefer a subscription that still bills over a newer one
+  // that ended, so the organization never drops to free while paying.
+  const sub =
+    subs.data.find(item => hasLiveSubscription(item.status)) ?? subs.data[0]
 
   if (
     !sub ||
@@ -90,12 +118,19 @@ export const syncSubscriptionFromStripe = async (
     return
   }
 
+  if (!KNOWN_STATUSES.has(sub.status)) {
+    throw new AppError(
+      AppErrorCode.INTERNAL,
+      `Stripe subscription ${sub.id} has unknown status ${sub.status}. Add it to the status enum to sync it.`
+    )
+  }
+
   const item = sub.items.data[0]
   const resolved = item ? getPlanAndIntervalByPriceId(item.price.id) : null
 
   if (!resolved) {
     console.error(
-      `Stripe price ${item?.price.id} on subscription ${sub.id} does not map to a known plan`
+      `Stripe price ${item?.price.id} on subscription ${sub.id} does not map to a plan; the organization stays on the free plan.`
     )
   }
 
@@ -105,7 +140,7 @@ export const syncSubscriptionFromStripe = async (
     .update(organizationSubscriptionsTable)
     .set({
       plan: resolved?.planId ?? 'free',
-      status: sub.status,
+      status: sub.status as SubscriptionStatus,
       interval: resolved?.interval ?? null,
       stripeSubscriptionId: sub.id,
       trialEndsAt: sub.trial_end ? new Date(sub.trial_end * 1000) : null,

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

@@ -0,0 +1,28 @@
+/** Origin used only to resolve a candidate callback and check where it lands. */
+const RESOLUTION_ORIGIN = 'https://callback.invalid'
+
+/**
+ * Narrow a caller-supplied `?callbackUrl=` down to a same-origin path.
+ *
+ * Returns the normalised path, or null when the value could leave the site.
+ * A leading `/` is not enough on its own: `//evil.com`, `/\evil.com`, and
+ * `/<tab>/evil.com` all resolve cross-origin in a browser, the last because
+ * URL parsing strips tabs and newlines first. The shape checks below reject
+ * the known forms, and resolving against a throwaway origin catches the rest.
+ */
+export function sanitizeCallbackUrl(
+  value: string | string[] | undefined
+): string | null {
+  if (typeof value !== 'string') return null
+  if (!/^\/(?![/\\])/.test(value)) return null
+  if (/[\t\n\r]/.test(value)) return null
+
+  try {
+    const resolved = new URL(value, RESOLUTION_ORIGIN)
+    if (resolved.origin !== RESOLUTION_ORIGIN) return null
+
+    return `${resolved.pathname}${resolved.search}${resolved.hash}`
+  } catch {
+    return null
+  }
+}

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

@@ -1,22 +1,91 @@
+/**
+ * @fileoverview Application-wide constants for configuration and validation.
+ *
+ * Read limits, labels, and repeated values from here in the UI, validation,
+ * tests, and docs, so one change updates every place.
+ *
+ * @module lib/constants
+ */
+
 // ============================================
-// BILLING CONFIGURATION
+// BILLING
 // ============================================
 
-/* Trial days */
+/** Length of the free trial on paid plans that offer one */
 export const TRIAL_DAYS = 7
 
 // ============================================
-// R2 STORAGE CONFIGURATION
+// ORGANIZATIONS
+// ============================================
+
+/** Organizations one user can create */
+export const MAX_ORGANIZATIONS_PER_USER = 10
+
+/** Days an organization invitation stays valid */
+export const INVITATION_EXPIRES_IN_DAYS = 7
+
+// ============================================
+// R2 STORAGE
 // ============================================
 
-/* Presigned URL TTL in seconds */
-export const PRESIGNED_URL_TTL_SECONDS = 900 // 15 min to complete the upload
+/** Seconds the client has to complete a presigned upload */
+export const PRESIGNED_URL_TTL_SECONDS = 900
 
-/* Temp cleanup threshold in milliseconds */
-export const TEMP_CLEANUP_THRESHOLD_MS = 2 * 60 * 60 * 1000 // 2 hours
+/** Age after which an unconfirmed upload is deleted */
+export const TEMP_CLEANUP_THRESHOLD_MS = 2 * 60 * 60 * 1000
 
-/* Maximum file size in MB */
+/** Maximum upload size in MB */
 export const MAX_FILE_SIZE_MB = 5
 
-/* Maximum file size in bytes */
+/** Maximum upload size in bytes */
 export const MAX_FILE_SIZE_BYTES = MAX_FILE_SIZE_MB * 1024 * 1024
+
+/** MIME types the upload flow accepts, mapped to the extension stored on the object key */
+export const R2_UPLOAD_EXTENSION_BY_MIME_TYPE = {
+  'image/jpeg': 'jpg',
+  'image/png': 'png',
+  'image/webp': 'webp',
+  'image/gif': 'gif'
+} as const
+
+export type R2UploadMimeType = keyof typeof R2_UPLOAD_EXTENSION_BY_MIME_TYPE
+
+// ============================================
+// REQUEST ARRAY BOUNDS
+// ============================================
+
+/*
+ * Ceilings for arrays that reach SQL as an `IN (…)` list. Postgres caps a
+ * statement at 65535 bind parameters, and an unbounded array also builds in
+ * server memory first.
+ */
+
+/** Values accepted in one list-filter array, such as status facets */
+export const MAX_FILTER_VALUES = 100
+
+// ============================================
+// TEXT AND INTEGER INPUT BOUNDS
+// ============================================
+
+/**
+ * Image value ceiling.
+ * Covers R2 object keys and base64 data URLs for the max upload size.
+ */
+export const MAX_IMAGE_URL_LENGTH =
+  Math.ceil(MAX_FILE_SIZE_BYTES * (4 / 3)) + 64
+
+/** URL slug for organizations */
+export const MAX_SLUG_LENGTH = 64
+
+/** Feedback comments */
+export const MAX_COMMENT_LENGTH = 3_000
+
+/** Support ticket bodies and contact form messages */
+export const MAX_MESSAGE_LENGTH = 5_000
+
+/** Shortest contact form message worth answering */
+export const MIN_CONTACT_MESSAGE_LENGTH = 10
+
+/** Star ratings on feedback */
+export const MIN_RATING = 1
+export const MAX_RATING = 5

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

@@ -1,2 +1,12 @@
+/**
+ * Creates a promise that resolves after a specified delay
+ * Useful for adding delays in async functions or testing
+ *
+ * @param ms - Milliseconds to delay
+ * @returns Promise that resolves after the delay
+ *
+ * @example
+ * await delay(1000) // Wait 1 second
+ */
 export const delay = (ms: number) =>
   new Promise(resolve => setTimeout(resolve, ms))

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

@@ -1,3 +1,5 @@
+import 'server-only'
+
 import { render, toPlainText } from '@react-email/render'
 import InvitationEmail, { InvitationEmailProps } from '~/emails/invitation'
 import MagicLinkEmail, { MagicLinkEmailProps } from '~/emails/magic-link'
@@ -25,6 +27,9 @@ const componentMap: Record<
   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]
@@ -43,6 +48,14 @@ async function renderEmailTemplate(
   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'
 
@@ -56,6 +69,14 @@ export async function sendWelcomeEmail(to: string, props: WelcomeEmailProps) {
   })
 }
 
+/**
+ * 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
@@ -72,6 +93,14 @@ export async function sendMagicLinkEmail(
   })
 }
 
+/**
+ * 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
@@ -82,7 +111,7 @@ export async function sendInvitationEmail(
 
   return await sendEmail({
     to,
-    subject: `You've been invited to join ${props.organizationName}`,
+    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

@@ -1,27 +1,25 @@
-export const formatCurrency = (
-  currencyCode: string,
-  num: number | string,
-  precision = 2
-) => {
-  const numCopy = Number(num)
+const formatters = new Map<string, Intl.NumberFormat>()
 
-  switch (currencyCode) {
-    case 'INR':
-      return new Intl.NumberFormat('en-IN', {
-        style: 'currency',
-        currency: 'INR',
-        signDisplay: 'negative'
-      }).format(numCopy)
-    case 'USD':
-      return new Intl.NumberFormat('en-US', {
-        style: 'currency',
-        currency: 'USD',
-        signDisplay: 'negative'
-      }).format(numCopy)
-    default:
-      console.warn(
-        `Unsupported currency: ${currencyCode}. Defaulting to fixed format.`
-      )
-      return numCopy.toFixed(precision)
+/**
+ * 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

@@ -1,12 +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?: { short?: boolean; time?: boolean; noYear?: boolean }
+  options?: DateFormatOptions
 ): string => {
-  if (date == null) return '-'
-  return new Date(date).toLocaleDateString('en-US', {
+  const instant = asValidDate(date)
+  if (!instant) return '-'
+
+  const dateOptions: Intl.DateTimeFormatOptions = {
     ...(options?.noYear ? {} : { year: 'numeric' }),
     month: options?.short ? 'short' : 'long',
-    day: 'numeric',
-    ...(options?.time ? { hour: '2-digit', minute: '2-digit' } : {})
-  })
+    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

@@ -1,16 +1,26 @@
+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: parseInt(env.EMAIL_SERVER_PORT),
-  secure: parseInt(env.EMAIL_SERVER_PORT) === 465, // Use secure for port 465, false for other ports
+  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
@@ -18,6 +28,17 @@ interface SendEmailParams {
   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,
@@ -38,6 +59,9 @@ export const sendEmail = async ({
     return info
   } catch (error) {
     console.error('Error sending email:', error)
-    throw new Error('Failed to send email')
+    throw new AppError(
+      AppErrorCode.INTERNAL,
+      'The email was not sent. Try again.'
+    )
   }
 }