@thebookingkit/server 0.1.1

package/src/auth.ts

@@ -0,0 +1,146 @@
+import { UnauthorizedError, ForbiddenError } from "@thebookingkit/core";
+
+/** Represents an authenticated user in the system */
+export interface AuthUser {
+  id: string;
+  email: string;
+  name?: string;
+  role?: "admin" | "provider" | "customer";
+}
+
+/** Session returned by the auth adapter */
+export interface AuthSession {
+  user: AuthUser;
+  expires: Date;
+}
+
+/**
+ * Pluggable authentication adapter interface.
+ * Default implementation uses NextAuth.js.
+ * Swap to Supabase Auth, Clerk, or Lucia by implementing this interface.
+ */
+export interface AuthAdapter {
+  /** Get the currently authenticated user from the request */
+  getCurrentUser(request: Request): Promise<AuthUser | null>;
+  /** Get the full session */
+  getSession(request: Request): Promise<AuthSession | null>;
+  /** Verify an API token or signed booking token */
+  verifyToken(token: string): Promise<AuthUser | null>;
+}
+
+/** Request with injected auth context */
+export interface AuthenticatedRequest extends Request {
+  user: AuthUser;
+}
+
+/** Options for the withAuth middleware */
+export interface WithAuthOptions {
+  /** Require a specific role */
+  requiredRole?: "admin" | "provider" | "customer";
+}
+
+/**
+ * Middleware wrapper that injects the authenticated user into every request.
+ *
+ * - Rejects unauthenticated requests with 401.
+ * - Optionally checks user role.
+ * - Passes the authenticated user to the handler.
+ *
+ * @example
+ * ```ts
+ * // In a Next.js API route
+ * export const GET = withAuth(authAdapter, async (req) => {
+ *   const userId = req.user.id;
+ *   // Provider can only access their own data
+ *   const bookings = await db.query.bookings.findMany({
+ *     where: eq(bookings.providerId, userId)
+ *   });
+ *   return Response.json(bookings);
+ * });
+ * ```
+ */
+export function withAuth(
+  adapter: AuthAdapter,
+  handler: (req: AuthenticatedRequest) => Promise<Response>,
+  options?: WithAuthOptions,
+): (req: Request) => Promise<Response> {
+  return async (req: Request): Promise<Response> => {
+    try {
+      // Try to get user from session first
+      let user = await adapter.getCurrentUser(req);
+
+      // If no session, try Bearer token
+      if (!user) {
+        const authHeader = req.headers.get("authorization");
+        if (authHeader?.startsWith("Bearer ")) {
+          const token = authHeader.slice(7);
+          user = await adapter.verifyToken(token);
+        }
+      }
+
+      if (!user) {
+        throw new UnauthorizedError();
+      }
+
+      // Check required role if specified
+      if (options?.requiredRole && user.role !== options.requiredRole) {
+        throw new ForbiddenError();
+      }
+
+      // Inject user into request
+      const authReq = req as AuthenticatedRequest;
+      authReq.user = user;
+
+      return await handler(authReq);
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        return Response.json(
+          { error: error.message, code: error.code },
+          { status: 401 },
+        );
+      }
+      if (error instanceof ForbiddenError) {
+        return Response.json(
+          { error: error.message, code: error.code },
+          { status: 403 },
+        );
+      }
+      throw error;
+    }
+  };
+}
+
+/**
+ * Helper to scope database queries to the authenticated user.
+ * Providers can only access their own rows (user_id matches).
+ *
+ * @example
+ * ```ts
+ * const provider = await assertOwnership(db, providers, req.user.id, providerId);
+ * ```
+ */
+export function assertProviderOwnership(
+  userId: string,
+  resourceUserId: string,
+): void {
+  if (userId !== resourceUserId) {
+    throw new ForbiddenError(
+      "You do not have permission to access this provider's data.",
+    );
+  }
+}
+
+/**
+ * Helper to verify customer access to their own bookings.
+ * Customers can only access bookings where customer_email matches.
+ */
+export function assertCustomerAccess(
+  userEmail: string,
+  bookingCustomerEmail: string,
+): void {
+  if (userEmail !== bookingCustomerEmail) {
+    throw new ForbiddenError(
+      "You do not have permission to access this booking.",
+    );
+  }
+}

package/src/booking-tokens.ts

@@ -0,0 +1,61 @@
+import { createHmac } from "crypto";
+
+/**
+ * Generate a signed booking management token.
+ *
+ * The token is a signed payload containing the booking ID and expiry time.
+ * It allows customers to view/manage their booking without authentication.
+ *
+ * @param bookingId - The booking UUID
+ * @param expiresAt - When the token expires
+ * @param secret - HMAC signing secret
+ */
+export function generateBookingToken(
+  bookingId: string,
+  expiresAt: Date,
+  secret: string,
+): string {
+  const payload = `${bookingId}:${expiresAt.getTime()}`;
+  const signature = createHmac("sha256", secret)
+    .update(payload)
+    .digest("hex")
+    .slice(0, 16);
+  return Buffer.from(`${payload}:${signature}`).toString("base64url");
+}
+
+/**
+ * Verify and decode a booking management token.
+ *
+ * @param token - The base64url-encoded token
+ * @param secret - HMAC signing secret (must match generation)
+ * @returns The booking ID if valid, null if invalid or expired
+ */
+export function verifyBookingToken(
+  token: string,
+  secret: string,
+): { bookingId: string; expiresAt: Date } | null {
+  try {
+    const decoded = Buffer.from(token, "base64url").toString("utf-8");
+    const parts = decoded.split(":");
+    if (parts.length !== 3) return null;
+
+    const [bookingId, expiresAtStr, signature] = parts;
+    const expiresAt = new Date(Number(expiresAtStr));
+
+    // Check expiry
+    if (expiresAt < new Date()) return null;
+
+    // Verify signature
+    const payload = `${bookingId}:${expiresAtStr}`;
+    const expectedSig = createHmac("sha256", secret)
+      .update(payload)
+      .digest("hex")
+      .slice(0, 16);
+
+    if (signature !== expectedSig) return null;
+
+    return { bookingId, expiresAt };
+  } catch {
+    return null;
+  }
+}

package/src/email-templates.ts

@@ -0,0 +1,140 @@
+/** Variables available in email templates */
+export interface EmailTemplateVars {
+  bookingId: string;
+  eventTitle: string;
+  providerName: string;
+  customerName: string;
+  customerEmail: string;
+  date: string;
+  time: string;
+  duration: string;
+  timezone: string;
+  location?: string;
+  managementUrl?: string;
+  unsubscribeUrl?: string;
+  cancelReason?: string;
+  oldDate?: string;
+  oldTime?: string;
+  newDate?: string;
+  newTime?: string;
+}
+
+/**
+ * Interpolate template variables into a template string.
+ * Variables use the format `{variableName}`.
+ */
+export function interpolateTemplate(
+  template: string,
+  vars: EmailTemplateVars,
+): string {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    const value = (vars as unknown as Record<string, string | undefined>)[key];
+    return value ?? match;
+  });
+}
+
+/** Default booking confirmation email template (HTML) */
+export const CONFIRMATION_EMAIL_HTML = `
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2>Booking Confirmed</h2>
+  <p>Hi {customerName},</p>
+  <p>Your booking has been confirmed. Here are the details:</p>
+  <table style="width: 100%; border-collapse: collapse;">
+    <tr><td style="padding: 8px; font-weight: bold;">Service</td><td style="padding: 8px;">{eventTitle}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Provider</td><td style="padding: 8px;">{providerName}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Date</td><td style="padding: 8px;">{date}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Time</td><td style="padding: 8px;">{time} ({timezone})</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Duration</td><td style="padding: 8px;">{duration}</td></tr>
+  </table>
+  <p style="margin-top: 20px;">
+    <a href="{managementUrl}" style="display: inline-block; padding: 12px 24px; background: #0070f3; color: white; text-decoration: none; border-radius: 6px;">
+      Manage Booking
+    </a>
+  </p>
+  <p style="margin-top: 30px; font-size: 12px; color: #666;">
+    <a href="{unsubscribeUrl}">Unsubscribe</a> from booking notifications.
+  </p>
+</div>
+`.trim();
+
+/** Default booking confirmation email (plain text) */
+export const CONFIRMATION_EMAIL_TEXT = `
+Booking Confirmed
+
+Hi {customerName},
+
+Your booking has been confirmed:
+
+Service: {eventTitle}
+Provider: {providerName}
+Date: {date}
+Time: {time} ({timezone})
+Duration: {duration}
+
+Manage your booking: {managementUrl}
+
+To unsubscribe: {unsubscribeUrl}
+`.trim();
+
+/** Default reminder email template */
+export const REMINDER_EMAIL_HTML = `
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2>Appointment Reminder</h2>
+  <p>Hi {customerName},</p>
+  <p>This is a reminder about your upcoming appointment:</p>
+  <table style="width: 100%; border-collapse: collapse;">
+    <tr><td style="padding: 8px; font-weight: bold;">Service</td><td style="padding: 8px;">{eventTitle}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Provider</td><td style="padding: 8px;">{providerName}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Date</td><td style="padding: 8px;">{date}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Time</td><td style="padding: 8px;">{time} ({timezone})</td></tr>
+  </table>
+  <p style="margin-top: 20px;">
+    <a href="{managementUrl}" style="display: inline-block; padding: 12px 24px; background: #0070f3; color: white; text-decoration: none; border-radius: 6px;">
+      Manage Booking
+    </a>
+  </p>
+  <p style="margin-top: 30px; font-size: 12px; color: #666;">
+    <a href="{unsubscribeUrl}">Unsubscribe</a>
+  </p>
+</div>
+`.trim();
+
+/** Default cancellation email template */
+export const CANCELLATION_EMAIL_HTML = `
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2>Booking Cancelled</h2>
+  <p>Hi {customerName},</p>
+  <p>Your booking has been cancelled:</p>
+  <table style="width: 100%; border-collapse: collapse;">
+    <tr><td style="padding: 8px; font-weight: bold;">Service</td><td style="padding: 8px;">{eventTitle}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Date</td><td style="padding: 8px;">{date}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Time</td><td style="padding: 8px;">{time} ({timezone})</td></tr>
+  </table>
+  <p style="margin-top: 30px; font-size: 12px; color: #666;">
+    <a href="{unsubscribeUrl}">Unsubscribe</a>
+  </p>
+</div>
+`.trim();
+
+/** Default reschedule email template */
+export const RESCHEDULE_EMAIL_HTML = `
+<div style="font-family: sans-serif; max-width: 600px; margin: 0 auto;">
+  <h2>Booking Rescheduled</h2>
+  <p>Hi {customerName},</p>
+  <p>Your booking has been rescheduled:</p>
+  <table style="width: 100%; border-collapse: collapse;">
+    <tr><td style="padding: 8px; font-weight: bold;">Service</td><td style="padding: 8px;">{eventTitle}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">Previous</td><td style="padding: 8px;">{oldDate} at {oldTime}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">New Date</td><td style="padding: 8px;">{newDate}</td></tr>
+    <tr><td style="padding: 8px; font-weight: bold;">New Time</td><td style="padding: 8px;">{newTime} ({timezone})</td></tr>
+  </table>
+  <p style="margin-top: 20px;">
+    <a href="{managementUrl}" style="display: inline-block; padding: 12px 24px; background: #0070f3; color: white; text-decoration: none; border-radius: 6px;">
+      Manage Booking
+    </a>
+  </p>
+  <p style="margin-top: 30px; font-size: 12px; color: #666;">
+    <a href="{unsubscribeUrl}">Unsubscribe</a>
+  </p>
+</div>
+`.trim();

package/src/index.ts

@@ -0,0 +1,192 @@
+// Re-export core errors used by server modules
+export {
+  BookingConflictError,
+  SerializationRetryExhaustedError,
+  UnauthorizedError,
+  ForbiddenError,
+} from "@thebookingkit/core";
+
+// Serialization retry utility
+export {
+  withSerializableRetry,
+  type SerializableRetryOptions,
+} from "./serialization-retry.js";
+
+// Auth middleware & adapters
+export {
+  withAuth,
+  assertProviderOwnership,
+  assertCustomerAccess,
+  type AuthUser,
+  type AuthSession,
+  type AuthAdapter,
+  type AuthenticatedRequest,
+  type WithAuthOptions,
+} from "./auth.js";
+
+// Adapters
+export type {
+  EmailAdapter,
+  SendEmailOptions,
+  EmailResult,
+  EmailDeliveryStatus,
+  EmailAttachment,
+  CalendarAdapter,
+  CalendarEventOptions,
+  CalendarEventResult,
+  CalendarConflict,
+  JobAdapter,
+  StorageAdapter,
+  SmsAdapter,
+  SendSmsOptions,
+  SmsResult,
+  PaymentAdapter,
+  CreatePaymentIntentOptions,
+  CreatePaymentIntentResult,
+  CreateSetupIntentOptions,
+  CreateSetupIntentResult,
+  CaptureResult,
+  RefundResult,
+} from "./adapters/index.js";
+export { generateICSAttachment, JOB_NAMES } from "./adapters/index.js";
+
+// Booking Tokens
+export {
+  generateBookingToken,
+  verifyBookingToken,
+} from "./booking-tokens.js";
+
+// Notification Jobs
+export {
+  sendConfirmationEmail,
+  sendReminderEmail,
+  sendCancellationEmail,
+  sendRescheduleEmail,
+  scheduleAutoReject,
+  syncBookingToCalendar,
+  deleteBookingFromCalendar,
+  formatDateTimeForEmail,
+  formatDurationForEmail,
+  type NotificationBookingData,
+  type ConfirmationEmailPayload,
+  type ReminderEmailPayload,
+  type CancellationEmailPayload,
+  type RescheduleEmailPayload,
+  type CalendarSyncPayload,
+  type CalendarDeletePayload,
+  type AutoRejectPendingPayload,
+} from "./notification-jobs.js";
+
+// Email Templates
+export {
+  interpolateTemplate,
+  CONFIRMATION_EMAIL_HTML,
+  CONFIRMATION_EMAIL_TEXT,
+  REMINDER_EMAIL_HTML,
+  CANCELLATION_EMAIL_HTML,
+  RESCHEDULE_EMAIL_HTML,
+  type EmailTemplateVars,
+} from "./email-templates.js";
+
+// Workflows
+export {
+  resolveTemplateVariables,
+  evaluateConditions,
+  validateWorkflow,
+  matchWorkflows,
+  DEFAULT_TEMPLATES,
+  TEMPLATE_VARIABLES,
+  WorkflowValidationError,
+  type WorkflowTrigger,
+  type WorkflowActionType,
+  type ConditionOperator,
+  type WorkflowCondition,
+  type EmailActionConfig,
+  type SmsActionConfig,
+  type WebhookActionConfig,
+  type StatusUpdateActionConfig,
+  type CalendarEventActionConfig,
+  type WorkflowAction,
+  type WorkflowDefinition,
+  type WorkflowContext,
+  type WorkflowLogEntry,
+} from "./workflows.js";
+
+// Webhooks
+export {
+  signWebhookPayload,
+  verifyWebhookSignature,
+  createWebhookEnvelope,
+  resolvePayloadTemplate,
+  matchWebhookSubscriptions,
+  getRetryDelay,
+  isSuccessResponse,
+  validateWebhookSubscription,
+  WebhookValidationError,
+  DEFAULT_RETRY_CONFIG,
+  WEBHOOK_TRIGGERS,
+  SIGNATURE_HEADER,
+  TIMESTAMP_HEADER,
+  DEFAULT_TOLERANCE_SECONDS,
+  type WebhookTrigger,
+  type WebhookAttendee,
+  type WebhookPayload,
+  type WebhookEnvelope,
+  type WebhookSubscription,
+  type WebhookDeliveryResult,
+  type WebhookRetryConfig,
+  type WebhookVerificationResult,
+} from "./webhooks.js";
+
+// REST API Utilities
+export {
+  createErrorResponse,
+  createSuccessResponse,
+  createPaginatedResponse,
+  generateApiKey,
+  hashApiKey,
+  verifyApiKey,
+  hasScope,
+  isKeyExpired,
+  checkRateLimit,
+  encodeCursor,
+  decodeCursor,
+  validateSlotQueryParams,
+  parseSortParam,
+  API_ERROR_CODES,
+  type ApiError,
+  type ApiErrorResponse,
+  type ApiSuccessResponse,
+  type ApiMeta,
+  type PaginatedResponse,
+  type ApiErrorCode,
+  type ApiKeyRecord,
+  type ApiKeyScope,
+  type GeneratedApiKey,
+  type RateLimitState,
+  type RateLimitResult,
+  type ValidationDetail,
+  type ValidationResult,
+} from "./api.js";
+
+// Multi-Tenancy
+export {
+  resolveEffectiveSettings,
+  getRolePermissions,
+  roleHasPermission,
+  assertOrgPermission,
+  assertTenantScope,
+  buildOrgBookingUrl,
+  parseOrgBookingPath,
+  TenantAuthorizationError,
+  GLOBAL_DEFAULTS,
+  type OrgRole,
+  type OrgMember,
+  type OrgBranding,
+  type OrgSettings,
+  type ProviderSettings,
+  type EventTypeSettings,
+  type GlobalDefaults,
+  type ResolvedSettings,
+  type OrgPermission,
+} from "./multi-tenancy.js";