@epnsproject/sdk-restapi v0.1.20
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'|
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago