PulseLeo SDK

A lightweight browser SDK for integrating PulseLeo Push Notifications.

Installation

npm install pulse-leo-sdk

Usage

1. Initialize

Initialize the client with your VAPID Public Key (found in your Dashboard).

import { PushClient } from "pulse-leo-sdk";

const pushClient = new PushClient({
  vapidPublicKey: "YOUR_VAPID_PUBLIC_KEY",
  backendRegisterUrl: "https://api.pulseleo.com/register", // Or your backend proxy
  serviceWorkerPath: "/sw.js", // Default
  tags: {
    category: "news",
    source: "landing_page",
  },
});

2. Service Worker Setup

The SDK requires a service worker to handle push notifications. Choose one of the following options:

Option A: Copy to Public Directory (Recommended)

Service workers must be served from your domain's root to properly control your application. The most reliable method is to copy the service worker file to your public directory.

Method 1: Using postinstall script

Add a postinstall script to your package.json:

{
  "scripts": {
    "postinstall": "cp node_modules/pulse-leo-sdk/dist/sw.js public/sw.js"
  }
}

Method 2: Using build tools (Vite example)

Install vite-plugin-static-copy:

npm install -D vite-plugin-static-copy

Add to your vite.config.ts:

import { viteStaticCopy } from 'vite-plugin-static-copy';

export default defineConfig({
  plugins: [
    viteStaticCopy({
      targets: [
        {
          src: 'node_modules/pulse-leo-sdk/dist/sw.js',
          dest: '.'
        }
      ]
    })
  ]
});

Then initialize the client (default path is /sw.js):

const pushClient = new PushClient({
  vapidPublicKey: "YOUR_VAPID_PUBLIC_KEY",
  backendRegisterUrl: "/api/register",
  // serviceWorkerPath: '/sw.js' is the default, no need to specify
});

Note: The ?url import method (e.g., import swUrl from 'pulse-leo-sdk/sw.js?url') is not recommended for service workers due to scope restrictions during development. Use the copy method instead.

Option B: Custom Service Worker

If you need to add your own service worker logic, you can import the SDK's service worker in your own:

// In your custom-sw.js
import "pulse-leo-sdk/sw";

// Add your own service worker logic here
self.addEventListener("install", (event) => {
  console.log("Custom service worker installed");
});

Then set serviceWorkerPath to your custom service worker:

const pushClient = new PushClient({
  vapidPublicKey: "YOUR_VAPID_PUBLIC_KEY",
  backendRegisterUrl: "/api/register",
  serviceWorkerPath: "/custom-sw.js",
});

3. Register for Notifications

Call the register() method, typically in response to a user action (like a button click) to request permission.

const button = document.getElementById("enable-push");
button.addEventListener("click", async () => {
  const success = await pushClient.register();
  if (success) {
    console.log("Successfully subscribed!");
  } else {
    console.error("Failed to subscribe.");
  }
});

4. Check Subscription Status

const isSubscribed = await pushClient.isSubscribed();
if (isSubscribed) {
  // Update UI to show "Subscribed"
}

Configuration Options

| Option | Type | Required | Description | | -------------------- | ------------------------ | -------- | ----------------------------------------------------------------- | | vapidPublicKey | string | Yes | Your VAPID Public Key. | | backendRegisterUrl | string | Yes | Endpoint to send subscription data to. | | serviceWorkerPath | string | No | Path to your service worker (default: /sw.js). | | tags | Record<string, string> | No | Tags to associate with the subscriber (e.g. { topic: "news" }). |

License

MIT