@engagespot/store v2.0.1

Engagespot Store

@engagespot/store is a framework-agnostic reactive library for managing Engagespot data. It is a wrapper over @engagespot/core that provides reactivity to the plain APIs. This library allows you to build real-time notification systems with ease, supporting features like notification feeds, web push notifications, user preferences, and more.

Table of Contents

• Features
• Installation
• Getting Started
• Usage Examples
  • Initializing the Store
  • Accessing Notifications
  • Handling Real-Time Updates
  • Web Push Notifications
  • Managing User Preferences
• API Reference
  • Store Options
  • Store Instance
  • Notification Feed
  • Web Push Service
  • Preferences Service
  • Actions Service
• Contributing
• License

Features

• Reactive Data Management: Automatically updates your application state with real-time notifications and data changes.
• Notification Feeds: Manage notification lists with pagination, unread counts, and more.
• Web Push Notifications: Integrate web push notifications seamlessly.
• User Preferences: Handle user notification preferences and categories.
• Real-Time Updates: Built-in support for real-time messaging and updates.
• Framework-Agnostic: Can be used with any JavaScript framework or library.
• Easy Integration: Simple APIs to integrate into existing applications.

Installation

Install the package using npm or yarn:

# Using npm
npm install @engagespot/store

# Using yarn
yarn add @engagespot/store

Note: @engagespot/core is a dependency of this package and will be installed automatically.

Getting Started

Before you start, make sure you have your Engagespot API Key from your Engagespot Dashboard.

Usage Examples

Initializing the Store

import { createStore } from '@engagespot/store';

const store = createStore({
  apiKey: 'YOUR_ENGAGESPOT_API_KEY',
  userId: 'unique_user_identifier',
  userSignature: 'optional_user_signature', // If using HMAC authentication
  debug: true, // Optional: Enable debug mode
  itemsPerPage: 20, // Optional: Number of notifications per page
  disableRealTimeStoreUpdates: false, // Optional: Disable real-time updates
});

Parameters:

• apiKey (string): Required. Your Engagespot API Key.
• userId (string): Required. A unique identifier for the user.
• userSignature (string, optional): Required if you have HMAC authentication enabled.
• debug (boolean, optional): Enable debug mode for logging.
• itemsPerPage (number, optional): Number of notifications per page.
• disableRealTimeStoreUpdates (boolean, optional): Disable automatic updates from real-time events.

Accessing Notifications

The store provides a reactive notification feed that you can use to display notifications in your application.

// Access the notification feed
const { stores, actions } = store.notificationFeed;

// Subscribe to notifications
stores.$notifications.subscribe(notifications => {
  console.log('Notifications:', notifications);
});

// Load more notifications
actions.loadMore();

// Refresh notifications
actions.refresh();

Note: The $notifications store is reactive and will update whenever new notifications are received or changes occur.

Handling Real-Time Updates

Real-time updates are handled automatically by default. You can listen to real-time events and update your UI accordingly.

// Access the unread count
store.notificationFeed.stores.$unreadCount.subscribe(unreadCount => {
  console.log('Unread notifications:', unreadCount);
});

Web Push Notifications

You can manage web push notifications using the webpush service.

// Check if web push is supported
if (store.webpush.actions.isSupported()) {
  // Subscribe to web push notifications
  await store.webpush.actions.subscribe();
}

// Access the web push state
store.webpush.stores.$webPushState.subscribe(state => {
  console.log('Web Push State:', state);
});

Note: Ensure that your application is served over HTTPS and that you have a valid service worker registered.

Managing User Preferences

You can manage user preferences using the preferences service.

// Access the preferences store
store.preferences.stores.$preferences.subscribe(preferences => {
  console.log('User Preferences:', preferences);
});

// Set user preferences
await store.preferences.actions.setPreferences([
  {
    categoryId: 'category_id',
    channels: [
      { channel: 'email', enabled: true },
      { channel: 'webPush', enabled: false },
    ],
  },
]);

// Set user profile attributes
await store.preferences.actions.setProfileAttributes({
  attribute1: 'value1',
  attribute2: 'value2',
});

API Reference

Store Options

When creating a store instance using createStore(options), the following options are available:

• apiKey (string): Required. Your Engagespot API Key.
• userId (string): Required. A unique identifier for the user.
• userSignature (string, optional): Required if HMAC authentication is enabled.
• debug (boolean, optional): Enable debug mode for logging. Default is false.
• itemsPerPage (number, optional): Number of notifications per page. Default is 15.
• disableRealTimeStoreUpdates (boolean, optional): Disable automatic updates from real-time events. Default is false.
• disableFetchOnStart (boolean, optional): Disable fetching notifications on store initialization. Default is false.
• relativeTimeUpdateInterval (number, optional): Interval in milliseconds to update relative time of notifications. Default is 60000 (1 minute).

Store Instance

The store instance returned by createStore contains the following services:

• instance: The underlying Engagespot instance from @engagespot/core.
• notificationFeed: Manages the notification feed.
• webpush: Manages web push notifications.
• connect: Provides connection status and related information.
• actions: Contains actions to manipulate notifications.
• rtm: Handles real-time messaging.
• preferences: Manages user preferences.

Notification Feed

Accessed via store.notificationFeed, provides stores and actions to manage notifications.

Stores

• $notifications: Reactive store containing the list of notifications.
• $unreadCount: Reactive store containing the number of unread notifications.
• $loading: Reactive store indicating if notifications are being loaded.
• $hasMore: Reactive store indicating if there are more notifications to load.

Actions

• loadMore(): Load the next page of notifications.
• refresh(): Refresh the notifications list.

Example

// Subscribe to notifications
store.notificationFeed.stores.$notifications.subscribe(notifications => {
  // Update your UI with the new notifications
});

// Load more notifications when needed
store.notificationFeed.actions.loadMore();

Web Push Service

Accessed via store.webpush, provides methods and stores to manage web push notifications.

Stores

• $webPushState: Reactive store containing the current web push permission state.

Actions

• subscribe(): Subscribe to web push notifications.
• clearWebPushSubscription(): Clear the web push subscription.
• isSupported(): Check if web push is supported in the browser.

Example

if (store.webpush.actions.isSupported()) {
  await store.webpush.actions.subscribe();
}

store.webpush.stores.$webPushState.subscribe(state => {
  console.log('Web Push State:', state);
});

Preferences Service

Accessed via store.preferences, provides methods and stores to manage user preferences.

Stores

• $preferences: Reactive store containing user preferences.
• $channels: Reactive store containing the available channels.

Actions

• setPreferences(preferences): Set user preferences.
• setProfileAttributes(attributes): Set user profile attributes.

Example

// Set user preferences
await store.preferences.actions.setPreferences([
  {
    categoryId: 'category_id',
    channels: [
      { channel: 'email', enabled: true },
      { channel: 'webPush', enabled: false },
    ],
  },
]);

Actions Service

Accessed via store.actions, provides methods to perform actions on notifications.

Methods

• deleteNotification(notificationId): Delete a notification.
• markAsRead(notificationId): Mark a notification as read.
• markAllAsRead(): Mark all notifications as read.
• deleteAllNotifications(): Delete all notifications.
• markAsSeen(): Mark notifications as seen.
• changeState({ id, state }): Change the state of a notification.

Example

// Mark a notification as read
await store.actions.markAsRead('notification_id');

// Delete a notification
await store.actions.deleteNotification('notification_id');

Contributing

We welcome contributions to the Engagespot Store! If you have any ideas, suggestions, or issues, please open an issue or pull request on our GitHub repository.

Development Setup

Clone the repository:

git clone https://github.com/Engagespot/engagespot-store.git

Install dependencies:

cd engagespot-store
npm install

Run tests:

npm test

Build the project:

npm run build

Coding Guidelines

• Follow the existing code style and structure.
• Write unit tests for new features or bug fixes.
• Ensure that all tests pass before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

For more information about Engagespot and its features, please visit our official website or check out our documentation.

If you have any questions or need assistance, feel free to reach out to our support team at support@engagespot.co.