feat(web-search-paid-api-ts): pay-as-you-go API key tutorial (Exa pattern)

[r-marques]

Summary

• New tutorial web-search-paid-api-ts/ demonstrating the pay-as-you-go API key monetization pattern: one x402-protected endpoint returns a quota-bearing API key, and the provider does its own metering on the issued key.
• Sibling to http-simple-agent-ts/ — that one settles credits on every protected request (burn-credits middleware). This one settles only at purchase time and gets out of the hot path.
• Mirrors the live Exa ↔ Nevermined integration, including the agent-discoverability convention (llms.txt → nevermined.md).

First of three PRs landing nevermined-io/nvm-monorepo#1684:

• PR-A (this) — runnable tutorial.
• PR-B — new "Use Cases" section in the docs (docs/use-cases/...) with the agent-discoverability page + Exa case study; links here.
• PR-C — multi-agent validation findings appended to the discoverability page.

What's in the tutorial

File	Purpose
src/server.ts	Express server. POST /purchase-key (x402-protected) + POST /search (api-key-gated). Uses the facilitator API directly (verifyPermissions / settlePermissions) — not the paymentMiddleware wrapper — so the verify → settle → provision flow is visible.
src/store.ts	In-memory payer → { apiKey, remainingQuota } map. The provider's own bookkeeping, independent of any Nevermined credit balance.
src/search.ts	Deterministic stub search results.
src/client.ts	Demo agent: mint x402 token → purchase key → search until quota exhausted → top up. Tagged-union outcome type for search() so call-site narrowing is clean.
src/llms-txt-template/llms.txt	Template for a provider's llms.txt (root of the docs site).
src/llms-txt-template/nevermined.md	Template integration page, structured to mirror Exa's. Placeholders marked {{LIKE_THIS}}.
README.md	Walkthrough + ASCII flow diagram + when-to-use-this-vs-the-burn-credits-pattern.

Design decisions worth flagging for review

1. verify → settle → provision (not verify → provision → settle). Settle moves the money; provisioning last means a settle failure leaves the store untouched, so the customer is neither charged nor served. Code-review caught this and an earlier ordering would have leaked quota on settle failure. docs/solutions/api-providers.mdx in docs_mintlify currently shows the unsafe order — PR-B will reconcile.
2. Facilitator API, not paymentMiddleware. The middleware hides the "do business logic between verify and settle" step inside the handler — but that step (provisioning the key) is exactly the educational point of this pattern, so we use the lower-level API explicitly.
3. PAYG framing. PAYG plans have no buyer-side credit balance; each successful /purchase-key call triggers exactly one card charge. The README and template are careful never to say "buy credits and burn them" — that's a credit-plan mental model, not a PAYG one.
4. In-memory store, by design. Real providers would persist this; the tutorial keeps it in-memory so the payment flow stays the focus.

Test plan

• yarn install resolves cleanly.
• yarn build (tsc) clean.
• Code review pass (covers settlement failure handling, quota-decrement ordering, token-replay note, limit clamp, contract docstrings).
• Code simplifier pass (one surgical type-narrowing improvement; everything else left alone).
• Smoke test against sandbox — blocked on a sandbox PAYG plan id + an enrolled card pm_id. Will run end-to-end: yarn agent + yarn client, exercise both first purchase and top-up paths, verify one card charge per /purchase-key.
• Manual verification that nevermined.md template renders correctly when placeholders are filled in.

Notes for reviewers

• The handler comments are intentional pedagogy; they explain why the ordering is what it is. They were preserved through both the reviewer and simplifier passes deliberately.
• The token-replay risk on /purchase-key is acknowledged in a code comment but not guarded against in the tutorial. Production code should de-dup by token hash or settlement transaction.
• Draft until smoke-test passes.

🤖 Generated with Claude Code