psf-bch-api/dev-docs/update-logs/2026-04-01.md

2026-04-01 Update Log

Summary

Added x402-gated discovery endpoints for agent/tool self-discovery, built a docs-derived artifact pipeline from apiDoc annotations, and documented the new flow and behavior.

Changes Made

• Added new discovery controller/router:
  • src/controllers/discovery/controller.js
  • src/controllers/discovery/router.js
• Added five root-path discovery endpoints:
  • GET /.well-known/x402
  • GET /openapi.json
  • GET /swagger.json
  • GET /llms.txt
  • GET /.well-known/agent.json
• Added x402-enabled gating:
  • All five endpoints now return 404 when X402_ENABLED=false.
  • When enabled, payloads are returned with x402-bch v2-oriented metadata.
• Added apiDoc-derived document builder:
  • src/discovery/build-documents.js
  • Parses @api annotations and builds OpenAPI, Swagger, llms, and agent documents.
  • Uses docs/discovery-artifacts.json if present, otherwise builds in-process.
• Added artifact generation script:
  • scripts/build-discovery-artifacts.js
  • Writes docs/discovery-artifacts.json
• Updated npm scripts in package.json:
  • docs:discovery
  • docs:all (runs docs then docs:discovery)
• Wired discovery routes into server bootstrap:
  • bin/server.js
• Added tests:
  • test/unit/controllers/discovery-controller-unit.js
  • test/unit/controllers/discovery-router-unit.js
  • test/unit/controllers/discovery-documents-unit.js
• Updated docs/config examples:
  • README.md (discovery endpoints + docs workflow)
  • .env-example (x402 gating note for discovery endpoints)

Why This Was Changed

• Endpoint probes for discovery paths are common from API tooling and AI agents.
• Serving structured discovery metadata improves machine interoperability for:
  • API clients and SDK tooling (openapi.json, swagger.json)
  • LLM retrieval workflows (llms.txt)
  • Agent capability discovery (agent.json)
  • x402 payment discovery (/.well-known/x402)
• Gating by X402_ENABLED keeps discovery aligned with monetization mode and avoids advertising payment surfaces when x402 is disabled.

Validation Notes

• Lint passed.
• New discovery-focused unit tests passed.
• Full npm test run showed one pre-existing timeout failure in test/unit/use-cases/price-use-cases-unit.js unrelated to discovery endpoint changes.

References

• Local protocol spec:
  • ../x402-bch/specs/x402-bch-specification-v2.2.md
• OpenAPI Specification:
  • https://spec.openapis.org/oas/latest.html
• Swagger / OpenAPI 2.0:
  • https://swagger.io/specification/v2/
• llms.txt proposal:
  • https://www.llmstxt.org/index.html
• Agent manifest draft reference:
  • https://agentwebprotocol.org/spec
• x402 HTTP 402 background:
  • https://docs.x402.org/core-concepts/http-402
• x402 DNS discovery draft:
  • https://www.ietf.org/archive/id/draft-jeftovic-x402-dns-discovery-00.html