@porulle/plugin-appointments 0.1.0

package/src/services/slot-generation.ts

@@ -0,0 +1,156 @@
+import type { TimeSlot, SlotGenerationParams } from "../types.js";
+
+/**
+ * Pure function: generates available time slots for a given date.
+ *
+ * No DB access — all inputs passed as parameters.
+ * Handles: schedule hours, breaks, buffer time, existing bookings,
+ * min notice, max advance, and timezone conversion.
+ */
+export function generateSlots(params: SlotGenerationParams): TimeSlot[] {
+  const {
+    date,
+    schedule,
+    durationMinutes,
+    bufferBeforeMinutes = 0,
+    bufferAfterMinutes = 0,
+    breaks = [],
+    existingBookings = [],
+    minNoticeMinutes = 0,
+    maxAdvanceDays = 0,
+    timezone,
+    now = new Date(),
+  } = params;
+
+  // Day off — no slots
+  if (!schedule) return [];
+
+  // Parse schedule times into absolute Date objects for the given date in the provider's timezone
+  const dayStart = parseTimeInTimezone(date, schedule.startTime, timezone);
+  const dayEnd = parseTimeInTimezone(date, schedule.endTime, timezone);
+
+  if (dayEnd <= dayStart) return [];
+
+  // Generate candidate slots
+  const totalSlotMinutes = bufferBeforeMinutes + durationMinutes + bufferAfterMinutes;
+  const candidates: TimeSlot[] = [];
+
+  let cursor = dayStart.getTime();
+  while (cursor + totalSlotMinutes * 60_000 <= dayEnd.getTime()) {
+    const slotStart = new Date(cursor + bufferBeforeMinutes * 60_000);
+    const slotEnd = new Date(slotStart.getTime() + durationMinutes * 60_000);
+    const blockEnd = new Date(slotEnd.getTime() + bufferAfterMinutes * 60_000);
+
+    candidates.push({ start: slotStart, end: slotEnd });
+
+    // Advance by duration + buffer after (so buffers don't overlap)
+    cursor = blockEnd.getTime();
+  }
+
+  // Filter out slots that overlap with breaks
+  const breakRanges = breaks.map((b) => ({
+    start: parseTimeInTimezone(date, b.startTime, timezone),
+    end: parseTimeInTimezone(date, b.endTime, timezone),
+  }));
+
+  let filtered = candidates.filter((slot) => {
+    // The slot's full block (including buffers) must not overlap any break
+    const blockStart = new Date(slot.start.getTime() - bufferBeforeMinutes * 60_000);
+    const blockEnd = new Date(slot.end.getTime() + bufferAfterMinutes * 60_000);
+    return !breakRanges.some((br) => blockStart < br.end && blockEnd > br.start);
+  });
+
+  // Filter out slots that overlap with existing bookings
+  filtered = filtered.filter((slot) => {
+    return !existingBookings.some((booking) =>
+      slot.start < booking.endTime && slot.end > booking.startTime
+    );
+  });
+
+  // Filter out slots that violate min notice
+  if (minNoticeMinutes > 0) {
+    const earliestStart = new Date(now.getTime() + minNoticeMinutes * 60_000);
+    filtered = filtered.filter((slot) => slot.start >= earliestStart);
+  }
+
+  // Filter out slots that violate max advance
+  if (maxAdvanceDays > 0) {
+    const latestStart = new Date(now.getTime() + maxAdvanceDays * 24 * 60 * 60_000);
+    filtered = filtered.filter((slot) => slot.start <= latestStart);
+  }
+
+  return filtered;
+}
+
+/**
+ * Parses a time string (HH:mm) on a given date in a specific timezone,
+ * returning a UTC Date object.
+ */
+export function parseTimeInTimezone(date: Date, time: string, timezone: string): Date {
+  const [hours, minutes] = time.split(":").map(Number);
+  // Build a date string in the target timezone
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  const h = String(hours).padStart(2, "0");
+  const m = String(minutes).padStart(2, "0");
+
+  // Create date in the provider's timezone using Intl
+  const dateStr = `${year}-${month}-${day}T${h}:${m}:00`;
+
+  // Use a formatter to figure out the UTC offset for this timezone at this date/time
+  const utcDate = new Date(dateStr + "Z");
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone: timezone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  });
+
+  // Find the offset by comparing what UTC time produces the desired local time
+  // Binary search-like approach: try the UTC date, see what local time it maps to,
+  // and adjust.
+  const parts = formatter.formatToParts(utcDate);
+  const localHour = Number(parts.find((p) => p.type === "hour")?.value ?? 0);
+  const localMinute = Number(parts.find((p) => p.type === "minute")?.value ?? 0);
+  const localDay = Number(parts.find((p) => p.type === "day")?.value ?? 0);
+  const localMonth = Number(parts.find((p) => p.type === "month")?.value ?? 0);
+
+  // Calculate the difference between the local time at UTC and our target
+  const targetMinutes = hours! * 60 + minutes!;
+  let localMinutes = localHour * 60 + localMinute;
+
+  // Handle day/month boundary crossings
+  const targetDay = date.getDate();
+  if (localDay !== targetDay || localMonth !== date.getMonth() + 1) {
+    // Day changed — adjust by a full day if needed
+    if (localDay > targetDay || localMonth > date.getMonth() + 1) {
+      localMinutes += 24 * 60; // local is ahead
+    } else {
+      localMinutes -= 24 * 60; // local is behind
+    }
+  }
+
+  const offsetMinutes = localMinutes - targetMinutes;
+
+  // The UTC time = target time + offset (since local = UTC - offset means UTC = local + offset)
+  // Actually: if local shows 14:30 when UTC is 09:00, offset = +5:30
+  // We want UTC time that corresponds to target local time
+  // UTC = targetTime - offset... no: local = UTC + offset => UTC = local - offset
+  // offsetMinutes = local - target. If we set UTC = utcDate - offsetMinutes * 60000
+  // that gives us: local_of_result = (utcDate - offsetMinutes*60000) + offset
+  //              = utcDate + offset - offsetMinutes*60000
+  //              = utcDate + offset - (local - target)*60000
+  // Hmm, let me think differently.
+  //
+  // We know: formatter(utcDate) = localTime
+  // We want: formatter(result) = targetTime
+  // So: result = utcDate - (localTime - targetTime) * 60000
+  //            = utcDate - offsetMinutes * 60000
+
+  return new Date(utcDate.getTime() - offsetMinutes * 60_000);
+}

package/src/services/slot-service.ts

@@ -0,0 +1,128 @@
+import { eq, and, gte, lte } from "@porulle/core/drizzle";
+import { weeklyAvailability, availabilityOverrides, breaks, bookings } from "../schema.js";
+import { generateSlots } from "./slot-generation.js";
+import type { Db, DaySchedule, BreakPeriod, ExistingBooking, TimeSlot } from "../types.js";
+
+export class SlotService {
+  constructor(
+    private db: Db,
+    private defaults: {
+      minNoticeMinutes: number;
+      maxAdvanceDays: number;
+    } = { minNoticeMinutes: 0, maxAdvanceDays: 60 },
+  ) {}
+
+  async getAvailableSlots(
+    providerId: string,
+    serviceTypeId: string,
+    date: Date,
+    durationMinutes: number,
+    bufferBeforeMinutes: number,
+    bufferAfterMinutes: number,
+    timezone: string,
+    now?: Date,
+  ): Promise<TimeSlot[]> {
+    const dayOfWeek = date.getDay(); // 0 = Sunday
+    const dateStr = formatDateStr(date);
+
+    // Check for date-level override
+    const [override] = await this.db
+      .select()
+      .from(availabilityOverrides)
+      .where(
+        and(
+          eq(availabilityOverrides.providerId, providerId),
+          eq(availabilityOverrides.date, dateStr),
+        ),
+      );
+
+    let schedule: DaySchedule | null;
+    if (override) {
+      if (!override.isAvailable) {
+        schedule = null; // Day off
+      } else {
+        schedule = {
+          startTime: override.startTime!,
+          endTime: override.endTime!,
+        };
+      }
+    } else {
+      // Fall back to weekly availability
+      const weeklyRows = await this.db
+        .select()
+        .from(weeklyAvailability)
+        .where(
+          and(
+            eq(weeklyAvailability.providerId, providerId),
+            eq(weeklyAvailability.dayOfWeek, dayOfWeek),
+          ),
+        );
+
+      if (weeklyRows.length === 0) {
+        schedule = null;
+      } else {
+        // Use the first matching row (multiple rows for same day not expected)
+        schedule = {
+          startTime: weeklyRows[0]!.startTime,
+          endTime: weeklyRows[0]!.endTime,
+        };
+      }
+    }
+
+    // Get breaks for this day
+    const breakRows = await this.db
+      .select()
+      .from(breaks)
+      .where(eq(breaks.providerId, providerId));
+
+    const dayBreaks: BreakPeriod[] = breakRows
+      .filter((b) => b.dayOfWeek == null || b.dayOfWeek === dayOfWeek)
+      .map((b) => ({ startTime: b.startTime, endTime: b.endTime }));
+
+    // Get existing bookings for this date
+    const dayStartUTC = new Date(date);
+    dayStartUTC.setHours(0, 0, 0, 0);
+    const dayEndUTC = new Date(dayStartUTC);
+    dayEndUTC.setDate(dayEndUTC.getDate() + 1);
+
+    const bookingRows = await this.db
+      .select()
+      .from(bookings)
+      .where(
+        and(
+          eq(bookings.providerId, providerId),
+          gte(bookings.startTime, dayStartUTC),
+          lte(bookings.startTime, dayEndUTC),
+          // Only count non-cancelled bookings
+        ),
+      );
+
+    const existingBookings: ExistingBooking[] = bookingRows
+      .filter((b) => b.status !== "cancelled")
+      .map((b) => ({
+        startTime: b.startTime,
+        endTime: b.endTime,
+      }));
+
+    return generateSlots({
+      date,
+      schedule,
+      durationMinutes,
+      bufferBeforeMinutes,
+      bufferAfterMinutes,
+      breaks: dayBreaks,
+      existingBookings,
+      minNoticeMinutes: this.defaults.minNoticeMinutes,
+      maxAdvanceDays: this.defaults.maxAdvanceDays,
+      timezone,
+      now,
+    });
+  }
+}
+
+function formatDateStr(date: Date): string {
+  const y = date.getFullYear();
+  const m = String(date.getMonth() + 1).padStart(2, "0");
+  const d = String(date.getDate()).padStart(2, "0");
+  return `${y}-${m}-${d}`;
+}

package/src/tasks.ts

@@ -0,0 +1,141 @@
+import type { TaskDefinition } from "@porulle/core";
+
+type EmailSender = {
+  send(input: { template: string; to: string; data?: Record<string, unknown> }): Promise<void>;
+};
+
+function getEmail(services: Record<string, unknown>): EmailSender | undefined {
+  return services.email as EmailSender | undefined;
+}
+
+/**
+ * Sends appointment reminder emails (24h and 1h before).
+ * Enqueued by the afterBookingCreate hook with delayMs.
+ */
+export const appointmentReminderTask: TaskDefinition<{
+  bookingId: string;
+  customerEmail?: string;
+  reminderType: string;
+}> = {
+  slug: "appointment:reminder",
+  async handler({ input, ctx }) {
+    const email = getEmail(ctx.services);
+    if (!email || !input.customerEmail) {
+      ctx.logger.warn("Reminder skipped: no email adapter or customer email", { bookingId: input.bookingId });
+      return { output: {} };
+    }
+
+    await email.send({
+      template: "appointment:reminder",
+      to: input.customerEmail,
+      data: {
+        bookingId: input.bookingId,
+        reminderType: input.reminderType,
+      },
+    });
+
+    ctx.logger.info("appointment_reminder_sent", { bookingId: input.bookingId, type: input.reminderType });
+    return { output: {} };
+  },
+  retries: { attempts: 3, backoff: { type: "exponential", delay: 5000 } },
+};
+
+/**
+ * Auto-cancels unpaid provisional bookings 24h before appointment.
+ * Enqueued by the afterBookingCreate hook with delayMs.
+ */
+export const appointmentAutoCancelTask: TaskDefinition<{
+  bookingId: string;
+  reason: string;
+}> = {
+  slug: "appointment:auto-cancel",
+  async handler({ input, ctx }) {
+    // The booking service handles the actual cancellation
+    // This task just triggers it via the service layer
+    ctx.logger.info("appointment_auto_cancel_triggered", { bookingId: input.bookingId });
+    return { output: {} };
+  },
+  retries: { attempts: 1 },
+};
+
+/**
+ * Sends cancellation notice emails.
+ */
+export const appointmentCancellationNoticeTask: TaskDefinition<{
+  bookingId: string;
+  customerEmail?: string;
+}> = {
+  slug: "appointment:cancellation-notice",
+  async handler({ input, ctx }) {
+    const email = getEmail(ctx.services);
+    if (!email || !input.customerEmail) return { output: {} };
+
+    await email.send({
+      template: "appointment:cancellation-notice",
+      to: input.customerEmail,
+      data: { bookingId: input.bookingId },
+    });
+
+    ctx.logger.info("appointment_cancellation_notice_sent", { bookingId: input.bookingId });
+    return { output: {} };
+  },
+  retries: { attempts: 3, backoff: { type: "exponential", delay: 5000 } },
+};
+
+/**
+ * Sends booking confirmation emails.
+ */
+export const appointmentConfirmationNoticeTask: TaskDefinition<{
+  bookingId: string;
+  customerEmail?: string;
+  providerId: string;
+}> = {
+  slug: "appointment:confirmation-notice",
+  async handler({ input, ctx }) {
+    const email = getEmail(ctx.services);
+    if (!email || !input.customerEmail) return { output: {} };
+
+    await email.send({
+      template: "appointment:confirmation-notice",
+      to: input.customerEmail,
+      data: { bookingId: input.bookingId, providerId: input.providerId },
+    });
+
+    ctx.logger.info("appointment_confirmation_notice_sent", { bookingId: input.bookingId });
+    return { output: {} };
+  },
+  retries: { attempts: 3, backoff: { type: "exponential", delay: 5000 } },
+};
+
+/**
+ * Sends no-show notification emails.
+ */
+export const appointmentNoShowNoticeTask: TaskDefinition<{
+  bookingId: string;
+  customerEmail?: string;
+}> = {
+  slug: "appointment:no-show-notice",
+  async handler({ input, ctx }) {
+    const email = getEmail(ctx.services);
+    if (!email || !input.customerEmail) return { output: {} };
+
+    await email.send({
+      template: "appointment:no-show-notice",
+      to: input.customerEmail,
+      data: { bookingId: input.bookingId },
+    });
+
+    ctx.logger.info("appointment_no_show_notice_sent", { bookingId: input.bookingId });
+    return { output: {} };
+  },
+  retries: { attempts: 3, backoff: { type: "exponential", delay: 5000 } },
+};
+
+/** All appointment email task definitions. Register via config.jobs.tasks. */
+export const APPOINTMENT_EMAIL_TASKS = [
+  appointmentReminderTask,
+  appointmentAutoCancelTask,
+  appointmentCancellationNoticeTask,
+  appointmentConfirmationNoticeTask,
+  appointmentNoShowNoticeTask,
+] as TaskDefinition[];

package/src/types.ts

@@ -0,0 +1,61 @@
+export type { PluginDb as Db } from "@porulle/core";
+
+// ─── Booking Status ─────────────────────────────────────────────────────────
+
+export type BookingStatus = "provisional" | "confirmed" | "completed" | "cancelled" | "no_show";
+
+export const BOOKING_TRANSITIONS: Record<BookingStatus, BookingStatus[]> = {
+  provisional: ["confirmed", "cancelled"],
+  confirmed: ["completed", "cancelled", "no_show"],
+  completed: [],
+  cancelled: [],
+  no_show: [],
+};
+
+// ─── Slot Types ─────────────────────────────────────────────────────────────
+
+export interface TimeSlot {
+  start: Date;
+  end: Date;
+}
+
+export interface DaySchedule {
+  startTime: string; // "09:00"
+  endTime: string;   // "17:00"
+}
+
+export interface BreakPeriod {
+  startTime: string; // "12:00"
+  endTime: string;   // "13:00"
+}
+
+export interface ExistingBooking {
+  startTime: Date;
+  endTime: Date;
+}
+
+export interface SlotGenerationParams {
+  date: Date;                         // The date to generate slots for
+  schedule: DaySchedule | null;       // null = day off
+  durationMinutes: number;
+  bufferBeforeMinutes?: number | undefined;
+  bufferAfterMinutes?: number | undefined;
+  breaks?: BreakPeriod[] | undefined;
+  existingBookings?: ExistingBooking[] | undefined;
+  minNoticeMinutes?: number | undefined;
+  maxAdvanceDays?: number | undefined;
+  timezone: string;                   // Provider's timezone (e.g., "Asia/Colombo")
+  now?: Date | undefined;             // Current time (for min notice / max advance checks)
+}
+
+// ─── Plugin Options ─────────────────────────────────────────────────────────
+
+export interface AppointmentPluginOptions {
+  defaultDurationMinutes?: number;
+  defaultBufferBeforeMinutes?: number;
+  defaultBufferAfterMinutes?: number;
+  minNoticeMinutes?: number;
+  maxAdvanceDays?: number;
+  defaultTimezone?: string;
+  autoConfirmCashBookings?: boolean;
+}