@bernierllc/onboarding-agent-nextjs

Thin Next.js App Router adapter that wraps OnboardingAgent into streaming SSE route handlers compatible with the Vercel AI SDK v6 and onboarding-chat-ui.

Installation

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

Peer dependency: next ^14.0.0 || ^15.0.0.

Usage

Chat Handler (SSE streaming)

// app/api/onboarding/chat/route.ts
import { createOnboardingRouteHandler } from '@bernierllc/onboarding-agent-nextjs';
import { agent } from '@/lib/onboarding-agent';
import { getServerSession } from 'next-auth';
import type { NextRequest } from 'next/server';
import { NextResponse } from 'next/server';

export const POST = createOnboardingRouteHandler(agent, {
  auth: async (req: NextRequest) => {
    const session = await getServerSession();
    if (!session?.user) {
      return new NextResponse(JSON.stringify({ error: 'Unauthorized' }), { status: 401 });
    }
    return { userId: session.user.id, sessionId: session.user.orgId };
  },
});

Status Handler

// app/api/onboarding/status/route.ts
import { createStatusRouteHandler } from '@bernierllc/onboarding-agent-nextjs';
import { agent } from '@/lib/onboarding-agent';

export const GET = createStatusRouteHandler(agent);

Rating Handler

// app/api/onboarding/rating/route.ts
import { createRatingRouteHandler } from '@bernierllc/onboarding-agent-nextjs';
import { agent } from '@/lib/onboarding-agent';

export const POST = createRatingRouteHandler(agent);

API

createOnboardingRouteHandler(agent, options?)

Returns a POST handler that streams OnboardingAgent.chat() output as SSE events.

Streaming format (Vercel AI SDK v6 compatible):

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

data: {"type":"done"}

data: [DONE]

Attachment extraction: Accepts both JSON { attachments: [{ filename, dataUrl, mimeType }] } and multipart/form-data with files[] fields (converted to base64 data URLs).

createStatusRouteHandler(agent, options?)

Returns a GET handler that calls agent.getSetupStatus(sessionId) and returns JSON.

createRatingRouteHandler(agent, options?)

Returns a POST handler that accepts { rating: 'up' | 'down' } and calls agent.recordRating(sessionId, rating).

OnboardingRouteOptions

| Field | Type | Description | |---|---|---| | auth? | (req: NextRequest) => Promise<{ userId, sessionId } \| NextResponse> | Optional auth middleware. Return NextResponse to block the request. | | contentType? | string | Override SSE content-type. Default: text/event-stream. |

HTTP Error Mapping

| OnboardingAgentError code | HTTP status | |---|---| | ONBOARDING_AGENT_INIT_ERROR | 503 | | ONBOARDING_HANDOFF_ERROR | 500 | | ONBOARDING_CONFIG_VALIDATION_ERROR | 400 | | ONBOARDING_PLUGIN_ERROR | 400 | | Any other OnboardingAgentError | 500 | | Non-OnboardingAgentError | 500 |

Error response body: { error: string, code?: string }.

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.