@stamprally/server 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -2,20 +2,36 @@ import * as _stamprally_core from '@stamprally/core';
 import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
 export { UserRallyState } from '@stamprally/core';
 
+interface UserClaimRecord {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly rewardId: string;
+    readonly ticketNumber: string;
+    readonly timestamp: number;
+}
 interface ServerPersistenceAdapter {
-    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
-    releaseLock(lockKey: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
+    /** Runs the callback in a storage-native transaction when supported. */
+    runTransaction?<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, lockKey: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    incrementRewardStock(rewardId: string): Promise<void>;
-    getIdempotentResult<T>(key: string): Promise<T | null>;
-    saveIdempotentResult<T>(key: string, result: T, ttlMs: number): Promise<void>;
+    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>;
+    recordUserClaim(params: UserClaimRecord): Promise<void>;
+    recordClaim?(params: UserClaimRecord): Promise<void>;
+    incrementUserClaimCount?(rallyId: string, userId: string, rewardId: string): Promise<void>;
     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>>;
@@ -23,21 +39,31 @@ interface InMemoryServerPersistenceOptions {
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
     constructor(options?: InMemoryServerPersistenceOptions);
-    acquireLock(key: string, ttlMs: number): Promise<boolean>;
-    releaseLock(key: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
+    acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, key: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
         success: boolean;
         remainingStock: number;
     }>;
-    incrementRewardStock(rewardId: string): Promise<void>;
-    getIdempotentResult<T>(key: string): Promise<T | null>;
-    saveIdempotentResult<T>(key: string, result: T, ttlMs: number): Promise<void>;
+    restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
+    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>;
-    recordClaim(rallyId: string, userId: string, rewardId: string): void;
+    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 = {
@@ -110,4 +136,4 @@ interface ServerOptions {
     readonly now?: () => string;
 }
 
-export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer };
+export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };

package/dist/index.d.ts

@@ -2,20 +2,36 @@ import * as _stamprally_core from '@stamprally/core';
 import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
 export { UserRallyState } from '@stamprally/core';
 
+interface UserClaimRecord {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly rewardId: string;
+    readonly ticketNumber: string;
+    readonly timestamp: number;
+}
 interface ServerPersistenceAdapter {
-    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
-    releaseLock(lockKey: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
+    /** Runs the callback in a storage-native transaction when supported. */
+    runTransaction?<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, lockKey: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
         readonly success: boolean;
         readonly remainingStock: number;
     }>;
-    incrementRewardStock(rewardId: string): Promise<void>;
-    getIdempotentResult<T>(key: string): Promise<T | null>;
-    saveIdempotentResult<T>(key: string, result: T, ttlMs: number): Promise<void>;
+    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>;
+    recordUserClaim(params: UserClaimRecord): Promise<void>;
+    recordClaim?(params: UserClaimRecord): Promise<void>;
+    incrementUserClaimCount?(rallyId: string, userId: string, rewardId: string): Promise<void>;
     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>>;
@@ -23,21 +39,31 @@ interface InMemoryServerPersistenceOptions {
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
     constructor(options?: InMemoryServerPersistenceOptions);
-    acquireLock(key: string, ttlMs: number): Promise<boolean>;
-    releaseLock(key: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
+    acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, key: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
         success: boolean;
         remainingStock: number;
     }>;
-    incrementRewardStock(rewardId: string): Promise<void>;
-    getIdempotentResult<T>(key: string): Promise<T | null>;
-    saveIdempotentResult<T>(key: string, result: T, ttlMs: number): Promise<void>;
+    restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
+    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>;
-    recordClaim(rallyId: string, userId: string, rewardId: string): void;
+    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 = {
@@ -110,4 +136,4 @@ interface ServerOptions {
     readonly now?: () => string;
 }
 
-export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer };
+export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };

package/dist/index.js

@@ -6,42 +6,73 @@ var InMemoryServerPersistenceAdapter = class {
   #idempotent = /* @__PURE__ */ new Map();
   #states = /* @__PURE__ */ new Map();
   #stocks;
+  #stockDefaults;
   #claims = /* @__PURE__ */ new Map();
+  #claimRecords = [];
   #auditLogs = [];
   constructor(options = {}) {
-    this.#stocks = new Map(Object.entries(options.stocks ?? {}));
+    this.#stocks = /* @__PURE__ */ new Map();
+    this.#stockDefaults = /* @__PURE__ */ new Map();
+    for (const [key, stock] of Object.entries(options.stocks ?? {})) {
+      if (key.includes(":")) this.#stocks.set(key, stock);
+      else this.#stockDefaults.set(key, stock);
+    }
+  }
+  #key(rallyId, key) {
+    return `${rallyId}:${key}`;
+  }
+  #stockKey(rallyId, rewardId) {
+    const scopedKey = `${rallyId}:${rewardId}`;
+    if (this.#stocks.has(scopedKey)) return scopedKey;
+    const defaultStock = this.#stockDefaults.get(rewardId);
+    if (defaultStock !== void 0) {
+      this.#stocks.set(scopedKey, defaultStock);
+      return scopedKey;
+    }
+    return scopedKey;
   }
-  async acquireLock(key, ttlMs) {
+  async acquireLock(rallyId, key, ttlMs) {
+    const scopedKey = this.#key(rallyId, key);
     const now2 = Date.now();
-    const until = this.#locks.get(key);
+    const until = this.#locks.get(scopedKey);
     if (until !== void 0 && until > now2) return false;
-    this.#locks.set(key, now2 + Math.max(1, ttlMs));
+    this.#locks.set(scopedKey, now2 + Math.max(1, ttlMs));
     return true;
   }
-  async releaseLock(key) {
-    this.#locks.delete(key);
+  async releaseLock(rallyId, key) {
+    this.#locks.delete(this.#key(rallyId, key));
+  }
+  async getRewardStock(rallyId, rewardId) {
+    return this.#stocks.get(this.#stockKey(rallyId, rewardId)) ?? null;
   }
-  async decrementRewardStock(rewardId) {
-    const current = this.#stocks.get(rewardId);
+  async decrementRewardStock(rallyId, rewardId) {
+    const key = this.#stockKey(rallyId, rewardId);
+    const current = this.#stocks.get(key);
     if (current === void 0) return { success: true, remainingStock: Number.POSITIVE_INFINITY };
     if (current <= 0) return { success: false, remainingStock: 0 };
-    this.#stocks.set(rewardId, current - 1);
+    this.#stocks.set(key, current - 1);
     return { success: true, remainingStock: current - 1 };
   }
-  async incrementRewardStock(rewardId) {
-    const current = this.#stocks.get(rewardId);
-    if (current !== void 0) this.#stocks.set(rewardId, current + 1);
+  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 + Math.max(0, count));
+  }
+  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(key) {
-    const value = this.#idempotent.get(key);
+  async getIdempotentResult(rallyId, key) {
+    const value = this.#idempotent.get(this.#key(rallyId, key));
     if (value === void 0 || value.expiresAt <= Date.now()) {
-      this.#idempotent.delete(key);
+      this.#idempotent.delete(this.#key(rallyId, key));
       return null;
     }
     return structuredClone(value.value);
   }
-  async saveIdempotentResult(key, result, ttlMs) {
-    this.#idempotent.set(key, {
+  async saveIdempotentResult(rallyId, key, result, ttlMs) {
+    this.#idempotent.set(this.#key(rallyId, key), {
       value: structuredClone(result),
       expiresAt: Date.now() + Math.max(1, ttlMs)
     });
@@ -59,13 +90,72 @@ 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);
   }
-  recordClaim(rallyId, userId, rewardId) {
+  async recordUserClaim(params) {
+    const { rallyId, userId, rewardId } = params;
+    const key = `${rallyId}:${userId}:${rewardId}`;
+    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);
   }
+  getClaimRecords() {
+    return structuredClone(this.#claimRecords);
+  }
+  recordClaim(paramsOrRallyId, userId, rewardId) {
+    const params = typeof paramsOrRallyId === "string" ? {
+      rallyId: paramsOrRallyId,
+      userId: userId ?? "",
+      rewardId: rewardId ?? "",
+      ticketNumber: "",
+      timestamp: Date.now()
+    } : 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), {
@@ -177,10 +267,17 @@ var StampRallyServer = class {
   }
   async checkIn(request) {
     const key = `check-in:${request.rallyId}:${request.userId}:${request.idempotencyKey}`;
-    const previous = await this.#persistence.getIdempotentResult(key);
+    const previous = await this.#persistence.getIdempotentResult(
+      request.rallyId,
+      key
+    );
     if (previous !== null) return previous;
     const lockKey = `state:${request.rallyId}:${request.userId}`;
-    if (!await this.#persistence.acquireLock(lockKey, this.#options.lockTtlMs ?? 5e3))
+    if (!await this.#persistence.acquireLock(
+      request.rallyId,
+      lockKey,
+      this.#options.lockTtlMs ?? 5e3
+    ))
       return { ok: false, code: "CONFLICT", message: "The user state is being updated." };
     const timestamp = now(this.#options, request.now);
     try {
@@ -264,12 +361,20 @@ var StampRallyServer = class {
         timestamp
       );
     } finally {
-      await this.#persistence.releaseLock(lockKey);
+      await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
   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 this.#persistence.getIdempotentResult(key);
+    const previous = await 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)
@@ -277,18 +382,24 @@ var StampRallyServer = class {
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
         request,
-        now(this.#options, request.now)
+        now(this.#options, request.now),
+        persistence
       );
     const lockKey = `reward:${request.rallyId}:${reward.id}`;
-    if (!await this.#persistence.acquireLock(lockKey, this.#options.lockTtlMs ?? 5e3))
+    if (!await 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 this.#persistence.getIdempotentResult(key);
+      const checked = await 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(
+      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(
         request.rallyId,
         request.userId,
         reward.id
@@ -311,15 +422,17 @@ var StampRallyServer = class {
           key,
           { ok: false, code: local.error.code, message: "Reward cannot be claimed." },
           request,
-          timestamp
+          timestamp,
+          persistence
         );
-      const stock = await this.#persistence.decrementRewardStock(reward.id);
+      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
+          timestamp,
+          persistence
         );
       decremented = true;
       const next = {
@@ -328,41 +441,59 @@ var StampRallyServer = class {
         updatedAt: timestamp
       };
       try {
-        await this.#persistence.saveUserState(request.rallyId, request.userId, next);
+        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 };
-        await this.#persistence.recordAuditLog(
-          audit(
-            request.rallyId,
-            request.userId,
-            "CLAIM_REWARD",
-            reward.id,
-            request.idempotencyKey,
-            "SUCCESS",
-            timestamp
-          )
+        recordedTicket = local.value.claimTicketNumber ?? "";
+        await persistence.recordUserClaim({
+          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
         );
-        await this.#persistence.saveIdempotentResult(
+        successAuditId = successAudit.id;
+        await persistence.recordAuditLog(successAudit);
+        await persistence.saveIdempotentResult(
+          request.rallyId,
           key,
           response,
           this.#options.idempotencyTtlMs ?? 864e5
         );
-        if (this.#persistence instanceof Object && "recordClaim" in this.#persistence && typeof this.#persistence.recordClaim === "function")
-          this.#persistence.recordClaim(request.rallyId, request.userId, reward.id);
         return response;
       } catch (error) {
-        await this.#persistence.incrementRewardStock(reward.id);
+        if (recordedTicket !== null && persistence.rollbackUserClaim !== void 0)
+          await persistence.rollbackUserClaim(
+            request.rallyId,
+            request.userId,
+            reward.id,
+            recordedTicket
+          );
+        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;
       }
     } catch (error) {
-      if (decremented) await this.#persistence.incrementRewardStock(reward.id);
+      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 this.#persistence.releaseLock(lockKey);
+      await persistence.releaseLock(request.rallyId, lockKey);
     }
   }
   async sync(rallyId, userId) {
@@ -395,14 +526,15 @@ var StampRallyServer = class {
       )
     );
     await this.#persistence.saveIdempotentResult(
+      rallyId,
       key,
       result,
       this.#options.idempotencyTtlMs ?? 864e5
     );
     return result;
   }
-  async #rememberClaim(key, result, request, timestamp) {
-    await this.#persistence.recordAuditLog(
+  async #rememberClaim(key, result, request, timestamp, persistence = this.#persistence) {
+    await persistence.recordAuditLog(
       audit(
         request.rallyId,
         request.userId,
@@ -414,13 +546,18 @@ var StampRallyServer = class {
         result.ok ? void 0 : result.code
       )
     );
-    await this.#persistence.saveIdempotentResult(
+    await persistence.saveIdempotentResult(
+      request.rallyId,
       key,
       result,
       this.#options.idempotencyTtlMs ?? 864e5
     );
     return result;
   }
+  async #restoreRewardStock(persistence, rallyId, rewardId) {
+    if (persistence.restoreRewardStock !== void 0)
+      await persistence.restoreRewardStock(rallyId, rewardId);
+  }
 };
 
 export { InMemoryServerPersistenceAdapter, StampRallyServer };