feat(api-service,framework): add rich content support and onAction handler for agent cards fixes NV-7363

apps/api/src/app/agents/dtos/agent-event.enum.ts

@@ -1,4 +1,5 @@
 export enum AgentEventEnum {
   ON_MESSAGE = 'onMessage',
+  ON_ACTION = 'onAction',
   ON_RESOLVE = 'onResolve',
 }

apps/api/src/app/agents/dtos/agent-reply-payload.dto.ts

@@ -2,24 +2,72 @@ import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
 import {
   IsArray,
-  IsDefined,
   IsIn,
   IsNotEmpty,
   IsObject,
   IsOptional,
   IsString,
   MaxLength,
+  Validate,
   ValidateNested,
+  ValidatorConstraint,
+  ValidatorConstraintInterface,
 } from 'class-validator';
 
 const SIGNAL_TYPES = ['metadata', 'trigger'] as const;
 
-export class TextContentDto {
-  @ApiProperty()
+export interface FileRef {
+  filename: string;
+  mimeType?: string;
+  data?: string;
+  url?: string;
+}
+
+@ValidatorConstraint({ name: 'isValidReplyContent', async: false })
+export class IsValidReplyContent implements ValidatorConstraintInterface {
+  validate(content: ReplyContentDto): boolean {
+    if (!content) return true;
+
+    const fields = [content.text, content.markdown, content.card].filter((v) => v !== undefined);
+    if (fields.length !== 1) return false;
+
+    if (content.files?.length && !content.markdown) return false;
+
+    for (const file of content.files ?? []) {
+      const sources = [file.data, file.url].filter(Boolean);
+      if (sources.length !== 1) return false;
+    }
+
+    return true;
+  }
+
+  defaultMessage(): string {
+    return 'Content must have exactly one of text, markdown, or card. Files only allowed with markdown. Each file needs exactly one of data or url.';
+  }
+}
+
+export class ReplyContentDto {
+  @ApiPropertyOptional()
+  @IsOptional()
   @IsString()
   @IsNotEmpty()
   @MaxLength(40_000)
-  text: string;
+  text?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  markdown?: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsObject()
+  card?: Record<string, unknown>;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsArray()
+  files?: FileRef[];
 }
 
 export class ResolveDto {
@@ -71,19 +119,21 @@ export class AgentReplyPayloadDto {
   @IsNotEmpty()
   integrationIdentifier: string;
 
-  @ApiPropertyOptional({ type: TextContentDto })
+  @ApiPropertyOptional({ type: ReplyContentDto })
   @IsOptional()
   @IsObject()
   @ValidateNested()
-  @Type(() => TextContentDto)
-  reply?: TextContentDto;
+  @Validate(IsValidReplyContent)
+  @Type(() => ReplyContentDto)
+  reply?: ReplyContentDto;
 
-  @ApiPropertyOptional({ type: TextContentDto })
+  @ApiPropertyOptional({ type: ReplyContentDto })
   @IsOptional()
   @IsObject()
   @ValidateNested()
-  @Type(() => TextContentDto)
-  update?: TextContentDto;
+  @Validate(IsValidReplyContent)
+  @Type(() => ReplyContentDto)
+  update?: ReplyContentDto;
 
   @ApiPropertyOptional({ type: ResolveDto })
   @IsOptional()

apps/api/src/app/agents/e2e/mock-agent-handler.ts

@@ -15,7 +15,19 @@
  *   5. @mention the bot in Slack — watch the round-trip in the logs
  */
 
-import { agent, Client, serve } from '@novu/framework/express';
+import {
+  agent,
+  serve,
+  Client,
+  Actions,
+  Button,
+  Card,
+  CardLink,
+  CardText,
+  Divider,
+  Select,
+  SelectOption,
+} from '@novu/framework/express';
 import express from 'express';
 
 const NOVU_SECRET_KEY = process.env.NOVU_SECRET_KEY;
@@ -47,9 +59,109 @@ const echoBot = agent('novu-agent', {
       return;
     }
 
+    if (userText.toLowerCase().includes('card')) {
+      await ctx.reply(
+        Card({
+          title: `Order #${Math.floor(Math.random() * 9000) + 1000}`,
+          children: [
+            CardText('Your order is ready for pickup.'),
+            Actions([
+              Button({ id: 'confirm', label: 'Confirm Pickup', style: 'primary' }),
+              Button({ id: 'cancel', label: 'Cancel Order', style: 'danger' }),
+            ]),
+          ],
+        })
+      );
+
+      return;
+    }
+
+    if (userText.toLowerCase().includes('incident')) {
+      await ctx.reply(
+        Card({
+          title: `Incident #${Math.floor(Math.random() * 9000) + 1000} — DB Latency Spike`,
+          children: [
+            CardText('*P1 — Production database latency spike*'),
+            CardText('Detected at 14:32 UTC. Response times exceeded 2s threshold for 3 minutes.'),
+            Divider(),
+            CardText('*Status:* Investigating  |  *Service:* payments-api  |  *Region:* us-east-1'),
+            Divider(),
+            Select({
+              id: 'assign',
+              label: 'Assign to on-call',
+              options: [
+                SelectOption({ value: 'alice', label: 'Alice Chen' }),
+                SelectOption({ value: 'bob', label: 'Bob Martinez' }),
+                SelectOption({ value: 'carol', label: 'Carol Wu' }),
+              ],
+            }),
+            Actions([
+              Button({ id: 'ack', label: 'Acknowledge', style: 'primary' }),
+              Button({ id: 'escalate', label: 'Escalate', style: 'danger' }),
+            ]),
+            CardLink({ url: 'https://grafana.example.com/d/abc', label: 'View Grafana Dashboard' }),
+          ],
+        })
+      );
+
+      return;
+    }
+
+    if (userText.toLowerCase().includes('markdown')) {
+      await ctx.reply({
+        markdown: [
+          `**Echo:** ${userText}`,
+          '',
+          '| Metric | Value |',
+          '|--------|-------|',
+          '| Latency | 142ms |',
+          '| Throughput | 1.2k rps |',
+          '| Error rate | 0.02% |',
+          '',
+          '> Sent from _Novu Agent Framework_',
+        ].join('\n'),
+      });
+
+      return;
+    }
+
     await ctx.reply(`Echo: ${userText}`);
   },
 
+  onAction: async (ctx) => {
+    console.log('\n─────────────────────────────────────────');
+    console.log(`[${ctx.event}] action: ${ctx.action?.actionId} = ${ctx.action?.value ?? '(no value)'}`);
+    console.log('─────────────────────────────────────────');
+
+    const actionId = ctx.action?.actionId ?? 'unknown';
+    const value = ctx.action?.value;
+
+    if (actionId === 'ack') {
+      await ctx.reply(
+        Card({
+          title: 'Incident Acknowledged',
+          children: [
+            CardText(
+              `Acknowledged by *${ctx.subscriber?.firstName ?? 'unknown'}* at ${new Date().toLocaleTimeString()}.`
+            ),
+            Actions([Button({ id: 'resolve', label: 'Resolve Incident', style: 'primary' })]),
+          ],
+        })
+      );
+    } else if (actionId === 'resolve') {
+      ctx.resolve('Incident resolved via action');
+      await ctx.reply(`Incident resolved by *${ctx.subscriber?.firstName ?? 'unknown'}*.`);
+    } else if (actionId === 'assign') {
+      await ctx.reply(`On-call assignment updated to *${value}*.`);
+    } else if (actionId === 'escalate') {
+      await ctx.reply({
+        markdown: `**Escalated** — paging the secondary on-call team.\n\n_Triggered by ${ctx.subscriber?.firstName ?? 'unknown'}_`,
+      });
+    } else {
+      await ctx.reply(`Got action: *${actionId}*${value ? ` = ${value}` : ''}`);
+    }
+  },
+
   onResolve: async (ctx) => {
     console.log(`\n[onResolve] Conversation ${ctx.conversation.identifier} closed.`);
     ctx.metadata.set('resolvedAt', new Date().toISOString());
@@ -70,7 +182,12 @@ app.use(
   })
 );
 
-app.listen(PORT, () => {
+const server = app.listen(PORT, () => {
   console.log(`\nAgent Handler (using @novu/framework) running on http://localhost:${PORT}/api/novu`);
   console.log('\nWaiting for bridge calls...\n');
 });
+
+server.on('error', (err) => console.error('Server error:', err));
+server.on('close', () => console.log('Server closed'));
+process.on('uncaughtException', (err) => console.error('Uncaught:', err));
+process.on('unhandledRejection', (err) => console.error('Unhandled rejection:', err));

apps/api/src/app/agents/services/agent-inbound-handler.service.ts

@@ -3,10 +3,10 @@ import { PinoLogger } from '@novu/application-generic';
 import { ConversationActivitySenderTypeEnum, ConversationParticipantTypeEnum, SubscriberRepository } from '@novu/dal';
 import type { Message, Thread } from 'chat';
 import { AgentEventEnum } from '../dtos/agent-event.enum';
-import { ResolvedPlatformConfig } from './agent-credential.service';
 import { AgentConversationService } from './agent-conversation.service';
+import { ResolvedPlatformConfig } from './agent-credential.service';
 import { AgentSubscriberResolver } from './agent-subscriber-resolver.service';
-import { BridgeExecutorService } from './bridge-executor.service';
+import { type BridgeAction, BridgeExecutorService } from './bridge-executor.service';
 
 @Injectable()
 export class AgentInboundHandler {
@@ -107,4 +107,78 @@ export class AgentInboundHandler {
       },
     });
   }
+
+  async handleAction(
+    agentId: string,
+    config: ResolvedPlatformConfig,
+    thread: Thread,
+    action: BridgeAction,
+    userId: string
+  ): Promise<void> {
+    const subscriberId = await this.subscriberResolver
+      .resolve({
+        environmentId: config.environmentId,
+        organizationId: config.organizationId,
+        platform: config.platform,
+        platformUserId: userId,
+        integrationIdentifier: config.integrationIdentifier,
+      })
+      .catch((err) => {
+        this.logger.warn(
+          err,
+          `[agent:${agentId}] Subscriber resolution failed for action, continuing without subscriber`
+        );
+
+        return null;
+      });
+
+    const participantId = subscriberId ?? `${config.platform}:${userId}`;
+    const participantType = subscriberId
+      ? ConversationParticipantTypeEnum.SUBSCRIBER
+      : ConversationParticipantTypeEnum.PLATFORM_USER;
+
+    const conversation = await this.conversationService.createOrGetConversation({
+      environmentId: config.environmentId,
+      organizationId: config.organizationId,
+      agentId,
+      platform: config.platform,
+      integrationId: config.integrationId,
+      platformThreadId: thread.id,
+      participantId,
+      participantType,
+      platformUserId: userId,
+      firstMessageText: `[action:${action.actionId}]`,
+    });
+
+    const serializedThread = thread.toJSON() as unknown as Record<string, unknown>;
+    await this.conversationService.updateChannelThread(
+      config.environmentId,
+      config.organizationId,
+      conversation._id,
+      thread.id,
+      serializedThread
+    );
+
+    const [subscriber, history] = await Promise.all([
+      subscriberId
+        ? this.subscriberRepository.findBySubscriberId(config.environmentId, subscriberId)
+        : Promise.resolve(null),
+      this.conversationService.getHistory(config.environmentId, conversation._id),
+    ]);
+
+    await this.bridgeExecutor.execute({
+      event: AgentEventEnum.ON_ACTION,
+      config,
+      conversation,
+      subscriber,
+      history,
+      message: null,
+      platformContext: {
+        threadId: thread.id,
+        channelId: thread.channelId,
+        isDM: thread.isDM,
+      },
+      action,
+    });
+  }
 }