@stamprally/server 0.18.0 → 0.20.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/server v0.18.0
+# @stamprally/server v0.20.0
 
 Web Standard `Request` / `Response` handlers for server-authoritative check-ins and reward claims.
 
@@ -26,6 +26,31 @@ Configure `anonymousPolicy: "session_scoped"` to use the UUID v4 from the
 HTTP 401 when no authenticated identity is present. Request validation failures use
 HTTP 400 with `{ error: "VALIDATION_FAILED", details: [...] }`.
 
+## Batch sync and trusted authentication
+
+`syncProgress(request, authContext)` evaluates `operations` by their request
+timestamp, preserving FIFO order for equal timestamps, and returns
+`{ results, currentState, syncTimestamp }`. A permanently rejected
+operation does not stop unrelated operations; a later operation depending on that
+resource receives `REJECTED_PREREQUISITE_FAILED`. Retryable failures are returned
+as `FAILED_RETRYABLE` so the client can retain them for the next request.
+
+Direct server calls require a verified `TrustedAuthContext`:
+
+```ts
+const progress = await server.syncProgress(
+  { rallyId: "city-tour", operations },
+  { authenticatedUserId: session.userId, claims: session.claims },
+);
+```
+
+The context identity is authoritative and overrides any caller-supplied `userId`.
+For inventory, `stockKey` selects the primary bucket and `secondaryStockKey`
+selects an additional bucket that must be decremented in the same transaction.
+An adapter using a secondary key must expose `supportsSecondaryStock: true` and
+persist both buckets atomically; otherwise the claim fails closed with
+`SECONDARY_STOCK_UNSUPPORTED`.
+
 Hono can mount the handler directly because it accepts the same Web Standard request and response types.
 
 ## License

package/dist/index.cjs

@@ -4,9 +4,13 @@ var core = require('@stamprally/core');
 
 // src/examples/transaction.ts
 async function executeClaimRewardTransaction(database, store, params2, mutation2) {
+  if (params2.secondaryStockKey !== void 0 && store.writeSecondaryStock === void 0)
+    return { success: false, error: "SECONDARY_STOCK_UNSUPPORTED" };
   try {
     return await database.transaction(async (transaction) => {
       const current = await store.readContext(transaction, params2);
+      if (params2.secondaryStockKey !== void 0 && current.secondaryStock === void 0)
+        return { success: false, error: "SECONDARY_STOCK_UNSUPPORTED" };
       const secondaryStock = current.secondaryStock ?? null;
       const rewardStock2 = params2.stockKey === "__shared__" ? secondaryStock : current.stock;
       const next = mutation2({
@@ -598,6 +602,40 @@ function validateSyncRequest(value) {
     return errors({ path: "$", message: "Expected an object.", code: "INVALID_TYPE" });
   if (value.userId !== void 0 && !nonEmpty(value.userId))
     return errors({ path: "userId", message: "userId must be non-empty.", code: "INVALID_TYPE" });
+  if (value.operations !== void 0) {
+    if (!Array.isArray(value.operations))
+      return errors({
+        path: "operations",
+        message: "operations must be an array.",
+        code: "INVALID_TYPE"
+      });
+    const operationErrors = [];
+    value.operations.forEach((operation, index) => {
+      const path = `operations[${index}]`;
+      if (!record(operation)) {
+        operationErrors.push({
+          path,
+          message: "Expected an operation object.",
+          code: "INVALID_TYPE"
+        });
+        return;
+      }
+      if (operation.kind !== "checkIn" && operation.kind !== "claimReward") {
+        operationErrors.push({
+          path: `${path}.kind`,
+          message: "Unknown sync operation.",
+          code: "INVALID_ENUM"
+        });
+        return;
+      }
+      const result = operation.kind === "checkIn" ? validateCheckInRequest(operation.request) : validateClaimRewardRequest(operation.request);
+      if (!result.success)
+        operationErrors.push(
+          ...result.errors.map((error) => ({ ...error, path: `${path}.request.${error.path}` }))
+        );
+    });
+    if (operationErrors.length > 0) return errors(...operationErrors);
+  }
   return {
     success: true,
     data: value
@@ -625,6 +663,15 @@ function timestampMillis(timestamp) {
   const value = Date.parse(timestamp);
   return Number.isFinite(value) ? value : Date.now();
 }
+function operationTimestamp(operation) {
+  const value = operation.request.now;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return Number.MAX_SAFE_INTEGER;
+}
 function validationResponse(errors2) {
   return json(
     {
@@ -712,6 +759,38 @@ function operationStatus(result) {
   if (result.ok) return "ACCEPTED";
   return result.code === "CONFLICT" || result.code === "PERSISTENCE_FAILED" ? "RETRYABLE_ERROR" : "REJECTED_PERMANENT";
 }
+function syncOperationId(operation, userId) {
+  return `${operation.kind}:${operation.request.rallyId}:${userId}:${operation.request.idempotencyKey}`;
+}
+function syncOperationResult(operation, userId, result) {
+  const operationId = syncOperationId(operation, userId);
+  const resourceId = operation.kind === "checkIn" ? operation.request.spotId : operation.request.rewardId;
+  const action = operation.kind === "checkIn" ? "CHECK_IN" : "CLAIM_REWARD";
+  const status = operationStatus(result);
+  if (status === "ACCEPTED") {
+    return {
+      operationId,
+      status,
+      resourceId,
+      action,
+      appliedAt: timestampMillis(result.ok ? result.state.updatedAt : "")
+    };
+  }
+  if (status === "RETRYABLE_ERROR")
+    return {
+      operationId,
+      status: "FAILED_RETRYABLE",
+      resourceId,
+      error: result.ok ? "The operation can be retried." : result.message
+    };
+  return {
+    operationId,
+    status,
+    resourceId,
+    errorCode: result.ok ? "REJECTED_PERMANENT" : result.code,
+    reason: result.ok ? "The operation was rejected." : result.message
+  };
+}
 function withDirectIdentity(request, authContext) {
   if (authContext !== void 0) {
     if (authContext.authenticatedUserId.trim() === "")
@@ -844,15 +923,17 @@ var StampRallyServer = class {
       ...sessionId === null ? {} : { isAnonymous: true, sessionId }
     };
     try {
+      const progress = await this.syncProgress(
+        {
+          rallyId: body.data.rallyId,
+          ...body.data.operations === void 0 ? {} : { operations: body.data.operations },
+          ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+        },
+        authContext
+      );
       return json({
         ok: true,
-        state: await this.syncProgress(
-          {
-            rallyId: body.data.rallyId,
-            ...sessionId === null ? {} : { anonymousSessionId: sessionId }
-          },
-          authContext
-        )
+        ...progress
       });
     } catch (error) {
       if (error instanceof RequestValidationException) return validationResponse(error.errors);
@@ -1189,7 +1270,39 @@ var StampRallyServer = class {
   async syncProgress(request, authContext) {
     const directRequest = withDirectIdentity(request, authContext);
     assertValidSyncParams(directRequest, this.#config);
-    return this.sync(directRequest.rallyId, authContext);
+    const results = [];
+    const rejectedCheckIns = /* @__PURE__ */ new Set();
+    const operations = [...request.operations ?? []].map((operation, index) => ({ operation, index })).sort(
+      (left, right) => operationTimestamp(left.operation) - operationTimestamp(right.operation) || left.index - right.index
+    ).map(({ operation }) => operation);
+    for (const operation of operations) {
+      const resourceId = operation.kind === "checkIn" ? operation.request.spotId : operation.request.rewardId;
+      if (operation.kind === "checkIn") {
+        const spot = this.#config.spots.find((candidate) => candidate.id === resourceId);
+        if (spot?.prerequisites?.some((prerequisite) => rejectedCheckIns.has(prerequisite))) {
+          results.push({
+            operationId: syncOperationId(operation, directRequest.userId),
+            status: "REJECTED_PERMANENT",
+            resourceId,
+            errorCode: "REJECTED_PREREQUISITE_FAILED",
+            reason: "A prerequisite operation was rejected by the server."
+          });
+          rejectedCheckIns.add(resourceId);
+          continue;
+        }
+      }
+      const result = operation.kind === "checkIn" ? await this.checkIn(operation.request, authContext) : await this.claimReward(operation.request, authContext);
+      const operationResult = syncOperationResult(operation, directRequest.userId, result);
+      results.push(operationResult);
+      if (operation.kind === "checkIn" && operationResult.status === "REJECTED_PERMANENT")
+        rejectedCheckIns.add(resourceId);
+    }
+    const currentState = await this.sync(directRequest.rallyId, authContext);
+    return {
+      results,
+      currentState,
+      syncTimestamp: timestampMillis(now(this.#options))
+    };
   }
   async #attachInventory(state2) {
     const rewardRemaining = {};