Notifications GraphQL API

Real-time notification system with queries, mutations, and WebSocket subscriptions.

Queries

getNotification

Fetch a single notification for the current user.

query {
  getNotification(organizationId: 1, notificationId: 42) {
    notificationId
    title
    message
    type
    priority
    entityType
    entityId
    isRead
    readAt
    created
  }
}

Parameters:

Parameter	Type	Required	Description
organizationId	Int	Yes	Organization scope
notificationId	Int	Yes	Notification to fetch

Returns null if the notification doesn't exist or isn't assigned to the current user.

getNotifications

Paginated list of notifications for the current user. Supports filtering, searching, and sorting.

query {
  getNotifications(organizationId: 1, filter: "isRead:false", orderBy: "-notification.created", skip: 0, take: 20) {
    items {
      notificationId
      title
      message
      type
      priority
      isRead
      created
    }
    totalCount
  }
}

Parameters:

Parameter	Type	Required	Description
organizationId	Int	Yes	Organization scope
filter	String	No	Lucene filter syntax (e.g. isRead:false, type:Alert)
search	String	No	Full-text search
orderBy	String	No	Sort field (default: -notification.created = newest first)

getUnreadNotificationCount

Returns the count of unread notifications for the current user.

query {
  getUnreadNotificationCount(organizationId: 1)
}

Mutations

createNotification

Create a new notification. If targetUserId is omitted, broadcasts to all active users in the organization.

mutation {
  createNotification(organizationId: 1, values: {
    title: "Order #1234 shipped"
    message: "Your order has been picked up by the carrier."
    type: ORDER_UPDATE
    priority: NORMAL
    entityType: "Order"
    entityId: 1234
  }) {
    notificationId
    title
    created
  }
}

Input fields (CreateNotificationCommandValues):

Field	Type	Required	Default	Description
title	String	Yes	—	Notification title
message	String	No	—	Notification body (supports Markdown)
type	NotificationType	Yes	—	System, OrderUpdate, TaskAssignment, Alert, Info
priority	NotificationPriority	No	Normal	Low, Normal, High, Urgent
targetUserId	String	No	—	Target user; null = broadcast
entityType	String	No	—	Linked entity type name
entityId	Int	No	—	Linked entity ID
expiresAt	DateTime	No	—	Optional expiration

markNotificationRead

Mark a single notification as read for the current user.

mutation {
  markNotificationRead(organizationId: 1, notificationId: 42)
}

Returns true on success.

markAllNotificationsRead

Mark all notifications as read for the current user. Returns the count of notifications marked.

mutation {
  markAllNotificationsRead(organizationId: 1)
}

deleteNotification

Delete a notification (removes for all users).

mutation {
  deleteNotification(organizationId: 1, notificationId: 42) {
    deletedCount
    id
  }
}

Subscriptions

onNotificationReceived

Real-time WebSocket subscription for new notifications. Uses PostgreSQL NOTIFY/LISTEN under the hood.

subscription {
  onNotificationReceived(organizationId: 1, userId: "user-abc-123") {
    notificationId
    title
    message
    type
    priority
    entityType
    entityId
    isRead
    created
    createdBy
  }
}

Topic format: {organizationId}_{userId}_notifications

The subscription fires whenever a new notification is created that targets the specified user (either directly or via broadcast).

Frontend Integration

The frontend uses the useNotifications React hook which:

1. Fetches notifications via GetNotifications query (RTK Query)
2. Fetches unread count via GetUnreadNotificationCount query
3. Subscribes to onNotificationReceived via graphql-ws WebSocket client
4. Shows toast notifications for real-time updates
5. Provides markAsRead, markAllAsRead, and deleteNotification actions

The NotificationsDropdown component in the navbar renders the notification bell icon with unread badge and a dropdown panel with the notification list. Message content is rendered as Markdown.