@stamprally/server 0.16.0 → 0.18.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/server v0.16.0
+# @stamprally/server v0.18.0
 
 Web Standard `Request` / `Response` handlers for server-authoritative check-ins and reward claims.
 

package/dist/index.cjs

@@ -7,7 +7,16 @@ async function executeClaimRewardTransaction(database, store, params2, mutation2
   try {
     return await database.transaction(async (transaction) => {
       const current = await store.readContext(transaction, params2);
-      const next = mutation2(current);
+      const secondaryStock = current.secondaryStock ?? null;
+      const rewardStock2 = params2.stockKey === "__shared__" ? secondaryStock : current.stock;
+      const next = mutation2({
+        ...current,
+        rewardStock: rewardStock2,
+        sharedStock: params2.stockKey === "__shared__" ? current.stock : null,
+        primaryStock: rewardStock2,
+        secondaryStock,
+        stock: current.stock
+      });
       if (next.error !== void 0) {
         await store.writeAudit(transaction, next.auditLog);
         if (params2.idempotencyKey !== void 0 && next.result !== void 0)
@@ -15,7 +24,7 @@ async function executeClaimRewardTransaction(database, store, params2, mutation2
         return { success: false, error: next.error };
       }
       if (next.nextSecondaryStock !== void 0 && store.writeSecondaryStock === void 0)
-        return { success: false, error: "INVENTORY_NOT_SUPPORTED" };
+        return { success: false, error: "INVENTORY_STORAGE_NOT_IMPLEMENTED" };
       if (next.nextStock !== null) await store.writeStock(transaction, params2, next.nextStock);
       if (next.nextSecondaryStock !== void 0 && store.writeSecondaryStock !== void 0) {
         if (next.nextSecondaryStock !== null)
@@ -69,6 +78,7 @@ async function executeRedisTransaction(redis, queue) {
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
   supportsRewardStock = true;
+  supportsSecondaryStock = true;
   #locks = /* @__PURE__ */ new Map();
   #idempotent = /* @__PURE__ */ new Map();
   #states = /* @__PURE__ */ new Map();
@@ -146,9 +156,16 @@ var InMemoryServerPersistenceAdapter = class {
           params2.stockKey ?? params2.rewardId
         );
         const storedSecondaryStock = params2.secondaryStockKey === void 0 ? null : await this.getRewardStock(params2.rallyId, params2.secondaryStockKey);
+        const stock = storedStock ?? initialStock;
+        const secondaryStock = storedSecondaryStock ?? initialSecondaryStock;
+        const rewardStock2 = params2.stockKey === "__shared__" ? secondaryStock : stock;
+        const sharedStock2 = params2.stockKey === "__shared__" ? stock : null;
         const mutationResult = mutation2({
-          stock: storedStock ?? initialStock,
-          secondaryStock: storedSecondaryStock ?? initialSecondaryStock,
+          rewardStock: rewardStock2,
+          sharedStock: sharedStock2,
+          primaryStock: rewardStock2,
+          secondaryStock,
+          stock,
           claimCount: await this.getUserClaimCount(params2.rallyId, params2.userId, params2.rewardId),
           userState
         });
@@ -626,26 +643,41 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
-function rewardStock(config, rewardId, stockLimit) {
-  const configured = config.inventory?.[rewardId];
+function rewardStock(config, reward) {
+  const stockLimit = reward.stockLimit;
+  const key = reward.stockKey ?? reward.id;
+  const configured = key === "__shared__" ? config.inventory?.sharedStock : config.inventory?.[key];
   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;
+  return config.inventory?.sharedStock ?? null;
 }
 function inventoryPlan(config, rewardId, stockLimit) {
-  const individual = rewardStock(config, rewardId, stockLimit);
+  const reward = config.rewards.find((item) => item.id === rewardId);
+  const individual = reward === void 0 ? stockLimit ?? null : rewardStock(config, reward);
   const shared = sharedStock(config);
+  const explicitPrimaryKey = reward?.stockKey;
+  const explicitSecondaryKey = reward?.secondaryStockKey;
   if (config.inventoryMode === "shared" && shared !== null) {
     return {
-      primaryKey: "__shared__",
-      primaryInitial: shared,
-      ...individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
+      primaryKey: explicitPrimaryKey ?? "__shared__",
+      primaryInitial: explicitPrimaryKey === void 0 ? shared : individual,
+      ...explicitSecondaryKey !== void 0 ? {
+        secondaryKey: explicitSecondaryKey,
+        secondaryInitial: config.inventory?.[explicitSecondaryKey] ?? individual
+      } : individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
     };
   }
-  return { primaryKey: rewardId, primaryInitial: individual };
+  return {
+    primaryKey: explicitPrimaryKey ?? rewardId,
+    primaryInitial: individual,
+    ...explicitSecondaryKey === void 0 ? {} : {
+      secondaryKey: explicitSecondaryKey,
+      secondaryInitial: config.inventory?.[explicitSecondaryKey] ?? null
+    }
+  };
 }
 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;
@@ -680,7 +712,18 @@ function operationStatus(result) {
   if (result.ok) return "ACCEPTED";
   return result.code === "CONFLICT" || result.code === "PERSISTENCE_FAILED" ? "RETRYABLE_ERROR" : "REJECTED_PERMANENT";
 }
-function withDirectIdentity(request) {
+function withDirectIdentity(request, authContext) {
+  if (authContext !== void 0) {
+    if (authContext.authenticatedUserId.trim() === "")
+      throw new RequestValidationException([
+        {
+          path: "authContext.authenticatedUserId",
+          message: "An authenticated userId is required.",
+          code: "REQUIRED"
+        }
+      ]);
+    return { ...request, userId: authContext.authenticatedUserId };
+  }
   if (request.userId !== void 0) return { ...request, userId: request.userId };
   if (request.anonymousSessionId !== void 0 && isUuidV4(request.anonymousSessionId))
     return { ...request, userId: request.anonymousSessionId };
@@ -796,22 +839,28 @@ var StampRallyServer = class {
         401
       );
     const sessionId = request.headers.get("x-anonymous-session-id");
+    const authContext = {
+      authenticatedUserId: userId,
+      ...sessionId === null ? {} : { isAnonymous: true, sessionId }
+    };
     try {
       return json({
         ok: true,
-        state: await this.syncProgress({
-          rallyId: body.data.rallyId,
-          userId,
-          ...sessionId === null ? {} : { anonymousSessionId: sessionId }
-        })
+        state: await this.syncProgress(
+          {
+            rallyId: body.data.rallyId,
+            ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+          },
+          authContext
+        )
       });
     } catch (error) {
       if (error instanceof RequestValidationException) return validationResponse(error.errors);
       throw error;
     }
   }
-  async checkIn(request) {
-    const directRequest = withDirectIdentity(request);
+  async checkIn(request, authContext) {
+    const directRequest = withDirectIdentity(request, authContext);
     assertValidCheckInParams(directRequest, this.#config);
     const { userId } = directRequest;
     const key = `check-in:${request.rallyId}:${userId}:${request.idempotencyKey}`;
@@ -944,8 +993,8 @@ var StampRallyServer = class {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
-  async claimReward(request) {
-    const directRequest = withDirectIdentity(request);
+  async claimReward(request, authContext) {
+    const directRequest = withDirectIdentity(request, authContext);
     assertValidClaimParams(directRequest, this.#config);
     const { userId } = directRequest;
     const key = `claim:${request.rallyId}:${userId}:${request.rewardId}:${request.idempotencyKey}`;
@@ -963,13 +1012,16 @@ var StampRallyServer = class {
         now(this.#options)
       );
     const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
-    if (rewardStock(this.#config, reward.id, reward.stockLimit) !== null && (this.#persistence.supportsRewardStock === false || typeof this.#persistence.getRewardStock !== "function"))
+    if (plan.secondaryKey !== void 0 && this.#persistence.supportsSecondaryStock !== true)
+      throw new Error("SECONDARY_STOCK_UNSUPPORTED");
+    const inventoryEnabled = plan.primaryInitial !== null || plan.secondaryInitial !== void 0 && plan.secondaryInitial !== null;
+    if (inventoryEnabled && (this.#persistence.supportsRewardStock === false || typeof this.#persistence.getRewardStock !== "function" || typeof this.#persistence.executeClaimRewardTransaction !== "function"))
       return this.#rememberClaim(
         key,
         {
           ok: false,
-          code: "INVENTORY_NOT_SUPPORTED",
-          message: "This persistence adapter cannot store per-reward inventory."
+          code: "INVENTORY_STORAGE_NOT_IMPLEMENTED",
+          message: "This persistence adapter cannot atomically store inventory."
         },
         directRequest,
         now(this.#options)
@@ -996,7 +1048,7 @@ var StampRallyServer = class {
           rewardId: reward.id,
           stockKey: plan.primaryKey,
           ...plan.secondaryKey === void 0 ? {} : { secondaryStockKey: plan.secondaryKey },
-          rewardStockLimit: rewardStock(this.#config, reward.id, reward.stockLimit),
+          rewardStockLimit: rewardStock(this.#config, reward),
           sharedStockLimit: this.#config.inventoryMode === "shared" ? sharedStock(this.#config) : null,
           initialStock: plan.primaryInitial,
           ...plan.secondaryInitial === void 0 ? {} : { initialSecondaryStock: plan.secondaryInitial },
@@ -1100,11 +1152,11 @@ var StampRallyServer = class {
       const response = responseHolder.value;
       if (!result.success) {
         if (response !== null && !response.ok && response.code === result.error) return response;
-        if (result.error === "INVENTORY_NOT_SUPPORTED")
+        if (result.error === "INVENTORY_STORAGE_NOT_IMPLEMENTED")
           return {
             ok: false,
-            code: "INVENTORY_NOT_SUPPORTED",
-            message: "This persistence adapter cannot store per-reward inventory."
+            code: "INVENTORY_STORAGE_NOT_IMPLEMENTED",
+            message: "This persistence adapter cannot atomically store inventory."
           };
         return {
           ok: false,
@@ -1128,21 +1180,24 @@ var StampRallyServer = class {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
-  async sync(rallyId, userId) {
+  async sync(rallyId, identity) {
+    const userId = typeof identity === "string" ? identity : identity.authenticatedUserId;
     assertValidSyncParams({ rallyId, userId }, this.#config);
     const state2 = await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
     return this.#attachInventory(state2);
   }
-  async syncProgress(request) {
-    const directRequest = withDirectIdentity(request);
+  async syncProgress(request, authContext) {
+    const directRequest = withDirectIdentity(request, authContext);
     assertValidSyncParams(directRequest, this.#config);
-    return this.sync(directRequest.rallyId, directRequest.userId);
+    return this.sync(directRequest.rallyId, authContext);
   }
   async #attachInventory(state2) {
     const rewardRemaining = {};
     for (const reward of this.#config.rewards) {
       const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
       if (plan.secondaryKey !== void 0) {
+        if (this.#persistence.supportsSecondaryStock !== true)
+          throw new Error("SECONDARY_STOCK_UNSUPPORTED");
         const stock = await this.#persistence.getRewardStock(state2.rallyId, plan.secondaryKey);
         const remaining = stock ?? plan.secondaryInitial ?? null;
         if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);
@@ -1312,6 +1367,15 @@ async function runPersistenceAdapterComplianceTests(createAdapter) {
     await adapter.getRewardStock("compliance-rally", "reward") === 0,
     "per-reward stock was not decremented atomically"
   );
+  const exhausted = await adapter.executeClaimRewardTransaction(
+    params("carol", "boundary"),
+    mutation
+  );
+  assert(!exhausted.success, "a zero-stock claim was accepted");
+  assert(
+    await adapter.getRewardStock("compliance-rally", "__shared__") === 0 && await adapter.getRewardStock("compliance-rally", "reward") === 0,
+    "zero-stock rejection did not preserve both stock boundaries"
+  );
   const idempotentAdapter = await createAdapter();
   const idempotentParams = params("alice", "same-key");
   const firstClaim = await idempotentAdapter.executeClaimRewardTransaction(
@@ -1327,6 +1391,10 @@ async function runPersistenceAdapterComplianceTests(createAdapter) {
     await idempotentAdapter.getRewardStock("compliance-rally", "__shared__") === 0,
     "idempotent retry decremented shared stock twice"
   );
+  assert(
+    await idempotentAdapter.getRewardStock("compliance-rally", "reward") === 0,
+    "idempotent retry decremented per-reward stock twice"
+  );
   const rollbackAdapter = await createAdapter();
   const rollbackParams = params("alice", "rollback");
   const rollback = await rollbackAdapter.executeClaimRewardTransaction(rollbackParams, () => {