@webmobix/pulse-leo-sdk 0.0.1 → 0.2.1

package/README.md

@@ -5,7 +5,7 @@ A lightweight browser SDK for integrating PulseLeo Push Notifications.
 ## Installation
 
 ```bash
-npm install pulse-leo-sdk
+npm install @webmobix/pulse-leo-sdk
 ```
 
 ## Usage
@@ -15,11 +15,11 @@ npm install pulse-leo-sdk
 Initialize the client with your VAPID Public Key (found in your Dashboard).
 
 ```typescript
-import { PushClient } from "pulse-leo-sdk";
+import { PushClient } from "@webmobix/pulse-leo-sdk";
 
 const pushClient = new PushClient({
   vapidPublicKey: "YOUR_VAPID_PUBLIC_KEY",
-  backendRegisterUrl: "https://api.pulseleo.com/register", // Or your backend proxy
+  backendRegisterUrl: "/api/register", // Or your backend proxy
   serviceWorkerPath: "/sw.js", // Default
   tags: {
     category: "news",
@@ -43,7 +43,7 @@ Add a postinstall script to your `package.json`:
 ```json
 {
   "scripts": {
-    "postinstall": "cp node_modules/pulse-leo-sdk/dist/sw.js public/sw.js"
+    "postinstall": "cp node_modules/@webmobix/pulse-leo-sdk/dist/sw.js public/sw.js"
   }
 }
 ```
@@ -66,7 +66,7 @@ export default defineConfig({
     viteStaticCopy({
       targets: [
         {
-          src: 'node_modules/pulse-leo-sdk/dist/sw.js',
+          src: 'node_modules/@webmobix/pulse-leo-sdk/dist/sw.js',
           dest: '.'
         }
       ]
@@ -75,17 +75,9 @@ export default defineConfig({
 });
 ```
 
-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.
+> `dist/sw.js` is a **single self-contained file** (it imports nothing), so copying just that one file to
+> your site root is all a host needs. (SDK 0.2.0 shipped a `sw.js` that imported a shared chunk and failed
+> to load when copied alone; fixed in 0.2.1 and guarded by a build check.)
 
 #### Option B: Custom Service Worker
 
@@ -93,7 +85,7 @@ If you need to add your own service worker logic, you can import the SDK's servi
 
 ```typescript
 // In your custom-sw.js
-import "pulse-leo-sdk/sw";
+import "@webmobix/pulse-leo-sdk/sw";
 
 // Add your own service worker logic here
 self.addEventListener("install", (event) => {
@@ -116,18 +108,99 @@ const pushClient = new PushClient({
 Call the `register()` method, typically in response to a user action (like a button click) to request permission.
 
 ```typescript
+import { PermissionDeniedError, SubscriptionError } from "@webmobix/pulse-leo-sdk";
+
 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.");
+  try {
+    const success = await pushClient.register();
+    if (success) {
+      console.log("Successfully subscribed!");
+    }
+  } catch (error) {
+    if (error instanceof PermissionDeniedError) {
+      console.log("User denied notification permission");
+    } else if (error instanceof SubscriptionError) {
+      console.error("Subscription failed:", error.message);
+    }
   }
 });
 ```
 
-### 4. Check Subscription Status
+If the browser already has a subscription, `register()` does not call your backend again. When your
+server may have lost the device (for example it was removed from another browser), re-send it with
+`register({ force: true })`; registration is an upsert keyed by endpoint, so this is idempotent.
+
+```typescript
+await pushClient.register({ force: true });
+```
+
+### 4. Unsubscribe from Notifications
+
+```typescript
+const success = await pushClient.unsubscribe();
+if (success) {
+  console.log("Successfully unsubscribed!");
+}
+```
+
+When there is no authenticated backend session any more (after a logout, or a remote removal),
+skip the unregister relay call and only remove the browser subscription:
+
+```typescript
+await pushClient.unsubscribe({ notifyBackend: false });
+```
+
+### 5. Subscriber Check-ins (Activity Analytics)
+
+By default, every successfully displayed push triggers a lightweight
+"check-in" to your backend relay, which PulseLeo uses for monthly
+active-subscriber analytics (a check-in is also recorded when a subscriber
+first registers). No secrets are involved — the service worker posts only
+the subscription endpoint to your relay, which attaches the API key
+server-side:
+
+```typescript
+const pushClient = new PushClient({
+  vapidPublicKey: "YOUR_PUBLIC_KEY",
+  backendRegisterUrl: "/api/push/register",
+  // Required for activity analytics: explicit check-in relay URL.
+  // The SDK never derives it; missing it fails loudly with CheckinConfigError.
+  backendCheckinUrl: "/api/push/checkin",
+});
+```
+
+Example relay route (Express-style pseudocode for your backend):
+
+```js
+app.post("/api/push/checkin", async (req, res) => {
+  await fetch("https://api.pulseleo.com/checkin", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${process.env.PULSE_LEO_TOKEN}`, // never in the browser
+    },
+    body: JSON.stringify({ endpoint: req.body.endpoint }),
+  });
+  res.sendStatus(204);
+});
+```
+
+Push-driven check-ins are throttled (at most one every 6 hours per
+subscriber). If you also want liveness pings while your site is open,
+start the opt-in periodic check-in after registration:
+
+```typescript
+// Fires immediately, then every 6h while the page stays open.
+pushClient.startPeriodicCheckin();
+// Custom interval:
+pushClient.startPeriodicCheckin(60 * 60 * 1000); // hourly
+
+// Stop when appropriate (unsubscribe() stops it automatically):
+pushClient.stopPeriodicCheckin();
+```
+
+### 6. Check Subscription Status
 
 ```typescript
 const isSubscribed = await pushClient.isSubscribed();
@@ -136,15 +209,133 @@ if (isSubscribed) {
 }
 ```
 
+### 6. Check Support and Permission State
+
+```typescript
+import { isPushSupported } from "@webmobix/pulse-leo-sdk";
+
+// Works without a client or VAPID key, so it can gate UI early.
+if (!isPushSupported()) {
+  // Show "not supported in this browser"
+}
+
+const permission = pushClient.getPermissionState();
+// Returns: 'granted', 'denied', 'default', or 'unsupported'
+
+if (permission === 'denied') {
+  // Show message that user needs to enable permissions in browser settings
+}
+```
+
+`pushClient.isSupported()` returns the same value as `isPushSupported()`.
+
+> **Upgrading from 0.1.x:** in browsers without Web Push, `getPermissionState()` now returns
+> `'unsupported'` instead of `'denied'`. Where you only cared about "cannot prompt", treat
+> `'unsupported'` like the old `'denied'`. `PermissionState` is now exported from the package.
+
+### 7. Update Expired Subscription
+
+```typescript
+try {
+  await pushClient.updateSubscription();
+  console.log("Subscription updated!");
+} catch (error) {
+  console.error("Failed to update subscription:", error);
+}
+```
+
+### 9. Event Handling
+
+Subscribe to events for real-time updates:
+
+```typescript
+// Listen for subscription changes
+pushClient.on('subscriptionChange', (data) => {
+  if (data.subscribed) {
+    console.log("User subscribed");
+  } else {
+    console.log("User unsubscribed");
+  }
+});
+
+// Listen for permission changes
+pushClient.on('permissionChange', (data) => {
+  console.log("Permission changed to:", data.permission);
+});
+
+// Remove listener when needed
+const handler = (data) => console.log(data);
+pushClient.on('subscriptionChange', handler);
+pushClient.off('subscriptionChange', handler);
+```
+
 ## Configuration Options
 
 | Option               | Type                     | Required | Description                                                       |
 | -------------------- | ------------------------ | -------- | ----------------------------------------------------------------- |
-| `vapidPublicKey`     | `string`                 | Yes      | Your VAPID Public Key.                                            |
-| `backendRegisterUrl` | `string`                 | Yes      | Endpoint to send subscription data to.                            |
+| `vapidPublicKey`     | `string`                 | Yes      | Your VAPID Public Key (base64url encoded, minimum 87 characters). |
+| `backendRegisterUrl` | `string`                 | Yes*     | Endpoint to send subscription data to. Use `endpoints.register` for new config. |
+| `endpoints`          | `object`                 | No       | Custom endpoint paths `{ register: string, unregister?: string }`. |
+| `headers`            | `Record<string, string>` | No       | Static headers for backend requests (e.g., auth tokens).          |
+| `getHeaders`         | `function`               | No       | Async function returning dynamic headers (e.g., fresh JWT).       |
 | `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" }`). |
+| `backendCheckinUrl`  | `string`                 | No*      | Check-in relay URL for activity analytics (push-receipt + periodic check-ins). Explicit — never derived; missing it throws `CheckinConfigError`. |
+| `retry`              | `object`                 | No       | Retry config `{ maxAttempts?: number, delayMs?: number, backoffMultiplier?: number, shouldRetry?: (status) => boolean }`. See [Retries](#retries). |
+
+*Either `backendRegisterUrl` or `endpoints.register` is required.
+
+*`backendCheckinUrl` is required whenever check-in analytics should be recorded (the dashboard's active-subscriber and inactive-cohort views): without it, register/update fails loudly with `CheckinConfigError` instead of silently skipping check-ins.
+
+## Retries
+
+Register and unregister relay calls are retried up to `maxAttempts` (default 3) with exponential
+backoff, but only when a retry can help: network errors and the statuses `408`, `425`, `429` and
+`5xx`. Any other status (`400`, `401`, `402`, `403`, `404`, ...) fails immediately, so a rejected
+request does not wait through useless retries. `BackendRegistrationError.status` tells you which
+status ended the registration.
+
+Override the decision with `retry.shouldRetry`, which receives the HTTP status (or `undefined` for a
+network failure) and replaces the default for both register and unregister:
+
+```typescript
+const pushClient = new PushClient({
+  vapidPublicKey: "...",
+  backendRegisterUrl: "/api/push/register",
+  backendCheckinUrl: "/api/push/checkin",
+  // My relay answers 503 when the plan's subscriber quota is exhausted: never retry that.
+  retry: { shouldRetry: (status) => status !== 503 },
+});
+```
+
+Use `shouldRetry: () => true` to restore the 0.1.x behaviour of retrying every failure.
+
+## Error Types
+
+The SDK throws typed errors for better handling:
+
+| Error Class           | Code                      | When Thrown                              |
+| --------------------- | ------------------------- | ---------------------------------------- |
+| `PermissionDeniedError` | `PERMISSION_DENIED`       | User denies notification permission      |
+| `SubscriptionError`   | `SUBSCRIPTION_FAILED`     | PushManager subscription fails           |
+| `ValidationError`     | `INVALID_VAPID_KEY`       | VAPID key format is invalid              |
+| `BackendRegistrationError` | `BACKEND_REGISTRATION_FAILED` | Backend registration fails (carries `status`, the HTTP status of the last failed response, or `undefined` for a network failure) |
+| `NotSupportedError`   | `NOT_SUPPORTED`           | Browser doesn't support push             |
+
+## Types
+
+```typescript
+import { PushNotificationPayload } from "@webmobix/pulse-leo-sdk";
+
+// Use for notification data structure
+const notification: PushNotificationPayload = {
+  title: "New Message",
+  body: "You have a new notification",
+  icon: "/icon.png",
+  data: { url: "/messages" }
+};
+```
 
 ## License
 
-MIT
+MIT

package/dist/checkin.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Subscriber check-in plumbing shared by the page context (PushClient) and
+ * the service worker (sw.ts).
+ *
+ * The service worker cannot receive configuration from the page directly, so
+ * the check-in target (the site's backend relay URL) and the subscription
+ * endpoint are exchanged through a small Cache Storage entry. On every push
+ * receipt the service worker reads that entry and fires a check-in to the
+ * site's relay, which forwards it to the PulseLeo API — proving the browser
+ * is still alive (used for monthly activity analytics).
+ */
+/** Configuration cached for the service worker to perform check-ins. */
+export interface CheckinConfig {
+    /** The site's backend relay URL that forwards check-ins to PulseLeo. */
+    checkinUrl: string;
+    /** The push subscription endpoint identifying this browser. */
+    endpoint: string;
+    /** ISO timestamp of the last successful check-in (for throttling). */
+    lastCheckinAt?: string | null;
+}
+/** Cache Storage bucket holding the check-in configuration. */
+export declare const CHECKIN_CACHE_NAME = "pulseleo-checkin";
+/** Synthetic request URL used as the cache key for the config entry. */
+export declare const CHECKIN_CONFIG_URL = "https://pulseleo.internal/checkin-config.json";
+/**
+ * Minimum interval between two check-ins fired by the service worker.
+ * Push-driven check-ins are throttled to avoid hammering the relay; the
+ * monthly aggregation only needs one check-in per month per subscriber.
+ */
+export declare const CHECKIN_THROTTLE_MS: number;
+/**
+ * Returns true when Cache Storage is available in the current context.
+ * Some environments (tests, insecure origins) do not provide it.
+ */
+export declare function isCacheStorageAvailable(): boolean;
+/**
+ * Read the check-in configuration cached by the page.
+ *
+ * @returns The stored config, or null when absent/unavailable.
+ */
+export declare function readCheckinConfig(): Promise<CheckinConfig | null>;
+/**
+ * Persist the check-in configuration for the service worker.
+ *
+ * @param config - The configuration to cache.
+ */
+export declare function writeCheckinConfig(config: CheckinConfig): Promise<void>;
+/**
+ * Remove the cached check-in configuration (called on unsubscribe).
+ */
+export declare function clearCheckinConfig(): Promise<void>;
+/**
+ * Pure throttle check: true when the last check-in is recent enough that a
+ * new one can be skipped.
+ *
+ * @param config - The current check-in config.
+ * @param now - Reference time (defaults to Date.now()).
+ */
+export declare function isCheckinThrottled(config: CheckinConfig, now?: number): boolean;
+/**
+ * POST a check-in to the site's relay endpoint and, on success, record the
+ * time in the cached config so the throttle kicks in for subsequent pushes.
+ *
+ * @param config - The check-in config (relay URL + endpoint).
+ * @param now - Reference time for the throttle bookkeeping (defaults to now).
+ * @returns true when the relay accepted the check-in.
+ */
+export declare function performCheckin(config: CheckinConfig, now?: number): Promise<boolean>;
+/**
+ * Convenience used by the service worker's push handler: read the cached
+ * config, respect the throttle, then perform the check-in.
+ *
+ * @param now - Reference time (defaults to now).
+ * @returns true when a check-in was sent and accepted.
+ */
+export declare function maybeCheckin(now?: number): Promise<boolean>;

package/dist/errors.d.ts

@@ -0,0 +1,52 @@
+export declare enum PushClientErrorCode {
+    PERMISSION_DENIED = "PERMISSION_DENIED",
+    SUBSCRIPTION_FAILED = "SUBSCRIPTION_FAILED",
+    INVALID_VAPID_KEY = "INVALID_VAPID_KEY",
+    UNSUBSCRIPTION_FAILED = "UNSUBSCRIPTION_FAILED",
+    BACKEND_REGISTRATION_FAILED = "BACKEND_REGISTRATION_FAILED",
+    CHECKIN_CONFIG_MISSING = "CHECKIN_CONFIG_MISSING",
+    NOT_SUPPORTED = "NOT_SUPPORTED"
+}
+export declare class PushClientError extends Error {
+    readonly code: PushClientErrorCode;
+    constructor(code: PushClientErrorCode, message: string, options?: ErrorOptions);
+}
+export declare class PermissionDeniedError extends PushClientError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class SubscriptionError extends PushClientError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class ValidationError extends PushClientError {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class UnsubscriptionError extends PushClientError {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Options for {@link BackendRegistrationError}. */
+export interface BackendRegistrationErrorOptions extends ErrorOptions {
+    /** HTTP status of the last failed relay response; omit for network failures. */
+    status?: number;
+}
+export declare class BackendRegistrationError extends PushClientError {
+    /**
+     * HTTP status code of the last failed relay response, or `undefined` when
+     * the last failure was not an HTTP response (network error, timeout).
+     */
+    readonly status?: number;
+    constructor(message: string, options?: BackendRegistrationErrorOptions);
+}
+/**
+ * Thrown when the check-in relay URL is missing: `backendCheckinUrl` is the
+ * required explicit configuration for the activity-analytics check-ins
+ * (push-receipt and periodic). The SDK never guesses the URL, and a missing
+ * one fails loudly instead of silently skipping check-ins — a silent no-op
+ * would make subscriber activity decay to registration-time only without
+ * any detectable signal.
+ */
+export declare class CheckinConfigError extends PushClientError {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export declare class NotSupportedError extends PushClientError {
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/events.d.ts

@@ -0,0 +1,20 @@
+type EventHandler<T = unknown> = (data: T) => void;
+interface SubscriptionChangeEvent {
+    subscribed: boolean;
+}
+interface PermissionChangeEvent {
+    permission: 'granted' | 'denied' | 'default';
+}
+type EventMap = {
+    subscriptionChange: SubscriptionChangeEvent;
+    permissionChange: PermissionChangeEvent;
+};
+type EventKey = keyof EventMap;
+export declare class PushClientEventEmitter {
+    private listeners;
+    on<K extends EventKey>(event: K, handler: EventHandler<EventMap[K]>): void;
+    off<K extends EventKey>(event: K, handler: EventHandler<EventMap[K]>): void;
+    emit<K extends EventKey>(event: K, data: EventMap[K]): void;
+    removeAllListeners(event?: EventKey): void;
+}
+export type { EventHandler, EventMap, SubscriptionChangeEvent, PermissionChangeEvent };

package/dist/index.d.ts

@@ -1,48 +1,70 @@
-import { PushClientOptions } from './types';
+import { PermissionState, PushClientOptions, RegisterOptions, UnsubscribeOptions } from './types';
+import { PushClientEventEmitter, EventMap, EventHandler } from './events';
 export * from './types';
 export * from './utils';
+export * from './vapid';
+export * from './errors';
+export * from './events';
+export * from './checkin';
 /**
- * Client for managing push notifications.
+ * Default retry policy for relay calls: retry network failures (no status),
+ * request timeouts (408), too-early (425), rate limiting (429) and server errors
+ * (5xx). Every other status (400, 401, 402, 403, 404, ...) cannot succeed on a
+ * retry and fails immediately.
  */
-export declare class PushClient {
+export declare function defaultShouldRetry(status: number | undefined): boolean;
+export declare class PushClient extends PushClientEventEmitter {
     private config;
-    /**
-     * Creates an instance of PushClient.
-     * @param config - The configuration options for the client.
-     */
+    private retryConfig;
+    private checkinTimer;
     constructor(config: PushClientOptions);
-    /**
-     * Checks if the client is already subscribed to push notifications.
-     * @returns A promise that resolves to true if subscribed, false otherwise.
-     */
+    on<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
+    off<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
     isSubscribed(): Promise<boolean>;
+    getPermissionState(): PermissionState;
+    register(options?: RegisterOptions): Promise<boolean>;
+    unsubscribe(options?: UnsubscribeOptions): Promise<boolean>;
+    updateSubscription(): 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.
+     * Whether this browser supports Web Push (service worker, PushManager and
+     * Notification). Same result as {@link isPushSupported}, which needs no client.
      */
-    register(): Promise<boolean>;
+    isSupported(): boolean;
+    private validateConfig;
+    private getRegisterUrl;
+    private getUnregisterUrl;
     /**
-     * Checks if push notifications are supported in the browser.
-     * @returns True if supported, false otherwise.
+     * Requires an explicit `backendCheckinUrl`; throws {@link CheckinConfigError}
+     * instead of silently skipping check-ins, so a misconfigured integration
+     * fails loudly before any subscription is created or reused.
+     *
+     * @throws {CheckinConfigError} When `backendCheckinUrl` is not configured.
      */
-    private isSupported;
+    private assertCheckinConfigured;
     /**
-     * Validates the configuration.
-     * @returns True if valid, false otherwise.
+     * Cache the check-in configuration for the service worker so received
+     * pushes can report liveness.
+     *
+     * @param subscription - The push subscription being registered.
+     * @throws {CheckinConfigError} When `backendCheckinUrl` is not configured.
      */
-    private validateConfig;
+    private persistCheckinConfig;
     /**
-     * Registers the service worker.
-     * @returns A promise that resolves with the ServiceWorkerRegistration.
+     * Opt-in periodic check-in: reports liveness immediately and then every
+     * `intervalMs` while the page stays open, in addition to the automatic
+     * push-driven check-ins. Intended for quota-accurate monthly actives.
+     *
+     * @param intervalMs - Check-in interval in milliseconds (default 6h).
+     * @throws {CheckinConfigError} When `backendCheckinUrl` is not configured —
+     *   periodic check-ins would silently do nothing, which must fail loudly.
      */
+    startPeriodicCheckin(intervalMs?: number): void;
+    /** Stop the periodic check-in started by startPeriodicCheckin. */
+    stopPeriodicCheckin(): void;
+    private getHeaders;
     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;
+    private sleep;
+    private backoffDelay;
+    private sendToBackendWithRetry;
+    private sendUnregisterToBackendWithRetry;
 }