restapi

This package gives access to EPNS backend APIs

How to use in your app?

Installation

  yarn add @epnsproject/sdk-restapi ethers

or

  npm install @epnsproject/sdk-restapi ethers 

Import in your file

import * as EpnsAPI from "@epnsproject/sdk-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 EpnsAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address in CAIP
  env: 'staging'
});

fetching user spam notifications

const spams = await EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.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 EpnsAPI.user.getFeeds({
  user: 'eip155:5:0xD8634C39BBFd4033c0d3289C4515275102423681', // user address
  raw: true,
  env: 'staging'
});
// parse it to get a specific shape of object.
const parsedResults = EpnsAPI.utils.parseApiResponse(apiResponse);

const [oneNotification] = parsedResults;

// Now this object can be directly used by for e.g. "@epnsproject/sdk-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 EpnsAPI.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'|