npm package: @payweave/core
Description: Core SDK for PayWeave - the payment layer for AI agents. Accept per-request USD micropayments via the Machine Payment Protocol (MPP).
Latest version: 0.0.3

# @payweave/core

Core SDK for PayWeave - the payment layer for AI agents. Accept per-request USD micropayments via the Machine Payment Protocol (MPP).

## Install

```bash
npm install @payweave/core
```

> Most users should install a framework adapter instead (`@payweave/express`, `@payweave/hono`, `@payweave/next`, or `@payweave/fastify`). The core package is used directly only for custom integrations.

## Usage

```typescript
import { PayWeave } from '@payweave/core';

const payweave = new PayWeave({
  appId: 'app_xxxxxxxxxxxx',
  appSecret: process.env.PAYWEAVE_APP_SECRET!,
});

// Initialize and fetch app config
const config = await payweave.initialize();
console.log(config.mode);    // 'test' or 'live'
console.log(config.wallet);  // your wallet address
console.log(config.network); // 'tempo'

// Record a settlement event
await payweave.recordSettlement({
  transactionHash: '0x...',
  payerAddress: '0x...',
  amount: '0.001',
  network: 'tempo',
  httpMethod: 'GET',
  httpPath: '/api/weather',
});
```

## API

### `new PayWeave(config)`

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

### `payweave.initialize()`

Fetches and caches your app configuration. Returns `MppInitResponse`:

```typescript
{
  mode: 'test' | 'live';
  wallet: string | null;
  currency: string;
  network: string;
  discoverable: boolean;
  quota: { used: number; limit: number; exceeded: boolean };
}
```

### `payweave.recordSettlement(event)`

Records a payment settlement event.

### `payweave.config`

Returns the cached config (or `null` before `initialize()`).

### `payweave.secret`

Returns the app secret key.

### `payweave.mode`

Returns `'test'` or `'live'` based on the secret prefix.

## PayweaveBase

The base class for building custom framework adapters. All official adapters (`@payweave/express`, `@payweave/hono`, etc.) extend this class.

```typescript
import { PayweaveBase } from '@payweave/core';

class MyAdapter extends PayweaveBase {
  charge(options) {
    return async (req, res) => {
      const result = await this.processCharge(
        env,
        options.price,
        options.description,
        req.method,
        req.path,
        paymentCredential,
        options.meta
      );

      if (result.status === 402) {
        // Return 402 with challenge headers
      }
      // Continue with Payment-Receipt header
    };
  }
}
```

## Payment Flow

1. Agent calls your API without a payment header
2. Your middleware responds with `402 Payment Required` and a `WWW-Authenticate` header
3. Agent submits payment on Tempo and retries with the payment credential
4. PayWeave verifies the payment, returns a `Payment-Receipt` header
5. Your handler executes and returns the response

## Error Classes

- `PayWeaveError` - Base error
- `PayWeaveConfigError` - Invalid configuration
- `PayWeaveQuotaExceededError` - Quota exceeded
- `PayWeaveSettlementError` - Settlement failed
- `PayWeaveVerificationError` - Payment verification failed
- `PayWeaveNetworkError` - Network error
- `PayWeaveEventError` - Event recording error
- `PayweaveChargeError` - Charge processing error

## License

MIT