[dimartiro]

Closes #69. Stacked on #73; review that one first.

The two TypeScript programs on Getting started, the merchant's gated route and the buyer's paying fetch, move into docs/snippets/*.ts, and the page transcludes them with <<< @/snippets/…#snippet. What the page shows is exactly what compiles.

I put the reader first

The issue suggests pulling code from examples/mortgage with region markers where it already exists. I tried that, and it made the page worse to learn from. Each side became four excerpts of the demo, with no imports, env helpers the page never shows (req(), netConfig(), authConfig()), and credit-score plumbing in the main path, so a reader could no longer copy one block and run it. I therefore kept each side as one self-contained program in the page's own names, and linked the mortgage demo as the runnable pair. Both copies compile, so a signature change breaks both. What this does not catch is the demo and the docs drifting apart in content.

The merchant program also reads the names the dashboard's integration panel prints (FACILITATOR_URL, FACILITATOR_API_KEY, NETWORK_ID, MERCHANT_PARTY, AMULET_ADMIN), so a merchant can drop that .env in as is. The API reference's curl uses $FACILITATOR_API_KEY for the same reason.

How it is checked

• docs/snippets is a private workspace package with a typecheck script, so the root pnpm typecheck covers it. CI already runs pnpm build first, so the snippets compile against the packages' real declarations, with no workflow change.
• Compiled, never run: no facilitator, key or ledger.
• VitePress renders the whole file, silently, when a #region is missing. The docs config now fails the page instead, checking the token VitePress itself resolved. With ci(docs): publish the docs site, with a preview per pull request  #72's docs build on every PR, this runs in CI once the branch is rebased.

Breaking a signature fails the docs

Demonstrated, then reverted. Renaming paymentRequired's requirements and CantonX402Payer's registries inside their packages, which still build, gives:

gate-express.ts(31,5): error TS2353: Object literal may only specify known properties, and 'requirements' does not exist in type 'PaymentRequiredOptions'.
pay-with-fetch.ts(41,3): error TS2353: Object literal may only specify known properties, and 'registries' does not exist in type 'CantonX402PayerOptions'.

Against the issue

• No pasted TypeScript left: both blocks are transcluded.
• docs/snippets is covered by pnpm typecheck and CI.
• Breaking a signature fails the build, demonstrated above.
• curl and npm install stay fenced, with a note on where $FACILITATOR_URL and $FACILITATOR_API_KEY come from.
• Pulling from examples/mortgage where the code exists: deliberately not done, as explained above.

Also

• The buyer program now ends with console.log(data), because the linter refuses an unused data.
• eslint skips docs/.vitepress/cache, which docs:dev fills with vendored Vue. Before this, pnpm lint failed locally after running the docs.
• Empty changeset: docs/snippets is a private workspace package, and changeset status asks for one.

Verification

pnpm build && pnpm typecheck, pnpm lint, prettier --check, pnpm docs:build and changeset status pass. The lockfile only gains the new importer, which reuses versions already in the tree.

[github-actions]

Coverage Report

ℹ️ This PR adds no executable lines, so there is no patch coverage to report.
Project coverage is 95.63% (±0.00% vs main@70cf2b1).

Additional details and impacted packages

@@              Coverage Diff              @@
##           main@70cf2b1      #74   +/-   ##
=============================================
  Coverage         95.63%   95.63%           
=============================================
  Packages              4        4           
  Lines               962      962           
  Branches            343      343           
=============================================
  Hits                920      920           
  Misses               42       42           

Package	Coverage Δ
@chainsafe/x402-client	95.33% <ø> (ø)
@chainsafe/x402-core	95.92% <ø> (ø)
@chainsafe/x402-express	92.81% <ø> (ø)
@chainsafe/x402-server-sdk	97.66% <ø> (ø)

_{Measured by vitest + v8 over each package's src/** — tests, fixtures and dist/ excluded. Patch coverage counts the executable lines this PR adds. lcov is attached to the run as the coverage artifact; pnpm test:coverage reproduces the report locally.}

[github-actions]

📘 Docs preview: https://chainsafe.github.io/canton-x402-sdk/pr-74/

Updated on every push. Removed when this pull request closes.