@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.1

package/src/offline/sync/models/OfflineChangeSetInterface.ts

@@ -0,0 +1,54 @@
+import { ApiDataInterface } from "../../../core/interfaces/ApiDataInterface";
+
+/** One waiting change as the server reads it (C1b, `attributes.changes[]`). */
+export type OfflineChange = {
+  seq: number;
+  method: "POST" | "PUT" | "PATCH" | "DELETE";
+  /** Relative to the API base, as EndpointCreator built it. */
+  path: string;
+  /** The JSON:API document the model built when the GM saved. */
+  body?: Record<string, unknown>;
+  /** Set for an edit or delete of one record. */
+  recordType?: string;
+  recordId?: string;
+  /** The record's JSON:API resource as of the last sync. */
+  base?: Record<string, unknown> | null;
+  /**
+   * Set on a re-sent change after the GM resolved its conflict. The change keeps its original
+   * `body` and `base`; the server runs the normal three-way merge and settles each conflicting
+   * field by `choices` (kind "mine": every conflicting field is "mine").
+   */
+  resolution?: OfflineChangeResolution;
+};
+
+export type OfflineChangeResolution = {
+  kind: "mine" | "merged";
+  /** Per conflicting field: whose value wins. */
+  choices?: Record<string, "mine" | "theirs" | "merged">;
+  /** The model-built JSON:API document holding only the fields chosen "merged", with their hand-merged values. */
+  mergedBody?: Record<string, unknown>;
+};
+
+/** The server's answer for one change (C1b, `attributes.results[]`). */
+export type OfflineChangeResult = {
+  seq: number;
+  status: "applied" | "conflict" | "could-not-apply" | "waiting";
+  conflict?: "fields" | "deleted-on-server" | "changed-on-server";
+  /** JSON:API resource as it is now on the server. */
+  current?: Record<string, unknown> | null;
+  /** Attributes the merge settled (for the conflict screen). */
+  merged?: Record<string, unknown>;
+  conflictFields?: string[];
+  /** Rich-text field → conflicting block ids. */
+  conflictBlocks?: Record<string, string[]>;
+  /** The server's reason for could-not-apply. */
+  detail?: string;
+  /** JSON:API document the route answered, when applied. */
+  response?: Record<string, unknown>;
+};
+
+export type OfflineChangeSetInput = { id: string; changes: OfflineChange[] };
+
+export interface OfflineChangeSetInterface extends ApiDataInterface {
+  get results(): OfflineChangeResult[];
+}

package/src/offline/sync/models/RootSync.ts

@@ -0,0 +1,68 @@
+import { AbstractApiData } from "../../../core/abstracts/AbstractApiData";
+import { JsonApiHydratedDataInterface } from "../../../core/interfaces/JsonApiHydratedDataInterface";
+import { RootSyncEntry, RootSyncInterface, RootSyncLink } from "./RootSyncInterface";
+
+/**
+ * Child path of the sync answer under the root module record
+ * (`GET /<root endpoint>/:id/sync`), the same value as the app API's sync meta endpoint
+ * (in Wyrdli, `campaignSyncMeta.endpoint`).
+ */
+export const ROOT_SYNC_ENDPOINT = "sync";
+
+/** The sync answer for one root record (`root-syncs`, id = root record id). Read-only. */
+export class RootSync extends AbstractApiData implements RootSyncInterface {
+  private _serverTime?: Date;
+  private _locked: boolean = false;
+  private _lockedFrom?: Date;
+  private _entries?: RootSyncEntry[];
+  private _links?: RootSyncLink[];
+
+  get serverTime(): Date {
+    if (!this._serverTime) throw new Error("serverTime is not set.");
+    return this._serverTime;
+  }
+
+  get locked(): boolean {
+    return this._locked;
+  }
+
+  get lockedFrom(): Date | undefined {
+    return this._lockedFrom;
+  }
+
+  get entries(): RootSyncEntry[] {
+    return this._entries ?? [];
+  }
+
+  get links(): RootSyncLink[] {
+    return this._links ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    const attributes = data.jsonApi.attributes ?? {};
+    this._serverTime = attributes.serverTime ? new Date(attributes.serverTime) : undefined;
+    this._locked = Boolean(attributes.locked);
+    this._lockedFrom = attributes.lockedFrom ? new Date(attributes.lockedFrom) : undefined;
+    this._entries = (attributes.entries ?? []).map((entry: { type: string; id: string; updatedAt: string }) => ({
+      type: entry.type,
+      id: entry.id,
+      updatedAt: new Date(entry.updatedAt),
+    }));
+    this._links = (attributes.links ?? []).map((link: RootSyncLink) => ({
+      fromType: link.fromType,
+      fromId: link.fromId,
+      toType: link.toType,
+      toId: link.toId,
+      kind: link.kind,
+      props: link.props ?? {},
+    }));
+
+    return this;
+  }
+
+  createJsonApi(_data?: any): any {
+    throw new Error("RootSync is read-only and cannot be created");
+  }
+}

package/src/offline/sync/models/RootSyncInterface.ts

@@ -0,0 +1,20 @@
+import { ApiDataInterface } from "../../../core/interfaces/ApiDataInterface";
+
+export type RootSyncEntry = { type: string; id: string; updatedAt: Date };
+
+export type RootSyncLink = {
+  fromType: string;
+  fromId: string;
+  toType: string;
+  toId: string;
+  kind: string;
+  props: Record<string, unknown>;
+};
+
+export interface RootSyncInterface extends ApiDataInterface {
+  get serverTime(): Date;
+  get locked(): boolean;
+  get lockedFrom(): Date | undefined;
+  get entries(): RootSyncEntry[];
+  get links(): RootSyncLink[];
+}

package/src/offline/sync/models/__tests__/OfflineChangeSet.spec.ts

@@ -0,0 +1,47 @@
+import { beforeAll, describe, expect, it } from "vitest";
+import { ApiRequestDataTypeInterface } from "../../../../core/interfaces/ApiRequestDataTypeInterface";
+import { ModuleRegistry } from "../../../../core/registry/ModuleRegistry";
+import { ModuleFactory, ModuleWithPermissions } from "../../../../permissions/types";
+import { OfflineChangeSet } from "../OfflineChangeSet";
+import { offlineModules } from "../offline.modules";
+
+const moduleFactory: ModuleFactory = (params) =>
+  ({ pageUrl: params.pageUrl, name: params.name, model: params.model }) as ModuleWithPermissions;
+
+const registerIfAbsent = (key: string, module: ApiRequestDataTypeInterface) => {
+  try {
+    ModuleRegistry.get(key as any);
+  } catch {
+    ModuleRegistry.register(key, module);
+  }
+};
+
+beforeAll(() => {
+  for (const [key, module] of Object.entries(offlineModules(moduleFactory))) registerIfAbsent(key, module);
+});
+
+describe("OfflineChangeSet", () => {
+  it("createJsonApi emits type offline-change-sets, the id and attributes.changes", () => {
+    const changes = [
+      { seq: 1, method: "POST" as const, path: "npcs", body: { data: { type: "npcs", id: "n1" } } },
+      { seq: 2, method: "DELETE" as const, path: "npcs/n2", recordType: "npcs", recordId: "n2", base: { id: "n2" } },
+    ];
+    const doc = new OfflineChangeSet().createJsonApi({ id: "pkg-1", changes });
+    expect(doc.data.type).toBe("offline-change-sets");
+    expect(doc.data.id).toBe("pkg-1");
+    expect(doc.data.attributes.changes).toEqual(changes);
+  });
+
+  it("rehydrate reads results", () => {
+    const results = [
+      { seq: 1, status: "applied" },
+      { seq: 2, status: "conflict", conflict: "fields", conflictFields: ["name"] },
+    ];
+    const set = new OfflineChangeSet().rehydrate({
+      jsonApi: { type: "offline-change-sets", id: "pkg-1", attributes: { results } },
+      included: [],
+    } as any);
+    expect(set.id).toBe("pkg-1");
+    expect(set.results).toEqual(results);
+  });
+});

package/src/offline/sync/models/__tests__/RootSync.spec.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from "vitest";
+import { RootSync } from "../RootSync";
+
+describe("RootSync", () => {
+  it("rehydrate parses serverTime, lockedFrom and every entries[].updatedAt with new Date", () => {
+    const sync = new RootSync().rehydrate({
+      jsonApi: {
+        type: "root-syncs",
+        id: "c1",
+        attributes: {
+          serverTime: "2026-11-01T10:00:00.000Z",
+          locked: false,
+          lockedFrom: "2026-11-20T00:00:00.000Z",
+          entries: [
+            { type: "npcs", id: "n1", updatedAt: "2026-10-30T08:00:00.000Z" },
+            { type: "scenes", id: "s1", updatedAt: "2026-10-31T09:30:00.000Z" },
+          ],
+          links: [
+            { fromType: "npcs", fromId: "n1", toType: "scenes", toId: "s1", kind: "APPEARS_IN", props: { x: 1 } },
+          ],
+        },
+      },
+      included: [],
+    } as any);
+
+    expect(sync.id).toBe("c1");
+    expect(sync.serverTime).toBeInstanceOf(Date);
+    expect(sync.serverTime.toISOString()).toBe("2026-11-01T10:00:00.000Z");
+    expect(sync.locked).toBe(false);
+    expect(sync.lockedFrom).toBeInstanceOf(Date);
+    expect(sync.lockedFrom?.toISOString()).toBe("2026-11-20T00:00:00.000Z");
+    expect(sync.entries.map((e) => e.updatedAt)).toEqual([
+      new Date("2026-10-30T08:00:00.000Z"),
+      new Date("2026-10-31T09:30:00.000Z"),
+    ]);
+    expect(sync.entries.every((e) => e.updatedAt instanceof Date)).toBe(true);
+    expect(sync.links).toEqual([
+      { fromType: "npcs", fromId: "n1", toType: "scenes", toId: "s1", kind: "APPEARS_IN", props: { x: 1 } },
+    ]);
+  });
+
+  it("a null lockedFrom rehydrates as undefined", () => {
+    const sync = new RootSync().rehydrate({
+      jsonApi: {
+        type: "root-syncs",
+        id: "c1",
+        attributes: { serverTime: "2026-11-01T10:00:00.000Z", locked: true, lockedFrom: null, entries: [], links: [] },
+      },
+      included: [],
+    } as any);
+    expect(sync.locked).toBe(true);
+    expect(sync.lockedFrom).toBeUndefined();
+  });
+});

package/src/offline/sync/models/index.ts

@@ -0,0 +1,5 @@
+export * from "./RootSync";
+export * from "./RootSyncInterface";
+export * from "./OfflineChangeSet";
+export * from "./OfflineChangeSetInterface";
+export * from "./offline.modules";

package/src/offline/sync/models/offline.modules.ts

@@ -0,0 +1,14 @@
+import { ModuleFactory, ModuleWithPermissions } from "../../../permissions/types";
+import { RootSync } from "./RootSync";
+import { OfflineChangeSet } from "./OfflineChangeSet";
+
+/**
+ * The offline resources, as one object an app that opts into offline mode
+ * spreads into its `allModules` (same rationale as `analyticsModules`).
+ * Neither has a pageUrl: these are not navigable resources.
+ */
+export const offlineModules = (factory: ModuleFactory) =>
+  ({
+    OfflineChangeSet: factory({ name: "offline-change-sets", model: OfflineChangeSet }),
+    RootSync: factory({ name: "root-syncs", model: RootSync }),
+  }) satisfies Record<string, ModuleWithPermissions>;

package/src/offline/sync/runtime.ts

@@ -0,0 +1,226 @@
+import { getCookie } from "cookies-next";
+import { getClientToken } from "../../client/token";
+import { directFetch } from "../../client/request";
+import { EndpointCreator } from "../../core/endpoint/EndpointCreator";
+import { buildUrl } from "../../unified/JsonApiRequest";
+import {
+  getOfflineConfig,
+  getOfflineStore,
+  isOfflineConfigured,
+  OfflineUnavailableError,
+  refreshOfflineDeviceState,
+} from "../config";
+import { getOfflineState, isReconnecting, setOfflineState, setReconnecting, subscribeOfflineState } from "../state";
+import { OFFLINE_REPLAY_HEADER } from "../types";
+import { refreshOfflineCounts } from "./counts";
+import { drainQueue } from "./drain-queue";
+import { knownRootIds, refreshLockedRoots } from "./known-roots";
+import { ROOT_SYNC_ENDPOINT } from "./models/RootSync";
+import { currentLocale } from "./session-refresh";
+import { syncAll } from "./sync-root";
+
+/** How often the stored lock dates are checked again (a lock date can pass while offline). */
+const LOCK_CHECK_INTERVAL_MS = 60_000;
+/** How often the API is probed while the session is offline but the browser says it is online. */
+const PROBE_INTERVAL_MS = 30_000;
+
+/**
+ * Asks the API whether it can be reached again. The request carries the replay header, so
+ * `directFetch` sends it to the network instead of answering it from the device copy. Any
+ * answer (even a 401) means the API is reachable; only a network error means it is not.
+ */
+async function probeApi(): Promise<boolean> {
+  const config = getOfflineConfig();
+  const store = await getOfflineStore();
+  const [rootId] = await knownRootIds(store);
+  const endpoint = rootId
+    ? new EndpointCreator({ endpoint: config.rootModule, id: rootId, childEndpoint: ROOT_SYNC_ENDPOINT })
+    : new EndpointCreator({ endpoint: config.rootModule }).addAdditionalParam("page[size]", "1");
+
+  const response = await directFetch({
+    method: "GET",
+    url: buildUrl(endpoint.generate()),
+    token: await getClientToken(),
+    language: currentLocale(),
+    additionalHeaders: { [OFFLINE_REPLAY_HEADER]: "1" },
+  });
+  return !response.networkError;
+}
+
+/** Remembers (for the tab) the sign-in a reload for the login was already tried for. */
+const LOGIN_RELOAD_KEY = "nja-offline-login-reload";
+let _reloadedForSignIn: string | undefined;
+
+/** A short fingerprint of the sign-in (the `token` cookie), never the token itself. */
+async function signInFingerprint(): Promise<string> {
+  const token = await getCookie("token");
+  if (!token) return "none";
+  let hash = 5381;
+  for (const char of String(token)) hash = ((hash * 33) ^ char.charCodeAt(0)) >>> 0;
+  return hash.toString(36);
+}
+
+const readReloadMarker = (): string | null => {
+  try {
+    return window.sessionStorage.getItem(LOGIN_RELOAD_KEY);
+  } catch {
+    return null;
+  }
+};
+
+const writeReloadMarker = (value: string | null): void => {
+  try {
+    if (value === null) window.sessionStorage.removeItem(LOGIN_RELOAD_KEY);
+    else window.sessionStorage.setItem(LOGIN_RELOAD_KEY, value);
+  } catch {
+    // Storage unavailable: the module flag still stops a loop within this page.
+  }
+};
+
+/**
+ * The sign-in expired: reloading sends the GM through the proxy to the login page. The queue
+ * stays. Tried once per sign-in: when the API still refuses the same sign-in after the reload
+ * (a 401 while the cookie exists), the GM stays on the page and the queue waits for a new
+ * sign-in, instead of reloading in a loop.
+ */
+async function signInExpired(): Promise<void> {
+  const signIn = await signInFingerprint();
+  if (_reloadedForSignIn === signIn || readReloadMarker() === signIn) {
+    console.warn("[offline] the sign-in expired; log in again to send the waiting changes");
+    return;
+  }
+  _reloadedForSignIn = signIn;
+  writeReloadMarker(signIn);
+  try {
+    window.location.reload();
+  } catch (error) {
+    console.warn("[offline] the sign-in expired; log in again to send the waiting changes", error);
+  }
+}
+
+/**
+ * Logs a failure of the runtime, except the browser being found unable to keep the device copy:
+ * that is warned once (`markOfflineUnavailable`) and the runtime stops.
+ */
+const warnUnlessUnavailable =
+  (message: string) =>
+  (error: unknown): void => {
+    if (!(error instanceof OfflineUnavailableError)) console.warn(message, error);
+  };
+
+const _runningRuntimes = new Set<() => void>();
+
+/** Stops every running offline runtime (timers, listeners). Called on logout. */
+export function stopOfflineRuntime(): void {
+  for (const stop of [..._runningRuntimes]) stop();
+}
+
+/**
+ * Starts the offline runtime: drain-then-sync on open (online) and on every reconnect, syncAll
+ * every `syncIntervalMs` while online, a probe of the API while the session is offline but the
+ * browser is online (a probe that reaches the API runs the drain and the sync, and the session
+ * goes online once they succeeded), and the lock dates checked every minute. Returns the stop
+ * function.
+ */
+export function startOfflineRuntime(): () => void {
+  refreshOfflineDeviceState();
+  if (!isOfflineConfigured()) return () => {};
+  const config = getOfflineConfig();
+
+  let running: Promise<void> | undefined;
+  let goingOnlineAfterSync = false;
+  /**
+   * Drain then sync. `reconnect`: a probe reached the API while the session is offline; the
+   * session stays offline during the drain and the sync and goes online only when both ran
+   * without a network failure (spec § 4: offline "until a sync succeeds").
+   */
+  const run = (reconnect: boolean): Promise<void> => {
+    if (!running) {
+      running = (async () => {
+        let succeeded = false;
+        if (reconnect) setReconnecting(true);
+        try {
+          const drained = await drainQueue();
+          if (drained.stoppedForLogin) {
+            await signInExpired();
+            return;
+          }
+          writeReloadMarker(null);
+          if (reconnect ? !isReconnecting() : !getOfflineState().online) return;
+          await syncAll();
+          succeeded = reconnect && isReconnecting();
+        } catch (error) {
+          warnUnlessUnavailable("[offline] background sync failed")(error);
+        } finally {
+          if (reconnect) setReconnecting(false);
+          running = undefined;
+          if (succeeded) {
+            goingOnlineAfterSync = true;
+            setOfflineState({ online: true });
+            goingOnlineAfterSync = false;
+            // Changes queued while the attempt ran (an edit, a resolved conflict) waited because
+            // the session was still offline: they are sent now, not at the next sync interval.
+            if (getOfflineState().pending > 0) {
+              drainQueue().catch(warnUnlessUnavailable("[offline] sending the waiting changes failed"));
+            }
+          }
+        }
+      })();
+    }
+    return running;
+  };
+  const runOnline = () => run(false);
+
+  let probing = false;
+  const probe = async () => {
+    if (probing || running || getOfflineState().online) return;
+    if (typeof navigator !== "undefined" && navigator.onLine === false) return;
+    probing = true;
+    try {
+      if (await probeApi()) await run(true);
+    } catch (error) {
+      warnUnlessUnavailable("[offline] probing the API failed")(error);
+    } finally {
+      probing = false;
+    }
+  };
+
+  // The browser says the network is back: probe the API now (the state stays offline until then).
+  const onBrowserOnline = () => void probe();
+  if (typeof window !== "undefined") window.addEventListener("online", onBrowserOnline);
+
+  let wasOnline = getOfflineState().online;
+  const unsubscribe = subscribeOfflineState((state) => {
+    // The browser cannot keep the device copy: offline mode is off for the page.
+    if (!state.available) {
+      stop();
+      return;
+    }
+    // Online after a reconnect attempt: its drain and sync already ran.
+    if (state.online && !wasOnline && !goingOnlineAfterSync) void runOnline();
+    wasOnline = state.online;
+  });
+
+  void refreshLockedRoots().catch(warnUnlessUnavailable("[offline] lock check failed"));
+  void refreshOfflineCounts().catch(warnUnlessUnavailable("[offline] reading the queue failed"));
+  if (getOfflineState().online) void runOnline();
+
+  const syncTimer = setInterval(() => {
+    if (getOfflineState().online) void runOnline();
+  }, config.syncIntervalMs);
+  const probeTimer = setInterval(() => void probe(), PROBE_INTERVAL_MS);
+  const lockTimer = setInterval(() => {
+    void refreshLockedRoots().catch(warnUnlessUnavailable("[offline] lock check failed"));
+  }, LOCK_CHECK_INTERVAL_MS);
+
+  const stop = () => {
+    _runningRuntimes.delete(stop);
+    clearInterval(syncTimer);
+    clearInterval(probeTimer);
+    clearInterval(lockTimer);
+    if (typeof window !== "undefined") window.removeEventListener("online", onBrowserOnline);
+    unsubscribe();
+  };
+  _runningRuntimes.add(stop);
+  return stop;
+}

package/src/offline/sync/session-refresh.ts

@@ -0,0 +1,32 @@
+import { getCookie } from "cookies-next";
+import { getI18nDefaultLocale, getI18nSupportedLocales } from "../../i18n/config";
+import { getOfflineConfig } from "../config";
+
+/** The locale of the page the GM is on (first path segment), or the app's default locale. */
+export function currentLocale(): string {
+  if (typeof window === "undefined") return getI18nDefaultLocale();
+  const first = window.location.pathname.split("/").filter(Boolean)[0];
+  return first && getI18nSupportedLocales().includes(first) ? first : getI18nDefaultLocale();
+}
+
+export type SessionRefreshResult = "ok" | "expired" | "unreachable";
+
+/**
+ * Renews the sign-in before the waiting changes are sent: one same-origin GET of the offline
+ * shell (`cache: "no-store"`). It passes through the app's proxy, which renews the `token`
+ * cookie; the shell path is public, so the proxy never redirects it. The sign-in has expired
+ * when the `token` cookie is absent after the request.
+ *
+ * This is the one `fetch` of the offline layer: a request to the web app itself, not the API
+ * (Carlo's decision, 2026-11-01).
+ */
+export async function refreshSession(): Promise<SessionRefreshResult> {
+  try {
+    await fetch(getOfflineConfig().shellPath(currentLocale()), { cache: "no-store", credentials: "same-origin" });
+  } catch {
+    return "unreachable";
+  }
+
+  const token = await getCookie("token");
+  return token ? "ok" : "expired";
+}