@phoenix-iq/notifications 1.0.0 → 1.2.0

package/src/index.ts

@@ -1,331 +0,0 @@
-import { keys, type StoredConfig, type StoredDevice, type StoredLogin, store } from './store.js';
-
-/**
- * Phoenix Notifications web SDK: subscribes the browser to web push for an app on notifications.phnx-iq.com, binds it to
- * the signed-in user with an identity token from the app's own backend, and hands notification clicks to the app.
- *
- * Nothing here throws for an unsupported browser or a denied permission: check `isSupported()` / `permission()`.
- * The service worker file (phoenix-notifications-sw.js) must be served from the site, at `serviceWorkerPath`.
- */
-
-export const DEFAULT_SERVER_URL = 'https://notifications.phnx-iq.com';
-export const DEFAULT_SERVICE_WORKER_PATH = '/phoenix-notifications-sw.js';
-
-export interface InitOptions {
-  /** The app id from the dashboard (App notifications → the app → Settings). */
-  appId: string;
-  /** Where the notifications API is. '' means this site's own origin (development through a proxy). */
-  serverUrl?: string;
-  serviceWorkerPath?: string;
-  serviceWorkerScope?: string;
-  /** Language the device reports (picks Arabic or English text); defaults to the browser's. */
-  language?: string;
-  appVersion?: string;
-}
-
-export type PushPermission = 'granted' | 'denied' | 'default' | 'unsupported';
-
-export interface NotificationClick {
-  url?: string;
-  data: Record<string, string>;
-  messageId?: string;
-}
-
-interface Envelope<T> {
-  result?: T;
-  errors?: string[];
-}
-
-interface WebConfig {
-  appId: string;
-  name: string;
-  vapidPublicKey: string;
-  iconUrl?: string | null;
-  defaultUrl?: string | null;
-}
-
-interface RegisteredDevice {
-  deviceId: string;
-  deviceSecret: string;
-  vapidPublicKey: string;
-}
-
-export class NotificationsError extends Error {
-  readonly status: number;
-
-  constructor(status: number, message: string) {
-    super(message);
-    this.name = 'NotificationsError';
-    this.status = status;
-  }
-}
-
-const CLICK_MESSAGE = 'phoenix-notifications:click';
-const RESYNC_AFTER_MS = 24 * 60 * 60 * 1000;
-
-let options: Required<Omit<InitOptions, 'appVersion'>> & { appVersion?: string } = {
-  appId: '',
-  serverUrl: DEFAULT_SERVER_URL,
-  serviceWorkerPath: DEFAULT_SERVICE_WORKER_PATH,
-  serviceWorkerScope: '/',
-  language: '',
-};
-let registration: ServiceWorkerRegistration | null = null;
-let ready: Promise<void> | null = null;
-let syncing: Promise<StoredDevice | null> | null = null;
-/** The last successful sync of this page, so init and login on the same load ask the server once. */
-let synced: { device: StoredDevice; at: number } | null = null;
-const SYNC_REUSE_MS = 5 * 60 * 1000;
-const clickHandlers = new Set<(click: NotificationClick) => void>();
-let listening = false;
-
-function supported(): boolean {
-  return (
-    typeof window !== 'undefined' &&
-    window.isSecureContext &&
-    'serviceWorker' in navigator &&
-    'PushManager' in window &&
-    'Notification' in window &&
-    'indexedDB' in window
-  );
-}
-
-function url(path: string): string {
-  return `${options.serverUrl.replace(/\/+$/, '')}${path}`;
-}
-
-async function call<T>(method: string, path: string, body?: unknown, deviceSecret?: string): Promise<T | undefined> {
-  const headers: Record<string, string> = {};
-  if (body !== undefined) headers['Content-Type'] = 'application/json';
-  if (deviceSecret) headers.Authorization = `Device ${deviceSecret}`;
-  const response = await fetch(url(path), { method, headers, body: body === undefined ? undefined : JSON.stringify(body) });
-  if (response.status === 204) return undefined;
-  let payload: Envelope<T> | undefined;
-  try {
-    payload = (await response.json()) as Envelope<T>;
-  } catch {
-    payload = undefined;
-  }
-  if (!response.ok) throw new NotificationsError(response.status, payload?.errors?.join(' ') || `Request failed with ${response.status}`);
-  return payload?.result;
-}
-
-function toBytes(base64Url: string): Uint8Array<ArrayBuffer> {
-  const padded = base64Url.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (base64Url.length % 4)) % 4);
-  const raw = atob(padded);
-  const bytes = new Uint8Array(new ArrayBuffer(raw.length));
-  for (let i = 0; i < raw.length; i++) bytes[i] = raw.charCodeAt(i);
-  return bytes;
-}
-
-function toBase64Url(buffer: ArrayBuffer | null): string {
-  if (!buffer) return '';
-  let raw = '';
-  for (const byte of new Uint8Array(buffer)) raw += String.fromCharCode(byte);
-  return btoa(raw).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
-}
-
-function sameKey(subscription: PushSubscription, vapidKey: string): boolean {
-  return toBase64Url(subscription.options.applicationServerKey) === vapidKey.replace(/=+$/, '');
-}
-
-function subscriptionBody(subscription: PushSubscription, vapidKey: string) {
-  return {
-    endpoint: subscription.endpoint,
-    p256dh: toBase64Url(subscription.getKey('p256dh')),
-    auth: toBase64Url(subscription.getKey('auth')),
-    applicationServerKey: vapidKey,
-  };
-}
-
-function deviceInfo() {
-  return {
-    language: options.language || navigator.language,
-    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-    appVersion: options.appVersion,
-    os: navigator.platform || undefined,
-    deviceModel: navigator.userAgent.slice(0, 200),
-  };
-}
-
-function listenForClicks(): void {
-  if (listening) return;
-  listening = true;
-  navigator.serviceWorker.addEventListener('message', (event: MessageEvent) => {
-    const message = event.data as { type?: string; url?: string; data?: Record<string, string>; messageId?: string } | undefined;
-    if (message?.type !== CLICK_MESSAGE) return;
-    const click: NotificationClick = { url: message.url, data: message.data ?? {}, messageId: message.messageId };
-    if (clickHandlers.size === 0) {
-      if (click.url) window.location.assign(click.url);
-      return;
-    }
-    for (const handler of clickHandlers) handler(click);
-  });
-  // messages from the worker wait in a queue until the page says it is listening
-  navigator.serviceWorker.startMessages();
-}
-
-/** Subscribes (or renews the subscription) and registers or updates the device. Needs the permission granted. */
-async function sync(): Promise<StoredDevice | null> {
-  if (!registration || Notification.permission !== 'granted') return null;
-
-  const config = await call<WebConfig>('GET', `/v1/apps/${options.appId}/web`);
-  if (!config) return null;
-  const vapidKey = config.vapidPublicKey;
-  await store.set<StoredConfig>(keys.config, { appId: options.appId, serverUrl: options.serverUrl, vapidKey });
-
-  let subscription = await registration.pushManager.getSubscription();
-  // a subscription made with another key (an earlier key of this app, or another push provider) cannot receive our pushes
-  if (subscription && !sameKey(subscription, vapidKey)) {
-    await subscription.unsubscribe();
-    subscription = null;
-  }
-  subscription ??= await registration.pushManager.subscribe({ userVisibleOnly: true, applicationServerKey: toBytes(vapidKey) });
-
-  const stored = await store.get<StoredDevice>(keys.device(options.appId));
-  const body = { subscription: subscriptionBody(subscription, vapidKey), ...deviceInfo() };
-  if (stored) {
-    const changed = stored.endpoint !== subscription.endpoint || stored.vapidKey !== vapidKey;
-    if (!changed && Date.now() - stored.syncedAt < RESYNC_AFTER_MS) return stored;
-    try {
-      await call('PUT', `/v1/devices/${stored.id}`, changed ? body : deviceInfo(), stored.secret);
-      const updated = { ...stored, endpoint: subscription.endpoint, vapidKey, syncedAt: Date.now() };
-      await store.set(keys.device(options.appId), updated);
-      return updated;
-    } catch (error) {
-      // the server no longer knows this device (or another record owns the subscription): register it again
-      if (!(error instanceof NotificationsError) || ![401, 404, 409].includes(error.status)) throw error;
-    }
-  }
-
-  const registered = await call<RegisteredDevice>('POST', `/v1/apps/${options.appId}/devices`, body);
-  if (!registered) return null;
-  const device: StoredDevice = {
-    appId: options.appId,
-    id: registered.deviceId,
-    secret: registered.deviceSecret,
-    endpoint: subscription.endpoint,
-    vapidKey,
-    syncedAt: Date.now(),
-  };
-  await store.set(keys.device(options.appId), device);
-  await store.remove(keys.login(options.appId));
-  return device;
-}
-
-function syncOnce(force = false): Promise<StoredDevice | null> {
-  if (!force && synced && synced.device.appId === options.appId && Date.now() - synced.at < SYNC_REUSE_MS) return Promise.resolve(synced.device);
-  syncing ??= sync()
-    .then((device) => {
-      synced = device ? { device, at: Date.now() } : null;
-      return device;
-    })
-    .finally(() => {
-      syncing = null;
-    });
-  return syncing;
-}
-
-/** A login made before the person allowed notifications is applied once there is a device. */
-async function applyPendingLogin(device: StoredDevice | null): Promise<void> {
-  if (!device) return;
-  const pending = await store.get<StoredLogin>(keys.login(options.appId));
-  if (pending && pending.at === 0) await Notifications.login(pending.token);
-}
-
-export const Notifications = {
-  /** True when this browser can receive web push here (a secure context with service workers and the Push API). */
-  isSupported(): boolean {
-    return supported();
-  },
-
-  /** Registers the service worker. When the person already allowed notifications, subscribes quietly. */
-  async init(init: InitOptions): Promise<void> {
-    if (!supported()) return;
-    if (!init.appId) throw new Error('Notifications.init needs the appId.');
-    options = {
-      appId: init.appId,
-      serverUrl: init.serverUrl ?? DEFAULT_SERVER_URL,
-      serviceWorkerPath: init.serviceWorkerPath ?? DEFAULT_SERVICE_WORKER_PATH,
-      serviceWorkerScope: init.serviceWorkerScope ?? '/',
-      language: init.language ?? '',
-      appVersion: init.appVersion,
-    };
-    ready = (async () => {
-      registration = await navigator.serviceWorker.register(options.serviceWorkerPath, { scope: options.serviceWorkerScope });
-      listenForClicks();
-    })();
-    await ready;
-    if (Notification.permission === 'granted') await applyPendingLogin(await syncOnce(true));
-  },
-
-  permission(): PushPermission {
-    return supported() ? Notification.permission : 'unsupported';
-  },
-
-  /** Asks the person (call it from a click) and subscribes when they allow. */
-  async requestPermission(): Promise<PushPermission> {
-    if (!supported()) return 'unsupported';
-    const result = await Notification.requestPermission();
-    if (result === 'granted') {
-      await ready;
-      await applyPendingLogin(await syncOnce(true));
-    }
-    return result;
-  },
-
-  /**
-   * Binds this browser to the user an identity token from the app's backend vouches for. Before the person allows
-   * notifications there is no device yet: the token is kept and used once they do.
-   */
-  async login(identityToken: string): Promise<void> {
-    if (!supported()) return;
-    await ready;
-    const loginKey = keys.login(options.appId);
-    const previous = await store.get<StoredLogin>(loginKey);
-    const device = await syncOnce();
-    if (!device) {
-      await store.set<StoredLogin>(loginKey, { appId: options.appId, token: identityToken, at: 0 });
-      return;
-    }
-    if (previous && previous.token === identityToken && previous.at > 0 && Date.now() - previous.at < RESYNC_AFTER_MS) return;
-    await call('POST', `/v1/devices/${device.id}/login`, { identityToken }, device.secret);
-    await store.set<StoredLogin>(loginKey, { appId: options.appId, token: identityToken, at: Date.now() });
-  },
-
-  /** The browser keeps receiving the app's broadcasts as a guest, but no longer this user's notifications. */
-  async logout(): Promise<void> {
-    if (!supported() || !options.appId) return;
-    await store.remove(keys.login(options.appId));
-    const device = await store.get<StoredDevice>(keys.device(options.appId));
-    if (device) await call('POST', `/v1/devices/${device.id}/logout`, undefined, device.secret);
-  },
-
-  /** Stops notifications in this browser altogether. */
-  async unsubscribe(): Promise<void> {
-    if (!supported() || !options.appId) return;
-    const device = await store.get<StoredDevice>(keys.device(options.appId));
-    if (device) {
-      await call('DELETE', `/v1/devices/${device.id}`, undefined, device.secret);
-      await store.remove(keys.device(options.appId));
-    }
-    await store.remove(keys.login(options.appId));
-    const subscription = await registration?.pushManager.getSubscription();
-    await subscription?.unsubscribe();
-  },
-
-  /** A notification was clicked while the site was open. Without a handler the SDK opens its link. Returns an unsubscribe function. */
-  onClick(handler: (click: NotificationClick) => void): () => void {
-    clickHandlers.add(handler);
-    return () => clickHandlers.delete(handler);
-  },
-
-  /** Re-runs the subscription check now (e.g. after the person changed the site's permission). */
-  async refresh(): Promise<void> {
-    if (!supported()) return;
-    await ready;
-    await applyPendingLogin(await syncOnce(true));
-  },
-};
-
-export type { StoredDevice };

package/src/store.ts

@@ -1,74 +0,0 @@
-/**
- * The SDK's state in IndexedDB, shared with the service worker (which reads `config` to report clicks and to renew a
- * subscription). Keep the database name, store and keys in step with phoenix-notifications-sw.js.
- */
-
-const DB_NAME = 'phoenix-notifications';
-const STORE = 'state';
-
-/** What the service worker needs: where to report clicks and the key to subscribe with. */
-export interface StoredConfig {
-  appId: string;
-  serverUrl: string;
-  vapidKey: string;
-}
-
-/** This browser's device record on the server. The secret authenticates every later call for the device. */
-export interface StoredDevice {
-  appId: string;
-  id: string;
-  secret: string;
-  endpoint: string;
-  vapidKey: string;
-  /** When the server last heard from this device (ms), to refresh it about once a day. */
-  syncedAt: number;
-}
-
-/** The user the device was last bound to, so a page load does not log in again with the same token. */
-export interface StoredLogin {
-  appId: string;
-  token: string;
-  at: number;
-}
-
-function open(): Promise<IDBDatabase> {
-  return new Promise((resolve, reject) => {
-    const request = indexedDB.open(DB_NAME, 1);
-    request.onupgradeneeded = () => {
-      if (!request.result.objectStoreNames.contains(STORE)) request.result.createObjectStore(STORE);
-    };
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error);
-  });
-}
-
-async function run<T>(mode: IDBTransactionMode, action: (store: IDBObjectStore) => IDBRequest): Promise<T> {
-  const db = await open();
-  try {
-    return await new Promise<T>((resolve, reject) => {
-      const request = action(db.transaction(STORE, mode).objectStore(STORE));
-      request.onsuccess = () => resolve(request.result as T);
-      request.onerror = () => reject(request.error);
-    });
-  } finally {
-    db.close();
-  }
-}
-
-export const store = {
-  get<T>(key: string): Promise<T | undefined> {
-    return run<T | undefined>('readonly', (s) => s.get(key));
-  },
-  set<T>(key: string, value: T): Promise<void> {
-    return run<void>('readwrite', (s) => s.put(value, key));
-  },
-  remove(key: string): Promise<void> {
-    return run<void>('readwrite', (s) => s.delete(key));
-  },
-};
-
-export const keys = {
-  config: 'config',
-  device: (appId: string) => `device:${appId}`,
-  login: (appId: string) => `login:${appId}`,
-};