@stamprally/server 0.19.0 → 0.20.0

package/README.md

@@ -1,4 +1,4 @@
-# @stamprally/server v0.19.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

@@ -663,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(
     {
@@ -750,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() === "")
@@ -882,16 +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,
-            ...body.data.operations === void 0 ? {} : { operations: body.data.operations },
-            ...sessionId === null ? {} : { anonymousSessionId: sessionId }
-          },
-          authContext
-        )
+        ...progress
       });
     } catch (error) {
       if (error instanceof RequestValidationException) return validationResponse(error.errors);
@@ -1228,11 +1270,39 @@ var StampRallyServer = class {
   async syncProgress(request, authContext) {
     const directRequest = withDirectIdentity(request, authContext);
     assertValidSyncParams(directRequest, this.#config);
-    for (const operation of request.operations ?? []) {
-      if (operation.kind === "checkIn") await this.checkIn(operation.request, authContext);
-      else await this.claimReward(operation.request, 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);
     }
-    return this.sync(directRequest.rallyId, authContext);
+    const currentState = await this.sync(directRequest.rallyId, authContext);
+    return {
+      results,
+      currentState,
+      syncTimestamp: timestampMillis(now(this.#options))
+    };
   }
   async #attachInventory(state2) {
     const rewardRemaining = {};