kaafil-react-uikit 0.8.0 → 0.9.0

package/dist/offline/index.cjs

@@ -0,0 +1,112 @@
+'use strict';
+
+// src/offline/credentialCache.ts
+function isFetchNetworkError(error) {
+  return error instanceof TypeError;
+}
+function withCachedCredential(resolve, options) {
+  const { store } = options;
+  const isUnreachable = options.isUnreachable ?? isFetchNetworkError;
+  return async function resolveWithCache() {
+    try {
+      const fresh = await resolve();
+      await store.write(fresh);
+      return fresh;
+    } catch (error) {
+      if (!isUnreachable(error)) throw error;
+      const cached = await store.read();
+      if (cached === null) throw error;
+      return cached;
+    }
+  };
+}
+function localStorageCredentialStore(scope) {
+  const key = `kaafil:credential:${scope}`;
+  return {
+    read() {
+      try {
+        const raw = localStorage.getItem(key);
+        if (raw === null) return null;
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    write(credential) {
+      try {
+        localStorage.setItem(key, JSON.stringify(credential));
+      } catch {
+      }
+    },
+    clear() {
+      try {
+        localStorage.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/offline/serviceWorker.ts
+function isKaafilApiHost(url) {
+  return url.hostname === "kaafil.in" || url.hostname.endsWith(".kaafil.in");
+}
+function installKaafilOfflineShell(options) {
+  const scope = self;
+  const { cacheName, appShellUrl, precache } = options;
+  const isApiRequest = options.isApiRequest ?? isKaafilApiHost;
+  scope.addEventListener("install", (event) => {
+    event.waitUntil(
+      (async () => {
+        const cache = await caches.open(cacheName);
+        await cache.addAll([...precache]);
+        await scope.skipWaiting();
+      })()
+    );
+  });
+  scope.addEventListener("activate", (event) => {
+    event.waitUntil(
+      (async () => {
+        const names = await caches.keys();
+        await Promise.all(
+          names.filter((name) => name !== cacheName).map((name) => caches.delete(name))
+        );
+        await scope.clients.claim();
+      })()
+    );
+  });
+  scope.addEventListener("fetch", (event) => {
+    const { request } = event;
+    if (request.method !== "GET") return;
+    const url = new URL(request.url);
+    if (isApiRequest(url)) return;
+    if (request.mode === "navigate") {
+      event.respondWith(
+        (async () => {
+          try {
+            return await fetch(request);
+          } catch {
+            const cache = await caches.open(cacheName);
+            const shell = await cache.match(appShellUrl);
+            if (shell !== void 0) return shell;
+            throw new Error(`kaafil offline shell: ${appShellUrl} is not in ${cacheName}`);
+          }
+        })()
+      );
+      return;
+    }
+    event.respondWith(
+      (async () => {
+        const cache = await caches.open(cacheName);
+        const hit = await cache.match(request);
+        return hit ?? await fetch(request);
+      })()
+    );
+  });
+}
+
+exports.installKaafilOfflineShell = installKaafilOfflineShell;
+exports.localStorageCredentialStore = localStorageCredentialStore;
+exports.withCachedCredential = withCachedCredential;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/offline/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/offline/credentialCache.ts","../../src/offline/serviceWorker.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["// An OPT-IN cache around the host's own credential resolver.\n//\n// The kit never persists a credential — where a token lives, how long it is\n// kept and what clears it are host security decisions, not a design system's\n// (`SessionShell.tsx`'s own header states this, and it is why\n// `credentialResolver` is a one-shot supplier whose result is handed straight\n// to `client.*.open()` and never stored).\n//\n// That rule is about WHERE the token lives, not about who sequences the\n// fallback. Every integrator hits the same two subtleties on the way to\n// milestone 10, and both are easy to get quietly wrong:\n//\n//   1. Falling back on ANY failure. A 401 or a 500 from a reachable server is\n//      a real failure and must still surface — silently serving a cached\n//      credential past a revocation is the failure mode that matters.\n//   2. Treating the cache as an authority on freshness. It is not, and this\n//      module deliberately cannot be: see `isUnreachable` below.\n//\n// So this helper owns the SEQUENCE and leaves the STORAGE to the host, which\n// keeps the security decision exactly where it was.\n\n/** The shape `KaafilUIKitProvider`'s `credentialResolver` resolves to —\n * structurally identical to `SessionShell.tsx`'s own union, restated here\n * rather than imported because nothing outside `src/core` may reach into the\n * SDK-facing shells (hard rule #1) and this module must stay SDK-free. */\nexport type StoredCredential =\n  | { readonly accessToken: string; readonly refreshToken: string; readonly agencyRef: string }\n  | { readonly shareToken: string };\n\nexport type CredentialResolver = () => Promise<StoredCredential>;\n\n/**\n * The host's own storage. Sync or async — a `localStorage` implementation and\n * an IndexedDB one both satisfy this.\n *\n * Nothing here is written to `window` (hard rule #22); a storage API is the\n * host's to choose, a global token stash is not.\n */\nexport interface CredentialStore {\n  read(): Promise<StoredCredential | null> | StoredCredential | null;\n  write(credential: StoredCredential): Promise<void> | void;\n  clear(): Promise<void> | void;\n}\n\nexport interface CachedCredentialOptions {\n  readonly store: CredentialStore;\n  /**\n   * Whether a thrown value means **the request never completed** — the only\n   * case in which the cached credential may be used.\n   *\n   * The default recognises exactly one thing: the `TypeError` that `fetch`\n   * throws when it cannot reach the network at all. That is deliberately\n   * narrow. A host using axios, ky or their own wrapper throws something else\n   * for the same condition and MUST supply this — a predicate that returns\n   * `true` too eagerly turns a 401 into a silent session extension, which is\n   * the exact bug this helper exists to prevent.\n   */\n  readonly isUnreachable?: (error: unknown) => boolean;\n}\n\n/** `fetch` rejects with a `TypeError` when the request never reached a server.\n * A response with a status — 401, 423, 500 — resolves, and is therefore not\n * this case. */\nfunction isFetchNetworkError(error: unknown): boolean {\n  return error instanceof TypeError;\n}\n\n/**\n * Wrap a credential resolver so a reload with no network still opens the\n * surface, instead of stranding the outbox behind a session that cannot mint.\n *\n * ```ts\n * const resolver = withCachedCredential(\n *   () => fetch('/api/admin-session', { method: 'POST' }).then((r) => r.json()),\n *   { store: localStorageCredentialStore('sharma:desk') },\n * );\n * ```\n *\n * ── WHAT THIS DOES NOT DO, ON PURPOSE ───────────────────────────────────────\n *\n * It stores and restores. It NEVER judges freshness, and it has no opinion on\n * expiry. A cached access token still expires, and offline it cannot be\n * refreshed — a manager who has been offline longer than the token's life will\n * not get in, and that is a real limit to design around, not a bug here. The\n * kit surfaces the outcome through `onSessionExpired` on the provider, which\n * is where a host reacts.\n *\n * That is not only a design preference: \"now\" in this package is\n * `meta.serverTime`, never a local wall clock, and a device that has been\n * offline for hours has no trustworthy `serverTime` to compare against. A\n * helper that checked expiry here would have to read the device clock to do\n * it — the precise thing the architecture forbids, for the precise reason it\n * would be wrong.\n */\nexport function withCachedCredential(\n  resolve: CredentialResolver,\n  options: CachedCredentialOptions,\n): CredentialResolver {\n  const { store } = options;\n  const isUnreachable = options.isUnreachable ?? isFetchNetworkError;\n\n  return async function resolveWithCache(): Promise<StoredCredential> {\n    try {\n      const fresh = await resolve();\n      await store.write(fresh);\n      return fresh;\n    } catch (error: unknown) {\n      // A server that ANSWERED — 401, 403, 500 — is a real failure and must\n      // surface. Only a request that never completed may fall back.\n      if (!isUnreachable(error)) throw error;\n\n      const cached = await store.read();\n      if (cached === null) throw error;\n\n      return cached;\n    }\n  };\n}\n\n/**\n * A `CredentialStore` over `localStorage`, for hosts that have decided that is\n * the right place for their token. Deliberately NOT the default — the kit does\n * not choose where a credential lives.\n *\n * `scope` is an IDENTIFIER (a staff id, a persona name), never the\n * credential's own secret: it becomes a storage key, and a key is readable by\n * anything that can read the store.\n *\n * Every access is wrapped: a private window, cleared site data, or a browser\n * configured to block site storage makes these APIs throw on access rather\n * than return empty, and a credential cache that takes the app down when\n * storage is unavailable is worse than no cache at all.\n */\nexport function localStorageCredentialStore(scope: string): CredentialStore {\n  const key = `kaafil:credential:${scope}`;\n\n  return {\n    read(): StoredCredential | null {\n      try {\n        const raw = localStorage.getItem(key);\n        if (raw === null) return null;\n        return JSON.parse(raw) as StoredCredential;\n      } catch {\n        return null;\n      }\n    },\n    write(credential: StoredCredential): void {\n      try {\n        localStorage.setItem(key, JSON.stringify(credential));\n      } catch {\n        // Storage unavailable or full — the surface still opens online, and\n        // the offline reload is what degrades. Never fail the mint for this.\n      }\n    },\n    clear(): void {\n      try {\n        localStorage.removeItem(key);\n      } catch {\n        // Same reasoning as `write`.\n      }\n    },\n  };\n}\n","// The Kaafil-specific half of a host's service worker.\n//\n// ── WHY THIS IS NOT A DROP-IN SERVICE WORKER ────────────────────────────────\n//\n// Kaafil makes your DATA survive a reload — the write goes to a durable outbox\n// and the read comes back from the snapshot store, both in IndexedDB, both\n// outliving a reload. It does nothing about your APPLICATION: the HTML\n// document, your JS, your CSS. Those come off the network like any other page,\n// so with no service worker a reload while offline gets the browser's offline\n// error page, and the queued writes sit intact behind a document that will not\n// open. The data was never lost; you just cannot reach it.\n//\n// Closing that gap is a service worker, and the CACHING half of it belongs to\n// the host: only your bundler knows your build's hashed filenames, your deploy\n// cadence and your revalidation strategy. Shipping an opinionated one here\n// would fight `vite-plugin-pwa`, `next-pwa` or whatever Workbox config you\n// already have.\n//\n// What this module ships instead is the part the kit genuinely knows: the\n// rules that are true of ANY Kaafil integration regardless of build tool. You\n// supply the precache manifest; this supplies the fetch policy.\n//\n// ── ON CACHING THE UIKIT'S OWN CSS AND JS ───────────────────────────────────\n//\n// There is nothing separate to do. This package is bundled INTO your build, so\n// its CSS and JS are already part of the output your precache manifest covers.\n// There is no Kaafil-specific asset step to add, and no Kaafil CDN URL to\n// allow — if your app shell is cached, so is the UIKit.\n\n/** The subset of the service-worker globals this module touches, declared\n * locally so the package does not have to add `lib: [\"WebWorker\"]` to its\n * tsconfig for one file. */\ninterface ServiceWorkerFetchEvent extends Event {\n  readonly request: Request;\n  respondWith(response: Promise<Response> | Response): void;\n}\n\ninterface ServiceWorkerLifecycleEvent extends Event {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\ninterface ServiceWorkerScope {\n  addEventListener(type: 'install', listener: (event: ServiceWorkerLifecycleEvent) => void): void;\n  addEventListener(type: 'activate', listener: (event: ServiceWorkerLifecycleEvent) => void): void;\n  addEventListener(type: 'fetch', listener: (event: ServiceWorkerFetchEvent) => void): void;\n  skipWaiting(): Promise<void>;\n  readonly clients: { claim(): Promise<void> };\n}\n\nexport interface KaafilOfflineShellOptions {\n  /**\n   * The cache this worker owns. Change it to invalidate — `activate` deletes\n   * every cache whose name differs, so your version string stays the only\n   * revalidation knob and this module never invents a second one.\n   */\n  readonly cacheName: string;\n  /**\n   * The document served for a navigation that cannot reach the network. Must\n   * be one of `precache`.\n   */\n  readonly appShellUrl: string;\n  /**\n   * Your build output, from your own bundler. `vite-plugin-pwa` and Workbox\n   * both inject a manifest; map it to URLs and pass it here.\n   */\n  readonly precache: readonly string[];\n  /**\n   * Whether a URL is a Kaafil API call, which must NEVER be served from cache.\n   * Defaults to any `kaafil.in` host. Override if you proxy the API through\n   * your own origin — and if you do, this is the one option you cannot afford\n   * to get wrong; see the note on `handleFetch`.\n   */\n  readonly isApiRequest?: (url: URL) => boolean;\n}\n\nfunction isKaafilApiHost(url: URL): boolean {\n  return url.hostname === 'kaafil.in' || url.hostname.endsWith('.kaafil.in');\n}\n\n/**\n * Register the Kaafil offline-shell rules on a service worker you own.\n *\n * ```js title=\"src/sw.ts\"\n * import { installKaafilOfflineShell } from 'kaafil-react-uikit/offline';\n *\n * installKaafilOfflineShell({\n *   cacheName: 'sharma-shell-v4',\n *   appShellUrl: '/index.html',\n *   precache: self.__WB_MANIFEST.map((e) => e.url),\n * });\n * ```\n *\n * Call it from your worker's top level. It adds `install`, `activate` and\n * `fetch` listeners and returns nothing — you are free to add your own\n * listeners alongside, including a `fetch` handler for routes this one\n * declines (it calls `respondWith` only for requests it actually owns).\n */\nexport function installKaafilOfflineShell(options: KaafilOfflineShellOptions): void {\n  const scope = self as unknown as ServiceWorkerScope;\n  const { cacheName, appShellUrl, precache } = options;\n  const isApiRequest = options.isApiRequest ?? isKaafilApiHost;\n\n  scope.addEventListener('install', (event) => {\n    event.waitUntil(\n      (async () => {\n        const cache = await caches.open(cacheName);\n        await cache.addAll([...precache]);\n        await scope.skipWaiting();\n      })(),\n    );\n  });\n\n  scope.addEventListener('activate', (event) => {\n    event.waitUntil(\n      (async () => {\n        const names = await caches.keys();\n        await Promise.all(\n          names.filter((name) => name !== cacheName).map((name) => caches.delete(name)),\n        );\n        await scope.clients.claim();\n      })(),\n    );\n  });\n\n  scope.addEventListener('fetch', (event) => {\n    const { request } = event;\n\n    // NEVER touch a write. The outbox owns retries and their idempotency (no\n    // hook mints its own key, and none accepts one); a service worker that\n    // replays a POST is a second retry engine racing the first, and the\n    // visible symptom is a duplicate expense nobody can explain.\n    if (request.method !== 'GET') return;\n\n    const url = new URL(request.url);\n\n    // NEVER cache a Kaafil API response. Two different failures, both real: a\n    // cached trip read shows a manager stale data they will act on, and a\n    // cached SHARE response keeps serving a traveller's itinerary after the\n    // token was revoked — a disclosure, not a staleness bug. Reads that should\n    // survive offline already do, from the SDK's own snapshot store.\n    if (isApiRequest(url)) return;\n\n    // A navigation that cannot reach the network falls back to the cached app\n    // shell. This single rule is what turns \"reload while offline\" from the\n    // browser's error page into a working surface with the outbox intact.\n    if (request.mode === 'navigate') {\n      event.respondWith(\n        (async () => {\n          try {\n            return await fetch(request);\n          } catch {\n            const cache = await caches.open(cacheName);\n            const shell = await cache.match(appShellUrl);\n            if (shell !== undefined) return shell;\n            throw new Error(`kaafil offline shell: ${appShellUrl} is not in ${cacheName}`);\n          }\n        })(),\n      );\n      return;\n    }\n\n    // Everything else that was precached is served cache-first. Anything not\n    // precached is left alone for the host's own handlers, or the network.\n    event.respondWith(\n      (async () => {\n        const cache = await caches.open(cacheName);\n        const hit = await cache.match(request);\n        return hit ?? (await fetch(request));\n      })(),\n    );\n  });\n}\n"]}

package/dist/offline/index.d.cts

@@ -0,0 +1,129 @@
+/** The shape `KaafilUIKitProvider`'s `credentialResolver` resolves to —
+ * structurally identical to `SessionShell.tsx`'s own union, restated here
+ * rather than imported because nothing outside `src/core` may reach into the
+ * SDK-facing shells (hard rule #1) and this module must stay SDK-free. */
+type StoredCredential = {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly agencyRef: string;
+} | {
+    readonly shareToken: string;
+};
+type CredentialResolver = () => Promise<StoredCredential>;
+/**
+ * The host's own storage. Sync or async — a `localStorage` implementation and
+ * an IndexedDB one both satisfy this.
+ *
+ * Nothing here is written to `window` (hard rule #22); a storage API is the
+ * host's to choose, a global token stash is not.
+ */
+interface CredentialStore {
+    read(): Promise<StoredCredential | null> | StoredCredential | null;
+    write(credential: StoredCredential): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+interface CachedCredentialOptions {
+    readonly store: CredentialStore;
+    /**
+     * Whether a thrown value means **the request never completed** — the only
+     * case in which the cached credential may be used.
+     *
+     * The default recognises exactly one thing: the `TypeError` that `fetch`
+     * throws when it cannot reach the network at all. That is deliberately
+     * narrow. A host using axios, ky or their own wrapper throws something else
+     * for the same condition and MUST supply this — a predicate that returns
+     * `true` too eagerly turns a 401 into a silent session extension, which is
+     * the exact bug this helper exists to prevent.
+     */
+    readonly isUnreachable?: (error: unknown) => boolean;
+}
+/**
+ * Wrap a credential resolver so a reload with no network still opens the
+ * surface, instead of stranding the outbox behind a session that cannot mint.
+ *
+ * ```ts
+ * const resolver = withCachedCredential(
+ *   () => fetch('/api/admin-session', { method: 'POST' }).then((r) => r.json()),
+ *   { store: localStorageCredentialStore('sharma:desk') },
+ * );
+ * ```
+ *
+ * ── WHAT THIS DOES NOT DO, ON PURPOSE ───────────────────────────────────────
+ *
+ * It stores and restores. It NEVER judges freshness, and it has no opinion on
+ * expiry. A cached access token still expires, and offline it cannot be
+ * refreshed — a manager who has been offline longer than the token's life will
+ * not get in, and that is a real limit to design around, not a bug here. The
+ * kit surfaces the outcome through `onSessionExpired` on the provider, which
+ * is where a host reacts.
+ *
+ * That is not only a design preference: "now" in this package is
+ * `meta.serverTime`, never a local wall clock, and a device that has been
+ * offline for hours has no trustworthy `serverTime` to compare against. A
+ * helper that checked expiry here would have to read the device clock to do
+ * it — the precise thing the architecture forbids, for the precise reason it
+ * would be wrong.
+ */
+declare function withCachedCredential(resolve: CredentialResolver, options: CachedCredentialOptions): CredentialResolver;
+/**
+ * A `CredentialStore` over `localStorage`, for hosts that have decided that is
+ * the right place for their token. Deliberately NOT the default — the kit does
+ * not choose where a credential lives.
+ *
+ * `scope` is an IDENTIFIER (a staff id, a persona name), never the
+ * credential's own secret: it becomes a storage key, and a key is readable by
+ * anything that can read the store.
+ *
+ * Every access is wrapped: a private window, cleared site data, or a browser
+ * configured to block site storage makes these APIs throw on access rather
+ * than return empty, and a credential cache that takes the app down when
+ * storage is unavailable is worse than no cache at all.
+ */
+declare function localStorageCredentialStore(scope: string): CredentialStore;
+
+interface KaafilOfflineShellOptions {
+    /**
+     * The cache this worker owns. Change it to invalidate — `activate` deletes
+     * every cache whose name differs, so your version string stays the only
+     * revalidation knob and this module never invents a second one.
+     */
+    readonly cacheName: string;
+    /**
+     * The document served for a navigation that cannot reach the network. Must
+     * be one of `precache`.
+     */
+    readonly appShellUrl: string;
+    /**
+     * Your build output, from your own bundler. `vite-plugin-pwa` and Workbox
+     * both inject a manifest; map it to URLs and pass it here.
+     */
+    readonly precache: readonly string[];
+    /**
+     * Whether a URL is a Kaafil API call, which must NEVER be served from cache.
+     * Defaults to any `kaafil.in` host. Override if you proxy the API through
+     * your own origin — and if you do, this is the one option you cannot afford
+     * to get wrong; see the note on `handleFetch`.
+     */
+    readonly isApiRequest?: (url: URL) => boolean;
+}
+/**
+ * Register the Kaafil offline-shell rules on a service worker you own.
+ *
+ * ```js title="src/sw.ts"
+ * import { installKaafilOfflineShell } from 'kaafil-react-uikit/offline';
+ *
+ * installKaafilOfflineShell({
+ *   cacheName: 'sharma-shell-v4',
+ *   appShellUrl: '/index.html',
+ *   precache: self.__WB_MANIFEST.map((e) => e.url),
+ * });
+ * ```
+ *
+ * Call it from your worker's top level. It adds `install`, `activate` and
+ * `fetch` listeners and returns nothing — you are free to add your own
+ * listeners alongside, including a `fetch` handler for routes this one
+ * declines (it calls `respondWith` only for requests it actually owns).
+ */
+declare function installKaafilOfflineShell(options: KaafilOfflineShellOptions): void;
+
+export { type CachedCredentialOptions, type CredentialResolver, type CredentialStore, type KaafilOfflineShellOptions, type StoredCredential, installKaafilOfflineShell, localStorageCredentialStore, withCachedCredential };

package/dist/offline/index.d.ts

@@ -0,0 +1,129 @@
+/** The shape `KaafilUIKitProvider`'s `credentialResolver` resolves to —
+ * structurally identical to `SessionShell.tsx`'s own union, restated here
+ * rather than imported because nothing outside `src/core` may reach into the
+ * SDK-facing shells (hard rule #1) and this module must stay SDK-free. */
+type StoredCredential = {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly agencyRef: string;
+} | {
+    readonly shareToken: string;
+};
+type CredentialResolver = () => Promise<StoredCredential>;
+/**
+ * The host's own storage. Sync or async — a `localStorage` implementation and
+ * an IndexedDB one both satisfy this.
+ *
+ * Nothing here is written to `window` (hard rule #22); a storage API is the
+ * host's to choose, a global token stash is not.
+ */
+interface CredentialStore {
+    read(): Promise<StoredCredential | null> | StoredCredential | null;
+    write(credential: StoredCredential): Promise<void> | void;
+    clear(): Promise<void> | void;
+}
+interface CachedCredentialOptions {
+    readonly store: CredentialStore;
+    /**
+     * Whether a thrown value means **the request never completed** — the only
+     * case in which the cached credential may be used.
+     *
+     * The default recognises exactly one thing: the `TypeError` that `fetch`
+     * throws when it cannot reach the network at all. That is deliberately
+     * narrow. A host using axios, ky or their own wrapper throws something else
+     * for the same condition and MUST supply this — a predicate that returns
+     * `true` too eagerly turns a 401 into a silent session extension, which is
+     * the exact bug this helper exists to prevent.
+     */
+    readonly isUnreachable?: (error: unknown) => boolean;
+}
+/**
+ * Wrap a credential resolver so a reload with no network still opens the
+ * surface, instead of stranding the outbox behind a session that cannot mint.
+ *
+ * ```ts
+ * const resolver = withCachedCredential(
+ *   () => fetch('/api/admin-session', { method: 'POST' }).then((r) => r.json()),
+ *   { store: localStorageCredentialStore('sharma:desk') },
+ * );
+ * ```
+ *
+ * ── WHAT THIS DOES NOT DO, ON PURPOSE ───────────────────────────────────────
+ *
+ * It stores and restores. It NEVER judges freshness, and it has no opinion on
+ * expiry. A cached access token still expires, and offline it cannot be
+ * refreshed — a manager who has been offline longer than the token's life will
+ * not get in, and that is a real limit to design around, not a bug here. The
+ * kit surfaces the outcome through `onSessionExpired` on the provider, which
+ * is where a host reacts.
+ *
+ * That is not only a design preference: "now" in this package is
+ * `meta.serverTime`, never a local wall clock, and a device that has been
+ * offline for hours has no trustworthy `serverTime` to compare against. A
+ * helper that checked expiry here would have to read the device clock to do
+ * it — the precise thing the architecture forbids, for the precise reason it
+ * would be wrong.
+ */
+declare function withCachedCredential(resolve: CredentialResolver, options: CachedCredentialOptions): CredentialResolver;
+/**
+ * A `CredentialStore` over `localStorage`, for hosts that have decided that is
+ * the right place for their token. Deliberately NOT the default — the kit does
+ * not choose where a credential lives.
+ *
+ * `scope` is an IDENTIFIER (a staff id, a persona name), never the
+ * credential's own secret: it becomes a storage key, and a key is readable by
+ * anything that can read the store.
+ *
+ * Every access is wrapped: a private window, cleared site data, or a browser
+ * configured to block site storage makes these APIs throw on access rather
+ * than return empty, and a credential cache that takes the app down when
+ * storage is unavailable is worse than no cache at all.
+ */
+declare function localStorageCredentialStore(scope: string): CredentialStore;
+
+interface KaafilOfflineShellOptions {
+    /**
+     * The cache this worker owns. Change it to invalidate — `activate` deletes
+     * every cache whose name differs, so your version string stays the only
+     * revalidation knob and this module never invents a second one.
+     */
+    readonly cacheName: string;
+    /**
+     * The document served for a navigation that cannot reach the network. Must
+     * be one of `precache`.
+     */
+    readonly appShellUrl: string;
+    /**
+     * Your build output, from your own bundler. `vite-plugin-pwa` and Workbox
+     * both inject a manifest; map it to URLs and pass it here.
+     */
+    readonly precache: readonly string[];
+    /**
+     * Whether a URL is a Kaafil API call, which must NEVER be served from cache.
+     * Defaults to any `kaafil.in` host. Override if you proxy the API through
+     * your own origin — and if you do, this is the one option you cannot afford
+     * to get wrong; see the note on `handleFetch`.
+     */
+    readonly isApiRequest?: (url: URL) => boolean;
+}
+/**
+ * Register the Kaafil offline-shell rules on a service worker you own.
+ *
+ * ```js title="src/sw.ts"
+ * import { installKaafilOfflineShell } from 'kaafil-react-uikit/offline';
+ *
+ * installKaafilOfflineShell({
+ *   cacheName: 'sharma-shell-v4',
+ *   appShellUrl: '/index.html',
+ *   precache: self.__WB_MANIFEST.map((e) => e.url),
+ * });
+ * ```
+ *
+ * Call it from your worker's top level. It adds `install`, `activate` and
+ * `fetch` listeners and returns nothing — you are free to add your own
+ * listeners alongside, including a `fetch` handler for routes this one
+ * declines (it calls `respondWith` only for requests it actually owns).
+ */
+declare function installKaafilOfflineShell(options: KaafilOfflineShellOptions): void;
+
+export { type CachedCredentialOptions, type CredentialResolver, type CredentialStore, type KaafilOfflineShellOptions, type StoredCredential, installKaafilOfflineShell, localStorageCredentialStore, withCachedCredential };

package/dist/offline/index.js

@@ -0,0 +1,108 @@
+// src/offline/credentialCache.ts
+function isFetchNetworkError(error) {
+  return error instanceof TypeError;
+}
+function withCachedCredential(resolve, options) {
+  const { store } = options;
+  const isUnreachable = options.isUnreachable ?? isFetchNetworkError;
+  return async function resolveWithCache() {
+    try {
+      const fresh = await resolve();
+      await store.write(fresh);
+      return fresh;
+    } catch (error) {
+      if (!isUnreachable(error)) throw error;
+      const cached = await store.read();
+      if (cached === null) throw error;
+      return cached;
+    }
+  };
+}
+function localStorageCredentialStore(scope) {
+  const key = `kaafil:credential:${scope}`;
+  return {
+    read() {
+      try {
+        const raw = localStorage.getItem(key);
+        if (raw === null) return null;
+        return JSON.parse(raw);
+      } catch {
+        return null;
+      }
+    },
+    write(credential) {
+      try {
+        localStorage.setItem(key, JSON.stringify(credential));
+      } catch {
+      }
+    },
+    clear() {
+      try {
+        localStorage.removeItem(key);
+      } catch {
+      }
+    }
+  };
+}
+
+// src/offline/serviceWorker.ts
+function isKaafilApiHost(url) {
+  return url.hostname === "kaafil.in" || url.hostname.endsWith(".kaafil.in");
+}
+function installKaafilOfflineShell(options) {
+  const scope = self;
+  const { cacheName, appShellUrl, precache } = options;
+  const isApiRequest = options.isApiRequest ?? isKaafilApiHost;
+  scope.addEventListener("install", (event) => {
+    event.waitUntil(
+      (async () => {
+        const cache = await caches.open(cacheName);
+        await cache.addAll([...precache]);
+        await scope.skipWaiting();
+      })()
+    );
+  });
+  scope.addEventListener("activate", (event) => {
+    event.waitUntil(
+      (async () => {
+        const names = await caches.keys();
+        await Promise.all(
+          names.filter((name) => name !== cacheName).map((name) => caches.delete(name))
+        );
+        await scope.clients.claim();
+      })()
+    );
+  });
+  scope.addEventListener("fetch", (event) => {
+    const { request } = event;
+    if (request.method !== "GET") return;
+    const url = new URL(request.url);
+    if (isApiRequest(url)) return;
+    if (request.mode === "navigate") {
+      event.respondWith(
+        (async () => {
+          try {
+            return await fetch(request);
+          } catch {
+            const cache = await caches.open(cacheName);
+            const shell = await cache.match(appShellUrl);
+            if (shell !== void 0) return shell;
+            throw new Error(`kaafil offline shell: ${appShellUrl} is not in ${cacheName}`);
+          }
+        })()
+      );
+      return;
+    }
+    event.respondWith(
+      (async () => {
+        const cache = await caches.open(cacheName);
+        const hit = await cache.match(request);
+        return hit ?? await fetch(request);
+      })()
+    );
+  });
+}
+
+export { installKaafilOfflineShell, localStorageCredentialStore, withCachedCredential };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/offline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/offline/credentialCache.ts","../../src/offline/serviceWorker.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["// An OPT-IN cache around the host's own credential resolver.\n//\n// The kit never persists a credential — where a token lives, how long it is\n// kept and what clears it are host security decisions, not a design system's\n// (`SessionShell.tsx`'s own header states this, and it is why\n// `credentialResolver` is a one-shot supplier whose result is handed straight\n// to `client.*.open()` and never stored).\n//\n// That rule is about WHERE the token lives, not about who sequences the\n// fallback. Every integrator hits the same two subtleties on the way to\n// milestone 10, and both are easy to get quietly wrong:\n//\n//   1. Falling back on ANY failure. A 401 or a 500 from a reachable server is\n//      a real failure and must still surface — silently serving a cached\n//      credential past a revocation is the failure mode that matters.\n//   2. Treating the cache as an authority on freshness. It is not, and this\n//      module deliberately cannot be: see `isUnreachable` below.\n//\n// So this helper owns the SEQUENCE and leaves the STORAGE to the host, which\n// keeps the security decision exactly where it was.\n\n/** The shape `KaafilUIKitProvider`'s `credentialResolver` resolves to —\n * structurally identical to `SessionShell.tsx`'s own union, restated here\n * rather than imported because nothing outside `src/core` may reach into the\n * SDK-facing shells (hard rule #1) and this module must stay SDK-free. */\nexport type StoredCredential =\n  | { readonly accessToken: string; readonly refreshToken: string; readonly agencyRef: string }\n  | { readonly shareToken: string };\n\nexport type CredentialResolver = () => Promise<StoredCredential>;\n\n/**\n * The host's own storage. Sync or async — a `localStorage` implementation and\n * an IndexedDB one both satisfy this.\n *\n * Nothing here is written to `window` (hard rule #22); a storage API is the\n * host's to choose, a global token stash is not.\n */\nexport interface CredentialStore {\n  read(): Promise<StoredCredential | null> | StoredCredential | null;\n  write(credential: StoredCredential): Promise<void> | void;\n  clear(): Promise<void> | void;\n}\n\nexport interface CachedCredentialOptions {\n  readonly store: CredentialStore;\n  /**\n   * Whether a thrown value means **the request never completed** — the only\n   * case in which the cached credential may be used.\n   *\n   * The default recognises exactly one thing: the `TypeError` that `fetch`\n   * throws when it cannot reach the network at all. That is deliberately\n   * narrow. A host using axios, ky or their own wrapper throws something else\n   * for the same condition and MUST supply this — a predicate that returns\n   * `true` too eagerly turns a 401 into a silent session extension, which is\n   * the exact bug this helper exists to prevent.\n   */\n  readonly isUnreachable?: (error: unknown) => boolean;\n}\n\n/** `fetch` rejects with a `TypeError` when the request never reached a server.\n * A response with a status — 401, 423, 500 — resolves, and is therefore not\n * this case. */\nfunction isFetchNetworkError(error: unknown): boolean {\n  return error instanceof TypeError;\n}\n\n/**\n * Wrap a credential resolver so a reload with no network still opens the\n * surface, instead of stranding the outbox behind a session that cannot mint.\n *\n * ```ts\n * const resolver = withCachedCredential(\n *   () => fetch('/api/admin-session', { method: 'POST' }).then((r) => r.json()),\n *   { store: localStorageCredentialStore('sharma:desk') },\n * );\n * ```\n *\n * ── WHAT THIS DOES NOT DO, ON PURPOSE ───────────────────────────────────────\n *\n * It stores and restores. It NEVER judges freshness, and it has no opinion on\n * expiry. A cached access token still expires, and offline it cannot be\n * refreshed — a manager who has been offline longer than the token's life will\n * not get in, and that is a real limit to design around, not a bug here. The\n * kit surfaces the outcome through `onSessionExpired` on the provider, which\n * is where a host reacts.\n *\n * That is not only a design preference: \"now\" in this package is\n * `meta.serverTime`, never a local wall clock, and a device that has been\n * offline for hours has no trustworthy `serverTime` to compare against. A\n * helper that checked expiry here would have to read the device clock to do\n * it — the precise thing the architecture forbids, for the precise reason it\n * would be wrong.\n */\nexport function withCachedCredential(\n  resolve: CredentialResolver,\n  options: CachedCredentialOptions,\n): CredentialResolver {\n  const { store } = options;\n  const isUnreachable = options.isUnreachable ?? isFetchNetworkError;\n\n  return async function resolveWithCache(): Promise<StoredCredential> {\n    try {\n      const fresh = await resolve();\n      await store.write(fresh);\n      return fresh;\n    } catch (error: unknown) {\n      // A server that ANSWERED — 401, 403, 500 — is a real failure and must\n      // surface. Only a request that never completed may fall back.\n      if (!isUnreachable(error)) throw error;\n\n      const cached = await store.read();\n      if (cached === null) throw error;\n\n      return cached;\n    }\n  };\n}\n\n/**\n * A `CredentialStore` over `localStorage`, for hosts that have decided that is\n * the right place for their token. Deliberately NOT the default — the kit does\n * not choose where a credential lives.\n *\n * `scope` is an IDENTIFIER (a staff id, a persona name), never the\n * credential's own secret: it becomes a storage key, and a key is readable by\n * anything that can read the store.\n *\n * Every access is wrapped: a private window, cleared site data, or a browser\n * configured to block site storage makes these APIs throw on access rather\n * than return empty, and a credential cache that takes the app down when\n * storage is unavailable is worse than no cache at all.\n */\nexport function localStorageCredentialStore(scope: string): CredentialStore {\n  const key = `kaafil:credential:${scope}`;\n\n  return {\n    read(): StoredCredential | null {\n      try {\n        const raw = localStorage.getItem(key);\n        if (raw === null) return null;\n        return JSON.parse(raw) as StoredCredential;\n      } catch {\n        return null;\n      }\n    },\n    write(credential: StoredCredential): void {\n      try {\n        localStorage.setItem(key, JSON.stringify(credential));\n      } catch {\n        // Storage unavailable or full — the surface still opens online, and\n        // the offline reload is what degrades. Never fail the mint for this.\n      }\n    },\n    clear(): void {\n      try {\n        localStorage.removeItem(key);\n      } catch {\n        // Same reasoning as `write`.\n      }\n    },\n  };\n}\n","// The Kaafil-specific half of a host's service worker.\n//\n// ── WHY THIS IS NOT A DROP-IN SERVICE WORKER ────────────────────────────────\n//\n// Kaafil makes your DATA survive a reload — the write goes to a durable outbox\n// and the read comes back from the snapshot store, both in IndexedDB, both\n// outliving a reload. It does nothing about your APPLICATION: the HTML\n// document, your JS, your CSS. Those come off the network like any other page,\n// so with no service worker a reload while offline gets the browser's offline\n// error page, and the queued writes sit intact behind a document that will not\n// open. The data was never lost; you just cannot reach it.\n//\n// Closing that gap is a service worker, and the CACHING half of it belongs to\n// the host: only your bundler knows your build's hashed filenames, your deploy\n// cadence and your revalidation strategy. Shipping an opinionated one here\n// would fight `vite-plugin-pwa`, `next-pwa` or whatever Workbox config you\n// already have.\n//\n// What this module ships instead is the part the kit genuinely knows: the\n// rules that are true of ANY Kaafil integration regardless of build tool. You\n// supply the precache manifest; this supplies the fetch policy.\n//\n// ── ON CACHING THE UIKIT'S OWN CSS AND JS ───────────────────────────────────\n//\n// There is nothing separate to do. This package is bundled INTO your build, so\n// its CSS and JS are already part of the output your precache manifest covers.\n// There is no Kaafil-specific asset step to add, and no Kaafil CDN URL to\n// allow — if your app shell is cached, so is the UIKit.\n\n/** The subset of the service-worker globals this module touches, declared\n * locally so the package does not have to add `lib: [\"WebWorker\"]` to its\n * tsconfig for one file. */\ninterface ServiceWorkerFetchEvent extends Event {\n  readonly request: Request;\n  respondWith(response: Promise<Response> | Response): void;\n}\n\ninterface ServiceWorkerLifecycleEvent extends Event {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\ninterface ServiceWorkerScope {\n  addEventListener(type: 'install', listener: (event: ServiceWorkerLifecycleEvent) => void): void;\n  addEventListener(type: 'activate', listener: (event: ServiceWorkerLifecycleEvent) => void): void;\n  addEventListener(type: 'fetch', listener: (event: ServiceWorkerFetchEvent) => void): void;\n  skipWaiting(): Promise<void>;\n  readonly clients: { claim(): Promise<void> };\n}\n\nexport interface KaafilOfflineShellOptions {\n  /**\n   * The cache this worker owns. Change it to invalidate — `activate` deletes\n   * every cache whose name differs, so your version string stays the only\n   * revalidation knob and this module never invents a second one.\n   */\n  readonly cacheName: string;\n  /**\n   * The document served for a navigation that cannot reach the network. Must\n   * be one of `precache`.\n   */\n  readonly appShellUrl: string;\n  /**\n   * Your build output, from your own bundler. `vite-plugin-pwa` and Workbox\n   * both inject a manifest; map it to URLs and pass it here.\n   */\n  readonly precache: readonly string[];\n  /**\n   * Whether a URL is a Kaafil API call, which must NEVER be served from cache.\n   * Defaults to any `kaafil.in` host. Override if you proxy the API through\n   * your own origin — and if you do, this is the one option you cannot afford\n   * to get wrong; see the note on `handleFetch`.\n   */\n  readonly isApiRequest?: (url: URL) => boolean;\n}\n\nfunction isKaafilApiHost(url: URL): boolean {\n  return url.hostname === 'kaafil.in' || url.hostname.endsWith('.kaafil.in');\n}\n\n/**\n * Register the Kaafil offline-shell rules on a service worker you own.\n *\n * ```js title=\"src/sw.ts\"\n * import { installKaafilOfflineShell } from 'kaafil-react-uikit/offline';\n *\n * installKaafilOfflineShell({\n *   cacheName: 'sharma-shell-v4',\n *   appShellUrl: '/index.html',\n *   precache: self.__WB_MANIFEST.map((e) => e.url),\n * });\n * ```\n *\n * Call it from your worker's top level. It adds `install`, `activate` and\n * `fetch` listeners and returns nothing — you are free to add your own\n * listeners alongside, including a `fetch` handler for routes this one\n * declines (it calls `respondWith` only for requests it actually owns).\n */\nexport function installKaafilOfflineShell(options: KaafilOfflineShellOptions): void {\n  const scope = self as unknown as ServiceWorkerScope;\n  const { cacheName, appShellUrl, precache } = options;\n  const isApiRequest = options.isApiRequest ?? isKaafilApiHost;\n\n  scope.addEventListener('install', (event) => {\n    event.waitUntil(\n      (async () => {\n        const cache = await caches.open(cacheName);\n        await cache.addAll([...precache]);\n        await scope.skipWaiting();\n      })(),\n    );\n  });\n\n  scope.addEventListener('activate', (event) => {\n    event.waitUntil(\n      (async () => {\n        const names = await caches.keys();\n        await Promise.all(\n          names.filter((name) => name !== cacheName).map((name) => caches.delete(name)),\n        );\n        await scope.clients.claim();\n      })(),\n    );\n  });\n\n  scope.addEventListener('fetch', (event) => {\n    const { request } = event;\n\n    // NEVER touch a write. The outbox owns retries and their idempotency (no\n    // hook mints its own key, and none accepts one); a service worker that\n    // replays a POST is a second retry engine racing the first, and the\n    // visible symptom is a duplicate expense nobody can explain.\n    if (request.method !== 'GET') return;\n\n    const url = new URL(request.url);\n\n    // NEVER cache a Kaafil API response. Two different failures, both real: a\n    // cached trip read shows a manager stale data they will act on, and a\n    // cached SHARE response keeps serving a traveller's itinerary after the\n    // token was revoked — a disclosure, not a staleness bug. Reads that should\n    // survive offline already do, from the SDK's own snapshot store.\n    if (isApiRequest(url)) return;\n\n    // A navigation that cannot reach the network falls back to the cached app\n    // shell. This single rule is what turns \"reload while offline\" from the\n    // browser's error page into a working surface with the outbox intact.\n    if (request.mode === 'navigate') {\n      event.respondWith(\n        (async () => {\n          try {\n            return await fetch(request);\n          } catch {\n            const cache = await caches.open(cacheName);\n            const shell = await cache.match(appShellUrl);\n            if (shell !== undefined) return shell;\n            throw new Error(`kaafil offline shell: ${appShellUrl} is not in ${cacheName}`);\n          }\n        })(),\n      );\n      return;\n    }\n\n    // Everything else that was precached is served cache-first. Anything not\n    // precached is left alone for the host's own handlers, or the network.\n    event.respondWith(\n      (async () => {\n        const cache = await caches.open(cacheName);\n        const hit = await cache.match(request);\n        return hit ?? (await fetch(request));\n      })(),\n    );\n  });\n}\n"]}