@stamprally/server 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -2,6 +2,16 @@ import * as _stamprally_core from '@stamprally/core';
 import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
 export { UserRallyState } from '@stamprally/core';
 
+/** Authentication already verified by the host application's middleware. */
+interface TrustedAuthContext {
+    readonly authenticatedUserId: string;
+    readonly isAnonymous?: boolean;
+    readonly sessionId?: string;
+    readonly claims?: Record<string, unknown>;
+}
+/** @deprecated Use TrustedAuthContext. */
+type AuthenticationContext = TrustedAuthContext;
+
 interface UserClaimRecord {
     readonly rallyId: string;
     readonly userId: string;
@@ -18,6 +28,10 @@ interface ClaimRewardTransactionParams {
     readonly idempotencyKey?: string;
     readonly proofData?: unknown;
     readonly idempotencyTtlMs?: number;
+    /** The configured per-reward stock limit, or null for unlimited stock. */
+    readonly rewardStockLimit: number | null;
+    /** The configured shared stock limit, or null when shared inventory is disabled. */
+    readonly sharedStockLimit: number | null;
     /** Used when the first claim is made before a user state has been stored. */
     readonly initialUserState?: UserRallyState;
     readonly stockKey?: string;
@@ -35,6 +49,16 @@ interface ClaimRewardTransactionMutation {
     /** A domain rejection is committed as an audit/idempotency record without mutations. */
     readonly error?: string;
 }
+interface ClaimRewardMutationContext {
+    readonly rewardStock: number | null;
+    readonly sharedStock: number | null;
+    readonly primaryStock: number | null;
+    readonly secondaryStock: number | null;
+    /** @deprecated Use rewardStock. */
+    readonly stock: number | null;
+    readonly claimCount: number;
+    readonly userState: UserRallyState;
+}
 interface CheckInTransactionParams {
     readonly rallyId: string;
     readonly userId: string;
@@ -63,15 +87,12 @@ interface ServerPersistenceAdapter {
      * Atomically commits stock, user state, claim count, audit log, and idempotency data.
      * Adapters must roll back every write when the callback or any commit operation fails.
      */
-    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
-        readonly stock: number | null;
-        readonly secondaryStock: number | null;
-        readonly claimCount: number;
-        readonly userState: UserRallyState;
-    }) => ClaimRewardTransactionMutation): Promise<{
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
         readonly success: boolean;
         readonly error?: string;
     }>;
+    /** Set false when the adapter cannot persist per-reward inventory atomically. */
+    readonly supportsRewardStock?: 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>;
@@ -95,6 +116,7 @@ interface InMemoryServerPersistenceOptions {
 }
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
+    readonly supportsRewardStock: boolean;
     constructor(options?: InMemoryServerPersistenceOptions);
     acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, key: string): Promise<void>;
@@ -104,12 +126,7 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         remainingStock: number;
     }>;
     restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
-    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
-        readonly stock: number | null;
-        readonly secondaryStock: number | null;
-        readonly claimCount: number;
-        readonly userState: UserRallyState;
-    }) => ClaimRewardTransactionMutation): Promise<{
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
         readonly success: boolean;
         readonly error?: string;
     }>;
@@ -135,7 +152,7 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
     /** @deprecated Use recordUserClaim with a ticket number and timestamp. */
     recordClaim(params: UserClaimRecord): Promise<void>;
     recordClaim(rallyId: string, userId: string, rewardId: string): Promise<void>;
-    runTransaction<T>(_rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    runTransaction<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
 }
 
 /**
@@ -168,11 +185,7 @@ interface SqlClaimRewardStore<Tx> {
  * while unexpected write failures reject the transaction and roll everything
  * back.
  */
-declare function executeClaimRewardTransaction<Tx>(database: SqlTransactionDatabase<Tx>, store: SqlClaimRewardStore<Tx>, params: ClaimRewardTransactionParams, mutation: (current: {
-    readonly stock: number | null;
-    readonly claimCount: number;
-    readonly userState: UserRallyState;
-}) => ClaimRewardTransactionMutation): Promise<{
+declare function executeClaimRewardTransaction<Tx>(database: SqlTransactionDatabase<Tx>, store: SqlClaimRewardStore<Tx>, params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
     readonly success: boolean;
     readonly error?: string;
 }>;
@@ -211,11 +224,27 @@ type RequestValidationResult<T> = {
     readonly success: false;
     readonly errors: ReadonlyArray<RequestValidationError>;
 };
+declare class RequestValidationException extends Error {
+    readonly code = "VALIDATION_FAILED";
+    readonly errors: ReadonlyArray<RequestValidationError>;
+    constructor(errors: ReadonlyArray<RequestValidationError>);
+}
 declare function validateCheckInRequest(value: unknown): RequestValidationResult<CheckInRequest>;
 declare function validateClaimRewardRequest(value: unknown): RequestValidationResult<ClaimRewardRequest>;
+declare function assertValidCheckInParams(value: unknown, config: AdminRallyConfig): asserts value is CheckInRequest & {
+    readonly userId: string;
+};
+declare function assertValidClaimParams(value: unknown, config: AdminRallyConfig): asserts value is ClaimRewardRequest & {
+    readonly userId: string;
+};
+declare function assertValidSyncParams(value: unknown, config: AdminRallyConfig): asserts value is {
+    readonly rallyId: string;
+    readonly userId: string;
+};
 declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
 }>;
 
 type ErrorResponse = {
@@ -240,15 +269,22 @@ declare class StampRallyServer {
     handleCheckIn(request: Request): Promise<Response>;
     handleClaimReward(request: Request): Promise<Response>;
     handleSync(request: Request): Promise<Response>;
-    checkIn(request: CheckInRequest & {
-        readonly userId: string;
-    }): Promise<CheckInResponse>;
-    claimReward(request: ClaimRewardRequest & {
-        readonly userId: string;
-    }): Promise<ClaimResponse>;
+    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>;
 }
 
+/**
+ * Runs the minimum atomicity and idempotency contract against a persistence adapter.
+ * The function throws a descriptive error when the adapter violates the contract.
+ */
+declare function runPersistenceAdapterComplianceTests(createAdapter: () => Promise<ServerPersistenceAdapter>): Promise<void>;
+
 interface AuditLog {
     readonly id: string;
     readonly timestamp: string;
@@ -264,6 +300,7 @@ type SyncOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR"
 interface CheckInRequest {
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
     readonly spotId: string;
     readonly context: _stamprally_core.VerificationContext;
     readonly idempotencyKey: string;
@@ -272,6 +309,7 @@ interface CheckInRequest {
 interface ClaimRewardRequest {
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
     readonly rewardId: string;
     readonly idempotencyKey: string;
     readonly staffPasscode?: string;
@@ -291,13 +329,10 @@ type CheckInResponse = {
 interface ServerOptions {
     readonly lockTtlMs?: number;
     readonly idempotencyTtlMs?: number;
-    readonly authenticate?: (request: Request) => Promise<string | AuthenticationContext | null> | string | AuthenticationContext | null;
+    readonly authenticate?: (request: Request) => Promise<string | TrustedAuthContext | null> | string | TrustedAuthContext | null;
     readonly customValidators?: Readonly<Record<string, _stamprally_core.Validator>>;
     readonly now?: () => string;
-    readonly anonymousPolicy?: "session_scoped" | "reject";
-}
-interface AuthenticationContext {
-    readonly authenticatedUserId: string;
+    readonly anonymousPolicy?: "session_scoped" | "reject" | "shared_global_opt_in_insecure";
 }
 
-export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type UserClaimRecord, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, 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 TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };

package/dist/index.d.ts

@@ -2,6 +2,16 @@ import * as _stamprally_core from '@stamprally/core';
 import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
 export { UserRallyState } from '@stamprally/core';
 
+/** Authentication already verified by the host application's middleware. */
+interface TrustedAuthContext {
+    readonly authenticatedUserId: string;
+    readonly isAnonymous?: boolean;
+    readonly sessionId?: string;
+    readonly claims?: Record<string, unknown>;
+}
+/** @deprecated Use TrustedAuthContext. */
+type AuthenticationContext = TrustedAuthContext;
+
 interface UserClaimRecord {
     readonly rallyId: string;
     readonly userId: string;
@@ -18,6 +28,10 @@ interface ClaimRewardTransactionParams {
     readonly idempotencyKey?: string;
     readonly proofData?: unknown;
     readonly idempotencyTtlMs?: number;
+    /** The configured per-reward stock limit, or null for unlimited stock. */
+    readonly rewardStockLimit: number | null;
+    /** The configured shared stock limit, or null when shared inventory is disabled. */
+    readonly sharedStockLimit: number | null;
     /** Used when the first claim is made before a user state has been stored. */
     readonly initialUserState?: UserRallyState;
     readonly stockKey?: string;
@@ -35,6 +49,16 @@ interface ClaimRewardTransactionMutation {
     /** A domain rejection is committed as an audit/idempotency record without mutations. */
     readonly error?: string;
 }
+interface ClaimRewardMutationContext {
+    readonly rewardStock: number | null;
+    readonly sharedStock: number | null;
+    readonly primaryStock: number | null;
+    readonly secondaryStock: number | null;
+    /** @deprecated Use rewardStock. */
+    readonly stock: number | null;
+    readonly claimCount: number;
+    readonly userState: UserRallyState;
+}
 interface CheckInTransactionParams {
     readonly rallyId: string;
     readonly userId: string;
@@ -63,15 +87,12 @@ interface ServerPersistenceAdapter {
      * Atomically commits stock, user state, claim count, audit log, and idempotency data.
      * Adapters must roll back every write when the callback or any commit operation fails.
      */
-    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
-        readonly stock: number | null;
-        readonly secondaryStock: number | null;
-        readonly claimCount: number;
-        readonly userState: UserRallyState;
-    }) => ClaimRewardTransactionMutation): Promise<{
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
         readonly success: boolean;
         readonly error?: string;
     }>;
+    /** Set false when the adapter cannot persist per-reward inventory atomically. */
+    readonly supportsRewardStock?: 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>;
@@ -95,6 +116,7 @@ interface InMemoryServerPersistenceOptions {
 }
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
+    readonly supportsRewardStock: boolean;
     constructor(options?: InMemoryServerPersistenceOptions);
     acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
     releaseLock(rallyId: string, key: string): Promise<void>;
@@ -104,12 +126,7 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
         remainingStock: number;
     }>;
     restoreRewardStock(rallyId: string, rewardId: string, count?: number): Promise<void>;
-    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: {
-        readonly stock: number | null;
-        readonly secondaryStock: number | null;
-        readonly claimCount: number;
-        readonly userState: UserRallyState;
-    }) => ClaimRewardTransactionMutation): Promise<{
+    executeClaimRewardTransaction(params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
         readonly success: boolean;
         readonly error?: string;
     }>;
@@ -135,7 +152,7 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
     /** @deprecated Use recordUserClaim with a ticket number and timestamp. */
     recordClaim(params: UserClaimRecord): Promise<void>;
     recordClaim(rallyId: string, userId: string, rewardId: string): Promise<void>;
-    runTransaction<T>(_rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
+    runTransaction<T>(rallyId: string, operation: (transaction: ServerPersistenceAdapter) => Promise<T>): Promise<T>;
 }
 
 /**
@@ -168,11 +185,7 @@ interface SqlClaimRewardStore<Tx> {
  * while unexpected write failures reject the transaction and roll everything
  * back.
  */
-declare function executeClaimRewardTransaction<Tx>(database: SqlTransactionDatabase<Tx>, store: SqlClaimRewardStore<Tx>, params: ClaimRewardTransactionParams, mutation: (current: {
-    readonly stock: number | null;
-    readonly claimCount: number;
-    readonly userState: UserRallyState;
-}) => ClaimRewardTransactionMutation): Promise<{
+declare function executeClaimRewardTransaction<Tx>(database: SqlTransactionDatabase<Tx>, store: SqlClaimRewardStore<Tx>, params: ClaimRewardTransactionParams, mutation: (current: ClaimRewardMutationContext) => ClaimRewardTransactionMutation): Promise<{
     readonly success: boolean;
     readonly error?: string;
 }>;
@@ -211,11 +224,27 @@ type RequestValidationResult<T> = {
     readonly success: false;
     readonly errors: ReadonlyArray<RequestValidationError>;
 };
+declare class RequestValidationException extends Error {
+    readonly code = "VALIDATION_FAILED";
+    readonly errors: ReadonlyArray<RequestValidationError>;
+    constructor(errors: ReadonlyArray<RequestValidationError>);
+}
 declare function validateCheckInRequest(value: unknown): RequestValidationResult<CheckInRequest>;
 declare function validateClaimRewardRequest(value: unknown): RequestValidationResult<ClaimRewardRequest>;
+declare function assertValidCheckInParams(value: unknown, config: AdminRallyConfig): asserts value is CheckInRequest & {
+    readonly userId: string;
+};
+declare function assertValidClaimParams(value: unknown, config: AdminRallyConfig): asserts value is ClaimRewardRequest & {
+    readonly userId: string;
+};
+declare function assertValidSyncParams(value: unknown, config: AdminRallyConfig): asserts value is {
+    readonly rallyId: string;
+    readonly userId: string;
+};
 declare function validateSyncRequest(value: unknown): RequestValidationResult<{
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
 }>;
 
 type ErrorResponse = {
@@ -240,15 +269,22 @@ declare class StampRallyServer {
     handleCheckIn(request: Request): Promise<Response>;
     handleClaimReward(request: Request): Promise<Response>;
     handleSync(request: Request): Promise<Response>;
-    checkIn(request: CheckInRequest & {
-        readonly userId: string;
-    }): Promise<CheckInResponse>;
-    claimReward(request: ClaimRewardRequest & {
-        readonly userId: string;
-    }): Promise<ClaimResponse>;
+    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>;
 }
 
+/**
+ * Runs the minimum atomicity and idempotency contract against a persistence adapter.
+ * The function throws a descriptive error when the adapter violates the contract.
+ */
+declare function runPersistenceAdapterComplianceTests(createAdapter: () => Promise<ServerPersistenceAdapter>): Promise<void>;
+
 interface AuditLog {
     readonly id: string;
     readonly timestamp: string;
@@ -264,6 +300,7 @@ type SyncOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR"
 interface CheckInRequest {
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
     readonly spotId: string;
     readonly context: _stamprally_core.VerificationContext;
     readonly idempotencyKey: string;
@@ -272,6 +309,7 @@ interface CheckInRequest {
 interface ClaimRewardRequest {
     readonly rallyId: string;
     readonly userId?: string;
+    readonly anonymousSessionId?: string;
     readonly rewardId: string;
     readonly idempotencyKey: string;
     readonly staffPasscode?: string;
@@ -291,13 +329,10 @@ type CheckInResponse = {
 interface ServerOptions {
     readonly lockTtlMs?: number;
     readonly idempotencyTtlMs?: number;
-    readonly authenticate?: (request: Request) => Promise<string | AuthenticationContext | null> | string | AuthenticationContext | null;
+    readonly authenticate?: (request: Request) => Promise<string | TrustedAuthContext | null> | string | TrustedAuthContext | null;
     readonly customValidators?: Readonly<Record<string, _stamprally_core.Validator>>;
     readonly now?: () => string;
-    readonly anonymousPolicy?: "session_scoped" | "reject";
-}
-interface AuthenticationContext {
-    readonly authenticatedUserId: string;
+    readonly anonymousPolicy?: "session_scoped" | "reject" | "shared_global_opt_in_insecure";
 }
 
-export { type AuditLog, type AuthenticationContext, type CheckInRequest, type CheckInResponse, type CheckInTransactionMutation, type CheckInTransactionParams, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type RedisMultiExecutor, type RequestValidationError, type RequestValidationResult, type ServerOptions, type ServerPersistenceAdapter, type SqlCheckInStore, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type UserClaimRecord, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, 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 TrustedAuthContext, type UserClaimRecord, assertValidCheckInParams, assertValidClaimParams, assertValidSyncParams, executeCheckInTransaction, executeClaimRewardTransaction, executeRedisTransaction, runPersistenceAdapterComplianceTests, validateCheckInRequest, validateClaimRewardRequest, validateSyncRequest };