@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.0

package/src/pwa/__tests__/sw.spec.ts

@@ -12,7 +12,13 @@ const SW_SOURCE = readFileSync(SW_PATH, "utf8");
 
 const ORIGIN = "https://app.test";
 
-type SwConfig = { appId: string; offlineRevision: string; notificationIcon: string };
+type SwConfig = {
+  appId: string;
+  offlineRevision: string;
+  notificationIcon: string;
+  offlineShell?: { default: string; locales?: Record<string, string> };
+  offlineImageHosts?: string[];
+};
 type Listener = (event: any) => void;
 
 // A worker resolves relative Request URLs against its own location; Node's
@@ -43,6 +49,7 @@ function loadWorker(config: SwConfig = { appId: "test", offlineRevision: "abc123
     fetch: vi.fn(),
     Response: globalThis.Response,
     Request: WorkerRequest,
+    URL: globalThis.URL,
     location: { origin: ORIGIN },
     console,
   };
@@ -81,6 +88,23 @@ function makeCache(overrides: Record<string, any> = {}) {
   };
 }
 
+const SHELL_CONFIG: SwConfig = {
+  appId: "test",
+  offlineRevision: "abc12345",
+  notificationIcon: "/icon.png",
+  offlineShell: { default: "/offline-shell", locales: { it: "/it/offline-shell" } },
+  offlineImageHosts: ["api.app.test"],
+};
+
+/** The entry the worker writes last into a shell cache; a cache without it is incomplete. */
+const SHELL_COMPLETE_URL = "/__nja-offline-shell-complete__";
+
+const MANIFEST = { buildId: "build-2", assets: ["/_next/static/chunks/a.js", "/_next/static/css/b.css"] };
+
+function manifestResponse(manifest = MANIFEST) {
+  return new Response(JSON.stringify(manifest), { status: 200, headers: { "content-type": "application/json" } });
+}
+
 function navigation(init: Record<string, any> = {}) {
   return {
     request: { mode: "navigate", destination: "document", url: `${ORIGIN}/campaigns` },
@@ -306,4 +330,337 @@ describe("pwa/sw.js", () => {
     expect(sandbox.clients.matchAll).not.toHaveBeenCalled();
     expect(client.postMessage).not.toHaveBeenCalled();
   });
+
+  describe("offline shell (opt-in)", () => {
+    it("without offlineShell, install caches only /offline.html (unchanged)", async () => {
+      const { sandbox, dispatch } = loadWorker();
+      const cache = makeCache();
+      sandbox.caches.open.mockResolvedValue(cache);
+
+      const event = dispatch("install");
+      await event.waitUntilPromise;
+
+      expect(sandbox.fetch).not.toHaveBeenCalled();
+      expect(sandbox.caches.open).toHaveBeenCalledTimes(1);
+      expect(sandbox.caches.open).toHaveBeenCalledWith("test-offline-abc12345");
+      expect(cache.addAll).not.toHaveBeenCalled();
+    });
+
+    it("with offlineShell, install reads /offline-manifest.json and caches every asset plus each shell URL in <appId>-shell-<buildId>", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      const offlineCache = makeCache();
+      const shellCache = makeCache();
+      sandbox.caches.open.mockImplementation(async (name: string) =>
+        name === "test-shell-build-2" ? shellCache : offlineCache,
+      );
+      sandbox.fetch.mockResolvedValue(manifestResponse());
+
+      const event = dispatch("install");
+      await event.waitUntilPromise;
+
+      expect(sandbox.fetch).toHaveBeenCalledTimes(1);
+      const manifestRequest = sandbox.fetch.mock.calls[0][0];
+      expect(new URL(manifestRequest.url).pathname).toBe("/offline-manifest.json");
+      expect(manifestRequest.cache).toBe("no-store");
+      expect(offlineCache.add).toHaveBeenCalledTimes(1);
+      expect(sandbox.caches.open).toHaveBeenCalledWith("test-shell-build-2");
+      expect(shellCache.addAll).toHaveBeenCalledTimes(1);
+      const cached = shellCache.addAll.mock.calls[0][0].map((request: Request) => new URL(request.url).pathname);
+      expect(cached.sort()).toEqual(
+        ["/_next/static/chunks/a.js", "/_next/static/css/b.css", "/offline-shell", "/it/offline-shell"].sort(),
+      );
+      for (const request of shellCache.addAll.mock.calls[0][0]) expect(request.cache).toBe("reload");
+      // The completion marker is written last, after every file is in.
+      expect(shellCache.put).toHaveBeenCalledTimes(1);
+      expect(shellCache.put.mock.calls[0][0]).toBe(SHELL_COMPLETE_URL);
+      expect(shellCache.put.mock.invocationCallOrder[0]).toBeGreaterThan(shellCache.addAll.mock.invocationCallOrder[0]);
+    });
+
+    it("install fails, and the old worker stays, when any asset fails", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      const offlineCache = makeCache();
+      const shellCache = makeCache({ addAll: vi.fn().mockRejectedValue(new Error("Request failed")) });
+      sandbox.caches.open.mockImplementation(async (name: string) =>
+        name === "test-shell-build-2" ? shellCache : offlineCache,
+      );
+      sandbox.caches.delete.mockResolvedValue(true);
+      sandbox.fetch.mockResolvedValue(manifestResponse());
+
+      const event = dispatch("install");
+
+      await expect(event.waitUntilPromise).rejects.toThrow("Request failed");
+      // The half-filled shell cache is deleted, so no worker ever picks it.
+      expect(sandbox.caches.delete).toHaveBeenCalledWith("test-shell-build-2");
+      expect(shellCache.put).not.toHaveBeenCalled();
+    });
+
+    it("never answers from a shell cache that is not complete (no completion marker)", async () => {
+      const complete = new Response("build-2 shell");
+      const partial = new Response("build-3 shell");
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      const caches: Record<string, ReturnType<typeof makeCache>> = {
+        "test-offline-abc12345": makeCache(),
+        "test-shell-build-2": makeCache({
+          match: vi.fn(async (url: string) =>
+            url === SHELL_COMPLETE_URL ? new Response("") : url === "/offline-shell" ? complete : undefined,
+          ),
+        }),
+        "test-shell-build-3": makeCache({
+          match: vi.fn(async (url: string) => (url === "/offline-shell" ? partial : undefined)),
+        }),
+      };
+      sandbox.caches.keys.mockResolvedValue(Object.keys(caches));
+      sandbox.caches.open.mockImplementation(async (name: string) => caches[name]);
+      sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+
+      const event = dispatch("fetch", navigation());
+
+      expect(await event.respondWithPromise).toBe(complete);
+    });
+
+    it("install fails when the manifest cannot be read", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      sandbox.caches.open.mockResolvedValue(makeCache());
+      sandbox.fetch.mockResolvedValue(new Response("nope", { status: 404 }));
+
+      const event = dispatch("install");
+
+      await expect(event.waitUntilPromise).rejects.toThrow();
+    });
+
+    it("activate deletes shell caches of other build ids and keeps <appId>-images", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      sandbox.caches.open.mockResolvedValue(makeCache());
+      sandbox.fetch.mockResolvedValue(manifestResponse());
+      await dispatch("install").waitUntilPromise;
+
+      sandbox.caches.keys.mockResolvedValue([
+        "test-offline-abc12345",
+        "test-shell-build-1",
+        "test-shell-build-2",
+        "test-images",
+        "serwist-precache",
+      ]);
+      sandbox.caches.delete.mockResolvedValue(true);
+      sandbox.registration.navigationPreload.enable.mockResolvedValue(undefined);
+      sandbox.clients.claim.mockResolvedValue(undefined);
+
+      await dispatch("activate").waitUntilPromise;
+
+      const deleted = sandbox.caches.delete.mock.calls.map((call: any[]) => call[0]).sort();
+      expect(deleted).toEqual(["serwist-precache", "test-shell-build-1"]);
+      expect(sandbox.clients.claim).toHaveBeenCalledTimes(1);
+    });
+
+    it("activate without offlineShell still deletes the images and shell caches (unchanged)", async () => {
+      const { sandbox, dispatch } = loadWorker();
+      sandbox.caches.keys.mockResolvedValue(["test-offline-abc12345", "test-shell-build-1", "test-images"]);
+      sandbox.caches.delete.mockResolvedValue(true);
+
+      await dispatch("activate").waitUntilPromise;
+
+      const deleted = sandbox.caches.delete.mock.calls.map((call: any[]) => call[0]).sort();
+      expect(deleted).toEqual(["test-images", "test-shell-build-1"]);
+    });
+
+    function shellWorker(shellEntries: Record<string, Response | undefined>, offlinePage?: Response) {
+      const worker = loadWorker(SHELL_CONFIG);
+      const entries: Record<string, Response | undefined> = { [SHELL_COMPLETE_URL]: new Response(""), ...shellEntries };
+      const shellCache = makeCache({ match: vi.fn(async (url: string) => entries[url]) });
+      const offlineCache = makeCache({ match: vi.fn().mockResolvedValue(offlinePage) });
+      worker.sandbox.caches.keys.mockResolvedValue(["test-offline-abc12345", "test-shell-build-2"]);
+      worker.sandbox.caches.open.mockImplementation(async (name: string) =>
+        name === "test-shell-build-2" ? shellCache : offlineCache,
+      );
+      worker.sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+      return { ...worker, shellCache, offlineCache };
+    }
+
+    it("a failed navigation to /it/... answers the it shell, any other path the default shell, and offline.html when no shell is cached", async () => {
+      const itShell = new Response("it shell");
+      const defaultShell = new Response("default shell");
+      const offline = new Response("offline page");
+
+      const withShell = shellWorker({ "/offline-shell": defaultShell, "/it/offline-shell": itShell });
+      const itNav = withShell.dispatch(
+        "fetch",
+        navigation({ request: { mode: "navigate", destination: "document", url: `${ORIGIN}/it/campaigns/c1/run` } }),
+      );
+      expect(await itNav.respondWithPromise).toBe(itShell);
+      const defaultNav = withShell.dispatch(
+        "fetch",
+        navigation({ request: { mode: "navigate", destination: "document", url: `${ORIGIN}/npcs/n1` } }),
+      );
+      expect(await defaultNav.respondWithPromise).toBe(defaultShell);
+
+      const noShell = shellWorker({}, offline);
+      const fallback = noShell.dispatch("fetch", navigation());
+      expect(await fallback.respondWithPromise).toBe(offline);
+      expect(noShell.offlineCache.match).toHaveBeenCalledWith("/offline.html");
+    });
+
+    it("after an online navigation, a new build in the manifest refreshes the shell in the background and drops the old one; the same build does nothing", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      // The worker runs on build-1; the server now serves build-2.
+      const caches = new Map<string, ReturnType<typeof makeCache>>();
+      const complete = makeCache({
+        match: vi.fn(async (url: string) => (url === SHELL_COMPLETE_URL ? new Response("") : undefined)),
+      });
+      caches.set("test-shell-build-1", complete);
+      sandbox.caches.keys.mockImplementation(async () => [...caches.keys()]);
+      sandbox.caches.open.mockImplementation(async (name: string) => {
+        if (!caches.has(name)) caches.set(name, makeCache());
+        return caches.get(name);
+      });
+      sandbox.caches.delete.mockImplementation(async (name: string) => caches.delete(name));
+      const page = new Response("page");
+      sandbox.fetch.mockImplementation(async (input: any) => {
+        const url = typeof input === "string" ? input : input.url;
+        if (url.endsWith("/offline-manifest.json")) return manifestResponse();
+        return page;
+      });
+
+      const event = dispatch("fetch", navigation());
+      expect(await event.respondWithPromise).toBe(page);
+      await event.waitUntilPromise;
+
+      const fresh = caches.get("test-shell-build-2");
+      expect(fresh?.addAll).toHaveBeenCalledTimes(1);
+      expect(fresh?.put).toHaveBeenCalledWith(SHELL_COMPLETE_URL, expect.anything());
+      expect(caches.has("test-shell-build-1")).toBe(false);
+
+      // Same build: no second precache.
+      fresh?.match.mockImplementation(async (url: string) =>
+        url === SHELL_COMPLETE_URL ? new Response("") : undefined,
+      );
+      const again = dispatch("fetch", navigation());
+      await again.respondWithPromise;
+      await again.waitUntilPromise;
+      expect(fresh?.addAll).toHaveBeenCalledTimes(1);
+    });
+
+    it("a GET under /_next/static/ is served cache-first from the shell cache", async () => {
+      const cachedChunk = new Response("cached chunk");
+      const { sandbox, dispatch } = shellWorker({ [`${ORIGIN}/_next/static/chunks/a.js`]: cachedChunk });
+
+      const hit = dispatch("fetch", {
+        request: { method: "GET", mode: "no-cors", destination: "script", url: `${ORIGIN}/_next/static/chunks/a.js` },
+      });
+      expect(hit.respondWith).toHaveBeenCalledTimes(1);
+      expect(await hit.respondWithPromise).toBe(cachedChunk);
+      expect(sandbox.fetch).not.toHaveBeenCalled();
+
+      const network = new Response("network chunk");
+      sandbox.fetch.mockResolvedValue(network);
+      const missRequest = {
+        method: "GET",
+        mode: "no-cors",
+        destination: "script",
+        url: `${ORIGIN}/_next/static/chunks/missing.js`,
+      };
+      const miss = dispatch("fetch", { request: missRequest });
+      expect(await miss.respondWithPromise).toBe(network);
+      expect(sandbox.fetch).toHaveBeenCalledWith(missRequest);
+    });
+
+    it("another same-origin GET in the shell cache (the device worker, SQLite) goes to the network first and is answered from the cache when the network fails", async () => {
+      const workerUrl = `${ORIGIN}/offline-sqlite/device-worker.mjs`;
+      const cachedWorker = new Response("cached worker");
+      const { sandbox, dispatch } = shellWorker({ [workerUrl]: cachedWorker });
+      const request = { method: "GET", mode: "same-origin", destination: "worker", url: workerUrl };
+
+      const online = new Response("network worker");
+      sandbox.fetch.mockResolvedValue(online);
+      const onlineEvent = dispatch("fetch", { request });
+      expect(onlineEvent.respondWith).toHaveBeenCalledTimes(1);
+      expect(await onlineEvent.respondWithPromise).toBe(online);
+
+      sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+      const offlineEvent = dispatch("fetch", { request });
+      expect(await offlineEvent.respondWithPromise).toBe(cachedWorker);
+
+      const notCached = dispatch("fetch", {
+        request: { method: "GET", mode: "cors", destination: "", url: `${ORIGIN}/campaigns?_rsc=1` },
+      });
+      // Not in the shell: a plain network error for the page, never an uncaught rejection in the worker.
+      expect(((await notCached.respondWithPromise) as Response).type).toBe("error");
+    });
+
+    it("a no-store GET (the session refresh of the shell) is never answered from the cache: it goes to the network untouched", async () => {
+      const cachedShell = new Response("cached shell");
+      const { sandbox, dispatch } = shellWorker({
+        "/offline-shell": cachedShell,
+        [`${ORIGIN}/offline-shell`]: cachedShell,
+      });
+
+      const event = dispatch("fetch", {
+        request: { method: "GET", mode: "cors", cache: "no-store", destination: "", url: `${ORIGIN}/offline-shell` },
+      });
+
+      expect(event.respondWith).not.toHaveBeenCalled();
+      expect(sandbox.fetch).not.toHaveBeenCalled();
+    });
+
+    it("a GET to an offlineImageHosts host for a URL in the images cache is answered from the cache when the network fails", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      const imageUrl = "https://api.app.test/s3/object?key=art.png&sig=1";
+      const cachedImage = new Response("image bytes");
+      const imagesCache = makeCache({
+        match: vi.fn(async (url: string) => (url === imageUrl ? cachedImage : undefined)),
+      });
+      sandbox.caches.open.mockImplementation(async (name: string) =>
+        name === "test-images" ? imagesCache : makeCache(),
+      );
+      sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+
+      const event = dispatch("fetch", {
+        request: { method: "GET", mode: "no-cors", destination: "image", url: imageUrl },
+      });
+
+      expect(event.respondWith).toHaveBeenCalledTimes(1);
+      expect(await event.respondWithPromise).toBe(cachedImage);
+      expect(sandbox.caches.open).toHaveBeenCalledWith("test-images");
+
+      const online = new Response("fresh bytes");
+      sandbox.fetch.mockResolvedValue(online);
+      const onlineEvent = dispatch("fetch", {
+        request: { method: "GET", mode: "no-cors", destination: "image", url: imageUrl },
+      });
+      expect(await onlineEvent.respondWithPromise).toBe(online);
+
+      const otherHost = dispatch("fetch", {
+        request: { method: "GET", mode: "no-cors", destination: "image", url: "https://cdn.other.test/a.png" },
+      });
+      expect(otherHost.respondWith).not.toHaveBeenCalled();
+    });
+
+    it("an offline image host's image through Next's optimizer (/_next/image) falls back to the downloaded original", async () => {
+      const { sandbox, dispatch } = loadWorker(SHELL_CONFIG);
+      const imageUrl = "https://api.app.test/s3/object?key=art.png&sig=1";
+      const cachedImage = new Response("image bytes");
+      const imagesCache = makeCache({
+        match: vi.fn(async (url: string) => (url === imageUrl ? cachedImage : undefined)),
+      });
+      sandbox.caches.open.mockImplementation(async (name: string) =>
+        name === "test-images" ? imagesCache : makeCache(),
+      );
+      sandbox.fetch.mockRejectedValue(new TypeError("Failed to fetch"));
+      const optimized = `${ORIGIN}/_next/image?url=${encodeURIComponent(imageUrl)}&w=256&q=75`;
+
+      const event = dispatch("fetch", {
+        request: { method: "GET", mode: "no-cors", destination: "image", url: optimized },
+      });
+      expect(await event.respondWithPromise).toBe(cachedImage);
+
+      const missing = dispatch("fetch", {
+        request: {
+          method: "GET",
+          mode: "no-cors",
+          destination: "image",
+          url: `${ORIGIN}/_next/image?url=${encodeURIComponent("https://api.app.test/s3/other")}&w=256&q=75`,
+        },
+      });
+      expect(((await missing.respondWithPromise) as Response).type).toBe("error");
+    });
+  });
 });

package/src/server/index.ts

@@ -15,3 +15,8 @@ export { NotificationService as ServerNotificationService } from "../features/no
 export { FeatureService as ServerFeatureService } from "../features/feature/data/feature.service";
 export { PushService as ServerPushService } from "../features/push/data/push.service";
 export { S3Service as ServerS3Service } from "../features/s3/data/s3.service";
+
+// Offline mode: the build manifest the service worker precaches (/offline-manifest.json).
+export { buildOfflineManifest } from "../offline/server/build-offline-manifest";
+export type { OfflineManifest } from "../offline/server/build-offline-manifest";
+export { DEFAULT_SQLITE_MODULE_URL, OFFLINE_SQLITE_FILES } from "../offline/types";

package/src/unified/__tests__/JsonApiRequest.offline.spec.ts

@@ -0,0 +1,243 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ClientJsonApiGet, configureClientJsonApi } from "../../client/JsonApiClient";
+import { ClientAbstractService } from "../../core/abstracts/ClientAbstractService";
+import { DataClassRegistry } from "../../core/registry/DataClassRegistry";
+import { resetOfflineConfig, setDeviceStoreOpener } from "../../offline/config";
+import {
+  allowWhileReconnecting,
+  getOfflineState,
+  isReconnecting,
+  resetOfflineState,
+  setOfflineState,
+  setReconnecting,
+} from "../../offline/state";
+import type { DeviceStore } from "../../offline/store/DeviceStore";
+import { OFFLINE_REPLAY_HEADER } from "../../offline/types";
+import {
+  Factions,
+  Npcs,
+  TestModel,
+  npc,
+  setUpOffline,
+  tearDownOffline,
+} from "../../offline/__tests__/offline-fixtures";
+import { configureJsonApi, JsonApiDelete, JsonApiGet, JsonApiPatch } from "../JsonApiRequest";
+
+const API = "http://api.test/";
+
+function jsonResponse(status: number, body: unknown) {
+  return { ok: status >= 200 && status < 300, status, statusText: "", json: async () => body };
+}
+
+class TestService extends ClientAbstractService {}
+
+describe("the offline layer in the request path", () => {
+  let fetchMock: ReturnType<typeof vi.fn>;
+  let store: DeviceStore;
+
+  beforeEach(() => {
+    DataClassRegistry.registerObjectClass(Npcs, TestModel as any);
+    DataClassRegistry.registerObjectClass(Factions, TestModel as any);
+    configureJsonApi({ apiUrl: API });
+    configureClientJsonApi({ apiUrl: API });
+    fetchMock = vi.fn();
+    vi.stubGlobal("fetch", fetchMock);
+  });
+
+  afterEach(() => {
+    tearDownOffline();
+    vi.unstubAllGlobals();
+  });
+
+  it("not configured → directFetch exactly as today, no store opened", async () => {
+    resetOfflineConfig();
+    resetOfflineState();
+    const opener = vi.fn();
+    setDeviceStoreOpener(opener);
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { data: npc("n1", "Server", "C") }));
+    fetchMock.mockRejectedValueOnce(new TypeError("Failed to fetch"));
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { data: npc("n1", "Server", "C") }));
+
+    const read = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+    const unreachable = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+    await JsonApiPatch({
+      classKey: Npcs,
+      endpoint: "npcs/n1",
+      body: { data: {} },
+      overridesJsonApiCreation: true,
+      language: "en",
+    });
+
+    expect((read.data as any).name).toBe("Server");
+    expect(unreachable.response).toBe(503);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(opener).not.toHaveBeenCalled();
+    expect(getOfflineState().online).toBe(true);
+  });
+
+  it("configured and online, GET → server answer, nothing stored", async () => {
+    store = await setUpOffline();
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { data: npc("n1", "Server", "C") }));
+
+    const response = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+
+    expect((response.data as any).name).toBe("Server");
+    expect((await store.getRecord("npcs", "n1"))?.resource.attributes.name).toBe("Alda");
+  });
+
+  it("configured and online, a successful PATCH writes the response resource and included to the store", async () => {
+    store = await setUpOffline();
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse(200, {
+        data: {
+          ...npc("n1", "Alda online", "C"),
+          attributes: { name: "Alda online", updatedAt: "2026-11-01T10:00:00.000Z" },
+        },
+        included: [
+          {
+            type: "factions",
+            id: "f2",
+            attributes: { name: "New guild" },
+            relationships: { root: { data: { type: "roots", id: "C" } } },
+          },
+        ],
+      }),
+    );
+
+    await JsonApiPatch({
+      classKey: Npcs,
+      endpoint: "npcs/n1",
+      body: { data: {} },
+      overridesJsonApiCreation: true,
+      language: "en",
+    });
+
+    const stored = await store.getRecord("npcs", "n1");
+    expect(stored?.resource.attributes).toEqual({
+      name: "Alda online",
+      description: "Alda text",
+      updatedAt: "2026-11-01T10:00:00.000Z",
+    });
+    expect(stored?.updatedAt).toEqual(new Date("2026-11-01T10:00:00.000Z"));
+    expect((await store.getRecord("factions", "f2"))?.rootId).toBe("C");
+    expect(await store.queue()).toEqual([]);
+  });
+
+  it("configured and online, a successful POST stores the new record; a DELETE removes it", async () => {
+    store = await setUpOffline();
+    fetchMock.mockResolvedValueOnce(jsonResponse(201, { data: npc("n7", "Created", "C") }));
+    fetchMock.mockResolvedValueOnce({
+      ok: true,
+      status: 204,
+      statusText: "",
+      json: async () => {
+        throw new Error("empty");
+      },
+    });
+
+    await TestService["callApi"]({
+      type: Npcs,
+      method: "POST" as any,
+      endpoint: "npcs",
+      input: { data: {} },
+      overridesJsonApiCreation: true,
+    });
+    expect((await store.getRecord("npcs", "n7"))?.rootId).toBe("C");
+
+    await JsonApiDelete({ classKey: Npcs, endpoint: "npcs/n7", language: "en" });
+    expect(await store.getRecord("npcs", "n7")).toBeUndefined();
+  });
+
+  it("configured, network error → state.online becomes false and the same request is answered locally", async () => {
+    store = await setUpOffline();
+    fetchMock.mockRejectedValueOnce(new TypeError("Failed to fetch"));
+
+    const response = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+
+    expect(getOfflineState().online).toBe(false);
+    expect(response.ok).toBe(true);
+    expect((response.data as any).name).toBe("Alda");
+
+    const next = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n2", language: "en" });
+    expect((next.data as any).name).toBe("brom");
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("during a reconnect attempt (offline), GETs and the let-through write go to the network, any other write stays local; a network error ends the attempt", async () => {
+    store = await setUpOffline();
+    setOfflineState({ online: false });
+    setReconnecting(true);
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { data: npc("n1", "Server", "C") }));
+    fetchMock.mockResolvedValueOnce(jsonResponse(200, { data: npc("n1", "Sent", "C") }));
+
+    const read = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+    expect((read.data as any).name).toBe("Server");
+
+    const release = allowWhileReconnecting(`${API}npcs/n1`);
+    await JsonApiPatch({
+      classKey: Npcs,
+      endpoint: "npcs/n1",
+      body: { data: npc("n1", "Sent", "C") },
+      overridesJsonApiCreation: true,
+      language: "en",
+    });
+    release();
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    await JsonApiPatch({
+      classKey: Npcs,
+      endpoint: "npcs/n2",
+      body: { data: npc("n2", "Local", "C") },
+      overridesJsonApiCreation: true,
+      language: "en",
+    });
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+    expect(getOfflineState().online).toBe(false);
+
+    fetchMock.mockRejectedValueOnce(new TypeError("Failed to fetch"));
+    const failed = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+    expect(failed.ok).toBe(true);
+    expect(isReconnecting()).toBe(false);
+  });
+
+  it("a request carrying x-offline-replay is never answered locally", async () => {
+    store = await setUpOffline();
+    setOfflineState({ online: false });
+    configureJsonApi({ apiUrl: API, additionalHeaders: { [OFFLINE_REPLAY_HEADER]: "1" } });
+    fetchMock.mockRejectedValueOnce(new TypeError("Failed to fetch"));
+
+    const response = await JsonApiGet({ classKey: Npcs, endpoint: "npcs/n1", language: "en" });
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(response.response).toBe(503);
+    expect(response.ok).toBe(false);
+  });
+
+  it("ClientAbstractService.next/previous and ClientJsonApiGet are answered locally when offline", async () => {
+    store = await setUpOffline();
+    setOfflineState({ online: false });
+
+    const first = await ClientJsonApiGet({
+      classKey: Npcs,
+      endpoint: "roots/C/npcs?orderBy=name&page[size]=1",
+      language: "en",
+    });
+    expect((first.data as any[]).map((item) => item.name)).toEqual(["Alda"]);
+    expect(first.next).toBe(`${API}roots/C/npcs?orderBy=name&page[size]=1&page[offset]=1`);
+
+    const nextRef: { next?: string } = {};
+    const previousRef: { previous?: string } = {};
+    const page2 = await TestService.next<any[]>({
+      type: Npcs,
+      endpoint: first.next!,
+      next: nextRef,
+      previous: previousRef,
+    });
+    expect(page2.map((item) => item.name)).toEqual(["brom"]);
+    expect(previousRef.previous).toBe(`${API}roots/C/npcs?orderBy=name&page[size]=1&page[offset]=0`);
+
+    const page1 = await TestService.previous<any[]>({ type: Npcs, endpoint: previousRef.previous! });
+    expect(page1.map((item) => item.name)).toEqual(["Alda"]);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+});