@thebookingkit/server 0.1.1

package/src/__tests__/workflows.test.ts

@@ -0,0 +1,422 @@
+import { describe, it, expect } from "vitest";
+import {
+  resolveTemplateVariables,
+  evaluateConditions,
+  validateWorkflow,
+  matchWorkflows,
+  DEFAULT_TEMPLATES,
+  WorkflowValidationError,
+  type WorkflowDefinition,
+  type WorkflowContext,
+  type WorkflowCondition,
+} from "../workflows.js";
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+function makeWorkflow(
+  overrides?: Partial<WorkflowDefinition>,
+): WorkflowDefinition {
+  return {
+    id: "wf-1",
+    name: "Confirmation Email",
+    trigger: "booking_created",
+    conditions: [],
+    actions: [
+      {
+        type: "send_email",
+        to: "customer",
+        subject: "Booking Confirmed: {booking.title}",
+        body: "Hi {attendee.name}, your booking is confirmed.",
+      },
+    ],
+    isActive: true,
+    ...overrides,
+  };
+}
+
+const sampleContext: WorkflowContext = {
+  bookingId: "bk-1",
+  eventTypeId: "evt-1",
+  providerId: "prov-1",
+  customerEmail: "jane@example.com",
+  customerName: "Jane Doe",
+  hostName: "Dr. Smith",
+  eventTitle: "Consultation",
+  eventDuration: 30,
+  eventLocation: "123 Main St",
+  startsAt: new Date("2026-03-15T14:00:00Z"),
+  endsAt: new Date("2026-03-15T14:30:00Z"),
+  managementUrl: "https://example.com/manage/bk-1",
+  status: "confirmed",
+};
+
+// ---------------------------------------------------------------------------
+// resolveTemplateVariables
+// ---------------------------------------------------------------------------
+
+describe("resolveTemplateVariables", () => {
+  it("resolves all standard variables", () => {
+    const template =
+      "Hi {attendee.name}, your {booking.title} with {host.name} is on {booking.date} at {booking.startTime}–{booking.endTime}. Duration: {event.duration}. Location: {event.location}. Manage: {booking.managementUrl}";
+    const result = resolveTemplateVariables(template, sampleContext);
+
+    expect(result).toContain("Jane Doe");
+    expect(result).toContain("Consultation");
+    expect(result).toContain("Dr. Smith");
+    expect(result).toContain("30 minutes");
+    expect(result).toContain("123 Main St");
+    expect(result).toContain("https://example.com/manage/bk-1");
+    expect(result).not.toContain("{");
+  });
+
+  it("replaces missing variables with empty strings", () => {
+    const template = "Hi {attendee.name}, location: {event.location}";
+    const result = resolveTemplateVariables(template, {
+      customerName: "Jane",
+    });
+
+    expect(result).toBe("Hi Jane, location: ");
+  });
+
+  it("handles template with no variables", () => {
+    const result = resolveTemplateVariables("Hello world", sampleContext);
+    expect(result).toBe("Hello world");
+  });
+
+  it("handles empty template", () => {
+    const result = resolveTemplateVariables("", sampleContext);
+    expect(result).toBe("");
+  });
+
+  it("resolves default confirmation template", () => {
+    const result = resolveTemplateVariables(
+      DEFAULT_TEMPLATES.confirmation.body,
+      sampleContext,
+    );
+
+    expect(result).toContain("Jane Doe");
+    expect(result).toContain("Consultation");
+    expect(result).toContain("Dr. Smith");
+    expect(result).not.toContain("{attendee.name}");
+  });
+
+  it("resolves default reminder template", () => {
+    const result = resolveTemplateVariables(
+      DEFAULT_TEMPLATES.reminder_24h.body,
+      sampleContext,
+    );
+
+    expect(result).toContain("Jane Doe");
+    expect(result).toContain("Consultation");
+  });
+
+  it("resolves default cancellation template", () => {
+    const result = resolveTemplateVariables(
+      DEFAULT_TEMPLATES.cancellation.body,
+      sampleContext,
+    );
+
+    expect(result).toContain("Jane Doe");
+    expect(result).toContain("Consultation");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// evaluateConditions
+// ---------------------------------------------------------------------------
+
+describe("evaluateConditions", () => {
+  it("returns true for empty conditions (unconditional)", () => {
+    expect(evaluateConditions([], sampleContext)).toBe(true);
+  });
+
+  it("equals operator matches", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "eventTypeId", operator: "equals", value: "evt-1" },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(true);
+  });
+
+  it("equals operator rejects non-match", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "eventTypeId", operator: "equals", value: "evt-2" },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(false);
+  });
+
+  it("not_equals operator works", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "status", operator: "not_equals", value: "cancelled" },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(true);
+  });
+
+  it("contains operator works (case-insensitive)", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "customerEmail", operator: "contains", value: "EXAMPLE" },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(true);
+  });
+
+  it("in operator works with array", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "status", operator: "in", value: ["confirmed", "pending"] },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(true);
+  });
+
+  it("in operator rejects when not in array", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "status", operator: "in", value: ["cancelled", "pending"] },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(false);
+  });
+
+  it("requires ALL conditions to match (AND logic)", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "eventTypeId", operator: "equals", value: "evt-1" },
+      { field: "status", operator: "equals", value: "cancelled" }, // doesn't match
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(false);
+  });
+
+  it("handles missing context fields gracefully", () => {
+    const conditions: WorkflowCondition[] = [
+      { field: "nonexistentField", operator: "equals", value: "" },
+    ];
+    expect(evaluateConditions(conditions, sampleContext)).toBe(true); // "" === ""
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateWorkflow
+// ---------------------------------------------------------------------------
+
+describe("validateWorkflow", () => {
+  it("accepts valid workflow", () => {
+    expect(() => validateWorkflow(makeWorkflow())).not.toThrow();
+  });
+
+  it("rejects empty name", () => {
+    expect(() => validateWorkflow(makeWorkflow({ name: "" }))).toThrow(
+      WorkflowValidationError,
+    );
+    expect(() => validateWorkflow(makeWorkflow({ name: "" }))).toThrow(
+      "name is required",
+    );
+  });
+
+  it("rejects invalid trigger", () => {
+    expect(() =>
+      validateWorkflow(makeWorkflow({ trigger: "invalid" as never })),
+    ).toThrow("Invalid trigger");
+  });
+
+  it("rejects empty actions", () => {
+    expect(() =>
+      validateWorkflow(makeWorkflow({ actions: [] })),
+    ).toThrow("at least one action");
+  });
+
+  it("rejects email action without to", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [
+            { type: "send_email", to: "", subject: "Hi", body: "Hello" },
+          ],
+        }),
+      ),
+    ).toThrow("'to' field");
+  });
+
+  it("rejects email action without subject", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [
+            { type: "send_email", to: "customer", subject: "", body: "Hello" },
+          ],
+        }),
+      ),
+    ).toThrow("'subject' field");
+  });
+
+  it("rejects email action without body", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [
+            { type: "send_email", to: "customer", subject: "Hi", body: "" },
+          ],
+        }),
+      ),
+    ).toThrow("'body' field");
+  });
+
+  it("rejects SMS action without to", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [{ type: "send_sms", to: "", body: "Hello" }],
+        }),
+      ),
+    ).toThrow("'to' field");
+  });
+
+  it("rejects webhook action without url", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [{ type: "fire_webhook", url: "" }],
+        }),
+      ),
+    ).toThrow("'url' field");
+  });
+
+  it("rejects status update action without status", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [{ type: "update_status", status: "" }],
+        }),
+      ),
+    ).toThrow("'status' field");
+  });
+
+  it("accepts calendar event action with no extra fields", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          actions: [{ type: "create_calendar_event" }],
+        }),
+      ),
+    ).not.toThrow();
+  });
+
+  it("rejects condition with empty field", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          conditions: [{ field: "", operator: "equals", value: "x" }],
+        }),
+      ),
+    ).toThrow("Condition field is required");
+  });
+
+  it("rejects invalid condition operator", () => {
+    expect(() =>
+      validateWorkflow(
+        makeWorkflow({
+          conditions: [
+            { field: "status", operator: "invalid" as never, value: "x" },
+          ],
+        }),
+      ),
+    ).toThrow("Invalid condition operator");
+  });
+
+  it("validates all supported triggers", () => {
+    const triggers = [
+      "booking_created",
+      "booking_confirmed",
+      "booking_cancelled",
+      "booking_rescheduled",
+      "before_event",
+      "after_event",
+      "payment_received",
+      "payment_failed",
+      "no_show_confirmed",
+      "form_submitted",
+    ] as const;
+
+    for (const trigger of triggers) {
+      expect(() =>
+        validateWorkflow(makeWorkflow({ trigger })),
+      ).not.toThrow();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// matchWorkflows
+// ---------------------------------------------------------------------------
+
+describe("matchWorkflows", () => {
+  const workflows: WorkflowDefinition[] = [
+    makeWorkflow({ id: "wf-1", trigger: "booking_created" }),
+    makeWorkflow({
+      id: "wf-2",
+      trigger: "booking_cancelled",
+      conditions: [
+        { field: "eventTypeId", operator: "equals", value: "evt-1" },
+      ],
+    }),
+    makeWorkflow({
+      id: "wf-3",
+      trigger: "booking_created",
+      isActive: false,
+    }),
+    makeWorkflow({
+      id: "wf-4",
+      trigger: "booking_created",
+      conditions: [
+        { field: "eventTypeId", operator: "equals", value: "evt-99" },
+      ],
+    }),
+  ];
+
+  it("matches active workflows with matching trigger", () => {
+    const matched = matchWorkflows(workflows, "booking_created", sampleContext);
+    expect(matched).toHaveLength(1);
+    expect(matched[0].id).toBe("wf-1");
+  });
+
+  it("excludes inactive workflows", () => {
+    const matched = matchWorkflows(workflows, "booking_created", sampleContext);
+    expect(matched.find((w) => w.id === "wf-3")).toBeUndefined();
+  });
+
+  it("excludes workflows with unmet conditions", () => {
+    const matched = matchWorkflows(workflows, "booking_created", sampleContext);
+    expect(matched.find((w) => w.id === "wf-4")).toBeUndefined();
+  });
+
+  it("matches workflows with met conditions", () => {
+    const matched = matchWorkflows(
+      workflows,
+      "booking_cancelled",
+      sampleContext,
+    );
+    expect(matched).toHaveLength(1);
+    expect(matched[0].id).toBe("wf-2");
+  });
+
+  it("returns empty array when no workflows match", () => {
+    const matched = matchWorkflows(workflows, "payment_received", sampleContext);
+    expect(matched).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// DEFAULT_TEMPLATES
+// ---------------------------------------------------------------------------
+
+describe("DEFAULT_TEMPLATES", () => {
+  it("has all expected templates", () => {
+    expect(DEFAULT_TEMPLATES).toHaveProperty("confirmation");
+    expect(DEFAULT_TEMPLATES).toHaveProperty("reminder_24h");
+    expect(DEFAULT_TEMPLATES).toHaveProperty("reminder_1h");
+    expect(DEFAULT_TEMPLATES).toHaveProperty("cancellation");
+    expect(DEFAULT_TEMPLATES).toHaveProperty("followup");
+  });
+
+  it("each template has subject and body", () => {
+    for (const [, template] of Object.entries(DEFAULT_TEMPLATES)) {
+      expect(template.subject).toBeTruthy();
+      expect(template.body).toBeTruthy();
+    }
+  });
+});

package/src/adapters/calendar-adapter.ts

@@ -0,0 +1,49 @@
+/**
+ * Calendar sync adapter interface.
+ * Default implementation uses Google Calendar OAuth.
+ * Swap to Outlook Calendar or CalDAV by implementing this interface.
+ */
+export interface CalendarAdapter {
+  /** Create a calendar event for a booking */
+  createEvent(options: CalendarEventOptions): Promise<CalendarEventResult>;
+  /** Update an existing calendar event */
+  updateEvent(eventId: string, options: Partial<CalendarEventOptions>): Promise<CalendarEventResult>;
+  /** Delete a calendar event */
+  deleteEvent(eventId: string): Promise<void>;
+  /** Get conflicts (busy times) from external calendar */
+  getConflicts(timeMin: Date, timeMax: Date): Promise<CalendarConflict[]>;
+}
+
+/** Options for creating/updating a calendar event */
+export interface CalendarEventOptions {
+  /** Event title */
+  title: string;
+  /** Event description/notes */
+  description?: string;
+  /** Event start time */
+  startsAt: Date;
+  /** Event end time */
+  endsAt: Date;
+  /** Event location */
+  location?: string;
+  /** Attendee email addresses */
+  attendees?: string[];
+  /** Provider's timezone */
+  timezone?: string;
+}
+
+/** Result of creating/updating a calendar event */
+export interface CalendarEventResult {
+  /** External calendar event ID */
+  eventId: string;
+  /** Link to the calendar event */
+  eventUrl?: string;
+}
+
+/** A busy time period from an external calendar */
+export interface CalendarConflict {
+  /** Start of busy period */
+  start: Date;
+  /** End of busy period */
+  end: Date;
+}

package/src/adapters/email-adapter.ts

@@ -0,0 +1,108 @@
+/**
+ * Email sending adapter interface.
+ * Default implementation uses Resend. Swap to SendGrid, AWS SES,
+ * or Postmark by implementing this interface.
+ */
+export interface EmailAdapter {
+  /** Send a single email */
+  send(options: SendEmailOptions): Promise<EmailResult>;
+  /** Send multiple emails in a batch */
+  sendBatch(emails: SendEmailOptions[]): Promise<EmailResult[]>;
+  /** Get delivery status of a previously sent email */
+  getDeliveryStatus?(messageId: string): Promise<EmailDeliveryStatus>;
+}
+
+/** Options for sending an email */
+export interface SendEmailOptions {
+  /** Recipient email address */
+  to: string;
+  /** Subject line */
+  subject: string;
+  /** HTML body */
+  html: string;
+  /** Plain text body (fallback) */
+  text?: string;
+  /** From address (defaults to configured sender) */
+  from?: string;
+  /** Reply-to address */
+  replyTo?: string;
+  /** Additional headers (List-Unsubscribe, etc.) */
+  headers?: Record<string, string>;
+  /** File attachments */
+  attachments?: EmailAttachment[];
+  /** Tags for categorization */
+  tags?: Record<string, string>;
+}
+
+/** An email attachment */
+export interface EmailAttachment {
+  filename: string;
+  content: string | Buffer;
+  contentType?: string;
+}
+
+/** Result of sending an email */
+export interface EmailResult {
+  success: boolean;
+  messageId?: string;
+  error?: string;
+}
+
+/** Delivery status of an email */
+export interface EmailDeliveryStatus {
+  status: "sent" | "delivered" | "bounced" | "complained" | "failed";
+  timestamp: Date;
+}
+
+/**
+ * Generate an ICS calendar attachment for a booking.
+ */
+export function generateICSAttachment(booking: {
+  id: string;
+  title: string;
+  startsAt: Date;
+  endsAt: Date;
+  location?: string;
+  description?: string;
+  organizerEmail?: string;
+  attendeeEmail: string;
+}): EmailAttachment {
+  const formatICSDate = (d: Date) =>
+    d.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}/, "");
+
+  const ics = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    "PRODID:-//SlotKit//EN",
+    "CALSCALE:GREGORIAN",
+    "METHOD:PUBLISH",
+    "BEGIN:VEVENT",
+    `UID:${booking.id}@slotkit`,
+    `DTSTART:${formatICSDate(booking.startsAt)}`,
+    `DTEND:${formatICSDate(booking.endsAt)}`,
+    `SUMMARY:${escapeICS(booking.title)}`,
+    booking.location ? `LOCATION:${escapeICS(booking.location)}` : "",
+    booking.description ? `DESCRIPTION:${escapeICS(booking.description)}` : "",
+    booking.organizerEmail ? `ORGANIZER:mailto:${booking.organizerEmail}` : "",
+    `ATTENDEE:mailto:${booking.attendeeEmail}`,
+    `DTSTAMP:${formatICSDate(new Date())}`,
+    "END:VEVENT",
+    "END:VCALENDAR",
+  ]
+    .filter(Boolean)
+    .join("\r\n");
+
+  return {
+    filename: "booking.ics",
+    content: ics,
+    contentType: "text/calendar",
+  };
+}
+
+function escapeICS(text: string): string {
+  return text
+    .replace(/\\/g, "\\\\")
+    .replace(/;/g, "\\;")
+    .replace(/,/g, "\\,")
+    .replace(/\n/g, "\\n");
+}

package/src/adapters/index.ts

@@ -0,0 +1,36 @@
+export type {
+  EmailAdapter,
+  SendEmailOptions,
+  EmailResult,
+  EmailDeliveryStatus,
+  EmailAttachment,
+} from "./email-adapter.js";
+export { generateICSAttachment } from "./email-adapter.js";
+
+export type {
+  CalendarAdapter,
+  CalendarEventOptions,
+  CalendarEventResult,
+  CalendarConflict,
+} from "./calendar-adapter.js";
+
+export type { JobAdapter } from "./job-adapter.js";
+export { JOB_NAMES } from "./job-adapter.js";
+
+export type { StorageAdapter } from "./storage-adapter.js";
+
+export type {
+  SmsAdapter,
+  SendSmsOptions,
+  SmsResult,
+} from "./sms-adapter.js";
+
+export type {
+  PaymentAdapter,
+  CreatePaymentIntentOptions,
+  CreatePaymentIntentResult,
+  CreateSetupIntentOptions,
+  CreateSetupIntentResult,
+  CaptureResult,
+  RefundResult,
+} from "./payment-adapter.js";

package/src/adapters/job-adapter.ts

@@ -0,0 +1,26 @@
+/**
+ * Background job adapter interface.
+ * Default implementation uses Inngest. Swap to Trigger.dev,
+ * BullMQ, or Vercel Cron by implementing this interface.
+ */
+export interface JobAdapter {
+  /** Enqueue a job for immediate execution */
+  enqueue<T>(jobName: string, payload: T): Promise<void>;
+  /** Schedule a job for future execution */
+  schedule<T>(jobName: string, payload: T, runAt: Date): Promise<string>;
+  /** Cancel a previously scheduled job */
+  cancel(jobId: string): Promise<void>;
+}
+
+/** Common job names used by SlotKit */
+export const JOB_NAMES = {
+  SEND_CONFIRMATION_EMAIL: "slotkit/send-confirmation-email",
+  SEND_REMINDER_EMAIL: "slotkit/send-reminder-email",
+  SEND_CANCELLATION_EMAIL: "slotkit/send-cancellation-email",
+  SEND_RESCHEDULE_EMAIL: "slotkit/send-reschedule-email",
+  SYNC_CALENDAR_EVENT: "slotkit/sync-calendar-event",
+  DELETE_CALENDAR_EVENT: "slotkit/delete-calendar-event",
+  CHECK_CALENDAR_CONFLICTS: "slotkit/check-calendar-conflicts",
+  AUTO_REJECT_PENDING: "slotkit/auto-reject-pending-booking",
+  PROCESS_WEBHOOK: "slotkit/process-webhook",
+} as const;