ballrush-core 0.13.0 → 1.3.2

package/dist/domain/event.d.ts

@@ -14,6 +14,7 @@ export declare class Event {
     private gameMode;
     private reportMessageId?;
     private status;
+    private excludeFromStats;
     private constructor();
     static create(params: {
         eventId: number;
@@ -30,6 +31,7 @@ export declare class Event {
         isRatingApplied?: boolean;
         status?: EventStatus;
         gameMode?: GameMode;
+        excludeFromStats?: boolean;
     }): Event;
     getEventId(): number;
     getGroupId(): number;
@@ -44,6 +46,7 @@ export declare class Event {
     getCreatedBy(): number;
     getStatus(): EventStatus;
     getIsRatingApplied(): boolean;
+    getExcludeFromStats(): boolean;
     getGameMode(): GameMode;
     canChangeGameMode(): boolean;
     setGameMode(mode: GameMode): void;
@@ -54,6 +57,7 @@ export declare class Event {
     replaceTeams(teams: Team[]): void;
     replaceMatches(matches: Match[]): void;
     setRatingApplied(mark: boolean): void;
+    setExcludeFromStats(value: boolean): void;
     setStatus(status: EventStatus): void;
     isActive(): boolean;
     isInProgress(): boolean;

package/dist/domain/event.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.Event = void 0;
 const types_1 = require("../types");
 class Event {
-    constructor(eventId, groupId, messageId, templateId, date, participants, teams, matches, createdBy, isRatingApplied, seasonId, gameMode, reportMessageId, status = "active") {
+    constructor(eventId, groupId, messageId, templateId, date, participants, teams, matches, createdBy, isRatingApplied, seasonId, gameMode, reportMessageId, status = "active", excludeFromStats = false) {
         this.eventId = eventId;
         this.groupId = groupId;
         this.messageId = messageId;
@@ -18,12 +18,13 @@ class Event {
         this.gameMode = gameMode;
         this.reportMessageId = reportMessageId;
         this.status = status;
+        this.excludeFromStats = excludeFromStats;
     }
     static create(params) {
         if (!params.seasonId) {
             throw new Error("Event must have a season ID");
         }
-        return new Event(params.eventId, params.groupId, params.messageId ?? 0, params.templateId, params.date, params.participants ?? [], params.teams ?? [], params.matches ?? [], params.createdBy, params.isRatingApplied ?? false, params.seasonId, params.gameMode ?? types_1.DEFAULT_GAME_MODE, params.reportMessageId, params.status ?? "active");
+        return new Event(params.eventId, params.groupId, params.messageId ?? 0, params.templateId, params.date, params.participants ?? [], params.teams ?? [], params.matches ?? [], params.createdBy, params.isRatingApplied ?? false, params.seasonId, params.gameMode ?? types_1.DEFAULT_GAME_MODE, params.reportMessageId, params.status ?? "active", params.excludeFromStats ?? false);
     }
     getEventId() { return this.eventId; }
     getGroupId() { return this.groupId; }
@@ -38,6 +39,7 @@ class Event {
     getCreatedBy() { return this.createdBy; }
     getStatus() { return this.status; }
     getIsRatingApplied() { return this.isRatingApplied; }
+    getExcludeFromStats() { return this.excludeFromStats; }
     getGameMode() { return this.gameMode; }
     canChangeGameMode() { return this.matches.length === 0; }
     setGameMode(mode) {
@@ -67,6 +69,9 @@ class Event {
     setRatingApplied(mark) {
         this.isRatingApplied = mark;
     }
+    setExcludeFromStats(value) {
+        this.excludeFromStats = value;
+    }
     setStatus(status) {
         this.status = status;
     }

package/dist/mongo/schemas/event.schema.d.ts

@@ -13,6 +13,7 @@ export interface EventDoc {
     seasonId: string;
     status: EventStatus;
     isRatingApplied: boolean;
+    excludeFromStats?: boolean;
     gameMode: GameMode;
     reportMessageId?: number;
 }

package/dist/mongo/schemas/event.schema.js

@@ -57,6 +57,7 @@ function createEventSchema() {
         teams: { type: [TeamSchema], default: [] },
         matches: { type: [MatchSchema], default: [] },
         isRatingApplied: { type: Boolean },
+        excludeFromStats: { type: Boolean, default: false },
         reportMessageId: { type: Number },
         gameMode: {
             type: String,

package/dist/ports/events.repository.d.ts

@@ -15,6 +15,7 @@ export type EventWrite = {
     isRatingApplied?: boolean;
     reportMessageId?: number;
     gameMode?: GameMode;
+    excludeFromStats?: boolean;
 };
 export interface EventsRepository {
     create(eventData: Event): Promise<Event>;

package/dist/ports/groups.repository.d.ts

@@ -14,10 +14,19 @@ export type GroupWrite = {
     language: LanguageType;
     isPublic: boolean;
 };
+export type GroupFieldsUpdate = Partial<Pick<GroupWrite, "groupName" | "timezone" | "isMessageLast" | "language" | "isPublic">>;
 export interface GroupsRepository {
     create(groupData: Group): Promise<Group>;
     findById(groupId: number): Promise<Group | null>;
     update(groupId: number, updates: Group): Promise<Group | null>;
+    /**
+     * Partial $set update for non-participant scalar fields.
+     * Use this instead of update() whenever you only need to change metadata
+     * (timezone, language, isMessageLast, etc.) — update() rewrites participants
+     * from the in-memory cache and can clobber rating data written by other
+     * processes between cache load and save.
+     */
+    updateFields(groupId: number, fields: GroupFieldsUpdate): Promise<void>;
     findAll(): Promise<Group[]>;
     delete(groupId: number): Promise<void>;
 }

package/dist/repositories/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./mongo/user.repository";
 export * from "./mongo/group.repository";
+export * from "./mongo/group-repo.events";
 export * from "./mongo/event.repository";
 export * from "./mongo/event-template.repository";
 export * from "./mongo/stat-group.repository";

package/dist/repositories/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./mongo/user.repository"), exports);
 __exportStar(require("./mongo/group.repository"), exports);
+__exportStar(require("./mongo/group-repo.events"), exports);
 __exportStar(require("./mongo/event.repository"), exports);
 __exportStar(require("./mongo/event-template.repository"), exports);
 __exportStar(require("./mongo/stat-group.repository"), exports);

package/dist/repositories/mongo/event.mapper.js

@@ -20,6 +20,7 @@ function toDomain(doc) {
         reportMessageId: doc.reportMessageId,
         status: doc.status,
         gameMode: doc.gameMode ?? types_1.DEFAULT_GAME_MODE,
+        excludeFromStats: doc.excludeFromStats ?? false,
     });
 }
 function toDoc(event) {
@@ -38,5 +39,6 @@ function toDoc(event) {
         isRatingApplied: event.getIsRatingApplied(),
         reportMessageId: event.getReportMessageId(),
         gameMode: event.getGameMode(),
+        excludeFromStats: event.getExcludeFromStats(),
     };
 }

package/dist/repositories/mongo/group-repo.events.d.ts

@@ -0,0 +1,42 @@
+import { EventEmitter } from "events";
+export type SuspiciousGroupUpdateReason = "rating_regression" | "history_truncated";
+export interface SuspiciousGroupUpdate {
+    groupId: number;
+    reason: SuspiciousGroupUpdateReason;
+    /** Sum of all rating points across all participants — before this update */
+    sumBefore: number;
+    /** Sum of all rating points across all participants — after this update would be applied */
+    sumAfter: number;
+    /** sumAfter - sumBefore (negative = regression) */
+    delta: number;
+    /** Total ratingHistory entries in the document — before */
+    historyCountBefore: number;
+    /** Total ratingHistory entries — after */
+    historyCountAfter: number;
+    /** Top 10 individual losses (userId, delta), sorted by largest loss first */
+    topLosses: Array<{
+        userId: number;
+        deltaSum: number;
+        deltaHistoryLen: number;
+    }>;
+    /** First N lines of the call stack pointing at the caller */
+    callerStack: string;
+    /** true if the repository refused to apply the write because of regression guard */
+    refused: boolean;
+    /** ISO timestamp of when the event fired */
+    timestamp: string;
+}
+declare class GroupRepoEvents extends EventEmitter {
+    emitSuspicious(ev: SuspiciousGroupUpdate): void;
+}
+/**
+ * Singleton emitter the MongoGroupsRepository fires events on whenever it
+ * detects something unusual (e.g. a write that would drop total rating
+ * significantly, or shorten history). Wire a listener in the app's bootstrap
+ * to forward these to Telegram, Slack, etc.
+ *
+ *   import { groupRepoEvents } from "ballrush-core/repositories";
+ *   groupRepoEvents.on("suspicious", (ev) => { ... });
+ */
+export declare const groupRepoEvents: GroupRepoEvents;
+export {};

package/dist/repositories/mongo/group-repo.events.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.groupRepoEvents = void 0;
+const events_1 = require("events");
+class GroupRepoEvents extends events_1.EventEmitter {
+    emitSuspicious(ev) {
+        this.emit("suspicious", ev);
+    }
+}
+/**
+ * Singleton emitter the MongoGroupsRepository fires events on whenever it
+ * detects something unusual (e.g. a write that would drop total rating
+ * significantly, or shorten history). Wire a listener in the app's bootstrap
+ * to forward these to Telegram, Slack, etc.
+ *
+ *   import { groupRepoEvents } from "ballrush-core/repositories";
+ *   groupRepoEvents.on("suspicious", (ev) => { ... });
+ */
+exports.groupRepoEvents = new GroupRepoEvents();

package/dist/repositories/mongo/group.repository.d.ts

@@ -1,5 +1,5 @@
 import type { Model } from "mongoose";
-import type { GroupsRepository } from "../../ports/groups.repository";
+import type { GroupsRepository, GroupFieldsUpdate } from "../../ports/groups.repository";
 import type { GroupDoc } from "../../mongo";
 import { Group } from "../../domain/group";
 export declare class MongoGroupsRepository implements GroupsRepository {
@@ -8,6 +8,7 @@ export declare class MongoGroupsRepository implements GroupsRepository {
     create(group: Group): Promise<Group>;
     findById(groupId: number): Promise<Group | null>;
     update(groupId: number, updates: Group): Promise<Group | null>;
+    updateFields(groupId: number, fields: GroupFieldsUpdate): Promise<void>;
     findAll(): Promise<Group[]>;
     delete(groupId: number): Promise<void>;
 }

package/dist/repositories/mongo/group.repository.js

@@ -3,6 +3,71 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MongoGroupsRepository = void 0;
 const group_mapper_1 = require("./group.mapper");
 const errors_1 = require("../../errors");
+const group_repo_events_1 = require("./group-repo.events");
+// Regression guard thresholds. Tunable via env:
+//   GROUPS_REGRESSION_GUARD=off — disable refusal (still logs + emits event)
+//   GROUPS_REGRESSION_ABS_DROP — absolute sum drop that counts as suspicious (default 50)
+//   GROUPS_REGRESSION_PCT_DROP — fractional drop (0..1) that counts as suspicious (default 0.05)
+function getRegressionGuardConfig() {
+    const enabled = (process.env.GROUPS_REGRESSION_GUARD ?? "on") !== "off";
+    const absDrop = Number(process.env.GROUPS_REGRESSION_ABS_DROP ?? 50);
+    const pctDrop = Number(process.env.GROUPS_REGRESSION_PCT_DROP ?? 0.05);
+    return { enabled, absDrop, pctDrop };
+}
+function sumOfHistory(participants) {
+    if (!participants)
+        return 0;
+    let total = 0;
+    for (const p of participants) {
+        for (const r of p.ratingHistory ?? [])
+            total += r.value ?? 0;
+    }
+    return total;
+}
+function countHistory(participants) {
+    if (!participants)
+        return 0;
+    let total = 0;
+    for (const p of participants)
+        total += (p.ratingHistory ?? []).length;
+    return total;
+}
+function computeTopLosses(before, after, limit = 10) {
+    const beforeBy = new Map();
+    for (const p of before)
+        beforeBy.set(p.userId, p);
+    const losses = [];
+    for (const a of after) {
+        const b = beforeBy.get(a.userId);
+        if (!b)
+            continue;
+        const bSum = (b.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+        const aSum = (a.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+        const deltaSum = aSum - bSum;
+        const deltaHistoryLen = (a.ratingHistory ?? []).length - (b.ratingHistory ?? []).length;
+        if (deltaSum < 0 || deltaHistoryLen < 0) {
+            losses.push({ userId: a.userId, deltaSum: Math.round(deltaSum * 100) / 100, deltaHistoryLen });
+        }
+    }
+    // also detect participants that disappeared entirely
+    const afterIds = new Set(after.map(p => p.userId));
+    for (const b of before) {
+        if (!afterIds.has(b.userId)) {
+            const bSum = (b.ratingHistory ?? []).reduce((s, r) => s + (r.value ?? 0), 0);
+            losses.push({
+                userId: b.userId,
+                deltaSum: Math.round(-bSum * 100) / 100,
+                deltaHistoryLen: -(b.ratingHistory ?? []).length,
+            });
+        }
+    }
+    losses.sort((x, y) => x.deltaSum - y.deltaSum);
+    return losses.slice(0, limit);
+}
+function shortStack(depth = 8) {
+    const raw = new Error().stack ?? "";
+    return raw.split("\n").slice(2, 2 + depth).join("\n");
+}
 class MongoGroupsRepository {
     constructor(GroupModel) {
         this.GroupModel = GroupModel;
@@ -58,6 +123,59 @@ class MongoGroupsRepository {
                 throw new errors_1.ValidationError('Group', 'updates', updates, 'updates object is required');
             }
             const write = (0, group_mapper_1.toDoc)(updates);
+            // --- Observability: log every full-document write of a group ---
+            // We log enough context to find the culprit after the fact if the
+            // historical Pattaya-style regression ever happens again.
+            const callerStack = shortStack();
+            const sumAfter = sumOfHistory(write.participants);
+            const historyCountAfter = countHistory(write.participants);
+            // Read current state ONCE for regression guard + alert payload.
+            const currentDoc = await this.GroupModel.findOne({ groupId }).lean();
+            const sumBefore = sumOfHistory(currentDoc?.participants ?? []);
+            const historyCountBefore = countHistory(currentDoc?.participants ?? []);
+            const delta = sumAfter - sumBefore;
+            const historyDelta = historyCountAfter - historyCountBefore;
+            console.log(`[GROUPS_UPDATE] groupId=${groupId} participants=${write.participants.length} ` +
+                `sumBefore=${sumBefore.toFixed(2)} sumAfter=${sumAfter.toFixed(2)} delta=${delta.toFixed(2)} ` +
+                `histBefore=${historyCountBefore} histAfter=${historyCountAfter} histDelta=${historyDelta}\n` +
+                `[GROUPS_UPDATE_STACK]\n${callerStack}`);
+            // --- Regression guard ---
+            const guard = getRegressionGuardConfig();
+            const absThreshold = Math.max(guard.absDrop, Math.abs(sumBefore) * guard.pctDrop);
+            const isRegression = currentDoc !== null && (delta < -absThreshold || // big rating drop
+                historyDelta < 0 // history shrank
+            );
+            if (isRegression) {
+                const topLosses = computeTopLosses((currentDoc?.participants ?? []), write.participants);
+                const event = {
+                    groupId,
+                    reason: (delta < -absThreshold ? "rating_regression" : "history_truncated"),
+                    sumBefore: Math.round(sumBefore * 100) / 100,
+                    sumAfter: Math.round(sumAfter * 100) / 100,
+                    delta: Math.round(delta * 100) / 100,
+                    historyCountBefore,
+                    historyCountAfter,
+                    topLosses,
+                    callerStack,
+                    refused: guard.enabled,
+                    timestamp: new Date().toISOString(),
+                };
+                console.error(`[GROUPS_REGRESSION] groupId=${groupId} reason=${event.reason} ` +
+                    `delta=${event.delta} histDelta=${historyDelta} refused=${event.refused}\n` +
+                    `topLosses=${JSON.stringify(event.topLosses)}\n` +
+                    `[GROUPS_REGRESSION_STACK]\n${callerStack}`);
+                // Fire-and-forget event for any listener (e.g. Telegram alerter in the bot).
+                try {
+                    group_repo_events_1.groupRepoEvents.emitSuspicious(event);
+                }
+                catch { /* never fail update because of a listener */ }
+                if (guard.enabled) {
+                    // Refuse the write — return null so callers can detect failure.
+                    // To bypass intentionally (e.g. legit reset by admin), run with:
+                    //   GROUPS_REGRESSION_GUARD=off
+                    return null;
+                }
+            }
             const doc = await this.GroupModel.findOneAndUpdate({ groupId }, { $set: write }, { new: true }).lean();
             return doc ? (0, group_mapper_1.toDomain)(doc) : null;
         }
@@ -68,6 +186,22 @@ class MongoGroupsRepository {
             throw new errors_1.QueryError('update', 'Group', groupId, error);
         }
     }
+    async updateFields(groupId, fields) {
+        try {
+            if (!groupId || groupId === 0) {
+                throw new errors_1.ValidationError('Group', 'groupId', groupId, 'must be a non-zero number');
+            }
+            if (!fields || Object.keys(fields).length === 0)
+                return;
+            await this.GroupModel.updateOne({ groupId }, { $set: fields });
+        }
+        catch (error) {
+            if (error instanceof errors_1.ValidationError) {
+                throw error;
+            }
+            throw new errors_1.QueryError('updateFields', 'Group', groupId, error);
+        }
+    }
     async findAll() {
         try {
             const docs = await this.GroupModel.find().lean();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "ballrush-core",
-    "version": "0.13.0",
+    "version": "1.3.2",
     "private": false,
     "license": "MIT",
     "main": "./dist/index.js",