Notifications

SMACKZ delivers push notifications to customers and restaurant staff via Firebase Cloud Messaging (FCM). All triggers, recipients, and payloads are catalogued in yum/docs/NOTIFICATIONS.md (mobile-developer guide) and yum/docs/NOTIFICATION_COVERAGE.md (implementation status audit).

Notification Types

Notifications cover the full order lifecycle plus payment, delivery, inventory, POS, and loyalty events.

Type	Trigger	Recipient	FCM type
New Order	Customer places order	Restaurant staff	new_order
Order Confirmed	Checkout completes	Customer	order_confirmed
Status Update	Staff changes order status	Customer	order_status_update
Customer Cancelled	Customer cancels	Restaurant staff	order_cancelled_by_customer
Payment Succeeded	Stripe webhook	Customer	payment_succeeded
Payment Failed	Stripe webhook	Customer	payment_failed
Refund Processed	Owner processes refund	Customer	refund_processed
Order Expired	Reservation timeout	Customer	order_expired
Cart Item Expired	Stock reservation timeout	Customer	cart_item_expired
Driver Assigned	DoorDash dasher_confirmed	Customer	driver_assigned
Order Picked Up	DoorDash dasher_picked_up	Customer	driver_pickup
Driver En Route	DoorDash dasher_enroute_to_dropoff	Customer	driver_en_route
Delivery Completed	DoorDash delivered	Customer	delivery_completed
Delivery Creation Failed	DoorDash API failure	Restaurant staff	delivery_creation_failed
Item Out of Stock	Stock hits 0 during validation	Restaurant staff	item_out_of_stock
Low Stock Warning	Stock below 20% threshold	Restaurant staff	low_stock_warning
POS Sync Failed	Clover/Square sync failure	Restaurant staff	pos_sync_failed
Loyalty Points Earned	Payment confirmed	Customer	loyalty_points_earned
Loyalty Points Reversed	Refund processed	Customer	loyalty_points_reversed

FCM Payload

All notifications use a standardized data payload so mobile apps can branch on type and deep-link via orderId:

{
  "notification": {
    "title": "Order Status Updated",
    "body": "Your order is now Preparing."
  },
  "data": {
    "type": "order_status_update",
    "orderId": "...",
    "status": "Preparing",
    "restaurantId": "..."
  }
}

Recipient Logic

• Customer notifications target all active FCM tokens registered for the order's userId.
• Restaurant staff alerts target all logged-in users for the restaurant whose role is Owner, Manager, User, or Employee.
• Channels (push / email / SMS) are configured per event type in notificationConfig.ts and resolved dynamically by order status.

Coverage Status (2026-04)

All 12 previously missing notification workflows have been implemented:

• Payment succeeded / failed (webhook.ts)
• Refund processed (order.ts processRefund)
• Order auto-expired + cart item expired (reservationExpiryHandler.ts)
• Delivery status updates (order.ts isDeliveryOnlyUpdate path)
• Delivery creation failed (order.ts .catch)
• Item out-of-stock + low stock warning (inventoryService.ts — rate-limited 1/item/hour via Redis SET NX EX)
• POS sync failed (order.ts — rate-limited 1/restaurant/5min)
• Loyalty points earned/reversed (order.ts)

Mobile handlers updated: smackz-mobile handles 16 types, kds-mobile handles 7. Refund-request flow (refund_request_received, refund_approved, refund_denied) is queued behind the REFUND epic (#356).

Multi-Channel

Push (FCM) is the only channel currently active. Email and SMS hooks are placeholders; a Twilio SMS template is staged and ready to wire up. All handlers are fire-and-forget with .catch(() => {}) safety nets so a failed notification never crashes the parent mutation.

Key Files

Path	Purpose
yum/api/services/notifications.ts	FCM dispatch logic
yum/api/services/notificationConfig.ts	Per-type channel + recipient config
yum/api/services/inventoryService.ts	Stock alert rate limiting
yum/docs/NOTIFICATIONS.md	Mobile developer reference
yum/docs/NOTIFICATION_COVERAGE.md	Implementation audit
SMACKZ-MOBILE/src/features/notifications/	Customer push handlers
kds-mobile/src/features/notifications/	Staff push handlers