@stamprally/core 0.9.0 → 0.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +10 -143
- package/dist/index.cjs +779 -103
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +114 -1
- package/dist/index.d.ts +114 -1
- package/dist/index.js +769 -104
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -123,6 +123,8 @@ interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record
|
|
|
123
123
|
readonly inventory?: Readonly<Record<string, number>>;
|
|
124
124
|
readonly serverMetadata?: Readonly<Record<string, unknown>>;
|
|
125
125
|
readonly metadata?: TMeta;
|
|
126
|
+
/** Explicit public metadata name. `metadata` remains supported for compatibility. */
|
|
127
|
+
readonly publicMetadata?: TMeta;
|
|
126
128
|
readonly serverEndpoint?: string;
|
|
127
129
|
}
|
|
128
130
|
interface PublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
|
|
@@ -165,6 +167,19 @@ interface StampRallyState {
|
|
|
165
167
|
}
|
|
166
168
|
type UserRallyState = StampRallyState;
|
|
167
169
|
|
|
170
|
+
/**
|
|
171
|
+
* Creates the client-facing configuration and removes private values at every
|
|
172
|
+
* nesting level. `customFilter` is an allow-list predicate: returning false
|
|
173
|
+
* removes that key.
|
|
174
|
+
*/
|
|
175
|
+
declare function sanitizeAdminConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>>(admin: AdminRallyConfig<TLocale, TMeta>, customFilter?: (key: string, value: unknown) => boolean): PublicRallyConfig<TLocale, TMeta>;
|
|
176
|
+
interface PublicConfigSafety {
|
|
177
|
+
readonly safe: boolean;
|
|
178
|
+
readonly leakedKeys: string[];
|
|
179
|
+
}
|
|
180
|
+
/** Finds private keys, including keys nested in metadata or custom values. */
|
|
181
|
+
declare function validatePublicConfigSafety(publicConfig: PublicRallyConfig): PublicConfigSafety;
|
|
182
|
+
|
|
168
183
|
type VerificationContext = {
|
|
169
184
|
readonly type: "qr";
|
|
170
185
|
readonly token: string;
|
|
@@ -245,12 +260,35 @@ type Validator = CustomValidator | ((context: CustomValidationContext) => Promis
|
|
|
245
260
|
readonly message?: string;
|
|
246
261
|
});
|
|
247
262
|
|
|
263
|
+
declare function updateLocalizedField<TLocale extends string>(current: LocalizedText<TLocale> | undefined, locale: TLocale, newValue: string): LocalizedText<TLocale>;
|
|
248
264
|
declare function resolveLocalizedText<TLocale extends string = SupportedLocale>(text: LocalizedText<TLocale> | undefined, locale: string, fallbackLocale?: string): string;
|
|
249
265
|
declare function toLocalizedString(text: LocalizedText | undefined): LocalizedString;
|
|
250
266
|
declare function toLocalizedString<TLocale extends string>(text: LocalizedText<TLocale> | undefined): LocalizedString<TLocale>;
|
|
251
267
|
|
|
252
268
|
declare const THEME_PRESETS: ReadonlyArray<ThemePreset>;
|
|
253
269
|
|
|
270
|
+
interface ValidationError {
|
|
271
|
+
readonly path: string;
|
|
272
|
+
readonly message: string;
|
|
273
|
+
readonly code: string;
|
|
274
|
+
}
|
|
275
|
+
type ParseResult<T> = {
|
|
276
|
+
readonly success: true;
|
|
277
|
+
readonly data: T;
|
|
278
|
+
} | {
|
|
279
|
+
readonly success: false;
|
|
280
|
+
readonly errors: ReadonlyArray<ValidationError>;
|
|
281
|
+
};
|
|
282
|
+
declare class ConfigValidationError extends Error {
|
|
283
|
+
readonly errors: ReadonlyArray<ValidationError>;
|
|
284
|
+
readonly name = "ConfigValidationError";
|
|
285
|
+
constructor(errors: ReadonlyArray<ValidationError>);
|
|
286
|
+
}
|
|
287
|
+
declare function safeParseAdminConfig(input: unknown): ParseResult<AdminRallyConfig>;
|
|
288
|
+
declare function parseAdminConfig(input: unknown): AdminRallyConfig;
|
|
289
|
+
declare function safeParsePublicConfig(input: unknown): ParseResult<PublicRallyConfig>;
|
|
290
|
+
declare function parsePublicConfig(input: unknown): PublicRallyConfig;
|
|
291
|
+
|
|
254
292
|
declare function calculateDistanceMeters(aLat: number, aLon: number, bLat: number, bLon: number): number;
|
|
255
293
|
declare function evaluateConditionDetailed(condition: CheckInCondition, context: VerificationContext): Result<ConditionMatch, ConditionMismatch>;
|
|
256
294
|
declare function evaluateCondition(condition: CheckInCondition, context: VerificationContext): boolean;
|
|
@@ -309,6 +347,77 @@ interface ProcessStampValue {
|
|
|
309
347
|
}
|
|
310
348
|
declare function processStamp(state: StampRallyState, config: AdminRallyConfig, spotId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
|
|
311
349
|
|
|
350
|
+
type OfflineOperation = {
|
|
351
|
+
readonly kind: "checkIn";
|
|
352
|
+
readonly request: CheckInRequest;
|
|
353
|
+
} | {
|
|
354
|
+
readonly kind: "claimReward";
|
|
355
|
+
readonly request: ClaimRequest;
|
|
356
|
+
};
|
|
357
|
+
type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
|
|
358
|
+
type SyncState = "idle" | "syncing" | "error";
|
|
359
|
+
type SyncConflictPolicy = "server_wins" | "merge";
|
|
360
|
+
interface OfflineConflictResult {
|
|
361
|
+
readonly conflict: true;
|
|
362
|
+
readonly localState: UserRallyState;
|
|
363
|
+
readonly serverState: UserRallyState;
|
|
364
|
+
}
|
|
365
|
+
interface OfflineQueueStorage {
|
|
366
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
367
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
368
|
+
}
|
|
369
|
+
interface OfflineQueueOptions {
|
|
370
|
+
readonly storage?: OfflineQueueStorage;
|
|
371
|
+
readonly storageLike?: {
|
|
372
|
+
getItem(key: string): string | null;
|
|
373
|
+
setItem(key: string, value: string): void;
|
|
374
|
+
removeItem?(key: string): void;
|
|
375
|
+
} | null;
|
|
376
|
+
readonly key?: string;
|
|
377
|
+
readonly databaseName?: string;
|
|
378
|
+
readonly conflictPolicy?: SyncConflictPolicy;
|
|
379
|
+
readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
|
|
380
|
+
}
|
|
381
|
+
interface OfflineConflict {
|
|
382
|
+
readonly operation: OfflineOperation;
|
|
383
|
+
readonly localState: UserRallyState;
|
|
384
|
+
readonly serverState: UserRallyState;
|
|
385
|
+
}
|
|
386
|
+
type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult>;
|
|
387
|
+
declare class MemoryQueueStorage implements OfflineQueueStorage {
|
|
388
|
+
#private;
|
|
389
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
390
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
391
|
+
}
|
|
392
|
+
interface IndexedDBOfflineQueueOptions {
|
|
393
|
+
readonly indexedDB?: IDBFactory | null;
|
|
394
|
+
readonly databaseName?: string;
|
|
395
|
+
}
|
|
396
|
+
declare class IndexedDBOfflineQueueStorage implements OfflineQueueStorage {
|
|
397
|
+
#private;
|
|
398
|
+
constructor(options?: IndexedDBOfflineQueueOptions);
|
|
399
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
400
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
401
|
+
}
|
|
402
|
+
/** Durable, sequential retry queue for operations created while disconnected. */
|
|
403
|
+
declare class OfflineQueue {
|
|
404
|
+
#private;
|
|
405
|
+
constructor(options?: OfflineQueueOptions);
|
|
406
|
+
get syncState(): SyncState;
|
|
407
|
+
get pendingCount(): number;
|
|
408
|
+
get error(): Error | null;
|
|
409
|
+
get operations(): ReadonlyArray<OfflineOperation>;
|
|
410
|
+
initialize(): Promise<void>;
|
|
411
|
+
setSender(sender: OfflineSender): void;
|
|
412
|
+
enqueue(operation: OfflineOperation): Promise<void>;
|
|
413
|
+
enqueueCheckIn(request: CheckInRequest): Promise<void>;
|
|
414
|
+
enqueueClaimReward(request: ClaimRequest): Promise<void>;
|
|
415
|
+
clear(): Promise<void>;
|
|
416
|
+
sync(sender?: OfflineSender | undefined): Promise<void>;
|
|
417
|
+
retrySync(sender?: OfflineSender | undefined): Promise<void>;
|
|
418
|
+
resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<void>;
|
|
419
|
+
}
|
|
420
|
+
|
|
312
421
|
interface StampStorage {
|
|
313
422
|
load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
|
|
314
423
|
save(state: StampRallyState): Promise<void>;
|
|
@@ -463,6 +572,7 @@ interface ClientOptions {
|
|
|
463
572
|
readonly customValidators?: Readonly<Record<string, Validator>>;
|
|
464
573
|
readonly clock?: () => string;
|
|
465
574
|
readonly userId?: string | null;
|
|
575
|
+
readonly offlineQueue?: OfflineQueue;
|
|
466
576
|
}
|
|
467
577
|
type StorageOrOptions = StampStorage | ClientOptions;
|
|
468
578
|
declare class StampRallyClient {
|
|
@@ -471,6 +581,8 @@ declare class StampRallyClient {
|
|
|
471
581
|
getConfig(): RallyConfig;
|
|
472
582
|
getState(): UserRallyState | null;
|
|
473
583
|
getUserId(): string | null;
|
|
584
|
+
get syncState(): SyncState;
|
|
585
|
+
get pendingCount(): number;
|
|
474
586
|
subscribe(listener: ClientListener): () => void;
|
|
475
587
|
subscribeEvents(listener: ClientEventListener): () => void;
|
|
476
588
|
init(): Promise<UserRallyState>;
|
|
@@ -481,6 +593,7 @@ declare class StampRallyClient {
|
|
|
481
593
|
checkIn(spotId: string, proofData: unknown, options?: CheckInOptions): Promise<CheckInResult>;
|
|
482
594
|
claimReward(rewardId: string, options?: ClaimOptions): Promise<ClaimResult>;
|
|
483
595
|
sync(adapter?: SyncAdapter | undefined): Promise<void>;
|
|
596
|
+
retrySync(): Promise<void>;
|
|
484
597
|
reset(): Promise<UserRallyState>;
|
|
485
598
|
restore(state: UserRallyState): Promise<UserRallyState>;
|
|
486
599
|
}
|
|
@@ -590,4 +703,4 @@ type SnapshotTokenVerification<T extends SnapshotTokenPayload = SnapshotTokenPay
|
|
|
590
703
|
declare function createSignedSnapshotToken<T extends SnapshotTokenPayload>(payload: T, secretKey: SnapshotSecretKey): Promise<string>;
|
|
591
704
|
declare function verifySnapshotToken<T extends SnapshotTokenPayload = SnapshotTokenPayload>(token: string, secretKey: SnapshotSecretKey, now?: number): Promise<SnapshotTokenVerification<T>>;
|
|
592
705
|
|
|
593
|
-
export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, storageKey, toLocalizedString, toPublicConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };
|
|
706
|
+
export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
|
package/dist/index.d.ts
CHANGED
|
@@ -123,6 +123,8 @@ interface AdminRallyConfig<TLocale extends string = string, TMeta extends Record
|
|
|
123
123
|
readonly inventory?: Readonly<Record<string, number>>;
|
|
124
124
|
readonly serverMetadata?: Readonly<Record<string, unknown>>;
|
|
125
125
|
readonly metadata?: TMeta;
|
|
126
|
+
/** Explicit public metadata name. `metadata` remains supported for compatibility. */
|
|
127
|
+
readonly publicMetadata?: TMeta;
|
|
126
128
|
readonly serverEndpoint?: string;
|
|
127
129
|
}
|
|
128
130
|
interface PublicRallyConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>> {
|
|
@@ -165,6 +167,19 @@ interface StampRallyState {
|
|
|
165
167
|
}
|
|
166
168
|
type UserRallyState = StampRallyState;
|
|
167
169
|
|
|
170
|
+
/**
|
|
171
|
+
* Creates the client-facing configuration and removes private values at every
|
|
172
|
+
* nesting level. `customFilter` is an allow-list predicate: returning false
|
|
173
|
+
* removes that key.
|
|
174
|
+
*/
|
|
175
|
+
declare function sanitizeAdminConfig<TLocale extends string = string, TMeta extends Record<string, unknown> = Record<string, unknown>>(admin: AdminRallyConfig<TLocale, TMeta>, customFilter?: (key: string, value: unknown) => boolean): PublicRallyConfig<TLocale, TMeta>;
|
|
176
|
+
interface PublicConfigSafety {
|
|
177
|
+
readonly safe: boolean;
|
|
178
|
+
readonly leakedKeys: string[];
|
|
179
|
+
}
|
|
180
|
+
/** Finds private keys, including keys nested in metadata or custom values. */
|
|
181
|
+
declare function validatePublicConfigSafety(publicConfig: PublicRallyConfig): PublicConfigSafety;
|
|
182
|
+
|
|
168
183
|
type VerificationContext = {
|
|
169
184
|
readonly type: "qr";
|
|
170
185
|
readonly token: string;
|
|
@@ -245,12 +260,35 @@ type Validator = CustomValidator | ((context: CustomValidationContext) => Promis
|
|
|
245
260
|
readonly message?: string;
|
|
246
261
|
});
|
|
247
262
|
|
|
263
|
+
declare function updateLocalizedField<TLocale extends string>(current: LocalizedText<TLocale> | undefined, locale: TLocale, newValue: string): LocalizedText<TLocale>;
|
|
248
264
|
declare function resolveLocalizedText<TLocale extends string = SupportedLocale>(text: LocalizedText<TLocale> | undefined, locale: string, fallbackLocale?: string): string;
|
|
249
265
|
declare function toLocalizedString(text: LocalizedText | undefined): LocalizedString;
|
|
250
266
|
declare function toLocalizedString<TLocale extends string>(text: LocalizedText<TLocale> | undefined): LocalizedString<TLocale>;
|
|
251
267
|
|
|
252
268
|
declare const THEME_PRESETS: ReadonlyArray<ThemePreset>;
|
|
253
269
|
|
|
270
|
+
interface ValidationError {
|
|
271
|
+
readonly path: string;
|
|
272
|
+
readonly message: string;
|
|
273
|
+
readonly code: string;
|
|
274
|
+
}
|
|
275
|
+
type ParseResult<T> = {
|
|
276
|
+
readonly success: true;
|
|
277
|
+
readonly data: T;
|
|
278
|
+
} | {
|
|
279
|
+
readonly success: false;
|
|
280
|
+
readonly errors: ReadonlyArray<ValidationError>;
|
|
281
|
+
};
|
|
282
|
+
declare class ConfigValidationError extends Error {
|
|
283
|
+
readonly errors: ReadonlyArray<ValidationError>;
|
|
284
|
+
readonly name = "ConfigValidationError";
|
|
285
|
+
constructor(errors: ReadonlyArray<ValidationError>);
|
|
286
|
+
}
|
|
287
|
+
declare function safeParseAdminConfig(input: unknown): ParseResult<AdminRallyConfig>;
|
|
288
|
+
declare function parseAdminConfig(input: unknown): AdminRallyConfig;
|
|
289
|
+
declare function safeParsePublicConfig(input: unknown): ParseResult<PublicRallyConfig>;
|
|
290
|
+
declare function parsePublicConfig(input: unknown): PublicRallyConfig;
|
|
291
|
+
|
|
254
292
|
declare function calculateDistanceMeters(aLat: number, aLon: number, bLat: number, bLon: number): number;
|
|
255
293
|
declare function evaluateConditionDetailed(condition: CheckInCondition, context: VerificationContext): Result<ConditionMatch, ConditionMismatch>;
|
|
256
294
|
declare function evaluateCondition(condition: CheckInCondition, context: VerificationContext): boolean;
|
|
@@ -309,6 +347,77 @@ interface ProcessStampValue {
|
|
|
309
347
|
}
|
|
310
348
|
declare function processStamp(state: StampRallyState, config: AdminRallyConfig, spotId: string, context: VerificationContext, now: string): Result<ProcessStampValue, StampError>;
|
|
311
349
|
|
|
350
|
+
type OfflineOperation = {
|
|
351
|
+
readonly kind: "checkIn";
|
|
352
|
+
readonly request: CheckInRequest;
|
|
353
|
+
} | {
|
|
354
|
+
readonly kind: "claimReward";
|
|
355
|
+
readonly request: ClaimRequest;
|
|
356
|
+
};
|
|
357
|
+
type OfflineResult = CheckInResult | ClaimResult | UserRallyState;
|
|
358
|
+
type SyncState = "idle" | "syncing" | "error";
|
|
359
|
+
type SyncConflictPolicy = "server_wins" | "merge";
|
|
360
|
+
interface OfflineConflictResult {
|
|
361
|
+
readonly conflict: true;
|
|
362
|
+
readonly localState: UserRallyState;
|
|
363
|
+
readonly serverState: UserRallyState;
|
|
364
|
+
}
|
|
365
|
+
interface OfflineQueueStorage {
|
|
366
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
367
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
368
|
+
}
|
|
369
|
+
interface OfflineQueueOptions {
|
|
370
|
+
readonly storage?: OfflineQueueStorage;
|
|
371
|
+
readonly storageLike?: {
|
|
372
|
+
getItem(key: string): string | null;
|
|
373
|
+
setItem(key: string, value: string): void;
|
|
374
|
+
removeItem?(key: string): void;
|
|
375
|
+
} | null;
|
|
376
|
+
readonly key?: string;
|
|
377
|
+
readonly databaseName?: string;
|
|
378
|
+
readonly conflictPolicy?: SyncConflictPolicy;
|
|
379
|
+
readonly onSyncConflict?: SyncConflictPolicy | ((context: OfflineConflict) => SyncConflictPolicy | Promise<SyncConflictPolicy>);
|
|
380
|
+
}
|
|
381
|
+
interface OfflineConflict {
|
|
382
|
+
readonly operation: OfflineOperation;
|
|
383
|
+
readonly localState: UserRallyState;
|
|
384
|
+
readonly serverState: UserRallyState;
|
|
385
|
+
}
|
|
386
|
+
type OfflineSender = (operation: OfflineOperation) => Promise<OfflineResult | OfflineConflictResult>;
|
|
387
|
+
declare class MemoryQueueStorage implements OfflineQueueStorage {
|
|
388
|
+
#private;
|
|
389
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
390
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
391
|
+
}
|
|
392
|
+
interface IndexedDBOfflineQueueOptions {
|
|
393
|
+
readonly indexedDB?: IDBFactory | null;
|
|
394
|
+
readonly databaseName?: string;
|
|
395
|
+
}
|
|
396
|
+
declare class IndexedDBOfflineQueueStorage implements OfflineQueueStorage {
|
|
397
|
+
#private;
|
|
398
|
+
constructor(options?: IndexedDBOfflineQueueOptions);
|
|
399
|
+
load(key: string): Promise<ReadonlyArray<OfflineOperation>>;
|
|
400
|
+
save(key: string, operations: ReadonlyArray<OfflineOperation>): Promise<void>;
|
|
401
|
+
}
|
|
402
|
+
/** Durable, sequential retry queue for operations created while disconnected. */
|
|
403
|
+
declare class OfflineQueue {
|
|
404
|
+
#private;
|
|
405
|
+
constructor(options?: OfflineQueueOptions);
|
|
406
|
+
get syncState(): SyncState;
|
|
407
|
+
get pendingCount(): number;
|
|
408
|
+
get error(): Error | null;
|
|
409
|
+
get operations(): ReadonlyArray<OfflineOperation>;
|
|
410
|
+
initialize(): Promise<void>;
|
|
411
|
+
setSender(sender: OfflineSender): void;
|
|
412
|
+
enqueue(operation: OfflineOperation): Promise<void>;
|
|
413
|
+
enqueueCheckIn(request: CheckInRequest): Promise<void>;
|
|
414
|
+
enqueueClaimReward(request: ClaimRequest): Promise<void>;
|
|
415
|
+
clear(): Promise<void>;
|
|
416
|
+
sync(sender?: OfflineSender | undefined): Promise<void>;
|
|
417
|
+
retrySync(sender?: OfflineSender | undefined): Promise<void>;
|
|
418
|
+
resolveConflict(operation: OfflineOperation, localState: UserRallyState, serverState: UserRallyState): Promise<void>;
|
|
419
|
+
}
|
|
420
|
+
|
|
312
421
|
interface StampStorage {
|
|
313
422
|
load(rallyId: string, userId: string | null): Promise<StampRallyState | null>;
|
|
314
423
|
save(state: StampRallyState): Promise<void>;
|
|
@@ -463,6 +572,7 @@ interface ClientOptions {
|
|
|
463
572
|
readonly customValidators?: Readonly<Record<string, Validator>>;
|
|
464
573
|
readonly clock?: () => string;
|
|
465
574
|
readonly userId?: string | null;
|
|
575
|
+
readonly offlineQueue?: OfflineQueue;
|
|
466
576
|
}
|
|
467
577
|
type StorageOrOptions = StampStorage | ClientOptions;
|
|
468
578
|
declare class StampRallyClient {
|
|
@@ -471,6 +581,8 @@ declare class StampRallyClient {
|
|
|
471
581
|
getConfig(): RallyConfig;
|
|
472
582
|
getState(): UserRallyState | null;
|
|
473
583
|
getUserId(): string | null;
|
|
584
|
+
get syncState(): SyncState;
|
|
585
|
+
get pendingCount(): number;
|
|
474
586
|
subscribe(listener: ClientListener): () => void;
|
|
475
587
|
subscribeEvents(listener: ClientEventListener): () => void;
|
|
476
588
|
init(): Promise<UserRallyState>;
|
|
@@ -481,6 +593,7 @@ declare class StampRallyClient {
|
|
|
481
593
|
checkIn(spotId: string, proofData: unknown, options?: CheckInOptions): Promise<CheckInResult>;
|
|
482
594
|
claimReward(rewardId: string, options?: ClaimOptions): Promise<ClaimResult>;
|
|
483
595
|
sync(adapter?: SyncAdapter | undefined): Promise<void>;
|
|
596
|
+
retrySync(): Promise<void>;
|
|
484
597
|
reset(): Promise<UserRallyState>;
|
|
485
598
|
restore(state: UserRallyState): Promise<UserRallyState>;
|
|
486
599
|
}
|
|
@@ -590,4 +703,4 @@ type SnapshotTokenVerification<T extends SnapshotTokenPayload = SnapshotTokenPay
|
|
|
590
703
|
declare function createSignedSnapshotToken<T extends SnapshotTokenPayload>(payload: T, secretKey: SnapshotSecretKey): Promise<string>;
|
|
591
704
|
declare function verifySnapshotToken<T extends SnapshotTokenPayload = SnapshotTokenPayload>(token: string, secretKey: SnapshotSecretKey, now?: number): Promise<SnapshotTokenVerification<T>>;
|
|
592
705
|
|
|
593
|
-
export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, storageKey, toLocalizedString, toPublicConfig, verifyPasscode, verifySecureToken, verifySnapshotToken };
|
|
706
|
+
export { type AdminRallyConfig, type CheckInCondition, type CheckInOptions, type CheckInRequest, type CheckInResult, type CheckInSuccess, type ClaimOptions, type ClaimRequest, type ClaimResult, type ClaimSuccess, type ClaimTicketOptions, type ClientError, type ClientEvent, type ClientEventListener, type ClientListener, type ClientOptions, type CompositeConditionFailure, type ConditionMatch, type ConditionMismatch, ConfigValidationError, type ConsumeResult, type ConsumeRewardParams, type CustomValidationContext, type CustomValidator, DEFAULT_SHEET_THEME, type DetectorError, type DetectorErrorCode, type DetectorKind, type DetectorResult, type ExternalReference, type FontFamily, type GeoDetectorOptions, type GeoVerificationContext, MemoryQueueStorage as InMemoryOfflineQueueStorage, InMemoryStorage, IndexedDBAdapter, type IndexedDBAdapterOptions, type IndexedDBOfflineQueueOptions, IndexedDBOfflineQueueStorage, LocalStorageAdapter, type LocalStorageAdapterOptions, type LocalStorageFailureMode, type LocaleDictionary, type LocalizedString, type LocalizedText, type NfcDetectorOptions, type NfcVerificationContext, type OfflineConflict, type OfflineConflictResult, type OfflineOperation, OfflineQueue, type OfflineQueueOptions, type OfflineQueueStorage, type OfflineResult, type OfflineSender, type ParseResult, type PasscodeCondition$1 as PasscodeCondition, type ProcessStampValue, type PublicCheckInCondition, type PublicConfigSafety, type PublicRallyConfig, type PublicReward, type PublicSpotItem, type QrDetectorOptions, type QrVerificationContext, type RallyConfig, type RallySnapshot, type RedemptionMethod, type Result, type Reward, type RewardConsumeError, type RewardState, type RewardStatus, type RewardType, type RewardUnlockCondition, type SecureTokenError, type SecureTokenErrorCode, type SecureTokenOptions, type SecureTokenPayload, type SecureTokenSecretKey, type SecureTokenVerification, type SheetTheme, type SlotShape, type SnapshotSecretKey, type SnapshotTokenError, type SnapshotTokenErrorCode, type SnapshotTokenPayload, type SnapshotTokenVerification, type SpotItem, type StampError, StampRallyClient, type StampRallyProgress, type StampRallyState, type StampRecord, type StampStorage, StorageAdapterError, type StorageAdapterErrorCode, type StorageLike, type StorageOperation, type StorageWarningHandler, type SupportedLocale, type SyncAdapter, type SyncConflictPolicy, type SyncState, THEME_PRESETS, type ThemePreset, type ThemePresetId, type UserRallyState, type ValidationError, type Validator, type VerificationContext, assertPublicConfig, calculateDistanceMeters, calculateProgress, consumeReward, createClaimTicketNumber, createSecureToken, createSignedSnapshotToken, createUniqueClaimTicketNumber, evaluateCondition, evaluateConditionDetailed, exportProgressToken, getCurrentGeoContext, getOrderedSpots, importProgressToken, isGeolocationSupported, isNfcSupported, isPublicConfig, isQrSupported, isRewardState, isStampRallyState, issueClaimTicketNumber, normalizePasscode, parseAdminConfig, parsePublicConfig, processStamp, readNfcContext, readQrContext, reconcileRewardStates, resolveLocalizedText, safeParseAdminConfig, safeParsePublicConfig, sanitizeAdminConfig, storageKey, toLocalizedString, toPublicConfig, updateLocalizedField, validatePublicConfigSafety, verifyPasscode, verifySecureToken, verifySnapshotToken };
|