@stamprally/server 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -20,9 +20,14 @@ interface ClaimRewardTransactionParams {
     readonly idempotencyTtlMs?: number;
     /** Used when the first claim is made before a user state has been stored. */
     readonly initialUserState?: UserRallyState;
+    readonly stockKey?: string;
+    readonly secondaryStockKey?: string;
+    readonly initialStock?: number | null;
+    readonly initialSecondaryStock?: number | null;
 }
 interface ClaimRewardTransactionMutation {
     readonly nextStock: number | null;
+    readonly nextSecondaryStock?: number | null;
     readonly nextUserState: UserRallyState;
     readonly auditLog: AuditLog;
     /** The server response is persisted by the adapter with the idempotency key. */
@@ -30,13 +35,37 @@ interface ClaimRewardTransactionMutation {
     /** A domain rejection is committed as an audit/idempotency record without mutations. */
     readonly error?: string;
 }
+interface CheckInTransactionParams {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly spotId: string;
+    readonly timestamp: number;
+    readonly idempotencyKey?: string;
+    readonly proofData?: unknown;
+    readonly idempotencyTtlMs?: number;
+    readonly initialUserState?: UserRallyState;
+}
+interface CheckInTransactionMutation {
+    readonly nextUserState: UserRallyState;
+    readonly auditLog: AuditLog;
+    readonly result?: unknown;
+    readonly error?: string;
+}
 interface ServerPersistenceAdapter {
+    /** Atomically commits user state, audit log, and idempotency data. */
+    executeCheckInTransaction(params: CheckInTransactionParams, mutation: (current: {
+        readonly userState: UserRallyState;
+    }) => CheckInTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     /**
      * 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<{
@@ -77,12 +106,19 @@ declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapt
     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<{
         readonly success: boolean;
         readonly error?: string;
     }>;
+    executeCheckInTransaction(params: CheckInTransactionParams, mutation: (current: {
+        readonly userState: UserRallyState;
+    }) => CheckInTransactionMutation): Promise<{
+        readonly success: boolean;
+        readonly error?: string;
+    }>;
     rollbackUserState(rallyId: string, userId: string, previousState: UserRallyState | null): Promise<void>;
     getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
     saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
@@ -115,10 +151,12 @@ interface SqlTransactionDatabase<Tx> {
 interface SqlClaimRewardStore<Tx> {
     readContext(transaction: Tx, params: ClaimRewardTransactionParams): Promise<{
         readonly stock: number | null;
+        readonly secondaryStock?: number | null;
         readonly claimCount: number;
         readonly userState: UserRallyState;
     }>;
     writeStock(transaction: Tx, params: ClaimRewardTransactionParams, nextStock: number): Promise<void>;
+    writeSecondaryStock?(transaction: Tx, params: ClaimRewardTransactionParams, nextStock: number): Promise<void>;
     writeUserState(transaction: Tx, params: ClaimRewardTransactionParams, state: UserRallyState): Promise<void>;
     writeClaimRecord(transaction: Tx, params: ClaimRewardTransactionParams, state: UserRallyState): Promise<void>;
     writeAudit(transaction: Tx, log: AuditLog): Promise<void>;
@@ -138,6 +176,47 @@ declare function executeClaimRewardTransaction<Tx>(database: SqlTransactionDatab
     readonly success: boolean;
     readonly error?: string;
 }>;
+interface SqlCheckInStore<Tx> {
+    readUserState?(transaction: Tx, params: CheckInTransactionParams): Promise<UserRallyState>;
+    writeUserState(transaction: Tx, params: CheckInTransactionParams, state: UserRallyState): Promise<void>;
+    writeAudit(transaction: Tx, log: AuditLog): Promise<void>;
+    writeIdempotency(transaction: Tx, params: CheckInTransactionParams, result: unknown): Promise<void>;
+}
+/** Reference transaction block for a check-in state, audit, and idempotency write. */
+declare function executeCheckInTransaction<Tx>(database: SqlTransactionDatabase<Tx>, store: SqlCheckInStore<Tx>, params: CheckInTransactionParams, mutation: (current: {
+    readonly userState: UserRallyState;
+}) => CheckInTransactionMutation, current?: UserRallyState): Promise<{
+    readonly success: boolean;
+    readonly error?: string;
+}>;
+interface RedisMultiExecutor<TMulti> {
+    multi(): TMulti;
+    exec(multi: TMulti): Promise<ReadonlyArray<unknown> | null>;
+}
+/** Reference for Redis MULTI/EXEC adapters: all queued commands commit together. */
+declare function executeRedisTransaction<TMulti>(redis: RedisMultiExecutor<TMulti>, queue: (multi: TMulti) => void): Promise<{
+    readonly success: boolean;
+    readonly error?: string;
+}>;
+
+interface RequestValidationError {
+    readonly path: string;
+    readonly message: string;
+    readonly code: string;
+}
+type RequestValidationResult<T> = {
+    readonly success: true;
+    readonly data: T;
+} | {
+    readonly success: false;
+    readonly errors: ReadonlyArray<RequestValidationError>;
+};
+declare function validateCheckInRequest(value: unknown): RequestValidationResult<CheckInRequest>;
+declare function validateClaimRewardRequest(value: unknown): RequestValidationResult<ClaimRewardRequest>;
+declare function validateSyncRequest(value: unknown): RequestValidationResult<{
+    readonly rallyId: string;
+    readonly userId?: string;
+}>;
 
 type ErrorResponse = {
     readonly ok: false;
@@ -148,7 +227,12 @@ type ClaimResponse = {
     readonly ok: true;
     readonly state: UserRallyState;
     readonly claimTicketNumber?: string;
+    readonly inventory?: InventoryStatus;
 } | ErrorResponse;
+interface InventoryStatus {
+    readonly sharedRemaining?: number;
+    readonly rewardRemaining?: number;
+}
 declare class StampRallyServer {
     #private;
     constructor(config: AdminRallyConfig, persistence: ServerPersistenceAdapter, options?: ServerOptions);
@@ -183,7 +267,7 @@ interface CheckInRequest {
     readonly spotId: string;
     readonly context: _stamprally_core.VerificationContext;
     readonly idempotencyKey: string;
-    readonly now?: string;
+    readonly now?: string | number;
 }
 interface ClaimRewardRequest {
     readonly rallyId: string;
@@ -192,7 +276,7 @@ interface ClaimRewardRequest {
     readonly idempotencyKey: string;
     readonly staffPasscode?: string;
     readonly staffId?: string;
-    readonly now?: string;
+    readonly now?: string | number;
 }
 type CheckInResponse = {
     readonly ok: true;
@@ -207,9 +291,13 @@ type CheckInResponse = {
 interface ServerOptions {
     readonly lockTtlMs?: number;
     readonly idempotencyTtlMs?: number;
-    readonly authenticate?: (request: Request) => Promise<string | null> | string | null;
+    readonly authenticate?: (request: Request) => Promise<string | AuthenticationContext | null> | string | AuthenticationContext | null;
     readonly customValidators?: Readonly<Record<string, _stamprally_core.Validator>>;
     readonly now?: () => string;
+    readonly anonymousPolicy?: "session_scoped" | "reject";
+}
+interface AuthenticationContext {
+    readonly authenticatedUserId: string;
 }
 
-export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, type ClaimRewardTransactionMutation, type ClaimRewardTransactionParams, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, type SqlClaimRewardStore, type SqlTransactionDatabase, StampRallyServer, type SyncOperationStatus, type UserClaimRecord, executeClaimRewardTransaction };
+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 };