create-ej-app 26.0.0 → 28.0.0

package/template/saas-starter/src/db/schema.ts

@@ -1,6 +1,14 @@
+/**
+ * @fileoverview Drizzle table definitions.
+ *
+ * Enums live in `./enums.ts` and reusable column helpers in `./common.ts`.
+ * Every foreign key leads an index and declares an explicit `onDelete`;
+ * `tests/db/fk-indexes.test.ts` enforces both.
+ */
 import { sql } from 'drizzle-orm'
 import {
   boolean,
+  check,
   index,
   integer,
   jsonb,
@@ -9,27 +17,35 @@ import {
   uniqueIndex,
   varchar
 } from 'drizzle-orm/pg-core'
-import { commonFieldDefs } from './common'
+import { commonFieldDefs, nonNegativeCheck } from './common'
 import {
   organizationSubscriptionIntervalEnum,
   organizationSubscriptionPlanEnum,
-  organizationSubscriptionStatusEnum
+  organizationSubscriptionStatusEnum,
+  supportTicketPriorityEnum,
+  supportTicketStatusEnum
 } from './enums'
 
 export * from './enums'
 
-export const usersTable = pgTable('users', {
-  id: commonFieldDefs.id('user'),
-  name: text('name').notNull(),
-  email: text('email').notNull().unique(),
-  emailVerified: boolean('email_verified').default(false).notNull(),
-  image: text('image'),
-  role: text('role'),
-  banned: boolean('banned').default(false),
-  banReason: text('ban_reason'),
-  banExpires: commonFieldDefs.date('ban_expires'),
-  ...commonFieldDefs.dates
-})
+// ─── Auth (Better Auth) ─────────────────────────────────────────
+
+export const usersTable = pgTable(
+  'users',
+  {
+    id: commonFieldDefs.id('user'),
+    name: text('name').notNull(),
+    email: text('email').notNull().unique(),
+    emailVerified: boolean('email_verified').default(false).notNull(),
+    image: text('image'),
+    role: text('role'),
+    banned: boolean('banned').default(false),
+    banReason: text('ban_reason'),
+    banExpires: commonFieldDefs.date('ban_expires'),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.createdAt), index().on(table.role)]
+)
 
 export const sessionsTable = pgTable(
   'sessions',
@@ -70,13 +86,19 @@ export const accountsTable = pgTable(
   table => [index().on(table.userId)]
 )
 
-export const verificationsTable = pgTable('verifications', {
-  id: commonFieldDefs.id('verification'),
-  identifier: text('identifier').notNull(),
-  value: text('value').notNull(),
-  expiresAt: commonFieldDefs.date('expires_at').notNull(),
-  ...commonFieldDefs.dates
-})
+export const verificationsTable = pgTable(
+  'verifications',
+  {
+    id: commonFieldDefs.id('verification'),
+    identifier: text('identifier').notNull(),
+    value: text('value').notNull(),
+    expiresAt: commonFieldDefs.date('expires_at').notNull(),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.identifier)]
+)
+
+// ─── Organizations (Better Auth) ────────────────────────────────
 
 export const organizationsTable = pgTable('organizations', {
   id: commonFieldDefs.id('organization'),
@@ -100,7 +122,10 @@ export const membersTable = pgTable(
     role: text('role').notNull(),
     ...commonFieldDefs.dates
   },
-  table => [index().on(table.organizationId), index().on(table.userId)]
+  table => [
+    uniqueIndex().on(table.organizationId, table.userId),
+    index().on(table.userId)
+  ]
 )
 
 export const invitationsTable = pgTable(
@@ -116,20 +141,21 @@ export const invitationsTable = pgTable(
     expiresAt: commonFieldDefs.date('expires_at'),
     inviterId: text('inviter_id')
       .notNull()
-      .references(() => usersTable.id, {
-        onDelete: 'cascade'
-      }),
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
     ...commonFieldDefs.dates
   },
   table => [
     index().on(table.organizationId),
     index().on(table.email),
+    index().on(table.inviterId),
     uniqueIndex()
       .on(table.organizationId, table.email)
       .where(sql`${table.status} = 'pending'`)
   ]
 )
 
+// ─── Billing ────────────────────────────────────────────────────
+
 export const organizationSubscriptionsTable = pgTable(
   'organization_subscriptions',
   {
@@ -137,7 +163,7 @@ export const organizationSubscriptionsTable = pgTable(
     organizationId: text('organization_id')
       .notNull()
       .unique()
-      .references(() => organizationsTable.id),
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
     plan: organizationSubscriptionPlanEnum('plan').notNull().default('free'),
     status: organizationSubscriptionStatusEnum('status')
       .notNull()
@@ -154,6 +180,7 @@ export const organizationSubscriptionsTable = pgTable(
   }
 )
 
+/** One row per Stripe event, so a redelivered webhook is processed once. */
 export const stripeWebhooksEventsTable = pgTable('stripe_webhooks_events', {
   id: text('id').primaryKey(),
   type: text('type').notNull(),
@@ -161,31 +188,155 @@ export const stripeWebhooksEventsTable = pgTable('stripe_webhooks_events', {
   processed: boolean('processed').notNull().default(false),
   processedAt: commonFieldDefs.date('processed_at'),
   error: text('error'),
-  payload: jsonb('payload') // store only on error
+  // Stored only when processing fails, for replay and debugging.
+  payload: jsonb('payload')
 })
 
+// ─── Support ────────────────────────────────────────────────────
+
+/** Single-row counter behind `TICKET-000001` numbers; see `scripts/setup-db.ts`. */
+export const supportTicketCounterTable = pgTable(
+  'support_ticket_counter',
+  {
+    id: integer('id').primaryKey().default(1),
+    counter: integer('counter').notNull().default(0)
+  },
+  table => [
+    nonNegativeCheck('support_ticket_counter_counter_non_negative', [
+      table.counter
+    ])
+  ]
+)
+
+/**
+ * A ticket with an `organizationId` belongs to that organization's managers.
+ * A ticket without one is an account ticket, visible only to its author.
+ * Platform admins see both.
+ */
+export const supportTicketsTable = pgTable(
+  'support_tickets',
+  {
+    id: commonFieldDefs.id('support_ticket'),
+    // The database fills this in from a trigger; see `scripts/setup-db.ts`.
+    ticketNumber: varchar('ticket_number')
+      .notNull()
+      .unique()
+      .$defaultFn(() => ''),
+    organizationId: varchar('organization_id').references(
+      () => organizationsTable.id,
+      { onDelete: 'set null' }
+    ),
+    userId: varchar('user_id').references(() => usersTable.id, {
+      onDelete: 'set null'
+    }),
+    subject: varchar('subject').notNull(),
+    status: supportTicketStatusEnum('status').notNull().default('open'),
+    priority: supportTicketPriorityEnum('priority'),
+    resolvedAt: commonFieldDefs.date('resolved_at'),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.userId, table.createdAt),
+    index().on(table.organizationId, table.createdAt),
+    index().on(table.status),
+    index().on(table.priority)
+  ]
+)
+
+export const supportTicketMessagesTable = pgTable(
+  'support_ticket_messages',
+  {
+    id: commonFieldDefs.id('support_ticket_message'),
+    ticketId: varchar('ticket_id')
+      .notNull()
+      .references(() => supportTicketsTable.id, { onDelete: 'cascade' }),
+    userId: varchar('user_id').references(() => usersTable.id, {
+      onDelete: 'set null'
+    }),
+    message: text('message').notNull(),
+    /** True when the support team wrote it, even if the author is also a customer. */
+    isAdmin: boolean('is_admin').notNull().default(false),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.ticketId), index().on(table.userId)]
+)
+
+export const feedbacksTable = pgTable(
+  'feedbacks',
+  {
+    id: commonFieldDefs.id('feedback'),
+    userId: varchar('user_id')
+      .notNull()
+      .references(() => usersTable.id, { onDelete: 'cascade' }),
+    organizationId: varchar('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'cascade' }),
+    rating: integer('rating').notNull(),
+    comment: text('comment'),
+    ...commonFieldDefs.dates
+  },
+  table => [
+    index().on(table.userId),
+    index().on(table.organizationId, table.createdAt),
+    index().on(table.createdAt),
+    check('feedbacks_rating_range', sql`${table.rating} BETWEEN 1 AND 5`)
+  ]
+)
+
+export const contactLeadsTable = pgTable(
+  'contact_leads',
+  {
+    id: commonFieldDefs.id('contact_lead'),
+    name: varchar('name').notNull(),
+    email: varchar('email').notNull(),
+    phone: varchar('phone'),
+    subject: varchar('subject').notNull(),
+    message: text('message').notNull(),
+    ...commonFieldDefs.dates
+  },
+  table => [index().on(table.createdAt)]
+)
+
+// ─── Uploads ────────────────────────────────────────────────────
+
 export const fileUploadsTable = pgTable(
   'file_uploads',
   {
-    id: varchar('id').primaryKey(),
-    // Object path e.g. uploads/organizations/organizationId/filename.jpg
+    id: commonFieldDefs.id('file_upload'),
+    // Object key, such as uploads/organizations/<organizationId>/<file>.jpg
     key: text('key').notNull().unique(),
     originalName: varchar('original_name').notNull(),
     mimeType: varchar('mime_type').notNull(),
-    // In Bytes
+    // In bytes
     size: integer('size').notNull(),
     isTemp: boolean('is_temp').notNull().default(true),
     uploadedBy: varchar('uploaded_by').references(() => usersTable.id, {
       onDelete: 'set null'
     }),
-    // Nullable: scopes upload to a organization for cleanup purposes
-    organizationId: varchar('organization_id').references(
-      () => organizationsTable.id
-    ),
+    // `restrict` forces organization deletion to remove the R2 objects first;
+    // see `deleteOrganizationUploads`.
+    organizationId: varchar('organization_id')
+      .notNull()
+      .references(() => organizationsTable.id, { onDelete: 'restrict' }),
     ...commonFieldDefs.dates
   },
   table => [
     index().on(table.uploadedBy),
-    index().on(table.isTemp, table.createdAt)
+    index().on(table.organizationId),
+    index().on(table.isTemp, table.createdAt),
+    nonNegativeCheck('file_uploads_size_non_negative', [table.size])
   ]
 )
+
+// ─── Seed ───────────────────────────────────────────────────────
+
+/**
+ * Singleton marker for a successful `seedDatabase` run. While
+ * {@link SEED_RUN_MARKER_ID} exists, the seed script does nothing.
+ */
+export const SEED_RUN_MARKER_ID = 'seed_run_default'
+
+export const seedRunsTable = pgTable('seed_runs', {
+  id: varchar('id').primaryKey(),
+  ...commonFieldDefs.dates
+})

package/template/saas-starter/src/emails/components/email-layout.tsx

@@ -1,8 +1,14 @@
+/**
+ * @fileoverview Shared email shell: a brand rule and name at the top, the
+ * content, and a copyright footer. Every template wraps its body in it.
+ *
+ * @module emails/components/email-layout
+ */
+
 import {
   Body,
   Container,
   Head,
-  Hr,
   Html,
   pixelBasedPreset,
   Preview,
@@ -11,7 +17,11 @@ import {
   Text
 } from 'react-email'
 
+/** Brand color. Email clients strip CSS variables, so it is a literal here. */
+const BRAND = '#171717'
+
 interface EmailLayoutProps {
+  /** Text email clients show in the inbox before the email is opened. */
   previewText: string
   companyName: string
   children: React.ReactNode
@@ -28,31 +38,37 @@ export default function EmailLayout({
       <Preview>{previewText}</Preview>
       <Tailwind
         config={{
-          presets: [pixelBasedPreset]
+          presets: [pixelBasedPreset],
+          theme: { extend: { colors: { brand: BRAND } } }
         }}
       >
         <Body className="bg-gray-100 font-sans">
           <Container className="mx-auto my-8 max-w-xl rounded-lg bg-white shadow-sm">
-            {/* Header */}
-            <Section className="rounded-t-lg bg-black px-8 py-6">
-              <Text className="m-0 text-center text-2xl font-bold text-white">
+            <Section
+              className="rounded-t-lg bg-white px-8 py-5"
+              style={{
+                borderTop: `4px solid ${BRAND}`,
+                borderBottom: '1px solid #E5E7EB'
+              }}
+            >
+              <Text className="m-0 text-lg font-bold tracking-tight text-gray-900">
                 {companyName}
               </Text>
             </Section>
 
-            {/* Content */}
             <Section className="px-8 py-6">{children}</Section>
 
-            {/* Footer */}
-            <Section className="rounded-b-lg bg-gray-50 px-8 py-6">
-              <Hr className="my-4 border-gray-200" />
+            <Section
+              className="rounded-b-lg bg-gray-50 px-8 py-6"
+              style={{ borderTop: '1px solid #E5E7EB' }}
+            >
               <Text className="m-0 text-center text-sm text-gray-500">
                 &copy; {new Date().getUTCFullYear()} {companyName}. All rights
                 reserved.
               </Text>
               <Text className="m-0 mt-2 text-center text-xs text-gray-400">
-                This is an automated email. Please do not reply directly to this
-                message.
+                This is an automated email. Replies to this address are not
+                read.
               </Text>
             </Section>
           </Container>

package/template/saas-starter/src/emails/invitation.tsx

@@ -1,56 +1,69 @@
 import { Button, Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { INVITATION_EXPIRES_IN_DAYS } from '~/lib/constants'
+import { roleArticle } from '~/lib/rbac'
+import { siteConfig } from '~/lib/siteConfig'
 
 export interface InvitationEmailProps {
-  inviterName: string
+  inviteUrl: string
   organizationName: string
-  inviteLink: string
+  inviterName: string
+  role: string
   companyName: string
 }
 
+/** Invitation to join an organization, sent by the Better Auth organization plugin. */
 export default function InvitationEmail({
-  inviterName,
+  inviteUrl,
   organizationName,
-  inviteLink,
+  inviterName,
+  role,
   companyName
 }: InvitationEmailProps) {
-  const previewText = `${inviterName} invited you to join ${organizationName}`
-
   return (
-    <EmailLayout previewText={previewText} companyName={companyName}>
+    <EmailLayout
+      previewText={`${inviterName} invited you to join ${organizationName}`}
+      companyName={companyName}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
-        You've been invited to join {organizationName}
+        You&apos;re Invited to Join {organizationName}
       </Heading>
 
       <Text className="mb-4 text-base text-gray-700">
-        <strong>{inviterName}</strong> has invited you to collaborate in{' '}
-        <strong>{organizationName}</strong> on {companyName}.
+        {inviterName} invited you to join <strong>{organizationName}</strong> on{' '}
+        {companyName} as {roleArticle(role)}.
+      </Text>
+
+      <Text className="mb-4 text-base text-gray-700">
+        Select the button below to accept. You&apos;ll sign in with this email
+        address first.
       </Text>
 
       <Button
-        href={inviteLink}
-        className="mb-4 rounded-lg bg-black px-6 py-3 text-center text-base font-semibold text-white no-underline"
+        href={inviteUrl}
+        className="bg-brand mb-4 rounded-lg px-6 py-3 text-center text-base font-semibold text-white no-underline"
       >
         Accept Invitation
       </Button>
 
       <Text className="mb-4 text-sm text-gray-600">
-        Or copy and paste this link into your browser:
+        Or copy this link into your browser:
       </Text>
 
-      <Text className="mb-4 text-sm break-all text-blue-600">{inviteLink}</Text>
+      <Text className="text-brand mb-4 text-sm break-all">{inviteUrl}</Text>
 
       <Text className="text-sm text-gray-500">
-        If you weren't expecting this invitation, you can safely ignore this
-        email.
+        This invitation expires in {INVITATION_EXPIRES_IN_DAYS} days. If you
+        weren&apos;t expecting it, you can ignore this email.
       </Text>
     </EmailLayout>
   )
 }
 
 InvitationEmail.PreviewProps = {
-  inviterName: 'John Doe',
-  organizationName: 'Acme Inc',
-  inviteLink: 'https://example.com/accept-invitation/abc123',
-  companyName: 'Example Site'
+  inviteUrl: 'https://example.com/accept-invitation/your_invitation_id_here',
+  organizationName: 'Acme Inc.',
+  inviterName: 'Alex Morgan',
+  role: 'member',
+  companyName: siteConfig.name
 } satisfies InvitationEmailProps

package/template/saas-starter/src/emails/magic-link.tsx

@@ -1,49 +1,51 @@
 import { Button, Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 export interface MagicLinkEmailProps {
   magicLink: string
   companyName: string
 }
 
+/** Passwordless sign-in link. The link works once and expires in 5 minutes. */
 export default function MagicLinkEmail({
   magicLink,
   companyName
 }: MagicLinkEmailProps) {
-  const previewText = `Your magic link to sign in to ${companyName}`
-
   return (
-    <EmailLayout previewText={previewText} companyName={companyName}>
+    <EmailLayout
+      previewText={`Your link to sign in to ${companyName}`}
+      companyName={companyName}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
-        Sign in to {companyName}
+        Sign In to {companyName}
       </Heading>
 
       <Text className="mb-4 text-base text-gray-700">
-        Click the button below to securely sign in to your account. This link
-        will expire in 5 minutes.
+        Select the button below to sign in. The link expires in 5 minutes.
       </Text>
 
       <Button
         href={magicLink}
-        className="mb-4 rounded-lg bg-black px-6 py-3 text-center text-base font-semibold text-white no-underline"
+        className="bg-brand mb-4 rounded-lg px-6 py-3 text-center text-base font-semibold text-white no-underline"
       >
         Sign In
       </Button>
 
       <Text className="mb-4 text-sm text-gray-600">
-        Or copy and paste this link into your browser:
+        Or copy this link into your browser:
       </Text>
 
-      <Text className="mb-4 text-sm break-all text-blue-600">{magicLink}</Text>
+      <Text className="text-brand mb-4 text-sm break-all">{magicLink}</Text>
 
       <Text className="text-sm text-gray-500">
-        If you didn't request this email, you can safely ignore it.
+        If you didn&apos;t ask to sign in, you can ignore this email.
       </Text>
     </EmailLayout>
   )
 }
 
 MagicLinkEmail.PreviewProps = {
-  magicLink: 'https://example.com/magic-link?token=abc123',
-  companyName: 'Example Site'
+  magicLink: 'https://example.com/magic-link?token=your_magic_link_token_here',
+  companyName: siteConfig.name
 } satisfies MagicLinkEmailProps

package/template/saas-starter/src/emails/test.tsx

@@ -1,25 +1,27 @@
 import { Button, Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 interface TestEmailProps {
   name: string
 }
 
+/** Sent by `bun run email:test` to check SMTP settings. */
 export default function TestEmail({ name }: TestEmailProps) {
   return (
-    <EmailLayout previewText="This is a test email" companyName="Test">
+    <EmailLayout
+      previewText="Test email from your app"
+      companyName={siteConfig.name}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
         Test Email for {name}
       </Heading>
-      <Text className="mb-4 text-base text-gray-700">
-        This is a test email template to verify email functionality.
-      </Text>
       <Text className="mb-6 text-base text-gray-700">
-        If you're seeing this, the email system is working correctly.
+        Your SMTP settings work: this email reached your inbox.
       </Text>
       <Button
         href="https://example.com"
-        className="rounded-md bg-black px-5 py-3 text-center text-sm font-medium text-white"
+        className="bg-brand rounded-md px-5 py-3 text-center text-sm font-medium text-white"
       >
         Test Button
       </Button>
@@ -28,5 +30,5 @@ export default function TestEmail({ name }: TestEmailProps) {
 }
 
 TestEmail.PreviewProps = {
-  name: 'John Doe'
-}
+  name: 'Alex Morgan'
+} satisfies TestEmailProps

package/template/saas-starter/src/emails/welcome.tsx

@@ -1,34 +1,37 @@
 import { Heading, Text } from 'react-email'
-import EmailLayout from './components/email-layout'
+import EmailLayout from '~/emails/components/email-layout'
+import { siteConfig } from '~/lib/siteConfig'
 
 export interface WelcomeEmailProps {
   userName: string
   companyName: string
 }
 
+/** Sent once, right after an account is created. */
 export default function WelcomeEmail({
   userName,
   companyName
 }: WelcomeEmailProps) {
-  const previewText = `Welcome to ${companyName}! Your account has been created successfully.`
-
   return (
-    <EmailLayout previewText={previewText} companyName={companyName}>
+    <EmailLayout
+      previewText={`Welcome to ${companyName}. Your account is ready.`}
+      companyName={companyName}
+    >
       <Heading className="mb-4 text-2xl font-bold text-gray-900">
-        Welcome to {companyName}! 🎉
+        Welcome to {companyName}
       </Heading>
 
       <Text className="mb-4 text-base text-gray-700">Hi {userName},</Text>
 
       <Text className="mb-4 text-base text-gray-700">
-        Thank you for creating an account with us. We're thrilled to have you as
-        part of our community!
+        Your account is ready. Sign in any time with the email address this
+        message was sent to.
       </Text>
     </EmailLayout>
   )
 }
 
 WelcomeEmail.PreviewProps = {
-  userName: 'John Doe',
-  companyName: 'Example Site'
+  userName: 'Alex Morgan',
+  companyName: siteConfig.name
 } satisfies WelcomeEmailProps

package/template/saas-starter/src/env.ts

@@ -15,7 +15,7 @@ export const env = createEnv({
     EMAIL_SERVER_USER: z.string(),
     EMAIL_SERVER_PASSWORD: z.string(),
     EMAIL_SERVER_HOST: z.string(),
-    EMAIL_SERVER_PORT: z.string(),
+    EMAIL_SERVER_PORT: z.coerce.number().int().min(1).max(65535),
     EMAIL_FROM: z.email(),
     STRIPE_SECRET_KEY: z.string(),
     STRIPE_WEBHOOK_SECRET: z.string(),