feat: 2.1.1 — typed errors, bootstrap session helper, stripe $0.50 auto-drop

[vvillait88]

Summary

Lifts patterns from the merchant-side template into the SDK so every gated endpoint gets the bootstrap UX out of the box, plus prevents an unprofitable Stripe rail from being advertised below the $0.50 USD floor.

1. Typed errors in stripe-multichain + dispatch helpers

• pay_to_address.ts: malformed Authorization: Payment, cache-miss recipient, missing recipient field → CheckoutValidationError(401, invalid_credential, action=retry_without_credential). Fallback when none of preferred/base/tempo recipients land in the minted PI → 503 payment_provider_unavailable.
• payment_intent.ts: Stripe returns an empty deposit_addresses map (account not enrolled in the Stablecoins-and-Crypto preview) → 503 payment_provider_unavailable.
• payment/dispatch.ts: unregistered EVM/Solana handler or unrecognized network family → 503 payment_provider_unavailable.

Previously these all surfaced as bare Error → 500 to the agent.

2. CheckoutValidationError extraction to its own module

src/errors.ts is the new canonical home. checkout.ts, pay_to_address.ts, payment_intent.ts, payment/dispatch.ts, identity/policy.ts import directly. index.ts re-exports for the public surface — no re-export through checkout (avoids the cycle).

In Checkout.handle, the wrap around the first resolveRecipientsForCtx call uses an inline err.name === 'CheckoutValidationError' check rather than instanceof — tsup's per-entry bundles produce separate class identities under splitting: false.

3. buildVerificationRequiredBody(reason, opts?) helper

Collapses the per-merchant identity_verification_required body mapping into one call. Returns the canonical 4xx envelope with verify_url / session_id / poll_secret / poll_url / agent_instructions spread in. Merchant overrides for message, agentInstructions, and arbitrary extra fields (goods merchants use the latter for order_id).

4. Checkout auto-defaults createSessionOnMissing

Mirrors python-commerce's behavior. When the merchant doesn't supply createSessionOnMissing in the gate config, Checkout builds one from gate.apiKey + gate.baseUrl + gate.context + gate.merchantName. Merchants that need custom session context or onBeforeSession side effects still supply their own to override. Standalone agentscoreGate adapters stay opt-in (read-only gates often want the bare-denial path).

5. Knip dead-code check wired into CI

Added bun run knip to the CI job between typecheck and test. To make it pass clean, this PR also addresses the three real findings: ComputeFirstMppContext + ComputeFirstSettledContext added to public exports (legitimate hook param types); RateLimitDecision export dropped (file-local in middleware/_core.ts); @solana/kit + @solana/mpp removed from ignoreDependencies (real runtime deps now).

6. Stripe $0.50 USD auto-drop (compose + discovery)

Stripe's fixed ~$0.30 fee makes sub-50-cent card charges unprofitable (a $0.11 PI nets -$0.19 after fees); many accounts also reject PI creation under the floor with amount_too_small. The SDK now drops the stripe/charge rail from BOTH layers when amountUsd < 0.50:

• buildMppxComposeRails in src/payment/compose_rails.ts — drops the stripe/charge intent at mppx compose time with a one-time console.warn.
• Checkout.emit_402 in src/checkout.ts AND computeFirstCheckout._emit_402 in src/checkout_compute_first.ts — strip the stripe slot from the rails dict before buildAcceptedMethods / buildHowToPay run, so the 402 body's accepted_methods + agent_instructions.how_to_pay stay consistent with what mppx will actually accept.

Pass includeStripe: false to suppress the warning when the merchant knows their pricing tier is permanently sub-50-cent. Shared constant: src/payment/constants.ts:STRIPE_MIN_CHARGE_USD.

7. Test coverage parity

test npm script now runs vitest run --coverage so local runs enforce the same global threshold as CI (90% branches / 96% statements). The CI workflow no longer passes -- --coverage since it's baked in. Caught a missing test on the new auto-drop emit-402 branch.

8. In-range deps bumps

@types/node 25.8.0 → 25.9.0, typescript-eslint 8.59.3 → 8.59.4. bun update only; no major bumps.

Version

• 2.1.0 → 2.1.1

Test plan

• bun run typecheck
• bun run lint
• bun run knip — clean
• bun run test — 1395 pass, 96.45/90.02/97.94/97.52 coverage
• bun run build — clean
• Live end-to-end smoke against people-data-labs (real PDL data via Tempo / x402 Base / Solana MPP settles) and martin-estate (Stripe auto-drop verified: stripe absent at test-wine $0.11, present at rose-2022 $51.72)

🤖 Generated with Claude Code