@withvlibe/base-sdk 1.0.1 → 1.1.1

package/README.md

@@ -309,6 +309,290 @@ const products = await db.query<Product>('products', { where: { isActive: true }
 const orders = await db.query<Order>('orders', { where: { userId: user.id } });
 ```
 
+## E-Commerce
+
+The SDK provides specialized e-commerce functionality through `VlibeBaseEcommerce`.
+
+### Setup
+
+```typescript
+import { VlibeBaseEcommerce } from '@withvlibe/base-sdk';
+
+// Initialize with database client
+export const ecommerce = new VlibeBaseEcommerce(db);
+```
+
+### Products
+
+```typescript
+// Create a product
+const product = await ecommerce.createProduct({
+  name: 'Premium T-Shirt',
+  description: 'High-quality cotton t-shirt',
+  price: 2999, // $29.99 in cents
+  currency: 'usd',
+  stock: 100,
+  images: ['https://example.com/tshirt.jpg'],
+  category: 'apparel',
+  isActive: true,
+});
+
+// List products
+const { products, total } = await ecommerce.listProducts({
+  category: 'apparel',
+  isActive: true,
+  sortBy: 'created_at',
+  limit: 20,
+});
+
+// Update inventory
+await ecommerce.updateInventory(productId, 50, 'set');
+await ecommerce.updateInventory(productId, 5, 'increment');
+await ecommerce.updateInventory(productId, 3, 'decrement');
+
+// Get low stock products
+const lowStock = await ecommerce.getLowStockProducts(10); // threshold: 10
+```
+
+### Shopping Cart
+
+```typescript
+// Add to cart
+await ecommerce.addToCart(userId, {
+  productId: 'product-123',
+  quantity: 2,
+});
+
+// Get cart (lightweight - only IDs and quantities)
+const cart = await ecommerce.getCart(userId);
+// Returns: [{ productId: '...', quantity: 2 }]
+
+// Get cart with full product details
+const detailedCart = await ecommerce.getCartWithDetails(userId);
+// Returns: [{ productId: '...', quantity: 2, product: {...}, lineTotal: 5998 }]
+
+// Update quantity
+await ecommerce.updateCartItem(userId, productId, 5);
+
+// Remove item (set quantity to 0)
+await ecommerce.updateCartItem(userId, productId, 0);
+
+// Calculate order totals
+const calculation = await ecommerce.calculateOrderTotal(cart);
+console.log('Subtotal:', calculation.subtotal);
+console.log('Tax:', calculation.tax);
+console.log('Shipping:', calculation.shipping);
+console.log('Total:', calculation.total);
+
+// Checkout (creates order and clears cart)
+const order = await ecommerce.checkout(userId, {
+  line1: '123 Main St',
+  city: 'San Francisco',
+  state: 'CA',
+  postalCode: '94102',
+  country: 'US',
+}, paymentMethodId);
+```
+
+### Orders
+
+```typescript
+// Create an order directly
+const order = await ecommerce.createOrder({
+  userId: 'user-123',
+  items: [
+    { productId: 'product-1', quantity: 2 },
+    { productId: 'product-2', quantity: 1 },
+  ],
+  shippingAddress: {
+    line1: '123 Main St',
+    city: 'San Francisco',
+    state: 'CA',
+    postalCode: '94102',
+    country: 'US',
+  },
+});
+
+// List orders
+const { orders, total } = await ecommerce.listOrders({
+  userId: 'user-123',
+  status: 'pending',
+  limit: 10,
+});
+
+// Update order status
+await ecommerce.updateOrderStatus(orderId, 'shipped');
+
+// Cancel order (optionally restore inventory)
+await ecommerce.cancelOrder(orderId, true);
+```
+
+### Analytics
+
+```typescript
+// Revenue stats
+const stats = await ecommerce.getRevenueStats('month');
+console.log('Revenue:', stats.totalRevenue);
+console.log('Orders:', stats.totalOrders);
+console.log('AOV:', stats.averageOrderValue);
+console.log('Trend:', stats.trend.revenue); // % change
+
+// Top products
+const topProducts = await ecommerce.getTopProducts(10, 'week');
+
+// Order statistics
+const orderStats = await ecommerce.getOrderStats();
+console.log('Pending:', orderStats.pending);
+console.log('Delivered:', orderStats.delivered);
+```
+
+### React Hooks for E-Commerce
+
+```tsx
+import { useProducts, useCart, useOrders } from '@withvlibe/base-sdk/react';
+
+function ProductList() {
+  const { products, loading, createProduct, updateProduct } = useProducts(ecommerce, {
+    category: 'apparel',
+    isActive: true,
+  });
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {products.map(product => (
+        <div key={product.id}>
+          <h3>{product.name}</h3>
+          <p>${(product.price / 100).toFixed(2)}</p>
+          <p>Stock: {product.stock}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function ShoppingCart({ userId }: { userId: string }) {
+  const { cart, itemCount, addItem, updateItem, removeItem, checkout, getCartWithDetails } = useCart(ecommerce, userId);
+  const [detailedItems, setDetailedItems] = useState([]);
+
+  useEffect(() => {
+    // Load cart with product details
+    const loadDetails = async () => {
+      const items = await getCartWithDetails();
+      setDetailedItems(items);
+    };
+    loadDetails();
+  }, [getCartWithDetails]);
+
+  return (
+    <div>
+      <h2>Cart ({itemCount} items)</h2>
+      {detailedItems.map(item => (
+        <div key={item.productId}>
+          <h3>{item.product.name}</h3>
+          <p>${(item.product.price / 100).toFixed(2)} x {item.quantity}</p>
+          <p>Subtotal: ${(item.lineTotal / 100).toFixed(2)}</p>
+          <button onClick={() => updateItem(item.productId, item.quantity + 1)}>+</button>
+          <button onClick={() => updateItem(item.productId, item.quantity - 1)}>-</button>
+          <button onClick={() => removeItem(item.productId)}>Remove</button>
+        </div>
+      ))}
+      <button onClick={() => checkout(shippingAddress)}>Checkout</button>
+    </div>
+  );
+}
+
+function OrderHistory({ userId }: { userId: string }) {
+  const { orders, loading, updateStatus, cancelOrder } = useOrders(ecommerce, { userId });
+
+  if (loading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      {orders.map(order => (
+        <div key={order.id}>
+          <h3>Order #{order.id}</h3>
+          <p>Status: {order.status}</p>
+          <p>Total: ${(order.total / 100).toFixed(2)}</p>
+          <ul>
+            {order.items.map(item => (
+              <li key={item.productId}>
+                {item.name} x {item.quantity} - ${(item.price / 100).toFixed(2)}
+              </li>
+            ))}
+          </ul>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### Database Schema
+
+Create these tables in your database:
+
+```typescript
+// Products table
+interface ProductRow {
+  id: string;
+  name: string;
+  description?: string;
+  sku?: string;
+  price: number; // cents
+  currency: string;
+  images: string[]; // JSON array
+  stock: number;
+  isActive: boolean;
+  category?: string;
+  metadata?: Record<string, any>; // JSON
+  created_at: string;
+  updated_at: string;
+}
+
+// Orders table
+interface OrderRow {
+  id: string;
+  userId: string;
+  status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
+  items: OrderItem[]; // JSON array
+  subtotal: number;
+  tax: number;
+  shipping: number;
+  total: number;
+  shippingAddress: Address; // JSON
+  billingAddress?: Address; // JSON
+  paymentMethodId?: string;
+  stripePaymentIntentId?: string;
+  notes?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+// Order Items table (for queries)
+interface OrderItemRow {
+  id: string;
+  orderId: string;
+  productId: string;
+  name: string;
+  quantity: number;
+  price: number;
+  lineTotal: number;
+  created_at: string;
+}
+
+// Carts table
+interface CartRow {
+  id: string;
+  userId: string;
+  productId: string;
+  quantity: number;
+  created_at: string;
+  updated_at: string;
+}
+```
+
 ## API Reference
 
 ### VlibeBaseDatabase

package/dist/{VlibeBaseAuth-BxS9T0vB.d.mts → VlibeBaseEcommerce-DXjHdN_L.d.mts}

@@ -236,8 +236,7 @@ interface UsageMetric {
     period: string;
     createdAt: string;
 }
-interface Product {
-    id: string;
+interface Product extends BaseRecord {
     name: string;
     description?: string;
     sku?: string;
@@ -247,19 +246,21 @@ interface Product {
     stock: number;
     isActive: boolean;
     category?: string;
-    createdAt: string;
-    updatedAt: string;
+    metadata?: Record<string, any>;
 }
-interface Order {
-    id: string;
+interface Order extends BaseRecord {
     userId: string;
     status: 'pending' | 'processing' | 'shipped' | 'delivered' | 'cancelled';
     items: OrderItem[];
     subtotal: number;
     tax: number;
+    shipping: number;
     total: number;
     shippingAddress?: Address;
-    createdAt: string;
+    billingAddress?: Address;
+    paymentMethodId?: string;
+    stripePaymentIntentId?: string;
+    notes?: string;
 }
 interface OrderItem {
     productId: string;
@@ -279,6 +280,76 @@ interface CartItem {
     productId: string;
     quantity: number;
 }
+interface CartItemWithProduct {
+    productId: string;
+    quantity: number;
+    product: Product;
+    lineTotal: number;
+}
+interface CreateProductInput {
+    name: string;
+    description?: string;
+    sku?: string;
+    price: number;
+    currency: string;
+    images?: string[];
+    stock: number;
+    isActive?: boolean;
+    category?: string;
+    metadata?: Record<string, any>;
+}
+interface CreateOrderInput {
+    userId: string;
+    items: Array<{
+        productId: string;
+        quantity: number;
+    }>;
+    shippingAddress: Address;
+    billingAddress?: Address;
+    paymentMethodId?: string;
+    notes?: string;
+}
+interface OrderCalculation {
+    subtotal: number;
+    tax: number;
+    shipping: number;
+    total: number;
+    items: Array<{
+        productId: string;
+        name: string;
+        price: number;
+        quantity: number;
+        lineTotal: number;
+        inStock: boolean;
+    }>;
+}
+interface RevenueStats {
+    totalRevenue: number;
+    totalOrders: number;
+    averageOrderValue: number;
+    period: {
+        start: string;
+        end: string;
+    };
+    trend: {
+        revenue: number;
+        orders: number;
+    };
+}
+interface ProductStats {
+    productId: string;
+    name: string;
+    totalSold: number;
+    revenue: number;
+}
+interface OrderStats {
+    pending: number;
+    processing: number;
+    shipped: number;
+    delivered: number;
+    cancelled: number;
+    averageOrderValue: number;
+}
 /**
  * Standard API response
  */
@@ -564,4 +635,133 @@ declare class VlibeBaseAuth {
     getBaseUrl(): string;
 }
 
-export { type AppCategory as A, type BasePlan as B, type ConnectStatus as C, type DatabaseConfig as D, type FeatureFlag as F, type Media as M, type Order as O, type PaymentsConfig as P, type QueryOptions as Q, type RefundOptions as R, type Subscription as S, type Transaction as T, type UsageMetric as U, VlibeBaseDatabase as V, type CheckoutOptions as a, type CheckoutSession as b, VlibeBaseAuth as c, type VlibeBaseConfig as d, type AuthConfig as e, type ColumnType as f, type TableColumn as g, type TableSchema as h, type TableInfo as i, type BaseRecord as j, type RealtimePayload as k, type VlibeUser as l, type VerifyResponse as m, type AuthSession as n, type Page as o, type Product as p, type OrderItem as q, type Address as r, type CartItem as s, type ApiResponse as t, type PaginatedResponse as u, type UseCollectionReturn as v, type UseCollectionOptions as w, type UseKVReturn as x, type UseAuthReturn as y, type UsePaymentsReturn as z };
+/**
+ * VlibeBaseEcommerce - E-commerce functionality for Vlibe Base apps
+ *
+ * Provides specialized methods for managing products, inventory, orders,
+ * shopping carts, and e-commerce analytics.
+ */
+declare class VlibeBaseEcommerce {
+    private db;
+    constructor(db: VlibeBaseDatabase);
+    /**
+     * Create a new product
+     * Auto-generates SKU if not provided
+     */
+    createProduct(input: CreateProductInput): Promise<Product>;
+    /**
+     * Update an existing product
+     */
+    updateProduct(productId: string, updates: Partial<Product>): Promise<Product>;
+    /**
+     * Get a single product by ID
+     */
+    getProduct(productId: string): Promise<Product | null>;
+    /**
+     * List products with filtering and pagination
+     */
+    listProducts(options?: {
+        category?: string;
+        isActive?: boolean;
+        sortBy?: 'name' | 'price' | 'stock' | 'created_at';
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        products: Product[];
+        total: number;
+    }>;
+    /**
+     * Soft delete a product (sets isActive = false)
+     */
+    deleteProduct(productId: string): Promise<void>;
+    /**
+     * Update product inventory with atomic operations
+     */
+    updateInventory(productId: string, quantity: number, operation: 'set' | 'increment' | 'decrement'): Promise<Product>;
+    /**
+     * Get products below stock threshold
+     */
+    getLowStockProducts(threshold?: number): Promise<Product[]>;
+    /**
+     * Bulk update inventory for multiple products
+     */
+    bulkUpdateInventory(updates: Array<{
+        productId: string;
+        quantity: number;
+        operation: 'set' | 'increment' | 'decrement';
+    }>): Promise<Product[]>;
+    /**
+     * Calculate order totals from cart items
+     */
+    calculateOrderTotal(items: CartItem[]): Promise<OrderCalculation>;
+    /**
+     * Create an order from cart items
+     * Reduces inventory atomically
+     */
+    createOrder(input: CreateOrderInput): Promise<Order>;
+    /**
+     * Get an order by ID
+     */
+    getOrder(orderId: string): Promise<Order | null>;
+    /**
+     * List orders with filtering
+     */
+    listOrders(options?: {
+        userId?: string;
+        status?: Order['status'];
+        sortBy?: 'created_at' | 'total';
+        limit?: number;
+        offset?: number;
+    }): Promise<{
+        orders: Order[];
+        total: number;
+    }>;
+    /**
+     * Update order status
+     */
+    updateOrderStatus(orderId: string, status: Order['status']): Promise<Order>;
+    /**
+     * Cancel an order and optionally restore inventory
+     */
+    cancelOrder(orderId: string, restoreInventory?: boolean): Promise<Order>;
+    /**
+     * Add item to user's cart
+     */
+    addToCart(userId: string, item: CartItem): Promise<CartItem[]>;
+    /**
+     * Update cart item quantity or remove if quantity = 0
+     */
+    updateCartItem(userId: string, productId: string, quantity: number): Promise<CartItem[]>;
+    /**
+     * Get user's cart
+     */
+    getCart(userId: string): Promise<CartItem[]>;
+    /**
+     * Get user's cart with full product details
+     */
+    getCartWithDetails(userId: string): Promise<CartItemWithProduct[]>;
+    /**
+     * Clear user's cart
+     */
+    clearCart(userId: string): Promise<void>;
+    /**
+     * Checkout - convert cart to order and clear cart
+     */
+    checkout(userId: string, shippingAddress: Address, paymentMethodId?: string): Promise<Order>;
+    /**
+     * Get revenue statistics for a time period
+     */
+    getRevenueStats(period: 'day' | 'week' | 'month' | 'year'): Promise<RevenueStats>;
+    /**
+     * Get top selling products
+     */
+    getTopProducts(limit?: number, period?: 'day' | 'week' | 'month'): Promise<ProductStats[]>;
+    /**
+     * Get order statistics by status
+     */
+    getOrderStats(): Promise<OrderStats>;
+    private generateSKU;
+    private getPeriodStart;
+}
+
+export { type AppCategory as A, type BasePlan as B, type ConnectStatus as C, type DatabaseConfig as D, type OrderStats as E, type FeatureFlag as F, type ApiResponse as G, type PaginatedResponse as H, type UseCollectionReturn as I, type UseCollectionOptions as J, type UseKVReturn as K, type UseAuthReturn as L, type Media as M, type UsePaymentsReturn as N, type Order as O, type PaymentsConfig as P, type QueryOptions as Q, type RefundOptions as R, type Subscription as S, type Transaction as T, type UsageMetric as U, VlibeBaseDatabase as V, type CheckoutOptions as a, type CheckoutSession as b, VlibeBaseAuth as c, VlibeBaseEcommerce as d, type VlibeBaseConfig as e, type AuthConfig as f, type ColumnType as g, type TableColumn as h, type TableSchema as i, type TableInfo as j, type BaseRecord as k, type RealtimePayload as l, type VlibeUser as m, type VerifyResponse as n, type AuthSession as o, type Page as p, type Product as q, type OrderItem as r, type Address as s, type CartItem as t, type CartItemWithProduct as u, type CreateProductInput as v, type CreateOrderInput as w, type OrderCalculation as x, type RevenueStats as y, type ProductStats as z };