Coding Guidelines

// Good - Type imports
import type { User } from "@prisma/client";
import type { NextApiRequest, NextApiResponse } from "next";

// Bad - Regular imports for types
import { User } from "@prisma/client";

// Good - Proper typing
function processBooking(booking: Booking): BookingResponse {
  return { id: booking.id, status: booking.status };
}

// Bad - Using any
function processBooking(booking: any): any {
  return booking;
}

// Good - Early returns reduce nesting
function getBooking(id: string) {
  const booking = await prisma.booking.findUnique({ where: { id } });
  if (!booking) return null;
  
  const user = await prisma.user.findUnique({ where: { id: booking.userId } });
  if (!user) return null;
  
  return { ...booking, user };
}

// Bad - Nested conditions
function getBooking(id: string) {
  const booking = await prisma.booking.findUnique({ where: { id } });
  if (booking) {
    const user = await prisma.user.findUnique({ where: { id: booking.userId } });
    if (user) {
      return { ...booking, user };
    }
  }
  return null;
}

// Good - Explicit field selection
const booking = await prisma.booking.findFirst({
  select: {
    id: true,
    title: true,
    startTime: true,
    user: {
      select: {
        id: true,
        name: true,
        email: true,
      },
    },
  },
});

// Bad - Includes all fields (performance and security issue)
const booking = await prisma.booking.findFirst({
  include: {
    user: true,
  },
});

// Good - Exclude sensitive fields
const credentials = await prisma.credential.findMany({
  select: {
    id: true,
    type: true,
    userId: true,
    // Never select credential.key
  },
});

// Bad - Exposes sensitive data
const credentials = await prisma.credential.findMany();

// Good - Direct imports
import { Button } from "@calcom/ui/components/button";
import { Dialog } from "@calcom/ui/components/dialog";

// Bad - Barrel imports (slower, breaks tree-shaking)
import { Button, Dialog } from "@calcom/ui";

// Step 1: In packages/platform/libraries/index.ts
export { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";

// Step 2: In apps/api/v2, import from platform-libraries
import { ProfileRepository } from "@calcom/platform-libraries";

// Bad - Direct import causes module not found error
import { ProfileRepository } from "@calcom/features/profile/repositories/ProfileRepository";

// Good - TRPCError in tRPC routers
import { TRPCError } from "@trpc/server";

throw new TRPCError({
  code: "NOT_FOUND",
  message: `Booking ${bookingId} not found for user ${userId}`,
});

// Good - ErrorWithCode in services/utilities
import { ErrorWithCode } from "@calcom/lib/error";

throw new ErrorWithCode(
  `Unable to create booking: User ${userId} has no available time slots for ${date}`,
  "BOOKING_UNAVAILABLE"
);

// Bad - Generic error without context
throw new Error("Booking failed");

// Good - Context included
throw new Error(
  `Unable to send email to ${email}: SMTP connection failed with code ${errorCode}`
);

// Bad - No context
throw new Error("Email failed");

// Pattern: <Entity>Service.ts

// File: MembershipService.ts
export class MembershipService { ... }

// File: HashedLinkService.ts
export class HashedLinkService { ... }

// Pattern: Prisma<Entity>Repository.ts

// File: PrismaAppRepository.ts
export class PrismaAppRepository { ... }

// File: PrismaMembershipRepository.ts
export class PrismaMembershipRepository { ... }

// Good - Explains why
// We need to delay the webhook by 5 seconds to ensure the booking
// is fully committed before external systems receive the notification
await delay(5000);

// Bad - Restates what the code does
// Get the user
const user = await getUser();

// packages/i18n/locales/en/common.json
{
  "booking_confirmed": "Booking confirmed",
  "booking_cancelled": "Booking cancelled"
}

// Usage in components
import { useLocale } from "@calcom/lib/hooks/useLocale";

const { t } = useLocale();
return <div>{t("booking_confirmed")}</div>;

feat(bookings): add cancellation reason field
fix(calendar): resolve timezone conversion bug
refactor(auth): extract session validation logic
docs(api): update webhook documentation
test(bookings): add unit tests for reschedule flow

PR 1: Database schema changes
PR 2: Backend API endpoints
PR 3: Frontend UI components
PR 4: Integration and testing

PR 1: Add notification preferences schema
PR 2: Add notification service and API
PR 3: Add notification UI components
PR 4: Integrate notifications into booking flow

PR 1: Extract calendar logic into service
PR 2: Add new calendar provider support

# Type check
yarn type-check:ci --force

# Lint and format
yarn biome check --write .

# Run relevant tests
TZ=UTC yarn test

# Add to .gitignore
.env
.env.local
credentials.json

import { z } from "zod";

// Good - Zod validation
const createBookingSchema = z.object({
  eventTypeId: z.number(),
  startTime: z.string().datetime(),
  timeZone: z.string(),
});

const validated = createBookingSchema.parse(input);

// Good - Only return necessary fields
return {
  id: user.id,
  name: user.name,
  email: user.email,
  // Never include password, tokens, or credential keys
};