diff --git a/docs/notifications.md b/docs/notifications.md new file mode 100644 index 0000000..f6bca95 --- /dev/null +++ b/docs/notifications.md @@ -0,0 +1,154 @@ +# 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 + +See `src/services/notifications/types.ts`'s `PREFERENCE_CONTROLLED_TYPES` +— this is the single source of truth; everything not listed there is +**required** (always sent on every channel it has a valid target for, no +toggle anywhere). Currently: + +- **Customer-facing**: only `BOOKING_REMINDER` is optional. Everything + else (confirmations, changes, cancellations, loyalty) always notifies + the customer — 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. + +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). A preference with +no saved row yet defaults to **on** — turning something off is always an +explicit, deliberate action. + +--- + +## Customer-facing + +| Type | Fires when | Default subject | +|---|---|---| +| `BOOKING_CONFIRMED` | A new booking is created and doesn't need approval | "Booking confirmed" | +| `BOOKING_PENDING_APPROVAL` | A new booking is created but the business requires approval first | "Booking request received" | +| `BOOKING_APPROVED` | An owner approves a pending booking | "Booking approved" | +| `BOOKING_RESCHEDULED` | The appointment's time changes (including an owner reassigning staff, which also triggers a reschedule) | "Booking rescheduled" | +| `BOOKING_CANCELLED` | The appointment is cancelled, by anyone | "Booking cancelled" (carries a "This was a late cancellation." note when applicable — not a separate type) | +| `BOOKING_BARBER_CHANGED` | An owner reassigns the appointment to a different staff member | "Your barber has changed" | +| `BOOKING_COMPLETED` | The appointment is marked completed | "Thanks for visiting" | +| `BOOKING_REMINDER` *(optional)* | 24 hours and 2 hours before a confirmed appointment (each is its own send) | "Upcoming appointment reminder" | +| `LOYALTY_STAMP_ADDED` | A loyalty stamp is added to their card | "You've earned a loyalty stamp" | +| `LOYALTY_REWARD_EARNED` | Their stamp count reaches the reward threshold | "You've earned a reward" | +| `LOYALTY_REWARD_EXPIRING` | A daily sweep finds their reward is nearing its expiry date (fires once per calendar day it's still found, not once total) | "Your reward is expiring soon" | +| `LOYALTY_REWARD_REDEEMED` | Their reward is applied to an appointment | "Reward applied" | + +## Staff-facing + +| Type | Fires when | Default subject | +|---|---|---| +| `STAFF_NEW_APPOINTMENT` *(optional)* | A new appointment is booked with them | "New appointment" | +| `STAFF_APPOINTMENT_RESCHEDULED` *(optional)* | One of their appointments is rescheduled | "Appointment rescheduled" | +| `STAFF_APPOINTMENT_CANCELLED` *(optional)* | One of their appointments is cancelled | "Appointment cancelled" | +| `STAFF_APPOINTMENT_REMINDER` *(optional)* | 24 hours and 2 hours before their appointment | "Upcoming appointment reminder" | +| `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" | +| `STAFF_INVITATION_RECEIVED` *(optional)* | They're added as a new team member | "You've been invited to join `{business}`" | +| `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 | — | + +## 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 | +|---|---|---| +| `OWNER_NEW_BOOKING` *(optional)* | A new booking is made anywhere in the business | "New booking" | +| `OWNER_BOOKING_CANCELLED` *(optional)* | A booking is cancelled anywhere in the business | "Booking cancelled" | +| `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" | +| `OWNER_STAFF_INVITATION_ACCEPTED` *(optional)* | An invited staff member verifies their email and joins | "Invitation accepted" | +| `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" | + +--- + +## 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**: `PREFERENCE_CONTROLLED_TYPES`, same file. +- **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`. diff --git a/src/app/(staff)/staff/appointments/[id]/page.tsx b/src/app/(staff)/staff/appointments/[id]/page.tsx index 1a60a67..ec725ba 100644 --- a/src/app/(staff)/staff/appointments/[id]/page.tsx +++ b/src/app/(staff)/staff/appointments/[id]/page.tsx @@ -258,20 +258,20 @@ export default async function StaffAppointmentDetailsPage({
{RESCHEDULABLE.has(appointment.status) && ( Reschedule )} {appointment.status === "COMPLETED" && ( - + )}
diff --git a/src/features/staff/components/appointment-status-actions.tsx b/src/features/staff/components/appointment-status-actions.tsx index 482808c..2c06c2e 100644 --- a/src/features/staff/components/appointment-status-actions.tsx +++ b/src/features/staff/components/appointment-status-actions.tsx @@ -117,6 +117,15 @@ export function AppointmentStatusActions({ ? "Mark as No-Show?" : "Cancel Appointment?"; + // "wrap" buttons are `flex-1` (not intrinsically sized) so a row of + // two or three ends up as an even, aligned segmented row instead of + // packing left at whatever width each label's text happens to need — + // that's what made "Check In"/"Mark No-Show"/"Cancel" (very different + // label lengths) look lopsided together. `min-w` keeps a button from + // getting squeezed illegibly thin before the row wraps. + const buttonSize = layout === "stack" ? undefined : "sm"; + const buttonClassName = layout === "stack" ? "w-full" : "min-w-[110px] flex-1"; + return (
{error && !confirmKind && ( @@ -127,8 +136,8 @@ export function AppointmentStatusActions({
{status === "PENDING" && ( )} {status === "IN_PROGRESS" && ( - )} {status === "CONFIRMED" && ( - )} {(status === "PENDING" || status === "CONFIRMED" || status === "CHECKED_IN") && ( - )}