@stamprally/server 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -9,7 +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 {
+    /**
+     * 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>;
@@ -17,7 +50,6 @@ interface ServerPersistenceAdapter {
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    restoreRewardStock?(rallyId: string, rewardId: 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>;
@@ -27,6 +59,7 @@ interface ServerPersistenceAdapter {
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
     recordAuditLog(log: AuditLog): Promise<void>;
+    removeAuditLog?(auditId: string): Promise<void>;
 }
 interface InMemoryServerPersistenceOptions {
     readonly stocks?: Readonly<Record<string, number>>;
@@ -41,20 +74,32 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         success: boolean;
         remainingStock: number;
     }>;
-    restoreRewardStock(rallyId: string, rewardId: string): Promise<void>;
+    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>;
     getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
     recordAuditLog(log: AuditLog): Promise<void>;
+    removeAuditLog(auditId: string): Promise<void>;
     getAuditLogs(): ReadonlyArray<AuditLog>;
     recordUserClaim(params: UserClaimRecord): Promise<void>;
+    rollbackUserClaim(rallyId: string, userId: string, rewardId: string, ticketNumber: string): Promise<void>;
     incrementUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<void>;
     getClaimRecords(): ReadonlyArray<UserClaimRecord>;
     /** @deprecated Use recordUserClaim with a ticket number and timestamp. */
     recordClaim(params: UserClaimRecord): Promise<void>;
     recordClaim(rallyId: string, userId: string, rewardId: string): Promise<void>;
+    runTransaction<T>(_rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
 }
 
 type ErrorResponse = {
@@ -127,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,7 +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 {
+    /**
+     * 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>;
@@ -17,7 +50,6 @@ interface ServerPersistenceAdapter {
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    restoreRewardStock?(rallyId: string, rewardId: 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>;
@@ -27,6 +59,7 @@ interface ServerPersistenceAdapter {
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
     recordAuditLog(log: AuditLog): Promise<void>;
+    removeAuditLog?(auditId: string): Promise<void>;
 }
 interface InMemoryServerPersistenceOptions {
     readonly stocks?: Readonly<Record<string, number>>;
@@ -41,20 +74,32 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         success: boolean;
         remainingStock: number;
     }>;
-    restoreRewardStock(rallyId: string, rewardId: string): Promise<void>;
+    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>;
     getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
     recordAuditLog(log: AuditLog): Promise<void>;
+    removeAuditLog(auditId: string): Promise<void>;
     getAuditLogs(): ReadonlyArray<AuditLog>;
     recordUserClaim(params: UserClaimRecord): Promise<void>;
+    rollbackUserClaim(rallyId: string, userId: string, rewardId: string, ticketNumber: string): Promise<void>;
     incrementUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<void>;
     getClaimRecords(): ReadonlyArray<UserClaimRecord>;
     /** @deprecated Use recordUserClaim with a ticket number and timestamp. */
     recordClaim(params: UserClaimRecord): Promise<void>;
     recordClaim(rallyId: string, userId: string, rewardId: string): Promise<void>;
+    runTransaction<T>(_rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
 }
 
 type ErrorResponse = {
@@ -127,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

@@ -53,10 +53,74 @@ var InMemoryServerPersistenceAdapter = class {
     this.#stocks.set(key, current - 1);
     return { success: true, remainingStock: current - 1 };
   }
-  async restoreRewardStock(rallyId, rewardId) {
+  async restoreRewardStock(rallyId, rewardId, count = 1) {
     const key = this.#stockKey(rallyId, rewardId);
     const current = this.#stocks.get(key);
-    if (current !== void 0) this.#stocks.set(key, current + 1);
+    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);
+    else this.#states.set(key, structuredClone(previousState));
   }
   async getIdempotentResult(rallyId, key) {
     const value = this.#idempotent.get(this.#key(rallyId, key));
@@ -85,6 +149,10 @@ var InMemoryServerPersistenceAdapter = class {
   async recordAuditLog(log) {
     this.#auditLogs.push(structuredClone(log));
   }
+  async removeAuditLog(auditId) {
+    const index = this.#auditLogs.findIndex((log) => log.id === auditId);
+    if (index >= 0) this.#auditLogs.splice(index, 1);
+  }
   getAuditLogs() {
     return structuredClone(this.#auditLogs);
   }
@@ -94,6 +162,16 @@ var InMemoryServerPersistenceAdapter = class {
     this.#claims.set(key, (this.#claims.get(key) ?? 0) + 1);
     this.#claimRecords.push(structuredClone(params));
   }
+  async rollbackUserClaim(rallyId, userId, rewardId, ticketNumber) {
+    const key = `${rallyId}:${userId}:${rewardId}`;
+    const count = this.#claims.get(key) ?? 0;
+    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
+    );
+    if (index >= 0) this.#claimRecords.splice(index, 1);
+  }
   async incrementUserClaimCount(rallyId, userId, rewardId) {
     const key = `${rallyId}:${userId}:${rewardId}`;
     this.#claims.set(key, (this.#claims.get(key) ?? 0) + 1);
@@ -111,6 +189,32 @@ var InMemoryServerPersistenceAdapter = class {
     } : paramsOrRallyId;
     return this.recordUserClaim(params);
   }
+  async runTransaction(_rallyId, operation) {
+    const snapshot = {
+      stocks: new Map(this.#stocks),
+      idempotent: new Map(this.#idempotent),
+      states: new Map(this.#states),
+      claims: new Map(this.#claims),
+      claimRecords: structuredClone(this.#claimRecords),
+      auditLogs: structuredClone(this.#auditLogs)
+    };
+    try {
+      return await operation(this);
+    } catch (error) {
+      this.#stocks.clear();
+      for (const [key, value] of snapshot.stocks) this.#stocks.set(key, value);
+      this.#idempotent.clear();
+      for (const [key, value] of snapshot.idempotent)
+        this.#idempotent.set(key, structuredClone(value));
+      this.#states.clear();
+      for (const [key, value] of snapshot.states) this.#states.set(key, structuredClone(value));
+      this.#claims.clear();
+      for (const [key, value] of snapshot.claims) this.#claims.set(key, value);
+      this.#claimRecords.splice(0, this.#claimRecords.length, ...snapshot.claimRecords);
+      this.#auditLogs.splice(0, this.#auditLogs.length, ...snapshot.auditLogs);
+      throw error;
+    }
+  }
 };
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), {
@@ -342,88 +446,108 @@ var StampRallyServer = class {
     ))
       return { ok: false, code: "CONFLICT", message: "The reward is being claimed." };
     const timestamp = now(this.#options, request.now);
-    let decremented = false;
     try {
       const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
         key
       );
       if (checked !== null) return checked;
-      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
-      const claimCount = await this.#persistence.getUserClaimCount(
-        request.rallyId,
-        request.userId,
-        reward.id
-      );
-      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
-        );
-      const stock = await this.#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
-        );
-      decremented = true;
-      const next = {
-        ...current,
-        rewards: current.rewards.map((item) => item.rewardId === reward.id ? local.value : item),
-        updatedAt: timestamp
-      };
-      try {
-        await this.#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 };
-        await this.#persistence.recordUserClaim({
+      const responseHolder = { value: null };
+      const result = await this.#persistence.executeClaimRewardTransaction(
+        {
           rallyId: request.rallyId,
           userId: request.userId,
           rewardId: reward.id,
-          ticketNumber: local.value.claimTicketNumber ?? "",
-          timestamp: Number.isNaN(Date.parse(timestamp)) ? Date.now() : Date.parse(timestamp)
-        });
-        await this.#persistence.recordAuditLog(
-          audit(
+          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,
             request.idempotencyKey,
-            "SUCCESS",
-            timestamp
-          )
-        );
-        await this.#persistence.saveIdempotentResult(
-          request.rallyId,
-          key,
-          response,
-          this.#options.idempotencyTtlMs ?? 864e5
-        );
-        return response;
-      } catch (error) {
-        await this.#restoreRewardStock(request.rallyId, reward.id);
-        decremented = false;
-        throw error;
+            status,
+            timestamp,
+            code
+          );
+          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(request.rallyId, reward.id);
       return {
         ok: false,
         code: "PERSISTENCE_FAILED",
@@ -491,10 +615,6 @@ var StampRallyServer = class {
     );
     return result;
   }
-  async #restoreRewardStock(rallyId, rewardId) {
-    if (this.#persistence.restoreRewardStock !== void 0)
-      await this.#persistence.restoreRewardStock(rallyId, rewardId);
-  }
 };
 
 export { InMemoryServerPersistenceAdapter, StampRallyServer };