@stamprally/core 0.5.1 → 0.6.0

package/dist/index.d.cts

@@ -112,7 +112,7 @@ type Result<T, E> = {
 
 type SupportedLocale = "ja" | "en";
 type LocalizedString<TLocale extends string = SupportedLocale> = Record<TLocale, string>;
-type LocalizedText<TLocale extends string = string> = string | Partial<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";
@@ -138,9 +138,9 @@ interface ThemePreset<TLocale extends string = SupportedLocale> {
 declare const DEFAULT_SHEET_THEME: SheetTheme;
 interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
-    readonly name: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
-    readonly hint?: LocalizedText<TLocale>;
+    readonly name: LocalizedText$1<TLocale>;
+    readonly description?: LocalizedText$1<TLocale>;
+    readonly hint?: LocalizedText$1<TLocale>;
     readonly condition: StampCondition;
     readonly orderIndex?: number;
     readonly order?: number;
@@ -157,7 +157,7 @@ interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Recor
 }
 /** @deprecated Use SpotItem instead. */
 type StampDefinition<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> = SpotItem<TLocale, TMeta>;
-interface StampRecord {
+interface StampRecord$1 {
     readonly stampId: string;
     readonly acquiredAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -180,8 +180,8 @@ type RewardUnlockCondition = {
 type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
 interface RewardItem<TLocale extends string = SupportedLocale> {
     readonly id: string;
-    readonly title: LocalizedText<TLocale>;
-    readonly description: LocalizedText<TLocale>;
+    readonly title: LocalizedText$1<TLocale>;
+    readonly description: LocalizedText$1<TLocale>;
     readonly type: RewardType;
     readonly redemptionMethod: RedemptionMethod;
     readonly requiredStampCount: number;
@@ -207,14 +207,14 @@ interface RewardState {
 }
 interface StampRallyState {
     readonly rallyId: string;
-    readonly records: ReadonlyArray<StampRecord>;
+    readonly records: ReadonlyArray<StampRecord$1>;
     readonly rewards?: ReadonlyArray<RewardState>;
     readonly updatedAt: string;
 }
 interface RallyConfig<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
-    readonly title?: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
+    readonly title?: LocalizedText$1<TLocale>;
+    readonly description?: LocalizedText$1<TLocale>;
     readonly stamps: ReadonlyArray<StampDefinition<TLocale, TMeta>>;
     readonly rewards?: ReadonlyArray<RewardItem<TLocale>>;
     readonly isSequential?: boolean;
@@ -224,9 +224,9 @@ interface RallyConfig<TLocale extends string = SupportedLocale, TMeta extends Re
     readonly endDate?: string;
 }
 
-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 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>;
 
@@ -303,7 +303,7 @@ declare function issueClaimTicketNumber(reward: RewardItem, currentState: Reward
 
 type StampRallyEvent = {
     readonly type: "stampAcquired";
-    readonly record: StampRecord;
+    readonly record: StampRecord$1;
 } | {
     readonly type: "rallyCompleted";
     readonly rallyId: string;
@@ -382,7 +382,7 @@ declare function isStampRallyState(value: unknown): value is StampRallyState;
 interface RallySnapshot {
     readonly version: 1;
     readonly rallyId: string;
-    readonly stamps: ReadonlyArray<StampRecord>;
+    readonly stamps: ReadonlyArray<StampRecord$1>;
     readonly rewards: ReadonlyArray<RewardState>;
     readonly exportedAt: string;
 }
@@ -537,6 +537,187 @@ interface QrDetectorOptions {
 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;
+}
+
 type SnapshotSecretKey = string | Uint8Array;
 interface SnapshotTokenPayload {
     readonly [key: string]: unknown;
@@ -560,4 +741,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 { CURRENT_RALLY_CONFIG_VERSION, type CheckInContext, type CheckInErrorCode, type CheckInInput, type CheckInResult$1 as CheckInResult, type ClaimTicketOptions, type Clock, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConsumeResult, type ConsumeRewardParams, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type PublicRallyConfig, type PublicRewardItem, type QrDetectorOptions, type RallyConfig, type RallyConfigValidationResult, type RallySnapshot, type RedemptionMethod, type Result, type RewardConsumeError, type RewardItem, 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 StampCondition, type StampDefinition, type StampError, StampRallyClient, type StampRallyClientEvent, type StampRallyEvent, type StampRallyEventListener, type StampRallyListener, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, THEME_PRESETS, type ThemePreset, type ThemePresetId, type TokenVerificationContext, type ValidationError, type VerificationContext, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCheckIn, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isGeolocationSupported, isNfcSupported, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, migrateRallyConfig, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, stripSensitiveConfig, toLocalizedString, validateRallyConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };
+export { type AuditLoggerAdapter, type AuthContextAdapter, CURRENT_RALLY_CONFIG_VERSION, type CheckInAttemptAuditEntry, type CheckInContext, type CheckInErrorCode, type CheckInInput, type CheckInResult$1 as CheckInResult, type ClaimTicketOptions, type Clock, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConditionVerifierPlugin, type ConsumeResult, type ConsumeRewardParams, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type EventPublisherAdapter, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, type LocalizedText as HeadlessLocalizedText, type IdGeneratorAdapter, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText$1 as LocalizedText, type Metadata, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type PublicRallyConfig, 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 UserId, type ValidationError, type ValidationInput, type ValidationOutcome, type VerificationContext, type VerificationCoordinates, type VerificationRequirement, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCheckIn, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isGeolocationSupported, isNfcSupported, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, migrateRallyConfig, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, stripSensitiveConfig, toLocalizedString, validateRallyConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/dist/index.d.ts

@@ -112,7 +112,7 @@ type Result<T, E> = {
 
 type SupportedLocale = "ja" | "en";
 type LocalizedString<TLocale extends string = SupportedLocale> = Record<TLocale, string>;
-type LocalizedText<TLocale extends string = string> = string | Partial<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";
@@ -138,9 +138,9 @@ interface ThemePreset<TLocale extends string = SupportedLocale> {
 declare const DEFAULT_SHEET_THEME: SheetTheme;
 interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
-    readonly name: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
-    readonly hint?: LocalizedText<TLocale>;
+    readonly name: LocalizedText$1<TLocale>;
+    readonly description?: LocalizedText$1<TLocale>;
+    readonly hint?: LocalizedText$1<TLocale>;
     readonly condition: StampCondition;
     readonly orderIndex?: number;
     readonly order?: number;
@@ -157,7 +157,7 @@ interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Recor
 }
 /** @deprecated Use SpotItem instead. */
 type StampDefinition<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> = SpotItem<TLocale, TMeta>;
-interface StampRecord {
+interface StampRecord$1 {
     readonly stampId: string;
     readonly acquiredAt: string;
     readonly metadata?: Readonly<Record<string, unknown>>;
@@ -180,8 +180,8 @@ type RewardUnlockCondition = {
 type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
 interface RewardItem<TLocale extends string = SupportedLocale> {
     readonly id: string;
-    readonly title: LocalizedText<TLocale>;
-    readonly description: LocalizedText<TLocale>;
+    readonly title: LocalizedText$1<TLocale>;
+    readonly description: LocalizedText$1<TLocale>;
     readonly type: RewardType;
     readonly redemptionMethod: RedemptionMethod;
     readonly requiredStampCount: number;
@@ -207,14 +207,14 @@ interface RewardState {
 }
 interface StampRallyState {
     readonly rallyId: string;
-    readonly records: ReadonlyArray<StampRecord>;
+    readonly records: ReadonlyArray<StampRecord$1>;
     readonly rewards?: ReadonlyArray<RewardState>;
     readonly updatedAt: string;
 }
 interface RallyConfig<TLocale extends string = SupportedLocale, TMeta extends Record<string, unknown> = Record<string, unknown>> {
     readonly id: string;
-    readonly title?: LocalizedText<TLocale>;
-    readonly description?: LocalizedText<TLocale>;
+    readonly title?: LocalizedText$1<TLocale>;
+    readonly description?: LocalizedText$1<TLocale>;
     readonly stamps: ReadonlyArray<StampDefinition<TLocale, TMeta>>;
     readonly rewards?: ReadonlyArray<RewardItem<TLocale>>;
     readonly isSequential?: boolean;
@@ -224,9 +224,9 @@ interface RallyConfig<TLocale extends string = SupportedLocale, TMeta extends Re
     readonly endDate?: string;
 }
 
-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 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>;
 
@@ -303,7 +303,7 @@ declare function issueClaimTicketNumber(reward: RewardItem, currentState: Reward
 
 type StampRallyEvent = {
     readonly type: "stampAcquired";
-    readonly record: StampRecord;
+    readonly record: StampRecord$1;
 } | {
     readonly type: "rallyCompleted";
     readonly rallyId: string;
@@ -382,7 +382,7 @@ declare function isStampRallyState(value: unknown): value is StampRallyState;
 interface RallySnapshot {
     readonly version: 1;
     readonly rallyId: string;
-    readonly stamps: ReadonlyArray<StampRecord>;
+    readonly stamps: ReadonlyArray<StampRecord$1>;
     readonly rewards: ReadonlyArray<RewardState>;
     readonly exportedAt: string;
 }
@@ -537,6 +537,187 @@ interface QrDetectorOptions {
 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;
+}
+
 type SnapshotSecretKey = string | Uint8Array;
 interface SnapshotTokenPayload {
     readonly [key: string]: unknown;
@@ -560,4 +741,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 { CURRENT_RALLY_CONFIG_VERSION, type CheckInContext, type CheckInErrorCode, type CheckInInput, type CheckInResult$1 as CheckInResult, type ClaimTicketOptions, type Clock, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConsumeResult, type ConsumeRewardParams, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type PublicRallyConfig, type PublicRewardItem, type QrDetectorOptions, type RallyConfig, type RallyConfigValidationResult, type RallySnapshot, type RedemptionMethod, type Result, type RewardConsumeError, type RewardItem, 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 StampCondition, type StampDefinition, type StampError, StampRallyClient, type StampRallyClientEvent, type StampRallyEvent, type StampRallyEventListener, type StampRallyListener, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, THEME_PRESETS, type ThemePreset, type ThemePresetId, type TokenVerificationContext, type ValidationError, type VerificationContext, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCheckIn, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isGeolocationSupported, isNfcSupported, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, migrateRallyConfig, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, stripSensitiveConfig, toLocalizedString, validateRallyConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };
+export { type AuditLoggerAdapter, type AuthContextAdapter, CURRENT_RALLY_CONFIG_VERSION, type CheckInAttemptAuditEntry, type CheckInContext, type CheckInErrorCode, type CheckInInput, type CheckInResult$1 as CheckInResult, type ClaimTicketOptions, type Clock, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConditionVerifierPlugin, type ConsumeResult, type ConsumeRewardParams, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type EventPublisherAdapter, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, type LocalizedText as HeadlessLocalizedText, type IdGeneratorAdapter, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText$1 as LocalizedText, type Metadata, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type PublicRallyConfig, 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 UserId, type ValidationError, type ValidationInput, type ValidationOutcome, type VerificationContext, type VerificationCoordinates, type VerificationRequirement, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCheckIn, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isGeolocationSupported, isNfcSupported, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, migrateRallyConfig, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, stripSensitiveConfig, toLocalizedString, validateRallyConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stamprally/core",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A dependency-free stamp rally domain engine and storage-agnostic client.",
   "license": "MIT",
   "repository": {