@stamprally/core 0.19.0 → 0.20.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/core v0.19.0
+# @stamprally/core v0.20.0
 
 Dependency-free domain models, immutable state transitions, storage adapters, browser detectors, and safe configuration parsers.
 
@@ -7,7 +7,7 @@ import { InMemoryStorage, StampRallyClient, type PublicRallyConfig } from "@stam
 
 const config: PublicRallyConfig = {
   id: "city-tour",
-  version: "0.19.0",
+  version: "0.20.0",
   title: "City Tour",
   spots: [{ id: "station", orderIndex: 0, name: "Central Station", conditions: [{ type: "passcode" }] }],
   rewards: [],
@@ -35,6 +35,33 @@ When no authenticated user is supplied, the client creates a persistent UUID v4
 `anonymousSessionId` and includes it in sync requests. Queue replay uses Web Locks
 when available and supports bounded exponential backoff through `retryOptions`.
 
+### v0.20.0 batch sync and storage capability
+
+An adapter can return `SyncProgressResponse` from `sync` when it sends queued
+operations to a server-side `syncProgress` endpoint. The adapter passes queued
+operations to its transport and maps the server request shape as needed:
+
+```ts
+const batchAdapter: SyncAdapter = {
+  sync: async ({ rallyId, userId, state, operations }) =>
+    postBatch({ rallyId, userId, state, operations }),
+};
+await client.sync(batchAdapter);
+```
+
+Each `SyncOperationResult`
+is `ACCEPTED`, `REJECTED_PERMANENT`, or `FAILED_RETRYABLE`. Accepted and permanent
+results are removed from the queue; permanent reasons are added to
+`rejectedHistory`, while retryable operations are kept for the next send. A
+permanent prerequisite failure does not prevent later independent operations from
+being evaluated.
+
+`client.queueCapability.multiTabSync` is `"supported_web_locks"` when the Web
+Locks API is available. Otherwise it is `"disabled_unsafe_environment"`:
+cross-tab automatic synchronization is disabled, the foreground tab must trigger
+sync explicitly, and a `storageCapabilityWarning` event is emitted. localStorage
+may still be used for durable queue data, but it is never used as a lock.
+
 `evaluateSpotStatus` derives `UNCLAIMED`, `CLAIMED`, `LOCKED`, or `VERIFYING`
 without mutating state. A spot with incomplete `prerequisites` is `LOCKED` and
 must not be verified by a client or viewer.

package/dist/index.cjs

@@ -1200,8 +1200,6 @@ function errorValue(value, fallbackCode) {
   if (typeof value === "string") return { code: fallbackCode, message: value };
   return { code: fallbackCode, message: "Offline operation was rejected." };
 }
-var syncLocks = /* @__PURE__ */ new Map();
-var SYNC_LOCK_TTL_MS = 3e4;
 var DEFAULT_RETRY_OPTIONS = {
   maxRetries: 0,
   initialIntervalMs: 250,
@@ -1228,9 +1226,7 @@ var OfflineQueue = class {
   #synchronizeInstances;
   #retryOptions;
   #instanceId = randomId();
-  #lockStorage;
-  #observedLocks = /* @__PURE__ */ new Map();
-  #warnedMemoryLock = false;
+  #warnedCapabilityMessages = /* @__PURE__ */ new Set();
   #capabilityWarningListener;
   #replayConfig;
   #storageListener;
@@ -1260,8 +1256,7 @@ var OfflineQueue = class {
       initialIntervalMs: Math.max(0, retryOptions.initialIntervalMs),
       backoffMultiplier: Math.max(1, retryOptions.backoffMultiplier)
     };
-    this.#lockStorage = options.storageLike ?? availableLocalStorage();
-    if (this.#synchronizeInstances) this.#subscribeToExternalChanges();
+    if (this.#synchronizeInstances && this.#hasWebLocks()) this.#subscribeToExternalChanges();
   }
   get syncState() {
     return this.#state;
@@ -1270,12 +1265,14 @@ var OfflineQueue = class {
     return this.#operations.length;
   }
   get queueCapability() {
-    return this.#queueCapability;
+    return {
+      storage: this.#queueCapability,
+      multiTabSync: this.#hasWebLocks() ? "supported_web_locks" : "disabled_unsafe_environment"
+    };
   }
   get storageCapability() {
     if (this.#queueCapability === "memory") return "memory";
-    const locks = globalThis.navigator?.locks;
-    return locks !== void 0 || this.#lockStorage !== null ? this.#queueCapability : "volatile_single_tab";
+    return this.#hasWebLocks() ? this.#queueCapability : "volatile_single_tab";
   }
   get isStoragePersistent() {
     return this.#queueCapability !== "memory";
@@ -1322,12 +1319,16 @@ var OfflineQueue = class {
       this.#queueCapability = "memory";
       this.#operations = [];
       this.#rejectedHistory = [];
-      this.#warnMemoryLock(
+      this.#warnCapability(
         `Offline queue persistence is unavailable; queued data can be lost after reload (${String(error)}).`
       );
     }
     if (this.#queueCapability === "memory")
-      this.#warnMemoryLock("Offline queue persistence is unavailable; queued data is memory-only.");
+      this.#warnCapability("Offline queue persistence is unavailable; queued data is memory-only.");
+    if (this.queueCapability.multiTabSync === "disabled_unsafe_environment")
+      this.#warnCapability(
+        "Web Locks is unavailable; automatic cross-tab synchronization is disabled. Sync must be triggered by the foreground tab."
+      );
     this.#loaded = true;
   }
   /** Releases browser listeners when the queue is no longer used. */
@@ -1338,7 +1339,6 @@ var OfflineQueue = class {
     this.#storageListener = void 0;
     this.#channel?.close();
     this.#channel = null;
-    this.#releaseSyncLock();
   }
   /** Selects a rally/user queue scope and loads its pending operations. */
   async setScope(rallyId, userId) {
@@ -1450,6 +1450,12 @@ var OfflineQueue = class {
   async retrySync(sender = this.#sender) {
     return this.sync(sender);
   }
+  /** Applies a server-side batch response while preserving retryable operations. */
+  async applySyncProgress(response) {
+    await this.initialize();
+    for (const result of response.results)
+      await this.#applySyncOperationResult(result, response.currentState);
+  }
   async #run(sender) {
     const locks = globalThis.navigator?.locks;
     if (locks !== void 0 && typeof locks.request === "function") {
@@ -1466,7 +1472,7 @@ var OfflineQueue = class {
               return false;
             }
             callbackStarted = true;
-            await this.#runWithStorageLock(sender);
+            await this.#runSingleTab(sender);
             return true;
           }
         );
@@ -1476,22 +1482,12 @@ var OfflineQueue = class {
         if (callbackStarted) throw error;
       }
     }
-    if (this.storageCapability === "volatile_single_tab")
-      this.#warnMemoryLock(
-        "No cross-tab storage lock is available; offline sync is single-tab only."
-      );
-    await this.#runWithStorageLock(sender);
+    await this.#runSingleTab(sender);
   }
-  async #runWithStorageLock(sender) {
+  async #runSingleTab(sender) {
     this.#state = "syncing";
     this.#error = null;
     this.#changeListener?.();
-    if (!this.#acquireSyncLock()) {
-      await this.#reloadFromStorage();
-      this.#state = "idle";
-      this.#changeListener?.();
-      return;
-    }
     try {
       while (this.#operations.length > 0) {
         const operation = this.#operations[0];
@@ -1563,8 +1559,6 @@ var OfflineQueue = class {
       this.#error = cause instanceof Error ? cause : new Error(String(cause));
       this.#changeListener?.();
       throw this.#error;
-    } finally {
-      this.#releaseSyncLock();
     }
   }
   async #updateOperationStatus(status, attempts) {
@@ -1574,6 +1568,59 @@ var OfflineQueue = class {
     await this.#storage.save(this.#storageKey(), this.#operations);
     this.#announceChange();
   }
+  async #applySyncOperationResult(result, currentState) {
+    const operationIndex = this.#operations.findIndex(
+      (operation2) => offlineOperationId(operation2) === result.operationId
+    );
+    const operation = operationIndex < 0 ? void 0 : this.#operations[operationIndex];
+    if (operation === void 0) return;
+    if (result.status === "FAILED_RETRYABLE") {
+      const attempts = (operation.attempts ?? 0) + 1;
+      this.#operations = [
+        ...this.#operations.slice(0, operationIndex),
+        { ...operation, status: "FAILED_RETRYABLE", attempts },
+        ...this.#operations.slice(operationIndex + 1)
+      ];
+      await this.#storage.save(this.#storageKey(), this.#operations);
+      this.#announceChange();
+      await this.#syncResultListener?.({
+        operation,
+        status: "RETRYABLE_ERROR",
+        error: { code: "FAILED_RETRYABLE", message: result.error }
+      });
+      return;
+    }
+    this.#operations = [
+      ...this.#operations.slice(0, operationIndex),
+      ...this.#operations.slice(operationIndex + 1)
+    ];
+    if (result.status === "REJECTED_PERMANENT") {
+      const attempts = (operation.attempts ?? 0) + 1;
+      const error = {
+        code: result.errorCode,
+        message: result.reason
+      };
+      this.#rejectedHistory = [
+        ...this.#rejectedHistory,
+        {
+          operation: { ...operation, status: "REJECTED_PERMANENT", attempts },
+          reason: error,
+          errorCode: result.errorCode,
+          rejectedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          attempts
+        }
+      ];
+      await this.#saveRejectedHistory();
+    }
+    await this.#storage.save(this.#storageKey(), this.#operations);
+    this.#announceChange();
+    await this.#syncResultListener?.({
+      operation,
+      status: result.status,
+      state: currentState,
+      ...result.status === "REJECTED_PERMANENT" ? { error: { code: result.errorCode, message: result.reason } } : {}
+    });
+  }
   async #rejectFailedPrerequisite(operation) {
     if (operation.kind !== "checkIn" || this.#replayConfig === void 0) return false;
     const spot2 = this.#replayConfig.spots.find(
@@ -1627,20 +1674,6 @@ var OfflineQueue = class {
       try {
         this.#channel = new Channel("stamprally:queue-sync");
         this.#channel.addEventListener("message", (event) => {
-          if (typeof event.data === "object" && event.data !== null) {
-            const data = event.data;
-            if (data.type === "lock" && data.lockKey === this.#lockKey()) {
-              this.#observedLocks.set(data.lockKey, {
-                owner: typeof data.owner === "string" ? data.owner : "unknown",
-                expiresAt: typeof data.expiresAt === "number" ? data.expiresAt : 0
-              });
-              return;
-            }
-            if (data.type === "unlock" && data.lockKey === this.#lockKey()) {
-              this.#observedLocks.delete(data.lockKey);
-              return;
-            }
-          }
           if (typeof event.data === "object" && event.data !== null && "key" in event.data && event.data.key === this.#storageKey())
             void this.#reloadFromStorage();
         });
@@ -1667,57 +1700,6 @@ var OfflineQueue = class {
     } catch {
     }
   }
-  #lockKey() {
-    return `${this.#storageKey()}:sync-lock`;
-  }
-  #acquireSyncLock() {
-    const key = this.#lockKey();
-    const now = Date.now();
-    const local = syncLocks.get(key);
-    if (local !== void 0 && local.expiresAt > now && local.owner !== this.#instanceId)
-      return false;
-    const observed = this.#observedLocks.get(key);
-    if (observed !== void 0 && observed.expiresAt > now && observed.owner !== this.#instanceId)
-      return false;
-    if (this.#lockStorage !== null) {
-      try {
-        const existing = this.#lockStorage.getItem(key);
-        if (existing !== null) {
-          const parsed = JSON.parse(existing);
-          if (typeof parsed === "object" && parsed !== null && typeof parsed.expiresAt === "number" && parsed.expiresAt > now && parsed.owner !== this.#instanceId)
-            return false;
-        }
-        this.#lockStorage.setItem(
-          key,
-          JSON.stringify({ owner: this.#instanceId, expiresAt: now + SYNC_LOCK_TTL_MS })
-        );
-        this.#channel?.postMessage({
-          type: "lock",
-          lockKey: key,
-          owner: this.#instanceId,
-          expiresAt: now + SYNC_LOCK_TTL_MS
-        });
-      } catch {
-        this.#warnMemoryLock("Persistent lock access failed; offline sync is single-tab only.");
-      }
-    }
-    syncLocks.set(key, { owner: this.#instanceId, expiresAt: now + SYNC_LOCK_TTL_MS });
-    return true;
-  }
-  #releaseSyncLock() {
-    const key = this.#lockKey();
-    const current = syncLocks.get(key);
-    if (current?.owner === this.#instanceId) syncLocks.delete(key);
-    if (this.#lockStorage !== null) {
-      try {
-        const value = this.#lockStorage.getItem(key);
-        if (value !== null && JSON.parse(value).owner === this.#instanceId)
-          this.#lockStorage.removeItem?.(key);
-        this.#channel?.postMessage({ type: "unlock", lockKey: key, owner: this.#instanceId });
-      } catch {
-      }
-    }
-  }
   #storageKey() {
     if (this.#configuredKey !== void 0) return this.#configuredKey;
     return `stamprally:queue:${this.#rallyId ?? "unscoped"}:${this.#userId ?? "anonymous"}`;
@@ -1740,17 +1722,22 @@ var OfflineQueue = class {
   async #saveRejectedHistory() {
     await this.#storage.saveRejectedHistory?.(this.#storageKey(), this.#rejectedHistory);
   }
-  #warnMemoryLock(message) {
-    if (this.#warnedMemoryLock) return;
-    this.#warnedMemoryLock = true;
+  #warnCapability(message) {
+    if (this.#warnedCapabilityMessages.has(message)) return;
+    this.#warnedCapabilityMessages.add(message);
     console.warn(`[@stamprally/core] ${message}`);
     this.#capabilityWarningListener?.({
       type: "STORAGE_CAPABILITY_WARNING",
       storageCapability: this.storageCapability === "memory" ? "memory" : "volatile_single_tab",
+      multiTabSync: "disabled_unsafe_environment",
       isStoragePersistent: this.isStoragePersistent,
       message
     });
   }
+  #hasWebLocks() {
+    const locks = globalThis.navigator?.locks;
+    return locks !== void 0 && typeof locks.request === "function";
+  }
 };
 function normalizeOperation(operation) {
   const status = operation.status;
@@ -1942,6 +1929,9 @@ function applyOptimisticRewardClaim(state, rewardId, reward2, now) {
 function errorMessage(error, fallback) {
   return error !== void 0 && "message" in error && typeof error.message === "string" ? error.message : fallback;
 }
+function isSyncProgressResponse(value) {
+  return typeof value === "object" && value !== null && "results" in value && Array.isArray(value.results) && "currentState" in value && "syncTimestamp" in value;
+}
 var StampRallyClient = class {
   #listeners = /* @__PURE__ */ new Set();
   #eventListeners = /* @__PURE__ */ new Set();
@@ -1999,7 +1989,10 @@ var StampRallyClient = class {
     return this.#syncRevision;
   }
   get queueCapability() {
-    return this.#offlineQueue?.queueCapability ?? "custom";
+    return this.#offlineQueue?.queueCapability ?? {
+      storage: "custom",
+      multiTabSync: "disabled_unsafe_environment"
+    };
   }
   get storageCapability() {
     return this.#offlineQueue?.storageCapability ?? "custom";
@@ -2216,7 +2209,9 @@ var StampRallyClient = class {
       this.#syncMetrics = { processed: 0, failed: 0 };
       try {
         const current = await this.initialize();
-        if (this.#offlineQueue !== void 0 && adapter !== void 0) {
+        const queuedOperations = this.#offlineQueue?.operations ?? [];
+        const hasPerOperationAdapters = adapter?.checkIn !== void 0 || adapter?.claimReward !== void 0;
+        if (this.#offlineQueue !== void 0 && adapter !== void 0 && hasPerOperationAdapters) {
           await this.#offlineQueue.sync(async (operation) => {
             if (operation.kind === "checkIn") {
               if (adapter.checkIn === void 0)
@@ -2233,12 +2228,16 @@ var StampRallyClient = class {
           return;
         }
         const localState = this.#state ?? current;
-        const serverState = await adapter.sync({
+        const syncResult = await adapter.sync({
           rallyId: this.#config.id,
           userId: this.#userId,
           state: localState,
-          ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {}
+          ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {},
+          ...this.#offlineQueue !== void 0 && !hasPerOperationAdapters && queuedOperations.length > 0 ? { operations: queuedOperations } : {}
         });
+        const progress = isSyncProgressResponse(syncResult) ? syncResult : void 0;
+        if (progress !== void 0) await this.#offlineQueue?.applySyncProgress(progress);
+        const serverState = isSyncProgressResponse(syncResult) ? syncResult.currentState : syncResult;
         const resolved = rebuildUserStateFromLog(
           serverState,
           this.#offlineQueue?.operations ?? [],