@futureverse/sylo-notifications-sdk

Broadcast / subscribe to Futureverse notifications over Sylo nodes.

Futureverse winddown

Futureverse (the publisher of @futureverse/*) is in winddown. The hosted services this package talked to (auth.futureverse.app, pass-api.futureverse.app, signer.futureverse.app) have been re-hosted by gen3labs at futurepass.gen3labs.tech (issuer) and fpsigner.gen3labs.tech (signer). For new projects, switch to the matching @gen3labs/* package — drop-in surface, default URLs already point at the gen3labs infra. The Asset Register API has no community replacement yet; see the Migration playbook for the per-package map.

Version

0.0.0-pre-SM-337.5

Published

2024-06-05

License

ISC

Status

fv-winddown

npm

https://www.npmjs.com/package/@futureverse/sylo-notifications-sdk

Types

./lib/src/index.d.ts

Maintainers

admin-futureverse, garethdainesnpm, jcsanpedro

Depends on

chai · uuid · fp-ts · io-ts · ethers · ts-proto · monocle-ts · newtype-ts · @types/chai · @types/uuid · io-ts-types · @sylo/logger · @types/mocha · @polkadot/api · io-ts-numbers · protoc-gen-js · ts-protoc-gen · @futureverse/experience-sdk · @futureverse/sylo-protocol-sdk

Recent versions

0.0.0-pre-SM-331.3 · 0.0.0-pre-SM-331.4 · 0.0.0-pre-SM-335.1 · 0.0.0-pre-SM-335.2 · 0.0.0-pre-SM-337.2 · 0.0.0-pre-SM-337.3 · 0.0.0-pre-SM-337.4 · 0.0.0-pre-SM-337.5

## Technical notes

Why use it

Push-style notifications without a centralised relay.

When to skip it

Standard webhooks/firehose suffices.

Pairs with

• @futureverse/sylo-protocol-sdk — transport

Upstream README

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;

Source: https://www.npmjs.com/package/@futureverse/sylo-notifications-sdk · captured 2026-05-02