@stamprally/core 0.14.0 → 0.15.0

package/dist/index.d.cts

@@ -97,6 +97,13 @@ type RewardUnlockCondition = {
 type RewardType = "digital" | "in_person";
 type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "server_claim";
 type InventoryAggregationMode = "shared" | "per_reward";
+type RallyInventory = Readonly<Record<string, number>> & {
+    readonly sharedStock?: number;
+};
+interface RallyInventoryState {
+    readonly sharedRemaining?: number;
+    readonly rewardRemaining?: Readonly<Record<string, number>>;
+}
 interface Reward<TLocale extends string = string> {
     readonly id: string;
     readonly title: LocalizedText<TLocale>;
@@ -121,7 +128,7 @@ interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record
     readonly spots: ReadonlyArray<SpotItem<TLocale, TMeta>>;
     readonly rewards: ReadonlyArray<Reward<TLocale>>;
     readonly staffPasscode?: string;
-    readonly inventory?: Readonly<Record<string, number>>;
+    readonly inventory?: RallyInventory;
     /** How the optional top-level inventory limit is aggregated. */
     readonly inventoryMode?: InventoryAggregationMode;
     readonly serverMetadata?: Readonly<Record<string, unknown>>;
@@ -167,6 +174,7 @@ interface StampRallyState {
     readonly userId: string | null;
     readonly records: ReadonlyArray<StampRecord>;
     readonly rewards: ReadonlyArray<RewardState>;
+    readonly inventory?: RallyInventoryState;
     readonly updatedAt: string;
 }
 type UserRallyState = StampRallyState;
@@ -367,9 +375,13 @@ declare function processStamp(state: StampRallyState, config: AdminRallyConfig,
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
+    readonly status?: OfflineOperationLifecycleStatus;
+    readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
+    readonly status?: OfflineOperationLifecycleStatus;
+    readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
@@ -400,6 +412,15 @@ interface OfflineQueueOptions {
     readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
     /** Enables storage-event/BroadcastChannel synchronization when browser APIs exist. */
     readonly synchronizeInstances?: boolean;
+    readonly retryOptions?: SyncRetryOptions;
+    readonly retry?: SyncRetryOptions;
+    /** Alias accepted for callers that configure retry behavior at sync time. */
+    readonly syncRetryOptions?: SyncRetryOptions;
+}
+interface SyncRetryOptions {
+    readonly maxRetries?: number;
+    readonly initialIntervalMs?: number;
+    readonly backoffMultiplier?: number;
 }
 interface OfflineConflict {
     readonly operation: OfflineOperation;
@@ -407,7 +428,8 @@ interface OfflineConflict {
     readonly serverState: UserRallyState;
 }
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
-type OfflineOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+type OfflineOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+type OfflineOperationLifecycleStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED";
 interface OfflineOperationError {
     readonly code: string;
     readonly message: string;
@@ -519,6 +541,7 @@ declare class InMemoryStorage implements StampStorage {
     remove(rallyId: string, userId: string | null): Promise<void>;
 }
 declare function storageKey(rallyId: string, userId: string | null): string;
+declare function createAnonymousSessionId(storage?: StorageLike | null): string;
 interface LocalStorageAdapterOptions {
     readonly storage?: StorageLike | null;
     readonly keyPrefix?: string;
@@ -607,6 +630,7 @@ interface CheckInRequest {
     readonly idempotencyKey: string;
     readonly now: string;
     readonly state: UserRallyState;
+    readonly anonymousSessionId?: string;
 }
 interface ClaimRequest {
     readonly rallyId: string;
@@ -616,6 +640,7 @@ interface ClaimRequest {
     readonly now: string;
     readonly options: ClaimOptions;
     readonly state: UserRallyState;
+    readonly anonymousSessionId?: string;
 }
 interface SyncAdapter {
     readonly checkIn?: (request: CheckInRequest) => Promise<CheckInResult>;
@@ -624,6 +649,7 @@ interface SyncAdapter {
         readonly rallyId: string;
         readonly userId: string | null;
         readonly state: UserRallyState;
+        readonly anonymousSessionId?: string;
     }) => Promise<UserRallyState>;
 }
 interface ClientOptions {
@@ -633,6 +659,7 @@ interface ClientOptions {
     readonly customValidators?: Readonly<Record<string, Validator>>;
     readonly clock?: () => string;
     readonly userId?: string | null;
+    readonly anonymousSessionId?: string;
     readonly offlineQueue?: OfflineQueue;
 }
 type StorageOrOptions = StampStorage | ClientOptions;
@@ -642,6 +669,7 @@ declare class StampRallyClient {
     getConfig(): RallyConfig;
     getState(): UserRallyState | null;
     getUserId(): string | null;
+    getAnonymousSessionId(): string;
     get syncState(): SyncState;
     get pendingCount(): number;
     subscribe(listener: ClientListener): () => void;
@@ -764,4 +792,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 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, 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 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 };

package/dist/index.d.ts

@@ -97,6 +97,13 @@ type RewardUnlockCondition = {
 type RewardType = "digital" | "in_person";
 type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "server_claim";
 type InventoryAggregationMode = "shared" | "per_reward";
+type RallyInventory = Readonly<Record<string, number>> & {
+    readonly sharedStock?: number;
+};
+interface RallyInventoryState {
+    readonly sharedRemaining?: number;
+    readonly rewardRemaining?: Readonly<Record<string, number>>;
+}
 interface Reward<TLocale extends string = string> {
     readonly id: string;
     readonly title: LocalizedText<TLocale>;
@@ -121,7 +128,7 @@ interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record
     readonly spots: ReadonlyArray<SpotItem<TLocale, TMeta>>;
     readonly rewards: ReadonlyArray<Reward<TLocale>>;
     readonly staffPasscode?: string;
-    readonly inventory?: Readonly<Record<string, number>>;
+    readonly inventory?: RallyInventory;
     /** How the optional top-level inventory limit is aggregated. */
     readonly inventoryMode?: InventoryAggregationMode;
     readonly serverMetadata?: Readonly<Record<string, unknown>>;
@@ -167,6 +174,7 @@ interface StampRallyState {
     readonly userId: string | null;
     readonly records: ReadonlyArray<StampRecord>;
     readonly rewards: ReadonlyArray<RewardState>;
+    readonly inventory?: RallyInventoryState;
     readonly updatedAt: string;
 }
 type UserRallyState = StampRallyState;
@@ -367,9 +375,13 @@ declare function processStamp(state: StampRallyState, config: AdminRallyConfig,
 type OfflineOperation = {
     readonly kind: "checkIn";
     readonly request: CheckInRequest;
+    readonly status?: OfflineOperationLifecycleStatus;
+    readonly attempts?: number;
 } | {
     readonly kind: "claimReward";
     readonly request: ClaimRequest;
+    readonly status?: OfflineOperationLifecycleStatus;
+    readonly attempts?: number;
 };
 type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
 type SyncState = "idle" | "syncing" | "error";
@@ -400,6 +412,15 @@ interface OfflineQueueOptions {
     readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
     /** Enables storage-event/BroadcastChannel synchronization when browser APIs exist. */
     readonly synchronizeInstances?: boolean;
+    readonly retryOptions?: SyncRetryOptions;
+    readonly retry?: SyncRetryOptions;
+    /** Alias accepted for callers that configure retry behavior at sync time. */
+    readonly syncRetryOptions?: SyncRetryOptions;
+}
+interface SyncRetryOptions {
+    readonly maxRetries?: number;
+    readonly initialIntervalMs?: number;
+    readonly backoffMultiplier?: number;
 }
 interface OfflineConflict {
     readonly operation: OfflineOperation;
@@ -407,7 +428,8 @@ interface OfflineConflict {
     readonly serverState: UserRallyState;
 }
 type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult | OfflineOperationResponse>;
-type OfflineOperationStatus = "ACCEPTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+type OfflineOperationStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED" | "REJECTED_PERMANENT" | "RETRYABLE_ERROR";
+type OfflineOperationLifecycleStatus = "PENDING" | "IN_FLIGHT" | "ACCEPTED" | "REJECTED";
 interface OfflineOperationError {
     readonly code: string;
     readonly message: string;
@@ -519,6 +541,7 @@ declare class InMemoryStorage implements StampStorage {
     remove(rallyId: string, userId: string | null): Promise<void>;
 }
 declare function storageKey(rallyId: string, userId: string | null): string;
+declare function createAnonymousSessionId(storage?: StorageLike | null): string;
 interface LocalStorageAdapterOptions {
     readonly storage?: StorageLike | null;
     readonly keyPrefix?: string;
@@ -607,6 +630,7 @@ interface CheckInRequest {
     readonly idempotencyKey: string;
     readonly now: string;
     readonly state: UserRallyState;
+    readonly anonymousSessionId?: string;
 }
 interface ClaimRequest {
     readonly rallyId: string;
@@ -616,6 +640,7 @@ interface ClaimRequest {
     readonly now: string;
     readonly options: ClaimOptions;
     readonly state: UserRallyState;
+    readonly anonymousSessionId?: string;
 }
 interface SyncAdapter {
     readonly checkIn?: (request: CheckInRequest) => Promise<CheckInResult>;
@@ -624,6 +649,7 @@ interface SyncAdapter {
         readonly rallyId: string;
         readonly userId: string | null;
         readonly state: UserRallyState;
+        readonly anonymousSessionId?: string;
     }) => Promise<UserRallyState>;
 }
 interface ClientOptions {
@@ -633,6 +659,7 @@ interface ClientOptions {
     readonly customValidators?: Readonly<Record<string, Validator>>;
     readonly clock?: () => string;
     readonly userId?: string | null;
+    readonly anonymousSessionId?: string;
     readonly offlineQueue?: OfflineQueue;
 }
 type StorageOrOptions = StampStorage | ClientOptions;
@@ -642,6 +669,7 @@ declare class StampRallyClient {
     getConfig(): RallyConfig;
     getState(): UserRallyState | null;
     getUserId(): string | null;
+    getAnonymousSessionId(): string;
     get syncState(): SyncState;
     get pendingCount(): number;
     subscribe(listener: ClientListener): () => void;
@@ -764,4 +792,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 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, 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 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 };

package/dist/index.js

@@ -615,7 +615,13 @@ function cloneState(state) {
   return {
     ...state,
     records: state.records.map(cloneRecord),
-    ...state.rewards === void 0 ? {} : { rewards: state.rewards.map(cloneRewardState) }
+    ...state.rewards === void 0 ? {} : { rewards: state.rewards.map(cloneRewardState) },
+    ...state.inventory === void 0 ? {} : {
+      inventory: {
+        ...state.inventory,
+        ...state.inventory.rewardRemaining === void 0 ? {} : { rewardRemaining: { ...state.inventory.rewardRemaining } }
+      }
+    }
   };
 }
 function isRecord(value) {
@@ -635,7 +641,7 @@ function isRewardState(value) {
 function isStampRallyState(value) {
   if (typeof value !== "object" || value === null) return false;
   const state = value;
-  return typeof state.rallyId === "string" && (typeof state.userId === "string" || state.userId === null) && typeof state.updatedAt === "string" && Array.isArray(state.records) && state.records.every(isRecord) && (state.rewards === void 0 || Array.isArray(state.rewards) && state.rewards.every(isRewardState));
+  return typeof state.rallyId === "string" && (typeof state.userId === "string" || state.userId === null) && typeof state.updatedAt === "string" && Array.isArray(state.records) && state.records.every(isRecord) && (state.rewards === void 0 || Array.isArray(state.rewards) && state.rewards.every(isRewardState)) && (state.inventory === void 0 || typeof state.inventory === "object" && state.inventory !== null && !Array.isArray(state.inventory) && (state.inventory.sharedRemaining === void 0 || typeof state.inventory.sharedRemaining === "number" && Number.isInteger(state.inventory.sharedRemaining) && state.inventory.sharedRemaining >= 0) && (state.inventory.rewardRemaining === void 0 || typeof state.inventory.rewardRemaining === "object" && state.inventory.rewardRemaining !== null && !Array.isArray(state.inventory.rewardRemaining)));
 }
 function isValidDate(value) {
   return typeof value === "string" && !Number.isNaN(Date.parse(value));
@@ -680,6 +686,35 @@ var InMemoryStorage = class {
 function storageKey(rallyId, userId) {
   return `stamprally:${rallyId}:${userId ?? "anonymous"}`;
 }
+function createAnonymousSessionId(storage) {
+  const key = "stamprally:anonymous-session-id";
+  try {
+    const browserStorage = typeof window === "undefined" ? null : window.localStorage;
+    const value = storage?.getItem(key) ?? browserStorage?.getItem(key);
+    if (value !== null && value !== void 0 && isUuidV4(value)) return value;
+    const generated = randomUuidV4();
+    (storage ?? browserStorage)?.setItem(key, generated);
+    return generated;
+  } catch {
+    return randomUuidV4();
+  }
+}
+function isUuidV4(value) {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function randomUuidV4() {
+  const cryptoApi3 = globalThis.crypto;
+  if (cryptoApi3?.randomUUID !== void 0) return cryptoApi3.randomUUID();
+  if (cryptoApi3?.getRandomValues !== void 0) {
+    const bytes2 = cryptoApi3.getRandomValues(new Uint8Array(16));
+    bytes2[6] = (bytes2[6] ?? 0) & 15 | 64;
+    bytes2[8] = (bytes2[8] ?? 0) & 63 | 128;
+    const hex = Array.from(bytes2, (byte) => byte.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  const random = `${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`.padEnd(32, "0").slice(0, 32);
+  return `${random.slice(0, 8)}-${random.slice(8, 12)}-4${random.slice(13, 16)}-8${random.slice(17, 20)}-${random.slice(20)}`;
+}
 var defaultStorageWarningHandler = (error) => {
   console.warn(`[@stamprally/core] ${error.message}`, error);
 };
@@ -1069,6 +1104,7 @@ var StampRallyClient = class {
   #config;
   #offlineQueue;
   #userId;
+  #anonymousSessionId;
   #state = null;
   #initialization = null;
   #queue = Promise.resolve();
@@ -1076,7 +1112,8 @@ var StampRallyClient = class {
     this.#config = config;
     this.#options = isStorage(storageOrOptions) ? { storage: storageOrOptions } : storageOrOptions;
     this.#storage = this.#options.storage ?? new InMemoryStorage();
-    this.#userId = this.#options.userId ?? null;
+    this.#anonymousSessionId = this.#options.anonymousSessionId ?? createAnonymousSessionId();
+    this.#userId = this.#options.userId ?? this.#anonymousSessionId;
     this.#offlineQueue = this.#options.offlineQueue;
     this.#offlineQueue?.setSyncResultListener((event) => this.#handleOfflineSyncResult(event));
   }
@@ -1089,6 +1126,9 @@ var StampRallyClient = class {
   getUserId() {
     return this.#userId;
   }
+  getAnonymousSessionId() {
+    return this.#anonymousSessionId;
+  }
   get syncState() {
     return this.#offlineQueue?.syncState ?? "idle";
   }
@@ -1126,11 +1166,12 @@ var StampRallyClient = class {
   }
   switchUser(newUserId) {
     return this.#enqueue(async () => {
-      if (this.#userId === newUserId && this.#state !== null) return this.#state;
-      this.#userId = newUserId;
+      const nextUserId = newUserId ?? this.#anonymousSessionId;
+      if (this.#userId === nextUserId && this.#state !== null) return this.#state;
+      this.#userId = nextUserId;
       this.#state = null;
       this.#initialization = null;
-      await this.#offlineQueue?.switchUser(newUserId);
+      await this.#offlineQueue?.switchUser(nextUserId);
       return this.initialize();
     });
   }
@@ -1198,7 +1239,8 @@ var StampRallyClient = class {
         proofData,
         idempotencyKey: options.idempotencyKey ?? id("check-in"),
         now,
-        state: current
+        state: current,
+        ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {}
       };
       const remote = this.#options.syncAdapter?.checkIn;
       if (options.sync !== false && remote !== void 0) {
@@ -1254,7 +1296,8 @@ var StampRallyClient = class {
         idempotencyKey: options.idempotencyKey ?? id("claim"),
         now,
         options,
-        state: current
+        state: current,
+        ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {}
       };
       const remote = this.#options.syncAdapter?.claimReward;
       if (options.sync !== false && remote !== void 0) {
@@ -1306,13 +1349,10 @@ var StampRallyClient = class {
       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
+        state: this.#state ?? current,
+        ...this.#userId === this.#anonymousSessionId ? { anonymousSessionId: this.#anonymousSessionId } : {}
       });
-      const next = this.#reconcile(merged);
+      const next = this.#reconcile(serverState);
       await this.#storage.save(next);
       this.#state = next;
       this.#emit(next);
@@ -1526,6 +1566,11 @@ function errorValue(value, fallbackCode) {
 }
 var syncLocks = /* @__PURE__ */ new Map();
 var SYNC_LOCK_TTL_MS = 3e4;
+var DEFAULT_RETRY_OPTIONS = {
+  maxRetries: 0,
+  initialIntervalMs: 250,
+  backoffMultiplier: 2
+};
 function randomId() {
   return globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
 }
@@ -1544,6 +1589,7 @@ var OfflineQueue = class {
   #syncPromise = null;
   #syncResultListener;
   #synchronizeInstances;
+  #retryOptions;
   #instanceId = randomId();
   #lockStorage;
   #storageListener;
@@ -1559,6 +1605,15 @@ var OfflineQueue = class {
     this.#conflictPolicy = options.conflictPolicy ?? "server_wins";
     this.#onSyncConflict = options.onSyncConflict;
     this.#synchronizeInstances = options.synchronizeInstances ?? true;
+    const retryOptions = {
+      ...DEFAULT_RETRY_OPTIONS,
+      ...options.retryOptions ?? options.syncRetryOptions ?? options.retry ?? {}
+    };
+    this.#retryOptions = {
+      maxRetries: Math.max(0, Math.floor(retryOptions.maxRetries)),
+      initialIntervalMs: Math.max(0, retryOptions.initialIntervalMs),
+      backoffMultiplier: Math.max(1, retryOptions.backoffMultiplier)
+    };
     this.#lockStorage = options.storageLike ?? globalThis.localStorage ?? null;
     if (this.#synchronizeInstances) this.#subscribeToExternalChanges();
   }
@@ -1591,7 +1646,7 @@ var OfflineQueue = class {
   }
   async initialize() {
     if (this.#loaded) return;
-    this.#operations = [...await this.#storage.load(this.#storageKey())];
+    this.#operations = (await this.#storage.load(this.#storageKey())).map(normalizeOperation);
     this.#loaded = true;
   }
   /** Releases browser listeners when the queue is no longer used. */
@@ -1636,7 +1691,7 @@ var OfflineQueue = class {
     await this.initialize();
     const id2 = operationId(operation);
     if (this.#operations.some((item) => operationId(item) === id2)) return;
-    this.#operations = [...this.#operations, operation];
+    this.#operations = [...this.#operations, { ...operation, status: "PENDING", attempts: 0 }];
     await this.#storage.save(this.#storageKey(), this.#operations);
     this.#announceChange();
   }
@@ -1666,6 +1721,33 @@ var OfflineQueue = class {
     return this.sync(sender);
   }
   async #run(sender) {
+    const locks = globalThis.navigator?.locks;
+    if (locks !== void 0) {
+      let callbackStarted = false;
+      try {
+        const acquired = await locks.request(
+          `stamprally:${this.#storageKey()}:sync`,
+          { ifAvailable: true },
+          async (lock) => {
+            if (lock === null) {
+              await this.#reloadFromStorage();
+              this.#state = "idle";
+              return false;
+            }
+            callbackStarted = true;
+            await this.#runWithStorageLock(sender);
+            return true;
+          }
+        );
+        if (!acquired) return;
+        return;
+      } catch (error) {
+        if (callbackStarted) throw error;
+      }
+    }
+    await this.#runWithStorageLock(sender);
+  }
+  async #runWithStorageLock(sender) {
     this.#state = "syncing";
     this.#error = null;
     if (!this.#acquireSyncLock()) {
@@ -1677,21 +1759,36 @@ var OfflineQueue = class {
       while (this.#operations.length > 0) {
         const operation = this.#operations[0];
         if (operation === void 0) break;
-        let rawResult;
-        try {
-          rawResult = await sender(operation);
-        } catch (cause) {
-          throw new Error(errorValue(cause, "RETRYABLE_ERROR").message);
-        }
-        const response = this.#normalizeResponse(rawResult);
-        if (response.status === "RETRYABLE_ERROR") {
+        let attempt = 0;
+        let response;
+        while (true) {
+          await this.#updateOperationStatus("IN_FLIGHT", attempt);
+          try {
+            response = this.#normalizeResponse(await sender(operation));
+          } catch (cause) {
+            response = {
+              status: "RETRYABLE_ERROR",
+              error: errorValue(cause, "RETRYABLE_ERROR")
+            };
+          }
+          if (response.status !== "RETRYABLE_ERROR") break;
           const error2 = errorValue(response.error ?? response.reason, "RETRYABLE_ERROR");
+          await this.#updateOperationStatus("PENDING", attempt + 1);
           await this.#syncResultListener?.({ operation, status: response.status, error: error2 });
-          throw new Error(error2.message);
+          if (attempt >= this.#retryOptions.maxRetries) throw new Error(error2.message);
+          const interval = this.#retryOptions.initialIntervalMs * this.#retryOptions.backoffMultiplier ** attempt;
+          await new Promise((resolve) => setTimeout(resolve, Math.max(0, interval)));
+          attempt += 1;
         }
         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;
+        await this.#updateOperationStatus(
+          response.status === "ACCEPTED" ? "ACCEPTED" : "REJECTED",
+          attempt + 1
+        );
+        const fallbackState = response.status === "REJECTED_PERMANENT" ? operation.request.state : void 0;
+        const eventState = state ?? fallbackState;
         this.#operations = this.#operations.slice(1);
         await this.#storage.save(this.#storageKey(), this.#operations);
         this.#announceChange();
@@ -1700,7 +1797,7 @@ var OfflineQueue = class {
           ...result === void 0 ? {} : { result },
           status: response.status,
           ...error === void 0 ? {} : { error },
-          ...state === void 0 ? {} : { state }
+          ...eventState === void 0 ? {} : { state: eventState }
         });
       }
       this.#state = "idle";
@@ -1712,6 +1809,13 @@ var OfflineQueue = class {
       this.#releaseSyncLock();
     }
   }
+  async #updateOperationStatus(status, attempts) {
+    const operation = this.#operations[0];
+    if (operation === void 0) return;
+    this.#operations = [{ ...operation, status, attempts }, ...this.#operations.slice(1)];
+    await this.#storage.save(this.#storageKey(), this.#operations);
+    this.#announceChange();
+  }
   #subscribeToExternalChanges() {
     const windowLike = globalThis.window;
     if (windowLike !== void 0) {
@@ -1739,7 +1843,7 @@ var OfflineQueue = class {
   async #reloadFromStorage() {
     if (this.#state === "syncing") return;
     try {
-      this.#operations = [...await this.#storage.load(this.#storageKey())];
+      this.#operations = (await this.#storage.load(this.#storageKey())).map(normalizeOperation);
       this.#loaded = true;
     } catch {
     }
@@ -1809,6 +1913,13 @@ var OfflineQueue = class {
     return resolveRallyStateConflict(serverState, localState, { policy });
   }
 };
+function normalizeOperation(operation) {
+  return {
+    ...operation,
+    status: operation.status === "IN_FLIGHT" ? "PENDING" : operation.status ?? "PENDING",
+    attempts: operation.attempts ?? 0
+  };
+}
 
 // src/crypto/token.ts
 var encoder = new TextEncoder();
@@ -2377,6 +2488,8 @@ function condition(value, path, errors, isPublic) {
     finiteNumber(value, "latitude", path, errors);
     finiteNumber(value, "longitude", path, errors);
     finiteNumber(value, "radiusMeters", path, errors, 0);
+    if (typeof value.radiusMeters === "number" && value.radiusMeters <= 0)
+      add(errors, `${path}.radiusMeters`, "Expected a radius greater than 0.", "out_of_range");
     if (typeof value.latitude === "number" && (value.latitude < -90 || value.latitude > 90))
       add(errors, `${path}.latitude`, "Expected a latitude between -90 and 90.", "out_of_range");
     if (typeof value.longitude === "number" && (value.longitude < -180 || value.longitude > 180))
@@ -2787,6 +2900,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, 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 { ConfigValidationError, DEFAULT_SHEET_THEME, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, IndexedDBOfflineQueueStorage, LocalStorageAdapter, OfflineQueue, StampRallyClient, StorageAdapterError, THEME_PRESETS, 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 };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map