npm - @stamprally/core - Versions diffs - 0.16.0 → 0.18.0 - Mend

@stamprally/core 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/index.d.cts CHANGED Viewed

@@ -117,6 +117,10 @@ interface Reward<TLocale extends string = string> {
     readonly validUntil?: string;
     readonly stockLimit?: number;
     readonly userClaimLimit?: number;
+    /** Explicit primary inventory key. Defaults to the reward id. */
+    readonly stockKey?: string;
+    /** Optional second inventory bucket that must be decremented atomically. */
+    readonly secondaryStockKey?: string;
 }
 type PublicReward<TLocale extends string = string> = Omit<Reward<TLocale>, "digitalContentUrl" | "staffPasscode">;
 interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
@@ -332,11 +336,9 @@ 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 ConflictResolutionPolicy = "authoritative_replay";
+/** Uses the server snapshot as the immutable replay baseline. */
+declare function resolveRallyStateConflict(serverState: UserRallyState, _localState: UserRallyState): UserRallyState;
 type RewardConsumeError = {
     readonly code: "NOT_AVAILABLE" | "ALREADY_CONSUMED" | "OUT_OF_STOCK" | "REWARD_NOT_FOUND";
@@ -374,20 +376,23 @@ declare function processStamp(state: StampRallyState, config: AdminRallyConfig,
 type QueueOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED_PERMANENT" | "FAILED_RETRYABLE";
 type OfflineQueueCapability = "indexeddb" | "localstorage" | "memory" | "custom";
+type OfflineStorageCapability = OfflineQueueCapability | "volatile_single_tab";
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
+    readonly optimisticState?: UserRallyState;
     readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
+    readonly optimisticState?: UserRallyState;
     readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
-type SyncConflictPolicy = "server_wins" | "merge";
+type SyncConflictPolicy = "authoritative_replay";
 interface OfflineConflictResult {
     readonly conflict: true;
     readonly localState: UserRallyState;
@@ -399,6 +404,12 @@ interface OfflineQueueStorage {
     loadRejectedHistory?(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
     saveRejectedHistory?(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
+interface OfflineQueueCapabilityWarning {
+    readonly type: "STORAGE_CAPABILITY_WARNING";
+    readonly storageCapability: "volatile_single_tab" | "memory";
+    readonly isStoragePersistent: boolean;
+    readonly message: string;
+}
 interface OfflineQueueOptions {
     readonly storage?: OfflineQueueStorage;
     readonly storageLike?: {
@@ -412,8 +423,6 @@ interface OfflineQueueOptions {
     /** 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>);
     /** Enables storage-event/BroadcastChannel synchronization when browser APIs exist. */
     readonly synchronizeInstances?: boolean;
     readonly retryOptions?: SyncRetryOptions;
@@ -426,11 +435,6 @@ interface SyncRetryOptions {
     readonly initialIntervalMs?: number;
     readonly backoffMultiplier?: number;
 }
-interface OfflineConflict {
-    readonly operation: OfflineOperation;
-    readonly localState: UserRallyState;
-    readonly serverState: UserRallyState;
-}
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
 type OfflineOperationStatus = QueueOperationStatus | "REJECTED" | "RETRYABLE_ERROR";
 type OfflineOperationLifecycleStatus = QueueOperationStatus;
@@ -469,6 +473,9 @@ interface OfflineSyncResultEvent {
     readonly state?: UserRallyState;
 }
 type OfflineSyncResultListener = (event: OfflineSyncResultEvent) => void | Promise<void>;
+type OfflineQueueChangeListener = () => void;
+/** Removes only an operation's optimistic changes without mutating its inputs. */
+declare function rollbackOptimisticOperation(state: UserRallyState, operation: OfflineOperation): UserRallyState;
 declare class MemoryQueueStorage implements OfflineQueueStorage {
     #private;
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
@@ -496,14 +503,18 @@ declare class OfflineQueue {
     get syncState(): SyncState;
     get pendingCount(): number;
     get queueCapability(): OfflineQueueCapability;
+    get storageCapability(): OfflineStorageCapability;
+    get isStoragePersistent(): boolean;
     get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
     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;
+    setChangeListener(listener: OfflineQueueChangeListener | undefined): void;
+    setCapabilityWarningListener(listener: ((event: OfflineQueueCapabilityWarning) => void) | undefined): void;
+    setReplayConfig(config: AdminRallyConfig | PublicRallyConfig): void;
     initialize(): Promise<void>;
     /** Releases browser listeners when the queue is no longer used. */
     dispose(): void;
@@ -512,8 +523,8 @@ declare class OfflineQueue {
     switchUser(newUserId: string | null): Promise<void>;
     setSender(sender: OfflineSender): void;
     enqueue(operation: OfflineOperation): Promise<void>;
-    enqueueCheckIn(request: CheckInRequest): Promise<void>;
-    enqueueClaimReward(request: ClaimRequest): Promise<void>;
+    enqueueCheckIn(request: CheckInRequest, optimisticState?: UserRallyState): Promise<void>;
+    enqueueClaimReward(request: ClaimRequest, optimisticState?: UserRallyState): Promise<void>;
     clear(): Promise<void>;
     discardRejected(operationId: string): Promise<boolean>;
     retryRejected(operationId: string): Promise<boolean>;
@@ -522,7 +533,6 @@ declare class OfflineQueue {
     clearRejectedHistory(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
-    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
 }
 interface StampStorage {
@@ -640,12 +650,37 @@ type ClientEvent = {
 } | {
     readonly type: "sync";
     readonly state: UserRallyState;
+} | {
+    readonly type: "syncLifecycle";
+    readonly event: SyncLifecycleEvent;
 } | {
     readonly type: "error";
     readonly error: ClientError | OfflineOperationError;
 };
 type ClientListener = (state: UserRallyState) => void;
 type ClientEventListener = (event: ClientEvent) => void;
+type SyncLifecycleEvent = {
+    readonly type: "SYNC_STARTED";
+} | {
+    readonly type: "OPERATION_ACCEPTED";
+    readonly operationId: string;
+    readonly resourceId: string;
+} | {
+    readonly type: "OPERATION_ROLLED_BACK";
+    readonly operationId: string;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly errorCode: string;
+} | {
+    readonly type: "OPERATION_RETRYABLE_ERROR";
+    readonly operationId: string;
+    readonly error: string;
+} | {
+    readonly type: "SYNC_COMPLETED";
+    readonly totalProcessed: number;
+    readonly failedCount: number;
+};
+type SyncEventListener = (event: SyncLifecycleEvent) => void;
 interface CheckInRequest {
     readonly rallyId: string;
     readonly userId: string | null;
@@ -697,11 +732,18 @@ declare class StampRallyClient {
     get syncState(): SyncState;
     get pendingCount(): number;
     get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
+    getSyncRevision(): number;
     get queueCapability(): OfflineQueueCapability;
+    get storageCapability(): OfflineStorageCapability;
+    get isStoragePersistent(): boolean;
     discardRejected(operationId: string): Promise<boolean>;
     retryRejected(operationId: string): Promise<boolean>;
+    dismissRejectedOperation(operationId: string): Promise<boolean>;
+    retryOperation(operationId: string): Promise<boolean>;
     subscribe(listener: ClientListener): () => void;
     subscribeEvents(listener: ClientEventListener): () => void;
+    subscribeSyncEvents(listener: SyncEventListener): () => void;
+    subscribeSyncState(listener: () => void): () => void;
     init(): Promise<UserRallyState>;
     initialize(): Promise<UserRallyState>;
     switchUser(newUserId: string | null): Promise<UserRallyState>;
@@ -715,6 +757,20 @@ declare class StampRallyClient {
     restore(state: UserRallyState): Promise<UserRallyState>;
 }
+interface RebuildUserStateOptions {
+    readonly baseline: UserRallyState;
+    readonly operations: ReadonlyArray<OfflineOperation>;
+    readonly config?: AdminRallyConfig | PublicRallyConfig;
+}
+interface RebuildUserStateResult {
+    readonly state: UserRallyState;
+    readonly rejectedOperationIds: ReadonlyArray<string>;
+}
+/** Replays the durable operation log on top of a server-confirmed baseline. */
+declare function rebuildUserStateFromLog(baseline: UserRallyState, operations: ReadonlyArray<OfflineOperation>, config?: AdminRallyConfig | PublicRallyConfig): UserRallyState;
+declare function rebuildUserStateFromLog(options: RebuildUserStateOptions): UserRallyState;
+declare function rebuildUserStateLog(baseline: UserRallyState, operations: ReadonlyArray<OfflineOperation>, config?: AdminRallyConfig | PublicRallyConfig): RebuildUserStateResult;
 type SecureTokenSecretKey = string | Uint8Array;
 interface SecureTokenOptions {
     readonly encrypt?: boolean;
@@ -820,4 +876,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, type InventoryAggregationMode, 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 OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, 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 QueueOperationStatus, type RallyConfig, type RallyInventory, type RallyInventoryState, type RallySnapshot, type RedemptionMethod, type RejectedOperation, type RejectedOperationHistoryEntry, 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 SyncRetryOptions, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createAnonymousSessionId, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, offlineOperationId, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, 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 ConflictResolutionPolicy, 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, type InventoryAggregationMode, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, type OfflineQueueCapabilityWarning, type OfflineQueueChangeListener, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type OfflineStorageCapability, 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 QueueOperationStatus, type RallyConfig, type RallyInventory, type RallyInventoryState, type RallySnapshot, type RebuildUserStateOptions, type RebuildUserStateResult, type RedemptionMethod, type RejectedOperation, type RejectedOperationHistoryEntry, 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 SyncEventListener, type SyncLifecycleEvent, type SyncRetryOptions, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createAnonymousSessionId, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, offlineOperationId, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, rebuildUserStateFromLog, rebuildUserStateLog, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, rollbackOptimisticOperation, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/dist/index.d.ts CHANGED Viewed

@@ -117,6 +117,10 @@ interface Reward<TLocale extends string = string> {
     readonly validUntil?: string;
     readonly stockLimit?: number;
     readonly userClaimLimit?: number;
+    /** Explicit primary inventory key. Defaults to the reward id. */
+    readonly stockKey?: string;
+    /** Optional second inventory bucket that must be decremented atomically. */
+    readonly secondaryStockKey?: string;
 }
 type PublicReward<TLocale extends string = string> = Omit<Reward<TLocale>, "digitalContentUrl" | "staffPasscode">;
 interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
@@ -332,11 +336,9 @@ 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 ConflictResolutionPolicy = "authoritative_replay";
+/** Uses the server snapshot as the immutable replay baseline. */
+declare function resolveRallyStateConflict(serverState: UserRallyState, _localState: UserRallyState): UserRallyState;
 type RewardConsumeError = {
     readonly code: "NOT_AVAILABLE" | "ALREADY_CONSUMED" | "OUT_OF_STOCK" | "REWARD_NOT_FOUND";
@@ -374,20 +376,23 @@ declare function processStamp(state: StampRallyState, config: AdminRallyConfig,
 type QueueOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED_PERMANENT" | "FAILED_RETRYABLE";
 type OfflineQueueCapability = "indexeddb" | "localstorage" | "memory" | "custom";
+type OfflineStorageCapability = OfflineQueueCapability | "volatile_single_tab";
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
+    readonly optimisticState?: UserRallyState;
     readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
+    readonly optimisticState?: UserRallyState;
     readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
-type SyncConflictPolicy = "server_wins" | "merge";
+type SyncConflictPolicy = "authoritative_replay";
 interface OfflineConflictResult {
     readonly conflict: true;
     readonly localState: UserRallyState;
@@ -399,6 +404,12 @@ interface OfflineQueueStorage {
     loadRejectedHistory?(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
     saveRejectedHistory?(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
+interface OfflineQueueCapabilityWarning {
+    readonly type: "STORAGE_CAPABILITY_WARNING";
+    readonly storageCapability: "volatile_single_tab" | "memory";
+    readonly isStoragePersistent: boolean;
+    readonly message: string;
+}
 interface OfflineQueueOptions {
     readonly storage?: OfflineQueueStorage;
     readonly storageLike?: {
@@ -412,8 +423,6 @@ interface OfflineQueueOptions {
     /** 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>);
     /** Enables storage-event/BroadcastChannel synchronization when browser APIs exist. */
     readonly synchronizeInstances?: boolean;
     readonly retryOptions?: SyncRetryOptions;
@@ -426,11 +435,6 @@ interface SyncRetryOptions {
     readonly initialIntervalMs?: number;
     readonly backoffMultiplier?: number;
 }
-interface OfflineConflict {
-    readonly operation: OfflineOperation;
-    readonly localState: UserRallyState;
-    readonly serverState: UserRallyState;
-}
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
 type OfflineOperationStatus = QueueOperationStatus | "REJECTED" | "RETRYABLE_ERROR";
 type OfflineOperationLifecycleStatus = QueueOperationStatus;
@@ -469,6 +473,9 @@ interface OfflineSyncResultEvent {
     readonly state?: UserRallyState;
 }
 type OfflineSyncResultListener = (event: OfflineSyncResultEvent) => void | Promise<void>;
+type OfflineQueueChangeListener = () => void;
+/** Removes only an operation's optimistic changes without mutating its inputs. */
+declare function rollbackOptimisticOperation(state: UserRallyState, operation: OfflineOperation): UserRallyState;
 declare class MemoryQueueStorage implements OfflineQueueStorage {
     #private;
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
@@ -496,14 +503,18 @@ declare class OfflineQueue {
     get syncState(): SyncState;
     get pendingCount(): number;
     get queueCapability(): OfflineQueueCapability;
+    get storageCapability(): OfflineStorageCapability;
+    get isStoragePersistent(): boolean;
     get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
     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;
+    setChangeListener(listener: OfflineQueueChangeListener | undefined): void;
+    setCapabilityWarningListener(listener: ((event: OfflineQueueCapabilityWarning) => void) | undefined): void;
+    setReplayConfig(config: AdminRallyConfig | PublicRallyConfig): void;
     initialize(): Promise<void>;
     /** Releases browser listeners when the queue is no longer used. */
     dispose(): void;
@@ -512,8 +523,8 @@ declare class OfflineQueue {
     switchUser(newUserId: string | null): Promise<void>;
     setSender(sender: OfflineSender): void;
     enqueue(operation: OfflineOperation): Promise<void>;
-    enqueueCheckIn(request: CheckInRequest): Promise<void>;
-    enqueueClaimReward(request: ClaimRequest): Promise<void>;
+    enqueueCheckIn(request: CheckInRequest, optimisticState?: UserRallyState): Promise<void>;
+    enqueueClaimReward(request: ClaimRequest, optimisticState?: UserRallyState): Promise<void>;
     clear(): Promise<void>;
     discardRejected(operationId: string): Promise<boolean>;
     retryRejected(operationId: string): Promise<boolean>;
@@ -522,7 +533,6 @@ declare class OfflineQueue {
     clearRejectedHistory(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
-    resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
 }
 interface StampStorage {
@@ -640,12 +650,37 @@ type ClientEvent = {
 } | {
     readonly type: "sync";
     readonly state: UserRallyState;
+} | {
+    readonly type: "syncLifecycle";
+    readonly event: SyncLifecycleEvent;
 } | {
     readonly type: "error";
     readonly error: ClientError | OfflineOperationError;
 };
 type ClientListener = (state: UserRallyState) => void;
 type ClientEventListener = (event: ClientEvent) => void;
+type SyncLifecycleEvent = {
+    readonly type: "SYNC_STARTED";
+} | {
+    readonly type: "OPERATION_ACCEPTED";
+    readonly operationId: string;
+    readonly resourceId: string;
+} | {
+    readonly type: "OPERATION_ROLLED_BACK";
+    readonly operationId: string;
+    readonly resourceId: string;
+    readonly reason: string;
+    readonly errorCode: string;
+} | {
+    readonly type: "OPERATION_RETRYABLE_ERROR";
+    readonly operationId: string;
+    readonly error: string;
+} | {
+    readonly type: "SYNC_COMPLETED";
+    readonly totalProcessed: number;
+    readonly failedCount: number;
+};
+type SyncEventListener = (event: SyncLifecycleEvent) => void;
 interface CheckInRequest {
     readonly rallyId: string;
     readonly userId: string | null;
@@ -697,11 +732,18 @@ declare class StampRallyClient {
     get syncState(): SyncState;
     get pendingCount(): number;
     get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
+    getSyncRevision(): number;
     get queueCapability(): OfflineQueueCapability;
+    get storageCapability(): OfflineStorageCapability;
+    get isStoragePersistent(): boolean;
     discardRejected(operationId: string): Promise<boolean>;
     retryRejected(operationId: string): Promise<boolean>;
+    dismissRejectedOperation(operationId: string): Promise<boolean>;
+    retryOperation(operationId: string): Promise<boolean>;
     subscribe(listener: ClientListener): () => void;
     subscribeEvents(listener: ClientEventListener): () => void;
+    subscribeSyncEvents(listener: SyncEventListener): () => void;
+    subscribeSyncState(listener: () => void): () => void;
     init(): Promise<UserRallyState>;
     initialize(): Promise<UserRallyState>;
     switchUser(newUserId: string | null): Promise<UserRallyState>;
@@ -715,6 +757,20 @@ declare class StampRallyClient {
     restore(state: UserRallyState): Promise<UserRallyState>;
 }
+interface RebuildUserStateOptions {
+    readonly baseline: UserRallyState;
+    readonly operations: ReadonlyArray<OfflineOperation>;
+    readonly config?: AdminRallyConfig | PublicRallyConfig;
+}
+interface RebuildUserStateResult {
+    readonly state: UserRallyState;
+    readonly rejectedOperationIds: ReadonlyArray<string>;
+}
+/** Replays the durable operation log on top of a server-confirmed baseline. */
+declare function rebuildUserStateFromLog(baseline: UserRallyState, operations: ReadonlyArray<OfflineOperation>, config?: AdminRallyConfig | PublicRallyConfig): UserRallyState;
+declare function rebuildUserStateFromLog(options: RebuildUserStateOptions): UserRallyState;
+declare function rebuildUserStateLog(baseline: UserRallyState, operations: ReadonlyArray<OfflineOperation>, config?: AdminRallyConfig | PublicRallyConfig): RebuildUserStateResult;
 type SecureTokenSecretKey = string | Uint8Array;
 interface SecureTokenOptions {
     readonly encrypt?: boolean;
@@ -820,4 +876,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, type InventoryAggregationMode, 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 OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, 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 QueueOperationStatus, type RallyConfig, type RallyInventory, type RallyInventoryState, type RallySnapshot, type RedemptionMethod, type RejectedOperation, type RejectedOperationHistoryEntry, 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 SyncRetryOptions, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createAnonymousSessionId, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, offlineOperationId, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, 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 ConflictResolutionPolicy, 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, type InventoryAggregationMode, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, type OfflineQueueCapabilityWarning, type OfflineQueueChangeListener, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type OfflineStorageCapability, 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 QueueOperationStatus, type RallyConfig, type RallyInventory, type RallyInventoryState, type RallySnapshot, type RebuildUserStateOptions, type RebuildUserStateResult, type RedemptionMethod, type RejectedOperation, type RejectedOperationHistoryEntry, 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 SyncEventListener, type SyncLifecycleEvent, type SyncRetryOptions, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createAnonymousSessionId, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, evaluateSpotStatus, exportProgressToken, getCurrentGeoContext, getOrderedSpots, getSpotStatus, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, offlineOperationId, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, rebuildUserStateFromLog, rebuildUserStateLog, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, rollbackOptimisticOperation, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, verifyPasscode, verifySecureToken, verifySnapshotToken };