v2: docs (#726)

* ts example docs

* improve ts package docs

Author: phdargen

examples/typescript/clients/advanced/README.md

@@ -1,79 +1,73 @@
 # Advanced x402 Client Examples
 
-This directory contains advanced, production-ready patterns for x402 TypeScript clients using fetch. These examples go beyond the basics to demonstrate sophisticated techniques for building robust, scalable payment-enabled applications.
+Advanced patterns for x402 TypeScript clients demonstrating payment lifecycle hooks and network preferences.
 
-## What This Shows
-
-Advanced patterns for production environments:
-
-- **Payment Lifecycle Hooks**: Custom logic at different payment stages
+## Prerequisites
 
-## Examples
+- Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))
+- pnpm v10 (install via [pnpm.io/installation](https://pnpm.io/installation))
+- Valid EVM and/or SVM private keys for making payments
+- A running x402 server (see [server examples](../../servers/))
+- Familiarity with the [basic fetch client](../fetch/)
 
-### 1. Payment Lifecycle Hooks (`hooks`)
+## Setup
 
-**Production Pattern**: Register hooks for payment creation lifecycle events
+1. Copy `.env-local` to `.env`:
 
 ```bash
-npm start hooks
+cp .env-local .env
 ```
 
-**Demonstrates:**
+and fill required environment variables:
 
-- onBeforePaymentCreation: Custom validation before payment
-- onAfterPaymentCreation: Logging and metrics after payment
-- onPaymentCreationFailure: Error recovery strategies
-- Payment event lifecycle management
+- `EVM_PRIVATE_KEY` - Ethereum private key for EVM payments
+- `SVM_PRIVATE_KEY` - Solana private key for SVM payments (required for preferred-network)
 
-**Use When:**
+2. Install and build all packages from the typescript examples root:
 
-- Need to log payment events for debugging/monitoring
-- Want custom validation before allowing payments
-- Require error recovery from payment failures
-- Building observable payment systems
+```bash
+cd ../../
+pnpm install && pnpm build
+cd clients/advanced
+```
 
-## Prerequisites
+3. Run the server
 
-- Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))
-- pnpm v10 (install via [pnpm.io/installation](https://pnpm.io/installation))
-- An Ethereum private key (testnet recommended)
-- A running x402 server (see [server examples](../../servers/))
-- Understanding of [basic fetch client](../fetch/)
+```bash
+pnpm dev
+```
 
-## Setup
+## Available Examples
 
-1. Install and build all packages from the typescript examples root:
+Each example demonstrates a specific advanced pattern:
 
-```bash
-cd ../../
-pnpm install
-pnpm build
-cd clients/advanced
-```
+| Example             | Command                      | Description                     |
+| ------------------- | ---------------------------- | ------------------------------- |
+| `hooks`             | `pnpm dev:hooks`             | Payment lifecycle hooks         |
+| `preferred-network` | `pnpm dev:preferred-network` | Client-side network preferences |
+
+## Testing the Examples
 
-2. Copy `.env-example` to `.env` and add your Ethereum private key:
+Start a server first:
 
 ```bash
-cp .env-example .env
+cd ../../servers/express
+pnpm dev
 ```
 
-## Running Examples
+Then run the examples:
 
 ```bash
-# Run specific advanced example
-npm start hooks
-# or
+cd ../../clients/advanced
 pnpm dev:hooks
 ```
 
-## Architecture Patterns
-
-### Payment Lifecycle Hooks
+## Example: Payment Lifecycle Hooks
 
-Register hooks for complete observability and control:
+Register custom logic at different payment stages for observability and control:
 
 ```typescript
-import { x402Client } from "@x402/fetch";
+import { x402Client, wrapFetchWithPayment } from "@x402/fetch";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
 import { privateKeyToAccount } from "viem/accounts";
 
@@ -82,91 +76,76 @@ const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);
 const client = new x402Client()
   .register("eip155:*", new ExactEvmScheme(signer))
   .onBeforePaymentCreation(async context => {
-    // Custom validation logic
     console.log("Creating payment for:", context.selectedRequirements);
-    // Optionally abort: return { abort: true, reason: "Not allowed" };
+    // Abort payment by returning: { abort: true, reason: "Not allowed" }
   })
   .onAfterPaymentCreation(async context => {
-    // Log successful payment creation
-    console.log("Payment created:", context.version);
+    console.log("Payment created:", context.paymentPayload.x402Version);
     // Send to analytics, database, etc.
   })
   .onPaymentCreationFailure(async context => {
-    // Handle failures
     console.error("Payment failed:", context.error);
-    // Optionally recover with alternative method
+    // Recover by returning: { recovered: true, payload: alternativePayload }
   });
+
+const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+const response = await fetchWithPayment("http://localhost:4021/weather");
 ```
 
-## Production Considerations
+Available hooks:
+
+- `onBeforePaymentCreation` — Run before payment creation (can abort)
+- `onAfterPaymentCreation` — Run after successful payment creation
+- `onPaymentCreationFailure` — Run when payment creation fails (can recover)
 
-### Hook Best Practices
+**Use case:**
 
-1. **Keep hooks fast**: Avoid blocking operations
-2. **Handle errors gracefully**: Don't throw in hooks
-3. **Log appropriately**: Use structured logging
-4. **Avoid side effects in before hooks**: Only use for validation
+- Log payment events for debugging and monitoring
+- Custom validation before allowing payments
+- Implement retry or recovery logic for failed payments
+- Metrics and analytics collection
 
-### Error Recovery Strategy
+## Example: Preferred Network Selection
 
-Implement intelligent error handling in failure hooks:
+Configure client-side network preferences with automatic fallback:
 
 ```typescript
-client.onPaymentCreationFailure(async context => {
-  const errorType = classifyError(context.error);
-
-  switch (errorType) {
-    case "network":
-      // Retry logic handled by client
-      return undefined;
-    case "insufficient_balance":
-      // Alert user, no recovery
-      notifyUser("Insufficient balance");
-      return undefined;
-    case "signing_error":
-      // Attempt recovery with different method
-      return {
-        recovered: true,
-        payload: await createAlternativePayment(),
-      };
+import { x402Client, wrapFetchWithPayment, type PaymentRequirements } from "@x402/fetch";
+import { ExactEvmScheme } from "@x402/evm/exact/client";
+import { ExactSvmScheme } from "@x402/svm/exact/client";
+
+// Define network preference order (most preferred first)
+const networkPreferences = ["solana:", "eip155:"];
+
+const preferredNetworkSelector = (
+  _x402Version: number,
+  options: PaymentRequirements[],
+): PaymentRequirements => {
+  // Try each preference in order
+  for (const preference of networkPreferences) {
+    const match = options.find(opt => opt.network.startsWith(preference));
+    if (match) return match;
   }
-});
-```
-
-## Testing Against Local Server
+  // Fallback to first mutually-supported option
+  return options[0];
+};
 
-1. Start server:
+const client = new x402Client(preferredNetworkSelector)
+  .register("eip155:*", new ExactEvmScheme(evmSigner))
+  .register("solana:*", new ExactSvmScheme(svmSigner));
 
-```bash
-cd ../../servers/express
-pnpm dev
+const fetchWithPayment = wrapFetchWithPayment(fetch, client);
+const response = await fetchWithPayment("http://localhost:4021/weather");
 ```
 
-2. Run advanced examples:
-
-```bash
-cd ../../clients/advanced
-pnpm dev:hooks
-```
-
-## Comparison: Basic vs Advanced
-
-| Feature          | Basic Client | Advanced Client             |
-| ---------------- | ------------ | --------------------------- |
-| Payment Hooks    | None         | ✅ Lifecycle event handling |
-| Observability    | Minimal      | ✅ Comprehensive logging    |
-| Error Recovery   | Basic        | ✅ Intelligent strategies   |
-| Production Ready | Basic        | ✅ Battle-tested patterns   |
-
-## Next Steps
+**Use case:**
 
-- **[Basic Fetch Client](../fetch/)**: Start here if you haven't already
-- **[Basic Axios Client](../axios/)**: Alternative HTTP client
-- **[Custom Client](../custom/)**: Learn the internals
-- **[Server Examples](../../servers/)**: Build complementary servers
+- Prefer payments on specific chains
+- User preference settings in wallet UIs
 
-## Related Resources
+## Hook Best Practices
 
-- [x402 Core Package Documentation](../../../../typescript/packages/core/)
-- [x402 Fetch Package Documentation](../../../../typescript/packages/x402-fetch/)
-- [Production Deployment Guide](../../../../docs/production.md)
+1. **Keep hooks fast** — Avoid blocking operations
+2. **Handle errors gracefully** — Don't throw in hooks
+3. **Log appropriately** — Use structured logging
+4. **Avoid side effects in before hooks** — Only use for validation

examples/typescript/clients/axios/README.md

@@ -1,67 +1,55 @@
 # x402-axios Example Client
 
-This is an example client that demonstrates how to use the `x402-axios` package to make HTTP requests to endpoints protected by the x402 payment protocol.
+Example client demonstrating how to use `@x402/axios` to make HTTP requests to endpoints protected by the x402 payment protocol.
 
 ## Prerequisites
 
 - Node.js v20+ (install via [nvm](https://github.com/nvm-sh/nvm))
 - pnpm v10 (install via [pnpm.io/installation](https://pnpm.io/installation))
-- A running x402 server (you can use the example express server at `examples/typescript/servers/express`)
-- A valid Ethereum private key for making payments
+- A running x402 server (see [express server example](../../servers/express))
+- Valid EVM and/or SVM private keys for making payments
 
 ## Setup
 
 1. Install and build all packages from the typescript examples root:
 ```bash
 cd ../../
-pnpm install
-pnpm build
+pnpm install && pnpm build
 cd clients/axios
 ```
 
-2. Copy `.env-local` to `.env` and add your Ethereum private key:
+2. Copy `.env-local` to `.env` and add your private keys:
 ```bash
 cp .env-local .env
 ```
 
-3. Start the example client:
+Required environment variables:
+- `EVM_PRIVATE_KEY` - Ethereum private key for EVM payments
+- `SVM_PRIVATE_KEY` - Solana private key for SVM payments
 
+3. Run the client:
 ```bash
-# Run the default example (builder-pattern)
 pnpm start
-
-# Or run a specific example:
-pnpm start builder-pattern
-pnpm start mechanism-helper-registration
-
-# Or use the convenience scripts:
-pnpm dev                                # builder-pattern
-pnpm dev:mechanism-helper-registration  # mechanism-helper-registration
 ```
 
 ## Available Examples
 
-This package contains two examples demonstrating different ways to configure the x402 client:
-
 ### 1. Builder Pattern (`builder-pattern`)
-Demonstrates the basic way to configure the client by chaining `registerScheme` calls to map scheme patterns to mechanism clients.
+Configure the client by chaining `.register()` calls to map scheme patterns to mechanism clients.
 
-### 2. Mechanism Helper Registration (`mechanism-helper-registration`)
-Shows how to use convenience helper functions provided by `@x402/evm` and `@x402/svm` packages to register all supported networks with recommended defaults.
+```bash
+pnpm start builder-pattern
+```
 
-## How It Works
+### 2. Mechanism Helper Registration (`mechanism-helper-registration`)
+Use convenience helper functions from `@x402/evm` and `@x402/svm` to register supported networks.
 
-The examples demonstrate how to:
-1. Create and configure an x402Client with different patterns
-2. Register mechanism clients for different blockchain schemes (EVM, SVM)
-3. Wrap axios with x402 payment handling
-4. Make a request to a paid endpoint
-5. Handle the response and payment details
+```bash
+pnpm start mechanism-helper-registration
+```
 
 ## Example Code
 
-Here's a simplified version of the builder pattern:
-
 ```typescript
 import { x402Client, wrapAxiosWithPayment } from "@x402/axios";
 import { ExactEvmScheme } from "@x402/evm/exact/client";
@@ -80,10 +68,9 @@ const api = wrapAxiosWithPayment(axios.create(), client);
 
 // Make request to paid endpoint
 const response = await api.get("http://localhost:4021/weather");
-const body = response.data;
-console.log(body);
+console.log(response.data);
 ```
 
-See the individual example files for more detailed demonstrations:
-- `builder-pattern.ts` - Basic builder pattern
-- `mechanism-helper-registration.ts` - Using helper functions
+## Next Steps
+
+See [Advanced Examples](../advanced/) for payment lifecycle hooks and setting network preferences.

examples/typescript/clients/axios/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@x402/fetch-client-example",
+  "name": "@x402/axios-client-example",
   "private": true,
   "type": "module",
   "scripts": {