@basedone/core 0.2.0 → 0.2.2

package/dist/ecommerce.d.ts

@@ -1093,6 +1093,73 @@ interface CustomerSummary {
     /** First order date */
     firstOrderDate?: string;
 }
+/**
+ * Flash sale item entity
+ */
+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
+ */
+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[];
+}
 
 /**
  * Ecommerce API Request Types
@@ -1570,6 +1637,80 @@ interface ListActiveBannersParams {
     /** Filter by merchant ID */
     merchantId?: string;
 }
+/**
+ * List active flash sales params
+ */
+interface ListActiveFlashSalesParams {
+    /** Maximum number of flash sales to return */
+    limit?: number;
+    /** Filter by merchant ID */
+    merchantId?: string;
+}
+/**
+ * Flash sale item input
+ */
+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
+ */
+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
+ */
+interface UpdateFlashSaleRequest extends Partial<CreateFlashSaleRequest> {
+}
+/**
+ * List merchant products params
+ */
+interface ListMerchantProductsParams extends PaginationParams {
+    /** Search query */
+    search?: string;
+    /** Filter by category slug */
+    category?: string;
+    /** Minimum price */
+    minPrice?: number;
+    /** Maximum price */
+    maxPrice?: number;
+    /** Sort by: popular, latest, top_sales, price_asc, price_desc, rating */
+    sortBy?: "popular" | "latest" | "top_sales" | "price_asc" | "price_desc" | "rating";
+}
+/**
+ * List followed merchants params
+ */
+interface ListFollowingParams extends PaginationParams {
+    /** Sort by: recent (default) or name */
+    sortBy?: "recent" | "name";
+}
 
 /**
  * Ecommerce API Response Types
@@ -1868,6 +2009,96 @@ interface MerchantProfileResponse {
     /** Merchant */
     merchant: Merchant;
 }
+/**
+ * Public merchant profile (for storefront)
+ */
+interface PublicMerchantProfile {
+    /** Merchant ID */
+    id: string;
+    /** Merchant name */
+    name: string;
+    /** Description */
+    description: string | null;
+    /** Created at */
+    createdAt: string;
+    /** Number of active products */
+    productCount: number;
+    /** Total orders */
+    orderCount: number;
+    /** Average rating */
+    averageRating: number | null;
+    /** Total sold count */
+    totalSold: number;
+    /** Total view count */
+    totalViews: number;
+    /** Review count */
+    reviewCount: number;
+    /** Follower count */
+    followerCount: number;
+    /** Categories the merchant sells in */
+    categories: string[];
+}
+/**
+ * Public merchant profile response
+ */
+interface PublicMerchantProfileResponse {
+    /** Merchant */
+    merchant: PublicMerchantProfile;
+}
+/**
+ * Merchant products response
+ */
+interface MerchantProductsResponse extends PaginatedResponse<Product> {
+    /** Merchant info */
+    merchant: {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * Follow status response
+ */
+interface FollowStatusResponse {
+    /** Whether the user is following */
+    isFollowing: boolean;
+    /** When the user followed (null if not following) */
+    followedAt: string | null;
+}
+/**
+ * Follow action response
+ */
+interface FollowActionResponse {
+    /** Success flag */
+    success: boolean;
+    /** Human-readable message */
+    message: string;
+    /** Whether the user is now following */
+    isFollowing: boolean;
+    /** When the user followed (only for follow action) */
+    followedAt?: string;
+}
+/**
+ * Followed merchant summary
+ */
+interface FollowedMerchantSummary {
+    /** When the user followed */
+    followedAt: string;
+    /** Merchant info */
+    merchant: {
+        id: string;
+        name: string;
+        description: string | null;
+        createdAt: string;
+        productCount: number;
+        averageRating: number | null;
+        totalSold: number;
+    };
+}
+/**
+ * List followed merchants response
+ */
+interface ListFollowingResponse extends PaginatedResponse<FollowedMerchantSummary> {
+}
 /**
  * List coupons response
  */
@@ -2019,6 +2250,38 @@ interface MessageResponse {
     /** Message */
     message: Message;
 }
+/**
+ * Customer messages response (for retail users)
+ *
+ * Groups messages by order, where each order represents a conversation with a merchant.
+ */
+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)
+ */
+interface MessageStatsResponse {
+    /** Unread message count */
+    unread: number;
+}
 /**
  * Analytics overview
  */
@@ -2297,6 +2560,22 @@ interface CreateOrderEventResponse {
     /** Event */
     event: any;
 }
+/**
+ * Active flash sales response
+ */
+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;
+}
 
 /**
  * Customer/End-User Ecommerce API Client
@@ -2675,6 +2954,187 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      * ```
      */
     trackBanner(bannerId: string, request: TrackBannerRequest): Promise<SuccessResponse>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    listMessages(): Promise<CustomerMessagesResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getMessageStats(): Promise<MessageStatsResponse>;
+    /**
+     * 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?"
+     * });
+     * ```
+     */
+    sendMessage(request: SendMessageRequest): Promise<MessageResponse>;
+    /**
+     * Mark a message as read
+     *
+     * @param messageId - Message ID
+     * @returns Updated message
+     *
+     * @example
+     * ```typescript
+     * await client.markMessageAsRead("msg_123");
+     * ```
+     */
+    markMessageAsRead(messageId: string): Promise<MessageResponse>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getMerchantProfile(merchantId: string): Promise<PublicMerchantProfileResponse>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    getMerchantProducts(merchantId: string, params?: ListMerchantProductsParams): Promise<MerchantProductsResponse>;
+    /**
+     * 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}`);
+     * }
+     * ```
+     */
+    isFollowingMerchant(merchantId: string): Promise<FollowStatusResponse>;
+    /**
+     * 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"
+     * ```
+     */
+    followMerchant(merchantId: string): Promise<FollowActionResponse>;
+    /**
+     * 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"
+     * ```
+     */
+    unfollowMerchant(merchantId: string): Promise<FollowActionResponse>;
+    /**
+     * 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}`);
+     * });
+     * ```
+     */
+    getFollowedMerchants(params?: ListFollowingParams): Promise<ListFollowingResponse>;
 }
 
 /**
@@ -3729,4 +4189,4 @@ declare function calculateDiscountAmount(price: number, discountType: "PERCENTAG
  */
 declare function calculateFinalPrice(price: number, discountType: "PERCENTAGE" | "FIXED_AMOUNT", discountValue: number): number;
 
-export { type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerSummary, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetCouponResponse, type GetOrderResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProfileRequest, type MerchantProfileResponse, MerchantStatus, type Message, type MessageResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, PaymentStatus, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };
+export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type FlashSale, type FlashSaleItem, type FlashSaleItemInput, type FollowActionResponse, type FollowStatusResponse, type FollowedMerchantSummary, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetCouponResponse, type GetOrderResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListFollowingParams, type ListFollowingResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMerchantProductsParams, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, PaymentStatus, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type PublicMerchantProfile, type PublicMerchantProfileResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };