@stamprally/server 0.17.0 → 0.19.0

package/dist/index.d.cts

@@ -93,6 +93,8 @@ interface ServerPersistenceAdapter {
     }>;
     /** Set false when the adapter cannot persist per-reward inventory atomically. */
     readonly supportsRewardStock?: boolean;
+    /** Must be true when a claim plan uses `secondaryStockKey`. */
+    readonly supportsSecondaryStock?: boolean;
     acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, lockKey: string): Promise<void>;
     getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
@@ -117,6 +119,7 @@ interface InMemoryServerPersistenceOptions {
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
     readonly supportsRewardStock: boolean;
+    readonly supportsSecondaryStock: boolean;
     constructor(options?: InMemoryServerPersistenceOptions);
     acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, key: string): Promise<void>;
@@ -245,6 +248,7 @@ declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
     readonly anonymousSessionId?: string;
+    readonly operations?: SyncProgressRequest["operations"];
 }>;
 
 type ErrorResponse = {
@@ -271,12 +275,8 @@ declare class StampRallyServer {
     handleSync(request: Request): Promise<Response>;
     checkIn(request: CheckInRequest, authContext?: TrustedAuthContext): Promise<CheckInResponse>;
     claimReward(request: ClaimRewardRequest, authContext?: TrustedAuthContext): Promise<ClaimResponse>;
-    sync(rallyId: string, userId: string): Promise<UserRallyState>;
-    syncProgress(request: {
-        readonly rallyId: string;
-        readonly userId?: string;
-        readonly anonymousSessionId?: string;
-    }): Promise<UserRallyState>;
+    sync(rallyId: string, identity: string | TrustedAuthContext): Promise<UserRallyState>;
+    syncProgress(request: SyncProgressRequest, authContext: TrustedAuthContext): Promise<UserRallyState>;
 }
 
 /**
@@ -316,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;
@@ -335,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

@@ -93,6 +93,8 @@ interface ServerPersistenceAdapter {
     }>;
     /** Set false when the adapter cannot persist per-reward inventory atomically. */
     readonly supportsRewardStock?: boolean;
+    /** Must be true when a claim plan uses `secondaryStockKey`. */
+    readonly supportsSecondaryStock?: boolean;
     acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, lockKey: string): Promise<void>;
     getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
@@ -117,6 +119,7 @@ interface InMemoryServerPersistenceOptions {
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
     readonly supportsRewardStock: boolean;
+    readonly supportsSecondaryStock: boolean;
     constructor(options?: InMemoryServerPersistenceOptions);
     acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, key: string): Promise<void>;
@@ -245,6 +248,7 @@ declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
     readonly anonymousSessionId?: string;
+    readonly operations?: SyncProgressRequest["operations"];
 }>;
 
 type ErrorResponse = {
@@ -271,12 +275,8 @@ declare class StampRallyServer {
     handleSync(request: Request): Promise<Response>;
     checkIn(request: CheckInRequest, authContext?: TrustedAuthContext): Promise<CheckInResponse>;
     claimReward(request: ClaimRewardRequest, authContext?: TrustedAuthContext): Promise<ClaimResponse>;
-    sync(rallyId: string, userId: string): Promise<UserRallyState>;
-    syncProgress(request: {
-        readonly rallyId: string;
-        readonly userId?: string;
-        readonly anonymousSessionId?: string;
-    }): Promise<UserRallyState>;
+    sync(rallyId: string, identity: string | TrustedAuthContext): Promise<UserRallyState>;
+    syncProgress(request: SyncProgressRequest, authContext: TrustedAuthContext): Promise<UserRallyState>;
 }
 
 /**
@@ -316,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;
@@ -335,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({
@@ -76,6 +80,7 @@ async function executeRedisTransaction(redis, queue) {
 // src/persistence.ts
 var InMemoryServerPersistenceAdapter = class {
   supportsRewardStock = true;
+  supportsSecondaryStock = true;
   #locks = /* @__PURE__ */ new Map();
   #idempotent = /* @__PURE__ */ new Map();
   #states = /* @__PURE__ */ new Map();
@@ -595,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
@@ -640,26 +679,41 @@ function initialState(config, userId, timestamp) {
     updatedAt: timestamp
   };
 }
-function rewardStock(config, rewardId, stockLimit) {
-  const configured = config.inventory?.[rewardId];
+function rewardStock(config, reward) {
+  const stockLimit = reward.stockLimit;
+  const key = reward.stockKey ?? reward.id;
+  const configured = key === "__shared__" ? config.inventory?.sharedStock : config.inventory?.[key];
   if (stockLimit === void 0) return configured ?? null;
   if (configured === void 0) return stockLimit;
   return Math.min(stockLimit, configured);
 }
 function sharedStock(config) {
-  return config.inventory?.sharedStock ?? config.inventory?.global ?? null;
+  return config.inventory?.sharedStock ?? null;
 }
 function inventoryPlan(config, rewardId, stockLimit) {
-  const individual = rewardStock(config, rewardId, stockLimit);
+  const reward = config.rewards.find((item) => item.id === rewardId);
+  const individual = reward === void 0 ? stockLimit ?? null : rewardStock(config, reward);
   const shared = sharedStock(config);
+  const explicitPrimaryKey = reward?.stockKey;
+  const explicitSecondaryKey = reward?.secondaryStockKey;
   if (config.inventoryMode === "shared" && shared !== null) {
     return {
-      primaryKey: "__shared__",
-      primaryInitial: shared,
-      ...individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
+      primaryKey: explicitPrimaryKey ?? "__shared__",
+      primaryInitial: explicitPrimaryKey === void 0 ? shared : individual,
+      ...explicitSecondaryKey !== void 0 ? {
+        secondaryKey: explicitSecondaryKey,
+        secondaryInitial: config.inventory?.[explicitSecondaryKey] ?? individual
+      } : individual === null ? {} : { secondaryKey: rewardId, secondaryInitial: individual }
     };
   }
-  return { primaryKey: rewardId, primaryInitial: individual };
+  return {
+    primaryKey: explicitPrimaryKey ?? rewardId,
+    primaryInitial: individual,
+    ...explicitSecondaryKey === void 0 ? {} : {
+      secondaryKey: explicitSecondaryKey,
+      secondaryInitial: config.inventory?.[explicitSecondaryKey] ?? null
+    }
+  };
 }
 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;
@@ -821,14 +875,21 @@ var StampRallyServer = class {
         401
       );
     const sessionId = request.headers.get("x-anonymous-session-id");
+    const authContext = {
+      authenticatedUserId: userId,
+      ...sessionId === null ? {} : { isAnonymous: true, sessionId }
+    };
     try {
       return json({
         ok: true,
-        state: await this.syncProgress({
-          rallyId: body.data.rallyId,
-          userId,
-          ...sessionId === null ? {} : { anonymousSessionId: sessionId }
-        })
+        state: await this.syncProgress(
+          {
+            rallyId: body.data.rallyId,
+            ...body.data.operations === void 0 ? {} : { operations: body.data.operations },
+            ...sessionId === null ? {} : { anonymousSessionId: sessionId }
+          },
+          authContext
+        )
       });
     } catch (error) {
       if (error instanceof RequestValidationException) return validationResponse(error.errors);
@@ -988,6 +1049,8 @@ var StampRallyServer = class {
         now(this.#options)
       );
     const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
+    if (plan.secondaryKey !== void 0 && this.#persistence.supportsSecondaryStock !== true)
+      throw new Error("SECONDARY_STOCK_UNSUPPORTED");
     const inventoryEnabled = plan.primaryInitial !== null || plan.secondaryInitial !== void 0 && plan.secondaryInitial !== null;
     if (inventoryEnabled && (this.#persistence.supportsRewardStock === false || typeof this.#persistence.getRewardStock !== "function" || typeof this.#persistence.executeClaimRewardTransaction !== "function"))
       return this.#rememberClaim(
@@ -1022,7 +1085,7 @@ var StampRallyServer = class {
           rewardId: reward.id,
           stockKey: plan.primaryKey,
           ...plan.secondaryKey === void 0 ? {} : { secondaryStockKey: plan.secondaryKey },
-          rewardStockLimit: rewardStock(this.#config, reward.id, reward.stockLimit),
+          rewardStockLimit: rewardStock(this.#config, reward),
           sharedStockLimit: this.#config.inventoryMode === "shared" ? sharedStock(this.#config) : null,
           initialStock: plan.primaryInitial,
           ...plan.secondaryInitial === void 0 ? {} : { initialSecondaryStock: plan.secondaryInitial },
@@ -1154,21 +1217,28 @@ var StampRallyServer = class {
       await this.#persistence.releaseLock(request.rallyId, lockKey);
     }
   }
-  async sync(rallyId, userId) {
+  async sync(rallyId, identity) {
+    const userId = typeof identity === "string" ? identity : identity.authenticatedUserId;
     assertValidSyncParams({ rallyId, userId }, this.#config);
     const state2 = await this.#persistence.getUserState(rallyId, userId) ?? initialState(this.#config, userId, now(this.#options));
     return this.#attachInventory(state2);
   }
-  async syncProgress(request) {
-    const directRequest = withDirectIdentity(request);
+  async syncProgress(request, authContext) {
+    const directRequest = withDirectIdentity(request, authContext);
     assertValidSyncParams(directRequest, this.#config);
-    return this.sync(directRequest.rallyId, directRequest.userId);
+    for (const operation of request.operations ?? []) {
+      if (operation.kind === "checkIn") await this.checkIn(operation.request, authContext);
+      else await this.claimReward(operation.request, authContext);
+    }
+    return this.sync(directRequest.rallyId, authContext);
   }
   async #attachInventory(state2) {
     const rewardRemaining = {};
     for (const reward of this.#config.rewards) {
       const plan = inventoryPlan(this.#config, reward.id, reward.stockLimit);
       if (plan.secondaryKey !== void 0) {
+        if (this.#persistence.supportsSecondaryStock !== true)
+          throw new Error("SECONDARY_STOCK_UNSUPPORTED");
         const stock = await this.#persistence.getRewardStock(state2.rallyId, plan.secondaryKey);
         const remaining = stock ?? plan.secondaryInitial ?? null;
         if (remaining !== null) rewardRemaining[reward.id] = Math.max(0, remaining);