npm package: @payweave/next
Description: Next.js integration for PayWeave - accept per-request USD micropayments on Next.js API routes.
Latest version: 0.0.3

# @payweave/next

Next.js integration for PayWeave - accept per-request USD micropayments on Next.js API routes.

## Install

```bash
npm install @payweave/next
```

## Quick Start

```typescript
// app/api/weather/route.ts
import { Payweave } from '@payweave/next';
import { NextRequest, NextResponse } from 'next/server';

const payweave = new Payweave(
  process.env.PAYWEAVE_APP_ID!,
  process.env.PAYWEAVE_APP_SECRET!
);

export const GET = payweave.charge(
  { price: '0.001', description: 'Weather API' },
  async (req: NextRequest) => {
    return NextResponse.json({ temp: 72, unit: 'F' });
  }
);
```

## API

### `new Payweave(appId, appSecret, baseUrl?)`

| Parameter | Type | Description |
|-----------|------|-------------|
| `appId` | `string` | Your app key ID |
| `appSecret` | `string` | Your app secret |
| `baseUrl` | `string?` | API base URL (defaults to `https://api.payweave.app`) |

### `payweave.charge(options, handler)`

Wraps a route handler with payment verification. Returns `(req: NextRequest) => Promise<NextResponse>`.

| Option | Type | Description |
|--------|------|-------------|
| `price` | `string \| (req: NextRequest) => string \| Promise<string>` | USD price per request |
| `description` | `string?` | Human-readable description |
| `meta` | `Record<string, string>?` | API metadata for agent discovery |

> Note: Unlike other adapters, the Next.js adapter wraps your handler function directly. The handler is passed as the second argument to `charge()`.

## Examples

### App Router (recommended)

```typescript
// app/api/search/route.ts
import { Payweave } from '@payweave/next';
import { NextRequest, NextResponse } from 'next/server';

const payweave = new Payweave(
  process.env.PAYWEAVE_APP_ID!,
  process.env.PAYWEAVE_APP_SECRET!
);

export const GET = payweave.charge(
  { price: '0.01' },
  async (req: NextRequest) => {
    const query = req.nextUrl.searchParams.get('q');
    return NextResponse.json({ results: [], query });
  }
);

export const POST = payweave.charge(
  { price: '0.02', description: 'Advanced search' },
  async (req: NextRequest) => {
    const body = await req.json();
    return NextResponse.json({ results: [], query: body.query });
  }
);
```

### Dynamic pricing

```typescript
export const POST = payweave.charge(
  {
    price: async (req: NextRequest) => {
      const body = await req.clone().json();
      return body.premium ? '0.05' : '0.01';
    },
    description: 'Text generation',
  },
  async (req: NextRequest) => {
    const body = await req.json();
    return NextResponse.json({ text: 'generated' });
  }
);
```

### With metadata for agent discovery

```typescript
export const POST = payweave.charge(
  {
    price: '0.005',
    description: 'Sentiment analysis',
    meta: {
      'method': 'POST',
      'input.content-type': 'application/json',
      'input.schema': '{"type":"object","properties":{"text":{"type":"string"}}}',
      'output.schema': '{"type":"object","properties":{"score":{"type":"number"}}}',
    },
  },
  async (req: NextRequest) => {
    const { text } = await req.json();
    return NextResponse.json({ score: 0.85, text });
  }
);
```

### Multiple routes

```
app/api/
  weather/route.ts    -> export const GET = payweave.charge(...)
  forecast/route.ts   -> export const GET = payweave.charge(...)
  analyze/route.ts    -> export const POST = payweave.charge(...)
```

## How It Works

1. A request hits your API route without a payment header
2. The wrapper responds with `402 Payment Required` and pricing info
3. The agent submits payment on Tempo and retries with `Authorization: Payment <credential>`
4. PayWeave verifies the payment, calls your handler, and adds a `Payment-Receipt` header to the response
5. Your response is returned to the agent

## License

MIT