tempest-react-sdk 0.7.0 → 0.9.0

package/dist/tempest-react-sdk.d.ts

@@ -1259,6 +1259,17 @@ export declare interface CreateLoggerOptions {
  */
 export declare function createOfflineStore<TItem, TKey extends string | number = string>(config: OfflineStoreConfig<TItem>): OfflineStore<TItem, TKey>;
 
+/**
+ * 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>;
+
 /**
  * Build a [[TelemetryAdapter]] backed by [`posthog-js`](https://posthog.com/docs/libraries/js).
  * The PostHog client is supplied by the caller (not bundled).
@@ -2455,6 +2466,42 @@ export declare interface InputProps extends Omit<InputHTMLAttributes<HTMLInputEl
 
 export declare type InputSize = "sm" | "md" | "lg";
 
+/**
+ * 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.
@@ -2466,6 +2513,32 @@ export declare interface InstallNotificationClickHandlerOptions {
     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.
@@ -2486,6 +2559,18 @@ export declare interface InstallPushHandlerOptions {
     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" }`.
@@ -3635,6 +3720,51 @@ export declare type RouterKind = "browser" | "hash" | "memory";
 
 export { Routes }
 
+/** 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";
+
 /**
  * Apply `env(safe-area-inset-*)` padding so content avoids iOS notch /
  * Android navbar / device chrome. Wrap the outermost container of pages