@porulle/plugin-appointments 0.1.0

package/src/routes/bookings.ts

@@ -0,0 +1,141 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { BookingService } from "../services/booking-service.js";
+import type { ProviderService } from "../services/provider-service.js";
+import type { BookingStatus } from "../types.js";
+
+const CreateBookingSchema = z.object({
+  providerId: z.string().uuid(),
+  serviceTypeId: z.string().uuid(),
+  startTime: z.string().datetime().openapi({ example: "2026-03-20T09:00:00Z" }),
+  customerName: z.string().min(1).openapi({ example: "John Doe" }),
+  customerEmail: z.string().email().openapi({ example: "john@example.com" }),
+  customerPhone: z.string().optional(),
+  paymentMethod: z.enum(["card", "cash", "invoice"]).openapi({ example: "cash" }),
+  notes: z.string().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateBookingRequest");
+
+const RescheduleBookingSchema = z.object({
+  newStartTime: z.string().datetime().openapi({ example: "2026-03-21T10:00:00Z" }),
+}).openapi("RescheduleBookingRequest");
+
+const CancelBookingSchema = z.object({
+  reason: z.string().optional(),
+}).openapi("CancelBookingRequest");
+
+export function buildBookingRoutes(services: {
+  booking: BookingService;
+  provider: ProviderService;
+}): PluginRouteRegistration[] {
+  const r = router("Appointments - Bookings", "/appointments/bookings");
+
+  r.get("/")
+    .summary("List bookings")
+    .permission("appointments:manage")
+    .query(z.object({
+      providerId: z.string().uuid().optional(),
+      from: z.string().datetime().optional(),
+      to: z.string().datetime().optional(),
+    }))
+    .handler(async ({ query }) => {
+      const providerId = query.providerId as string | undefined;
+      if (!providerId) throw new Error("providerId is required");
+      return services.booking.listByProvider(
+        providerId,
+        query.from ? new Date(query.from as string) : undefined,
+        query.to ? new Date(query.to as string) : undefined,
+      );
+    });
+
+  r.post("/")
+    .summary("Create booking")
+    .auth()
+    .input(CreateBookingSchema)
+    .handler(async ({ input, actor }) => {
+      const body = input as z.infer<typeof CreateBookingSchema>;
+      const result = await services.booking.create({
+        providerId: body.providerId,
+        serviceTypeId: body.serviceTypeId,
+        customerId: actor!.userId,
+        customerName: body.customerName,
+        customerEmail: body.customerEmail,
+        customerPhone: body.customerPhone,
+        startTime: new Date(body.startTime),
+        paymentMethod: body.paymentMethod,
+        notes: body.notes,
+        metadata: body.metadata,
+      });
+
+      if (!result.ok) {
+        const status = result.code === "CONFLICT" ? 409 : result.code === "NOT_FOUND" ? 404 : 400;
+        throw Object.assign(new Error(result.error), { statusCode: status });
+      }
+
+      return {
+        booking: result.booking,
+        ...(result.paymentIntent ? { paymentIntent: result.paymentIntent } : {}),
+      };
+    });
+
+  r.get("/{id}")
+    .summary("Get booking")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const booking = await services.booking.getById(params.id!);
+      if (!booking) throw new Error("Booking not found");
+      return booking;
+    });
+
+  r.post("/{id}/confirm")
+    .summary("Confirm booking")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const result = await services.booking.changeStatus(params.id!, "confirmed");
+      if (!result.ok) throw new Error(result.error);
+      return result.booking;
+    });
+
+  r.post("/{id}/complete")
+    .summary("Complete appointment")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const result = await services.booking.complete(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.booking;
+    });
+
+  r.post("/{id}/no-show")
+    .summary("Mark as no-show")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const result = await services.booking.markNoShow(params.id!);
+      if (!result.ok) throw new Error(result.error);
+      return result.booking;
+    });
+
+  r.post("/{id}/cancel")
+    .summary("Cancel booking")
+    .auth()
+    .input(CancelBookingSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof CancelBookingSchema>;
+      const result = await services.booking.cancel(params.id!, body.reason);
+      if (!result.ok) throw new Error(result.error);
+      return { booking: result.booking, refunded: result.refunded };
+    });
+
+  r.post("/{id}/reschedule")
+    .summary("Reschedule booking")
+    .auth()
+    .input(RescheduleBookingSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof RescheduleBookingSchema>;
+      const result = await services.booking.reschedule(params.id!, new Date(body.newStartTime));
+      if (!result.ok) throw new Error(result.error);
+      return { oldBooking: result.oldBooking, newBooking: result.newBooking };
+    });
+
+  return r.routes();
+}

package/src/routes/my-bookings.ts

@@ -0,0 +1,28 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import type { BookingService } from "../services/booking-service.js";
+
+export function buildMyBookingRoutes(services: {
+  booking: BookingService;
+}): PluginRouteRegistration[] {
+  const r = router("Appointments - My Bookings", "/appointments/my-bookings");
+
+  r.get("/")
+    .summary("List my bookings")
+    .auth()
+    .handler(async ({ actor }) => {
+      return services.booking.listByCustomer(actor!.userId);
+    });
+
+  r.get("/{id}")
+    .summary("Get my booking")
+    .auth()
+    .handler(async ({ params, actor }) => {
+      const booking = await services.booking.getById(params.id!);
+      if (!booking) throw new Error("Booking not found");
+      if (booking.customerId !== actor!.userId) throw new Error("Booking not found");
+      return booking;
+    });
+
+  return r.routes();
+}

package/src/routes/providers.ts

@@ -0,0 +1,97 @@
+import { router, resolveOrgId } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ProviderService } from "../services/provider-service.js";
+import { stripUndefined } from "./util.js";
+
+const CreateProviderSchema = z.object({
+  name: z.string().min(1).openapi({ example: "Jane Smith" }),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  timezone: z.string().optional().openapi({ example: "Asia/Colombo" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateProviderRequest");
+
+const UpdateProviderSchema = z.object({
+  name: z.string().optional(),
+  email: z.string().email().optional(),
+  phone: z.string().optional(),
+  timezone: z.string().optional(),
+  isActive: z.boolean().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("UpdateProviderRequest");
+
+export function buildProviderRoutes(services: {
+  provider: ProviderService;
+}): PluginRouteRegistration[] {
+  const r = router("Appointments - Providers", "/appointments/providers");
+
+  r.get("/")
+    .summary("List providers")
+    .handler(async () => {
+      return services.provider.listProviders();
+    });
+
+  r.post("/")
+    .summary("Create provider")
+    .permission("appointments:admin")
+    .input(CreateProviderSchema)
+    .handler(async ({ input, actor }) => {
+      const body = input as z.infer<typeof CreateProviderSchema>;
+      return services.provider.createProvider(resolveOrgId(actor), stripUndefined(body));
+    });
+
+  r.get("/{id}")
+    .summary("Get provider")
+    .handler(async ({ params }) => {
+      const provider = await services.provider.getProvider(params.id!);
+      if (!provider) throw new Error("Provider not found");
+      return provider;
+    });
+
+  r.patch("/{id}")
+    .summary("Update provider")
+    .permission("appointments:admin")
+    .input(UpdateProviderSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UpdateProviderSchema>;
+      const updated = await services.provider.updateProvider(params.id!, stripUndefined(body));
+      if (!updated) throw new Error("Provider not found");
+      return updated;
+    });
+
+  r.delete("/{id}")
+    .summary("Delete provider")
+    .permission("appointments:admin")
+    .handler(async ({ params }) => {
+      const deleted = await services.provider.deleteProvider(params.id!);
+      if (!deleted) throw new Error("Provider not found");
+      return deleted;
+    });
+
+  // ─── Provider ↔ Service Links ───────────────────────────────────────────────
+
+  r.post("/{id}/services")
+    .summary("Link service type to provider")
+    .permission("appointments:admin")
+    .input(z.object({
+      serviceTypeId: z.string().uuid().openapi({ example: "uuid" }),
+      customDurationMinutes: z.number().int().min(5).optional(),
+      customPriceCents: z.number().int().min(0).optional(),
+    }).openapi("LinkProviderServiceRequest"))
+    .handler(async ({ params, input }) => {
+      const body = input as { serviceTypeId: string; customDurationMinutes?: number; customPriceCents?: number };
+      return services.provider.linkServiceType(params.id!, body.serviceTypeId, stripUndefined({
+        customDurationMinutes: body.customDurationMinutes,
+        customPriceCents: body.customPriceCents,
+      }));
+    });
+
+  r.get("/{id}/services")
+    .summary("List provider's service types")
+    .handler(async ({ params }) => {
+      return services.provider.getProviderServices(params.id!);
+    });
+
+  return r.routes();
+}

package/src/routes/services.ts

@@ -0,0 +1,78 @@
+import { router, resolveOrgId } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ProviderService } from "../services/provider-service.js";
+import { stripUndefined } from "./util.js";
+
+const CreateServiceTypeSchema = z.object({
+  name: z.string().min(1).openapi({ example: "Haircut" }),
+  slug: z.string().min(1).openapi({ example: "haircut" }),
+  description: z.string().optional(),
+  durationMinutes: z.number().int().min(5).optional().openapi({ example: 30 }),
+  priceCents: z.number().int().min(0).optional().openapi({ example: 3000 }),
+  currency: z.string().optional().openapi({ example: "USD" }),
+  bufferBeforeMinutes: z.number().int().min(0).optional(),
+  bufferAfterMinutes: z.number().int().min(0).optional(),
+}).openapi("CreateServiceTypeRequest");
+
+const UpdateServiceTypeSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  durationMinutes: z.number().int().min(5).optional(),
+  priceCents: z.number().int().min(0).optional(),
+  currency: z.string().optional(),
+  bufferBeforeMinutes: z.number().int().min(0).optional(),
+  bufferAfterMinutes: z.number().int().min(0).optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateServiceTypeRequest");
+
+export function buildServiceRoutes(services: {
+  provider: ProviderService;
+}): PluginRouteRegistration[] {
+  const r = router("Appointments - Services", "/appointments/services");
+
+  r.get("/")
+    .summary("List service types")
+    .handler(async () => {
+      return services.provider.listServiceTypes();
+    });
+
+  r.post("/")
+    .summary("Create service type")
+    .permission("appointments:admin")
+    .input(CreateServiceTypeSchema)
+    .handler(async ({ input, actor }) => {
+      const body = input as z.infer<typeof CreateServiceTypeSchema>;
+      return services.provider.createServiceType(resolveOrgId(actor), stripUndefined(body));
+    });
+
+  r.get("/{id}")
+    .summary("Get service type")
+    .handler(async ({ params }) => {
+      const svc = await services.provider.getServiceType(params.id!);
+      if (!svc) throw new Error("Service type not found");
+      return svc;
+    });
+
+  r.patch("/{id}")
+    .summary("Update service type")
+    .permission("appointments:admin")
+    .input(UpdateServiceTypeSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof UpdateServiceTypeSchema>;
+      const updated = await services.provider.updateServiceType(params.id!, stripUndefined(body));
+      if (!updated) throw new Error("Service type not found");
+      return updated;
+    });
+
+  r.delete("/{id}")
+    .summary("Delete service type")
+    .permission("appointments:admin")
+    .handler(async ({ params }) => {
+      const deleted = await services.provider.deleteServiceType(params.id!);
+      if (!deleted) throw new Error("Service type not found");
+      return deleted;
+    });
+
+  return r.routes();
+}

package/src/routes/util.ts

@@ -0,0 +1,11 @@
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function stripUndefined<T>(obj: T): T extends Record<string, any> ? { [K in keyof T]: Exclude<T[K], undefined> } : T {
+  if (obj == null || typeof obj !== "object") return obj as never;
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+    if (value !== undefined) {
+      result[key] = value;
+    }
+  }
+  return result as never;
+}

package/src/schema.ts

@@ -0,0 +1,144 @@
+import { boolean, integer, jsonb, pgTable, text, timestamp, uuid, index, uniqueIndex } from "@porulle/core/drizzle";
+
+// ─── Service Types ──────────────────────────────────────────────────────────
+
+export const serviceTypes = pgTable("appointment_service_types", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  name: text("name").notNull(),
+  slug: text("slug").notNull(),
+  description: text("description"),
+  durationMinutes: integer("duration_minutes").notNull().default(30),
+  priceCents: integer("price_cents").notNull().default(0),
+  currency: text("currency").notNull().default("USD"),
+  mode: text("mode").notNull().default("in_person"), // in_person | online | hybrid
+  bufferBeforeMinutes: integer("buffer_before_minutes").notNull().default(0),
+  bufferAfterMinutes: integer("buffer_after_minutes").notNull().default(0),
+  maxAdvanceDays: integer("max_advance_days").notNull().default(60),
+  minNoticeMins: integer("min_notice_mins").notNull().default(60),
+  isActive: boolean("is_active").notNull().default(true),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgSlugUnique: uniqueIndex("apt_service_types_org_slug_unique").on(table.organizationId, table.slug),
+  orgIdx: index("idx_apt_service_types_org").on(table.organizationId),
+  slugIdx: index("idx_apt_service_types_slug").on(table.slug),
+  activeIdx: index("idx_apt_service_types_active").on(table.isActive),
+}));
+
+// ─── Providers ──────────────────────────────────────────────────────────────
+
+export const providers = pgTable("appointment_providers", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  organizationId: text("organization_id").notNull(),
+  userId: text("user_id"), // Better Auth user ID (nullable for admin-created providers)
+  name: text("name").notNull(),
+  bio: text("bio"),
+  email: text("email"),
+  phone: text("phone"),
+  timezone: text("timezone").notNull().default("UTC"),
+  isActive: boolean("is_active").notNull().default(true),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  orgIdx: index("idx_apt_providers_org").on(table.organizationId),
+  activeIdx: index("idx_apt_providers_active").on(table.isActive),
+}));
+
+// ─── Provider–ServiceType Link ──────────────────────────────────────────────
+
+export const providerServices = pgTable("appointment_provider_services", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  providerId: uuid("provider_id").notNull(),
+  serviceTypeId: uuid("service_type_id").notNull(),
+  customDurationMinutes: integer("custom_duration_minutes"),
+  customPriceCents: integer("custom_price_cents"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  providerServiceIdx: uniqueIndex("idx_provider_service").on(table.providerId, table.serviceTypeId),
+}));
+
+// ─── Weekly Availability ────────────────────────────────────────────────────
+
+export const weeklyAvailability = pgTable("appointment_weekly_availability", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  providerId: uuid("provider_id").notNull(),
+  dayOfWeek: integer("day_of_week").notNull(), // 0 = Sunday, 6 = Saturday
+  startTime: text("start_time").notNull(), // "09:00" (HH:mm in provider's timezone)
+  endTime: text("end_time").notNull(),     // "17:00"
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  providerDayIdx: index("idx_weekly_provider_day").on(table.providerId, table.dayOfWeek),
+}));
+
+// ─── Availability Overrides (date-level) ────────────────────────────────────
+
+export const availabilityOverrides = pgTable("appointment_availability_overrides", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  providerId: uuid("provider_id").notNull(),
+  date: text("date").notNull(), // "2026-03-25" (YYYY-MM-DD)
+  isAvailable: boolean("is_available").notNull().default(true),
+  startTime: text("start_time"), // null if isAvailable = false (day off)
+  endTime: text("end_time"),
+  reason: text("reason"),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  providerDateIdx: uniqueIndex("idx_override_provider_date").on(table.providerId, table.date),
+}));
+
+// ─── Breaks ─────────────────────────────────────────────────────────────────
+
+export const breaks = pgTable("appointment_breaks", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  providerId: uuid("provider_id").notNull(),
+  dayOfWeek: integer("day_of_week"), // null = every day
+  startTime: text("start_time").notNull(), // "12:00"
+  endTime: text("end_time").notNull(),     // "13:00"
+  label: text("label"), // "Lunch"
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+// ─── Bookings ───────────────────────────────────────────────────────────────
+
+export const bookings = pgTable("appointment_bookings", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  providerId: uuid("provider_id").notNull(),
+  serviceTypeId: uuid("service_type_id").notNull(),
+  customerId: text("customer_id").notNull(),
+  customerName: text("customer_name").notNull(),
+  customerEmail: text("customer_email").notNull(),
+  customerPhone: text("customer_phone"),
+  startTime: timestamp("start_time", { withTimezone: true }).notNull(),
+  endTime: timestamp("end_time", { withTimezone: true }).notNull(),
+  status: text("status").notNull().default("provisional"),
+  // provisional → confirmed → completed | cancelled | no_show
+  paymentMethod: text("payment_method").notNull(), // "card" | "cash" | "invoice"
+  notes: text("notes"),
+  cancellationReason: text("cancellation_reason"),
+  rescheduledFromId: uuid("rescheduled_from_id"),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+  updatedAt: timestamp("updated_at", { withTimezone: true }).defaultNow().notNull(),
+}, (table) => ({
+  providerTimeIdx: index("idx_apt_bookings_provider_time").on(table.providerId, table.startTime),
+  customerIdx: index("idx_apt_bookings_customer").on(table.customerId),
+  statusIdx: index("idx_apt_bookings_status").on(table.status),
+  startTimeIdx: index("idx_apt_bookings_start_time").on(table.startTime),
+}));
+
+// ─── Booking Payments ───────────────────────────────────────────────────────
+
+export const bookingPayments = pgTable("appointment_booking_payments", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  bookingId: uuid("booking_id").notNull().unique(),
+  amountCents: integer("amount_cents").notNull(),
+  currency: text("currency").notNull(),
+  status: text("status").notNull().default("pending"), // pending | paid | refunded | failed
+  paymentIntentId: text("payment_intent_id"),
+  paidAt: timestamp("paid_at", { withTimezone: true }),
+  refundedAt: timestamp("refunded_at", { withTimezone: true }),
+  metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});