create-ej-app 25.0.0 → 27.0.0

package/template/saas-starter/src/scripts/setup-db.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Installs Postgres functions and triggers that Drizzle cannot
+ * manage.
+ *
+ * Support tickets get a `TICKET-000001` number from a counter table. The
+ * counter function upserts atomically, and a BEFORE INSERT trigger fills in
+ * `ticket_number`, so inserts never pass the number themselves.
+ *
+ * Everything is CREATE OR REPLACE, so the script is safe to re-run.
+ * `bun run db:push` runs it before `drizzle-kit push`.
+ */
+
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+
+/** Installs every custom function and trigger on the given client. */
+export async function setupDatabase(database: typeof db = db): Promise<void> {
+  // INSERT ... ON CONFLICT ... DO UPDATE is one atomic statement, so two
+  // concurrent calls never receive the same number.
+  await database.execute(sql`
+    CREATE OR REPLACE FUNCTION get_next_support_ticket_number()
+    RETURNS TEXT AS $$
+    DECLARE
+        new_number INTEGER;
+    BEGIN
+        INSERT INTO support_ticket_counter (id, counter)
+        VALUES (1, 1)
+        ON CONFLICT (id)
+        DO UPDATE SET counter = support_ticket_counter.counter + 1
+        RETURNING counter INTO new_number;
+
+        RETURN 'TICKET-' || LPAD(new_number::TEXT, 6, '0');
+    END;
+    $$ LANGUAGE plpgsql;
+  `)
+
+  // An explicit ticket_number (seeding, migrations) skips the counter.
+  await database.execute(sql`
+    CREATE OR REPLACE FUNCTION trg_set_support_ticket_number()
+    RETURNS TRIGGER AS $$
+    BEGIN
+        IF NEW.ticket_number IS NULL OR NEW.ticket_number = '' THEN
+            NEW.ticket_number := get_next_support_ticket_number();
+        END IF;
+        RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql;
+  `)
+
+  // On a fresh database this runs before drizzle-kit push, so create a stub
+  // table for the trigger to attach to. The push then adds the real columns.
+  await database.execute(sql`
+    CREATE TABLE IF NOT EXISTS support_tickets (
+      id TEXT PRIMARY KEY
+    );
+  `)
+
+  await database.execute(sql`
+    CREATE OR REPLACE TRIGGER set_support_ticket_number
+    BEFORE INSERT ON support_tickets
+    FOR EACH ROW EXECUTE FUNCTION trg_set_support_ticket_number();
+  `)
+}
+
+if (import.meta.main) {
+  setupDatabase(db)
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error running setup-db:', err)
+      process.exit(1)
+    })
+}

package/template/saas-starter/src/scripts/setup-stripe-plans.ts

@@ -0,0 +1,206 @@
+/**
+ * @fileoverview Creates the Stripe products, prices, and billing portal
+ * configuration for every paid plan in `~/lib/plans`.
+ *
+ * Existing prices are reused. New IDs are written to `stripe.txt`; copy them
+ * into `.env`, then delete the file.
+ */
+import { writeFile } from 'fs/promises'
+import type Stripe from 'stripe'
+import { env } from '~/env'
+import { PLANS } from '~/lib/plans'
+import { stripeClient } from '~/lib/stripe'
+
+const checkStripePriceExists = async (priceId: string) => {
+  try {
+    await stripeClient.prices.retrieve(priceId)
+    return true
+  } catch (err) {
+    if (
+      err &&
+      typeof err === 'object' &&
+      'code' in err &&
+      (err as { code?: string }).code === 'resource_missing'
+    ) {
+      return false
+    }
+    throw err
+  }
+}
+
+const createStripeProduct = async (name: string, planId: string) => {
+  const newProduct = await stripeClient.products.create({
+    name,
+    metadata: { planId }
+  })
+
+  return newProduct.id
+}
+
+const createStripePrice = async (
+  productId: string,
+  planId: string,
+  interval: 'month' | 'year',
+  amount: number,
+  currency: string
+) => {
+  const newPrice = await stripeClient.prices.create({
+    product: productId,
+    currency,
+    unit_amount: amount,
+    recurring: { interval },
+    metadata: { planId }
+  })
+
+  return newPrice.id
+}
+
+type PaidPlanPrices = {
+  planId: string
+  productId: string
+  monthlyPriceId: string
+  annualPriceId: string
+}
+
+const setupStripePlans = async () => {
+  let newEnvString = ''
+  const paidPlans: PaidPlanPrices[] = []
+
+  for (const plan of PLANS) {
+    if (!plan.stripePrice) continue
+
+    const monthlyExists = await checkStripePriceExists(
+      plan.stripePrice.monthly.id
+    )
+    const annualExists = await checkStripePriceExists(
+      plan.stripePrice.annual.id
+    )
+
+    if ((!monthlyExists && annualExists) || (monthlyExists && !annualExists)) {
+      throw new Error(
+        `Inconsistent Stripe price setup for plan ${plan.name}. Monthly exists: ${monthlyExists}, Annual exists: ${annualExists}`
+      )
+    }
+
+    if (monthlyExists && annualExists) {
+      const price = await stripeClient.prices.retrieve(
+        plan.stripePrice.monthly.id
+      )
+      paidPlans.push({
+        planId: plan.id,
+        productId:
+          typeof price.product === 'string' ? price.product : price.product.id,
+        monthlyPriceId: plan.stripePrice.monthly.id,
+        annualPriceId: plan.stripePrice.annual.id
+      })
+      continue
+    }
+
+    const productId = await createStripeProduct(plan.name, plan.id)
+    const monthlyPriceId = await createStripePrice(
+      productId,
+      plan.id,
+      'month',
+      plan.stripePrice.monthly.amount,
+      plan.stripePrice.monthly.currency
+    )
+
+    newEnvString += `\nSTRIPE_PRICE_${plan.id.toUpperCase()}_MONTHLY="${monthlyPriceId}"`
+
+    const annualPriceId = await createStripePrice(
+      productId,
+      plan.id,
+      'year',
+      plan.stripePrice.annual.amount,
+      plan.stripePrice.annual.currency
+    )
+
+    newEnvString += `\nSTRIPE_PRICE_${plan.id.toUpperCase()}_ANNUAL="${annualPriceId}"`
+
+    paidPlans.push({
+      planId: plan.id,
+      productId,
+      monthlyPriceId,
+      annualPriceId
+    })
+  }
+
+  const portalConfigId = await setupPortalConfiguration(paidPlans)
+  if (portalConfigId) {
+    newEnvString += `\nSTRIPE_PORTAL_CONFIGURATION_ID="${portalConfigId}"`
+  }
+
+  newEnvString = newEnvString.trim()
+
+  if (newEnvString) {
+    await writeFile('stripe.txt', newEnvString)
+    console.info('Stripe setup complete. New values written to stripe.txt')
+  } else {
+    console.info('All Stripe plans and portal config already exist.')
+  }
+}
+
+const setupPortalConfiguration = async (paidPlans: PaidPlanPrices[]) => {
+  if (paidPlans.length === 0) return null
+
+  const params: Stripe.BillingPortal.ConfigurationCreateParams = {
+    features: {
+      customer_update: {
+        enabled: true,
+        allowed_updates: ['address', 'name', 'tax_id']
+      },
+      invoice_history: { enabled: true },
+      payment_method_update: { enabled: true },
+      subscription_cancel: {
+        enabled: true,
+        mode: 'at_period_end',
+        cancellation_reason: {
+          enabled: true,
+          options: [
+            'too_expensive',
+            'missing_features',
+            'switched_service',
+            'unused',
+            'other'
+          ]
+        }
+      },
+      subscription_update: {
+        enabled: true,
+        default_allowed_updates: ['price'],
+        proration_behavior: 'create_prorations',
+        products: paidPlans.map(p => ({
+          product: p.productId,
+          prices: [p.monthlyPriceId, p.annualPriceId]
+        }))
+      }
+    }
+  }
+
+  const existingId = env.STRIPE_PORTAL_CONFIGURATION_ID
+  if (existingId) {
+    try {
+      await stripeClient.billingPortal.configurations.update(existingId, params)
+      return null
+    } catch (err) {
+      const isMissing =
+        err &&
+        typeof err === 'object' &&
+        'code' in err &&
+        (err as { code?: string }).code === 'resource_missing'
+      if (!isMissing) throw err
+    }
+  }
+
+  const created = await stripeClient.billingPortal.configurations.create(params)
+  return created.id
+}
+
+if (import.meta.main) {
+  setupStripePlans()
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error setting up Stripe plans:', err)
+      process.exit(1)
+    })
+}

package/template/saas-starter/src/scripts/test-mail.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview Sends one test email to check SMTP settings.
+ *
+ * @example
+ * ```bash
+ * bun run email:test you@example.com
+ * ```
+ */
+
+import { render, toPlainText } from '@react-email/render'
+import TestEmail from '~/emails/test'
+import { sendEmail } from '~/lib/nodemailer'
+
+async function sendTestMail(to: string) {
+  const html = await render(TestEmail({ name: to }), { pretty: true })
+
+  const result = await sendEmail({
+    to,
+    subject: 'Test Email',
+    text: toPlainText(html),
+    html
+  })
+
+  console.info('Test email sent', result)
+}
+
+if (import.meta.main) {
+  const to = process.argv[2]
+
+  if (!to) {
+    console.error(
+      'Pass a recipient address: bun run email:test you@example.com'
+    )
+    process.exit(1)
+  }
+
+  sendTestMail(to)
+    .then(() => process.exit(0))
+    .catch(err => {
+      console.error('Error sending test mail:', err)
+      process.exit(1)
+    })
+}

package/template/saas-starter/tests/admin/users.test.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, test } from 'bun:test'
+import { createUser, getUsers, updateUser } from '~/app/(admin)/actions/users'
+import {
+  asAnonymous,
+  asUser,
+  expectData,
+  expectServerError,
+  Fixtures
+} from '../helpers'
+
+describe('admin user management', () => {
+  const fx = new Fixtures()
+  afterEach(() => fx.cleanup())
+
+  test('signed-out and regular users cannot reach admin actions', async () => {
+    const user = await fx.user()
+
+    expectServerError(
+      await asAnonymous(() => getUsers({ page: 1, limit: 10 })),
+      'sign in'
+    )
+    expectServerError(
+      await asUser(user, () => getUsers({ page: 1, limit: 10 })),
+      'permission'
+    )
+  })
+
+  test('a superadmin cannot remove their own superadmin role', async () => {
+    const superadmin = await fx.platformUser('superadmin')
+
+    const result = await asUser(superadmin, () =>
+      updateUser({
+        id: superadmin.id,
+        name: superadmin.name,
+        email: superadmin.email,
+        role: 'admin'
+      })
+    )
+
+    expectServerError(result, 'your own superadmin role')
+  })
+
+  test('admins cannot manage users; superadmins can', async () => {
+    const admin = await fx.platformUser('admin')
+    const superadmin = await fx.platformUser('superadmin')
+
+    expectServerError(
+      await asUser(admin, () => getUsers({ page: 1, limit: 10 })),
+      'permission'
+    )
+    expectData(await asUser(superadmin, () => getUsers({ page: 1, limit: 10 })))
+  })
+
+  test('creating a user with a taken email explains the conflict', async () => {
+    const superadmin = await fx.platformUser('superadmin')
+    const existing = await fx.user()
+
+    const result = await asUser(superadmin, () =>
+      createUser({ name: 'Duplicate', email: existing.email, role: 'user' })
+    )
+
+    expectServerError(result, 'already uses this email')
+  })
+})

package/template/saas-starter/tests/db/fk-indexes.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test'
+import { sql } from 'drizzle-orm'
+import { db } from '~/db'
+
+/**
+ * Postgres does not index foreign key columns automatically. Without an index,
+ * every cascade or SET NULL from the parent side sequentially scans the child
+ * table while holding row locks, so deleting one organization can stall the
+ * platform.
+ *
+ * This finds every FK whose leading column is not the leading column of any
+ * index, which is exactly the shape that degrades.
+ */
+const UNINDEXED_FOREIGN_KEYS = sql`
+  SELECT
+    c.conrelid::regclass::text AS table_name,
+    a.attname::text AS column_name
+  FROM pg_constraint c
+  JOIN pg_attribute a
+    ON a.attrelid = c.conrelid AND a.attnum = c.conkey[1]
+  WHERE c.contype = 'f'
+    AND NOT EXISTS (
+      SELECT 1
+      FROM pg_index i
+      WHERE i.indrelid = c.conrelid
+        AND i.indkey[0] = c.conkey[1]
+    )
+  ORDER BY 1, 2
+`
+
+/** postgres-js returns a row array; PGlite returns `{ rows }`. */
+const toRows = <T>(result: unknown): T[] =>
+  Array.isArray(result)
+    ? (result as T[])
+    : ((result as { rows: T[] }).rows ?? [])
+
+describe('foreign key indexing', () => {
+  test('every foreign key column leads an index', async () => {
+    const rows = toRows<{ table_name: string; column_name: string }>(
+      await db.execute(UNINDEXED_FOREIGN_KEYS)
+    )
+
+    expect(rows.map(r => `${r.table_name}.${r.column_name}`)).toEqual([])
+  })
+
+  test('every foreign key declares an explicit delete rule', async () => {
+    const rows = toRows<{ table_name: string; constraint_name: string }>(
+      await db.execute(sql`
+        SELECT
+          c.conrelid::regclass::text AS table_name,
+          c.conname::text AS constraint_name
+        FROM pg_constraint c
+        WHERE c.contype = 'f' AND c.confdeltype = 'a'
+        ORDER BY 1, 2
+      `)
+    )
+
+    // confdeltype 'a' is NO ACTION, which is what an omitted onDelete leaves
+    // behind. Every FK should say cascade, set null, or restrict on purpose.
+    expect(rows.map(r => `${r.table_name}.${r.constraint_name}`)).toEqual([])
+  })
+})

package/template/saas-starter/tests/db/seed.test.ts

@@ -0,0 +1,57 @@
+import { PGlite } from '@electric-sql/pglite'
+import { describe, expect, test } from 'bun:test'
+import { pushSchema } from 'drizzle-kit/api'
+import { drizzle } from 'drizzle-orm/pglite'
+import * as relations from '~/db/relations'
+import * as schema from '~/db/schema'
+import { seedDatabase } from '~/scripts/seed'
+import { setupDatabase } from '~/scripts/setup-db'
+
+/**
+ * The seed writes straight through the schema, around Zod, so it exercises
+ * CHECK constraints, foreign keys, and triggers against realistic data.
+ *
+ * It runs on its own PGlite instance: seeded rows would otherwise leak into
+ * every other suite in the same worker and break their counts.
+ */
+describe('seed script', () => {
+  test('applies cleanly once, then skips', async () => {
+    // Same Emscripten proc_exit side effect as tests/setup/pglite-db.ts.
+    const exitCodeBeforePglite = process.exitCode
+
+    const client = new PGlite()
+    const db = drizzle({ client, schema: { ...schema, ...relations } })
+
+    const { apply, hasDataLoss } = await pushSchema(
+      schema,
+      db as unknown as Parameters<typeof pushSchema>[1]
+    )
+    expect(hasDataLoss).toBe(false)
+    await apply()
+    await setupDatabase(db as unknown as Parameters<typeof setupDatabase>[0])
+
+    const seed = () =>
+      seedDatabase(db as unknown as Parameters<typeof seedDatabase>[0])
+
+    expect((await seed()).skipped).toBe(false)
+
+    const [users, organizations, subscriptions] = await Promise.all([
+      db.select().from(schema.usersTable),
+      db.select().from(schema.organizationsTable),
+      db.select().from(schema.organizationSubscriptionsTable)
+    ])
+    expect(users.map(user => user.role).sort()).toEqual(['superadmin', 'user'])
+    expect(organizations).toHaveLength(1)
+    expect(subscriptions).toHaveLength(1)
+
+    expect((await seed()).skipped).toBe(true)
+    expect(await db.select().from(schema.usersTable)).toHaveLength(2)
+
+    if (process.exitCode === 99) {
+      process.exitCode =
+        exitCodeBeforePglite !== undefined && exitCodeBeforePglite !== 99
+          ? exitCodeBeforePglite
+          : 0
+    }
+  }, 120_000)
+})

package/template/saas-starter/tests/helpers/action.ts

@@ -0,0 +1,71 @@
+import { expect } from 'bun:test'
+import { UNEXPECTED_ERROR_MESSAGE } from '~/lib/safe-action'
+
+type ActionResult = {
+  data?: unknown
+  serverError?: string
+  validationErrors?: unknown
+}
+
+const MASKED = UNEXPECTED_ERROR_MESSAGE
+
+export function expectData<T>(
+  result: ActionResult | undefined
+): asserts result is { data: T } {
+  if (!result) throw new Error('Expected action result, got undefined')
+  if (result.serverError) {
+    throw new Error(`Expected success, got serverError: ${result.serverError}`)
+  }
+  if (result.validationErrors) {
+    throw new Error(
+      `Expected success, got validationErrors: ${JSON.stringify(result.validationErrors)}`
+    )
+  }
+  if (result.data === undefined) {
+    throw new Error('Expected action data, got undefined')
+  }
+}
+
+/** Action returned null/undefined data (some actions swallow errors). */
+export function expectNoData(result: ActionResult | undefined) {
+  expect(result?.data ?? null).toBeNull()
+}
+
+/** Action was rejected by its input schema, before any handler ran. */
+export function expectValidationError(result: ActionResult | undefined) {
+  if (!result?.validationErrors) {
+    throw new Error(
+      `Expected validationErrors, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  return result.validationErrors
+}
+
+/**
+ * Action failed with a serverError.
+ * next-safe-action can mask thrown Error messages as a generic string.
+ * In that case, this helper only asserts that a failure occurred.
+ */
+export function expectServerError(
+  result: ActionResult | undefined,
+  messageIncludes?: string | RegExp
+) {
+  if (!result?.serverError) {
+    throw new Error(
+      `Expected serverError, got: ${JSON.stringify(result ?? null)}`
+    )
+  }
+  if (
+    messageIncludes &&
+    result.serverError.toLowerCase() !== MASKED.toLowerCase()
+  ) {
+    if (typeof messageIncludes === 'string') {
+      expect(result.serverError.toLowerCase()).toContain(
+        messageIncludes.toLowerCase()
+      )
+    } else {
+      expect(result.serverError).toMatch(messageIncludes)
+    }
+  }
+  return result.serverError
+}