@webmobix/pulse-leo-sdk 0.0.1

package/README.md

@@ -0,0 +1,150 @@
+# PulseLeo SDK
+
+A lightweight browser SDK for integrating PulseLeo Push Notifications.
+
+## Installation
+
+```bash
+npm install pulse-leo-sdk
+```
+
+## Usage
+
+### 1. Initialize
+
+Initialize the client with your VAPID Public Key (found in your Dashboard).
+
+```typescript
+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`:
+
+```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`:
+
+```bash
+npm install -D vite-plugin-static-copy
+```
+
+Add to your `vite.config.ts`:
+
+```typescript
+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`):
+
+```typescript
+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:
+
+```typescript
+// 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:
+
+```typescript
+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.
+
+```typescript
+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
+
+```typescript
+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

package/dist/index.d.ts

@@ -0,0 +1,48 @@
+import { PushClientOptions } from './types';
+export * from './types';
+export * from './utils';
+/**
+ * Client for managing push notifications.
+ */
+export declare class PushClient {
+    private config;
+    /**
+     * Creates an instance of PushClient.
+     * @param config - The configuration options for the client.
+     */
+    constructor(config: PushClientOptions);
+    /**
+     * Checks if the client is already subscribed to push notifications.
+     * @returns A promise that resolves to true if subscribed, false otherwise.
+     */
+    isSubscribed(): Promise<boolean>;
+    /**
+     * Registers the client for push notifications.
+     * Checks support, config, and existing subscription.
+     * Requests permission and registers with backend if necessary.
+     * @returns A promise that resolves to true if registration is successful (or already exists), false otherwise.
+     */
+    register(): Promise<boolean>;
+    /**
+     * Checks if push notifications are supported in the browser.
+     * @returns True if supported, false otherwise.
+     */
+    private isSupported;
+    /**
+     * Validates the configuration.
+     * @returns True if valid, false otherwise.
+     */
+    private validateConfig;
+    /**
+     * Registers the service worker.
+     * @returns A promise that resolves with the ServiceWorkerRegistration.
+     */
+    private registerServiceWorker;
+    /**
+     * Sends the subscription to the backend.
+     * @param subscription - The push subscription object.
+     * @returns A promise that resolves when the subscription is sent.
+     * @throws Will throw an error if the backend request fails.
+     */
+    private sendToBackend;
+}

package/dist/index.js

@@ -0,0 +1,125 @@
+function o(n) {
+  const e = "=".repeat((4 - n.length % 4) % 4), i = (n + e).replace(/-/g, "+").replace(/_/g, "/"), r = atob(i), s = new Uint8Array(r.length);
+  for (let t = 0; t < r.length; ++t)
+    s[t] = r.charCodeAt(t);
+  return s;
+}
+function a(n) {
+  const e = new Uint8Array(n);
+  let i = "";
+  for (let r = 0; r < e.byteLength; r++)
+    i += String.fromCharCode(e[r]);
+  return btoa(i).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+class c {
+  config;
+  /**
+   * Creates an instance of PushClient.
+   * @param config - The configuration options for the client.
+   */
+  constructor(e) {
+    console.debug("PushClient initialized"), this.config = e;
+  }
+  /**
+   * Checks if the client is already subscribed to push notifications.
+   * @returns A promise that resolves to true if subscribed, false otherwise.
+   */
+  async isSubscribed() {
+    if (!this.isSupported())
+      return !1;
+    const e = await navigator.serviceWorker.getRegistration();
+    return e ? !!await e.pushManager.getSubscription() : !1;
+  }
+  /**
+   * Registers the client for push notifications.
+   * Checks support, config, and existing subscription.
+   * Requests permission and registers with backend if necessary.
+   * @returns A promise that resolves to true if registration is successful (or already exists), false otherwise.
+   */
+  async register() {
+    console.debug("Registering push notifications...");
+    try {
+      if (!this.isSupported())
+        return console.warn("Push notifications are not supported in this browser."), !1;
+      if (!this.validateConfig())
+        return console.error("Invalid PushClient configuration."), !1;
+      const e = await this.registerServiceWorker();
+      if (await e.pushManager.getSubscription())
+        return !0;
+      const r = await Notification.requestPermission();
+      if (console.debug(`Notification permission: ${r}`), r !== "granted")
+        return console.warn("Notification permission denied."), !1;
+      const s = o(
+        this.config.vapidPublicKey
+      ), t = await e.pushManager.subscribe({
+        userVisibleOnly: !0,
+        applicationServerKey: s
+      });
+      return await this.sendToBackend(t), !0;
+    } catch (e) {
+      return console.error("Failed to register push client:", e), !1;
+    }
+  }
+  /**
+   * Checks if push notifications are supported in the browser.
+   * @returns True if supported, false otherwise.
+   */
+  isSupported() {
+    return typeof window < "u" && "serviceWorker" in navigator && !!navigator.serviceWorker && "PushManager" in window && "Notification" in window;
+  }
+  /**
+   * Validates the configuration.
+   * @returns True if valid, false otherwise.
+   */
+  validateConfig() {
+    return !!(this.config.vapidPublicKey && this.config.backendRegisterUrl);
+  }
+  /**
+   * Registers the service worker.
+   * @returns A promise that resolves with the ServiceWorkerRegistration.
+   */
+  async registerServiceWorker() {
+    const e = this.config.serviceWorkerPath || "/sw.js";
+    console.debug(`[PushClient] Registering service worker at: ${e}`);
+    try {
+      const i = await navigator.serviceWorker.register(e, {
+        scope: "/"
+      });
+      console.debug("[PushClient] Service Worker registered:", i), console.debug(
+        `[PushClient] SW state: ${i.installing ? "installing" : i.waiting ? "waiting" : i.active ? "active" : "unknown"}`
+      );
+      const r = await navigator.serviceWorker.ready;
+      return console.debug("[PushClient] Service Worker ready"), r;
+    } catch (i) {
+      throw console.error("[PushClient] Failed to register service worker:", i), i;
+    }
+  }
+  /**
+   * Sends the subscription to the backend.
+   * @param subscription - The push subscription object.
+   * @returns A promise that resolves when the subscription is sent.
+   * @throws Will throw an error if the backend request fails.
+   */
+  async sendToBackend(e) {
+    console.debug("[PushClient] Sending subscription to backend", e);
+    const i = {
+      ...e.toJSON(),
+      tags: this.config.tags
+    }, r = await fetch(this.config.backendRegisterUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(i)
+    });
+    if (!r.ok)
+      throw new Error(
+        `Failed to register push subscription: ${r.statusText}`
+      );
+  }
+}
+export {
+  c as PushClient,
+  a as arrayBufferToUrlBase64,
+  o as urlBase64ToUint8Array
+};

package/dist/sw.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/sw.js

@@ -0,0 +1,55 @@
+const n = self;
+n.addEventListener("install", (i) => {
+  console.log("[SW] Service Worker installing..."), i.waitUntil(n.skipWaiting());
+});
+n.addEventListener("activate", (i) => {
+  console.log("[SW] Service Worker activated"), i.waitUntil(n.clients.claim());
+});
+n.addEventListener("push", (i) => {
+  if (!i.data) {
+    console.warn("Push event received with no data.");
+    return;
+  }
+  try {
+    const t = i.data.json(), o = t.title || "Notification", a = {
+      body: t.body,
+      icon: t.icon,
+      badge: t.badge,
+      data: t.data,
+      tag: t.tag,
+      renotify: t.renotify,
+      requireInteraction: t.requireInteraction,
+      silent: t.silent,
+      timestamp: t.timestamp,
+      actions: t.actions,
+      dir: t.dir,
+      lang: t.lang,
+      vibrate: t.vibrate,
+      image: t.image
+    };
+    i.waitUntil(n.registration.showNotification(o, a));
+  } catch (t) {
+    console.error("Error handling push event:", t);
+  }
+});
+n.addEventListener("notificationclick", (i) => {
+  i.notification.close();
+  const t = i.notification.data?.url || "/", o = n.clients.matchAll({
+    type: "window",
+    includeUncontrolled: !0
+  }).then((a) => {
+    let e = null;
+    for (const r of a) {
+      const l = new URL(r.url, self.location.href), c = new URL(t, self.location.href);
+      if (l.href === c.href) {
+        e = r;
+        break;
+      }
+    }
+    if (e && "focus" in e)
+      return e.focus();
+    if (n.clients.openWindow)
+      return n.clients.openWindow(t);
+  });
+  i.waitUntil(o);
+});

package/dist/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Options for initializing the PushClient
+ */
+export interface PushClientOptions {
+    /**
+     * The public VAPID key for the push service.
+     */
+    vapidPublicKey: string;
+    /**
+     * The path to the service worker file (e.g., "/sw.js").
+     * Defaults to "/sw.js" if not provided.
+     */
+    serviceWorkerPath?: string;
+    /**
+     * The URL of your backend endpoint that registers the subscription with PulseLeo.
+     */
+    backendRegisterUrl: string;
+    /**
+     * Optional tags to associate with the subscription (key-value pairs).
+     * Example: { category: "news", plan: "premium" }
+     */
+    tags?: Record<string, string>;
+}
+/**
+ * Data structure required for push subscription
+ */
+export interface PushSubscriptionData {
+    endpoint: string;
+    expirationTime?: number | null;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    tags?: Record<string, string>;
+}

package/dist/utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Converts a VAPID public key (base64url string) to a Uint8Array.
+ * @param base64String The base64url encoded VAPID public key.
+ * @returns The Uint8Array representation of the key.
+ */
+export declare function urlBase64ToUint8Array(base64String: string): Uint8Array;
+/**
+ * Converts an ArrayBuffer or Uint8Array to a base64url string.
+ * @param buffer The buffer to convert.
+ * @returns The base64url string.
+ */
+export declare function arrayBufferToUrlBase64(buffer: ArrayBuffer | Uint8Array): string;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@webmobix/pulse-leo-sdk",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./sw.js": "./dist/sw.js",
+    "./sw": "./dist/sw.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@playwright/test": "^1.56.1",
+    "@types/node": "^22.19.1",
+    "happy-dom": "^20.0.10",
+    "typescript": "^5.9.3",
+    "vite": "^7.2.4",
+    "vite-plugin-dts": "^4.5.4",
+    "vitest": "^4.0.13"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc && tsc -p tsconfig.worker.json && vite build",
+    "test": "vitest"
+  }
+}