@stamprally/server 0.18.0 → 0.20.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import * as _stamprally_core from '@stamprally/core';
-import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
-export { UserRallyState } from '@stamprally/core';
+import { UserRallyState, AdminRallyConfig, SyncProgressResponse } from '@stamprally/core';
+export { SyncOperationResult, SyncProgressResponse, UserRallyState } from '@stamprally/core';
 
 /** Authentication already verified by the host application's middleware. */
 interface TrustedAuthContext {
@@ -248,6 +248,7 @@ declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
     readonly anonymousSessionId?: string;
+    readonly operations?: SyncProgressRequest["operations"];
 }>;
 
 type ErrorResponse = {
@@ -275,11 +276,7 @@ declare class StampRallyServer {
     checkIn(request: CheckInRequest, authContext?: TrustedAuthContext): Promise<CheckInResponse>;
     claimReward(request: ClaimRewardRequest, authContext?: TrustedAuthContext): Promise<ClaimResponse>;
     sync(rallyId: string, identity: string | TrustedAuthContext): Promise<UserRallyState>;
-    syncProgress(request: {
-        readonly rallyId: string;
-        readonly userId?: string;
-        readonly anonymousSessionId?: string;
-    }, authContext: TrustedAuthContext): Promise<UserRallyState>;
+    syncProgress(request: SyncProgressRequest, authContext: TrustedAuthContext): Promise<SyncProgressResponse>;
 }
 
 /**
@@ -319,6 +316,19 @@ interface ClaimRewardRequest {
     readonly staffId?: string;
     readonly now?: string | number;
 }
+type SyncProgressOperation = {
+    readonly kind: "checkIn";
+    readonly request: CheckInRequest;
+} | {
+    readonly kind: "claimReward";
+    readonly request: ClaimRewardRequest;
+};
+interface SyncProgressRequest {
+    readonly rallyId: string;
+    readonly userId?: string;
+    readonly anonymousSessionId?: string;
+    readonly operations?: ReadonlyArray<SyncProgressOperation>;
+}
 type CheckInResponse = {
     readonly ok: true;
     readonly state: UserRallyState;
@@ -338,4 +348,4 @@ interface ServerOptions {
     readonly anonymousPolicy?: "session_scoped" | "reject" | "shared_global_opt_in_insecure";
 }
 
-export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardMutationContext, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, RequestValidationException, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };
+export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardMutationContext, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, RequestValidationException, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type SyncProgressOperation, type SyncProgressRequest, type TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as _stamprally_core from '@stamprally/core';
-import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
-export { UserRallyState } from '@stamprally/core';
+import { UserRallyState, AdminRallyConfig, SyncProgressResponse } from '@stamprally/core';
+export { SyncOperationResult, SyncProgressResponse, UserRallyState } from '@stamprally/core';
 
 /** Authentication already verified by the host application's middleware. */
 interface TrustedAuthContext {
@@ -248,6 +248,7 @@ declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
     readonly anonymousSessionId?: string;
+    readonly operations?: SyncProgressRequest["operations"];
 }>;
 
 type ErrorResponse = {
@@ -275,11 +276,7 @@ declare class StampRallyServer {
     checkIn(request: CheckInRequest, authContext?: TrustedAuthContext): Promise<CheckInResponse>;
     claimReward(request: ClaimRewardRequest, authContext?: TrustedAuthContext): Promise<ClaimResponse>;
     sync(rallyId: string, identity: string | TrustedAuthContext): Promise<UserRallyState>;
-    syncProgress(request: {
-        readonly rallyId: string;
-        readonly userId?: string;
-        readonly anonymousSessionId?: string;
-    }, authContext: TrustedAuthContext): Promise<UserRallyState>;
+    syncProgress(request: SyncProgressRequest, authContext: TrustedAuthContext): Promise<SyncProgressResponse>;
 }
 
 /**
@@ -319,6 +316,19 @@ interface ClaimRewardRequest {
     readonly staffId?: string;
     readonly now?: string | number;
 }
+type SyncProgressOperation = {
+    readonly kind: "checkIn";
+    readonly request: CheckInRequest;
+} | {
+    readonly kind: "claimReward";
+    readonly request: ClaimRewardRequest;
+};
+interface SyncProgressRequest {
+    readonly rallyId: string;
+    readonly userId?: string;
+    readonly anonymousSessionId?: string;
+    readonly operations?: ReadonlyArray<SyncProgressOperation>;
+}
 type CheckInResponse = {
     readonly ok: true;
     readonly state: UserRallyState;
@@ -338,4 +348,4 @@ interface ServerOptions {
     readonly anonymousPolicy?: "session_scoped" | "reject" | "shared_global_opt_in_insecure";
 }
 
-export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardMutationContext, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, RequestValidationException, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };
+export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardMutationContext, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, RequestValidationException, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type SyncProgressOperation, type SyncProgressRequest, type TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };

package/dist/index.js

@@ -2,9 +2,13 @@ import { reconcileRewardStates, consumeReward, evaluateConditionDetailed } from
 
 // 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({
@@ -596,6 +600,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
@@ -623,6 +661,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(
     {
@@ -710,6 +757,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() === "")
@@ -842,15 +921,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);
@@ -1187,7 +1268,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 = {};