Notifications & CRM Sync Implementation Plan

apps/backend/convex/
├── schema.ts                    # MODIFY — add notificationLogs, zohoSyncLogs tables
├── functions/
│   ├── notifications.ts         # Email + WhatsApp sending via direct SDK calls (CREATE)
│   └── crm-sync.ts             # Zoho CRM + Books sync via direct API calls (CREATE)
│
apps/frontend/lib/
├── resend.ts          # Resend client config (CREATE)
├── whatsapp.ts        # WhatsApp client config (CREATE)
└── zoho.ts           # Zoho OAuth2 client (CREATE)

.env.example           # Add Zoho + Resend env vars

npm install resend

// apps/frontend/lib/resend.ts
import { Resend } from "resend";
 
export const resend = new Resend(process.env.RESEND_API_KEY);
 
export async function sendEmail({
  to,
  subject,
  html,
}: {
  to: string;
  subject: string;
  html: string;
}) {
  const result = await resend.emails.send({
    from: "House of Legends <bookings@houseoflegends.vn>",
    to,
    subject,
    html,
  });
  return result;
}

RESEND_API_KEY=re_xxxxxxxxxxxx

// apps/frontend/lib/email-templates.ts
import { getTranslations } from "next-intl/server";
 
type BookingEmailData = {
  locale: string;
  customerFirstName: string;
  showTitle: string;
  showDate: string;
  showTime: string;
  ticketType: string;
  quantity: number;
  totalAmount: number;
  qrCode?: string;
};
 
export async function buildBookingConfirmationEmail(data: BookingEmailData) {
  const t = await getTranslations({
    locale: data.locale,
    namespace: "notifications.email",
  });
 
  const ticketTypeLabel =
    data.ticketType === "DINNER_THEATRE"
      ? t("ticketType.dinnerTheatre")
      : t("ticketType.showOnly");
 
  const html = `
    <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
      <h1 style="color: #C5A059;">${t("confirmationTitle")}</h1>
      <p>${t("dearCustomer", { name: data.customerFirstName })}</p>
      <p>${t("bookingConfirmed")}</p>
      <table style="width: 100%; border-collapse: collapse;">
        <tr>
          <td style="padding: 8px; border: 1px solid #333;">${t("labelShow")}</td>
          <td style="padding: 8px; border: 1px solid #333;">${data.showTitle}</td>
        </tr>
        <tr>
          <td style="padding: 8px; border: 1px solid #333;">${t("labelDate")}</td>
          <td style="padding: 8px; border: 1px solid #333;">${data.showDate} ${t("at")} ${data.showTime}</td>
        </tr>
        <tr>
          <td style="padding: 8px; border: 1px solid #333;">${t("labelTicketType")}</td>
          <td style="padding: 8px; border: 1px solid #333;">${ticketTypeLabel}</td>
        </tr>
        <tr>
          <td style="padding: 8px; border: 1px solid #333;">${t("labelQuantity")}</td>
          <td style="padding: 8px; border: 1px solid #333;">${data.quantity}</td>
        </tr>
        <tr>
          <td style="padding: 8px; border: 1px solid #333;">${t("labelTotalPaid")}</td>
          <td style="padding: 8px; border: 1px solid #333;">${data.totalAmount.toLocaleString()} VND</td>
        </tr>
      </table>
      ${data.qrCode ? `<img src="${data.qrCode}" alt="QR Code" style="margin-top: 20px;" />` : ""}
      <p style="margin-top: 20px;">${t("seeYouAtVenue")}</p>
    </div>
  `;
 
  return {
    subject: t("confirmationSubject", { showTitle: data.showTitle }),
    html,
  };
}
 
type CancellationEmailData = {
  locale: string;
  customerFirstName: string;
  totalAmount: number;
};
 
export async function buildCancellationEmail(data: CancellationEmailData) {
  const t = await getTranslations({
    locale: data.locale,
    namespace: "notifications.email",
  });
 
  const html = `
    <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
      <h1 style="color: #C5A059;">${t("cancellationTitle")}</h1>
      <p>${t("dearCustomer", { name: data.customerFirstName })}</p>
      <p>${t("bookingCancelled")}</p>
      ${data.totalAmount > 0 ? `<p>${t("refundInfo", { amount: data.totalAmount.toLocaleString() })}</p>` : ""}
    </div>
  `;
 
  return {
    subject: t("cancellationSubject"),
    html,
  };
}
 
type AdminNewBookingEmailData = {
  locale: string;
  customerFirstName: string;
  customerLastName: string;
  customerEmail: string;
  customerPhone?: string;
  showTitle: string;
  showDate: string;
  showTime: string;
  totalAmount: number;
};
 
export async function buildAdminNewBookingEmail(
  data: AdminNewBookingEmailData,
) {
  const t = await getTranslations({
    locale: data.locale,
    namespace: "notifications.email",
  });
 
  const html = `
    <div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
      <h1 style="color: #C5A059;">${t("adminNewBookingTitle")}</h1>
      <table style="width: 100%;">
        <tr><td>${t("labelCustomer")}</td><td>${data.customerFirstName} ${data.customerLastName}</td></tr>
        <tr><td>${t("labelEmail")}</td><td>${data.customerEmail}</td></tr>
        ${data.customerPhone ? `<tr><td>${t("labelPhone")}</td><td>${data.customerPhone}</td></tr>` : ""}
        <tr><td>${t("labelShow")}</td><td>${data.showTitle}</td></tr>
        <tr><td>${t("labelDate")}</td><td>${data.showDate} ${t("at")} ${data.showTime}</td></tr>
        <tr><td>${t("labelTotal")}</td><td>${data.totalAmount.toLocaleString()} VND</td></tr>
      </table>
    </div>
  `;
 
  return {
    subject: t("adminNewBookingSubject", {
      showTitle: data.showTitle,
      showDate: data.showDate,
    }),
    html,
  };
}

// apps/backend/convex/functions/notifications.ts
import { mutation } from "convex/_generated/server";
import { v } from "convex/values";
import { consola } from "consola";
import { sendEmail } from "~/lib/resend";
 
const NOTIFICATION_ERROR_CODES = {
  RESEND_API_ERROR: "RESEND_API_ERROR",
  WHATSAPP_API_ERROR: "WHATSAPP_API_ERROR",
  WHATSAPP_NO_PHONE: "WHATSAPP_NO_PHONE",
  UNAUTHORIZED: "UNAUTHORIZED",
} as const;
 
type NotificationErrorCode = keyof typeof NOTIFICATION_ERROR_CODES;
 
/**
 * Helper: inline role check using ctx.auth.getUserIdentity()
 * Do NOT import and call getCurrentUser (it is a QUERY, not a utility function)
 */
async function requireStaffOrAdmin(
  ctx: HandlerContext,
): Promise<{ role: string }> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error(NOTIFICATION_ERROR_CODES.UNAUTHORIZED);
  const user = await ctx.db
    .query("users")
    .withIndex("by_email", (q) => q.eq("email", identity.email!))
    .first();
  if (!user || (user.role !== "ADMIN" && user.role !== "STAFF")) {
    throw new Error(NOTIFICATION_ERROR_CODES.UNAUTHORIZED);
  }
  return user as { role: string };
}
 
type HandlerContext = {
  auth: { getUserIdentity: () => Promise<{ email?: string } | null> };
  db: {
    query: (table: string) => {
      withIndex: (
        name: string,
        fn: (q: QueryBuilder) => QueryBuilder,
      ) => { first: () => Promise<unknown> };
    };
  };
};
 
type QueryBuilder = {
  eq: (field: string, value: string) => { first: () => Promise<unknown> };
};
 
/**
 * Send a pre-rendered email (HTML and subject pre-built by caller).
 * Direct Resend SDK call — no HTTP fetch needed.
 */
export const sendEmailNotification = mutation({
  args: {
    to: v.string(),
    subject: v.string(),
    html: v.string(),
    type: v.union(
      v.literal("EMAIL_CONFIRMATION"),
      v.literal("EMAIL_CANCELLATION"),
      v.literal("EMAIL_ADMIN_NEW_BOOKING"),
    ),
    reservationId: v.optional(v.id("reservations")),
  },
  handler: async (ctx, args) => {
    // CORRECT: Use inline role check via ctx.auth.getUserIdentity()
    await requireStaffOrAdmin(ctx);
 
    try {
      // Direct Resend SDK call — no HTTP fetch
      const result = await sendEmail({
        to: args.to,
        subject: args.subject,
        html: args.html,
      });
 
      if (result.error) {
        throw new Error(NOTIFICATION_ERROR_CODES.RESEND_API_ERROR);
      }
 
      consola.success("Email sent", { to: args.to, type: args.type });
      return { success: true };
    } catch (err) {
      consola.error("Email send failed", {
        to: args.to,
        type: args.type,
        error: err,
      });
      throw new Error(NOTIFICATION_ERROR_CODES.RESEND_API_ERROR);
    }
  },
});
 
type BookingWhatsAppParams = {
  customerPhone: string;
  customerFirstName: string;
  customerLastName: string;
  showTitle: string;
  showDateTime: string;
  totalAmount: number;
};
 
/**
 * Send WhatsApp booking confirmation.
 * Template content is pre-approved in WhatsApp Business Manager.
 * Direct WhatsApp API call — no HTTP fetch needed.
 */
export const sendBookingConfirmationWhatsApp = mutation({
  args: {
    customerPhone: v.string(),
    customerFirstName: v.string(),
    customerLastName: v.string(),
    showTitle: v.string(),
    showDateTime: v.string(),
    totalAmount: v.number(),
    reservationId: v.optional(v.id("reservations")),
  },
  handler: async (ctx, args) => {
    // CORRECT: Inline role check via ctx.auth.getUserIdentity()
    await requireStaffOrAdmin(ctx);
 
    if (!args.customerPhone) {
      consola.info("WhatsApp skipped: no phone number");
      return { success: true, skipped: true };
    }
 
    try {
      // Direct WhatsApp API call — no HTTP fetch
      const { sendWhatsAppTemplate } = await import("~/lib/whatsapp");
      await sendWhatsAppTemplate({
        to: args.customerPhone,
        templateName: "booking_confirmation",
        components: [
          {
            type: "body",
            parameters: [
              {
                type: "text",
                text: `${args.customerFirstName} ${args.customerLastName}`,
              },
              { type: "text", text: args.showTitle },
              { type: "text", text: args.showDateTime },
              { type: "text", text: args.totalAmount.toLocaleString() },
            ],
          },
        ],
      });
 
      consola.success("WhatsApp sent", { to: args.customerPhone });
      return { success: true };
    } catch (err) {
      consola.error("WhatsApp send failed", {
        to: args.customerPhone,
        error: err,
      });
      throw new Error(NOTIFICATION_ERROR_CODES.WHATSAPP_API_ERROR);
    }
  },
});

// apps/frontend/lib/whatsapp.ts
const WHATSAPP_API_URL = `https://graph.facebook.com/v18.0/${process.env.WHATSAPP_PHONE_NUMBER_ID}/messages`;
 
export async function sendWhatsAppTemplate({
  to,
  templateName,
  components,
}: {
  to: string;
  templateName: string;
  components: Array<{
    type: "body";
    parameters: Array<{ type: "text"; text: string }>;
  }>;
}) {
  const response = await fetch(WHATSAPP_API_URL, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.WHATSAPP_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messaging_product: "whatsapp",
      to,
      type: "template",
      template: {
        name: templateName,
        language: { code: "en" },
        components,
      },
    }),
  });
 
  if (!response.ok) {
    throw new Error(`WHATSAPP_API_ERROR: ${response.status}`);
  }
 
  return response.json();
}

WHATSAPP_PHONE_NUMBER_ID=xxxxxxxxxxxx
WHATSAPP_ACCESS_TOKEN=xxxxxxxxxxxx

// apps/frontend/lib/zoho.ts
let accessToken: string | null = null;
let tokenExpiry: number = 0;
 
export async function getZohoAccessToken(): Promise<string> {
  if (accessToken && Date.now() < tokenExpiry) {
    return accessToken;
  }
 
  const response = await fetch("https://accounts.zoho.com/oauth/v2/token", {
    method: "POST",
    body: new URLSearchParams({
      grant_type: "refresh_token",
      client_id: process.env.ZOHO_CLIENT_ID!,
      client_secret: process.env.ZOHO_CLIENT_SECRET!,
      refresh_token: process.env.ZOHO_REFRESH_TOKEN!,
    }),
  });
 
  const data = await response.json();
  accessToken = data.access_token;
  tokenExpiry = Date.now() + (data.expires_in - 60) * 1000;
 
  return accessToken!;
}
 
export async function zohoApiCall(endpoint: string, options: RequestInit = {}) {
  const token = await getZohoAccessToken();
  return fetch(`https://www.zohoapis.com${endpoint}`, {
    ...options,
    headers: {
      Authorization: `Zoho-oauthtoken ${token}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });
}

# Zoho OAuth
ZOHO_CLIENT_ID=xxxxxxxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxxxxxxx
ZOHO_REFRESH_TOKEN=1000.xxxxxx.xxxxxx
 
# Zoho Books
ZOHO_BOOKS_ORGANIZATION_ID=xxxxxxxxxxxx

// apps/backend/convex/functions/crm-sync.ts
import { mutation } from "convex/_generated/server";
import { v } from "convex/values";
import { consola } from "consola";
import { zohoApiCall } from "~/lib/zoho";
 
const CRM_ERROR_CODES = {
  ZOHO_AUTH_ERROR: "ZOHO_AUTH_ERROR",
  ZOHO_API_ERROR: "ZOHO_API_ERROR",
  ZOHO_CONTACT_ERROR: "ZOHO_CONTACT_ERROR",
  ZOHO_DEAL_ERROR: "ZOHO_DEAL_ERROR",
  ZOHO_INVOICE_ERROR: "ZOHO_INVOICE_ERROR",
  UNAUTHORIZED: "UNAUTHORIZED",
} as const;
 
type CrmErrorCode = keyof typeof CRM_ERROR_CODES;
 
type ContactParams = {
  customerFirstName: string;
  customerLastName: string;
  customerEmail: string;
  customerPhone?: string;
};
 
/**
 * Helper: inline role check using ctx.auth.getUserIdentity()
 */
async function requireStaffOrAdmin(
  ctx: CrmHandlerContext,
): Promise<{ role: string }> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) throw new Error(CRM_ERROR_CODES.UNAUTHORIZED);
  const user = await ctx.db
    .query("users")
    .withIndex("by_email", (q) => q.eq("email", identity.email!))
    .first();
  if (!user || (user.role !== "ADMIN" && user.role !== "STAFF")) {
    throw new Error(CRM_ERROR_CODES.UNAUTHORIZED);
  }
  return user as { role: string };
}
 
type CrmHandlerContext = {
  auth: { getUserIdentity: () => Promise<{ email?: string } | null> };
  db: {
    query: (table: string) => {
      withIndex: (
        name: string,
        fn: (q: QueryBuilder) => QueryBuilder,
      ) => { first: () => Promise<unknown> };
    };
  };
};
 
type QueryBuilder = {
  eq: (field: string, value: string) => { first: () => Promise<unknown> };
};
 
export const upsertZohoContact = mutation({
  args: {
    customerFirstName: v.string(),
    customerLastName: v.string(),
    customerEmail: v.string(),
    customerPhone: v.optional(v.string()),
  },
  handler: async (ctx, args) => {
    await requireStaffOrAdmin(ctx);
 
    const {
      customerFirstName,
      customerLastName,
      customerEmail,
      customerPhone,
    } = args;
 
    const data = {
      First_Name: customerFirstName,
      Last_Name: customerLastName,
      Email: customerEmail,
      Phone: customerPhone ?? undefined,
      Lead_Source: "Website Booking",
    };
 
    try {
      // Check if contact exists by email — direct Zoho API call
      const searchResponse = await zohoApiCall(
        "/crm/v3/contacts/search?email=" + encodeURIComponent(customerEmail),
        { method: "GET" },
      );
      const searchData = await searchResponse.json();
 
      if (searchData.data && searchData.data.length > 0) {
        // Update existing contact
        const contactId = searchData.data[0].id;
        await zohoApiCall(`/crm/v3/contacts/${contactId}`, {
          method: "PUT",
          body: JSON.stringify({ data }),
        });
        consola.success("Zoho contact updated", {
          contactId,
          email: customerEmail,
        });
        return { success: true, action: "updated", contactId };
      } else {
        // Create new contact
        const createResponse = await zohoApiCall("/crm/v3/contacts", {
          method: "POST",
          body: JSON.stringify({ data }),
        });
        const createData = await createResponse.json();
        consola.success("Zoho contact created", {
          email: customerEmail,
          id: createData.data?.[0]?.details?.id,
        });
        return {
          success: true,
          action: "created",
          contactId: createData.data?.[0]?.details?.id,
        };
      }
    } catch (err) {
      consola.error("Zoho contact upsert failed", {
        email: customerEmail,
        error: err,
      });
      throw new Error(CRM_ERROR_CODES.ZOHO_CONTACT_ERROR);
    }
  },
});

export const createZohoDeal = mutation({
  args: {
    customerFirstName: v.string(),
    customerLastName: v.string(),
    showTitle: v.string(),
    showDate: v.string(),
    ticketType: v.union(v.literal("DINNER_THEATRE"), v.literal("SHOW_ONLY")),
    quantity: v.number(),
    totalAmount: v.number(),
  },
  handler: async (ctx, args) => {
    await requireStaffOrAdmin(ctx);
 
    const {
      customerFirstName,
      customerLastName,
      showTitle,
      showDate,
      ticketType,
      quantity,
      totalAmount,
    } = args;
 
    const dealData = {
      Deal_Name: `HOL - ${showTitle} - ${customerLastName}`,
      Amount: totalAmount,
      Closing_Date: showDate,
      Stage: "Closed Won",
      Lead_Source: "Website Booking",
      Description: `Ticket: ${ticketType} x ${quantity}`,
      Contact_Name: `${customerFirstName} ${customerLastName}`,
    };
 
    try {
      // Direct Zoho API call
      const response = await zohoApiCall("/crm/v3/deals", {
        method: "POST",
        body: JSON.stringify({ data: [dealData] }),
      });
      const responseData = await response.json();
      consola.success("Zoho deal created", {
        dealName: dealData.Deal_Name,
        id: responseData.data?.[0]?.details?.id,
      });
      return { success: true, dealId: responseData.data?.[0]?.details?.id };
    } catch (err) {
      consola.error("Zoho deal creation failed", {
        dealName: dealData.Deal_Name,
        error: err,
      });
      throw new Error(CRM_ERROR_CODES.ZOHO_DEAL_ERROR);
    }
  },
});

export const createZohoInvoice = mutation({
  args: {
    customerEmail: v.string(),
    showTitle: v.string(),
    ticketType: v.union(v.literal("DINNER_THEATRE"), v.literal("SHOW_ONLY")),
    quantity: v.number(),
    subtotal: v.number(),
    totalAmount: v.number(),
    vnpayTransactionId: v.optional(v.string()),
    addOns: v.optional(
      v.array(
        v.object({
          name: v.string(),
          quantity: v.number(),
          price: v.number(),
        }),
      ),
    ),
  },
  handler: async (ctx, args) => {
    await requireStaffOrAdmin(ctx);
 
    const {
      customerEmail,
      showTitle,
      ticketType,
      quantity,
      subtotal,
      totalAmount,
      vnpayTransactionId,
      addOns = [],
    } = args;
 
    const lineItems = [
      {
        item_id: "ticket_product_id", // Pre-configured in Zoho Books
        name: `${showTitle} - ${ticketType}`,
        quantity,
        rate: subtotal / quantity,
      },
    ];
 
    // Add add-ons as separate line items
    for (const addon of addOns) {
      lineItems.push({
        name: addon.name,
        quantity: addon.quantity,
        rate: addon.price,
      });
    }
 
    const invoiceData = {
      customer_email: customerEmail,
      line_items: lineItems,
      date: new Date().toISOString().split("T")[0],
      payment_terms: "Due on Receipt",
    };
 
    try {
      // Direct Zoho Books API call
      const response = await zohoApiCall("/books/v3/invoices", {
        method: "POST",
        body: JSON.stringify({ data: [invoiceData] }),
      });
      const responseData = await response.json();
 
      // Mark invoice as paid (since it's a confirmed booking)
      if (responseData.invoice?.id) {
        await zohoApiCall(
          `/books/v3/invoices/${responseData.invoice.id}/markaspaid`,
          {
            method: "POST",
            body: JSON.stringify({
              amount: totalAmount,
              payment_mode: "VNPay",
              reference_number: vnpayTransactionId ?? undefined,
            }),
          },
        );
        consola.success("Zoho invoice created and marked paid", {
          invoiceId: responseData.invoice.id,
        });
      }
      return { success: true, invoiceId: responseData.invoice?.id };
    } catch (err) {
      consola.error("Zoho invoice creation failed", {
        customerEmail,
        error: err,
      });
      throw new Error(CRM_ERROR_CODES.ZOHO_INVOICE_ERROR);
    }
  },
});

// In the VNPay IPN handler, after successful payment update to PAID:
// Direct Convex mutation calls — no HTTP fetch needed
await ctx.runMutation(internal.crm_sync.upsertZohoContact, {
  customerFirstName: reservation.customerFirstName,
  customerLastName: reservation.customerLastName,
  customerEmail: reservation.customerEmail,
  customerPhone: reservation.customerPhone ?? undefined,
});
 
await ctx.runMutation(internal.crm_sync.createZohoDeal, {
  customerFirstName: reservation.customerFirstName,
  customerLastName: reservation.customerLastName,
  showTitle: template?.title ?? "House of Legends",
  showDate: occurrence?.date ?? new Date().toISOString().split("T")[0],
  ticketType: reservation.ticketType,
  quantity: reservation.quantity,
  totalAmount: reservation.totalAmount,
});
 
await ctx.runMutation(internal.crm_sync.createZohoInvoice, {
  customerEmail: reservation.customerEmail,
  showTitle: template?.title ?? "House of Legends",
  ticketType: reservation.ticketType,
  quantity: reservation.quantity,
  subtotal: reservation.subtotal,
  totalAmount: reservation.totalAmount,
  vnpayTransactionId: reservation.vnpayTransactionId ?? undefined,
  addOns: reservation.addOns ?? [],
});
 
// Email and WhatsApp notifications (pre-rendered content passed directly)
await ctx.runMutation(internal.notifications.sendEmailNotification, {
  to: reservation.customerEmail,
  subject: emailSubject,
  html: emailHtml,
  type: "EMAIL_CONFIRMATION",
  reservationId: reservation._id,
});
 
if (reservation.customerPhone) {
  await ctx.runMutation(
    internal.notifications.sendBookingConfirmationWhatsApp,
    {
      customerPhone: reservation.customerPhone,
      customerFirstName: reservation.customerFirstName,
      customerLastName: reservation.customerLastName,
      showTitle: template?.title ?? "House of Legends",
      showDateTime: `${occurrence?.date ?? ""} at ${occurrence?.time ?? ""}`,
      totalAmount: reservation.totalAmount,
      reservationId: reservation._id,
    },
  );
}

// In the cancelReservation mutation:
await ctx.runMutation(internal.notifications.sendEmailNotification, {
  to: reservation.customerEmail,
  subject: cancellationSubject,
  html: cancellationHtml,
  type: "EMAIL_CANCELLATION",
  reservationId: reservation._id,
});

notificationLogs: defineTable({
  reservationId: v.optional(v.id("reservations")),
  type: v.union(
    v.literal("EMAIL_CONFIRMATION"),
    v.literal("EMAIL_CANCELLATION"),
    v.literal("EMAIL_REFUND"),
    v.literal("EMAIL_ADMIN_NEW_BOOKING"),
    v.literal("WHATSAPP_CONFIRMATION"),
    v.literal("WHATSAPP_REMINDER")
  ),
  channel: v.union(v.literal("EMAIL"), v.literal("WHATSAPP")),
  recipient: v.string(),
  status: v.union(
    v.literal("PENDING"),
    v.literal("SENT"),
    v.literal("FAILED")
  ),
  externalId: v.optional(v.string()),
  errorMessage: v.optional(v.string()),
  createdAt: v.number(),
  sentAt: v.optional(v.number()),
})
  .index("by_reservation", ["reservationId"])
  .index("by_status", ["status"]),

zohoSyncLogs: defineTable({
  reservationId: v.id("reservations"),
  action: v.union(
    v.literal("CONTACT_UPSERT"),
    v.literal("DEAL_CREATE"),
    v.literal("INVOICE_CREATE"),
    v.literal("INVOICE_PAYMENT")
  ),
  zohoRecordId: v.optional(v.string()),
  status: v.union(
    v.literal("PENDING"),
    v.literal("SUCCESS"),
    v.literal("FAILED")
  ),
  errorMessage: v.optional(v.string()),
  retryCount: v.number(),
  createdAt: v.number(),
  syncedAt: v.optional(v.number()),
})
  .index("by_reservation", ["reservationId"])
  .index("by_status", ["status"]),

// apps/backend/convex/functions/notifications.ts
import { z } from "zod";
 
export const SendEmailNotificationSchema = z.object({
  to: z.string().email("Invalid email address"),
  subject: z.string().min(1, "Subject is required"),
  html: z.string().min(1, "HTML content is required"),
  type: z.enum([
    "EMAIL_CONFIRMATION",
    "EMAIL_CANCELLATION",
    "EMAIL_ADMIN_NEW_BOOKING",
  ]),
  reservationId: z.string().optional(),
});
 
export const SendWhatsAppNotificationSchema = z.object({
  customerPhone: z.string().min(1, "Phone number is required"),
  customerFirstName: z.string().min(1, "First name is required"),
  customerLastName: z.string().min(1, "Last name is required"),
  showTitle: z.string().min(1, "Show title is required"),
  showDateTime: z.string().min(1, "Show date/time is required"),
  totalAmount: z.number().nonnegative(),
  reservationId: z.string().optional(),
});
 
// apps/backend/convex/functions/crm-sync.ts
export const UpsertZohoContactSchema = z.object({
  customerFirstName: z.string().min(1, "First name is required"),
  customerLastName: z.string().min(1, "Last name is required"),
  customerEmail: z.string().email("Invalid email address"),
  customerPhone: z.string().optional(),
});
 
export const CreateZohoDealSchema = z.object({
  customerFirstName: z.string().min(1, "First name is required"),
  customerLastName: z.string().min(1, "Last name is required"),
  showTitle: z.string().min(1, "Show title is required"),
  showDate: z
    .string()
    .regex(/^\d{4}-\d{2}-\d{2}$/, "Date must be YYYY-MM-DD format"),
  ticketType: z.enum(["DINNER_THEATRE", "SHOW_ONLY"]),
  quantity: z.number().int().positive("Quantity must be positive"),
  totalAmount: z.number().nonnegative(),
});
 
export const CreateZohoInvoiceSchema = z.object({
  customerEmail: z.string().email("Invalid email address"),
  showTitle: z.string().min(1, "Show title is required"),
  ticketType: z.enum(["DINNER_THEATRE", "SHOW_ONLY"]),
  quantity: z.number().int().positive("Quantity must be positive"),
  subtotal: z.number().nonnegative(),
  totalAmount: z.number().nonnegative(),
  vnpayTransactionId: z.string().optional(),
  addOns: z
    .array(
      z.object({
        name: z.string(),
        quantity: z.number().int().positive(),
        price: z.number().nonnegative(),
      }),
    )
    .optional(),
});

export const NOTIFICATION_ERROR_CODES = {
  RESEND_API_ERROR: "RESEND_API_ERROR",
  WHATSAPP_API_ERROR: "WHATSAPP_API_ERROR",
  WHATSAPP_NO_PHONE: "WHATSAPP_NO_PHONE",
  UNAUTHORIZED: "UNAUTHORIZED",
} as const;
 
export const CRM_ERROR_CODES = {
  ZOHO_AUTH_ERROR: "ZOHO_AUTH_ERROR",
  ZOHO_API_ERROR: "ZOHO_API_ERROR",
  ZOHO_CONTACT_ERROR: "ZOHO_CONTACT_ERROR",
  ZOHO_DEAL_ERROR: "ZOHO_DEAL_ERROR",
  ZOHO_INVOICE_ERROR: "ZOHO_INVOICE_ERROR",
  UNAUTHORIZED: "UNAUTHORIZED",
} as const;

// Admin dashboard — recent notifications
const recentNotifications = useQuery(api.notifications.listRecent, {
  limit: 50,
});
 
// Admin dashboard — sync status
const syncStatus = useQuery(api.crmSync.getByReservation, { reservationId });

{
  "notifications": {
    "email": {
      "confirmationTitle": "Booking Confirmed",
      "cancellationTitle": "Booking Cancelled",
      "dearCustomer": "Dear {name}",
      "bookingConfirmed": "Your booking has been confirmed.",
      "bookingCancelled": "Your booking has been cancelled.",
      "refundInfo": "A refund of {amount} VND will be processed.",
      "seeYouAtVenue": "We look forward to seeing you at House of Legends!",
      "adminNewBookingTitle": "New Booking Received",
      "ticketType": {
        "dinnerTheatre": "Dinner Theatre",
        "showOnly": "Show Only"
      },
      "labelShow": "Show",
      "labelDate": "Date",
      "labelTicketType": "Ticket Type",
      "labelQuantity": "Quantity",
      "labelTotalPaid": "Total Paid",
      "labelCustomer": "Customer",
      "labelEmail": "Email",
      "labelPhone": "Phone",
      "labelTotal": "Total",
      "at": "at"
    },
    "whatsapp": {
      "confirmationBody": [
        "Dear {name}",
        "Your booking for {showTitle} on {dateTime} is confirmed. Total: {amount} VND."
      ]
    }
  },
  "errors": {
    "notifications": {
      "resendFailed": "Failed to send email. Please try again.",
      "whatsappFailed": "Failed to send WhatsApp message.",
      "noPhone": "No phone number provided.",
      "zohoAuthFailed": "CRM authentication failed.",
      "zohoApiFailed": "CRM API error.",
      "zohoContactFailed": "Failed to sync customer to CRM.",
      "zohoDealFailed": "Failed to create deal in CRM.",
      "zohoInvoiceFailed": "Failed to create invoice in CRM."
    },
    "auth": {
      "unauthorized": "You must be signed in as staff or admin"
    }
  }
}

// In Next.js server action — Good (has access to getTranslations via next-intl/server)
const { subject, html } = await buildBookingConfirmationEmail(data);
 
// Convex receives pre-built strings — Good
await sendEmail({ to, subject, html });

// Good — env var with fallback
adminEmail: process.env.ADMIN_EMAIL ?? "admin@houseoflegends.vn";

# Server-only (never exposed to client):
CLERK_SECRET_KEY=           # Clerk secret key
RESEND_API_KEY=re_xxxxxxxxxxxx
WHATSAPP_ACCESS_TOKEN=xxxxxxxxxxxx
ZOHO_CLIENT_ID=xxxxxxxxxxxx
ZOHO_CLIENT_SECRET=xxxxxxxxxxxx
ZOHO_REFRESH_TOKEN=1000.xxxxxx.xxxxxx
ZOHO_BOOKS_ORGANIZATION_ID=xxxxxxxxxxxx
 
# Client-safe (NEXT_PUBLIC_ prefix):
NEXT_PUBLIC_CONVEX_URL=    # Convex deployment URL
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=  # Clerk publishable key
NEXT_PUBLIC_APP_URL=        # Frontend URL (still needed for redirects, not for internal calls)
 
# Admin configuration:
ADMIN_EMAIL=admin@houseoflegends.vn
GOOGLE_REVIEW_URL=https://g.page/r/.../review

// e2e/notifications.spec.ts
 
test("NOT-E2E-1.1: Customer receives confirmation email after payment", async ({
  page,
}) => {
  // Given: VNPay payment confirmed for booking "BOOK-123"
  // When: Payment webhook is received with code "00"
  // Then: Customer receives email with show title, date, time, ticket type, quantity, total, QR code
  // (This is tested via mock - actual email delivery verified in staging)
});
 
test("NOT-E2E-1.2: Customer receives WhatsApp if phone provided", async ({
  page,
}) => {
  // Given: Booking confirmed with customerPhone "+84912345678"
  // When: Payment confirmed
  // Then: WhatsApp template message sent to +84912345678
});
 
test("NOT-E2E-1.3: WhatsApp skipped when no phone", async ({ page }) => {
  // Given: Booking confirmed without customerPhone
  // When: Payment confirmed
  // Then: No WhatsApp message attempted
});
 
test("NOT-E2E-1.4: Admin receives new booking email", async ({ page }) => {
  // Given: New booking confirmed
  // When: Payment confirmed
  // Then: Admin email receives new booking notification with customer details
});

// __tests__/components/email-templates.test.tsx
 
it("NOT-CT-1.1: Booking confirmation email renders with all fields", async () => {
  // Given: Booking data with all fields populated
  const data = {
    locale: "en",
    customerFirstName: "John",
    showTitle: "Legendary Show",
    showDate: "May 15, 2026",
    showTime: "7:30 PM",
    ticketType: "DINNER_THEATRE",
    quantity: 2,
    totalAmount: 2300000,
    qrCode: "https://example.com/qr.png",
  };
  // When: buildBookingConfirmationEmail is called
  const { subject, html } = await buildBookingConfirmationEmail(data);
  // Then: Subject contains show title, HTML contains all data fields
  expect(subject).toContain("Legendary Show");
  expect(html).toContain("John");
  expect(html).toContain("Legendary Show");
  expect(html).toContain("May 15, 2026");
  expect(html).toContain("7:30 PM");
  expect(html).toContain("Dinner Theatre");
  expect(html).toContain("2");
  expect(html).toContain("2,300,000");
});
 
it("NOT-CT-1.2: Cancellation email shows refund info when amount > 0", async () => {
  // Given: Cancellation with totalAmount 2,300,000 VND
  const data = {
    locale: "en",
    customerFirstName: "John",
    totalAmount: 2300000,
  };
  // When: buildCancellationEmail is called
  const { html } = await buildCancellationEmail(data);
  // Then: HTML contains refund info
  expect(html).toContain("2,300,000");
});
 
it("NOT-CT-1.3: Cancellation email shows no refund info when amount is 0", async () => {
  // Given: Cancellation with totalAmount 0
  const data = { locale: "en", customerFirstName: "John", totalAmount: 0 };
  // When: buildCancellationEmail is called
  const { html } = await buildCancellationEmail(data);
  // Then: HTML does not contain refund info
  expect(html).not.toContain("refundInfo");
});

// __tests__/convex/notifications.test.ts
 
it("NOT-BE-1.1: sendEmailNotification throws UNAUTHORIZED when not staff/admin", async () => {
  // Given: Mock context with unauthenticated identity
  const ctx = createMockContext({ identity: null });
  // When: Calling sendEmailNotification
  // Then: Throws UNAUTHORIZED
  await expect(
    ctx.runMutation(api.notifications.sendEmailNotification, {
      to: "john@example.com",
      subject: "Test",
      html: "<p>Test</p>",
      type: "EMAIL_CONFIRMATION",
    }),
  ).rejects.toThrow("UNAUTHORIZED");
});
 
it("NOT-BE-1.2: sendEmailNotification throws UNAUTHORIZED for GUEST role", async () => {
  // Given: Mock context with GUEST role
  const ctx = createMockContext({
    identity: { email: "guest@example.com" },
    userRole: "GUEST",
  });
  // When: Calling sendEmailNotification
  // Then: Throws UNAUTHORIZED
  await expect(
    ctx.runMutation(api.notifications.sendEmailNotification, {
      to: "john@example.com",
      subject: "Test",
      html: "<p>Test</p>",
      type: "EMAIL_CONFIRMATION",
    }),
  ).rejects.toThrow("UNAUTHORIZED");
});
 
it("NOT-BE-1.3: sendEmailNotification succeeds for ADMIN role", async () => {
  // Given: Mock context with ADMIN role
  const ctx = createMockContext({
    identity: { email: "admin@example.com" },
    userRole: "ADMIN",
  });
  // Mock the Resend SDK call
  const mockSendEmail = vi.fn().mockResolvedValue({ data: { id: "test-id" } });
  vi.mock("~/lib/resend", () => ({
    sendEmail: mockSendEmail,
  }));
  // When: Calling sendEmailNotification
  // Then: Succeeds and calls Resend directly
  await ctx.runMutation(api.notifications.sendEmailNotification, {
    to: "john@example.com",
    subject: "Booking Confirmed",
    html: "<h1>Confirmed</h1>",
    type: "EMAIL_CONFIRMATION",
  });
  expect(mockSendEmail).toHaveBeenCalledWith({
    to: "john@example.com",
    subject: "Booking Confirmed",
    html: "<h1>Confirmed</h1>",
  });
});
 
it("NOT-BE-1.4: sendBookingConfirmationWhatsApp skips when phone empty", async () => {
  // Given: Mock context with ADMIN role
  const ctx = createMockContext({
    identity: { email: "admin@example.com" },
    userRole: "ADMIN",
  });
  // When: Calling with empty customerPhone
  // Then: Returns { success: true, skipped: true }
  const result = await ctx.runMutation(
    api.notifications.sendBookingConfirmationWhatsApp,
    {
      customerPhone: "",
      customerFirstName: "John",
      customerLastName: "Doe",
      showTitle: "Legendary Show",
      showDateTime: "2026-05-15 at 19:30",
      totalAmount: 1800000,
    },
  );
  expect(result).toEqual({ success: true, skipped: true });
});
 
it("NOT-BE-1.5: upsertZohoContact throws UNAUTHORIZED when not staff/admin", async () => {
  // Given: Mock context with GUEST role
  const ctx = createMockContext({
    identity: { email: "guest@example.com" },
    userRole: "GUEST",
  });
  // When: Calling upsertZohoContact
  // Then: Throws UNAUTHORIZED
  await expect(
    ctx.runMutation(api.crmSync.upsertZohoContact, {
      customerFirstName: "John",
      customerLastName: "Doe",
      customerEmail: "john@example.com",
    }),
  ).rejects.toThrow("UNAUTHORIZED");
});
 
it("NOT-BE-1.6: createZohoDeal succeeds for ADMIN role", async () => {
  // Given: Mock context with ADMIN role
  const ctx = createMockContext({
    identity: { email: "admin@example.com" },
    userRole: "ADMIN",
  });
  // Mock the Zoho API call
  const mockZohoApiCall = vi.fn().mockResolvedValue({
    json: () => Promise.resolve({ data: [{ details: { id: "deal123" } }] }),
  });
  vi.mock("~/lib/zoho", () => ({
    zohoApiCall: mockZohoApiCall,
  }));
  // When: Calling createZohoDeal
  // Then: Succeeds
  const result = await ctx.runMutation(api.crmSync.createZohoDeal, {
    customerFirstName: "John",
    customerLastName: "Doe",
    showTitle: "Legendary Show",
    showDate: "2026-05-15",
    ticketType: "DINNER_THEATRE",
    quantity: 2,
    totalAmount: 2300000,
  });
  expect(result.success).toBe(true);
});