diff --git a/docs/specs/clients/notify/authentication.md b/docs/specs/clients/notify/authentication.md index 77ebd9d9..afc79309 100644 --- a/docs/specs/clients/notify/authentication.md +++ b/docs/specs/clients/notify/authentication.md @@ -121,9 +121,68 @@ A non-ideal way to avoid the race condition is for the sender to set the message ## wc_notifyDelete response -- act - `notify_delete_response`` +- act - `notify_delete_response` - iss - did:key of dapp authentication key - aud - did:key of client identity key - app - did:web of app domain that this request is associated with - Example: `did:web:app.example.com` - sbs - array of [Notify Server Subscriptions](./data-structures.md#notify-server-subscriptions) + +## `wc_notifyGetNotifications` + +Paginated list of notifications with the most recently sent first. Unread notifications may be dispersed throughout the list and on subsequent pages. + +### Request + +- act - `notify_get_notifications` +- iss - did:key of client identity key +- ksu - key server for identity key verification +- aud - did:key of dapp authentication key +- app - did:web of app domain that this request is associated with + - Example: `did:web:app.example.com` +- lmt - the max number of notifications to return. Maximum value is 50. +- aft - the notification ID to start returning messages after. Null to start with the most recent notification + +```typescript +{ + auth: string, +} +``` + +| IRN | | +| ------- | ------------ | +| TTL | 300 | +| Tag | 4014 | +| Topic | notify topic | + +### Response + +- act - `notify_get_notifications_response` +- iss - did:key of client identity key +- aud - did:key of Notify Server authentication key +- nfs - array of [Notify Notifications](./data-structures.md#notify-notification) +- mre - true if there are more pages, false otherwise + +```typescript +{ + auth: string, +} +``` + +| IRN | | +| ------- | ------------ | +| TTL | 300 | +| Tag | 4015 | +| Topic | notify topic | + +## Noop + +Noop message sent by the Notify Server after subscription creation to mark a topic as long-lived so the relay does not destroy it. Clients should ignore this message. + +Content is empty string. + +| IRN | | +| ------- | ------------ | +| TTL | 300 | +| Tag | 4050 | +| Topic | notify topic | diff --git a/docs/specs/clients/notify/client-sdk-api.md b/docs/specs/clients/notify/client-sdk-api.md index 5c1d2af3..0c440c9e 100644 --- a/docs/specs/clients/notify/client-sdk-api.md +++ b/docs/specs/clients/notify/client-sdk-api.md @@ -14,7 +14,7 @@ abstract class Client { // Calls `wc_notifyWatchSubscriptions` for all previously registered accounts, // watches for future subscription updates, and subscribes to all notification topics public abstract init(): Promise; - + // send notify subscription public abstract subscribe(params: { appDomain: string, @@ -37,27 +37,28 @@ abstract class Client { account: string, }): Promise>; - // get all notifications for a subscription + // Get a paginated list of notifications with the most recently sent first. public abstract getNotificationHistory(params: { topic: string, - }): Promise> + // Default 10, max 50 + limit?: number, + startingAfter?: string, + }): Promise<{ + notifications: NotifyNotificationRecord[], + hasMore: boolean, + }> // delete active subscription public abstract deleteSubscription(params: { topic: string, }): Promise; - - // delete notification - public abstract deleteNotification(params: { - id: number, - }): Promise; - + // decrypt notify subscription message public abstract decryptNotification(params: { topic: string, encryptedMessage: string, }): Promise; - + // Generates and returns SIWE message along with // Cacao Payload with identity key public abstract prepareRegistration(params: { @@ -69,7 +70,7 @@ abstract class Client { registerParams: NotifyRegistrationParams, message: string }>; - + // "Logs in" this client to notifications for the specified account. This involves: // - Verifies signature by reconstructing formatted message using provided payload // - Expected payload comes from prepareRegistration @@ -80,7 +81,7 @@ abstract class Client { registerParams: NotifyRegistrationParams, signature: string; }): Promise; - + // Returns true if account has a valid and up to date registration, false otherwise public abstract isRegistered(params: { account: string, @@ -105,10 +106,10 @@ abstract class Client { // for wallet to listen for notify subscription created public abstract on("notify_subscription", (result: NotifySubscription | Error) => {}): void; - - // for wallet to listen on notify notification - public abstract on("notify_notification", (message: NotifyNotificationRecord, metadata: Metadata) => {}): void; - + + // for wallet to listen on notify notification + public abstract on("notify_notification", (notification: NotifyNotificationRecord, metadata: Metadata) => {}): void; + // for wallet to listen for result of notify subscription update public abstract on("notify_update", (result: NotifySubscription | Error) => {}): void; diff --git a/docs/specs/clients/notify/data-structures.md b/docs/specs/clients/notify/data-structures.md index 8d6647e4..727129d9 100644 --- a/docs/specs/clients/notify/data-structures.md +++ b/docs/specs/clients/notify/data-structures.md @@ -20,6 +20,31 @@ ```typescript { + // ID of the notification + id: string, + // Unix ms timestamp when the notification was sent + sent_at: number, + // Notification type which matches the scope of notify subscription + type: string, + // Short message used in the title of the notification + title: string, + // Long messages used in the body of the notification + body: string, + // Image URL used to display with the notification. If null, the app's icon from Notify Config is used instead + icon: string | null, + // Redirect URL for call-to-action related to notification. If null, there is no link + url: string | null, +} +``` + +## Notify Message + +```typescript +{ + // ID of the notification + id: string, + // Unix ms timestamp when the notification was sent + sent_at: number, // Notification type which matches the scope of notify subscription type: string, // Short message used in the title of the notification @@ -28,7 +53,7 @@ body: string, // Image URL used to display with the notification. If empty, the app's icon from Notify Config is used instead icon: string, - // Redirect URL for call-to-action related to notification. If empty, do not redirect + // Redirect URL for call-to-action related to notification. If empty, there is no link url: string, } ```