@stamprally/server 0.13.0 → 0.15.0

package/dist/index.js

@@ -13,6 +13,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);
@@ -24,6 +28,39 @@ async function executeClaimRewardTransaction(database, store, params, mutation)
     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) };
+  }
+}
 
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
@@ -89,8 +126,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
         });
@@ -106,16 +149,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
@@ -142,6 +214,39 @@ var InMemoryServerPersistenceAdapter = class {
       return { success: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
+  async executeCheckInTransaction(params, mutation) {
+    try {
+      return await this.runTransaction(params.rallyId, async () => {
+        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 mutationResult = mutation({ userState });
+        if (mutationResult.error !== void 0) {
+          await this.recordAuditLog(mutationResult.auditLog);
+          if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+            await this.saveIdempotentResult(
+              params.rallyId,
+              params.idempotencyKey,
+              mutationResult.result,
+              params.idempotencyTtlMs ?? 864e5
+            );
+          return { success: false, error: mutationResult.error };
+        }
+        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        await this.recordAuditLog(mutationResult.auditLog);
+        if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+          await this.saveIdempotentResult(
+            params.rallyId,
+            params.idempotencyKey,
+            mutationResult.result,
+            params.idempotencyTtlMs ?? 864e5
+          );
+        return { success: true };
+      });
+    } catch (error) {
+      return { success: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
   async rollbackUserState(rallyId, userId, previousState) {
     const key = `${rallyId}:${userId}`;
     if (previousState === null) this.#states.delete(key);
@@ -193,7 +298,7 @@ var InMemoryServerPersistenceAdapter = class {
     if (count <= 1) this.#claims.delete(key);
     else this.#claims.set(key, count - 1);
     const index = this.#claimRecords.findIndex(
-      (record) => record.rallyId === rallyId && record.userId === userId && record.rewardId === rewardId && record.ticketNumber === ticketNumber
+      (record2) => record2.rallyId === rallyId && record2.userId === userId && record2.rewardId === rewardId && record2.ticketNumber === ticketNumber
     );
     if (index >= 0) this.#claimRecords.splice(index, 1);
   }
@@ -241,6 +346,138 @@ var InMemoryServerPersistenceAdapter = class {
     }
   }
 };
+
+// src/security.ts
+function errors(...items) {
+  return { success: false, errors: items };
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+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 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) {
+  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 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) {
+  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 errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.staffPasscode !== void 0 && !nonEmpty(value.staffPasscode))
+    return errors({
+      path: "staffPasscode",
+      message: "staffPasscode must be non-empty.",
+      code: "INVALID_TYPE"
+    });
+  if (value.staffId !== void 0 && !nonEmpty(value.staffId))
+    return errors({ path: "staffId", message: "staffId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.now !== void 0 && !nonEmpty(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 validateSyncRequest(value) {
+  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 errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  return { success: true, data: value };
+}
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), {
     status,
@@ -250,11 +487,27 @@ 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)}`}`;
 }
-function now(options, requested) {
-  return requested ?? options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
+function now(options) {
+  return options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+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 {
@@ -265,6 +518,27 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
+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;
 }
@@ -317,47 +591,69 @@ var StampRallyServer = class {
     return json({ ok: false, code: "NOT_FOUND", message: "Route not found." }, 404);
   }
   async handleCheckIn(request) {
-    const body = await this.#body(request);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id || body.spotId === "" || body.idempotencyKey === "" || body.context === void 0)
-      return json(
+    const body = validateCheckInRequest(await this.#body(request));
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
         {
-          ok: false,
-          code: "INVALID_REQUEST",
-          message: "rallyId, spotId, context, and idempotencyKey are required."
-        },
-        400
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
+    const userId = await this.#user(request);
+    if (userId === null)
+      return json(
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
       );
-    const result = await this.checkIn({ ...body, userId });
+    const result = await this.checkIn({ ...body.data, userId });
     return json(
       { ...result, status: operationStatus(result) },
       result.ok ? 200 : result.code === "SPOT_NOT_FOUND" ? 404 : 422
     );
   }
   async handleClaimReward(request) {
-    const body = await this.#body(request);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id || body.rewardId === "" || body.idempotencyKey === "")
-      return json(
+    const body = validateClaimRewardRequest(await this.#body(request));
+    if (!body.success) return validationResponse(body.errors);
+    if (body.data.rallyId !== this.#config.id)
+      return validationResponse([
         {
-          ok: false,
-          code: "INVALID_REQUEST",
-          message: "rallyId, rewardId, and idempotencyKey are required."
-        },
-        400
+          path: "rallyId",
+          message: "The rally does not match this server.",
+          code: "INVALID_VALUE"
+        }
+      ]);
+    const userId = await this.#user(request);
+    if (userId === null)
+      return json(
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
       );
-    const result = await this.claimReward({ ...body, userId });
+    const result = await this.claimReward({ ...body.data, userId });
     return json(
       { ...result, status: operationStatus(result) },
       result.ok ? 200 : result.code === "REWARD_NOT_FOUND" ? 404 : 422
     );
   }
   async handleSync(request) {
-    const body = await this.#body(request);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "rallyId is required." }, 400);
-    return json({ ok: true, state: await this.sync(body.rallyId, userId) });
+    const body = validateSyncRequest(await this.#body(request));
+    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(
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
+      );
+    return json({ ok: true, state: await this.sync(body.data.rallyId, userId) });
   }
   async checkIn(request) {
     const key = `check-in:${request.rallyId}:${request.userId}:${request.idempotencyKey}`;
@@ -373,47 +669,68 @@ var StampRallyServer = class {
       this.#options.lockTtlMs ?? 5e3
     ))
       return { ok: false, code: "CONFLICT", message: "The user state is being updated." };
-    const timestamp = now(this.#options, request.now);
+    const timestamp = now(this.#options);
     try {
+      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
+      const responseHolder = { value: null };
+      const makeAudit = (status, code) => audit(
+        request.rallyId,
+        request.userId,
+        "CHECK_IN",
+        request.spotId,
+        request.idempotencyKey,
+        status,
+        timestamp,
+        code
+      );
       const spot = this.#config.spots.find((item) => item.id === request.spotId);
-      if (spot === void 0)
-        return this.#remember(
+      if (spot === void 0) {
+        responseHolder.value = {
+          ok: false,
+          code: "SPOT_NOT_FOUND",
+          message: "Spot was not found."
+        };
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          { ok: false, code: "SPOT_NOT_FOUND", message: "Spot was not found." },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          {
+            nextUserState: current,
+            auditLog: makeAudit("REJECTED", "SPOT_NOT_FOUND"),
+            result: responseHolder.value,
+            error: "SPOT_NOT_FOUND"
+          },
+          responseHolder
         );
-      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
-      if (current.records.some((record) => record.stampId === request.spotId))
-        return this.#remember(
+      }
+      const rejected = (code, message) => {
+        responseHolder.value = { ok: false, code, message };
+        return {
+          nextUserState: current,
+          auditLog: makeAudit("REJECTED", code),
+          result: responseHolder.value,
+          error: code
+        };
+      };
+      if (current.records.some((record2) => record2.stampId === request.spotId))
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          { ok: false, code: "STAMP_ALREADY_ACQUIRED", message: "Spot was already claimed." },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          rejected("STAMP_ALREADY_ACQUIRED", "Spot was already claimed."),
+          responseHolder
         );
-      const acquired = new Set(current.records.map((record) => record.stampId));
+      const acquired = new Set(current.records.map((record2) => record2.stampId));
       if (spot.prerequisites?.some((id) => !acquired.has(id)))
-        return this.#remember(
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          {
-            ok: false,
-            code: "PREREQUISITES_NOT_MET",
-            message: "Prerequisite spots are not complete."
-          },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          rejected("PREREQUISITES_NOT_MET", "Prerequisite spots are not complete."),
+          responseHolder
         );
       for (const condition of spot.conditions)
         if (!await evaluate(
@@ -422,15 +739,13 @@ var StampRallyServer = class {
           condition.type === "custom" ? this.#options.customValidators?.[condition.validatorName] : void 0,
           { rallyId: request.rallyId, spotId: request.spotId, state: current }
         ))
-          return this.#remember(
+          return await this.#rememberCheckInTransaction(
+            request,
+            timestamp,
             key,
-            { ok: false, code: "INVALID_PROOF", message: "Verification failed." },
-            request.rallyId,
-            request.userId,
-            "CHECK_IN",
-            request.spotId,
-            request.idempotencyKey,
-            timestamp
+            current,
+            rejected("INVALID_PROOF", "Verification failed."),
+            responseHolder
           );
       const next = {
         ...current,
@@ -443,17 +758,30 @@ var StampRallyServer = class {
         ),
         updatedAt: timestamp
       };
-      await this.#persistence.saveUserState(request.rallyId, request.userId, next);
-      return this.#remember(
-        key,
-        { ok: true, state: next },
-        request.rallyId,
-        request.userId,
-        "CHECK_IN",
-        request.spotId,
-        request.idempotencyKey,
-        timestamp
+      responseHolder.value = { ok: true, state: next };
+      const transaction = await this.#persistence.executeCheckInTransaction(
+        {
+          rallyId: request.rallyId,
+          userId: request.userId,
+          spotId: request.spotId,
+          timestamp: timestampMillis(timestamp),
+          idempotencyKey: key,
+          proofData: request.context,
+          ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
+          initialUserState: current
+        },
+        () => ({
+          nextUserState: next,
+          auditLog: makeAudit("SUCCESS"),
+          result: responseHolder.value
+        })
       );
+      if (transaction.success && responseHolder.value !== null) return responseHolder.value;
+      return {
+        ok: false,
+        code: "PERSISTENCE_FAILED",
+        message: transaction.error ?? "Check-in failed."
+      };
     } finally {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
@@ -471,16 +799,17 @@ var StampRallyServer = class {
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
         request,
-        now(this.#options, request.now)
+        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,
       this.#options.lockTtlMs ?? 5e3
     ))
       return { ok: false, code: "CONFLICT", message: "The reward is being claimed." };
-    const timestamp = now(this.#options, request.now);
+    const timestamp = now(this.#options);
+    const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
     try {
       const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
@@ -493,6 +822,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,
@@ -500,7 +833,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"
@@ -516,7 +849,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",
@@ -524,14 +857,16 @@ var StampRallyServer = class {
             };
             return {
               nextStock: stock,
+              ...plan.secondaryKey === void 0 ? {} : { nextSecondaryStock: secondaryStock },
               nextUserState: userState,
               auditLog: makeAudit("REJECTED", "OUT_OF_STOCK"),
               result: responseHolder.value,
               error: "OUT_OF_STOCK"
             };
           }
+          const effectiveReward = reward.staffPasscode === void 0 && this.#config.staffPasscode !== void 0 ? { ...reward, staffPasscode: this.#config.staffPasscode } : reward;
           const local = consumeReward({
-            reward,
+            reward: effectiveReward,
             currentState: currentReward,
             now: timestamp,
             userRedemptionCount: claimCount,
@@ -553,14 +888,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
@@ -593,7 +949,35 @@ var StampRallyServer = class {
     }
   }
   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 {
@@ -603,31 +987,40 @@ var StampRallyServer = class {
       return null;
     }
   }
-  async #user(request, requested) {
-    if (this.#options.authenticate !== void 0)
-      return await this.#options.authenticate(request) ?? null;
-    return requested ?? null;
+  async #user(request) {
+    if (this.#options.authenticate !== void 0) {
+      const identity = await this.#options.authenticate(request);
+      if (typeof identity === "string") return identity.length > 0 ? identity : null;
+      if (identity === null) return null;
+      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 #remember(key, result, rallyId, userId, action, resourceId, idempotencyKey, timestamp) {
-    await this.#persistence.recordAuditLog(
-      audit(
-        rallyId,
-        userId,
-        action,
-        resourceId,
-        idempotencyKey,
-        result.ok ? "SUCCESS" : "REJECTED",
-        timestamp,
-        result.ok ? void 0 : result.code
-      )
-    );
-    await this.#persistence.saveIdempotentResult(
-      rallyId,
-      key,
-      result,
-      this.#options.idempotencyTtlMs ?? 864e5
+  async #rememberCheckInTransaction(request, timestamp, key, current, mutation, responseHolder) {
+    const transaction = await this.#persistence.executeCheckInTransaction(
+      {
+        rallyId: request.rallyId,
+        userId: request.userId,
+        spotId: request.spotId,
+        timestamp: timestampMillis(timestamp),
+        idempotencyKey: key,
+        ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
+        initialUserState: current
+      },
+      () => mutation
     );
-    return result;
+    if (responseHolder.value !== null && (transaction.success || transaction.error === mutation.error))
+      return responseHolder.value;
+    return {
+      ok: false,
+      code: "PERSISTENCE_FAILED",
+      message: transaction.error ?? "Check-in failed."
+    };
   }
   async #rememberClaim(key, result, request, timestamp) {
     await this.#persistence.recordAuditLog(
@@ -652,6 +1045,6 @@ var StampRallyServer = class {
   }
 };
 
-export { InMemoryServerPersistenceAdapter, StampRallyServer, executeClaimRewardTransaction };
+export { InMemoryServerPersistenceAdapter, StampRallyServer, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map