@stamprally/core 0.20.1 → 0.22.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/core v0.20.1
+# @stamprally/core v0.22.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.20.1",
+  version: "0.22.0",
   title: "City Tour",
   spots: [{ id: "station", orderIndex: 0, name: "Central Station", conditions: [{ type: "passcode" }] }],
   rewards: [],
@@ -23,7 +23,7 @@ The browser detectors `getCurrentGeoContext`, `readNfcContext`, and `readQrConte
 
 `InMemoryStorage`, `LocalStorageAdapter`, and `IndexedDBAdapter` implement `StampStorage`. `updateLocalizedField` updates one locale without dropping existing translations.
 
-## v0.17.0 offline synchronization
+## v0.22.0 offline synchronization
 
 Configure `OfflineQueue` with `rallyId` and `userId` to persist pending work under
 `stamprally:queue:<rallyId>:<userId-or-anonymous>`. `switchUser` loads the other
@@ -35,7 +35,7 @@ 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.1 batch sync and storage capability
+### v0.22.0 batch sync, queue capability, 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
@@ -56,12 +56,19 @@ results are removed from the queue; permanent reasons are added to
 permanent prerequisite failure does not prevent later independent operations from
 being evaluated.
 
-`client.queueCapability.multiTabSync` is `"supported_web_locks"` when the Web
+`client.queueCapabilities.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.
 
+`client.queueCapability` remains the legacy storage string (`"indexeddb"`,
+`"localstorage"`, `"memory"`, `"custom"`, or `"disabled"`) so string comparisons
+such as `client.queueCapability === "indexeddb"` remain valid. New code can use
+`client.queueCapabilities`, which provides `storageType`, `isPersistent`, and
+`multiTabSync`. An omitted or `false` `offlineQueue` is reported as
+`disabled` with `storageType: "none"`.
+
 `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

@@ -457,6 +457,12 @@ async function readQrContext(videoElement, options = {}) {
 }
 
 // src/engine/transition.ts
+function sortOperationsDeterministically(operations) {
+  return [...operations].sort((left, right) => {
+    if (left.timestamp !== right.timestamp) return left.timestamp - right.timestamp;
+    return left.operationId.localeCompare(right.operationId);
+  });
+}
 function reconcileRewardStates(rewards, currentStates, acquiredStampCount, now) {
   const states = new Map(currentStates.map((state) => [state.rewardId, state]));
   return rewards.map((reward2) => {
@@ -1007,6 +1013,11 @@ var IndexedDBAdapter = class {
 };
 
 // src/client/offlineQueue.ts
+function getLegacyQueueCapability(capability) {
+  if (typeof capability === "string")
+    return capability === "memory" || capability === "disabled" ? "volatile" : "persistent";
+  return capability.isPersistent ? "persistent" : "volatile";
+}
 function rollbackOptimisticOperation(state, operation) {
   const previous = operation.request.state;
   if (operation.kind === "checkIn") {
@@ -1265,8 +1276,14 @@ var OfflineQueue = class {
     return this.#operations.length;
   }
   get queueCapability() {
+    return this.#queueCapability;
+  }
+  get queueCapabilities() {
+    const storageType = this.#queueCapability;
+    const isPersistent = storageType !== "memory";
     return {
-      storage: this.#queueCapability,
+      storageType,
+      isPersistent,
       multiTabSync: this.#hasWebLocks() ? "supported_web_locks" : "disabled_unsafe_environment"
     };
   }
@@ -1325,7 +1342,7 @@ var OfflineQueue = class {
     }
     if (this.#queueCapability === "memory")
       this.#warnCapability("Offline queue persistence is unavailable; queued data is memory-only.");
-    if (this.queueCapability.multiTabSync === "disabled_unsafe_environment")
+    if (this.queueCapabilities.multiTabSync === "disabled_unsafe_environment")
       this.#warnCapability(
         "Web Locks is unavailable; automatic cross-tab synchronization is disabled. Sync must be triggered by the foreground tab."
       );
@@ -1763,8 +1780,11 @@ function isReplayable(operation) {
   return operation.status === void 0 || operation.status === "ACCEPTED" || operation.status === "PENDING" || operation.status === "IN_FLIGHT" || operation.status === "FAILED_RETRYABLE";
 }
 function operationId(operation) {
-  const identity = operation.request.userId ?? operation.request.anonymousSessionId ?? "anonymous";
-  return `${operation.kind}:${operation.request.rallyId}:${identity}:${operation.request.idempotencyKey}`;
+  return offlineOperationId(operation);
+}
+function operationTimestamp(operation) {
+  const parsed = Date.parse(operation.request.now);
+  return Number.isFinite(parsed) ? parsed : Number.MAX_SAFE_INTEGER;
 }
 function applyInventoryDelta(state, previous, optimistic) {
   const previousInventory = previous.inventory;
@@ -1840,12 +1860,19 @@ function rebuildUserStateFromLog(baselineOrOptions, operationsArgument, configAr
 function rebuildUserStateLog(baseline, operations, config) {
   let state = cloneState(baseline);
   const rejectedOperationIds = [];
+  const sortedOperations = sortOperationsDeterministically(
+    operations.map((operation) => ({
+      operation,
+      operationId: offlineOperationId(operation),
+      timestamp: operationTimestamp(operation)
+    }))
+  ).map(({ operation }) => operation);
   const rejectedCheckIns = new Set(
-    operations.filter(
+    sortedOperations.filter(
       (operation) => operation.status === "REJECTED_PERMANENT" && operation.kind === "checkIn"
     ).map((operation) => operation.kind === "checkIn" ? operation.request.spotId : void 0).filter((spotId) => spotId !== void 0)
   );
-  for (const operation of operations) {
+  for (const operation of sortedOperations) {
     if (operation.status === "REJECTED_PERMANENT") {
       if (operation.kind === "checkIn") rejectedCheckIns.add(operation.request.spotId);
       continue;
@@ -1953,7 +1980,7 @@ var StampRallyClient = class {
     this.#storage = this.#options.storage ?? new InMemoryStorage();
     this.#anonymousSessionId = this.#options.anonymousSessionId ?? createAnonymousSessionId();
     this.#userId = this.#options.userId ?? this.#anonymousSessionId;
-    this.#offlineQueue = this.#options.offlineQueue;
+    this.#offlineQueue = this.#options.offlineQueue === false ? void 0 : this.#options.offlineQueue;
     this.#offlineQueue?.setReplayConfig(config);
     this.#offlineQueue?.setSyncResultListener((event) => this.#handleOfflineSyncResult(event));
     this.#offlineQueue?.setCapabilityWarningListener(
@@ -1989,16 +2016,20 @@ var StampRallyClient = class {
     return this.#syncRevision;
   }
   get queueCapability() {
-    return this.#offlineQueue?.queueCapability ?? {
-      storage: "custom",
+    return this.#offlineQueue?.queueCapability ?? "disabled";
+  }
+  get queueCapabilities() {
+    return this.#offlineQueue?.queueCapabilities ?? {
+      storageType: "none",
+      isPersistent: false,
       multiTabSync: "disabled_unsafe_environment"
     };
   }
   get storageCapability() {
-    return this.#offlineQueue?.storageCapability ?? "custom";
+    return this.#offlineQueue?.storageCapability ?? "disabled";
   }
   get isStoragePersistent() {
-    return this.#offlineQueue?.isStoragePersistent ?? true;
+    return this.#offlineQueue?.isStoragePersistent ?? false;
   }
   discardRejected(operationId2) {
     return this.#offlineQueue?.discardRejected(operationId2) ?? Promise.resolve(false);
@@ -3481,6 +3512,7 @@ exports.evaluateConditionDetailed = evaluateConditionDetailed;
 exports.evaluateSpotStatus = evaluateSpotStatus;
 exports.exportProgressToken = exportProgressToken;
 exports.getCurrentGeoContext = getCurrentGeoContext;
+exports.getLegacyQueueCapability = getLegacyQueueCapability;
 exports.getOrderedSpots = getOrderedSpots;
 exports.getSpotStatus = getSpotStatus;
 exports.importProgressToken = importProgressToken;
@@ -3507,6 +3539,7 @@ exports.rollbackOptimisticOperation = rollbackOptimisticOperation;
 exports.safeParseAdminConfig = safeParseAdminConfig;
 exports.safeParsePublicConfig = safeParsePublicConfig;
 exports.sanitizeAdminConfig = sanitizeAdminConfig;
+exports.sortOperationsDeterministically = sortOperationsDeterministically;
 exports.storageKey = storageKey;
 exports.toLocalizedString = toLocalizedString;
 exports.toPublicConfig = toPublicConfig;