Discoverability Smoke Test

This is the bounded acceptance check for BDT-312.

It starts from /llms.txt, walks the agent entry docs, registers a sandbox merchant, creates a test payment session, simulates completion, and finishes by verifying either a receipt PDF or a webhook signature.

Run it

npm run smoke:agent

Use a live backend when you have an API URL:

PLAIDLY_API_BASE_URL=https://api.plaidly.io \
npm run smoke:agent

The default smoke:agent invocation runs in mock mode unless PLAIDLY_API_BASE_URL is set:

• with no live URL, it runs the deterministic mock path
• with a live URL, it probes the backend with a public read-only request
• if the probe is unavailable, it falls back to the deterministic mock path
• if the probe succeeds, it runs the live backend flow end-to-end

Force a specific mode when you need it:

npm run smoke:agent:mock
npm run smoke:agent:live

PLAIDLY_SMOKE_MODE=live disables the fallback and fails fast on live backend errors.

What the smoke flow checks

1. Read public/llms.txt and confirm the agent entry points are published.
2. Register a sandbox merchant with POST /v1/merchants. As of BDT-542, real registration also requires the email-verification + proof-of-work + trust-gate steps described in Register a merchant. scripts/agent-discoverability-smoke.mjs's live-mode flow still calls POST /v1/merchants directly with none of those steps, so npm run smoke:agent:live against a real trust-gate-enforcing backend currently fails at merchant registration rather than falling back to mock (only 502/503/504-class errors trigger the auto-mode fallback). Mock mode (npm run smoke:agent:mock) is unaffected and still exercises the rest of the flow.
3. Create a test payment session with X-API-Key and paymentMethod.network = testnet.
4. Simulate the payment with POST /v1/payment_sessions/{session_id}/simulate.
5. Verify completion by polling the session to confirmed, fetching the receipt PDF, and validating the webhook signature helper against the live merchant secret.

If you also provide a reachable PLAIDLY_WEBHOOK_URL, the backend can deliver a real signed callback and the session response will surface the delivery status.

Live flow

The live flow uses the contract described in Agent OpenAPI / SDK Contracts. As of BDT-542, registering for real requires the full email-verification + proof-of-work + trust-gate sequence — see Register a merchant for the four calls involved. The final call looks like:

curl -X POST https://api.plaidly.io/v1/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "BDT-312 Smoke Merchant",
    "sandbox": true,
    "webhook_url": "https://your-public-webhook.example/webhooks/plaidly",
    "registration_intent_id": "...",
    "proof_of_work_challenge_id": "...",
    "proof_of_work_nonce": "..."
  }'

The response should include:

• id
• api_key
• webhook_secret

Then create the sandbox payment session:

curl -X POST https://api.plaidly.io/v1/payment_sessions \
  -H "X-API-Key: plaidly_sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 0.0015,
    "expires_in": "30m",
    "paymentMethod": {
      "methodID": 0,
      "chain": "solana",
      "token": "USDC",
      "network": "testnet"
    },
    "metadata": {
      "source": "docs-discoverability-smoke"
    }
  }'

Expected response fields:

• session_id
• address
• status
• demo

After simulation, a successful run should end with either:

• a non-empty application/pdf receipt from /v1/payment_sessions/{session_id}/receipt
• a session response that reaches confirmed
• a valid X-Plaidly-Signature check against the merchant webhook_secret

When a reachable webhook receiver is configured, the live backend also exposes the delivery state in webhook_delivery.

Mock flow

The mock path is for local or CI use when no API endpoint is reachable. It keeps the same assertions:

• llms.txt is present and points at the agent entry pages
• merchant registration returns an API key and webhook secret
• session creation returns a session ID and address
• simulation marks the session complete
• webhook verification passes for the generated payload

This makes the smoke test useful even before a live backend is available.