torque-checkout 1.1.10 → 2.0.1

package/README.md

@@ -1,99 +1,199 @@
-# torque-checkout
+# Torque Checkout SDK
 
-Official Torque checkout SDK for seamless eCommerce integrations. Generate multi-product checkout links, track orders, and manage customer data with our powerful API.
+> **Official Torque checkout SDK for seamless eCommerce integrations with Next.js**
 
-## Quick Start
+The easiest way to integrate Torque checkout into your Next.js eCommerce application. Accept crypto payments with just a few lines of code.
 
-### Prerequisites
+[![npm version](https://img.shields.io/npm/v/torque-checkout.svg)](https://www.npmjs.com/package/torque-checkout)
+[![npm downloads](https://img.shields.io/npm/dm/torque-checkout.svg)](https://www.npmjs.com/package/torque-checkout)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 
-**Before installing the package, you must create your Torque business profile:**
+## Table of Contents
 
-1. **Go to Torque Business Dashboard**: https://torque.fi/business/settings
-2. **Connect your wallet** (MetaMask, WalletConnect, etc.)
-3. **Fill out business information** (name, email, website, etc.)
-4. **Set your payment wallet address** (where you want to receive payments)
-5. **Save your profile** (API key will be generated automatically)
-6. **Get your credentials** from the bottom of the business settings page
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Documentation](#documentation)
+- [Examples](#examples)
+- [TypeScript](#typescript)
+- [Error Handling](#error-handling)
+- [Security](#security)
+- [Troubleshooting](#troubleshooting)
+- [Migration Guide](#migration-guide)
+- [Support](#support)
+
+## Features
 
-### Installation
+- **Lightweight & Fast** - Minimal bundle size (~40KB), optimized for performance
+- **Zero Configuration** - Works out of the box with environment variables
+- **TypeScript First** - Full TypeScript support with comprehensive types and IntelliSense
+- **React Hooks** - Built-in React hooks for seamless client-side integration
+- **Next.js Optimized** - Server-side utilities for App Router and Pages Router
+- **Production Ready** - Comprehensive error handling, validation, and retry logic
+- **Multi-Product Support** - Handle complex carts with multiple items and variants
+- **Subscription Support** - Built-in subscription and recurring payment management
+- **Universal** - Works in browser, Node.js, and edge environments
+
+## Installation
 
 ```bash
 npm install torque-checkout
 # or
 yarn add torque-checkout
+# or
+pnpm add torque-checkout
 ```
 
-### Basic Usage
+### Requirements
 
-```typescript
-import { TorqueCheckout } from 'torque-checkout'
+- **Node.js**: >= 16.0.0
+- **Next.js**: >= 13.0.0 (for Next.js utilities)
+- **React**: >= 16.8.0 (for React hooks, optional)
 
-const torque = new TorqueCheckout({
-  businessId: 'your_business_id',
-  apiKey: 'your_api_key'
-})
+## Quick Start
 
-// Generate cart checkout link
-const checkoutUrl = await torque.generateCartCheckoutUrl({
-  items: [
-    { productId: 'prod_123', quantity: 2, variant: 'large' },
-    { productId: 'prod_456', quantity: 1 }
-  ],
-  customer: {
-    email: 'customer@example.com',
-    firstName: 'John',
-    lastName: 'Doe'
-  }
-})
+### Step 1: Get Your API Credentials
 
-// Redirect customer to checkout
-window.location.href = checkoutUrl
+1. **Visit [Torque Business Dashboard](https://app.torque.fi/business/settings)**
+2. **Connect your wallet** (MetaMask, WalletConnect, etc.)
+3. **Complete your business profile**:
+   - Business name, email, website
+   - **Payment wallet address** (where payments will be sent)
+4. **Save your profile** - API credentials are generated automatically
+5. **Copy your credentials** from the API Integration section:
+   - `Business ID`
+   - `API Key`
+
+> **Tip**: Your payment wallet address is set once in business settings. All successful payments automatically go to this wallet - no code needed!
+
+### Step 2: Configure Environment Variables
 
-// The generated URL will look like:
-// https://torque.fi/checkout/{businessId}/cart?items={encoded_cart_data}
+Create a `.env.local` file in your Next.js project root:
+
+```env
+# Required
+TORQUE_BUSINESS_ID=your_business_id_here
+TORQUE_API_KEY=your_api_key_here
+
+# Optional (defaults to production)
+TORQUE_BASE_URL=https://app.torque.fi
 ```
 
-## URL Structure
+> **Security**: Never commit `.env.local` to version control. Add it to `.gitignore`.
 
-The SDK generates checkout URLs in this format:
+### Step 3: Choose Your Integration Method
 
-- **Single Product**: `https://torque.fi/checkout/{businessId}/{productId}?quantity=1`
-- **Multi-Product Cart**: `https://torque.fi/checkout/{businessId}/cart?items={encoded_cart_data}`
+#### Option A: React Hook (Client-Side) - Recommended for Most Cases
 
-The `items` parameter contains URL-encoded JSON with your cart data.
+```tsx
+'use client'
 
-## API Reference
+import { useTorqueCheckout } from 'torque-checkout/react'
 
-### Constructor
+export default function CheckoutButton() {
+  const { generateProductCheckout, isLoading } = useTorqueCheckout({
+    autoRedirect: true // Automatically redirects to checkout
+  })
 
-```typescript
-new TorqueCheckout(config: TorqueConfig)
+  return (
+    <button
+      onClick={() => generateProductCheckout('prod_123', 1, {
+        email: 'customer@example.com'
+      })}
+      disabled={isLoading}
+    >
+      {isLoading ? 'Loading...' : 'Buy Now'}
+    </button>
+  )
+}
 ```
 
-**Config Options:**
-- `businessId` (required): Your Torque business ID (get from business dashboard)
-- `apiKey` (required): Your API authentication key (get from business dashboard)
-- `timeout` (optional): Request timeout in milliseconds (defaults to 30000)
+#### Option B: Server-Side API Route (Most Secure)
+
+```ts
+// app/api/checkout/route.ts
+import { handleCheckoutRequest } from 'torque-checkout/nextjs'
 
-**Important:** Your `businessId` and `apiKey` are generated when you create your business profile in the Torque dashboard. Make sure you've set your payment wallet address in the business settings before using the SDK.
+export const POST = handleCheckoutRequest()
+```
+
+Then call from your frontend:
+
+```tsx
+const response = await fetch('/api/checkout', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({
+    items: [{ productId: 'prod_123', quantity: 1 }],
+    customer: { email: 'customer@example.com' }
+  })
+})
+
+const { checkoutUrl } = await response.json()
+window.location.href = checkoutUrl
+```
+
+#### Option C: Direct SDK Usage
+
+```ts
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
+
+const torque = createTorqueCheckoutFromEnv()
+
+const checkoutUrl = await torque.generateCartCheckoutUrl({
+  items: [{ productId: 'prod_123', quantity: 1 }],
+  customer: { email: 'customer@example.com' }
+})
+
+window.location.href = checkoutUrl
+```
 
-### Methods
+## Documentation
 
-#### `generateCartCheckoutUrl(cart: CartData): Promise<string>`
+### Core SDK
+
+#### Initialization
+
+```ts
+import { createTorqueCheckout, createTorqueCheckoutFromEnv } from 'torque-checkout'
+
+// Method 1: From environment variables (recommended)
+const torque = createTorqueCheckoutFromEnv()
+
+// Method 2: Explicit configuration
+const torque = createTorqueCheckout({
+  businessId: process.env.TORQUE_BUSINESS_ID!,
+  apiKey: process.env.TORQUE_API_KEY!,
+  baseUrl: 'https://app.torque.fi', // Optional
+  timeout: 30000 // Optional, default: 30000ms
+})
+```
+
+#### Methods
+
+##### `generateCartCheckoutUrl(cart: CartData): Promise<string>`
 
 Generate a checkout URL for a multi-product cart.
 
-```typescript
+```ts
 const checkoutUrl = await torque.generateCartCheckoutUrl({
   items: [
-    { productId: 'prod_123', quantity: 2, variant: 'large' },
+    { 
+      productId: 'prod_123', 
+      quantity: 2, 
+      price: 29.99, // Optional: override product price
+      variant: 'large', // Optional: product variant
+      metadata: { customField: 'value' } // Optional: custom data
+    },
     { productId: 'prod_456', quantity: 1 }
   ],
   customer: {
-    email: 'customer@example.com',
-    firstName: 'John',
-    lastName: 'Doe',
-    shippingAddress: {
+    email: 'customer@example.com', // Required
+    firstName: 'John', // Optional
+    lastName: 'Doe', // Optional
+    phone: '+1234567890', // Optional
+    shippingAddress: { // Optional: pre-fill shipping
       street: '123 Main St',
       city: 'New York',
       state: 'NY',
@@ -102,311 +202,689 @@ const checkoutUrl = await torque.generateCartCheckoutUrl({
     }
   },
   options: {
-    metadata: {
-      orderId: 'order_123',
-      source: 'shopify'
-    },
-    expiresIn: 24 * 60 * 60 * 1000 // 24 hours
+    metadata: { orderId: 'order_123', source: 'website' }, // Optional
+    expiresIn: 24 * 60 * 60 * 1000, // Optional: 24 hours
+    redirectUrl: 'https://yoursite.com/thank-you' // Optional
   }
 })
 ```
 
-#### `generateProductCheckoutUrl(productId: string, quantity?: number, customer?: CustomerData, options?: CartOptions): Promise<string>`
+##### `generateProductCheckoutUrl(productId, quantity?, customer?, options?): Promise<string>`
 
-Generate a checkout URL for a single product.
+Quick method for single product checkout.
 
-```typescript
+```ts
 const checkoutUrl = await torque.generateProductCheckoutUrl(
-  'prod_123',
-  2,
-  { email: 'customer@example.com' }
+  'prod_123', // Product ID
+  2, // Quantity (default: 1)
+  { email: 'customer@example.com' }, // Customer data (optional)
+  { redirectUrl: 'https://yoursite.com/success' } // Options (optional)
 )
 ```
 
-#### `validateCart(cart: CartData): Promise<CartValidation>`
+##### `generateSubscriptionCheckoutUrl(productId, paymentPlanId, customer?, options?): Promise<string>`
 
-Validate cart data before generating checkout links.
+Generate checkout for subscription products.
 
-```typescript
+```ts
+const checkoutUrl = await torque.generateSubscriptionCheckoutUrl(
+  'prod_subscription_123', // Subscription product ID
+  'plan_monthly_123', // Payment plan ID
+  { email: 'customer@example.com' },
+  { redirectUrl: 'https://yoursite.com/subscription-success' }
+)
+```
+
+##### `validateCart(cart: CartData): Promise<CartValidation>`
+
+Validate cart before checkout to catch errors early.
+
+```ts
 const validation = await torque.validateCart({
-  items: [
-    { productId: 'prod_123', quantity: 2 },
-    { productId: 'prod_456', quantity: 1 }
-  ]
+  items: [{ productId: 'prod_123', quantity: 2 }]
 })
 
 if (validation.valid) {
-  console.log('Cart is valid, estimated total:', validation.estimatedTotal)
+  console.log('Cart is valid')
+  console.log('Estimated total:', validation.estimatedTotal)
 } else {
-  console.log('Cart validation errors:', validation.errors)
+  console.error('Validation errors:', validation.errors)
+  console.warn('Warnings:', validation.warnings)
 }
 ```
 
-#### `getOrderStatus(orderId: string): Promise<OrderStatus>`
+##### `getOrderStatus(orderId: string): Promise<OrderStatus>`
+
+Check order status after checkout.
 
-Get the current status of an order.
+```ts
+const order = await torque.getOrderStatus('order_123')
 
-```typescript
-const orderStatus = await torque.getOrderStatus('order_123')
-console.log('Order status:', orderStatus.status)
-console.log('Total amount:', orderStatus.totals.total)
+console.log('Status:', order.status) // e.g., 'completed', 'pending', 'failed'
+console.log('Total:', order.totals.total)
+console.log('Payment status:', order.paymentStatus)
+console.log('Items:', order.items)
 ```
 
-#### `sendWebhookEvent(orderId: string, status: string, customerData?: any, metadata?: Record<string, any>): Promise<void>`
+### React Hooks
+
+#### `useTorqueCheckout(options?)`
+
+React hook for client-side checkout with built-in state management.
+
+```tsx
+import { useTorqueCheckout } from 'torque-checkout/react'
+
+function CheckoutButton() {
+  const {
+    generateCheckout,
+    generateProductCheckout,
+    generateSubscriptionCheckout,
+    validateCart,
+    getOrderStatus,
+    isLoading,
+    error,
+    checkoutUrl
+  } = useTorqueCheckout({
+    // Optional: explicit config (or use env vars)
+    // config: {
+    //   businessId: 'your_business_id',
+    //   apiKey: 'your_api_key'
+    // },
+    autoRedirect: true, // Auto-redirect to checkout URL
+    onSuccess: (url) => {
+      console.log('Checkout URL generated:', url)
+      // Optional: track analytics
+    },
+    onError: (error) => {
+      console.error('Checkout error:', error)
+      // Optional: show error toast
+    }
+  })
 
-Send webhook events to update order status.
+  const handleCheckout = async () => {
+    const url = await generateProductCheckout('prod_123', 1, {
+      email: 'customer@example.com'
+    })
+    // If autoRedirect is false, you can handle the URL manually
+    if (url && !autoRedirect) {
+      window.location.href = url
+    }
+  }
 
-```typescript
-await torque.sendWebhookEvent('order_123', 'shipped', {
-  trackingNumber: '1Z999AA1234567890',
-  carrier: 'UPS'
-})
+  return (
+    <div>
+      <button onClick={handleCheckout} disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Checkout'}
+      </button>
+      {error && <p className="error">{error.message}</p>}
+      {checkoutUrl && <p>Checkout URL: {checkoutUrl}</p>}
+    </div>
+  )
+}
 ```
 
-#### `trackCartView(cartId: string, cartData: CartData): Promise<void>`
+#### `useCart()`
+
+Shopping cart state management hook.
+
+```tsx
+import { useCart } from 'torque-checkout/react'
+
+function ShoppingCart() {
+  const {
+    items,
+    addItem,
+    removeItem,
+    updateQuantity,
+    clearCart,
+    getTotal,
+    getItemCount
+  } = useCart()
+
+  return (
+    <div>
+      <h2>Shopping Cart ({getItemCount()} items)</h2>
+      
+      {items.map(item => (
+        <div key={`${item.productId}-${item.variant || ''}`}>
+          <span>Product {item.productId}</span>
+          <span>Quantity: {item.quantity}</span>
+          <button onClick={() => updateQuantity(item.productId, item.quantity + 1, item.variant)}>
+            +
+          </button>
+          <button onClick={() => updateQuantity(item.productId, item.quantity - 1, item.variant)}>
+            -
+          </button>
+          <button onClick={() => removeItem(item.productId, item.variant)}>
+            Remove
+          </button>
+        </div>
+      ))}
+      
+      <p>Total: ${getTotal().toFixed(2)}</p>
+      <button onClick={clearCart}>Clear Cart</button>
+    </div>
+  )
+}
+```
 
-Track cart views for analytics.
+### Next.js Server Utilities
 
-```typescript
-await torque.trackCartView('cart_123', {
-  items: [{ productId: 'prod_123', quantity: 2 }]
-})
-```
+#### `handleCheckoutRequest(options?)`
 
-#### `trackCheckoutComplete(orderId: string, checkoutData: any): Promise<void>`
+Complete API route handler with error handling.
 
-Track successful checkout completions.
+```ts
+// app/api/checkout/route.ts
+import { handleCheckoutRequest } from 'torque-checkout/nextjs'
 
-```typescript
-await torque.trackCheckoutComplete('order_123', {
-  paymentMethod: 'card',
-  total: 99.99
+export const POST = handleCheckoutRequest({
+  onSuccess: async (checkoutUrl, cart) => {
+    // Optional: Log, track analytics, send notifications
+    console.log('Checkout generated:', checkoutUrl)
+    await logCheckoutEvent(cart)
+  },
+  onError: async (error, cart) => {
+    // Optional: Error logging, notifications
+    console.error('Checkout error:', error)
+    await logError(error, cart)
+  }
 })
 ```
 
-#### `generateCartHash(cart: CartData): string`
+#### `handleWebhook(options?)`
 
-Generate a unique hash for cart identification and caching.
+Webhook handler for order events.
 
-```typescript
-const cartHash = torque.generateCartHash({
-  items: [{ productId: 'prod_123', quantity: 2 }]
+```ts
+// app/api/webhooks/torque/route.ts
+import { handleWebhook } from 'torque-checkout/nextjs'
+
+export const POST = handleWebhook({
+  secret: process.env.TORQUE_WEBHOOK_SECRET, // Optional: verify signatures
+  onOrderCompleted: async (event) => {
+    // Fulfill order
+    await fulfillOrder(event.orderId!)
+    await sendConfirmationEmail(event.data.customerEmail)
+  },
+  onOrderFailed: async (event) => {
+    // Handle failed payment
+    await notifyCustomer(event.orderId!)
+  },
+  onSubscriptionCreated: async (event) => {
+    // Activate subscription
+    await activateSubscription(event.subscriptionId!)
+  }
 })
 ```
 
-## Data Types
+#### `generateCheckoutUrl(cart, config?)`
+
+Server-side checkout URL generation.
 
-### CartItem
+```ts
+// app/api/checkout/route.ts
+import { generateCheckoutUrl } from 'torque-checkout/nextjs'
 
-```typescript
-interface CartItem {
-  productId: string        // Required: Torque product ID
-  quantity: number         // Required: Quantity to purchase
-  variant?: string         // Optional: Product variant (size, color, etc.)
-  price?: number           // Optional: Override product price
-  metadata?: Record<string, any> // Optional: Custom data
+export async function POST(request: Request) {
+  const cart = await request.json()
+  
+  try {
+    const checkoutUrl = await generateCheckoutUrl(cart)
+    return Response.json({ checkoutUrl })
+  } catch (error: any) {
+    return Response.json(
+      { error: error.message, code: error.code },
+      { status: error.statusCode || 500 }
+    )
+  }
 }
 ```
 
-### CustomerData
-
-```typescript
-interface CustomerData {
-  email: string            // Required: Customer email
-  firstName?: string       // Optional: First name
-  lastName?: string        // Optional: Last name
-  phone?: string           // Optional: Phone number
-  shippingAddress?: {      // Optional: Pre-fill shipping address
-    street: string
-    city: string
-    state: string
-    zipCode: string
-    country: string
+## Complete Examples
+
+### E-Commerce Product Page
+
+```tsx
+// app/products/[id]/page.tsx
+'use client'
+
+import { useTorqueCheckout, useCart } from 'torque-checkout/react'
+import { useState } from 'react'
+
+export default function ProductPage({ params }: { params: { id: string } }) {
+  const cart = useCart()
+  const { generateProductCheckout, isLoading } = useTorqueCheckout({
+    autoRedirect: true
+  })
+  const [quantity, setQuantity] = useState(1)
+
+  const handleAddToCart = () => {
+    cart.addItem({
+      productId: params.id,
+      quantity,
+      price: 29.99
+    })
   }
-  billingAddress?: {       // Optional: Pre-fill billing address
-    // Same structure as shippingAddress
+
+  const handleBuyNow = async () => {
+    await generateProductCheckout(
+      params.id,
+      quantity,
+      {
+        email: 'customer@example.com' // Get from auth/session
+      }
+    )
   }
+
+  return (
+    <div>
+      <h1>Product {params.id}</h1>
+      <p>$29.99</p>
+      
+      <div>
+        <label>Quantity:</label>
+        <input
+          type="number"
+          value={quantity}
+          onChange={(e) => setQuantity(Number(e.target.value))}
+          min="1"
+        />
+      </div>
+      
+      <button onClick={handleAddToCart}>
+        Add to Cart ({cart.getItemCount()} items)
+      </button>
+      
+      <button onClick={handleBuyNow} disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Buy Now'}
+      </button>
+    </div>
+  )
 }
 ```
 
-### CartOptions
+### Shopping Cart with Checkout
 
-```typescript
-interface CartOptions {
-  domain?: string          // Optional: Custom domain for checkout
-  expiresIn?: number       // Optional: Link expiration time (ms)
-  metadata?: Record<string, any> // Optional: Custom metadata
-  redirectUrl?: string     // Optional: Post-checkout redirect URL
-}
-```
+```tsx
+// app/cart/page.tsx
+'use client'
 
-## Platform Integrations
+import { useTorqueCheckout, useCart } from 'torque-checkout/react'
 
-### Shopify
+export default function CartPage() {
+  const cart = useCart()
+  const { generateCheckout, isLoading } = useTorqueCheckout()
 
-```typescript
-// Shopify app integration
-app.post('/checkout', async (req, res) => {
-  const { cart, customer } = req.body
-  
-  try {
-    const checkoutUrl = await torque.generateCartCheckoutUrl({
-      items: cart.items.map(item => ({
-        productId: item.product_id,
-        quantity: item.quantity,
-        variant: item.variant_title,
-        price: item.price
-      })),
+  const handleCheckout = async () => {
+    const url = await generateCheckout({
+      items: cart.items,
       customer: {
-        email: customer.email,
-        firstName: customer.first_name,
-        lastName: customer.last_name,
-        shippingAddress: customer.shipping_address
+        email: 'customer@example.com' // Get from auth
       },
       options: {
-        metadata: {
-          orderId: cart.order_id,
-          source: 'shopify'
-        }
+        redirectUrl: window.location.origin + '/thank-you'
       }
     })
     
-    res.json({ checkoutUrl })
-  } catch (error) {
-    res.status(500).json({ error: error.message })
+    if (url) {
+      window.location.href = url
+    }
   }
-})
+
+  if (cart.items.length === 0) {
+    return <p>Your cart is empty</p>
+  }
+
+  return (
+    <div>
+      <h1>Shopping Cart</h1>
+      {cart.items.map(item => (
+        <div key={`${item.productId}-${item.variant || ''}`}>
+          <span>Product {item.productId}</span>
+          <span>Qty: {item.quantity}</span>
+          <span>${((item.price || 0) * item.quantity).toFixed(2)}</span>
+          <button onClick={() => cart.removeItem(item.productId, item.variant)}>
+            Remove
+          </button>
+        </div>
+      ))}
+      <div>
+        <strong>Total: ${cart.getTotal().toFixed(2)}</strong>
+      </div>
+      <button onClick={handleCheckout} disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Proceed to Checkout'}
+      </button>
+    </div>
+  )
+}
 ```
 
-### WooCommerce
+### Server Component Checkout (Next.js 13+)
 
-```php
-// WooCommerce hook integration
-add_action('woocommerce_checkout_order_processed', 'redirect_to_torque_checkout', 10, 3);
+```tsx
+// app/checkout/page.tsx
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
+import { redirect } from 'next/navigation'
+import { cookies } from 'next/headers'
 
-function redirect_to_torque_checkout($order_id, $posted_data, $order) {
-    $cart_items = [];
-    
-    foreach ($order->get_items() as $item) {
-        $cart_items[] = [
-            'productId' => $item->get_product_id(),
-            'quantity' => $item->get_quantity(),
-            'variant' => $item->get_variation_id() ? $item->get_name() : null,
-            'price' => $item->get_total() / $item->get_quantity()
-        ];
-    }
-    
-    $checkout_data = [
-        'businessId' => get_option('torque_business_id'),
-        'cart' => ['items' => $cart_items],
-        'customerData' => [
-            'email' => $order->get_billing_email(),
-            'firstName' => $order->get_billing_first_name(),
-            'lastName' => $order->get_billing_last_name()
-        ]
-    ];
-    
-    // Use JavaScript SDK or direct API call
-    $response = wp_remote_post('https://dashboard.torque.fi/api/checkout/generate-link', [
-        'body' => json_encode($checkout_data),
-        'headers' => ['Content-Type' => 'application/json'],
-        'timeout' => 30
-    ]);
-    
-    if (!is_wp_error($response)) {
-        $body = json_decode(wp_remote_retrieve_body($response), true);
-        if ($body['checkoutUrl']) {
-            wp_redirect($body['checkoutUrl']);
-            exit;
-        }
-    }
+export default async function CheckoutPage({
+  searchParams
+}: {
+  searchParams: { productId: string; quantity?: string }
+}) {
+  const torque = createTorqueCheckoutFromEnv()
+  
+  // Get customer email from session/cookies
+  const customerEmail = cookies().get('user_email')?.value || 'guest@example.com'
+  
+  const checkoutUrl = await torque.generateProductCheckoutUrl(
+    searchParams.productId,
+    Number(searchParams.quantity) || 1,
+    { email: customerEmail }
+  )
+
+  redirect(checkoutUrl)
 }
 ```
 
-## Testing
+### Pages Router API Route
 
-### Test Environment
+```ts
+// pages/api/checkout.ts
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
 
-Use our sandbox environment for testing:
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' })
+  }
 
-```typescript
-const torque = new TorqueCheckout({
-  businessId: 'test_business_123',
-  apiKey: 'test_api_key'
-})
+  try {
+    const torque = createTorqueCheckoutFromEnv()
+    const checkoutUrl = await torque.generateCartCheckoutUrl(req.body)
+
+    res.status(200).json({ checkoutUrl })
+  } catch (error: any) {
+    res.status(error.statusCode || 500).json({
+      error: error.message,
+      code: error.code
+    })
+  }
+}
+```
+
+## TypeScript
+
+Full TypeScript support with comprehensive types:
+
+```ts
+import type {
+  // Cart types
+  CartItem,
+  CartData,
+  CartOptions,
+  CartValidation,
+  
+  // Customer types
+  CustomerData,
+  
+  // Order types
+  OrderStatus,
+  CheckoutResponse,
+  
+  // Subscription types
+  Subscription,
+  SubscriptionProduct,
+  PaymentPlan,
+  CreateSubscriptionData,
+  UpdateSubscriptionData,
+  
+  // Config types
+  TorqueConfig,
+  TorqueCheckoutError
+} from 'torque-checkout'
 ```
 
-### Test Data
+### Type-Safe Usage
+
+```ts
+import { createTorqueCheckout } from 'torque-checkout'
+import type { CartData, CustomerData } from 'torque-checkout'
 
-```typescript
-const testCart = {
+const torque = createTorqueCheckout({
+  businessId: process.env.TORQUE_BUSINESS_ID!,
+  apiKey: process.env.TORQUE_API_KEY!
+})
+
+const cart: CartData = {
   items: [
-    { productId: 'test_prod_1', quantity: 1, price: 10.00 }
+    { productId: 'prod_123', quantity: 1 }
   ],
   customer: {
-    email: 'test@example.com'
-  }
+    email: 'customer@example.com'
+  } as CustomerData
 }
 
-const checkoutUrl = await torque.generateCartCheckoutUrl(testCart)
+const url: string = await torque.generateCartCheckoutUrl(cart)
 ```
 
 ## Error Handling
 
-The SDK throws descriptive errors for various failure scenarios:
+The SDK uses custom error classes for better error handling:
+
+```ts
+import { TorqueCheckoutError } from 'torque-checkout'
 
-```typescript
 try {
-  const checkoutUrl = await torque.generateCartCheckoutUrl(cart)
+  const url = await torque.generateCartCheckoutUrl(cart)
 } catch (error) {
-  if (error.message.includes('BUSINESS_NOT_FOUND')) {
-    console.error('Invalid business ID')
-  } else if (error.message.includes('PRODUCTS_NOT_FOUND')) {
-    console.error('Some products not found')
-  } else if (error.message.includes('Request timeout')) {
-    console.error('API request timed out')
+  if (error instanceof TorqueCheckoutError) {
+    console.error('Error code:', error.code)
+    console.error('Status code:', error.statusCode)
+    console.error('Details:', error.details)
+    
+    // Handle specific error codes
+    switch (error.code) {
+      case 'VALIDATION_ERROR':
+        // Show validation errors to user
+        showErrors(error.details?.errors)
+        break
+      case 'BUSINESS_NOT_FOUND':
+        // Check business ID configuration
+        console.error('Invalid business ID')
+        break
+      case 'TIMEOUT':
+        // Retry or show timeout message
+        retryCheckout()
+        break
+      case 'NETWORK_ERROR':
+        // Check internet connection
+        showNetworkError()
+        break
+      default:
+        // Generic error handling
+        showGenericError(error.message)
+    }
   } else {
-    console.error('Unexpected error:', error.message)
+    // Unknown error
+    console.error('Unexpected error:', error)
   }
 }
 ```
 
-## Analytics & Tracking
+### Common Error Codes
+
+| Code | Description | Solution |
+|------|-------------|----------|
+| `VALIDATION_ERROR` | Cart validation failed | Check cart items and customer data |
+| `BUSINESS_NOT_FOUND` | Invalid business ID | Verify `TORQUE_BUSINESS_ID` |
+| `INVALID_API_KEY` | Invalid API key | Verify `TORQUE_API_KEY` |
+| `TIMEOUT` | Request timed out | Check network, increase timeout |
+| `NETWORK_ERROR` | Network request failed | Check internet connection |
+| `ORDER_NOT_FOUND` | Order doesn't exist | Verify order ID |
+
+## Security Best Practices
+
+1. **Never expose API keys in client-side code**
+   ```ts
+   // BAD - Don't do this
+   const torque = createTorqueCheckout({
+     businessId: 'business_123',
+     apiKey: 'sk_live_...' // Exposed in browser!
+   })
+   
+   // GOOD - Use server-side API routes
+   // app/api/checkout/route.ts
+   export const POST = handleCheckoutRequest()
+   ```
+
+2. **Use environment variables**
+   ```env
+   # .env.local (never commit)
+   TORQUE_BUSINESS_ID=your_business_id
+   TORQUE_API_KEY=your_api_key
+   ```
+
+3. **Validate user input**
+   ```ts
+   // Always validate before sending to API
+   if (!cart.items || cart.items.length === 0) {
+     throw new Error('Cart is empty')
+   }
+   ```
+
+4. **Use HTTPS in production**
+   - Always use HTTPS for checkout URLs
+   - Never send sensitive data over HTTP
+
+5. **Verify webhook signatures**
+   ```ts
+   export const POST = handleWebhook({
+     secret: process.env.TORQUE_WEBHOOK_SECRET
+   })
+   ```
+
+6. **Set payment wallet in business settings**
+   - Payments automatically go to your configured wallet
+   - No need to handle wallet addresses in code
+
+## Troubleshooting
+
+### Issue: "TorqueCheckout not initialized"
+
+**Solution**: Make sure environment variables are set:
+```bash
+# Check if variables are loaded
+echo $TORQUE_BUSINESS_ID
+echo $TORQUE_API_KEY
+```
 
-Track customer behavior and optimize conversions:
+Or provide explicit config:
+```ts
+const torque = createTorqueCheckout({
+  businessId: 'your_business_id',
+  apiKey: 'your_api_key'
+})
+```
 
-```typescript
-// Track cart abandonment
-await torque.trackCartView('cart_123', cartData)
+### Issue: "Request timeout"
 
-// Track successful checkouts
-await torque.trackCheckoutComplete('order_123', {
-  paymentMethod: 'card',
-  total: 99.99,
-  items: 3
+**Solution**: Increase timeout or check network:
+```ts
+const torque = createTorqueCheckout({
+  businessId: process.env.TORQUE_BUSINESS_ID!,
+  apiKey: process.env.TORQUE_API_KEY!,
+  timeout: 60000 // 60 seconds
 })
 ```
 
-## Payment Destination
+### Issue: "Business not found"
+
+**Solution**: 
+1. Verify business ID in [Business Settings](https://app.torque.fi/business/settings)
+2. Check environment variable is correct
+3. Ensure business profile is saved and active
 
-**Payments are transferred to the wallet address set in business profile.**
+### Issue: React hooks not working
 
-- **Set once**: Configure your payment wallet in business settings
-- **Automatic transfers**: All successful checkouts send funds to your wallet
-- **Secure**: No need to handle payment addresses in your code
-- **Update anytime**: Change your payment wallet in business settings
+**Solution**: Make sure you're using the React entry point:
+```tsx
+// Correct
+import { useTorqueCheckout } from 'torque-checkout/react'
 
-## Performance
+// Wrong
+import { useTorqueCheckout } from 'torque-checkout'
+```
+
+### Issue: TypeScript errors
 
-- Built-in request caching with cart hashing
-- Configurable timeouts
-- Efficient error handling
-- Minimal bundle size
+**Solution**: Make sure TypeScript can find the types:
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
+  }
+}
+```
+
+## Migration Guide
+
+### From v1.x to v2.0.0
+
+v2.0.0 is **backward compatible** with v1.x. No code changes required!
+
+**New features available (optional):**
+- React hooks: `useTorqueCheckout()`, `useCart()`
+- Next.js utilities: `handleCheckoutRequest()`, `handleWebhook()`
+- Environment variable support: `createTorqueCheckoutFromEnv()`
+
+**Migration example:**
+
+```ts
+// v1.x (still works)
+import { TorqueCheckout } from 'torque-checkout'
+const torque = new TorqueCheckout({ businessId, apiKey })
+
+// v2.0.0 (new, optional)
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
+const torque = createTorqueCheckoutFromEnv() // Uses env vars
+```
+
+## API Reference
+
+For complete API documentation, visit:
+- **Full API Docs**: [https://docs.torque.fi/api](https://docs.torque.fi/api)
+- **Integration Guide**: [https://docs.torque.fi/integrations](https://docs.torque.fi/integrations)
 
 ## Support
 
 - **Documentation**: [https://docs.torque.fi](https://docs.torque.fi)
-- **API Reference**: [https://docs.torque.fi/api](https://docs.torque.fi/api)
-- **Integration Guide**: [https://docs.torque.fi/integrations](https://docs.torque.fi/integrations)
-- **NPM Package**: [https://www.npmjs.com/package/torque-checkout](https://www.npmjs.com/package/torque-checkout)
-- **Support**: hello@torque.fi
+- **Email**: hello@torque.fi
+- **GitHub Issues**: [https://github.com/torque-fi/torque-checkout/issues](https://github.com/torque-fi/torque-checkout/issues)
+- **Business Dashboard**: [https://app.torque.fi/business/settings](https://app.torque.fi/business/settings)
+
+## License
+
+MIT © [Torque](https://torque.fi)
+
+## Getting Started Checklist
+
+- [ ] Install: `npm install torque-checkout`
+- [ ] Create business profile: [app.torque.fi/business/settings](https://app.torque.fi/business/settings)
+- [ ] Set payment wallet address in business settings
+- [ ] Copy Business ID and API Key
+- [ ] Add environment variables to `.env.local`
+- [ ] Import and use the SDK
+- [ ] Test checkout flow
+- [ ] Deploy to production!
+
+---
+
+**Made with love by [Torque](https://torque.fi)**