@thebookingkit/server 0.1.2 → 0.1.3

package/src/notification-jobs.ts

@@ -1,428 +0,0 @@
-/**
- * Notification job payload types and helper functions for E-06.
- *
- * These types are used by background job functions (Inngest, Trigger.dev, BullMQ, etc.)
- * when sending booking notification emails and syncing calendar events.
- *
- * The actual job implementation lives in the consumer app (or a provided Inngest
- * functions file), but the payload shapes and builder functions are framework-agnostic.
- */
-
-import type { EmailAdapter, CalendarAdapter, JobAdapter } from "./adapters/index.js";
-import { generateICSAttachment } from "./adapters/index.js";
-import {
-  interpolateTemplate,
-  CONFIRMATION_EMAIL_HTML,
-  CONFIRMATION_EMAIL_TEXT,
-  REMINDER_EMAIL_HTML,
-  CANCELLATION_EMAIL_HTML,
-  RESCHEDULE_EMAIL_HTML,
-  type EmailTemplateVars,
-} from "./email-templates.js";
-import { JOB_NAMES } from "./adapters/job-adapter.js";
-
-// ---------------------------------------------------------------------------
-// Payload types for each notification job
-// ---------------------------------------------------------------------------
-
-/** Common booking data included in every notification payload */
-export interface NotificationBookingData {
-  bookingId: string;
-  eventTitle: string;
-  providerName: string;
-  providerEmail: string;
-  customerName: string;
-  customerEmail: string;
-  /** ISO datetime strings */
-  startsAt: string;
-  endsAt: string;
-  timezone: string;
-  location?: string;
-  /** Signed management URL for the customer */
-  managementUrl?: string;
-  /** Unsubscribe URL */
-  unsubscribeUrl?: string;
-}
-
-/** Payload for SEND_CONFIRMATION_EMAIL job */
-export interface ConfirmationEmailPayload extends NotificationBookingData {
-  /** Whether to also send a notification to the provider */
-  notifyProvider?: boolean;
-}
-
-/** Payload for SEND_REMINDER_EMAIL job */
-export interface ReminderEmailPayload extends NotificationBookingData {
-  /** How many hours before the appointment this reminder is for (e.g., 24 or 1) */
-  reminderHours: number;
-}
-
-/** Payload for SEND_CANCELLATION_EMAIL job */
-export interface CancellationEmailPayload extends NotificationBookingData {
-  /** Who initiated the cancellation */
-  cancelledBy: "customer" | "provider" | "system";
-  /** Optional reason for cancellation */
-  reason?: string;
-}
-
-/** Payload for SEND_RESCHEDULE_EMAIL job */
-export interface RescheduleEmailPayload extends NotificationBookingData {
-  /** Original booking datetime strings */
-  oldStartsAt: string;
-  oldEndsAt: string;
-}
-
-/** Payload for SYNC_CALENDAR_EVENT job */
-export interface CalendarSyncPayload {
-  bookingId: string;
-  providerId: string;
-  /** External calendar event ID (for updates/deletes) */
-  externalEventId?: string;
-  eventTitle: string;
-  customerName: string;
-  customerEmail: string;
-  startsAt: string;
-  endsAt: string;
-  timezone: string;
-  location?: string;
-  description?: string;
-}
-
-/** Payload for DELETE_CALENDAR_EVENT job */
-export interface CalendarDeletePayload {
-  bookingId: string;
-  providerId: string;
-  externalEventId: string;
-}
-
-/** Payload for AUTO_REJECT_PENDING job */
-export interface AutoRejectPendingPayload {
-  bookingId: string;
-  /** Actor to record in the booking_event */
-  actor?: string;
-}
-
-// ---------------------------------------------------------------------------
-// Helper functions for building notification payloads
-// ---------------------------------------------------------------------------
-
-/**
- * Format a UTC datetime string in a given timezone for email templates.
- *
- * @returns `{ date, time }` formatted for the email template variables
- */
-export function formatDateTimeForEmail(
-  isoString: string,
-  timezone: string,
-): { date: string; time: string } {
-  const dt = new Date(isoString);
-  const date = dt.toLocaleDateString("en-US", {
-    weekday: "long",
-    year: "numeric",
-    month: "long",
-    day: "numeric",
-    timeZone: timezone,
-  });
-  const time = dt.toLocaleTimeString("en-US", {
-    hour: "numeric",
-    minute: "2-digit",
-    hour12: true,
-    timeZone: timezone,
-  });
-  return { date, time };
-}
-
-/**
- * Calculate duration in human-readable form from start/end ISO strings.
- */
-export function formatDurationForEmail(startsAt: string, endsAt: string): string {
-  const ms = new Date(endsAt).getTime() - new Date(startsAt).getTime();
-  const mins = Math.round(ms / 60000);
-  if (mins < 60) return `${mins} minutes`;
-  const hours = Math.floor(mins / 60);
-  const remainder = mins % 60;
-  return remainder === 0
-    ? `${hours} hour${hours !== 1 ? "s" : ""}`
-    : `${hours}h ${remainder}m`;
-}
-
-// ---------------------------------------------------------------------------
-// Job execution helpers (framework-agnostic)
-// ---------------------------------------------------------------------------
-
-/**
- * Send a booking confirmation email to the customer (and optionally the provider).
- *
- * Call this from your Inngest/Trigger.dev/BullMQ job handler.
- *
- * @example
- * ```ts
- * // In your Inngest function:
- * export const sendConfirmation = inngest.createFunction(
- *   { id: "send-confirmation-email" },
- *   { event: JOB_NAMES.SEND_CONFIRMATION_EMAIL },
- *   async ({ event }) => {
- *     await sendConfirmationEmail(event.data, emailAdapter);
- *   },
- * );
- * ```
- */
-export async function sendConfirmationEmail(
-  payload: ConfirmationEmailPayload,
-  emailAdapter: EmailAdapter,
-): Promise<void> {
-  const { date, time } = formatDateTimeForEmail(payload.startsAt, payload.timezone);
-  const duration = formatDurationForEmail(payload.startsAt, payload.endsAt);
-
-  const vars: EmailTemplateVars = {
-    bookingId: payload.bookingId,
-    eventTitle: payload.eventTitle,
-    providerName: payload.providerName,
-    customerName: payload.customerName,
-    customerEmail: payload.customerEmail,
-    date,
-    time,
-    duration,
-    timezone: payload.timezone,
-    location: payload.location,
-    managementUrl: payload.managementUrl,
-    unsubscribeUrl: payload.unsubscribeUrl,
-  };
-
-  const icsAttachment = generateBookingICS(payload);
-
-  await emailAdapter.send({
-    to: payload.customerEmail,
-    subject: `Booking Confirmed: ${payload.eventTitle} on ${date}`,
-    html: interpolateTemplate(CONFIRMATION_EMAIL_HTML, vars),
-    text: interpolateTemplate(CONFIRMATION_EMAIL_TEXT, vars),
-    attachments: icsAttachment ? [icsAttachment] : undefined,
-    headers: buildEmailHeaders(payload.unsubscribeUrl),
-  });
-
-  if (payload.notifyProvider) {
-    await emailAdapter.send({
-      to: payload.providerEmail,
-      subject: `New Booking: ${payload.customerName} — ${payload.eventTitle}`,
-      html: interpolateTemplate(CONFIRMATION_EMAIL_HTML, {
-        ...vars,
-        customerName: payload.customerName,
-      }),
-      text: interpolateTemplate(CONFIRMATION_EMAIL_TEXT, vars),
-      headers: buildEmailHeaders(),
-    });
-  }
-}
-
-/**
- * Send a reminder email to the customer before their appointment.
- */
-export async function sendReminderEmail(
-  payload: ReminderEmailPayload,
-  emailAdapter: EmailAdapter,
-): Promise<void> {
-  const { date, time } = formatDateTimeForEmail(payload.startsAt, payload.timezone);
-
-  const vars: EmailTemplateVars = {
-    bookingId: payload.bookingId,
-    eventTitle: payload.eventTitle,
-    providerName: payload.providerName,
-    customerName: payload.customerName,
-    customerEmail: payload.customerEmail,
-    date,
-    time,
-    duration: formatDurationForEmail(payload.startsAt, payload.endsAt),
-    timezone: payload.timezone,
-    location: payload.location,
-    managementUrl: payload.managementUrl,
-    unsubscribeUrl: payload.unsubscribeUrl,
-  };
-
-  const label =
-    payload.reminderHours >= 24
-      ? `${payload.reminderHours / 24} day`
-      : `${payload.reminderHours} hour`;
-
-  await emailAdapter.send({
-    to: payload.customerEmail,
-    subject: `Reminder: ${payload.eventTitle} in ${label}${Number(label.split(" ")[0]) !== 1 ? "s" : ""}`,
-    html: interpolateTemplate(REMINDER_EMAIL_HTML, vars),
-    headers: buildEmailHeaders(payload.unsubscribeUrl),
-  });
-}
-
-/**
- * Send cancellation notification emails to customer and provider.
- */
-export async function sendCancellationEmail(
-  payload: CancellationEmailPayload,
-  emailAdapter: EmailAdapter,
-): Promise<void> {
-  const { date, time } = formatDateTimeForEmail(payload.startsAt, payload.timezone);
-
-  const vars: EmailTemplateVars = {
-    bookingId: payload.bookingId,
-    eventTitle: payload.eventTitle,
-    providerName: payload.providerName,
-    customerName: payload.customerName,
-    customerEmail: payload.customerEmail,
-    date,
-    time,
-    duration: formatDurationForEmail(payload.startsAt, payload.endsAt),
-    timezone: payload.timezone,
-    location: payload.location,
-    unsubscribeUrl: payload.unsubscribeUrl,
-    cancelReason: payload.reason,
-  };
-
-  await emailAdapter.send({
-    to: payload.customerEmail,
-    subject: `Booking Cancelled: ${payload.eventTitle}`,
-    html: interpolateTemplate(CANCELLATION_EMAIL_HTML, vars),
-    headers: buildEmailHeaders(payload.unsubscribeUrl),
-  });
-
-  await emailAdapter.send({
-    to: payload.providerEmail,
-    subject: `Booking Cancelled by ${payload.cancelledBy}: ${payload.customerName}`,
-    html: interpolateTemplate(CANCELLATION_EMAIL_HTML, vars),
-    headers: buildEmailHeaders(),
-  });
-}
-
-/**
- * Send reschedule notification emails to customer and provider.
- */
-export async function sendRescheduleEmail(
-  payload: RescheduleEmailPayload,
-  emailAdapter: EmailAdapter,
-): Promise<void> {
-  const { date: newDate, time: newTime } = formatDateTimeForEmail(
-    payload.startsAt,
-    payload.timezone,
-  );
-  const { date: oldDate, time: oldTime } = formatDateTimeForEmail(
-    payload.oldStartsAt,
-    payload.timezone,
-  );
-
-  const vars: EmailTemplateVars = {
-    bookingId: payload.bookingId,
-    eventTitle: payload.eventTitle,
-    providerName: payload.providerName,
-    customerName: payload.customerName,
-    customerEmail: payload.customerEmail,
-    date: newDate,
-    time: newTime,
-    duration: formatDurationForEmail(payload.startsAt, payload.endsAt),
-    timezone: payload.timezone,
-    location: payload.location,
-    managementUrl: payload.managementUrl,
-    unsubscribeUrl: payload.unsubscribeUrl,
-    oldDate,
-    oldTime,
-    newDate,
-    newTime,
-  };
-
-  await emailAdapter.send({
-    to: payload.customerEmail,
-    subject: `Booking Rescheduled: ${payload.eventTitle}`,
-    html: interpolateTemplate(RESCHEDULE_EMAIL_HTML, vars),
-    headers: buildEmailHeaders(payload.unsubscribeUrl),
-  });
-
-  await emailAdapter.send({
-    to: payload.providerEmail,
-    subject: `Booking Rescheduled: ${payload.customerName} — ${payload.eventTitle}`,
-    html: interpolateTemplate(RESCHEDULE_EMAIL_HTML, vars),
-    headers: buildEmailHeaders(),
-  });
-}
-
-/**
- * Schedule the auto-rejection of a pending booking using the job adapter.
- *
- * Call this immediately after creating a booking that requires confirmation.
- *
- * @param bookingId - ID of the pending booking
- * @param deadline - Date at which to auto-reject (from `getAutoRejectDeadline`)
- * @param jobs - Your `JobAdapter` instance
- * @returns The scheduled job ID (store it if you need to cancel on manual confirm/reject)
- */
-export async function scheduleAutoReject(
-  bookingId: string,
-  deadline: Date,
-  jobs: JobAdapter,
-): Promise<string> {
-  const payload: AutoRejectPendingPayload = { bookingId, actor: "system" };
-  return jobs.schedule(JOB_NAMES.AUTO_REJECT_PENDING, payload, deadline);
-}
-
-/**
- * Sync a confirmed booking to the provider's connected calendar.
- */
-export async function syncBookingToCalendar(
-  payload: CalendarSyncPayload,
-  calendarAdapter: CalendarAdapter,
-): Promise<string | undefined> {
-  const result = await calendarAdapter.createEvent({
-    title: `${payload.eventTitle} — ${payload.customerName}`,
-    description: `Customer: ${payload.customerName} (${payload.customerEmail})`,
-    startsAt: new Date(payload.startsAt),
-    endsAt: new Date(payload.endsAt),
-    timezone: payload.timezone,
-    location: payload.location,
-    attendees: [payload.customerEmail],
-  });
-  return result.eventId;
-}
-
-/**
- * Delete a calendar event when a booking is cancelled.
- */
-export async function deleteBookingFromCalendar(
-  externalEventId: string,
-  calendarAdapter: CalendarAdapter,
-): Promise<void> {
-  await calendarAdapter.deleteEvent(externalEventId);
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-function buildEmailHeaders(
-  unsubscribeUrl?: string,
-): Record<string, string> | undefined {
-  if (!unsubscribeUrl) return undefined;
-  return {
-    "List-Unsubscribe": `<${unsubscribeUrl}>`,
-    "List-Unsubscribe-Post": "List-Unsubscribe=One-Click",
-  };
-}
-
-function generateBookingICS(
-  payload: NotificationBookingData,
-): { filename: string; content: string; contentType: string } | null {
-  try {
-    const attachment = generateICSAttachment({
-      id: payload.bookingId,
-      title: payload.eventTitle,
-      startsAt: new Date(payload.startsAt),
-      endsAt: new Date(payload.endsAt),
-      location: payload.location,
-      description: `Booking with ${payload.providerName}`,
-      organizerEmail: payload.providerEmail,
-      attendeeEmail: payload.customerEmail,
-    });
-    return {
-      filename: attachment.filename,
-      content: attachment.content as string,
-      contentType: attachment.contentType ?? "text/calendar",
-    };
-  } catch {
-    return null;
-  }
-}
-
-export { JOB_NAMES };

package/src/serialization-retry.ts

@@ -1,94 +0,0 @@
-import {
-  BookingConflictError,
-  SerializationRetryExhaustedError,
-} from "@thebookingkit/core";
-
-/** Options for the serialization retry wrapper */
-export interface SerializableRetryOptions {
-  /** Maximum number of retries on serialization failure. Default: 3 */
-  maxRetries?: number;
-  /** Base delay in milliseconds for exponential backoff. Default: 50 */
-  baseDelayMs?: number;
-}
-
-/**
- * Postgres SQLSTATE codes we handle:
- * - 40001: serialization_failure (SERIALIZABLE transaction contention)
- * - 23P01: exclusion_violation (EXCLUDE constraint — slot already taken)
- */
-const SERIALIZATION_FAILURE = "40001";
-const EXCLUSION_VIOLATION = "23P01";
-
-/**
- * Check if an error is a Postgres error with a specific code.
- */
-function getPostgresErrorCode(error: unknown): string | undefined {
-  if (
-    error &&
-    typeof error === "object" &&
-    "code" in error &&
-    typeof (error as { code: unknown }).code === "string"
-  ) {
-    return (error as { code: string }).code;
-  }
-  return undefined;
-}
-
-/**
- * Wraps a database operation in serialization retry logic.
- *
- * If the operation fails with SQLSTATE 40001 (serialization_failure),
- * retries up to `maxRetries` times with jittered exponential backoff.
- *
- * If the operation fails with SQLSTATE 23P01 (exclusion_violation),
- * immediately throws a `BookingConflictError` (no retry — the slot is taken).
- *
- * @example
- * ```ts
- * const booking = await withSerializableRetry(
- *   () => db.transaction(async (tx) => {
- *     // insert booking in SERIALIZABLE isolation
- *   }),
- *   { maxRetries: 3 }
- * );
- * ```
- */
-export async function withSerializableRetry<T>(
-  fn: () => Promise<T>,
-  options?: SerializableRetryOptions,
-): Promise<T> {
-  const maxRetries = options?.maxRetries ?? 3;
-  const baseDelayMs = options?.baseDelayMs ?? 50;
-
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      const code = getPostgresErrorCode(error);
-
-      // Exclusion violation — slot is taken, do not retry
-      if (code === EXCLUSION_VIOLATION) {
-        throw new BookingConflictError();
-      }
-
-      // Serialization failure — retry with backoff
-      if (code === SERIALIZATION_FAILURE && attempt < maxRetries) {
-        const delay = baseDelayMs * Math.pow(2, attempt);
-        const jitter = Math.random() * delay;
-        await new Promise((resolve) => setTimeout(resolve, delay + jitter));
-        continue;
-      }
-
-      // All retries exhausted for serialization failure
-      if (code === SERIALIZATION_FAILURE) {
-        throw new SerializationRetryExhaustedError(maxRetries);
-      }
-
-      // Unknown error — rethrow as-is
-      throw error;
-    }
-  }
-
-  // Should never reach here, but TypeScript needs it
-  throw new SerializationRetryExhaustedError(maxRetries);
-}