Sylo Notifications SDK

This SDK provides utility functions for broadcasting and subscribing to Futureverse Notifications sent over the Seekers Node Network. It is responsible for creating the notification object, and for serialization and deserialization. This package is a simple wrapper over the sylo-protocol-sdk. It is recommened to first become familiar with the documentation available for the protocol sdk.

Install

NPM

npm install @futureverse/sylo-notifications-sdk

Yarn

yarn add @futureverse/sylo-notifications-sdk

Usage

To use the methods available from this sdk, a protocol-sdk client must first be created.

Notification Object

| Field | Description | | ---------- | ------------------------------------------------- | | id | uuid to uniquely identify this notification | | title | title descriptor | | body | notification contents | | created_at | unix timestamp of when it was sent | | cta_label | optional field indicating a call to action label | | cta_url | optional field indicating a call to action url | | tags | optional field of an array of strings | | icon_url | optional field indicating a url for an icon image |

Delivering

A single notification can be delivered to a single ethereum address via the relay service.

| Parameter | Description | | --------- | ----------------------------------------------------------------------------- | | client | The protocol sdk client from which the notification message will be sent from | | recipient | The ethereum address of the user this notification is intended for | | title | title of the notification | | body | notification contents | | cta_label | optional field indicating a call to action label | | cta_url | optional field indicating a call to action url | | tags | optional field of an array of strings | | icon_url | optional field indicating a url for an icon image |

import { deliverNotification } from "@futureverse/sylo-notifications-sdk";

deliverNotification(client, to, "title", "body", ["tag1", "tag2"]);

export type DeliverError = Error | EncodingError | ProtocolError | ScanError;

export async function deliverNotification(
  client: protocolSdk.client.Client,
  to: EthereumAddress,
  title: string,
  body: string,
  tags: string[],
  ctaLabel?: string,
  ctaUrl?: string,
  iconUrl?: string
): Promise<E.Either<DeliverError, void>>;

deliverNotification returns a Either<DeliverError, void>> result type.

Broadcasting

A single notification can be broadcast to multiple ethereum users via the pubsub service.

| Parameter | Description | | --------- | ----------------------------------------------------------------------------- | | client | The protocol sdk client from which the notification message will be sent from | | topic | topic of the notification | | title | title of the notification | | body | notification contents | | cta_label | optional field indicating a call to action label | | cta_url | optional field indicating a call to action url | | tags | optional field of an array of strings | | icon_url | optional field indicating a url for an icon image |

import { broadcastNotification } from "@futureverse/sylo-notifications-sdk";

broadcastNotification(client, "topic", "title", "body", ["tag1", "tag2"]);

export type BroadcastError =
  | Error
  | EncodingError
  | ProtocolError
  | ScanError
  | PublishError;

export async function broadcastNotification(
  client: protocolSdk.client.Client,
  topic: string,
  title: string,
  body: string,
  tags: string[],
  ctaLabel?: string,
  ctaUrl?: string,
  iconUrl?: string
): Promise<E.Either<BroadcastError, void>>;

broadcastNotification returns a Ether<BroadcastError, void>> result type.

Subscribing

This SDK is also used to subscribe to FV notifications. An application can subscribe to both delivered and broadcasted notifications.

subscribeDirectNotifications

| Parameter | Description | | --------- | ----------------------------------------------------------------------------- | | client | The protocol sdk client from which the notification message will be sent from | | signal | An AbortSignal used to cancel the subscription |

const notificationsSub = await subscribeDirectNotifications(
  client,
  abortController.signal
);

const next = await notificationsSub.next();
if (next.done) {
  assert.fail("Expected next value");
}

const receivedNotification = next.value;

console.log(receivedNotification.title);
console.log(receivedNotification.body);

export async function subscribeNotifications(
  client: protocolSdk.client.Client,
  signal: AbortSignal,
  logger = L.consoleLogger
): Promise<E.Either<SubscribeError, AsyncGenerator<FVNotification>>>;

subscribeNotifications

| Parameter | Description | | --------- | ----------------------------------------------------------------------------- | | client | The protocol sdk client from which the notification message will be sent from | | signal | An AbortSignal used to cancel the subscription | | from | The sender of the notification | | topic | The topic of the notifications to subscribe to |

const notificationsSub = await subscribeNotifications(
  client,
  { sender, topic },
  abortController.signal
);

const next = await notificationsSub.next();
if (next.done) {
  assert.fail("Expected next value");
}

const receivedNotification = next.value;

console.log(receivedNotification.title);
console.log(receivedNotification.body);

export async function subscribeNotifications(
  client: protocolSdk.client.Client,
  options: {
    sender: EthereumAddress;
    topic: string;
  },
  signal: AbortSignal,
  logger = L.consoleLogger
): Promise<E.Either<SubscribeError, AsyncGenerator<FVNotification>>>;

Subscription Result

subscribeDirectNotifications and subscribeNotifications returns a Ether<SubscribeError, AsyncGenerator<FVNotification>>> result type. The iterator will only be returned if the underlying subscription is successful.

export type SubscribeError =
  | Error
  | DecodingError
  | ProtocolError
  | PubSubError
  | DeliveryError
  | ScanError;