@basedone/core 0.2.0 → 0.2.1

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/README.md

@@ -375,6 +375,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,8 @@ import type {
   CalculateTaxRequest,
   ListActiveBannersParams,
   TrackBannerRequest,
+  SendMessageRequest,
+  ListActiveFlashSalesParams,
   
   // Response types
   ListProductsResponse,
@@ -39,6 +41,10 @@ import type {
   ListBannersResponse,
   SuccessResponse,
   ProductDiscountsResponse,
+  CustomerMessagesResponse,
+  MessageStatsResponse,
+  MessageResponse,
+  ActiveFlashSalesResponse,
 } from "../types";
 
 /**
@@ -518,5 +524,116 @@ 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}`);
+  }
 }
 

package/lib/ecommerce/types/entities.ts

@@ -720,3 +720,72 @@ export interface CustomerSummary {
   firstOrderDate?: string;
 }
 
+/**
+ * Flash sale item entity
+ */
+export interface FlashSaleItem {
+  /** Item ID */
+  id: string;
+  /** Product ID */
+  productId: string;
+  /** Sale price in USDC */
+  salePrice: string;
+  /** Original price in USDC */
+  originalPrice: string;
+  /** Discount percentage */
+  discountPercent: number;
+  /** Maximum quantity available at this price */
+  maxQuantity: number | null;
+  /** Quantity sold at flash price */
+  soldQuantity: number;
+  /** Remaining quantity */
+  remainingQuantity: number | null;
+  /** Limit per customer */
+  limitPerCustomer: number | null;
+  /** Product details */
+  product: {
+    id: string;
+    title: string;
+    description?: string | null;
+    images: string[];
+    priceUSDC: string;
+    inventory: number | null;
+    soldCount: number;
+    averageRating: number | null;
+    reviewCount: number;
+    merchant?: {
+      id: string;
+      name: string;
+    };
+  };
+}
+
+/**
+ * Flash sale entity
+ */
+export interface FlashSale {
+  /** Flash sale ID */
+  id: string;
+  /** Sale name */
+  name: string;
+  /** Description */
+  description?: string | null;
+  /** Start timestamp */
+  startsAt: string;
+  /** End timestamp */
+  endsAt: string;
+  /** Badge text (e.g., "Mall", "Hot Deal") */
+  badgeText?: string | null;
+  /** Badge color (hex) */
+  badgeColor?: string | null;
+  /** Priority (higher = shown first) */
+  priority: number;
+  /** Merchant information */
+  merchant?: {
+    id: string;
+    name: string;
+  } | null;
+  /** Flash sale items */
+  items: FlashSaleItem[];
+}
+

package/lib/ecommerce/types/requests.ts

@@ -523,3 +523,58 @@ export interface ListActiveBannersParams {
   merchantId?: string;
 }
 
+/**
+ * List active flash sales params
+ */
+export interface ListActiveFlashSalesParams {
+  /** Maximum number of flash sales to return */
+  limit?: number;
+  /** Filter by merchant ID */
+  merchantId?: string;
+}
+
+/**
+ * Flash sale item input
+ */
+export interface FlashSaleItemInput {
+  /** Product ID */
+  productId: string;
+  /** Sale price in USDC */
+  salePrice: number;
+  /** Maximum quantity available */
+  maxQuantity?: number | null;
+  /** Limit per customer */
+  limitPerCustomer?: number;
+  /** Sort order */
+  sortOrder?: number;
+}
+
+/**
+ * Create flash sale request
+ */
+export interface CreateFlashSaleRequest {
+  /** Sale name */
+  name: string;
+  /** Description */
+  description?: string | null;
+  /** Start timestamp */
+  startsAt: string;
+  /** End timestamp */
+  endsAt: string;
+  /** Badge text */
+  badgeText?: string;
+  /** Badge color (hex) */
+  badgeColor?: string;
+  /** Priority (higher = shown first) */
+  priority?: number;
+  /** Is active */
+  isActive?: boolean;
+  /** Flash sale items */
+  items?: FlashSaleItemInput[];
+}
+
+/**
+ * Update flash sale request
+ */
+export interface UpdateFlashSaleRequest extends Partial<CreateFlashSaleRequest> {}
+

package/lib/ecommerce/types/responses.ts

@@ -25,6 +25,7 @@ import {
   CustomerSummary,
   ProductVariant,
   CouponUsage,
+  FlashSale,
 } from "./entities";
 
 /**
@@ -504,6 +505,40 @@ export interface MessageResponse {
   message: Message;
 }
 
+/**
+ * Customer messages response (for retail users)
+ * 
+ * Groups messages by order, where each order represents a conversation with a merchant.
+ */
+export interface CustomerMessagesResponse {
+  /** Conversations grouped by order */
+  conversations: Array<{
+    orderId: string;
+    orderNumber: string;
+    merchant: {
+      id: string;
+      name: string;
+      ownerUserId: string;
+    };
+    lastMessage: Message;
+    unreadCount: number;
+    messages: Message[];
+  }>;
+  /** Stats */
+  stats: {
+    total: number;
+    unread: number;
+  };
+}
+
+/**
+ * Message stats response (for notification badges)
+ */
+export interface MessageStatsResponse {
+  /** Unread message count */
+  unread: number;
+}
+
 /**
  * Analytics overview
  */
@@ -803,3 +838,20 @@ export interface CreateOrderEventResponse {
   event: any;
 }
 
+/**
+ * Active flash sales response
+ */
+export interface ActiveFlashSalesResponse {
+  /** Flash sales */
+  flashSales: FlashSale[];
+  /** Time remaining for the featured/first sale */
+  timeRemaining: {
+    /** End timestamp */
+    endsAt: string;
+    /** Remaining seconds */
+    remainingSeconds: number;
+  } | null;
+  /** Server time (for client-side sync) */
+  serverTime: string;
+}
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",