@openora/core 0.4.1-canary.60 → 0.4.1-canary.63

package/dist/engagement/social-transfers/service/social-transfers.service.js

@@ -0,0 +1,789 @@
+import { createHash } from 'node:crypto';
+import { and, eq, isNull, sql } from 'drizzle-orm';
+import { createLogger, makeNotFoundError, makeConflictError, mapConcurrent, moneyToNumber, findOneOrThrow, createDomainError, } from '@openora/core/server';
+import { chatChannel } from '@openora/core/contracts';
+import { chatCommandConfig } from '@openora/core/engagement/schema/chat-commands';
+import { playerGift, playerDonate, playerRain, playerRainReceiver } from '../schema/index.js';
+const logger = createLogger('social-transfers');
+function publishChatEvent(transport, roomId, event) {
+    void Promise.resolve()
+        .then(() => transport.publish(chatChannel(roomId), event))
+        .catch((err) => {
+        logger.error({ err, roomId }, 'chat realtime publish failed');
+    });
+}
+export const CommandDisabledError = makeNotFoundError('ChatCommand');
+export const NoOnlineUsersError = makeConflictError('NoOnlineUsers', 'No other users are online in this room');
+export const InsufficientBalanceError = makeConflictError('InsufficientBalance', 'Not enough balance');
+export const ExceedsLimitError = makeConflictError('ExceedsLimit', 'Amount exceeds the command limit');
+export const BelowMinimumError = makeConflictError('BelowMinimum', 'Amount is below the minimum for this command');
+export const RainCreditError = makeConflictError('RainCreditError', 'A recipient wallet is unavailable; rain aborted');
+export class ChatPlayerNotFoundError extends Error {
+    playerId;
+    constructor(playerId) {
+        super(`ChatPlayer not found: ${playerId}`);
+        this.playerId = playerId;
+        this.name = 'ChatPlayerNotFoundError';
+    }
+}
+export const GiftNotFoundError = makeNotFoundError('ChatGift');
+export const GiftAlreadyClaimedError = makeConflictError('GiftAlreadyClaimed', 'This gift has already been claimed');
+export const GiftSelfClaimError = makeConflictError('GiftSelfClaim', 'You cannot claim your own gift');
+export const GiftCreditError = makeConflictError('GiftCreditError', 'Recipient wallet is unavailable; gift claim aborted');
+export const DonateSelfError = makeConflictError('DonateSelf', 'You cannot donate to yourself');
+export const TooManyRecipientsError = makeConflictError('TooManyRecipients', 'Amount too small: you need at least $1 per recipient');
+export const ChatCommandIdempotencyKeyReuseError = makeConflictError('ChatCommandIdempotencyKeyReuse', 'This idempotency key was already used with different request parameters');
+export const ConcurrentCommandReplayError = makeConflictError('ConcurrentCommandReplay', 'This request is already being processed - please retry');
+export const ChatRoomNotMemberError = createDomainError('ChatRoomNotMemberError', (roomId) => `You are not a member of room: ${roomId}`);
+// Internal-only: createDomainError instances don't expose their constructor args as
+// properties, so this carries the gift's roomId across the doClaimGift -> toClaimGiftResult
+// boundary - without it, the ClaimGiftResult's room_not_member reason has no roomId, and
+// chat-commands (which only has giftId in scope) would build a ChatRoomNotMemberError with
+// the wrong id. Never crosses the GIFT_COMMANDS port boundary itself.
+class GiftRoomAccessError extends Error {
+    roomId;
+    constructor(roomId) {
+        super('room_not_member');
+        this.roomId = roomId;
+        this.name = 'GiftRoomAccessError';
+    }
+}
+const COMMAND_IDEMPOTENCY_TTL_MS = 5 * 60 * 1000;
+// The replay guard must match on the COMPLETE request, not just the amount - a reused
+// key with a different room, recipient count, or donate target is a distinct request,
+// not a replay of the original. `idempotencyKey` itself is excluded so the fingerprint
+// is stable for the row it guards. The cache-key namespace stays `chat-command:*` even
+// though this logic now lives here - see AGENTS.md.
+export function fingerprintCommand(input) {
+    const canonical = input.type === 'gift'
+        ? { type: input.type, amount: input.amount, roomId: input.roomId }
+        : input.type === 'rain'
+            ? {
+                type: input.type,
+                amount: input.amount,
+                recipientCount: input.recipientCount,
+                roomId: input.roomId,
+            }
+            : {
+                type: input.type,
+                amount: input.amount,
+                targetUsername: input.targetUsername,
+                roomId: input.roomId,
+            };
+    return createHash('sha256').update(JSON.stringify(canonical)).digest('hex');
+}
+function shuffleArray(arr) {
+    const result = [...arr];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        const a = result.at(i);
+        const b = result.at(j);
+        if (a !== undefined && b !== undefined) {
+            result[i] = b;
+            result[j] = a;
+        }
+    }
+    return result;
+}
+// Translates a thrown domain error into the GIFT_COMMANDS port's discriminated
+// result so chat-commands never needs to import this module's error classes
+// (module boundary) - only genuinely unexpected errors still throw across the
+// port. `.name`-based fallback covers an error surfacing from CHAT_ROOM_ACCESS
+// (a different module's class), mirroring the sender-side room-access guard.
+function toSendGiftResult(error) {
+    if (error instanceof CommandDisabledError) {
+        return { ok: false, reason: 'disabled' };
+    }
+    if (error instanceof InsufficientBalanceError) {
+        return { ok: false, reason: 'insufficient_balance' };
+    }
+    if (error instanceof ExceedsLimitError) {
+        return { ok: false, reason: 'exceeds_limit' };
+    }
+    if (error instanceof BelowMinimumError) {
+        return { ok: false, reason: 'below_minimum' };
+    }
+    if (error instanceof ChatPlayerNotFoundError) {
+        return { ok: false, reason: 'player_not_found', playerId: error.playerId };
+    }
+    if (error instanceof ChatCommandIdempotencyKeyReuseError) {
+        return { ok: false, reason: 'idempotency_key_reuse' };
+    }
+    if (error instanceof ConcurrentCommandReplayError) {
+        return { ok: false, reason: 'concurrent_replay' };
+    }
+    if (error instanceof ChatRoomNotMemberError ||
+        (error instanceof Error && error.name === 'ChatRoomNotMemberError')) {
+        return { ok: false, reason: 'room_not_member' };
+    }
+    throw error;
+}
+function toClaimGiftResult(error) {
+    if (error instanceof GiftNotFoundError) {
+        return { ok: false, reason: 'gift_not_found' };
+    }
+    if (error instanceof GiftAlreadyClaimedError) {
+        return { ok: false, reason: 'already_claimed' };
+    }
+    if (error instanceof GiftSelfClaimError) {
+        return { ok: false, reason: 'self_claim' };
+    }
+    if (error instanceof GiftRoomAccessError) {
+        return { ok: false, reason: 'room_not_member', roomId: error.roomId };
+    }
+    if (error instanceof GiftCreditError) {
+        return { ok: false, reason: 'gift_credit_failed' };
+    }
+    throw error;
+}
+function toGetGiftResult(error) {
+    if (error instanceof GiftNotFoundError) {
+        return { ok: false, reason: 'gift_not_found' };
+    }
+    if (error instanceof GiftRoomAccessError) {
+        return { ok: false, reason: 'room_not_member', roomId: error.roomId };
+    }
+    throw error;
+}
+function toSendRainResult(error) {
+    if (error instanceof CommandDisabledError) {
+        return { ok: false, reason: 'disabled' };
+    }
+    if (error instanceof InsufficientBalanceError) {
+        return { ok: false, reason: 'insufficient_balance' };
+    }
+    if (error instanceof ExceedsLimitError) {
+        return { ok: false, reason: 'exceeds_limit' };
+    }
+    if (error instanceof BelowMinimumError) {
+        return { ok: false, reason: 'below_minimum' };
+    }
+    if (error instanceof ChatPlayerNotFoundError) {
+        return { ok: false, reason: 'player_not_found', playerId: error.playerId };
+    }
+    if (error instanceof NoOnlineUsersError) {
+        return { ok: false, reason: 'no_online_users' };
+    }
+    if (error instanceof TooManyRecipientsError) {
+        return { ok: false, reason: 'too_many_recipients' };
+    }
+    if (error instanceof RainCreditError) {
+        return { ok: false, reason: 'rain_credit_failed' };
+    }
+    if (error instanceof ChatCommandIdempotencyKeyReuseError) {
+        return { ok: false, reason: 'idempotency_key_reuse' };
+    }
+    if (error instanceof ConcurrentCommandReplayError) {
+        return { ok: false, reason: 'concurrent_replay' };
+    }
+    if (error instanceof ChatRoomNotMemberError ||
+        (error instanceof Error && error.name === 'ChatRoomNotMemberError')) {
+        return { ok: false, reason: 'room_not_member' };
+    }
+    throw error;
+}
+export class SocialTransfersService {
+    drizzle;
+    systemWriter;
+    wallet;
+    directory;
+    audit;
+    transport;
+    events;
+    roomAccess;
+    cache;
+    idempotencyTtlMs;
+    constructor(drizzle, systemWriter, wallet, directory, audit, transport, events, roomAccess, cache, idempotencyTtlMs = COMMAND_IDEMPOTENCY_TTL_MS) {
+        this.drizzle = drizzle;
+        this.systemWriter = systemWriter;
+        this.wallet = wallet;
+        this.directory = directory;
+        this.audit = audit;
+        this.transport = transport;
+        this.events = events;
+        this.roomAccess = roomAccess;
+        this.cache = cache;
+        this.idempotencyTtlMs = idempotencyTtlMs;
+    }
+    // GIFT_COMMANDS port impl, consumed by chat-commands via DI - never throws,
+    // every failure the caller must distinguish comes back as a typed `reason`.
+    async sendGift(input, actorId) {
+        try {
+            const message = await this.doSendGift(input, actorId);
+            return { ok: true, message };
+        }
+        catch (error) {
+            return toSendGiftResult(error);
+        }
+    }
+    async claimGift(giftId, claimerId) {
+        try {
+            return await this.doClaimGift(giftId, claimerId);
+        }
+        catch (error) {
+            return toClaimGiftResult(error);
+        }
+    }
+    async getGift(giftId, viewerId) {
+        try {
+            const gift = await this.doGetGift(giftId, viewerId);
+            return { ok: true, gift };
+        }
+        catch (error) {
+            return toGetGiftResult(error);
+        }
+    }
+    // RAIN_COMMANDS port impl, consumed by chat-commands via DI - never throws.
+    // `input.onlineUserIds` is resolved by the caller (chat-commands owns
+    // presence via its own dependency on `chat`); this module never queries
+    // online status itself.
+    async sendRain(input, actorId) {
+        try {
+            const message = await this.doSendRain(input, actorId);
+            return { ok: true, message };
+        }
+        catch (error) {
+            return toSendRainResult(error);
+        }
+    }
+    async sendDonate(input, actorId) {
+        return this.doSendDonate(input, actorId);
+    }
+    async loadCommandConfig(key) {
+        const [row] = await this.drizzle.db
+            .select()
+            .from(chatCommandConfig)
+            .where(eq(chatCommandConfig.key, key))
+            .limit(1);
+        if (!row || !row.enabled) {
+            throw new CommandDisabledError(key);
+        }
+        return row.config ?? null;
+    }
+    async verifyRoomAccessIfNeeded(roomId, actorId) {
+        if (!roomId) {
+            return;
+        }
+        try {
+            await this.roomAccess.verifyRoomAccess(roomId, actorId);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'ChatRoomNotMemberError') {
+                throw new ChatRoomNotMemberError(roomId);
+            }
+            throw error;
+        }
+    }
+    async findCommandReplay(commandType, actorId, idempotencyKey, fingerprint) {
+        const record = await this.cache.get(this.idempotencyCacheKey(commandType, actorId, idempotencyKey));
+        if (!record) {
+            return null;
+        }
+        if (record.fingerprint !== fingerprint) {
+            throw new ChatCommandIdempotencyKeyReuseError();
+        }
+        if (!record.result) {
+            throw new ConcurrentCommandReplayError();
+        }
+        return record.result;
+    }
+    idempotencyCacheKey(commandType, actorId, idempotencyKey) {
+        return `chat-command:idempotency:${actorId}:${commandType}:${idempotencyKey}`;
+    }
+    async reserveCommandIdempotency(commandType, actorId, idempotencyKey, fingerprint) {
+        const reserved = await this.cache.setIfAbsent(this.idempotencyCacheKey(commandType, actorId, idempotencyKey), { fingerprint, result: null }, { ttlMs: this.idempotencyTtlMs });
+        if (!reserved) {
+            throw new ConcurrentCommandReplayError();
+        }
+    }
+    async completeCommandIdempotency(commandType, actorId, idempotencyKey, fingerprint, result) {
+        try {
+            await this.cache.set(this.idempotencyCacheKey(commandType, actorId, idempotencyKey), { fingerprint, result }, { ttlMs: this.idempotencyTtlMs });
+        }
+        catch (err) {
+            logger.error({ err, commandType, actorId, idempotencyKey }, 'idempotency result cache failed');
+        }
+    }
+    async runWithCommandReservation(commandType, actorId, idempotencyKey, work) {
+        try {
+            return await work();
+        }
+        catch (error) {
+            try {
+                await this.cache.delete(this.idempotencyCacheKey(commandType, actorId, idempotencyKey));
+            }
+            catch (cleanupError) {
+                logger.error({ err: cleanupError, commandType, actorId, idempotencyKey }, 'idempotency reservation cleanup failed');
+            }
+            throw error;
+        }
+    }
+    // Exact, case-insensitive username resolution for callers holding a complete, already-known
+    // username (never a partial search term) - `/donate`. Distinct from findPlayerIds' capped
+    // fuzzy substring search, which can silently drop the real match once more than 20 unrelated
+    // accounts substring-collide with a short/common username.
+    async resolveExactPlayer(username) {
+        const summary = await this.directory.getPlayerByUsername(username);
+        if (!summary) {
+            throw new ChatPlayerNotFoundError(username);
+        }
+        return summary;
+    }
+    async doSendGift(input, actorId) {
+        await this.verifyRoomAccessIfNeeded(input.roomId, actorId);
+        const config = await this.loadCommandConfig('gift');
+        if (config?.maxAmount !== undefined &&
+            moneyToNumber(input.amount) > moneyToNumber(config.maxAmount)) {
+            throw new ExceedsLimitError();
+        }
+        if (config?.minAmount !== undefined &&
+            moneyToNumber(input.amount) < moneyToNumber(config.minAmount)) {
+            throw new BelowMinimumError();
+        }
+        const senderSummaries = await this.directory.lookupPlayers([actorId]);
+        const senderSummary = senderSummaries.find((s) => s.userId === actorId);
+        if (!senderSummary) {
+            throw new ChatPlayerNotFoundError(actorId);
+        }
+        const senderUsername = senderSummary.username;
+        // Sender resolved BEFORE reserving (mirrors doSendDonate): runWithCommandReservation
+        // only releases the reservation on a failure inside its own callback, so anything
+        // between reserveCommandIdempotency and that callback would otherwise leak a stuck
+        // reservation for the full TTL on a transient directory error.
+        const fingerprint = fingerprintCommand({ type: 'gift', ...input });
+        const replay = await this.findCommandReplay('gift', actorId, input.idempotencyKey, fingerprint);
+        if (replay) {
+            return replay;
+        }
+        await this.reserveCommandIdempotency('gift', actorId, input.idempotencyKey, fingerprint);
+        const { msg, giftId, currency } = await this.runWithCommandReservation('gift', actorId, input.idempotencyKey, () => this.drizzle.db.transaction(async (tx) => {
+            const debit = await this.wallet.debit(tx, {
+                userId: actorId,
+                amount: input.amount,
+                type: 'gift',
+            });
+            if (!debit.ok) {
+                throw new InsufficientBalanceError();
+            }
+            const [giftRow] = await tx
+                .insert(playerGift)
+                .values({
+                senderId: actorId,
+                senderUsername,
+                amount: input.amount,
+                currency: debit.currency,
+                roomId: input.roomId,
+                // messageId is back-filled below, in the same transaction, once the
+                // system message exists (same insert-then-update pattern as before).
+                messageId: '00000000-0000-0000-0000-000000000000',
+            })
+                .returning();
+            if (!giftRow) {
+                throw new InsufficientBalanceError();
+            }
+            const message = await this.systemWriter.postSystemMessage({
+                roomId: input.roomId,
+                actorId,
+                tx,
+                metadata: {
+                    command: 'gift',
+                    giftId: giftRow.id,
+                    senderId: actorId,
+                    senderUsername,
+                    amount: input.amount,
+                    currency: debit.currency,
+                    status: 'available',
+                    claimedBy: null,
+                    claimedByUsername: null,
+                    claimedAt: null,
+                },
+            });
+            await tx
+                .update(playerGift)
+                .set({ messageId: message.id })
+                .where(eq(playerGift.id, giftRow.id));
+            await this.audit.recordInTransaction(tx, {
+                actorId,
+                actorType: 'player',
+                action: 'chat.gift',
+                resourceType: 'player_gift',
+                resourceId: giftRow.id,
+                before: null,
+                after: { amount: input.amount, roomId: input.roomId },
+            });
+            return { msg: message, giftId: giftRow.id, currency: debit.currency };
+        }));
+        await this.completeCommandIdempotency('gift', actorId, input.idempotencyKey, fingerprint, msg);
+        // The caller now owns the commit boundary: postSystemMessage was passed `tx` above so
+        // it did not auto-publish - publish only now that this transaction has committed.
+        publishChatEvent(this.transport, input.roomId, msg);
+        void this.events.emit('chat.gift.sent', {
+            giftId,
+            senderId: actorId,
+            senderUsername,
+            amount: input.amount,
+            currency,
+            roomId: input.roomId,
+            messageId: msg.id,
+        });
+        return msg;
+    }
+    async doClaimGift(giftId, claimerId) {
+        const claimerSummaries = await this.directory.lookupPlayers([claimerId]);
+        const claimerSummary = claimerSummaries.find((s) => s.userId === claimerId);
+        if (!claimerSummary) {
+            throw new GiftNotFoundError(claimerId);
+        }
+        const claimerUsername = claimerSummary.username;
+        const { claimed, currency, roomId, senderId, message } = await this.drizzle.db.transaction(async (tx) => {
+            // FOR UPDATE serializes concurrent claims against the same gift row under READ COMMITTED.
+            const giftRow = findOneOrThrow(await tx.select().from(playerGift).where(eq(playerGift.id, giftId)).for('update'), new GiftNotFoundError(giftId));
+            try {
+                await this.verifyRoomAccessIfNeeded(giftRow.roomId, claimerId);
+            }
+            catch (error) {
+                if (error instanceof Error && error.name === 'ChatRoomNotMemberError') {
+                    throw new GiftRoomAccessError(giftRow.roomId);
+                }
+                throw error;
+            }
+            if (giftRow.senderId === claimerId) {
+                throw new GiftSelfClaimError();
+            }
+            if (giftRow.claimedBy) {
+                throw new GiftAlreadyClaimedError();
+            }
+            const claimedAt = new Date();
+            // Guarded conditional update: WHERE claimed_by IS NULL stays as defense-in-depth
+            // alongside the row lock above (same pattern as wallet's guarded debit).
+            const results = await tx
+                .update(playerGift)
+                .set({ claimedBy: claimerId, claimedByUsername: claimerUsername, claimedAt })
+                .where(and(eq(playerGift.id, giftId), isNull(playerGift.claimedBy)))
+                .returning();
+            const updated = findOneOrThrow(results, new GiftAlreadyClaimedError());
+            const credit = await this.wallet.credit(tx, {
+                userId: claimerId,
+                amount: updated.amount,
+                currency: updated.currency,
+                type: 'gift',
+            });
+            if (!credit.ok) {
+                throw new GiftCreditError();
+            }
+            await this.audit.recordInTransaction(tx, {
+                actorId: claimerId,
+                actorType: 'player',
+                action: 'chat.gift.claimed',
+                resourceType: 'player_gift',
+                resourceId: giftId,
+                before: null,
+                after: { claimedBy: claimerId, amount: updated.amount },
+            });
+            const updatedMessage = await this.systemWriter.updateSystemMessage({
+                messageId: giftRow.messageId,
+                tx,
+                metadata: {
+                    command: 'gift',
+                    giftId: giftRow.id,
+                    senderId: giftRow.senderId,
+                    senderUsername: giftRow.senderUsername,
+                    amount: giftRow.amount,
+                    currency: updated.currency,
+                    status: 'claimed',
+                    claimedBy: claimerId,
+                    claimedByUsername: claimerUsername,
+                    claimedAt: claimedAt.toISOString(),
+                },
+            });
+            return {
+                claimed: updated,
+                currency: updated.currency,
+                roomId: updated.roomId,
+                senderId: giftRow.senderId,
+                message: updatedMessage,
+            };
+        });
+        const claimedAtIso = claimed.claimedAt?.toISOString() ?? new Date().toISOString();
+        publishChatEvent(this.transport, roomId, message);
+        void this.events.emit('chat.gift.claimed', {
+            giftId,
+            claimerId,
+            claimerUsername,
+            senderId,
+            amount: claimed.amount,
+            currency,
+            roomId,
+        });
+        return {
+            ok: true,
+            claimedBy: claimerId,
+            claimedByUsername: claimerUsername,
+            claimedAt: claimedAtIso,
+        };
+    }
+    async doGetGift(giftId, viewerId) {
+        const rows = await this.drizzle.db.select().from(playerGift).where(eq(playerGift.id, giftId));
+        const giftRow = findOneOrThrow(rows, new GiftNotFoundError(giftId));
+        // Same room-membership boundary as doClaimGift: a viewer must be a member
+        // of the gift's room to poll its status. No FOR UPDATE - read-only, no
+        // mutation, no need to serialize against concurrent claims.
+        try {
+            await this.verifyRoomAccessIfNeeded(giftRow.roomId, viewerId);
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'ChatRoomNotMemberError') {
+                throw new GiftRoomAccessError(giftRow.roomId);
+            }
+            throw error;
+        }
+        return {
+            id: giftRow.id,
+            senderId: giftRow.senderId,
+            senderUsername: giftRow.senderUsername,
+            amount: giftRow.amount,
+            currency: giftRow.currency,
+            claimedBy: giftRow.claimedBy,
+            claimedByUsername: giftRow.claimedByUsername,
+            claimedAt: giftRow.claimedAt ? giftRow.claimedAt.toISOString() : null,
+            createdAt: giftRow.createdAt.toISOString(),
+        };
+    }
+    async doSendRain(input, actorId) {
+        await this.verifyRoomAccessIfNeeded(input.roomId, actorId);
+        const config = await this.loadCommandConfig('rain');
+        if (config?.maxAmount !== undefined &&
+            moneyToNumber(input.amount) > moneyToNumber(config.maxAmount)) {
+            throw new ExceedsLimitError();
+        }
+        if (config?.minAmount !== undefined &&
+            moneyToNumber(input.amount) < moneyToNumber(config.minAmount)) {
+            throw new BelowMinimumError();
+        }
+        const configMax = config?.maxRecipients ?? 50;
+        if (input.recipientCount > configMax) {
+            throw new ExceedsLimitError();
+        }
+        const amountUnits = Math.floor(moneyToNumber(input.amount));
+        if (input.recipientCount > amountUnits) {
+            throw new TooManyRecipientsError();
+        }
+        const senderSummaries = await this.directory.lookupPlayers([actorId]);
+        const sender = senderSummaries.find((s) => s.userId === actorId);
+        if (!sender) {
+            throw new ChatPlayerNotFoundError(actorId);
+        }
+        const fingerprint = fingerprintCommand({ type: 'rain', ...input });
+        const replay = await this.findCommandReplay('rain', actorId, input.idempotencyKey, fingerprint);
+        if (replay) {
+            return replay;
+        }
+        await this.reserveCommandIdempotency('rain', actorId, input.idempotencyKey, fingerprint);
+        // Recipients resolved INSIDE runWithCommandReservation's callback (unlike doSendGift's
+        // pre-reservation directory lookup): runWithCommandReservation only releases the reservation
+        // on a failure inside its own callback, so throwing NoOnlineUsersError here - after
+        // reserveCommandIdempotency but before the callback - would otherwise leak a stuck reservation
+        // for the full TTL. It must also stay after findCommandReplay/reserveCommandIdempotency so a
+        // replay with a now-empty onlineUserIds list (the caller retried after everyone left) still
+        // returns the original stored result instead of a spurious NoOnlineUsersError.
+        const { msg, currency, totalDistributed, recipientIds } = await this.runWithCommandReservation('rain', actorId, input.idempotencyKey, async () => {
+            const recipients = shuffleArray(input.onlineUserIds.filter((id) => id !== actorId)).slice(0, input.recipientCount);
+            if (recipients.length === 0) {
+                throw new NoOnlineUsersError();
+            }
+            const recipientSummaries = await this.directory.lookupPlayers(recipients);
+            const recipientDetails = recipients.map((recipientId) => {
+                const summary = recipientSummaries.find((s) => s.userId === recipientId);
+                if (!summary) {
+                    throw new ChatPlayerNotFoundError(recipientId);
+                }
+                return { userId: summary.userId, username: summary.username };
+            });
+            return this.drizzle.db.transaction(async (tx) => {
+                const splitResult = await tx.execute(sql `SELECT
+              (floor(floor(${input.amount}::numeric) / ${recipients.length}))::text AS per_recipient,
+              (floor(floor(${input.amount}::numeric) / ${recipients.length}) * ${recipients.length})::text AS total_distributed`);
+                const { per_recipient: perRecipient, total_distributed: totalDistributed } = splitResult
+                    .rows[0];
+                const debit = await this.wallet.debit(tx, {
+                    userId: actorId,
+                    amount: totalDistributed,
+                    type: 'rain',
+                });
+                if (!debit.ok) {
+                    throw new InsufficientBalanceError();
+                }
+                const credits = await mapConcurrent(recipients, 10, (userId) => this.wallet.credit(tx, {
+                    userId,
+                    amount: perRecipient,
+                    currency: debit.currency,
+                    type: 'rain',
+                }));
+                if (credits.some((c) => !c.ok)) {
+                    throw new RainCreditError();
+                }
+                const [rainRow] = await tx
+                    .insert(playerRain)
+                    .values({
+                    senderId: actorId,
+                    amount: totalDistributed,
+                    perRecipient,
+                    currency: debit.currency,
+                    roomId: input.roomId,
+                    recipientCount: recipients.length,
+                })
+                    .returning();
+                if (!rainRow) {
+                    throw new RainCreditError();
+                }
+                await tx.insert(playerRainReceiver).values(recipients.map((recipientId) => ({
+                    rainId: rainRow.id,
+                    recipientId,
+                    amount: perRecipient,
+                })));
+                const message = await this.systemWriter.postSystemMessage({
+                    roomId: input.roomId,
+                    actorId,
+                    tx,
+                    metadata: {
+                        command: 'rain',
+                        fromUserId: actorId,
+                        fromUsername: sender.username,
+                        amount: totalDistributed,
+                        currency: debit.currency,
+                        recipientCount: recipients.length,
+                        perRecipient,
+                        recipients: recipientDetails,
+                    },
+                });
+                await this.audit.recordInTransaction(tx, {
+                    actorId,
+                    actorType: 'player',
+                    action: 'chat.rain',
+                    resourceType: 'player_rain',
+                    resourceId: rainRow.id,
+                    before: null,
+                    after: { amount: totalDistributed, recipientCount: recipients.length },
+                });
+                return {
+                    msg: message,
+                    currency: debit.currency,
+                    totalDistributed,
+                    perRecipient,
+                    recipientIds: recipients,
+                };
+            });
+        });
+        await this.completeCommandIdempotency('rain', actorId, input.idempotencyKey, fingerprint, msg);
+        // The caller now owns the commit boundary: postSystemMessage was passed `tx` above so
+        // it did not auto-publish - publish only now that this transaction has committed.
+        publishChatEvent(this.transport, input.roomId, msg);
+        void this.events.emit('chat.rain.distributed', {
+            fromUserId: actorId,
+            recipients: recipientIds,
+            recipientCount: recipientIds.length,
+            totalAmount: totalDistributed,
+            currency,
+            roomId: input.roomId,
+        });
+        return msg;
+    }
+    async doSendDonate(input, actorId) {
+        await this.verifyRoomAccessIfNeeded(input.roomId, actorId);
+        const config = await this.loadCommandConfig('donate');
+        if (config?.maxAmount !== undefined &&
+            moneyToNumber(input.amount) > moneyToNumber(config.maxAmount)) {
+            throw new ExceedsLimitError();
+        }
+        if (config?.minAmount !== undefined &&
+            moneyToNumber(input.amount) < moneyToNumber(config.minAmount)) {
+            throw new BelowMinimumError();
+        }
+        const target = await this.resolveExactPlayer(input.targetUsername);
+        if (target.userId === actorId) {
+            throw new DonateSelfError();
+        }
+        const senderSummaries = await this.directory.lookupPlayers([actorId]);
+        const sender = senderSummaries.find((s) => s.userId === actorId);
+        if (!sender) {
+            throw new ChatPlayerNotFoundError(actorId);
+        }
+        const fingerprint = fingerprintCommand({ type: 'donate', ...input });
+        const replay = await this.findCommandReplay('donate', actorId, input.idempotencyKey, fingerprint);
+        if (replay) {
+            return replay;
+        }
+        await this.reserveCommandIdempotency('donate', actorId, input.idempotencyKey, fingerprint);
+        const { msg, currency } = await this.runWithCommandReservation('donate', actorId, input.idempotencyKey, () => this.drizzle.db.transaction(async (tx) => {
+            const debit = await this.wallet.debit(tx, {
+                userId: actorId,
+                amount: input.amount,
+                type: 'tip',
+            });
+            if (!debit.ok) {
+                throw new InsufficientBalanceError();
+            }
+            const credit = await this.wallet.credit(tx, {
+                userId: target.userId,
+                amount: input.amount,
+                currency: debit.currency,
+                type: 'tip',
+            });
+            if (!credit.ok) {
+                throw new ChatPlayerNotFoundError(target.userId);
+            }
+            const message = await this.systemWriter.postSystemMessage({
+                roomId: input.roomId,
+                actorId,
+                tx,
+                metadata: {
+                    command: 'donate',
+                    senderId: actorId,
+                    senderUsername: sender.username,
+                    recipientId: target.userId,
+                    recipientUsername: target.username,
+                    amount: input.amount,
+                    currency: debit.currency,
+                },
+            });
+            const [donateRow] = await tx
+                .insert(playerDonate)
+                .values({
+                senderId: actorId,
+                senderUsername: sender.username,
+                recipientId: target.userId,
+                recipientUsername: target.username,
+                amount: input.amount,
+                currency: debit.currency,
+                roomId: input.roomId,
+            })
+                .returning();
+            if (!donateRow) {
+                throw new ChatPlayerNotFoundError(target.userId);
+            }
+            await this.audit.recordInTransaction(tx, {
+                actorId,
+                actorType: 'player',
+                action: 'chat.donate',
+                resourceType: 'player_donate',
+                resourceId: donateRow.id,
+                before: null,
+                after: { recipientId: target.userId, amount: input.amount, currency: debit.currency },
+            });
+            return { msg: message, currency: debit.currency };
+        }));
+        await this.completeCommandIdempotency('donate', actorId, input.idempotencyKey, fingerprint, msg);
+        publishChatEvent(this.transport, input.roomId, msg);
+        void this.events.emit('chat.donate.sent', {
+            senderId: actorId,
+            senderUsername: sender.username,
+            recipientId: target.userId,
+            recipientUsername: target.username,
+            amount: input.amount,
+            currency,
+            roomId: input.roomId,
+        });
+        return msg;
+    }
+}
+//# sourceMappingURL=social-transfers.service.js.map