@basedone/core 0.1.10 → 0.2.0

package/lib/ecommerce/README.md

@@ -0,0 +1,385 @@
+# Ecommerce SDK
+
+A comprehensive TypeScript SDK for the Based One marketplace/ecommerce API, designed for use in mobile apps (React Native) and web applications.
+
+## Features
+
+- ✅ **Full TypeScript support** with extensive type definitions
+- ✅ **Customer & Merchant APIs** - Complete coverage of all endpoints
+- ✅ **Authentication** - Built-in Bearer token authentication
+- ✅ **Error handling** - Comprehensive error types and retry logic
+- ✅ **Automatic retries** - Exponential backoff for failed requests
+- ✅ **JSDoc documentation** - IntelliSense support in your IDE
+- ✅ **Mobile-friendly** - Works with React Native and Expo
+- ✅ **Multi-merchant support** - Automatic order splitting for multi-merchant carts
+
+## Installation
+
+```bash
+npm install @basedone/core
+# or
+pnpm add @basedone/core
+# or
+yarn add @basedone/core
+```
+
+## Quick Start
+
+### Customer/End-User Client
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  authToken: "your-user-auth-token",
+  timeout: 30000,
+  maxRetries: 3,
+});
+
+// Browse products
+const products = await client.listProducts({
+  limit: 20,
+  category: "electronics",
+  sortBy: "price_asc",
+});
+
+// Place an order
+const order = await client.createOrder({
+  items: [
+    { productId: "prod_123", quantity: 2 },
+    { productId: "prod_456", quantity: 1 },
+  ],
+  paymentMethod: "USDC_ESCROW",
+  shippingAddress: {
+    fullName: "John Doe",
+    phone: "+1234567890",
+    addressLine1: "123 Main St",
+    city: "New York",
+    stateProvince: "NY",
+    postalCode: "10001",
+    country: "US",
+  },
+});
+
+// For USDC escrow payment
+if (order.escrow) {
+  console.log(`Deposit ${order.escrow.amountUSDC} USDC to ${order.escrow.address}`);
+  // After depositing, confirm the transaction
+  await client.confirmEscrowDeposit(order.orders[0].id);
+}
+```
+
+### Merchant Client
+
+```typescript
+import { MerchantEcommerceClient } from "@basedone/core/ecommerce";
+
+const client = new MerchantEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  authToken: "your-merchant-auth-token",
+});
+
+// Create a product
+const product = await client.createProduct({
+  title: "Awesome Product",
+  images: ["https://..."],
+  priceUSDC: 49.99,
+  inventory: 100,
+  category: "electronics",
+});
+
+// Get analytics
+const analytics = await client.getAnalytics({ range: "30days" });
+console.log("Revenue:", analytics.overview.totalRevenue);
+console.log("Orders:", analytics.overview.totalOrders);
+
+// Fulfill an order
+await client.updateOrderStatus("ord_123", {
+  status: "SHIPPED",
+  tracking: {
+    trackingNumber: "1Z999AA10123456784",
+    carrier: "UPS",
+  },
+});
+```
+
+## API Reference
+
+### Customer APIs
+
+#### Products
+- `listProducts(params?)` - List products with filtering and pagination
+- `getProduct(productId)` - Get product details
+- `trackProductView(productId)` - Track product view
+- `getProductDiscounts(productId)` - Get active discounts for a product
+
+#### Orders
+- `createOrder(request)` - Create order from cart (supports multi-merchant)
+- `listOrders(params?)` - List user's orders
+- `getOrder(orderId)` - Get order details
+- `confirmEscrowDeposit(orderId)` - Confirm USDC escrow payment
+- `getOrderReceipt(orderId)` - Get order receipt
+
+#### Reviews
+- `listProductReviews(productId, params?)` - List product reviews
+- `createReview(productId, request)` - Create a review
+
+#### Shipping Addresses
+- `listShippingAddresses()` - List saved addresses
+- `createShippingAddress(request)` - Add new address
+- `updateShippingAddress(addressId, request)` - Update address
+- `deleteShippingAddress(addressId)` - Delete address
+
+#### Cart & Discounts
+- `calculateCartDiscounts(request)` - Calculate automatic discounts
+- `validateDiscountCode(request)` - Validate coupon code
+
+#### Tax
+- `calculateTax(request)` - Calculate tax for cart
+
+#### Banners
+- `getActiveBanners(params?)` - Get active promotional banners
+- `trackBanner(bannerId, request)` - Track banner impression/click
+
+### Merchant APIs
+
+#### Profile
+- `getMerchantProfile()` - Get merchant profile
+- `upsertMerchantProfile(request)` - Create/update profile
+
+#### Products
+- `listMerchantProducts(params?)` - List merchant's products
+- `createProduct(request)` - Create product
+- `updateProduct(productId, request)` - Update product
+- `deleteProduct(productId)` - Delete product
+- `setProductFeatured(productId, featured)` - Toggle featured status
+- `getProductMetrics()` - Get product performance metrics
+
+#### Product Variants
+- `listProductVariants(productId)` - List variants
+- `createProductVariant(productId, request)` - Create variant
+- `getProductVariant(productId, variantId)` - Get variant
+- `updateProductVariant(productId, variantId, request)` - Update variant
+- `deleteProductVariant(productId, variantId)` - Delete variant
+
+#### Orders
+- `listMerchantOrders(params?)` - List merchant's orders
+- `getMerchantOrder(orderId)` - Get order details
+- `updateOrderStatus(orderId, request)` - Update order status
+- `createOrderEvent(orderId, request)` - Create custom order event
+
+#### Customers
+- `listCustomers(params?)` - List customers with stats
+
+#### Coupons
+- `listCoupons()` - List coupons
+- `createCoupon(request)` - Create coupon
+- `getCoupon(couponId)` - Get coupon with usage history
+- `updateCoupon(couponId, request)` - Update coupon
+- `deleteCoupon(couponId)` - Delete coupon
+
+#### Shipping
+- `listShippingMethods()` - List shipping methods
+- `createShippingMethod(request)` - Create method
+- `updateShippingMethod(methodId, request)` - Update method
+- `deleteShippingMethod(methodId)` - Delete method
+- `listShipments()` - List shipments
+- `updateShipment(shipmentId, request)` - Update shipment
+
+#### Returns
+- `listReturns()` - List returns
+- `approveReturn(returnId)` - Approve return
+- `rejectReturn(returnId)` - Reject return
+- `markReturnReceived(returnId)` - Mark as received
+- `processRefund(returnId)` - Process refund
+
+#### Reviews
+- `listMerchantReviews()` - List reviews
+- `respondToReview(reviewId, request)` - Respond to review
+- `flagReview(reviewId)` - Flag inappropriate review
+
+#### Messages
+- `listMessages()` - List conversations
+- `sendMessage(request)` - Send message to customer
+- `markMessageRead(messageId)` - Mark as read
+
+#### Media
+- `listMediaAssets(params?)` - List media library
+- `uploadMediaAsset(formData)` - Upload image
+- `deleteMediaAsset(assetId)` - Delete asset
+
+#### Banners
+- `listMerchantBanners()` - List banners
+- `createBanner(request)` - Create banner
+- `getBanner(bannerId)` - Get banner
+- `updateBanner(bannerId, request)` - Update banner
+- `deleteBanner(bannerId)` - Delete banner
+
+#### Analytics
+- `getAnalytics(params?)` - Get merchant analytics
+
+#### Inventory
+- `getInventoryAudit()` - Get inventory audit log
+
+#### Tax Management
+- `getTaxSettings()` - Get tax settings
+- `updateTaxSettings(request)` - Update settings
+- `listTaxRules()` - List tax rules
+- `createTaxRule(request)` - Create rule
+- `getTaxRule(ruleId)` - Get rule
+- `updateTaxRule(ruleId, request)` - Update rule
+- `deleteTaxRule(ruleId)` - Delete rule
+- `listTaxNexus()` - List nexus locations
+- `createTaxNexus(request)` - Add nexus
+- `updateTaxNexus(nexusId, request)` - Update nexus
+- `deleteTaxNexus(nexusId)` - Delete nexus
+- `listTaxReports(params?)` - List tax reports
+- `generateTaxReport(request)` - Generate report
+- `getTaxReport(reportId)` - Get report details
+- `updateTaxReportStatus(reportId, request)` - Update status
+- `exportTaxReport(reportId)` - Export as CSV
+
+## Configuration
+
+### Client Options
+
+```typescript
+interface EcommerceClientConfig {
+  /** Base API URL */
+  baseURL: string;
+  
+  /** Authentication token (Bearer token) */
+  authToken?: string;
+  
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  
+  /** Maximum number of retries for failed requests (default: 3) */
+  maxRetries?: number;
+  
+  /** Base delay for exponential backoff in ms (default: 1000) */
+  retryBaseDelay?: number;
+  
+  /** Custom headers */
+  headers?: Record<string, string>;
+  
+  /** Enable automatic retry on retryable errors (default: true) */
+  enableRetry?: boolean;
+}
+```
+
+### Authentication
+
+Update the auth token dynamically:
+
+```typescript
+// Set token
+client.setAuthToken("new-token");
+
+// Clear token
+client.clearAuthToken();
+```
+
+## Error Handling
+
+```typescript
+import { EcommerceApiError } from "@basedone/core/ecommerce";
+
+try {
+  const products = await client.listProducts();
+} catch (error) {
+  if (error instanceof EcommerceApiError) {
+    console.error("Status:", error.statusCode);
+    console.error("Message:", error.message);
+    
+    if (error.isAuthError) {
+      // Handle authentication error (401/403)
+      console.log("Please log in again");
+    } else if (error.isNetworkError) {
+      // Handle network error
+      console.log("Check your internet connection");
+    } else if (error.isTimeoutError) {
+      // Handle timeout
+      console.log("Request timed out");
+    }
+  }
+}
+```
+
+## TypeScript Types
+
+All types are fully documented and exported:
+
+```typescript
+import type {
+  Product,
+  Order,
+  OrderStatus,
+  PaymentMethod,
+  CreateOrderRequest,
+  ListProductsParams,
+  // ... and many more
+} from "@basedone/core/ecommerce";
+```
+
+## React Native / Expo
+
+The SDK works seamlessly with React Native and Expo:
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+import AsyncStorage from "@react-native-async-storage/async-storage";
+
+// Store auth token
+const authToken = await AsyncStorage.getItem("authToken");
+
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  authToken,
+});
+
+// Use in your components
+const [products, setProducts] = useState([]);
+
+useEffect(() => {
+  client.listProducts({ limit: 20 }).then(setProducts);
+}, []);
+```
+
+## Advanced Usage
+
+### Custom Axios Configuration
+
+Access the underlying axios instance for advanced use cases:
+
+```typescript
+const axios = client.getAxiosInstance();
+axios.interceptors.request.use(/* custom interceptor */);
+```
+
+### Retry Logic
+
+The SDK automatically retries failed requests with exponential backoff for:
+- Network errors
+- Timeout errors
+- 5xx server errors
+- 429 rate limit errors
+
+You can disable retry:
+
+```typescript
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.basedone.com",
+  enableRetry: false,
+});
+```
+
+## Support
+
+For issues or questions, please open an issue on GitHub or contact support.
+
+## License
+
+ISC
+