@stamprally/core 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -1,126 +1,36 @@
-type StampCondition = {
-    readonly type: "instant";
-} | {
-    readonly type: "token";
-    readonly token: string;
-} | {
-    readonly type: "geo";
-    readonly latitude: number;
-    readonly longitude: number;
-    readonly radiusMeters: number;
-} | {
-    readonly type: "composite";
-    readonly operator: "AND" | "OR";
-    readonly conditions: ReadonlyArray<StampCondition>;
-} | {
-    readonly type: "time_window";
-    readonly startsAt: string;
-    readonly endsAt: string;
-    readonly condition: StampCondition;
-};
-type VerificationContext = {
-    readonly type: "instant";
-} | {
-    readonly type: "token";
-    readonly token: string;
-} | {
-    readonly type: "geo";
-    readonly currentLatitude: number;
-    readonly currentLongitude: number;
-} | {
-    readonly type: "composite";
-    readonly contexts: ReadonlyArray<VerificationContext>;
-};
-
-interface ConditionMatch {
-    readonly conditionType: StampCondition["type"];
-    readonly distanceMeters?: number;
+type SupportedLocale = "ja" | "en";
+type LocalizedText<TLocale extends string = string> = string | Partial<Record<TLocale, string>>;
+type LocalizedString<TLocale extends string = SupportedLocale> = Record<TLocale, string>;
+type LocaleDictionary<TLocale extends string = string> = Readonly<Record<TLocale, Readonly<Record<string, string>>>>;
+type SlotShape = "circle" | "square" | "rounded";
+type FontFamily = "system-ui" | "serif" | "rounded-sans" | "monospace" | "handwritten";
+interface SheetTheme {
+    readonly primaryColor: string;
+    readonly backgroundColor?: string;
+    readonly backgroundImageUrl?: string;
+    readonly cardBackgroundColor: string;
+    readonly textColor: string;
+    readonly slotShape: SlotShape;
+    readonly gridColumns: number;
+    readonly unclaimedOpacity?: number;
+    readonly completedStampColor?: string;
+    readonly fontFamily?: FontFamily;
 }
-interface CompositeConditionFailure {
-    readonly index: number;
-    readonly error: ConditionMismatch;
+type ThemePresetId = "default" | "modern_dark" | "pop_candy" | "retro_craft" | "cyber";
+interface ThemePreset<TLocale extends string = SupportedLocale> {
+    readonly id: ThemePresetId;
+    readonly name: LocalizedString<TLocale>;
+    readonly description: LocalizedString<TLocale>;
+    readonly theme: SheetTheme;
 }
-type ConditionMismatch = {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: Exclude<StampCondition["type"], "time_window">;
-    readonly reason: "CONTEXT_TYPE_MISMATCH";
-    readonly expectedContextType: VerificationContext["type"];
-    readonly actualContextType: VerificationContext["type"];
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "token";
-    readonly reason: "TOKEN_MISMATCH";
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "geo";
-    readonly reason: "INVALID_GEO_INPUT";
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "geo";
-    readonly reason: "OUTSIDE_RADIUS";
-    readonly distanceMeters: number;
-    readonly radiusMeters: number;
-    readonly differenceMeters: number;
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "composite";
-    readonly reason: "CONTEXT_LENGTH_MISMATCH";
-    readonly expectedCount: number;
-    readonly actualCount: number;
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "composite";
-    readonly reason: "AND_CHILD_FAILED" | "OR_ALL_FAILED";
-    readonly failures: ReadonlyArray<CompositeConditionFailure>;
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly conditionType: "time_window";
-    readonly reason: "INVALID_NOW" | "INVALID_TIME_WINDOW" | "BEFORE_START" | "AFTER_END";
-    readonly now: string;
-    readonly startsAt: string;
-    readonly endsAt: string;
-};
-type StampError = {
-    readonly code: "STAMP_NOT_FOUND";
-    readonly stampId: string;
-} | {
-    readonly code: "STAMP_ALREADY_ACQUIRED";
-    readonly stampId: string;
-} | {
-    readonly code: "INVALID_ORDER";
-    readonly stampId: string;
-    readonly expectedStampId: string;
-} | {
-    readonly code: "CONDITION_MISMATCH";
-    readonly stampId: string;
-    readonly mismatch: ConditionMismatch;
-} | {
-    readonly code: "OFFLINE_QUEUED";
-    readonly stampId: string;
-    readonly idempotencyKey: string;
-} | {
-    readonly code: "INVALID_PROOF";
-    readonly stampId: string;
-};
-type Result<T, E> = {
-    readonly ok: true;
-    readonly value: T;
-} | {
-    readonly ok: false;
-    readonly error: E;
-};
-
-/** A human-readable value that may be supplied in one or more locales. */
-type UniversalLocalizedText<TLocale extends string = string> = string | Partial<Record<TLocale, string>>;
-/** A link to an entity owned by the host application or another system. */
-interface ExternalReference$1 {
+declare const DEFAULT_SHEET_THEME: SheetTheme;
+interface ExternalReference {
     readonly type: string;
     readonly id: string;
     readonly url?: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-/** Server-only verification material. Never send this shape to a browser. */
-type VerificationCondition = {
+type CheckInCondition = {
     readonly type: "qr";
     readonly secretToken: string;
     readonly qrEntryUrl?: string;
@@ -133,15 +43,17 @@ type VerificationCondition = {
     readonly latitude: number;
     readonly longitude: number;
     readonly radiusMeters: number;
+} | {
+    readonly type: "nfc";
+    readonly tagId: string;
 } | {
     readonly type: "custom";
     readonly validatorName: string;
     readonly secretParams?: Readonly<Record<string, unknown>>;
 };
-/** Safe condition metadata intended for a participant client. */
 type PublicCheckInCondition = {
     readonly type: "qr";
-    readonly qrEntryUrl: string;
+    readonly qrEntryUrl?: string;
 } | {
     readonly type: "passcode";
 } | {
@@ -149,39 +61,30 @@ type PublicCheckInCondition = {
     readonly latitude: number;
     readonly longitude: number;
     readonly radiusMeters: number;
+} | {
+    readonly type: "nfc";
 } | {
     readonly type: "custom";
     readonly validatorName: string;
 };
-interface UniversalSpotItem<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
+interface SpotItem<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
     readonly orderIndex: number;
-    readonly name: UniversalLocalizedText<TLocale>;
-    readonly description?: UniversalLocalizedText<TLocale>;
-    readonly hint?: UniversalLocalizedText<TLocale>;
+    readonly name: LocalizedText<TLocale>;
+    readonly description?: LocalizedText<TLocale>;
+    readonly hint?: LocalizedText<TLocale>;
     readonly imageUrl?: string;
     readonly iconUrl?: string;
     readonly redirectUrlAfterClaim?: string;
-    readonly externalReferences?: ReadonlyArray<ExternalReference$1>;
+    readonly externalReferences?: ReadonlyArray<ExternalReference>;
     readonly metadata?: TMeta;
-    readonly conditions: ReadonlyArray<VerificationCondition>;
+    readonly conditions: ReadonlyArray<CheckInCondition>;
     readonly prerequisites?: ReadonlyArray<string>;
 }
-type AdminReward<TLocale extends string = string> = {
-    readonly id: string;
-    readonly title: UniversalLocalizedText<TLocale>;
-    readonly description?: UniversalLocalizedText<TLocale>;
-    readonly type: "digital" | "in_person";
-    readonly redemptionMethod: "manual_slide" | "staff_passcode" | "view_only" | "server_claim";
-    readonly requiredStampCount: number;
-    readonly conditions?: ReadonlyArray<RewardUnlockCondition$1>;
-    readonly stockLimit?: number;
-    readonly userClaimLimit?: number;
-    readonly staffPasscode?: string;
-    readonly digitalContentUrl?: string;
+type PublicSpotItem<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<SpotItem<TLocale, TMeta>, "conditions"> & {
+    readonly conditions: ReadonlyArray<PublicCheckInCondition>;
 };
-type PublicReward<TLocale extends string = string> = Omit<AdminReward<TLocale>, "staffPasscode" | "digitalContentUrl">;
-type RewardUnlockCondition$1 = {
+type RewardUnlockCondition = {
     readonly type: "stamp_count";
     readonly count: number;
 } | {
@@ -189,127 +92,60 @@ type RewardUnlockCondition$1 = {
     readonly stampIds: ReadonlyArray<string>;
 } | {
     readonly type: "all" | "any";
-    readonly conditions: ReadonlyArray<RewardUnlockCondition$1>;
+    readonly conditions: ReadonlyArray<RewardUnlockCondition>;
 };
+type RewardType = "digital" | "in_person";
+type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "server_claim";
+interface Reward<TLocale extends string = string> {
+    readonly id: string;
+    readonly title: LocalizedText<TLocale>;
+    readonly description?: LocalizedText<TLocale>;
+    readonly type: RewardType;
+    readonly redemptionMethod: RedemptionMethod;
+    readonly requiredStampCount: number;
+    readonly conditions?: ReadonlyArray<RewardUnlockCondition>;
+    readonly digitalContentUrl?: string;
+    readonly staffPasscode?: string;
+    readonly validUntil?: string;
+    readonly stockLimit?: number;
+    readonly userClaimLimit?: number;
+}
+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>> {
     readonly id: string;
     readonly version: string;
-    readonly title: UniversalLocalizedText<TLocale>;
-    readonly description?: UniversalLocalizedText<TLocale>;
+    readonly title: LocalizedText<TLocale>;
+    readonly description?: LocalizedText<TLocale>;
     readonly theme?: SheetTheme;
-    readonly spots: ReadonlyArray<UniversalSpotItem<TLocale, TMeta>>;
-    readonly rewards: ReadonlyArray<AdminReward<TLocale>>;
-    readonly serverEndpoint?: string;
+    readonly spots: ReadonlyArray<SpotItem<TLocale, TMeta>>;
+    readonly rewards: ReadonlyArray<Reward<TLocale>>;
+    readonly staffPasscode?: string;
+    readonly inventory?: Readonly<Record<string, number>>;
+    readonly serverMetadata?: Readonly<Record<string, unknown>>;
     readonly metadata?: TMeta;
+    readonly serverEndpoint?: string;
 }
 interface PublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
     readonly version: string;
-    readonly title: UniversalLocalizedText<TLocale>;
-    readonly description?: UniversalLocalizedText<TLocale>;
+    readonly title: LocalizedText<TLocale>;
+    readonly description?: LocalizedText<TLocale>;
     readonly theme?: SheetTheme;
-    readonly spots: ReadonlyArray<Omit<UniversalSpotItem<TLocale, TMeta>, "conditions"> & {
-        readonly conditions: ReadonlyArray<PublicCheckInCondition>;
-    }>;
+    readonly spots: ReadonlyArray<PublicSpotItem<TLocale, TMeta>>;
     readonly rewards: ReadonlyArray<PublicReward<TLocale>>;
-    readonly serverEndpoint?: string;
-    readonly metadata?: TMeta;
-}
-/** Produce the browser-safe projection without mutating the admin config. */
-declare function toPublicRallyConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: AdminRallyConfig<TLocale, TMeta>): PublicRallyConfig<TLocale, TMeta>;
-/** Runtime guard for values crossing the public configuration boundary. */
-declare function isPublicRallyConfig(value: unknown): value is PublicRallyConfig;
-
-type SupportedLocale = "ja" | "en";
-type LocalizedString<TLocale extends string = SupportedLocale> = Record<TLocale, string>;
-type LocalizedText$1<TLocale extends string = string> = string | Partial<Record<TLocale, string>>;
-type LocaleDictionary<TLocale extends string = string> = Readonly<Record<TLocale, Readonly<Record<string, string>>>>;
-type SlotShape = "circle" | "square" | "rounded";
-type FontFamily = "system-ui" | "serif" | "rounded-sans" | "monospace" | "handwritten";
-interface SheetTheme {
-    readonly primaryColor: string;
-    readonly backgroundColor?: string;
-    readonly backgroundImageUrl?: string;
-    readonly cardBackgroundColor: string;
-    readonly textColor: string;
-    readonly slotShape: SlotShape;
-    readonly gridColumns: number;
-    readonly unclaimedOpacity?: number;
-    readonly completedStampColor?: string;
-    readonly fontFamily?: FontFamily;
-}
-type ThemePresetId = "default" | "modern_dark" | "pop_candy" | "retro_craft" | "cyber";
-interface ThemePreset<TLocale extends string = SupportedLocale> {
-    readonly id: ThemePresetId;
-    readonly name: LocalizedString<TLocale>;
-    readonly description: LocalizedString<TLocale>;
-    readonly theme: SheetTheme;
-}
-declare const DEFAULT_SHEET_THEME: SheetTheme;
-/** @deprecated Use UniversalSpotItem from the universal model. */
-interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
-    readonly id: string;
-    readonly name: LocalizedText$1<TLocale>;
-    readonly description?: LocalizedText$1<TLocale>;
-    readonly hint?: LocalizedText$1<TLocale>;
-    readonly condition: StampCondition;
-    readonly orderIndex?: number;
-    readonly order?: number;
-    readonly deckId?: string;
-    readonly groupId?: string;
-    readonly guideId?: string;
-    readonly iconUrl?: string;
-    readonly imageUrl?: string;
-    readonly externalUrl?: string;
-    readonly redirectUrlAfterClaim?: string;
     readonly metadata?: TMeta;
-    /** Canonical universal-model conditions. Legacy `condition` remains for engine internals. */
-    readonly conditions?: ReadonlyArray<VerificationCondition>;
-    readonly externalReferences?: ReadonlyArray<ExternalReference$1>;
-    readonly prerequisites?: ReadonlyArray<string>;
-    readonly dependsOn?: ReadonlyArray<string>;
-    readonly requiresStampIds?: ReadonlyArray<string>;
+    readonly serverEndpoint?: string;
 }
-/** @deprecated Use SpotItem instead. */
-type StampDefinition<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> = SpotItem<TLocale, TMeta>;
-interface StampRecord$1 {
+type RallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = PublicRallyConfig<TLocale, TMeta>;
+declare function toPublicConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: AdminRallyConfig<TLocale, TMeta>): PublicRallyConfig<TLocale, TMeta>;
+declare function assertPublicConfig(config: unknown): asserts config is PublicRallyConfig;
+declare function isPublicConfig(value: unknown): value is PublicRallyConfig;
+interface StampRecord {
     readonly stampId: string;
     readonly acquiredAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
 }
-type RewardType = "digital" | "in_person";
-type RedemptionMethod = "manual_slide" | "staff_passcode" | "view_only" | "server_claim";
-type RewardUnlockCondition = {
-    readonly type: "stamp_count";
-    readonly count: number;
-} | {
-    readonly type: "stamps";
-    readonly stampIds: ReadonlyArray<string>;
-} | {
-    readonly type: "group_complete";
-    readonly groupId: string;
-} | {
-    readonly type: "all" | "any";
-    readonly conditions: ReadonlyArray<RewardUnlockCondition>;
-};
 type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
-interface RewardItem<TLocale extends string = SupportedLocale> {
-    readonly id: string;
-    readonly title: LocalizedText$1<TLocale>;
-    readonly description: LocalizedText$1<TLocale>;
-    readonly type: RewardType;
-    readonly redemptionMethod: RedemptionMethod;
-    readonly requiredStampCount: number;
-    readonly conditions?: ReadonlyArray<RewardUnlockCondition>;
-    readonly digitalContentUrl?: string;
-    readonly staffPasscode?: string;
-    readonly validUntil?: string;
-    readonly stockLimit?: number;
-    readonly userClaimLimit?: number;
-    readonly maxStock?: number;
-    readonly limitPerUser?: number;
-    readonly claimTicketNumber?: string;
-}
 interface RewardState {
     readonly rewardId: string;
     readonly status: RewardStatus;
@@ -322,104 +158,134 @@ interface RewardState {
 }
 interface StampRallyState {
     readonly rallyId: string;
-    readonly records: ReadonlyArray<StampRecord$1>;
-    readonly rewards?: ReadonlyArray<RewardState>;
+    readonly userId: string | null;
+    readonly records: ReadonlyArray<StampRecord>;
+    readonly rewards: ReadonlyArray<RewardState>;
     readonly updatedAt: string;
 }
-/** @deprecated Use AdminRallyConfig or PublicRallyConfig from the universal model. */
-interface RallyConfig<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
-    readonly id: string;
-    readonly title?: LocalizedText$1<TLocale>;
-    readonly description?: LocalizedText$1<TLocale>;
-    readonly stamps: ReadonlyArray<StampDefinition<TLocale, TMeta>>;
-    readonly rewards?: ReadonlyArray<RewardItem<TLocale>>;
-    readonly isSequential?: boolean;
-    readonly theme?: SheetTheme;
-    readonly version?: number;
-    readonly startDate?: string;
-    readonly endDate?: string;
-}
-
-declare function resolveLocalizedText<TLocale extends string = SupportedLocale>(text: LocalizedText$1<TLocale> | undefined, locale: string, fallbackLocale?: string): string;
-declare function toLocalizedString(text: LocalizedText$1 | undefined): LocalizedString;
-declare function toLocalizedString<TLocale extends string>(text: LocalizedText$1<TLocale> | undefined): LocalizedString<TLocale>;
-
-declare function migrateRallyConfig<TLocale extends string = SupportedLocale>(raw: unknown): RallyConfig<TLocale>;
+type UserRallyState = StampRallyState;
 
-type PublicRewardItem<TLocale extends string = string> = Omit<RewardItem<TLocale>, "staffPasscode">;
-type LegacyPublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<RallyConfig<TLocale, TMeta>, "rewards"> & {
-    readonly rewards?: ReadonlyArray<PublicRewardItem<TLocale>>;
+type VerificationContext = {
+    readonly type: "qr";
+    readonly token: string;
+} | {
+    readonly type: "passcode";
+    readonly code: string;
+} | {
+    readonly type: "gps";
+    readonly latitude: number;
+    readonly longitude: number;
+} | {
+    readonly type: "nfc";
+    readonly tagId: string;
+} | {
+    readonly type: "custom";
+    readonly value: unknown;
 };
-declare function stripSensitiveConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: AdminRallyConfig<TLocale, TMeta>): PublicRallyConfig<TLocale, TMeta>;
-declare function stripSensitiveConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: RallyConfig<TLocale, TMeta>): LegacyPublicRallyConfig<TLocale, TMeta>;
 
-declare const THEME_PRESETS: ReadonlyArray<ThemePreset>;
-
-interface UniversalValidationError {
-    readonly path: string;
-    readonly code: "INVALID_TYPE" | "REQUIRED" | "EMPTY_STRING" | "DUPLICATE_ID" | "INVALID_COORDINATES" | "INVALID_RADIUS" | "INVALID_VERSION" | "INVALID_REWARD" | "CYCLE_DETECTED" | "SECRET_IN_PUBLIC_CONFIG";
+interface ConditionMatch {
+    readonly conditionType: CheckInCondition["type"];
+    readonly distanceMeters?: number;
+}
+type ConditionMismatch = {
+    readonly code: "CONDITION_MISMATCH";
+    readonly conditionType: CheckInCondition["type"];
+    readonly reason: "INVALID_PROOF" | "INVALID_GEO_INPUT" | "OUTSIDE_RADIUS" | "VALIDATOR_FAILED";
+    readonly distanceMeters?: number;
+    readonly radiusMeters?: number;
+};
+interface CompositeConditionFailure {
+    readonly index: number;
+    readonly error: ConditionMismatch;
+}
+type StampError = {
+    readonly code: "SPOT_NOT_FOUND";
+    readonly spotId: string;
+} | {
+    readonly code: "STAMP_ALREADY_ACQUIRED";
+    readonly spotId: string;
+} | {
+    readonly code: "PREREQUISITES_NOT_MET";
+    readonly spotId: string;
+} | {
+    readonly code: "INVALID_PROOF";
+    readonly spotId: string;
+} | {
+    readonly code: "CUSTOM_VALIDATION_FAILED";
+    readonly spotId: string;
     readonly message: string;
+};
+type Result<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+interface CustomValidationContext {
+    readonly rallyId: string;
+    readonly spotId: string;
+    readonly proofData: unknown;
+    readonly condition: Extract<CheckInCondition, {
+        readonly type: "custom";
+    }>;
+    readonly userState: UserRallyState;
 }
-interface UniversalValidationResult {
-    readonly valid: boolean;
-    readonly errors: ReadonlyArray<UniversalValidationError>;
+interface CustomValidator {
+    validate(context: CustomValidationContext): Promise<boolean | {
+        readonly valid: boolean;
+        readonly message?: string;
+    }>;
 }
-declare function validateAdminRallyConfig(value: unknown): UniversalValidationResult;
-declare function validatePublicRallyConfig(value: unknown): UniversalValidationResult;
-declare function isAdminRallyConfig(value: unknown): value is AdminRallyConfig;
-declare function isPublicRallyConfigShape(value: unknown): value is PublicRallyConfig;
+type Validator = CustomValidator | ((context: CustomValidationContext) => Promise<boolean | {
+    readonly valid: boolean;
+    readonly message?: string;
+}> | boolean | {
+    readonly valid: boolean;
+    readonly message?: string;
+});
+
+declare function updateLocalizedField<TLocale extends string>(current: LocalizedText<TLocale> | undefined, locale: TLocale, newValue: string): LocalizedText<TLocale>;
+declare function resolveLocalizedText<TLocale extends string = SupportedLocale>(text: LocalizedText<TLocale> | undefined, locale: string, fallbackLocale?: string): string;
+declare function toLocalizedString(text: LocalizedText | undefined): LocalizedString;
+declare function toLocalizedString<TLocale extends string>(text: LocalizedText<TLocale> | undefined): LocalizedString<TLocale>;
+
+declare const THEME_PRESETS: ReadonlyArray<ThemePreset>;
 
-declare const CURRENT_RALLY_CONFIG_VERSION = 2;
 interface ValidationError {
     readonly path: string;
-    readonly code: "INVALID_TYPE" | "REQUIRED" | "EMPTY_STRING" | "DUPLICATE_ID" | "INVALID_COORDINATES" | "INVALID_RADIUS" | "INVALID_DATE" | "INVALID_VERSION" | "INVALID_REWARD" | "CYCLE_DETECTED";
     readonly message: string;
+    readonly code: string;
 }
-interface RallyConfigValidationResult {
-    readonly valid: boolean;
-    readonly errors: ReadonlyArray<ValidationError>;
-}
-declare function validateRallyConfig(config: unknown): RallyConfigValidationResult;
-
-type CheckInErrorCode = "ORDER_VIOLATION" | "OUT_OF_RANGE" | "EXPIRED" | "INVALID_PROOF" | "INVALID_CONTEXT" | "ALREADY_CLAIMED";
-interface CheckInContext {
-    readonly verificationContext: VerificationContext;
-    readonly now?: string;
-    readonly expectedStampId?: string;
-    readonly proof?: string;
-    readonly alreadyClaimed?: boolean;
-}
-type CheckInInput = VerificationContext | (VerificationContext & {
-    readonly now?: string;
-    readonly expectedStampId?: string;
-    readonly alreadyClaimed?: boolean;
-}) | CheckInContext;
-type CheckInResult$1 = {
-    readonly ok: true;
+type ParseResult<T> = {
     readonly success: true;
-    readonly stampId: string;
-    readonly checkedAt: string;
+    readonly data: T;
 } | {
-    readonly ok: false;
     readonly success: false;
-    readonly code: CheckInErrorCode;
-    readonly stampId: string;
-    readonly message: string;
+    readonly errors: ReadonlyArray<ValidationError>;
 };
-declare function evaluateCheckIn(spot: SpotItem, input: CheckInInput): CheckInResult$1;
+declare class ConfigValidationError extends Error {
+    readonly errors: ReadonlyArray<ValidationError>;
+    readonly name = "ConfigValidationError";
+    constructor(errors: ReadonlyArray<ValidationError>);
+}
+declare function safeParseAdminConfig(input: unknown): ParseResult<AdminRallyConfig>;
+declare function parseAdminConfig(input: unknown): AdminRallyConfig;
+declare function safeParsePublicConfig(input: unknown): ParseResult<PublicRallyConfig>;
+declare function parsePublicConfig(input: unknown): PublicRallyConfig;
 
-declare function calculateDistanceMeters(latitudeA: number, longitudeA: number, latitudeB: number, longitudeB: number): number;
-declare function evaluateConditionDetailed(condition: StampCondition, context: VerificationContext, now: string): Result<ConditionMatch, ConditionMismatch>;
-declare function evaluateCondition(condition: StampCondition, context: VerificationContext, now?: string): boolean;
+declare function calculateDistanceMeters(aLat: number, aLon: number, bLat: number, bLon: number): number;
+declare function evaluateConditionDetailed(condition: CheckInCondition, context: VerificationContext): Result<ConditionMatch, ConditionMismatch>;
+declare function evaluateCondition(condition: CheckInCondition, context: VerificationContext): boolean;
+
+declare function getOrderedSpots<TLocale extends string, TMeta extends Record<string, unknown>>(spots: ReadonlyArray<SpotItem<TLocale, TMeta>>): ReadonlyArray<SpotItem<TLocale, TMeta>>;
 
 interface StampRallyProgress {
     readonly acquired: number;
     readonly total: number;
     readonly percentage: number;
     readonly isCompleted: boolean;
-    /** @deprecated Use isCompleted instead. */
-    readonly isComplete: boolean;
-    readonly nextAvailableStamps: ReadonlyArray<StampDefinition>;
+    readonly nextAvailableSpots: ReadonlyArray<PublicSpotItem>;
 }
 declare function calculateProgress(state: StampRallyState, config: RallyConfig): StampRallyProgress;
 
@@ -430,29 +296,10 @@ interface ClaimTicketOptions {
 declare function createClaimTicketNumber(rewardId: string, options?: ClaimTicketOptions): string;
 /** Creates a one-time ticket for a successful reward consumption. */
 declare function createUniqueClaimTicketNumber(rewardId: string, issuedAt: string): string;
-declare function issueClaimTicketNumber(reward: RewardItem, currentState: RewardState, options?: ClaimTicketOptions): RewardState;
+declare function issueClaimTicketNumber(reward: Reward, currentState: RewardState, options?: ClaimTicketOptions): RewardState;
 
-type StampRallyEvent = {
-    readonly type: "stampAcquired";
-    readonly record: StampRecord$1;
-} | {
-    readonly type: "rallyCompleted";
-    readonly rallyId: string;
-    readonly completedAt: string;
-} | {
-    readonly type: "rewardUnlocked";
-    readonly rewardId: string;
-    readonly unlockedAt: string;
-};
-interface ProcessStampValue {
-    readonly nextState: StampRallyState;
-    readonly events: ReadonlyArray<StampRallyEvent>;
-}
 type RewardConsumeError = {
-    readonly code: "NOT_AVAILABLE";
-    readonly rewardId: string;
-} | {
-    readonly code: "ALREADY_CONSUMED";
+    readonly code: "NOT_AVAILABLE" | "ALREADY_CONSUMED" | "OUT_OF_STOCK" | "REWARD_NOT_FOUND";
     readonly rewardId: string;
 } | {
     readonly code: "INVALID_PASSCODE";
@@ -460,37 +307,35 @@ type RewardConsumeError = {
     readonly message: string;
 } | {
     readonly code: "EXPIRED";
-    readonly reason: "EXPIRED";
-    readonly rewardId: string;
-} | {
-    readonly code: "OUT_OF_STOCK";
     readonly rewardId: string;
 } | {
     readonly code: "USER_LIMIT_REACHED";
-    readonly reason: "LIMIT_EXCEEDED";
-    readonly rewardId: string;
-} | {
-    readonly code: "REWARD_NOT_FOUND";
     readonly rewardId: string;
 };
 interface ConsumeRewardParams {
-    readonly reward: RewardItem;
+    readonly reward: Reward;
     readonly currentState: RewardState;
     readonly inputPasscode?: string;
     readonly staffId?: string;
     readonly now: string;
-    readonly userId?: string;
     readonly userRedemptionCount?: number;
 }
 type ConsumeResult = Result<RewardState, RewardConsumeError>;
-declare function reconcileRewardStates(rewards: ReadonlyArray<RewardItem>, currentStates: ReadonlyArray<RewardState>, acquiredStampCount: number, now: string): ReadonlyArray<RewardState>;
+declare function reconcileRewardStates(rewards: ReadonlyArray<Reward>, currentStates: ReadonlyArray<RewardState>, acquiredStampCount: number, now: string): ReadonlyArray<RewardState>;
 declare function consumeReward(params: ConsumeRewardParams): ConsumeResult;
-declare function processStamp(state: StampRallyState, config: RallyConfig, targetStampId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
+interface ProcessStampValue {
+    readonly nextState: StampRallyState;
+    readonly events: ReadonlyArray<{
+        readonly type: "stampAcquired";
+        readonly record: StampRecord;
+    }>;
+}
+declare function processStamp(state: StampRallyState, config: AdminRallyConfig, spotId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
 
 interface StampStorage {
-    load(rallyId: string): Promise<StampRallyState | null>;
+    load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
     save(state: StampRallyState): Promise<void>;
-    remove(rallyId: string): Promise<void>;
+    remove(rallyId: string, userId: string | null): Promise<void>;
 }
 interface StorageLike {
     getItem(key: string): string | null;
@@ -513,7 +358,8 @@ declare function isStampRallyState(value: unknown): value is StampRallyState;
 interface RallySnapshot {
     readonly version: 1;
     readonly rallyId: string;
-    readonly stamps: ReadonlyArray<StampRecord$1>;
+    readonly userId: string | null;
+    readonly records: ReadonlyArray<StampRecord>;
     readonly rewards: ReadonlyArray<RewardState>;
     readonly exportedAt: string;
 }
@@ -521,10 +367,11 @@ declare function exportProgressToken(snapshot: RallySnapshot): string;
 declare function importProgressToken(token: string, currentRallyId: string): RallySnapshot | null;
 declare class InMemoryStorage implements StampStorage {
     #private;
-    load(rallyId: string): Promise<StampRallyState | null>;
+    load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
     save(state: StampRallyState): Promise<void>;
-    remove(rallyId: string): Promise<void>;
+    remove(rallyId: string, userId: string | null): Promise<void>;
 }
+declare function storageKey(rallyId: string, userId: string | null): string;
 interface LocalStorageAdapterOptions {
     readonly storage?: StorageLike | null;
     readonly keyPrefix?: string;
@@ -536,9 +383,9 @@ type StorageWarningHandler = (error: StorageAdapterError) => void;
 declare class LocalStorageAdapter implements StampStorage {
     #private;
     constructor(options?: LocalStorageAdapterOptions);
-    load(rallyId: string): Promise<StampRallyState | null>;
+    load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
     save(state: StampRallyState): Promise<void>;
-    remove(rallyId: string): Promise<void>;
+    remove(rallyId: string, userId: string | null): Promise<void>;
 }
 interface IndexedDBAdapterOptions {
     readonly indexedDB?: IDBFactory | null;
@@ -547,101 +394,25 @@ interface IndexedDBAdapterOptions {
 declare class IndexedDBAdapter implements StampStorage {
     #private;
     constructor(options?: IndexedDBAdapterOptions);
-    load(rallyId: string): Promise<StampRallyState | null>;
+    load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
     save(state: StampRallyState): Promise<void>;
-    remove(rallyId: string): Promise<void>;
-}
-
-type StampRallyListener = (state: StampRallyState) => void;
-type StampRallyClientEvent = {
-    readonly type: "checkIn";
-    readonly stampId: string;
-    readonly state: StampRallyState;
-} | {
-    readonly type: "rewardClaimed";
-    readonly rewardId: string;
-    readonly state: StampRallyState;
-} | {
-    readonly type: "syncCompleted";
-    readonly state: StampRallyState;
-} | {
-    readonly type: "error";
-    readonly error: unknown;
-};
-type StampRallyEventListener = (event: StampRallyClientEvent) => void;
-type Clock = () => string;
-declare class StampRallyClient {
-    #private;
-    constructor(config: RallyConfig, storage: StampStorage, clock?: Clock);
-    getState(): StampRallyState | null;
-    getConfig(): RallyConfig;
-    subscribe(listener: StampRallyListener): () => void;
-    subscribe(listener: StampRallyEventListener, options: {
-        readonly events: true;
-    }): () => void;
-    subscribeEvents(listener: StampRallyEventListener): () => void;
-    updateConfig(newConfig: LegacyPublicRallyConfig): Promise<StampRallyState>;
-    notifyRewardClaimed(rewardId: string, state?: StampRallyState | null): void;
-    notifySyncCompleted(state?: StampRallyState | null): void;
-    init(): Promise<StampRallyState>;
-    initialize(): Promise<StampRallyState>;
-    acquire(stampId: string, context: VerificationContext, now?: string): Promise<Result<ProcessStampValue, StampError>>;
-    reset(now?: string): Promise<StampRallyState>;
-    restore(state: StampRallyState): Promise<StampRallyState>;
+    remove(rallyId: string, userId: string | null): Promise<void>;
 }
 
-type UserRallyState = StampRallyState;
-type CustomValidator = (context: {
-    readonly spotId: string;
-    readonly proofData: unknown;
-    readonly config: PublicRallyConfig;
-    readonly userState: UserRallyState;
-}) => Promise<{
-    readonly success: boolean;
-    readonly error?: string;
-}>;
-interface CheckInOptions {
+type CheckInOptions = {
     readonly now?: string;
     readonly idempotencyKey?: string;
     readonly sync?: boolean;
-}
-interface ClaimOptions {
+};
+type ClaimOptions = {
     readonly now?: string;
     readonly idempotencyKey?: string;
     readonly staffPasscode?: string;
     readonly staffId?: string;
     readonly sync?: boolean;
-}
-interface UniversalClientRequest {
-    readonly rallyId: string;
-    readonly spotId: string;
-    readonly proofData: unknown;
-    readonly idempotencyKey: string;
-    readonly now: string;
-    readonly state: UserRallyState;
-}
-interface UniversalClaimRequest {
-    readonly rallyId: string;
-    readonly rewardId: string;
-    readonly idempotencyKey: string;
-    readonly now: string;
-    readonly options: ClaimOptions;
-    readonly state: UserRallyState;
-}
-type UniversalClientError = {
-    readonly code: "SPOT_NOT_FOUND";
-    readonly spotId: string;
-    readonly message: string;
-} | {
-    readonly code: "STAMP_ALREADY_ACQUIRED";
-    readonly spotId: string;
-    readonly message: string;
-} | {
-    readonly code: "PREREQUISITES_NOT_MET";
-    readonly spotId: string;
-    readonly message: string;
-} | {
-    readonly code: "INVALID_PROOF";
+};
+type ClientError = {
+    readonly code: "SPOT_NOT_FOUND" | "STAMP_ALREADY_ACQUIRED" | "PREREQUISITES_NOT_MET" | "INVALID_PROOF";
     readonly spotId: string;
     readonly message: string;
 } | {
@@ -655,70 +426,86 @@ type UniversalClientError = {
 } | {
     readonly code: "SYNC_FAILED";
     readonly message: string;
-} | {
-    readonly code: "REMOTE_ERROR";
-    readonly message: string;
 } | RewardConsumeError;
 interface CheckInSuccess {
     readonly state: UserRallyState;
-    readonly record: StampRecord$1;
+    readonly record: StampRecord;
 }
-type UniversalCheckInResult = Result<CheckInSuccess, UniversalClientError>;
-type ClientCheckInResult = UniversalCheckInResult;
+type CheckInResult = Result<CheckInSuccess, ClientError>;
 interface ClaimSuccess {
     readonly state: UserRallyState;
     readonly reward: RewardState;
 }
-type UniversalClaimResult = Result<ClaimSuccess, UniversalClientError>;
-type ClaimResult = UniversalClaimResult;
-type ClientClaimResult = UniversalClaimResult;
-type UniversalClientEvent = {
+type ClaimResult = Result<ClaimSuccess, ClientError>;
+type ClientEvent = {
     readonly type: "checkIn";
-    readonly result: UniversalCheckInResult;
+    readonly result: CheckInResult;
 } | {
     readonly type: "rewardClaimed";
-    readonly result: UniversalClaimResult;
+    readonly result: ClaimResult;
 } | {
     readonly type: "sync";
     readonly state: UserRallyState;
 } | {
     readonly type: "error";
-    readonly error: UniversalClientError;
+    readonly error: ClientError;
 };
-type UniversalClientListener = (state: UserRallyState) => void;
-type UniversalClientEventListener = (event: UniversalClientEvent) => void;
-interface UniversalClientSyncAdapter {
-    readonly checkIn?: (request: UniversalClientRequest) => Promise<UniversalCheckInResult>;
-    readonly claimReward?: (request: UniversalClaimRequest) => Promise<UniversalClaimResult>;
+type ClientListener = (state: UserRallyState) => void;
+type ClientEventListener = (event: ClientEvent) => void;
+interface CheckInRequest {
+    readonly rallyId: string;
+    readonly userId: string | null;
+    readonly spotId: string;
+    readonly proofData: unknown;
+    readonly idempotencyKey: string;
+    readonly now: string;
+    readonly state: UserRallyState;
+}
+interface ClaimRequest {
+    readonly rallyId: string;
+    readonly userId: string | null;
+    readonly rewardId: string;
+    readonly idempotencyKey: string;
+    readonly now: string;
+    readonly options: ClaimOptions;
+    readonly state: UserRallyState;
+}
+interface SyncAdapter {
+    readonly checkIn?: (request: CheckInRequest) => Promise<CheckInResult>;
+    readonly claimReward?: (request: ClaimRequest) => Promise<ClaimResult>;
     readonly sync?: (request: {
         readonly rallyId: string;
+        readonly userId: string | null;
         readonly state: UserRallyState;
     }) => Promise<UserRallyState>;
 }
-interface UniversalStampRallyClientOptions {
+interface ClientOptions {
     readonly storage?: StampStorage;
-    readonly syncAdapter?: UniversalClientSyncAdapter;
-    readonly customValidator?: CustomValidator;
-    readonly customValidators?: Readonly<Record<string, CustomValidator>>;
+    readonly syncAdapter?: SyncAdapter;
+    readonly customValidator?: Validator;
+    readonly customValidators?: Readonly<Record<string, Validator>>;
     readonly clock?: () => string;
+    readonly userId?: string | null;
 }
-type UniversalClientOptionsOrStorage = UniversalStampRallyClientOptions | StampStorage;
-/**
- * Storage- and framework-independent client state machine for a public rally.
- * All operations create new state snapshots and notify subscribers after persistence.
- */
-declare class UniversalStampRallyClient {
+type StorageOrOptions = StampStorage | ClientOptions;
+declare class StampRallyClient {
     #private;
-    constructor(config: PublicRallyConfig, storageOrOptions?: UniversalClientOptionsOrStorage, clock?: () => string);
-    getConfig(): PublicRallyConfig;
+    constructor(config: PublicRallyConfig, storageOrOptions?: StorageOrOptions);
+    getConfig(): RallyConfig;
     getState(): UserRallyState | null;
-    subscribe(listener: UniversalClientListener): () => void;
-    subscribeEvents(listener: UniversalClientEventListener): () => void;
+    getUserId(): string | null;
+    subscribe(listener: ClientListener): () => void;
+    subscribeEvents(listener: ClientEventListener): () => void;
     init(): Promise<UserRallyState>;
     initialize(): Promise<UserRallyState>;
-    checkIn(spotId: string, proofData: unknown, options?: CheckInOptions): Promise<UniversalCheckInResult>;
-    claimReward(rewardId: string, options?: ClaimOptions): Promise<UniversalClaimResult>;
-    sync(adapter?: UniversalClientSyncAdapter): Promise<void>;
+    switchUser(newUserId: string | null): Promise<UserRallyState>;
+    getUserState(rallyId: string, userId: string): Promise<UserRallyState | null>;
+    clearUserState(userId?: string | null): Promise<void>;
+    checkIn(spotId: string, proofData: unknown, options?: CheckInOptions): Promise<CheckInResult>;
+    claimReward(rewardId: string, options?: ClaimOptions): Promise<ClaimResult>;
+    sync(adapter?: SyncAdapter | undefined): Promise<void>;
+    reset(): Promise<UserRallyState>;
+    restore(state: UserRallyState): Promise<UserRallyState>;
 }
 
 type SecureTokenSecretKey = string | Uint8Array;
@@ -756,23 +543,19 @@ interface DetectorError {
     readonly cause?: unknown;
 }
 type GeoVerificationContext = Extract<VerificationContext, {
-    readonly type: "geo";
+    readonly type: "gps";
 }>;
-type TokenVerificationContext = Extract<VerificationContext, {
-    readonly type: "token";
+type QrVerificationContext = Extract<VerificationContext, {
+    readonly type: "qr";
+}>;
+type NfcVerificationContext = Extract<VerificationContext, {
+    readonly type: "nfc";
 }>;
 type DetectorResult<T extends VerificationContext> = Result<T, DetectorError>;
-interface PasscodeCondition {
-    readonly passcode: string;
+interface PasscodeCondition$1 {
+    readonly code: string;
     readonly caseSensitive?: boolean;
 }
-type CheckInResult = {
-    readonly success: true;
-} | {
-    readonly success: false;
-    readonly reason: "INVALID_PASSCODE";
-    readonly message: string;
-};
 
 interface GeoDetectorOptions {
     readonly enableHighAccuracy?: boolean;
@@ -786,10 +569,18 @@ interface NfcDetectorOptions {
     readonly signal?: AbortSignal;
 }
 declare function isNfcSupported(): boolean;
-declare function readNfcContext(options?: NfcDetectorOptions): Promise<DetectorResult<TokenVerificationContext>>;
+declare function readNfcContext(options?: NfcDetectorOptions): Promise<DetectorResult<NfcVerificationContext>>;
 
+interface PasscodeCondition {
+    readonly code: string;
+    readonly caseSensitive?: boolean;
+}
+interface PasscodeCheckResult {
+    readonly success: boolean;
+    readonly message?: string;
+}
 declare function normalizePasscode(input: string, caseSensitive?: boolean): string;
-declare function verifyPasscode(inputCode: string, condition: PasscodeCondition): CheckInResult;
+declare function verifyPasscode(inputCode: string, condition: PasscodeCondition): PasscodeCheckResult;
 
 interface QrDetectorOptions {
     readonly timeout?: number;
@@ -797,188 +588,7 @@ interface QrDetectorOptions {
     readonly facingMode?: "user" | "environment";
 }
 declare function isQrSupported(): boolean;
-declare function readQrContext(videoElement: HTMLVideoElement, options?: QrDetectorOptions): Promise<DetectorResult<TokenVerificationContext>>;
-
-/**
- * Branded identifiers keep values from different parts of the domain from
- * being exchanged accidentally while remaining plain strings at runtime.
- */
-type RallyId = string & {
-    readonly __brand: "RallyId";
-};
-type SpotId = string & {
-    readonly __brand: "SpotId";
-};
-type UserId = string & {
-    readonly __brand: "UserId";
-};
-type Metadata = Readonly<Record<string, unknown>>;
-/** A locale-independent fallback plus zero or more locale-specific values. */
-interface LocalizedText<TLocale extends string = string> {
-    readonly default: string;
-    readonly translations: Readonly<Partial<Record<TLocale, string>>>;
-}
-/** A reference to an entity owned by an external system. */
-interface ExternalReference {
-    readonly systemId: string;
-    readonly entityType: string;
-    readonly entityId: string;
-    readonly attributes?: Metadata;
-}
-/** Public, non-secret configuration for one check-in location. */
-interface SpotDefinition<TLocale extends string = string> {
-    readonly id: SpotId;
-    readonly name: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
-    readonly hint?: LocalizedText<TLocale>;
-    readonly order?: number;
-    readonly iconUrl?: string;
-    readonly imageUrl?: string;
-    readonly externalReference?: ExternalReference;
-    readonly metadata?: Metadata;
-    readonly verification: VerificationRequirement;
-    readonly dependsOn?: ReadonlyArray<SpotId>;
-}
-/** Public description of a verifier selected at runtime through DI. */
-interface VerificationRequirement {
-    readonly pluginId: string;
-    /** Public parameters only; secrets belong to SpotVerificationSecret. */
-    readonly parameters?: Metadata;
-}
-/** Public configuration safe to distribute to a browser client. */
-interface RallyDefinition<TLocale extends string = string> {
-    readonly id: RallyId;
-    readonly title: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
-    readonly spots: ReadonlyArray<SpotDefinition<TLocale>>;
-    readonly startsAt?: string;
-    readonly endsAt?: string;
-    readonly externalReference?: ExternalReference;
-    readonly metadata?: Metadata;
-}
-interface VerificationCoordinates {
-    readonly latitude: number;
-    readonly longitude: number;
-    readonly radiusMeters: number;
-}
-/** Server-only material used by a verifier. Never include this in a public definition. */
-interface SpotVerificationSecret {
-    readonly spotId: SpotId;
-    readonly pluginId: string;
-    readonly secret?: string | Readonly<Uint8Array>;
-    readonly expectedValue?: string;
-    readonly coordinates?: VerificationCoordinates;
-    readonly metadata?: Metadata;
-}
-/** Server-only configuration composed from a public definition and secrets. */
-interface ServerRallyConfig<TLocale extends string = string> {
-    readonly definition: RallyDefinition<TLocale>;
-    readonly verificationSecrets: ReadonlyArray<SpotVerificationSecret>;
-    readonly schemaVersion: SchemaVersion;
-    readonly metadata?: Metadata;
-}
-type SchemaVersion = number;
-interface StampRecord {
-    readonly stampId: SpotId;
-    readonly acquiredAt: string;
-    readonly verificationPluginId?: string;
-    readonly metadata?: Metadata;
-}
-interface RallyProgress {
-    readonly rallyId: RallyId;
-    readonly userId: UserId;
-    readonly stamps: ReadonlyArray<StampRecord>;
-    /** Monotonically increasing revision used for optimistic locking. */
-    readonly stateSequence: number;
-    readonly schemaVersion: SchemaVersion;
-    readonly updatedAt: string;
-    readonly completedAt?: string;
-    readonly metadata?: Metadata;
-}
-interface StorageSaveRequest {
-    readonly progress: RallyProgress;
-    readonly expectedStateSequence: number;
-    readonly idempotencyKey: string;
-}
-type StorageSaveOutcome = {
-    readonly status: "saved";
-    readonly progress: RallyProgress;
-    readonly idempotent: boolean;
-} | {
-    readonly status: "conflict";
-    readonly current: RallyProgress | null;
-};
-/** Persistence boundary. Implementations own transactions and concurrency control. */
-interface StorageAdapter {
-    load(rallyId: RallyId, userId: UserId): Promise<RallyProgress | null>;
-    save(request: StorageSaveRequest): Promise<StorageSaveOutcome>;
-}
-interface AuthContextAdapter<TRequest = unknown> {
-    getUserId(request: TRequest): Promise<UserId | null> | UserId | null;
-}
-interface ValidationInput<TProof = unknown> {
-    readonly rallyId: RallyId;
-    readonly spotId: SpotId;
-    readonly userId: UserId;
-    readonly proof: TProof;
-    readonly requestedAt: string;
-    readonly publicParameters?: Metadata;
-}
-type ValidationOutcome = {
-    readonly valid: true;
-    readonly reason?: string;
-    readonly metadata?: Metadata;
-} | {
-    readonly valid: false;
-    readonly code: string;
-    readonly reason?: string;
-    readonly metadata?: Metadata;
-};
-/** Pluggable verifier for GPS, TOTP/HMAC, signatures, or application rules. */
-interface ConditionVerifierPlugin<TProof = unknown> {
-    readonly id: string;
-    verify(input: ValidationInput<TProof>, secret: SpotVerificationSecret): Promise<ValidationOutcome> | ValidationOutcome;
-}
-interface CheckInAttemptAuditEntry {
-    readonly rallyId: RallyId;
-    readonly spotId: SpotId;
-    readonly userId: UserId;
-    readonly attemptedAt: string;
-    readonly outcome: ValidationOutcome;
-    readonly idempotencyKey?: string;
-    /** Use a digest or other redacted representation; never require raw proof data. */
-    readonly proofDigest?: string;
-    readonly metadata?: Metadata;
-}
-interface AuditLoggerAdapter {
-    logCheckInAttempt(entry: CheckInAttemptAuditEntry): Promise<void>;
-}
-interface StampAcquiredEvent {
-    readonly type: "stampAcquired";
-    readonly rallyId: RallyId;
-    readonly spotId: SpotId;
-    readonly userId: UserId;
-    readonly record: StampRecord;
-}
-interface RallyCompletedEvent {
-    readonly type: "rallyCompleted";
-    readonly rallyId: RallyId;
-    readonly userId: UserId;
-    readonly completedAt: string;
-}
-type RallyEvent = StampAcquiredEvent | RallyCompletedEvent;
-interface EventPublisherAdapter {
-    publish(event: RallyEvent): Promise<void>;
-}
-interface SystemClockAdapter {
-    now(): string;
-}
-interface IdGeneratorAdapter {
-    generate(): string;
-}
-interface StateMigrator {
-    migrate(state: unknown, fromVersion: SchemaVersion, toVersion: SchemaVersion): RallyProgress;
-}
+declare function readQrContext(videoElement: HTMLVideoElement, options?: QrDetectorOptions): Promise<DetectorResult<QrVerificationContext>>;
 
 type SnapshotSecretKey = string | Uint8Array;
 interface SnapshotTokenPayload {
@@ -1003,4 +613,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 AdminReward, type AuditLoggerAdapter, type AuthContextAdapter, CURRENT_RALLY_CONFIG_VERSION, type CheckInAttemptAuditEntry, type CheckInContext, type CheckInErrorCode, type CheckInInput, type CheckInOptions, type CheckInResult$1 as CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientCheckInResult, type ClientClaimResult, type Clock, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConditionVerifierPlugin, type ConsumeResult, type ConsumeRewardParams, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type EventPublisherAdapter, type ExternalReference$1 as ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, type LocalizedText as HeadlessLocalizedText, type IdGeneratorAdapter, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type LegacyPublicRallyConfig, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText$1 as LocalizedText, type Metadata, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicRallyConfig, type PublicReward, type PublicRewardItem, type QrDetectorOptions, type RallyCompletedEvent, type RallyConfig, type RallyConfigValidationResult, type RallyDefinition, type RallyEvent, type RallyId, type RallyProgress, type RallySnapshot, type RedemptionMethod, type Result, type RewardConsumeError, type RewardItem, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SchemaVersion, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type ServerRallyConfig, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotDefinition, type SpotId, type SpotItem, type SpotVerificationSecret, type StampAcquiredEvent, type StampCondition, type StampDefinition, type StampError, StampRallyClient, type StampRallyClientEvent, type StampRallyEvent, type StampRallyEventListener, type StampRallyListener, type StampRallyProgress, type StampRallyState, type StampRecord$1 as StampRecord, type StampStorage, type StateMigrator, type StorageAdapter, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageSaveOutcome, type StorageSaveRequest, type StorageWarningHandler, type SupportedLocale, type SystemClockAdapter, THEME_PRESETS, type ThemePreset, type ThemePresetId, type TokenVerificationContext, type UniversalCheckInResult, type UniversalClaimRequest, type UniversalClaimResult, type UniversalClientError, type UniversalClientEvent, type UniversalClientEventListener, type UniversalClientListener, type UniversalClientRequest, type UniversalClientSyncAdapter, type UniversalLocalizedText, type UniversalSpotItem, UniversalStampRallyClient, type UniversalStampRallyClientOptions, type UniversalValidationError, type UniversalValidationResult, type UserId, type UserRallyState, type ValidationError, type ValidationInput, type ValidationOutcome, type VerificationCondition, type VerificationContext, type VerificationCoordinates, type VerificationRequirement, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCheckIn, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isAdminRallyConfig, isGeolocationSupported, isNfcSupported, isPublicRallyConfig, isPublicRallyConfigShape, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, migrateRallyConfig, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, stripSensitiveConfig, toLocalizedString, toPublicRallyConfig, validateAdminRallyConfig, validatePublicRallyConfig, validateRallyConfig, 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, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, verifyPasscode, verifySecureToken, verifySnapshotToken };