create-ej-app 25.0.0 → 27.0.0

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

@@ -0,0 +1,312 @@
+import 'server-only'
+
+import { validateEmail } from '@ejekanshjain/simple-email-validator'
+import { createId } from '@paralleldrive/cuid2'
+import { APIError, betterAuth } from 'better-auth'
+import { drizzleAdapter } from 'better-auth/adapters/drizzle'
+import { createAuthMiddleware } from 'better-auth/api'
+import {
+  admin,
+  lastLoginMethod,
+  magicLink,
+  organization
+} from 'better-auth/plugins'
+import { and, count, eq, isNull, ne } from 'drizzle-orm'
+import { alias } from 'drizzle-orm/pg-core'
+import { headers } from 'next/headers'
+import { cache } from 'react'
+import { start } from 'workflow/api'
+import { db } from '~/db'
+import {
+  accountsTable,
+  invitationsTable,
+  membersTable,
+  organizationSubscriptionsTable,
+  organizationsTable,
+  sessionsTable,
+  usersTable,
+  verificationsTable
+} from '~/db/schema'
+import { env } from '~/env'
+import { ac, adminRoles, roles } from './auth-permissions'
+import {
+  INVITATION_EXPIRES_IN_DAYS,
+  MAX_ORGANIZATIONS_PER_USER
+} from './constants'
+import {
+  sendInvitationEmail,
+  sendMagicLinkEmail,
+  sendWelcomeEmail
+} from './email-service'
+import { getOrganizationPlan } from './plan-limits'
+import { siteConfig } from './siteConfig'
+import { deleteOrganizationUploads } from './storage'
+import { stripeClient } from './stripe'
+
+/**
+ * Blocks organization logos set through the Better Auth client. Logos go
+ * through `updateOrganizationAction`, which checks the upload belongs to the
+ * organization before saving it.
+ */
+function rejectClientLogo(logo: string | null | undefined) {
+  if (logo) {
+    throw new APIError('BAD_REQUEST', {
+      message: 'Change the logo from the organization settings page.'
+    })
+  }
+}
+
+/** True when `userId` is the only owner of at least one organization. */
+async function ownsOrganizationAlone(userId: string): Promise<boolean> {
+  const otherOwners = alias(membersTable, 'other_owners')
+
+  const [row] = await db
+    .select({ organizationId: membersTable.organizationId })
+    .from(membersTable)
+    .leftJoin(
+      otherOwners,
+      and(
+        eq(otherOwners.organizationId, membersTable.organizationId),
+        eq(otherOwners.role, 'owner'),
+        ne(otherOwners.userId, userId)
+      )
+    )
+    .where(
+      and(
+        eq(membersTable.userId, userId),
+        eq(membersTable.role, 'owner'),
+        isNull(otherOwners.id)
+      )
+    )
+    .limit(1)
+
+  return Boolean(row)
+}
+
+/**
+ * Better Auth configuration.
+ *
+ * Features:
+ * - Magic link email sign-in
+ * - OAuth (GitHub, Google) with account linking
+ * - Admin plugin with `user`, `admin`, and `superadmin` roles
+ * - Organization plugin with owner, admin, and member roles
+ */
+export const auth = betterAuth({
+  database: drizzleAdapter(db, {
+    provider: 'pg',
+    schema: {
+      user: usersTable,
+      session: sessionsTable,
+      account: accountsTable,
+      verification: verificationsTable,
+      organization: organizationsTable,
+      member: membersTable,
+      invitation: invitationsTable
+    }
+  }),
+  account: {
+    accountLinking: {
+      enabled: true
+    }
+  },
+  advanced: {
+    database: {
+      generateId: ({ model }) => `${model}_${createId()}`
+    }
+  },
+  socialProviders: {
+    github: {
+      prompt: 'select_account',
+      clientId: env.BETTER_AUTH_GITHUB_ID,
+      clientSecret: env.BETTER_AUTH_GITHUB_SECRET
+    },
+    google: {
+      prompt: 'select_account',
+      clientId: env.BETTER_AUTH_GOOGLE_ID,
+      clientSecret: env.BETTER_AUTH_GOOGLE_SECRET
+    }
+  },
+  databaseHooks: {
+    user: {
+      create: {
+        // Magic-link sign-up sends an empty name; fall back to the email's
+        // local part so greetings and avatars never render blank.
+        before: async user => ({
+          data: { ...user, name: user.name.trim() || user.email.split('@')[0]! }
+        }),
+        after: async user => {
+          try {
+            await start(sendWelcomeEmail, [
+              user.email,
+              {
+                userName: user.name,
+                companyName: siteConfig.name
+              }
+            ])
+          } catch (error) {
+            console.error('Failed to send welcome email:', error)
+          }
+        }
+      },
+      delete: {
+        before: async user => {
+          if (await ownsOrganizationAlone(user.id)) {
+            throw new APIError('BAD_REQUEST', {
+              message:
+                'This user is the only owner of an organization. Transfer ownership or delete the organization first.'
+            })
+          }
+        }
+      }
+    }
+  },
+  plugins: [
+    magicLink({
+      sendMagicLink: async ({ email, url }) => {
+        try {
+          await start(sendMagicLinkEmail, [
+            email,
+            {
+              magicLink: url,
+              companyName: siteConfig.name
+            }
+          ])
+        } catch (error) {
+          console.error('Failed to send magic link email:', error)
+        }
+      }
+    }),
+    admin({
+      ac,
+      roles,
+      adminRoles: [...adminRoles],
+      defaultRole: 'user'
+    }),
+    organization({
+      organizationLimit: MAX_ORGANIZATIONS_PER_USER,
+      invitationExpiresIn: INVITATION_EXPIRES_IN_DAYS * 24 * 60 * 60,
+      cancelPendingInvitationsOnReInvite: true,
+      sendInvitationEmail: async ({
+        id,
+        email,
+        role,
+        organization,
+        inviter
+      }) => {
+        try {
+          await start(sendInvitationEmail, [
+            email,
+            {
+              inviterName: inviter.user.name,
+              organizationName: organization.name,
+              inviteUrl: `${env.BETTER_AUTH_URL}/accept-invitation/${id}`,
+              role,
+              companyName: siteConfig.name
+            }
+          ])
+        } catch (error) {
+          console.error('Failed to send invitation email:', error)
+        }
+      },
+      organizationHooks: {
+        beforeCreateOrganization: async ({ organization }) => {
+          rejectClientLogo(organization.logo)
+        },
+        afterCreateOrganization: async ({ organization }) => {
+          await db.insert(organizationSubscriptionsTable).values({
+            organizationId: organization.id
+          })
+        },
+        beforeUpdateOrganization: async ({ organization }) => {
+          rejectClientLogo(organization.logo)
+        },
+        // Files go first: if R2 fails, the organization and its paid plan
+        // both stay intact. Stripe is cancelled only once nothing else can fail.
+        beforeDeleteOrganization: async ({ organization }) => {
+          await deleteOrganizationUploads(organization.id)
+
+          const sub = await db.query.organizationSubscriptionsTable.findFirst({
+            where: eq(
+              organizationSubscriptionsTable.organizationId,
+              organization.id
+            ),
+            columns: { stripeSubscriptionId: true }
+          })
+
+          if (sub?.stripeSubscriptionId) {
+            try {
+              await stripeClient.subscriptions.cancel(sub.stripeSubscriptionId)
+            } catch (error) {
+              console.error(
+                `Failed to cancel Stripe subscription ${sub.stripeSubscriptionId} while deleting organization ${organization.id}:`,
+                error
+              )
+              throw new APIError('BAD_REQUEST', {
+                message:
+                  'We could not cancel the active subscription, so the organization was kept. Try again in a few minutes.'
+              })
+            }
+          }
+        }
+      },
+      // Better Auth caps pending invitations at this number, so leave room
+      // only for the seats current members do not fill.
+      invitationLimit: async ({ organization }) => {
+        const [{ plan }, [row]] = await Promise.all([
+          getOrganizationPlan(organization.id),
+          db
+            .select({ count: count() })
+            .from(membersTable)
+            .where(eq(membersTable.organizationId, organization.id))
+        ])
+        return Math.max(0, plan.maxMembers - (row?.count ?? 0))
+      },
+      membershipLimit: async (_, organization) => {
+        const { plan } = await getOrganizationPlan(organization.id)
+        return plan.maxMembers
+      }
+    }),
+    lastLoginMethod()
+  ],
+  hooks: {
+    before: createAuthMiddleware(async ctx => {
+      if (ctx.path === '/sign-in/magic-link' && ctx.body?.email) {
+        try {
+          const validation = await validateEmail({
+            email: ctx.body.email
+          })
+
+          if (validation.isValid === false) {
+            throw new APIError('BAD_REQUEST', {
+              message: 'Please use a valid email address.'
+            })
+          }
+        } catch (err) {
+          console.error('Email validation failed', err)
+        }
+      }
+    })
+  }
+})
+
+/**
+ * The current session, cached per request.
+ *
+ * Returns null when signed out. `isAdmin` is true for both `admin` and
+ * `superadmin` (admin panel access). `isSuperAdmin` is true only for
+ * `superadmin` (user management, role changes, and impersonation).
+ */
+export const getAuthSession = cache(async () => {
+  const authSession = await auth.api.getSession({
+    headers: await headers()
+  })
+
+  if (!authSession || !authSession.user || !authSession.session) return null
+
+  const role = authSession.user.role
+  const isSuperAdmin = role === 'superadmin'
+  const isAdmin = role === 'admin' || isSuperAdmin
+
+  return { ...authSession, isAdmin, isSuperAdmin }
+})

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

@@ -0,0 +1,152 @@
+import 'server-only'
+
+import { eq } from 'drizzle-orm'
+import { db } from '~/db'
+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: PlanId; interval: 'month' | 'year' } | null => {
+  for (const plan of PLANS) {
+    if (!plan.stripePrice) continue
+    if (plan.stripePrice.monthly.id === priceId)
+      return { planId: plan.id, interval: 'month' }
+    if (plan.stripePrice.annual.id === priceId)
+      return { planId: plan.id, interval: 'year' }
+  }
+  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 (
+  sub: SubscriptionRow
+): Promise<string> => {
+  if (sub.stripeCustomerId) return sub.stripeCustomerId
+
+  if (!sub.billingEmail) {
+    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, sub.organizationId),
+    columns: { name: true }
+  })
+
+  // 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.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: 10
+  })
+
+  // 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 ||
+    sub.status === 'canceled' ||
+    sub.status === 'incomplete_expired'
+  ) {
+    await db
+      .update(organizationSubscriptionsTable)
+      .set({
+        plan: 'free',
+        status: 'free',
+        interval: null,
+        stripeSubscriptionId: null,
+        trialEndsAt: null,
+        currentPeriodEnd: null,
+        cancelAtPeriodEnd: false
+      })
+      .where(eq(organizationSubscriptionsTable.stripeCustomerId, customerId))
+    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 plan; the organization stays on the free plan.`
+    )
+  }
+
+  const periodEnd = item?.current_period_end ?? null
+
+  await db
+    .update(organizationSubscriptionsTable)
+    .set({
+      plan: resolved?.planId ?? 'free',
+      status: sub.status as SubscriptionStatus,
+      interval: resolved?.interval ?? null,
+      stripeSubscriptionId: sub.id,
+      trialEndsAt: sub.trial_end ? new Date(sub.trial_end * 1000) : null,
+      currentPeriodEnd: periodEnd ? new Date(periodEnd * 1000) : null,
+      cancelAtPeriodEnd: sub.cancel_at_period_end,
+      ...(sub.status === 'trialing' ? { hasUsedTrial: true } : {})
+    })
+    .where(eq(organizationSubscriptionsTable.stripeCustomerId, customerId))
+}

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/cn.ts

@@ -0,0 +1,4 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export const cn = (...inputs: ClassValue[]) => twMerge(clsx(inputs))

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

@@ -0,0 +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
+// ============================================
+
+/** Length of the free trial on paid plans that offer one */
+export const TRIAL_DAYS = 7
+
+// ============================================
+// 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
+// ============================================
+
+/** Seconds the client has to complete a presigned upload */
+export const PRESIGNED_URL_TTL_SECONDS = 900
+
+/** Age after which an unconfirmed upload is deleted */
+export const TEMP_CLEANUP_THRESHOLD_MS = 2 * 60 * 60 * 1000
+
+/** Maximum upload size in MB */
+export const MAX_FILE_SIZE_MB = 5
+
+/** 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

@@ -0,0 +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))