@sweidos/eidos 1.1.0 → 1.2.0

package/README.md

@@ -233,6 +233,81 @@ const mutation = useEidosMutation(createOrder, {
 
 ---
 
+## Push Notifications
+
+Headless, framework-agnostic Web Push. Tree-shaken via a separate subpath — adds zero bytes unless imported.
+
+**1. Generate VAPID keys (one-time):**
+
+```sh
+npx @sweidos/eidos generate-vapid-keys
+```
+
+Detects your framework (Vite/Next/SvelteKit/Nuxt) and writes a correctly-prefixed
+public key + an unprefixed private key to `.env.local`:
+
+```
+VITE_EIDOS_VAPID_PUBLIC_KEY=...
+EIDOS_VAPID_PRIVATE_KEY=...
+```
+
+Give `EIDOS_VAPID_PRIVATE_KEY` (and the public key) to your backend. What the
+backend does with them — language, storage, send timing — is entirely its own
+concern; Eidos never talks to it directly.
+
+**2. Register handlers once at app init (any tab, no permission prompt):**
+
+```ts
+import { registerPushHandlers } from '@sweidos/eidos/push';
+
+registerPushHandlers({
+  onNotificationClick: (data) => router.push(data.url),
+  onSubscriptionExpired: (sub) =>
+    fetch('/api/push-subscribe', { method: 'POST', body: JSON.stringify(sub) }),
+});
+```
+
+**3. Subscribe from a user gesture (e.g. an "Enable notifications" button):**
+
+```ts
+import { subscribeToPush, isPushSupported, getPushPermissionState } from '@sweidos/eidos/push';
+
+async function onEnableClick() {
+  const result = await subscribeToPush({
+    vapidPublicKey: import.meta.env.VITE_EIDOS_VAPID_PUBLIC_KEY,
+    onSubscribe: (sub) =>
+      fetch('/api/push-subscribe', { method: 'POST', body: JSON.stringify(sub) }),
+  });
+
+  if (result.status === 'subscribed') toast('Notifications enabled');
+  else if (result.status === 'denied') toast('Permission denied');
+}
+```
+
+`isPushSupported()` / `getPushPermissionState()` / `getPushUnsupportedReason()`
+let you hide the button when push is unavailable (e.g. iOS Safari outside an
+installed PWA returns `'ios-not-installed'`).
+
+### Server payload schema
+
+The service worker shows whatever your server sends — Eidos never renders UI:
+
+```json
+{
+  "title": "Order shipped",
+  "body": "Your order #1234 is on its way",
+  "icon": "/icon.png",
+  "badge": "/badge.png",
+  "tag": "order-1234",
+  "data": { "url": "/orders/1234" }
+}
+```
+
+Click behavior: if the app is open, `data` is delivered to `onNotificationClick`
+for client-side routing; otherwise the SW opens `data.url` directly.
+
+---
+
 ## Testing
 
 ```ts

package/dist/action.js

@@ -1,66 +1,99 @@
-import { useEidosStore as s } from "./store.js";
-import { getSwRegistration as w } from "./sw-bridge.js";
-import { idbQueueStorage as g } from "./idb.js";
-import { _getQueueStorage as m } from "./queue-storage.js";
-var d = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Map();
+import { useEidosStore as y } from "./store.js";
+import { getSwRegistration as _ } from "./sw-bridge.js";
+import { idbQueueStorage as S } from "./idb.js";
+import { _getQueueStorage as M } from "./queue-storage.js";
+var h = /* @__PURE__ */ new Map(), k = /* @__PURE__ */ new Map(), C = /* @__PURE__ */ new Map(), Q = /* @__PURE__ */ new Map(), x = /* @__PURE__ */ new Map(), p = /* @__PURE__ */ new Map();
 function u() {
-  return m() ?? g;
+  return M() ?? S;
 }
-function y() {
+function m() {
   return crypto.randomUUID();
 }
-function C(e, t) {
-  const r = t.name || e.name || y();
-  d.set(r, e), t.onRollback && p.set(r, t.onRollback), t.onConflict && f.set(r, t.onConflict);
-  const a = async (...i) => {
-    const { isOnline: n } = s.getState();
-    if (t.onOptimistic?.(...i), t.reliability === "neverLose") {
-      if (!n) return l(r, r, i, t);
-      try {
-        return await e(...i);
-      } catch {
-        return l(r, r, i, t);
-      }
+function v(e, t, i) {
+  return e(...t, i);
+}
+function U(e, t) {
+  const i = t.name || e.name || m(), a = t.namespace ? `${t.namespace}::${i}` : i;
+  h.set(a, e), x.set(a, t), t.onRollback && k.set(a, t.onRollback), t.onConflict && C.set(a, t.onConflict), t.conflict && Q.set(a, t.conflict);
+  const c = async (...n) => {
+    const { isOnline: s } = y.getState(), l = t.reliability === "neverLose" || t.cancellable, o = l ? m() : "";
+    let d;
+    if (t.cancellable) {
+      const f = new AbortController();
+      p.set(o, f), d = f.signal;
     }
+    const g = {
+      idempotencyKey: o,
+      attempt: 0,
+      signal: d
+    };
+    t.onOptimistic?.(...n, g);
     try {
-      return await e(...i);
-    } catch (o) {
-      throw t.onRollback?.(...i), o;
+      if (t.reliability === "neverLose") {
+        if (!s) return R(a, a, n, t, o);
+        try {
+          return await v(e, n, g);
+        } catch (f) {
+          if (A(f)) throw f;
+          return R(a, a, n, t, o);
+        }
+      }
+      try {
+        return l ? await v(e, n, g) : await e(...n);
+      } catch (f) {
+        throw t.onRollback?.(...n), f;
+      }
+    } finally {
+      t.cancellable && p.delete(o);
     }
+  }, r = async (n) => {
+    const s = p.get(n);
+    if (s)
+      return s.abort(), !0;
+    const l = (await u().getAll()).find((o) => o.idempotencyKey === n && o.status === "pending");
+    return l ? (y.getState().removeQueueItem(l.id), await u().remove(l.id), !0) : !1;
   };
-  return Object.defineProperty(a, "id", {
-    value: r,
+  return Object.defineProperty(c, "id", {
+    value: a,
     writable: !1
-  }), Object.defineProperty(a, "config", {
+  }), Object.defineProperty(c, "config", {
     value: t,
     writable: !1
-  }), a;
+  }), Object.defineProperty(c, "cancel", {
+    value: r,
+    writable: !1
+  }), c;
 }
-async function l(e, t, r, a) {
-  const i = y(), n = {
-    id: i,
+async function R(e, t, i, a, c) {
+  const r = m(), n = {
+    schemaVersion: 2,
+    id: r,
     actionId: e,
     actionName: t,
-    args: r,
+    idempotencyKey: c,
+    args: i,
     queuedAt: Date.now(),
     retryCount: 0,
     maxRetries: a.maxRetries ?? 3,
     status: "pending",
     priority: a.priority ?? "normal"
   };
-  await u().add(n), s.getState().addQueueItem(n);
+  await u().add(n), y.getState().addQueueItem(n);
   try {
-    const o = w();
-    o && "sync" in o && await o.sync.register("eidos-queue-replay");
+    const s = _();
+    s && "sync" in s && await s.sync.register("eidos-queue-replay");
   } catch {
   }
   return {
     queued: !0,
-    id: i,
+    id: r,
     message: `"${t}" queued — will execute when online`
   };
 }
-function h(e) {
+function A(e) {
+  return e instanceof DOMException && e.name === "AbortError";
+}
+function K(e) {
   if (e instanceof Response) return e.status >= 400 && e.status < 500;
   if (typeof e == "object" && e !== null) {
     const t = e.status;
@@ -68,112 +101,152 @@ function h(e) {
   }
   return !1;
 }
-function R(e) {
+function O(e) {
   return Math.min(2e3 * 2 ** e, 3e5) * (0.8 + Math.random() * 0.4);
 }
-var c = !1;
-async function _() {
-  const e = s.getState();
-  if (!e.isOnline || c) return {
+function w() {
+  return {
     attempted: 0,
     succeeded: 0,
     failed: 0,
     retrying: 0,
     skipped: 0,
-    conflicted: 0
+    conflicted: 0,
+    cancelled: 0
   };
-  c = !0;
+}
+var b = !1, q = "eidos-queue-replay";
+async function $() {
+  const e = y.getState();
+  if (!e.isOnline) return w();
+  if (typeof navigator < "u" && navigator.locks) return navigator.locks.request(q, { ifAvailable: !0 }, async (t) => t ? I(e) : w());
+  if (b) return w();
+  b = !0;
   try {
-    return await Q(e);
+    return await I(e);
   } finally {
-    c = !1;
+    b = !1;
   }
 }
-async function b(e, t) {
-  const r = d.get(e.actionId);
-  if (!r) return "skipped";
+async function E(e, t) {
+  const i = h.get(e.actionId);
+  if (!i) return "skipped";
+  const a = x.get(e.actionId)?.cancellable;
+  let c;
+  if (a) {
+    const n = new AbortController();
+    p.set(e.idempotencyKey, n), c = n.signal;
+  }
+  const r = {
+    idempotencyKey: e.idempotencyKey,
+    attempt: e.retryCount,
+    signal: c
+  };
   try {
-    await r(...e.args);
-    const a = Date.now();
+    await v(i, e.args, r);
+    const n = Date.now();
     return t.updateQueueItem(e.id, {
       status: "succeeded",
-      completedAt: a
+      completedAt: n
     }), await u().update(e.id, {
       status: "succeeded",
-      completedAt: a
+      completedAt: n
     }), setTimeout(() => {
       t.removeQueueItem(e.id), u().remove(e.id);
     }, 3e3), "succeeded";
-  } catch (a) {
-    if (h(a)) {
-      const n = f.get(e.actionId);
-      if (n && n(a, e.args) === "skip")
+  } catch (n) {
+    if (A(n))
+      return t.removeQueueItem(e.id), await u().remove(e.id), "cancelled";
+    if (K(n)) {
+      const l = Q.get(e.actionId);
+      let o;
+      if (l) switch (l.strategy) {
+        case "serverWins":
+          o = "skip";
+          break;
+        case "clientWins":
+        case "lastWriteWins":
+          o = "retry";
+          break;
+        case "merge":
+        case "custom": {
+          const d = {
+            error: n,
+            args: e.args,
+            attempt: e.retryCount,
+            idempotencyKey: e.idempotencyKey
+          };
+          o = l.resolve?.(d) ?? "retry";
+          break;
+        }
+      }
+      else {
+        const d = C.get(e.actionId);
+        d && (o = d(n, e.args));
+      }
+      if (o === "skip")
         return t.removeQueueItem(e.id), await u().remove(e.id), "conflicted";
+      o && typeof o == "object" && (e.args = o.resolved, t.updateQueueItem(e.id, { args: o.resolved }), await u().update(e.id, { args: o.resolved }));
     }
-    const i = e.retryCount + 1;
-    if (i >= e.maxRetries)
+    const s = e.retryCount + 1;
+    if (s >= e.maxRetries)
       return t.updateQueueItem(e.id, {
         status: "failed",
-        error: String(a),
-        retryCount: i
+        error: String(n),
+        retryCount: s
       }), await u().update(e.id, {
         status: "failed",
-        error: String(a),
-        retryCount: i
-      }), p.get(e.actionId)?.(...e.args), "failed";
+        error: String(n),
+        retryCount: s
+      }), k.get(e.actionId)?.(...e.args), "failed";
     {
-      const n = Date.now() + R(i);
+      const l = Date.now() + O(s);
       return t.updateQueueItem(e.id, {
         status: "pending",
-        retryCount: i,
-        nextRetryAt: n
+        retryCount: s,
+        nextRetryAt: l
       }), await u().update(e.id, {
         status: "pending",
-        retryCount: i,
-        nextRetryAt: n
+        retryCount: s,
+        nextRetryAt: l
       }), "retrying";
     }
+  } finally {
+    a && p.delete(e.idempotencyKey);
   }
 }
-async function I(e, t, r) {
+async function D(e, t, i) {
   if (e.length === 0) return;
-  const a = e.filter((n) => d.has(n.actionId));
-  if (r.skipped += e.length - a.length, a.length > 0) {
-    t.batchUpdateQueueItems(a.map((n) => ({
-      id: n.id,
+  const a = e.filter((r) => h.has(r.actionId));
+  if (i.skipped += e.length - a.length, a.length > 0) {
+    t.batchUpdateQueueItems(a.map((r) => ({
+      id: r.id,
       update: { status: "replaying" }
     })));
-    for (const n of a) u().update(n.id, { status: "replaying" });
+    for (const r of a) u().update(r.id, { status: "replaying" });
   }
-  const i = await Promise.allSettled(a.map((n) => b(n, t)));
-  for (const n of i) {
-    const o = n.status === "fulfilled" ? n.value : "failed";
-    o === "skipped" ? r.skipped++ : o === "conflicted" ? r.conflicted++ : (r.attempted++, r[o]++);
+  const c = await Promise.allSettled(a.map((r) => E(r, t)));
+  for (const r of c) {
+    const n = r.status === "fulfilled" ? r.value : "failed";
+    n === "skipped" ? i.skipped++ : n === "conflicted" ? i.conflicted++ : n === "cancelled" ? i.cancelled++ : (i.attempted++, i[n]++);
   }
 }
-async function Q(e) {
-  const t = await u().getPending(), r = Date.now(), a = t.filter((n) => n.retryCount < n.maxRetries && (!n.nextRetryAt || n.nextRetryAt <= r)), i = {
-    attempted: 0,
-    succeeded: 0,
-    failed: 0,
-    retrying: 0,
-    skipped: 0,
-    conflicted: 0
-  };
-  for (const n of [
+async function I(e) {
+  const t = await u().getPending(), i = Date.now(), a = t.filter((r) => r.retryCount < r.maxRetries && (!r.nextRetryAt || r.nextRetryAt <= i)), c = w();
+  for (const r of [
     "high",
     "normal",
     "low"
-  ]) await I(a.filter((o) => (o.priority ?? "normal") === n), e, i);
-  return i;
+  ]) await D(a.filter((n) => (n.priority ?? "normal") === r), e, c);
+  return c;
 }
-async function A() {
-  await u().clear(), s.getState().hydrateQueue([]);
+async function T() {
+  await u().clear(), y.getState().hydrateQueue([]);
 }
 export {
-  C as action,
-  A as clearQueue,
-  _ as replayQueue
+  U as action,
+  T as clearQueue,
+  $ as replayQueue
 };
 
 //# sourceMappingURL=action.js.map

package/dist/cli.js

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import { generateKeyPairSync } from "node:crypto";
+import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+//#region src/cli.ts
+var PUBLIC_KEY_NAME = "EIDOS_VAPID_PUBLIC_KEY";
+var PRIVATE_KEY_NAME = "EIDOS_VAPID_PRIVATE_KEY";
+function base64UrlFromBuffer(buf) {
+	return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlToBuffer(b64url) {
+	const b64 = (b64url + "=".repeat((4 - b64url.length % 4) % 4)).replace(/-/g, "+").replace(/_/g, "/");
+	return Buffer.from(b64, "base64");
+}
+/** Pads a base64url-encoded big-endian integer to `length` bytes (leading zeros). */
+function padTo(b64url, length) {
+	const buf = base64UrlToBuffer(b64url);
+	if (buf.length === length) return buf;
+	const padded = Buffer.alloc(length);
+	buf.copy(padded, length - buf.length);
+	return padded;
+}
+function generateVapidKeys() {
+	const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+	const pubJwk = publicKey.export({ format: "jwk" });
+	const privJwk = privateKey.export({ format: "jwk" });
+	const x = padTo(pubJwk.x, 32);
+	const y = padTo(pubJwk.y, 32);
+	const point = Buffer.concat([
+		Buffer.from([4]),
+		x,
+		y
+	]);
+	const d = padTo(privJwk.d, 32);
+	return {
+		publicKey: base64UrlFromBuffer(point),
+		privateKey: base64UrlFromBuffer(d)
+	};
+}
+function detectEnvPrefix(cwd) {
+	if (existsSync(resolve(cwd, "next.config.js")) || existsSync(resolve(cwd, "next.config.ts"))) return "NEXT_PUBLIC_";
+	if (existsSync(resolve(cwd, "vite.config.ts")) || existsSync(resolve(cwd, "vite.config.js"))) return "VITE_";
+	if (existsSync(resolve(cwd, "svelte.config.js"))) return "PUBLIC_";
+	if (existsSync(resolve(cwd, "nuxt.config.ts")) || existsSync(resolve(cwd, "nuxt.config.js"))) return "NUXT_PUBLIC_";
+	return "";
+}
+function pickEnvFile(cwd) {
+	if (existsSync(resolve(cwd, ".env.local"))) return resolve(cwd, ".env.local");
+	if (existsSync(resolve(cwd, ".env"))) return resolve(cwd, ".env");
+	return resolve(cwd, ".env.local");
+}
+async function confirm(message) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	const answer = await rl.question(`${message} (type "yes" to continue): `);
+	rl.close();
+	return answer.trim().toLowerCase() === "yes";
+}
+async function generateVapidKeysCommand() {
+	const cwd = process.cwd();
+	const publicKeyName = `${detectEnvPrefix(cwd)}${PUBLIC_KEY_NAME}`;
+	const force = process.argv.includes("--force");
+	const envFile = pickEnvFile(cwd);
+	const existing = existsSync(envFile) ? readFileSync(envFile, "utf8") : "";
+	const hasPublic = new RegExp(`^${publicKeyName}=`, "m").test(existing);
+	const hasPrivate = new RegExp(`^${PRIVATE_KEY_NAME}=`, "m").test(existing);
+	if (hasPublic && hasPrivate) {
+		if (!force) {
+			console.log(`VAPID keys already configured in ${envFile} — nothing to do.`);
+			console.log("Pass --force to regenerate (this invalidates ALL existing push subscriptions).");
+			return;
+		}
+		if (!await confirm(`⚠ Regenerating VAPID keys will invalidate ALL existing push subscriptions in ${envFile}. Continue?`)) {
+			console.log("Aborted.");
+			return;
+		}
+	}
+	const { publicKey, privateKey } = generateVapidKeys();
+	const lines = [`${publicKeyName}=${publicKey}`, `${PRIVATE_KEY_NAME}=${privateKey}`];
+	if (hasPublic && hasPrivate) writeFileSync(envFile, `${existing.split("\n").filter((line) => !line.startsWith(`${publicKeyName}=`) && !line.startsWith(`${PRIVATE_KEY_NAME}=`)).join("\n").replace(/\n+$/, "")}\n${lines.join("\n")}\n`);
+	else appendFileSync(envFile, `${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}${lines.join("\n")}\n`);
+	console.log(`✓ VAPID keys written to ${envFile}`);
+	console.log("");
+	console.log(`  ${publicKeyName}=${publicKey}`);
+	console.log(`  ${PRIVATE_KEY_NAME}=${privateKey}`);
+	console.log("");
+	console.log(`Give ${PRIVATE_KEY_NAME} and ${publicKeyName} to your backend.`);
+	console.log("Backend needs a VAPID-capable web-push library (any language) to send notifications using subscription objects received via onSubscribe.");
+}
+var command = process.argv[2];
+switch (command) {
+	case "generate-vapid-keys":
+		await generateVapidKeysCommand();
+		break;
+	default:
+		console.log("Usage: eidos generate-vapid-keys [--force]");
+		process.exit(command ? 1 : 0);
+}
+//#endregion