create-ej-app 26.0.0 → 27.0.0

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

@@ -1,93 +1,73 @@
 import 'server-only'
 
-import { and, count, desc, eq } from 'drizzle-orm'
-import { cache } from 'react'
+import { and, eq, inArray } from 'drizzle-orm'
 import { db } from '~/db'
-import { membersTable, organizationsTable } from '~/db/schema'
-import type { UserOrganization } from './app-navigation'
-import { getAuthSession } from './auth'
-import { resolveImageUrl } from './storage'
+import { membersTable } from '~/db/schema'
+import { AppError, AppErrorCode } from './errors'
+import type { OrganizationRole } from './rbac'
 
-const getUserOrganizations = async (): Promise<UserOrganization[]> => {
-  const session = await getAuthSession()
-  if (!session) return []
-
-  const orgs = await db
-    .select({
-      id: organizationsTable.id,
-      name: organizationsTable.name,
-      slug: organizationsTable.slug,
-      logo: organizationsTable.logo,
-      role: membersTable.role,
-      userId: membersTable.userId,
-      memberId: membersTable.id
-    })
-    .from(membersTable)
-    .innerJoin(
-      organizationsTable,
-      eq(membersTable.organizationId, organizationsTable.id)
-    )
-    .where(eq(membersTable.userId, session.user.id))
-    .orderBy(desc(membersTable.createdAt))
-
-  return orgs.map(o => ({ ...o, logo: resolveImageUrl(o.logo) }))
-}
-
-export const getUserOrganizationsCached = cache(getUserOrganizations)
-
-export const getUserMembershipCached = cache(async (organizationId: string) => {
-  const session = await getAuthSession()
-  if (!session) return null
-
-  const member = await db.query.membersTable.findFirst({
+/**
+ * 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, session.user.id)
-    )
-  })
-
-  return member ?? null
-})
-
-export const getOrganizationMembers = cache(async (organizationId: string) =>
-  db.query.membersTable.findMany({
-    where: eq(membersTable.organizationId, organizationId),
-    with: {
-      user: {
-        columns: { id: true, name: true, email: true, image: true }
-      }
-    },
-    orderBy: [desc(membersTable.createdAt)]
+      eq(membersTable.userId, userId)
+    ),
+    columns: { id: true, role: true }
   })
-)
-
-export const getOrganizationMemberCount = cache(
-  async (organizationId: string) => {
-    const [row] = await db
-      .select({ count: count() })
-      .from(membersTable)
-      .where(eq(membersTable.organizationId, organizationId))
 
-    return row?.count ?? 0
-  }
-)
+  return membership ?? null
+}
 
-export const assertUserMembership = async (organizationId: string) => {
-  const membership = await getUserMembershipCached(organizationId)
+/**
+ * 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 Error('User does not have access to this organization')
+    throw new AppError(
+      AppErrorCode.FORBIDDEN,
+      'You do not have access to this organization.'
+    )
   }
   return membership
 }
 
-const MANAGER_ROLES = ['owner', 'admin']
-
-export const assertUserCanManageOrganization = async (
-  organizationId: string
-) => {
-  const membership = await getUserMembershipCached(organizationId)
-  if (!membership || !MANAGER_ROLES.includes(membership.role)) {
-    throw new Error('User does not have permission to manage this organization')
+/**
+ * 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

@@ -1,17 +1,107 @@
-import { SpanStatusCode, trace } from '@opentelemetry/api'
+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
 }
 
-export function recordWideEvent(attributes: Record<string, any>) {
+/**
+ * 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

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 }
+})

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

@@ -1,24 +1,25 @@
+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: 'free' | 'pro' | 'ultimate'
+  id: PlanId
   name: string
   maxMembers: number
-  stripePrice?: {
-    monthly: {
-      id: string
-      amount: number
-      currency: string
-    }
-    annual: {
-      id: string
-      amount: number
-      currency: string
-    }
-  }
+  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',
@@ -61,3 +62,29 @@ export const PLANS: Plan[] = [
     }
   }
 ]
+
+/** 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

@@ -8,25 +8,52 @@ import {
 } from '@tanstack/react-query'
 import type { SafeActionResult } from 'next-safe-action'
 
-type AnyAction = (
+/** 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>,
+  input?: ActionInput<TAction>,
   options?: Omit<UseQueryOptions<ActionData<TAction>>, 'queryKey' | 'queryFn'>
 ) {
   return useQuery({
@@ -39,7 +66,10 @@ export function useSafeActionQuery<TAction extends AnyAction>(
       }
 
       if (result?.validationErrors) {
-        throw new SafeActionError('Validation failed', result.validationErrors)
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
       }
 
       return result?.data
@@ -48,13 +78,31 @@ export function useSafeActionQuery<TAction extends AnyAction>(
   })
 }
 
+/**
+ * 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>,
-    SafeActionError,
-    ActionInput<TAction>
-  >
+  options?: UseMutationOptions<ActionData<TAction>, Error, ActionInput<TAction>>
 ) {
   return useMutation({
     mutationFn: async (input: ActionInput<TAction>) => {
@@ -65,7 +113,10 @@ export function useSafeActionMutation<TAction extends AnyAction>(
       }
 
       if (result?.validationErrors) {
-        throw new SafeActionError('Validation failed', result.validationErrors)
+        throw new SafeActionError(
+          'Check the highlighted fields and try again.',
+          result.validationErrors
+        )
       }
 
       return result?.data