@pushprotocol/restapi v1.7.14

restapi

This package gives access to Push Protocol (Push Nodes) APIs. Visit Developer Docs or Push.org to learn more.

Index

• How to use in your app?
  • Installation
  • Import SDK
  • About generating the "signer" object for different platforms
    • When using in SERVER-SIDE code:
    • When using in FRONT-END code:
  • About blockchain agnostic address format
    • Chat blockchain agnostic address format
• SDK Features
  • Manage User
    • Initialize
    • Reinitialize
    • Fetch Info
    • Fetch User Profile Info
    • Update user Profile Info
    • Fetch User Encryption Info
    • Update User Encryption
  • For Push Notifications
    • Fetch Inbox Or Spam notifications
    • Fetch user subscriptions
    • Subscribe to a channel
    • Unsubscribe to a channel
    • Channel information
    • Search Channels
    • Get Subscribers Of A Channel
    • Send a notification
    • Create a channel
    • Update channel information
    • Verify a channel
    • Create channel Setting
    • Get delegators information
    • Add delegator to a channel or alias
    • Remove delegator from a channel or alias
    • Alias Information
    • Stream Notifications
  • For Push Chat
    • Fetch Latest Chat
    • Fetch Chat History
    • Send Message
    • Accept Chat Request
    • Reject Chat Request
    • Block Chat User
    • Unblock Chat User
    • Create Group
    • Fetch Group Info
    • Fetch Group Permission
    • Update Group
    • Add To Group
    • Remove From Group
    • Join Group
    • Leave Group
    • Reject Group Joining Request
    • Stream Chat Events
  • For Push Spaces
    • To create a space
    • To create a token gated space
    • To check user access of a token gated space
    • To update space details
    • To update token gated space details
    • To get space details by spaceId
    • To start a space
    • To stop a space
    • To approve a space request
    • To add listeners to space
    • To remove listeners from space
    • To add speakers to space
    • To remove speakers from space
    • Fetching list of user spaces
    • Fetching list of user space requests
    • Fetching list of trending spaces
  • For Push Video
    • data & setData
    • Stream API
    • Initialize Video API
    • Request a Video Call
    • Accept an incoming Video Call
    • Reject an incoming Video Call
    • Disconnect an ongoing video call
    • Managing Media Config
    • Read Current Media State

How to use in your app?

Installation

yarn add @pushprotocol/restapi@latest

or

npm install @pushprotocol/restapi@latest

Note - ethers is an optional peer dependency and is required only when sdk is used with ethers signer.

Import SDK

import { PushAPI } from '@pushprotocol/restapi';

About generating the "signer" object for different platforms

When using in SERVER-SIDE code:

const ethers = require('ethers');
const PK = 'your_channel_address_secret_key';
const Pkey = `0x${PK}`;
const _signer = new ethers.Wallet(Pkey);

When using in FRONT-END code:

// any other web3 ui lib is also acceptable
import { useWeb3React } from "@web3-react/core";
.
.
.
const { account, library, chainId } = useWeb3React();
const _signer = library.getSigner(account);

About blockchain agnostic address format

In any of the below methods (unless explicitly stated otherwise) we accept either -

• CAIP format: for any on chain addresses We strongly recommend using this address format. Learn more about the format and examples. (Example : eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb)

• ETH address format: only for backwards compatibility. (Example: 0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb)

Chat blockchain agnostic address format

Note - For chat related apis, the address is in the format: eip155:<address> instead of eip155:<chainId>:<address>, we call this format Partial CAIP (Example : eip155:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb)

SDK Features

Manage User

APIs to Initialise User and User APIs.

Initialize

// Initialize PushAPI class instance
const userAlice = await PushAPI.initialize(signer, {
  env: 'staging',
});

Parameters

* - Optional

Reinitialize

// Reinitialize PushAPI for fresh start of NFT Account
// Reinitialize only succeeds if the signer account is the owner of the NFT
await userAlice.reinitialize({
  versionMeta: { NFTPGP_V1: { password: 'NewPassword' } },
});

Parameters

Fetch User Info

// userAlice.info({options?})
const response = await userAlice.info();

Parameters: | Param | Type | Default | Remarks| | ---------- | ---------- | ------------- | ---------------------- | | options | InfoOptions | - | Optional configuration properties | | - | options.overrideAccount | - | The account for which info is retrieved, can override to get info of other accounts not owned by the user. If not provided, it is derived from signer. |

Fetch Profile Info

// userAlice.profile.info({options?})
const response = await userAlice.profile.info();

Parameters: | Param | Type | Default | Remarks| | ---------- | --------- | ------------- | ---------------------- | | options | InfoOptions | - | Optional configuration properties | | - | options.overrideAccount | - | The account for which info is retrieved, can override to get info of other accounts not owned by the user. If not provided, it is derived from signer. |

Update Profile Info

// Update Push Profile
// userAlice.profile.update({options?})
const response = await userAlice.profile.update({
  name: 'Alice',
  description: 'Alice is a software developer',
  picture: imageInBase64Format, // base64 encoded image
});

* - Optional

Fetch Encryption Info

// Fetch Encryption Info
const aliceEncryptionInfo = await userAlice.encryption.info();

Update Encryption

// userAlice.encryption.update(ENCRYPTION_TYPE, {options?})
// Wallet User Update,
// Usually not required as it's handled internally by the SDK to automatically update to recommended encryption type
const walletAlice = await userAlice.encryption.update(
  CONSTANTS.USER.ENCRYPTION_TYPE.PGP_V3
);

// NFT User Update
// Should be done when the NFT is transferred to a different user
// so messages and connections can be migrated to the new user
const nftAlice = await userAlice.encryption.update(
  CONSTANTS.USER.ENCRYPTION_TYPE.NFTPGP_V1,
  {
    versionMeta: {
      NFTPGP_V1: {
        password: 'new_password',
      },
    },
  }
);

* - Optional

For Push Notifications

Initializing User is the first step before proceeding to sending/interacting with Notification APIs. Please refer Initialize User Section

Fetch Inbox Or Spam notifications

// lists feeds
const aliceInfo = await userAlice.notification.list('INBOX');

Parameters:

* - Optional

Fetch user subscriptions

// fetches list of channels to which the user is subscribed
const subscriptions = await userAlice.notification.subscriptions();

Parameters:

* - Optional

Subscribe to a channel

// subscribes to a channel
const subscribeStatus = await userAlice.notification.subscribe(channelInCAIP, {
  settings,
});

Parameters:

Individual setting object:

* - Optional

Unsubscribe to a channel

// unsubscribes to the channel
const unsubscribeResponse = await userAlice.notification.unsubscribe(
  channelAddressInCAIP
);

Parameters:

* - Optional

Channel information

// fetches information about the channel
const channelInfo = await userAlice.channel.info(channelAddressInCAIP);

Parameters:

* - Optional

Search Channels

// returns channel matching the query
const searchResult = await userAlice.channel.search('push');

Parameters:

* - Optional

Get Subscribers Of A Channel

// userAlice.channel.subscribers({options?})
const channelSubscribers = await userAlice.channel.subscribers();

Parameters:

* - Optional

Send a notification

// sends a notification
// userAlice.channel.send([recipients], {options?})
const sendNotifRes = await userAlice.channel.send(['*'], {
  notification: { title: 'test', body: 'test' },
});

Parameters:

* - Optional

Create a channel

// creates a channel
// userAlice.channel.create({options})
const response = await userAlice.channel.create({
  name: 'Test Channel',
  description: 'Test Description',
  icon: imageBase64Format,
  url: 'https://push.org',
});

Parameters:

* - Optional

Optional: Informs about individual progress stages during channel creation if progresshook is function is passed during channel creation API call.

Progress object details

Update channel information

// updates channel info
// userAlice.channel.update({options?})
const updateChannelRes = await userAlice.channel.update({
  name: newChannelName,
  description: newChannelDescription,
  url: newChannelURL,
  icon: newBase64FormatImage,
  alias: newAliasAddressInCAIP,
});

Parameters:

* - Optional

Optional: Informs about individual progress stages during channel creation if progresshook is function is passed during channel creation API call.

Progress object details

Verify a channel

const verifyChannelRes = await userAlice.channel.verify(channel);

Parameters:

Create channel Setting

// creates channel settings
const createChannelSettingRes = userAlice.channel.setting([
  {
    type: 1, // Boolean type
    default: 1,
    description: 'Receive marketing notifications',
  },
  {
    type: 2, // Slider type
    default: 10,
    description: 'Notify when loan health breaches',
    data: { upper: 100, lower: 5, ticker: 1 },
  },
]);

Parameters:

| * - Optional

Get delegators information

// fetch delegate information
const delegates = await userAlice.channel.delegate.get();

Parameters:

* - Optional

Add delegator to a channel or alias

// adds a delegate
const addedDelegate = await userAlice.channel.delegate.add(delegate);

Parameters:

Remove delegator from a channel or alias

// removes a delegate
const removeDelegate = await userAlice.channel.delegate.remove(delegate);

Parameters:

Alias Information

// fetch alias info
const aliasInfo = userAlice.channel.alias.info({
  alias: aliasAddress,
  aliasChain: 'POLYGON',
});

Parameters:

Stream Notifications

// userAlice.stream(listen, {options?})
// Initial setup
const stream = await userAlice.initStream([CONSTANTS.STREAM.NOTIF], {
  filter: {
    channels: ['*'], // pass in specific channels to only listen to those
    chats: ['*'], // pass in specific chat ids to only listen to those
  },
  connection: {
    retries: 3, // number of retries in case of error
  },
  raw: false, // enable true to show all data
});

// Listen for notifications events
stream.on(CONSTANTS.STREAM.NOTIF, (data: any) => {
  console.log(data);
});

// Connect stream, Important to setup up listen events first
stream.connect();

// stream supports other products as well, such as STREAM.CHAT, STREAM.CHAT_OPS
// more info can be found at push.org/docs/chat

Parameters: | Param | Type | Default | Remarks | | ----- | ---- | ------- | ------- | | listen | constant | - | can be CONSTANTS.STREAM.CHAT, CONSTANTS.STREAM.CHAT_OPS, CONSTANTS.STREAM.NOTIF, CONSTANTS.STREAM.CONNECT, CONSTANTS.STREAM.DISCONNECT | | options* | PushStreamInitializeProps | - | Optional configuration properties for initializing the stream. | | options.filter* | object | - | Option to configure to enable listening to only certain chats or notifications. | | options.filter.channels* | array of strings | ['*'] | pass list of channels over here to only listen to notifications coming from them. | | options.filter.chats* | array of strings | ['*'] | pass list of chatids over here to only listen to chats coming from them. | | options.connection* | object | - | Option to configure the connection settings of the stream | | options.connection.retries* | number | 3 | Number of automatic retries incase of error | | options.raw* | boolean | false | If enabled, will also respond with meta data useful in verifying the integrity of incoming chats or notifications among other things. |

Stream Notification Events

For Push Chat

Initializing User is the first step before proceeding to Chat APIs. Please refer Manage User Section

Fetch List of Chats

// List all chats
const aliceChats = await userAlice.chat.list('CHATS');
// List all chat requests
const aliceRequests = await userAlice.chat.list('REQUESTS');

* - Optional

Fetch Latest Chat

// Latest Chat message with the target(bob) user
const aliceChats = await userAlice.chat.latest(bobAddress);

Fetch Chat History

// userAlice.chat.history(recipient. {options?})
const aliceChatHistoryWithBob = await userAlice.chat.history(bobAddress);

* - Optional

Send Message

// Alice sends message to bob
const aliceMessagesBob = await userAlice.chat.send(bobAddress, {
  content: 'Hello Bob!',
  type: 'Text',
});

* - Optional

Accept Chat Request

// Accept Chat Request of Alice
const bobAcceptAliceRequest = await userBob.chat.accept(aliceAddress);

Reject Chat Request

// Accept Chat Request of alice
await userBob.chat.reject(aliceAddress);

Block Chat User

// Block chat user
const AliceBlocksBob = await userAlice.chat.block([bobAddress]);

Unblock Chat User

// Unblock chat user
const AliceUnblocksBob = await userAlice.chat.unblock([bobAddress]);

Create Group

// Create a Group
// userAlice.chat.group.create(name, {options?})
const createdGroup = await userAlice.chat.group.create(name);

* - Optional

Fetch Group Info

// Fetch Group Info
const fetchGroupInfo = await userAlice.chat.group.info(groupChatId);

Fetch Group Permissions

// Fetch Group Permissions
const fetchGroupPermissions = await userAlice.chat.group.permissions(
  groupChatId
);

Update Group

// Update Group Info
// userAlice.chat.group.update(chatid, {options?})
const updatedGroup = await userAlice.chat.group.update(chatid, options);

* - Optional

Add To Group

// await userAlice.chat.group.add(chatid, {options?})
const addAdminToGroup = await userAlice.chat.group.add(groupChatId, {
  role: 'ADMIN', // 'ADMIN' or 'MEMBER'
  accounts: [account1, account2],
});

Remove From Group

// await userAlice.chat.group.remove(chatid, {options?})
const removeAdminFromGroup = await userAlice.chat.group.remove(groupChatId, {
  role: 'ADMIN', // 'ADMIN' or 'MEMBER'
  accounts: [account1, account2],
});

Join Group

const joinGroup = await userAlice.chat.group.join(groupChatId);