NextChair/docs/notifications.md

Notifications reference

A living reference for every notification NextChair sends — what it is, who gets it, on which channels, and whether the recipient can turn it off. Unlike the other files in docs/ (dated phase summaries), this one is meant to be kept current as notifications change; if you add, remove, or retarget one, update this file in the same change.

Two separate mechanisms

Most of what's on this page goes through the queued notification system: an event happens, a Notification + one NotificationDelivery row per applicable channel is created immediately, but the actual EMAIL/PUSH send only happens when the background processor runs (see src/services/notifications/reminder-worker.ts, triggered by POST /api/cron/process-notifications — see the root README's "Notification delivery" section for how that's scheduled on a real deployment). IN_APP deliveries have no send step; they're just a database row the notification bell/centre reads directly.

One-time codes (below, in their own section) are different — they're sent synchronously, the moment they're requested, with no queue at all.

Either way, nothing actually reaches an inbox unless that business has EMAIL_PROVIDER=brevo configured (Manager's Settings → Email, or a business's own .env) — with the default EMAIL_PROVIDER=console, every send just logs to the container's console instead.

Channels

• EMAIL — sent only if the recipient has a resolvable email address (a registered user's User.email, or a guest customer's CustomerProfile.email).
• PUSH — sent only if the recipient has at least one active (not revoked) browser push subscription.
• IN_APP — only meaningful for a recipient with a real account (recipientUserId set) — a guest customer never gets one, since they have nothing to sign into.

Preferences — who can turn what off, and what's on by default

See src/services/notifications/types.ts's PREFERENCE_CONTROLLED_TYPES — this is the single source of truth for which types have a toggle at all; everything not listed there is required (always sent on every channel it has a valid target for, no toggle anywhere — see "Fixed no-email types" below for a separate, smaller mechanism that trims one channel off a handful of these without making them toggleable).

• Customer-facing: only BOOKING_REMINDER is optional (and only controls the customer reminder — see "Reminder timing"). Everything else (confirmations, changes, cancellations, loyalty) always notifies the customer on every resolvable channel — not finding out your appointment was cancelled is a real risk, not just noise.
• Staff- and owner-facing: every type is optional. The owner of a business is commonly also its only barber — one StaffProfile, one account — so without this, a single new booking would unconditionally notify that one person twice (STAFF_NEW_APPOINTMENT + OWNER_NEW_BOOKING) on every channel, including in-app, with no way to quiet either copy. (Cross-role dedup, below, now also prevents the literal duplicate even when both happen to be enabled.)

Toggles live at Settings → Notifications — customers see one "Appointment reminders" group; staff see their own six groups, plus five more owner-only groups if they hold VIEW_REPORTING (i.e. are actually an owner — see src/services/notifications/recipients.ts's getOwnerUserIds, which checks the same permission).

Defaults: types.ts's defaultPreferenceIsEnabled(type) is the single source of truth for what a toggle shows/does before anyone has ever saved a preference row for it — used both by the actual send decision (notification.service.ts's isChannelEnabled) and by the Settings pages themselves, so a toggle's initial on/off state always matches what will actually happen. Once a user explicitly saves a preference, that stored value always wins, in either direction — this function only governs the "nobody has touched this yet" fallback.

Most staff/owner types default to on. These default to off (on every channel) instead — a solo owner-barber otherwise gets emailed/pushed/in-app'd for everything the moment they sign in, with no gentle on-ramp:

Type	Why
STAFF_NEW_APPOINTMENT	Noisy for a busy barber; STAFF_APPOINTMENT_CANCELLED (which stays on) is the one that actually needs acting on.
STAFF_APPOINTMENT_RESCHEDULED	Same reasoning.
OWNER_NEW_BOOKING	Same as STAFF_NEW_APPOINTMENT, from the owner's side.
OWNER_NO_SHOW	The barber who marked it already knows — there's no staff-facing equivalent by design.

Defaults can also differ per channel, not just per type (DEFAULT_DISABLED_CHANNELS in types.ts). Currently one: STAFF_APPOINTMENT_REMINDER is on for push and in-app but off for email — a barber gets a nudge on their phone two hours out without a second email for something that's about to happen anyway. Email is opt-in under Settings → Notifications.

Fixed no-email types

A few types are EMAIL never, always, and unconditionally — not a default that can be toggled back on, because the type either has no preference toggle at all or (for BOOKING_BARBER_CHANGED) the decision is per-booking context a stored preference can't express. This is NotifyParams.skipEmail in notification.service.ts — a single boolean the caller passes, checked in resolveChannels()'s EMAIL branch independently of the preference system. PUSH/IN_APP are unaffected in every case below.

Type	Condition
BOOKING_COMPLETED	Always — a "thanks for visiting" email after every single cut was more noise than value.
LOYALTY_STAMP_ADDED	Always — a stamp is added on nearly every visit.
LOYALTY_REWARD_REDEEMED	Always — the customer is present when a reward is redeemed; an email receipt afterward added little.
BOOKING_BARBER_CHANGED	Only when the customer originally booked without picking a specific staff member ("any available barber" — see Appointment.staffSelectedByCustomer) and hasn't been reassigned before. Someone who booked "any available" is less likely to care who they end up with; someone who picked this barber specifically still gets emailed.

Cross-role deduplication

A person who holds two roles for the same booking (most commonly a solo owner-barber: one User, one StaffProfile, and a role with VIEW_REPORTING) can be the target of two equivalent notifications for one underlying event — e.g. a new booking fires both STAFF_NEW_APPOINTMENT (they're the assigned staff) and OWNER_NEW_BOOKING (they're also an owner). Since both resolve to the identical recipientUserId, notification.service.ts's notify() detects this and suppresses the less-specific one — on every channel, not just email — rather than relying on the person to manually mute one side.

EQUIVALENCE_GROUPS in that file lists which types are considered the same underlying event, and their relative priority:

Group	Types (higher priority first)
new_appointment	STAFF_NEW_APPOINTMENT > OWNER_NEW_BOOKING
appointment_cancelled	STAFF_APPOINTMENT_CANCELLED > OWNER_BOOKING_CANCELLED

When an equivalent, higher-or-equal-priority notification already exists for the same (businessId, appointmentId, recipientUserId), the new one is still created as a Notification row (audit trail, keeps idempotencyKey semantics intact) but with zero deliveries — nothing sends on any channel. This relies on call order: every real call site (booking-notifications.ts) already notifies the STAFF_* type before looping the OWNER_* type for the same event, so the more specific one is always created first. Only types explicitly listed in EQUIVALENCE_GROUPS ever participate — e.g. OWNER_NO_SHOW has no staff equivalent and is never touched by this, and any future owner-only actionable type (e.g. "approve this booking") would likewise stay untouched simply by not being added to the map. Unrelated events for the same appointment (a confirmation, then later a cancellation) are never conflated — they're different types in different groups, or no group at all.

Reminder timing

src/services/scheduling/reminder-scheduling.ts schedules reminders at fixed offsets before the appointment, independently for the customer and the assigned staff member:

• Customer (BOOKING_REMINDER): one reminder, 24 hours before. If the booking was made too late for that (a same-day or next-morning booking), they get one 2 hours before instead — never both, and never nothing, unless the appointment is under 2 hours away.
• Staff (STAFF_APPOINTMENT_REMINDER): one reminder, 2 hours before. No 24-hour one. Push and in-app on by default, email opt-in — see "Defaults" above.
• Owner: no reminders.

A reminder time that's already in the past when the booking is made/approved is never scheduled retroactively.

In-app reminders are held back until they're due. Every scheduled notification's in-app copy is created SCHEDULED, not SENT, so it stays out of the notification bell and unread count until the background processor releases it at the reminder time (releaseDueInAppReminders in reminder-worker.ts). Cancelling or rescheduling cancels it along with the email/push copies, so a stale reminder never appears.

Stale-send guard. Before sending (or releasing) a reminder, the worker checks the appointment is still CONFIRMED and hasn't started; if not, the delivery is marked CANCELLED (not FAILED, so it doesn't count toward the owner's delivery-failure alert). This is a backstop for the processor being down long enough that a "24 hours before" reminder would otherwise arrive after the appointment.

Guest links. A guest has no account, so every customer-facing link in their emails carries an access token (customerAppointmentLink in guest-access.service.ts). The booking-time token is random and only its hash is stored, so later emails use a token derived from the appointment id and AUTH_SECRET instead; validateGuestAccessToken accepts either, and revoking a guest appointment's access kills both.

---

Customer-facing

Type	Fires when	Default subject	Email
BOOKING_CONFIRMED	A new booking is created and doesn't need approval	"Booking confirmed"	Always
BOOKING_PENDING_APPROVAL	A new booking is created but the business requires approval first	"Booking request received"	Always
BOOKING_APPROVED	An owner approves a pending booking	"Booking approved"	Always
BOOKING_RESCHEDULED	The appointment's time changes (including an owner reassigning staff, which also triggers a reschedule)	"Booking rescheduled"	Always
BOOKING_CANCELLED	The appointment is cancelled, by anyone	"Booking cancelled" (carries a "This was a late cancellation." note when applicable — not a separate type)	Always
BOOKING_BARBER_CHANGED	An owner reassigns the appointment to a different staff member	"Your barber has changed"	Only if the customer originally picked a specific staff member — see "Fixed no-email types"
BOOKING_COMPLETED	The appointment is marked completed	"Thanks for visiting"	Never
BOOKING_REMINDER (optional)	24 hours before a confirmed appointment (2 hours before if booked with less than 24 hours' notice)	"Upcoming appointment reminder"	Default on
LOYALTY_STAMP_ADDED	A loyalty stamp is added to their card	"You've earned a loyalty stamp"	Never
LOYALTY_REWARD_EARNED	Their stamp count reaches the reward threshold	"You've earned a reward"	Always
LOYALTY_REWARD_EXPIRING	A reward's expiry is within 7 days — sent once when it enters that window, and once more when it's down to its last day (two at most per reward)	"Your reward is expiring soon"	Always
LOYALTY_REWARD_REDEEMED	Their reward is applied to an appointment	"Reward applied"	Never

Staff-facing

Type	Fires when	Default subject	Default
STAFF_NEW_APPOINTMENT (optional)	A new appointment is booked with them	"New appointment"	Off
STAFF_APPOINTMENT_RESCHEDULED (optional)	One of their appointments is rescheduled	"Appointment rescheduled"	Off
STAFF_APPOINTMENT_CANCELLED (optional)	One of their appointments is cancelled	"Appointment cancelled"	On
STAFF_APPOINTMENT_REMINDER (optional)	2 hours before their appointment	"Upcoming appointment reminder"	In-app and push on, email off
STAFF_SCHEDULE_CHANGED (optional)	An owner edits their working hours/breaks/time-off on their behalf — never fires from the self-service editors, since notifying someone about their own edit would just be noise	"Your schedule was updated"	On
STAFF_INVITATION_RECEIVED (optional)	They're added as a new team member	"You've been invited to join {business}"	On
STAFF_APPOINTMENT_CHECKED_IN	Defined in the schema, has a recipient assigned — but nothing in the codebase currently triggers it. Preference-controlled for forward-compatibility, but has no toggle in the UI since there's nothing to preview. Left dormant on purpose	—	—

Owner-facing

Sent to every active staff member whose role holds VIEW_REPORTING — that can be more than one person; there's no single "the owner" column anywhere in the schema.

Type	Fires when	Default subject	Default
OWNER_NEW_BOOKING (optional)	A new booking is made anywhere in the business	"New booking"	Off
OWNER_BOOKING_CANCELLED (optional)	A booking is cancelled anywhere in the business	"Booking cancelled"	On
OWNER_NO_SHOW (optional)	A customer is marked as a no-show (staff-facing equivalent doesn't exist — the barber who marked it already knows)	"No-show recorded"	Off
OWNER_STAFF_INVITATION_ACCEPTED (optional)	An invited staff member verifies their email and joins	"Invitation accepted"	On
OWNER_REPEATED_DELIVERY_FAILURE (optional)	The background processor itself detects repeated delivery failures that day — a self-monitoring alert, not triggered by a domain event. At most once per business per day	"Some notifications failed to send"	On

---

One-time codes (not part of the system above)

Sent immediately and synchronously — see src/lib/auth/otp.service.ts. Not queued, not preference-controlled, no in-app record.

Purpose	Sent to	When
login	The email being signed in with	Every sign-in attempt
register	The email registering	Customer self-registration
staff-invite	The invited email	Accepting a staff invitation (/invite/accept)
install	The administrator's email	The install wizard's administrator-verification step
email-change	The new email address	A signed-in user changing their account email

Platform-level (Manager, not tied to any business)

• Settings → Email → Send Test Email — a manual, one-off admin action in the Manager app, unrelated to any business's own notification queue. See manager/src/lib/test-email.ts.

---

Where things live, if you're changing any of this

• What exists / who it's for: prisma/schema.prisma's NotificationType enum, and RECIPIENT_KIND in src/services/notifications/types.ts.
• Whether it's optional, and its default: PREFERENCE_CONTROLLED_TYPES and defaultPreferenceIsEnabled(), same file.
• Fixed no-email types: NotifyParams.skipEmail in notification.service.ts, set at the relevant call site in booking-notifications.ts/loyalty-notifications.ts.
• Cross-role dedup: EQUIVALENCE_GROUPS in notification.service.ts.
• Whether the customer picked a specific barber originally: Appointment.staffSelectedByCustomer, set once at booking creation in booking.service.ts's createBooking(), read at reassignment time in src/features/owner/actions/appointments.ts.
• When it actually fires: src/services/scheduling/booking-notifications.ts, reminder-scheduling.ts, src/services/loyalty/loyalty-notifications.ts, src/services/staff/staff-notifications.ts, src/services/staff/staff-invitation.service.ts, and reminder-worker.ts (for the self-monitoring alert).
• Channel resolution / preference enforcement: src/services/notifications/notification.service.ts's resolveChannels/isChannelEnabled.
• The actual send: src/services/notifications/providers/ (Brevo/ console email, web-push/console push) plus reminder-worker.ts, which processes the queue.
• Settings UI: src/features/staff/components/notification-preferences-form.tsx (shared by customer/staff/owner), wired up per audience in src/app/(customer)/settings/notifications/page.tsx and src/app/(staff)/staff/settings/notifications/page.tsx.
• Guest-to-account merge (what happens to a guest's history when they later sign up): src/services/customer/guest-merge.service.ts, called from authorizeCredentials (OTP sign-in), src/auth.ts's Google signIn event, and createCustomerByStaff.