create-ej-app 26.0.0 → 27.0.0

package/template/saas-starter/src/lib/safe-action.ts

@@ -1,30 +1,132 @@
+import 'server-only'
+
 import { createSafeActionClient } from 'next-safe-action'
 import { getAuthSession } from './auth'
-import { recordWideEvent } from './otel'
+import { AppError, AppErrorCode, isAppError } from './errors'
+import { flattenForWideEvent, recordError, recordWideEvent } from './otel'
+
+/** Shown for every unexpected error; details stay in telemetry. */
+export const UNEXPECTED_ERROR_MESSAGE =
+  'The request did not finish. Try again in a few minutes.'
 
-export const actionClient = createSafeActionClient().use(
-  async ({ next, ctx }) => {
-    const authSession = await getAuthSession()
+type ActionServerArgs = {
+  parsedInput?: unknown
+  clientInput?: unknown
+  [key: string]: unknown
+}
 
-    if (authSession)
+/**
+ * Wrap a safe-action server function with wide-event telemetry.
+ *
+ * Records `action.name`, flattened `parsedInput` (or `clientInput`), and on
+ * success `outcome: 'success'` plus `duration_ms`. Failures keep error fields
+ * from `handleServerError`; duration is still recorded.
+ *
+ * @example
+ * export const myAction = authActionClient
+ *   .inputSchema(schema)
+ *   .action(
+ *     withWideEvent('myAction', async ({ parsedInput, ctx }) => {
+ *       // business logic only
+ *     })
+ *   )
+ */
+export function withWideEvent<TArgs extends ActionServerArgs, TResult>(
+  actionName: string,
+  serverCode: (args: TArgs) => Promise<TResult>
+): (args: TArgs) => Promise<TResult> {
+  return async args => {
+    const startedAt = Date.now()
+    const input = args.parsedInput ?? args.clientInput
+
+    recordWideEvent({
+      'action.name': actionName,
+      ...flattenForWideEvent(input, 'input')
+    })
+
+    try {
+      const result = await serverCode(args)
+      recordWideEvent({
+        outcome: 'success',
+        duration_ms: Date.now() - startedAt
+      })
+      return result
+    } catch (error) {
       recordWideEvent({
-        'user.id': authSession.user.id,
-        'user.admin': authSession.isAdmin,
-        'session.id': authSession.session.id
+        outcome: 'error',
+        duration_ms: Date.now() - startedAt
       })
+      throw error
+    }
+  }
+}
 
-    return next({
-      ctx: {
-        ...ctx,
-        ...authSession
-      }
+/**
+ * Configured safe action client with authentication middleware
+ * This client wraps server actions with:
+ * - Automatic input/output validation using Zod
+ * - Type-safe error handling ({@link AppError} messages reach the client)
+ * - Server-side authentication injection
+ *
+ * All server actions using this client automatically receive the current auth session
+ * in the context, so protected actions can access user information.
+ *
+ * @example
+ * export const myAction = actionClient
+ *   .inputSchema(z.object({ name: z.string() }))
+ *   .action(async ({ parsedInput: { name }, ctx }) => {
+ *     const userId = ctx.user?.id // Auth injected automatically
+ *     return { success: true }
+ *   })
+ */
+export const actionClient = createSafeActionClient({
+  handleServerError(e) {
+    if (isAppError(e)) {
+      recordWideEvent({
+        'error.name': e.name,
+        'error.code': e.code,
+        'error.message': e.message,
+        'error.expected': true,
+        outcome: 'error'
+      })
+      return e.message
+    }
+
+    recordError(e)
+    recordWideEvent({
+      'error.name': e.name,
+      'error.expected': false,
+      'error.message': e.message,
+      outcome: 'error'
     })
+    return UNEXPECTED_ERROR_MESSAGE
   }
-)
+}).use(async ({ next, ctx }) => {
+  // Retrieve current authentication session
+  const authSession = await getAuthSession()
+
+  // Record user information in telemetry for all actions, if available
+  if (authSession) {
+    recordWideEvent({
+      'user.id': authSession.user.id,
+      'user.admin': authSession.isAdmin,
+      'user.superAdmin': authSession.isSuperAdmin,
+      'session.id': authSession.session.id
+    })
+  }
+
+  // Inject auth session into action context for all downstream actions
+  return next({
+    ctx: {
+      ...ctx,
+      ...authSession
+    }
+  })
+})
 
 export const authActionClient = actionClient.use(async ({ ctx, next }) => {
   if (!ctx?.user || !ctx?.session) {
-    throw new Error('Unauthorized')
+    throw new AppError(AppErrorCode.UNAUTHORIZED, 'Sign in to continue.')
   }
 
   return next({
@@ -36,9 +138,18 @@ export const authActionClient = actionClient.use(async ({ ctx, next }) => {
   })
 })
 
+/**
+ * Action client for the admin panel.
+ *
+ * Allows both `admin` and `superadmin` roles. Use for actions that any
+ * admin-panel user may run (support tickets, feedback, and contact leads).
+ */
 export const adminActionClient = authActionClient.use(async ({ ctx, next }) => {
   if (!ctx.isAdmin) {
-    throw new Error('Forbidden')
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to do this.'
+    )
   }
 
   return next({
@@ -50,10 +161,19 @@ export const adminActionClient = authActionClient.use(async ({ ctx, next }) => {
   })
 })
 
+/**
+ * Action client restricted to the `superadmin` role.
+ *
+ * Use for privileged operations, such as user management, role changes, and
+ * impersonation, that `admin` users cannot perform.
+ */
 export const superAdminActionClient = adminActionClient.use(
   async ({ ctx, next }) => {
     if (!ctx.isSuperAdmin) {
-      throw new Error('Forbidden')
+      throw new AppError(
+        AppErrorCode.FORBIDDEN,
+        'You do not have permission to do this.'
+      )
     }
 
     return next({

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

@@ -0,0 +1,16 @@
+/**
+ * Escape characters that are special in SQL LIKE / ILIKE patterns.
+ *
+ * Postgres uses `\` as the default escape character. Without escaping, a
+ * user-typed `%` or `_` becomes a wildcard and can force full-table scans.
+ */
+export function escapeLikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, char => `\\${char}`)
+}
+
+/**
+ * Build a case-insensitive contains pattern: `%value%` with wildcards escaped.
+ */
+export function likeContains(value: string): string {
+  return `%${escapeLikePattern(value)}%`
+}

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

@@ -0,0 +1,7 @@
+import type { Metadata } from 'next'
+
+/** Meta robots for authenticated or non-public surfaces. */
+export const privatePageRobots = {
+  index: false,
+  follow: false
+} satisfies NonNullable<Metadata['robots']>

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

@@ -1,4 +1,20 @@
+/**
+ * @fileoverview Brand identity and site-wide copy.
+ *
+ * Layouts, emails, legal pages, and metadata read from here. Never hardcode
+ * the product name anywhere else.
+ *
+ * @module lib/siteConfig
+ */
 export const siteConfig = {
   name: 'Project Name',
-  description: 'Project Description'
+  description: 'Project Description',
+  logo: '/logo.svg',
+  logoDark: '/logo-dark.svg',
+  contact: {
+    email: 'hello@example.com'
+  },
+  legal: {
+    lastUpdated: 'September 25, 2026'
+  }
 }

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

@@ -1,3 +1,5 @@
+import 'server-only'
+
 import {
   DeleteObjectCommand,
   PutObjectCommand,
@@ -11,27 +13,29 @@ import { fileUploadsTable } from '~/db/schema'
 import { env } from '~/env'
 import {
   PRESIGNED_URL_TTL_SECONDS,
-  TEMP_CLEANUP_THRESHOLD_MS
+  R2_UPLOAD_EXTENSION_BY_MIME_TYPE,
+  TEMP_CLEANUP_THRESHOLD_MS,
+  type R2UploadMimeType
 } from './constants'
+import { AppError, AppErrorCode } from './errors'
+import {
+  canPersistImageValue,
+  isDataImageUrl,
+  isR2ObjectKey
+} from './image-url'
 
 /*
-R2 Policy need to be set
+The R2 bucket needs this CORS policy for browser uploads:
 [
   {
-    "AllowedOrigins": [
-      "http://localhost:3000"
-    ],
-    "AllowedMethods": [
-      "PUT"
-    ],
-    "AllowedHeaders": [
-      "content-type",
-      "content-length"
-    ]
+    "AllowedOrigins": ["http://localhost:3000"],
+    "AllowedMethods": ["PUT"],
+    "AllowedHeaders": ["content-type", "content-length"]
   }
 ]
 */
 
+/** True when all five R2 env vars are set. When false, uploads fall back to base64 data URLs. */
 export function isR2Configured(): boolean {
   return !!(
     env.R2_ACCOUNT_ID &&
@@ -44,12 +48,17 @@ export function isR2Configured(): boolean {
 
 let _r2Client: S3Client | null = null
 
+/**
+ * `requestChecksumCalculation: 'WHEN_REQUIRED'` avoids signing
+ * `x-amz-checksum-crc32=AAAAAA==` (empty body) into presigned PUTs, which
+ * breaks non-empty uploads on backends that validate the header.
+ */
 function getR2Client(): S3Client {
   if (_r2Client) return _r2Client
 
-  const configured = isR2Configured()
-  if (!configured) {
-    throw new Error('R2 storage is not configured')
+  if (!isR2Configured()) {
+    // A configuration bug, not a customer error: masked and recorded.
+    throw new Error('R2 storage is not configured.')
   }
 
   _r2Client = new S3Client({
@@ -58,52 +67,94 @@ function getR2Client(): S3Client {
     credentials: {
       accessKeyId: env.R2_ACCESS_KEY_ID!,
       secretAccessKey: env.R2_SECRET_ACCESS_KEY!
-    }
+    },
+    requestChecksumCalculation: 'WHEN_REQUIRED',
+    responseChecksumValidation: 'WHEN_REQUIRED'
   })
 
   return _r2Client
 }
 
+/**
+ * Throws unless `key` sits under `uploads/organizations/<organizationId>/` and
+ * has a `file_uploads` row recorded for that same organization.
+ *
+ * Call this on any R2 key that comes from user input before it is persisted,
+ * confirmed, or deleted, so a request can never reference another tenant's
+ * object.
+ */
+export async function assertOwnedR2Key(
+  key: string,
+  organizationId: string
+): Promise<void> {
+  if (!key.startsWith(`uploads/organizations/${organizationId}/`)) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to use this file.'
+    )
+  }
+
+  const exists = await db.query.fileUploadsTable.findFirst({
+    where: and(
+      eq(fileUploadsTable.key, key),
+      eq(fileUploadsTable.organizationId, organizationId)
+    ),
+    columns: { id: true }
+  })
+
+  if (!exists) {
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to use this file.'
+    )
+  }
+}
+
+/**
+ * Deletes a file from R2 and removes its tracking row.
+ *
+ * Trusted-caller primitive with no ownership check. Validate a key that came
+ * from user input with {@link assertOwnedR2Key} first.
+ */
 export async function deleteFile(key: string): Promise<void> {
-  const client = getR2Client()
-  await client.send(
-    new DeleteObjectCommand({
-      Bucket: env.R2_BUCKET_NAME,
-      Key: key
-    })
+  await getR2Client().send(
+    new DeleteObjectCommand({ Bucket: env.R2_BUCKET_NAME, Key: key })
   )
 
   await db.delete(fileUploadsTable).where(eq(fileUploadsTable.key, key))
 }
 
+/**
+ * Presigns a PUT for a direct browser-to-R2 upload and records it as
+ * temporary. Content-Type is signed, so the browser cannot upload `text/html`
+ * under an image key.
+ *
+ * The browser PUTs the file to `uploadUrl`, then the action that saves the
+ * resource calls {@link confirmUpload} with the returned `key`.
+ */
 export async function generateUploadUrl(params: {
   filename: string
-  mimeType: string
+  mimeType: R2UploadMimeType
   size: number
   uploadedBy: string
-  organizationId?: string | null
-}): Promise<{
-  uploadUrl: string
-  key: string
-}> {
-  const ext = params.filename.split('.').pop()?.toLowerCase() ?? 'bin'
-  const folder = params.organizationId
-    ? `uploads/organizations/${params.organizationId}`
-    : `uploads/misc`
-
+  organizationId: string
+}): Promise<{ uploadUrl: string; key: string }> {
+  const ext = R2_UPLOAD_EXTENSION_BY_MIME_TYPE[params.mimeType]
   const fileId = createId()
-  const key = `${folder}/${fileId}.${ext}`
+  const key = `uploads/organizations/${params.organizationId}/${fileId}.${ext}`
 
-  const client = getR2Client()
   const uploadUrl = await getSignedUrl(
-    client,
+    getR2Client(),
     new PutObjectCommand({
       Bucket: env.R2_BUCKET_NAME!,
       Key: key,
       ContentType: params.mimeType,
       ContentLength: params.size
     }),
-    { expiresIn: PRESIGNED_URL_TTL_SECONDS }
+    {
+      expiresIn: PRESIGNED_URL_TTL_SECONDS,
+      signableHeaders: new Set(['content-type'])
+    }
   )
 
   await db.insert(fileUploadsTable).values({
@@ -120,35 +171,114 @@ export async function generateUploadUrl(params: {
   return { uploadUrl, key }
 }
 
+/**
+ * Marks an upload permanent and deletes the file it replaces.
+ *
+ * Call it in the action that saves the resource. `newKey` must belong to
+ * `organizationId`, and this throws otherwise. Deleting `oldKey` is
+ * best-effort and never blocks the save.
+ */
 export async function confirmUpload(
   newKey: string,
+  organizationId: string,
   oldKey?: string | null
 ): Promise<void> {
+  await assertOwnedR2Key(newKey, organizationId)
+
   await db
     .update(fileUploadsTable)
     .set({ isTemp: false })
     .where(eq(fileUploadsTable.key, newKey))
 
-  if (oldKey && isR2Configured()) {
-    await deleteFile(oldKey).catch(() => {
-      // Non-fatal: old file cleanup failure should not block the save
-    })
+  if (oldKey && oldKey !== newKey)
+    await deleteOwnedFileQuietly(oldKey, organizationId)
+}
+
+/**
+ * Deletes a replaced or cleared file when `organizationId` owns it. Failures
+ * are swallowed: a stale object costs storage, not correctness.
+ */
+export async function deleteOwnedFileQuietly(
+  key: string,
+  organizationId: string
+): Promise<void> {
+  if (!isR2Key(key) || !isR2Configured()) return
+
+  const owned = await assertOwnedR2Key(key, organizationId)
+    .then(() => true)
+    .catch(() => false)
+
+  if (owned) await deleteFile(key).catch(() => {})
+}
+
+/**
+ * Deletes every upload an organization owns, from R2 and the database.
+ * `file_uploads.organization_id` restricts deletes, so the organization row
+ * can only go once this has run.
+ */
+export async function deleteOrganizationUploads(
+  organizationId: string
+): Promise<void> {
+  const uploads = await db
+    .select({ key: fileUploadsTable.key })
+    .from(fileUploadsTable)
+    .where(eq(fileUploadsTable.organizationId, organizationId))
+
+  if (isR2Configured()) {
+    for (const upload of uploads) {
+      await deleteFile(upload.key)
+    }
   }
+
+  await db
+    .delete(fileUploadsTable)
+    .where(eq(fileUploadsTable.organizationId, organizationId))
 }
 
+/** True when `value` is an R2 object key (`uploads/organizations/<id>/<file>.<ext>`). */
 export function isR2Key(value: string | null | undefined): value is string {
-  return !!value && !value.startsWith('data:') && !value.startsWith('https://')
+  return !!value && isR2ObjectKey(value)
+}
+
+/**
+ * Rejects image values that must not be written to a resource. This blocks
+ * `data:` URLs when R2 is configured. Ownership stays in {@link assertOwnedR2Key}.
+ */
+export function assertPersistableImageValue(
+  value: string | null | undefined
+): void {
+  if (!value) return
+  if (canPersistImageValue(value, isR2Configured())) return
+  throw new AppError(
+    AppErrorCode.BAD_REQUEST,
+    'Upload an image file. Embedded images are not stored.'
+  )
 }
 
+/**
+ * Resolves a stored image value to a renderable URL.
+ *
+ * - R2 object key: prefixed with `R2_PUBLIC_URL`
+ * - `data:image/*;base64,...` (dev without R2): returned as-is
+ * - anything else, including `https://` and `javascript:`: `null`
+ */
 export function resolveImageUrl(
   value: string | null | undefined
 ): string | null {
   if (!value) return null
-  if (!isR2Key(value)) return value
-  if (!isR2Configured()) return null
-  return `${env.R2_PUBLIC_URL}/${value}`
+  if (isR2ObjectKey(value)) {
+    if (!isR2Configured()) return null
+    return `${env.R2_PUBLIC_URL}/${value}`
+  }
+  if (isDataImageUrl(value)) return value
+  return null
 }
 
+/**
+ * Deletes temporary uploads older than {@link TEMP_CLEANUP_THRESHOLD_MS}.
+ * Per-file errors are counted, not thrown, so one failure cannot abort the
+ * batch. `bun run storage:cleanup` runs it; schedule that command.
+ */
 export async function cleanupTempUploads(): Promise<{
   deleted: number
   errors: number
@@ -156,7 +286,7 @@ export async function cleanupTempUploads(): Promise<{
   const threshold = new Date(Date.now() - TEMP_CLEANUP_THRESHOLD_MS)
 
   const stale = await db
-    .select({ id: fileUploadsTable.id, key: fileUploadsTable.key })
+    .select({ key: fileUploadsTable.key })
     .from(fileUploadsTable)
     .where(
       and(

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

@@ -1,6 +1,9 @@
+import 'server-only'
+
 import Stripe from 'stripe'
 import { env } from '~/env'
 
+/** Pinned to the API version this `stripe` SDK release was built for. Bump both together. */
 export const stripeClient = new Stripe(env.STRIPE_SECRET_KEY, {
-  apiVersion: '2026-05-27.dahlia'
+  apiVersion: '2026-08-26.dahlia'
 })

package/template/saas-starter/src/lib/toast-message.ts

@@ -2,14 +2,100 @@
 
 import { toast } from 'sonner'
 
+const DEFAULT_ERROR = 'The request did not finish. Try again in a few minutes.'
+
+type ActionResultLike = {
+  serverError?: string
+  validationErrors?: unknown
+}
+
+/**
+ * Displays a success toast notification to the user.
+ */
 export const toastSuccessMessage = (message: string) =>
   toast.success(message, {
     richColors: true,
     position: 'top-center'
   })
 
+/**
+ * Displays an informational toast (neutral, non-error feedback).
+ */
+export const toastInfoMessage = (message: string) =>
+  toast.info(message, {
+    richColors: true,
+    position: 'top-center'
+  })
+
+/**
+ * Displays an error toast. Uses a default message when none is provided.
+ */
 export const toastErrorMessage = (message?: string) =>
-  toast.error(message || 'Something went wrong. Please try again later.', {
+  toast.error(message || DEFAULT_ERROR, {
     richColors: true,
     position: 'top-center'
   })
+
+/**
+ * Toast an action failure from `await someAction(...)`.
+ * Returns true when a toast was shown so callers can bail.
+ *
+ * @example
+ * const result = await upsertTableAction(values)
+ * if (toastIfActionFailed(result)) return
+ */
+export function toastIfActionFailed(
+  result: ActionResultLike | undefined | null
+): boolean {
+  if (!result) return false
+  if (result.serverError) {
+    toastErrorMessage(result.serverError)
+    return true
+  }
+  if (result.validationErrors) {
+    toastErrorMessage('Check the highlighted fields and try again.')
+    return true
+  }
+  return false
+}
+
+/**
+ * Toast a failure from hooks (`useSafeActionMutation`, `useAction`) or a thrown Error.
+ *
+ * Accepts:
+ * - `SafeActionError` / `Error` (`message`)
+ * - `useAction` error bag (`{ serverError, validationErrors }`)
+ * - plain string
+ *
+ * @example
+ * onError: error => toastActionError(error, 'Failed to save')
+ * onError: ({ error }) => toastActionError(error, 'Failed to save')
+ */
+export function toastActionError(
+  error: unknown,
+  fallback = DEFAULT_ERROR
+): void {
+  if (typeof error === 'string' && error.trim()) {
+    toastErrorMessage(error)
+    return
+  }
+
+  if (error && typeof error === 'object') {
+    const bag = error as ActionResultLike & { message?: string }
+
+    if (typeof bag.serverError === 'string' && bag.serverError) {
+      toastErrorMessage(bag.serverError)
+      return
+    }
+    if (bag.validationErrors) {
+      toastErrorMessage('Check the highlighted fields and try again.')
+      return
+    }
+    if (typeof bag.message === 'string' && bag.message.trim()) {
+      toastErrorMessage(bag.message)
+      return
+    }
+  }
+
+  toastErrorMessage(fallback)
+}