schemantic 0.2.1 → 0.4.0

package/docs/FASTAPI_TUTORIAL.md

@@ -1,1497 +1,109 @@
-# FastAPI + Schemantic: Complete Tutorial
-
-This tutorial shows you how to build a complete, type-safe full-stack application using FastAPI, Schemantic, and React with TypeScript.
-
-## Prerequisites
-
-- Python 3.8+ with pip
-- Node.js 16+ with npm
-- Basic knowledge of FastAPI and React
-
-## Project Overview
-
-We'll build an e-commerce API with the following features:
-
-- User authentication and management
-- Product catalog
-- Order management
-- Type-safe frontend with generated API client
-- React hooks for data fetching
-
-## Part 1: FastAPI Backend Setup
-
-### 1.1 Create the FastAPI Project
-
-```bash
-# Create project directory
-mkdir fastapi-Schemantic-demo
-cd fastapi-Schemantic-demo
-
-# Create backend directory
-mkdir backend
-cd backend
-
-# Create virtual environment
-python -m venv venv
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-
-# Install dependencies
-pip install fastapi uvicorn pydantic sqlalchemy python-jose[cryptography] passlib[bcrypt] python-multipart
-```
-
-### 1.2 Create the Database Models
-
-Create `backend/models.py`:
-
-```python
-from sqlalchemy import Column, Integer, String, Float, DateTime, ForeignKey, Boolean
-from sqlalchemy.ext.declarative import declarative_base
-from sqlalchemy.orm import relationship
-from datetime import datetime
-
-Base = declarative_base()
-
-class User(Base):
-    __tablename__ = "users"
-
-    id = Column(Integer, primary_key=True, index=True)
-    email = Column(String, unique=True, index=True, nullable=False)
-    username = Column(String, unique=True, index=True, nullable=False)
-    hashed_password = Column(String, nullable=False)
-    full_name = Column(String)
-    is_active = Column(Boolean, default=True)
-    is_admin = Column(Boolean, default=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-    # Relationships
-    orders = relationship("Order", back_populates="user")
-
-class Product(Base):
-    __tablename__ = "products"
-
-    id = Column(Integer, primary_key=True, index=True)
-    name = Column(String, nullable=False)
-    description = Column(String)
-    price = Column(Float, nullable=False)
-    category = Column(String, nullable=False)
-    stock_quantity = Column(Integer, default=0)
-    image_url = Column(String)
-    is_active = Column(Boolean, default=True)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-    # Relationships
-    order_items = relationship("OrderItem", back_populates="product")
-
-class Order(Base):
-    __tablename__ = "orders"
-
-    id = Column(Integer, primary_key=True, index=True)
-    user_id = Column(Integer, ForeignKey("users.id"), nullable=False)
-    total_amount = Column(Float, nullable=False)
-    status = Column(String, default="pending")  # pending, processing, shipped, delivered, cancelled
-    shipping_address = Column(String, nullable=False)
-    created_at = Column(DateTime, default=datetime.utcnow)
-    updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)
-
-    # Relationships
-    user = relationship("User", back_populates="orders")
-    items = relationship("OrderItem", back_populates="order")
-
-class OrderItem(Base):
-    __tablename__ = "order_items"
-
-    id = Column(Integer, primary_key=True, index=True)
-    order_id = Column(Integer, ForeignKey("orders.id"), nullable=False)
-    product_id = Column(Integer, ForeignKey("products.id"), nullable=False)
-    quantity = Column(Integer, nullable=False)
-    unit_price = Column(Float, nullable=False)
-
-    # Relationships
-    order = relationship("Order", back_populates="items")
-    product = relationship("Product", back_populates="order_items")
-```
-
-### 1.3 Create Pydantic Schemas
-
-Create `backend/schemas.py`:
-
-```python
-from pydantic import BaseModel, EmailStr, Field
-from datetime import datetime
-from typing import List, Optional
-from enum import Enum
-
-# Enums
-class OrderStatus(str, Enum):
-    pending = "pending"
-    processing = "processing"
-    shipped = "shipped"
-    delivered = "delivered"
-    cancelled = "cancelled"
-
-class ProductCategory(str, Enum):
-    electronics = "electronics"
-    clothing = "clothing"
-    books = "books"
-    home = "home"
-    sports = "sports"
-
-# Base schemas
-class UserBase(BaseModel):
-    email: EmailStr = Field(..., description="User's email address")
-    username: str = Field(..., min_length=3, max_length=50, description="Unique username")
-    full_name: Optional[str] = Field(None, max_length=100, description="User's full name")
-
-class UserCreate(UserBase):
-    password: str = Field(..., min_length=8, description="User's password (min 8 characters)")
-
-class UserUpdate(BaseModel):
-    email: Optional[EmailStr] = Field(None, description="Updated email address")
-    username: Optional[str] = Field(None, min_length=3, max_length=50, description="Updated username")
-    full_name: Optional[str] = Field(None, max_length=100, description="Updated full name")
-    is_active: Optional[bool] = Field(None, description="Whether user is active")
-
-class User(UserBase):
-    id: int = Field(..., description="Unique user identifier")
-    is_active: bool = Field(..., description="Whether user is active")
-    is_admin: bool = Field(..., description="Whether user has admin privileges")
-    created_at: datetime = Field(..., description="User creation timestamp")
-    updated_at: datetime = Field(..., description="Last update timestamp")
-
-    class Config:
-        from_attributes = True
-
-# Product schemas
-class ProductBase(BaseModel):
-    name: str = Field(..., min_length=1, max_length=200, description="Product name")
-    description: Optional[str] = Field(None, max_length=1000, description="Product description")
-    price: float = Field(..., gt=0, description="Product price (must be positive)")
-    category: ProductCategory = Field(..., description="Product category")
-    stock_quantity: int = Field(0, ge=0, description="Available stock quantity")
-    image_url: Optional[str] = Field(None, description="Product image URL")
-
-class ProductCreate(ProductBase):
-    pass
-
-class ProductUpdate(BaseModel):
-    name: Optional[str] = Field(None, min_length=1, max_length=200, description="Updated product name")
-    description: Optional[str] = Field(None, max_length=1000, description="Updated description")
-    price: Optional[float] = Field(None, gt=0, description="Updated price")
-    category: Optional[ProductCategory] = Field(None, description="Updated category")
-    stock_quantity: Optional[int] = Field(None, ge=0, description="Updated stock quantity")
-    image_url: Optional[str] = Field(None, description="Updated image URL")
-    is_active: Optional[bool] = Field(None, description="Whether product is active")
-
-class Product(ProductBase):
-    id: int = Field(..., description="Unique product identifier")
-    is_active: bool = Field(..., description="Whether product is active")
-    created_at: datetime = Field(..., description="Product creation timestamp")
-    updated_at: datetime = Field(..., description="Last update timestamp")
-
-    class Config:
-        from_attributes = True
-
-# Order schemas
-class OrderItemBase(BaseModel):
-    product_id: int = Field(..., description="Product identifier")
-    quantity: int = Field(..., gt=0, description="Quantity ordered")
-
-class OrderItemCreate(OrderItemBase):
-    pass
-
-class OrderItem(OrderItemBase):
-    id: int = Field(..., description="Unique order item identifier")
-    unit_price: float = Field(..., description="Price per unit at time of order")
-    product: Product = Field(..., description="Product details")
-
-    class Config:
-        from_attributes = True
-
-class OrderBase(BaseModel):
-    shipping_address: str = Field(..., min_length=10, max_length=500, description="Shipping address")
-
-class OrderCreate(OrderBase):
-    items: List[OrderItemCreate] = Field(..., min_items=1, description="List of items to order")
-
-class OrderUpdate(BaseModel):
-    status: Optional[OrderStatus] = Field(None, description="Updated order status")
-    shipping_address: Optional[str] = Field(None, min_length=10, max_length=500, description="Updated shipping address")
-
-class Order(OrderBase):
-    id: int = Field(..., description="Unique order identifier")
-    user_id: int = Field(..., description="User who placed the order")
-    total_amount: float = Field(..., description="Total order amount")
-    status: OrderStatus = Field(..., description="Current order status")
-    created_at: datetime = Field(..., description="Order creation timestamp")
-    updated_at: datetime = Field(..., description="Last update timestamp")
-    items: List[OrderItem] = Field(..., description="List of ordered items")
-    user: User = Field(..., description="User details")
-
-    class Config:
-        from_attributes = True
-
-# Authentication schemas
-class Token(BaseModel):
-    access_token: str = Field(..., description="JWT access token")
-    token_type: str = Field("bearer", description="Token type")
-
-class TokenData(BaseModel):
-    username: Optional[str] = None
-
-class LoginRequest(BaseModel):
-    username: str = Field(..., description="Username or email")
-    password: str = Field(..., description="User password")
-
-# API Response schemas
-class APIResponse(BaseModel):
-    success: bool = Field(..., description="Whether the operation was successful")
-    message: str = Field(..., description="Response message")
-    data: Optional[dict] = Field(None, description="Response data")
-
-class PaginatedResponse(BaseModel):
-    items: List[dict] = Field(..., description="List of items")
-    total: int = Field(..., description="Total number of items")
-    page: int = Field(..., description="Current page number")
-    per_page: int = Field(..., description="Items per page")
-    pages: int = Field(..., description="Total number of pages")
-
-# Health check schema
-class HealthCheck(BaseModel):
-    status: str = Field("healthy", description="Service health status")
-    timestamp: datetime = Field(..., description="Health check timestamp")
-    version: str = Field("1.0.0", description="API version")
-```
-
-### 1.4 Create the FastAPI Application
-
-Create `backend/main.py`:
-
-```python
-from fastapi import FastAPI, Depends, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
-from fastapi.middleware.cors import CORSMiddleware
-from sqlalchemy.orm import Session
-from typing import List, Optional
-from datetime import datetime, timedelta
-import uvicorn
-
-from models import Base, User, Product, Order, OrderItem
-from schemas import (
-    User as UserSchema, UserCreate, UserUpdate,
-    Product as ProductSchema, ProductCreate, ProductUpdate,
-    Order as OrderSchema, OrderCreate, OrderUpdate,
-    Token, LoginRequest, HealthCheck, APIResponse, PaginatedResponse,
-    OrderStatus, ProductCategory
-)
-from database import engine, get_db
-from auth import authenticate_user, create_access_token, get_current_user, get_password_hash
-
-# Create database tables
-Base.metadata.create_all(bind=engine)
-
-# FastAPI app configuration
-app = FastAPI(
-    title="E-Commerce API",
-    description="A comprehensive e-commerce API built with FastAPI and Schemantic",
-    version="1.0.0",
-    contact={
-        "name": "API Support",
-        "email": "support@ecommerce-api.com",
-    },
-    license_info={
-        "name": "MIT",
-        "url": "https://opensource.org/licenses/MIT",
-    },
-)
-
-# CORS middleware
-app.add_middleware(
-    CORSMiddleware,
-    allow_origins=["http://localhost:3000", "http://localhost:5173"],  # React dev servers
-    allow_credentials=True,
-    allow_methods=["*"],
-    allow_headers=["*"],
-)
-
-# OAuth2 scheme
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/login")
-
-# Health check endpoint
-@app.get("/health", response_model=HealthCheck, tags=["Health"])
-async def health_check():
-    """Check the health status of the API"""
-    return HealthCheck(timestamp=datetime.utcnow())
-
-# Authentication endpoints
-@app.post("/auth/register", response_model=UserSchema, tags=["Authentication"])
-async def register_user(user: UserCreate, db: Session = Depends(get_db)):
-    """Register a new user account"""
-    # Check if user already exists
-    db_user = db.query(User).filter(
-        (User.email == user.email) | (User.username == user.username)
-    ).first()
-
-    if db_user:
-        raise HTTPException(
-            status_code=400,
-            detail="User with this email or username already exists"
-        )
-
-    # Create new user
-    hashed_password = get_password_hash(user.password)
-    db_user = User(
-        email=user.email,
-        username=user.username,
-        full_name=user.full_name,
-        hashed_password=hashed_password
-    )
-
-    db.add(db_user)
-    db.commit()
-    db.refresh(db_user)
-
-    return db_user
-
-@app.post("/auth/login", response_model=Token, tags=["Authentication"])
-async def login_user(form_data: OAuth2PasswordRequestForm = Depends(), db: Session = Depends(get_db)):
-    """Authenticate user and return access token"""
-    user = authenticate_user(db, form_data.username, form_data.password)
-    if not user:
-        raise HTTPException(
-            status_code=status.HTTP_401_UNAUTHORIZED,
-            detail="Incorrect username or password",
-            headers={"WWW-Authenticate": "Bearer"},
-        )
-
-    access_token = create_access_token(data={"sub": user.username})
-    return {"access_token": access_token, "token_type": "bearer"}
-
-@app.get("/auth/me", response_model=UserSchema, tags=["Authentication"])
-async def get_current_user_info(current_user: User = Depends(get_current_user)):
-    """Get current authenticated user information"""
-    return current_user
-
-# User management endpoints
-@app.get("/users", response_model=List[UserSchema], tags=["Users"])
-async def get_users(
-    skip: int = 0,
-    limit: int = 100,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Get list of users (admin only)"""
-    if not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    users = db.query(User).offset(skip).limit(limit).all()
-    return users
-
-@app.get("/users/{user_id}", response_model=UserSchema, tags=["Users"])
-async def get_user(
-    user_id: int,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Get user by ID"""
-    if current_user.id != user_id and not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    user = db.query(User).filter(User.id == user_id).first()
-    if user is None:
-        raise HTTPException(status_code=404, detail="User not found")
-
-    return user
-
-@app.put("/users/{user_id}", response_model=UserSchema, tags=["Users"])
-async def update_user(
-    user_id: int,
-    user_update: UserUpdate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Update user information"""
-    if current_user.id != user_id and not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    user = db.query(User).filter(User.id == user_id).first()
-    if user is None:
-        raise HTTPException(status_code=404, detail="User not found")
-
-    update_data = user_update.dict(exclude_unset=True)
-    for field, value in update_data.items():
-        setattr(user, field, value)
-
-    user.updated_at = datetime.utcnow()
-    db.commit()
-    db.refresh(user)
-
-    return user
-
-# Product endpoints
-@app.get("/products", response_model=List[ProductSchema], tags=["Products"])
-async def get_products(
-    skip: int = 0,
-    limit: int = 100,
-    category: Optional[ProductCategory] = None,
-    search: Optional[str] = None,
-    db: Session = Depends(get_db)
-):
-    """Get list of products with optional filtering"""
-    query = db.query(Product).filter(Product.is_active == True)
-
-    if category:
-        query = query.filter(Product.category == category)
-
-    if search:
-        query = query.filter(Product.name.contains(search))
-
-    products = query.offset(skip).limit(limit).all()
-    return products
-
-@app.get("/products/{product_id}", response_model=ProductSchema, tags=["Products"])
-async def get_product(product_id: int, db: Session = Depends(get_db)):
-    """Get product by ID"""
-    product = db.query(Product).filter(Product.id == product_id, Product.is_active == True).first()
-    if product is None:
-        raise HTTPException(status_code=404, detail="Product not found")
-
-    return product
-
-@app.post("/products", response_model=ProductSchema, tags=["Products"])
-async def create_product(
-    product: ProductCreate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Create a new product (admin only)"""
-    if not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    db_product = Product(**product.dict())
-    db.add(db_product)
-    db.commit()
-    db.refresh(db_product)
-
-    return db_product
-
-@app.put("/products/{product_id}", response_model=ProductSchema, tags=["Products"])
-async def update_product(
-    product_id: int,
-    product_update: ProductUpdate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Update product (admin only)"""
-    if not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    product = db.query(Product).filter(Product.id == product_id).first()
-    if product is None:
-        raise HTTPException(status_code=404, detail="Product not found")
-
-    update_data = product_update.dict(exclude_unset=True)
-    for field, value in update_data.items():
-        setattr(product, field, value)
-
-    product.updated_at = datetime.utcnow()
-    db.commit()
-    db.refresh(product)
-
-    return product
-
-# Order endpoints
-@app.get("/orders", response_model=List[OrderSchema], tags=["Orders"])
-async def get_orders(
-    skip: int = 0,
-    limit: int = 100,
-    status: Optional[OrderStatus] = None,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Get user's orders"""
-    query = db.query(Order).filter(Order.user_id == current_user.id)
-
-    if status:
-        query = query.filter(Order.status == status)
-
-    orders = query.offset(skip).limit(limit).all()
-    return orders
-
-@app.get("/orders/{order_id}", response_model=OrderSchema, tags=["Orders"])
-async def get_order(
-    order_id: int,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Get order by ID"""
-    order = db.query(Order).filter(Order.id == order_id).first()
-    if order is None:
-        raise HTTPException(status_code=404, detail="Order not found")
-
-    if order.user_id != current_user.id and not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    return order
-
-@app.post("/orders", response_model=OrderSchema, tags=["Orders"])
-async def create_order(
-    order: OrderCreate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Create a new order"""
-    total_amount = 0
-    order_items = []
-
-    # Calculate total and validate products
-    for item in order.items:
-        product = db.query(Product).filter(Product.id == item.product_id, Product.is_active == True).first()
-        if not product:
-            raise HTTPException(status_code=404, detail=f"Product {item.product_id} not found")
-
-        if product.stock_quantity < item.quantity:
-            raise HTTPException(status_code=400, detail=f"Insufficient stock for product {product.name}")
-
-        item_total = product.price * item.quantity
-        total_amount += item_total
-
-        order_items.append(OrderItem(
-            product_id=item.product_id,
-            quantity=item.quantity,
-            unit_price=product.price
-        ))
-
-    # Create order
-    db_order = Order(
-        user_id=current_user.id,
-        total_amount=total_amount,
-        shipping_address=order.shipping_address,
-        items=order_items
-    )
-
-    # Update product stock
-    for item in order.items:
-        product = db.query(Product).filter(Product.id == item.product_id).first()
-        product.stock_quantity -= item.quantity
-
-    db.add(db_order)
-    db.commit()
-    db.refresh(db_order)
-
-    return db_order
-
-@app.put("/orders/{order_id}", response_model=OrderSchema, tags=["Orders"])
-async def update_order(
-    order_id: int,
-    order_update: OrderUpdate,
-    current_user: User = Depends(get_current_user),
-    db: Session = Depends(get_db)
-):
-    """Update order status (admin only for status changes)"""
-    order = db.query(Order).filter(Order.id == order_id).first()
-    if order is None:
-        raise HTTPException(status_code=404, detail="Order not found")
-
-    # Check permissions
-    if order.user_id != current_user.id and not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Not enough permissions")
-
-    # Only admins can change status
-    if order_update.status and not current_user.is_admin:
-        raise HTTPException(status_code=403, detail="Only admins can change order status")
-
-    update_data = order_update.dict(exclude_unset=True)
-    for field, value in update_data.items():
-        setattr(order, field, value)
-
-    order.updated_at = datetime.utcnow()
-    db.commit()
-    db.refresh(order)
-
-    return order
-
-if __name__ == "__main__":
-    uvicorn.run(app, host="0.0.0.0", port=8000)
-```
-
-### 1.5 Create Database Configuration
-
-Create `backend/database.py`:
-
-```python
-from sqlalchemy import create_engine
-from sqlalchemy.orm import sessionmaker
-
-DATABASE_URL = "sqlite:///./ecommerce.db"
-
-engine = create_engine(
-    DATABASE_URL, connect_args={"check_same_thread": False}
-)
-SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
-
-def get_db():
-    db = SessionLocal()
-    try:
-        yield db
-    finally:
-        db.close()
-```
-
-### 1.6 Create Authentication System
-
-Create `backend/auth.py`:
-
-```python
-from datetime import datetime, timedelta
-from typing import Optional
-from fastapi import Depends, HTTPException, status
-from fastapi.security import OAuth2PasswordBearer
-from jose import JWTError, jwt
-from passlib.context import CryptContext
-from sqlalchemy.orm import Session
-
-from models import User
-from schemas import TokenData
-from database import get_db
-
-# Configuration
-SECRET_KEY = "your-secret-key-here"  # In production, use environment variable
-ALGORITHM = "HS256"
-ACCESS_TOKEN_EXPIRE_MINUTES = 30
-
-# Password hashing
-pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
-oauth2_scheme = OAuth2PasswordBearer(tokenUrl="auth/login")
-
-def verify_password(plain_password, hashed_password):
-    return pwd_context.verify(plain_password, hashed_password)
-
-def get_password_hash(password):
-    return pwd_context.hash(password)
-
-def authenticate_user(db: Session, username: str, password: str):
-    user = db.query(User).filter(
-        (User.username == username) | (User.email == username)
-    ).first()
-
-    if not user or not verify_password(password, user.hashed_password):
-        return False
-
-    return user
-
-def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
-    to_encode = data.copy()
-    if expires_delta:
-        expire = datetime.utcnow() + expires_delta
-    else:
-        expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
-
-    to_encode.update({"exp": expire})
-    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
-    return encoded_jwt
-
-async def get_current_user(token: str = Depends(oauth2_scheme), db: Session = Depends(get_db)):
-    credentials_exception = HTTPException(
-        status_code=status.HTTP_401_UNAUTHORIZED,
-        detail="Could not validate credentials",
-        headers={"WWW-Authenticate": "Bearer"},
-    )
-
-    try:
-        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
-        username: str = payload.get("sub")
-        if username is None:
-            raise credentials_exception
-        token_data = TokenData(username=username)
-    except JWTError:
-        raise credentials_exception
-
-    user = db.query(User).filter(User.username == token_data.username).first()
-    if user is None:
-        raise credentials_exception
-
-    return user
-```
-
-### 1.7 Run the FastAPI Server
-
-```bash
-cd backend
-uvicorn main:app --reload
-```
-
-Your API will be available at http://localhost:8000, with interactive docs at http://localhost:8000/docs.
-
-## Part 2: Generate TypeScript Types with Schemantic
-
-### 2.1 Install Schemantic
-
-```bash
-# Go back to project root
-cd ..
-
-# Install Schemantic
-npm install -g schemantic
-```
-
-### 2.2 Generate Types and API Client
-
-```bash
-# Create output directory
-mkdir frontend/src/generated
-
-# Generate types and API client with React hooks
-npx schemantic generate \
-  --url http://localhost:8000/openapi.json \
-  --output ./frontend/src/generated \
-  --hooks \
-  --naming camelCase \
-  # No prefix by default; to add a prefix use --prefix "MyAPI"
-
-# Generated files:
-# - types.ts (TypeScript interfaces)
-# - api-client.ts (API client class)
-# - hooks.ts (React hooks)
-# - index.ts (barrel exports)
-```
-
-### 2.3 Verify Generated Types
-
-Check the generated files:
-
-```typescript
-// frontend/src/generated/types.ts
-export interface APIUser {
-  id: number;
-  email: string;
-  username: string;
-  fullName?: string;
-  isActive: boolean;
-  isAdmin: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export interface APIProduct {
-  id: number;
-  name: string;
-  description?: string;
-  price: number;
-  category: APIProductCategory;
-  stockQuantity: number;
-  imageUrl?: string;
-  isActive: boolean;
-  createdAt: string;
-  updatedAt: string;
-}
-
-export enum APIProductCategory {
-  ELECTRONICS = "electronics",
-  CLOTHING = "clothing",
-  BOOKS = "books",
-  HOME = "home",
-  SPORTS = "sports",
-}
-
-export enum APIOrderStatus {
-  PENDING = "pending",
-  PROCESSING = "processing",
-  SHIPPED = "shipped",
-  DELIVERED = "delivered",
-  CANCELLED = "cancelled",
-}
-
-// ... many more types
-```
-
-## Part 3: React Frontend Setup
-
-### 3.1 Create React Application
-
-```bash
-# Create React app with TypeScript
-npx create-react-app frontend --template typescript
-cd frontend
-
-# Install additional dependencies
-npm install @tanstack/react-query axios react-router-dom @types/react-router-dom
-npm install @mui/material @emotion/react @emotion/styled @mui/icons-material
-```
-
-### 3.2 Configure API Client
-
-Create `frontend/src/api/client.ts`:
-
-```typescript
-import { ECommerceApiClient } from "../generated";
-
-// Create API client instance
-export const apiClient = new ECommerceApiClient({
-  baseUrl: "http://localhost:8000",
-  headers: {
-    "Content-Type": "application/json",
-  },
-});
-
-// Add authentication token to requests
-export const setAuthToken = (token: string) => {
-  apiClient.setDefaultHeader("Authorization", `Bearer ${token}`);
-};
-
-export const clearAuthToken = () => {
-  apiClient.removeDefaultHeader("Authorization");
-};
-```
-
-### 3.3 Setup React Query and Hooks
-
-Create `frontend/src/hooks/api.ts`:
-
-```typescript
-import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
-import { apiClient } from "../api/client";
-import { createApiHooks } from "../generated";
-
-// Create typed hooks
-export const apiHooks = createApiHooks(apiClient);
-
-// Export specific hooks for easy use
-export const {
-  // Authentication hooks
-  useAuthRegisterMutation,
-  useAuthLoginMutation,
-  useAuthMeQuery,
-
-  // User hooks
-  useUsersQuery,
-  useUsersUserIdQuery,
-  useUsersUserIdMutation,
-
-  // Product hooks
-  useProductsQuery,
-  useProductsProductIdQuery,
-  useProductsMutation,
-  useProductsProductIdMutation,
-
-  // Order hooks
-  useOrdersQuery,
-  useOrdersOrderIdQuery,
-  useOrdersMutation,
-  useOrdersOrderIdMutation,
-} = apiHooks;
-
-// Custom hooks for common patterns
-export const useAuth = () => {
-  const queryClient = useQueryClient();
-
-  const loginMutation = useAuthLoginMutation({
-    onSuccess: (data) => {
-      localStorage.setItem("token", data.accessToken);
-      queryClient.invalidateQueries(["auth", "me"]);
-    },
-  });
-
-  const logout = () => {
-    localStorage.removeItem("token");
-    queryClient.clear();
-  };
-
-  return {
-    login: loginMutation.mutate,
-    logout,
-    isLoading: loginMutation.isLoading,
-    error: loginMutation.error,
-  };
-};
-
-export const useProducts = (filters?: {
-  category?: string;
-  search?: string;
-  page?: number;
-  limit?: number;
-}) => {
-  return useProductsQuery({
-    query: {
-      skip: ((filters?.page || 1) - 1) * (filters?.limit || 20),
-      limit: filters?.limit || 20,
-      category: filters?.category,
-      search: filters?.search,
-    },
-  });
-};
-
-export const useUserOrders = (userId?: number) => {
-  return useOrdersQuery({
-    enabled: !!userId,
-  });
-};
-```
-
-### 3.4 Create React Components
-
-Create `frontend/src/components/ProductList.tsx`:
-
-```typescript
-import React, { useState } from "react";
-import {
-  Grid,
-  Card,
-  CardContent,
-  CardMedia,
-  Typography,
-  Button,
-  TextField,
-  Select,
-  MenuItem,
-  FormControl,
-  InputLabel,
-  Box,
-  CircularProgress,
-  Alert,
-} from "@mui/material";
-import { APIProduct, APIProductCategory } from "../generated";
-import { useProducts } from "../hooks/api";
-
-interface ProductListProps {
-  onAddToCart?: (product: APIProduct) => void;
-}
-
-export const ProductList: React.FC<ProductListProps> = ({ onAddToCart }) => {
-  const [search, setSearch] = useState("");
-  const [category, setCategory] = useState<APIProductCategory | "">("");
-  const [page, setPage] = useState(1);
-
-  const {
-    data: products,
-    isLoading,
-    error,
-  } = useProducts({
-    search: search || undefined,
-    category: category || undefined,
-    page,
-    limit: 12,
-  });
-
-  if (isLoading) {
-    return (
-      <Box display="flex" justifyContent="center" p={4}>
-        <CircularProgress />
-      </Box>
-    );
-  }
-
-  if (error) {
-    return (
-      <Alert severity="error">Failed to load products: {error.message}</Alert>
-    );
-  }
-
-  return (
-    <Box>
-      {/* Filters */}
-      <Box display="flex" gap={2} mb={3}>
-        <TextField
-          label="Search products"
-          value={search}
-          onChange={(e) => setSearch(e.target.value)}
-          variant="outlined"
-          size="small"
-          sx={{ minWidth: 200 }}
-        />
-
-        <FormControl size="small" sx={{ minWidth: 150 }}>
-          <InputLabel>Category</InputLabel>
-          <Select
-            value={category}
-            onChange={(e) => setCategory(e.target.value as APIProductCategory)}
-            label="Category"
-          >
-            <MenuItem value="">All Categories</MenuItem>
-            {Object.values(APIProductCategory).map((cat) => (
-              <MenuItem key={cat} value={cat}>
-                {cat.charAt(0).toUpperCase() + cat.slice(1)}
-              </MenuItem>
-            ))}
-          </Select>
-        </FormControl>
-      </Box>
-
-      {/* Product Grid */}
-      <Grid container spacing={3}>
-        {products?.map((product) => (
-          <Grid item xs={12} sm={6} md={4} lg={3} key={product.id}>
-            <Card>
-              {product.imageUrl && (
-                <CardMedia
-                  component="img"
-                  height="200"
-                  image={product.imageUrl}
-                  alt={product.name}
-                />
-              )}
-
-              <CardContent>
-                <Typography variant="h6" component="h2" gutterBottom>
-                  {product.name}
-                </Typography>
-
-                <Typography variant="body2" color="text.secondary" paragraph>
-                  {product.description}
-                </Typography>
-
-                <Typography variant="h6" color="primary" gutterBottom>
-                  ${product.price.toFixed(2)}
-                </Typography>
-
-                <Typography variant="body2" color="text.secondary">
-                  Stock: {product.stockQuantity}
-                </Typography>
-
-                <Button
-                  variant="contained"
-                  fullWidth
-                  sx={{ mt: 2 }}
-                  disabled={product.stockQuantity === 0}
-                  onClick={() => onAddToCart?.(product)}
-                >
-                  {product.stockQuantity === 0 ? "Out of Stock" : "Add to Cart"}
-                </Button>
-              </CardContent>
-            </Card>
-          </Grid>
-        ))}
-      </Grid>
-    </Box>
-  );
-};
-```
-
-Create `frontend/src/components/UserProfile.tsx`:
-
-```typescript
-import React from "react";
-import {
-  Card,
-  CardContent,
-  Typography,
-  Button,
-  Box,
-  Chip,
-  CircularProgress,
-  Alert,
-} from "@mui/material";
-import { useAuthMeQuery } from "../hooks/api";
-
-export const UserProfile: React.FC = () => {
-  const { data: user, isLoading, error } = useAuthMeQuery();
-
-  if (isLoading) {
-    return (
-      <Box display="flex" justifyContent="center" p={4}>
-        <CircularProgress />
-      </Box>
-    );
-  }
-
-  if (error) {
-    return (
-      <Alert severity="error">
-        Failed to load user profile: {error.message}
-      </Alert>
-    );
-  }
-
-  if (!user) {
-    return <Alert severity="info">Please log in to view your profile.</Alert>;
-  }
-
-  return (
-    <Card>
-      <CardContent>
-        <Typography variant="h5" component="h1" gutterBottom>
-          User Profile
-        </Typography>
-
-        <Box display="flex" flexDirection="column" gap={2}>
-          <Box>
-            <Typography variant="subtitle1" fontWeight="bold">
-              Username:
-            </Typography>
-            <Typography>{user.username}</Typography>
-          </Box>
-
-          <Box>
-            <Typography variant="subtitle1" fontWeight="bold">
-              Email:
-            </Typography>
-            <Typography>{user.email}</Typography>
-          </Box>
-
-          {user.fullName && (
-            <Box>
-              <Typography variant="subtitle1" fontWeight="bold">
-                Full Name:
-              </Typography>
-              <Typography>{user.fullName}</Typography>
-            </Box>
-          )}
-
-          <Box>
-            <Typography variant="subtitle1" fontWeight="bold">
-              Status:
-            </Typography>
-            <Box display="flex" gap={1}>
-              <Chip
-                label={user.isActive ? "Active" : "Inactive"}
-                color={user.isActive ? "success" : "error"}
-                size="small"
-              />
-              {user.isAdmin && (
-                <Chip label="Admin" color="primary" size="small" />
-              )}
-            </Box>
-          </Box>
-
-          <Box>
-            <Typography variant="subtitle1" fontWeight="bold">
-              Member Since:
-            </Typography>
-            <Typography>
-              {new Date(user.createdAt).toLocaleDateString()}
-            </Typography>
-          </Box>
-        </Box>
-
-        <Button
-          variant="outlined"
-          sx={{ mt: 3 }}
-          onClick={() => {
-            // Handle edit profile
-          }}
-        >
-          Edit Profile
-        </Button>
-      </CardContent>
-    </Card>
-  );
-};
-```
-
-Create `frontend/src/components/OrderHistory.tsx`:
-
-```typescript
-import React from "react";
-import {
-  Table,
-  TableBody,
-  TableCell,
-  TableContainer,
-  TableHead,
-  TableRow,
-  Paper,
-  Chip,
-  Typography,
-  Box,
-  CircularProgress,
-  Alert,
-} from "@mui/material";
-import { APIOrderStatus } from "../generated";
-import { useOrdersQuery } from "../hooks/api";
-
-const getStatusColor = (status: APIOrderStatus) => {
-  switch (status) {
-    case APIOrderStatus.PENDING:
-      return "warning";
-    case APIOrderStatus.PROCESSING:
-      return "info";
-    case APIOrderStatus.SHIPPED:
-      return "primary";
-    case APIOrderStatus.DELIVERED:
-      return "success";
-    case APIOrderStatus.CANCELLED:
-      return "error";
-    default:
-      return "default";
-  }
-};
-
-export const OrderHistory: React.FC = () => {
-  const { data: orders, isLoading, error } = useOrdersQuery();
-
-  if (isLoading) {
-    return (
-      <Box display="flex" justifyContent="center" p={4}>
-        <CircularProgress />
-      </Box>
-    );
-  }
-
-  if (error) {
-    return (
-      <Alert severity="error">Failed to load orders: {error.message}</Alert>
-    );
-  }
-
-  if (!orders || orders.length === 0) {
-    return <Alert severity="info">You haven't placed any orders yet.</Alert>;
-  }
-
-  return (
-    <Box>
-      <Typography variant="h5" component="h1" gutterBottom>
-        Order History
-      </Typography>
-
-      <TableContainer component={Paper}>
-        <Table>
-          <TableHead>
-            <TableRow>
-              <TableCell>Order ID</TableCell>
-              <TableCell>Date</TableCell>
-              <TableCell>Items</TableCell>
-              <TableCell>Total</TableCell>
-              <TableCell>Status</TableCell>
-            </TableRow>
-          </TableHead>
-          <TableBody>
-            {orders.map((order) => (
-              <TableRow key={order.id}>
-                <TableCell>#{order.id}</TableCell>
-                <TableCell>
-                  {new Date(order.createdAt).toLocaleDateString()}
-                </TableCell>
-                <TableCell>
-                  {order.items.length} item{order.items.length !== 1 ? "s" : ""}
-                </TableCell>
-                <TableCell>${order.totalAmount.toFixed(2)}</TableCell>
-                <TableCell>
-                  <Chip
-                    label={order.status.toUpperCase()}
-                    color={getStatusColor(order.status)}
-                    size="small"
-                  />
-                </TableCell>
-              </TableRow>
-            ))}
-          </TableBody>
-        </Table>
-      </TableContainer>
-    </Box>
-  );
-};
-```
-
-### 3.5 Setup App with React Query
-
-Update `frontend/src/App.tsx`:
-
-```typescript
-import React from "react";
-import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
-import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
-import { ThemeProvider, createTheme, CssBaseline } from "@mui/material";
-import { BrowserRouter as Router, Routes, Route } from "react-router-dom";
-import { ProductList } from "./components/ProductList";
-import { UserProfile } from "./components/UserProfile";
-import { OrderHistory } from "./components/OrderHistory";
-
-// Create React Query client
-const queryClient = new QueryClient({
-  defaultOptions: {
-    queries: {
-      retry: 1,
-      refetchOnWindowFocus: false,
-    },
-  },
-});
-
-// Create Material-UI theme
-const theme = createTheme({
-  palette: {
-    mode: "light",
-    primary: {
-      main: "#1976d2",
-    },
-    secondary: {
-      main: "#dc004e",
-    },
-  },
-});
-
-function App() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <ThemeProvider theme={theme}>
-        <CssBaseline />
-        <Router>
-          <div className="App">
-            <Routes>
-              <Route path="/" element={<ProductList />} />
-              <Route path="/profile" element={<UserProfile />} />
-              <Route path="/orders" element={<OrderHistory />} />
-            </Routes>
-          </div>
-        </Router>
-        <ReactQueryDevtools initialIsOpen={false} />
-      </ThemeProvider>
-    </QueryClientProvider>
-  );
-}
-
-export default App;
-```
-
-## Part 4: Run the Complete Application
-
-### 4.1 Start the Backend
-
-```bash
-cd backend
-source venv/bin/activate  # On Windows: venv\Scripts\activate
-uvicorn main:app --reload
-```
-
-### 4.2 Start the Frontend
-
-```bash
-cd frontend
-npm start
-```
-
-### 4.3 Test the Integration
-
-1. **Visit the API docs**: http://localhost:8000/docs
-2. **Visit the React app**: http://localhost:3000
-3. **Test the type safety**: Try modifying API responses and see TypeScript errors in the frontend
-
-## Part 5: Advanced Features
-
-### 5.1 Regenerate Types on API Changes
-
-Create `scripts/update-types.sh`:
-
-```bash
-#!/bin/bash
-echo "🔄 Updating TypeScript types from API..."
-
-# Check if API is running
-if ! curl -s http://localhost:8000/health > /dev/null; then
-    echo "❌ API server is not running. Please start it first."
-    exit 1
-fi
-
-# Generate new types
-npx schemantic generate \
-  --url http://localhost:8000/openapi.json \
-  --output ./frontend/src/generated \
-  --hooks \
-  --naming camelCase \
-  # No prefix by default; to add a prefix use --prefix "MyAPI"
-
-echo "✅ Types updated successfully!"
-echo "🏗️ Building frontend to verify types..."
-
-cd frontend
-npm run build
-
-if [ $? -eq 0 ]; then
-    echo "✅ Frontend builds successfully with new types!"
-else
-    echo "❌ Frontend build failed. Please check for type errors."
-    exit 1
-fi
-```
-
-### 5.2 Add Type-Safe Error Handling
-
-Create `frontend/src/utils/errors.ts`:
-
-```typescript
-import { APIResponse } from "../generated";
-
-export class APIError extends Error {
-  constructor(message: string, public status: number, public response?: any) {
-    super(message);
-    this.name = "APIError";
-  }
-}
-
-export const handleAPIError = (error: any): string => {
-  if (error instanceof APIError) {
-    return `API Error (${error.status}): ${error.message}`;
-  }
-
-  if (error.response?.data?.message) {
-    return error.response.data.message;
-  }
-
-  return error.message || "An unexpected error occurred";
-};
-```
-
-### 5.3 Add Real-time Updates with WebSockets
-
-The generated types can also be used with WebSocket events:
-
-```typescript
-// frontend/src/hooks/useWebSocket.ts
-import { useEffect, useState } from "react";
-import { APIOrder } from "../generated";
-
-export const useOrderUpdates = (userId: number) => {
-  const [orders, setOrders] = useState<APIOrder[]>([]);
-
-  useEffect(() => {
-    const ws = new WebSocket(`ws://localhost:8000/ws/orders/${userId}`);
-
-    ws.onmessage = (event) => {
-      const data = JSON.parse(event.data);
-
-      // Type-safe handling of WebSocket messages
-      if (data.type === "order_update") {
-        const updatedOrder: APIOrder = data.order;
-        setOrders((prev) =>
-          prev.map((order) =>
-            order.id === updatedOrder.id ? updatedOrder : order
-          )
-        );
-      }
-    };
-
-    return () => ws.close();
-  }, [userId]);
-
-  return orders;
-};
-```
-
-## Conclusion
-
-You now have a complete, type-safe full-stack application with:
-
-1. ✅ **FastAPI backend** with comprehensive API
-2. ✅ **Generated TypeScript types** that match your API exactly
-3. ✅ **Type-safe API client** with error handling
-4. ✅ **React hooks** for data fetching with React Query
-5. ✅ **Full type safety** from database to UI
-6. ✅ **Automatic synchronization** between backend and frontend types
-
-### Key Benefits
-
-- **Type Safety**: Catch API integration errors at compile time
-- **Developer Experience**: Auto-completion and IntelliSense for API calls
-- **Maintainability**: Types automatically update when API changes
-- **Performance**: Optimized data fetching with React Query
-- **Scalability**: Clean separation of concerns and modular architecture
-
-### Next Steps
-
-1. **Add authentication persistence** with localStorage
-2. **Implement real-time features** with WebSockets
-3. **Add comprehensive error handling** throughout the app
-4. **Set up automated type generation** in your CI/CD pipeline
-5. **Add testing** with the generated types for both frontend and backend
-
-This tutorial demonstrates the power of Schemantic in creating maintainable, type-safe full-stack applications where the frontend and backend always stay in sync!
+# FastAPI tutorial
+
+This example uses Node.js 20+, Python with FastAPI/Uvicorn, and a TypeScript consumer. The generated client uses fetch; no React dependency is needed for the default output.
+
+## Run the API
+
+```sh
+python -m pip install fastapi uvicorn
+```
+
+Save `main.py`:
+
+```python
+from fastapi import FastAPI
+from pydantic import BaseModel
+
+app = FastAPI(title="Users API")
+
+class User(BaseModel):
+    id: int
+    display_name: str
+
+@app.get("/users/{user_id}", response_model=User, operation_id="getUser")
+def get_user(user_id: int):
+    return User(id=user_id, display_name="Example")
+
+@app.post("/users", response_model=User, operation_id="createUser")
+def create_user(user: User):
+    return user
+```
+
+```sh
+python -m uvicorn main:app --host 127.0.0.1 --port 8000
+```
+
+## Generate and use the client
+
+From your TypeScript project:
+
+```sh
+npm install --save-dev schemantic typescript
+npx schemantic generate --url http://127.0.0.1:8000/openapi.json --output ./src/generated
+```
+
+```ts
+import { UsersApiClient as ApiClient } from './generated/index.js';
+
+const client = new ApiClient({ baseUrl: 'http://127.0.0.1:8000' });
+const user = await client.getUser(1);
+console.log(user.id, user.displayName);
+```
+
+The explicit `operation_id` gives stable operation/method names. The API sends `display_name`; the default application property is `displayName`. Use `propertyNaming: "preserve"` if your application should keep the wire property names. Generated types derive from the live schema, including request/response projections; inspect generated body signatures before constructing a request. Use requestInit headers for per-call overrides. For bearer auth, use `setAuthToken(token)`/`clearAuthToken()`; the client does not perform an OAuth authorization flow.
+
+```ts
+import { UsersApiClient as ApiClient } from './generated/index.js';
+
+const client = new ApiClient({ baseUrl: 'http://127.0.0.1:8000' });
+const user = await client.getUser(1, { headers: { 'X-Request-ID': 'example' } });
+console.log(user.id, user.displayName);
+```
+
+## Optional plain React hooks
+
+```sh
+npm install react
+npx schemantic generate --url http://127.0.0.1:8000/openapi.json --output ./src/generated --hooks
+```
+
+```tsx
+import { UsersApiClient as ApiClient, createApiHooks } from './generated/index.js';
+
+const client = new ApiClient({ baseUrl: 'http://127.0.0.1:8000' });
+const hooks = createApiHooks(client);
+
+export function UserView() {
+  const { data, error, loading, refetch } = hooks.useGetUserQuery({ path: { user_id: 1 } });
+  if (loading) return <p>Loading</p>;
+  if (error) return <p>{error.message}</p>;
+  return <button onClick={() => { void refetch(); }}>{data?.id}</button>;
+}
+```
+
+Mutation hooks take no callback options. Get `mutate` and `loading` from the hook, then `await mutate({ body: value })` in an event handler with try/catch. Do not pass TanStack Query `enabled`, `onSuccess`, `onError`, or read `isLoading`; these are plain React hooks.
+
+## Config and validation
+
+```sh
+npx schemantic init --yes
+```
+
+Edit `schemantic.config.json`:
+
+```json
+{
+  "schemaUrl": "http://127.0.0.1:8000/openapi.json",
+  "outputDir": "./src/generated",
+  "generateHooks": false
+}
+```
+
+```sh
+npx schemantic validate --config
+npx schemantic generate --verbose
+```
+
+A config file is never replaced implicitly: explicit `init --force` is required. Validation reports supported-schema diagnostics and does not repair files. File watch is available for local JSON snapshots; URL watch is unsupported.
+
+For runtime validation, install Zod 4 and enable `zod-validation`, then explicitly call the generated validator helpers. Enabling a plugin does not insert validation/caching/timing into each endpoint automatically. JSON OpenAPI 3.0.x/3.1.x and local refs are supported; YAML, external refs, and OpenAPI 3.2+ are rejected. See [configuration](CONFIGURATION.md) and [plugin contracts](PLUGINS.md).