@basedone/core 0.1.10 → 0.2.1

package/lib/ecommerce/USAGE_EXAMPLES.md

@@ -0,0 +1,704 @@
+# Ecommerce SDK Usage Examples
+
+This document provides comprehensive examples of using the Ecommerce SDK in various scenarios.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Customer Examples](#customer-examples)
+  - [Browsing Products](#browsing-products)
+  - [Placing Orders](#placing-orders)
+  - [Managing Reviews](#managing-reviews)
+  - [Shipping Addresses](#shipping-addresses)
+  - [Cart & Discounts](#cart--discounts)
+- [Merchant Examples](#merchant-examples)
+  - [Product Management](#product-management)
+  - [Order Fulfillment](#order-fulfillment)
+  - [Customer Management](#customer-management)
+  - [Analytics](#analytics)
+  - [Tax Management](#tax-management)
+- [React Native Examples](#react-native-examples)
+- [Error Handling](#error-handling)
+
+## Installation
+
+```bash
+npm install @basedone/core
+# or
+pnpm add @basedone/core
+```
+
+## Customer Examples
+
+### Browsing Products
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  authToken: "user-auth-token",
+});
+
+// List all products
+const products = await client.listProducts({
+  limit: 20,
+  offset: 0,
+});
+
+// Search products
+const searchResults = await client.listProducts({
+  search: "laptop",
+  category: "electronics",
+  minPrice: 500,
+  maxPrice: 2000,
+  sortBy: "price_asc",
+});
+
+// Get product details
+const product = await client.getProduct("prod_123");
+console.log(product.product.title, product.product.priceUSDC);
+
+// Track product view (analytics)
+await client.trackProductView("prod_123");
+
+// Get active discounts for a product
+const discounts = await client.getProductDiscounts("prod_123");
+discounts.discounts.forEach(d => {
+  console.log(d.badge, d.description);
+});
+```
+
+### Placing Orders
+
+```typescript
+// Create order with USDC escrow payment
+const order = await client.createOrder({
+  items: [
+    { productId: "prod_123", quantity: 2 },
+    { productId: "prod_456", quantity: 1, variantId: "var_789" },
+  ],
+  paymentMethod: "USDC_ESCROW",
+  shippingAddress: {
+    fullName: "John Doe",
+    phone: "+1234567890",
+    email: "john@example.com",
+    addressLine1: "123 Main St",
+    addressLine2: "Apt 4B",
+    city: "New York",
+    stateProvince: "NY",
+    postalCode: "10001",
+    country: "US",
+  },
+  couponCode: "SAVE10",
+  customerNotes: "Please leave at door",
+});
+
+// For USDC escrow, deposit to the escrow address
+if (order.escrow) {
+  console.log(`Deposit ${order.escrow.amountUSDC} USDC to ${order.escrow.address}`);
+  
+  // After depositing via Hyperliquid, confirm the transaction
+  const confirmation = await client.confirmEscrowDeposit(order.orders[0].id);
+  console.log("Payment confirmed:", confirmation.depositTxHash);
+}
+
+// Multi-merchant checkout (automatic order splitting)
+const multiMerchantOrder = await client.createOrder({
+  items: [
+    { productId: "prod_from_merchant_a", quantity: 1 },
+    { productId: "prod_from_merchant_b", quantity: 2 },
+  ],
+  paymentMethod: "USDC_ESCROW",
+  shippingAddress: { /* ... */ },
+});
+
+console.log(`Created ${multiMerchantOrder.summary.orderCount} orders`);
+console.log(`Merchants: ${multiMerchantOrder.summary.merchantNames.join(", ")}`);
+
+// List user's orders
+const orders = await client.listOrders({
+  limit: 10,
+  offset: 0,
+  status: "SHIPPED",
+});
+
+// Get order details
+const orderDetails = await client.getOrder("ord_123");
+console.log("Status:", orderDetails.order.status);
+console.log("Tracking:", orderDetails.order.shipment?.trackingNumber);
+
+// Get order receipt
+const receipt = await client.getOrderReceipt("ord_123");
+console.log("Order #", receipt.receipt.orderNumber);
+```
+
+### Managing Reviews
+
+```typescript
+// List product reviews
+const reviews = await client.listProductReviews("prod_123", {
+  limit: 10,
+  sortBy: "highest",
+});
+
+reviews.items.forEach(review => {
+  console.log(`${review.rating}/5 - ${review.title}`);
+  console.log(review.comment);
+  if (review.merchantResponse) {
+    console.log("Merchant:", review.merchantResponse);
+  }
+});
+
+// Create a review (requires verified purchase)
+const review = await client.createReview("prod_123", {
+  rating: 5,
+  title: "Excellent product!",
+  comment: "Exactly what I needed. Fast shipping and great quality.",
+});
+```
+
+### Shipping Addresses
+
+```typescript
+// List saved addresses
+const addresses = await client.listShippingAddresses();
+const defaultAddress = addresses.addresses.find(a => a.isDefault);
+
+// Add new address
+const newAddress = await client.createShippingAddress({
+  fullName: "John Doe",
+  phone: "+1234567890",
+  addressLine1: "456 Oak Ave",
+  city: "Los Angeles",
+  stateProvince: "CA",
+  postalCode: "90001",
+  country: "US",
+  isDefault: true,
+  label: "Home",
+});
+
+// Update address
+await client.updateShippingAddress("addr_123", {
+  phone: "+0987654321",
+});
+
+// Delete address
+await client.deleteShippingAddress("addr_123");
+```
+
+### Cart & Discounts
+
+```typescript
+// Calculate automatic discounts
+const cart = [
+  { productId: "prod_123", quantity: 2 },
+  { productId: "prod_456", quantity: 1 },
+];
+
+const discountResult = await client.calculateCartDiscounts({ items: cart });
+console.log("Subtotal:", discountResult.subtotal);
+console.log("Discount:", discountResult.discountAmount);
+console.log("Total:", discountResult.total);
+
+discountResult.appliedDiscounts.forEach(d => {
+  console.log(`${d.code}: -$${d.discountAmount}`);
+});
+
+// Validate coupon code
+const validation = await client.validateDiscountCode({
+  code: "SAVE20",
+  items: cart,
+});
+
+if (validation.valid) {
+  console.log("Coupon valid! Discount:", validation.discount?.discountAmount);
+} else {
+  console.log("Error:", validation.error);
+}
+
+// Calculate tax
+const taxResult = await client.calculateTax({
+  items: cart,
+  shippingAddress: {
+    country: "US",
+    region: "NY",
+    postalCode: "10001",
+  },
+});
+
+console.log("Subtotal:", taxResult.subtotal);
+console.log("Tax:", taxResult.taxAmount);
+console.log("Total:", taxResult.total);
+
+taxResult.breakdown.forEach(tax => {
+  console.log(`${tax.taxName}: ${tax.taxRate}% = $${tax.taxAmount}`);
+});
+```
+
+## Merchant Examples
+
+### Product Management
+
+```typescript
+import { MerchantEcommerceClient } from "@basedone/core/ecommerce";
+
+const client = new MerchantEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  authToken: "merchant-auth-token",
+});
+
+// Create merchant profile
+await client.upsertMerchantProfile({
+  name: "My Awesome Store",
+  description: "We sell the best products",
+  payoutAddress: "0x1234567890abcdef...",
+});
+
+// List merchant's products
+const products = await client.listMerchantProducts({ limit: 50 });
+
+// Create a product
+const product = await client.createProduct({
+  title: "Premium Laptop",
+  images: [
+    "https://storage.example.com/laptop-1.jpg",
+    "https://storage.example.com/laptop-2.jpg",
+  ],
+  priceUSDC: 1299.99,
+  compareAtPrice: 1499.99, // Show discount
+  inventory: 50,
+  sku: "LAPTOP-001",
+  category: "electronics",
+  richDescription: "<p>High-performance laptop with...</p>",
+  weight: 2.5,
+  dimensions: {
+    length: 35,
+    width: 25,
+    height: 2,
+  },
+  moq: 1,
+  isActive: true,
+});
+
+// Update product
+await client.updateProduct("prod_123", {
+  priceUSDC: 1199.99,
+  inventory: 45,
+});
+
+// Set product as featured
+await client.setProductFeatured("prod_123", true);
+
+// Create product variants
+const variant = await client.createProductVariant("prod_123", {
+  name: "16GB RAM / 512GB SSD",
+  sku: "LAPTOP-001-16-512",
+  attributes: {
+    ram: "16GB",
+    storage: "512GB",
+  },
+  priceUSDC: 1399.99,
+  inventory: 20,
+  sortOrder: 1,
+});
+
+// Get product metrics
+const metrics = await client.getProductMetrics();
+console.log("Total revenue:", metrics.summary.totalRevenue);
+console.log("Total sales:", metrics.summary.totalSales);
+
+metrics.products.forEach(p => {
+  console.log(`${p.name}: ${p.soldCount} sold, ${p.viewCount} views`);
+  console.log(`Conversion rate: ${p.conversionRate}%`);
+});
+```
+
+### Order Fulfillment
+
+```typescript
+// List orders
+const orders = await client.listMerchantOrders({
+  limit: 20,
+  status: "PAYMENT_RESERVED",
+});
+
+// Get order details
+const order = await client.getMerchantOrder("ord_123");
+
+// Accept order
+await client.updateOrderStatus("ord_123", {
+  status: "MERCHANT_ACCEPTED",
+});
+
+// Mark as shipped
+await client.updateOrderStatus("ord_123", {
+  status: "SHIPPED",
+  tracking: {
+    trackingNumber: "1Z999AA10123456784",
+    carrier: "UPS",
+  },
+});
+
+// Mark as delivered
+await client.updateOrderStatus("ord_123", {
+  status: "DELIVERED",
+});
+
+// Cancel order
+await client.updateOrderStatus("ord_123", {
+  status: "CANCELLED",
+});
+
+// Add custom order event
+await client.createOrderEvent("ord_123", {
+  eventType: "CUSTOM",
+  title: "Package delayed",
+  description: "Shipment delayed due to weather conditions",
+  metadata: {
+    reason: "weather",
+    estimatedDelay: "2 days",
+  },
+});
+
+// Manage shipments
+const shipments = await client.listShipments();
+
+await client.updateShipment("ship_123", {
+  status: "SHIPPED",
+  trackingNumber: "1Z999AA10123456784",
+  carrier: "UPS",
+});
+```
+
+### Customer Management
+
+```typescript
+// List customers with stats
+const customers = await client.listCustomers({ limit: 100 });
+
+customers.items.forEach(customer => {
+  console.log(`${customer.username || customer.email}`);
+  console.log(`Total orders: ${customer.totalOrders}`);
+  console.log(`Total spent: $${customer.totalSpent}`);
+  console.log(`Average order: $${customer.averageOrderValue}`);
+  console.log(`Last order: ${customer.lastOrderDate}`);
+});
+
+// Send message to customer
+await client.sendMessage({
+  orderId: "ord_123",
+  recipientId: "user_456",
+  message: "Your order has been shipped! Tracking: 1Z999AA10123456784",
+});
+
+// List messages
+const messages = await client.listMessages();
+console.log(`Total conversations: ${messages.stats.total}`);
+console.log(`Unread: ${messages.stats.unread}`);
+
+messages.conversations.forEach(conv => {
+  console.log(`Order #${conv.orderNumber} - ${conv.customer.name}`);
+  console.log(`Last: ${conv.lastMessage.message}`);
+  console.log(`Unread: ${conv.unreadCount}`);
+});
+
+// Mark message as read
+await client.markMessageRead("msg_123");
+```
+
+### Analytics
+
+```typescript
+// Get analytics dashboard
+const analytics = await client.getAnalytics({ range: "30days" });
+
+// Overview stats
+console.log("Total Revenue:", analytics.overview.totalRevenue);
+console.log("Revenue Change:", analytics.overview.revenueChange, "%");
+console.log("Total Orders:", analytics.overview.totalOrders);
+console.log("Orders Change:", analytics.overview.ordersChange, "%");
+console.log("Average Order Value:", analytics.overview.averageOrderValue);
+console.log("Total Customers:", analytics.overview.totalCustomers);
+
+// Revenue by day
+analytics.revenueByDay.forEach(day => {
+  console.log(`${day.date}: $${day.revenue} (${day.orders} orders)`);
+});
+
+// Top products
+analytics.topProducts.forEach((product, index) => {
+  console.log(`${index + 1}. ${product.name}`);
+  console.log(`   Sold: ${product.soldCount}, Revenue: $${product.revenue}`);
+});
+
+// Orders by status
+analytics.ordersByStatus.forEach(status => {
+  console.log(`${status.status}: ${status.count} (${status.percentage}%)`);
+});
+
+// Recent orders
+analytics.recentOrders.forEach(order => {
+  console.log(`#${order.orderNumber} - $${order.totalAmount} - ${order.status}`);
+});
+```
+
+### Tax Management
+
+```typescript
+// Get tax settings
+const settings = await client.getTaxSettings();
+console.log("Tax enabled:", settings.settings.taxEnabled);
+
+// Update tax settings
+await client.updateTaxSettings({
+  taxEnabled: true,
+  pricesIncludeTax: false,
+  defaultTaxBehavior: "CHARGE",
+  taxRegistrationNumber: "123456789",
+  registrationCountry: "US",
+});
+
+// Create tax rule
+await client.createTaxRule({
+  country: "US",
+  region: "NY",
+  taxType: "SALES_TAX",
+  taxName: "NY Sales Tax",
+  taxRate: 8.875,
+  priority: 1,
+});
+
+// Add tax nexus location
+await client.createTaxNexus({
+  country: "US",
+  region: "CA",
+  registrationId: "987654321",
+});
+
+// Generate tax report
+const report = await client.generateTaxReport({
+  periodType: "MONTHLY",
+  year: 2025,
+  period: 1, // January
+});
+
+// Get tax report details
+const reportDetails = await client.getTaxReport("report_123");
+console.log("Total taxable:", reportDetails.report.totalTaxable);
+console.log("Total tax:", reportDetails.report.totalTax);
+
+reportDetails.details.forEach(detail => {
+  console.log(`Order ${detail.orderId}: $${detail.taxAmount}`);
+});
+
+// Export tax report as CSV
+const csv = await client.exportTaxReport("report_123");
+// Save or download CSV
+```
+
+## React Native Examples
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { useEffect, useState } from "react";
+
+// Create client with stored auth token
+const createClient = async () => {
+  const authToken = await AsyncStorage.getItem("authToken");
+  return new CustomerEcommerceClient({
+    baseURL: "https://api.basedone.com",
+    authToken: authToken || undefined,
+  });
+};
+
+// Product list component
+function ProductList() {
+  const [products, setProducts] = useState([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const loadProducts = async () => {
+      try {
+        const client = await createClient();
+        const result = await client.listProducts({ limit: 20 });
+        setProducts(result.items);
+      } catch (error) {
+        console.error("Failed to load products:", error);
+      } finally {
+        setLoading(false);
+      }
+    };
+
+    loadProducts();
+  }, []);
+
+  if (loading) {
+    return <ActivityIndicator />;
+  }
+
+  return (
+    <FlatList
+      data={products}
+      renderItem={({ item }) => (
+        <ProductCard product={item} />
+      )}
+      keyExtractor={(item) => item.id}
+    />
+  );
+}
+
+// Checkout component
+function Checkout({ cartItems, shippingAddress }) {
+  const [loading, setLoading] = useState(false);
+
+  const handleCheckout = async () => {
+    setLoading(true);
+    try {
+      const client = await createClient();
+      
+      const order = await client.createOrder({
+        items: cartItems,
+        paymentMethod: "USDC_ESCROW",
+        shippingAddress,
+      });
+
+      if (order.escrow) {
+        // Navigate to payment screen with escrow details
+        navigation.navigate("Payment", {
+          address: order.escrow.address,
+          amount: order.escrow.amountUSDC,
+          orderId: order.orders[0].id,
+        });
+      }
+    } catch (error) {
+      Alert.alert("Error", error.message);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <Button
+      title="Place Order"
+      onPress={handleCheckout}
+      disabled={loading}
+    />
+  );
+}
+```
+
+## Error Handling
+
+```typescript
+import { EcommerceApiError } from "@basedone/core/ecommerce";
+
+try {
+  const products = await client.listProducts();
+} catch (error) {
+  if (error instanceof EcommerceApiError) {
+    console.error("API Error:", error.message);
+    console.error("Status Code:", error.statusCode);
+    
+    if (error.isAuthError) {
+      // Handle authentication error (401/403)
+      console.log("Please log in again");
+      // Redirect to login
+    } else if (error.isNetworkError) {
+      // Handle network error
+      console.log("Check your internet connection");
+      // Show retry button
+    } else if (error.isTimeoutError) {
+      // Handle timeout
+      console.log("Request timed out, please try again");
+      // Show retry button
+    } else if (error.statusCode === 400) {
+      // Handle validation error
+      console.log("Invalid request:", error.data);
+    } else if (error.statusCode === 404) {
+      // Handle not found
+      console.log("Resource not found");
+    } else if (error.statusCode && error.statusCode >= 500) {
+      // Handle server error
+      console.log("Server error, please try again later");
+    }
+  } else {
+    // Handle unexpected error
+    console.error("Unexpected error:", error);
+  }
+}
+
+// Automatic retry is enabled by default
+// Disable it if needed:
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  enableRetry: false,
+});
+
+// Custom retry configuration
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  maxRetries: 5,
+  retryBaseDelay: 2000, // 2 seconds
+});
+```
+
+## Advanced Usage
+
+### Custom Headers
+
+```typescript
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  headers: {
+    "X-Custom-Header": "value",
+    "X-App-Version": "1.0.0",
+  },
+});
+```
+
+### Dynamic Auth Token
+
+```typescript
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+});
+
+// Set token later
+client.setAuthToken("new-token");
+
+// Clear token
+client.clearAuthToken();
+```
+
+### Access Underlying Axios Instance
+
+```typescript
+const axios = client.getAxiosInstance();
+
+// Add custom interceptor
+axios.interceptors.request.use((config) => {
+  console.log("Request:", config.url);
+  return config;
+});
+```
+
+## Best Practices
+
+1. **Reuse client instances** - Create one client per auth context and reuse it
+2. **Handle errors gracefully** - Always wrap API calls in try-catch
+3. **Use TypeScript** - Take advantage of full type safety
+4. **Store auth tokens securely** - Use secure storage (AsyncStorage, Keychain)
+5. **Implement loading states** - Show loading indicators during API calls
+6. **Cache data when appropriate** - Reduce API calls with local caching
+7. **Test error scenarios** - Handle network failures, timeouts, etc.
+8. **Monitor API usage** - Track API calls and performance
+
+## Support
+
+For issues or questions:
+- GitHub Issues: [github.com/basedone/issues](https://github.com/basedone/issues)
+- Documentation: [docs.basedone.com](https://docs.basedone.com)
+- Email: support@basedone.com
+