volleyballsimtypes 0.0.491 → 0.0.492

package/dist/esm/src/data/models/event-result.js

@@ -0,0 +1,44 @@
+import { DataTypes, Model } from 'sequelize';
+export class EventResultModel extends Model {
+    static initModel(sequelize) {
+        return EventResultModel.init({
+            event_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: { model: 'Event', key: 'event_id' }
+            },
+            team_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: { model: 'Team', key: 'team_id' }
+            },
+            position: {
+                type: DataTypes.INTEGER,
+                allowNull: true
+            },
+            entrants: {
+                type: DataTypes.INTEGER,
+                allowNull: false
+            },
+            key: {
+                type: DataTypes.TEXT,
+                allowNull: false
+            },
+            ended_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            }
+        }, {
+            sequelize,
+            tableName: 'EventResult',
+            schema: 'public',
+            timestamps: false,
+            indexes: [
+                { name: 'EventResult_pk', unique: true, fields: [{ name: 'event_id' }, { name: 'team_id' }] },
+                { name: 'EventResult_team_id_idx', fields: [{ name: 'team_id' }] }
+            ]
+        });
+    }
+}

package/dist/esm/src/data/models/event-squad.d.ts

@@ -0,0 +1,30 @@
+import * as Sequelize from 'sequelize';
+import { Model, Optional } from 'sequelize';
+import { EventId, EventModel, TeamAttributes, TeamId, TeamModel } from '.';
+export interface EventSquadAttributes {
+    event_id: string;
+    user_id: string;
+    /** The throwaway Team (active = false) holding the drafted players. Deleted at purge. */
+    team_id: string;
+    complete: boolean;
+    drafted_at: Date | null;
+    team?: TeamAttributes;
+}
+export type EventSquadPk = 'event_id' | 'user_id';
+export type EventSquadId = EventSquadModel[EventSquadPk];
+export type EventSquadOptionalAttributes = 'complete' | 'drafted_at';
+export type EventSquadCreationAttributes = Optional<EventSquadAttributes, EventSquadOptionalAttributes>;
+export declare class EventSquadModel extends Model<EventSquadAttributes, EventSquadCreationAttributes> implements EventSquadAttributes {
+    event_id: string;
+    user_id: string;
+    team_id: string;
+    complete: boolean;
+    drafted_at: Date | null;
+    Event: EventModel;
+    getEvent: Sequelize.BelongsToGetAssociationMixin<EventModel>;
+    setEvent: Sequelize.BelongsToSetAssociationMixin<EventModel, EventId>;
+    team: TeamModel;
+    getTeam: Sequelize.BelongsToGetAssociationMixin<TeamModel>;
+    setTeam: Sequelize.BelongsToSetAssociationMixin<TeamModel, TeamId>;
+    static initModel(sequelize: Sequelize.Sequelize): typeof EventSquadModel;
+}

package/dist/esm/src/data/models/event-squad.js

@@ -0,0 +1,42 @@
+import { DataTypes, Model } from 'sequelize';
+export class EventSquadModel extends Model {
+    static initModel(sequelize) {
+        return EventSquadModel.init({
+            event_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: { model: 'Event', key: 'event_id' }
+            },
+            user_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                references: { model: 'AuthUser', key: 'user_id' }
+            },
+            team_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                references: { model: 'Team', key: 'team_id' }
+            },
+            complete: {
+                type: DataTypes.BOOLEAN,
+                allowNull: false,
+                defaultValue: false
+            },
+            drafted_at: {
+                type: DataTypes.DATE,
+                allowNull: true
+            }
+        }, {
+            sequelize,
+            tableName: 'EventSquad',
+            schema: 'public',
+            timestamps: false,
+            indexes: [
+                { name: 'EventSquad_pk', unique: true, fields: [{ name: 'event_id' }, { name: 'user_id' }] },
+                { name: 'EventSquad_team_id_idx', fields: [{ name: 'team_id' }] }
+            ]
+        });
+    }
+}

package/dist/esm/src/data/models/event.d.ts

@@ -0,0 +1,51 @@
+import * as Sequelize from 'sequelize';
+import { Model, Optional } from 'sequelize';
+import type { EventFormat, EventKey, EventStatus } from '../../service/competition/event-schedule';
+import { EventCompetitionAttributes, EventCompetitionModel, EventSquadAttributes, EventSquadModel } from '.';
+export interface EventAttributes {
+    event_id: string;
+    key: EventKey;
+    format: EventFormat;
+    /** The rarity every player in an entrant's lineup must be. */
+    restriction: string;
+    status: EventStatus;
+    registration_opens_at: Date;
+    registration_closes_at: Date;
+    starts_at: Date;
+    final_starts_at: Date;
+    ends_at: Date;
+    purge_at: Date;
+    /** Set when the event's data was deleted; null while it still has competitions and matches. */
+    purged_at: Date | null;
+    /**
+     * Which of this event's notifications have already gone out, keyed by notification type. The tick runs every
+     * ~60 seconds, so without a marker every phase transition would re-send on every pass.
+     */
+    notified: Record<string, boolean>;
+    EventCompetitions?: EventCompetitionAttributes[];
+    EventSquads?: EventSquadAttributes[];
+}
+export type EventPk = 'event_id';
+export type EventId = EventModel[EventPk];
+export type EventOptionalAttributes = 'event_id' | 'purged_at' | 'notified';
+export type EventCreationAttributes = Optional<EventAttributes, EventOptionalAttributes>;
+export declare class EventModel extends Model<EventAttributes, EventCreationAttributes> implements EventAttributes {
+    event_id: string;
+    key: EventKey;
+    format: EventFormat;
+    restriction: string;
+    status: EventStatus;
+    registration_opens_at: Date;
+    registration_closes_at: Date;
+    starts_at: Date;
+    final_starts_at: Date;
+    ends_at: Date;
+    purge_at: Date;
+    purged_at: Date | null;
+    notified: Record<string, boolean>;
+    EventCompetitions: EventCompetitionModel[];
+    getEventCompetitions: Sequelize.HasManyGetAssociationsMixin<EventCompetitionModel>;
+    EventSquads: EventSquadModel[];
+    getEventSquads: Sequelize.HasManyGetAssociationsMixin<EventSquadModel>;
+    static initModel(sequelize: Sequelize.Sequelize): typeof EventModel;
+}

package/dist/esm/src/data/models/event.js

@@ -0,0 +1,78 @@
+import { DataTypes, Model } from 'sequelize';
+export class EventModel extends Model {
+    static initModel(sequelize) {
+        return EventModel.init({
+            event_id: {
+                type: DataTypes.UUID,
+                allowNull: false,
+                primaryKey: true,
+                defaultValue: DataTypes.UUIDV4
+            },
+            key: {
+                type: DataTypes.TEXT,
+                allowNull: false
+            },
+            format: {
+                type: DataTypes.TEXT,
+                allowNull: false
+            },
+            restriction: {
+                type: DataTypes.TEXT,
+                allowNull: false
+            },
+            status: {
+                type: DataTypes.TEXT,
+                allowNull: false
+            },
+            registration_opens_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            registration_closes_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            starts_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            final_starts_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            ends_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            purge_at: {
+                type: DataTypes.DATE,
+                allowNull: false
+            },
+            purged_at: {
+                type: DataTypes.DATE,
+                allowNull: true
+            },
+            notified: {
+                type: DataTypes.JSONB,
+                allowNull: false,
+                defaultValue: {}
+            }
+        }, {
+            sequelize,
+            tableName: 'Event',
+            schema: 'public',
+            timestamps: false,
+            indexes: [
+                {
+                    name: 'Event_pk',
+                    unique: true,
+                    fields: [{ name: 'event_id' }]
+                },
+                {
+                    name: 'Event_starts_at_idx',
+                    fields: [{ name: 'starts_at' }]
+                }
+            ]
+        });
+    }
+}

package/dist/esm/src/data/models/index.d.ts

@@ -38,6 +38,13 @@ export * from './team';
 export * from './team-replacement';
 export * from './tactics';
 export * from './lineup-preset';
+export * from './event';
+export * from './event-competition';
+export * from './event-bot-team';
+export * from './event-squad';
+export * from './event-pack';
+export * from './event-pack-player';
+export * from './event-result';
 export * from './match-preset';
 export * from './user-currency';
 export * from './user-player-progress';

package/dist/esm/src/data/models/index.js

@@ -38,6 +38,13 @@ export * from './team';
 export * from './team-replacement';
 export * from './tactics';
 export * from './lineup-preset';
+export * from './event';
+export * from './event-competition';
+export * from './event-bot-team';
+export * from './event-squad';
+export * from './event-pack';
+export * from './event-pack-player';
+export * from './event-result';
 export * from './match-preset';
 export * from './user-currency';
 export * from './user-player-progress';

package/dist/esm/src/data/models/lineup-preset.d.ts

@@ -9,10 +9,11 @@ export interface LineupPresetAttributes {
     is_active: boolean;
     order_index: number;
     config: ApiTactics;
+    event_id: string | null;
 }
 export type LineupPresetPk = 'preset_id';
 export type LineupPresetId = LineupPresetModel[LineupPresetPk];
-export type LineupPresetOptionalAttributes = 'preset_id' | 'is_active';
+export type LineupPresetOptionalAttributes = 'preset_id' | 'is_active' | 'event_id';
 export type LineupPresetCreationAttributes = Optional<LineupPresetAttributes, LineupPresetOptionalAttributes>;
 export declare class LineupPresetModel extends Model<LineupPresetAttributes, LineupPresetCreationAttributes> implements LineupPresetAttributes {
     preset_id: string;
@@ -21,6 +22,7 @@ export declare class LineupPresetModel extends Model<LineupPresetAttributes, Lin
     is_active: boolean;
     order_index: number;
     config: ApiTactics;
+    event_id: string | null;
     team: TeamModel;
     getTeam: Sequelize.BelongsToGetAssociationMixin<TeamModel>;
     setTeam: Sequelize.BelongsToSetAssociationMixin<TeamModel, TeamId>;

package/dist/esm/src/data/models/lineup-preset.js

@@ -1,3 +1,4 @@
+import * as Sequelize from 'sequelize';
 import { DataTypes, Model } from 'sequelize';
 export class LineupPresetModel extends Model {
     static initModel(sequelize) {
@@ -32,6 +33,15 @@ export class LineupPresetModel extends Model {
             config: {
                 type: DataTypes.JSONB,
                 allowNull: false
+            },
+            event_id: {
+                type: DataTypes.UUID,
+                allowNull: true,
+                defaultValue: null,
+                references: {
+                    model: 'Event',
+                    key: 'event_id'
+                }
             }
         }, {
             sequelize,
@@ -60,6 +70,16 @@ export class LineupPresetModel extends Model {
                         { name: 'team_id' }
                     ],
                     where: { is_active: true }
+                },
+                {
+                    // At most one event lineup per team per event, so the save endpoint can upsert safely.
+                    name: 'LineupPreset_one_per_team_event',
+                    unique: true,
+                    fields: [
+                        { name: 'team_id' },
+                        { name: 'event_id' }
+                    ],
+                    where: { event_id: { [Sequelize.Op.ne]: null } }
                 }
             ]
         });

package/dist/esm/src/index.d.ts

@@ -1,3 +1,4 @@
 export * from './service';
 export * from './data';
 export * from './stat-config';
+export { collectTacticsPlayerIds } from './api/tactics-player-refs';

package/dist/esm/src/index.js

@@ -1,3 +1,7 @@
 export * from './service';
 export * from './data';
 export * from './stat-config';
+// Named rather than `export * from './api'`: the api module re-declares Tactics/Player/Team/Match as DTO
+// shapes, which would collide with the service classes of the same name at the root. Consumers that want the
+// DTO types import them from the `volleyballsimtypes/api` subpath.
+export { collectTacticsPlayerIds } from './api/tactics-player-refs';

package/dist/esm/src/service/competition/event-draft.d.ts

@@ -0,0 +1,46 @@
+import { Country } from '../country';
+import { Player, Rarity, Role } from '../player';
+/** A pack targets one role, or ANY for the single free pick at the end. */
+export type DraftRole = Role | 'ANY';
+/** How many players an opened pack offers. */
+export declare const PACK_SIZE = 4;
+/**
+ * The pack sequence, in the order they are opened. One pick each, so this is also the squad: 2 setters,
+ * 4 outsides, 3 middles, 2 opposites, 2 liberos, plus one free pick, for a squad of 14 like every other team.
+ *
+ * Role-targeted rather than free choice on purpose: it makes a positionally valid squad impossible to get
+ * wrong, so nobody drafts six liberos and then cannot field a legal lineup.
+ */
+export declare const DRAFT_PLAN: readonly DraftRole[];
+/** The size of a drafted squad: one pick per pack. */
+export declare const DRAFT_SQUAD_SIZE: number;
+/**
+ * How far a pack's players may sit from the median for their rarity, as a fraction of the role score.
+ *
+ * The whole point of a generated draft is that the material is comparable: without this, one entrant opens a
+ * pack of duds while another opens a pack of stars and the event is decided before a ball is served. A player
+ * whose role score falls outside the band is rerolled.
+ */
+export declare const PACK_QUALITY_TOLERANCE = 0.08;
+export interface PackQualityBand {
+    readonly role: Role;
+    readonly min: number;
+    readonly max: number;
+}
+/**
+ * The in-band range for a role at a rarity, measured from a sample of freshly generated players rather than
+ * from hardcoded numbers, so it tracks the generator instead of drifting away from it whenever stats are
+ * retuned. Deterministic enough in aggregate: the sample is large and the band is a fraction of its median.
+ */
+export declare function packQualityBand(country: Country, rarity: Rarity, role: Role, sampleSize?: number): PackQualityBand;
+/**
+ * The players a pack offers: `PACK_SIZE` of the pack's role at the event's rarity, every one of them inside
+ * the fairness band.
+ *
+ * `pickRole` decides what an ANY pack rolls; it is passed in rather than chosen here so the caller controls the
+ * randomness (and a test can make it deterministic).
+ */
+export declare function generatePack(country: Country, rarity: Rarity, packRole: DraftRole, band: (role: Role) => PackQualityBand, pickRole: (roles: readonly Role[]) => Role): Player[];
+/** The role of the pack at `index`, or undefined once the draft is complete. */
+export declare function draftPackRole(index: number): DraftRole | undefined;
+export declare function isDraftComplete(picks: number): boolean;

package/dist/esm/src/service/competition/event-draft.js

@@ -0,0 +1,78 @@
+import { PlayerGenerator, RoleEnum, calculateRoleScore } from '../player';
+/** How many players an opened pack offers. */
+export const PACK_SIZE = 4;
+/**
+ * The pack sequence, in the order they are opened. One pick each, so this is also the squad: 2 setters,
+ * 4 outsides, 3 middles, 2 opposites, 2 liberos, plus one free pick, for a squad of 14 like every other team.
+ *
+ * Role-targeted rather than free choice on purpose: it makes a positionally valid squad impossible to get
+ * wrong, so nobody drafts six liberos and then cannot field a legal lineup.
+ */
+export const DRAFT_PLAN = [
+    RoleEnum.SETTER, RoleEnum.SETTER,
+    RoleEnum.OUTSIDE_HITTER, RoleEnum.OUTSIDE_HITTER, RoleEnum.OUTSIDE_HITTER, RoleEnum.OUTSIDE_HITTER,
+    RoleEnum.MIDDLE_BLOCKER, RoleEnum.MIDDLE_BLOCKER, RoleEnum.MIDDLE_BLOCKER,
+    RoleEnum.OPPOSITE_HITTER, RoleEnum.OPPOSITE_HITTER,
+    RoleEnum.LIBERO, RoleEnum.LIBERO,
+    'ANY'
+];
+/** The size of a drafted squad: one pick per pack. */
+export const DRAFT_SQUAD_SIZE = DRAFT_PLAN.length;
+/** The role a free pack rolls its choices at, so an ANY pack still offers a coherent set. */
+const ANY_PACK_ROLES = [
+    RoleEnum.SETTER, RoleEnum.OUTSIDE_HITTER, RoleEnum.MIDDLE_BLOCKER, RoleEnum.OPPOSITE_HITTER, RoleEnum.LIBERO
+];
+/**
+ * How far a pack's players may sit from the median for their rarity, as a fraction of the role score.
+ *
+ * The whole point of a generated draft is that the material is comparable: without this, one entrant opens a
+ * pack of duds while another opens a pack of stars and the event is decided before a ball is served. A player
+ * whose role score falls outside the band is rerolled.
+ */
+export const PACK_QUALITY_TOLERANCE = 0.08;
+/** Give up rerolling after this many attempts and take what we have, so generation can never spin forever. */
+const MAX_REROLLS = 40;
+/**
+ * The in-band range for a role at a rarity, measured from a sample of freshly generated players rather than
+ * from hardcoded numbers, so it tracks the generator instead of drifting away from it whenever stats are
+ * retuned. Deterministic enough in aggregate: the sample is large and the band is a fraction of its median.
+ */
+export function packQualityBand(country, rarity, role, sampleSize = 60) {
+    const scores = Array.from({ length: sampleSize }, () => calculateRoleScore(PlayerGenerator.generatePlayer(country, rarity, role, false, 1).stats, role)).sort((a, b) => a - b);
+    const median = scores[Math.floor(scores.length / 2)];
+    return {
+        role,
+        min: median * (1 - PACK_QUALITY_TOLERANCE),
+        max: median * (1 + PACK_QUALITY_TOLERANCE)
+    };
+}
+/**
+ * The players a pack offers: `PACK_SIZE` of the pack's role at the event's rarity, every one of them inside
+ * the fairness band.
+ *
+ * `pickRole` decides what an ANY pack rolls; it is passed in rather than chosen here so the caller controls the
+ * randomness (and a test can make it deterministic).
+ */
+export function generatePack(country, rarity, packRole, band, pickRole) {
+    const role = packRole === 'ANY' ? pickRole(ANY_PACK_ROLES) : packRole;
+    const { min, max } = band(role);
+    const players = [];
+    for (let i = 0; i < PACK_SIZE; i++) {
+        let player = PlayerGenerator.generatePlayer(country, rarity, role, false, 1);
+        for (let attempt = 0; attempt < MAX_REROLLS; attempt++) {
+            const score = calculateRoleScore(player.stats, role);
+            if (score >= min && score <= max)
+                break;
+            player = PlayerGenerator.generatePlayer(country, rarity, role, false, 1);
+        }
+        players.push(player);
+    }
+    return players;
+}
+/** The role of the pack at `index`, or undefined once the draft is complete. */
+export function draftPackRole(index) {
+    return DRAFT_PLAN[index];
+}
+export function isDraftComplete(picks) {
+    return picks >= DRAFT_SQUAD_SIZE;
+}

package/dist/esm/src/service/competition/event-draft.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/esm/src/service/competition/event-draft.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect } from '@jest/globals';
+import { DRAFT_PLAN, DRAFT_SQUAD_SIZE, PACK_SIZE, draftPackRole, generatePack, isDraftComplete, packQualityBand } from './event-draft';
+import { RarityEnum, RoleEnum, calculateRoleScore } from '../player';
+import { makeCountry } from '../test-helpers';
+const COUNTRY = makeCountry();
+describe('DRAFT_PLAN', () => {
+    it('drafts a full 14-player squad, one pick per pack', () => {
+        expect(DRAFT_SQUAD_SIZE).toBe(14);
+        expect(DRAFT_PLAN).toHaveLength(14);
+    });
+    it('guarantees a positionally valid squad', () => {
+        const counts = DRAFT_PLAN.reduce((acc, role) => {
+            acc[role] = (acc[role] ?? 0) + 1;
+            return acc;
+        }, {});
+        expect(counts[RoleEnum.SETTER]).toBe(2);
+        expect(counts[RoleEnum.OUTSIDE_HITTER]).toBe(4);
+        expect(counts[RoleEnum.MIDDLE_BLOCKER]).toBe(3);
+        expect(counts[RoleEnum.OPPOSITE_HITTER]).toBe(2);
+        expect(counts[RoleEnum.LIBERO]).toBe(2);
+        expect(counts.ANY).toBe(1);
+        // Enough for a legal starting six plus a libero, whatever the free pack is spent on: a 5-1 needs a setter,
+        // two middles, two outsides and an opposite on court, and a libero off it.
+        expect(counts[RoleEnum.SETTER]).toBeGreaterThanOrEqual(1);
+        expect(counts[RoleEnum.MIDDLE_BLOCKER]).toBeGreaterThanOrEqual(2);
+        expect(counts[RoleEnum.OUTSIDE_HITTER]).toBeGreaterThanOrEqual(2);
+        expect(counts[RoleEnum.OPPOSITE_HITTER]).toBeGreaterThanOrEqual(1);
+        expect(counts[RoleEnum.LIBERO]).toBeGreaterThanOrEqual(1);
+    });
+    it('walks pack by pack and then reports the draft complete', () => {
+        for (let i = 0; i < DRAFT_SQUAD_SIZE; i++) {
+            expect(draftPackRole(i)).toBeDefined();
+            expect(isDraftComplete(i)).toBe(false);
+        }
+        expect(draftPackRole(DRAFT_SQUAD_SIZE)).toBeUndefined();
+        expect(isDraftComplete(DRAFT_SQUAD_SIZE)).toBe(true);
+    });
+});
+describe('generatePack()', () => {
+    const first = (roles) => roles[0];
+    it.each([RarityEnum.COMMON, RarityEnum.RARE, RarityEnum.LEGENDARY])('offers %s players of the pack role, all inside the fairness band', (rarity) => {
+        const role = RoleEnum.OUTSIDE_HITTER;
+        const band = packQualityBand(COUNTRY, rarity, role);
+        const pack = generatePack(COUNTRY, rarity, role, () => band, first);
+        expect(pack).toHaveLength(PACK_SIZE);
+        for (const player of pack) {
+            expect(player.rarity).toBe(rarity);
+            expect(player.roles).toContain(role);
+            const score = calculateRoleScore(player.stats, role);
+            expect(score).toBeGreaterThanOrEqual(band.min);
+            expect(score).toBeLessThanOrEqual(band.max);
+        }
+    });
+    it('keeps two packs of the same role comparable', () => {
+        const role = RoleEnum.MIDDLE_BLOCKER;
+        const band = packQualityBand(COUNTRY, RarityEnum.RARE, role);
+        const score = (p) => calculateRoleScore(p.stats, role);
+        const a = generatePack(COUNTRY, RarityEnum.RARE, role, () => band, first).map(score);
+        const b = generatePack(COUNTRY, RarityEnum.RARE, role, () => band, first).map(score);
+        // The point of the band: the best pack cannot run away from the worst one.
+        const spread = Math.max(...a, ...b) - Math.min(...a, ...b);
+        expect(spread).toBeLessThanOrEqual(band.max - band.min);
+    });
+    it('rolls a free pack at the role it is handed', () => {
+        const band = packQualityBand(COUNTRY, RarityEnum.COMMON, RoleEnum.LIBERO);
+        const pack = generatePack(COUNTRY, RarityEnum.COMMON, 'ANY', () => band, () => RoleEnum.LIBERO);
+        expect(pack).toHaveLength(PACK_SIZE);
+        for (const player of pack)
+            expect(player.roles).toContain(RoleEnum.LIBERO);
+    });
+    it('terminates even when nothing can land in band', () => {
+        const impossible = { role: RoleEnum.SETTER, min: Number.MAX_SAFE_INTEGER, max: Number.MAX_SAFE_INTEGER };
+        const pack = generatePack(COUNTRY, RarityEnum.COMMON, RoleEnum.SETTER, () => impossible, first);
+        // Generation gives up rather than spinning: a full pack is still returned.
+        expect(pack).toHaveLength(PACK_SIZE);
+    });
+});
+describe('packQualityBand()', () => {
+    it('brackets the median of what the generator actually produces', () => {
+        const band = packQualityBand(COUNTRY, RarityEnum.LEGENDARY, RoleEnum.SETTER);
+        expect(band.min).toBeLessThan(band.max);
+        expect(band.min).toBeGreaterThan(0);
+    });
+    it('scales with rarity, so a legendary band sits above a common one', () => {
+        const common = packQualityBand(COUNTRY, RarityEnum.COMMON, RoleEnum.OUTSIDE_HITTER);
+        const legendary = packQualityBand(COUNTRY, RarityEnum.LEGENDARY, RoleEnum.OUTSIDE_HITTER);
+        expect(legendary.min).toBeGreaterThan(common.max);
+    });
+});

package/dist/esm/src/service/competition/event-rewards.d.ts

@@ -0,0 +1,26 @@
+export type EventRewardBand = 'PARTICIPATION' | 'TOP_20' | 'TOP_10' | 'TOP_5' | 'TOP_3' | 'TOP_1';
+export interface EventRewardRow {
+    readonly band: EventRewardBand;
+    /** Best final position that earns this row; PARTICIPATION has none. */
+    readonly maxPosition: number | null;
+    /** Event Packs awarded by this row alone. */
+    readonly packs: number;
+    /** Coins awarded by this row alone. */
+    readonly coins: number;
+}
+/**
+ * Best band first. A team earns its own row and every row BELOW it, which is what "cumulative" means: first
+ * place collects all six.
+ */
+export declare const EVENT_REWARDS: readonly EventRewardRow[];
+/**
+ * The band a finish falls into. `position` is the place in the FINAL table; null means the team never reached
+ * the final, and so does any position past the last banded row, which both count as taking part.
+ */
+export declare function eventRewardBandFor(position: number | null): EventRewardBand;
+export interface EventPayout {
+    readonly packs: number;
+    readonly coins: number;
+}
+/** Everything a finish earns, adding its own row to every row beneath it. */
+export declare function eventPayoutFor(position: number | null): EventPayout;

package/dist/esm/src/service/competition/event-rewards.js

@@ -0,0 +1,44 @@
+// What an event pays out, and the band a team's finish falls into. Owner-defined 2026-07-23.
+//
+// One source of truth for three consumers: the simulator grants from it, the About view lists it, and the
+// accolades page names the band. Rewards are CUMULATIVE, so a team collects every row from Participation down
+// to its own placement.
+/**
+ * Best band first. A team earns its own row and every row BELOW it, which is what "cumulative" means: first
+ * place collects all six.
+ */
+export const EVENT_REWARDS = [
+    { band: 'TOP_1', maxPosition: 1, packs: 1, coins: 0 },
+    { band: 'TOP_3', maxPosition: 3, packs: 0, coins: 500 },
+    { band: 'TOP_5', maxPosition: 5, packs: 0, coins: 1000 },
+    { band: 'TOP_10', maxPosition: 10, packs: 1, coins: 0 },
+    { band: 'TOP_20', maxPosition: 20, packs: 0, coins: 1000 },
+    { band: 'PARTICIPATION', maxPosition: null, packs: 1, coins: 1000 }
+];
+/**
+ * The band a finish falls into. `position` is the place in the FINAL table; null means the team never reached
+ * the final, and so does any position past the last banded row, which both count as taking part.
+ */
+export function eventRewardBandFor(position) {
+    if (position == null)
+        return 'PARTICIPATION';
+    // Rows are ordered best-first, so the FIRST row the position satisfies is the narrowest band it earns.
+    // Scanning to the end instead would always land on the widest, handing first place a "top 20" badge.
+    for (const row of EVENT_REWARDS) {
+        if (row.maxPosition != null && position <= row.maxPosition)
+            return row.band;
+    }
+    return 'PARTICIPATION';
+}
+/** Everything a finish earns, adding its own row to every row beneath it. */
+export function eventPayoutFor(position) {
+    const band = eventRewardBandFor(position);
+    const from = EVENT_REWARDS.findIndex(row => row.band === band);
+    let packs = 0;
+    let coins = 0;
+    for (const row of EVENT_REWARDS.slice(from)) {
+        packs += row.packs;
+        coins += row.coins;
+    }
+    return { packs, coins };
+}

package/dist/esm/src/service/competition/event-rewards.test.d.ts

@@ -0,0 +1 @@
+export {};