@stamprally/server 0.12.0 → 0.14.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 (error2) {
+    return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+  }
+}
+
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
   #locks = /* @__PURE__ */ new Map();
@@ -115,8 +140,41 @@ var InMemoryServerPersistenceAdapter = class {
           );
         return { success: true };
       });
-    } catch (error) {
-      return { success: false, error: error instanceof Error ? error.message : String(error) };
+    } catch (error2) {
+      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
+    }
+  }
+  async executeCheckInTransaction(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({ userState });
+        if (mutationResult.error !== void 0) {
+          await this.recordAuditLog(mutationResult.auditLog);
+          if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+            await this.saveIdempotentResult(
+              params.rallyId,
+              params.idempotencyKey,
+              mutationResult.result,
+              params.idempotencyTtlMs ?? 864e5
+            );
+          return { success: false, error: mutationResult.error };
+        }
+        await this.saveUserState(params.rallyId, params.userId, mutationResult.nextUserState);
+        await this.recordAuditLog(mutationResult.auditLog);
+        if (params.idempotencyKey !== void 0 && mutationResult.result !== void 0)
+          await this.saveIdempotentResult(
+            params.rallyId,
+            params.idempotencyKey,
+            mutationResult.result,
+            params.idempotencyTtlMs ?? 864e5
+          );
+        return { success: true };
+      });
+    } catch (error2) {
+      return { success: false, error: error2 instanceof Error ? error2.message : String(error2) };
     }
   }
   async rollbackUserState(rallyId, userId, previousState) {
@@ -170,7 +228,7 @@ var InMemoryServerPersistenceAdapter = class {
     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
+      (record2) => record2.rallyId === rallyId && record2.userId === userId && record2.rewardId === rewardId && record2.ticketNumber === ticketNumber
     );
     if (index >= 0) this.#claimRecords.splice(index, 1);
   }
@@ -202,7 +260,7 @@ var InMemoryServerPersistenceAdapter = class {
     };
     try {
       return await operation(this);
-    } catch (error) {
+    } catch (error2) {
       this.#stocks.clear();
       for (const [key, value] of snapshot.stocks) this.#stocks.set(key, value);
       this.#idempotent.clear();
@@ -214,10 +272,63 @@ var InMemoryServerPersistenceAdapter = class {
       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;
+      throw error2;
     }
   }
 };
+
+// src/security.ts
+function error(path, message) {
+  return { success: false, errors: [{ path, message, code: "invalid_request" }] };
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function context(value) {
+  if (!record(value) || typeof value.type !== "string") return false;
+  if (value.type === "qr") return nonEmpty(value.token);
+  if (value.type === "passcode") return nonEmpty(value.code);
+  if (value.type === "nfc") return nonEmpty(value.tagId);
+  if (value.type === "custom") return "value" in value;
+  return value.type === "gps" && typeof value.latitude === "number" && Number.isFinite(value.latitude) && typeof value.longitude === "number" && Number.isFinite(value.longitude);
+}
+function common(value, fields) {
+  if (!record(value)) return false;
+  return fields.every((field) => nonEmpty(value[field]));
+}
+function validateCheckInRequest(value) {
+  if (!common(value, ["rallyId", "spotId", "idempotencyKey"]))
+    return error("$", "rallyId, spotId, and idempotencyKey must be non-empty strings.");
+  if (!context(value.context))
+    return error("context", "context is not a valid verification context.");
+  if (value.userId !== void 0 && !nonEmpty(value.userId))
+    return error("userId", "userId must be non-empty.");
+  if (value.now !== void 0 && !nonEmpty(value.now))
+    return error("now", "now must be non-empty when provided.");
+  return { success: true, data: value };
+}
+function validateClaimRewardRequest(value) {
+  if (!common(value, ["rallyId", "rewardId", "idempotencyKey"]))
+    return error("$", "rallyId, rewardId, and idempotencyKey must be non-empty strings.");
+  if (value.userId !== void 0 && !nonEmpty(value.userId))
+    return error("userId", "userId must be non-empty.");
+  if (value.staffPasscode !== void 0 && !nonEmpty(value.staffPasscode))
+    return error("staffPasscode", "staffPasscode must be non-empty.");
+  if (value.staffId !== void 0 && !nonEmpty(value.staffId))
+    return error("staffId", "staffId must be non-empty.");
+  if (value.now !== void 0 && !nonEmpty(value.now))
+    return error("now", "now must be non-empty when provided.");
+  return { success: true, data: value };
+}
+function validateSyncRequest(value) {
+  if (!common(value, ["rallyId"])) return error("rallyId", "rallyId must be a non-empty string.");
+  if (value.userId !== void 0 && !nonEmpty(value.userId))
+    return error("userId", "userId must be non-empty.");
+  return { success: true, data: value };
+}
 function json(body, status = 200) {
   return new Response(JSON.stringify(body), {
     status,
@@ -230,8 +341,12 @@ function isObject(value) {
 function requestId(prefix) {
   return `${prefix}-${globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`}`;
 }
-function now(options, requested) {
-  return requested ?? options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
+function now(options) {
+  return options.now?.() ?? (/* @__PURE__ */ new Date()).toISOString();
+}
+function timestampMillis(timestamp) {
+  const value = Date.parse(timestamp);
+  return Number.isFinite(value) ? value : Date.now();
 }
 function initialState(config, userId, timestamp) {
   return {
@@ -242,16 +357,16 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
-function getProof(context) {
-  return context.type === "qr" ? context.token : context.type === "passcode" ? context.code : context.type === "gps" ? { latitude: context.latitude, longitude: context.longitude } : context.type === "nfc" ? context.tagId : context.value;
+function getProof(context2) {
+  return context2.type === "qr" ? context2.token : context2.type === "passcode" ? context2.code : context2.type === "gps" ? { latitude: context2.latitude, longitude: context2.longitude } : context2.type === "nfc" ? context2.tagId : context2.value;
 }
-async function evaluate(condition, context, validator, base) {
-  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context).ok;
+async function evaluate(condition, context2, validator, base) {
+  if (condition.type !== "custom") return core.evaluateConditionDetailed(condition, context2).ok;
   if (validator === void 0) return false;
   const validationContext = {
     rallyId: base.rallyId,
     spotId: base.spotId,
-    proofData: getProof(context),
+    proofData: getProof(context2),
     condition,
     userState: base.state
   };
@@ -271,6 +386,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;
@@ -290,41 +409,51 @@ var StampRallyServer = class {
     return json({ ok: false, code: "NOT_FOUND", message: "Route not found." }, 404);
   }
   async handleCheckIn(request) {
-    const body = await this.#body(request);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id || body.spotId === "" || body.idempotencyKey === "" || body.context === void 0)
+    const body = validateCheckInRequest(await this.#body(request));
+    if (!body.success || body.data.rallyId !== this.#config.id)
       return json(
-        {
-          ok: false,
-          code: "INVALID_REQUEST",
-          message: "rallyId, spotId, context, and idempotencyKey are required."
-        },
+        { ok: false, code: "INVALID_REQUEST", message: "Invalid check-in request." },
         400
       );
-    const result = await this.checkIn({ ...body, userId });
-    return json(result, result.ok ? 200 : result.code === "SPOT_NOT_FOUND" ? 404 : 422);
+    const userId = await this.#user(request);
+    if (userId === null)
+      return json(
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
+      );
+    const result = await this.checkIn({ ...body.data, userId });
+    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);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id || body.rewardId === "" || body.idempotencyKey === "")
+    const body = validateClaimRewardRequest(await this.#body(request));
+    if (!body.success || body.data.rallyId !== this.#config.id)
+      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid reward request." }, 400);
+    const userId = await this.#user(request);
+    if (userId === null)
       return json(
-        {
-          ok: false,
-          code: "INVALID_REQUEST",
-          message: "rallyId, rewardId, and idempotencyKey are required."
-        },
-        400
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
       );
-    const result = await this.claimReward({ ...body, userId });
-    return json(result, result.ok ? 200 : result.code === "REWARD_NOT_FOUND" ? 404 : 422);
+    const result = await this.claimReward({ ...body.data, userId });
+    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);
-    const userId = await this.#user(request, body?.userId);
-    if (body === null || userId === null || body.rallyId !== this.#config.id)
-      return json({ ok: false, code: "INVALID_REQUEST", message: "rallyId is required." }, 400);
-    return json({ ok: true, state: await this.sync(body.rallyId, userId) });
+    const body = validateSyncRequest(await this.#body(request));
+    if (!body.success || body.data.rallyId !== this.#config.id)
+      return json({ ok: false, code: "INVALID_REQUEST", message: "Invalid sync request." }, 400);
+    const userId = await this.#user(request);
+    if (userId === null)
+      return json(
+        { ok: false, code: "UNAUTHENTICATED", message: "Authentication is required." },
+        401
+      );
+    return json({ ok: true, state: await this.sync(body.data.rallyId, userId) });
   }
   async checkIn(request) {
     const key = `check-in:${request.rallyId}:${request.userId}:${request.idempotencyKey}`;
@@ -340,47 +469,68 @@ var StampRallyServer = class {
       this.#options.lockTtlMs ?? 5e3
     ))
       return { ok: false, code: "CONFLICT", message: "The user state is being updated." };
-    const timestamp = now(this.#options, request.now);
+    const timestamp = now(this.#options);
     try {
+      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
+      const responseHolder = { value: null };
+      const makeAudit = (status, code) => audit(
+        request.rallyId,
+        request.userId,
+        "CHECK_IN",
+        request.spotId,
+        request.idempotencyKey,
+        status,
+        timestamp,
+        code
+      );
       const spot = this.#config.spots.find((item) => item.id === request.spotId);
-      if (spot === void 0)
-        return this.#remember(
+      if (spot === void 0) {
+        responseHolder.value = {
+          ok: false,
+          code: "SPOT_NOT_FOUND",
+          message: "Spot was not found."
+        };
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          { ok: false, code: "SPOT_NOT_FOUND", message: "Spot was not found." },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          {
+            nextUserState: current,
+            auditLog: makeAudit("REJECTED", "SPOT_NOT_FOUND"),
+            result: responseHolder.value,
+            error: "SPOT_NOT_FOUND"
+          },
+          responseHolder
         );
-      const current = await this.#persistence.getUserState(request.rallyId, request.userId) ?? initialState(this.#config, request.userId, timestamp);
-      if (current.records.some((record) => record.stampId === request.spotId))
-        return this.#remember(
+      }
+      const rejected = (code, message) => {
+        responseHolder.value = { ok: false, code, message };
+        return {
+          nextUserState: current,
+          auditLog: makeAudit("REJECTED", code),
+          result: responseHolder.value,
+          error: code
+        };
+      };
+      if (current.records.some((record2) => record2.stampId === request.spotId))
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          { ok: false, code: "STAMP_ALREADY_ACQUIRED", message: "Spot was already claimed." },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          rejected("STAMP_ALREADY_ACQUIRED", "Spot was already claimed."),
+          responseHolder
         );
-      const acquired = new Set(current.records.map((record) => record.stampId));
+      const acquired = new Set(current.records.map((record2) => record2.stampId));
       if (spot.prerequisites?.some((id) => !acquired.has(id)))
-        return this.#remember(
+        return await this.#rememberCheckInTransaction(
+          request,
+          timestamp,
           key,
-          {
-            ok: false,
-            code: "PREREQUISITES_NOT_MET",
-            message: "Prerequisite spots are not complete."
-          },
-          request.rallyId,
-          request.userId,
-          "CHECK_IN",
-          request.spotId,
-          request.idempotencyKey,
-          timestamp
+          current,
+          rejected("PREREQUISITES_NOT_MET", "Prerequisite spots are not complete."),
+          responseHolder
         );
       for (const condition of spot.conditions)
         if (!await evaluate(
@@ -389,15 +539,13 @@ var StampRallyServer = class {
           condition.type === "custom" ? this.#options.customValidators?.[condition.validatorName] : void 0,
           { rallyId: request.rallyId, spotId: request.spotId, state: current }
         ))
-          return this.#remember(
+          return await this.#rememberCheckInTransaction(
+            request,
+            timestamp,
             key,
-            { ok: false, code: "INVALID_PROOF", message: "Verification failed." },
-            request.rallyId,
-            request.userId,
-            "CHECK_IN",
-            request.spotId,
-            request.idempotencyKey,
-            timestamp
+            current,
+            rejected("INVALID_PROOF", "Verification failed."),
+            responseHolder
           );
       const next = {
         ...current,
@@ -410,17 +558,30 @@ var StampRallyServer = class {
         ),
         updatedAt: timestamp
       };
-      await this.#persistence.saveUserState(request.rallyId, request.userId, next);
-      return this.#remember(
-        key,
-        { ok: true, state: next },
-        request.rallyId,
-        request.userId,
-        "CHECK_IN",
-        request.spotId,
-        request.idempotencyKey,
-        timestamp
+      responseHolder.value = { ok: true, state: next };
+      const transaction = await this.#persistence.executeCheckInTransaction(
+        {
+          rallyId: request.rallyId,
+          userId: request.userId,
+          spotId: request.spotId,
+          timestamp: timestampMillis(timestamp),
+          idempotencyKey: key,
+          proofData: request.context,
+          ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
+          initialUserState: current
+        },
+        () => ({
+          nextUserState: next,
+          auditLog: makeAudit("SUCCESS"),
+          result: responseHolder.value
+        })
       );
+      if (transaction.success && responseHolder.value !== null) return responseHolder.value;
+      return {
+        ok: false,
+        code: "PERSISTENCE_FAILED",
+        message: transaction.error ?? "Check-in failed."
+      };
     } finally {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
@@ -438,7 +599,7 @@ var StampRallyServer = class {
         key,
         { ok: false, code: "REWARD_NOT_FOUND", message: "Reward was not found." },
         request,
-        now(this.#options, request.now)
+        now(this.#options)
       );
     const lockKey = `reward:${request.rallyId}:${reward.id}`;
     if (!await this.#persistence.acquireLock(
@@ -447,7 +608,7 @@ var StampRallyServer = class {
       this.#options.lockTtlMs ?? 5e3
     ))
       return { ok: false, code: "CONFLICT", message: "The reward is being claimed." };
-    const timestamp = now(this.#options, request.now);
+    const timestamp = now(this.#options);
     try {
       const checked = await this.#persistence.getIdempotentResult(
         request.rallyId,
@@ -497,8 +658,9 @@ var StampRallyServer = class {
               error: "OUT_OF_STOCK"
             };
           }
+          const effectiveReward = reward.staffPasscode === void 0 && this.#config.staffPasscode !== void 0 ? { ...reward, staffPasscode: this.#config.staffPasscode } : reward;
           const local = core.consumeReward({
-            reward,
+            reward: effectiveReward,
             currentState: currentReward,
             now: timestamp,
             userRedemptionCount: claimCount,
@@ -549,11 +711,11 @@ var StampRallyServer = class {
         code: "PERSISTENCE_FAILED",
         message: result.error ?? "Reward claim failed."
       };
-    } catch (error) {
+    } catch (error2) {
       return {
         ok: false,
         code: "PERSISTENCE_FAILED",
-        message: error instanceof Error ? error.message : "Reward claim failed."
+        message: error2 instanceof Error ? error2.message : "Reward claim failed."
       };
     } finally {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
@@ -570,31 +732,36 @@ var StampRallyServer = class {
       return null;
     }
   }
-  async #user(request, requested) {
-    if (this.#options.authenticate !== void 0)
-      return await this.#options.authenticate(request) ?? null;
-    return requested ?? null;
-  }
-  async #remember(key, result, rallyId, userId, action, resourceId, idempotencyKey, timestamp) {
-    await this.#persistence.recordAuditLog(
-      audit(
-        rallyId,
-        userId,
-        action,
-        resourceId,
-        idempotencyKey,
-        result.ok ? "SUCCESS" : "REJECTED",
-        timestamp,
-        result.ok ? void 0 : result.code
-      )
-    );
-    await this.#persistence.saveIdempotentResult(
-      rallyId,
-      key,
-      result,
-      this.#options.idempotencyTtlMs ?? 864e5
+  async #user(request) {
+    if (this.#options.authenticate !== void 0) {
+      const identity = await this.#options.authenticate(request);
+      if (typeof identity === "string") return identity.length > 0 ? identity : null;
+      if (identity === null) return null;
+      const authenticatedUserId = identity.authenticatedUserId;
+      return authenticatedUserId.length > 0 ? authenticatedUserId : null;
+    }
+    return "anonymous";
+  }
+  async #rememberCheckInTransaction(request, timestamp, key, current, mutation, responseHolder) {
+    const transaction = await this.#persistence.executeCheckInTransaction(
+      {
+        rallyId: request.rallyId,
+        userId: request.userId,
+        spotId: request.spotId,
+        timestamp: timestampMillis(timestamp),
+        idempotencyKey: key,
+        ...this.#options.idempotencyTtlMs === void 0 ? {} : { idempotencyTtlMs: this.#options.idempotencyTtlMs },
+        initialUserState: current
+      },
+      () => mutation
     );
-    return result;
+    if (responseHolder.value !== null && (transaction.success || transaction.error === mutation.error))
+      return responseHolder.value;
+    return {
+      ok: false,
+      code: "PERSISTENCE_FAILED",
+      message: transaction.error ?? "Check-in failed."
+    };
   }
   async #rememberClaim(key, result, request, timestamp) {
     await this.#persistence.recordAuditLog(
@@ -621,5 +788,9 @@ var StampRallyServer = class {
 
 exports.InMemoryServerPersistenceAdapter = InMemoryServerPersistenceAdapter;
 exports.StampRallyServer = StampRallyServer;
+exports.executeClaimRewardTransaction = executeClaimRewardTransaction;
+exports.validateCheckInRequest = validateCheckInRequest;
+exports.validateClaimRewardRequest = validateClaimRewardRequest;
+exports.validateSyncRequest = validateSyncRequest;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map