@stamprally/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,372 @@
+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;
+}
+interface CompositeConditionFailure {
+    readonly index: number;
+    readonly error: ConditionMismatch;
+}
+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;
+};
+type Result<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+
+type SupportedLocale = "ja" | "en";
+type LocalizedString = Record<SupportedLocale, string>;
+type LocalizedText = string | LocalizedString;
+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 {
+    readonly id: ThemePresetId;
+    readonly name: LocalizedString;
+    readonly description: LocalizedString;
+    readonly theme: SheetTheme;
+}
+declare const DEFAULT_SHEET_THEME: SheetTheme;
+interface SpotItem {
+    readonly id: string;
+    readonly name: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly hint?: LocalizedText;
+    readonly condition: StampCondition;
+    readonly order?: number;
+}
+/** @deprecated Use SpotItem instead. */
+type StampDefinition = SpotItem;
+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";
+type RewardStatus = "LOCKED" | "AVAILABLE" | "CONSUMED" | "EXPIRED";
+interface RewardItem {
+    readonly id: string;
+    readonly title: LocalizedText;
+    readonly description: LocalizedText;
+    readonly type: RewardType;
+    readonly redemptionMethod: RedemptionMethod;
+    readonly requiredStampCount: number;
+    readonly digitalContentUrl?: string;
+    readonly staffPasscode?: string;
+}
+interface RewardState {
+    readonly rewardId: string;
+    readonly status: RewardStatus;
+    readonly unlockedAt?: string;
+    readonly consumedAt?: string;
+    readonly consumedByStaffId?: string;
+}
+interface StampRallyState {
+    readonly rallyId: string;
+    readonly records: ReadonlyArray<StampRecord>;
+    readonly rewards?: ReadonlyArray<RewardState>;
+    readonly updatedAt: string;
+}
+interface RallyConfig {
+    readonly id: string;
+    readonly title?: LocalizedText;
+    readonly description?: LocalizedText;
+    readonly stamps: ReadonlyArray<StampDefinition>;
+    readonly rewards?: ReadonlyArray<RewardItem>;
+    readonly isSequential?: boolean;
+    readonly theme?: SheetTheme;
+}
+
+declare function resolveLocalizedText(text: LocalizedText | undefined, locale: SupportedLocale, fallbackLocale?: SupportedLocale): string;
+declare function toLocalizedString(text: LocalizedText | undefined): LocalizedString;
+
+declare const THEME_PRESETS: ReadonlyArray<ThemePreset>;
+
+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;
+
+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>;
+}
+declare function calculateProgress(state: StampRallyState, config: RallyConfig): StampRallyProgress;
+
+type StampRallyEvent = {
+    readonly type: "stampAcquired";
+    readonly record: StampRecord;
+} | {
+    readonly type: "rallyCompleted";
+    readonly rallyId: string;
+    readonly completedAt: string;
+};
+interface ProcessStampValue {
+    readonly nextState: StampRallyState;
+    readonly events: ReadonlyArray<StampRallyEvent>;
+}
+type RewardConsumeError = {
+    readonly code: "NOT_AVAILABLE";
+    readonly rewardId: string;
+} | {
+    readonly code: "ALREADY_CONSUMED";
+    readonly rewardId: string;
+} | {
+    readonly code: "INVALID_PASSCODE";
+    readonly rewardId: string;
+    readonly message: string;
+} | {
+    readonly code: "REWARD_NOT_FOUND";
+    readonly rewardId: string;
+};
+interface ConsumeRewardParams {
+    readonly reward: RewardItem;
+    readonly currentState: RewardState;
+    readonly inputPasscode?: string;
+    readonly staffId?: string;
+    readonly now: string;
+}
+type ConsumeResult = Result<RewardState, RewardConsumeError>;
+declare function reconcileRewardStates(rewards: ReadonlyArray<RewardItem>, 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 StampStorage {
+    load(rallyId: string): Promise<StampRallyState | null>;
+    save(state: StampRallyState): Promise<void>;
+    remove(rallyId: string): Promise<void>;
+}
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+type StorageOperation = "open" | "load" | "save" | "remove";
+type StorageAdapterErrorCode = "STORAGE_UNAVAILABLE" | "STORAGE_OPEN_FAILED" | "STORAGE_READ_FAILED" | "STORAGE_WRITE_FAILED" | "STORAGE_REMOVE_FAILED" | "STORAGE_INVALID_DATA";
+declare class StorageAdapterError extends Error {
+    readonly code: StorageAdapterErrorCode;
+    readonly operation: StorageOperation;
+    readonly rallyId: string | undefined;
+    constructor(code: StorageAdapterErrorCode, operation: StorageOperation, message: string, options?: {
+        readonly cause?: unknown;
+        readonly rallyId?: string;
+    });
+}
+declare function isRewardState(value: unknown): value is RewardState;
+declare function isStampRallyState(value: unknown): value is StampRallyState;
+interface RallySnapshot {
+    readonly version: 1;
+    readonly rallyId: string;
+    readonly stamps: ReadonlyArray<StampRecord>;
+    readonly rewards: ReadonlyArray<RewardState>;
+    readonly exportedAt: string;
+}
+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>;
+    save(state: StampRallyState): Promise<void>;
+    remove(rallyId: string): Promise<void>;
+}
+interface LocalStorageAdapterOptions {
+    readonly storage?: StorageLike | null;
+    readonly keyPrefix?: string;
+    readonly failureMode?: LocalStorageFailureMode;
+    readonly onWarning?: StorageWarningHandler;
+}
+type LocalStorageFailureMode = "fallback" | "throw";
+type StorageWarningHandler = (error: StorageAdapterError) => void;
+declare class LocalStorageAdapter implements StampStorage {
+    #private;
+    constructor(options?: LocalStorageAdapterOptions);
+    load(rallyId: string): Promise<StampRallyState | null>;
+    save(state: StampRallyState): Promise<void>;
+    remove(rallyId: string): Promise<void>;
+}
+interface IndexedDBAdapterOptions {
+    readonly indexedDB?: IDBFactory | null;
+    readonly databaseName?: string;
+}
+declare class IndexedDBAdapter implements StampStorage {
+    #private;
+    constructor(options?: IndexedDBAdapterOptions);
+    load(rallyId: string): Promise<StampRallyState | null>;
+    save(state: StampRallyState): Promise<void>;
+    remove(rallyId: string): Promise<void>;
+}
+
+type StampRallyListener = (state: StampRallyState) => void;
+type Clock = () => string;
+declare class StampRallyClient {
+    #private;
+    constructor(config: RallyConfig, storage: StampStorage, clock?: Clock);
+    getState(): StampRallyState | null;
+    getConfig(): RallyConfig;
+    subscribe(listener: StampRallyListener): () => 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>;
+}
+
+type DetectorKind = "geolocation" | "nfc" | "qr";
+type DetectorErrorCode = "UNSUPPORTED" | "PERMISSION_DENIED" | "POSITION_UNAVAILABLE" | "TIMEOUT" | "ABORTED" | "READ_FAILED" | "INVALID_DATA" | "NO_TOKEN";
+interface DetectorError {
+    readonly detector: DetectorKind;
+    readonly code: DetectorErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+type GeoVerificationContext = Extract<VerificationContext, {
+    readonly type: "geo";
+}>;
+type TokenVerificationContext = Extract<VerificationContext, {
+    readonly type: "token";
+}>;
+type DetectorResult<T extends VerificationContext> = Result<T, DetectorError>;
+interface PasscodeCondition {
+    readonly passcode: string;
+    readonly caseSensitive?: boolean;
+}
+type CheckInResult = {
+    readonly success: true;
+} | {
+    readonly success: false;
+    readonly reason: "INVALID_PASSCODE";
+    readonly message: string;
+};
+
+interface GeoDetectorOptions {
+    readonly enableHighAccuracy?: boolean;
+    readonly timeout?: number;
+}
+declare function isGeolocationSupported(): boolean;
+declare function getCurrentGeoContext(options?: GeoDetectorOptions): Promise<DetectorResult<GeoVerificationContext>>;
+
+interface NfcDetectorOptions {
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+}
+declare function isNfcSupported(): boolean;
+declare function readNfcContext(options?: NfcDetectorOptions): Promise<DetectorResult<TokenVerificationContext>>;
+
+declare function normalizePasscode(input: string, caseSensitive?: boolean): string;
+declare function verifyPasscode(inputCode: string, condition: PasscodeCondition): CheckInResult;
+
+interface QrDetectorOptions {
+    readonly timeout?: number;
+    readonly signal?: AbortSignal;
+    readonly facingMode?: "user" | "environment";
+}
+declare function isQrSupported(): boolean;
+declare function readQrContext(videoElement: HTMLVideoElement, options?: QrDetectorOptions): Promise<DetectorResult<TokenVerificationContext>>;
+
+export { type CheckInResult, 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 LocalizedString, type LocalizedText, type NfcDetectorOptions, type PasscodeCondition, type ProcessStampValue, type QrDetectorOptions, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type RewardConsumeError, type RewardItem, type RewardState, type RewardStatus, type RewardType, type SheetTheme, type SlotShape, type SpotItem, type StampCondition, type StampDefinition, type StampError, StampRallyClient, type StampRallyEvent, 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 VerificationContext, calculateDistanceMeters, calculateProgress, consumeReward, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, importProgressToken, isGeolocationSupported, isNfcSupported, isQrSupported, isRewardState, isStampRallyState, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, toLocalizedString, verifyPasscode };