@porulle/plugin-appointments 0.1.0

package/dist/services/slot-service.js

@@ -0,0 +1,91 @@
+import { eq, and, gte, lte } from "@porulle/core/drizzle";
+import { weeklyAvailability, availabilityOverrides, breaks, bookings } from "../schema.js";
+import { generateSlots } from "./slot-generation.js";
+export class SlotService {
+    db;
+    defaults;
+    constructor(db, defaults = { minNoticeMinutes: 0, maxAdvanceDays: 60 }) {
+        this.db = db;
+        this.defaults = defaults;
+    }
+    async getAvailableSlots(providerId, serviceTypeId, date, durationMinutes, bufferBeforeMinutes, bufferAfterMinutes, timezone, now) {
+        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;
+        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 = 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)));
+        const existingBookings = 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) {
+    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/dist/tasks.d.ts

@@ -0,0 +1,43 @@
+import type { TaskDefinition } from "@porulle/core";
+/**
+ * Sends appointment reminder emails (24h and 1h before).
+ * Enqueued by the afterBookingCreate hook with delayMs.
+ */
+export declare const appointmentReminderTask: TaskDefinition<{
+    bookingId: string;
+    customerEmail?: string;
+    reminderType: string;
+}>;
+/**
+ * Auto-cancels unpaid provisional bookings 24h before appointment.
+ * Enqueued by the afterBookingCreate hook with delayMs.
+ */
+export declare const appointmentAutoCancelTask: TaskDefinition<{
+    bookingId: string;
+    reason: string;
+}>;
+/**
+ * Sends cancellation notice emails.
+ */
+export declare const appointmentCancellationNoticeTask: TaskDefinition<{
+    bookingId: string;
+    customerEmail?: string;
+}>;
+/**
+ * Sends booking confirmation emails.
+ */
+export declare const appointmentConfirmationNoticeTask: TaskDefinition<{
+    bookingId: string;
+    customerEmail?: string;
+    providerId: string;
+}>;
+/**
+ * Sends no-show notification emails.
+ */
+export declare const appointmentNoShowNoticeTask: TaskDefinition<{
+    bookingId: string;
+    customerEmail?: string;
+}>;
+/** All appointment email task definitions. Register via config.jobs.tasks. */
+export declare const APPOINTMENT_EMAIL_TASKS: TaskDefinition[];
+//# sourceMappingURL=tasks.d.ts.map

package/dist/tasks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../src/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAUpD;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,cAAc,CAAC;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;CACtB,CAsBA,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,cAAc,CAAC;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB,CASA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iCAAiC,EAAE,cAAc,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAgBA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,iCAAiC,EAAE,cAAc,CAAC;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAgBA,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,2BAA2B,EAAE,cAAc,CAAC;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAgBA,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,EAM/B,cAAc,EAAE,CAAC"}

package/dist/tasks.js

@@ -0,0 +1,107 @@
+function getEmail(services) {
+    return services.email;
+}
+/**
+ * Sends appointment reminder emails (24h and 1h before).
+ * Enqueued by the afterBookingCreate hook with delayMs.
+ */
+export const appointmentReminderTask = {
+    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 = {
+    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 = {
+    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 = {
+    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 = {
+    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,
+];

package/dist/types.d.ts

@@ -0,0 +1,42 @@
+export type { PluginDb as Db } from "@porulle/core";
+export type BookingStatus = "provisional" | "confirmed" | "completed" | "cancelled" | "no_show";
+export declare const BOOKING_TRANSITIONS: Record<BookingStatus, BookingStatus[]>;
+export interface TimeSlot {
+    start: Date;
+    end: Date;
+}
+export interface DaySchedule {
+    startTime: string;
+    endTime: string;
+}
+export interface BreakPeriod {
+    startTime: string;
+    endTime: string;
+}
+export interface ExistingBooking {
+    startTime: Date;
+    endTime: Date;
+}
+export interface SlotGenerationParams {
+    date: Date;
+    schedule: DaySchedule | null;
+    durationMinutes: number;
+    bufferBeforeMinutes?: number | undefined;
+    bufferAfterMinutes?: number | undefined;
+    breaks?: BreakPeriod[] | undefined;
+    existingBookings?: ExistingBooking[] | undefined;
+    minNoticeMinutes?: number | undefined;
+    maxAdvanceDays?: number | undefined;
+    timezone: string;
+    now?: Date | undefined;
+}
+export interface AppointmentPluginOptions {
+    defaultDurationMinutes?: number;
+    defaultBufferBeforeMinutes?: number;
+    defaultBufferAfterMinutes?: number;
+    minNoticeMinutes?: number;
+    maxAdvanceDays?: number;
+    defaultTimezone?: string;
+    autoConfirmCashBookings?: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,eAAe,CAAC;AAIpD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,GAAG,SAAS,CAAC;AAEhG,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,aAAa,EAAE,aAAa,EAAE,CAMtE,CAAC;AAIF,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,WAAW,GAAG,IAAI,CAAC;IAC7B,eAAe,EAAE,MAAM,CAAC;IACxB,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,EAAE,WAAW,EAAE,GAAG,SAAS,CAAC;IACnC,gBAAgB,CAAC,EAAE,eAAe,EAAE,GAAG,SAAS,CAAC;IACjD,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACxB;AAID,MAAM,WAAW,wBAAwB;IACvC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC"}

package/dist/types.js

@@ -0,0 +1,7 @@
+export const BOOKING_TRANSITIONS = {
+    provisional: ["confirmed", "cancelled"],
+    confirmed: ["completed", "cancelled", "no_show"],
+    completed: [],
+    cancelled: [],
+    no_show: [],
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@porulle/plugin-appointments",
+  "version": "0.1.0",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    },
+    "./schema": {
+      "bun": "./src/schema.ts",
+      "import": "./dist/schema.js",
+      "require": "./dist/schema.js",
+      "types": "./src/schema.ts"
+    }
+  },
+  "scripts": {
+    "build": "rm -rf dist tsconfig.build.tsbuildinfo && tsc -p tsconfig.build.json",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint . --max-warnings 1000",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@hono/zod-openapi": "^1.2.2",
+    "@porulle/core": "workspace:*",
+    "hono": "^4.12.5"
+  },
+  "devDependencies": {
+    "@repo/eslint-config": "*",
+    "@repo/typescript-config": "*",
+    "@types/node": "^24.5.2",
+    "eslint": "^9.39.1",
+    "typescript": "5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "zod": ">=4.0.0"
+  },
+  "description": "Headless booking for service types, providers, availability, and customer appointments with slot-based scheduling.",
+  "homepage": "https://porulle-docs.vercel.app",
+  "bugs": {
+    "url": "https://github.com/asyncdotengineering/porulle/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncdotengineering/porulle.git",
+    "directory": "packages/plugins/plugin-appointments"
+  },
+  "author": "Porulle contributors"
+}

package/src/analytics-models.ts

@@ -0,0 +1,30 @@
+import type { AnalyticsModel } from "@porulle/core";
+
+export const APPOINTMENT_BOOKINGS_MODEL: AnalyticsModel = {
+  name: "AppointmentBookings",
+  table: "appointment_bookings",
+  measures: {
+    count: { type: "count" },
+    revenue: { sql: "price_cents", type: "sum" },
+    averagePrice: { sql: "price_cents", type: "avg" },
+  },
+  dimensions: {
+    id: { sql: "id", type: "string" },
+    providerId: { sql: "provider_id", type: "string" },
+    serviceTypeId: { sql: "service_type_id", type: "string" },
+    customerId: { sql: "customer_id", type: "string" },
+    status: { sql: "status", type: "string" },
+    paymentMethod: { sql: "payment_method", type: "string" },
+    startTime: { sql: "start_time", type: "time" },
+    createdAt: { sql: "created_at", type: "time" },
+  },
+  segments: {
+    completed: { sql: "status = 'completed'" },
+    cancelled: { sql: "status = 'cancelled'" },
+    noShow: { sql: "status = 'no_show'" },
+  },
+};
+
+export const APPOINTMENT_ANALYTICS_MODELS: AnalyticsModel[] = [
+  APPOINTMENT_BOOKINGS_MODEL,
+];

package/src/hooks.ts

@@ -0,0 +1,15 @@
+import type { PluginHookRegistration } from "@porulle/core";
+import type { AppointmentPluginOptions } from "./types.js";
+
+/**
+ * Appointment plugin hooks.
+ *
+ * Notification job enqueueing (reminders, cancellation notices, etc.) is handled
+ * directly by BookingService, not via hooks. The BookingService receives a
+ * JobsAdapter from the kernel's service container and enqueues jobs inline
+ * after successful operations. This avoids the dead-code problem where plugin
+ * hooks register handlers for custom keys that nobody fires.
+ */
+export function buildHooks(_options: AppointmentPluginOptions): PluginHookRegistration[] {
+  return [];
+}

package/src/index.ts

@@ -0,0 +1,74 @@
+import { defineCommercePlugin } from "@porulle/core";
+import { APPOINTMENT_ANALYTICS_MODELS } from "./analytics-models.js";
+import {
+  serviceTypes, providers, providerServices,
+  weeklyAvailability, availabilityOverrides, breaks,
+  bookings, bookingPayments,
+} from "./schema.js";
+import { ProviderService } from "./services/provider-service.js";
+import { SlotService } from "./services/slot-service.js";
+import { BookingService } from "./services/booking-service.js";
+import { buildHooks } from "./hooks.js";
+import { buildServiceRoutes } from "./routes/services.js";
+import { buildProviderRoutes } from "./routes/providers.js";
+import { buildAvailabilityRoutes } from "./routes/availability.js";
+import { buildBookingRoutes } from "./routes/bookings.js";
+import { buildMyBookingRoutes } from "./routes/my-bookings.js";
+import type { AppointmentPluginOptions, Db } from "./types.js";
+
+export type { AppointmentPluginOptions } from "./types.js";
+export { APPOINTMENT_EMAIL_TASKS } from "./tasks.js";
+
+function createServices(db: Db, options: AppointmentPluginOptions, kernelServices?: Record<string, unknown>) {
+  const provider = new ProviderService(db);
+  const slots = new SlotService(db, {
+    minNoticeMinutes: options.minNoticeMinutes ?? 0,
+    maxAdvanceDays: options.maxAdvanceDays ?? 60,
+  });
+  // Wire jobs adapter from kernel services so BookingService can enqueue notifications
+  const jobs = kernelServices?.jobs as import("@porulle/core").JobsAdapter | undefined;
+  const booking = new BookingService(db, slots, undefined, jobs);
+  return { provider, slots, booking };
+}
+
+export function appointmentPlugin(options: AppointmentPluginOptions = {}) {
+  return defineCommercePlugin({
+    id: "appointments",
+    version: "1.0.0",
+
+    permissions: [
+      { scope: "appointments:admin", description: "Full appointment administration (services, providers)" },
+      { scope: "appointments:manage", description: "Manage bookings and availability (for providers)" },
+      { scope: "appointments:book", description: "Create and manage own bookings (for customers)" },
+    ],
+
+    schema: () => ({
+      serviceTypes,
+      providers,
+      providerServices,
+      weeklyAvailability,
+      availabilityOverrides,
+      breaks,
+      bookings,
+      bookingPayments,
+    }),
+
+    hooks: () => buildHooks(options),
+
+    routes: (ctx) => {
+      const db = ctx.database.db as Db;
+      const services = db ? createServices(db, options, ctx.services) : null;
+      if (!services) return [];
+
+      return [
+        ...buildServiceRoutes(services),
+        ...buildProviderRoutes(services),
+        ...buildAvailabilityRoutes(services),
+        ...buildBookingRoutes(services),
+        ...buildMyBookingRoutes(services),
+      ];
+    },
+
+    analyticsModels: () => APPOINTMENT_ANALYTICS_MODELS,
+  });
+}

package/src/routes/availability.ts

@@ -0,0 +1,153 @@
+import { router } from "@porulle/core";
+import type { PluginRouteRegistration } from "@porulle/core";
+import { z } from "@hono/zod-openapi";
+import type { ProviderService } from "../services/provider-service.js";
+import type { SlotService } from "../services/slot-service.js";
+
+const WeeklyScheduleSchema = z.object({
+  schedules: z.array(z.object({
+    dayOfWeek: z.number().int().min(0).max(6),
+    startTime: z.string().regex(/^\d{2}:\d{2}$/).openapi({ example: "09:00" }),
+    endTime: z.string().regex(/^\d{2}:\d{2}$/).openapi({ example: "17:00" }),
+  })),
+}).openapi("SetWeeklyAvailabilityRequest");
+
+const AddBreakSchema = z.object({
+  dayOfWeek: z.number().int().min(0).max(6).optional(),
+  startTime: z.string().regex(/^\d{2}:\d{2}$/).openapi({ example: "12:00" }),
+  endTime: z.string().regex(/^\d{2}:\d{2}$/).openapi({ example: "13:00" }),
+  label: z.string().optional().openapi({ example: "Lunch" }),
+}).openapi("AddBreakRequest");
+
+const AddOverrideSchema = z.object({
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).openapi({ example: "2026-12-25" }),
+  isAvailable: z.boolean(),
+  startTime: z.string().regex(/^\d{2}:\d{2}$/).optional(),
+  endTime: z.string().regex(/^\d{2}:\d{2}$/).optional(),
+  reason: z.string().optional().openapi({ example: "Christmas Day" }),
+}).openapi("AddOverrideRequest");
+
+export function buildAvailabilityRoutes(services: {
+  provider: ProviderService;
+  slots: SlotService;
+}): PluginRouteRegistration[] {
+  const r = router("Appointments - Availability", "/appointments/availability");
+
+  // ─── Weekly Schedule ────────────────────────────────────────────────────────
+
+  r.put("/{providerId}/weekly")
+    .summary("Set weekly availability")
+    .permission("appointments:manage")
+    .input(WeeklyScheduleSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof WeeklyScheduleSchema>;
+      return services.provider.setWeeklyAvailability(params.providerId!, body.schedules);
+    });
+
+  r.get("/{providerId}/weekly")
+    .summary("Get weekly availability")
+    .handler(async ({ params }) => {
+      return services.provider.getWeeklyAvailability(params.providerId!);
+    });
+
+  // ─── Breaks ─────────────────────────────────────────────────────────────────
+
+  r.post("/{providerId}/breaks")
+    .summary("Add break")
+    .permission("appointments:manage")
+    .input(AddBreakSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof AddBreakSchema>;
+      return services.provider.addBreak(params.providerId!, body);
+    });
+
+  r.get("/{providerId}/breaks")
+    .summary("List breaks")
+    .handler(async ({ params }) => {
+      return services.provider.getBreaks(params.providerId!);
+    });
+
+  r.delete("/{providerId}/breaks/{breakId}")
+    .summary("Delete break")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const deleted = await services.provider.deleteBreak(params.breakId!);
+      if (!deleted) throw new Error("Break not found");
+      return deleted;
+    });
+
+  // ─── Overrides ──────────────────────────────────────────────────────────────
+
+  r.post("/{providerId}/overrides")
+    .summary("Add date override")
+    .permission("appointments:manage")
+    .input(AddOverrideSchema)
+    .handler(async ({ params, input }) => {
+      const body = input as z.infer<typeof AddOverrideSchema>;
+      return services.provider.addOverride(params.providerId!, body);
+    });
+
+  r.get("/{providerId}/overrides")
+    .summary("List overrides")
+    .handler(async ({ params }) => {
+      return services.provider.getOverrides(params.providerId!);
+    });
+
+  r.delete("/{providerId}/overrides/{overrideId}")
+    .summary("Delete override")
+    .permission("appointments:manage")
+    .handler(async ({ params }) => {
+      const deleted = await services.provider.deleteOverride(params.overrideId!);
+      if (!deleted) throw new Error("Override not found");
+      return deleted;
+    });
+
+  // ─── Available Slots ────────────────────────────────────────────────────────
+
+  r.get("/{providerId}/slots")
+    .summary("Get available slots for a date")
+    .query(z.object({
+      date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).openapi({ example: "2026-03-20" }),
+      serviceTypeId: z.string().uuid(),
+    }))
+    .handler(async ({ params, query }) => {
+      const providerId = params.providerId!;
+      const dateStr = query.date as string;
+      const serviceTypeId = query.serviceTypeId as string;
+
+      const provider = await services.provider.getProvider(providerId);
+      if (!provider) throw new Error("Provider not found");
+
+      const serviceType = await services.provider.getServiceType(serviceTypeId);
+      if (!serviceType) throw new Error("Service type not found");
+
+      // Check for provider-level custom duration/price
+      const providerSvcs = await services.provider.getProviderServices(providerId);
+      const link = providerSvcs.find((ps) => ps.serviceTypeId === serviceTypeId);
+
+      const durationMinutes = link?.customDurationMinutes ?? serviceType.durationMinutes;
+      const bufferBefore = serviceType.bufferBeforeMinutes;
+      const bufferAfter = serviceType.bufferAfterMinutes;
+
+      // Parse date (in provider's local context)
+      const [year, month, day] = dateStr.split("-").map(Number);
+      const date = new Date(year!, month! - 1, day!);
+
+      const slots = await services.slots.getAvailableSlots(
+        providerId,
+        serviceTypeId,
+        date,
+        durationMinutes,
+        bufferBefore,
+        bufferAfter,
+        provider.timezone,
+      );
+
+      return slots.map((s) => ({
+        start: s.start.toISOString(),
+        end: s.end.toISOString(),
+      }));
+    });
+
+  return r.routes();
+}