@stamprally/server 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,105 +1,89 @@
-import { AdminRallyConfig as AdminRallyConfig$1, VerificationCondition, RallyConfig, SecureTokenSecretKey, StampRallyState, VerificationContext } from '@stamprally/core';
-export { StampError, StampRecord } from '@stamprally/core';
+import * as _stamprally_core from '@stamprally/core';
+import { UserRallyState, AdminRallyConfig } from '@stamprally/core';
+export { UserRallyState } from '@stamprally/core';
 
-/** Persistence contract for implementations backed by Redis, SQL, or another RDB. */
+interface UserClaimRecord {
+    readonly rallyId: string;
+    readonly userId: string;
+    readonly rewardId: string;
+    readonly ticketNumber: string;
+    readonly timestamp: number;
+}
 interface ServerPersistenceAdapter {
-    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
-    releaseLock(lockKey: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
-        success: boolean;
-        remainingStock: number;
+    acquireLock(rallyId: string, lockKey: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, lockKey: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
+        readonly success: boolean;
+        readonly remainingStock: number;
     }>;
-    getIdempotentResult<T>(idempotencyKey: string): Promise<T | null>;
-    saveIdempotentResult<T>(idempotencyKey: string, result: T, ttlMs: number): Promise<void>;
+    restoreRewardStock?(rallyId: string, rewardId: string): Promise<void>;
+    getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
+    saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
+    getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
+    recordUserClaim(params: UserClaimRecord): Promise<void>;
+    recordClaim?(params: UserClaimRecord): Promise<void>;
+    incrementUserClaimCount?(rallyId: string, userId: string, rewardId: string): Promise<void>;
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
-    recordAuditLog(log: RallyAuditLog): Promise<void>;
+    recordAuditLog(log: AuditLog): Promise<void>;
 }
 interface InMemoryServerPersistenceOptions {
     readonly stocks?: Readonly<Record<string, number>>;
 }
-/** Deterministic adapter for tests and small single-process deployments. */
 declare class InMemoryServerPersistenceAdapter implements ServerPersistenceAdapter {
     #private;
     constructor(options?: InMemoryServerPersistenceOptions);
-    acquireLock(lockKey: string, ttlMs: number): Promise<boolean>;
-    releaseLock(lockKey: string): Promise<void>;
-    decrementRewardStock(rewardId: string): Promise<{
+    acquireLock(rallyId: string, key: string, ttlMs: number): Promise<boolean>;
+    releaseLock(rallyId: string, key: string): Promise<void>;
+    getRewardStock(rallyId: string, rewardId: string): Promise<number | null>;
+    decrementRewardStock(rallyId: string, rewardId: string): Promise<{
         success: boolean;
         remainingStock: number;
     }>;
-    getIdempotentResult<T>(idempotencyKey: string): Promise<T | null>;
-    saveIdempotentResult<T>(idempotencyKey: string, result: T, ttlMs: number): Promise<void>;
+    restoreRewardStock(rallyId: string, rewardId: string): Promise<void>;
+    getIdempotentResult<T>(rallyId: string, key: string): Promise<T | null>;
+    saveIdempotentResult<T>(rallyId: string, key: string, result: T, ttlMs: number): Promise<void>;
+    getUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<number>;
     getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
     saveUserState(rallyId: string, userId: string, state: UserRallyState): Promise<void>;
-    recordAuditLog(log: RallyAuditLog): Promise<void>;
-    getAuditLogs(): ReadonlyArray<RallyAuditLog>;
+    recordAuditLog(log: AuditLog): Promise<void>;
+    getAuditLogs(): ReadonlyArray<AuditLog>;
+    recordUserClaim(params: UserClaimRecord): Promise<void>;
+    incrementUserClaimCount(rallyId: string, userId: string, rewardId: string): Promise<void>;
+    getClaimRecords(): ReadonlyArray<UserClaimRecord>;
+    /** @deprecated Use recordUserClaim with a ticket number and timestamp. */
+    recordClaim(params: UserClaimRecord): Promise<void>;
+    recordClaim(rallyId: string, userId: string, rewardId: string): Promise<void>;
 }
 
-type UniversalVerificationContext = {
-    readonly type: "qr";
-    readonly token: string;
-} | {
-    readonly type: "passcode";
-    readonly code: string;
-} | {
-    readonly type: "gps";
-    readonly latitude: number;
-    readonly longitude: number;
-} | {
-    readonly type: "custom";
-    readonly value: unknown;
-};
-interface UniversalCheckInRequest {
-    readonly rallyId: string;
-    readonly userId: string;
-    readonly spotId: string;
-    readonly context: UniversalVerificationContext;
-    readonly idempotencyKey: string;
-    readonly now?: string;
-}
-interface UniversalClaimRewardRequest {
-    readonly rallyId: string;
-    readonly userId: string;
-    readonly rewardId: string;
-    readonly idempotencyKey: string;
-    readonly staffPasscode?: string;
-    readonly staffId?: string;
-    readonly now?: string;
-}
-type UniversalCheckInResult = {
-    readonly ok: true;
-    readonly state: UserRallyState;
-} | {
+type ErrorResponse = {
     readonly ok: false;
     readonly code: string;
     readonly message: string;
 };
-interface UniversalRallyServerOptions {
-    readonly idempotencyTtlMs?: number;
-    readonly lockTtlMs?: number;
-    readonly customValidators?: Readonly<Record<string, (value: unknown, condition: VerificationCondition) => boolean>>;
-    readonly now?: () => string;
-    /** Extract the authenticated identity; request-body userId is never trusted when this is set. */
-    readonly authenticate?: (request: Request) => Promise<string | null> | string | null;
-}
-/** Atomic, adapter-backed check-in service for the universal model. */
-declare class UniversalRallyServer {
+type ClaimResponse = {
+    readonly ok: true;
+    readonly state: UserRallyState;
+    readonly claimTicketNumber?: string;
+} | ErrorResponse;
+declare class StampRallyServer {
     #private;
-    constructor(config: AdminRallyConfig$1, persistence: ServerPersistenceAdapter, options?: UniversalRallyServerOptions);
-    /** Web Standard endpoint handler. Authentication, when configured, supplies the user identity. */
+    constructor(config: AdminRallyConfig, persistence: ServerPersistenceAdapter, options?: ServerOptions);
+    handle(request: Request): Promise<Response>;
     handleCheckIn(request: Request): Promise<Response>;
     handleClaimReward(request: Request): Promise<Response>;
     handleSync(request: Request): Promise<Response>;
-    handle(request: Request): Promise<Response>;
-    checkIn(request: UniversalCheckInRequest): Promise<UniversalCheckInResult>;
+    checkIn(request: CheckInRequest & {
+        readonly userId: string;
+    }): Promise<CheckInResponse>;
+    claimReward(request: ClaimRewardRequest & {
+        readonly userId: string;
+    }): Promise<ClaimResponse>;
     sync(rallyId: string, userId: string): Promise<UserRallyState>;
 }
 
-interface UserRallyState extends StampRallyState {
-    readonly userId?: string;
-}
-interface RallyAuditLog {
+interface AuditLog {
     readonly id: string;
     readonly timestamp: string;
     readonly rallyId: string;
@@ -108,79 +92,39 @@ interface RallyAuditLog {
     readonly resourceId: string;
     readonly status: "SUCCESS" | "REJECTED";
     readonly idempotencyKey: string;
-    readonly proofData?: unknown;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-interface ServerStorageAdapter {
-    getRewardStock(rewardId: string): Promise<number | null>;
-    decrementRewardStock(rewardId: string): Promise<boolean>;
-    getUserClaims(userId: string, rewardId: string): Promise<number>;
-    recordAuditLog(log: RallyAuditLog): Promise<void>;
-    saveUserState(userId: string, state: UserRallyState): Promise<void>;
-    getUserState(userId: string): Promise<UserRallyState | null>;
-}
-interface AdminRallyConfig extends RallyConfig {
-    readonly secretKey: SecureTokenSecretKey;
-    readonly proofTtlSeconds?: number;
-    readonly authenticate?: (request: Request) => Promise<string | null> | string | null;
-}
 interface CheckInRequest {
-    readonly userId: string;
+    readonly rallyId: string;
+    readonly userId?: string;
     readonly spotId: string;
-    readonly claimMethod: string;
-    readonly proofData?: unknown;
+    readonly context: _stamprally_core.VerificationContext;
     readonly idempotencyKey: string;
+    readonly now?: string;
 }
 interface ClaimRewardRequest {
-    readonly userId: string;
+    readonly rallyId: string;
+    readonly userId?: string;
     readonly rewardId: string;
-    readonly staffPasscode?: string;
     readonly idempotencyKey: string;
+    readonly staffPasscode?: string;
     readonly staffId?: string;
+    readonly now?: string;
 }
-interface SyncRequest {
-    readonly userId: string;
-    readonly queue?: ReadonlyArray<SyncCheckInOperation>;
-    readonly operations?: ReadonlyArray<SyncCheckInOperation>;
-}
-interface SyncCheckInOperation {
-    readonly userId?: string;
-    readonly spotId?: string;
-    readonly stampId?: string;
-    readonly claimMethod?: string;
-    readonly proofData?: unknown;
-    readonly context?: VerificationContext;
-    readonly idempotencyKey: string;
-}
-interface StampClaimProof {
-    readonly token: string;
-    readonly rallyId: string;
-    readonly userId: string;
-    readonly spotId: string;
-    readonly acquiredAt: string;
-}
-interface InMemoryServerStorageOptions {
-    readonly stocks?: Readonly<Record<string, number>>;
-}
-declare class InMemoryServerStorage implements ServerStorageAdapter {
-    #private;
-    constructor(options?: InMemoryServerStorageOptions);
-    getRewardStock(rewardId: string): Promise<number | null>;
-    decrementRewardStock(rewardId: string): Promise<boolean>;
-    getUserClaims(userId: string, rewardId: string): Promise<number>;
-    recordAuditLog(log: RallyAuditLog): Promise<void>;
-    saveUserState(userId: string, state: UserRallyState): Promise<void>;
-    getUserState(userId: string): Promise<UserRallyState | null>;
-    getAuditLogs(): ReadonlyArray<RallyAuditLog>;
-    recordClaim(userId: string, rewardId: string): void;
-}
-declare class StampRallyServer {
-    #private;
-    constructor(config: AdminRallyConfig, storage: ServerStorageAdapter);
-    handle(request: Request): Promise<Response>;
-    verifyCheckIn(request: Request): Promise<Response>;
-    claimReward(request: Request): Promise<Response>;
-    syncProgress(request: Request): Promise<Response>;
+type CheckInResponse = {
+    readonly ok: true;
+    readonly state: UserRallyState;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+interface ServerOptions {
+    readonly lockTtlMs?: number;
+    readonly idempotencyTtlMs?: number;
+    readonly authenticate?: (request: Request) => Promise<string | null> | string | null;
+    readonly customValidators?: Readonly<Record<string, _stamprally_core.Validator>>;
+    readonly now?: () => string;
 }
 
-export { type AdminRallyConfig, type CheckInRequest, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, InMemoryServerStorage, type InMemoryServerStorageOptions, type RallyAuditLog, type ServerPersistenceAdapter, type ServerStorageAdapter, type StampClaimProof, StampRallyServer, type SyncCheckInOperation, type SyncRequest, type UniversalCheckInRequest, type UniversalCheckInResult, type UniversalClaimRewardRequest, UniversalRallyServer, type UniversalRallyServerOptions, type UniversalVerificationContext, type UserRallyState };
+export { type AuditLog, type CheckInRequest, type CheckInResponse, type ClaimRewardRequest, InMemoryServerPersistenceAdapter, type InMemoryServerPersistenceOptions, type ServerOptions, type ServerPersistenceAdapter, StampRallyServer, type UserClaimRecord };