@bernierllc/admin-agent-nextjs

Thin Next.js App Router adapter that wraps an AdminAgent into a streaming SSE POST route handler with auth, validation, and error mapping.

Installation

npm install @bernierllc/admin-agent-nextjs @bernierllc/admin-agent-service

Peer dependency: next >= 14.0.0 < 16.

Usage

// app/api/chat/admin/route.ts
import { createAdminAgentRouteHandler } from '@bernierllc/admin-agent-nextjs';
import { adminAgent } from '@/lib/admin-agent';
import { getServerSession } from 'next-auth';
import { AdminAgentRouteUnauthorizedError } from '@bernierllc/admin-agent-nextjs';

export const POST = createAdminAgentRouteHandler({
  agent: adminAgent,

  auth: async (request) => {
    const session = await getServerSession();
    if (!session?.user) {
      throw new AdminAgentRouteUnauthorizedError('Not authenticated');
    }
    return { userId: session.user.id, orgId: session.user.orgId };
  },
});

API

createAdminAgentRouteHandler(config)

Returns an async (request: Request) => Promise<Response> function suitable for export const POST in a Next.js App Router route file.

Config options:

| Field | Type | Description | |---|---|---| | agent | AdminAgent | Agent instance from @bernierllc/admin-agent-service | | auth | (request: Request) => Promise<AuthContext> | Extract auth context; throw AdminAgentRouteUnauthorizedError for 401 | | validateBody? | (body: unknown) => { message: string } | Custom body validator; default validates { message: string } | | transformEvent? | (event: AdminAgentEvent) => AdminAgentEvent \| null | Filter or transform events; return null to suppress |

Errors

• AdminAgentRouteError — base error class
• AdminAgentRouteUnauthorizedError — throw from auth() to produce a 401
• AdminAgentRouteBodyError — throw from validateBody() to produce a 400

Error-to-HTTP Mapping

| Condition | HTTP Status | |---|---| | Body parse failure | 400 | | validateBody throws | 400 | | auth throws AdminAgentRouteUnauthorizedError | 401 | | auth throws any other error | 500 | | Agent initialization failure | 500 | | rate-limited event received | 200 (stream closes with event) | | feature-disabled event received | 200 (stream closes with event) |

Response Format

Streaming text/plain; charset=utf-8 with Transfer-Encoding: chunked. Events are newline-delimited JSON:

{"type":"text-delta","delta":"Hello"}
{"type":"done"}

Node.js Only

This package requires a Node.js server runtime. It is not browser-safe.

License

Copyright (c) 2025 Bernier LLC. All rights reserved.