@glissandoo/lib 1.116.0 → 1.117.0

package/types/payoutRule.ts

@@ -0,0 +1,132 @@
+import { Timestamp } from '@google-cloud/firestore';
+
+/**
+ * Shared types for the payout rules engine.
+ * Rules live at two levels:
+ *  - Group level (templates, can be `pinned` to auto-apply to new events)
+ *  - Event level (snapshot copied from the group when payout is initialized)
+ */
+
+export enum PayoutRuleType {
+	EntityShare = 'entityShare',
+	DefaultExpense = 'defaultExpense',
+	PlayerMultiplier = 'playerMultiplier',
+	PlayerBonus = 'playerBonus',
+	PlayerFixed = 'playerFixed',
+	PlayerExclude = 'playerExclude',
+}
+
+export enum PayoutRuleConditionOperator {
+	Eq = 'eq',
+	Neq = 'neq',
+	Gt = 'gt',
+	Gte = 'gte',
+	Lt = 'lt',
+	Lte = 'lte',
+	In = 'in',
+	Nin = 'nin',
+}
+
+export type PayoutRuleConditionFieldKind = 'mainInstrument' | 'isGuest' | `custom.${string}`;
+
+export type PayoutRuleConditionValue = string | number | boolean | string[] | number[] | null;
+
+export interface PayoutRuleCondition {
+	field: PayoutRuleConditionFieldKind;
+	operator: PayoutRuleConditionOperator;
+	value: PayoutRuleConditionValue;
+}
+
+export enum PayoutRuleEntityShareMode {
+	Fixed = 'fixed',
+	Percentage = 'percentage',
+}
+
+export interface PayoutRuleEntityShareEffect {
+	mode: PayoutRuleEntityShareMode;
+	value: number;
+}
+
+export interface PayoutRuleDefaultExpenseEffect {
+	concept: string;
+	amount: number;
+	/**
+	 * `null` = expense remains general (reduces the shared pot).
+	 * Future: could materialize per-attendee expenses.
+	 */
+	assignTo: null;
+}
+
+export interface PayoutRulePlayerMultiplierEffect {
+	multiplier: number;
+}
+
+export interface PayoutRulePlayerBonusEffect {
+	amount: number;
+}
+
+export interface PayoutRulePlayerFixedEffect {
+	amount: number;
+}
+
+export type PayoutRulePlayerExcludeEffect = Record<string, never>;
+
+export type PayoutRuleEffect =
+	| { type: PayoutRuleType.EntityShare; data: PayoutRuleEntityShareEffect }
+	| { type: PayoutRuleType.DefaultExpense; data: PayoutRuleDefaultExpenseEffect }
+	| { type: PayoutRuleType.PlayerMultiplier; data: PayoutRulePlayerMultiplierEffect }
+	| { type: PayoutRuleType.PlayerBonus; data: PayoutRulePlayerBonusEffect }
+	| { type: PayoutRuleType.PlayerFixed; data: PayoutRulePlayerFixedEffect }
+	| { type: PayoutRuleType.PlayerExclude; data: PayoutRulePlayerExcludeEffect };
+
+/**
+ * Common shape stored in both group templates and event snapshots.
+ */
+export interface PayoutRuleBaseData {
+	name: string;
+	description: string | null;
+	order: number;
+	conditions: PayoutRuleCondition[];
+	effect: PayoutRuleEffect;
+	createdAt: Timestamp;
+	createdBy: string;
+	editedAt: Timestamp | null;
+	editedBy: string | null;
+}
+
+/**
+ * Helper used by the pure rules engine. Holds the minimal data
+ * required to evaluate conditions against a player.
+ */
+export interface PayoutRulePlayerInput {
+	id: string;
+	mainInstrument: string;
+	isGuest: boolean;
+	customFields: Record<string, string | number | boolean | null>;
+}
+
+export interface GroupPayoutRuleEntry {
+	id: string;
+	name: string;
+	order: number;
+	pinned: boolean;
+	conditions: PayoutRuleCondition[];
+	effect: PayoutRuleEffect;
+	createdAt: Timestamp;
+	createdBy: string;
+	editedAt: Timestamp | null;
+	editedBy: string | null;
+}
+
+export interface EventoPayoutRuleEntry {
+	id: string;
+	name: string;
+	order: number;
+	sourceGroupRuleId: string | null;
+	conditions: PayoutRuleCondition[];
+	effect: PayoutRuleEffect;
+	createdAt: Timestamp;
+	createdBy: string;
+	editedAt: Timestamp | null;
+	editedBy: string | null;
+}