@openora/core 0.4.1-canary.49 → 0.4.1-canary.50

package/dist/engagement/chat-commands/service/__tests__/chat-commands.service.test.js

@@ -0,0 +1,888 @@
+import { describe, it, expect, vi } from 'vitest';
+import { mock, makeDrizzle, makeEventBus } from '../../../../testing/mock.js';
+import { ChatCommandsService, CommandDisabledError, InsufficientBalanceError, BelowMinimumError, NoOnlineUsersError, ExceedsLimitError, GiftNotFoundError, GiftAlreadyClaimedError, GiftSelfClaimError, DonateSelfError, ChatPlayerNotFoundError, TooManyRecipientsError, SelfModerationActionError, ChatCommandIdempotencyKeyReuseError, fingerprintCommand, } from '../chat-commands.service.js';
+const ACTOR_ID = '00000000-0000-0000-0000-000000000001';
+const CLAIMER_ID = '00000000-0000-0000-0000-000000000002';
+const ROOM_ID = '00000000-0000-0000-0000-000000000003';
+const MSG_ID = '00000000-0000-0000-0000-000000000004';
+const GIFT_ID = '00000000-0000-0000-0000-000000000005';
+const OTHER_ROOM_ID = '00000000-0000-0000-0000-000000000009';
+const ENABLED_ROW = {
+    key: 'gift',
+    enabled: true,
+    label: 'Gift',
+    description: null,
+    config: null,
+    updatedAt: new Date(),
+};
+const DISABLED_ROW = { ...ENABLED_ROW, enabled: false };
+const SYSTEM_MSG = {
+    id: MSG_ID,
+    roomId: ROOM_ID,
+    actorId: ACTOR_ID,
+    content: '',
+    metadata: {
+        command: 'gift',
+        giftId: GIFT_ID,
+        senderId: ACTOR_ID,
+        senderUsername: 'bob',
+        amount: '10.00000000',
+        currency: 'USD',
+    },
+    createdAt: new Date().toISOString(),
+};
+/** Gift row as returned from the DB (dates as Date objects, amount as string). */
+const GIFT_ROW = {
+    id: GIFT_ID,
+    messageId: MSG_ID,
+    senderId: ACTOR_ID,
+    senderUsername: 'bob',
+    amount: '10.00000000',
+    currency: 'USD',
+    roomId: ROOM_ID,
+    claimedBy: null,
+    claimedByUsername: null,
+    claimedAt: null,
+    createdAt: new Date(),
+};
+function makeWriter() {
+    return mock({
+        postSystemMessage: vi.fn().mockResolvedValue(SYSTEM_MSG),
+    });
+}
+function makeWallet(ok = true) {
+    return mock({
+        debit: vi
+            .fn()
+            .mockResolvedValue(ok
+            ? { ok: true, newBalance: '90.00000000', currency: 'USD' }
+            : { ok: false, available: '5.00000000' }),
+        credit: vi.fn().mockResolvedValue({ ok: true, newBalance: '110.00000000' }),
+    });
+}
+const DIRECTORY_CREATED_AT = new Date('2026-01-01T00:00:00.000Z');
+function makeDirectory(senderUsername = 'bob', claimerUsername = 'alice') {
+    const all = [
+        {
+            userId: ACTOR_ID,
+            username: senderUsername,
+            email: 'bob@example.com',
+            kycStatus: null,
+            language: null,
+            avatarUrl: null,
+            createdAt: DIRECTORY_CREATED_AT,
+            level: 3,
+            currency: 'USD',
+        },
+        {
+            userId: CLAIMER_ID,
+            username: claimerUsername,
+            email: 'alice@example.com',
+            kycStatus: null,
+            language: null,
+            avatarUrl: null,
+            createdAt: DIRECTORY_CREATED_AT,
+            level: 1,
+            currency: 'USD',
+        },
+    ];
+    return mock({
+        findPlayerIds: vi.fn().mockResolvedValue([ACTOR_ID]),
+        lookupPlayers: vi.fn().mockImplementation((ids) => {
+            return Promise.resolve(all.filter((p) => ids.includes(p.userId)));
+        }),
+        getPlayerByUsername: vi.fn().mockImplementation((username) => {
+            return Promise.resolve(all.find((p) => p.username.toLowerCase() === username.toLowerCase()) ?? null);
+        }),
+    });
+}
+function makeAudit() {
+    return mock({
+        record: vi.fn().mockResolvedValue(undefined),
+        recordInTransaction: vi.fn().mockResolvedValue(undefined),
+    });
+}
+function makeBlockWriter() {
+    return mock({
+        blockUser: vi.fn().mockResolvedValue(undefined),
+        ignoreUser: vi.fn().mockResolvedValue(undefined),
+        getExcludedUserIds: vi.fn().mockResolvedValue([]),
+    });
+}
+function makeGameReporting() {
+    return mock({
+        getPlayerStats: vi.fn().mockResolvedValue({ totalWagered: '100.00000000', totalBets: 5 }),
+    });
+}
+function makeTransport(onlineIds = [CLAIMER_ID]) {
+    return mock({
+        getOnlineUserIds: vi.fn().mockResolvedValue(onlineIds),
+        publish: vi.fn().mockResolvedValue(undefined),
+    });
+}
+function makeRoomAccess() {
+    return mock({ verifyRoomAccess: vi.fn().mockResolvedValue(undefined) });
+}
+function makeCache(initial = {}) {
+    const values = new Map(Object.entries(initial));
+    return {
+        get: async (key) => values.get(key),
+        set: vi.fn(async (key, value) => {
+            values.set(key, value);
+        }),
+        setIfAbsent: vi.fn(async (key, value) => {
+            if (values.has(key)) {
+                return false;
+            }
+            values.set(key, value);
+            return true;
+        }),
+        delete: vi.fn(async (key) => {
+            for (const item of Array.isArray(key) ? key : [key]) {
+                values.delete(item);
+            }
+        }),
+    };
+}
+function makeSvc(overrides = {}) {
+    const drizzle = makeDrizzle({
+        select: overrides.drizzleRows?.select ?? [],
+        returning: overrides.drizzleRows?.returning ?? [],
+        execute: overrides.drizzleRows?.execute,
+    });
+    return new ChatCommandsService(drizzle, overrides.writer ?? makeWriter(), overrides.wallet ?? makeWallet(), overrides.directory ?? makeDirectory(), overrides.audit ?? makeAudit(), overrides.transport ?? makeTransport(), mock(makeEventBus()), overrides.blockWriter ?? makeBlockWriter(), overrides.gameReporting ?? makeGameReporting(), overrides.roomAccess ?? makeRoomAccess(), overrides.cache ?? makeCache());
+}
+describe('ChatCommandsService.listCommands', () => {
+    it('returns only enabled commands by default', async () => {
+        // mock simulates DB returning only enabled rows (WHERE enabled = true applied at SQL level)
+        const svc = makeSvc({
+            drizzleRows: { select: [[ENABLED_ROW]] },
+        });
+        const result = await svc.listCommands();
+        expect(result).toHaveLength(1);
+        expect(result[0]?.key).toBe('gift');
+    });
+    it('returns all commands when includeDisabled is true', async () => {
+        // mock simulates DB returning all rows (no WHERE clause)
+        const svc = makeSvc({
+            drizzleRows: { select: [[ENABLED_ROW, DISABLED_ROW]] },
+        });
+        const result = await svc.listCommands(true);
+        expect(result).toHaveLength(2);
+    });
+});
+describe('ChatCommandsService.searchMentions', () => {
+    it('passes limit to findPlayerIds', async () => {
+        const directory = makeDirectory();
+        const svc = makeSvc({ directory });
+        await svc.searchMentions('ali', 5, CLAIMER_ID);
+        expect(directory.findPlayerIds).toHaveBeenCalledWith('ali', 5);
+    });
+    it('returns empty array when no ids found', async () => {
+        const directory = mock({
+            findPlayerIds: vi.fn().mockResolvedValue([]),
+            lookupPlayers: vi.fn().mockResolvedValue([]),
+        });
+        const svc = makeSvc({ directory });
+        const result = await svc.searchMentions('xyz', 10, CLAIMER_ID);
+        expect(result).toEqual([]);
+    });
+    it('excludes ids the viewer has blocked or ignored', async () => {
+        const directory = makeDirectory();
+        const blockWriter = mock({
+            blockUser: vi.fn().mockResolvedValue(undefined),
+            ignoreUser: vi.fn().mockResolvedValue(undefined),
+            getExcludedUserIds: vi.fn().mockResolvedValue([ACTOR_ID]),
+        });
+        const svc = makeSvc({ directory, blockWriter });
+        const result = await svc.searchMentions('bo', 5, CLAIMER_ID);
+        expect(blockWriter.getExcludedUserIds).toHaveBeenCalledWith(CLAIMER_ID);
+        expect(result).toEqual([]);
+    });
+});
+describe('ChatCommandsService.searchPlayers', () => {
+    it('returns mapped player search results', async () => {
+        const directory = makeDirectory();
+        const svc = makeSvc({ directory });
+        const result = await svc.searchPlayers('bo', 5, CLAIMER_ID);
+        expect(directory.findPlayerIds).toHaveBeenCalledWith('bo', 5);
+        expect(result).toEqual([{ userId: ACTOR_ID, username: 'bob', avatarUrl: null, level: 3 }]);
+    });
+    it('returns empty array when no matches', async () => {
+        const directory = mock({
+            findPlayerIds: vi.fn().mockResolvedValue([]),
+            lookupPlayers: vi.fn().mockResolvedValue([]),
+        });
+        const svc = makeSvc({ directory });
+        const result = await svc.searchPlayers('xyz', 10, CLAIMER_ID);
+        expect(result).toEqual([]);
+    });
+    it('excludes ids the viewer has blocked or ignored', async () => {
+        const directory = makeDirectory();
+        const blockWriter = mock({
+            blockUser: vi.fn().mockResolvedValue(undefined),
+            ignoreUser: vi.fn().mockResolvedValue(undefined),
+            getExcludedUserIds: vi.fn().mockResolvedValue([ACTOR_ID]),
+        });
+        const svc = makeSvc({ directory, blockWriter });
+        const result = await svc.searchPlayers('bo', 5, CLAIMER_ID);
+        expect(blockWriter.getExcludedUserIds).toHaveBeenCalledWith(CLAIMER_ID);
+        expect(result).toEqual([]);
+    });
+});
+describe('ChatCommandsService.getPlayerProfile', () => {
+    it('returns the full profile card on the happy path', async () => {
+        const gameReporting = makeGameReporting();
+        const svc = makeSvc({ directory: makeDirectory(), gameReporting });
+        const result = await svc.getPlayerProfile(ACTOR_ID, ACTOR_ID);
+        expect(gameReporting.getPlayerStats).toHaveBeenCalledWith(ACTOR_ID);
+        expect(result).toEqual({
+            userId: ACTOR_ID,
+            username: 'bob',
+            avatarUrl: null,
+            level: 3,
+            joinedAt: DIRECTORY_CREATED_AT.toISOString(),
+            totalWagered: '100.00000000',
+            totalBets: 5,
+            currency: 'USD',
+        });
+    });
+    it('throws ChatPlayerNotFoundError for an unknown userId', async () => {
+        const directory = mock({
+            lookupPlayers: vi.fn().mockResolvedValue([]),
+        });
+        const svc = makeSvc({ directory });
+        await expect(svc.getPlayerProfile(CLAIMER_ID, ACTOR_ID)).rejects.toThrow(ChatPlayerNotFoundError);
+    });
+    it('redacts private profile fields for another viewer', async () => {
+        const gameReporting = makeGameReporting();
+        const svc = makeSvc({ directory: makeDirectory(), gameReporting });
+        const result = await svc.getPlayerProfile(ACTOR_ID, CLAIMER_ID);
+        expect(result).toMatchObject({
+            userId: ACTOR_ID,
+            username: 'bob',
+            avatarUrl: null,
+            level: 3,
+            joinedAt: null,
+            totalWagered: null,
+            totalBets: null,
+            currency: null,
+        });
+        expect(gameReporting.getPlayerStats).not.toHaveBeenCalled();
+    });
+});
+const IDEMPOTENCY_KEY = '00000000-0000-0000-0000-0000000000aa';
+const IDEMPOTENCY_CACHE_KEY = `chat-command:idempotency:${ACTOR_ID}:gift:${IDEMPOTENCY_KEY}`;
+const RAIN_IDEMPOTENCY_CACHE_KEY = `chat-command:idempotency:${ACTOR_ID}:rain:${IDEMPOTENCY_KEY}`;
+const IDEMPOTENCY_ROW_ID = '00000000-0000-0000-0000-0000000000bb';
+describe('ChatCommandsService.executeCommand (gift)', () => {
+    it('throws CommandDisabledError when command row is missing', async () => {
+        const svc = makeSvc({ drizzleRows: { select: [[]] } });
+        await expect(svc.executeCommand({ type: 'gift', amount: '10', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID)).rejects.toThrow(CommandDisabledError);
+    });
+    it('throws CommandDisabledError when command is disabled', async () => {
+        const svc = makeSvc({ drizzleRows: { select: [[DISABLED_ROW]] } });
+        await expect(svc.executeCommand({ type: 'gift', amount: '10', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID)).rejects.toThrow(CommandDisabledError);
+    });
+    it('throws InsufficientBalanceError when wallet debit fails', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[ENABLED_ROW]],
+                // Only the idempotency guard insert is reached; wallet fails before the gift insert.
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+            },
+            wallet: makeWallet(false),
+        });
+        await expect(svc.executeCommand({ type: 'gift', amount: '10', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID)).rejects.toThrow(InsufficientBalanceError);
+    });
+    it('posts system message with new gift metadata on success', async () => {
+        const writer = makeWriter();
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[ENABLED_ROW]],
+                // First returning: idempotency guard insert; second: chatGift insert.
+                returning: [[{ ...GIFT_ROW }]],
+            },
+            writer,
+        });
+        const result = await svc.executeCommand({ type: 'gift', amount: '10.00000000', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID);
+        expect(writer.postSystemMessage).toHaveBeenCalledOnce();
+        expect(writer.postSystemMessage).toHaveBeenCalledWith(expect.objectContaining({
+            metadata: expect.objectContaining({
+                command: 'gift',
+                giftId: GIFT_ID,
+                senderId: ACTOR_ID,
+                senderUsername: 'bob',
+            }),
+        }));
+        expect(result.id).toBe(MSG_ID);
+    });
+    it('enforces minAmount from config', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[{ ...ENABLED_ROW, config: { minAmount: '5.00000000' } }]],
+            },
+        });
+        await expect(svc.executeCommand({
+            type: 'gift',
+            amount: '1.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(BelowMinimumError);
+    });
+});
+describe('ChatCommandsService.executeCommand (gift idempotency)', () => {
+    it('inserts the idempotency guard row and debits once when a fresh key is supplied', async () => {
+        const wallet = makeWallet();
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[ENABLED_ROW], []],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }], [{ ...GIFT_ROW }]],
+            },
+            wallet,
+        });
+        const result = await svc.executeCommand({ type: 'gift', amount: '10.00000000', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID);
+        expect(wallet.debit).toHaveBeenCalledOnce();
+        expect(result.id).toBe(MSG_ID);
+    });
+    it('replays the stored result without debiting the wallet again', async () => {
+        const wallet = makeWallet();
+        const giftInput = {
+            type: 'gift',
+            amount: '10.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        };
+        const storedRow = {
+            id: IDEMPOTENCY_ROW_ID,
+            actorId: ACTOR_ID,
+            commandType: 'gift',
+            idempotencyKey: IDEMPOTENCY_KEY,
+            amount: '10.00000000',
+            fingerprint: fingerprintCommand(giftInput),
+            result: SYSTEM_MSG,
+            createdAt: new Date(),
+        };
+        const svc = makeSvc({
+            drizzleRows: { select: [[ENABLED_ROW]] },
+            cache: makeCache({
+                [IDEMPOTENCY_CACHE_KEY]: { fingerprint: storedRow.fingerprint, result: SYSTEM_MSG },
+            }),
+            wallet,
+        });
+        const result = await svc.executeCommand(giftInput, ACTOR_ID);
+        expect(wallet.debit).not.toHaveBeenCalled();
+        expect(result).toEqual(SYSTEM_MSG);
+    });
+    it('throws ChatCommandIdempotencyKeyReuseError when the same key is reused with a different amount', async () => {
+        const storedRow = {
+            id: IDEMPOTENCY_ROW_ID,
+            actorId: ACTOR_ID,
+            commandType: 'gift',
+            idempotencyKey: IDEMPOTENCY_KEY,
+            amount: '5.00000000',
+            fingerprint: fingerprintCommand({
+                type: 'gift',
+                amount: '5.00000000',
+                roomId: ROOM_ID,
+                idempotencyKey: IDEMPOTENCY_KEY,
+            }),
+            result: SYSTEM_MSG,
+            createdAt: new Date(),
+        };
+        const svc = makeSvc({
+            drizzleRows: { select: [[ENABLED_ROW]] },
+            cache: makeCache({
+                [IDEMPOTENCY_CACHE_KEY]: { fingerprint: storedRow.fingerprint, result: SYSTEM_MSG },
+            }),
+        });
+        await expect(svc.executeCommand({ type: 'gift', amount: '10.00000000', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID)).rejects.toThrow(ChatCommandIdempotencyKeyReuseError);
+    });
+    it('throws ChatCommandIdempotencyKeyReuseError when the same key+amount is reused for a different room', async () => {
+        const storedRow = {
+            id: IDEMPOTENCY_ROW_ID,
+            actorId: ACTOR_ID,
+            commandType: 'gift',
+            idempotencyKey: IDEMPOTENCY_KEY,
+            amount: '10.00000000',
+            fingerprint: fingerprintCommand({
+                type: 'gift',
+                amount: '10.00000000',
+                roomId: OTHER_ROOM_ID,
+                idempotencyKey: IDEMPOTENCY_KEY,
+            }),
+            result: SYSTEM_MSG,
+            createdAt: new Date(),
+        };
+        const svc = makeSvc({
+            drizzleRows: { select: [[ENABLED_ROW]] },
+            cache: makeCache({
+                [IDEMPOTENCY_CACHE_KEY]: { fingerprint: storedRow.fingerprint, result: SYSTEM_MSG },
+            }),
+        });
+        await expect(svc.executeCommand({ type: 'gift', amount: '10.00000000', roomId: ROOM_ID, idempotencyKey: IDEMPOTENCY_KEY }, ACTOR_ID)).rejects.toThrow(ChatCommandIdempotencyKeyReuseError);
+    });
+});
+describe('ChatCommandsService.claimGift', () => {
+    it('credits the claimer and returns claim info on happy path', async () => {
+        const wallet = makeWallet();
+        const svc = makeSvc({
+            drizzleRows: {
+                // select[0]: gift lookup; returning[0]: atomic update result
+                select: [[GIFT_ROW]],
+                returning: [
+                    [
+                        {
+                            ...GIFT_ROW,
+                            claimedBy: CLAIMER_ID,
+                            claimedByUsername: 'alice',
+                            claimedAt: new Date(),
+                        },
+                    ],
+                ],
+            },
+            wallet,
+        });
+        const result = await svc.claimGift(GIFT_ID, CLAIMER_ID);
+        expect(wallet.credit).toHaveBeenCalledOnce();
+        expect(wallet.credit).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ userId: CLAIMER_ID, type: 'gift' }));
+        expect(result.claimedBy).toBe(CLAIMER_ID);
+        expect(result.claimedByUsername).toBe('alice');
+        expect(result.claimedAt).toEqual(expect.any(String));
+    });
+    it('throws GiftSelfClaimError when sender tries to claim their own gift', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[GIFT_ROW]], // senderId === ACTOR_ID
+                returning: [],
+            },
+        });
+        await expect(svc.claimGift(GIFT_ID, ACTOR_ID)).rejects.toThrow(GiftSelfClaimError);
+    });
+    it('throws GiftAlreadyClaimedError when update returns no rows (race lost)', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[GIFT_ROW]],
+                returning: [[]], // empty = already claimed
+            },
+        });
+        await expect(svc.claimGift(GIFT_ID, CLAIMER_ID)).rejects.toThrow(GiftAlreadyClaimedError);
+    });
+    it('throws GiftNotFoundError when gift does not exist', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[]], // no gift row
+                returning: [],
+            },
+        });
+        await expect(svc.claimGift(GIFT_ID, CLAIMER_ID)).rejects.toThrow(GiftNotFoundError);
+    });
+});
+describe('ChatCommandsService.adminUpdateCommand', () => {
+    it('upserts the command row and returns the descriptor', async () => {
+        const updatedRow = { ...ENABLED_ROW, key: 'gift', enabled: false };
+        const svc = makeSvc({
+            drizzleRows: { returning: [[updatedRow]] },
+        });
+        const result = await svc.adminUpdateCommand({ key: 'gift', enabled: false }, ACTOR_ID);
+        expect(result.key).toBe('gift');
+        expect(result.enabled).toBe(false);
+    });
+    it('records an audit entry on update', async () => {
+        const updatedRow = { ...ENABLED_ROW, key: 'rain', enabled: false };
+        const audit = makeAudit();
+        const drizzle = makeDrizzle({ select: [], returning: [[updatedRow]] });
+        const svcWithAudit = new ChatCommandsService(drizzle, makeWriter(), makeWallet(), makeDirectory(), audit, makeTransport(), mock(makeEventBus()), makeBlockWriter(), makeGameReporting(), makeRoomAccess(), makeCache());
+        await svcWithAudit.adminUpdateCommand({ key: 'rain', enabled: false }, ACTOR_ID);
+        expect(audit.record).toHaveBeenCalledWith(expect.objectContaining({
+            actorId: ACTOR_ID,
+            actorType: 'admin',
+            action: 'chat.command.updated',
+            resourceId: 'rain',
+        }));
+    });
+});
+describe('ChatCommandsService.handleRain', () => {
+    const RAIN_ROW = { ...ENABLED_ROW, key: 'rain', label: 'Rain' };
+    it('throws NoOnlineUsersError when no other users are online', async () => {
+        const svc = makeSvc({
+            drizzleRows: { select: [[RAIN_ROW]] },
+            transport: makeTransport([ACTOR_ID]),
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '10.00000000',
+            recipientCount: 5,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(NoOnlineUsersError);
+    });
+    it('replays before discovering online presence', async () => {
+        const transport = makeTransport();
+        const storedRow = {
+            id: IDEMPOTENCY_ROW_ID,
+            actorId: ACTOR_ID,
+            commandType: 'rain',
+            idempotencyKey: IDEMPOTENCY_KEY,
+            amount: '10.99000000',
+            fingerprint: fingerprintCommand({
+                type: 'rain',
+                amount: '10.99000000',
+                recipientCount: 10,
+                roomId: ROOM_ID,
+                idempotencyKey: IDEMPOTENCY_KEY,
+            }),
+            result: SYSTEM_MSG,
+            createdAt: new Date(),
+        };
+        const svc = makeSvc({
+            drizzleRows: { select: [[RAIN_ROW]] },
+            transport,
+            cache: makeCache({
+                [RAIN_IDEMPOTENCY_CACHE_KEY]: { fingerprint: storedRow.fingerprint, result: SYSTEM_MSG },
+            }),
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '10.99000000',
+            recipientCount: 10,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).resolves.toEqual(SYSTEM_MSG);
+        expect(transport.getOnlineUserIds).not.toHaveBeenCalled();
+    });
+    it('distributes to online recipients excluding the actor', async () => {
+        const RECIPIENT_2 = '00000000-0000-0000-0000-000000000006';
+        const wallet = makeWallet();
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[RAIN_ROW]],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+                execute: [[{ per_recipient: '5.00000000', total_distributed: '10.00000000' }]],
+            },
+            wallet,
+            transport: makeTransport([ACTOR_ID, CLAIMER_ID, RECIPIENT_2]),
+        });
+        await svc.executeCommand({
+            type: 'rain',
+            amount: '10.00000000',
+            recipientCount: 2,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID);
+        expect(wallet.credit).toHaveBeenCalledTimes(2);
+        expect(wallet.credit).toHaveBeenCalledWith(expect.anything(), {
+            userId: CLAIMER_ID,
+            amount: '5.00000000',
+            currency: 'USD',
+            type: 'rain',
+        });
+    });
+    it('uses Postgres floor division to avoid float imprecision', async () => {
+        const wallet = makeWallet();
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[RAIN_ROW]],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+                execute: [[{ per_recipient: '3.33333333', total_distributed: '9.99999999' }]],
+            },
+            wallet,
+            transport: makeTransport([
+                CLAIMER_ID,
+                '00000000-0000-0000-0000-000000000006',
+                '00000000-0000-0000-0000-000000000007',
+            ]),
+        });
+        await svc.executeCommand({
+            type: 'rain',
+            amount: '10.00000000',
+            recipientCount: 3,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID);
+        expect(wallet.credit).toHaveBeenCalledWith(expect.anything(), {
+            userId: expect.any(String),
+            amount: '3.33333333',
+            currency: 'USD',
+            type: 'rain',
+        });
+    });
+    it('debits only the amount actually distributed (floor(amount/n)*n), never the raw player-typed amount', async () => {
+        const wallet = makeWallet();
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[RAIN_ROW]],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+                execute: [[{ per_recipient: '1.00000000', total_distributed: '10.00000000' }]],
+            },
+            wallet,
+            transport: makeTransport(Array.from({ length: 10 }, (_, i) => `00000000-0000-0000-0000-0000000000${10 + i}`)),
+        });
+        await svc.executeCommand({
+            type: 'rain',
+            amount: '10.99000000',
+            recipientCount: 10,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID);
+        expect(wallet.debit).toHaveBeenCalledWith(expect.anything(), {
+            userId: ACTOR_ID,
+            amount: '10.00000000',
+            type: 'rain',
+        });
+    });
+    it('throws BelowMinimumError when amount is below config minAmount', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[{ ...RAIN_ROW, config: { minAmount: '5.00000000' } }]],
+            },
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '1.00000000',
+            recipientCount: 1,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(BelowMinimumError);
+    });
+    it('throws ExceedsLimitError when amount is above config maxAmount', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[{ ...RAIN_ROW, config: { maxAmount: '10.00000000' } }]],
+            },
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '50.00000000',
+            recipientCount: 1,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(ExceedsLimitError);
+    });
+    it('throws ExceedsLimitError when recipientCount exceeds config maxRecipients', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[{ ...RAIN_ROW, config: { maxRecipients: 10 } }]],
+            },
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '100.00000000',
+            recipientCount: 11,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(ExceedsLimitError);
+    });
+    it('throws TooManyRecipientsError when recipientCount exceeds the whole-dollar amount', async () => {
+        const svc = makeSvc({
+            drizzleRows: { select: [[RAIN_ROW]] },
+        });
+        await expect(svc.executeCommand({
+            type: 'rain',
+            amount: '3.00000000',
+            recipientCount: 4,
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(TooManyRecipientsError);
+    });
+});
+const DONATE_ROW = {
+    key: 'donate',
+    enabled: true,
+    label: 'Donate',
+    description: 'Send a direct tip to a specific player',
+    config: null,
+    updatedAt: new Date(),
+};
+const DONATE_SYSTEM_MSG = {
+    id: MSG_ID,
+    roomId: ROOM_ID,
+    actorId: ACTOR_ID,
+    content: '',
+    metadata: {
+        command: 'donate',
+        recipientId: CLAIMER_ID,
+        recipientUsername: 'alice',
+        amount: '10.00000000',
+        currency: 'USD',
+    },
+    createdAt: new Date().toISOString(),
+};
+/**
+ * Directory mock where findPlayerIds resolves the RECIPIENT (CLAIMER_ID = 'alice').
+ * Used for donate tests that target 'alice' — the default makeDirectory() always
+ * returns ACTOR_ID which only has username 'bob', so alice is never found.
+ */
+function makeRecipientDirectory() {
+    const all = [
+        {
+            userId: ACTOR_ID,
+            username: 'bob',
+            email: 'bob@example.com',
+            kycStatus: null,
+            language: null,
+            avatarUrl: null,
+            createdAt: DIRECTORY_CREATED_AT,
+            level: 3,
+            currency: 'USD',
+        },
+        {
+            userId: CLAIMER_ID,
+            username: 'alice',
+            email: 'alice@example.com',
+            kycStatus: null,
+            language: null,
+            avatarUrl: null,
+            createdAt: DIRECTORY_CREATED_AT,
+            level: 1,
+            currency: 'USD',
+        },
+    ];
+    return mock({
+        findPlayerIds: vi.fn().mockResolvedValue([CLAIMER_ID]),
+        lookupPlayers: vi.fn().mockImplementation((ids) => {
+            return Promise.resolve(all.filter((p) => ids.includes(p.userId)));
+        }),
+        getPlayerByUsername: vi.fn().mockImplementation((username) => {
+            return Promise.resolve(all.find((p) => p.username.toLowerCase() === username.toLowerCase()) ?? null);
+        }),
+    });
+}
+describe('ChatCommandsService.handleDonate', () => {
+    it('debits sender, credits recipient, and returns system message on success', async () => {
+        const wallet = makeWallet();
+        const writer = mock({
+            postSystemMessage: vi.fn().mockResolvedValue(DONATE_SYSTEM_MSG),
+        });
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[DONATE_ROW]],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+            },
+            wallet,
+            writer,
+            directory: makeRecipientDirectory(),
+        });
+        const result = await svc.executeCommand({
+            type: 'donate',
+            targetUsername: 'alice',
+            amount: '10.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID);
+        expect(wallet.debit).toHaveBeenCalledWith(expect.anything(), {
+            userId: ACTOR_ID,
+            amount: '10.00000000',
+            type: 'tip',
+        });
+        expect(wallet.credit).toHaveBeenCalledWith(expect.anything(), {
+            userId: CLAIMER_ID,
+            amount: '10.00000000',
+            currency: 'USD',
+            type: 'tip',
+        });
+        expect(result.id).toBe(MSG_ID);
+    });
+    it('throws DonateSelfError when sender targets themselves', async () => {
+        // Default makeDirectory() returns ACTOR_ID ('bob') from findPlayerIds — correct for self-target.
+        const svc = makeSvc({
+            drizzleRows: { select: [[DONATE_ROW]] },
+        });
+        await expect(svc.executeCommand({
+            type: 'donate',
+            targetUsername: 'bob',
+            amount: '10.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(DonateSelfError);
+    });
+    it('throws ChatPlayerNotFoundError when target username does not exist', async () => {
+        const directory = mock({
+            findPlayerIds: vi.fn().mockResolvedValue([]),
+            lookupPlayers: vi.fn().mockResolvedValue([]),
+            getPlayerByUsername: vi.fn().mockResolvedValue(null),
+        });
+        const svc = makeSvc({
+            drizzleRows: { select: [[DONATE_ROW]] },
+            directory,
+        });
+        await expect(svc.executeCommand({
+            type: 'donate',
+            targetUsername: 'ghost',
+            amount: '10.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(ChatPlayerNotFoundError);
+    });
+    it('throws InsufficientBalanceError when sender wallet debit fails', async () => {
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[DONATE_ROW]],
+                returning: [[{ id: IDEMPOTENCY_ROW_ID }]],
+            },
+            wallet: makeWallet(false),
+            directory: makeRecipientDirectory(),
+        });
+        await expect(svc.executeCommand({
+            type: 'donate',
+            targetUsername: 'alice',
+            amount: '10.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(InsufficientBalanceError);
+    });
+    it('throws BelowMinimumError when amount is below config minAmount', async () => {
+        // Amount check fires before directory lookup, so directory mock does not matter here.
+        const svc = makeSvc({
+            drizzleRows: {
+                select: [[{ ...DONATE_ROW, config: { minAmount: '5.00000000' } }]],
+            },
+        });
+        await expect(svc.executeCommand({
+            type: 'donate',
+            targetUsername: 'alice',
+            amount: '1.00000000',
+            roomId: ROOM_ID,
+            idempotencyKey: IDEMPOTENCY_KEY,
+        }, ACTOR_ID)).rejects.toThrow(BelowMinimumError);
+    });
+});
+const BLOCK_ROW = { ...ENABLED_ROW, key: 'block', label: 'Block' };
+const IGNORE_ROW = { ...ENABLED_ROW, key: 'ignore', label: 'Ignore' };
+describe('ChatCommandsService.handleBlockAction', () => {
+    it('dispatches "block" to blockWriter.blockUser, not ignoreUser', async () => {
+        const blockWriter = makeBlockWriter();
+        const svc = makeSvc({
+            drizzleRows: { select: [[BLOCK_ROW]] },
+            directory: makeRecipientDirectory(),
+            blockWriter,
+        });
+        await svc.executeCommand({ type: 'block', targetUsername: 'alice', roomId: ROOM_ID }, ACTOR_ID);
+        expect(blockWriter.blockUser).toHaveBeenCalledWith(ACTOR_ID, CLAIMER_ID);
+        expect(blockWriter.ignoreUser).not.toHaveBeenCalled();
+    });
+    it('dispatches "ignore" to blockWriter.ignoreUser, not blockUser', async () => {
+        const blockWriter = makeBlockWriter();
+        const svc = makeSvc({
+            drizzleRows: { select: [[IGNORE_ROW]] },
+            directory: makeRecipientDirectory(),
+            blockWriter,
+        });
+        await svc.executeCommand({ type: 'ignore', targetUsername: 'alice', roomId: ROOM_ID }, ACTOR_ID);
+        expect(blockWriter.ignoreUser).toHaveBeenCalledWith(ACTOR_ID, CLAIMER_ID);
+        expect(blockWriter.blockUser).not.toHaveBeenCalled();
+    });
+    it('throws SelfModerationActionError on self-block', async () => {
+        const svc = makeSvc({
+            drizzleRows: { select: [[BLOCK_ROW]] },
+        });
+        await expect(svc.executeCommand({ type: 'block', targetUsername: 'bob', roomId: ROOM_ID }, ACTOR_ID)).rejects.toThrow(SelfModerationActionError);
+    });
+    it('throws SelfModerationActionError on self-ignore', async () => {
+        const svc = makeSvc({
+            drizzleRows: { select: [[IGNORE_ROW]] },
+        });
+        await expect(svc.executeCommand({ type: 'ignore', targetUsername: 'bob', roomId: ROOM_ID }, ACTOR_ID)).rejects.toThrow(SelfModerationActionError);
+    });
+});
+//# sourceMappingURL=chat-commands.service.test.js.map