@carlonicora/nextjs-jsonapi 6.12.2 → 6.13.1

package/src/offline/sync/artwork-cache.ts

@@ -0,0 +1,67 @@
+// Artwork images for the device copy, kept in Cache Storage under the exact URL the stored
+// artwork record holds (`attributes.imageUrl`). The service worker answers those URLs from the
+// same cache when the network fails. The image downloads are plain GETs of the URLs the API
+// already returned (decision recorded in the plan).
+
+// The service worker names its caches `${appId}-images` and `${appId}-offline-${revision}`
+// (pwa/sw.js). The page does not load sw-config.js, so it finds the app id from those names;
+// Cache Storage is per origin, so only this app's caches are listed.
+const IMAGES_CACHE_SUFFIX = "-images";
+const OFFLINE_CACHE_MARKER = "-offline-";
+
+async function imagesCacheName(): Promise<string | undefined> {
+  if (typeof caches === "undefined") return undefined;
+  const keys = await caches.keys();
+  const existing = keys.find((key) => key.endsWith(IMAGES_CACHE_SUFFIX));
+  if (existing) return existing;
+
+  const offline = keys.find((key) => key.includes(OFFLINE_CACHE_MARKER));
+  if (!offline) return undefined;
+  return `${offline.slice(0, offline.indexOf(OFFLINE_CACHE_MARKER))}${IMAGES_CACHE_SUFFIX}`;
+}
+
+/** The image URL a stored resource carries, if any. */
+export function imageUrlOf(resource: any): string | undefined {
+  const url = resource?.attributes?.imageUrl;
+  return typeof url === "string" && url.length > 0 ? url : undefined;
+}
+
+/**
+ * Makes sure `url` is in the images cache: downloaded when missing. When `previousUrl` is a
+ * different URL of the same artwork, its entry is removed. A failed download is logged and
+ * retried at the next sync.
+ */
+export async function cacheArtworkImage(url: string, previousUrl?: string): Promise<void> {
+  const name = await imagesCacheName();
+  if (!name) return;
+  const cache = await caches.open(name);
+
+  if (previousUrl && previousUrl !== url) await cache.delete(previousUrl);
+  if (await cache.match(url)) return;
+
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      console.warn("[offline] could not download an artwork image", url, response.status);
+      return;
+    }
+    await cache.put(url, response);
+  } catch (error) {
+    console.warn("[offline] could not download an artwork image", url, error);
+  }
+}
+
+/** Removes the cached copy of `url`. */
+export async function removeArtworkImage(url: string): Promise<void> {
+  const name = await imagesCacheName();
+  if (!name) return;
+  const cache = await caches.open(name);
+  await cache.delete(url);
+}
+
+/** Deletes this app's whole images cache (logout, or another user signing in). */
+export async function deleteImagesCaches(): Promise<void> {
+  if (typeof caches === "undefined") return;
+  const keys = await caches.keys();
+  await Promise.all(keys.filter((key) => key.endsWith(IMAGES_CACHE_SUFFIX)).map((key) => caches.delete(key)));
+}

package/src/offline/sync/conflicts.ts

@@ -0,0 +1,211 @@
+import { EndpointCreator } from "../../core/endpoint/EndpointCreator";
+import { getOfflineConfig, getOfflineStore } from "../config";
+import { getOfflineState } from "../state";
+import type { Conflict, DeviceStore, QueueEntry } from "../store/DeviceStore";
+import type { OfflineChangeResolution } from "./models/OfflineChangeSetInterface";
+import { refreshOfflineCounts } from "./counts";
+import { drainQueue } from "./drain-queue";
+
+export { useConflicts } from "./counts";
+
+export type ConflictChoice =
+  | { kind: "mine" }
+  | { kind: "theirs" }
+  /**
+   * Per conflicting field: whose value wins. `mergedBody`: the JSON:API document the record
+   * type's model built with createJsonApi() holding only the fields chosen "merged".
+   */
+  | { kind: "fields"; choices: Record<string, "mine" | "theirs" | "merged">; mergedBody?: any }
+  | { kind: "restore" }
+  | { kind: "accept-deletion" }
+  | { kind: "delete-anyway" }
+  | { kind: "retry" }
+  | { kind: "discard" };
+
+function updatedAtOf(resource: any): Date | null {
+  const value = resource?.attributes?.updatedAt;
+  if (!value) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/** Writes the chosen "theirs" and "merged" values of the conflicting fields into the stored record. */
+async function applyChoicesToRecord(
+  store: DeviceStore,
+  conflict: Conflict,
+  choices: Record<string, "mine" | "theirs" | "merged">,
+  mergedBody: any,
+): Promise<void> {
+  if (!conflict.recordType || !conflict.recordId) return;
+  const record = await store.getRecord(conflict.recordType, conflict.recordId);
+  if (!record) return;
+  const attributes = { ...(record.resource?.attributes ?? {}) };
+  const relationships = { ...(record.resource?.relationships ?? {}) };
+  for (const [field, choice] of Object.entries(choices)) {
+    const source = choice === "theirs" ? conflict.theirs : choice === "merged" ? mergedBody?.data : undefined;
+    if (!source) continue;
+    if (source.attributes && field in source.attributes) attributes[field] = source.attributes[field];
+    else if (source.relationships && field in source.relationships) relationships[field] = source.relationships[field];
+  }
+  await store.putRecord({ ...record, resource: { ...record.resource, attributes, relationships } });
+}
+
+async function rootIdOf(store: DeviceStore, conflict: Conflict, entry: QueueEntry | undefined): Promise<string> {
+  if (entry) return entry.rootId;
+  if (conflict.recordType && conflict.recordId) {
+    const record = await store.getRecord(conflict.recordType, conflict.recordId);
+    if (record) return record.rootId;
+  }
+  throw new Error(`[offline] conflict ${conflict.id} belongs to no root record on this device`);
+}
+
+/** The collection path of a record type, from the configured module (EndpointCreator). */
+function collectionPath(recordType: string): string {
+  const module = getOfflineConfig().types.find((typeConfig) => typeConfig.module.name === recordType)?.module;
+  return new EndpointCreator({ endpoint: module ?? recordType }).generate();
+}
+
+/** Queues the conflicting change again, unchanged apart from `resolution`, and drops the old entry. */
+async function requeueOriginal(
+  store: DeviceStore,
+  conflict: Conflict,
+  entry: QueueEntry | undefined,
+  fallbackMethod: "PATCH" | "DELETE",
+  resolution: OfflineChangeResolution,
+): Promise<void> {
+  const method = entry?.method ?? fallbackMethod;
+  const body = method === "DELETE" ? undefined : (entry?.body ?? conflict.mine ?? undefined);
+  await store.enqueue({
+    rootId: await rootIdOf(store, conflict, entry),
+    method,
+    path:
+      entry?.path ??
+      new EndpointCreator({ endpoint: collectionPath(conflict.recordType!), id: conflict.recordId }).generate(),
+    ...(body !== undefined ? { body } : {}),
+    recordType: entry?.recordType ?? conflict.recordType,
+    recordId: entry?.recordId ?? conflict.recordId,
+    base: entry ? entry.base : (conflict.base ?? null),
+    // QueueEntry["resolution"] is the store's copy of OfflineChange["resolution"].
+    resolution: resolution as QueueEntry["resolution"],
+  });
+  if (entry) await store.removeQueueEntry(entry.seq);
+}
+
+async function resolve(store: DeviceStore, conflict: Conflict, choice: ConflictChoice): Promise<void> {
+  const entry = (await store.queue()).find((candidate) => candidate.seq === conflict.queueSeq);
+  const dropEntry = async () => {
+    if (entry) await store.removeQueueEntry(entry.seq);
+  };
+
+  switch (choice.kind) {
+    case "mine":
+    case "fields": {
+      if (choice.kind === "fields" && Object.values(choice.choices).every((value) => value === "theirs")) {
+        return resolve(store, conflict, { kind: "theirs" });
+      }
+      // The ORIGINAL change goes back (original body and base, so the server's three-way merge
+      // keeps every field only the server changed), carrying how each conflicting field is settled.
+      const resolution: OfflineChangeResolution =
+        choice.kind === "mine"
+          ? { kind: "mine" }
+          : {
+              kind: "merged",
+              choices: choice.choices,
+              ...(choice.mergedBody !== undefined ? { mergedBody: choice.mergedBody } : {}),
+            };
+      await requeueOriginal(store, conflict, entry, "PATCH", resolution);
+      if (choice.kind === "fields") await applyChoicesToRecord(store, conflict, choice.choices, choice.mergedBody);
+      break;
+    }
+    case "theirs": {
+      // Only the device changes: the server's version replaces mine.
+      await dropEntry();
+      if (conflict.recordType && conflict.recordId) {
+        if (conflict.theirs) {
+          await store.putRecord({
+            type: conflict.recordType,
+            id: conflict.recordId,
+            rootId: await rootIdOf(store, conflict, entry),
+            resource: conflict.theirs,
+            updatedAt: updatedAtOf(conflict.theirs),
+            base: null,
+            localOnly: false,
+          });
+        } else {
+          await store.deleteRecord(conflict.recordType, conflict.recordId);
+        }
+      }
+      break;
+    }
+    case "restore": {
+      // Deleted on the server: created again with my version.
+      if (!conflict.recordType) throw new Error(`[offline] conflict ${conflict.id} has no record to restore`);
+      const body = conflict.mine ?? entry?.body;
+      const rootId = await rootIdOf(store, conflict, entry);
+      await store.enqueue({
+        rootId,
+        method: "POST",
+        path: collectionPath(conflict.recordType),
+        body,
+        recordType: conflict.recordType,
+        recordId: conflict.recordId,
+        base: null,
+      });
+      await dropEntry();
+      if (conflict.recordId) {
+        const record = await store.getRecord(conflict.recordType, conflict.recordId);
+        // localOnly keeps it on the device until the server has it again.
+        if (record) await store.putRecord({ ...record, base: null, localOnly: true });
+        else if (body?.data)
+          await store.putRecord({
+            type: conflict.recordType,
+            id: conflict.recordId,
+            rootId,
+            resource: body.data,
+            updatedAt: null,
+            base: null,
+            localOnly: true,
+          });
+      }
+      break;
+    }
+    case "accept-deletion": {
+      await dropEntry();
+      if (conflict.recordType && conflict.recordId) await store.deleteRecord(conflict.recordType, conflict.recordId);
+      break;
+    }
+    case "delete-anyway": {
+      // The original DELETE with a resolution: the server skips the changed-on-server check.
+      await requeueOriginal(store, conflict, entry, "DELETE", { kind: "mine" });
+      break;
+    }
+    case "retry": {
+      if (entry) await store.setQueueStatus(entry.seq, "pending");
+      break;
+    }
+    case "discard": {
+      await dropEntry();
+      break;
+    }
+  }
+
+  await store.removeConflict(conflict.id);
+}
+
+/**
+ * Applies the GM's choice for one conflict. "keep mine", per-field choices, "restore" and "delete anyway"
+ * queue one more change (sent with the next package); "keep theirs" and "let the deletion
+ * stand" only update the device. Online, the queue is sent right away.
+ */
+export async function resolveConflict(id: string, choice: ConflictChoice): Promise<void> {
+  const store = await getOfflineStore();
+  const conflict = (await store.conflicts()).find((candidate) => candidate.id === id);
+  if (!conflict) throw new Error(`[offline] no conflict ${id}`);
+
+  await store.transaction((tx) => resolve(tx, conflict, choice));
+  await refreshOfflineCounts(store);
+
+  if (getOfflineState().online) {
+    drainQueue().catch((error) => console.warn("[offline] sending the resolved change failed", error));
+  }
+}

package/src/offline/sync/counts.ts

@@ -0,0 +1,39 @@
+import { useSyncExternalStore } from "react";
+import { getOfflineConfig, getOfflineStore, isOfflineConfigured } from "../config";
+import { setOfflineState } from "../state";
+import type { Conflict, DeviceStore } from "../store/DeviceStore";
+
+const EMPTY: Conflict[] = [];
+let _conflicts: Conflict[] = EMPTY;
+const _listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+/** Re-reads the queue and the conflicts: updates `pending`/`conflicts` and the `useConflicts` list. */
+export async function refreshOfflineCounts(store?: DeviceStore): Promise<void> {
+  if (!store) {
+    if (!isOfflineConfigured() || !getOfflineConfig().getUserId()) return;
+    store = await getOfflineStore();
+  }
+  const entries = await store.queue();
+  _conflicts = await store.conflicts();
+  for (const listener of [..._listeners]) listener();
+  setOfflineState({
+    pending: entries.filter((entry) => entry.status !== "conflict").length,
+    conflicts: _conflicts.length,
+  });
+}
+
+/** The unresolved conflicts of the signed-in user's device. */
+export function useConflicts(): Conflict[] {
+  return useSyncExternalStore(
+    subscribe,
+    () => _conflicts,
+    () => EMPTY,
+  );
+}

package/src/offline/sync/drain-queue.ts

@@ -0,0 +1,246 @@
+import { EndpointCreator } from "../../core/endpoint/EndpointCreator";
+import { Modules } from "../../core/registry/ModuleRegistry";
+import { buildUrl, JsonApiPost } from "../../unified/JsonApiRequest";
+import { getOfflineConfig, getOfflineStore, isOfflineConfigured } from "../config";
+import { allowWhileReconnecting, getOfflineState, setOfflineState } from "../state";
+import type { DeviceStore, QueueEntry } from "../store/DeviceStore";
+import { isRootLocked } from "../store/lifecycle";
+import { writeThrough } from "../write-through";
+import { refreshOfflineCounts } from "./counts";
+import { OfflineChangeSet } from "./models/OfflineChangeSet";
+import { OfflineChange, OfflineChangeResult } from "./models/OfflineChangeSetInterface";
+import { currentLocale, refreshSession } from "./session-refresh";
+import { recordKeysOfEntry, waitingRecordKeys } from "./waiting";
+
+export type DrainResult = { applied: number; conflicts: number; stoppedForLogin: boolean };
+
+const syncedTypeNames = () => new Set(getOfflineConfig().types.map((typeConfig) => typeConfig.module.name));
+
+/**
+ * The body as sent: each resource's server-owned fields (AI summaries, tl;dr, `aiStatus`, …) are
+ * left out of its attributes. The stored body and the stored record keep them.
+ */
+function withoutServerOwnedFields(body: any): any {
+  const data = body?.data;
+  if (!data) return body;
+  const owned = new Map(
+    getOfflineConfig().types.map((typeConfig) => [typeConfig.module.name, typeConfig.serverOwnedFields]),
+  );
+  const strip = (resource: any) => {
+    const fields = owned.get(resource?.type) ?? [];
+    if (!resource?.attributes || fields.length === 0) return resource;
+    const attributes = { ...resource.attributes };
+    for (const field of fields) delete attributes[field];
+    return { ...resource, attributes };
+  };
+  return { ...body, data: Array.isArray(data) ? data.map(strip) : strip(data) };
+}
+
+function toChange(entry: QueueEntry): OfflineChange {
+  const change: OfflineChange = { seq: entry.seq, method: entry.method as OfflineChange["method"], path: entry.path };
+  if (entry.body !== undefined) change.body = withoutServerOwnedFields(entry.body);
+  if (entry.recordType) change.recordType = entry.recordType;
+  if (entry.recordId) change.recordId = entry.recordId;
+  change.base = entry.base ?? null;
+  if (entry.resolution) change.resolution = entry.resolution;
+  return change;
+}
+
+/**
+ * The merge the server settled, as a resource the record type's model can rehydrate: the server's
+ * current resource with the merged attribute values laid over it (decision piece 2: the library
+ * shapes stored resources). Undefined when the server gave no merge or no current record.
+ */
+function mergedResource(current: any, merged: Record<string, unknown> | undefined): any | undefined {
+  if (!merged || !current?.type) return undefined;
+  return { ...current, attributes: { ...(current.attributes ?? {}), ...merged } };
+}
+
+function newPackageId(): string {
+  return globalThis.crypto.randomUUID();
+}
+
+/**
+ * The id of the package to send: the id of a package that never got its answer (the page
+ * closed, the network dropped) when one of the entries carries it, so the server applies it
+ * once; a fresh id otherwise.
+ */
+function packageIdFor(entries: QueueEntry[]): string {
+  return entries.find((entry) => entry.packageId)?.packageId ?? newPackageId();
+}
+
+/** The entries to send: pending, of unlocked root records, not behind a conflict on the same record. */
+async function entriesToSend(store: DeviceStore): Promise<QueueEntry[]> {
+  const all = await store.queue();
+  const typeNames = syncedTypeNames();
+  const blocked = waitingRecordKeys(
+    all.filter((entry) => entry.status === "conflict"),
+    typeNames,
+  );
+  const lockedIds = new Set(getOfflineState().lockedRootIds);
+  const lockedByRoot = new Map<string, boolean>();
+  const now = new Date();
+
+  const result: QueueEntry[] = [];
+  for (const entry of all) {
+    // "sending" is a package that never got its answer (the page closed): it is sent again.
+    if (entry.status !== "pending" && entry.status !== "sending") continue;
+    if (recordKeysOfEntry(entry, typeNames).some((key) => blocked.has(key))) continue;
+
+    if (!lockedByRoot.has(entry.rootId)) {
+      lockedByRoot.set(
+        entry.rootId,
+        lockedIds.has(entry.rootId) || isRootLocked(await store.getSyncState(entry.rootId), now),
+      );
+    }
+    if (lockedByRoot.get(entry.rootId)) continue;
+    result.push(entry);
+  }
+  return result.sort((a, b) => a.seq - b.seq);
+}
+
+async function applyResult(
+  store: DeviceStore,
+  entry: QueueEntry,
+  result: OfflineChangeResult,
+): Promise<"applied" | "conflict" | "pending"> {
+  if (result.status === "applied") {
+    await store.removeQueueEntry(entry.seq);
+    // The record's base is kept only while it has unsent changes; cleared first, so the
+    // write-through below may store the server's answer (it never overwrites a record that
+    // still has a base or a waiting change).
+    const typeNames = syncedTypeNames();
+    const stillWaiting = waitingRecordKeys(await store.queue(), typeNames);
+    for (const key of recordKeysOfEntry(entry, typeNames)) {
+      if (stillWaiting.has(key)) continue;
+      const separator = key.indexOf(":");
+      const record = await store.getRecord(key.slice(0, separator), key.slice(separator + 1));
+      if (record && (record.base !== null || record.localOnly)) {
+        await store.putRecord({ ...record, base: null, localOnly: false });
+      }
+    }
+    if (result.response) {
+      await writeThrough(
+        { method: entry.method, url: entry.path },
+        { ok: true, status: 200, statusText: "OK", data: result.response },
+      );
+    } else if (entry.method === "DELETE") {
+      await writeThrough(
+        { method: entry.method, url: entry.path },
+        { ok: true, status: 204, statusText: "OK", data: undefined },
+      );
+    }
+    return "applied";
+  }
+
+  if (result.status === "conflict" || result.status === "could-not-apply") {
+    await store.addConflict({
+      queueSeq: entry.seq,
+      kind: result.status === "could-not-apply" ? "could-not-apply" : (result.conflict ?? "fields"),
+      recordType: entry.recordType,
+      recordId: entry.recordId,
+      mine: entry.body ?? null,
+      theirs: result.current ?? null,
+      base: entry.base ?? null,
+      merged: mergedResource(result.current, result.merged),
+      fields: result.conflictFields ?? [],
+      blocks: result.conflictBlocks,
+      reason: result.detail,
+    });
+    await store.setQueueStatus(entry.seq, "conflict");
+    return "conflict";
+  }
+
+  await store.setQueueStatus(entry.seq, "pending");
+  return "pending";
+}
+
+async function drain(): Promise<DrainResult> {
+  const outcome: DrainResult = { applied: 0, conflicts: 0, stoppedForLogin: false };
+  if (!isOfflineConfigured() || !getOfflineConfig().getUserId()) return outcome;
+
+  const store = await getOfflineStore();
+  const entries = await entriesToSend(store);
+  if (entries.length === 0) return outcome;
+
+  const session = await refreshSession();
+  if (session === "unreachable") return outcome;
+  if (session === "expired") return { ...outcome, stoppedForLogin: true };
+
+  setOfflineState({ draining: true });
+  const handled = new Set<number>();
+  try {
+    const packageId = packageIdFor(entries);
+    // Stored with the entries before sending: an unanswered package keeps its id for the resend.
+    await store.setQueuePackage(
+      entries.map((entry) => entry.seq),
+      packageId,
+    );
+    for (const entry of entries) await store.setQueueStatus(entry.seq, "sending");
+
+    // ONE request with every waiting change, whatever its size: never split (Carlo, 2026-11-01).
+    const endpoint = new EndpointCreator({ endpoint: Modules.OfflineChangeSet }).generate();
+    // During a reconnect attempt the session is still offline: this request goes to the network.
+    const release = allowWhileReconnecting(buildUrl(endpoint));
+    let response: Awaited<ReturnType<typeof JsonApiPost>>;
+    try {
+      response = await JsonApiPost({
+        classKey: Modules.OfflineChangeSet,
+        endpoint,
+        body: { id: packageId, changes: entries.map(toChange) },
+        language: currentLocale(),
+      });
+    } finally {
+      release();
+    }
+
+    if (!response.ok) {
+      if (response.response === 401) outcome.stoppedForLogin = true;
+      return outcome;
+    }
+
+    // The server answered for this package: every entry left in the queue leaves it.
+    await store.setQueuePackage(
+      entries.map((entry) => entry.seq),
+      null,
+    );
+
+    const results = new Map((response.data as OfflineChangeSet).results.map((result) => [result.seq, result]));
+    for (const entry of entries) {
+      const result = results.get(entry.seq);
+      const status = result ? await applyResult(store, entry, result) : "pending";
+      if (!result) await store.setQueueStatus(entry.seq, "pending");
+      handled.add(entry.seq);
+      if (status === "applied") outcome.applied++;
+      if (status === "conflict") outcome.conflicts++;
+    }
+    return outcome;
+  } catch (error) {
+    console.error("[offline] sending the waiting changes failed", error);
+    return outcome;
+  } finally {
+    // Nothing is dropped: every entry without an answer goes back to pending.
+    for (const entry of entries) {
+      if (!handled.has(entry.seq)) await store.setQueueStatus(entry.seq, "pending");
+    }
+    setOfflineState({ draining: false });
+    await refreshOfflineCounts(store);
+  }
+}
+
+let _inFlight: Promise<DrainResult> | undefined;
+
+/**
+ * Sends every waiting change of the unlocked root records in ONE `offline-change-sets` request,
+ * after renewing the sign-in. Applied entries are removed and their answer written to the
+ * device copy; conflicts become Conflict rows; waiting entries stay pending. A network error
+ * or an expired sign-in stops it and keeps every entry.
+ */
+export function drainQueue(): Promise<DrainResult> {
+  if (!_inFlight) {
+    _inFlight = drain().finally(() => {
+      _inFlight = undefined;
+    });
+  }
+  return _inFlight;
+}

package/src/offline/sync/known-roots.ts

@@ -0,0 +1,37 @@
+import { getOfflineConfig, getOfflineStore } from "../config";
+import { setOfflineState } from "../state";
+import type { DeviceStore } from "../store/DeviceStore";
+import { isRootLocked } from "../store/lifecycle";
+
+let _lastSyncRoots: string[] = [];
+
+/** Remembers the root records the last online `listSyncRoots()` returned. */
+export function rememberSyncRoots(ids: string[]): void {
+  _lastSyncRoots = [...ids];
+}
+
+/**
+ * Every root record the device knows of: its stored root records, the root records with waiting
+ * changes, and the last sync roots (a locked root record is never downloaded, so it may have
+ * no stored record).
+ */
+export async function knownRootIds(store: DeviceStore): Promise<string[]> {
+  const config = getOfflineConfig();
+  const ids = new Set<string>(_lastSyncRoots);
+  for (const record of await store.listRecords({ type: config.rootModule.name })) ids.add(record.id);
+  for (const entry of await store.queue()) ids.add(entry.rootId);
+  return [...ids].sort();
+}
+
+/** Recomputes `lockedRootIds` from the stored sync states, now. */
+export async function refreshLockedRoots(): Promise<void> {
+  const config = getOfflineConfig();
+  if (!config.getUserId()) return;
+  const store = await getOfflineStore();
+  const now = new Date();
+  const locked: string[] = [];
+  for (const id of await knownRootIds(store)) {
+    if (isRootLocked(await store.getSyncState(id), now)) locked.push(id);
+  }
+  setOfflineState({ lockedRootIds: locked });
+}

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

@@ -0,0 +1,34 @@
+import { AbstractApiData } from "../../../core/abstracts/AbstractApiData";
+import { JsonApiHydratedDataInterface } from "../../../core/interfaces/JsonApiHydratedDataInterface";
+import { Modules } from "../../../core/registry/ModuleRegistry";
+import { OfflineChangeResult, OfflineChangeSetInput, OfflineChangeSetInterface } from "./OfflineChangeSetInterface";
+
+/**
+ * The package of every waiting change the device sends in ONE request
+ * (`POST /offline-change-sets`). The answer carries one result per change.
+ */
+export class OfflineChangeSet extends AbstractApiData implements OfflineChangeSetInterface {
+  private _results?: OfflineChangeResult[];
+
+  get results(): OfflineChangeResult[] {
+    return this._results ?? [];
+  }
+
+  rehydrate(data: JsonApiHydratedDataInterface): this {
+    super.rehydrate(data);
+
+    this._results = data.jsonApi.attributes?.results ?? [];
+
+    return this;
+  }
+
+  createJsonApi(data: OfflineChangeSetInput) {
+    return {
+      data: {
+        type: Modules.OfflineChangeSet.name,
+        id: data.id,
+        attributes: { changes: data.changes },
+      },
+    };
+  }
+}