# Siren JS SDK

The Siren JS SDK for In-App Notifications enhances Siren's capabilities by providing users with advanced notification management functionalities within their javascript applications. This feature ensures a seamless integration process, robust error handling, and compatibility with Siren's existing ecosystem

## Installation

You can install the js sdk from npm

```bash
npm install @sirenapp/js-sdk
```

or from yarn

```bash
yarn add @sirenapp/js-sdk
```

or from cdn

```bash
<script src="https://siren-js.sirenapp.io/siren-js-umd-sdk.js"></script>
```

## Usage

Initialize the SDK by creating a class instance as follows

```bash
import Siren from "@sirenapp/js-sdk"

const sirenInstance = new Siren({
        token: "your-user-token",
        recipientId: "your-recipient-id",
        onError: (error) => {
            # error callback function
        });
        actionCallbacks:{
            onEventReceive?: (response: NotificationsApiResponse, eventType: 'NOTIFICATIONS'| 'UNVIEWED_COUNT') => {
                 # callback function to receive data
            };
            onStatusChange?: (status: 'SUCCESS' | 'FAILED' | 'PENDING') =>{
                  # callback function triggered when token verification status changes
            }
        }
```

All the exposed methods can be accessed using sirenInstance object.
For example,to fetch all notifications,

```bash
const response = await sirenInstance.fetchAllNotifications({ page: 0, size: 10 })
```

Siren constructor accepts the following arguments

<table>
    <thead>
        <tr>
            <th>Property</th>
            <th>Description</th>
            <th>Type</th>
            <th>Optional</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>token</td>
            <td>Siren user token</td>
            <td>string</td>
            <td>false</td>
        </tr>
        <tr>
            <td>recipientId</td>
            <td>Siren recipient id</td>
            <td>string</td>
            <td>false</td>
        </tr>
         <tr>
            <td>onError</td>
            <td>To receive error call backs when there is any error </td>
            <td>function</td>
            <td>false</td>
        </tr>
        <tr>
            <td>actionCallbacks</td>
            <td>An object used to specify the callbacks triggered upon fetching the notifications or the unviewed count dynamically </td>
            <td>object</td>
            <td>true</td>
        </tr>
    </tbody>
</table>

## Siren Methods

### 1. verifyToken

This method verifies the validity of the given tokens (recipientId and userToken).This method is called automatically while creating the instance . Once the verification is successful, the remaining exposed methods can be accessed.

```bash
await sirenInstance.verifyToken();
```

### 2. fetchUnviewedNotificationsCount

This method retrieves the count of unviewed notifications.

```bash
const { unviewedCount } = await sirenInstance.fetchUnviewedNotificationsCount()
```

### 3. fetchAllNotifications

This method retrieves list of notifications in a paginated manner.

```bash
const notifications = await sirenInstance.fetchAllNotifications({ page: 0, size: 15, start: '', end: '', isRead: false, category: 'posts' });
```

Below are the accepted optional filters
<table>
    <thead>
        <tr>
            <th>Argument</th>
            <th>Description</th>
            <th>Type</th>
            <th>Default</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>page</td>
            <td>Current page</td>
            <td>number</td>
            <td>0</td>
        </tr>
        <tr>
            <td>size</td>
            <td>Number of items fetched </td>
            <td>number</td>
            <td>10</td>
        </tr>
        <tr>
            <td>start</td>
            <td>Accepts an ISO date string to filter notifications created after the specified date. By default, only the first 20 notifications will be fetched <br />
            eg: 2024-02-19T06:37:33.792+00:00</td>
            <td>string</td>
            <td>null</td>
        </tr>
         <tr>
            <td>end</td>
            <td>Accepts an ISO date string to filter notifications created before the specified date. By default, only the first 20 notifications will be fetched <br />
            eg: 2024-02-19T06:37:33.792+00:00</td>
            <td>string</td>
            <td>null</td>
        </tr>
        <tr>
            <td>isRead</td>
            <td>Filter to fetch read or unread notifications. If not specified, it retrieves both read and unread notifications</td>
            <td>boolean</td>
            <td>null</td>
        </tr>
         <tr>
            <td>category</td>
            <td>Filter to fetch notifications by category. If not specified, it retrieves all notifications</td>
            <td>string</td>
            <td>null</td>
        </tr>
    </tbody>
</table>

#### Response

```bash
 interface Notifications = {
    id: string;
    createdAt?: string;
    message: {
        channel: string;
        header: string;
        subHeader: string;
        body: string;
        actionUrl: string;
        avatar: {
            imageUrl: string;
            actionUrl: string | null;
        }
        additionalData: string;
    }
    requestId: string;
    isRead: boolean;
}[]
```

### 4. startRealTimeFetch

By specifying the parameter eventType as either `NOTIFICATIONS` or `UNVIEWED_COUNT`, this method triggers the real-time retrieval of notifications or the count of unviewed notifications. If `NOTIFICATIONS` is selected, further parameters (`params`) can be provided for additional customization or filtering

```bash
sirenInstance.startRealTimeFetch({ eventType: NOTIFICATIONS, params:{ page: 0, size: 15, start: '', end: '', isRead: false, category: 'posts' }});

sirenInstance.startRealTimeFetch({ eventType: UNVIEWED_COUNT });
```

Below are the accepted optional filters for `NOTIFICATIONS` event type

<table>
    <thead>
        <tr>
            <th>Argument</th>
            <th>Description</th>
            <th>Type</th>
            <th>Default</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>page</td>
            <td>Represents the current page</td>
            <td>number</td>
            <td>0</td>
        </tr>
        <tr>
            <td>size</td>
            <td>The number of items to be fetched in a single call</td>
            <td>number</td>
            <td>10</td>
        </tr>
        <tr>
            <td>start</td>
            <td>Accepts an ISO date string to filter notifications created after the specified date. By default, only the first 20 notifications will be fetched </td>
            <td>string</td>
            <td>null</td>
        </tr>
         <tr>
            <td>end</td>
            <td>Accepts an ISO date string to filter notifications created before the specified date. By default, only the first 20 notifications will be fetched</td>
            <td>string</td>
            <td>null</td>
        </tr>
        <tr>
            <td>isRead</td>
            <td>Filter to fetch read or unread notifications. If not specified, it retrieves both read and unread notifications</td>
            <td>number</td>
            <td>null</td>
        </tr>
         <tr>
            <td>category</td>
            <td>Filter to fetch notifications by category. If not specified, it retrieves all notifications</td>
            <td>string</td>
            <td>null</td>
        </tr>
    </tbody>
</table>

### 5. stopRealTimeFetch

By specifying the parameter eventType as either `NOTIFICATIONS` or `UNVIEWED_COUNT`, this method stops the real-time retrieval of notifications or the count of unviewed notifications.

```bash
sirenInstance.stopRealTimeFetch(NOTIFICATIONS);


sirenInstance.stopRealTimeFetch(UNVIEWED_COUNT);
```

### 6. markAsReadById

This method marks the notification as read. It accepts a notification id as an argument.

```bash
await sirenInstance.markAsReadById("your-notification-id");
```

### 7. markAsReadByDate

This method marks the notifications as read till the given date.<br />
It accepts a param object as an argument with keys startDate (ISO date string) and category(string).

```bash
await sirenInstance.markAsReadByDate({startDate: "2011-10-05T14:48:00.000Z"});
```

### 8. deleteById

This method deletes a notification. It accepts a notification id as an argument.

```bash
await sirenInstance.deleteById("your-notification-id");
```

### 9. deleteByDate

This method deletes the notifications till the given date.<br />
It accepts a param object as an argument with keys startDate (ISO date string), isRead(boolean) and category(string).

```bash
await sirenInstance.deleteByDate({startDate: "2011-10-05T14:48:00.000Z"});
```

### 10. markAllAsViewed

This method marks the notifications as viewed till the given date. This sets the unviewed count as 0 <br />
It accepts an ISO date string as an argument

```bash
await sirenInstance.markAllAsViewed("2011-10-05T14:48:00.000Z");
```