feat(examples): add advanced client usage examples

Add three new example files demonstrating advanced client features:

- client_error_handling.go: Comprehensive error handling patterns
  - ValidationError with field-level violations
  - Generic API errors
  - Network errors and timeouts
  - Context cancellation

- client_content_types.go: JSON vs binary protobuf
  - Default JSON client
  - Binary protobuf for performance
  - Per-request content type override
  - Performance comparison

- client_per_call_options.go: Per-request customization
  - Custom headers (tracing, correlation IDs)
  - Generated header helpers
  - Dynamic headers based on context
  - A/B testing with headers

Update README.md with documentation for all client examples.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

Author: SebastienMelki

examples/restful-crud/README.md

@@ -220,3 +220,88 @@ Path parameters like `{product_id}` are automatically bound from the URL path to
 ### Query Parameters
 
 Fields annotated with `(sebuf.http.query)` are parsed from URL query string instead of request body. This is useful for GET requests that shouldn't have a body.
+
+## Client Examples
+
+This directory contains several example files demonstrating advanced client usage patterns:
+
+| File | Description |
+|------|-------------|
+| `client_example.go` | Basic CRUD operations with the generated client |
+| `client_error_handling.go` | Comprehensive error handling patterns |
+| `client_content_types.go` | JSON vs binary protobuf content types |
+| `client_per_call_options.go` | Per-request customization with call options |
+
+### Running the Examples
+
+First, start the server:
+```bash
+make run
+```
+
+Then run any example:
+```bash
+go run client_example.go
+go run client_error_handling.go
+go run client_content_types.go
+go run client_per_call_options.go
+```
+
+### Error Handling Example
+
+Demonstrates handling different error types:
+- Validation errors (HTTP 400) with field-level details
+- Not found errors (HTTP 404)
+- Missing required headers
+- Network errors and timeouts
+- Context cancellation
+
+```go
+var validationErr *sebufhttp.ValidationError
+if errors.As(err, &validationErr) {
+    for _, violation := range validationErr.GetViolations() {
+        fmt.Printf("Field '%s': %s\n", violation.GetField(), violation.GetDescription())
+    }
+}
+```
+
+### Content Types Example
+
+Demonstrates switching between JSON and binary protobuf:
+- Default JSON client
+- Binary protobuf for better performance
+- Per-request content type override
+- Performance comparison
+
+```go
+// Default JSON
+client := services.NewProductServiceClient("http://localhost:8080")
+
+// Binary protobuf (30-50% smaller payloads)
+protoClient := services.NewProductServiceClient(
+    "http://localhost:8080",
+    services.WithProductServiceContentType(services.ContentTypeProto),
+)
+
+// Per-request override
+client.ListProducts(ctx, req,
+    services.WithProductServiceCallContentType(services.ContentTypeProto),
+)
+```
+
+### Per-Call Options Example
+
+Demonstrates request-level customization:
+- Custom headers per request (tracing, correlation IDs)
+- Generated header helpers
+- Content type override per request
+- Dynamic headers based on context
+- A/B testing with headers
+
+```go
+product, err := client.CreateProduct(ctx, req,
+    services.WithProductServiceHeader("X-Request-ID", "req-123"),
+    services.WithProductServiceHeader("X-Correlation-ID", "corr-456"),
+    services.WithProductServiceCallContentType(services.ContentTypeProto),
+)
+```

examples/restful-crud/client_content_types.go

@@ -0,0 +1,154 @@
+//go:build ignore
+
+// This example demonstrates content type switching between JSON and binary protobuf.
+// Run with: go run client_content_types.go
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net/http"
+	"time"
+
+	"github.com/SebastienMelki/sebuf/examples/restful-crud/api/proto/models"
+	"github.com/SebastienMelki/sebuf/examples/restful-crud/api/proto/services"
+)
+
+func main() {
+	ctx := context.Background()
+
+	fmt.Println("=== Content Type Examples ===\n")
+
+	// Example 1: Default JSON client
+	fmt.Println("1. JSON Client (Default)")
+	jsonClient := services.NewProductServiceClient(
+		"http://localhost:8080",
+		services.WithProductServiceAPIKey("123e4567-e89b-12d3-a456-426614174000"),
+		// JSON is the default, no need to specify
+	)
+
+	product, err := createTestProduct(ctx, jsonClient, "JSON Product")
+	if err != nil {
+		log.Printf("   Error: %v\n", err)
+	} else {
+		fmt.Printf("   Created product via JSON: %s (ID: %s)\n", product.Name, product.Id)
+	}
+
+	// Example 2: Binary protobuf client (better performance for large payloads)
+	fmt.Println("\n2. Binary Protobuf Client (Better Performance)")
+	protoClient := services.NewProductServiceClient(
+		"http://localhost:8080",
+		services.WithProductServiceAPIKey("123e4567-e89b-12d3-a456-426614174000"),
+		services.WithProductServiceContentType(services.ContentTypeProto),
+	)
+
+	product, err = createTestProduct(ctx, protoClient, "Protobuf Product")
+	if err != nil {
+		log.Printf("   Error: %v\n", err)
+	} else {
+		fmt.Printf("   Created product via Protobuf: %s (ID: %s)\n", product.Name, product.Id)
+	}
+
+	// Example 3: Per-request content type override
+	fmt.Println("\n3. Per-Request Content Type Override")
+	fmt.Println("   Using JSON client but overriding to Protobuf for one request...")
+
+	// Client defaults to JSON
+	mixedClient := services.NewProductServiceClient(
+		"http://localhost:8080",
+		services.WithProductServiceAPIKey("123e4567-e89b-12d3-a456-426614174000"),
+		// Default: JSON
+	)
+
+	// But this specific request uses Protobuf
+	product, err = mixedClient.CreateProduct(ctx, &models.CreateProductRequest{
+		Name:        "Mixed Content Product",
+		Description: "Created with Protobuf override",
+		Price:       39.99,
+		CategoryId:  "mixed",
+	},
+		services.WithProductServiceCallContentType(services.ContentTypeProto),
+	)
+
+	if err != nil {
+		log.Printf("   Error: %v\n", err)
+	} else {
+		fmt.Printf("   Created product with Protobuf override: %s\n", product.Name)
+	}
+
+	// Example 4: Performance comparison
+	fmt.Println("\n4. Performance Comparison (JSON vs Protobuf)")
+	runPerformanceComparison(ctx, jsonClient, protoClient)
+
+	// Example 5: When to use each content type
+	fmt.Println("\n5. Content Type Guidelines")
+	fmt.Println("   JSON (application/json):")
+	fmt.Println("      - Human-readable, easy to debug")
+	fmt.Println("      - Better for browser/JavaScript clients")
+	fmt.Println("      - Larger payload size")
+	fmt.Println("      - Default choice for most APIs")
+	fmt.Println("")
+	fmt.Println("   Protobuf (application/x-protobuf):")
+	fmt.Println("      - Smaller payload size (30-50% smaller)")
+	fmt.Println("      - Faster serialization/deserialization")
+	fmt.Println("      - Better for high-throughput services")
+	fmt.Println("      - Better for large payloads or batch operations")
+	fmt.Println("      - Requires protobuf-aware clients")
+
+	fmt.Println("\n=== Content Type Examples Complete ===")
+}
+
+func createTestProduct(ctx context.Context, client services.ProductServiceClient, name string) (*models.Product, error) {
+	return client.CreateProduct(ctx, &models.CreateProductRequest{
+		Name:        name,
+		Description: "Test product for content type demo",
+		Price:       29.99,
+		CategoryId:  "test",
+		Tags:        []string{"demo", "test"},
+	})
+}
+
+func runPerformanceComparison(ctx context.Context, jsonClient, protoClient services.ProductServiceClient) {
+	iterations := 10
+
+	// Measure JSON performance
+	jsonStart := time.Now()
+	for i := 0; i < iterations; i++ {
+		_, err := jsonClient.ListProducts(ctx, &models.ListProductsRequest{
+			Page:  1,
+			Limit: 50,
+		})
+		if err != nil {
+			log.Printf("   JSON request %d failed: %v", i, err)
+			return
+		}
+	}
+	jsonDuration := time.Since(jsonStart)
+
+	// Measure Protobuf performance
+	protoStart := time.Now()
+	for i := 0; i < iterations; i++ {
+		_, err := protoClient.ListProducts(ctx, &models.ListProductsRequest{
+			Page:  1,
+			Limit: 50,
+		})
+		if err != nil {
+			log.Printf("   Protobuf request %d failed: %v", i, err)
+			return
+		}
+	}
+	protoDuration := time.Since(protoStart)
+
+	fmt.Printf("   JSON:     %d requests in %v (avg: %v/req)\n",
+		iterations, jsonDuration, jsonDuration/time.Duration(iterations))
+	fmt.Printf("   Protobuf: %d requests in %v (avg: %v/req)\n",
+		iterations, protoDuration, protoDuration/time.Duration(iterations))
+
+	if protoDuration < jsonDuration {
+		improvement := float64(jsonDuration-protoDuration) / float64(jsonDuration) * 100
+		fmt.Printf("   Protobuf is %.1f%% faster\n", improvement)
+	} else {
+		fmt.Println("   (Results may vary based on payload size and network conditions)")
+	}
+}