torque-checkout 2.0.0 → 2.0.2

package/README.md

@@ -5,21 +5,57 @@
 The easiest way to integrate Torque checkout into your Next.js eCommerce application. Accept crypto payments with just a few lines of code.
 
 [![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/)
+
+## Table of Contents
+
+- [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
+
+- **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
 
-## ✨ Features
+```bash
+npm install torque-checkout
+# or
+yarn add torque-checkout
+# or
+pnpm add torque-checkout
+```
+
+### Requirements
 
-- 🚀 **Lightweight & Fast** - Minimal bundle size, optimized for performance
-- ⚡ **Zero Configuration** - Works out of the box with environment variables
-- 🎯 **TypeScript First** - Full TypeScript support with comprehensive types
-- ⚛️ **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 and validation
-- 📦 **Multi-Product Support** - Handle complex carts with multiple items
-- 🔄 **Subscription Support** - Built-in subscription management
+- **Node.js**: >= 16.0.0
+- **Next.js**: >= 13.0.0 (for Next.js utilities)
+- **React**: >= 16.8.0 (for React hooks, optional)
 
-## 📦 Installation
+## Quick Start
 
+### Get Checkout Working in 3 Steps
+
+**1. Install & Get Credentials**
 ```bash
 npm install torque-checkout
 # or
@@ -27,35 +63,78 @@ yarn add torque-checkout
 # or
 pnpm add torque-checkout
 ```
+- Visit https://app.torque.fi/business/settings
+- Connect wallet, complete profile, set payment wallet
+- Copy Business ID and API Key
+
+**2. Add Environment Variables**
+Create `.env.local`:
+```env
+TORQUE_BUSINESS_ID=your_business_id
+TORQUE_API_KEY=your_api_key
+```
+
+**3. Add Checkout Button**
+```tsx
+'use client'
+import { useTorqueCheckout } from 'torque-checkout/react'
+
+export default function CheckoutButton() {
+  const { generateProductCheckout, isLoading } = useTorqueCheckout({
+    autoRedirect: true
+  })
+
+  return (
+    <button
+      onClick={() => generateProductCheckout('prod_123', 1, {
+        email: 'customer@example.com'
+      })}
+      disabled={isLoading}
+    >
+      {isLoading ? 'Loading...' : 'Buy Now'}
+    </button>
+  )
+}
+```
+
+**Done!** Customer clicks → Redirects to checkout → Payment goes to your wallet.
 
-## 🚀 Quick Start
+---
 
-### 1. Get Your API Credentials
+### Detailed Setup
 
-Before using the SDK, you need to set up your Torque business profile:
+### Step 1: Get Your API Credentials
 
-1. **Go to [Torque Business Dashboard](https://app.torque.fi/business/settings)**
+1. **Visit [Torque Business Dashboard](https://app.torque.fi/business/settings)**
 2. **Connect your wallet** (MetaMask, WalletConnect, etc.)
-3. **Fill out your business information** (name, email, website, etc.)
-4. **Set your payment wallet address** (where you want to receive payments)
-5. **Save your profile** - Your API key will be generated automatically
-6. **Copy your credentials** from the API Integration section:
-   - Business ID
-   - API Key
+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!
 
-### 2. Configure Environment Variables
+### Step 2: Configure Environment Variables
 
-Create a `.env.local` file in your Next.js project:
+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
-TORQUE_BASE_URL=https://app.torque.fi  # Optional, defaults to production
+
+# Optional (defaults to production)
+TORQUE_BASE_URL=https://app.torque.fi
 ```
 
-### 3. Basic Usage
+> **Security**: Never commit `.env.local` to version control. Add it to `.gitignore`.
+
+### Step 3: Choose Your Integration Method
 
-#### Client-Side (React Component)
+#### Option A: React Hook (Client-Side) - Recommended for Most Cases
 
 ```tsx
 'use client'
@@ -64,82 +143,78 @@ import { useTorqueCheckout } from 'torque-checkout/react'
 
 export default function CheckoutButton() {
   const { generateProductCheckout, isLoading } = useTorqueCheckout({
-    autoRedirect: true, // Automatically redirect to checkout
-    onSuccess: (url) => console.log('Checkout URL:', url),
-    onError: (error) => console.error('Error:', error)
+    autoRedirect: true // Automatically redirects to checkout
   })
 
-  const handleCheckout = async () => {
-    await generateProductCheckout('prod_123', 1, {
-      email: 'customer@example.com',
-      firstName: 'John',
-      lastName: 'Doe'
-    })
-  }
-
   return (
-    <button onClick={handleCheckout} disabled={isLoading}>
-      {isLoading ? 'Loading...' : 'Checkout'}
+    <button
+      onClick={() => generateProductCheckout('prod_123', 1, {
+        email: 'customer@example.com'
+      })}
+      disabled={isLoading}
+    >
+      {isLoading ? 'Loading...' : 'Buy Now'}
     </button>
   )
 }
 ```
 
-#### Server-Side (API Route)
+#### Option B: Server-Side API Route (Most Secure)
 
 ```ts
 // app/api/checkout/route.ts
 import { handleCheckoutRequest } from 'torque-checkout/nextjs'
 
-export const POST = handleCheckoutRequest({
-  onSuccess: async (url, cart) => {
-    // Optional: Log checkout generation
-    console.log('Checkout generated:', url)
-  }
+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
 ```
 
-#### Direct SDK Usage
+#### Option C: Direct SDK Usage
 
 ```ts
-import { createTorqueCheckout } from 'torque-checkout'
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
 
-const torque = createTorqueCheckout({
-  businessId: process.env.TORQUE_BUSINESS_ID!,
-  apiKey: process.env.TORQUE_API_KEY!
-})
+const torque = createTorqueCheckoutFromEnv()
 
-// Generate checkout URL
 const checkoutUrl = await torque.generateCartCheckoutUrl({
-  items: [
-    { productId: 'prod_123', quantity: 2 },
-    { productId: 'prod_456', quantity: 1 }
-  ],
-  customer: {
-    email: 'customer@example.com',
-    firstName: 'John',
-    lastName: 'Doe'
-  }
+  items: [{ productId: 'prod_123', quantity: 1 }],
+  customer: { email: 'customer@example.com' }
 })
 
-// Redirect customer
 window.location.href = checkoutUrl
 ```
 
-## 📚 Documentation
+## Documentation
 
 ### Core SDK
 
-#### `TorqueCheckout` Class
-
-The main SDK class for generating checkout URLs and managing orders.
+#### Initialization
 
 ```ts
-import { createTorqueCheckout } from 'torque-checkout'
+import { createTorqueCheckout, createTorqueCheckoutFromEnv } from 'torque-checkout'
 
+// Method 1: From environment variables (recommended)
+const torque = createTorqueCheckoutFromEnv()
+
+// Method 2: Explicit configuration
 const torque = createTorqueCheckout({
-  businessId: 'your_business_id',
-  apiKey: 'your_api_key',
+  businessId: process.env.TORQUE_BUSINESS_ID!,
+  apiKey: process.env.TORQUE_API_KEY!,
   baseUrl: 'https://app.torque.fi', // Optional
   timeout: 30000 // Optional, default: 30000ms
 })
@@ -152,16 +227,23 @@ const torque = createTorqueCheckout({
 Generate a checkout URL for a multi-product cart.
 
 ```ts
-const url = await torque.generateCartCheckoutUrl({
+const checkoutUrl = await torque.generateCartCheckoutUrl({
   items: [
-    { productId: 'prod_123', quantity: 2, price: 29.99 },
-    { productId: 'prod_456', quantity: 1, price: 49.99 }
+    { 
+      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',
@@ -170,66 +252,75 @@ const url = await torque.generateCartCheckoutUrl({
     }
   },
   options: {
-    metadata: { orderId: 'order_123', source: 'website' },
-    expiresIn: 24 * 60 * 60 * 1000, // 24 hours
-    redirectUrl: 'https://yoursite.com/thank-you'
+    metadata: { orderId: 'order_123', source: 'website' }, // Optional
+    expiresIn: 24 * 60 * 60 * 1000, // Optional: 24 hours
+    redirectUrl: 'https://yoursite.com/thank-you' // Optional
   }
 })
 ```
 
-##### `generateProductCheckoutUrl(productId, quantity, customer?, options?): Promise<string>`
+##### `generateProductCheckoutUrl(productId, quantity?, customer?, options?): Promise<string>`
 
-Generate a checkout URL for a single product.
+Quick method for single product checkout.
 
 ```ts
-const url = await torque.generateProductCheckoutUrl(
-  'prod_123',
-  2,
-  { email: 'customer@example.com' }
+const checkoutUrl = await torque.generateProductCheckoutUrl(
+  'prod_123', // Product ID
+  2, // Quantity (default: 1)
+  { email: 'customer@example.com' }, // Customer data (optional)
+  { redirectUrl: 'https://yoursite.com/success' } // Options (optional)
 )
 ```
 
 ##### `generateSubscriptionCheckoutUrl(productId, paymentPlanId, customer?, options?): Promise<string>`
 
-Generate a checkout URL for a subscription product.
+Generate checkout for subscription products.
 
 ```ts
-const url = await torque.generateSubscriptionCheckoutUrl(
-  'prod_subscription_123',
-  'plan_monthly_123',
-  { email: 'customer@example.com' }
+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 data before generating checkout.
+Validate cart before checkout to catch errors early.
 
 ```ts
-const validation = await torque.validateCart(cart)
+const validation = await torque.validateCart({
+  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.error('Validation errors:', validation.errors)
+  console.warn('Warnings:', validation.warnings)
 }
 ```
 
 ##### `getOrderStatus(orderId: string): Promise<OrderStatus>`
 
-Get the current status of an order.
+Check order status after checkout.
 
 ```ts
 const order = await torque.getOrderStatus('order_123')
-console.log('Order status:', order.status)
+
+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)
 ```
 
 ### React Hooks
 
 #### `useTorqueCheckout(options?)`
 
-React hook for client-side checkout generation.
+React hook for client-side checkout with built-in state management.
 
 ```tsx
 import { useTorqueCheckout } from 'torque-checkout/react'
@@ -245,23 +336,47 @@ function CheckoutButton() {
     error,
     checkoutUrl
   } = useTorqueCheckout({
-    config: {
-      businessId: 'your_business_id',
-      apiKey: 'your_api_key'
+    // 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
     },
-    // Or use environment variables (no config needed)
-    autoRedirect: true,
-    onSuccess: (url) => console.log('Success:', url),
-    onError: (error) => console.error('Error:', error)
+    onError: (error) => {
+      console.error('Checkout error:', error)
+      // Optional: show error toast
+    }
   })
 
-  // Use the methods...
+  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
+    }
+  }
+
+  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>
+  )
 }
 ```
 
 #### `useCart()`
 
-React hook for managing shopping cart state.
+Shopping cart state management hook.
 
 ```tsx
 import { useCart } from 'torque-checkout/react'
@@ -279,16 +394,26 @@ function ShoppingCart() {
 
   return (
     <div>
-      <h2>Cart ({getItemCount()} items)</h2>
-      <p>Total: ${getTotal().toFixed(2)}</p>
+      <h2>Shopping Cart ({getItemCount()} items)</h2>
+      
       {items.map(item => (
-        <div key={`${item.productId}-${item.variant}`}>
-          {item.productId} x {item.quantity}
+        <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>
   )
 }
@@ -296,65 +421,80 @@ function ShoppingCart() {
 
 ### Next.js Server Utilities
 
-#### `generateCheckoutUrl(cart, config?)`
-
-Generate checkout URL on the server.
-
-```ts
-// app/api/checkout/route.ts
-import { generateCheckoutUrl } from 'torque-checkout/nextjs'
-
-export async function POST(request: Request) {
-  const cart = await request.json()
-  const url = await generateCheckoutUrl(cart)
-  return Response.json({ checkoutUrl: url })
-}
-```
-
 #### `handleCheckoutRequest(options?)`
 
-Next.js API route handler for checkout generation.
+Complete API route handler with error handling.
 
 ```ts
 // app/api/checkout/route.ts
 import { handleCheckoutRequest } from 'torque-checkout/nextjs'
 
 export const POST = handleCheckoutRequest({
-  onSuccess: async (url, cart) => {
-    // Log or process checkout
-    console.log('Checkout generated:', url)
+  onSuccess: async (checkoutUrl, cart) => {
+    // Optional: Log, track analytics, send notifications
+    console.log('Checkout generated:', checkoutUrl)
+    await logCheckoutEvent(cart)
   },
   onError: async (error, cart) => {
-    // Handle error
+    // Optional: Error logging, notifications
     console.error('Checkout error:', error)
+    await logError(error, cart)
   }
 })
 ```
 
 #### `handleWebhook(options?)`
 
-Next.js API route handler for webhook events.
+Webhook handler for order events.
 
 ```ts
 // app/api/webhooks/torque/route.ts
 import { handleWebhook } from 'torque-checkout/nextjs'
 
 export const POST = handleWebhook({
-  secret: process.env.TORQUE_WEBHOOK_SECRET,
+  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 order
+    // Handle failed payment
     await notifyCustomer(event.orderId!)
+  },
+  onSubscriptionCreated: async (event) => {
+    // Activate subscription
+    await activateSubscription(event.subscriptionId!)
   }
 })
 ```
 
-## 🎯 Complete Examples
+#### `generateCheckoutUrl(cart, config?)`
+
+Server-side checkout URL generation.
 
-### Next.js App Router - Full E-Commerce Integration
+```ts
+// app/api/checkout/route.ts
+import { generateCheckoutUrl } from 'torque-checkout/nextjs'
+
+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 }
+    )
+  }
+}
+```
+
+## Complete Examples
+
+### E-Commerce Product Page
 
 ```tsx
 // app/products/[id]/page.tsx
@@ -364,26 +504,26 @@ import { useTorqueCheckout, useCart } from 'torque-checkout/react'
 import { useState } from 'react'
 
 export default function ProductPage({ params }: { params: { id: string } }) {
-  const { addItem, items, getItemCount } = useCart()
+  const cart = useCart()
   const { generateProductCheckout, isLoading } = useTorqueCheckout({
     autoRedirect: true
   })
   const [quantity, setQuantity] = useState(1)
 
   const handleAddToCart = () => {
-    addItem({
+    cart.addItem({
       productId: params.id,
       quantity,
-      price: 29.99 // Your product price
+      price: 29.99
     })
   }
 
-  const handleCheckout = async () => {
+  const handleBuyNow = async () => {
     await generateProductCheckout(
       params.id,
       quantity,
       {
-        email: 'customer@example.com' // Get from user session
+        email: 'customer@example.com' // Get from auth/session
       }
     )
   }
@@ -391,6 +531,8 @@ export default function ProductPage({ params }: { params: { id: string } }) {
   return (
     <div>
       <h1>Product {params.id}</h1>
+      <p>$29.99</p>
+      
       <div>
         <label>Quantity:</label>
         <input
@@ -400,51 +542,82 @@ export default function ProductPage({ params }: { params: { id: string } }) {
           min="1"
         />
       </div>
-      <button onClick={handleAddToCart}>Add to Cart</button>
-      <button onClick={handleCheckout} disabled={isLoading}>
-        {isLoading ? 'Processing...' : 'Checkout'}
+      
+      <button onClick={handleAddToCart}>
+        Add to Cart ({cart.getItemCount()} items)
+      </button>
+      
+      <button onClick={handleBuyNow} disabled={isLoading}>
+        {isLoading ? 'Processing...' : 'Buy Now'}
       </button>
-      <p>Cart: {getItemCount()} items</p>
     </div>
   )
 }
 ```
 
-### Next.js Pages Router - API Route
+### Shopping Cart with Checkout
 
-```ts
-// pages/api/checkout.ts
-import type { NextApiRequest, NextApiResponse } from 'next'
-import { createTorqueCheckoutFromEnv } from 'torque-checkout'
+```tsx
+// app/cart/page.tsx
+'use client'
 
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' })
-  }
+import { useTorqueCheckout, useCart } from 'torque-checkout/react'
 
-  try {
-    const torque = createTorqueCheckoutFromEnv()
-    const checkoutUrl = await torque.generateCartCheckoutUrl(req.body)
+export default function CartPage() {
+  const cart = useCart()
+  const { generateCheckout, isLoading } = useTorqueCheckout()
 
-    res.status(200).json({ checkoutUrl })
-  } catch (error: any) {
-    res.status(500).json({
-      error: error.message,
-      code: error.code
+  const handleCheckout = async () => {
+    const url = await generateCheckout({
+      items: cart.items,
+      customer: {
+        email: 'customer@example.com' // Get from auth
+      },
+      options: {
+        redirectUrl: window.location.origin + '/thank-you'
+      }
     })
+    
+    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>
+  )
 }
 ```
 
-### Server Component (Next.js 13+)
+### Server Component Checkout (Next.js 13+)
 
 ```tsx
 // app/checkout/page.tsx
 import { createTorqueCheckoutFromEnv } from 'torque-checkout'
 import { redirect } from 'next/navigation'
+import { cookies } from 'next/headers'
 
 export default async function CheckoutPage({
   searchParams
@@ -453,40 +626,104 @@ export default async function CheckoutPage({
 }) {
   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: 'customer@example.com' // Get from session
-    }
+    { email: customerEmail }
   )
 
   redirect(checkoutUrl)
 }
 ```
 
-## 🔧 TypeScript Types
+### Pages Router API Route
+
+```ts
+// pages/api/checkout.ts
+import type { NextApiRequest, NextApiResponse } from 'next'
+import { createTorqueCheckoutFromEnv } from 'torque-checkout'
 
-The SDK provides comprehensive TypeScript types:
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' })
+  }
+
+  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,
-  CustomerData,
   CartOptions,
-  CheckoutResponse,
-  OrderStatus,
   CartValidation,
+  
+  // Customer types
+  CustomerData,
+  
+  // Order types
+  OrderStatus,
+  CheckoutResponse,
+  
+  // Subscription types
   Subscription,
   SubscriptionProduct,
   PaymentPlan,
+  CreateSubscriptionData,
+  UpdateSubscriptionData,
+  
+  // Config types
   TorqueConfig,
   TorqueCheckoutError
 } from 'torque-checkout'
 ```
 
-## 🛡️ Error Handling
+### Type-Safe Usage
+
+```ts
+import { createTorqueCheckout } from 'torque-checkout'
+import type { CartData, CustomerData } from 'torque-checkout'
+
+const torque = createTorqueCheckout({
+  businessId: process.env.TORQUE_BUSINESS_ID!,
+  apiKey: process.env.TORQUE_API_KEY!
+})
+
+const cart: CartData = {
+  items: [
+    { productId: 'prod_123', quantity: 1 }
+  ],
+  customer: {
+    email: 'customer@example.com'
+  } as CustomerData
+}
+
+const url: string = await torque.generateCartCheckoutUrl(cart)
+```
+
+## Error Handling
 
 The SDK uses custom error classes for better error handling:
 
@@ -504,54 +741,200 @@ try {
     // Handle specific error codes
     switch (error.code) {
       case 'VALIDATION_ERROR':
-        // Handle validation errors
+        // Show validation errors to user
+        showErrors(error.details?.errors)
         break
       case 'BUSINESS_NOT_FOUND':
-        // Handle business not found
+        // Check business ID configuration
+        console.error('Invalid business ID')
         break
       case 'TIMEOUT':
-        // Handle timeout
+        // Retry or show timeout message
+        retryCheckout()
+        break
+      case 'NETWORK_ERROR':
+        // Check internet connection
+        showNetworkError()
         break
       default:
-        // Handle other errors
+        // Generic error handling
+        showGenericError(error.message)
     }
+  } else {
+    // Unknown error
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+### 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
+```
+
+Or provide explicit config:
+```ts
+const torque = createTorqueCheckout({
+  businessId: 'your_business_id',
+  apiKey: 'your_api_key'
+})
+```
+
+### Issue: "Request timeout"
+
+**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
+})
+```
+
+### 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
+
+### Issue: React hooks not working
+
+**Solution**: Make sure you're using the React entry point:
+```tsx
+// Correct
+import { useTorqueCheckout } from 'torque-checkout/react'
+
+// Wrong
+import { useTorqueCheckout } from 'torque-checkout'
+```
+
+### Issue: TypeScript errors
+
+**Solution**: Make sure TypeScript can find the types:
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "moduleResolution": "node",
+    "esModuleInterop": true
   }
 }
 ```
 
-## 🔐 Security Best Practices
+## Migration Guide
+
+### From v1.x to v2.0.0
 
-1. **Never expose API keys in client-side code** - Use environment variables and server-side API routes
-2. **Validate all input** - The SDK includes validation, but always validate user input
-3. **Use HTTPS** - Always use HTTPS in production
-4. **Verify webhook signatures** - Use the webhook secret to verify webhook authenticity
-5. **Set payment wallet in business settings** - Payments automatically go to your configured wallet
+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
+## API Reference
 
-See the [full API documentation](https://docs.torque.fi/api) for complete 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
+## Support
 
 - **Documentation**: [https://docs.torque.fi](https://docs.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
+## License
 
 MIT © [Torque](https://torque.fi)
 
-## 🎉 Getting Started Checklist
+## Getting Started Checklist
 
-- [ ] Install the package: `npm install torque-checkout`
-- [ ] Create Torque business profile at [app.torque.fi/business/settings](https://app.torque.fi/business/settings)
+- [ ] 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 in your code
+- [ ] Import and use the SDK
 - [ ] Test checkout flow
-- [ ] Deploy to production! 🚀
+- [ ] Deploy to production!
 
 ---
 
-**Made with ❤️ by [Torque](https://torque.fi)**
+**Made with love by [Torque](https://torque.fi)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "torque-checkout",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Official Torque checkout SDK for seamless eCommerce integrations with Next.js",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",