@stamprally/server 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -9,9 +9,40 @@ interface UserClaimRecord {
     readonly ticketNumber: string;
     readonly timestamp: number;
 }
+interface ClaimRewardTransactionParams {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly rewardId: string;
+    readonly ticketNumber: string;
+    readonly timestamp: number;
+    readonly idempotencyKey?: string;
+    readonly proofData?: unknown;
+    readonly idempotencyTtlMs?: number;
+    /** Used when the first claim is made before a user state has been stored. */
+    readonly initialUserState?: UserRallyState;
+}
+interface ClaimRewardTransactionMutation {
+    readonly nextStock: number | null;
+    readonly nextUserState: UserRallyState;
+    readonly auditLog: AuditLog;
+    /** The server response is persisted by the adapter with the idempotency key. */
+    readonly result?: unknown;
+    /** A domain rejection is committed as an audit/idempotency record without mutations. */
+    readonly error?: string;
+}
 interface ServerPersistenceAdapter {
-    /** Runs the callback in a storage-native transaction when supported. */
-    runTransaction?<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Atomically commits stock, user state, claim count, audit log, and idempotency data.
+     * Adapters must roll back every write when the callback or any commit operation fails.
+     */
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
+        readonly stock: number | null;
+        readonly claimCount: number;
+        readonly userState: UserRallyState;
+    }) => ClaimRewardTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, lockKey: string): Promise<void>;
     getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
@@ -19,9 +50,6 @@ interface ServerPersistenceAdapter {
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    restoreRewardStock?(rallyId: string, rewardId: string, count?: number): Promise<void>;
-    rollbackUserState?(rallyId: string, userId: string, previousState: UserRallyState | null): Promise<void>;
-    rollbackUserClaim?(rallyId: string, userId: string, rewardId: string, ticketNumber: string): Promise<void>;
     getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
     saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
     getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
@@ -47,6 +75,14 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         remainingStock: number;
     }>;
     restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
+        readonly stock: number | null;
+        readonly claimCount: number;
+        readonly userState: UserRallyState;
+    }) => ClaimRewardTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     rollbackUserState(rallyId: string, userId: string, previousState: UserRallyState | null): Promise<void>;
     getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
     saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
@@ -136,4 +172,4 @@ interface ServerOptions {
     readonly now?: () => string;
 }
 
-export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };
+export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };

package/dist/index.d.ts

@@ -9,9 +9,40 @@ interface UserClaimRecord {
     readonly ticketNumber: string;
     readonly timestamp: number;
 }
+interface ClaimRewardTransactionParams {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly rewardId: string;
+    readonly ticketNumber: string;
+    readonly timestamp: number;
+    readonly idempotencyKey?: string;
+    readonly proofData?: unknown;
+    readonly idempotencyTtlMs?: number;
+    /** Used when the first claim is made before a user state has been stored. */
+    readonly initialUserState?: UserRallyState;
+}
+interface ClaimRewardTransactionMutation {
+    readonly nextStock: number | null;
+    readonly nextUserState: UserRallyState;
+    readonly auditLog: AuditLog;
+    /** The server response is persisted by the adapter with the idempotency key. */
+    readonly result?: unknown;
+    /** A domain rejection is committed as an audit/idempotency record without mutations. */
+    readonly error?: string;
+}
 interface ServerPersistenceAdapter {
-    /** Runs the callback in a storage-native transaction when supported. */
-    runTransaction?<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    /**
+     * Atomically commits stock, user state, claim count, audit log, and idempotency data.
+     * Adapters must roll back every write when the callback or any commit operation fails.
+     */
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
+        readonly stock: number | null;
+        readonly claimCount: number;
+        readonly userState: UserRallyState;
+    }) => ClaimRewardTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, lockKey: string): Promise<void>;
     getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
@@ -19,9 +50,6 @@ interface ServerPersistenceAdapter {
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    restoreRewardStock?(rallyId: string, rewardId: string, count?: number): Promise<void>;
-    rollbackUserState?(rallyId: string, userId: string, previousState: UserRallyState | null): Promise<void>;
-    rollbackUserClaim?(rallyId: string, userId: string, rewardId: string, ticketNumber: string): Promise<void>;
     getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
     saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
     getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
@@ -47,6 +75,14 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         remainingStock: number;
     }>;
     restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
+        readonly stock: number | null;
+        readonly claimCount: number;
+        readonly userState: UserRallyState;
+    }) => ClaimRewardTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     rollbackUserState(rallyId: string, userId: string, previousState: UserRallyState | null): Promise<void>;
     getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
     saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
@@ -136,4 +172,4 @@ interface ServerOptions {
     readonly now?: () => string;
 }
 
-export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };
+export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };

package/dist/index.js

@@ -58,6 +58,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);
@@ -365,16 +424,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)
@@ -382,118 +436,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 = 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 = 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) {
@@ -533,8 +594,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,
@@ -546,7 +607,7 @@ var StampRallyServer = class {
         result.ok ? void 0 : result.code
       )
     );
-    await persistence.saveIdempotentResult(
+    await this.#persistence.saveIdempotentResult(
       request.rallyId,
       key,
       result,
@@ -554,10 +615,6 @@ var StampRallyServer = class {
     );
     return result;
   }
-  async #restoreRewardStock(persistence, rallyId, rewardId) {
-    if (persistence.restoreRewardStock !== void 0)
-      await persistence.restoreRewardStock(rallyId, rewardId);
-  }
 };
 
 export { InMemoryServerPersistenceAdapter, StampRallyServer };