@stamprally/server 0.14.0 → 0.15.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/server
+# @stamprally/server v0.15.0
 
 Web Standard `Request` / `Response` handlers for server-authoritative check-ins and reward claims.
 
@@ -16,8 +16,15 @@ const response = await server.handle(request);
 HTTP check-in and reward-claim responses include an operation status: `ACCEPTED`,
 `REJECTED_PERMANENT`, or `RETRYABLE_ERROR`. Clients can pass the response directly
 to an `OfflineQueue` sender; the queue removes accepted/permanent operations and
-retains retryable failures. The SQL transaction contract and all-or-nothing example
-are exported as `executeClaimRewardTransaction` from `src/examples/transaction.ts`.
+retains retryable failures. The SQL transaction contract and all-or-nothing examples
+for check-ins and claims are exported as `executeCheckInTransaction` and
+`executeClaimRewardTransaction` from `src/examples/transaction.ts`. Redis adapters
+can use the exported `executeRedisTransaction` helper to wrap a MULTI/EXEC batch.
+
+Configure `anonymousPolicy: "session_scoped"` to use the UUID v4 from the
+`X-Anonymous-Session-Id` header as the anonymous identity, or `"reject"` to return
+HTTP 401 when no authenticated identity is present. Request validation failures use
+HTTP 400 with `{ error: "VALIDATION_FAILED", details: [...] }`.
 
 Hono can mount the handler directly because it accepts the same Web Standard request and response types.
 

package/dist/index.cjs

@@ -15,6 +15,10 @@ async function executeClaimRewardTransaction(database, store, params, mutation)
         return { success: false, error: next.error };
       }
       if (next.nextStock !== null) await store.writeStock(transaction, params, next.nextStock);
+      if (next.nextSecondaryStock !== void 0 && store.writeSecondaryStock !== void 0) {
+        if (next.nextSecondaryStock !== null)
+          await store.writeSecondaryStock(transaction, params, next.nextSecondaryStock);
+      }
       await store.writeUserState(transaction, params, next.nextUserState);
       await store.writeClaimRecord(transaction, params, next.nextUserState);
       await store.writeAudit(transaction, next.auditLog);
@@ -22,8 +26,41 @@ async function executeClaimRewardTransaction(database, store, params, mutation)
         await store.writeIdempotency(transaction, params, next.result);
       return { success: true };
     });
-  } catch (error2) {
-    return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function executeCheckInTransaction(database, store, params, mutation, current) {
+  try {
+    return await database.transaction(async (transaction) => {
+      const userState = current ?? (store.readUserState === void 0 ? (() => {
+        throw new Error("A current user state or readUserState implementation is required.");
+      })() : await store.readUserState(transaction, params));
+      const next = mutation({ userState });
+      if (next.error !== void 0) {
+        await store.writeAudit(transaction, next.auditLog);
+        if (params.idempotencyKey !== void 0 && next.result !== void 0)
+          await store.writeIdempotency(transaction, params, next.result);
+        return { success: false, error: next.error };
+      }
+      await store.writeUserState(transaction, params, next.nextUserState);
+      await store.writeAudit(transaction, next.auditLog);
+      if (params.idempotencyKey !== void 0 && next.result !== void 0)
+        await store.writeIdempotency(transaction, params, next.result);
+      return { success: true };
+    });
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
+  }
+}
+async function executeRedisTransaction(redis, queue) {
+  try {
+    const multi = redis.multi();
+    queue(multi);
+    const result = await redis.exec(multi);
+    return result === null ? { success: false, error: "Redis transaction was aborted." } : { success: true };
+  } catch (error) {
+    return { success: false, error: error instanceof Error ? error.message : String(error) };
   }
 }
 
@@ -91,8 +128,14 @@ var InMemoryServerPersistenceAdapter = class {
         const userState = await this.getUserState(params.rallyId, params.userId) ?? params.initialUserState;
         if (userState === void 0)
           return { success: false, error: "A user state is required for this transaction." };
+        const storedStock = await this.getRewardStock(
+          params.rallyId,
+          params.stockKey ?? params.rewardId
+        );
+        const storedSecondaryStock = params.secondaryStockKey === void 0 ? null : await this.getRewardStock(params.rallyId, params.secondaryStockKey);
         const mutationResult = mutation({
-          stock: await this.getRewardStock(params.rallyId, params.rewardId),
+          stock: storedStock ?? params.initialStock ?? null,
+          secondaryStock: storedSecondaryStock ?? params.initialSecondaryStock ?? null,
           claimCount: await this.getUserClaimCount(params.rallyId, params.userId, params.rewardId),
           userState
         });
@@ -108,16 +151,45 @@ var InMemoryServerPersistenceAdapter = class {
             );
           return { success: false, error: mutationResult.error };
         }
-        const currentStock = await this.getRewardStock(params.rallyId, params.rewardId);
-        if (currentStock !== null && (mutationResult.nextStock === null || mutationResult.nextStock < 0))
+        const currentStock = await this.getRewardStock(
+          params.rallyId,
+          params.stockKey ?? params.rewardId
+        );
+        const effectiveStock = currentStock ?? params.initialStock ?? null;
+        if (currentStock === null && params.initialStock !== void 0 && params.initialStock !== null)
+          this.#stocks.set(
+            this.#stockKey(params.rallyId, params.stockKey ?? params.rewardId),
+            params.initialStock
+          );
+        const currentSecondaryStock = params.secondaryStockKey === void 0 ? null : await this.getRewardStock(params.rallyId, params.secondaryStockKey);
+        const effectiveSecondaryStock = currentSecondaryStock ?? params.initialSecondaryStock ?? null;
+        if (currentSecondaryStock === null && params.secondaryStockKey !== void 0 && params.initialSecondaryStock !== void 0 && params.initialSecondaryStock !== null)
+          this.#stocks.set(
+            this.#stockKey(params.rallyId, params.secondaryStockKey),
+            params.initialSecondaryStock
+          );
+        if (effectiveStock !== null && (mutationResult.nextStock === null || mutationResult.nextStock < 0))
           throw new Error("The transaction produced an invalid stock value.");
-        if (currentStock === null && mutationResult.nextStock !== null)
+        if (effectiveStock === null && mutationResult.nextStock !== null)
           throw new Error("The transaction changed an unlimited stock to a limited stock.");
         if (mutationResult.nextStock !== null)
           this.#stocks.set(
-            this.#stockKey(params.rallyId, params.rewardId),
+            this.#stockKey(params.rallyId, params.stockKey ?? params.rewardId),
             mutationResult.nextStock
           );
+        if (params.secondaryStockKey !== void 0 && mutationResult.nextSecondaryStock !== void 0) {
+          if (effectiveSecondaryStock !== null && (mutationResult.nextSecondaryStock === null || mutationResult.nextSecondaryStock < 0))
+            throw new Error("The transaction produced an invalid secondary stock value.");
+          if (effectiveSecondaryStock === null && mutationResult.nextSecondaryStock !== null)
+            throw new Error(
+              "The transaction changed an unlimited secondary stock to a limited stock."
+            );
+          if (mutationResult.nextSecondaryStock !== null)
+            this.#stocks.set(
+              this.#stockKey(params.rallyId, params.secondaryStockKey),
+              mutationResult.nextSecondaryStock
+            );
+        }
         await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
         const reward = mutationResult.nextUserState.rewards.find(
           (item) => item.rewardId === params.rewardId
@@ -140,8 +212,8 @@ var InMemoryServerPersistenceAdapter = class {
           );
         return { success: true };
       });
-    } catch (error2) {
-      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
   async executeCheckInTransaction(params, mutation) {
@@ -173,8 +245,8 @@ var InMemoryServerPersistenceAdapter = class {
           );
         return { success: true };
       });
-    } catch (error2) {
-      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
   async rollbackUserState(rallyId, userId, previousState) {
@@ -260,7 +332,7 @@ var InMemoryServerPersistenceAdapter = class {
     };
     try {
       return await operation(this);
-    } catch (error2) {
+    } catch (error) {
       this.#stocks.clear();
       for (const [key, value] of snapshot.stocks) this.#stocks.set(key, value);
       this.#idempotent.clear();
@@ -272,14 +344,14 @@ var InMemoryServerPersistenceAdapter = class {
       for (const [key, value] of snapshot.claims) this.#claims.set(key, value);
       this.#claimRecords.splice(0, this.#claimRecords.length, ...snapshot.claimRecords);
       this.#auditLogs.splice(0, this.#auditLogs.length, ...snapshot.auditLogs);
-      throw error2;
+      throw error;
     }
   }
 };
 
 // src/security.ts
-function error(path, message) {
-  return { success: false, errors: [{ path, message, code: "invalid_request" }] };
+function errors(...items) {
+  return { success: false, errors: items };
 }
 function record(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -287,46 +359,125 @@ function record(value) {
 function nonEmpty(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
-function context(value) {
-  if (!record(value) || typeof value.type !== "string") return false;
-  if (value.type === "qr") return nonEmpty(value.token);
-  if (value.type === "passcode") return nonEmpty(value.code);
-  if (value.type === "nfc") return nonEmpty(value.tagId);
-  if (value.type === "custom") return "value" in value;
-  return value.type === "gps" && typeof value.latitude === "number" && Number.isFinite(value.latitude) && typeof value.longitude === "number" && Number.isFinite(value.longitude);
+function contextErrors(value) {
+  if (!record(value) || typeof value.type !== "string")
+    return [
+      {
+        path: "proof",
+        message: "proof is not a valid verification context.",
+        code: "INVALID_TYPE"
+      }
+    ];
+  if (value.type === "qr" && !nonEmpty(value.token))
+    return [
+      { path: "proof.token", message: "token must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "passcode" && !nonEmpty(value.code))
+    return [
+      { path: "proof.code", message: "code must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "nfc" && !nonEmpty(value.tagId))
+    return [
+      { path: "proof.tagId", message: "tagId must be a non-empty string.", code: "INVALID_TYPE" }
+    ];
+  if (value.type === "custom")
+    return "value" in value ? [] : [{ path: "proof.value", message: "value is required.", code: "REQUIRED" }];
+  if (value.type === "qr" || value.type === "passcode" || value.type === "nfc") return [];
+  if (value.type !== "gps")
+    return [{ path: "proof.type", message: "Unknown verification type.", code: "INVALID_ENUM" }];
+  const result = [];
+  if (typeof value.latitude !== "number" || !Number.isFinite(value.latitude))
+    result.push({
+      path: "proof.latitude",
+      message: "Latitude must be a finite number.",
+      code: "INVALID_TYPE"
+    });
+  else if (value.latitude < -90 || value.latitude > 90)
+    result.push({
+      path: "proof.latitude",
+      message: "Latitude must be between -90 and 90.",
+      code: "INVALID_RANGE"
+    });
+  if (typeof value.longitude !== "number" || !Number.isFinite(value.longitude))
+    result.push({
+      path: "proof.longitude",
+      message: "Longitude must be a finite number.",
+      code: "INVALID_TYPE"
+    });
+  else if (value.longitude < -180 || value.longitude > 180)
+    result.push({
+      path: "proof.longitude",
+      message: "Longitude must be between -180 and 180.",
+      code: "INVALID_RANGE"
+    });
+  if ("radiusMeters" in value && (typeof value.radiusMeters !== "number" || !Number.isFinite(value.radiusMeters) || value.radiusMeters <= 0))
+    result.push({
+      path: "proof.radiusMeters",
+      message: "Radius must be greater than zero.",
+      code: "INVALID_RANGE"
+    });
+  return result;
+}
+function dateInput(value) {
+  if (typeof value === "number") return Number.isInteger(value) && value > 0;
+  if (typeof value !== "string" || value.trim() === "") return false;
+  return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?(?:Z|[+-]\d{2}:?\d{2})$/.test(value) && !Number.isNaN(Date.parse(value));
 }
-function common(value, fields) {
-  if (!record(value)) return false;
-  return fields.every((field) => nonEmpty(value[field]));
+function requiredErrors(value, fields) {
+  if (record(value) && fields.every((field) => nonEmpty(value[field]))) return [];
+  return fields.filter((field) => !record(value) || !nonEmpty(value[field])).map((field) => ({
+    path: field,
+    message: `${field} must be a non-empty string.`,
+    code: "REQUIRED"
+  }));
 }
 function validateCheckInRequest(value) {
-  if (!common(value, ["rallyId", "spotId", "idempotencyKey"]))
-    return error("$", "rallyId, spotId, and idempotencyKey must be non-empty strings.");
-  if (!context(value.context))
-    return error("context", "context is not a valid verification context.");
+  const required = requiredErrors(value, ["rallyId", "spotId", "idempotencyKey"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
+  const proof = contextErrors(value.context);
+  if (proof.length > 0) return errors(...proof);
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
-  if (value.now !== void 0 && !nonEmpty(value.now))
-    return error("now", "now must be non-empty when provided.");
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.now !== void 0 && !dateInput(value.now))
+    return errors({
+      path: "now",
+      message: "now must be an ISO 8601 date or positive timestamp.",
+      code: "INVALID_DATE"
+    });
   return { success: true, data: value };
 }
 function validateClaimRewardRequest(value) {
-  if (!common(value, ["rallyId", "rewardId", "idempotencyKey"]))
-    return error("$", "rallyId, rewardId, and idempotencyKey must be non-empty strings.");
+  const required = requiredErrors(value, ["rallyId", "rewardId", "idempotencyKey"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
   if (value.staffPasscode !== void 0 && !nonEmpty(value.staffPasscode))
-    return error("staffPasscode", "staffPasscode must be non-empty.");
+    return errors({
+      path: "staffPasscode",
+      message: "staffPasscode must be non-empty.",
+      code: "INVALID_TYPE"
+    });
   if (value.staffId !== void 0 && !nonEmpty(value.staffId))
-    return error("staffId", "staffId must be non-empty.");
+    return errors({ path: "staffId", message: "staffId must be non-empty.", code: "INVALID_TYPE" });
   if (value.now !== void 0 && !nonEmpty(value.now))
-    return error("now", "now must be non-empty when provided.");
+    return errors({
+      path: "now",
+      message: "now must be an ISO 8601 date or positive timestamp.",
+      code: "INVALID_DATE"
+    });
   return { success: true, data: value };
 }
 function validateSyncRequest(value) {
-  if (!common(value, ["rallyId"])) return error("rallyId", "rallyId must be a non-empty string.");
+  const required = requiredErrors(value, ["rallyId"]);
+  if (required.length > 0) return errors(...required);
+  if (!record(value))
+    return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
-    return error("userId", "userId must be non-empty.");
+    return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
   return { success: true, data: value };
 }
 function json(body, status = 200) {
@@ -338,6 +489,9 @@ function json(body, status = 200) {
 function isObject(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isUuidV4(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
 function requestId(prefix) {
   return `${prefix}-${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
 }
@@ -348,6 +502,15 @@ function timestampMillis(timestamp) {
   const value = Date.parse(timestamp);
   return Number.isFinite(value) ? value : Date.now();
 }
+function validationResponse(errors2) {
+  return json(
+    {
+      error: "VALIDATION_FAILED",
+      details: errors2.map(({ path, message, code }) => ({ path, message, code }))
+    },
+    400
+  );
+}
 function initialState(config, userId, timestamp) {
   return {
     rallyId: config.id,
@@ -357,16 +520,37 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
-function getProof(context2) {
-  return context2.type === "qr" ? context2.token : context2.type === "passcode" ? context2.code : context2.type === "gps" ? { latitude: context2.latitude, longitude: context2.longitude } : context2.type === "nfc" ? context2.tagId : context2.value;
+function rewardStock(config, rewardId, stockLimit) {
+  const configured = config.inventory?.[rewardId];
+  if (stockLimit === void 0) return configured ?? null;
+  if (configured === void 0) return stockLimit;
+  return Math.min(stockLimit, configured);
+}
+function sharedStock(config) {
+  return config.inventory?.sharedStock ?? config.inventory?.global ?? null;
+}
+function inventoryPlan(config, rewardId, stockLimit) {
+  const individual = rewardStock(config, rewardId, stockLimit);
+  const shared = sharedStock(config);
+  if (config.inventoryMode === "shared" && shared !== null) {
+    return {
+      primaryKey: "__shared__",
+      primaryInitial: shared,
+      ...individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
+    };
+  }
+  return { primaryKey: rewardId, primaryInitial: individual };
+}
+function getProof(context) {
+  return context.type === "qr" ? context.token : context.type === "passcode" ? context.code : context.type === "gps" ? { latitude: context.latitude, longitude: context.longitude } : context.type === "nfc" ? context.tagId : context.value;
 }
-async function evaluate(condition, context2, validator, base) {
-  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context2).ok;
+async function evaluate(condition, context, validator, base) {
+  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context).ok;
   if (validator === void 0) return false;
   const validationContext = {
     rallyId: base.rallyId,
     spotId: base.spotId,
-    proofData: getProof(context2),
+    proofData: getProof(context),
     condition,
     userState: base.state
   };
@@ -410,11 +594,15 @@ var StampRallyServer = class {
   }
   async handleCheckIn(request) {
     const body = validateCheckInRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json(
-        { ok: false, code: "INVALID_REQUEST", message: "Invalid check-in request." },
-        400
-      );
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
@@ -429,8 +617,15 @@ var StampRallyServer = class {
   }
   async handleClaimReward(request) {
     const body = validateClaimRewardRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid reward request." }, 400);
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
@@ -445,8 +640,15 @@ var StampRallyServer = class {
   }
   async handleSync(request) {
     const body = validateSyncRequest(await this.#body(request));
-    if (!body.success || body.data.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid sync request." }, 400);
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
+        {
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
     const userId = await this.#user(request);
     if (userId === null)
       return json(
@@ -601,7 +803,7 @@ var StampRallyServer = class {
         request,
         now(this.#options)
       );
-    const lockKey = `reward:${request.rallyId}:${reward.id}`;
+    const lockKey = this.#config.inventoryMode === "shared" ? "inventory:shared" : `reward:${request.rallyId}:${reward.id}`;
     if (!await this.#persistence.acquireLock(
       request.rallyId,
       lockKey,
@@ -609,6 +811,7 @@ var StampRallyServer = class {
     ))
       return { ok: false, code: "CONFLICT", message: "The reward is being claimed." };
     const timestamp = now(this.#options);
+    const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
     try {
       const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
@@ -621,6 +824,10 @@ var StampRallyServer = class {
           rallyId: request.rallyId,
           userId: request.userId,
           rewardId: reward.id,
+          stockKey: plan.primaryKey,
+          ...plan.secondaryKey === void 0 ? {} : { secondaryStockKey: plan.secondaryKey },
+          initialStock: plan.primaryInitial,
+          ...plan.secondaryInitial === void 0 ? {} : { initialSecondaryStock: plan.secondaryInitial },
           ticketNumber: request.idempotencyKey,
           timestamp: Number.isNaN(Date.parse(timestamp)) ? Date.now() : Date.parse(timestamp),
           idempotencyKey: key,
@@ -628,7 +835,7 @@ var StampRallyServer = class {
           ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
           initialUserState: initialState(this.#config, request.userId, timestamp)
         },
-        ({ stock, claimCount, userState }) => {
+        ({ stock, secondaryStock, claimCount, userState }) => {
           const storedReward = userState.rewards.find((item) => item.rewardId === reward.id) ?? {
             rewardId: reward.id,
             status: "LOCKED"
@@ -644,7 +851,7 @@ var StampRallyServer = class {
             timestamp,
             code
           );
-          if (stock !== null && stock <= 0) {
+          if (stock !== null && stock <= 0 || secondaryStock !== null && secondaryStock <= 0) {
             responseHolder.value = {
               ok: false,
               code: "OUT_OF_STOCK",
@@ -652,6 +859,7 @@ var StampRallyServer = class {
             };
             return {
               nextStock: stock,
+              ...plan.secondaryKey === void 0 ? {} : { nextSecondaryStock: secondaryStock },
               nextUserState: userState,
               auditLog: makeAudit("REJECTED", "OUT_OF_STOCK"),
               result: responseHolder.value,
@@ -682,14 +890,35 @@ var StampRallyServer = class {
             };
           }
           const nextRewards = userState.rewards.some((item) => item.rewardId === reward.id) ? userState.rewards.map((item) => item.rewardId === reward.id ? local.value : item) : [...userState.rewards, local.value];
+          const consumed = local.value.claimTicketNumber !== void 0;
+          const nextStock = consumed && stock !== null ? Math.max(0, stock - 1) : stock;
+          const nextSecondaryStock = consumed && secondaryStock !== null ? Math.max(0, secondaryStock - 1) : secondaryStock;
           const next = {
             ...userState,
             rewards: nextRewards,
-            updatedAt: timestamp
+            updatedAt: timestamp,
+            inventory: {
+              ...plan.primaryKey === "__shared__" && nextStock !== null ? { sharedRemaining: nextStock } : {},
+              ...plan.secondaryKey !== void 0 && nextSecondaryStock !== null ? { rewardRemaining: { [reward.id]: nextSecondaryStock } } : plan.primaryKey === reward.id && nextStock !== null ? { rewardRemaining: { [reward.id]: nextStock } } : {}
+            }
+          };
+          const inventory = {
+            ...plan.primaryKey === "__shared__" && nextStock !== null ? { sharedRemaining: nextStock } : {},
+            ...plan.secondaryKey !== void 0 && nextSecondaryStock !== null ? { rewardRemaining: nextSecondaryStock } : plan.primaryKey === reward.id && nextStock !== null ? { rewardRemaining: nextStock } : {}
+          };
+          responseHolder.value = local.value.claimTicketNumber === void 0 ? {
+            ok: true,
+            state: next,
+            ...Object.keys(inventory).length === 0 ? {} : { inventory }
+          } : {
+            ok: true,
+            state: next,
+            claimTicketNumber: local.value.claimTicketNumber,
+            ...Object.keys(inventory).length === 0 ? {} : { inventory }
           };
-          responseHolder.value = local.value.claimTicketNumber === void 0 ? { ok: true, state: next } : { ok: true, state: next, claimTicketNumber: local.value.claimTicketNumber };
           return {
-            nextStock: stock === null ? null : stock - 1,
+            nextStock,
+            ...plan.secondaryKey === void 0 ? {} : { nextSecondaryStock },
             nextUserState: next,
             auditLog: makeAudit("SUCCESS"),
             result: responseHolder.value
@@ -711,18 +940,46 @@ var StampRallyServer = class {
         code: "PERSISTENCE_FAILED",
         message: result.error ?? "Reward claim failed."
       };
-    } catch (error2) {
+    } catch (error) {
       return {
         ok: false,
         code: "PERSISTENCE_FAILED",
-        message: error2 instanceof Error ? error2.message : "Reward claim failed."
+        message: error instanceof Error ? error.message : "Reward claim failed."
       };
     } finally {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
   async sync(rallyId, userId) {
-    return await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
+    const state = await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
+    return this.#attachInventory(state);
+  }
+  async #attachInventory(state) {
+    const rewardRemaining = {};
+    for (const reward of this.#config.rewards) {
+      const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
+      if (plan.secondaryKey !== void 0) {
+        const stock = await this.#persistence.getRewardStock(state.rallyId, plan.secondaryKey);
+        const remaining = stock ?? plan.secondaryInitial ?? null;
+        if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);
+      } else if (plan.primaryKey !== "__shared__") {
+        const stock = await this.#persistence.getRewardStock(state.rallyId, plan.primaryKey);
+        const remaining = stock ?? plan.primaryInitial;
+        if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);
+      }
+    }
+    const shared = sharedStock(this.#config);
+    const storedShared = await this.#persistence.getRewardStock(state.rallyId, "__shared__");
+    const sharedRemaining = this.#config.inventoryMode === "shared" && shared !== null ? Math.max(0, storedShared ?? shared) : void 0;
+    return {
+      ...state,
+      ...Object.keys(rewardRemaining).length === 0 && sharedRemaining === void 0 ? {} : {
+        inventory: {
+          ...sharedRemaining === void 0 ? {} : { sharedRemaining },
+          ...Object.keys(rewardRemaining).length === 0 ? {} : { rewardRemaining }
+        }
+      }
+    };
   }
   async #body(request) {
     try {
@@ -740,6 +997,10 @@ var StampRallyServer = class {
       const authenticatedUserId = identity.authenticatedUserId;
       return authenticatedUserId.length > 0 ? authenticatedUserId : null;
     }
+    if (this.#options.anonymousPolicy === "reject") return null;
+    const sessionId = request.headers.get("X-Anonymous-Session-Id");
+    if (sessionId !== null && isUuidV4(sessionId)) return sessionId;
+    if (this.#options.anonymousPolicy === "session_scoped") return null;
     return "anonymous";
   }
   async #rememberCheckInTransaction(request, timestamp, key, current, mutation, responseHolder) {
@@ -788,7 +1049,9 @@ var StampRallyServer = class {
 
 exports.InMemoryServerPersistenceAdapter = InMemoryServerPersistenceAdapter;
 exports.StampRallyServer = StampRallyServer;
+exports.executeCheckInTransaction = executeCheckInTransaction;
 exports.executeClaimRewardTransaction = executeClaimRewardTransaction;
+exports.executeRedisTransaction = executeRedisTransaction;
 exports.validateCheckInRequest = validateCheckInRequest;
 exports.validateClaimRewardRequest = validateClaimRewardRequest;
 exports.validateSyncRequest = validateSyncRequest;