mirror of
https://github.com/Permissionless-Software-Foundation/psf-bch-api.git
synced 2026-09-21 16:52:00 -07:00
73 lines
2.8 KiB
Markdown
73 lines
2.8 KiB
Markdown
# 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
|