npm package: @inception-agents/vercel
Description: Next.js middleware integration for Inception Agents. Detects AI agent traffic at the edge and serves optimized content without affecting human visitors.
Latest version: 0.1.0

# @inception-agents/vercel

Next.js middleware integration for Inception Agents. Detects AI agent traffic at the edge and serves optimized content without affecting human visitors.

## Installation

```bash
npm install @inception-agents/vercel
```

**Peer dependency:** `next` >= 14.0.0

## Quick Start

Create or update your `middleware.ts` at the project root:

```typescript
import { withInception } from '@inception-agents/vercel';

export const middleware = withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
});

export const config = {
  matcher: ['/((?!_next/static|_next/image|favicon.ico).*)'],
};
```

That's it. Human traffic passes through untouched. AI agents receive optimized content automatically.

## API Reference

### `withInception(options)`

Creates a Next.js-compatible middleware function that wraps the full Inception pipeline. When the pipeline returns optimized content, that response is served directly. Otherwise, Next.js continues handling the request normally.

```typescript
import { withInception } from '@inception-agents/vercel';

export const middleware = withInception({
  apiKey: process.env.INCEPTION_API_KEY!,
  bypassPaths: ['/api/webhooks'],
});
```

**Returns:** `(request: Request) => Promise<Response>` — a function compatible with Next.js `middleware.ts` export.

### `createInceptionMiddleware(options)`

Lower-level alternative that returns `null` for human traffic instead of a pass-through response. Useful when you need to compose with other middleware.

```typescript
import { createInceptionMiddleware } from '@inception-agents/vercel';
import { NextResponse } from 'next/server';

const inception = createInceptionMiddleware({
  apiKey: process.env.INCEPTION_API_KEY!,
});

export async function middleware(request: Request) {
  const agentResponse = await inception(request);
  if (agentResponse) return agentResponse;

  // Your custom middleware logic here
  return NextResponse.next();
}
```

**Returns:** `(request: Request) => Promise<Response | null>`

## Configuration

### `VercelMiddlewareOptions`

Extends `InceptionConfig` from `@inception-agents/core`.

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | *required* | Your Inception Agents API key |
| `bypassPaths` | `string[]` | `[]` | Additional paths to skip (beyond core defaults) |
| `debug` | `boolean` | `false` | Enable debug logging |
| `excludePaths` | `string[]` | `['/api/', '/_next/', ...]` | Paths that bypass detection |
| `detectionThreshold` | `number` | `0.7` | Minimum confidence to classify as agent |
| `cacheMaxAge` | `number` | `300` | Cache-Control max-age (seconds) |
| `enableLlmsTxt` | `boolean` | `true` | Serve `/llms.txt` and `/llms-full.txt` |
| `enableJsonLd` | `boolean` | `true` | Serve JSON-LD enrichment for agents |
| `enableAgentCard` | `boolean` | `false` | Serve `/.well-known/agent.json` |

## Exported Types

- `InceptionConfig` — Base configuration interface
- `AgentDetectionResult` — Detection result with agent identity and confidence
- `IntentClassification` — Classified agent intent
- `VercelMiddlewareOptions` — Vercel-specific options extending `InceptionConfig`

## How It Works

1. Every request passes through the middleware at the Vercel edge
2. The Inception pipeline checks the request for AI agent signals (user-agent, IP range, headers)
3. If an agent is detected above the confidence threshold, optimized content is served directly
4. If the visitor is human, the middleware passes through with zero latency impact
5. Analytics signals are collected asynchronously (fire-and-forget)

## Related

- [Full documentation](https://www.inceptionagents.com/docs/integrations/vercel)
- [@inception-agents/core](https://www.npmjs.com/package/@inception-agents/core)