fix(chat): adding metadata to system messages and more

docs/catalog.json

@@ -1032,6 +1032,10 @@
       "name": "ClientMetaSchema",
       "file": "packages/core/src/contracts/schemas/common.ts"
     },
+    {
+      "name": "CommandChatMessageSchema",
+      "file": "packages/core/src/contracts/schemas/chat-command.ts"
+    },
     {
       "name": "CommandConfigSchema",
       "file": "packages/core/src/engagement/chat-commands/contract/index.ts"

packages/core/src/contracts/adapters/chat-system-writer.ts

@@ -1,7 +1,12 @@
 import { createToken } from './token.js';
-import type { SystemChatMessage, CommandMetadata } from '../schemas/chat-command.js';
+import type {
+  SystemChatMessage,
+  CommandChatMessage,
+  CommandMetadata,
+} from '../schemas/chat-command.js';
 
 export type { SystemChatMessage as ChatSystemMessage };
+export type { CommandChatMessage };
 
 export type ChatSystemWriter = {
   postSystemMessage(args: {
@@ -10,6 +15,18 @@ export type ChatSystemWriter = {
     metadata: CommandMetadata;
     tx?: unknown;
   }): Promise<SystemChatMessage>;
+  postCommandMessage(args: {
+    roomId: string | null;
+    userId: string;
+    username: string;
+    metadata: CommandMetadata;
+    tx?: unknown;
+  }): Promise<CommandChatMessage>;
+  updateCommandMessage(args: {
+    messageId: string;
+    metadata: CommandMetadata;
+    tx?: unknown;
+  }): Promise<CommandChatMessage>;
 };
 
 export const CHAT_SYSTEM_WRITER = createToken<ChatSystemWriter>('ChatSystemWriter');

packages/core/src/contracts/adapters/gift-commands.ts

@@ -8,7 +8,7 @@
 // AGENTS.md).
 import { createToken, type Token } from './token.js';
 import type { Uuid } from '../schemas/common.js';
-import type { ChatSystemMessage as SystemChatMessage } from './chat-system-writer.js';
+import type { CommandChatMessage } from './chat-system-writer.js';
 
 export type SendGiftArgs = {
   amount: string;
@@ -27,7 +27,7 @@ export type SendGiftFailureReason =
   | 'room_not_member';
 
 export type SendGiftResult =
-  | { ok: true; message: SystemChatMessage }
+  | { ok: true; message: CommandChatMessage }
   | { ok: false; reason: SendGiftFailureReason };
 
 export type ClaimGiftFailureReason =

packages/core/src/contracts/adapters/index.ts

@@ -199,7 +199,11 @@ export { LOGIN_ENFORCEMENT } from './login-enforcement.js';
 export type { PlayEligibilityPort } from './play-eligibility.js';
 export { PLAY_ELIGIBILITY } from './play-eligibility.js';
 
-export type { ChatSystemMessage, ChatSystemWriter } from './chat-system-writer.js';
+export type {
+  ChatSystemMessage,
+  CommandChatMessage,
+  ChatSystemWriter,
+} from './chat-system-writer.js';
 export { CHAT_SYSTEM_WRITER } from './chat-system-writer.js';
 
 export type { ChatBlockWriter } from './chat-block-writer.js';

packages/core/src/contracts/adapters/rain-commands.ts

@@ -9,7 +9,7 @@
 // import. ADR-0017.
 import { createToken, type Token } from './token.js';
 import type { Uuid } from '../schemas/common.js';
-import type { ChatSystemMessage } from './chat-system-writer.js';
+import type { CommandChatMessage } from './chat-system-writer.js';
 
 export type SendRainArgs = {
   amount: string;
@@ -36,7 +36,7 @@ export type SendRainFailureReason =
   | 'room_not_member';
 
 export type SendRainResult =
-  | { ok: true; message: ChatSystemMessage }
+  | { ok: true; message: CommandChatMessage }
   | { ok: false; reason: SendRainFailureReason };
 
 export type RainCommands = {

packages/core/src/contracts/schemas/chat-command-metadata.ts

@@ -16,16 +16,31 @@ export const GiftCommandMetadataSchema = z.object({
   senderUsername: z.string(),
   amount: MoneyAmountSchema,
   currency: z.string(),
+  // Optional for compatibility with gift messages persisted before claim state
+  // was included in command metadata. New gift messages always populate these.
+  status: z.enum(['available', 'claimed']).optional(),
+  claimedBy: UuidSchema.nullable().optional(),
+  claimedByUsername: z.string().nullable().optional(),
+  claimedAt: z.string().nullable().optional(),
 });
 export type GiftCommandMetadata = z.infer<typeof GiftCommandMetadataSchema>;
 
 export const RainCommandMetadataSchema = z.object({
   command: z.literal('rain'),
   fromUserId: UuidSchema,
+  fromUsername: z.string().optional(),
   amount: MoneyAmountSchema,
   currency: z.string(),
   recipientCount: z.number().int(),
   perRecipient: MoneyAmountSchema,
+  recipients: z
+    .array(
+      z.object({
+        userId: UuidSchema,
+        username: z.string(),
+      }),
+    )
+    .optional(),
 });
 export type RainCommandMetadata = z.infer<typeof RainCommandMetadataSchema>;
 
@@ -59,6 +74,8 @@ export type UnignoreCommandMetadata = z.infer<typeof UnignoreCommandMetadataSche
 
 export const DonateCommandMetadataSchema = z.object({
   command: z.literal('donate'),
+  senderId: UuidSchema.optional(),
+  senderUsername: z.string().optional(),
   recipientId: UuidSchema,
   recipientUsername: z.string(),
   amount: MoneyAmountSchema,

packages/core/src/contracts/schemas/chat-command.ts

@@ -37,6 +37,20 @@ export const SystemChatMessageSchema = z.object({
 });
 export type SystemChatMessage = z.infer<typeof SystemChatMessageSchema>;
 
+/** A user-authored chat message carrying structured command metadata. */
+export const CommandChatMessageSchema = z.object({
+  id: UuidSchema,
+  roomId: UuidSchema.nullable(),
+  userId: UuidSchema,
+  username: z.string(),
+  content: z.string(),
+  type: z.literal('user'),
+  metadata: CommandMetadataSchema,
+  isDeleted: z.boolean(),
+  createdAt: z.string(),
+});
+export type CommandChatMessage = z.infer<typeof CommandChatMessageSchema>;
+
 /**
  * Client-facing sentinel for global chat wherever a chat command's `roomId`
  * field is otherwise a real room UUID (`/gift`, `/rain`, `/donate`) - the

packages/core/src/engagement/chat-commands/contract/index.ts

@@ -4,6 +4,7 @@ import {
   UuidSchema,
   MoneyAmountSchema,
   SystemChatMessageSchema,
+  CommandChatMessageSchema,
   ChatRoomIdSchema,
   TimestampSchema,
 } from '@openora/core/contracts';
@@ -50,7 +51,7 @@ export const MentionResultSchema = z.object({
 });
 export type MentionResult = z.infer<typeof MentionResultSchema>;
 
-export { SystemChatMessageSchema };
+export { SystemChatMessageSchema, CommandChatMessageSchema };
 
 export const PostGiftInputSchema = z.object({
   amount: MoneyAmountSchema,
@@ -99,7 +100,7 @@ export const chatCommandsContract = {
   postGift: oc
     .route({ method: 'POST', path: '/chat-command/gift' })
     .input(PostGiftInputSchema)
-    .output(SystemChatMessageSchema),
+    .output(CommandChatMessageSchema),
 
   claimGift: oc
     .route({ method: 'POST', path: '/chat-command/gift/{id}/claim' })
@@ -118,7 +119,7 @@ export const chatCommandsContract = {
   postRain: oc
     .route({ method: 'POST', path: '/chat-command/rain' })
     .input(PostRainInputSchema)
-    .output(SystemChatMessageSchema),
+    .output(CommandChatMessageSchema),
 
   mentionSearch: oc
     .route({ method: 'GET', path: '/chat-command/mention-search' })

packages/core/src/engagement/chat-commands/service/__tests__/chat-commands.service.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi } from 'vitest';
 import { mock, makeDrizzle } from '../../../../testing/mock.js';
 import type {
-  ChatSystemMessage,
+  CommandChatMessage,
   ChatBlockWriter,
   AdminUserDirectory,
   GiftCommands,
@@ -41,18 +41,25 @@ const ENABLED_ROW = {
 
 const DISABLED_ROW = { ...ENABLED_ROW, enabled: false };
 
-const SYSTEM_MSG: ChatSystemMessage = {
+const SYSTEM_MSG: CommandChatMessage = {
   id: MSG_ID,
   roomId: ROOM_ID,
-  actorId: ACTOR_ID,
+  userId: ACTOR_ID,
+  username: 'bob',
   content: '',
+  type: 'user',
+  isDeleted: false,
   metadata: {
     command: 'gift',
     giftId: GIFT_ID,
     senderId: ACTOR_ID,
     senderUsername: 'bob',
     amount: '10.00000000',
     currency: 'USD',
+    status: 'available',
+    claimedBy: null,
+    claimedByUsername: null,
+    claimedAt: null,
   },
   createdAt: new Date().toISOString(),
 };

packages/core/src/engagement/chat-commands/service/chat-commands.service.ts

@@ -9,7 +9,7 @@ import {
 } from '@openora/core/server';
 import type {
   Uuid,
-  ChatSystemMessage,
+  CommandChatMessage,
   ChatBlockWriter,
   AdminUserDirectory,
   GiftCommands,
@@ -193,7 +193,7 @@ export class ChatCommandsService {
     return summaries.map((s) => ({ userId: s.userId, username: s.username }));
   }
 
-  async postGift(input: PostGiftInput, actorId: Uuid): Promise<ChatSystemMessage> {
+  async postGift(input: PostGiftInput, actorId: Uuid): Promise<CommandChatMessage> {
     const result = await this.giftCommands.sendGift(input, actorId);
     if (result.ok) {
       return result.message;
@@ -258,7 +258,7 @@ export class ChatCommandsService {
   // who is online (it owns presence for the whole chat-command surface via
   // its own dependency on `chat`) and translates the port's discriminated
   // result into the typed errors this module's router maps to transport codes.
-  async postRain(input: PostRainInput, actorId: Uuid): Promise<ChatSystemMessage> {
+  async postRain(input: PostRainInput, actorId: Uuid): Promise<CommandChatMessage> {
     const onlineUserIds = await this.transport.getOnlineUserIds(chatChannel(input.roomId));
     const result = await this.rainCommands.sendRain({ ...input, onlineUserIds }, actorId);
     if (result.ok) {

packages/core/src/engagement/chat/service/chat.service.ts

@@ -18,6 +18,7 @@ import type {
   RealtimeTransport,
   CommandMetadata,
   ChatSystemMessage,
+  CommandChatMessage,
   AdminUserDirectory,
 } from '@openora/core/contracts';
 import { chatChannel } from '@openora/core/contracts';
@@ -1185,6 +1186,50 @@ export class ChatService {
     return msg;
   }
 
+  async postCommandMessage(args: {
+    roomId: ChatRoom['id'] | null;
+    userId: User['id'];
+    username: string;
+    metadata: CommandMetadata;
+    tx?: unknown;
+  }): Promise<CommandChatMessage> {
+    const db = (args.tx as DrizzleDb | undefined) ?? this.drizzle.db;
+    const [record] = await db
+      .insert(chatMessage)
+      .values({
+        roomId: args.roomId,
+        userId: args.userId,
+        username: args.username,
+        content: '',
+        type: 'user',
+        metadata: args.metadata,
+      })
+      .returning();
+    const message = toMessage(record);
+    if (!args.tx) {
+      void this.transport.publish(chatChannel(args.roomId), message);
+    }
+    return message as CommandChatMessage;
+  }
+
+  async updateCommandMessage(args: {
+    messageId: ChatMessage['id'];
+    metadata: CommandMetadata;
+    tx?: unknown;
+  }): Promise<CommandChatMessage> {
+    const db = (args.tx as DrizzleDb | undefined) ?? this.drizzle.db;
+    const [record] = await db
+      .update(chatMessage)
+      .set({ metadata: args.metadata })
+      .where(eq(chatMessage.id, args.messageId))
+      .returning();
+    const message = toMessage(record);
+    if (!args.tx) {
+      void this.transport.publish(chatChannel(message.roomId), message);
+    }
+    return message as CommandChatMessage;
+  }
+
   async listRoomMembers({ roomId, viewerId }: { roomId: ChatRoom['id']; viewerId?: User['id'] }) {
     await this.verifyRoomAccess(roomId, viewerId);
     const members = await this.drizzle.db

packages/core/src/engagement/social-transfers/contract/index.ts

@@ -4,10 +4,11 @@ import {
   UuidSchema,
   MoneyAmountSchema,
   SystemChatMessageSchema,
+  CommandChatMessageSchema,
   ChatRoomIdSchema,
 } from '@openora/core/contracts';
 
-export { SystemChatMessageSchema };
+export { SystemChatMessageSchema, CommandChatMessageSchema };
 
 export const SendDonateInputSchema = z.object({
   targetUsername: z.string().min(1),
@@ -25,5 +26,5 @@ export const socialTransfersContract = {
   sendDonate: oc
     .route({ method: 'POST', path: '/social-transfers/donate' })
     .input(SendDonateInputSchema)
-    .output(SystemChatMessageSchema),
+    .output(CommandChatMessageSchema),
 };