@swoff/cli 0.3.5 → 0.3.7

package/dist/lib/generators/file-generators/mutation-queue.js

@@ -4,14 +4,22 @@
 import { writeFile } from "./context.js";
 export function generateMutationQueue(ctx) {
     const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type} ` : " ");
+    const PT = (type) => (ts ? `<${type}>` : "");
+    const AS = (type) => (ts ? ` as ${type}` : "");
     const authEnabled = ctx.config.features.auth.enabled;
     const importLines = authEnabled
-        ? `import { getAuth } from "./auth-store.${ext}";
+        ? `import { getAuth } from "./auth/store.${ext}";
 `
         : "";
+    const additionalImports = `import { invalidateByTags } from "./cache.${ext}";
+${ts ? `import type { MutationQueueItem } from "./swoff.d.ts";
+` : ""}`;
     const authReplayBlock = authEnabled
         ? `  const auth = await getAuth();
-  const authHeader = auth?.token ? { Authorization: \`Bearer \${auth.token}\` } : {};
+  const authHeader${T("Record<string, string>")} = auth?.token ? { Authorization: \`Bearer \${auth.token}\` } : {};
 `
         : "";
     const authHeadersSpread = authEnabled
@@ -30,8 +38,6 @@ export function generateMutationQueue(ctx) {
  *     url: "/api/todos",
  *     body: { title: "Grocery" },
  *     tags: ["todos"],
- *     storeName: "todos",
- *     tempId: "temp_abc123",
  *   });
  *
  *   // Flush queued mutations (e.g., after login)
@@ -40,47 +46,57 @@ export function generateMutationQueue(ctx) {
  *   // Auto-processes on online event
  */
 
-${importLines}const DB_NAME = "swoff-queue";
+${importLines}${additionalImports}const DB_NAME = "swoff-queue";
 const STORE_NAME = "mutations";
 const MAX_RETRIES = 5;
 
-function openQueueDB() {
-  return new Promise((resolve, reject) => {
+function openQueueDB()${R("Promise<IDBDatabase>")}{
+  return new Promise${PT("IDBDatabase")}((resolve, reject) => {
     const request = indexedDB.open(DB_NAME, 1);
     request.onupgradeneeded = (e) => {
-      const db = e.target.result;
+      const db = (e.target${AS("IDBOpenDBRequest")}).result;
       if (!db.objectStoreNames.contains(STORE_NAME)) {
         const store = db.createObjectStore(STORE_NAME, { keyPath: "id" });
         store.createIndex("by-timestamp", "timestamp");
       }
     };
-    request.onsuccess = (e) => resolve(e.target.result);
-    request.onerror = (e) => reject(e.target.error);
+    request.onsuccess = (e) => resolve((e.target${AS("IDBOpenDBRequest")}).result);
+    request.onerror = (e) => reject((e.target${AS("IDBRequest")}).error);
   });
 }
 
 let isSyncing = false;
 
-export async function queueMutation(mutation) {
+/** Store a write operation in IndexedDB for later sync. Works offline — use it for POST/PUT/PATCH/DELETE when the user might be offline. */
+export async function queueMutation(mutation${T("Partial<MutationQueueItem>")})${R("Promise<void>")}{
   const db = await openQueueDB();
   const tx = db.transaction(STORE_NAME, "readwrite");
   const store = tx.objectStore(STORE_NAME);
 
+  let body = mutation.body;
+  let bodyType = "json";
+  if (body instanceof FormData) {
+    bodyType = "formdata";
+    body = [...body.entries()];
+  } else if (body instanceof Blob) {
+    bodyType = "blob";
+  } else if (body instanceof ArrayBuffer || ArrayBuffer.isView(body)) {
+    bodyType = "buffer";
+  }
+
   store.add({
     id: crypto.randomUUID(),
     method: mutation.method,
     url: mutation.url,
-    body: mutation.body,
+    body,
+    bodyType,
     headers: mutation.headers || {},
-    previousData: mutation.previousData || null,
     timestamp: Date.now(),
     retryCount: 0,
     tags: mutation.tags || [],
-    storeName: mutation.storeName || null,
-    tempId: mutation.tempId || null,
   });
 
-  await new Promise((resolve, reject) => {
+  await new Promise<void>((resolve, reject) => {
     tx.oncomplete = () => resolve();
     tx.onerror = () => reject(tx.error);
   });
@@ -88,7 +104,8 @@ export async function queueMutation(mutation) {
   window.dispatchEvent(new CustomEvent("mutation-queue-changed"));
 }
 
-export async function processMutationQueue() {
+/** Process all queued mutations in order. Sends them to the server. Runs automatically on the online event. */
+export async function processMutationQueue()${R("Promise<void>")}{
   if (!navigator.onLine || isSyncing) return;
   isSyncing = true;
 
@@ -97,7 +114,7 @@ ${authReplayBlock}    const db = await openQueueDB();
     const tx = db.transaction(STORE_NAME, "readonly");
     const store = tx.objectStore(STORE_NAME);
     const index = store.index("by-timestamp");
-    const queue = await new Promise((resolve, reject) => {
+    const queue${T("MutationQueueItem[]")} = await new Promise${PT("MutationQueueItem[]")}((resolve, reject) => {
       const request = index.getAll();
       request.onsuccess = () => resolve(request.result);
       request.onerror = () => reject(request.error);
@@ -108,32 +125,40 @@ ${authReplayBlock}    const db = await openQueueDB();
 
     for (const item of queue) {
       if (item.retryCount >= MAX_RETRIES) {
-        await rollbackMutation(item);
         await removeFromQueue(item.id);
         failed++;
         continue;
       }
 
       try {
+        let replayBody${T("BodyInit | null")}${ts ? " = null" : ""};
+        let contentType${T("string | undefined")};
+        const bt = item.bodyType || "json";
+        if (bt === "formdata") {
+          replayBody = new FormData();
+          for (const [key, value] of (item.body || [])${AS("[string, FormDataEntryValue][]")}) {
+            replayBody.append(key, value);
+          }
+        } else if (bt === "blob") {
+          replayBody = item.body${AS("BodyInit | null")};
+        } else if (bt === "buffer") {
+          replayBody = item.body instanceof ArrayBuffer ? new Uint8Array(item.body)${AS("BodyInit")} : item.body${AS("BodyInit")};
+        } else {
+          replayBody = JSON.stringify(item.body);
+          contentType = "application/json";
+        }
         const response = await fetch(item.url, {
           method: item.method,
           headers: {
-            "Content-Type": "application/json",
+            ...(contentType ? { "Content-Type": contentType } : {}),
 ${authHeadersSpread}            ...item.headers,
           },
-          body: JSON.stringify(item.body),
+          body: replayBody,
         });
 
         if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
 
-        const serverData = await response.json();
-
-        if (item.tempId && item.storeName) {
-          await reconcileRecord(item.storeName, item.tempId, serverData);
-        }
-
         if (item.tags && item.tags.length > 0) {
-          const { invalidateByTags } = await import("./cache.${ext}");
           await invalidateByTags(item.tags);
         }
 
@@ -157,88 +182,41 @@ ${authHeadersSpread}            ...item.headers,
   }
 }
 
-export async function flushMutations() {
+/** Immediately process all queued mutations. Call this after re-login to flush mutations that failed due to auth expiry. */
+export async function flushMutations()${R("Promise<void>")}{
   await processMutationQueue();
 }
 `;
-    // Helper functions (unchanged) are appended outside the template string
+    // Helper functions appended outside the template string
     const helpers = `
-async function removeFromQueue(id) {
+async function removeFromQueue(id${T("string")})${R("Promise<void>")}{
   const db = await openQueueDB();
   const tx = db.transaction(STORE_NAME, "readwrite");
   tx.objectStore(STORE_NAME).delete(id);
-  await new Promise((resolve, reject) => {
+  await new Promise${PT("void")}((resolve, reject) => {
     tx.oncomplete = () => resolve();
     tx.onerror = () => reject(tx.error);
   });
 }
 
-async function updateInQueue(item) {
+async function updateInQueue(item${T("MutationQueueItem")})${R("Promise<void>")}{
   const db = await openQueueDB();
   const tx = db.transaction(STORE_NAME, "readwrite");
   tx.objectStore(STORE_NAME).put(item);
-  await new Promise((resolve, reject) => {
+  await new Promise${PT("void")}((resolve, reject) => {
     tx.oncomplete = () => resolve();
     tx.onerror = () => reject(tx.error);
   });
 }
 
-async function rollbackMutation(item) {
-  if (!item.storeName) return;
-
-  if (item.method === "POST" && item.tempId) {
-    const { deleteRecord } = await import("./store.${ext}");
-    await deleteRecord(item.storeName, item.tempId);
-  } else if (
-    (item.method === "PUT" || item.method === "PATCH") &&
-    item.previousData
-  ) {
-    const { putRecord } = await import("./store.${ext}");
-    await putRecord(item.storeName, { ...item.previousData, $synced: true });
-  } else if (item.method === "DELETE" && item.tempId && item.previousData) {
-    const { putRecord } = await import("./store.${ext}");
-    await putRecord(item.storeName, { ...item.previousData, $synced: true });
-  }
-
-  window.dispatchEvent(
-    new CustomEvent("mutation-rollback", {
-      detail: {
-        method: item.method,
-        url: item.url,
-        tempId: item.tempId,
-        previousData: item.previousData,
-      },
-    })
-  );
-}
-
-async function reconcileRecord(storeName, tempId, serverData) {
-  const { getRecord, putRecord, deleteRecord } = await import("./store.${ext}");
-  const existing = await getRecord(storeName, tempId);
-  if (!existing) return;
-
-  const reconciled = {
-    ...existing,
-    ...serverData,
-    id: serverData.id,
-    $synced: true,
-    $syncedAt: Date.now(),
-  };
-
-  await putRecord(storeName, reconciled);
-
-  if (String(tempId) !== String(serverData.id)) {
-    await deleteRecord(storeName, tempId);
-  }
-}
-
-export async function getPendingCount() {
+/** Get the number of queued mutations waiting to be synced. Useful for showing a sync badge. */
+export async function getPendingCount()${R("Promise<number>")}{
   const db = await openQueueDB();
-  return new Promise((resolve, reject) => {
+  return new Promise${PT("number")}((resolve, reject) => {
     const tx = db.transaction(STORE_NAME, "readonly");
     const request = tx.objectStore(STORE_NAME).count();
-    request.onsuccess = () => resolve(request.result);
-    request.onerror = () => reject(request.error);
+    request.onsuccess = () => resolve((request${AS("IDBRequest<number>")}).result);
+    request.onerror = () => reject((request${AS("IDBRequest")}).error);
   });
 }
 `;

package/dist/lib/generators/file-generators/mutation-queue.js.map

@@ -1 +1 @@
-{"version":3,"file":"mutation-queue.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-queue.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,qBAAqB,CAAC,GAAqB;IACzD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC;IAErD,MAAM,WAAW,GAAG,WAAW;QAC7B,CAAC,CAAC,yCAAyC,GAAG;CACjD;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,eAAe,GAAG,WAAW;QACjC,CAAC,CAAC;;CAEL;QACG,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,iBAAiB,GAAG,WAAW;QACnC,CAAC,CAAC,4BAA4B;QAC9B,CAAC,CAAC,EAAE,CAAC;IAEP,MAAM,IAAI,GAAG;;;;;oHAKqG,GAAG;;;;;;;;;;;;;;;;;;EAkBrH,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAqDX,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;EA0Bf,iBAAiB;;;;;;;;;;;;;;+DAc4C,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BjE,CAAC;IAEA,wEAAwE;IACxE,MAAM,OAAO,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;qDAyBmC,GAAG;;;;;;kDAMN,GAAG;;;kDAGH,GAAG;;;;;;;;;;;;;;;;;yEAiBoB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4B3E,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,kBAAkB,GAAG,EAAE,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"mutation-queue.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-queue.ts"],"names":[],"mappings":"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"}

package/dist/lib/generators/file-generators/mutation-reconcile.js

@@ -0,0 +1,57 @@
+/**
+ * Generates mutation-reconcile.js - ID reconciliation after mutation sync.
+ */
+import { writeFile } from "./context.js";
+export function generateMutationReconcile(ctx) {
+    const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type} ` : " ");
+    const AS = (type) => (ts ? ` as ${type}` : "");
+    const code = `/**
+ * Swoff Mutation Reconciliation
+ * Reconciles local optimistic records with server response after a queued
+ * mutation is processed by the service worker.
+ *
+ * Usage:
+ *   import { reconcileRecord } from './swoff/mutation-reconcile.${ext}';
+ *
+ *   // Called automatically by mutation-queue after a successful sync
+ *   await reconcileRecord('todos', 'temp_abc123', serverData);
+ *
+ *   // Only override this if your data has foreign key references:
+ *   // export async function reconcileReferences(...) { ... }
+ */
+
+import { getRecord, putRecord, deleteRecord } from './store.${ext}';
+
+/** Replace a temporary optimistic ID with the server-assigned ID after mutation sync. Called automatically by mutation-queue. */
+export async function reconcileRecord(storeName${T("string")}, tempId${T("string")}, serverData${T("Record<string, unknown>")})${R("Promise<void>")}{
+  const existing = await getRecord(storeName, tempId);
+  if (!existing) return;
+
+  const reconciled = {
+    ...existing,
+    ...serverData,
+    id: serverData.id,
+    $synced: true,
+    $syncedAt: Date.now(),
+  };
+
+  await putRecord(storeName, reconciled);
+
+  if (String(tempId) !== String(serverData.id)) {
+    await deleteRecord(storeName, tempId);
+  }
+
+  await reconcileReferences(storeName, tempId, serverData.id${AS("string | number")});
+}
+
+/** Update foreign key references in other records that pointed to the old temp ID. Override this for your app's schema relationships. */
+export async function reconcileReferences(_storeName${T("string")}, _oldId${T("string")}, _newId${T("string | number")})${R("Promise<void>")}{
+  // Override this for your app's schema.
+}
+`;
+    writeFile(ctx, `mutation-reconcile.${ext}`, code);
+}
+//# sourceMappingURL=mutation-reconcile.js.map

package/dist/lib/generators/file-generators/mutation-reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-reconcile.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/mutation-reconcile.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,yBAAyB,CAAC,GAAqB;IAC7D,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvD,MAAM,IAAI,GAAG;;;;;;mEAMoD,GAAG;;;;;;;;;8DASR,GAAG;;;iDAGhB,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,yBAAyB,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;8DAkBrF,EAAE,CAAC,iBAAiB,CAAC;;;;sDAI7B,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC;;;CAG3I,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,sBAAsB,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACpD,CAAC"}

package/dist/lib/generators/file-generators/push.js

@@ -0,0 +1,143 @@
+/**
+ * Generates push.{js|ts} - push notification subscription management.
+ */
+import { writeFile } from "./context.js";
+export function generatePush(ctx) {
+    const ext = ctx.ext;
+    const ts = ext === "ts";
+    const T = (type) => (ts ? `: ${type}` : "");
+    const R = (type) => (ts ? `: ${type} ` : " ");
+    const PT = (type) => (ts ? `<${type}>` : "");
+    const AS = (type) => (ts ? ` as ${type}` : "");
+    const code = `/**
+ * Swoff Push Notifications
+ * Push subscription management with IndexedDB persistence.
+ *
+ * Usage:
+ *   import { subscribeToPush, unsubscribeFromPush, isSubscribed } from './swoff/push.${ext}';
+ *
+ *   // Enable (triggers permission prompt)
+ *   const subscription = await subscribeToPush("YOUR_VAPID_PUBLIC_KEY");
+ *   await fetch("/api/push/subscribe", {
+ *     method: "POST",
+ *     body: JSON.stringify(subscription.toJSON()),
+ *   });
+ *
+ *   // Disable
+ *   await unsubscribeFromPush();
+ *
+ * Window events:
+ *   push-permission-changed   - Permission granted/denied (detail: { permission })
+ *   push-subscription-changed - Subscribed/unsubscribed (detail: { subscribed })
+ */
+
+const SUBSCRIPTION_DB = "swoff-push";
+const SUBSCRIPTION_STORE = "subscription";
+
+let permissionState = Notification.permission;
+
+function openPushDB()${R("Promise<IDBDatabase>")}{
+  return new Promise${PT("IDBDatabase")}((resolve, reject) => {
+    const request = indexedDB.open(SUBSCRIPTION_DB, 1);
+    request.onupgradeneeded = (e) => {
+      const db = (e.target${AS("IDBOpenDBRequest")}).result;
+      if (!db.objectStoreNames.contains(SUBSCRIPTION_STORE)) {
+        db.createObjectStore(SUBSCRIPTION_STORE, { keyPath: "id" });
+      }
+    };
+    request.onsuccess = (e) => resolve((e.target${AS("IDBOpenDBRequest")}).result);
+    request.onerror = (e) => reject((e.target${AS("IDBRequest")}).error);
+  });
+}
+
+/** Request notification permission from the user. Returns true if granted. */
+export async function requestNotificationPermission()${R("Promise<boolean>")}{
+  if (permissionState === "granted") return true;
+  if (permissionState === "denied") return false;
+
+  const result = await Notification.requestPermission();
+  permissionState = result;
+  window.dispatchEvent(
+    new CustomEvent("push-permission-changed", { detail: { permission: result } }),
+  );
+  return result === "granted";
+}
+
+/** Get the current push subscription, or null if not subscribed. */
+export async function getPushSubscription()${R("Promise<PushSubscription | null>")}{
+  try {
+    const registration = await navigator.serviceWorker.ready;
+    return await registration.pushManager.getSubscription();
+  } catch {
+    return null;
+  }
+}
+
+/** Subscribe to push notifications. Returns the subscription or null if permission denied. */
+export async function subscribeToPush(vapidPublicKey${T("string")})${R("Promise<PushSubscription | null>")}{
+  const granted = await requestNotificationPermission();
+  if (!granted) return null;
+
+  const registration = await navigator.serviceWorker.ready;
+  const subscription = await registration.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(vapidPublicKey)${AS("BufferSource")},
+  });
+
+  const db = await openPushDB();
+  const tx = db.transaction(SUBSCRIPTION_STORE, "readwrite");
+  tx.objectStore(SUBSCRIPTION_STORE).put({
+    id: "current",
+    endpoint: subscription.endpoint,
+    keys: subscription.toJSON().keys,
+    subscribedAt: Date.now(),
+  });
+  await new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+
+  window.dispatchEvent(
+    new CustomEvent("push-subscription-changed", { detail: { subscribed: true } }),
+  );
+
+  return subscription;
+}
+
+/** Unsubscribe from push notifications. */
+export async function unsubscribeFromPush()${R("Promise<void>")}{
+  const subscription = await getPushSubscription();
+  if (!subscription) return;
+
+  await subscription.unsubscribe();
+
+  const db = await openPushDB();
+  const tx = db.transaction(SUBSCRIPTION_STORE, "readwrite");
+  tx.objectStore(SUBSCRIPTION_STORE).delete("current");
+  await new Promise<void>((resolve, reject) => {
+    tx.oncomplete = () => resolve();
+    tx.onerror = () => reject(tx.error);
+  });
+
+  window.dispatchEvent(
+    new CustomEvent("push-subscription-changed", { detail: { subscribed: false } }),
+  );
+}
+
+/** Check if the user is subscribed to push notifications. */
+export async function isSubscribed()${R("Promise<boolean>")}{
+  const sub = await getPushSubscription();
+  return sub !== null;
+}
+
+/** Convert a base64 VAPID public key to a Uint8Array for pushManager.subscribe(). */
+function urlBase64ToUint8Array(base64String${T("string")})${R("Uint8Array")}{
+  const padding = "=".repeat((4 - (base64String.length % 4)) % 4);
+  const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+  const rawData = atob(base64);
+  return Uint8Array.from(rawData, (c) => c.charCodeAt(0));
+}
+`;
+    writeFile(ctx, `push.${ext}`, code);
+}
+//# sourceMappingURL=push.js.map

package/dist/lib/generators/file-generators/push.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/push.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,YAAY,CAAC,GAAqB;IAChD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACpD,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrD,MAAM,EAAE,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEvD,MAAM,IAAI,GAAG;;;;;wFAKyE,GAAG;;;;;;;;;;;;;;;;;;;;;;uBAsBpE,CAAC,CAAC,sBAAsB,CAAC;sBAC1B,EAAE,CAAC,aAAa,CAAC;;;4BAGX,EAAE,CAAC,kBAAkB,CAAC;;;;;kDAKA,EAAE,CAAC,kBAAkB,CAAC;+CACzB,EAAE,CAAC,YAAY,CAAC;;;;;uDAKR,CAAC,CAAC,kBAAkB,CAAC;;;;;;;;;;;;;6CAa/B,CAAC,CAAC,kCAAkC,CAAC;;;;;;;;;;sDAU5B,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,kCAAkC,CAAC;;;;;;;iEAOzC,EAAE,CAAC,cAAc,CAAC;;;;;;;;;;;;;;;;;;;;;;;;6CAwBtC,CAAC,CAAC,eAAe,CAAC;;;;;;;;;;;;;;;;;;;;sCAoBzB,CAAC,CAAC,kBAAkB,CAAC;;;;;;6CAMd,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,YAAY,CAAC;;;;;;CAM1E,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AACtC,CAAC"}

package/dist/lib/generators/file-generators/pwa-install.js

@@ -4,28 +4,60 @@
 import { writeFile } from "./context.js";
 export function generatePwaInstall(ctx) {
     const ext = ctx.ext;
+    const ts = ext === "ts";
+    const R = (type) => (ts ? `: ${type} ` : " ");
+    const preventDefaultInstall = ctx.config.features.pwa.preventDefaultInstall;
+    const preventLine = preventDefaultInstall ? "    e.preventDefault();\n" : "";
     const code = `/**
- * Swoff PWA Install Prompt
- * Manual install trigger and installability check.
- * Event listeners are registered in sw-injector at app entry.
+ * Swoff PWA Install Support
+ * Manual install trigger, installability check, and event listener setup.
  *
  * Usage:
- *   import { isInstallable, promptInstall } from './swoff/pwa-install.${ext}';
+ *   import { setupPwaInstall, isInstallable, promptInstall } from './swoff/pwa/install.${ext}';
+ *
+ *   setupPwaInstall();  // sets up beforeinstallprompt and appinstalled listeners
  *
  *   if (isInstallable()) {
  *     const result = await promptInstall();
- *     console.log('User choice:', result.outcome);
  *   }
  *
- * Window properties (set by sw-injector):
+ * Window properties:
  *   window.deferredInstallPrompt - The captured BeforeInstallPromptEvent
  */
 
-export function isInstallable() {
+/** Set up beforeinstallprompt and appinstalled event listeners. Call once at app startup. */
+export function setupPwaInstall()${R("void")}{
+  window.addEventListener("beforeinstallprompt", (e) => {
+    window.deferredInstallPrompt = e as BeforeInstallPromptEvent;
+    window.pwaInstallable = true;
+
+${preventLine}
+    window.dispatchEvent(
+      new CustomEvent("pwa-installable", {
+        detail: { isInstallable: true },
+      })
+    );
+  });
+
+  window.addEventListener("appinstalled", () => {
+    window.deferredInstallPrompt = null;
+    window.pwaInstallable = false;
+
+    window.dispatchEvent(
+      new CustomEvent("pwa-installed", {
+        detail: { outcome: "accepted" },
+      })
+    );
+  });
+}
+
+/** Check if the PWA install prompt is available (user has met install criteria). */
+export function isInstallable()${R("boolean")}{
   return !!window.deferredInstallPrompt;
 }
 
-export async function promptInstall() {
+/** Show the browser's native install prompt. Throws if prompt is not available. */
+export async function promptInstall()${R("Promise<{ outcome: string }>")}{
   if (!window.deferredInstallPrompt) {
     throw new Error("Install prompt not available");
   }
@@ -53,6 +85,6 @@ export async function promptInstall() {
   return choice;
 }
 `;
-    writeFile(ctx, `pwa-install.${ext}`, code);
+    writeFile(ctx, `pwa/install.${ext}`, code);
 }
 //# sourceMappingURL=pwa-install.js.map

package/dist/lib/generators/file-generators/pwa-install.js.map

@@ -1 +1 @@
-{"version":3,"file":"pwa-install.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/pwa-install.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,kBAAkB,CAAC,GAAqB;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IAEpB,MAAM,IAAI,GAAG;;;;;;yEAM0D,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0C3E,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC"}
+{"version":3,"file":"pwa-install.js","sourceRoot":"","sources":["../../../../src/lib/generators/file-generators/pwa-install.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAoB,SAAS,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,UAAU,kBAAkB,CAAC,GAAqB;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,CAAC;IACpB,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,CAAC;IACxB,MAAM,CAAC,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACtD,MAAM,qBAAqB,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,qBAAqB,CAAC;IAC5E,MAAM,WAAW,GAAG,qBAAqB,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,EAAE,CAAC;IAE7E,MAAM,IAAI,GAAG;;;;;0FAK2E,GAAG;;;;;;;;;;;;;mCAa1D,CAAC,CAAC,MAAM,CAAC;;;;;EAK1C,WAAW;;;;;;;;;;;;;;;;;;;;;iCAqBoB,CAAC,CAAC,SAAS,CAAC;;;;;uCAKN,CAAC,CAAC,8BAA8B,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2BvE,CAAC;IAEA,SAAS,CAAC,GAAG,EAAE,eAAe,GAAG,EAAE,EAAE,IAAI,CAAC,CAAC;AAC7C,CAAC"}

package/dist/lib/generators/file-generators/quick-readme.js

@@ -0,0 +1,88 @@
+/**
+ * Generates README.md — quick reference for integrating enabled features.
+ */
+import { writeFile } from "./context.js";
+export function generateReadme(ctx) {
+    const { config } = ctx;
+    const ext = ctx.ext;
+    const lines = [];
+    const w = (s) => lines.push(s);
+    w("# Swoff — Quick Reference");
+    w("");
+    w("For the full guide with explanations, read **[GUIDE.md](./GUIDE.md)**.");
+    w("");
+    const hasClientInjector = true;
+    if (hasClientInjector) {
+        w("## Entry point");
+        w("```ts");
+        w(`import { initServiceWorker } from "./swoff/client-injector.${ext}";`);
+        w("initServiceWorker();");
+        w("```");
+        w("");
+    }
+    w("## API calls (use for all fetch requests)");
+    w("Use `fetchWithCache` instead of `fetch()` — it sets caching headers the SW needs.");
+    w("Plain `fetch()` skips SW caching when `cacheStrategy` is `\"explicit-only\"`.");
+    w("```ts");
+    w(`import { fetchWithCache } from "./swoff/fetch-wrapper.${ext}";`);
+    w('const data = await fetchWithCache("/api/data").then(r => r.json());');
+    w("```");
+    w("");
+    if (config.features.auth.enabled) {
+        w("## Authenticated API calls");
+        w("```ts");
+        w(`import { fetchWithCache } from "./swoff/fetch-wrapper.${ext}";`);
+        w('const data = await fetchWithCache("/api/me", { auth: true }).then(r => r.json());');
+        w("```");
+        w("");
+    }
+    if (config.features.mutationQueue) {
+        w("## Offline mutations (queue writes when offline)");
+        w("```ts");
+        w(`import { queueMutation, getPendingCount } from "./swoff/mutation-queue.${ext}";`);
+        w("await queueMutation({ method: \"POST\", url: \"/api/todos\", body: {...} });");
+        w("```");
+        w("");
+        if (config.features.auth.enabled) {
+            w("## After re-login (flush queued mutations)");
+            w("```ts");
+            w(`import { flushMutations } from "./swoff/mutation-queue.${ext}";`);
+            w("await flushMutations();");
+            w("```");
+            w("");
+        }
+    }
+    if (config.features.pushNotifications?.enabled) {
+        w("## Push notifications");
+        w("```ts");
+        w(`import { subscribeToPush, unsubscribeFromPush, isSubscribed } from "./swoff/push.${ext}";`);
+        w('const sub = await subscribeToPush("YOUR_VAPID_PUBLIC_KEY");');
+        w("```");
+        w("");
+    }
+    if (config.features.tagInvalidation) {
+        w("## Cache invalidation");
+        w("```ts");
+        w(`import { generateTags, invalidateUrl } from "./swoff/invalidation-tags.${ext}";`);
+        w('const data = await fetchWithCache("/api/todos", { tags: generateTags("/api/todos") });');
+        w('await invalidateUrl("/api/todos/42"); // after mutation');
+        w("```");
+        w("");
+    }
+    if (ctx.frameworkName === "react") {
+        w("## React hook — auto-refetch on cache invalidation");
+        w("```tsx");
+        w(`import { useCachedFetch } from "./swoff/hooks/useCachedFetch.${ext}x";`);
+        w('const { data, error, loading, refetch } = useCachedFetch("/api/todos");');
+        w("```");
+        w("");
+    }
+    w("## Build script");
+    w("The SW generator learns your build output to precache assets.");
+    w("Swoff has already added this to your `package.json`:");
+    w("```json");
+    w('"build": "<your-build> && node swoff/sw/generator.js"');
+    w("```");
+    writeFile(ctx, "README.md", lines.join("\n"));
+}
+//# sourceMappingURL=quick-readme.js.map