react-achievements 3.7.0 → 3.9.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 +69 -336
- package/dist/index.cjs +1458 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +96 -489
- package/dist/index.esm.js +1354 -0
- package/dist/index.esm.js.map +1 -0
- package/dist/types/core/types.d.ts +15 -0
- package/dist/types/core/ui/interfaces.d.ts +2 -6
- package/dist/types/hooks/useAchievementEngine.d.ts +36 -0
- package/dist/types/hooks/useSimpleAchievements.d.ts +3 -3
- package/dist/types/index.d.ts +21 -13
- package/dist/types/providers/AchievementProvider.d.ts +10 -7
- package/package.json +13 -3
- package/dist/index.js +0 -2792
- package/dist/index.js.map +0 -1
package/dist/index.d.ts
CHANGED
|
@@ -1,20 +1,19 @@
|
|
|
1
1
|
import React$1 from 'react';
|
|
2
|
+
import * as achievements_engine from 'achievements-engine';
|
|
3
|
+
import { ImportOptions, ImportResult, AchievementWithStatus as AchievementWithStatus$1, AchievementEngine, AchievementConfigurationType as AchievementConfigurationType$1, AchievementStorage as AchievementStorage$1, AsyncAchievementStorage as AsyncAchievementStorage$1, StorageType, RestApiStorageConfig, EventMapping, AchievementError } from 'achievements-engine';
|
|
4
|
+
export { AchievementBuilder, AchievementEngine, AchievementEngineApi, AchievementError, AchievementUnlockedEvent, AsyncStorageAdapter, AwardDetails, ConfigurationError, EngineConfig, EngineEvent, ErrorEvent, EventMapping, ExportedData, ImportOptions, ImportResult, ImportValidationError, IndexedDBStorage, LocalStorage, MemoryStorage, MetricUpdatedEvent, MetricUpdater, OfflineQueueStorage, RestApiStorage, RestApiStorageConfig, StateChangedEvent, StorageError, StorageQuotaError, StorageType, SyncError, UnsubscribeFn, createConfigHash, exportAchievementData, importAchievementData, isAchievementError, isRecoverableError, isSimpleConfig, normalizeAchievements } from 'achievements-engine';
|
|
2
5
|
|
|
3
6
|
/**
|
|
4
7
|
* Notification component interface
|
|
5
8
|
* Displays achievement unlock notifications
|
|
6
9
|
*/
|
|
7
10
|
interface NotificationProps {
|
|
8
|
-
achievement:
|
|
9
|
-
id: string;
|
|
10
|
-
title: string;
|
|
11
|
-
description: string;
|
|
12
|
-
icon: string;
|
|
13
|
-
};
|
|
11
|
+
achievement: AchievementWithStatus;
|
|
14
12
|
onClose?: () => void;
|
|
15
13
|
duration?: number;
|
|
16
14
|
position?: NotificationPosition;
|
|
17
15
|
theme?: string;
|
|
16
|
+
icons?: Record<string, string>;
|
|
18
17
|
}
|
|
19
18
|
type NotificationComponent = React$1.FC<NotificationProps>;
|
|
20
19
|
/**
|
|
@@ -188,6 +187,21 @@ interface AsyncAchievementStorage {
|
|
|
188
187
|
}
|
|
189
188
|
type AnyAchievementStorage = AchievementStorage | AsyncAchievementStorage;
|
|
190
189
|
declare function isAsyncStorage(storage: AnyAchievementStorage): storage is AsyncAchievementStorage;
|
|
190
|
+
/**
|
|
191
|
+
* @deprecated This type is outdated and will be removed in v4.0.0.
|
|
192
|
+
* Use AchievementContextType from 'react-achievements' instead.
|
|
193
|
+
*
|
|
194
|
+
* This legacy interface does not include the 'engine' property.
|
|
195
|
+
*
|
|
196
|
+
* @example
|
|
197
|
+
* ```typescript
|
|
198
|
+
* // Old (deprecated)
|
|
199
|
+
* import { AchievementContextValue } from 'react-achievements';
|
|
200
|
+
*
|
|
201
|
+
* // New (recommended)
|
|
202
|
+
* import { AchievementContextType } from 'react-achievements';
|
|
203
|
+
* ```
|
|
204
|
+
*/
|
|
191
205
|
interface AchievementContextValue {
|
|
192
206
|
updateMetrics: (metrics: AchievementMetrics | ((prev: AchievementMetrics) => AchievementMetrics)) => void;
|
|
193
207
|
unlockedAchievements: string[];
|
|
@@ -222,232 +236,49 @@ interface AchievementProviderProps$1 {
|
|
|
222
236
|
storage?: AchievementStorage;
|
|
223
237
|
onAchievementUnlocked?: (achievement: AchievementDetails) => void;
|
|
224
238
|
}
|
|
225
|
-
declare enum StorageType {
|
|
226
|
-
Local = "local",// Synchronous localStorage
|
|
227
|
-
Memory = "memory",// Synchronous in-memory storage
|
|
228
|
-
IndexedDB = "indexeddb",// Asynchronous IndexedDB storage
|
|
229
|
-
RestAPI = "restapi"
|
|
230
|
-
}
|
|
231
|
-
|
|
232
|
-
declare class LocalStorage implements AchievementStorage {
|
|
233
|
-
private storageKey;
|
|
234
|
-
constructor(storageKey: string);
|
|
235
|
-
private serializeValue;
|
|
236
|
-
private deserializeValue;
|
|
237
|
-
private serializeMetrics;
|
|
238
|
-
private deserializeMetrics;
|
|
239
|
-
private getStorageData;
|
|
240
|
-
private setStorageData;
|
|
241
|
-
getMetrics(): AchievementMetrics;
|
|
242
|
-
setMetrics(metrics: AchievementMetrics): void;
|
|
243
|
-
getUnlockedAchievements(): string[];
|
|
244
|
-
setUnlockedAchievements(achievements: string[]): void;
|
|
245
|
-
clear(): void;
|
|
246
|
-
}
|
|
247
|
-
|
|
248
|
-
declare class MemoryStorage implements AchievementStorage {
|
|
249
|
-
private metrics;
|
|
250
|
-
private unlockedAchievements;
|
|
251
|
-
constructor();
|
|
252
|
-
getMetrics(): AchievementMetrics;
|
|
253
|
-
setMetrics(metrics: AchievementMetrics): void;
|
|
254
|
-
getUnlockedAchievements(): string[];
|
|
255
|
-
setUnlockedAchievements(achievements: string[]): void;
|
|
256
|
-
clear(): void;
|
|
257
|
-
}
|
|
258
|
-
|
|
259
|
-
/**
|
|
260
|
-
* Base error class for all achievement-related errors
|
|
261
|
-
*/
|
|
262
|
-
declare class AchievementError extends Error {
|
|
263
|
-
code: string;
|
|
264
|
-
recoverable: boolean;
|
|
265
|
-
remedy?: string | undefined;
|
|
266
|
-
constructor(message: string, code: string, recoverable: boolean, remedy?: string | undefined);
|
|
267
|
-
}
|
|
268
|
-
/**
|
|
269
|
-
* Error thrown when browser storage quota is exceeded
|
|
270
|
-
*/
|
|
271
|
-
declare class StorageQuotaError extends AchievementError {
|
|
272
|
-
bytesNeeded: number;
|
|
273
|
-
constructor(bytesNeeded: number);
|
|
274
|
-
}
|
|
275
|
-
/**
|
|
276
|
-
* Error thrown when imported data fails validation
|
|
277
|
-
*/
|
|
278
|
-
declare class ImportValidationError extends AchievementError {
|
|
279
|
-
validationErrors: string[];
|
|
280
|
-
constructor(validationErrors: string[]);
|
|
281
|
-
}
|
|
282
|
-
/**
|
|
283
|
-
* Error thrown when storage operations fail
|
|
284
|
-
*/
|
|
285
|
-
declare class StorageError extends AchievementError {
|
|
286
|
-
originalError?: Error | undefined;
|
|
287
|
-
constructor(message: string, originalError?: Error | undefined);
|
|
288
|
-
}
|
|
289
|
-
/**
|
|
290
|
-
* Error thrown when configuration is invalid
|
|
291
|
-
*/
|
|
292
|
-
declare class ConfigurationError extends AchievementError {
|
|
293
|
-
constructor(message: string);
|
|
294
|
-
}
|
|
295
|
-
/**
|
|
296
|
-
* Error thrown when network sync operations fail
|
|
297
|
-
*/
|
|
298
|
-
declare class SyncError extends AchievementError {
|
|
299
|
-
readonly statusCode?: number;
|
|
300
|
-
readonly timeout?: number;
|
|
301
|
-
constructor(message: string, details?: {
|
|
302
|
-
statusCode?: number;
|
|
303
|
-
timeout?: number;
|
|
304
|
-
});
|
|
305
|
-
}
|
|
306
|
-
/**
|
|
307
|
-
* Type guard to check if an error is an AchievementError
|
|
308
|
-
*/
|
|
309
|
-
declare function isAchievementError(error: unknown): error is AchievementError;
|
|
310
|
-
/**
|
|
311
|
-
* Type guard to check if an error is recoverable
|
|
312
|
-
*/
|
|
313
|
-
declare function isRecoverableError(error: unknown): boolean;
|
|
314
239
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
*/
|
|
332
|
-
private ensureCacheLoaded;
|
|
333
|
-
/**
|
|
334
|
-
* SYNC READ: Returns cached metrics immediately
|
|
335
|
-
* Cache is loaded eagerly during construction
|
|
336
|
-
*/
|
|
337
|
-
getMetrics(): AchievementMetrics;
|
|
338
|
-
/**
|
|
339
|
-
* SYNC WRITE: Updates cache immediately, writes to storage in background
|
|
340
|
-
* Uses optimistic updates - assumes write will succeed
|
|
341
|
-
*/
|
|
342
|
-
setMetrics(metrics: AchievementMetrics): void;
|
|
343
|
-
/**
|
|
344
|
-
* SYNC READ: Returns cached unlocked achievements immediately
|
|
345
|
-
*/
|
|
346
|
-
getUnlockedAchievements(): string[];
|
|
347
|
-
/**
|
|
348
|
-
* SYNC WRITE: Updates cache immediately, writes to storage in background
|
|
349
|
-
*/
|
|
350
|
-
setUnlockedAchievements(achievements: string[]): void;
|
|
351
|
-
/**
|
|
352
|
-
* SYNC CLEAR: Clears cache immediately, clears storage in background
|
|
353
|
-
*/
|
|
354
|
-
clear(): void;
|
|
355
|
-
/**
|
|
356
|
-
* Wait for all pending writes to complete (useful for testing/cleanup)
|
|
357
|
-
* NOT part of AchievementStorage interface - utility method
|
|
358
|
-
*/
|
|
359
|
-
flush(): Promise<void>;
|
|
360
|
-
}
|
|
361
|
-
|
|
362
|
-
declare class IndexedDBStorage implements AsyncAchievementStorage {
|
|
363
|
-
private dbName;
|
|
364
|
-
private storeName;
|
|
365
|
-
private db;
|
|
366
|
-
private initPromise;
|
|
367
|
-
constructor(dbName?: string);
|
|
368
|
-
/**
|
|
369
|
-
* Initialize IndexedDB database and object store
|
|
370
|
-
*/
|
|
371
|
-
private initDB;
|
|
372
|
-
/**
|
|
373
|
-
* Generic get operation from IndexedDB
|
|
374
|
-
*/
|
|
375
|
-
private get;
|
|
376
|
-
/**
|
|
377
|
-
* Generic set operation to IndexedDB
|
|
378
|
-
*/
|
|
379
|
-
private set;
|
|
380
|
-
/**
|
|
381
|
-
* Delete operation from IndexedDB
|
|
382
|
-
*/
|
|
383
|
-
private delete;
|
|
384
|
-
getMetrics(): Promise<AchievementMetrics>;
|
|
385
|
-
setMetrics(metrics: AchievementMetrics): Promise<void>;
|
|
386
|
-
getUnlockedAchievements(): Promise<string[]>;
|
|
387
|
-
setUnlockedAchievements(achievements: string[]): Promise<void>;
|
|
388
|
-
clear(): Promise<void>;
|
|
389
|
-
}
|
|
390
|
-
|
|
391
|
-
interface RestApiStorageConfig {
|
|
392
|
-
baseUrl: string;
|
|
393
|
-
userId: string;
|
|
394
|
-
headers?: Record<string, string>;
|
|
395
|
-
timeout?: number;
|
|
396
|
-
}
|
|
397
|
-
declare class RestApiStorage implements AsyncAchievementStorage {
|
|
398
|
-
private config;
|
|
399
|
-
constructor(config: RestApiStorageConfig);
|
|
400
|
-
/**
|
|
401
|
-
* Generic fetch wrapper with timeout and error handling
|
|
402
|
-
*/
|
|
403
|
-
private fetchWithTimeout;
|
|
404
|
-
getMetrics(): Promise<AchievementMetrics>;
|
|
405
|
-
setMetrics(metrics: AchievementMetrics): Promise<void>;
|
|
406
|
-
getUnlockedAchievements(): Promise<string[]>;
|
|
407
|
-
setUnlockedAchievements(achievements: string[]): Promise<void>;
|
|
408
|
-
clear(): Promise<void>;
|
|
409
|
-
}
|
|
410
|
-
|
|
411
|
-
interface QueuedOperation {
|
|
412
|
-
id: string;
|
|
413
|
-
type: 'setMetrics' | 'setUnlockedAchievements' | 'clear';
|
|
414
|
-
data?: any;
|
|
415
|
-
timestamp: number;
|
|
240
|
+
interface AchievementContextType {
|
|
241
|
+
update: (metrics: Record<string, any>) => void;
|
|
242
|
+
achievements: {
|
|
243
|
+
unlocked: string[];
|
|
244
|
+
all: Record<string, any>;
|
|
245
|
+
};
|
|
246
|
+
reset: () => void;
|
|
247
|
+
getState: () => {
|
|
248
|
+
metrics: Record<string, any>;
|
|
249
|
+
unlocked: string[];
|
|
250
|
+
};
|
|
251
|
+
exportData: () => string;
|
|
252
|
+
importData: (jsonString: string, options?: ImportOptions) => ImportResult;
|
|
253
|
+
getAllAchievements: () => AchievementWithStatus$1[];
|
|
254
|
+
engine: AchievementEngine;
|
|
255
|
+
_isLegacyPattern: boolean;
|
|
416
256
|
}
|
|
417
|
-
declare
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
private handleOffline;
|
|
428
|
-
private processQueue;
|
|
429
|
-
private queueOperation;
|
|
430
|
-
getMetrics(): Promise<AchievementMetrics>;
|
|
431
|
-
setMetrics(metrics: AchievementMetrics): Promise<void>;
|
|
432
|
-
getUnlockedAchievements(): Promise<string[]>;
|
|
433
|
-
setUnlockedAchievements(achievements: string[]): Promise<void>;
|
|
434
|
-
clear(): Promise<void>;
|
|
435
|
-
/**
|
|
436
|
-
* Manually trigger queue processing (useful for testing)
|
|
437
|
-
*/
|
|
438
|
-
sync(): Promise<void>;
|
|
257
|
+
declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
|
|
258
|
+
interface AchievementProviderProps {
|
|
259
|
+
achievements?: AchievementConfigurationType$1;
|
|
260
|
+
storage?: AchievementStorage$1 | AsyncAchievementStorage$1 | StorageType;
|
|
261
|
+
restApiConfig?: RestApiStorageConfig;
|
|
262
|
+
eventMapping?: EventMapping;
|
|
263
|
+
engine?: AchievementEngine;
|
|
264
|
+
children: React$1.ReactNode;
|
|
265
|
+
icons?: Record<string, string>;
|
|
266
|
+
onError?: (error: AchievementError) => void;
|
|
439
267
|
/**
|
|
440
|
-
*
|
|
268
|
+
* UI configuration for notifications, modal, and confetti
|
|
269
|
+
* NEW in v3.6.0
|
|
441
270
|
*/
|
|
442
|
-
|
|
443
|
-
pending: number;
|
|
444
|
-
operations: QueuedOperation[];
|
|
445
|
-
};
|
|
271
|
+
ui?: UIConfig;
|
|
446
272
|
/**
|
|
447
|
-
*
|
|
273
|
+
* Force use of built-in UI components (opt-in for v3.x)
|
|
274
|
+
* Set to true to skip legacy library detection and use built-in UI
|
|
275
|
+
* In v4.0.0, this will become the default behavior
|
|
276
|
+
* NEW in v3.6.0
|
|
277
|
+
* @default false
|
|
448
278
|
*/
|
|
449
|
-
|
|
279
|
+
useBuiltInUI?: boolean;
|
|
450
280
|
}
|
|
281
|
+
declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
|
|
451
282
|
|
|
452
283
|
interface BadgesButtonProps {
|
|
453
284
|
onClick: () => void;
|
|
@@ -542,95 +373,6 @@ interface ConfettiWrapperProps {
|
|
|
542
373
|
}
|
|
543
374
|
declare const ConfettiWrapper: React$1.FC<ConfettiWrapperProps>;
|
|
544
375
|
|
|
545
|
-
/**
|
|
546
|
-
* Options for importing achievement data
|
|
547
|
-
*/
|
|
548
|
-
interface ImportOptions {
|
|
549
|
-
/** Strategy for merging imported data with existing data */
|
|
550
|
-
mergeStrategy?: 'replace' | 'merge' | 'preserve';
|
|
551
|
-
/** Whether to validate the imported data */
|
|
552
|
-
validate?: boolean;
|
|
553
|
-
/** Optional config hash to validate against */
|
|
554
|
-
expectedConfigHash?: string;
|
|
555
|
-
}
|
|
556
|
-
/**
|
|
557
|
-
* Result of an import operation
|
|
558
|
-
*/
|
|
559
|
-
interface ImportResult {
|
|
560
|
-
success: boolean;
|
|
561
|
-
imported: {
|
|
562
|
-
metrics: number;
|
|
563
|
-
achievements: number;
|
|
564
|
-
};
|
|
565
|
-
errors?: string[];
|
|
566
|
-
warnings?: string[];
|
|
567
|
-
}
|
|
568
|
-
/**
|
|
569
|
-
* Imports achievement data from a JSON string
|
|
570
|
-
*
|
|
571
|
-
* @param jsonString - JSON string containing exported achievement data
|
|
572
|
-
* @param currentMetrics - Current metrics state
|
|
573
|
-
* @param currentUnlocked - Current unlocked achievements
|
|
574
|
-
* @param options - Import options
|
|
575
|
-
* @returns Import result with success status and any errors
|
|
576
|
-
*
|
|
577
|
-
* @example
|
|
578
|
-
* ```typescript
|
|
579
|
-
* const result = importAchievementData(
|
|
580
|
-
* jsonString,
|
|
581
|
-
* currentMetrics,
|
|
582
|
-
* currentUnlocked,
|
|
583
|
-
* { mergeStrategy: 'merge', validate: true }
|
|
584
|
-
* );
|
|
585
|
-
*
|
|
586
|
-
* if (result.success) {
|
|
587
|
-
* console.log(`Imported ${result.imported.achievements} achievements`);
|
|
588
|
-
* } else {
|
|
589
|
-
* console.error('Import failed:', result.errors);
|
|
590
|
-
* }
|
|
591
|
-
* ```
|
|
592
|
-
*/
|
|
593
|
-
declare function importAchievementData(jsonString: string, currentMetrics: AchievementMetrics, currentUnlocked: string[], options?: ImportOptions): ImportResult;
|
|
594
|
-
|
|
595
|
-
interface AchievementContextType {
|
|
596
|
-
update: (metrics: Record<string, any>) => void;
|
|
597
|
-
achievements: {
|
|
598
|
-
unlocked: string[];
|
|
599
|
-
all: Record<string, any>;
|
|
600
|
-
};
|
|
601
|
-
reset: () => void;
|
|
602
|
-
getState: () => {
|
|
603
|
-
metrics: AchievementMetrics;
|
|
604
|
-
unlocked: string[];
|
|
605
|
-
};
|
|
606
|
-
exportData: () => string;
|
|
607
|
-
importData: (jsonString: string, options?: ImportOptions) => ImportResult;
|
|
608
|
-
getAllAchievements: () => AchievementWithStatus[];
|
|
609
|
-
}
|
|
610
|
-
declare const AchievementContext: React$1.Context<AchievementContextType | undefined>;
|
|
611
|
-
interface AchievementProviderProps {
|
|
612
|
-
achievements: AchievementConfigurationType;
|
|
613
|
-
storage?: AchievementStorage | AsyncAchievementStorage | StorageType;
|
|
614
|
-
children: React$1.ReactNode;
|
|
615
|
-
icons?: Record<string, string>;
|
|
616
|
-
onError?: (error: AchievementError) => void;
|
|
617
|
-
restApiConfig?: RestApiStorageConfig;
|
|
618
|
-
/**
|
|
619
|
-
* UI configuration for notifications, modal, and confetti
|
|
620
|
-
* NEW in v3.6.0
|
|
621
|
-
*/
|
|
622
|
-
ui?: UIConfig;
|
|
623
|
-
/**
|
|
624
|
-
* Force use of built-in UI components (opt-in for v3.x)
|
|
625
|
-
* Set to true to skip legacy library detection and use built-in UI
|
|
626
|
-
* In v4.0.0, this will become the default behavior
|
|
627
|
-
* NEW in v3.6.0
|
|
628
|
-
* @default false
|
|
629
|
-
*/
|
|
630
|
-
useBuiltInUI?: boolean;
|
|
631
|
-
}
|
|
632
|
-
declare const AchievementProvider: React$1.FC<AchievementProviderProps>;
|
|
633
|
-
|
|
634
376
|
declare const useAchievements: () => AchievementContextType;
|
|
635
377
|
|
|
636
378
|
/**
|
|
@@ -675,7 +417,7 @@ declare const useSimpleAchievements: () => {
|
|
|
675
417
|
* Get current state (advanced usage)
|
|
676
418
|
*/
|
|
677
419
|
getState: () => {
|
|
678
|
-
metrics:
|
|
420
|
+
metrics: Record<string, any>;
|
|
679
421
|
unlocked: string[];
|
|
680
422
|
};
|
|
681
423
|
/**
|
|
@@ -689,14 +431,50 @@ declare const useSimpleAchievements: () => {
|
|
|
689
431
|
* @param options - Import options (merge strategy, validation)
|
|
690
432
|
* @returns Import result with success status and any errors
|
|
691
433
|
*/
|
|
692
|
-
importData: (jsonString: string, options?: ImportOptions) => ImportResult;
|
|
434
|
+
importData: (jsonString: string, options?: achievements_engine.ImportOptions) => achievements_engine.ImportResult;
|
|
693
435
|
/**
|
|
694
436
|
* Get all achievements with their unlock status
|
|
695
437
|
* @returns Array of achievements with isUnlocked boolean property
|
|
696
438
|
*/
|
|
697
|
-
getAllAchievements: () => AchievementWithStatus[];
|
|
439
|
+
getAllAchievements: () => achievements_engine.AchievementWithStatus[];
|
|
698
440
|
};
|
|
699
441
|
|
|
442
|
+
/**
|
|
443
|
+
* Hook to access the injected AchievementEngine instance (NEW event-based pattern)
|
|
444
|
+
*
|
|
445
|
+
* IMPORTANT: This hook only works when Provider has an externally created engine injected via the `engine` prop.
|
|
446
|
+
* Do NOT use this hook with the old `achievements` prop pattern - use `useAchievements()` instead.
|
|
447
|
+
*
|
|
448
|
+
* @example
|
|
449
|
+
* ```tsx
|
|
450
|
+
* // Create engine outside React
|
|
451
|
+
* import { AchievementEngine } from 'achievements-engine';
|
|
452
|
+
*
|
|
453
|
+
* const myEngine = new AchievementEngine({
|
|
454
|
+
* achievements: config,
|
|
455
|
+
* eventMapping: { 'userScored': 'score', 'levelUp': 'level' },
|
|
456
|
+
* storage: 'local'
|
|
457
|
+
* });
|
|
458
|
+
*
|
|
459
|
+
* // Inject into Provider
|
|
460
|
+
* <AchievementProvider engine={myEngine}>
|
|
461
|
+
* <App />
|
|
462
|
+
* </AchievementProvider>
|
|
463
|
+
*
|
|
464
|
+
* function App() {
|
|
465
|
+
* const engine = useAchievementEngine();
|
|
466
|
+
* engine.emit('userScored', 100);
|
|
467
|
+
* engine.emit('levelUp', 5);
|
|
468
|
+
* }
|
|
469
|
+
* ```
|
|
470
|
+
*
|
|
471
|
+
* @returns AchievementEngine instance
|
|
472
|
+
* @throws Error if used with old achievements prop pattern
|
|
473
|
+
* @throws Error if used outside AchievementProvider
|
|
474
|
+
* @since 3.8.0
|
|
475
|
+
*/
|
|
476
|
+
declare const useAchievementEngine: () => AchievementEngine;
|
|
477
|
+
|
|
700
478
|
declare const defaultStyles: Required<StylesProps>;
|
|
701
479
|
|
|
702
480
|
declare const defaultAchievementIcons: {
|
|
@@ -708,177 +486,6 @@ declare const defaultAchievementIcons: {
|
|
|
708
486
|
star: string;
|
|
709
487
|
};
|
|
710
488
|
|
|
711
|
-
declare function isSimpleConfig(config: AchievementConfigurationType): config is SimpleAchievementConfig;
|
|
712
|
-
declare function normalizeAchievements(config: AchievementConfigurationType): AchievementConfiguration;
|
|
713
|
-
|
|
714
|
-
/**
|
|
715
|
-
* Helper interface for cleaner achievement award definitions
|
|
716
|
-
*/
|
|
717
|
-
interface AwardDetails {
|
|
718
|
-
title?: string;
|
|
719
|
-
description?: string;
|
|
720
|
-
icon?: string;
|
|
721
|
-
}
|
|
722
|
-
/**
|
|
723
|
-
* Base class for chainable achievement configuration (Tier 2)
|
|
724
|
-
*/
|
|
725
|
-
declare abstract class Achievement {
|
|
726
|
-
protected metric: string;
|
|
727
|
-
protected award: AwardDetails;
|
|
728
|
-
constructor(metric: string, defaultAward: AwardDetails);
|
|
729
|
-
/**
|
|
730
|
-
* Customize the award details for this achievement
|
|
731
|
-
* @param award - Custom award details
|
|
732
|
-
* @returns This achievement for chaining
|
|
733
|
-
*/
|
|
734
|
-
withAward(award: AwardDetails): Achievement;
|
|
735
|
-
/**
|
|
736
|
-
* Convert this achievement to a SimpleAchievementConfig
|
|
737
|
-
*/
|
|
738
|
-
abstract toConfig(): SimpleAchievementConfig;
|
|
739
|
-
}
|
|
740
|
-
/**
|
|
741
|
-
* Threshold-based achievement (score, level, etc.)
|
|
742
|
-
*/
|
|
743
|
-
declare class ThresholdAchievement extends Achievement {
|
|
744
|
-
private threshold;
|
|
745
|
-
constructor(metric: string, threshold: number, defaultAward: AwardDetails);
|
|
746
|
-
toConfig(): SimpleAchievementConfig;
|
|
747
|
-
}
|
|
748
|
-
/**
|
|
749
|
-
* Boolean achievement (tutorial completion, first login, etc.)
|
|
750
|
-
*/
|
|
751
|
-
declare class BooleanAchievement extends Achievement {
|
|
752
|
-
toConfig(): SimpleAchievementConfig;
|
|
753
|
-
}
|
|
754
|
-
/**
|
|
755
|
-
* Value-based achievement (character class, difficulty, etc.)
|
|
756
|
-
*/
|
|
757
|
-
declare class ValueAchievement extends Achievement {
|
|
758
|
-
private value;
|
|
759
|
-
constructor(metric: string, value: string, defaultAward: AwardDetails);
|
|
760
|
-
toConfig(): SimpleAchievementConfig;
|
|
761
|
-
}
|
|
762
|
-
/**
|
|
763
|
-
* Complex achievement builder for power users (Tier 3)
|
|
764
|
-
*/
|
|
765
|
-
declare class ComplexAchievementBuilder {
|
|
766
|
-
private id;
|
|
767
|
-
private metric;
|
|
768
|
-
private condition;
|
|
769
|
-
private award;
|
|
770
|
-
/**
|
|
771
|
-
* Set the unique identifier for this achievement
|
|
772
|
-
*/
|
|
773
|
-
withId(id: string): ComplexAchievementBuilder;
|
|
774
|
-
/**
|
|
775
|
-
* Set the metric this achievement tracks
|
|
776
|
-
*/
|
|
777
|
-
withMetric(metric: string): ComplexAchievementBuilder;
|
|
778
|
-
/**
|
|
779
|
-
* Set the condition function that determines if achievement is unlocked
|
|
780
|
-
*/
|
|
781
|
-
withCondition(fn: (value: AchievementMetricValue, state: AchievementState) => boolean): ComplexAchievementBuilder;
|
|
782
|
-
/**
|
|
783
|
-
* Set the award details for this achievement
|
|
784
|
-
*/
|
|
785
|
-
withAward(award: AwardDetails): ComplexAchievementBuilder;
|
|
786
|
-
/**
|
|
787
|
-
* Build the final achievement configuration
|
|
788
|
-
*/
|
|
789
|
-
build(): SimpleAchievementConfig;
|
|
790
|
-
}
|
|
791
|
-
/**
|
|
792
|
-
* Main AchievementBuilder with three-tier API
|
|
793
|
-
* Tier 1: Simple static methods with smart defaults
|
|
794
|
-
* Tier 2: Chainable customization
|
|
795
|
-
* Tier 3: Full builder for complex logic
|
|
796
|
-
*/
|
|
797
|
-
declare class AchievementBuilder {
|
|
798
|
-
/**
|
|
799
|
-
* Create a single score achievement with smart defaults
|
|
800
|
-
* @param threshold - Score threshold to achieve
|
|
801
|
-
* @returns Chainable ThresholdAchievement
|
|
802
|
-
*/
|
|
803
|
-
static createScoreAchievement(threshold: number): ThresholdAchievement;
|
|
804
|
-
/**
|
|
805
|
-
* Create multiple score achievements
|
|
806
|
-
* @param thresholds - Array of thresholds or [threshold, award] tuples
|
|
807
|
-
* @returns Complete SimpleAchievementConfig
|
|
808
|
-
*/
|
|
809
|
-
static createScoreAchievements(thresholds: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
|
|
810
|
-
/**
|
|
811
|
-
* Create a single level achievement with smart defaults
|
|
812
|
-
* @param level - Level threshold to achieve
|
|
813
|
-
* @returns Chainable ThresholdAchievement
|
|
814
|
-
*/
|
|
815
|
-
static createLevelAchievement(level: number): ThresholdAchievement;
|
|
816
|
-
/**
|
|
817
|
-
* Create multiple level achievements
|
|
818
|
-
* @param levels - Array of levels or [level, award] tuples
|
|
819
|
-
* @returns Complete SimpleAchievementConfig
|
|
820
|
-
*/
|
|
821
|
-
static createLevelAchievements(levels: (number | [number, AwardDetails])[]): SimpleAchievementConfig;
|
|
822
|
-
/**
|
|
823
|
-
* Create a boolean achievement with smart defaults
|
|
824
|
-
* @param metric - The metric name (e.g., 'completedTutorial')
|
|
825
|
-
* @returns Chainable BooleanAchievement
|
|
826
|
-
*/
|
|
827
|
-
static createBooleanAchievement(metric: string): BooleanAchievement;
|
|
828
|
-
/**
|
|
829
|
-
* Create a value-based achievement with smart defaults
|
|
830
|
-
* @param metric - The metric name (e.g., 'characterClass')
|
|
831
|
-
* @param value - The value to match (e.g., 'wizard')
|
|
832
|
-
* @returns Chainable ValueAchievement
|
|
833
|
-
*/
|
|
834
|
-
static createValueAchievement(metric: string, value: string): ValueAchievement;
|
|
835
|
-
/**
|
|
836
|
-
* Create a complex achievement builder for power users
|
|
837
|
-
* @returns ComplexAchievementBuilder for full control
|
|
838
|
-
*/
|
|
839
|
-
static create(): ComplexAchievementBuilder;
|
|
840
|
-
/**
|
|
841
|
-
* Combine multiple achievement configurations
|
|
842
|
-
* @param achievements - Array of SimpleAchievementConfig objects or Achievement instances
|
|
843
|
-
* @returns Combined SimpleAchievementConfig
|
|
844
|
-
*/
|
|
845
|
-
static combine(achievements: (SimpleAchievementConfig | Achievement)[]): SimpleAchievementConfig;
|
|
846
|
-
}
|
|
847
|
-
|
|
848
|
-
/**
|
|
849
|
-
* Structure of exported achievement data
|
|
850
|
-
*/
|
|
851
|
-
interface ExportedData {
|
|
852
|
-
version: string;
|
|
853
|
-
timestamp: number;
|
|
854
|
-
metrics: AchievementMetrics;
|
|
855
|
-
unlockedAchievements: string[];
|
|
856
|
-
configHash?: string;
|
|
857
|
-
}
|
|
858
|
-
/**
|
|
859
|
-
* Exports achievement data to a JSON string
|
|
860
|
-
*
|
|
861
|
-
* @param metrics - Current achievement metrics
|
|
862
|
-
* @param unlocked - Array of unlocked achievement IDs
|
|
863
|
-
* @param configHash - Optional hash of achievement configuration for validation
|
|
864
|
-
* @returns JSON string containing all achievement data
|
|
865
|
-
*
|
|
866
|
-
* @example
|
|
867
|
-
* ```typescript
|
|
868
|
-
* const json = exportAchievementData(_metrics, ['score_100', 'level_5']);
|
|
869
|
-
* // Save json to file or send to server
|
|
870
|
-
* ```
|
|
871
|
-
*/
|
|
872
|
-
declare function exportAchievementData(metrics: AchievementMetrics, unlocked: string[], configHash?: string): string;
|
|
873
|
-
/**
|
|
874
|
-
* Creates a simple hash of the achievement configuration
|
|
875
|
-
* Used to validate that imported data matches the current configuration
|
|
876
|
-
*
|
|
877
|
-
* @param config - Achievement configuration object
|
|
878
|
-
* @returns Simple hash string
|
|
879
|
-
*/
|
|
880
|
-
declare function createConfigHash(config: any): string;
|
|
881
|
-
|
|
882
489
|
/**
|
|
883
490
|
* Built-in notification component
|
|
884
491
|
* Modern, theme-aware achievement notification with smooth animations
|
|
@@ -914,4 +521,4 @@ declare function useWindowSize(): {
|
|
|
914
521
|
height: number;
|
|
915
522
|
};
|
|
916
523
|
|
|
917
|
-
export {
|
|
524
|
+
export { AchievementCondition, AchievementConfiguration, AchievementConfigurationType, AchievementContext, AchievementContextType, AchievementContextValue, AchievementDetails, AchievementMetricArrayValue, AchievementMetricValue, AchievementMetrics, AchievementProvider, AchievementProviderProps$1 as AchievementProviderProps, AchievementState, AchievementStorage, AchievementWithStatus, AnyAchievementStorage, AsyncAchievementStorage, BadgesButton, BadgesButtonWithModal, BadgesModal, BuiltInConfetti, BuiltInModal, BuiltInNotification, ConfettiComponent, ConfettiProps, ConfettiWrapper, CustomAchievementDetails, InitialAchievementMetrics, ModalComponent, ModalProps, NotificationComponent, NotificationPosition, NotificationProps, SimpleAchievementConfig, SimpleAchievementDetails, StylesProps, ThemeConfig, UIConfig, defaultAchievementIcons, defaultStyles, isAsyncStorage, useAchievementEngine, useAchievements, useSimpleAchievements, useWindowSize };
|