restapi

This package gives access to EPNS backend APIs

How to use in your app?

$3

``
yarn add @epnsproject/sdk-restapi ethers
`
or
`
npm install @epnsproject/sdk-restapi ethers
`
Import in your file
`typescript
import * as EpnsAPI from "@epnsproject/sdk-restapi";
`

$3

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)

$3

#### When using in SERVER-SIDE code:
`typescript
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:
`typescript
// any other web3 ui lib is also acceptable
import { useWeb3React } from "@web3-react/core";
.
.
.
const { account, library, chainId } = useWeb3React();
const signer = library.getSigner(account);
`

$3

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

#### fetching user spam notifications
`typescript
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
`typescript
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
`typescript
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)
`typescript
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
`typescript
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
`typescript
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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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)
`typescript
// 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!!
`typescript
// 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!!
`typescript
// 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!!
`typescript
// 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'|

$3


#### parsing notifications
Utils method to parse raw EPNS Feeds API response into a pre-defined shape as below.
`typescript
// 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.




$3




$3

#### get a channel's subscriber list of addresses
`typescript
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'|