feat: Achievements

.env.example

@@ -69,4 +69,5 @@ ZOOM_ACCOUNT_ID=
 ZOOM_MEETING_SDK_CLIENT_ID=
 ZOOM_MEETING_SDK_CLIENT_SECRET=
 
-ZOOM_ACTIVE=
+ZOOM_ACTIVE=
+GAMIFICATION_ACTIVE=

common/achievement/aggregator.ts

@@ -4,4 +4,34 @@ type Aggregator = Record<string, AggregatorFunction>;
 
 // Aggregators are needed to aggregate event values (achievement_event.value) or buckets for evaluation (like sum, count, max, min, avg)
 
-export const aggregators: Aggregator = {};
+export const aggregators: Aggregator = {
+    sum: {
+        function: (elements): number => {
+            return elements.reduce((total, num) => total + num, 0);
+        },
+    },
+    count: {
+        function: (elements): number => {
+            return elements.length;
+        },
+    },
+    // this aggregator should be used to check if min one event exist in a bucket, i.e. if one event happend in one week / one month
+    presenceOfEvents: {
+        function: (elements): number => {
+            return elements.length > 0 ? 1 : 0;
+        },
+    },
+    lastStreakLength: {
+        function: (elements): number => {
+            // elements are sorted desc, i.e. [KW 52, KW 51, KW 50]
+            let value = 0;
+            for (const element of elements) {
+                if (element === 0) {
+                    break;
+                }
+                value += 1;
+            }
+            return value;
+        },
+    },
+};

common/achievement/bucket.ts

@@ -1,6 +1,84 @@
-import { BucketFormula } from './types';
+import moment from 'moment';
+import { BucketFormula, DefaultBucket, GenericBucketConfig, TimeBucket } from './types';
 
 type BucketCreatorDefs = Record<string, BucketFormula>;
 
 // Buckets are needed to pre-sort and aggregate certain events by types / a certain time window (e.g. weekly) etc.
-export const bucketCreatorDefs: BucketCreatorDefs = {};
+export const bucketCreatorDefs: BucketCreatorDefs = {
+    default: {
+        function: (): GenericBucketConfig<DefaultBucket> => {
+            return { bucketKind: 'default', buckets: [] };
+        },
+    },
+    by_lecture_start: {
+        function: (bucketContext): GenericBucketConfig<TimeBucket> => {
+            const { context } = bucketContext;
+
+            if (!context[context.type].lecture) {
+                return { bucketKind: 'time', buckets: [] };
+            }
+
+            return {
+                bucketKind: 'time',
+                buckets: context[context.type].lecture.map((lecture) => ({
+                    kind: 'time',
+                    startTime: moment(lecture.start).subtract(10, 'minutes').toDate(),
+                    endTime: moment(lecture.start).add(lecture.duration, 'minutes').add(10, 'minutes').toDate(),
+                })),
+            };
+        },
+    },
+    by_weeks: {
+        function: (context): GenericBucketConfig<TimeBucket> => {
+            const { recordValue: weeks } = context;
+            // the buckets are created in a desc order
+            const today = moment();
+            const buckets: TimeBucket[] = [];
+
+            /*
+            This is to look at the last few weeks before the current event so that we can evaluate whether the streak has been interrupted for the last few weeks or whether we have a new record.
+            ---
+            Why do we pass the `recordValue` as weeks / months?
+            Let's imagine our current record: 6
+            We now want to see if this record still exists. We want to know whether the last 7 weeks are correct, because the previous record was 6.
+            Now it doesn't matter how long the user was inactive or similar. As soon as only one bucket is found among these buckets (7 buckets) that contains nothing, we know that the record has not been surpassed.
+            */
+            for (let i = 0; i < weeks + 1; i++) {
+                const weeksBefore = today.clone().subtract(i, 'week');
+                buckets.push({
+                    kind: 'time',
+                    startTime: weeksBefore.startOf('week').toDate(),
+                    endTime: weeksBefore.endOf('week').toDate(),
+                });
+            }
+
+            return {
+                bucketKind: 'time',
+                buckets,
+            };
+        },
+    },
+    by_months: {
+        function: (context): GenericBucketConfig<TimeBucket> => {
+            const { recordValue: months } = context;
+
+            // the buckets are created in a desc order
+            const today = moment();
+            const buckets: TimeBucket[] = [];
+
+            for (let i = 0; i < months + 1; i++) {
+                const monthsBefore = today.clone().subtract(i, 'month');
+                buckets.push({
+                    kind: 'time',
+                    startTime: monthsBefore.startOf('month').toDate(),
+                    endTime: monthsBefore.endOf('month').toDate(),
+                });
+            }
+
+            return {
+                bucketKind: 'time',
+                buckets,
+            };
+        },
+    },
+};

common/achievement/create.ts

@@ -0,0 +1,96 @@
+import { Prisma } from '@prisma/client';
+import { Achievement_template, JsonFilter, achievement_template_for_enum } from '../../graphql/generated';
+import { ActionID, SpecificNotificationContext } from '../notification/actions';
+import { prisma } from '../prisma';
+import { TemplateSelectEnum, getAchievementTemplates } from './template';
+
+async function findUserAchievement<ID extends ActionID>(templateId: number, userId: string, context: SpecificNotificationContext<ID>) {
+    const keys = context ? Object.keys(context) : [];
+    const userAchievement = await prisma.user_achievement.findFirst({
+        where: {
+            templateId,
+            userId,
+            AND: keys.map((key) => {
+                return {
+                    context: {
+                        path: key,
+                        equals: context[key],
+                    },
+                };
+            }),
+        },
+        select: { id: true, userId: true, context: true, template: true, achievedAt: true, recordValue: true },
+    });
+    return userAchievement;
+}
+
+async function getOrCreateUserAchievement<ID extends ActionID>(template: Achievement_template, userId: string, context?: SpecificNotificationContext<ID>) {
+    const isGlobal =
+        template.templateFor === achievement_template_for_enum.Global ||
+        template.templateFor === achievement_template_for_enum.Global_Courses ||
+        template.templateFor === achievement_template_for_enum.Global_Matches;
+    const existingUserAchievement = await findUserAchievement(template.id, userId, !isGlobal && context);
+    if (!existingUserAchievement) {
+        return await createAchievement(template, userId, context);
+    }
+    return existingUserAchievement;
+}
+
+async function createAchievement<ID extends ActionID>(currentTemplate: Achievement_template, userId: string, context: SpecificNotificationContext<ID>) {
+    const templatesByGroup = await getAchievementTemplates(TemplateSelectEnum.BY_GROUP);
+    const keys = Object.keys(context);
+    const userAchievementsByGroup = await prisma.user_achievement.findMany({
+        where: {
+            template: {
+                group: currentTemplate.group,
+            },
+            userId,
+            AND: keys.map((key) => {
+                return {
+                    context: {
+                        path: key,
+                        equals: context[key],
+                    },
+                };
+            }),
+        },
+        orderBy: { template: { groupOrder: 'asc' } },
+    });
+
+    const nextStepIndex = userAchievementsByGroup.length > 0 ? userAchievementsByGroup.findIndex((e) => e.groupOrder === currentTemplate.groupOrder) + 1 : 0;
+
+    const templatesForGroup = templatesByGroup.get(currentTemplate.group);
+    if (templatesForGroup && templatesForGroup.length > nextStepIndex) {
+        const createdUserAchievement = await createNextUserAchievement(templatesForGroup, nextStepIndex, userId, context);
+        return createdUserAchievement;
+    }
+}
+
+async function createNextUserAchievement<ID extends ActionID>(
+    templatesForGroup: Achievement_template[],
+    nextStepIndex: number,
+    userId: string,
+    context: SpecificNotificationContext<ID>
+) {
+    const nextStepTemplate = templatesForGroup[nextStepIndex];
+    // Here a user template is created for the next template in the group. This is done to always have the data availible for the next step.
+    // This could mean to, for example, have the name of a match partner that is not yet availible due to a unfinished matching process.
+    if (nextStepTemplate && nextStepTemplate.isActive) {
+        const createdUserAchievement = await prisma.user_achievement.create({
+            data: {
+                userId: userId,
+                group: nextStepTemplate.group,
+                groupOrder: nextStepTemplate.groupOrder,
+                context: context ? context : Prisma.JsonNull,
+                template: { connect: { id: nextStepTemplate.id } },
+                recordValue: nextStepTemplate.type === 'STREAK' ? 0 : null,
+            },
+            select: { id: true, userId: true, context: true, template: true, achievedAt: true, recordValue: true },
+        });
+        return createdUserAchievement;
+    }
+    const nextUserAchievement = await createNextUserAchievement(templatesForGroup, nextStepIndex + 1, userId, context);
+    return nextUserAchievement;
+}
+
+export { getOrCreateUserAchievement, createAchievement };

common/achievement/evaluate.ts

@@ -0,0 +1,114 @@
+import { Achievement_event } from '../../graphql/generated';
+import { AchievementContextType, BucketConfig, BucketEvents, ConditionDataAggregations, EvaluationResult } from './types';
+import { prisma } from '../prisma';
+import { aggregators } from './aggregator';
+import swan from '@onlabsorg/swan-js';
+import { bucketCreatorDefs } from './bucket';
+import { getLogger } from '../logger/logger';
+import { getBucketContext } from './util';
+const logger = getLogger('Achievement');
+
+export async function evaluateAchievement(
+    condition: string,
+    dataAggregation: ConditionDataAggregations,
+    metrics: string[],
+    recordValue: number
+): Promise<EvaluationResult> {
+    const achievementEvents = await prisma.achievement_event.findMany({ where: { metric: { in: metrics } }, orderBy: { createdAt: 'desc' } });
+
+    const eventsByMetric: Record<string, Achievement_event[]> = {};
+    for (const event of achievementEvents) {
+        if (!eventsByMetric[event.metric]) {
+            eventsByMetric[event.metric] = [];
+        }
+        eventsByMetric[event.metric].push(event);
+    }
+
+    const resultObject: Record<string, number> = {};
+    resultObject['recordValue'] = recordValue;
+
+    for (const key in dataAggregation) {
+        if (!dataAggregation[key]) {
+            continue;
+        }
+        const dataAggregationObject = dataAggregation[key];
+        const metricName = dataAggregationObject.metric;
+
+        const bucketCreator = dataAggregationObject.createBuckets || 'default';
+        const bucketAggregator = dataAggregationObject.bucketAggregator || 'count';
+
+        const aggregator = dataAggregationObject.aggregator;
+
+        const eventsForMetric = eventsByMetric[metricName];
+        if (!eventsForMetric) {
+            continue;
+        }
+        // we take the relation from the first event, that posesses one, in order to create buckets from it, if needed
+        const relation = eventsForMetric.find((event) => event.relation)?.relation;
+
+        const bucketCreatorFunction = bucketCreatorDefs[bucketCreator].function;
+        const bucketAggregatorFunction = aggregators[bucketAggregator].function;
+
+        const aggregatorFunction = aggregators[aggregator].function;
+
+        if (!bucketCreatorFunction || !bucketAggregatorFunction || !aggregatorFunction) {
+            logger.error(
+                `No bucket creator or aggregator function found for ${bucketCreator}, ${aggregator} or ${bucketAggregator} during the evaluation of achievement`
+            );
+            return;
+        }
+
+        let bucketContext: AchievementContextType;
+        if (relation) {
+            bucketContext = await getBucketContext(relation);
+        }
+
+        const buckets = bucketCreatorFunction({ recordValue: recordValue, context: bucketContext });
+
+        const bucketEvents = createBucketEvents(eventsForMetric, buckets);
+        const bucketAggr = bucketEvents.map((bucketEvent) => bucketAggregatorFunction(bucketEvent.events.map((event) => event.value)));
+
+        const value = aggregatorFunction(bucketAggr);
+        resultObject[key] = value;
+    }
+    // TODO: return true if the condition is empty (eg. a student finishes a course and automatically receives an achievement)
+    const evaluate = swan.parse(condition);
+    const value: boolean = await evaluate(resultObject);
+
+    return {
+        conditionIsMet: value,
+        resultObject,
+    };
+}
+
+export function createBucketEvents(events: Achievement_event[], bucketConfig: BucketConfig): BucketEvents[] {
+    switch (bucketConfig.bucketKind) {
+        case 'default':
+            return createDefaultBuckets(events, bucketConfig);
+        case 'time':
+            return createTimeBuckets(events, bucketConfig);
+    }
+}
+
+const createDefaultBuckets = (events: Achievement_event[], bucketConfig: BucketConfig): BucketEvents[] => {
+    return events.map((event) => ({
+        kind: 'default',
+        events: [event],
+    }));
+};
+
+const createTimeBuckets = (events: Achievement_event[], bucketConfig: BucketConfig): BucketEvents[] => {
+    const { buckets } = bucketConfig;
+    const bucketsWithEvents: BucketEvents[] = buckets.map((bucket) => {
+        // values will be sorted in a desc order
+        const filteredEvents = events.filter((event) => event.createdAt >= bucket.startTime && event.createdAt <= bucket.endTime);
+
+        return {
+            kind: bucket.kind,
+            startTime: bucket.startTime,
+            endTime: bucket.endTime,
+            events: filteredEvents,
+        };
+    });
+    return bucketsWithEvents;
+};