tempest-react-sdk 0.7.0 → 0.9.0

package/dist/sw.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Build a `206 Partial Content` response from a full one for an HTTP `Range`
+ * request. Supports `bytes=start-end`, open-ended `bytes=start-` and suffix
+ * `bytes=-suffixLength`. Returns the original response when there is no usable
+ * `Range` header, or a `416` when the range is unsatisfiable.
+ *
+ * @param request The incoming request (its `Range` header drives the slice).
+ * @param response The full (200) response to slice.
+ */
+export declare function createPartialResponse(request: Request, response: Response): Promise<Response>;
+
+/**
+ * Install the background-sync queue: on a failed mutating request, the request
+ * is serialized to IndexedDB and a sync is registered; the original fetch still
+ * rejects (so your app can show an offline state), and the request is replayed
+ * later when the network returns.
+ */
+export declare function installBackgroundSync(options?: InstallBackgroundSyncOptions): void;
+
+/**
+ * Background-sync helper: queue failed mutating requests (POST/PUT/PATCH/DELETE)
+ * while offline and replay them when connectivity returns. A dependency-free
+ * take on Workbox's `BackgroundSyncPlugin`, backed by a tiny IndexedDB queue.
+ *
+ * Import inside your `sw.ts`. Uses the Background Sync API (`registration.sync`)
+ * when available, and also replays opportunistically on the next request as a
+ * fallback for browsers without it (e.g. Safari).
+ *
+ * @example
+ *   import { installBackgroundSync } from "tempest-react-sdk/sw";
+ *
+ *   installBackgroundSync({ match: (url) => url.pathname.startsWith("/api/") });
+ */
+/** Options for {@link installBackgroundSync}. */
+export declare interface InstallBackgroundSyncOptions {
+    /**
+     * Which requests to queue on failure. A `RegExp` against the URL or a
+     * predicate. Only non-`GET` requests are ever considered. Default: all
+     * non-`GET` requests.
+     */
+    match?: RegExp | ((url: URL, request: Request) => boolean);
+    /** IndexedDB database name, also used as the sync tag. Default `tempest-bg-sync`. */
+    queueName?: string;
+    /** Drop queued requests older than this (minutes) on replay. Default `1440` (24h). */
+    maxRetentionMinutes?: number;
+}
+
+/**
+ * Install a `notificationclick` handler that focuses an existing client when
+ * possible and falls back to opening a new window.
+ */
+export declare function installNotificationClickHandler(options?: InstallNotificationClickHandlerOptions): void;
+
+export declare interface InstallNotificationClickHandlerOptions {
+    /** Resolve the destination URL from the notification data. Default: `data.url`. */
+    resolveUrl?: (data: unknown) => string;
+}
+
+/**
+ * Precache the app shell at `install` and serve it offline:
+ *  - reads `precache-manifest.json` (emitted by `tempestPwaManifest()`),
+ *  - caches every listed URL under a versioned cache,
+ *  - on `activate`, deletes stale precache versions and claims open clients,
+ *  - on `fetch`, serves precached assets cache-first and falls back to the
+ *    `navigateFallback` document for offline navigations (SPA routing).
+ *
+ * Same-origin only. Register this LAST, after any {@link installRuntimeCache}.
+ */
+export declare function installPrecache(options?: InstallPrecacheOptions): void;
+
+/** Options for {@link installPrecache}. */
+export declare interface InstallPrecacheOptions {
+    /** URL of the manifest emitted by `tempestPwaManifest()`. Default `/precache-manifest.json`. */
+    manifestUrl?: string;
+    /** Cache name prefix; the manifest `version` is appended. Default `tempest-precache`. */
+    cacheName?: string;
+    /** App-shell document served for navigation requests offline. Default `/index.html`. */
+    navigateFallback?: string;
+    /** Navigation paths that should NOT use the fallback (e.g. `[/^\/api\//]`). */
+    navigateFallbackDenylist?: RegExp[];
+    /** Activate the new worker immediately after precaching. Default `true`. */
+    skipWaiting?: boolean;
+}
+
+/**
+ * Install a `push` event listener that parses the payload as JSON (with a
+ * plain-text fallback) and shows a notification.
+ */
+export declare function installPushHandler(options?: InstallPushHandlerOptions): void;
+
+export declare interface InstallPushHandlerOptions {
+    /** Title used when the payload omits one. */
+    defaultTitle?: string;
+    /** Icon used when the payload omits one. */
+    defaultIcon?: string;
+    /** Badge image (mobile). */
+    defaultBadge?: string;
+    /**
+     * Transform the raw payload before showing the notification. Return `null`
+     * to suppress the notification entirely (e.g. silent pings).
+     */
+    transform?: (payload: PushPayload) => PushPayload | null;
+}
+
+/**
+ * Install a `fetch` handler that resolves matching `GET` requests with the
+ * given runtime strategies. Non-matching requests are left untouched (no
+ * `respondWith`), so a later {@link installPrecache} can handle them.
+ *
+ * Register this BEFORE `installPrecache` so specific routes win over the
+ * precache catch-all.
+ *
+ * @param routes Ordered rules; the first whose `match` passes handles the request.
+ */
+export declare function installRuntimeCache(routes: RuntimeRoute[]): void;
+
+/**
+ * Install a `message` listener that activates a waiting worker when the host
+ * app sends `{ type: "SKIP_WAITING" }`.
+ */
+export declare function installSkipWaitingListener(): void;
+
+/**
+ * Service-worker context helpers for handling `push` and `notificationclick`
+ * events. Import these inside your own `sw.ts` — they expect to run in the
+ * service-worker global scope, not in the main thread.
+ *
+ * @example
+ *   /// <reference lib="webworker" />
+ *   import { installPushHandler, installNotificationClickHandler } from "tempest-react-sdk";
+ *
+ *   installPushHandler({ defaultIcon: "/icons/Logo.png" });
+ *   installNotificationClickHandler();
+ */
+export declare interface PushPayload {
+    title?: string;
+    body?: string;
+    icon?: string;
+    badge?: string;
+    image?: string;
+    tag?: string;
+    url?: string;
+    /** Arbitrary extra data forwarded to `event.notification.data`. */
+    data?: Record<string, unknown>;
+}
+
+/**
+ * Register a service worker with consistent update-detection wiring.
+ *
+ * Skips silently when the runtime has no `serviceWorker` support. The host
+ * app keeps full control over the SW file — this helper only handles the
+ * boilerplate around `register()` and `updatefound`.
+ *
+ * @returns The registration when it succeeds, or `null` when unsupported.
+ */
+export declare function registerServiceWorker(options: RegisterServiceWorkerOptions): Promise<ServiceWorkerRegistration | null>;
+
+export declare interface RegisterServiceWorkerOptions {
+    /** Public URL of the compiled service worker file (e.g. `/sw.js`). */
+    url: string;
+    /** SW scope (default: SW directory). */
+    scope?: string;
+    /** Called once the registration is active. */
+    onReady?: (registration: ServiceWorkerRegistration) => void;
+    /**
+     * Called when a new worker has finished installing while another worker
+     * still controls the page. The host app typically prompts the user to
+     * reload and then calls {@link skipWaiting} on the returned worker.
+     */
+    onUpdate?: (waiting: ServiceWorker, registration: ServiceWorkerRegistration) => void;
+    /** Called on registration failure. */
+    onError?: (error: unknown) => void;
+}
+
+/** A single runtime-caching rule, matched against each `GET` request. */
+export declare interface RuntimeRoute {
+    /** A `RegExp` tested against the full URL, or a predicate over the parsed URL. */
+    match: RegExp | ((url: URL, request: Request) => boolean);
+    /** How to resolve a match. */
+    strategy: RuntimeStrategy;
+    /** Cache bucket name for this route. */
+    cacheName: string;
+    /** Trim the cache to at most this many entries (FIFO) after each write. */
+    maxEntries?: number;
+    /** Treat a cached response older than this (seconds) as a miss. */
+    maxAgeSeconds?: number;
+    /** For `network-first`: fall back to cache after this timeout (seconds). */
+    networkTimeoutSeconds?: number;
+    /**
+     * Serve HTTP `Range` requests (206 Partial Content) by slicing the cached
+     * full response. Enable for audio/video so seeking works offline. The full
+     * resource is cached once (the `Range` header is stripped before caching).
+     */
+    rangeRequests?: boolean;
+}
+
+/**
+ * Service-worker caching helpers — a small, dependency-free subset of what
+ * Workbox provides: precaching of the build's app shell (so the app launches
+ * offline) plus runtime caching strategies for fonts, APIs and images.
+ *
+ * Import these inside your own `sw.ts`. They run in the service-worker global
+ * scope, not the main thread. Pair `installPrecache` with the
+ * `tempestPwaManifest()` Vite plugin (from `tempest-react-sdk/vite`), which
+ * emits the `precache-manifest.json` this reads at install time.
+ *
+ * @example
+ *   /// <reference lib="webworker" />
+ *   import { installRuntimeCache, installPrecache } from "tempest-react-sdk/sw";
+ *
+ *   // Register specific routes FIRST so they win over the precache catch-all.
+ *   installRuntimeCache([
+ *     { match: /\/api\//, strategy: "network-first", cacheName: "api", maxAgeSeconds: 300 },
+ *   ]);
+ *   installPrecache();
+ */
+/** Caching strategy for a runtime route. Mirrors the common Workbox trio. */
+export declare type RuntimeStrategy = "cache-first" | "network-first" | "stale-while-revalidate";
+
+/**
+ * Tell a waiting worker to activate immediately. Pair with `onUpdate` to roll
+ * out updates after the user confirms a reload prompt.
+ */
+export declare function skipWaiting(worker: ServiceWorker): void;
+
+/**
+ * Unregister all registered service workers for this origin.
+ *
+ * @returns Number of workers that were unregistered.
+ */
+export declare function unregisterAllServiceWorkers(): Promise<number>;
+
+export { }

package/dist/sw.js

@@ -0,0 +1,361 @@
+async function j(t) {
+  if (typeof navigator > "u" || !("serviceWorker" in navigator))
+    return null;
+  try {
+    const e = await navigator.serviceWorker.register(t.url, {
+      scope: t.scope
+    });
+    return e.active && t.onReady?.(e), e.addEventListener("updatefound", () => {
+      const a = e.installing;
+      a && a.addEventListener("statechange", () => {
+        a.state === "installed" && navigator.serviceWorker.controller && t.onUpdate?.(a, e);
+      });
+    }), e;
+  } catch (e) {
+    return t.onError?.(e), null;
+  }
+}
+function q(t) {
+  t.postMessage({ type: "SKIP_WAITING" });
+}
+async function C() {
+  if (typeof navigator > "u" || !("serviceWorker" in navigator)) return 0;
+  const t = await navigator.serviceWorker.getRegistrations();
+  let e = 0;
+  for (const a of t)
+    await a.unregister() && (e += 1);
+  return e;
+}
+function w() {
+  return globalThis;
+}
+function H(t = {}) {
+  const e = w(), { defaultTitle: a = "Notificação", defaultIcon: n, defaultBadge: c, transform: i } = t;
+  e.addEventListener("push", (r) => {
+    if (!r.data) return;
+    let s;
+    try {
+      s = r.data.json();
+    } catch {
+      s = { title: a, body: r.data.text() };
+    }
+    const o = i ? i(s) : s;
+    if (!o) return;
+    const u = o.title ?? a, l = {
+      body: o.body,
+      icon: o.icon ?? n,
+      badge: o.badge ?? c,
+      image: o.image,
+      tag: o.tag,
+      data: { url: o.url ?? "/", ...o.data ?? {} }
+    };
+    r.waitUntil(e.registration.showNotification(u, l));
+  });
+}
+function M(t = {}) {
+  const e = w(), a = t.resolveUrl ?? ((n) => {
+    if (typeof n == "string") return n;
+    if (n && typeof n == "object" && "url" in n) {
+      const c = n.url;
+      return typeof c == "string" ? c : "/";
+    }
+    return "/";
+  });
+  e.addEventListener("notificationclick", (n) => {
+    n.notification.close();
+    const c = a(n.notification.data);
+    n.waitUntil(
+      (async () => {
+        const i = await e.clients.matchAll({
+          type: "window",
+          includeUncontrolled: !0
+        });
+        for (const r of i)
+          if (r.url.includes(c))
+            return r.focus();
+        return e.clients.openWindow(c);
+      })()
+    );
+  });
+}
+function G() {
+  const t = w();
+  t.addEventListener("message", (e) => {
+    e.data?.type === "SKIP_WAITING" && t.skipWaiting();
+  });
+}
+function v() {
+  return globalThis;
+}
+let h = "";
+const p = /* @__PURE__ */ new Set();
+function R(t, e) {
+  if (!e) return !1;
+  const a = t.headers.get("date");
+  return a ? (Date.now() - new Date(a).getTime()) / 1e3 > e : !1;
+}
+async function g(t, e) {
+  if (!e) return;
+  const a = await caches.open(t), n = await a.keys();
+  if (!(n.length <= e))
+    for (const c of n.slice(0, n.length - e))
+      await a.delete(c);
+}
+async function S(t, e) {
+  const a = await caches.open(e.cacheName), n = await a.match(t);
+  if (n && !R(n, e.maxAgeSeconds)) return n;
+  const c = await fetch(t);
+  return c.ok && (await a.put(t, c.clone()), await g(e.cacheName, e.maxEntries)), c;
+}
+async function W(t, e) {
+  const a = await caches.open(e.cacheName), n = (async () => {
+    const i = await fetch(t);
+    return i.ok && (await a.put(t, i.clone()), await g(e.cacheName, e.maxEntries)), i;
+  })(), c = (e.networkTimeoutSeconds ?? 0) * 1e3;
+  try {
+    if (c > 0) {
+      const i = new Promise(
+        (r, s) => setTimeout(() => s(new Error("network-timeout")), c)
+      );
+      return await Promise.race([n, i]);
+    }
+    return await n;
+  } catch {
+    const i = await a.match(t);
+    if (i) return i;
+    throw new Error("network-first: no network and no cache");
+  }
+}
+async function L(t, e) {
+  const a = await caches.open(e.cacheName), n = await a.match(t), c = fetch(t).then(async (r) => (r.ok && (await a.put(t, r.clone()), await g(e.cacheName, e.maxEntries)), r)).catch(() => {
+  });
+  if (n && !R(n, e.maxAgeSeconds)) return n;
+  const i = await c;
+  if (i) return i;
+  if (n) return n;
+  throw new Error("stale-while-revalidate: no network and no cache");
+}
+function y(t, e) {
+  switch (e.strategy) {
+    case "cache-first":
+      return S(t, e);
+    case "network-first":
+      return W(t, e);
+    case "stale-while-revalidate":
+      return L(t, e);
+  }
+}
+function N(t, e, a) {
+  return typeof t.match == "function" ? t.match(e, a) : t.match.test(e.href);
+}
+async function T(t, e) {
+  const a = t.headers.get("range");
+  if (!a) return e;
+  const n = /^bytes=(\d*)-(\d*)$/.exec(a.trim());
+  if (!n || n[1] === "" && n[2] === "")
+    return new Response(null, { status: 416, statusText: "Range Not Satisfiable" });
+  const c = await e.clone().arrayBuffer(), i = c.byteLength;
+  let r, s;
+  if (n[1] === "") {
+    const l = Number(n[2]);
+    r = Math.max(0, i - l), s = i - 1;
+  } else
+    r = Number(n[1]), s = n[2] === "" ? i - 1 : Math.min(Number(n[2]), i - 1);
+  if (r > s || r >= i)
+    return new Response(null, {
+      status: 416,
+      statusText: "Range Not Satisfiable",
+      headers: { "Content-Range": `bytes */${i}` }
+    });
+  const o = c.slice(r, s + 1), u = new Headers(e.headers);
+  return u.set("Content-Range", `bytes ${r}-${s}/${i}`), u.set("Content-Length", String(o.byteLength)), u.set("Accept-Ranges", "bytes"), new Response(o, {
+    status: 206,
+    statusText: "Partial Content",
+    headers: u
+  });
+}
+function B(t) {
+  v().addEventListener("fetch", (a) => {
+    const n = a.request;
+    if (n.method !== "GET") return;
+    const c = new URL(n.url), i = t.find((r) => N(r, c, n));
+    if (i) {
+      if (i.rangeRequests && n.headers.has("range")) {
+        const r = new Request(n.url, {
+          headers: x(n.headers),
+          credentials: n.credentials,
+          mode: n.mode === "navigate" ? "same-origin" : n.mode
+        });
+        a.respondWith(
+          y(r, i).then((s) => T(n, s))
+        );
+        return;
+      }
+      a.respondWith(y(n, i));
+    }
+  });
+}
+function x(t) {
+  const e = new Headers(t);
+  return e.delete("range"), e;
+}
+function F(t = {}) {
+  const e = v(), {
+    manifestUrl: a = "/precache-manifest.json",
+    cacheName: n = "tempest-precache",
+    navigateFallback: c = "/index.html",
+    navigateFallbackDenylist: i = [],
+    skipWaiting: r = !0
+  } = t;
+  e.addEventListener("install", (s) => {
+    s.waitUntil(
+      (async () => {
+        const u = await (await fetch(a, { cache: "no-cache" })).json();
+        h = `${n}-${u.version}`, await (await caches.open(h)).addAll(u.urls);
+        for (const d of u.urls)
+          p.add(new URL(d, e.location.origin).pathname);
+        r && await e.skipWaiting();
+      })()
+    );
+  }), e.addEventListener("activate", (s) => {
+    s.waitUntil(
+      (async () => {
+        const o = await caches.keys();
+        await Promise.all(
+          o.filter((u) => u.startsWith(`${n}-`) && u !== h).map((u) => caches.delete(u))
+        ), await e.clients.claim();
+      })()
+    );
+  }), e.addEventListener("fetch", (s) => {
+    const o = s.request;
+    if (o.method !== "GET") return;
+    const u = new URL(o.url);
+    if (u.origin === e.location.origin) {
+      if (o.mode === "navigate") {
+        if (i.some((l) => l.test(u.pathname))) return;
+        s.respondWith(
+          (async () => {
+            try {
+              return await fetch(o);
+            } catch {
+              const d = await (await caches.open(h)).match(c);
+              if (d) return d;
+              throw new Error("offline and no cached app shell");
+            }
+          })()
+        );
+        return;
+      }
+      p.has(u.pathname) && s.respondWith(
+        (async () => await (await caches.open(h)).match(o) ?? fetch(o))()
+      );
+    }
+  });
+}
+function U() {
+  return globalThis;
+}
+const f = "requests";
+function m(t) {
+  return new Promise((e, a) => {
+    const n = indexedDB.open(t, 1);
+    n.onupgradeneeded = () => {
+      n.result.createObjectStore(f, { keyPath: "id", autoIncrement: !0 });
+    }, n.onsuccess = () => e(n.result), n.onerror = () => a(n.error);
+  });
+}
+function E(t) {
+  return new Promise((e, a) => {
+    t.oncomplete = () => e(), t.onerror = () => a(t.error), t.onabort = () => a(t.error);
+  });
+}
+async function P(t, e) {
+  const a = await m(t), n = a.transaction(f, "readwrite");
+  n.objectStore(f).add(e), await E(n), a.close();
+}
+async function $(t) {
+  const e = await m(t), a = e.transaction(f, "readonly"), n = await new Promise((c, i) => {
+    const r = a.objectStore(f).getAll();
+    r.onsuccess = () => c(r.result), r.onerror = () => i(r.error);
+  });
+  return e.close(), n;
+}
+async function b(t, e) {
+  const a = await m(t), n = a.transaction(f, "readwrite");
+  n.objectStore(f).delete(e), await E(n), a.close();
+}
+async function A(t, e) {
+  const a = await t.clone().arrayBuffer();
+  return {
+    url: t.url,
+    method: t.method,
+    headers: [...t.headers.entries()],
+    body: a.byteLength > 0 ? a : null,
+    timestamp: e
+  };
+}
+function D(t) {
+  return new Request(t.url, {
+    method: t.method,
+    headers: t.headers,
+    body: t.body ?? void 0
+  });
+}
+async function k(t, e, a) {
+  const n = await $(t);
+  let c = 0;
+  for (const i of n)
+    if (i.id !== void 0) {
+      if (a - i.timestamp > e) {
+        await b(t, i.id);
+        continue;
+      }
+      try {
+        const r = await fetch(D(i));
+        r.ok || r.status >= 400 && r.status < 500 ? await b(t, i.id) : c += 1;
+      } catch {
+        c += 1;
+      }
+    }
+  if (c > 0) throw new Error(`background-sync: ${c} request(s) still pending`);
+}
+function I(t, e, a) {
+  return t ? typeof t == "function" ? t(e, a) : t.test(e.href) : !0;
+}
+function _(t = {}) {
+  const e = U(), { match: a, queueName: n = "tempest-bg-sync", maxRetentionMinutes: c = 1440 } = t, i = c * 60 * 1e3;
+  e.addEventListener("fetch", (r) => {
+    const s = r.request;
+    if (s.method === "GET" || s.method === "HEAD") return;
+    const o = new URL(s.url);
+    I(a, o, s) && r.respondWith(
+      fetch(s.clone()).catch(async (u) => {
+        const l = await A(s, Date.now());
+        await P(n, l);
+        try {
+          await e.registration.sync?.register(n);
+        } catch {
+        }
+        throw u;
+      })
+    );
+  }), e.addEventListener("sync", (r) => {
+    r.tag === n && r.waitUntil(k(n, i, Date.now()));
+  }), e.addEventListener("fetch", (r) => {
+    e.registration.sync || r.request.method === "GET" && r.waitUntil(k(n, i, Date.now()).catch(() => {
+    }));
+  });
+}
+export {
+  T as createPartialResponse,
+  _ as installBackgroundSync,
+  M as installNotificationClickHandler,
+  F as installPrecache,
+  H as installPushHandler,
+  B as installRuntimeCache,
+  G as installSkipWaitingListener,
+  j as registerServiceWorker,
+  q as skipWaiting,
+  C as unregisterAllServiceWorkers
+};
+//# sourceMappingURL=sw.js.map