@research-ag/ic-web-push 0.1.0

package/README.md

@@ -0,0 +1,241 @@
+# IC Web Push (browser SDK)
+
+IC Web Push is a tiny browser-side SDK that wires your web app to the Internet Computer (IC) notification canister to enable standards-based Web Push notifications.
+
+- Works with the standard Push API in Safari, Chromium, Firefox, Edge, and Android browsers.
+- Coexists with your existing service worker by using a separate scope.
+- Handles subscription, unsubscription, and application registration against the IC notification canister.
+
+Default notification canister ID: `zjwxf-jyaaa-aaaao-a43ca-cai` (configurable).
+
+## High-level architecture
+
+1. Your app registers a dedicated service worker (SW) under a separate scope (e.g., `/ic-web-push/`). This SW only handles displaying push notifications and reacting to clicks.
+2. The SDK lists available relayers from the IC notification canister, picks one (random by default), fetches its VAPID public key, and subscribes the browser via `PushManager` using that key.
+3. The resulting `PushSubscription` plus the chosen relayer principal is sent to the notification canister and associated with your application canister principal.
+4. Your backend canister sends notifications to the notification canister; each subscription is routed to its chosen relayer's queue for delivery via Web Push.
+
+## Files in this module
+
+- `index.ts` — public API surface for initializing and controlling subscriptions.
+- `sw.js` — the service worker that displays notifications and handles clicks.
+
+## Coexisting with your app's service worker
+
+Service workers are scoped by path. To avoid conflicts with your main app SW, IC Web Push uses its own scope, by default `/ic-web-push/`, and assumes its file is hosted at `/ic-web-push-sw.js` in your web root.
+
+You may keep your app's own `sw.js` for app caching, offline, etc. This SDK's SW will not interfere because it is registered under a separate scope and only handles `push` and `notificationclick` events within that scope.
+
+## Hosting the service worker file
+
+Place the service worker file at the web root so it can be served at `/ic-web-push-sw.js`. There are multiple ways to do this depending on your bundler:
+
+- Vite: copy `src/ic-web-push/sw.js` into `public/ic-web-push-sw.js` (the `public` folder is served at web root). Example:
+  - Copy once manually, or
+  - Add a small build step/plugin to copy the file on build
+- CRA/Next.js/others: add a copy step to move `sw.js` to the output root as `ic-web-push-sw.js`.
+
+You can also customize the path/scope via `init()` if you prefer a different location.
+
+## Usage
+
+1) Initialize the SDK early in app startup:
+
+```ts
+import icWebPush from 'ic-web-push';
+import { HttpAgent } from '@dfinity/agent';
+
+const agent = new HttpAgent({ host: 'https://ic0.app' });
+// If developing locally against a replica, you may need:
+// await agent.fetchRootKey();
+
+icWebPush.init({
+  agent,
+  // Notification canister ID (defaults to mainnet id):
+  // notificationCanisterId: 'zjwxf-jyaaa-aaaao-a43ca-cai',
+  // Your application canister principal (REQUIRED to subscribe):
+  applicationCanisterId: '<your app canister id>',
+  // Optional: customize where the service worker is served from
+  serviceWorkerPath: '/ic-web-push-sw.js',
+  serviceWorkerScope: '/ic-web-push/',
+});
+
+icWebPush.setDebug(true); // optional
+```
+
+2) Register the service worker:
+
+```ts
+await icWebPush.registerServiceWorker();
+```
+
+3) Request permission (if needed) and subscribe:
+
+```ts
+// One-shot convenience that registers SW, ensures permission, and subscribes
+await icWebPush.ensureSubscribed({ requestPermissionIfNeeded: true });
+
+// Or do it step-by-step and pick a relayer explicitly
+if (await icWebPush.getPermissionStatus() !== 'granted') {
+  await icWebPush.requestPermission();
+}
+
+// Option A: pick a random relayer
+const relayer = await icWebPush.chooseRandomRelayer();
+if (!relayer) throw new Error('No relayers available');
+await icWebPush.subscribe({ relayer });
+
+// Option B: list relayers and choose one by your own policy
+const relayers = await icWebPush.listRelayers();
+// e.g., pick the first or prefer by description
+await icWebPush.subscribe({ relayer: relayers[0].relayer });
+```
+
+4) Unsubscribe later (optional):
+
+```ts
+await icWebPush.unsubscribe();
+// Or to remove all subscriptions for your app principal on-chain:
+await icWebPush.unsubscribeAll();
+```
+
+
+## API reference
+
+- `init(config)` — initializes SDK. Options:
+  - `agent` (HttpAgent): an agent for interaction with IC. Should use user's identity.
+  - `notificationCanisterId` (string): notification canister ID, default mainnet ID.
+  - `applicationCanisterId` (string): your app canister principal. Required for `subscribe`/`unsubscribeAll`.
+  - `serviceWorkerPath` (string): where the SW file is served from. Default `/ic-web-push-sw.js`.
+  - `serviceWorkerScope` (string): SW scope. Default `/ic-web-push/`.
+
+- `setDebug(enabled)` — toggles debug logs.
+- `registerServiceWorker()` — registers the SW at the configured path/scope.
+- `getPermissionStatus()` — returns the current `Notification.permission`.
+- `requestPermission()` — prompts the browser permission dialog.
+- `subscribe({ requestPermissionIfNeeded? })` — creates a push subscription and registers it on-chain.
+- `ensureSubscribed({ requestPermissionIfNeeded? })` — convenience wrapper to do SW, permission, and subscription together.
+- `getSubscription()` — resolves the current `PushSubscription` or `null`.
+- `isSubscribed()` — boolean indicating whether a subscription exists locally.
+- `unsubscribe()` — removes the local subscription and tries to unregister it on the canister.
+- `unsubscribeAll()` — unregisters all subscriptions for the configured application principal on the canister.
+
+## Service worker behavior
+
+This SDK ships a dedicated service worker (`sw.js`) intended to live under its own scope (recommended: `/ic-web-push/`) and be served from your web root as `/ic-web-push-sw.js`. It is designed to coexist with your app’s main service worker without conflict. The worker implements the following:
+
+- `install`
+  - Calls `self.skipWaiting()` so that updates to the worker take effect immediately after install.
+- `activate`
+  - Calls `self.clients.claim()` to take control of pages under its scope without a manual reload.
+- `push`
+  - Parses a JSON payload (if present). Robust to missing/invalid payloads and falls back to a generic notification.
+  - Supported payload fields (top-level preferred; `data.*` also accepted for backward compatibility):
+    - `title` (string): Notification title. Default: `"New notification"`.
+    - `content` (string): Notification text; mapped to Notification API `body`. Default: `"You have a new message"`.
+    - `url` (string): A URL to open/focus when the notification is clicked. May also be provided as `data.url`.
+    - `actions` (array): Standard Notification API actions.
+    - `requireInteraction` (boolean): If `true`, the notification stays until user interaction.
+    - `tag` (string): Notification tag for collapsing/updating and for later clearing.
+    - `data` (object): Arbitrary extra fields; merged into the notification `data` object. The worker ensures `data.url` is set to the resolved URL.
+  - Display options applied by default:
+    - `icon` and `badge` default to `/favicon.ico` (override by editing `sw.js`).
+    - If `tag` is provided, it is set on the notification so later notifications with the same tag replace or group, per browser behavior.
+  - Example payload sent by your canister (matches `NotificationBody`):
+    ```json
+    {
+      "title": "New message",
+      "content": "You received a message",
+      "url": "/inbox/123",
+      "tag": "chat-123"
+    }
+    ```
+- `message`
+  - Listens for `{ type: 'CLEAR_NOTIFICATIONS_BY_TAG', tag: string }` to programmatically close notifications with the given tag.
+  - Uses `registration.getNotifications({ includeTriggered: true })` when supported, with a safe fallback to `getNotifications()`.
+  - Example from a page context (any controlled client under the SW scope):
+    ```ts
+    navigator.serviceWorker.controller?.postMessage({
+      type: 'CLEAR_NOTIFICATIONS_BY_TAG',
+      tag: 'chat-123',
+    });
+    ```
+- `notificationclick`
+  - Closes the clicked notification.
+  - Resolves a target URL from `notification.data.url` (defaults to `/`).
+  - Looks for an existing same-origin window client and, if found:
+    - Focuses it.
+    - Tries to `postMessage({ type: 'OPEN_URL', url })` so the app can handle in-app routing/session flags.
+    - As a safe fallback, if the client is not at the origin root and the href differs, calls `client.navigate(url)`.
+  - If no suitable client exists, opens a new window via `clients.openWindow(url)`.
+
+You can customize icons, default texts, or add behavior by editing `src/ic-web-push/sw.js` before copying it into your build’s web root as `ic-web-push-sw.js`.
+
+### Page <-> SW messaging: handling OPEN_URL
+
+When a notification is clicked, the SW first tries to notify an existing tab using a message. In your application code, you may listen to this message to perform client-side routing instead of a hard navigation:
+
+```ts
+if ('serviceWorker' in navigator) {
+  navigator.serviceWorker.addEventListener('message', (event) => {
+    const msg = event.data;
+    if (msg?.type === 'OPEN_URL' && typeof msg.url === 'string') {
+      // App-specific navigation, e.g., using your router
+      // router.push(new URL(msg.url, location.origin).pathname);
+      // Or simply: location.href = msg.url;
+    }
+  });
+}
+```
+
+## Integration example (Vite + the provided chat_frontend)
+
+1. Copy the service worker to the example's public root:
+   - Copy `src/ic-web-push/sw.js` to `example/chat_frontend/public/ic-web-push-sw.js`.
+
+2. Initialize and subscribe in your app code, e.g., `example/chat_frontend/src/App.jsx`:
+
+```jsx
+import { useEffect } from 'react';
+import icWebPush from 'ic-web-push';
+import { HttpAgent } from '@dfinity/agent';
+
+export default function App() {
+  useEffect(() => {
+    icWebPush.init({
+      agent: new HttpAgent(),
+      applicationCanisterId: '<chat_backend_canister_id>',
+      // notificationCanisterId: '<override if not using default>'
+    });
+    icWebPush.ensureSubscribed({ requestPermissionIfNeeded: true }).catch(console.error);
+  }, []);
+
+  return <div>Chat app with IC Web Push</div>;
+}
+```
+
+3. Start the dev server. Verify you see the permission prompt and a registered service worker under Application > Service Workers in DevTools.
+
+## Sending notifications
+
+From your canister or backend, call `sendNotifications` with a vector of `(principal, NotificationBody)` pairs on the notification canister. The `principal` should be your application canister principal that was used when registering subscriptions.
+
+`NotificationBody` schema:
+```candid
+record {
+  title: text;
+  content: text;
+  url: opt text;
+  tag: opt text;
+}
+```
+
+Refer to the canister Candid (`src/notification-canister/notification_canister.did`) for the full interface. On-chain sending uses `sendNotifications(principal, NotificationBody)`.
+
+## Troubleshooting
+
+- Ensure HTTPS and a secure origin. Service workers and Push require secure contexts.
+- Make sure the SW file is actually served at the path you configured in `init()`.
+- If subscription fails, check that the VAPID key is being fetched successfully from the notification canister.
+- If notifications do not appear, ensure the notification payload fields match what your SW expects, and that the browser has permission granted.
+- Some desktop browsers block notifications when the window is focused; try sending while unfocused or check OS notification settings.

package/dist/declarations/notification_canister/index.d.ts

@@ -0,0 +1,45 @@
+import type { ActorConfig, ActorSubclass, Agent, HttpAgentOptions, } from "@dfinity/agent";
+import type { Principal } from "@dfinity/principal";
+import type { IDL } from "@dfinity/candid";
+
+import { _SERVICE } from './notification_canister.did';
+
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const canisterId: string;
+
+export declare interface CreateActorOptions {
+  /**
+   * @see {@link Agent}
+   */
+  agent?: Agent;
+  /**
+   * @see {@link HttpAgentOptions}
+   */
+  agentOptions?: HttpAgentOptions;
+  /**
+   * @see {@link ActorConfig}
+   */
+  actorOptions?: ActorConfig;
+}
+
+/**
+ * Intializes an {@link ActorSubclass}, configured with the provided SERVICE interface of a canister.
+ * @constructs {@link ActorSubClass}
+ * @param {string | Principal} canisterId - ID of the canister the {@link Actor} will talk to
+ * @param {CreateActorOptions} options - see {@link CreateActorOptions}
+ * @param {CreateActorOptions["agent"]} options.agent - a pre-configured agent you'd like to use. Supercedes agentOptions
+ * @param {CreateActorOptions["agentOptions"]} options.agentOptions - options to set up a new agent
+ * @see {@link HttpAgentOptions}
+ * @param {CreateActorOptions["actorOptions"]} options.actorOptions - options for the Actor
+ * @see {@link ActorConfig}
+ */
+export declare const createActor: (
+  canisterId: string | Principal,
+  options?: CreateActorOptions
+) => ActorSubclass<_SERVICE>;
+
+/**
+ * Intialized Actor using default settings, ready to talk to a canister using its candid interface
+ * @constructs {@link ActorSubClass}
+ */
+export declare const notification_canister: ActorSubclass<_SERVICE>;

package/dist/declarations/notification_canister/index.js

@@ -0,0 +1,43 @@
+import {Actor, HttpAgent} from "@dfinity/agent";
+
+// Imports and re-exports candid interface
+import {idlFactory} from "./notification_canister.did.js";
+
+export {idlFactory} from "./notification_canister.did.js";
+
+/* CANISTER_ID is replaced by webpack based on node environment
+ * Note: canister environment variable will be standardized as
+ * process.env.CANISTER_ID_<CANISTER_NAME_UPPERCASE>
+ * beginning in dfx 0.15.0
+ */
+export const canisterId =
+    process.env.CANISTER_ID_NOTIFICATION_CANISTER;
+
+export const createActor = (canisterId, options = {}) => {
+    const agent = options.agent || new HttpAgent({...options.agentOptions});
+
+    if (options.agent && options.agentOptions) {
+        console.warn(
+            "Detected both agent and agentOptions passed to createActor. Ignoring agentOptions and proceeding with the provided agent."
+        );
+    }
+
+    // Fetch root key for certificate validation during development
+    if (process.env.DFX_NETWORK !== "ic") {
+        agent.fetchRootKey().catch((err) => {
+            console.warn(
+                "Unable to fetch root key. Check to ensure that your local replica is running"
+            );
+            console.error(err);
+        });
+    }
+
+    // Creates an actor with using the candid interface and the HttpAgent
+    return Actor.createActor(idlFactory, {
+        agent,
+        canisterId,
+        ...options.actorOptions,
+    });
+};
+
+export const notification_canister = canisterId ? createActor(canisterId) : undefined;

package/dist/declarations/notification_canister/notification_canister.did.d.ts

@@ -0,0 +1,35 @@
+import type { Principal } from '@dfinity/principal';
+import type { ActorMethod } from '@dfinity/agent';
+import type { IDL } from '@dfinity/candid';
+
+export interface RelayerInfo {
+  'relayer': Principal,
+  'description': string,
+  'lastUpdatedAt': bigint,
+  'vapid_public_key': string,
+  'registeredAt': bigint,
+}
+
+export interface Subscription {
+  'endpoint': string,
+  'keys': SubscriptionKeys,
+  'relayer': Principal,
+  'expirationTime': [] | [bigint],
+}
+
+export interface SubscriptionKeys {
+  'auth': string,
+  'p256dh': string
+}
+
+export interface _SERVICE {
+  'getVapidPublicKey': ActorMethod<[Principal], string>,
+  'hasSubscription': ActorMethod<[Principal, string], boolean>,
+  'listRelayers': ActorMethod<[], Array<RelayerInfo>>,
+  'subscribe': ActorMethod<[Principal, Subscription], undefined>,
+  'unsubscribe': ActorMethod<[Principal, string], undefined>,
+  'unsubscribeAll': ActorMethod<[Principal], undefined>,
+}
+
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];

package/dist/declarations/notification_canister/notification_canister.did.js

@@ -0,0 +1,34 @@
+export const idlFactory = ({IDL}) => {
+    const RelayerInfo = IDL.Record({
+        'relayer': IDL.Principal,
+        'description': IDL.Text,
+        'lastUpdatedAt': IDL.Nat64,
+        'vapid_public_key': IDL.Text,
+        'registeredAt': IDL.Nat64,
+    });
+    const SubscriptionKeys = IDL.Record({
+        'auth': IDL.Text,
+        'p256dh': IDL.Text,
+    });
+    const Subscription = IDL.Record({
+        'endpoint': IDL.Text,
+        'keys': SubscriptionKeys,
+        'relayer': IDL.Principal,
+        'expirationTime': IDL.Opt(IDL.Nat),
+    });
+    return IDL.Service({
+        'getVapidPublicKey': IDL.Func([IDL.Principal], [IDL.Text], ['query']),
+        'hasSubscription': IDL.Func(
+            [IDL.Principal, IDL.Text],
+            [IDL.Bool],
+            ['query'],
+        ),
+        'listRelayers': IDL.Func([], [IDL.Vec(RelayerInfo)], ['query']),
+        'subscribe': IDL.Func([IDL.Principal, Subscription], [], []),
+        'unsubscribe': IDL.Func([IDL.Principal, IDL.Text], [], []),
+        'unsubscribeAll': IDL.Func([IDL.Principal], [], []),
+    });
+};
+export const init = ({IDL}) => {
+    return [];
+};

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+import { HttpAgent } from '@dfinity/agent';
+import { Principal } from '@dfinity/principal';
+export type IcWebPushConfig = {
+    agent: HttpAgent;
+    /** Notification canister ID (Principal text). Defaults to known mainnet ID. */
+    notificationCanisterId?: string;
+    /** Your application canister ID (Principal text) to associate subscriptions with. REQUIRED for subscribe(). */
+    applicationCanisterId?: string;
+    /** Path to the service worker file within your web root. Default: '/ic-web-push-sw.js' */
+    serviceWorkerPath?: string;
+    /** Service worker scope. Default: '/ic-web-push/' */
+    serviceWorkerScope?: string;
+};
+export type SubscribeOptions = {
+    requestPermissionIfNeeded?: boolean;
+    relayer?: string | Principal;
+};
+export declare function setDebug(enabled: boolean): void;
+export declare function setDebugAlerts(enabled: boolean): void;
+export declare function init(config: IcWebPushConfig): void;
+export declare function getPermissionStatus(): Promise<NotificationPermission>;
+export declare function requestPermission(): Promise<NotificationPermission>;
+export declare function registerServiceWorker(): Promise<ServiceWorkerRegistration | null>;
+export declare function ensurePushSupported(): boolean;
+export type RelayerInfo = {
+    relayer: Principal;
+    vapid_public_key: string;
+    registeredAt: bigint;
+    lastUpdatedAt: bigint;
+    description: string;
+};
+export declare function listRelayers(): Promise<RelayerInfo[]>;
+export declare function chooseRandomRelayer(): Promise<Principal | null>;
+export declare function getVapidPublicKey(relayer: string | Principal): Promise<string>;
+export declare function getSubscription(): Promise<PushSubscription | null>;
+export declare function isSubscribed(): Promise<boolean>;
+/** Subscribe the browser and register the subscription on the notification canister. */
+export declare function subscribe(options?: SubscribeOptions): Promise<PushSubscription>;
+/** Unsubscribe from browser and unregister from the notification canister. */
+export declare function unsubscribe(): Promise<void>;
+/** Unregister all subscriptions for this application principal on the canister. */
+export declare function unsubscribeAll(): Promise<void>;
+export declare function ensureSubscribed(options?: SubscribeOptions): Promise<PushSubscription>;
+export type IcWebPushPublicAPI = {
+    init: typeof init;
+    registerServiceWorker: typeof registerServiceWorker;
+    requestPermission: typeof requestPermission;
+    getPermissionStatus: typeof getPermissionStatus;
+    listRelayers: typeof listRelayers;
+    chooseRandomRelayer: typeof chooseRandomRelayer;
+    getVapidPublicKey: typeof getVapidPublicKey;
+    subscribe: typeof subscribe;
+    unsubscribe: typeof unsubscribe;
+    unsubscribeAll: typeof unsubscribeAll;
+    ensureSubscribed: typeof ensureSubscribed;
+    getSubscription: typeof getSubscription;
+    isSubscribed: typeof isSubscribed;
+    setDebug: typeof setDebug;
+    setDebugAlerts: typeof setDebugAlerts;
+};
+declare const api: IcWebPushPublicAPI;
+export default api;

package/dist/index.js

@@ -0,0 +1,365 @@
+import { Actor } from '@dfinity/agent';
+import { Principal } from '@dfinity/principal';
+import { idlFactory as notificationIdlFactory } from './declarations/notification_canister/notification_canister.did.js';
+const DEFAULTS = {
+    notificationCanisterId: 'zjwxf-jyaaa-aaaao-a43ca-cai',
+    serviceWorkerPath: '/ic-web-push-sw.js',
+    serviceWorkerScope: '/ic-web-push/',
+};
+let _config = { ...DEFAULTS };
+let _actor = null;
+let _debug = false;
+let _debugAlerts = false;
+function dbg(...args) {
+    if (_debug) {
+        console.log('[ic-web-push]', ...args);
+        if (_debugAlerts) {
+            alert('[ic-web-push] ' + args.map(x => JSON.stringify(x)).join(', '));
+        }
+    }
+}
+export function setDebug(enabled) {
+    _debug = enabled;
+}
+export function setDebugAlerts(enabled) {
+    _debugAlerts = enabled;
+}
+export function init(config) {
+    _config = {
+        agent: config.agent,
+        notificationCanisterId: config?.notificationCanisterId ?? DEFAULTS.notificationCanisterId,
+        serviceWorkerPath: config?.serviceWorkerPath ?? DEFAULTS.serviceWorkerPath,
+        serviceWorkerScope: config?.serviceWorkerScope ?? DEFAULTS.serviceWorkerScope,
+        applicationCanisterId: config?.applicationCanisterId,
+    };
+    _actor = null;
+    dbg('Initialized with config', _config);
+}
+function requireWindow() {
+    if (typeof window === 'undefined')
+        throw new Error('ic-web-push: must be used in a browser context');
+    return window;
+}
+async function getActor() {
+    if (_actor)
+        return _actor;
+    if (!_config || !_config.agent) {
+        throw new Error('ic-web-push: init() must be called with an HttpAgent before use');
+    }
+    const agent = _config.agent;
+    const canisterId = _config.notificationCanisterId;
+    const actor = Actor.createActor(notificationIdlFactory, {
+        agent,
+        canisterId,
+    });
+    _actor = actor;
+    return _actor;
+}
+export async function getPermissionStatus() {
+    requireWindow();
+    return Notification.permission;
+}
+export async function requestPermission() {
+    requireWindow();
+    const res = await Notification.requestPermission();
+    dbg('Notification permission result:', res);
+    return res;
+}
+export async function registerServiceWorker() {
+    const w = requireWindow();
+    if (!('serviceWorker' in navigator)) {
+        console.warn('[ic-web-push] Service workers are not supported in this browser.');
+        return null;
+    }
+    try {
+        const reg = await navigator.serviceWorker.register(_config.serviceWorkerPath, {
+            scope: _config.serviceWorkerScope,
+            // type: 'module', // our sw is classic to maximize compatibility
+            updateViaCache: 'none',
+        });
+        await reg.update();
+        dbg('Service worker registered', reg);
+        return reg;
+    }
+    catch (e) {
+        console.error('[ic-web-push] Failed to register service worker:', e);
+        throw e;
+    }
+}
+export function ensurePushSupported() {
+    try {
+        requireWindow();
+    }
+    catch {
+        return false;
+    }
+    const supported = 'serviceWorker' in navigator && 'PushManager' in window && 'Notification' in window;
+    if (!supported) {
+        dbg('[ic-web-push] Push is not supported in this browser.');
+        console.warn('[ic-web-push] Push is not supported in this browser.');
+    }
+    return supported;
+}
+function urlBase64ToUint8Array(base64String) {
+    const padding = '='.repeat((4 - (base64String.length % 4)) % 4);
+    const base64 = (base64String + padding).replace(/-/g, '+').replace(/_/g, '/');
+    const rawData = atob(base64);
+    const outputArray = new Uint8Array(rawData.length);
+    for (let i = 0; i < rawData.length; ++i) {
+        outputArray[i] = rawData.charCodeAt(i);
+    }
+    return outputArray;
+}
+function toPrincipal(p) {
+    return typeof p === 'string' ? Principal.fromText(p) : p;
+}
+export async function listRelayers() {
+    const actor = await getActor();
+    return actor.listRelayers();
+}
+export async function chooseRandomRelayer() {
+    const list = await listRelayers();
+    if (!list || list.length === 0)
+        return null;
+    const idx = Math.floor(Math.random() * list.length);
+    return list[idx].relayer;
+}
+export async function getVapidPublicKey(relayer) {
+    const actor = await getActor();
+    const key = await actor.getVapidPublicKey(toPrincipal(relayer));
+    dbg('VAPID public key fetched for relayer');
+    return key;
+}
+function subscriptionToRecord(sub, relayer) {
+    const json = sub.toJSON();
+    return {
+        endpoint: sub.endpoint,
+        keys: {
+            p256dh: json.keys?.p256dh ?? '',
+            auth: json.keys?.auth ?? '',
+        },
+        expirationTime: json.expirationTime ? [BigInt(json.expirationTime)] : [],
+        relayer,
+    };
+}
+const LS = {
+    registered: 'icwp.registered',
+    endpoint: 'icwp.endpoint',
+    relayer: 'icwp.relayer',
+};
+function setLocalRegistered(endpoint) {
+    try {
+        if (endpoint) {
+            localStorage.setItem(LS.registered, '1');
+            localStorage.setItem(LS.endpoint, endpoint);
+        }
+        else {
+            localStorage.removeItem(LS.registered);
+            localStorage.removeItem(LS.endpoint);
+        }
+    }
+    catch {
+    }
+}
+export async function getSubscription() {
+    try {
+        requireWindow();
+    }
+    catch {
+        return null; // SSR or non-browser environment
+    }
+    if (!('serviceWorker' in navigator))
+        return null;
+    const reg = await navigator.serviceWorker.getRegistration(_config.serviceWorkerScope);
+    if (!reg)
+        return null;
+    return reg.pushManager.getSubscription();
+}
+export async function isSubscribed() {
+    const sub = await getSubscription();
+    if (!sub)
+        return false;
+    // Best-effort relayer consistency check: if we stored a relayer locally, ensure it's still registered.
+    try {
+        const storedRelayerTxt = localStorage.getItem(LS.relayer);
+        if (storedRelayerTxt) {
+            const relayers = await listRelayers();
+            const exists = relayers.some(r => r.relayer.toText() === storedRelayerTxt);
+            if (!exists) {
+                dbg('[ic-web-push] Stored relayer is no longer registered. Treating as unsubscribed.');
+                return false;
+            }
+        }
+    }
+    catch {
+    }
+    // If applicationCanisterId is configured, verify with server canister.
+    if (_config.applicationCanisterId) {
+        try {
+            const actor = await getActor();
+            const app = Principal.fromText(_config.applicationCanisterId);
+            const ok = await actor.hasSubscription(app, sub.endpoint);
+            if (!ok) {
+                dbg('[ic-web-push] Local subscription not found on the canister. Removing it locally');
+                // Remote canister has no record: revoke local subscription to keep state consistent.
+                try {
+                    await sub.unsubscribe();
+                }
+                catch (e) {
+                    dbg('[ic-web-push] Failed to unsubscribe local PushSubscription after remote mismatch:', e);
+                    console.warn('[ic-web-push] Failed to unsubscribe local PushSubscription after remote mismatch:', e);
+                }
+                finally {
+                    setLocalRegistered(null);
+                }
+                return false;
+            }
+        }
+        catch (e) {
+            dbg('[ic-web-push] hasSubscription check failed; assuming local subscription is valid:', e);
+            console.warn('[ic-web-push] hasSubscription check failed; assuming local subscription is valid:', e);
+            // Fall through and trust local presence
+        }
+    }
+    return true;
+}
+async function ensureServiceWorkerReady() {
+    let reg = await navigator.serviceWorker.getRegistration(_config.serviceWorkerScope);
+    if (!reg) {
+        reg = (await registerServiceWorker());
+    }
+    if (!reg)
+        throw new Error('ic-web-push: service worker is required but was not registered');
+    return reg;
+}
+/** Subscribe the browser and register the subscription on the notification canister. */
+export async function subscribe(options) {
+    if (!_config.applicationCanisterId)
+        throw new Error('ic-web-push: applicationCanisterId is required in init() to subscribe');
+    if (!ensurePushSupported())
+        throw new Error('ic-web-push: Push not supported');
+    const permission = await getPermissionStatus();
+    if (permission !== 'granted') {
+        if (options?.requestPermissionIfNeeded) {
+            const p = await requestPermission();
+            if (p !== 'granted')
+                throw new Error('ic-web-push: Notification permission was not granted');
+        }
+        else {
+            throw new Error('ic-web-push: Notification permission is not granted');
+        }
+    }
+    // Resolve relayer to use
+    let relayer = null;
+    try {
+        if (options?.relayer)
+            relayer = toPrincipal(options.relayer);
+        else {
+            const stored = localStorage.getItem(LS.relayer);
+            if (stored)
+                relayer = Principal.fromText(stored);
+        }
+    }
+    catch {
+    }
+    if (!relayer) {
+        relayer = await chooseRandomRelayer();
+    }
+    if (!relayer) {
+        throw new Error('ic-web-push: No relayers are registered on the notification canister');
+    }
+    const reg = await ensureServiceWorkerReady();
+    const existing = await reg.pushManager.getSubscription();
+    const vapidKey = await getVapidPublicKey(relayer);
+    const appServerKey = urlBase64ToUint8Array(vapidKey);
+    let subscription = existing;
+    if (!subscription) {
+        subscription = await reg.pushManager.subscribe({
+            userVisibleOnly: true,
+            applicationServerKey: appServerKey
+        });
+        dbg('Created new PushSubscription');
+    }
+    else {
+        dbg('Existing PushSubscription found');
+    }
+    const actor = await getActor();
+    const app = Principal.fromText(_config.applicationCanisterId);
+    await actor.subscribe(app, subscriptionToRecord(subscription, relayer));
+    setLocalRegistered(subscription.endpoint);
+    try {
+        localStorage.setItem(LS.relayer, relayer.toText());
+    }
+    catch {
+    }
+    dbg('Subscription registered on canister with relayer', relayer.toText());
+    return subscription;
+}
+/** Unsubscribe from browser and unregister from the notification canister. */
+export async function unsubscribe() {
+    const sub = await getSubscription();
+    if (!sub) {
+        dbg('No subscription present');
+        return;
+    }
+    try {
+        // Try unregister on canister first
+        const actor = await getActor();
+        if (_config.applicationCanisterId) {
+            const app = Principal.fromText(_config.applicationCanisterId);
+            await actor.unsubscribe(app, sub.endpoint);
+            dbg('Subscription removed from canister. Endpoint: ', sub.endpoint);
+        }
+    }
+    catch (e) {
+        dbg('[ic-web-push] Failed to unregister on canister (will still remove local sub):', e);
+        console.warn('[ic-web-push] Failed to unregister on canister (will still remove local sub):', e);
+    }
+    try {
+        const ok = await sub.unsubscribe();
+        dbg('Browser PushSubscription unsubscribed:', ok);
+    }
+    finally {
+        setLocalRegistered(null);
+    }
+}
+/** Unregister all subscriptions for this application principal on the canister. */
+export async function unsubscribeAll() {
+    if (!_config.applicationCanisterId)
+        throw new Error('ic-web-push: applicationCanisterId is required in init() to unsubscribeAll');
+    const actor = await getActor();
+    const app = Principal.fromText(_config.applicationCanisterId);
+    await actor.unsubscribeAll(app);
+    dbg('[ic-web-push] Removed all subscriptions from the canister');
+    // keep local sub as-is; caller may also call unsubscribe()
+}
+// Convenience: combined flow to ensure sw + permission + subscription
+export async function ensureSubscribed(options) {
+    await registerServiceWorker();
+    if ((await getPermissionStatus()) !== 'granted') {
+        if (options?.requestPermissionIfNeeded) {
+            await requestPermission();
+        }
+    }
+    return subscribe({ requestPermissionIfNeeded: false });
+}
+const api = {
+    init,
+    registerServiceWorker,
+    requestPermission,
+    getPermissionStatus,
+    // Relayers
+    listRelayers,
+    chooseRandomRelayer,
+    getVapidPublicKey,
+    // Subs
+    subscribe,
+    unsubscribe,
+    unsubscribeAll,
+    ensureSubscribed,
+    getSubscription,
+    isSubscribed,
+    setDebug,
+    setDebugAlerts,
+};
+export default api;

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@research-ag/ic-web-push",
+  "version": "0.1.0",
+  "description": "Browser SDK for Internet Computer web push notifications with a companion service worker.",
+  "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"
+    }
+  },
+  "files": [
+    "dist",
+    "sw.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "copy:declarations": "node -e \"const fs=require('fs');const path=require('path');const src=path.join(process.cwd(),'declarations');const dest=path.join(process.cwd(),'dist','declarations');try{if(fs.existsSync(src)){fs.rmSync(dest,{recursive:true,force:true});fs.mkdirSync(dest,{recursive:true});fs.cpSync(src,dest,{recursive:true});console.log('[ic-web-push] Copied',src,'->',dest);}else{console.warn('[ic-web-push] No declarations directory found at',src);}}catch(e){console.error('[ic-web-push] Failed to copy declarations:',e&&e.message||e);process.exitCode=1;}\"",
+    "build": "tsc -p tsconfig.json && npm run copy:declarations",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "internet-computer",
+    "dfinity",
+    "web-push",
+    "service-worker",
+    "notifications"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+  },
+  "devDependencies": {
+    "rimraf": "^5.0.5",
+    "typescript": "^5.4.0"
+  },
+  "peerDependencies": {
+    "@dfinity/agent": "^3.4.3",
+    "@dfinity/principal": "^3.4.3"
+  },
+  "sideEffects": false
+}

package/sw.js

@@ -0,0 +1,111 @@
+/*
+IC Web Push Service Worker
+
+Scope recommendation: '/ic-web-push/'
+File name recommendation at web root: '/ic-web-push-sw.js'
+
+This SW is designed to coexist with your main application SW, by using a dedicated scope.
+It handles 'push' events to display notifications and 'notificationclick' to focus/open the app.
+*/
+
+self.addEventListener('install', (event) => {
+    // Skip waiting so updates take effect quickly
+    self.skipWaiting();
+});
+
+self.addEventListener('activate', (event) => {
+    // Claim the clients in our scope so we can receive messages immediately
+    event.waitUntil(self.clients.claim());
+});
+
+self.addEventListener('push', (event) => {
+    event.waitUntil((async () => {
+        try {
+            const data = event.data ? event.data.json() : {};
+            const title = data.title || 'New notification';
+            const urlFromPayload = data?.url || (data?.data?.url) || '/';
+            const options = {
+                body: data.content || data.body || 'You have a new message',
+                icon: '/favicon.ico',
+                badge: '/favicon.ico',
+                data: {...(data.data || {}), url: urlFromPayload},
+                actions: data.actions || [],
+                requireInteraction: !!data.requireInteraction,
+            };
+            let tag = data?.tag || data?.data?.tag;
+            if (tag) {
+                options.tag = tag;
+            }
+            return self.registration.showNotification(title, options);
+        } catch (e) {
+            return self.registration.showNotification('New notification', {
+                body: 'You have a new notification',
+                icon: '/favicon.ico'
+            });
+        }
+    })());
+});
+
+self.addEventListener('message', (event) => {
+    try {
+        const data = event?.data || {};
+        if (data && data.type === 'CLEAR_NOTIFICATIONS_BY_TAG') {
+            const tag = data.tag;
+            if (!tag) return;
+            event.waitUntil((async () => {
+                try {
+                    const list = await self.registration.getNotifications({ includeTriggered: true });
+                    for (const n of list) {
+                        if (n?.tag === tag) {
+                            try { n.close(); } catch (_) {}
+                        }
+                    }
+                } catch (_) {
+                    try {
+                        const list = await self.registration.getNotifications();
+                        for (const n of list) {
+                            if (n?.tag === tag) {
+                                try { n.close(); } catch (_) {}
+                            }
+                        }
+                    } catch (_) {}
+                }
+            })());
+        }
+    } catch (_) {}
+});
+
+self.addEventListener('notificationclick', (event) => {
+    event.notification.close();
+    const url = event.notification?.data?.url || '/';
+    event.waitUntil(
+        (async () => {
+            const targetUrl = new URL(url, self.location.origin);
+            // Try to find and focus an existing same-origin client
+            const allClients = await self.clients.matchAll({type: 'window', includeUncontrolled: true});
+            for (const client of allClients) {
+                try {
+                    const clientUrl = new URL(client.url);
+                    if (clientUrl.origin !== targetUrl.origin) continue;
+
+                    await client.focus();
+                    // Prefer messaging so the app can set session flags and handle navigation itself
+                    try {
+                        client.postMessage({type: 'OPEN_URL', url: targetUrl.href});
+                    } catch (_) {
+                    }
+
+                    // Safe fallback: if the app is already in-app (not start_url) and different href, also navigate
+                    const atRoot = clientUrl.pathname === '/' && clientUrl.search === '' && clientUrl.hash === '';
+                    if ('navigate' in client && !atRoot && clientUrl.href !== targetUrl.href) {
+                        return client.navigate(targetUrl.href);
+                    }
+                    return;
+                } catch (_) {
+                }
+            }
+            // If no client exists, open a new window at the target URL
+            return self.clients.openWindow(targetUrl.href);
+        })()
+    );
+});