create-ej-app 26.0.0 → 28.0.0

package/template/saas-starter/src/app/actions/support-tickets.ts

@@ -0,0 +1,510 @@
+'use server'
+
+import {
+  and,
+  asc,
+  count,
+  desc,
+  eq,
+  ilike,
+  inArray,
+  isNull,
+  or
+} from 'drizzle-orm'
+import { z } from 'zod'
+import { SortOrderEnum } from '~/components/data-table/enum'
+import { db } from '~/db'
+import {
+  organizationsTable,
+  supportTicketMessagesTable,
+  supportTicketsTable,
+  usersTable
+} from '~/db/schema'
+import { getPaginationSchema } from '~/lib/actions'
+import { AppError, AppErrorCode } from '~/lib/errors'
+import { assertCanManageOrganization } from '~/lib/organization-access'
+import {
+  adminActionClient,
+  authActionClient,
+  withWideEvent
+} from '~/lib/safe-action'
+import { likeContains } from '~/lib/search'
+import { optionalStringValidation } from '~/lib/validations'
+import {
+  ACCOUNT_TICKET_FILTER_VALUE,
+  addSupportTicketMessageSchema,
+  createSupportTicketSchema,
+  listAccountSupportTicketsSchema,
+  listAdminSupportTicketsSchema,
+  listOrganizationSupportTicketsSchema,
+  supportTicketIdSchema,
+  updateSupportTicketStatusSchema
+} from './support-tickets.validation'
+
+/**
+ * Tickets come in two shapes.
+ *
+ * An **organization ticket** has an `organizationId`. Every owner and admin
+ * of that organization reads and answers it, whoever opened the thread;
+ * members have no access. An **account ticket** has none, and belongs to the person who raised
+ * it alone, so any signed-in user can open one about their own account.
+ *
+ * Platform admins see both.
+ */
+
+const ticketSelect = {
+  id: supportTicketsTable.id,
+  ticketNumber: supportTicketsTable.ticketNumber,
+  subject: supportTicketsTable.subject,
+  status: supportTicketsTable.status,
+  priority: supportTicketsTable.priority,
+  createdAt: supportTicketsTable.createdAt,
+  resolvedAt: supportTicketsTable.resolvedAt,
+  userId: supportTicketsTable.userId,
+  userEmail: usersTable.email,
+  userName: usersTable.name,
+  organizationId: supportTicketsTable.organizationId,
+  organizationName: organizationsTable.name
+}
+
+const orderBy = (sortBy: string | undefined, sortOrder: string | undefined) => {
+  const column = supportTicketsTable[(sortBy || 'createdAt') as 'createdAt']
+  return sortOrder === SortOrderEnum.ASC ? asc(column) : desc(column)
+}
+
+/**
+ * Build the admin list's organization filter. The sentinel selects account
+ * tickets, which `inArray` cannot express, so the two halves are OR'd.
+ */
+function organizationFilter(selected: string[] | undefined) {
+  if (!selected?.length) return undefined
+
+  const organizationIds = selected.filter(
+    value => value !== ACCOUNT_TICKET_FILTER_VALUE
+  )
+  const conditions = [
+    ...(selected.includes(ACCOUNT_TICKET_FILTER_VALUE)
+      ? [isNull(supportTicketsTable.organizationId)]
+      : []),
+    ...(organizationIds.length
+      ? [inArray(supportTicketsTable.organizationId, organizationIds)]
+      : [])
+  ]
+
+  return or(...conditions)
+}
+
+/**
+ * Load a ticket and assert the caller may read it: a platform admin, a manager
+ * of the organization it belongs to, or the author of an account ticket.
+ */
+async function assertTicketAccess(
+  ticketId: string,
+  ctx: { user: { id: string }; isAdmin?: boolean }
+) {
+  const ticket = await db.query.supportTicketsTable.findFirst({
+    where: eq(supportTicketsTable.id, ticketId),
+    columns: { id: true, userId: true, status: true, organizationId: true }
+  })
+
+  if (!ticket)
+    throw new AppError(AppErrorCode.NOT_FOUND, 'Support ticket not found.')
+
+  // Branch explicitly. A missing organizationId means "author only", never
+  // "skip the check".
+  if (!ctx.isAdmin) {
+    if (ticket.organizationId) {
+      await assertCanManageOrganization(ticket.organizationId, ctx.user.id)
+    } else if (ticket.userId !== ctx.user.id) {
+      throw new AppError(
+        AppErrorCode.FORBIDDEN,
+        'You do not have permission to do this.'
+      )
+    }
+  }
+
+  return ticket
+}
+
+export const getOrganizationSupportTicketsAction = authActionClient
+  .inputSchema(listOrganizationSupportTicketsSchema)
+  .action(
+    withWideEvent(
+      'getOrganizationSupportTicketsAction',
+      async ({
+        parsedInput: {
+          organizationId,
+          page,
+          limit,
+          sortBy,
+          sortOrder,
+          search,
+          filters
+        },
+        ctx
+      }) => {
+        await assertCanManageOrganization(organizationId, ctx.user.id)
+
+        const where = and(
+          eq(supportTicketsTable.organizationId, organizationId),
+          search
+            ? or(
+                ilike(supportTicketsTable.ticketNumber, likeContains(search)),
+                ilike(supportTicketsTable.subject, likeContains(search))
+              )
+            : undefined,
+          filters?.status?.length
+            ? inArray(supportTicketsTable.status, filters.status)
+            : undefined,
+          filters?.priority?.length
+            ? inArray(supportTicketsTable.priority, filters.priority)
+            : undefined
+        )
+
+        const [results, total] = await Promise.all([
+          db
+            .select(ticketSelect)
+            .from(supportTicketsTable)
+            .leftJoin(usersTable, eq(supportTicketsTable.userId, usersTable.id))
+            .leftJoin(
+              organizationsTable,
+              eq(supportTicketsTable.organizationId, organizationsTable.id)
+            )
+            .where(where)
+            .limit(limit)
+            .offset((page - 1) * limit)
+            .orderBy(orderBy(sortBy, sortOrder)),
+          db.select({ count: count() }).from(supportTicketsTable).where(where)
+        ])
+
+        return [results, total[0]?.count || 0] as const
+      }
+    )
+  )
+
+/**
+ * The caller's own account tickets. Organization tickets are deliberately absent:
+ * they live in their organization's shared queue, so each ticket appears in
+ * exactly one list.
+ */
+export const getMyAccountSupportTicketsAction = authActionClient
+  .inputSchema(listAccountSupportTicketsSchema)
+  .action(
+    withWideEvent(
+      'getMyAccountSupportTicketsAction',
+      async ({
+        parsedInput: { page, limit, sortBy, sortOrder, search, filters },
+        ctx
+      }) => {
+        const where = and(
+          eq(supportTicketsTable.userId, ctx.user.id),
+          isNull(supportTicketsTable.organizationId),
+          search
+            ? or(
+                ilike(supportTicketsTable.ticketNumber, likeContains(search)),
+                ilike(supportTicketsTable.subject, likeContains(search))
+              )
+            : undefined,
+          filters?.status?.length
+            ? inArray(supportTicketsTable.status, filters.status)
+            : undefined,
+          filters?.priority?.length
+            ? inArray(supportTicketsTable.priority, filters.priority)
+            : undefined
+        )
+
+        const [results, total] = await Promise.all([
+          db
+            .select(ticketSelect)
+            .from(supportTicketsTable)
+            .leftJoin(usersTable, eq(supportTicketsTable.userId, usersTable.id))
+            .leftJoin(
+              organizationsTable,
+              eq(supportTicketsTable.organizationId, organizationsTable.id)
+            )
+            .where(where)
+            .limit(limit)
+            .offset((page - 1) * limit)
+            .orderBy(orderBy(sortBy, sortOrder)),
+          db.select({ count: count() }).from(supportTicketsTable).where(where)
+        ])
+
+        return [results, total[0]?.count || 0] as const
+      }
+    )
+  )
+
+export const getAdminSupportTicketsAction = adminActionClient
+  .inputSchema(listAdminSupportTicketsSchema)
+  .action(
+    withWideEvent(
+      'getAdminSupportTicketsAction',
+      async ({
+        parsedInput: { page, limit, sortBy, sortOrder, search, filters }
+      }) => {
+        const where = and(
+          search
+            ? or(
+                ilike(supportTicketsTable.ticketNumber, likeContains(search)),
+                ilike(supportTicketsTable.subject, likeContains(search)),
+                ilike(usersTable.email, likeContains(search)),
+                ilike(usersTable.name, likeContains(search)),
+                ilike(organizationsTable.name, likeContains(search))
+              )
+            : undefined,
+          filters?.status?.length
+            ? inArray(supportTicketsTable.status, filters.status)
+            : undefined,
+          filters?.priority?.length
+            ? inArray(supportTicketsTable.priority, filters.priority)
+            : undefined,
+          organizationFilter(filters?.organizationId)
+        )
+
+        const [results, total] = await Promise.all([
+          db
+            .select(ticketSelect)
+            .from(supportTicketsTable)
+            .leftJoin(usersTable, eq(supportTicketsTable.userId, usersTable.id))
+            .leftJoin(
+              organizationsTable,
+              eq(supportTicketsTable.organizationId, organizationsTable.id)
+            )
+            .where(where)
+            .limit(limit)
+            .offset((page - 1) * limit)
+            .orderBy(orderBy(sortBy, sortOrder)),
+          db
+            .select({ count: count() })
+            .from(supportTicketsTable)
+            .leftJoin(usersTable, eq(supportTicketsTable.userId, usersTable.id))
+            .leftJoin(
+              organizationsTable,
+              eq(supportTicketsTable.organizationId, organizationsTable.id)
+            )
+            .where(where)
+        ])
+
+        return [results, total[0]?.count || 0] as const
+      }
+    )
+  )
+
+/** Organizations that have at least one ticket, for the admin list filter. */
+export const getSupportTicketOrganizationsAction = adminActionClient
+  .inputSchema(
+    z.object({
+      search: optionalStringValidation,
+      ...getPaginationSchema(20)
+    })
+  )
+  .action(
+    withWideEvent(
+      'getSupportTicketOrganizationsAction',
+      async ({ parsedInput: { search, limit } }) => {
+        const rows = await db
+          .selectDistinct({
+            value: organizationsTable.id,
+            label: organizationsTable.name
+          })
+          .from(supportTicketsTable)
+          .innerJoin(
+            organizationsTable,
+            eq(supportTicketsTable.organizationId, organizationsTable.id)
+          )
+          .where(
+            search
+              ? ilike(organizationsTable.name, likeContains(search))
+              : undefined
+          )
+          .orderBy(asc(organizationsTable.name))
+          .limit(limit)
+
+        const [accountTicket] = await db
+          .select({ id: supportTicketsTable.id })
+          .from(supportTicketsTable)
+          .where(isNull(supportTicketsTable.organizationId))
+          .limit(1)
+
+        return accountTicket
+          ? [
+              {
+                value: ACCOUNT_TICKET_FILTER_VALUE,
+                label: 'Account (no organization)'
+              },
+              ...rows
+            ]
+          : rows
+      }
+    )
+  )
+
+export const getSupportTicketDetailsAction = authActionClient
+  .inputSchema(supportTicketIdSchema)
+  .action(
+    withWideEvent(
+      'getSupportTicketDetailsAction',
+      async ({ parsedInput: { ticketId }, ctx }) => {
+        await assertTicketAccess(ticketId, ctx)
+
+        const [ticket] = await db
+          .select(ticketSelect)
+          .from(supportTicketsTable)
+          .leftJoin(usersTable, eq(supportTicketsTable.userId, usersTable.id))
+          .leftJoin(
+            organizationsTable,
+            eq(supportTicketsTable.organizationId, organizationsTable.id)
+          )
+          .where(eq(supportTicketsTable.id, ticketId))
+
+        if (!ticket)
+          throw new AppError(
+            AppErrorCode.NOT_FOUND,
+            'Support ticket not found.'
+          )
+
+        const messages = await db
+          .select({
+            id: supportTicketMessagesTable.id,
+            ticketId: supportTicketMessagesTable.ticketId,
+            userId: supportTicketMessagesTable.userId,
+            message: supportTicketMessagesTable.message,
+            isAdmin: supportTicketMessagesTable.isAdmin,
+            createdAt: supportTicketMessagesTable.createdAt,
+            userName: usersTable.name,
+            userEmail: usersTable.email
+          })
+          .from(supportTicketMessagesTable)
+          .leftJoin(
+            usersTable,
+            eq(supportTicketMessagesTable.userId, usersTable.id)
+          )
+          .where(eq(supportTicketMessagesTable.ticketId, ticketId))
+          .orderBy(asc(supportTicketMessagesTable.createdAt))
+
+        return { ticket, messages }
+      }
+    )
+  )
+
+export const createSupportTicketAction = authActionClient
+  .inputSchema(createSupportTicketSchema)
+  .action(
+    withWideEvent('createSupportTicketAction', async ({ parsedInput, ctx }) => {
+      // Only an organization ticket needs a membership check. An account ticket is
+      // owned by whoever raises it, so any signed-in user may open one.
+      if (parsedInput.organizationId) {
+        await assertCanManageOrganization(
+          parsedInput.organizationId,
+          ctx.user.id
+        )
+      }
+
+      const [ticket] = await db
+        .insert(supportTicketsTable)
+        .values({
+          organizationId: parsedInput.organizationId ?? null,
+          userId: ctx.user.id,
+          subject: parsedInput.subject,
+          priority: parsedInput.priority,
+          status: 'open'
+        })
+        .returning()
+
+      if (!ticket)
+        throw new AppError(
+          AppErrorCode.INTERNAL,
+          'The support ticket was not created. Try again.'
+        )
+
+      await db.insert(supportTicketMessagesTable).values({
+        ticketId: ticket.id,
+        userId: ctx.user.id,
+        message: parsedInput.message,
+        isAdmin: false
+      })
+
+      return ticket
+    })
+  )
+
+export const addSupportTicketMessageAction = authActionClient
+  .inputSchema(addSupportTicketMessageSchema)
+  .action(
+    withWideEvent(
+      'addSupportTicketMessageAction',
+      async ({ parsedInput, ctx }) => {
+        const ticket = await assertTicketAccess(parsedInput.ticketId, ctx)
+        // A platform admin replying from the admin panel is the support team.
+        // The same person replying from their own ticket page is the customer.
+        const asSupport = Boolean(ctx.isAdmin) && parsedInput.asSupport
+
+        if (!asSupport && ['closed', 'resolved'].includes(ticket.status)) {
+          throw new AppError(
+            AppErrorCode.BAD_REQUEST,
+            'Resolved or closed support tickets cannot receive customer messages.'
+          )
+        }
+
+        const [message] = await db
+          .insert(supportTicketMessagesTable)
+          .values({
+            ticketId: ticket.id,
+            userId: ctx.user.id,
+            message: parsedInput.message,
+            isAdmin: asSupport
+          })
+          .returning()
+
+        if (asSupport) {
+          await db
+            .update(supportTicketsTable)
+            .set({
+              status: 'waiting_customer',
+              resolvedAt: null,
+              updatedAt: new Date()
+            })
+            .where(eq(supportTicketsTable.id, ticket.id))
+        } else if (ticket.status === 'waiting_customer') {
+          await db
+            .update(supportTicketsTable)
+            .set({
+              status: 'in_progress',
+              updatedAt: new Date()
+            })
+            .where(eq(supportTicketsTable.id, ticket.id))
+        }
+
+        return message
+      }
+    )
+  )
+
+export const updateSupportTicketStatusAction = adminActionClient
+  .inputSchema(updateSupportTicketStatusSchema)
+  .action(
+    withWideEvent(
+      'updateSupportTicketStatusAction',
+      async ({ parsedInput }) => {
+        const [ticket] = await db
+          .update(supportTicketsTable)
+          .set({
+            status: parsedInput.status,
+            resolvedAt: ['resolved', 'closed'].includes(parsedInput.status)
+              ? new Date()
+              : null,
+            updatedAt: new Date()
+          })
+          .where(eq(supportTicketsTable.id, parsedInput.ticketId))
+          .returning()
+
+        if (!ticket)
+          throw new AppError(
+            AppErrorCode.NOT_FOUND,
+            'Support ticket not found.'
+          )
+
+        return ticket
+      }
+    )
+  )

package/template/saas-starter/src/app/actions/support-tickets.validation.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod'
+import { getPaginationSchema, getSortSchema } from '~/lib/actions'
+import { MAX_FILTER_VALUES } from '~/lib/constants'
+import {
+  optionalStringValidation,
+  requiredMessageValidation,
+  stringValidation
+} from '~/lib/validations'
+
+export const supportTicketStatusSchema = z.enum([
+  'open',
+  'in_progress',
+  'waiting_customer',
+  'resolved',
+  'closed'
+])
+
+export const supportTicketPrioritySchema = z.enum([
+  'low',
+  'medium',
+  'high',
+  'urgent'
+])
+
+/**
+ * Omit `organizationId` to raise an account ticket, visible only to its author
+ * and platform admins. Supply it to raise an organization ticket, which every
+ * manager of that organization can read and answer. An empty string is coerced
+ * to null so a blank form field cannot masquerade as an organization id.
+ */
+export const createSupportTicketSchema = z.object({
+  organizationId: z
+    .string()
+    .trim()
+    .transform(value => value || null)
+    .nullish(),
+  subject: stringValidation,
+  priority: supportTicketPrioritySchema.default('medium'),
+  message: requiredMessageValidation
+})
+
+export const addSupportTicketMessageSchema = z.object({
+  ticketId: stringValidation,
+  message: requiredMessageValidation,
+  /** Reply as the support team. Ignored unless the caller is a platform admin. */
+  asSupport: z.boolean().default(false)
+})
+
+export const updateSupportTicketStatusSchema = z.object({
+  ticketId: stringValidation,
+  status: supportTicketStatusSchema
+})
+
+const listSortKeys = [
+  'ticketNumber',
+  'subject',
+  'status',
+  'priority',
+  'createdAt',
+  'resolvedAt'
+] as const
+
+/** Shared list shape. The admin list adds an organization filter on top. */
+const baseListSchema = {
+  ...getPaginationSchema(),
+  ...getSortSchema([...listSortKeys]),
+  search: optionalStringValidation,
+  filters: z
+    .object({
+      status: z
+        .array(supportTicketStatusSchema)
+        .max(MAX_FILTER_VALUES)
+        .optional(),
+      priority: z
+        .array(supportTicketPrioritySchema)
+        .max(MAX_FILTER_VALUES)
+        .optional()
+    })
+    .optional()
+}
+
+export const listOrganizationSupportTicketsSchema = z.object({
+  organizationId: stringValidation,
+  ...baseListSchema
+})
+
+export const listAccountSupportTicketsSchema = z.object(baseListSchema)
+
+/**
+ * Sentinel for the admin organization filter. `inArray` cannot express IS NULL,
+ * so account tickets are selected by this value instead of an organization id.
+ */
+export const ACCOUNT_TICKET_FILTER_VALUE = 'account'
+
+export const listAdminSupportTicketsSchema = z.object({
+  ...baseListSchema,
+  filters: z
+    .object({
+      status: z
+        .array(supportTicketStatusSchema)
+        .max(MAX_FILTER_VALUES)
+        .optional(),
+      priority: z
+        .array(supportTicketPrioritySchema)
+        .max(MAX_FILTER_VALUES)
+        .optional(),
+      organizationId: z.array(z.string()).max(MAX_FILTER_VALUES).optional()
+    })
+    .optional()
+})
+
+export const supportTicketIdSchema = z.object({ ticketId: stringValidation })

package/template/saas-starter/src/app/actions/uploads.ts

@@ -0,0 +1,36 @@
+'use server'
+
+import { assertCanManageOrganization } from '~/lib/organization-access'
+import { authActionClient, withWideEvent } from '~/lib/safe-action'
+import { generateUploadUrl, isR2Configured } from '~/lib/storage'
+import { generateUploadUrlSchema } from './uploads.validation'
+
+/**
+ * Starts an upload for an organization the caller manages. Without R2 the
+ * client falls back to a base64 data URL, which the saving action accepts
+ * only while R2 stays unconfigured.
+ */
+export const generateUploadUrlAction = authActionClient
+  .inputSchema(generateUploadUrlSchema)
+  .action(
+    withWideEvent(
+      'generateUploadUrlAction',
+      async ({ parsedInput, ctx: { user } }) => {
+        await assertCanManageOrganization(parsedInput.organizationId, user.id)
+
+        if (!isR2Configured()) {
+          return { mode: 'base64' as const }
+        }
+
+        const { uploadUrl, key } = await generateUploadUrl({
+          filename: parsedInput.filename,
+          mimeType: parsedInput.mimeType,
+          size: parsedInput.size,
+          uploadedBy: user.id,
+          organizationId: parsedInput.organizationId
+        })
+
+        return { mode: 'r2' as const, uploadUrl, key }
+      }
+    )
+  )

package/template/saas-starter/src/app/actions/uploads.validation.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod'
+import {
+  MAX_FILE_SIZE_BYTES,
+  MAX_FILE_SIZE_MB,
+  R2_UPLOAD_EXTENSION_BY_MIME_TYPE,
+  type R2UploadMimeType
+} from '~/lib/constants'
+import { stringValidation } from '~/lib/validations'
+
+const R2_UPLOAD_MIME_TYPES = Object.keys(R2_UPLOAD_EXTENSION_BY_MIME_TYPE) as [
+  R2UploadMimeType,
+  ...R2UploadMimeType[]
+]
+
+export const generateUploadUrlSchema = z.object({
+  filename: stringValidation,
+  mimeType: z.enum(R2_UPLOAD_MIME_TYPES),
+  size: z
+    .number()
+    .int()
+    .positive()
+    .max(MAX_FILE_SIZE_BYTES, `Choose a file under ${MAX_FILE_SIZE_MB} MB.`),
+  organizationId: stringValidation
+})