​
Overview

The Siren JS SDK enhances Siren’s capabilities by providing advanced notification management functionalities within JavaScript applications. It offers seamless integration, robust error handling, and compatibility with Siren’s ecosystem.

​
Installation

npm install @sirenapp/js-sdk

​
Usage

​
Initialization

import Siren from "@sirenapp/js-sdk";

const sirenInstance = new Siren({
  token: "your-user-token",
  recipientId: "your-recipient-id",
  onError: (error) => {
    console.error("Siren Error:", error);
  },
  actionCallbacks: {
    onEventReceive: (response, eventType) => {
      console.log("Event received:", eventType, response);
    }
  }
});

​
Constructor Options

PropertyDescriptionTypeRequired
tokenSiren user tokenstringYes
recipientIdSiren recipient IDstringYes
onErrorError callback functionFunctionYes
actionCallbacksCallbacks for notifications and countsObjectNo

​
Methods

​
fetchUnviewedNotificationsCount()

Retrieves the count of unviewed notifications. 
const { unviewedCount } = await sirenInstance.fetchUnviewedNotificationsCount();
console.log("Unviewed notifications:", unviewedCount);

​
fetchAllNotifications(options)

Retrieves a paginated list of notifications. 
const notifications = await sirenInstance.fetchAllNotifications({
  page: 0,
  size: 15,
  start: '2024-01-01T00:00:00.000Z',
  end: '2024-12-31T23:59:59.999Z',
  isRead: false,
  category: 'updates'
});

​
Options

ParameterDescriptionTypeDefault
pageCurrent page numbernumber0
sizeItems per pagenumber10
startFilter notifications after this date (ISO string)stringnull
endFilter notifications before this date (ISO string)stringnull
isReadFilter by read statusbooleannull
categoryFilter by categorystringnull

​
Response

interface Notification {
  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;
}

​
startRealTimeFetch(options)

Starts real-time notification updates. 
// For notifications
sirenInstance.startRealTimeFetch({
  eventType: 'NOTIFICATIONS',
  params: {
    page: 0,
    size: 15,
    start: '2024-01-01T00:00:00.000Z',
    end: '2024-12-31T23:59:59.999Z',
    isRead: false,
    category: 'updates'
  }
});

// For unviewed count
sirenInstance.startRealTimeFetch({
  eventType: 'UNVIEWED_COUNT'
});

​
stopRealTimeFetch(eventType)

Stops real-time updates. 
// Stop notifications updates
sirenInstance.stopRealTimeFetch('NOTIFICATIONS');

// Stop unviewed count updates
sirenInstance.stopRealTimeFetch('UNVIEWED_COUNT');

​
markAsReadById(notificationId)

Marks a notification as read. 
await sirenInstance.markAsReadById("notification-id-123");

​
markAsReadByDate(params)

Marks notifications as read until a specific date. 
await sirenInstance.markAsReadByDate({
  startDate: "2024-01-01T00:00:00.000Z",
  category: "updates" // Optional
});

​
deleteById(notificationId)

Deletes a notification. 
await sirenInstance.deleteById("notification-id-123");

​
deleteByDate(params)

Deletes notifications until a specific date. 
await sirenInstance.deleteByDate({
  startDate: "2024-01-01T00:00:00.000Z",
  isRead: true, // Optional
  category: "updates" // Optional
});

​
markAllAsViewed(date)

Marks all notifications as viewed until the specified date. 
await sirenInstance.markAllAsViewed("2024-01-01T00:00:00.000Z");

​
Example

import Siren from "@sirenapp/js-sdk";

// Initialize
const siren = new Siren({
  token: "your-user-token",
  recipientId: "your-recipient-id",
  onError: (error) => {
    console.error("Siren Error:", error);
  },
  actionCallbacks: {
    onEventReceive: (response, eventType) => {
      if (eventType === 'NOTIFICATIONS') {
        console.log("New notifications:", response);
      } else if (eventType === 'UNVIEWED_COUNT') {
        console.log("Unviewed count:", response.unviewedCount);
      }
    }
  }
});

// Fetch initial data
async function initialize() {
  try {
    // Get unread count
    const { unviewedCount } = await siren.fetchUnviewedNotificationsCount();
    console.log("Initial unread count:", unviewedCount);

    // Get notifications
    const notifications = await siren.fetchAllNotifications({
      page: 0,
      size: 10,
      isRead: false
    });
    console.log("Initial notifications:", notifications);

    // Start real-time updates
    siren.startRealTimeFetch({ eventType: 'NOTIFICATIONS' });
    siren.startRealTimeFetch({ eventType: 'UNVIEWED_COUNT' });

  } catch (error) {
    console.error("Initialization failed:", error);
  }
}

// Mark all as read
async function markAllAsRead() {
  try {
    await siren.markAsReadByDate({
      startDate: new Date().toISOString()
    });
    console.log("All notifications marked as read");
  } catch (error) {
    console.error("Failed to mark as read:", error);
  }
}

// Clean up
function cleanup() {
  siren.stopRealTimeFetch('NOTIFICATIONS');
  siren.stopRealTimeFetch('UNVIEWED_COUNT');
}

// Initialize the app
initialize();

// Clean up on unmount
window.addEventListener('beforeunload', cleanup);

​
Error Handling

All methods return Promises that can be caught for error handling: 
try {
  const result = await sirenInstance.someMethod();
  // Handle success
} catch (error) {
  console.error("Operation failed:", error);
  // Handle error
}

​
Support

For additional help, please contact our support team or refer to the official documentation.