create-ej-app 25.0.0 → 27.0.0

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

@@ -0,0 +1,90 @@
+import 'server-only'
+
+import { env } from '~/env'
+
+export type PlanId = 'free' | 'pro' | 'ultimate'
+
+type PlanPrice = {
+  id: string
+  /** Minor units, as Stripe stores them: 2000 is $20.00. */
+  amount: number
+  currency: string
+}
+
+export type Plan = {
+  id: PlanId
+  name: string
+  maxMembers: number
+  stripePrice?: { monthly: PlanPrice; annual: PlanPrice }
+  canUseTrial?: boolean
+}
+
+/** Every plan, cheapest first. Stripe prices come from `bun run stripe:setup`. */
+export const PLANS: Plan[] = [
+  {
+    id: 'free',
+    name: 'Free',
+    maxMembers: 1
+  },
+  {
+    id: 'pro',
+    name: 'Pro',
+    maxMembers: 25,
+    stripePrice: {
+      monthly: {
+        id: env.STRIPE_PRICE_PRO_MONTHLY,
+        amount: 2000,
+        currency: 'USD'
+      },
+      annual: {
+        id: env.STRIPE_PRICE_PRO_ANNUAL,
+        amount: 20000,
+        currency: 'USD'
+      }
+    },
+    canUseTrial: true
+  },
+  {
+    id: 'ultimate',
+    name: 'Ultimate',
+    maxMembers: 100,
+    stripePrice: {
+      monthly: {
+        id: env.STRIPE_PRICE_ULTIMATE_MONTHLY,
+        amount: 10000,
+        currency: 'USD'
+      },
+      annual: {
+        id: env.STRIPE_PRICE_ULTIMATE_ANNUAL,
+        amount: 100000,
+        currency: 'USD'
+      }
+    }
+  }
+]
+
+/** Subscription statuses that keep the paid plan's features switched on. */
+export const ACTIVE_SUBSCRIPTION_STATUSES = [
+  'trialing',
+  'active',
+  'past_due'
+] as const
+
+export function isActiveSubscriptionStatus(status: string): boolean {
+  return (ACTIVE_SUBSCRIPTION_STATUSES as readonly string[]).includes(status)
+}
+
+/**
+ * Statuses with no live Stripe subscription behind them. Any other status
+ * (including `unpaid`, `paused`, and `incomplete`) still bills or can resume,
+ * so changes go through the billing portal instead of a new checkout.
+ */
+export const ENDED_SUBSCRIPTION_STATUSES = [
+  'free',
+  'canceled',
+  'incomplete_expired'
+] as const
+
+export function hasLiveSubscription(status: string): boolean {
+  return !(ENDED_SUBSCRIPTION_STATUSES as readonly string[]).includes(status)
+}

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

@@ -0,0 +1,44 @@
+/**
+ * Organization role predicates and labels, shared by server and client.
+ *
+ * The roles are the Better Auth organization plugin defaults:
+ *   - owner: full control, including ownership transfer and deletion
+ *   - admin: manages settings, billing, and members, but not ownership
+ *   - member: standard access to the organization's workspace
+ */
+
+export type OrganizationRole = 'owner' | 'admin' | 'member'
+
+/** Roles an owner or admin can give to someone. Ownership moves only by transfer. */
+export const ASSIGNABLE_ROLES = ['admin', 'member'] as const
+
+export type AssignableRole = (typeof ASSIGNABLE_ROLES)[number]
+
+/** True for the manager tier: owner and admin. */
+export function isManagerRole(role: string | null | undefined): boolean {
+  return role === 'owner' || role === 'admin'
+}
+
+/** Descriptions shown when you pick a role for a member or an invitation. */
+export const ROLE_DESCRIPTIONS: Record<AssignableRole, string> = {
+  admin: 'Admin: manage settings, billing, and members',
+  member: 'Member: use the workspace'
+}
+
+/** Shown to an owner before they transfer ownership to another member. */
+export const OWNERSHIP_DEMOTION_NOTICE =
+  'After the transfer, your role becomes admin: you keep every permission except ownership transfer and organization deletion.'
+
+/** Role with its article, for sentences such as "join Acme as an admin". */
+export function roleArticle(role: string): string {
+  switch (role) {
+    case 'owner':
+      return 'an owner'
+    case 'admin':
+      return 'an admin'
+    case 'member':
+      return 'a member'
+    default:
+      return `a ${role}`
+  }
+}

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

@@ -0,0 +1,126 @@
+'use client'
+
+import {
+  useMutation,
+  useQuery,
+  type UseMutationOptions,
+  type UseQueryOptions
+} from '@tanstack/react-query'
+import type { SafeActionResult } from 'next-safe-action'
+
+/** Type helper for any server action function */
+export type AnyAction = (
+  ...args: any[]
+) => Promise<SafeActionResult<any, any, any, any, any>>
+
+/** Extracts the input type from a server action */
+type ActionInput<T extends AnyAction> = Parameters<T>[0]
+
+/** Extracts the data type from a server action result */
+type ActionData<T extends AnyAction> = Awaited<ReturnType<T>>['data']
+
+/**
+ * Client-side error for server action failures.
+ * Carries the user-facing `serverError` string (including unmasked AppError
+ * messages) and optional Zod validation errors.
+ */
+class SafeActionError extends Error {
+  constructor(
+    public message: string,
+    public validationErrors?: Record<string, string[] | undefined>
+  ) {
+    super(message)
+    this.name = 'SafeActionError'
+  }
+}
+
+/**
+ * React Query hook for server actions that fetch data
+ * Wraps server actions with proper error handling and caching support
+ *
+ * @param key - Unique query key for caching
+ * @param action - Server action function to execute
+ * @param input - Input parameters for the server action (optional)
+ * @param options - React Query options (staleTime, refetchInterval, etc.)
+ *
+ * @returns React Query result with data, loading, and error states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading } = useSafeActionQuery('cart-items', getCartItems)
+ * ```
+ */
+export function useSafeActionQuery<TAction extends AnyAction>(
+  key: string,
+  action: TAction,
+  input?: ActionInput<TAction>,
+  options?: Omit<UseQueryOptions<ActionData<TAction>>, 'queryKey' | 'queryFn'>
+) {
+  return useQuery({
+    queryKey: [key, input],
+    queryFn: async () => {
+      const result = await action(input)
+
+      if (result?.serverError) {
+        throw new SafeActionError(result.serverError)
+      }
+
+      if (result?.validationErrors) {
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
+      }
+
+      return result?.data
+    },
+    ...options
+  })
+}
+
+/**
+ * React Query mutation hook for server actions that modify data
+ * Wraps server actions with proper error handling and optimistic updates support
+ *
+ * @param action - Server action function to execute
+ * @param options - React Query mutation options (onSuccess, onError, etc.)
+ *
+ * @returns React Query mutation result with mutate function and states
+ *
+ * @example
+ * ```tsx
+ * const { mutate, isPending } = useSafeActionMutation(addToCart, {
+ *   onSuccess: (data) => {
+ *     toastSuccessMessage('Added to cart!')
+ *     queryClient.invalidateQueries({ queryKey: ['cart-items'] })
+ *   },
+ *   onError: (error) => {
+ *     toastActionError(error, 'Failed to add to cart')
+ *   }
+ * })
+ * ```
+ */
+export function useSafeActionMutation<TAction extends AnyAction>(
+  action: TAction,
+  options?: UseMutationOptions<ActionData<TAction>, Error, ActionInput<TAction>>
+) {
+  return useMutation({
+    mutationFn: async (input: ActionInput<TAction>) => {
+      const result = await action(input)
+
+      if (result?.serverError) {
+        throw new SafeActionError(result.serverError)
+      }
+
+      if (result?.validationErrors) {
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
+      }
+
+      return result?.data
+    },
+    ...options
+  })
+}

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

@@ -0,0 +1,187 @@
+import 'server-only'
+
+import { createSafeActionClient } from 'next-safe-action'
+import { getAuthSession } from './auth'
+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.'
+
+type ActionServerArgs = {
+  parsedInput?: unknown
+  clientInput?: unknown
+  [key: string]: unknown
+}
+
+/**
+ * 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({
+        outcome: 'error',
+        duration_ms: Date.now() - startedAt
+      })
+      throw error
+    }
+  }
+}
+
+/**
+ * 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 AppError(AppErrorCode.UNAUTHORIZED, 'Sign in to continue.')
+  }
+
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.user,
+      session: ctx.session
+    }
+  })
+})
+
+/**
+ * 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 AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have permission to do this.'
+    )
+  }
+
+  return next({
+    ctx: {
+      ...ctx,
+      user: ctx.user,
+      session: ctx.session
+    }
+  })
+})
+
+/**
+ * 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 AppError(
+        AppErrorCode.FORBIDDEN,
+        'You do not have permission to do this.'
+      )
+    }
+
+    return next({
+      ctx: {
+        ...ctx,
+        user: ctx.user,
+        session: ctx.session
+      }
+    })
+  }
+)

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

@@ -0,0 +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',
+  logo: '/logo.svg',
+  logoDark: '/logo-dark.svg',
+  contact: {
+    email: 'hello@example.com'
+  },
+  legal: {
+    lastUpdated: 'September 25, 2026'
+  }
+}