@stamprally/core 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -110,6 +110,116 @@ type Result<T, E> = {
     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 {
+    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 = {
+    readonly type: "qr";
+    readonly secretToken: string;
+    readonly qrEntryUrl?: string;
+} | {
+    readonly type: "passcode";
+    readonly code: string;
+    readonly caseSensitive?: boolean;
+} | {
+    readonly type: "gps";
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly radiusMeters: number;
+} | {
+    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 type: "passcode";
+} | {
+    readonly type: "gps";
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly radiusMeters: number;
+} | {
+    readonly type: "custom";
+    readonly validatorName: string;
+};
+interface UniversalSpotItem<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 imageUrl?: string;
+    readonly iconUrl?: string;
+    readonly redirectUrlAfterClaim?: string;
+    readonly externalReferences?: ReadonlyArray<ExternalReference$1>;
+    readonly metadata?: TMeta;
+    readonly conditions: ReadonlyArray<VerificationCondition>;
+    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 PublicReward<TLocale extends string = string> = Omit<AdminReward<TLocale>, "staffPasscode" | "digitalContentUrl">;
+type RewardUnlockCondition$1 = {
+    readonly type: "stamp_count";
+    readonly count: number;
+} | {
+    readonly type: "stamps";
+    readonly stampIds: ReadonlyArray<string>;
+} | {
+    readonly type: "all" | "any";
+    readonly conditions: ReadonlyArray<RewardUnlockCondition$1>;
+};
+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 theme?: SheetTheme;
+    readonly spots: ReadonlyArray<UniversalSpotItem<TLocale, TMeta>>;
+    readonly rewards: ReadonlyArray<AdminReward<TLocale>>;
+    readonly serverEndpoint?: string;
+    readonly metadata?: TMeta;
+}
+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 theme?: SheetTheme;
+    readonly spots: ReadonlyArray<Omit<UniversalSpotItem<TLocale, TMeta>, "conditions"> & {
+        readonly conditions: ReadonlyArray<PublicCheckInCondition>;
+    }>;
+    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>>;
@@ -136,6 +246,7 @@ interface ThemePreset<TLocale extends string = SupportedLocale> {
     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>;
@@ -152,6 +263,10 @@ interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Recor
     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>;
 }
@@ -211,6 +326,7 @@ interface StampRallyState {
     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>;
@@ -231,13 +347,28 @@ declare function toLocalizedString<TLocale extends string>(text: LocalizedText$1
 declare function migrateRallyConfig<TLocale extends string = SupportedLocale>(raw: unknown): RallyConfig<TLocale>;
 
 type PublicRewardItem<TLocale extends string = string> = Omit<RewardItem<TLocale>, "staffPasscode">;
-type PublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<RallyConfig<TLocale, TMeta>, "rewards"> & {
+type LegacyPublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<RallyConfig<TLocale, TMeta>, "rewards"> & {
     readonly rewards?: ReadonlyArray<PublicRewardItem<TLocale>>;
 };
-declare function stripSensitiveConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: RallyConfig<TLocale, TMeta>): PublicRallyConfig<TLocale, TMeta>;
+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";
+    readonly message: string;
+}
+interface UniversalValidationResult {
+    readonly valid: boolean;
+    readonly errors: ReadonlyArray<UniversalValidationError>;
+}
+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;
+
 declare const CURRENT_RALLY_CONFIG_VERSION = 2;
 interface ValidationError {
     readonly path: string;
@@ -449,7 +580,7 @@ declare class StampRallyClient {
         readonly events: true;
     }): () => void;
     subscribeEvents(listener: StampRallyEventListener): () => void;
-    updateConfig(newConfig: PublicRallyConfig): Promise<StampRallyState>;
+    updateConfig(newConfig: LegacyPublicRallyConfig): Promise<StampRallyState>;
     notifyRewardClaimed(rewardId: string, state?: StampRallyState | null): void;
     notifySyncCompleted(state?: StampRallyState | null): void;
     init(): Promise<StampRallyState>;
@@ -459,6 +590,137 @@ declare class StampRallyClient {
     restore(state: StampRallyState): Promise<StampRallyState>;
 }
 
+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 {
+    readonly now?: string;
+    readonly idempotencyKey?: string;
+    readonly sync?: boolean;
+}
+interface 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";
+    readonly spotId: string;
+    readonly message: string;
+} | {
+    readonly code: "CUSTOM_VALIDATION_FAILED";
+    readonly spotId: string;
+    readonly message: string;
+} | {
+    readonly code: "REWARD_NOT_FOUND";
+    readonly rewardId: string;
+    readonly message: string;
+} | {
+    readonly code: "SYNC_FAILED";
+    readonly message: string;
+} | {
+    readonly code: "REMOTE_ERROR";
+    readonly message: string;
+} | RewardConsumeError;
+interface CheckInSuccess {
+    readonly state: UserRallyState;
+    readonly record: StampRecord$1;
+}
+type UniversalCheckInResult = Result<CheckInSuccess, UniversalClientError>;
+type ClientCheckInResult = UniversalCheckInResult;
+interface ClaimSuccess {
+    readonly state: UserRallyState;
+    readonly reward: RewardState;
+}
+type UniversalClaimResult = Result<ClaimSuccess, UniversalClientError>;
+type ClaimResult = UniversalClaimResult;
+type ClientClaimResult = UniversalClaimResult;
+type UniversalClientEvent = {
+    readonly type: "checkIn";
+    readonly result: UniversalCheckInResult;
+} | {
+    readonly type: "rewardClaimed";
+    readonly result: UniversalClaimResult;
+} | {
+    readonly type: "sync";
+    readonly state: UserRallyState;
+} | {
+    readonly type: "error";
+    readonly error: UniversalClientError;
+};
+type UniversalClientListener = (state: UserRallyState) => void;
+type UniversalClientEventListener = (event: UniversalClientEvent) => void;
+interface UniversalClientSyncAdapter {
+    readonly checkIn?: (request: UniversalClientRequest) => Promise<UniversalCheckInResult>;
+    readonly claimReward?: (request: UniversalClaimRequest) => Promise<UniversalClaimResult>;
+    readonly sync?: (request: {
+        readonly rallyId: string;
+        readonly state: UserRallyState;
+    }) => Promise<UserRallyState>;
+}
+interface UniversalStampRallyClientOptions {
+    readonly storage?: StampStorage;
+    readonly syncAdapter?: UniversalClientSyncAdapter;
+    readonly customValidator?: CustomValidator;
+    readonly customValidators?: Readonly<Record<string, CustomValidator>>;
+    readonly clock?: () => string;
+}
+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 {
+    #private;
+    constructor(config: PublicRallyConfig, storageOrOptions?: UniversalClientOptionsOrStorage, clock?: () => string);
+    getConfig(): PublicRallyConfig;
+    getState(): UserRallyState | null;
+    subscribe(listener: UniversalClientListener): () => void;
+    subscribeEvents(listener: UniversalClientEventListener): () => 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>;
+}
+
 type SecureTokenSecretKey = string | Uint8Array;
 interface SecureTokenOptions {
     readonly encrypt?: boolean;
@@ -741,4 +1003,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 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 };
+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 };

package/dist/index.d.ts

@@ -110,6 +110,116 @@ type Result<T, E> = {
     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 {
+    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 = {
+    readonly type: "qr";
+    readonly secretToken: string;
+    readonly qrEntryUrl?: string;
+} | {
+    readonly type: "passcode";
+    readonly code: string;
+    readonly caseSensitive?: boolean;
+} | {
+    readonly type: "gps";
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly radiusMeters: number;
+} | {
+    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 type: "passcode";
+} | {
+    readonly type: "gps";
+    readonly latitude: number;
+    readonly longitude: number;
+    readonly radiusMeters: number;
+} | {
+    readonly type: "custom";
+    readonly validatorName: string;
+};
+interface UniversalSpotItem<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 imageUrl?: string;
+    readonly iconUrl?: string;
+    readonly redirectUrlAfterClaim?: string;
+    readonly externalReferences?: ReadonlyArray<ExternalReference$1>;
+    readonly metadata?: TMeta;
+    readonly conditions: ReadonlyArray<VerificationCondition>;
+    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 PublicReward<TLocale extends string = string> = Omit<AdminReward<TLocale>, "staffPasscode" | "digitalContentUrl">;
+type RewardUnlockCondition$1 = {
+    readonly type: "stamp_count";
+    readonly count: number;
+} | {
+    readonly type: "stamps";
+    readonly stampIds: ReadonlyArray<string>;
+} | {
+    readonly type: "all" | "any";
+    readonly conditions: ReadonlyArray<RewardUnlockCondition$1>;
+};
+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 theme?: SheetTheme;
+    readonly spots: ReadonlyArray<UniversalSpotItem<TLocale, TMeta>>;
+    readonly rewards: ReadonlyArray<AdminReward<TLocale>>;
+    readonly serverEndpoint?: string;
+    readonly metadata?: TMeta;
+}
+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 theme?: SheetTheme;
+    readonly spots: ReadonlyArray<Omit<UniversalSpotItem<TLocale, TMeta>, "conditions"> & {
+        readonly conditions: ReadonlyArray<PublicCheckInCondition>;
+    }>;
+    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>>;
@@ -136,6 +246,7 @@ interface ThemePreset<TLocale extends string = SupportedLocale> {
     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>;
@@ -152,6 +263,10 @@ interface SpotItem<TLocale extends string = SupportedLocale, TMeta extends Recor
     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>;
 }
@@ -211,6 +326,7 @@ interface StampRallyState {
     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>;
@@ -231,13 +347,28 @@ declare function toLocalizedString<TLocale extends string>(text: LocalizedText$1
 declare function migrateRallyConfig<TLocale extends string = SupportedLocale>(raw: unknown): RallyConfig<TLocale>;
 
 type PublicRewardItem<TLocale extends string = string> = Omit<RewardItem<TLocale>, "staffPasscode">;
-type PublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<RallyConfig<TLocale, TMeta>, "rewards"> & {
+type LegacyPublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> = Omit<RallyConfig<TLocale, TMeta>, "rewards"> & {
     readonly rewards?: ReadonlyArray<PublicRewardItem<TLocale>>;
 };
-declare function stripSensitiveConfig<TLocale extends string, TMeta extends Record<string, unknown>>(config: RallyConfig<TLocale, TMeta>): PublicRallyConfig<TLocale, TMeta>;
+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";
+    readonly message: string;
+}
+interface UniversalValidationResult {
+    readonly valid: boolean;
+    readonly errors: ReadonlyArray<UniversalValidationError>;
+}
+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;
+
 declare const CURRENT_RALLY_CONFIG_VERSION = 2;
 interface ValidationError {
     readonly path: string;
@@ -449,7 +580,7 @@ declare class StampRallyClient {
         readonly events: true;
     }): () => void;
     subscribeEvents(listener: StampRallyEventListener): () => void;
-    updateConfig(newConfig: PublicRallyConfig): Promise<StampRallyState>;
+    updateConfig(newConfig: LegacyPublicRallyConfig): Promise<StampRallyState>;
     notifyRewardClaimed(rewardId: string, state?: StampRallyState | null): void;
     notifySyncCompleted(state?: StampRallyState | null): void;
     init(): Promise<StampRallyState>;
@@ -459,6 +590,137 @@ declare class StampRallyClient {
     restore(state: StampRallyState): Promise<StampRallyState>;
 }
 
+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 {
+    readonly now?: string;
+    readonly idempotencyKey?: string;
+    readonly sync?: boolean;
+}
+interface 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";
+    readonly spotId: string;
+    readonly message: string;
+} | {
+    readonly code: "CUSTOM_VALIDATION_FAILED";
+    readonly spotId: string;
+    readonly message: string;
+} | {
+    readonly code: "REWARD_NOT_FOUND";
+    readonly rewardId: string;
+    readonly message: string;
+} | {
+    readonly code: "SYNC_FAILED";
+    readonly message: string;
+} | {
+    readonly code: "REMOTE_ERROR";
+    readonly message: string;
+} | RewardConsumeError;
+interface CheckInSuccess {
+    readonly state: UserRallyState;
+    readonly record: StampRecord$1;
+}
+type UniversalCheckInResult = Result<CheckInSuccess, UniversalClientError>;
+type ClientCheckInResult = UniversalCheckInResult;
+interface ClaimSuccess {
+    readonly state: UserRallyState;
+    readonly reward: RewardState;
+}
+type UniversalClaimResult = Result<ClaimSuccess, UniversalClientError>;
+type ClaimResult = UniversalClaimResult;
+type ClientClaimResult = UniversalClaimResult;
+type UniversalClientEvent = {
+    readonly type: "checkIn";
+    readonly result: UniversalCheckInResult;
+} | {
+    readonly type: "rewardClaimed";
+    readonly result: UniversalClaimResult;
+} | {
+    readonly type: "sync";
+    readonly state: UserRallyState;
+} | {
+    readonly type: "error";
+    readonly error: UniversalClientError;
+};
+type UniversalClientListener = (state: UserRallyState) => void;
+type UniversalClientEventListener = (event: UniversalClientEvent) => void;
+interface UniversalClientSyncAdapter {
+    readonly checkIn?: (request: UniversalClientRequest) => Promise<UniversalCheckInResult>;
+    readonly claimReward?: (request: UniversalClaimRequest) => Promise<UniversalClaimResult>;
+    readonly sync?: (request: {
+        readonly rallyId: string;
+        readonly state: UserRallyState;
+    }) => Promise<UserRallyState>;
+}
+interface UniversalStampRallyClientOptions {
+    readonly storage?: StampStorage;
+    readonly syncAdapter?: UniversalClientSyncAdapter;
+    readonly customValidator?: CustomValidator;
+    readonly customValidators?: Readonly<Record<string, CustomValidator>>;
+    readonly clock?: () => string;
+}
+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 {
+    #private;
+    constructor(config: PublicRallyConfig, storageOrOptions?: UniversalClientOptionsOrStorage, clock?: () => string);
+    getConfig(): PublicRallyConfig;
+    getState(): UserRallyState | null;
+    subscribe(listener: UniversalClientListener): () => void;
+    subscribeEvents(listener: UniversalClientEventListener): () => 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>;
+}
+
 type SecureTokenSecretKey = string | Uint8Array;
 interface SecureTokenOptions {
     readonly encrypt?: boolean;
@@ -741,4 +1003,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 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 };
+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 };