@stamprally/core 0.15.0 → 0.17.0

package/dist/index.d.cts

@@ -99,6 +99,7 @@ type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "serve
 type InventoryAggregationMode = "shared" | "per_reward";
 type RallyInventory = Readonly<Record<string, number>> & {
     readonly sharedStock?: number;
+    readonly global?: number;
 };
 interface RallyInventoryState {
     readonly sharedRemaining?: number;
@@ -332,8 +333,10 @@ 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;
 
+type ConflictResolutionPolicy = "authoritative_replay" | "server_wins" | "merge";
 interface MergeConflictOptions {
-    readonly policy: "server_wins" | "merge";
+    /** `merge` is retained for compatibility; synchronization paths use `authoritative_replay`. */
+    readonly policy: ConflictResolutionPolicy;
 }
 /** Resolves a server/local state conflict without mutating either input state. */
 declare function resolveRallyStateConflict(serverState: UserRallyState, localState: UserRallyState, options?: MergeConflictOptions): UserRallyState;
@@ -372,20 +375,22 @@ interface ProcessStampValue {
 }
 declare function processStamp(state: StampRallyState, config: AdminRallyConfig, spotId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
 
+type QueueOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED_PERMANENT" | "FAILED_RETRYABLE";
+type OfflineQueueCapability = "indexeddb" | "localstorage" | "memory" | "custom";
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
-    readonly status?: OfflineOperationLifecycleStatus;
+    readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
-    readonly status?: OfflineOperationLifecycleStatus;
+    readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
-type SyncConflictPolicy = "server_wins" | "merge";
+type SyncConflictPolicy = ConflictResolutionPolicy;
 interface OfflineConflictResult {
     readonly conflict: true;
     readonly localState: UserRallyState;
@@ -394,6 +399,8 @@ interface OfflineConflictResult {
 interface OfflineQueueStorage {
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory?(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory?(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
 interface OfflineQueueOptions {
     readonly storage?: OfflineQueueStorage;
@@ -428,13 +435,21 @@ interface OfflineConflict {
     readonly serverState: UserRallyState;
 }
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
-type OfflineOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
-type OfflineOperationLifecycleStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED";
+type OfflineOperationStatus = QueueOperationStatus | "REJECTED" | "RETRYABLE_ERROR";
+type OfflineOperationLifecycleStatus = QueueOperationStatus;
 interface OfflineOperationError {
     readonly code: string;
     readonly message: string;
     readonly [key: string]: unknown;
 }
+interface RejectedOperationHistoryEntry {
+    readonly operation: OfflineOperation;
+    readonly reason: OfflineOperationError;
+    readonly errorCode: string;
+    readonly rejectedAt: string;
+    readonly attempts: number;
+}
+type RejectedOperation = RejectedOperationHistoryEntry;
 type OfflineOperationResponse = {
     readonly status: "ACCEPTED";
     readonly result?: OfflineResult | OfflineConflictResult;
@@ -457,10 +472,15 @@ 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>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
 interface IndexedDBOfflineQueueOptions {
     readonly indexedDB?: IDBFactory | null;
@@ -471,13 +491,18 @@ declare class IndexedDBOfflineQueueStorage implements OfflineQueueStorage {
     constructor(options?: IndexedDBOfflineQueueOptions);
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
+declare function offlineOperationId(operation: OfflineOperation): string;
 /** Durable, sequential retry queue for operations created while disconnected. */
 declare class OfflineQueue {
     #private;
     constructor(options?: OfflineQueueOptions);
     get syncState(): SyncState;
     get pendingCount(): number;
+    get queueCapability(): OfflineQueueCapability;
+    get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
     get error(): Error | null;
     get operations(): ReadonlyArray<OfflineOperation>;
     get conflictPolicy(): SyncConflictPolicy;
@@ -485,6 +510,7 @@ declare class OfflineQueue {
     get rallyId(): string | undefined;
     get userId(): string | null;
     setSyncResultListener(listener: OfflineSyncResultListener | undefined): void;
+    setChangeListener(listener: OfflineQueueChangeListener | undefined): void;
     initialize(): Promise<void>;
     /** Releases browser listeners when the queue is no longer used. */
     dispose(): void;
@@ -496,6 +522,11 @@ declare class OfflineQueue {
     enqueueCheckIn(request: CheckInRequest): Promise<void>;
     enqueueClaimReward(request: ClaimRequest): Promise<void>;
     clear(): Promise<void>;
+    discardRejected(operationId: string): Promise<boolean>;
+    retryRejected(operationId: string): Promise<boolean>;
+    discardRejectedOperation(operationId: string): Promise<boolean>;
+    retryRejectedOperation(operationId: string): Promise<boolean>;
+    clearRejectedHistory(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
     resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
@@ -616,12 +647,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;
@@ -661,6 +717,9 @@ interface ClientOptions {
     readonly userId?: string | null;
     readonly anonymousSessionId?: string;
     readonly offlineQueue?: OfflineQueue;
+    readonly conflictResolutionPolicy?: ConflictResolutionPolicy;
+    /** Alias for conflictResolutionPolicy. */
+    readonly conflictPolicy?: ConflictResolutionPolicy;
 }
 type StorageOrOptions = StampStorage | ClientOptions;
 declare class StampRallyClient {
@@ -672,8 +731,17 @@ declare class StampRallyClient {
     getAnonymousSessionId(): string;
     get syncState(): SyncState;
     get pendingCount(): number;
+    get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
+    getSyncRevision(): number;
+    get queueCapability(): OfflineQueueCapability;
+    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>;
@@ -792,4 +860,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 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 RallyInventory, type RallyInventoryState, 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 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, 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 MergeConflictOptions, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, type OfflineQueueChangeListener, 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 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, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, rollbackOptimisticOperation, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/dist/index.d.ts

@@ -99,6 +99,7 @@ type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "serve
 type InventoryAggregationMode = "shared" | "per_reward";
 type RallyInventory = Readonly<Record<string, number>> & {
     readonly sharedStock?: number;
+    readonly global?: number;
 };
 interface RallyInventoryState {
     readonly sharedRemaining?: number;
@@ -332,8 +333,10 @@ 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;
 
+type ConflictResolutionPolicy = "authoritative_replay" | "server_wins" | "merge";
 interface MergeConflictOptions {
-    readonly policy: "server_wins" | "merge";
+    /** `merge` is retained for compatibility; synchronization paths use `authoritative_replay`. */
+    readonly policy: ConflictResolutionPolicy;
 }
 /** Resolves a server/local state conflict without mutating either input state. */
 declare function resolveRallyStateConflict(serverState: UserRallyState, localState: UserRallyState, options?: MergeConflictOptions): UserRallyState;
@@ -372,20 +375,22 @@ interface ProcessStampValue {
 }
 declare function processStamp(state: StampRallyState, config: AdminRallyConfig, spotId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
 
+type QueueOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED_PERMANENT" | "FAILED_RETRYABLE";
+type OfflineQueueCapability = "indexeddb" | "localstorage" | "memory" | "custom";
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
-    readonly status?: OfflineOperationLifecycleStatus;
+    readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
-    readonly status?: OfflineOperationLifecycleStatus;
+    readonly status?: QueueOperationStatus;
     readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
-type SyncConflictPolicy = "server_wins" | "merge";
+type SyncConflictPolicy = ConflictResolutionPolicy;
 interface OfflineConflictResult {
     readonly conflict: true;
     readonly localState: UserRallyState;
@@ -394,6 +399,8 @@ interface OfflineConflictResult {
 interface OfflineQueueStorage {
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory?(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory?(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
 interface OfflineQueueOptions {
     readonly storage?: OfflineQueueStorage;
@@ -428,13 +435,21 @@ interface OfflineConflict {
     readonly serverState: UserRallyState;
 }
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
-type OfflineOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
-type OfflineOperationLifecycleStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED";
+type OfflineOperationStatus = QueueOperationStatus | "REJECTED" | "RETRYABLE_ERROR";
+type OfflineOperationLifecycleStatus = QueueOperationStatus;
 interface OfflineOperationError {
     readonly code: string;
     readonly message: string;
     readonly [key: string]: unknown;
 }
+interface RejectedOperationHistoryEntry {
+    readonly operation: OfflineOperation;
+    readonly reason: OfflineOperationError;
+    readonly errorCode: string;
+    readonly rejectedAt: string;
+    readonly attempts: number;
+}
+type RejectedOperation = RejectedOperationHistoryEntry;
 type OfflineOperationResponse = {
     readonly status: "ACCEPTED";
     readonly result?: OfflineResult | OfflineConflictResult;
@@ -457,10 +472,15 @@ 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>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
 interface IndexedDBOfflineQueueOptions {
     readonly indexedDB?: IDBFactory | null;
@@ -471,13 +491,18 @@ declare class IndexedDBOfflineQueueStorage implements OfflineQueueStorage {
     constructor(options?: IndexedDBOfflineQueueOptions);
     load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
     save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
+    loadRejectedHistory(key: string): Promise<ReadonlyArray<RejectedOperationHistoryEntry>>;
+    saveRejectedHistory(key: string, history: ReadonlyArray<RejectedOperationHistoryEntry>): Promise<void>;
 }
+declare function offlineOperationId(operation: OfflineOperation): string;
 /** Durable, sequential retry queue for operations created while disconnected. */
 declare class OfflineQueue {
     #private;
     constructor(options?: OfflineQueueOptions);
     get syncState(): SyncState;
     get pendingCount(): number;
+    get queueCapability(): OfflineQueueCapability;
+    get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
     get error(): Error | null;
     get operations(): ReadonlyArray<OfflineOperation>;
     get conflictPolicy(): SyncConflictPolicy;
@@ -485,6 +510,7 @@ declare class OfflineQueue {
     get rallyId(): string | undefined;
     get userId(): string | null;
     setSyncResultListener(listener: OfflineSyncResultListener | undefined): void;
+    setChangeListener(listener: OfflineQueueChangeListener | undefined): void;
     initialize(): Promise<void>;
     /** Releases browser listeners when the queue is no longer used. */
     dispose(): void;
@@ -496,6 +522,11 @@ declare class OfflineQueue {
     enqueueCheckIn(request: CheckInRequest): Promise<void>;
     enqueueClaimReward(request: ClaimRequest): Promise<void>;
     clear(): Promise<void>;
+    discardRejected(operationId: string): Promise<boolean>;
+    retryRejected(operationId: string): Promise<boolean>;
+    discardRejectedOperation(operationId: string): Promise<boolean>;
+    retryRejectedOperation(operationId: string): Promise<boolean>;
+    clearRejectedHistory(): Promise<void>;
     sync(sender?: OfflineSender | undefined): Promise<void>;
     retrySync(sender?: OfflineSender | undefined): Promise<void>;
     resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<UserRallyState>;
@@ -616,12 +647,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;
@@ -661,6 +717,9 @@ interface ClientOptions {
     readonly userId?: string | null;
     readonly anonymousSessionId?: string;
     readonly offlineQueue?: OfflineQueue;
+    readonly conflictResolutionPolicy?: ConflictResolutionPolicy;
+    /** Alias for conflictResolutionPolicy. */
+    readonly conflictPolicy?: ConflictResolutionPolicy;
 }
 type StorageOrOptions = StampStorage | ClientOptions;
 declare class StampRallyClient {
@@ -672,8 +731,17 @@ declare class StampRallyClient {
     getAnonymousSessionId(): string;
     get syncState(): SyncState;
     get pendingCount(): number;
+    get rejectedHistory(): ReadonlyArray<RejectedOperationHistoryEntry>;
+    getSyncRevision(): number;
+    get queueCapability(): OfflineQueueCapability;
+    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>;
@@ -792,4 +860,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 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 RallyInventory, type RallyInventoryState, 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 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, 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 MergeConflictOptions, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, type OfflineOperationError, type OfflineOperationLifecycleStatus, type OfflineOperationResponse, type OfflineOperationStatus, OfflineQueue, type OfflineQueueCapability, type OfflineQueueChangeListener, 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 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, reconcileRewardStates, resolveLocalizedText, resolveRallyStateConflict, rollbackOptimisticOperation, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, validateRallyConfigRelations, verifyPasscode, verifySecureToken, verifySnapshotToken };