npm package: @inception-agents/cloudflare
Description: Cloudflare Worker middleware for Inception Agents. Intercepts AI agent traffic at the edge with optional KV-backed caching for sub-millisecond cached responses.
Latest version: 0.1.0

# @inception-agents/cloudflare

Cloudflare Worker middleware for Inception Agents. Intercepts AI agent traffic at the edge with optional KV-backed caching for sub-millisecond cached responses.

## Installation

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

## Quick Start

### Worker Setup

```typescript
import { createInceptionHandler } from '@inception-agents/cloudflare';

const handler = createInceptionHandler({
  apiKey: 'iak_your_api_key',
  originUrl: 'https://your-origin.com',
});

export default {
  async fetch(request: Request, env: Record<string, unknown>, ctx: ExecutionContext) {
    return handler(request, env, ctx);
  },
};
```

### With KV Caching

```typescript
import { createInceptionHandler } from '@inception-agents/cloudflare';

interface Env {
  INCEPTION_CACHE: KVNamespace;
  INCEPTION_API_KEY: string;
}

export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const handler = createInceptionHandler({
      apiKey: env.INCEPTION_API_KEY,
      originUrl: 'https://your-origin.com',
      kvCache: env.INCEPTION_CACHE,
      kvCacheTtl: 600,
    });

    return handler(request, env, ctx);
  },
};
```

### wrangler.toml

```toml
name = "my-site-inception"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[[kv_namespaces]]
binding = "INCEPTION_CACHE"
id = "your-kv-namespace-id"

[vars]
INCEPTION_API_KEY = "iak_your_api_key"
```

## API Reference

### `createInceptionHandler(options)`

Creates a Cloudflare Worker fetch handler that intercepts agent traffic and serves optimized responses. Non-agent traffic is proxied to the configured origin.

**Returns:** `(request: Request, env?: Record<string, unknown>, ctx?: ExecutionContext) => Promise<Response>`

### `createDetectionHandler(config)`

Creates a lightweight detection-only handler that returns agent detection metadata as JSON. Useful as a Worker binding for service-to-service detection without content optimization.

```typescript
import { createDetectionHandler } from '@inception-agents/cloudflare';

const detect = createDetectionHandler({ apiKey: 'iak_...' });

export default {
  async fetch(request: Request) {
    return detect(request);
    // Returns: { isAgent: true, agentType: "assistant", identity: "ChatGPT-User", ... }
  },
};
```

**Returns:** `(request: Request) => Promise<Response>` (JSON response with `AgentDetectionResult`)

## Configuration

### `CloudflareHandlerOptions`

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

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | *required* | Your Inception Agents API key |
| `originUrl` | `string` | — | Origin URL for proxying non-agent traffic |
| `kvCache` | `KVNamespace` | — | KV namespace for caching optimized responses |
| `kvCacheTtl` | `number` | `300` | Cache TTL in seconds for KV-backed responses |
| `debug` | `boolean` | `false` | Enable debug logging |
| `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` |

## KV Caching

When a `kvCache` namespace is provided, optimized responses are cached in Cloudflare KV for subsequent requests. The cache key is `inception:{pathname}`.

- Cache writes happen asynchronously via `ctx.waitUntil()` to avoid blocking the response
- Cached responses include an `X-Inception-Cache: HIT` header
- TTL defaults to 300 seconds (5 minutes), configurable via `kvCacheTtl`

## Exported Types

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

## Related

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