feat(api-service): per-agent bridge URL with dev/production toggle fixes NV-7373

apps/api/src/app/agents/agents.controller.ts

@@ -9,6 +9,7 @@ import {
   Param,
   Patch,
   Post,
+  Put,
   Query,
   UseGuards,
   UseInterceptors,
@@ -17,6 +18,7 @@ import { ApiExcludeController, ApiOperation } from '@nestjs/swagger';
 import { RequirePermissions } from '@novu/application-generic';
 import { ApiRateLimitCategoryEnum, DirectionEnum, PermissionsEnum, UserSessionData } from '@novu/shared';
 import { RequireAuthentication } from '../auth/framework/auth.decorator';
+import { ExternalApiAccessible } from '../auth/framework/external-api.decorator';
 import { ThrottlerCategory } from '../rate-limiting/guards';
 import {
   ApiCommonResponses,
@@ -34,6 +36,7 @@ import {
   ListAgentIntegrationsResponseDto,
   ListAgentsQueryDto,
   ListAgentsResponseDto,
+  UpdateAgentBridgeRequestDto,
   UpdateAgentIntegrationRequestDto,
   UpdateAgentRequestDto,
 } from './dtos';
@@ -240,6 +243,36 @@ export class AgentsController {
     );
   }
 
+  @Put('/:identifier/bridge')
+  @ApiResponse(AgentResponseDto)
+  @ApiOperation({
+    summary: 'Update agent bridge configuration',
+    description:
+      'Updates the bridge URL configuration for an agent. Used by the CLI to register dev tunnel URLs. Refuses to activate dev bridges on production environments.',
+  })
+  @ApiNotFoundResponse({
+    description: 'The agent was not found.',
+  })
+  @ExternalApiAccessible()
+  @RequirePermissions(PermissionsEnum.AGENT_WRITE)
+  updateAgentBridge(
+    @UserSession() user: UserSessionData,
+    @Param('identifier') identifier: string,
+    @Body() body: UpdateAgentBridgeRequestDto
+  ): Promise<AgentResponseDto> {
+    return this.updateAgentUsecase.execute(
+      UpdateAgentCommand.create({
+        userId: user._id,
+        environmentId: user.environmentId,
+        organizationId: user.organizationId,
+        identifier,
+        bridgeUrl: body.bridgeUrl,
+        devBridgeUrl: body.devBridgeUrl,
+        devBridgeActive: body.devBridgeActive,
+      })
+    );
+  }
+
   @Get('/:identifier')
   @ApiResponse(AgentResponseDto)
   @ApiOperation({
@@ -285,6 +318,9 @@ export class AgentsController {
         description: body.description,
         active: body.active,
         behavior: body.behavior,
+        bridgeUrl: body.bridgeUrl,
+        devBridgeUrl: body.devBridgeUrl,
+        devBridgeActive: body.devBridgeActive,
       })
     );
   }

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

@@ -22,6 +22,15 @@ export class AgentResponseDto {
   @ApiProperty()
   active: boolean;
 
+  @ApiPropertyOptional({ description: 'Production bridge URL' })
+  bridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Development bridge URL (set by npx novu dev)' })
+  devBridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Whether the dev bridge override is active' })
+  devBridgeActive?: boolean;
+
   @ApiProperty()
   _environmentId: string;
 

apps/api/src/app/agents/dtos/index.ts

@@ -9,4 +9,5 @@ export * from './list-agent-integrations-response.dto';
 export * from './list-agents-query.dto';
 export * from './list-agents-response.dto';
 export * from './update-agent-integration-request.dto';
+export * from './update-agent-bridge-request.dto';
 export * from './update-agent-request.dto';

apps/api/src/app/agents/dtos/update-agent-bridge-request.dto.ts

@@ -0,0 +1,19 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsBoolean, IsOptional, IsUrl } from 'class-validator';
+
+export class UpdateAgentBridgeRequestDto {
+  @ApiPropertyOptional({ description: 'Production bridge URL for this agent' })
+  @IsUrl({ require_tld: false })
+  @IsOptional()
+  bridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Development bridge URL (set by npx novu dev)' })
+  @IsUrl({ require_tld: false })
+  @IsOptional()
+  devBridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Whether the dev bridge override is active' })
+  @IsBoolean()
+  @IsOptional()
+  devBridgeActive?: boolean;
+}

apps/api/src/app/agents/dtos/update-agent-request.dto.ts

@@ -1,6 +1,6 @@
 import { ApiPropertyOptional } from '@nestjs/swagger';
 import { Type } from 'class-transformer';
-import { IsBoolean, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { IsBoolean, IsOptional, IsString, IsUrl, ValidateNested } from 'class-validator';
 
 import { AgentBehaviorDto } from './agent-behavior.dto';
 
@@ -25,4 +25,19 @@ export class UpdateAgentRequestDto {
   @Type(() => AgentBehaviorDto)
   @IsOptional()
   behavior?: AgentBehaviorDto;
+
+  @ApiPropertyOptional({ description: 'Production bridge URL for this agent' })
+  @IsUrl({ require_tld: false })
+  @IsOptional()
+  bridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Development bridge URL (set by npx novu dev)' })
+  @IsUrl({ require_tld: false })
+  @IsOptional()
+  devBridgeUrl?: string;
+
+  @ApiPropertyOptional({ description: 'Whether the dev bridge override is active' })
+  @IsBoolean()
+  @IsOptional()
+  devBridgeActive?: boolean;
 }

apps/api/src/app/agents/e2e/agents.e2e.ts

@@ -299,4 +299,141 @@ describe('Agents API - /agents #novu-v2', () => {
 
     expect(agentAfter).to.equal(null);
   });
+
+  describe('Bridge URL management', () => {
+    let identifier: string;
+
+    beforeEach(async () => {
+      identifier = `e2e-bridge-${Date.now()}`;
+      await session.testAgent.post('/v1/agents').send({ name: 'Bridge Agent', identifier });
+    });
+
+    afterEach(async () => {
+      await session.testAgent.delete(`/v1/agents/${encodeURIComponent(identifier)}`);
+    });
+
+    it('should update bridgeUrl via PATCH', async () => {
+      const res = await session.testAgent.patch(`/v1/agents/${encodeURIComponent(identifier)}`).send({
+        bridgeUrl: 'https://prod.example.com/api/novu',
+      });
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.bridgeUrl).to.equal('https://prod.example.com/api/novu');
+    });
+
+    it('should update devBridgeUrl and devBridgeActive via PUT bridge endpoint', async () => {
+      const res = await session.testAgent.put(`/v1/agents/${encodeURIComponent(identifier)}/bridge`).send({
+        devBridgeUrl: 'https://tunnel.example.com',
+        devBridgeActive: true,
+      });
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.devBridgeUrl).to.equal('https://tunnel.example.com');
+      expect(res.body.data.devBridgeActive).to.equal(true);
+    });
+
+    it('should set bridgeUrl via PUT bridge endpoint', async () => {
+      const res = await session.testAgent.put(`/v1/agents/${encodeURIComponent(identifier)}/bridge`).send({
+        bridgeUrl: 'https://prod.example.com/novu',
+      });
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.bridgeUrl).to.equal('https://prod.example.com/novu');
+    });
+
+    it('should return bridge fields on GET', async () => {
+      await session.testAgent.patch(`/v1/agents/${encodeURIComponent(identifier)}`).send({
+        bridgeUrl: 'https://prod.example.com/api/novu',
+        devBridgeUrl: 'https://tunnel.example.com',
+        devBridgeActive: true,
+      });
+
+      const res = await session.testAgent.get(`/v1/agents/${encodeURIComponent(identifier)}`);
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.bridgeUrl).to.equal('https://prod.example.com/api/novu');
+      expect(res.body.data.devBridgeUrl).to.equal('https://tunnel.example.com');
+      expect(res.body.data.devBridgeActive).to.equal(true);
+    });
+
+    it('should deactivate devBridgeActive', async () => {
+      await session.testAgent.patch(`/v1/agents/${encodeURIComponent(identifier)}`).send({
+        devBridgeUrl: 'https://tunnel.example.com',
+        devBridgeActive: true,
+      });
+
+      const res = await session.testAgent.patch(`/v1/agents/${encodeURIComponent(identifier)}`).send({
+        devBridgeActive: false,
+      });
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.devBridgeActive).to.equal(false);
+      expect(res.body.data.devBridgeUrl).to.equal('https://tunnel.example.com');
+    });
+  });
+
+  describe('Production environment guard', () => {
+    let prodSession: UserSession;
+    let identifier: string;
+
+    before(async () => {
+      prodSession = new UserSession();
+      await prodSession.initialize();
+    });
+
+    beforeEach(async () => {
+      identifier = `e2e-prodguard-${Date.now()}`;
+
+      await prodSession.switchToDevEnvironment();
+      await prodSession.testAgent.post('/v1/agents').send({ name: 'Guard Agent', identifier });
+    });
+
+    afterEach(async () => {
+      await prodSession.switchToDevEnvironment();
+      await prodSession.testAgent.delete(`/v1/agents/${encodeURIComponent(identifier)}`);
+    });
+
+    it('should reject devBridgeActive=true on production environment', async () => {
+      await prodSession.switchToProdEnvironment();
+
+      await prodSession.testAgent.post('/v1/agents').send({ name: 'Prod Agent', identifier: `${identifier}-prod` });
+
+      const res = await prodSession.testAgent.patch(`/v1/agents/${encodeURIComponent(`${identifier}-prod`)}`).send({
+        devBridgeActive: true,
+      });
+
+      expect(res.status).to.equal(403);
+
+      await prodSession.testAgent.delete(`/v1/agents/${encodeURIComponent(`${identifier}-prod`)}`);
+    });
+
+    it('should reject devBridgeUrl on production environment', async () => {
+      await prodSession.switchToProdEnvironment();
+
+      await prodSession.testAgent.post('/v1/agents').send({ name: 'Prod Agent 2', identifier: `${identifier}-prod2` });
+
+      const res = await prodSession.testAgent.patch(`/v1/agents/${encodeURIComponent(`${identifier}-prod2`)}`).send({
+        devBridgeUrl: 'https://tunnel.example.com',
+      });
+
+      expect(res.status).to.equal(403);
+
+      await prodSession.testAgent.delete(`/v1/agents/${encodeURIComponent(`${identifier}-prod2`)}`);
+    });
+
+    it('should allow bridgeUrl on production environment', async () => {
+      await prodSession.switchToProdEnvironment();
+
+      await prodSession.testAgent.post('/v1/agents').send({ name: 'Prod Agent 3', identifier: `${identifier}-prod3` });
+
+      const res = await prodSession.testAgent.patch(`/v1/agents/${encodeURIComponent(`${identifier}-prod3`)}`).send({
+        bridgeUrl: 'https://prod.example.com/novu',
+      });
+
+      expect(res.status).to.equal(200);
+      expect(res.body.data.bridgeUrl).to.equal('https://prod.example.com/novu');
+
+      await prodSession.testAgent.delete(`/v1/agents/${encodeURIComponent(`${identifier}-prod3`)}`);
+    });
+  });
 });

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

@@ -128,18 +128,6 @@ const echoBot = agent('novu-agent', {
     await ctx.reply(`Echo: ${userText}`);
   },
 
-  onReaction: async (ctx) => {
-    console.log('\n─────────────────────────────────────────');
-    console.log(`[${ctx.event}] reaction: ${ctx.reaction?.emoji.name} (${ctx.reaction?.added ? 'added' : 'removed'})`);
-    console.log(`Reacted message: ${ctx.reaction?.message?.text ?? '(unavailable)'}`);
-    console.log('─────────────────────────────────────────');
-
-    const emoji = ctx.reaction?.emoji.name ?? 'unknown';
-    const added = ctx.reaction?.added ?? false;
-
-    await ctx.reply(`Got ${added ? '' : 'un'}reaction: :${emoji}:`);
-  },
-
   onAction: async (ctx) => {
     console.log('\n─────────────────────────────────────────');
     console.log(`[${ctx.event}] action: ${ctx.action?.actionId} = ${ctx.action?.value ?? '(no value)'}`);

apps/api/src/app/agents/mappers/agent-response.mapper.ts

@@ -10,6 +10,9 @@ export function toAgentResponse(agent: AgentEntity): AgentResponseDto {
     description: agent.description,
     active: agent.active,
     behavior: agent.behavior,
+    bridgeUrl: agent.bridgeUrl,
+    devBridgeUrl: agent.devBridgeUrl,
+    devBridgeActive: agent.devBridgeActive,
     _environmentId: agent._environmentId,
     _organizationId: agent._organizationId,
     createdAt: agent.createdAt,

apps/api/src/app/agents/services/agent-config-resolver.service.ts

@@ -23,6 +23,9 @@ export interface ResolvedAgentConfig {
   thinkingIndicatorEnabled: boolean;
   reactionOnMessageReceived: string | null;
   reactionOnResolved: string | null;
+  bridgeUrl?: string;
+  devBridgeUrl?: string;
+  devBridgeActive?: boolean;
 }
 
 const DEFAULT_REACTION_ON_MESSAGE = 'eyes';
@@ -135,6 +138,9 @@ export class AgentConfigResolver {
         DEFAULT_REACTION_ON_MESSAGE
       ),
       reactionOnResolved: resolveReaction(agent.behavior?.reactions?.onResolved, DEFAULT_REACTION_ON_RESOLVED),
+      bridgeUrl: agent.bridgeUrl,
+      devBridgeUrl: agent.devBridgeUrl,
+      devBridgeActive: agent.devBridgeActive,
     };
   }
 }

apps/api/src/app/agents/services/bridge-executor.service.ts

@@ -10,7 +10,6 @@ import {
   ConversationActivitySenderTypeEnum,
   ConversationActivityTypeEnum,
   ConversationEntity,
-  EnvironmentRepository,
   SubscriberEntity,
 } from '@novu/dal';
 import type { Message } from 'chat';
@@ -129,7 +128,6 @@ export class NoBridgeUrlError extends Error {
 @Injectable()
 export class BridgeExecutorService {
   constructor(
-    private readonly environmentRepository: EnvironmentRepository,
     private readonly getDecryptedSecretKey: GetDecryptedSecretKey,
     private readonly logger: PinoLogger
   ) {}
@@ -140,12 +138,7 @@ export class BridgeExecutorService {
     try {
       const { config, event } = params;
 
-      const bridgeUrl = await this.resolveBridgeUrl(
-        config.environmentId,
-        config.organizationId,
-        agentIdentifier,
-        event
-      );
+      const bridgeUrl = this.resolveBridgeUrl(config, agentIdentifier, event);
       if (!bridgeUrl) {
         throw new NoBridgeUrlError(agentIdentifier);
       }
@@ -219,20 +212,21 @@ export class BridgeExecutorService {
     });
   }
 
-  private async resolveBridgeUrl(
-    environmentId: string,
-    organizationId: string,
+  private resolveBridgeUrl(
+    config: ResolvedAgentConfig,
     agentIdentifier: string,
     event: AgentEventEnum
-  ): Promise<string | null> {
-    const environment = await this.environmentRepository.findOne(
-      { _id: environmentId, _organizationId: organizationId },
-      ['bridge']
-    );
-    const baseUrl = environment?.bridge?.url;
+  ): string | null {
+    let baseUrl: string | undefined;
+
+    if (config.devBridgeActive && config.devBridgeUrl) {
+      baseUrl = config.devBridgeUrl;
+    } else if (config.bridgeUrl) {
+      baseUrl = config.bridgeUrl;
+    }
 
     if (!baseUrl) {
-      this.logger.warn(`[agent:${agentIdentifier}] No bridge URL configured on environment, skipping bridge call`);
+      this.logger.warn(`[agent:${agentIdentifier}] No bridge URL configured on agent, skipping bridge call`);
 
       return null;
     }