@stamprally/server 0.11.0 → 0.13.0

package/README.md

@@ -13,6 +13,12 @@ const response = await server.handle(request);
 
 `ServerPersistenceAdapter` scopes locks, reward stock, idempotency records, user state, claim records, and audit logs by `rallyId`. Its `recordUserClaim` operation receives the rally, user, reward, issued ticket number, and timestamp. Use a transactional database or equivalent Redis primitives for multi-instance production deployments.
 
+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`.
+
 Hono can mount the handler directly because it accepts the same Web Standard request and response types.
 
 ## License

package/dist/index.cjs

@@ -2,6 +2,31 @@
 
 var core = require('@stamprally/core');
 
+// src/examples/transaction.ts
+async function executeClaimRewardTransaction(database, store, params, mutation) {
+  try {
+    return await database.transaction(async (transaction) => {
+      const current = await store.readContext(transaction, params);
+      const next = mutation(current);
+      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 };
+      }
+      if (next.nextStock !== null) await store.writeStock(transaction, params, next.nextStock);
+      await store.writeUserState(transaction, params, next.nextUserState);
+      await store.writeClaimRecord(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) };
+  }
+}
+
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
   #locks = /* @__PURE__ */ new Map();
@@ -60,6 +85,65 @@ var InMemoryServerPersistenceAdapter = class {
     const current = this.#stocks.get(key);
     if (current !== void 0) this.#stocks.set(key, current + Math.max(0, count));
   }
+  async executeClaimRewardTransaction(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({
+          stock: await this.getRewardStock(params.rallyId, params.rewardId),
+          claimCount: await this.getUserClaimCount(params.rallyId, params.userId, params.rewardId),
+          userState
+        });
+        const idempotencyKey = params.idempotencyKey;
+        if (mutationResult.error !== void 0) {
+          await this.recordAuditLog(mutationResult.auditLog);
+          if (idempotencyKey !== void 0 && mutationResult.result !== void 0)
+            await this.saveIdempotentResult(
+              params.rallyId,
+              idempotencyKey,
+              mutationResult.result,
+              params.idempotencyTtlMs ?? 864e5
+            );
+          return { success: false, error: mutationResult.error };
+        }
+        const currentStock = await this.getRewardStock(params.rallyId, params.rewardId);
+        if (currentStock !== null && (mutationResult.nextStock === null || mutationResult.nextStock < 0))
+          throw new Error("The transaction produced an invalid stock value.");
+        if (currentStock === 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),
+            mutationResult.nextStock
+          );
+        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        const reward = mutationResult.nextUserState.rewards.find(
+          (item) => item.rewardId === params.rewardId
+        );
+        if (reward?.claimTicketNumber !== void 0)
+          await this.recordUserClaim({
+            rallyId: params.rallyId,
+            userId: params.userId,
+            rewardId: params.rewardId,
+            ticketNumber: reward.claimTicketNumber,
+            timestamp: params.timestamp
+          });
+        await this.recordAuditLog(mutationResult.auditLog);
+        if (idempotencyKey !== void 0 && mutationResult.result !== void 0)
+          await this.saveIdempotentResult(
+            params.rallyId,
+            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);
@@ -212,6 +296,10 @@ function audit(rallyId, userId, action, resourceId, key, status, timestamp, code
     ...code === void 0 ? {} : { metadata: { errorCode: code } }
   };
 }
+function operationStatus(result) {
+  if (result.ok) return "ACCEPTED";
+  return result.code === "CONFLICT" || result.code === "PERSISTENCE_FAILED" ? "RETRYABLE_ERROR" : "REJECTED_PERMANENT";
+}
 var StampRallyServer = class {
   #config;
   #persistence;
@@ -243,7 +331,10 @@ var StampRallyServer = class {
         400
       );
     const result = await this.checkIn({ ...body, userId });
-    return json(result, result.ok ? 200 : result.code === "SPOT_NOT_FOUND" ? 404 : 422);
+    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);
@@ -258,7 +349,10 @@ var StampRallyServer = class {
         400
       );
     const result = await this.claimReward({ ...body, userId });
-    return json(result, result.ok ? 200 : result.code === "REWARD_NOT_FOUND" ? 404 : 422);
+    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);
@@ -367,16 +461,11 @@ var StampRallyServer = class {
     }
   }
   async claimReward(request) {
-    if (this.#persistence.runTransaction !== void 0)
-      return this.#persistence.runTransaction(
-        request.rallyId,
-        (transaction) => this.#claimRewardMutation(request, transaction)
-      );
-    return this.#claimRewardMutation(request, this.#persistence);
-  }
-  async #claimRewardMutation(request, persistence) {
     const key = `claim:${request.rallyId}:${request.userId}:${request.rewardId}:${request.idempotencyKey}`;
-    const previous = await persistence.getIdempotentResult(request.rallyId, key);
+    const previous = await this.#persistence.getIdempotentResult(
+      request.rallyId,
+      key
+    );
     if (previous !== null) return previous;
     const reward = this.#config.rewards.find((item) => item.id === request.rewardId);
     if (reward === void 0)
@@ -384,118 +473,125 @@ var StampRallyServer = class {
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
         request,
-        now(this.#options, request.now),
-        persistence
+        now(this.#options, request.now)
       );
     const lockKey = `reward:${request.rallyId}:${reward.id}`;
-    if (!await persistence.acquireLock(request.rallyId, lockKey, this.#options.lockTtlMs ?? 5e3))
+    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);
-    let decremented = false;
-    let previousState = null;
-    let recordedTicket = null;
-    let successAuditId = null;
     try {
-      const checked = await persistence.getIdempotentResult(request.rallyId, key);
-      if (checked !== null) return checked;
-      const storedState = await persistence.getUserState(request.rallyId, request.userId);
-      previousState = storedState;
-      const current = storedState ?? initialState(this.#config, request.userId, timestamp);
-      const claimCount = await persistence.getUserClaimCount(
+      const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
-        request.userId,
-        reward.id
+        key
       );
-      const storedReward = current.rewards.find((item) => item.rewardId === reward.id) ?? {
-        rewardId: reward.id,
-        status: "LOCKED"
-      };
-      const currentReward = reward.redemptionMethod === "server_claim" && storedReward.status === "CONSUMED" && (reward.userClaimLimit === void 0 || claimCount < reward.userClaimLimit) ? { ...storedReward, status: "AVAILABLE" } : storedReward;
-      const local = core.consumeReward({
-        reward,
-        currentState: currentReward,
-        now: timestamp,
-        userRedemptionCount: claimCount,
-        ...request.staffPasscode === void 0 ? {} : { inputPasscode: request.staffPasscode },
-        ...request.staffId === void 0 ? {} : { staffId: request.staffId }
-      });
-      if (!local.ok)
-        return this.#rememberClaim(
-          key,
-          { ok: false, code: local.error.code, message: "Reward cannot be claimed." },
-          request,
-          timestamp,
-          persistence
-        );
-      const stock = await persistence.decrementRewardStock(request.rallyId, reward.id);
-      if (!stock.success)
-        return this.#rememberClaim(
-          key,
-          { ok: false, code: "OUT_OF_STOCK", message: "Reward is out of stock." },
-          request,
-          timestamp,
-          persistence
-        );
-      decremented = true;
-      const next = {
-        ...current,
-        rewards: current.rewards.map((item) => item.rewardId === reward.id ? local.value : item),
-        updatedAt: timestamp
-      };
-      try {
-        await persistence.saveUserState(request.rallyId, request.userId, next);
-        const response = local.value.claimTicketNumber === void 0 ? { ok: true, state: next } : { ok: true, state: next, claimTicketNumber: local.value.claimTicketNumber };
-        recordedTicket = local.value.claimTicketNumber ?? "";
-        await persistence.recordUserClaim({
+      if (checked !== null) return checked;
+      const responseHolder = { value: null };
+      const result = await this.#persistence.executeClaimRewardTransaction(
+        {
           rallyId: request.rallyId,
           userId: request.userId,
           rewardId: reward.id,
-          ticketNumber: recordedTicket,
-          timestamp: Number.isNaN(Date.parse(timestamp)) ? Date.now() : Date.parse(timestamp)
-        });
-        const successAudit = audit(
-          request.rallyId,
-          request.userId,
-          "CLAIM_REWARD",
-          reward.id,
-          request.idempotencyKey,
-          "SUCCESS",
-          timestamp
-        );
-        successAuditId = successAudit.id;
-        await persistence.recordAuditLog(successAudit);
-        await persistence.saveIdempotentResult(
-          request.rallyId,
-          key,
-          response,
-          this.#options.idempotencyTtlMs ?? 864e5
-        );
-        return response;
-      } catch (error) {
-        if (recordedTicket !== null && persistence.rollbackUserClaim !== void 0)
-          await persistence.rollbackUserClaim(
+          ticketNumber: request.idempotencyKey,
+          timestamp: Number.isNaN(Date.parse(timestamp)) ? Date.now() : Date.parse(timestamp),
+          idempotencyKey: key,
+          ...request.staffPasscode === void 0 ? {} : { proofData: request.staffPasscode },
+          ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
+          initialUserState: initialState(this.#config, request.userId, timestamp)
+        },
+        ({ stock, claimCount, userState }) => {
+          const storedReward = userState.rewards.find((item) => item.rewardId === reward.id) ?? {
+            rewardId: reward.id,
+            status: "LOCKED"
+          };
+          const currentReward = reward.redemptionMethod === "server_claim" && storedReward.status === "CONSUMED" && (reward.userClaimLimit === void 0 || claimCount < reward.userClaimLimit) ? { ...storedReward, status: "AVAILABLE" } : storedReward;
+          const makeAudit = (status, code) => audit(
             request.rallyId,
             request.userId,
+            "CLAIM_REWARD",
             reward.id,
-            recordedTicket
+            request.idempotencyKey,
+            status,
+            timestamp,
+            code
           );
-        if (persistence.rollbackUserState !== void 0)
-          await persistence.rollbackUserState(request.rallyId, request.userId, previousState);
-        if (successAuditId !== null && persistence.removeAuditLog !== void 0)
-          await persistence.removeAuditLog(successAuditId);
-        await this.#restoreRewardStock(persistence, request.rallyId, reward.id);
-        decremented = false;
-        throw error;
+          if (stock !== null && stock <= 0) {
+            responseHolder.value = {
+              ok: false,
+              code: "OUT_OF_STOCK",
+              message: "Reward is out of stock."
+            };
+            return {
+              nextStock: stock,
+              nextUserState: userState,
+              auditLog: makeAudit("REJECTED", "OUT_OF_STOCK"),
+              result: responseHolder.value,
+              error: "OUT_OF_STOCK"
+            };
+          }
+          const local = core.consumeReward({
+            reward,
+            currentState: currentReward,
+            now: timestamp,
+            userRedemptionCount: claimCount,
+            ...request.staffPasscode === void 0 ? {} : { inputPasscode: request.staffPasscode },
+            ...request.staffId === void 0 ? {} : { staffId: request.staffId }
+          });
+          if (!local.ok) {
+            responseHolder.value = {
+              ok: false,
+              code: local.error.code,
+              message: "Reward cannot be claimed."
+            };
+            return {
+              nextStock: stock,
+              nextUserState: userState,
+              auditLog: makeAudit("REJECTED", local.error.code),
+              result: responseHolder.value,
+              error: local.error.code
+            };
+          }
+          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 next = {
+            ...userState,
+            rewards: nextRewards,
+            updatedAt: timestamp
+          };
+          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,
+            nextUserState: next,
+            auditLog: makeAudit("SUCCESS"),
+            result: responseHolder.value
+          };
+        }
+      );
+      const response = responseHolder.value;
+      if (!result.success) {
+        if (response !== null && !response.ok && response.code === result.error) return response;
+        return {
+          ok: false,
+          code: "PERSISTENCE_FAILED",
+          message: result.error ?? "Reward claim failed."
+        };
       }
+      if (response !== null && result.success) return response;
+      return {
+        ok: false,
+        code: "PERSISTENCE_FAILED",
+        message: result.error ?? "Reward claim failed."
+      };
     } catch (error) {
-      if (decremented) await this.#restoreRewardStock(persistence, request.rallyId, reward.id);
       return {
         ok: false,
         code: "PERSISTENCE_FAILED",
         message: error instanceof Error ? error.message : "Reward claim failed."
       };
     } finally {
-      await persistence.releaseLock(request.rallyId, lockKey);
+      await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
   async sync(rallyId, userId) {
@@ -535,8 +631,8 @@ var StampRallyServer = class {
     );
     return result;
   }
-  async #rememberClaim(key, result, request, timestamp, persistence = this.#persistence) {
-    await persistence.recordAuditLog(
+  async #rememberClaim(key, result, request, timestamp) {
+    await this.#persistence.recordAuditLog(
       audit(
         request.rallyId,
         request.userId,
@@ -548,7 +644,7 @@ var StampRallyServer = class {
         result.ok ? void 0 : result.code
       )
     );
-    await persistence.saveIdempotentResult(
+    await this.#persistence.saveIdempotentResult(
       request.rallyId,
       key,
       result,
@@ -556,13 +652,10 @@ var StampRallyServer = class {
     );
     return result;
   }
-  async #restoreRewardStock(persistence, rallyId, rewardId) {
-    if (persistence.restoreRewardStock !== void 0)
-      await persistence.restoreRewardStock(rallyId, rewardId);
-  }
 };
 
 exports.InMemoryServerPersistenceAdapter = InMemoryServerPersistenceAdapter;
 exports.StampRallyServer = StampRallyServer;
+exports.executeClaimRewardTransaction = executeClaimRewardTransaction;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map