Merge pull request #1376 from WalletConnect/feat/web3inbox-read-unread

feat: read/unread status

Author: chris13524

docs/api/notify/usage.mdx

@@ -226,11 +226,14 @@ const accountSubscriptions = notifyClient.getActiveSubscriptions({
 
 ```javascript
 // Will return all past Notify messages for the provided subscription topic, keyed by messageId.
-const messageHistory = notifyClient.getNotificationHistory({
-  topic,
-  limit: 10,
-  startingAfter: 'notification-id'
-})
+const messageHistory = notifyClient.getNotificationHistory({ topic, limit: 10, startingAfter: 'notification-id', unreadFirst: true })
+```
+
+#### Marking notification as read
+
+```javascript
+// Will mark the 2 specific notifications as read
+const messageHistory = notifyClient.markNotificationsAsRead({ topic, notificationIds: ["notification-1", "notification-2" ] })
 ```
 
 </PlatformTabItem>

docs/web3inbox/about.mdx

@@ -23,6 +23,7 @@ Some of the key features of the Web3Inbox SDK include:
 - **Device push notifications:** Push notifications to the user's wallet (if it supports Notify API) or the [Web3Inbox.com app](https://app.web3inbox.com).
 - **Notification history:** Notifications are stored and can be accessed from any device.
 - **Spam protection/subscription control.** Using notification types, subscribers can opt-out of certain notification types they do not want to receive.
+- **Tracking read status across devices.**
 
 ## How do users receive notifications?
 

docs/web3inbox/backend-integration.mdx

@@ -206,6 +206,46 @@ curl 'https://notify.walletconnect.com/<PROJECT_ID>/subscribers' \
 
 </Tabs>
 
+## Mark all notifications as read
+
+Unless marked as read by an app frontend, notifications will always be "unread". Because of this, when you
+initially add support for displaying unread status or unread count to your frontend, users that have received
+notifications in the past will have notifications display as "unread" even if they already have seen them.
+This can potentially be an undesireable user experience.
+
+To mitigate this problem, you can make a one-time call to the `/v1/<project-id>/mark-all-as-read` API endpoint
+which will mark all existing notifications as read. Notifications marked as read in this way will not contribute
+to read rate analytics. After you deploy your integration of unread states, you can call this endpoint to
+reset the unread state for all of your existing notifications.
+
+<Tabs queryString={'api-client'}>
+
+<TabItem value="javascript" label="JavaScript">
+
+```typescript
+const PROJECT_ID = '<PROJECT_ID>'
+const NOTIFY_API_SECRET = '<NOTIFY_API_SECRET>'
+const response = await fetch(`https://notify.walletconnect.com/v1/${PROJECT_ID}/mark-all-as-read`, {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${NOTIFY_API_SECRET}`
+  }
+})
+```
+
+</TabItem>
+
+<TabItem value="curl" label="cURL">
+
+```bash
+curl -X POST 'https://notify.walletconnect.com/v1/<PROJECT_ID>/mark-all-as-read' \
+  --header 'Authorization: Bearer <NOTIFY_API_SECRET>'
+```
+
+</TabItem>
+
+</Tabs>
+
 ## Rate limits
 
 To protect our system and subscribers, various limits and rate limits are in-place.
@@ -219,3 +259,5 @@ Rate limits are implemented as [token bucket](https://en.wikipedia.org/wiki/Toke
   - Each app can call this endpoint 100 times per second with a burst up to 100. Rate limited requests will return a 429 status code.
 - `GET /<project-id>/subscribers`
   - Each app can call this endpoint 1 time every 5 minutes with a burst up to 2. Rate limited requests will return a 429 status code.
+- `POST /v1/<project-id>/mark-all-as-read`
+  - Each app can call this endpoint 1 time per hour with a burst up to 5. Rate limited requests will return a 429 status code.

docs/web3inbox/frontend-integration/api.mdx

@@ -249,6 +249,7 @@ const isSubscribed = Boolean(subscription)
   scope: ScopeMap
   expiry: number
   symkey: string
+  unreadCount: number
 }
 ```
 
@@ -307,6 +308,7 @@ client.watchSubscriptions(subscriptions => console.log({ subscriptions }))
   scope: ScopeMap
   expiry: number
   symkey: string
+  unreadCount: number
 }
 ```
 
@@ -330,24 +332,75 @@ Get notifications
 // watch notifications of current account's subscription to current dapp
 const notificationsPerPage = 5
 const isInfiniteScroll = true
+const unreadFirst = true
+
+const {
+  data: notifications,
+  nextPage,
+  markNotificationsAsRead,
+  markAllNotificationsAsRead
+} = useNotifications(
+  notificationsPerPage, 
+  isInfiniteScroll,
+  account,
+  domain,
+  unreadFirst,
+  onRead // optional function to run whenever messages are read
+)
+
+// marking a single notification as read
+await notifications[0].markAsRead();
+
+// mark specific notifications as read for default account and under default domain
+await markNotificationsAsRead(notifications.slice(2).map(n => n.id));
+
+// mark specific notifications as read for specified account under default domain
+await markNotificationsAsRead(notifications.slice(2).map(n => n.id), differentAccount);
+
+// mark specific notifications as read for default account under specified domain
+await markNotificationsAsRead(notifications.slice(2).map(n => n.id), undefined, differentDomain);
+
+// mark specific notifications as read for specified account under specified domain
+await markNotificationsAsRead(notifications.slice(2).map(n => n.id), differentAccount, differentDomain);
+
+// mark all notifications as read for default account under default domain
+await markAllNotificationsAsRead();
+
+// mark all notifications as read for specified account under default domain
+await markAllNotificationsAsRead(differentAccount);
+
+// mark all notifications as read for default account under specified domain
+await markAllNotificationsAsRead(undefined, differentDomain);
+
+// mark all notifications as read for specified account under specified domain
+await markAllNotificationsAsRead(differentAccount, differentDomain);
+
 
-const { data: notifications, nextPage } = useNotifications(notificationsPerPage, isInfiniteScroll)
 ```
 
 #### References
 
-- **notificationsPerPage:** Number representing how many notifications to get per fetch
-- **isInfiniteScroll:** Whether or not to keep already fetched notifications when getting next page
+- **useNotifications()**
+  - **notificationsPerPage:** Number representing how many notifications to get per fetch
+  - **isInfiniteScroll:** Whether or not to keep already fetched notifications when getting next page
+  - **params:** (optional) Additional parameters
+  - **unreadFirst:** (optional, default `true`, since 1.3.0) Whether or not unread messages should be sorted at the top, regardless of timestamp
+- **nextPage:** A function to be called to fetch the next page of notifications
 - **notifications:** Array of notifications, of type
+- **notification.read:** Mark the notification as read
+- **markNotificationsAsRead**: Takes an array of notification IDs and marks them as read. Max 1000 IDs
+- **markAllNotificationsAsRead**: Mark all notifications as read.
 
 ```ts
 {
   title: string
   sentAt: number
   body: string
   id: string
+  isRead: boolean
   url: string | null
   type: string
+  markAsRead: () => Promise<void>
 }
 ```
 
@@ -365,26 +418,61 @@ const notificationsPage = client.getNotificationHistory({
 
 const notificationsPerPage = 5
 const isInfiniteScroll = true
+const unreadFirst = true
 
-const { nextPage } = client.pageNotifications(notificationsPerPage, isInfiniteScroll)(onUpdate)
+let notifications = []
+
+const onUpdate = ({notifications: fetchedNotifications}: GetNotificationsReturn) => {
+  notifications = fetchedNotifications
+}
+
+const {
+  nextPage,
+  markNotificationAsRead,
+  markAllNotificationsAsRead
+} = client.pageNotifications(
+  notificationsPerPage,
+  isInfiniteScroll,
+  specifiedAccount // OR undefined,
+  specifiedDomain // OR undefined,
+  unreadFirst
+)(onUpdate)
+
+
+// marking a single notification as read
+await notifications[0].markAsRead();
+
+// mark specific notifications as read
+await markNotificationsAsRead(notifications.slice(2).map(n => n.id));
+
+// mark all notifications as read
+await markAllNotificationsAsRead();
 ```
 
 #### References
 
-- **notificationsPerPage:** Number representing how many notifications to get per fetch
-- **isInfiniteScroll:** Whether or not to keep already fetched notifications when getting next page
+- **pageNotifications:**
+  - **notificationsPerPage:** Number representing how many notifications to get per fetch
+  - **isInfiniteScroll:** Whether or not to keep already fetched notifications when getting next page
+  - **params:* (optional) Additional parameters
+  - **unreadFirst:** (optional, default `true`, since 1.3.0) Whether or not unread messages should be sorted at the top, regardless of timestamp
 - **onUpdate:**: A callback that will be called whenever notifications get updated
 - **nextPage:**: A function to be called to fetch the next page of notifications
 - **notifications:** Array of notifications, of type
+- **notification.markAsRead:** Mark the notification as read
+- **markNotificationsAsRead**: Takes an array of notification IDs and marks them as read. Max 1000 IDs
+- **markAllNotificationsAsRead**: Mark all notifications as read.
 
 ```ts
 {
   title: string
   sentAt: number
   body: string
   id: string
+  isRead: boolean // since 1.3.0
   url: string | null
   type: string
+  read: () => Promise<void> // since 1.3.0
 }
 ```
 

docs/web3inbox/frontend-integration/usage.mdx

@@ -78,7 +78,7 @@ import {
 import { useCallback, useEffect } from 'react'
 import { useSignMessage, useAccount } from 'wagmi'
 
-import Messages from './Messages'
+import Notifications from './Notifications'
 
 export default function App() {
   // Wagmi Hooks
@@ -134,7 +134,7 @@ export default function App() {
                 {isSubscribed ? 'Unsubscribe' : 'Subscribe'}
               </button>
               <hr />
-              {isSubscribed ? <Messages /> : null}
+              {isSubscribed ? <Notifications /> : null}
             </div>
           </div>
         )}
@@ -145,34 +145,39 @@ export default function App() {
 ```
 
 ```tsx
-//Messages.tsx
+// Notifications.tsx
 import { useNotifications } from '@web3inbox/react'
 import React from 'react'
-import styles from '@/styles/Messages.module.css'
+import styles from '@/styles/Notifications.module.css'
 
-function Messages() {
-  const { data: notifications } = useNotifications(3, false)
+function Notifications() {
+  const { data: subscription } = useSubscription()
+  const { data: notifications } = useNotifications(5)
 
   return (
     <div>
-      <h2 className={styles.heading}>Previous Messages</h2>
-      <div className={styles.messageContainer}>
+      <h2 className={styles.heading}>Notifications</h2>
+      <p>You have {subscription.unreadCount} unread notifications.</p>
+      <div className={styles.notificationsContainer}>
         {!notifications?.length ? (
-          <p className={styles.fallbackText}>No messages yet.</p>
+          <p className={styles.fallbackText}>No notifications yet.</p>
         ) : (
           notifications.map(({ id, ...message }) => (
             <div key={id} className={styles.message}>
               <h3>{message.title}</h3>
               <p>{message.body}</p>
+              <p>{message.isRead ? "Read" : "Unread"}</p>
+              <button onClick={message.markAsRead}>Mark as read</button>
             </div>
           ))
         )}
       </div>
+      <button onClick={nextPage}>Next page</button>
     </div>
   )
 }
 
-export default Messages
+export default Notifications
 ```
 
 </PlatformTabItem>
@@ -209,7 +214,8 @@ client.pageNotifications(
   isInfiniteScroll
 )(notifications => {
   // add logic to display notifications here.
-  //if isInfiniteScroll is true, notifications will contain all notifications fetched so far, else it will only fetch current page
+  // if isInfiniteScroll is true, notifications will contain all notifications fetched so far, else it will only fetch current page
+  // See API docs for more information on `pageNotifications()` and how to use `notifications`
 })
 ```