@stamprally/core 0.11.0 → 0.13.0

package/dist/index.d.cts

@@ -147,6 +147,7 @@ interface StampRecord {
     readonly acquiredAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+type SpotStatus = "UNCLAIMED" | "CLAIMED" | "LOCKED" | "VERIFYING";
 type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
 interface RewardState {
     readonly rewardId: string;
@@ -292,6 +293,11 @@ declare function parsePublicConfig(input: unknown): PublicRallyConfig;
 declare function calculateDistanceMeters(aLat: number, aLon: number, bLat: number, bLon: number): number;
 declare function evaluateConditionDetailed(condition: CheckInCondition, context: VerificationContext): Result<ConditionMatch, ConditionMismatch>;
 declare function evaluateCondition(condition: CheckInCondition, context: VerificationContext): boolean;
+/** Derives a viewer-safe spot status without changing the supplied state. */
+declare function evaluateSpotStatus(spot: Pick<SpotItem, "id" | "prerequisites">, state: Pick<UserRallyState, "records">, options?: {
+    readonly verifying?: boolean;
+}): SpotStatus;
+declare const getSpotStatus: typeof evaluateSpotStatus;
 
 declare function getOrderedSpots<TLocale extends string, TMeta extends Record<string, unknown>>(spots: ReadonlyArray<SpotItem<TLocale, TMeta>>): ReadonlyArray<SpotItem<TLocale, TMeta>>;
 
@@ -313,6 +319,12 @@ declare function createClaimTicketNumber(rewardId: string, options?: ClaimTicket
 declare function createUniqueClaimTicketNumber(rewardId: string, issuedAt: string): string;
 declare function issueClaimTicketNumber(reward: Reward, currentState: RewardState, options?: ClaimTicketOptions): RewardState;
 
+interface MergeConflictOptions {
+    readonly policy: "server_wins" | "merge";
+}
+/** Resolves a server/local state conflict without mutating either input state. */
+declare function resolveRallyStateConflict(serverState: UserRallyState, localState: UserRallyState, options?: MergeConflictOptions): UserRallyState;
+
 type RewardConsumeError = {
     readonly code: "NOT_AVAILABLE" | "ALREADY_CONSUMED" | "OUT_OF_STOCK" | "REWARD_NOT_FOUND";
     readonly rewardId: string;
@@ -374,6 +386,10 @@ interface OfflineQueueOptions {
         removeItem?(key: string): void;
     } | null;
     readonly key?: string;
+    /** Rally scope used by the default durable key. */
+    readonly rallyId?: string;
+    /** User scope used by the default durable key. */
+    readonly userId?: string | null;
     readonly databaseName?: string;
     readonly conflictPolicy?: SyncConflictPolicy;
     readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
@@ -383,7 +399,35 @@ interface OfflineConflict {
     readonly localState: UserRallyState;
     readonly serverState: UserRallyState;
 }
-type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult>;
+type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
+type OfflineOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+interface OfflineOperationError {
+    readonly code: string;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+type OfflineOperationResponse = {
+    readonly status: "ACCEPTED";
+    readonly result?: OfflineResult | OfflineConflictResult;
+    readonly state?: UserRallyState;
+} | {
+    readonly status: "REJECTED_PERMANENT";
+    readonly error?: ClientError | OfflineOperationError;
+    readonly reason?: ClientError | OfflineOperationError;
+    readonly state?: UserRallyState;
+} | {
+    readonly status: "RETRYABLE_ERROR";
+    readonly error?: ClientError | OfflineOperationError;
+    readonly reason?: ClientError | OfflineOperationError;
+};
+interface OfflineSyncResultEvent {
+    readonly operation: OfflineOperation;
+    readonly result?: OfflineResult | OfflineConflictResult;
+    readonly status?: OfflineOperationStatus;
+    readonly error?: ClientError | OfflineOperationError;
+    readonly state?: UserRallyState;
+}
+type OfflineSyncResultListener = (event: OfflineSyncResultEvent) => void | Promise<void>;
 declare class MemoryQueueStorage implements OfflineQueueStorage {
     #private;
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
@@ -407,7 +451,15 @@ declare class OfflineQueue {
     get pendingCount(): number;
     get error(): Error | null;
     get operations(): ReadonlyArray<OfflineOperation>;
+    get conflictPolicy(): SyncConflictPolicy;
+    get storageKey(): string;
+    get rallyId(): string | undefined;
+    get userId(): string | null;
+    setSyncResultListener(listener: OfflineSyncResultListener | undefined): void;
     initialize(): Promise<void>;
+    /** Selects a rally/user queue scope and loads its pending operations. */
+    setScope(rallyId: string, userId: string | null): Promise<void>;
+    switchUser(newUserId: string | null): Promise<void>;
     setSender(sender: OfflineSender): void;
     enqueue(operation: OfflineOperation): Promise<void>;
     enqueueCheckIn(request: CheckInRequest): Promise<void>;
@@ -415,7 +467,7 @@ declare class OfflineQueue {
     clear(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
-    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<void>;
+    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
 }
 
 interface StampStorage {
@@ -534,7 +586,7 @@ type ClientEvent = {
     readonly state: UserRallyState;
 } | {
     readonly type: "error";
-    readonly error: ClientError;
+    readonly error: ClientError | OfflineOperationError;
 };
 type ClientListener = (state: UserRallyState) => void;
 type ClientEventListener = (event: ClientEvent) => void;
@@ -703,4 +755,4 @@ type SnapshotTokenVerification<T extends SnapshotTokenPayload = SnapshotTokenPay
 declare function createSignedSnapshotToken<T extends SnapshotTokenPayload>(payload: T, secretKey: SnapshotSecretKey): Promise<string>;
 declare function verifySnapshotToken<T extends SnapshotTokenPayload = SnapshotTokenPayload>(token: string, secretKey: SnapshotSecretKey, now?: number): Promise<SnapshotTokenVerification<T>>;
 
-export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
+export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type MergeConflictOptions, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type OfflineSyncResultEvent, type OfflineSyncResultListener, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type SpotStatus, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/dist/index.d.ts

@@ -147,6 +147,7 @@ interface StampRecord {
     readonly acquiredAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
+type SpotStatus = "UNCLAIMED" | "CLAIMED" | "LOCKED" | "VERIFYING";
 type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
 interface RewardState {
     readonly rewardId: string;
@@ -292,6 +293,11 @@ declare function parsePublicConfig(input: unknown): PublicRallyConfig;
 declare function calculateDistanceMeters(aLat: number, aLon: number, bLat: number, bLon: number): number;
 declare function evaluateConditionDetailed(condition: CheckInCondition, context: VerificationContext): Result<ConditionMatch, ConditionMismatch>;
 declare function evaluateCondition(condition: CheckInCondition, context: VerificationContext): boolean;
+/** Derives a viewer-safe spot status without changing the supplied state. */
+declare function evaluateSpotStatus(spot: Pick<SpotItem, "id" | "prerequisites">, state: Pick<UserRallyState, "records">, options?: {
+    readonly verifying?: boolean;
+}): SpotStatus;
+declare const getSpotStatus: typeof evaluateSpotStatus;
 
 declare function getOrderedSpots<TLocale extends string, TMeta extends Record<string, unknown>>(spots: ReadonlyArray<SpotItem<TLocale, TMeta>>): ReadonlyArray<SpotItem<TLocale, TMeta>>;
 
@@ -313,6 +319,12 @@ declare function createClaimTicketNumber(rewardId: string, options?: ClaimTicket
 declare function createUniqueClaimTicketNumber(rewardId: string, issuedAt: string): string;
 declare function issueClaimTicketNumber(reward: Reward, currentState: RewardState, options?: ClaimTicketOptions): RewardState;
 
+interface MergeConflictOptions {
+    readonly policy: "server_wins" | "merge";
+}
+/** Resolves a server/local state conflict without mutating either input state. */
+declare function resolveRallyStateConflict(serverState: UserRallyState, localState: UserRallyState, options?: MergeConflictOptions): UserRallyState;
+
 type RewardConsumeError = {
     readonly code: "NOT_AVAILABLE" | "ALREADY_CONSUMED" | "OUT_OF_STOCK" | "REWARD_NOT_FOUND";
     readonly rewardId: string;
@@ -374,6 +386,10 @@ interface OfflineQueueOptions {
         removeItem?(key: string): void;
     } | null;
     readonly key?: string;
+    /** Rally scope used by the default durable key. */
+    readonly rallyId?: string;
+    /** User scope used by the default durable key. */
+    readonly userId?: string | null;
     readonly databaseName?: string;
     readonly conflictPolicy?: SyncConflictPolicy;
     readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
@@ -383,7 +399,35 @@ interface OfflineConflict {
     readonly localState: UserRallyState;
     readonly serverState: UserRallyState;
 }
-type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult>;
+type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
+type OfflineOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+interface OfflineOperationError {
+    readonly code: string;
+    readonly message: string;
+    readonly [key: string]: unknown;
+}
+type OfflineOperationResponse = {
+    readonly status: "ACCEPTED";
+    readonly result?: OfflineResult | OfflineConflictResult;
+    readonly state?: UserRallyState;
+} | {
+    readonly status: "REJECTED_PERMANENT";
+    readonly error?: ClientError | OfflineOperationError;
+    readonly reason?: ClientError | OfflineOperationError;
+    readonly state?: UserRallyState;
+} | {
+    readonly status: "RETRYABLE_ERROR";
+    readonly error?: ClientError | OfflineOperationError;
+    readonly reason?: ClientError | OfflineOperationError;
+};
+interface OfflineSyncResultEvent {
+    readonly operation: OfflineOperation;
+    readonly result?: OfflineResult | OfflineConflictResult;
+    readonly status?: OfflineOperationStatus;
+    readonly error?: ClientError | OfflineOperationError;
+    readonly state?: UserRallyState;
+}
+type OfflineSyncResultListener = (event: OfflineSyncResultEvent) => void | Promise<void>;
 declare class MemoryQueueStorage implements OfflineQueueStorage {
     #private;
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
@@ -407,7 +451,15 @@ declare class OfflineQueue {
     get pendingCount(): number;
     get error(): Error | null;
     get operations(): ReadonlyArray<OfflineOperation>;
+    get conflictPolicy(): SyncConflictPolicy;
+    get storageKey(): string;
+    get rallyId(): string | undefined;
+    get userId(): string | null;
+    setSyncResultListener(listener: OfflineSyncResultListener | undefined): void;
     initialize(): Promise<void>;
+    /** Selects a rally/user queue scope and loads its pending operations. */
+    setScope(rallyId: string, userId: string | null): Promise<void>;
+    switchUser(newUserId: string | null): Promise<void>;
     setSender(sender: OfflineSender): void;
     enqueue(operation: OfflineOperation): Promise<void>;
     enqueueCheckIn(request: CheckInRequest): Promise<void>;
@@ -415,7 +467,7 @@ declare class OfflineQueue {
     clear(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
-    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<void>;
+    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
 }
 
 interface StampStorage {
@@ -534,7 +586,7 @@ type ClientEvent = {
     readonly state: UserRallyState;
 } | {
     readonly type: "error";
-    readonly error: ClientError;
+    readonly error: ClientError | OfflineOperationError;
 };
 type ClientListener = (state: UserRallyState) => void;
 type ClientEventListener = (event: ClientEvent) => void;
@@ -703,4 +755,4 @@ type SnapshotTokenVerification<T extends SnapshotTokenPayload = SnapshotTokenPay
 declare function createSignedSnapshotToken<T extends SnapshotTokenPayload>(payload: T, secretKey: SnapshotSecretKey): Promise<string>;
 declare function verifySnapshotToken<T extends SnapshotTokenPayload = SnapshotTokenPayload>(token: string, secretKey: SnapshotSecretKey, now?: number): Promise<SnapshotTokenVerification<T>>;
 
-export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
+export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type MergeConflictOptions, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type OfflineSyncResultEvent, type OfflineSyncResultListener, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type SpotStatus, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/dist/index.js

@@ -39,6 +39,14 @@ function evaluateConditionDetailed(condition2, context) {
 function evaluateCondition(condition2, context) {
   return evaluateConditionDetailed(condition2, context).ok;
 }
+function evaluateSpotStatus(spot2, state, options = {}) {
+  if (options.verifying === true) return "VERIFYING";
+  if (state.records.some((record) => record.stampId === spot2.id)) return "CLAIMED";
+  const acquired = new Set(state.records.map((record) => record.stampId));
+  if (spot2.prerequisites?.some((prerequisite) => !acquired.has(prerequisite))) return "LOCKED";
+  return "UNCLAIMED";
+}
+var getSpotStatus = evaluateSpotStatus;
 
 // src/engine/order.ts
 function getOrderedSpots(spots) {
@@ -97,6 +105,76 @@ function issueClaimTicketNumber(reward2, currentState, options = {}) {
   return { ...currentState, claimTicketNumber };
 }
 
+// src/engine/sync.ts
+function latestTimestamp(serverTimestamp, localTimestamp) {
+  const serverTime = Date.parse(serverTimestamp);
+  const localTime = Date.parse(localTimestamp);
+  if (!Number.isNaN(serverTime) && !Number.isNaN(localTime))
+    return serverTime >= localTime ? serverTimestamp : localTimestamp;
+  if (!Number.isNaN(serverTime)) return serverTimestamp;
+  if (!Number.isNaN(localTime)) return localTimestamp;
+  return serverTimestamp >= localTimestamp ? serverTimestamp : localTimestamp;
+}
+function mergeRewardStates(serverRewards, localRewards) {
+  const merged = new Map(serverRewards.map((reward2) => [reward2.rewardId, reward2]));
+  for (const localReward of localRewards) {
+    const serverReward = merged.get(localReward.rewardId);
+    if (serverReward === void 0) {
+      merged.set(localReward.rewardId, localReward);
+      continue;
+    }
+    const winner = localReward.status === "CONSUMED" && serverReward.status !== "CONSUMED" ? localReward : serverReward;
+    merged.set(localReward.rewardId, {
+      ...winner,
+      ...serverReward.unlockedAt === void 0 && localReward.unlockedAt === void 0 ? {} : {
+        unlockedAt: serverReward.unlockedAt === void 0 ? localReward.unlockedAt : localReward.unlockedAt === void 0 ? serverReward.unlockedAt : latestTimestamp(serverReward.unlockedAt, localReward.unlockedAt)
+      },
+      ...serverReward.consumedAt === void 0 && localReward.consumedAt === void 0 ? {} : {
+        consumedAt: serverReward.consumedAt === void 0 ? localReward.consumedAt : localReward.consumedAt === void 0 ? serverReward.consumedAt : latestTimestamp(serverReward.consumedAt, localReward.consumedAt)
+      },
+      ...serverReward.redeemedCount === void 0 && localReward.redeemedCount === void 0 ? {} : {
+        redeemedCount: Math.max(
+          serverReward.redeemedCount ?? 0,
+          localReward.redeemedCount ?? 0
+        )
+      },
+      ...serverReward.userRedemptionCount === void 0 && localReward.userRedemptionCount === void 0 ? {} : {
+        userRedemptionCount: Math.max(
+          serverReward.userRedemptionCount ?? 0,
+          localReward.userRedemptionCount ?? 0
+        )
+      }
+    });
+  }
+  return [...merged.values()];
+}
+function mergeStampRecords(serverRecords, localRecords) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const record of [...serverRecords, ...localRecords]) {
+    const current = merged.get(record.stampId);
+    if (current === void 0) {
+      merged.set(record.stampId, record);
+      continue;
+    }
+    const acquiredAt = latestTimestamp(current.acquiredAt, record.acquiredAt);
+    merged.set(record.stampId, {
+      ...current,
+      ...acquiredAt === current.acquiredAt ? {} : { acquiredAt },
+      ...current.metadata === void 0 && record.metadata !== void 0 ? { metadata: record.metadata } : {}
+    });
+  }
+  return [...merged.values()];
+}
+function resolveRallyStateConflict(serverState, localState, options = { policy: "merge" }) {
+  if (options.policy === "server_wins") return serverState;
+  return {
+    ...serverState,
+    records: mergeStampRecords(serverState.records, localState.records),
+    rewards: mergeRewardStates(serverState.rewards, localState.rewards),
+    updatedAt: latestTimestamp(serverState.updatedAt, localState.updatedAt)
+  };
+}
+
 // src/detectors/types.ts
 function createDetectorError(detector, code, message, cause) {
   return cause === void 0 ? { detector, code, message } : { detector, code, message, cause };
@@ -998,6 +1076,7 @@ var StampRallyClient = class {
     this.#storage = this.#options.storage ?? new InMemoryStorage();
     this.#userId = this.#options.userId ?? null;
     this.#offlineQueue = this.#options.offlineQueue;
+    this.#offlineQueue?.setSyncResultListener((event) => this.#handleOfflineSyncResult(event));
   }
   getConfig() {
     return this.#config;
@@ -1028,7 +1107,10 @@ var StampRallyClient = class {
   initialize() {
     if (this.#state !== null) return Promise.resolve(this.#state);
     if (this.#initialization === null) {
-      this.#initialization = this.#storage.load(this.#config.id, this.#userId).then((state) => {
+      this.#initialization = (async () => {
+        await this.#offlineQueue?.setScope(this.#config.id, this.#userId);
+        return this.#storage.load(this.#config.id, this.#userId);
+      })().then((state) => {
         const next = state === null ? emptyState(this.#config, this.#userId, this.#now()) : this.#reconcile(state);
         this.#state = next;
         this.#emit(next);
@@ -1046,6 +1128,7 @@ var StampRallyClient = class {
       this.#userId = newUserId;
       this.#state = null;
       this.#initialization = null;
+      await this.#offlineQueue?.switchUser(newUserId);
       return this.initialize();
     });
   }
@@ -1215,12 +1298,19 @@ var StampRallyClient = class {
         });
       }
       if (adapter?.sync === void 0) {
-        this.#emitEvent({ type: "sync", state: current });
+        this.#emitEvent({ type: "sync", state: this.#state ?? current });
         return;
       }
-      const next = this.#reconcile(
-        await adapter.sync({ rallyId: this.#config.id, userId: this.#userId, state: current })
-      );
+      const serverState = await adapter.sync({
+        rallyId: this.#config.id,
+        userId: this.#userId,
+        state: this.#state ?? current
+      });
+      const localState = this.#state ?? current;
+      const merged = this.#offlineQueue === void 0 ? serverState : resolveRallyStateConflict(serverState, localState, {
+        policy: this.#offlineQueue.conflictPolicy
+      });
+      const next = this.#reconcile(merged);
       await this.#storage.save(next);
       this.#state = next;
       this.#emit(next);
@@ -1280,6 +1370,17 @@ var StampRallyClient = class {
       )
     };
   }
+  async #handleOfflineSyncResult(event) {
+    if (event.state !== void 0) {
+      const next = this.#reconcile(event.state);
+      await this.#storage.save(next);
+      this.#state = next;
+      this.#emit(next);
+    }
+    if (event.error !== void 0) this.#emitEvent({ type: "error", error: event.error });
+    else if (event.result !== void 0 && "ok" in event.result && !event.result.ok)
+      this.#emitEvent({ type: "error", error: event.result.error });
+  }
   #now() {
     return this.#options.clock?.() ?? (/* @__PURE__ */ new Date()).toISOString();
   }
@@ -1405,9 +1506,27 @@ function defaultStorage(databaseName) {
 function operationId(operation) {
   return operation.kind === "checkIn" ? `checkIn:${operation.request.rallyId}:${operation.request.userId ?? "anonymous"}:${operation.request.idempotencyKey}` : `claimReward:${operation.request.rallyId}:${operation.request.userId ?? "anonymous"}:${operation.request.idempotencyKey}`;
 }
+function requestScope(operation) {
+  return {
+    rallyId: operation.request.rallyId,
+    userId: operation.request.userId
+  };
+}
+function errorValue(value, fallbackCode) {
+  if (typeof value === "object" && value !== null) {
+    const candidate = value;
+    if (typeof candidate.code === "string" && typeof candidate.message === "string")
+      return { ...candidate, code: candidate.code, message: candidate.message };
+  }
+  if (value instanceof Error) return { code: fallbackCode, message: value.message };
+  if (typeof value === "string") return { code: fallbackCode, message: value };
+  return { code: fallbackCode, message: "Offline operation was rejected." };
+}
 var OfflineQueue = class {
   #storage;
-  #key;
+  #configuredKey;
+  #rallyId;
+  #userId;
   #conflictPolicy;
   #onSyncConflict;
   #operations = [];
@@ -1416,12 +1535,15 @@ var OfflineQueue = class {
   #error = null;
   #sender;
   #syncPromise = null;
+  #syncResultListener;
   constructor(options = {}) {
     if (options.storage !== void 0) this.#storage = options.storage;
     else if (options.storageLike !== void 0 && options.storageLike !== null)
       this.#storage = new LocalStorageQueueStorage(options.storageLike);
     else this.#storage = defaultStorage(options.databaseName);
-    this.#key = options.key ?? "stamprally:offline-queue";
+    this.#configuredKey = options.key;
+    this.#rallyId = options.rallyId;
+    this.#userId = options.userId ?? null;
     this.#conflictPolicy = options.conflictPolicy ?? "server_wins";
     this.#onSyncConflict = options.onSyncConflict;
   }
@@ -1437,20 +1559,60 @@ var OfflineQueue = class {
   get operations() {
     return this.#operations;
   }
+  get conflictPolicy() {
+    return this.#conflictPolicy;
+  }
+  get storageKey() {
+    return this.#storageKey();
+  }
+  get rallyId() {
+    return this.#rallyId;
+  }
+  get userId() {
+    return this.#userId;
+  }
+  setSyncResultListener(listener) {
+    this.#syncResultListener = listener;
+  }
   async initialize() {
     if (this.#loaded) return;
-    this.#operations = [...await this.#storage.load(this.#key)];
+    this.#operations = [...await this.#storage.load(this.#storageKey())];
     this.#loaded = true;
   }
+  /** Selects a rally/user queue scope and loads its pending operations. */
+  async setScope(rallyId, userId) {
+    if (this.#configuredKey !== void 0) {
+      this.#rallyId = rallyId;
+      this.#userId = userId;
+      return this.initialize();
+    }
+    if (this.#rallyId === rallyId && this.#userId === userId && this.#loaded) return;
+    this.#rallyId = rallyId;
+    this.#userId = userId;
+    this.#operations = [];
+    this.#loaded = false;
+    await this.initialize();
+  }
+  async switchUser(newUserId) {
+    if (this.#rallyId === void 0)
+      throw new Error("OfflineQueue.switchUser requires a rally scope.");
+    await this.setScope(this.#rallyId, newUserId);
+  }
   setSender(sender) {
     this.#sender = sender;
   }
   async enqueue(operation) {
+    if (this.#configuredKey === void 0) {
+      const scope = requestScope(operation);
+      if (this.#rallyId === void 0) await this.setScope(scope.rallyId, scope.userId);
+      if (this.#rallyId !== scope.rallyId || this.#userId !== scope.userId)
+        throw new Error("Offline operation belongs to another rally or user queue.");
+    }
     await this.initialize();
     const id2 = operationId(operation);
     if (this.#operations.some((item) => operationId(item) === id2)) return;
     this.#operations = [...this.#operations, operation];
-    await this.#storage.save(this.#key, this.#operations);
+    await this.#storage.save(this.#storageKey(), this.#operations);
   }
   async enqueueCheckIn(request) {
     return this.enqueue({ kind: "checkIn", request });
@@ -1461,7 +1623,7 @@ var OfflineQueue = class {
   async clear() {
     await this.initialize();
     this.#operations = [];
-    await this.#storage.save(this.#key, this.#operations);
+    await this.#storage.save(this.#storageKey(), this.#operations);
   }
   async sync(sender = this.#sender) {
     await this.initialize();
@@ -1483,16 +1645,30 @@ var OfflineQueue = class {
       while (this.#operations.length > 0) {
         const operation = this.#operations[0];
         if (operation === void 0) break;
-        let result;
+        let rawResult;
         try {
-          result = await sender(operation);
+          rawResult = await sender(operation);
         } catch (cause) {
-          throw cause instanceof Error ? cause : new Error(String(cause));
+          throw new Error(errorValue(cause, "RETRYABLE_ERROR").message);
         }
-        if ("conflict" in result && result.conflict === true)
-          await this.resolveConflict(operation, result.localState, result.serverState);
+        const response = this.#normalizeResponse(rawResult);
+        if (response.status === "RETRYABLE_ERROR") {
+          const error2 = errorValue(response.error ?? response.reason, "RETRYABLE_ERROR");
+          await this.#syncResultListener?.({ operation, status: response.status, error: error2 });
+          throw new Error(error2.message);
+        }
+        const result = response.result;
+        const state = response.state ?? (result !== void 0 && "conflict" in result && result.conflict === true ? await this.resolveConflict(operation, result.localState, result.serverState) : result !== void 0 && "ok" in result && result.ok ? result.value.state : void 0);
+        const error = response.status === "REJECTED_PERMANENT" ? errorValue(response.error ?? response.reason, "REJECTED_PERMANENT") : void 0;
         this.#operations = this.#operations.slice(1);
-        await this.#storage.save(this.#key, this.#operations);
+        await this.#storage.save(this.#storageKey(), this.#operations);
+        await this.#syncResultListener?.({
+          operation,
+          ...result === void 0 ? {} : { result },
+          status: response.status,
+          ...error === void 0 ? {} : { error },
+          ...state === void 0 ? {} : { state }
+        });
       }
       this.#state = "idle";
     } catch (cause) {
@@ -1501,12 +1677,29 @@ var OfflineQueue = class {
       throw this.#error;
     }
   }
+  #storageKey() {
+    if (this.#configuredKey !== void 0) return this.#configuredKey;
+    return `stamprally:queue:${this.#rallyId ?? "unscoped"}:${this.#userId ?? "anonymous"}`;
+  }
+  #normalizeResponse(value) {
+    if ("ok" in value) {
+      if (value.ok === false) {
+        if ("status" in value && value.status === "RETRYABLE_ERROR")
+          return { status: "RETRYABLE_ERROR", error: errorValue(value.error, "RETRYABLE_ERROR") };
+        return { status: "REJECTED_PERMANENT", result: value };
+      }
+      return { status: "ACCEPTED", result: value };
+    }
+    if ("status" in value) {
+      if (value.status === "ACCEPTED") return value;
+      return value;
+    }
+    return { status: "ACCEPTED", result: value };
+  }
   async resolveConflict(operation, localState, serverState) {
     const configured = this.#onSyncConflict;
     const policy = (typeof configured === "function" ? await configured({ operation, localState, serverState }) : configured) ?? this.#conflictPolicy;
-    if (policy === "merge") {
-      return;
-    }
+    return resolveRallyStateConflict(serverState, localState, { policy });
   }
 };
 
@@ -2395,6 +2588,6 @@ async function verifySnapshotToken(token, secretKey, now = Date.now()) {
   }
 }
 
-export { ConfigValidationError, DEFAULT_SHEET_THEME, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, IndexedDBOfflineQueueStorage, LocalStorageAdapter, OfflineQueue, StampRallyClient, StorageAdapterError, THEME_PRESETS, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
+export { ConfigValidationError, DEFAULT_SHEET_THEME, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, IndexedDBOfflineQueueStorage, LocalStorageAdapter, OfflineQueue, StampRallyClient, StorageAdapterError, THEME_PRESETS, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map