plushwipes-agent-revenue

# Plushwipes Agent Revenue V1

Approved active production release of the machine-readable Agent Revenue program for `earn.plushwipes.com`.

The repository contains the public opportunity surface, agent registration, referral attribution, performance reporting, commission state transitions, a public leaderboard, sanitized Shopify webhook processing and local synthetic acceptance tests. It does not contain production credentials or customer/order data.

## Runtime

- Node.js `>=22.13.0`
- vinext / Cloudflare Workers
- Cloudflare D1 through the `DB` binding

## Local setup

Install the locked dependency tree:

```bash
npm ci --ignore-scripts
```

Create and migrate a local D1 database:

```bash
npx wrangler d1 create plushwipes-agent-revenue-v1-local --local --config wrangler.local.jsonc
npx wrangler d1 migrations apply DB --local --config wrangler.local.jsonc
```

Start with synthetic-only secrets:

```bash
SHOPIFY_WEBHOOK_SECRET=synthetic-test-webhook-secret \
ADMIN_API_KEY=synthetic-test-admin-key \
REGISTRATION_RATE_LIMIT_SECRET=synthetic-test-rate-secret \
PROGRAM_STATUS=active \
npm run dev
```

Run build, unit, static and rendered-content tests:

```bash
npm test
```

With the local server running, run the synthetic workflow:

```bash
npm run test:e2e
```

## Public surfaces

- `/skill.md`
- `/opportunity.json`
- `/products.json`
- `/claims.json`
- `/assets.json`
- `/reviews.json`
- `/service.json`
- `/policy.json`
- `/terms.md`
- `GET /api/evaluate` (read-only; no registration, terms acceptance or credential creation)
- `POST /api/register`
- `GET /s/{source_token}/skill.md`
- `POST /api/terms/accept`
- `GET /r/{referral_code}`
- `GET /api/performance/{agent_id}`
- `GET /api/leaderboard`

## Operator surfaces

Operator endpoints require `Authorization: Bearer <ADMIN_API_KEY>`:

- `POST /api/admin/commissions/{order_id}`
- `GET /api/admin/daily-report`
- `GET /api/admin/database-status`
- `GET /api/admin/diagnostics/webhook-failures`
- `GET /api/admin/distribution-report`

Shopify webhook endpoints require a valid raw-body HMAC:

- `POST /api/webhooks/shopify/orders-paid`
- `POST /api/webhooks/shopify/refunds-create`
- `POST /api/webhooks/shopify/orders-cancelled`

The integration contract and prelaunch Shopify instructions are in `integration/shopify/`. No Shopify write is performed by local setup or tests.

## Production gate

The committed public dataset is the approved `"program_status": "active"` production release. Rollback is the saved Sites version 1 with the `PROGRAM_STATUS=prelaunch` environment gate.