czapp-shared 1.0.38 → 1.1.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/dist/index.d.mts +193 -1
- package/dist/index.d.ts +193 -1
- package/dist/index.js +388 -2
- package/dist/index.mjs +362 -1
- package/package.json +1 -1
- package/src/concrete/color.ts +41 -0
- package/src/concrete/level.ts +144 -0
- package/src/concrete/levelDefaults.ts +118 -0
- package/src/concrete/levelValidation.ts +101 -0
- package/src/design/api.ts +5 -0
- package/src/design/levels.ts +103 -0
- package/src/design/user.ts +5 -1
- package/src/index.ts +5 -0
- package/test/level.test.ts +89 -0
- package/test/levelConfig.test.ts +106 -0
package/dist/index.d.mts
CHANGED
|
@@ -1,3 +1,13 @@
|
|
|
1
|
+
type Hsl = {
|
|
2
|
+
h: number;
|
|
3
|
+
s: number;
|
|
4
|
+
l: number;
|
|
5
|
+
};
|
|
6
|
+
declare const hexToHsl: (hex: string) => Hsl;
|
|
7
|
+
declare const hslToHex: ({ h, s, l }: Hsl) => string;
|
|
8
|
+
declare const shiftHue: (hex: string, degrees: number) => string;
|
|
9
|
+
declare const isHexColor: (value: unknown) => value is string;
|
|
10
|
+
|
|
1
11
|
/**
|
|
2
12
|
* @name getMysqlDateIgnoreTZ
|
|
3
13
|
* @description Converts a JavaScript Date object to a MySQL date string by ignoring the timezone
|
|
@@ -51,6 +61,185 @@ declare const isTheSameDay: (date1: MySQLDate, date2: MySQLDate) => boolean;
|
|
|
51
61
|
declare const getFormattedDate: (date: Date) => DateString;
|
|
52
62
|
declare const isExpired: (date: MySQLDate) => boolean;
|
|
53
63
|
|
|
64
|
+
/**
|
|
65
|
+
* Experience level definitions, as stored per level in the czapp-server xp_levels table (draft and published JSON),
|
|
66
|
+
* edited in the backoffice Level Designer and loaded by the apps from GET /levels. See concrete/level.ts for how a
|
|
67
|
+
* user's level is worked out, and concrete/levelDefaults.ts for the built-in defaults.
|
|
68
|
+
*/
|
|
69
|
+
declare enum AvatarPresetId {
|
|
70
|
+
COOL_CATALYST = "coolCatalyst",
|
|
71
|
+
SWIFT_STARTER = "swiftStarter",
|
|
72
|
+
BOLD_BUILDER = "boldBuilder",
|
|
73
|
+
WORD_WRANGLER = "wordWrangler",
|
|
74
|
+
FLUENT_FLAME = "fluentFlame",
|
|
75
|
+
MIGHTY_MASTER = "mightyMaster",
|
|
76
|
+
RADIANT_ROCKSTAR = "radiantRockstar",
|
|
77
|
+
WISE_WIZARD = "wiseWizard",
|
|
78
|
+
LEGENDARY_LINGUIST = "legendaryLinguist",
|
|
79
|
+
ABSOLUTE_ALPHA = "absoluteAlpha"
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Named colour tokens for one level's theme. Every themed colour in the apps comes from one of these, so a designer
|
|
83
|
+
* can coordinate foreground, background and accents freely. All are #rrggbb hex.
|
|
84
|
+
*/
|
|
85
|
+
interface ILevelPalette {
|
|
86
|
+
background: string;
|
|
87
|
+
card: string;
|
|
88
|
+
brand: string;
|
|
89
|
+
brandMid: string;
|
|
90
|
+
brandLight: string;
|
|
91
|
+
brandPale: string;
|
|
92
|
+
points: string;
|
|
93
|
+
streak: string;
|
|
94
|
+
test: string;
|
|
95
|
+
testDark: string;
|
|
96
|
+
testText: string;
|
|
97
|
+
accent: string;
|
|
98
|
+
accentDark: string;
|
|
99
|
+
accentLight: string;
|
|
100
|
+
accentPale: string;
|
|
101
|
+
chartRetired: string;
|
|
102
|
+
chartLearning: string;
|
|
103
|
+
chartQueued: string;
|
|
104
|
+
leaderboardHighlight: string;
|
|
105
|
+
divider: string;
|
|
106
|
+
heatScale: [string, string, string, string, string, string];
|
|
107
|
+
celebrationGradient: [string, string, string];
|
|
108
|
+
iconHueShift: number;
|
|
109
|
+
}
|
|
110
|
+
interface ILevelAvatar {
|
|
111
|
+
alphaHueShift: number;
|
|
112
|
+
preset?: {
|
|
113
|
+
id: AvatarPresetId;
|
|
114
|
+
params: Record<string, number | string>;
|
|
115
|
+
};
|
|
116
|
+
lottie?: string;
|
|
117
|
+
images?: {
|
|
118
|
+
id: string;
|
|
119
|
+
svg: string;
|
|
120
|
+
}[];
|
|
121
|
+
}
|
|
122
|
+
interface ILevelDefinition {
|
|
123
|
+
level: number;
|
|
124
|
+
xpThreshold: number;
|
|
125
|
+
minBestStreak: number;
|
|
126
|
+
names: {
|
|
127
|
+
en: string;
|
|
128
|
+
cz: string;
|
|
129
|
+
};
|
|
130
|
+
palette: ILevelPalette;
|
|
131
|
+
avatar: ILevelAvatar;
|
|
132
|
+
}
|
|
133
|
+
interface IXpAwards {
|
|
134
|
+
flashcardReview: number;
|
|
135
|
+
test: number;
|
|
136
|
+
perTestKnownAnswer: number;
|
|
137
|
+
perWordRetired: number;
|
|
138
|
+
dailyStreakBonusCap: number;
|
|
139
|
+
}
|
|
140
|
+
interface ILevelsConfig {
|
|
141
|
+
version: number;
|
|
142
|
+
levels: ILevelDefinition[];
|
|
143
|
+
awards: IXpAwards;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* GET /levels?version=<the app's cached version>: the published configuration, or just `unchanged` when the app
|
|
147
|
+
* already has the current version, so unchanged configurations aren't re-downloaded on every launch.
|
|
148
|
+
*/
|
|
149
|
+
type LevelsResponseData = ILevelsConfig | {
|
|
150
|
+
version: number;
|
|
151
|
+
unchanged: true;
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* XP and experience levels.
|
|
156
|
+
*
|
|
157
|
+
* XP vs reward points - two separate running totals on the user, both updated by /test/complete:
|
|
158
|
+
*
|
|
159
|
+
* Reward points (IUserData.rewardPoints)
|
|
160
|
+
* - Measure PERFORMANCE: points per word known, plus bonuses for high scores in a session.
|
|
161
|
+
* - Shown to the user (home screen Reward Points card) and ranked on the leaderboard.
|
|
162
|
+
*
|
|
163
|
+
* XP (IUserData.xp)
|
|
164
|
+
* - Measure ENGAGEMENT and PROGRESS: doing reviews and tests at all, mastering (retiring) words, keeping a
|
|
165
|
+
* daily streak. A weak session still earns XP; scores barely matter.
|
|
166
|
+
* - Internal only: NEVER shown to the user, who would confuse it with reward points. Its sole purpose is to
|
|
167
|
+
* decide the user's experience level (the level name and alpha artwork on the home screen).
|
|
168
|
+
*
|
|
169
|
+
* Never derive one from the other, and don't show XP numbers in the app - show the level and progress towards the
|
|
170
|
+
* next one instead.
|
|
171
|
+
*
|
|
172
|
+
* A user's level is derived from their XP and their best streak - it is never stored, so client and server can't
|
|
173
|
+
* disagree, and because neither value ever decreases, a level once reached is never lost.
|
|
174
|
+
*/
|
|
175
|
+
|
|
176
|
+
declare const XP_FLASHCARD_REVIEW = 10;
|
|
177
|
+
declare const XP_TEST = 15;
|
|
178
|
+
declare const XP_PER_TEST_KNOWN_ANSWER = 1;
|
|
179
|
+
declare const XP_PER_WORD_RETIRED = 5;
|
|
180
|
+
declare const XP_DAILY_STREAK_BONUS_CAP = 30;
|
|
181
|
+
interface ILevel {
|
|
182
|
+
level: number;
|
|
183
|
+
xpThreshold: number;
|
|
184
|
+
minBestStreak: number;
|
|
185
|
+
}
|
|
186
|
+
declare const LEVELS: readonly ILevel[];
|
|
187
|
+
declare const maxLevel: number;
|
|
188
|
+
/**
|
|
189
|
+
* @name getLevel
|
|
190
|
+
* @description The highest level whose XP threshold and best-streak requirement are both met. Levels must be
|
|
191
|
+
* reached in order, so a missing streak for level 5 holds the user at level 4 however much XP they have.
|
|
192
|
+
* @param levels - the level rules, e.g. the published ILevelsConfig levels; defaults to the built-in LEVELS
|
|
193
|
+
*/
|
|
194
|
+
declare const getLevel: (xp: number, bestStreak: number, levels?: readonly ILevel[]) => number;
|
|
195
|
+
interface ILevelProgress {
|
|
196
|
+
level: number;
|
|
197
|
+
nextLevel?: number;
|
|
198
|
+
xpToNextLevel: number;
|
|
199
|
+
xpProgress: number;
|
|
200
|
+
streakDaysToNextLevel: number;
|
|
201
|
+
}
|
|
202
|
+
declare const getLevelProgress: (xp: number, bestStreak: number, levels?: readonly ILevel[]) => ILevelProgress;
|
|
203
|
+
declare const DEFAULT_XP_AWARDS: IXpAwards;
|
|
204
|
+
/**
|
|
205
|
+
* @name getFlashcardReviewXp
|
|
206
|
+
* @param retiredCount - words promoted to RETIRED (mastered) by this review
|
|
207
|
+
* @param newStreakDayLength - the streak length if this review is the first of a new streak day, otherwise 0
|
|
208
|
+
* @param awards - the XP award amounts; defaults to the built-in ones
|
|
209
|
+
*/
|
|
210
|
+
declare const getFlashcardReviewXp: (retiredCount: number, newStreakDayLength: number, awards?: IXpAwards) => number;
|
|
211
|
+
declare const getTestXp: (knownCount: number, awards?: IXpAwards) => number;
|
|
212
|
+
declare const getBestStreak: (user: {
|
|
213
|
+
highStreakLength: number;
|
|
214
|
+
currentStreakLength: number;
|
|
215
|
+
}) => number;
|
|
216
|
+
declare const getUserLevelProgress: (user: {
|
|
217
|
+
xp: number;
|
|
218
|
+
highStreakLength: number;
|
|
219
|
+
currentStreakLength: number;
|
|
220
|
+
}, levels?: readonly ILevel[]) => ILevelProgress;
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* A full palette generated from one hue: the original design rotated round the colour wheel by (hue - level 1's
|
|
224
|
+
* hue), with the level's accent shades derived from the hue itself. The Level Designer's "generate from hue" uses
|
|
225
|
+
* this as a starting point.
|
|
226
|
+
*/
|
|
227
|
+
declare const generatePalette: (hue: number) => ILevelPalette;
|
|
228
|
+
declare const DEFAULT_LEVEL_DEFINITIONS: ILevelDefinition[];
|
|
229
|
+
declare const DEFAULT_LEVELS_CONFIG: ILevelsConfig;
|
|
230
|
+
|
|
231
|
+
declare const MAX_LOTTIE_BYTES: number;
|
|
232
|
+
declare const MAX_SVG_BYTES: number;
|
|
233
|
+
declare const MAX_LEVEL_NAME_LENGTH = 40;
|
|
234
|
+
/** Problems with one level definition (empty when it's valid). */
|
|
235
|
+
declare const validateLevelDefinition: (level: ILevelDefinition) => string[];
|
|
236
|
+
declare const validateXpAwards: (awards: IXpAwards) => string[];
|
|
237
|
+
/**
|
|
238
|
+
* Problems with a whole configuration (empty when it can be published): every level valid, levels numbered 1..n
|
|
239
|
+
* with no gaps, XP thresholds rising from 0 and streak gates never falling.
|
|
240
|
+
*/
|
|
241
|
+
declare const validateLevelsConfig: (config: Pick<ILevelsConfig, 'levels' | 'awards'>) => string[];
|
|
242
|
+
|
|
54
243
|
interface ISession {
|
|
55
244
|
sessionToken: string | undefined;
|
|
56
245
|
deviceId: string | undefined;
|
|
@@ -281,6 +470,7 @@ interface IUserData {
|
|
|
281
470
|
uiLanguage: Language;
|
|
282
471
|
completedOnboarding: boolean;
|
|
283
472
|
learningSet: number;
|
|
473
|
+
xp: number;
|
|
284
474
|
}
|
|
285
475
|
|
|
286
476
|
declare enum HttpStatusCode {
|
|
@@ -304,6 +494,7 @@ declare enum ApiPath {
|
|
|
304
494
|
HEALTH = "/health",
|
|
305
495
|
LAST_WORDS_ADDED = "/lastWordsAdded",
|
|
306
496
|
LEADERBOARD = "/leaderboard",
|
|
497
|
+
LEVELS = "/levels",
|
|
307
498
|
LEXEMES = "/lexemes",
|
|
308
499
|
LEXEMES_ALL = "/lexemes/all",
|
|
309
500
|
LEXEMES_COUNT = "/lexemes/count/:language",
|
|
@@ -475,6 +666,7 @@ interface TestCompleteResponseData {
|
|
|
475
666
|
user: IUserData;
|
|
476
667
|
testResultIds: number[];
|
|
477
668
|
rewardPointsDelta: number;
|
|
669
|
+
xpDelta: number;
|
|
478
670
|
vocabCheckActivity: IVocabCheckActivity[];
|
|
479
671
|
}
|
|
480
672
|
interface HeatMapResponseData {
|
|
@@ -489,4 +681,4 @@ type DeeplTranslation = {
|
|
|
489
681
|
}>;
|
|
490
682
|
};
|
|
491
683
|
|
|
492
|
-
export { ApiMethod, ApiPath, AppError, type AutologinRequestBody, ClientPlatform, type ControllerResponse, type DateString, type DeeplTranslation, type DeleteLexemePairRequestParams, Familiarity, type HeatMapParams, type HeatMapResponseData, HttpStatusCode, type IActivityCount, type ICount, type ILeaderboardEntry, type ILexeme, type ILexemeIdPair, type ILexemeLearningInfo, type ILexemePair, type ILexemePairTexts, type IProgressHistoryDay, type ISession, type ITestResult, type IUserData, type IVocabCheckActivity, type InsertOrUpdateRequestBody, type InsertOrUpdateResponseData, LEARNING_STAGES_IN_GROUP, Language, LearningStage, LearningStageGroup, Lexeme, LexemePair, type LexemePairRequestBody, type LexemePairWithLang, type MySQLDate, Progress, type RecycleLexemePairParams, type RegisterPushTokenRequestBody, ReminderFrequency, type ResetTestUserParams, type Result, Scenario, type SelectAllTranslationsParams, type SelectLexemeCountParams, type SelectLexemePairParams, type SelectLexemePairsByTextParams, type SelectLexemesParams, type SelectProgressHistoryParams, type SelectTestLexemesParams, type SelectVocabCheckActivityParams, type SignInRequestBody, type SignInResponseData, type Streaks, type TestCompleteRequestBody, type TestCompleteResponseData, type TestInitRequestBody, type TestInitResponseData, type TranslationRequestBody, type TranslationResponseData, type UpdateLexemePairFamiliarityParams, type UpdateOnboardingStatusRequestBody, type UpdateUserRequestBody, VocabCheckType, convertJSDateStringToMySQLDate, dateDifferenceInDays, deriveStreakFromVocabCheckActivity, getFormattedDate, getMysqlDateIgnoreTZ, isClientDateTooFarFromServerDate, isExpired, isFinalTest, isLearningStageGroup, isStringContainingInteger, isThePreviousDay, isTheSameDay, isValidJsDateString, isValidMysqlDateString, parameterReplace };
|
|
684
|
+
export { ApiMethod, ApiPath, AppError, type AutologinRequestBody, AvatarPresetId, ClientPlatform, type ControllerResponse, DEFAULT_LEVELS_CONFIG, DEFAULT_LEVEL_DEFINITIONS, DEFAULT_XP_AWARDS, type DateString, type DeeplTranslation, type DeleteLexemePairRequestParams, Familiarity, type HeatMapParams, type HeatMapResponseData, type Hsl, HttpStatusCode, type IActivityCount, type ICount, type ILeaderboardEntry, type ILevel, type ILevelAvatar, type ILevelDefinition, type ILevelPalette, type ILevelProgress, type ILevelsConfig, type ILexeme, type ILexemeIdPair, type ILexemeLearningInfo, type ILexemePair, type ILexemePairTexts, type IProgressHistoryDay, type ISession, type ITestResult, type IUserData, type IVocabCheckActivity, type IXpAwards, type InsertOrUpdateRequestBody, type InsertOrUpdateResponseData, LEARNING_STAGES_IN_GROUP, LEVELS, Language, LearningStage, LearningStageGroup, type LevelsResponseData, Lexeme, LexemePair, type LexemePairRequestBody, type LexemePairWithLang, MAX_LEVEL_NAME_LENGTH, MAX_LOTTIE_BYTES, MAX_SVG_BYTES, type MySQLDate, Progress, type RecycleLexemePairParams, type RegisterPushTokenRequestBody, ReminderFrequency, type ResetTestUserParams, type Result, Scenario, type SelectAllTranslationsParams, type SelectLexemeCountParams, type SelectLexemePairParams, type SelectLexemePairsByTextParams, type SelectLexemesParams, type SelectProgressHistoryParams, type SelectTestLexemesParams, type SelectVocabCheckActivityParams, type SignInRequestBody, type SignInResponseData, type Streaks, type TestCompleteRequestBody, type TestCompleteResponseData, type TestInitRequestBody, type TestInitResponseData, type TranslationRequestBody, type TranslationResponseData, type UpdateLexemePairFamiliarityParams, type UpdateOnboardingStatusRequestBody, type UpdateUserRequestBody, VocabCheckType, XP_DAILY_STREAK_BONUS_CAP, XP_FLASHCARD_REVIEW, XP_PER_TEST_KNOWN_ANSWER, XP_PER_WORD_RETIRED, XP_TEST, convertJSDateStringToMySQLDate, dateDifferenceInDays, deriveStreakFromVocabCheckActivity, generatePalette, getBestStreak, getFlashcardReviewXp, getFormattedDate, getLevel, getLevelProgress, getMysqlDateIgnoreTZ, getTestXp, getUserLevelProgress, hexToHsl, hslToHex, isClientDateTooFarFromServerDate, isExpired, isFinalTest, isHexColor, isLearningStageGroup, isStringContainingInteger, isThePreviousDay, isTheSameDay, isValidJsDateString, isValidMysqlDateString, maxLevel, parameterReplace, shiftHue, validateLevelDefinition, validateLevelsConfig, validateXpAwards };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,13 @@
|
|
|
1
|
+
type Hsl = {
|
|
2
|
+
h: number;
|
|
3
|
+
s: number;
|
|
4
|
+
l: number;
|
|
5
|
+
};
|
|
6
|
+
declare const hexToHsl: (hex: string) => Hsl;
|
|
7
|
+
declare const hslToHex: ({ h, s, l }: Hsl) => string;
|
|
8
|
+
declare const shiftHue: (hex: string, degrees: number) => string;
|
|
9
|
+
declare const isHexColor: (value: unknown) => value is string;
|
|
10
|
+
|
|
1
11
|
/**
|
|
2
12
|
* @name getMysqlDateIgnoreTZ
|
|
3
13
|
* @description Converts a JavaScript Date object to a MySQL date string by ignoring the timezone
|
|
@@ -51,6 +61,185 @@ declare const isTheSameDay: (date1: MySQLDate, date2: MySQLDate) => boolean;
|
|
|
51
61
|
declare const getFormattedDate: (date: Date) => DateString;
|
|
52
62
|
declare const isExpired: (date: MySQLDate) => boolean;
|
|
53
63
|
|
|
64
|
+
/**
|
|
65
|
+
* Experience level definitions, as stored per level in the czapp-server xp_levels table (draft and published JSON),
|
|
66
|
+
* edited in the backoffice Level Designer and loaded by the apps from GET /levels. See concrete/level.ts for how a
|
|
67
|
+
* user's level is worked out, and concrete/levelDefaults.ts for the built-in defaults.
|
|
68
|
+
*/
|
|
69
|
+
declare enum AvatarPresetId {
|
|
70
|
+
COOL_CATALYST = "coolCatalyst",
|
|
71
|
+
SWIFT_STARTER = "swiftStarter",
|
|
72
|
+
BOLD_BUILDER = "boldBuilder",
|
|
73
|
+
WORD_WRANGLER = "wordWrangler",
|
|
74
|
+
FLUENT_FLAME = "fluentFlame",
|
|
75
|
+
MIGHTY_MASTER = "mightyMaster",
|
|
76
|
+
RADIANT_ROCKSTAR = "radiantRockstar",
|
|
77
|
+
WISE_WIZARD = "wiseWizard",
|
|
78
|
+
LEGENDARY_LINGUIST = "legendaryLinguist",
|
|
79
|
+
ABSOLUTE_ALPHA = "absoluteAlpha"
|
|
80
|
+
}
|
|
81
|
+
/**
|
|
82
|
+
* Named colour tokens for one level's theme. Every themed colour in the apps comes from one of these, so a designer
|
|
83
|
+
* can coordinate foreground, background and accents freely. All are #rrggbb hex.
|
|
84
|
+
*/
|
|
85
|
+
interface ILevelPalette {
|
|
86
|
+
background: string;
|
|
87
|
+
card: string;
|
|
88
|
+
brand: string;
|
|
89
|
+
brandMid: string;
|
|
90
|
+
brandLight: string;
|
|
91
|
+
brandPale: string;
|
|
92
|
+
points: string;
|
|
93
|
+
streak: string;
|
|
94
|
+
test: string;
|
|
95
|
+
testDark: string;
|
|
96
|
+
testText: string;
|
|
97
|
+
accent: string;
|
|
98
|
+
accentDark: string;
|
|
99
|
+
accentLight: string;
|
|
100
|
+
accentPale: string;
|
|
101
|
+
chartRetired: string;
|
|
102
|
+
chartLearning: string;
|
|
103
|
+
chartQueued: string;
|
|
104
|
+
leaderboardHighlight: string;
|
|
105
|
+
divider: string;
|
|
106
|
+
heatScale: [string, string, string, string, string, string];
|
|
107
|
+
celebrationGradient: [string, string, string];
|
|
108
|
+
iconHueShift: number;
|
|
109
|
+
}
|
|
110
|
+
interface ILevelAvatar {
|
|
111
|
+
alphaHueShift: number;
|
|
112
|
+
preset?: {
|
|
113
|
+
id: AvatarPresetId;
|
|
114
|
+
params: Record<string, number | string>;
|
|
115
|
+
};
|
|
116
|
+
lottie?: string;
|
|
117
|
+
images?: {
|
|
118
|
+
id: string;
|
|
119
|
+
svg: string;
|
|
120
|
+
}[];
|
|
121
|
+
}
|
|
122
|
+
interface ILevelDefinition {
|
|
123
|
+
level: number;
|
|
124
|
+
xpThreshold: number;
|
|
125
|
+
minBestStreak: number;
|
|
126
|
+
names: {
|
|
127
|
+
en: string;
|
|
128
|
+
cz: string;
|
|
129
|
+
};
|
|
130
|
+
palette: ILevelPalette;
|
|
131
|
+
avatar: ILevelAvatar;
|
|
132
|
+
}
|
|
133
|
+
interface IXpAwards {
|
|
134
|
+
flashcardReview: number;
|
|
135
|
+
test: number;
|
|
136
|
+
perTestKnownAnswer: number;
|
|
137
|
+
perWordRetired: number;
|
|
138
|
+
dailyStreakBonusCap: number;
|
|
139
|
+
}
|
|
140
|
+
interface ILevelsConfig {
|
|
141
|
+
version: number;
|
|
142
|
+
levels: ILevelDefinition[];
|
|
143
|
+
awards: IXpAwards;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* GET /levels?version=<the app's cached version>: the published configuration, or just `unchanged` when the app
|
|
147
|
+
* already has the current version, so unchanged configurations aren't re-downloaded on every launch.
|
|
148
|
+
*/
|
|
149
|
+
type LevelsResponseData = ILevelsConfig | {
|
|
150
|
+
version: number;
|
|
151
|
+
unchanged: true;
|
|
152
|
+
};
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* XP and experience levels.
|
|
156
|
+
*
|
|
157
|
+
* XP vs reward points - two separate running totals on the user, both updated by /test/complete:
|
|
158
|
+
*
|
|
159
|
+
* Reward points (IUserData.rewardPoints)
|
|
160
|
+
* - Measure PERFORMANCE: points per word known, plus bonuses for high scores in a session.
|
|
161
|
+
* - Shown to the user (home screen Reward Points card) and ranked on the leaderboard.
|
|
162
|
+
*
|
|
163
|
+
* XP (IUserData.xp)
|
|
164
|
+
* - Measure ENGAGEMENT and PROGRESS: doing reviews and tests at all, mastering (retiring) words, keeping a
|
|
165
|
+
* daily streak. A weak session still earns XP; scores barely matter.
|
|
166
|
+
* - Internal only: NEVER shown to the user, who would confuse it with reward points. Its sole purpose is to
|
|
167
|
+
* decide the user's experience level (the level name and alpha artwork on the home screen).
|
|
168
|
+
*
|
|
169
|
+
* Never derive one from the other, and don't show XP numbers in the app - show the level and progress towards the
|
|
170
|
+
* next one instead.
|
|
171
|
+
*
|
|
172
|
+
* A user's level is derived from their XP and their best streak - it is never stored, so client and server can't
|
|
173
|
+
* disagree, and because neither value ever decreases, a level once reached is never lost.
|
|
174
|
+
*/
|
|
175
|
+
|
|
176
|
+
declare const XP_FLASHCARD_REVIEW = 10;
|
|
177
|
+
declare const XP_TEST = 15;
|
|
178
|
+
declare const XP_PER_TEST_KNOWN_ANSWER = 1;
|
|
179
|
+
declare const XP_PER_WORD_RETIRED = 5;
|
|
180
|
+
declare const XP_DAILY_STREAK_BONUS_CAP = 30;
|
|
181
|
+
interface ILevel {
|
|
182
|
+
level: number;
|
|
183
|
+
xpThreshold: number;
|
|
184
|
+
minBestStreak: number;
|
|
185
|
+
}
|
|
186
|
+
declare const LEVELS: readonly ILevel[];
|
|
187
|
+
declare const maxLevel: number;
|
|
188
|
+
/**
|
|
189
|
+
* @name getLevel
|
|
190
|
+
* @description The highest level whose XP threshold and best-streak requirement are both met. Levels must be
|
|
191
|
+
* reached in order, so a missing streak for level 5 holds the user at level 4 however much XP they have.
|
|
192
|
+
* @param levels - the level rules, e.g. the published ILevelsConfig levels; defaults to the built-in LEVELS
|
|
193
|
+
*/
|
|
194
|
+
declare const getLevel: (xp: number, bestStreak: number, levels?: readonly ILevel[]) => number;
|
|
195
|
+
interface ILevelProgress {
|
|
196
|
+
level: number;
|
|
197
|
+
nextLevel?: number;
|
|
198
|
+
xpToNextLevel: number;
|
|
199
|
+
xpProgress: number;
|
|
200
|
+
streakDaysToNextLevel: number;
|
|
201
|
+
}
|
|
202
|
+
declare const getLevelProgress: (xp: number, bestStreak: number, levels?: readonly ILevel[]) => ILevelProgress;
|
|
203
|
+
declare const DEFAULT_XP_AWARDS: IXpAwards;
|
|
204
|
+
/**
|
|
205
|
+
* @name getFlashcardReviewXp
|
|
206
|
+
* @param retiredCount - words promoted to RETIRED (mastered) by this review
|
|
207
|
+
* @param newStreakDayLength - the streak length if this review is the first of a new streak day, otherwise 0
|
|
208
|
+
* @param awards - the XP award amounts; defaults to the built-in ones
|
|
209
|
+
*/
|
|
210
|
+
declare const getFlashcardReviewXp: (retiredCount: number, newStreakDayLength: number, awards?: IXpAwards) => number;
|
|
211
|
+
declare const getTestXp: (knownCount: number, awards?: IXpAwards) => number;
|
|
212
|
+
declare const getBestStreak: (user: {
|
|
213
|
+
highStreakLength: number;
|
|
214
|
+
currentStreakLength: number;
|
|
215
|
+
}) => number;
|
|
216
|
+
declare const getUserLevelProgress: (user: {
|
|
217
|
+
xp: number;
|
|
218
|
+
highStreakLength: number;
|
|
219
|
+
currentStreakLength: number;
|
|
220
|
+
}, levels?: readonly ILevel[]) => ILevelProgress;
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* A full palette generated from one hue: the original design rotated round the colour wheel by (hue - level 1's
|
|
224
|
+
* hue), with the level's accent shades derived from the hue itself. The Level Designer's "generate from hue" uses
|
|
225
|
+
* this as a starting point.
|
|
226
|
+
*/
|
|
227
|
+
declare const generatePalette: (hue: number) => ILevelPalette;
|
|
228
|
+
declare const DEFAULT_LEVEL_DEFINITIONS: ILevelDefinition[];
|
|
229
|
+
declare const DEFAULT_LEVELS_CONFIG: ILevelsConfig;
|
|
230
|
+
|
|
231
|
+
declare const MAX_LOTTIE_BYTES: number;
|
|
232
|
+
declare const MAX_SVG_BYTES: number;
|
|
233
|
+
declare const MAX_LEVEL_NAME_LENGTH = 40;
|
|
234
|
+
/** Problems with one level definition (empty when it's valid). */
|
|
235
|
+
declare const validateLevelDefinition: (level: ILevelDefinition) => string[];
|
|
236
|
+
declare const validateXpAwards: (awards: IXpAwards) => string[];
|
|
237
|
+
/**
|
|
238
|
+
* Problems with a whole configuration (empty when it can be published): every level valid, levels numbered 1..n
|
|
239
|
+
* with no gaps, XP thresholds rising from 0 and streak gates never falling.
|
|
240
|
+
*/
|
|
241
|
+
declare const validateLevelsConfig: (config: Pick<ILevelsConfig, 'levels' | 'awards'>) => string[];
|
|
242
|
+
|
|
54
243
|
interface ISession {
|
|
55
244
|
sessionToken: string | undefined;
|
|
56
245
|
deviceId: string | undefined;
|
|
@@ -281,6 +470,7 @@ interface IUserData {
|
|
|
281
470
|
uiLanguage: Language;
|
|
282
471
|
completedOnboarding: boolean;
|
|
283
472
|
learningSet: number;
|
|
473
|
+
xp: number;
|
|
284
474
|
}
|
|
285
475
|
|
|
286
476
|
declare enum HttpStatusCode {
|
|
@@ -304,6 +494,7 @@ declare enum ApiPath {
|
|
|
304
494
|
HEALTH = "/health",
|
|
305
495
|
LAST_WORDS_ADDED = "/lastWordsAdded",
|
|
306
496
|
LEADERBOARD = "/leaderboard",
|
|
497
|
+
LEVELS = "/levels",
|
|
307
498
|
LEXEMES = "/lexemes",
|
|
308
499
|
LEXEMES_ALL = "/lexemes/all",
|
|
309
500
|
LEXEMES_COUNT = "/lexemes/count/:language",
|
|
@@ -475,6 +666,7 @@ interface TestCompleteResponseData {
|
|
|
475
666
|
user: IUserData;
|
|
476
667
|
testResultIds: number[];
|
|
477
668
|
rewardPointsDelta: number;
|
|
669
|
+
xpDelta: number;
|
|
478
670
|
vocabCheckActivity: IVocabCheckActivity[];
|
|
479
671
|
}
|
|
480
672
|
interface HeatMapResponseData {
|
|
@@ -489,4 +681,4 @@ type DeeplTranslation = {
|
|
|
489
681
|
}>;
|
|
490
682
|
};
|
|
491
683
|
|
|
492
|
-
export { ApiMethod, ApiPath, AppError, type AutologinRequestBody, ClientPlatform, type ControllerResponse, type DateString, type DeeplTranslation, type DeleteLexemePairRequestParams, Familiarity, type HeatMapParams, type HeatMapResponseData, HttpStatusCode, type IActivityCount, type ICount, type ILeaderboardEntry, type ILexeme, type ILexemeIdPair, type ILexemeLearningInfo, type ILexemePair, type ILexemePairTexts, type IProgressHistoryDay, type ISession, type ITestResult, type IUserData, type IVocabCheckActivity, type InsertOrUpdateRequestBody, type InsertOrUpdateResponseData, LEARNING_STAGES_IN_GROUP, Language, LearningStage, LearningStageGroup, Lexeme, LexemePair, type LexemePairRequestBody, type LexemePairWithLang, type MySQLDate, Progress, type RecycleLexemePairParams, type RegisterPushTokenRequestBody, ReminderFrequency, type ResetTestUserParams, type Result, Scenario, type SelectAllTranslationsParams, type SelectLexemeCountParams, type SelectLexemePairParams, type SelectLexemePairsByTextParams, type SelectLexemesParams, type SelectProgressHistoryParams, type SelectTestLexemesParams, type SelectVocabCheckActivityParams, type SignInRequestBody, type SignInResponseData, type Streaks, type TestCompleteRequestBody, type TestCompleteResponseData, type TestInitRequestBody, type TestInitResponseData, type TranslationRequestBody, type TranslationResponseData, type UpdateLexemePairFamiliarityParams, type UpdateOnboardingStatusRequestBody, type UpdateUserRequestBody, VocabCheckType, convertJSDateStringToMySQLDate, dateDifferenceInDays, deriveStreakFromVocabCheckActivity, getFormattedDate, getMysqlDateIgnoreTZ, isClientDateTooFarFromServerDate, isExpired, isFinalTest, isLearningStageGroup, isStringContainingInteger, isThePreviousDay, isTheSameDay, isValidJsDateString, isValidMysqlDateString, parameterReplace };
|
|
684
|
+
export { ApiMethod, ApiPath, AppError, type AutologinRequestBody, AvatarPresetId, ClientPlatform, type ControllerResponse, DEFAULT_LEVELS_CONFIG, DEFAULT_LEVEL_DEFINITIONS, DEFAULT_XP_AWARDS, type DateString, type DeeplTranslation, type DeleteLexemePairRequestParams, Familiarity, type HeatMapParams, type HeatMapResponseData, type Hsl, HttpStatusCode, type IActivityCount, type ICount, type ILeaderboardEntry, type ILevel, type ILevelAvatar, type ILevelDefinition, type ILevelPalette, type ILevelProgress, type ILevelsConfig, type ILexeme, type ILexemeIdPair, type ILexemeLearningInfo, type ILexemePair, type ILexemePairTexts, type IProgressHistoryDay, type ISession, type ITestResult, type IUserData, type IVocabCheckActivity, type IXpAwards, type InsertOrUpdateRequestBody, type InsertOrUpdateResponseData, LEARNING_STAGES_IN_GROUP, LEVELS, Language, LearningStage, LearningStageGroup, type LevelsResponseData, Lexeme, LexemePair, type LexemePairRequestBody, type LexemePairWithLang, MAX_LEVEL_NAME_LENGTH, MAX_LOTTIE_BYTES, MAX_SVG_BYTES, type MySQLDate, Progress, type RecycleLexemePairParams, type RegisterPushTokenRequestBody, ReminderFrequency, type ResetTestUserParams, type Result, Scenario, type SelectAllTranslationsParams, type SelectLexemeCountParams, type SelectLexemePairParams, type SelectLexemePairsByTextParams, type SelectLexemesParams, type SelectProgressHistoryParams, type SelectTestLexemesParams, type SelectVocabCheckActivityParams, type SignInRequestBody, type SignInResponseData, type Streaks, type TestCompleteRequestBody, type TestCompleteResponseData, type TestInitRequestBody, type TestInitResponseData, type TranslationRequestBody, type TranslationResponseData, type UpdateLexemePairFamiliarityParams, type UpdateOnboardingStatusRequestBody, type UpdateUserRequestBody, VocabCheckType, XP_DAILY_STREAK_BONUS_CAP, XP_FLASHCARD_REVIEW, XP_PER_TEST_KNOWN_ANSWER, XP_PER_WORD_RETIRED, XP_TEST, convertJSDateStringToMySQLDate, dateDifferenceInDays, deriveStreakFromVocabCheckActivity, generatePalette, getBestStreak, getFlashcardReviewXp, getFormattedDate, getLevel, getLevelProgress, getMysqlDateIgnoreTZ, getTestXp, getUserLevelProgress, hexToHsl, hslToHex, isClientDateTooFarFromServerDate, isExpired, isFinalTest, isHexColor, isLearningStageGroup, isStringContainingInteger, isThePreviousDay, isTheSameDay, isValidJsDateString, isValidMysqlDateString, maxLevel, parameterReplace, shiftHue, validateLevelDefinition, validateLevelsConfig, validateXpAwards };
|