@basedone/core 0.2.0 → 0.2.2

package/lib/ecommerce/FLASH_SALES.md

@@ -0,0 +1,340 @@
+# Flash Sales SDK Documentation
+
+This guide shows you how to use the `@basedone/core/ecommerce` SDK to fetch and display active flash sales.
+
+## Overview
+
+Flash sales are time-limited deals with discounted products. The SDK provides a simple method to fetch all currently active flash sales with their products, pricing, and countdown information.
+
+## Installation
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+```
+
+## Basic Usage
+
+### Initialize the Client
+
+```typescript
+const client = new CustomerEcommerceClient({
+  baseURL: "https://your-api-domain.com",
+  authToken: "your-auth-token", // Optional for public endpoints
+});
+```
+
+### Fetch Active Flash Sales
+
+```typescript
+// Get all active flash sales
+const result = await client.getActiveFlashSales();
+
+console.log(`Found ${result.flashSales.length} active flash sales`);
+
+// Access the first flash sale
+const featuredSale = result.flashSales[0];
+console.log(`Sale: ${featuredSale.name}`);
+console.log(`Ends at: ${featuredSale.endsAt}`);
+
+// Access countdown timer info
+if (result.timeRemaining) {
+  console.log(`Time remaining: ${result.timeRemaining.remainingSeconds} seconds`);
+}
+```
+
+### With Parameters
+
+```typescript
+// Limit the number of flash sales returned
+const result = await client.getActiveFlashSales({
+  limit: 5, // Maximum 50
+});
+
+// Filter by merchant (optional)
+const result = await client.getActiveFlashSales({
+  limit: 10,
+  merchantId: "merchant_123",
+});
+```
+
+## Response Structure
+
+### ActiveFlashSalesResponse
+
+```typescript
+{
+  flashSales: FlashSale[];        // Array of active flash sales
+  timeRemaining: {                 // Countdown info for featured sale
+    endsAt: string;                // ISO timestamp
+    remainingSeconds: number;       // Seconds until end
+  } | null;
+  serverTime: string;              // Server timestamp for sync
+}
+```
+
+### FlashSale
+
+```typescript
+{
+  id: string;                      // Flash sale ID
+  name: string;                    // Sale name (e.g., "Summer Flash Sale")
+  description?: string;            // Optional description
+  startsAt: string;                // ISO timestamp
+  endsAt: string;                  // ISO timestamp
+  badgeText?: string;              // Badge text (e.g., "Mall")
+  badgeColor?: string;            // Badge color hex (e.g., "#facc15")
+  priority: number;               // Display priority (higher = first)
+  merchant?: {                     // Merchant info (null for admin sales)
+    id: string;
+    name: string;
+  } | null;
+  items: FlashSaleItem[];         // Products in this sale
+}
+```
+
+### FlashSaleItem
+
+```typescript
+{
+  id: string;                      // Item ID
+  productId: string;               // Product ID
+  salePrice: string;               // Sale price in USDC (e.g., "17.90")
+  originalPrice: string;          // Original price in USDC (e.g., "30.00")
+  discountPercent: number;         // Discount percentage (e.g., 42)
+  maxQuantity: number | null;      // Max available (null = unlimited)
+  soldQuantity: number;             // Already sold count
+  remainingQuantity: number | null; // Remaining (null if unlimited)
+  limitPerCustomer: number | null;  // Max per customer
+  product: {                       // Full product details
+    id: string;
+    title: string;
+    description?: string;
+    images: string[];
+    priceUSDC: string;
+    inventory: number | null;
+    soldCount: number;
+    averageRating: number | null;
+    reviewCount: number;
+    merchant?: {
+      id: string;
+      name: string;
+    };
+  };
+}
+```
+
+## Example: Display Flash Sales
+
+```typescript
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+
+const client = new CustomerEcommerceClient({
+  baseURL: "https://api.example.com",
+});
+
+async function displayFlashSales() {
+  try {
+    const result = await client.getActiveFlashSales({ limit: 10 });
+
+    if (result.flashSales.length === 0) {
+      console.log("No active flash sales");
+      return;
+    }
+
+    // Display each flash sale
+    result.flashSales.forEach((sale) => {
+      console.log(`\n⚡ ${sale.name}`);
+      console.log(`   Badge: ${sale.badgeText || "Flash Deal"}`);
+      console.log(`   Ends: ${new Date(sale.endsAt).toLocaleString()}`);
+      console.log(`   Products: ${sale.items.length}`);
+
+      // Display products
+      sale.items.forEach((item) => {
+        console.log(`   - ${item.product.title}`);
+        console.log(`     Original: $${item.originalPrice} → Sale: $${item.salePrice}`);
+        console.log(`     Discount: ${item.discountPercent}% off`);
+        
+        if (item.remainingQuantity !== null) {
+          console.log(`     Only ${item.remainingQuantity} left!`);
+        }
+      });
+    });
+
+    // Display countdown
+    if (result.timeRemaining) {
+      const hours = Math.floor(result.timeRemaining.remainingSeconds / 3600);
+      const minutes = Math.floor((result.timeRemaining.remainingSeconds % 3600) / 60);
+      const seconds = result.timeRemaining.remainingSeconds % 60;
+      console.log(`\n⏰ Time remaining: ${hours}h ${minutes}m ${seconds}s`);
+    }
+  } catch (error) {
+    console.error("Error fetching flash sales:", error);
+  }
+}
+
+displayFlashSales();
+```
+
+## Example: React Component
+
+```typescript
+import { useState, useEffect } from "react";
+import { CustomerEcommerceClient, ActiveFlashSalesResponse } from "@basedone/core/ecommerce";
+
+function FlashSalesList() {
+  const [flashSales, setFlashSales] = useState<ActiveFlashSalesResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    const client = new CustomerEcommerceClient({
+      baseURL: process.env.NEXT_PUBLIC_API_URL || "",
+    });
+
+    client
+      .getActiveFlashSales({ limit: 10 })
+      .then((data) => {
+        setFlashSales(data);
+        setLoading(false);
+      })
+      .catch((error) => {
+        console.error("Failed to load flash sales:", error);
+        setLoading(false);
+      });
+  }, []);
+
+  if (loading) return <div>Loading flash sales...</div>;
+  if (!flashSales || flashSales.flashSales.length === 0) {
+    return <div>No active flash sales</div>;
+  }
+
+  return (
+    <div>
+      {flashSales.flashSales.map((sale) => (
+        <div key={sale.id} className="flash-sale-card">
+          <h2>{sale.name}</h2>
+          {sale.badgeText && (
+            <span style={{ backgroundColor: sale.badgeColor || "#f97316" }}>
+              {sale.badgeText}
+            </span>
+          )}
+          <p>Ends: {new Date(sale.endsAt).toLocaleString()}</p>
+          
+          <div className="products">
+            {sale.items.map((item) => (
+              <div key={item.id} className="product-card">
+                <img src={item.product.images[0]} alt={item.product.title} />
+                <h3>{item.product.title}</h3>
+                <div className="pricing">
+                  <span className="original-price">${item.originalPrice}</span>
+                  <span className="sale-price">${item.salePrice}</span>
+                  <span className="discount">-{item.discountPercent}%</span>
+                </div>
+                {item.remainingQuantity !== null && item.remainingQuantity <= 10 && (
+                  <div className="scarcity">Only {item.remainingQuantity} left!</div>
+                )}
+              </div>
+            ))}
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Example: Countdown Timer
+
+```typescript
+import { useState, useEffect } from "react";
+import { CustomerEcommerceClient } from "@basedone/core/ecommerce";
+
+function CountdownTimer() {
+  const [timeLeft, setTimeLeft] = useState({ hours: 0, minutes: 0, seconds: 0 });
+  const [serverTime, setServerTime] = useState<Date | null>(null);
+
+  useEffect(() => {
+    const client = new CustomerEcommerceClient({
+      baseURL: process.env.NEXT_PUBLIC_API_URL || "",
+    });
+
+    // Fetch flash sales and sync with server time
+    client.getActiveFlashSales().then((result) => {
+      if (result.timeRemaining) {
+        const serverTimeDate = new Date(result.serverTime);
+        setServerTime(serverTimeDate);
+        
+        // Calculate offset for accurate countdown
+        const offset = serverTimeDate.getTime() - Date.now();
+        const endTime = new Date(result.timeRemaining.endsAt).getTime();
+
+        const updateTimer = () => {
+          const now = Date.now() + offset;
+          const remaining = Math.max(0, endTime - now);
+          
+          setTimeLeft({
+            hours: Math.floor(remaining / (1000 * 60 * 60)),
+            minutes: Math.floor((remaining % (1000 * 60 * 60)) / (1000 * 60)),
+            seconds: Math.floor((remaining % (1000 * 60)) / 1000),
+          });
+        };
+
+        updateTimer();
+        const interval = setInterval(updateTimer, 1000);
+        return () => clearInterval(interval);
+      }
+    });
+  }, []);
+
+  return (
+    <div className="countdown">
+      {timeLeft.hours.toString().padStart(2, "0")}:
+      {timeLeft.minutes.toString().padStart(2, "0")}:
+      {timeLeft.seconds.toString().padStart(2, "0")}
+    </div>
+  );
+}
+```
+
+## Error Handling
+
+```typescript
+try {
+  const result = await client.getActiveFlashSales();
+  // Use result...
+} catch (error) {
+  if (error instanceof EcommerceApiError) {
+    console.error("API Error:", error.message);
+    console.error("Status:", error.status);
+  } else {
+    console.error("Unexpected error:", error);
+  }
+}
+```
+
+## Notes
+
+- Flash sales are automatically filtered to only show active sales (between `startsAt` and `endsAt`)
+- The `timeRemaining` field provides countdown info for the featured/first flash sale
+- Use `serverTime` to sync client-side countdown timers accurately
+- Products in flash sales are automatically filtered to only include active products
+- Discount percentages are pre-calculated for convenience
+- The endpoint caches responses for 30 seconds due to time-sensitive nature
+
+## API Endpoint
+
+The SDK method calls:
+```
+GET /api/marketplace/flash-sales/active?limit={limit}&merchantId={merchantId}
+```
+
+## Related Types
+
+```typescript
+import type {
+  ActiveFlashSalesResponse,
+  FlashSale,
+  FlashSaleItem,
+  ListActiveFlashSalesParams,
+} from "@basedone/core/ecommerce";
+```
+

package/lib/ecommerce/QUICK_REFERENCE.md

@@ -57,6 +57,16 @@ await client.createReview("prod_123", {
   comment: "Love it!",
 });
 
+// Shop Following
+const followStatus = await client.isFollowingMerchant("merchant_123");
+await client.followMerchant("merchant_123");
+await client.unfollowMerchant("merchant_123");
+const following = await client.getFollowedMerchants({ limit: 20 });
+
+// Merchant Profile & Products (public)
+const merchant = await client.getMerchantProfile("merchant_123");
+const products = await client.getMerchantProducts("merchant_123", { sortBy: "popular" });
+
 // Calculate discounts
 const discounts = await client.calculateCartDiscounts({
   items: [{ productId: "prod_123", quantity: 2 }],
@@ -67,6 +77,17 @@ const tax = await client.calculateTax({
   items: [{ productId: "prod_123", quantity: 2 }],
   shippingAddress: { country: "US", region: "NY" },
 });
+
+// Get merchant storefront profile
+const merchant = await client.getMerchantProfile("merchant_123");
+console.log(merchant.merchant.name, merchant.merchant.productCount);
+
+// List merchant products with search/sort
+const merchantProducts = await client.getMerchantProducts("merchant_123", {
+  search: "laptop",
+  sortBy: "popular",
+  limit: 20,
+});
 ```
 
 ## Merchant Client
@@ -200,6 +221,11 @@ import type {
   PaymentMethod,
   CreateOrderRequest,
   ListProductsParams,
+  // Merchant storefront types
+  PublicMerchantProfile,
+  PublicMerchantProfileResponse,
+  MerchantProductsResponse,
+  ListMerchantProductsParams,
 } from "@basedone/core/ecommerce";
 ```
 

package/lib/ecommerce/README.md

@@ -68,6 +68,17 @@ if (order.escrow) {
   // After depositing, confirm the transaction
   await client.confirmEscrowDeposit(order.orders[0].id);
 }
+
+// Browse a merchant's storefront
+const merchantProfile = await client.getMerchantProfile("merchant_123");
+console.log(`${merchantProfile.merchant.name} - ${merchantProfile.merchant.productCount} products`);
+
+// Get merchant products with search and sort
+const merchantProducts = await client.getMerchantProducts("merchant_123", {
+  search: "laptop",
+  sortBy: "popular", // popular, latest, top_sales, price_asc, price_desc, rating
+  limit: 20,
+});
 ```
 
 ### Merchant Client
@@ -142,6 +153,16 @@ await client.updateOrderStatus("ord_123", {
 - `getActiveBanners(params?)` - Get active promotional banners
 - `trackBanner(bannerId, request)` - Track banner impression/click
 
+#### Merchant Storefront (Public)
+- `getMerchantProfile(merchantId)` - Get public merchant profile
+- `getMerchantProducts(merchantId, params?)` - Get merchant's products with filtering
+
+#### Shop Following
+- `isFollowingMerchant(merchantId)` - Check if following a merchant
+- `followMerchant(merchantId)` - Follow a merchant
+- `unfollowMerchant(merchantId)` - Unfollow a merchant
+- `getFollowedMerchants(params?)` - Get list of followed merchants
+
 ### Merchant APIs
 
 #### Profile
@@ -319,6 +340,11 @@ import type {
   PaymentMethod,
   CreateOrderRequest,
   ListProductsParams,
+  // Merchant storefront types
+  PublicMerchantProfile,
+  PublicMerchantProfileResponse,
+  MerchantProductsResponse,
+  ListMerchantProductsParams,
   // ... and many more
 } from "@basedone/core/ecommerce";
 ```
@@ -375,6 +401,12 @@ const client = new CustomerEcommerceClient({
 });
 ```
 
+## Additional Documentation
+
+- **[Flash Sales Guide](./FLASH_SALES.md)** - Complete guide for fetching and displaying flash sales
+- **[Usage Examples](./USAGE_EXAMPLES.md)** - More detailed code examples
+- **[Quick Reference](./QUICK_REFERENCE.md)** - API method quick reference
+
 ## Support
 
 For issues or questions, please open an issue on GitHub or contact support.

package/lib/ecommerce/client/customer.ts

@@ -20,6 +20,10 @@ import type {
   CalculateTaxRequest,
   ListActiveBannersParams,
   TrackBannerRequest,
+  SendMessageRequest,
+  ListActiveFlashSalesParams,
+  ListMerchantProductsParams,
+  ListFollowingParams,
   
   // Response types
   ListProductsResponse,
@@ -39,6 +43,15 @@ import type {
   ListBannersResponse,
   SuccessResponse,
   ProductDiscountsResponse,
+  CustomerMessagesResponse,
+  MessageStatsResponse,
+  MessageResponse,
+  ActiveFlashSalesResponse,
+  PublicMerchantProfileResponse,
+  MerchantProductsResponse,
+  FollowStatusResponse,
+  FollowActionResponse,
+  ListFollowingResponse,
 } from "../types";
 
 /**
@@ -518,5 +531,241 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async trackBanner(bannerId: string, request: TrackBannerRequest): Promise<SuccessResponse> {
     return this.post(`/api/marketplace/banners/${bannerId}/track`, request);
   }
+  
+  // ============================================================================
+  // Messages API
+  // ============================================================================
+  
+  /**
+   * List messages for customer
+   * 
+   * Returns all conversations grouped by order, where each order represents
+   * a conversation with a merchant.
+   * 
+   * @returns List of conversations with messages and stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.listMessages();
+   * console.log("Unread:", result.stats.unread);
+   * result.conversations.forEach(conv => {
+   *   console.log(`Order ${conv.orderNumber}: ${conv.unreadCount} unread`);
+   * });
+   * ```
+   */
+  async listMessages(): Promise<CustomerMessagesResponse> {
+    return this.get("/api/marketplace/messages");
+  }
+  
+  /**
+   * Get message stats (unread count)
+   * 
+   * Lightweight endpoint for notification badges.
+   * 
+   * @returns Unread message count
+   * 
+   * @example
+   * ```typescript
+   * const stats = await client.getMessageStats();
+   * console.log("Unread messages:", stats.unread);
+   * ```
+   */
+  async getMessageStats(): Promise<MessageStatsResponse> {
+    return this.get("/api/marketplace/messages/stats");
+  }
+  
+  /**
+   * Send a message to a merchant about an order
+   * 
+   * @param request - Message data including orderId, recipientId (merchant user ID), and message
+   * @returns Sent message
+   * 
+   * @example
+   * ```typescript
+   * await client.sendMessage({
+   *   orderId: "ord_123",
+   *   recipientId: "user_merchant_456",
+   *   message: "When will my order ship?"
+   * });
+   * ```
+   */
+  async sendMessage(request: SendMessageRequest): Promise<MessageResponse> {
+    return this.post("/api/marketplace/messages/send", request);
+  }
+  
+  /**
+   * Mark a message as read
+   * 
+   * @param messageId - Message ID
+   * @returns Updated message
+   * 
+   * @example
+   * ```typescript
+   * await client.markMessageAsRead("msg_123");
+   * ```
+   */
+  async markMessageAsRead(messageId: string): Promise<MessageResponse> {
+    return this.patch(`/api/marketplace/messages/${messageId}/read`, {});
+  }
+  
+  // ============================================================================
+  // Flash Sales API
+  // ============================================================================
+  
+  /**
+   * Get active flash sales
+   * 
+   * Returns currently running flash sales with their discounted products.
+   * Includes countdown timer information for UI display.
+   * 
+   * @param params - Query parameters
+   * @returns List of active flash sales with time remaining
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getActiveFlashSales({ limit: 5 });
+   * 
+   * result.flashSales.forEach(sale => {
+   *   console.log(`${sale.name} - ends at ${sale.endsAt}`);
+   *   sale.items.forEach(item => {
+   *     console.log(`  ${item.product.title}: $${item.salePrice} (${item.discountPercent}% off)`);
+   *   });
+   * });
+   * 
+   * // Use timeRemaining for countdown UI
+   * if (result.timeRemaining) {
+   *   console.log(`Featured sale ends in ${result.timeRemaining.remainingSeconds} seconds`);
+   * }
+   * ```
+   */
+  async getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/flash-sales/active${queryString}`);
+  }
+  
+  // ============================================================================
+  // Merchant Storefront API
+  // ============================================================================
+  
+  /**
+   * Get public merchant profile
+   * 
+   * Fetches public information about a merchant for the storefront page.
+   * 
+   * @param merchantId - Merchant ID
+   * @returns Public merchant profile with stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getMerchantProfile("merchant_123");
+   * console.log(result.merchant.name, result.merchant.productCount);
+   * ```
+   */
+  async getMerchantProfile(merchantId: string): Promise<PublicMerchantProfileResponse> {
+    return this.get(`/api/marketplace/merchants/${merchantId}`);
+  }
+  
+  /**
+   * List merchant products
+   * 
+   * Fetches products for a specific merchant with search, filter, and sort options.
+   * 
+   * @param merchantId - Merchant ID
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated list of products
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getMerchantProducts("merchant_123", {
+   *   search: "laptop",
+   *   sortBy: "popular",
+   *   limit: 20,
+   * });
+   * 
+   * result.items.forEach(product => {
+   *   console.log(product.title, product.priceUSDC);
+   * });
+   * ```
+   */
+  async getMerchantProducts(
+    merchantId: string,
+    params?: ListMerchantProductsParams
+  ): Promise<MerchantProductsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchants/${merchantId}/products${queryString}`);
+  }
+  
+  // ============================================================================
+  // Shop Following API
+  // ============================================================================
+  
+  /**
+   * Check if following a merchant
+   * 
+   * @param merchantId - Merchant ID
+   * @returns Follow status with follow date if applicable
+   * 
+   * @example
+   * ```typescript
+   * const status = await client.isFollowingMerchant("merchant_123");
+   * if (status.isFollowing) {
+   *   console.log(`Following since ${status.followedAt}`);
+   * }
+   * ```
+   */
+  async isFollowingMerchant(merchantId: string): Promise<FollowStatusResponse> {
+    return this.get(`/api/marketplace/merchants/${merchantId}/follow`);
+  }
+  
+  /**
+   * Follow a merchant
+   * 
+   * @param merchantId - Merchant ID to follow
+   * @returns Follow action result
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.followMerchant("merchant_123");
+   * console.log(result.message); // "Now following Awesome Store"
+   * ```
+   */
+  async followMerchant(merchantId: string): Promise<FollowActionResponse> {
+    return this.post(`/api/marketplace/merchants/${merchantId}/follow`);
+  }
+  
+  /**
+   * Unfollow a merchant
+   * 
+   * @param merchantId - Merchant ID to unfollow
+   * @returns Unfollow action result
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.unfollowMerchant("merchant_123");
+   * console.log(result.message); // "Unfollowed successfully"
+   * ```
+   */
+  async unfollowMerchant(merchantId: string): Promise<FollowActionResponse> {
+    return this.delete(`/api/marketplace/merchants/${merchantId}/follow`);
+  }
+  
+  /**
+   * Get list of followed merchants
+   * 
+   * @param params - Query parameters for pagination and sorting
+   * @returns Paginated list of followed merchants with their info
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getFollowedMerchants({ limit: 20, sortBy: "recent" });
+   * result.items.forEach(item => {
+   *   console.log(`${item.merchant.name} - followed on ${item.followedAt}`);
+   * });
+   * ```
+   */
+  async getFollowedMerchants(params?: ListFollowingParams): Promise<ListFollowingResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/following${queryString}`);
+  }
 }