npm package: @payweave/hono
Description: Hono middleware for PayWeave - accept per-request USD micropayments on any Hono route. Works across all Hono runtimes (Cloudflare Workers, Bun, Deno, Node.js).
Latest version: 0.0.3

# @payweave/hono

Hono middleware for PayWeave - accept per-request USD micropayments on any Hono route. Works across all Hono runtimes (Cloudflare Workers, Bun, Deno, Node.js).

## Install

```bash
npm install @payweave/hono
```

## Quick Start

```typescript
import { Payweave } from '@payweave/hono';
import { Hono } from 'hono';

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

app.get(
  '/api/weather',
  payweave.charge({ price: '0.001', description: 'Weather API' }),
  (c) => c.json({ temp: 72, unit: 'F' })
);

export default app;
```

## 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)`

Returns a Hono `MiddlewareHandler`.

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

## Examples

### Static pricing

```typescript
app.get(
  '/api/search',
  payweave.charge({ price: '0.01' }),
  (c) => c.json({ results: [] })
);
```

### Dynamic pricing from context

```typescript
app.post(
  '/api/generate',
  payweave.charge({
    price: async (c) => {
      const body = await c.req.json();
      return body.model === 'gpt-4' ? '0.05' : '0.01';
    },
    description: 'Text generation',
  }),
  async (c) => {
    const body = await c.req.json();
    return c.json({ text: 'generated' });
  }
);
```

### Route groups

```typescript
const api = new Hono();

api.get('/weather', payweave.charge({ price: '0.001' }), weatherHandler);
api.get('/forecast', payweave.charge({ price: '0.005' }), forecastHandler);
api.post('/analyze', payweave.charge({ price: '0.01' }), analyzeHandler);

app.route('/api', api);
```

### With metadata for agent discovery

```typescript
app.post(
  '/api/sentiment',
  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"}}}',
    },
  }),
  (c) => c.json({ score: 0.85 })
);
```

### Cloudflare Workers

```typescript
import { Payweave } from '@payweave/hono';
import { Hono } from 'hono';

type Env = { PAYWEAVE_APP_ID: string; PAYWEAVE_APP_SECRET: string };

const app = new Hono<{ Bindings: Env }>();

app.get('/api/data', (c, next) => {
  const pw = new Payweave(c.env.PAYWEAVE_APP_ID, c.env.PAYWEAVE_APP_SECRET);
  return pw.charge({ price: '0.001' })(c, next);
}, (c) => c.json({ data: 'paid content' }));

export default app;
```

## How It Works

1. A request hits your route without a payment header
2. The middleware 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 and sets a `Payment-Receipt` header
5. Your handler executes normally

## License

MIT