Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

@pushprotocol/restapi

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@pushprotocol/restapi

This package gives access to EPNS backend APIs

0.0.2
npm

Version published: 2 years ago

Weekly downloads: 2.4K; increased by22.05%

Maintainers: 1

Weekly downloads

Created: 2 years ago

Source

restapi

This package gives access to EPNS backend APIs

How to use in your app?

Installation

  yarn add @pushprotocol/restapi ethers

  npm install @pushprotocol/restapi ethers

Import in your file

import * as PushAPI from "@pushprotocol/restapi";

NOTE on Addresses:

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. (Example : eip155:1:0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb)
ETH address format: only for backwards compatibility. (Example: 0xab16a96d359ec26a11e2c2b3d8f8b8942d5bfcdb)

NOTE on 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);

MAIN FEATURES

fetching user notifications

const notifications = await PushAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address in CAIP
  env: 'staging'
});

fetching user spam notifications

const spams = await PushAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address in CAIP
  spam: true,
  env: 'staging'
});

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
user*	string	-	user account address (CAIP)
page	number	1	page index of the results
limit	number	10	number of items in 1 page
spam	boolean	false	if "true" it will fetch spam feeds
env	string	'prod'	API env - 'prod', 'staging', 'dev'
raw	boolean	false	if "true" the method will return unformatted raw API response

fetching user subscriptions

const subscriptions = await PushAPI.user.getSubscriptions({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address in CAIP
  env: 'staging'
});

where subscriptions is a list of channels [{ channel: '0xaddress', ... }] subscribed by the user.

Note: We can find out if a user is subscribed to a channel by checking if the channel address is present in the subscriptions list

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
user*	string	-	user address (CAIP)
env	string	'prod'	API env - 'prod', 'staging', 'dev'

fetching channel details

const channelData = await PushAPI.channels.getChannel({
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // channel address in CAIP
  env: 'staging'
});

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
channel*	string	-	channel address (CAIP)
env	string	'prod'	API env - 'prod', 'staging', 'dev'

searching for channel(s)

const channelsData = await PushAPI.channels.search({
  query: 'epns', // a search query
  page: 1, // page index
  limit: 20, // no of items per page
  env: 'staging'
});

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
query*	string	-	search query
page	number	1	page index of the results
limit	number	10	number of items in 1 page
env	string	'prod'	API env - 'prod', 'staging', 'dev'

opt in to a channel

await PushAPI.channels.subscribe({
  signer: _signer,
  channelAddress: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // channel address in CAIP
  userAddress: 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3', // user address in CAIP
  onSuccess: () => {
   console.log('opt in success');
  },
  onError: () => {
    console.error('opt in error');
  },
  env: 'staging'
})

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
signer*	-	-	Signer object
channelAddress*	string	-	channel address (CAIP)
userAddress*	string	-	user address (CAIP)
verifyingContractAddress	string	-	EPNS communicator contract address
onSuccess	function	-	on success callback
onError	function	-	on error callback
env	string	'prod'	API env - 'prod', 'staging', 'dev'

opt out to a channel

await PushAPI.channels.unsubscribe({
  signer: _signer,
  channelAddress: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // channel address in CAIP
  userAddress: 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3', // user address in CAIP
  onSuccess: () => {
   console.log('opt out success');
  },
  onError: () => {
    console.error('opt out error');
  },
  env: 'staging'
})

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
signer*	-	-	Signer object
channelAddress*	string	-	channel address (CAIP)
userAddress*	string	-	user address (CAIP)
verifyingContractAddress	string	-	EPNS communicator contract address
onSuccess	function	-	on success callback
onError	function	-	on error callback
env	string	'prod'	API env - 'prod', 'staging', 'dev'

^*EPNS communicator contract address

ETH Mainnet - 0xb3971BCef2D791bc4027BbfedFb47319A4AAaaAa
ETH Goerli - 0x87da9Af1899ad477C67FeA31ce89c1d2435c77DC

sending notification

direct payload for single recipient(target)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 3, // target
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // recipient address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

direct payload for group of recipients(subset)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 4, // subset
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: ['eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1'], // recipients addresses
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

direct payload for all recipients(broadcast)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 1, // broadcast
  identityType: 2, // direct payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

IPFS payload for single recipient(target)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 3, // target
  identityType: 1, // ipfs payload
  ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we', // IPFS hash of the payload
  recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', // recipient address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

IPFS payload for group of recipients(subset)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 4, // subset
  identityType: 1, // ipfs payload
  ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we', // IPFS hash of the payload
  recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'], // recipients addresses
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

IPFS payload for all recipients(broadcast)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 1, // broadcast
  identityType: 1, // direct payload
  ipfsHash: 'bafkreicuttr5gpbyzyn6cyapxctlr7dk2g6fnydqxy6lps424mcjcn73we', // IPFS hash of the payload
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

minimal payload for single recipient(target)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 3, // target
  identityType: 0, // Minimal payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', // recipient address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

minimal payload for a group of recipient(subset)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 4, // subset
  identityType: 0, // Minimal payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'], // recipients address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

minimal payload for all recipients(broadcast)

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 1, // broadcast
  identityType: 0, // Minimal payload
  notification: {
    title: `[SDK-TEST] notification TITLE:`,
    body: `[sdk-test] notification BODY`
  },
  payload: {
    title: `[sdk-test] payload title`,
    body: `sample msg body`,
    cta: '',
    img: ''
  },
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

graph payload for single recipient(target)

Make sure the channel has the graph id you are providing!!

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 3, // target
  identityType: 3, // Subgraph payload
  graph: {
    id: '_your_graph_id',
    counter: 3
  },
  recipients: 'eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', // recipient address
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

graph payload for group of recipients(subset)

Make sure the channel has the graph id you are providing!!

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 4, // subset
  identityType: 3, // graph payload
  graph: {
    id: '_your_graph_id',
    counter: 3
  },
  recipients: ['eip155:5:0xCdBE6D076e05c5875D90fa35cc85694E1EAFBBd1', 'eip155:5:0x52f856A160733A860ae7DC98DC71061bE33A28b3'], // recipients addresses
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

graph payload for all recipients(broadcast)

Make sure the channel has the graph id you are providing!!

// apiResponse?.status === 204, if sent successfully!
const apiResponse = await PushAPI.payloads.sendNotification({
  signer,
  type: 1, // broadcast
  identityType: 3, // graph payload
  graph: {
    id: '_your_graph_id',
    counter: 3
  },
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // your channel address
  env: 'staging'
});

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
signer*	-	-	Signer object
channel*	string	-	channel address (CAIP)
type*	number	-	Notification Type Target = 3 (send to 1 address), Subset = 4 (send to 1 or more addresses), Broadcast = 1 (send to all addresses)
identityType*	number	-	Identity Type Minimal = 0, IPFS = 1, Direct Payload = 2, Subgraph = 3 }
recipients*	string or string[]	-	for Notification Type = Target it is 1 address, for Notification Type = Subset, Broadcast it is an array of addresses (CAIP)
notification.title*	string	-	Push Notification Title (not required for identityType IPFS, Subgraph)
notification.body*	string	-	Push Notification Body (not required for identityType IPFS, Subgraph)
payload.title	string	-	Notification Title (not required for identityType IPFS, Subgraph)
payload.body	string	-	Notification Body (not required for identityType IPFS, Subgraph)
payload.cta	string	-	Notification Call To Action url (not required for identityType IPFS, Subgraph)
payload.img	string	-	Notification Media url (not required for identityType IPFS, Subgraph)
payload.sectype	string	-	If Secret Notification then pass (not required for identityType IPFS, Subgraph)
graph.id	string	-	graph id, required only if the identityType is 3
graph.counter	string	-	graph counter, required only if the identityType is 3
ipfsHash	string	-	ipfsHash, required only if the identityType is 1
expiry	number	-	(optional) epoch value if the notification has an expiry
hidden	boolean	false	(optional) true if we want to hide the notification
env	string	'prod'	API env - 'prod', 'staging', 'dev'

UTILS

parsing notifications

Utils method to parse raw EPNS Feeds API response into a pre-defined shape as below.

// fetch some raw feeds data
const apiResponse = await PushAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address
  raw: true,
  env: 'staging'
});
// parse it to get a specific shape of object.
const parsedResults = PushAPI.utils.parseApiResponse(apiResponse);

const [oneNotification] = parsedResults;

// Now this object can be directly used by for e.g. "@pushprotocol/uiweb"  NotificationItem component as props.

const {
  cta,
  title,
  message,
  app,
  icon,
  image,
  url,
  blockchain,
  secret,
  notification
} = oneNotification;

We get the above keys after the parsing of the API repsonse.

ADVANCED (WIP)

DEPRECATED

get a channel's subscriber list of addresses

const subscribers = await PushAPI.channels._getSubscribers({
  channel: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // channel address in CAIP
  env: 'staging'
});

Allowed Options (params with * are mandatory)

Param	Type	Default	Remarks
channel*	string	-	channel address (CAIP)
env	string	'prod'	API env - 'prod', 'staging', 'dev'

FAQs

What is @pushprotocol/restapi?

Is @pushprotocol/restapi popular?

Is @pushprotocol/restapi well maintained?

Package last updated on 05 Oct 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@pushprotocol/restapi

restapi

How to use in your app?

Installation

NOTE on Addresses:

NOTE on generating the "signer" object for different platforms:

When using in SERVER-SIDE code:

When using in FRONT-END code:

MAIN FEATURES

fetching user notifications

fetching user spam notifications

fetching user subscriptions

fetching channel details

searching for channel(s)

opt in to a channel

opt out to a channel

sending notification

direct payload for single recipient(target)

direct payload for group of recipients(subset)

direct payload for all recipients(broadcast)

IPFS payload for single recipient(target)

IPFS payload for group of recipients(subset)

IPFS payload for all recipients(broadcast)

minimal payload for single recipient(target)

minimal payload for a group of recipient(subset)

minimal payload for all recipients(broadcast)

graph payload for single recipient(target)

graph payload for group of recipients(subset)

graph payload for all recipients(broadcast)

UTILS

parsing notifications

ADVANCED (WIP)

DEPRECATED

get a channel's subscriber list of addresses

Related posts

Author Typosquatting on npm: Attackers Impersonate Sindre Sorhus with Malicious ‘chalk-node’ Package

Supply Chain Attack on LottieFiles Player Caused by Compromised npmjs Credentials