@basedone/core 0.1.10 → 0.2.1

package/lib/ecommerce/types/responses.ts

@@ -0,0 +1,857 @@
+/**
+ * Ecommerce API Response Types
+ * 
+ * This module contains all response types for the ecommerce API.
+ */
+
+import {
+  Product,
+  Order,
+  Merchant,
+  ProductReview,
+  UserShippingAddress,
+  Coupon,
+  ShippingMethod,
+  Shipment,
+  Return,
+  Banner,
+  MediaAsset,
+  Message,
+  TaxSettings,
+  TaxRule,
+  TaxNexus,
+  TaxReport,
+  InventoryAuditEntry,
+  CustomerSummary,
+  ProductVariant,
+  CouponUsage,
+  FlashSale,
+} from "./entities";
+
+/**
+ * Base API response
+ */
+export interface ApiResponse<T = any> {
+  /** Response data */
+  data?: T;
+  /** Error message */
+  error?: string;
+  /** Success flag */
+  success?: boolean;
+}
+
+/**
+ * Paginated response
+ */
+export interface PaginatedResponse<T> {
+  /** Items */
+  items: T[];
+  /** Total count */
+  total: number;
+  /** Limit */
+  limit: number;
+  /** Offset */
+  offset: number;
+}
+
+/**
+ * List products response
+ */
+export interface ListProductsResponse extends PaginatedResponse<Product> {}
+
+/**
+ * Get product response
+ * 
+ * Note: The API returns the product object directly, not wrapped in a `product` field.
+ * This type extends Product to be compatible with the actual API response.
+ */
+export type GetProductResponse = Product;
+
+/**
+ * Create/Update product response
+ */
+export interface ProductResponse {
+  /** Product */
+  product: Product;
+}
+
+/**
+ * List product variants response
+ */
+export interface ListProductVariantsResponse {
+  /** Variants */
+  variants: ProductVariant[];
+}
+
+/**
+ * Product variant response
+ */
+export interface ProductVariantResponse {
+  /** Variant */
+  variant: ProductVariant;
+}
+
+/**
+ * List orders response
+ */
+export interface ListOrdersResponse extends PaginatedResponse<Order> {
+  /** Merchant information (for merchant endpoints) */
+  merchant?: Merchant;
+}
+
+/**
+ * Get order response
+ */
+export interface GetOrderResponse {
+  /** Order */
+  order: Order;
+}
+
+/**
+ * Create order response
+ */
+export interface CreateOrderResponse {
+  /** Created orders (array for multi-merchant checkout) */
+  orders: Order[];
+  /** Summary */
+  summary: {
+    /** Total amount */
+    totalAmount: string;
+    /** Order count */
+    orderCount: number;
+    /** Merchant names */
+    merchantNames: string[];
+  };
+  /** Escrow payment instructions (for USDC_ESCROW) */
+  escrow?: {
+    /** Escrow address */
+    address: string;
+    /** Amount in USDC */
+    amountUSDC: string;
+  };
+  /** Test mode flag */
+  testMode?: boolean;
+}
+
+/**
+ * Update order response
+ */
+export interface UpdateOrderResponse {
+  /** Updated order */
+  order: Order;
+}
+
+/**
+ * Confirm escrow deposit response
+ */
+export interface ConfirmEscrowDepositResponse {
+  /** Success flag */
+  ok: boolean;
+  /** Order ID */
+  orderId: string;
+  /** Order status */
+  status: string;
+  /** Deposit transaction hash */
+  depositTxHash: string | null;
+}
+
+/**
+ * Order receipt response
+ */
+export interface OrderReceiptResponse {
+  /** Receipt */
+  receipt: {
+    /** Order number */
+    orderNumber: string;
+    /** Order ID */
+    orderId: string;
+    /** Order date */
+    orderDate: string;
+    /** Status */
+    status: string;
+    /** Customer */
+    customer: {
+      name: string;
+      email?: string;
+    };
+    /** Merchant */
+    merchant: {
+      name: string;
+    };
+    /** Shipping address */
+    shippingAddress: any;
+    /** Items */
+    items: Array<{
+      title: string;
+      quantity: number;
+      unitPrice: string;
+      totalPrice: string;
+    }>;
+    /** Subtotal */
+    subtotal: string;
+    /** Tax */
+    tax: string;
+    /** Shipping */
+    shipping: string;
+    /** Total */
+    total: string;
+    /** Payment */
+    payment: {
+      method: string;
+      status?: string;
+      transactionHash?: string | null;
+    };
+  };
+}
+
+/**
+ * List reviews response
+ */
+export interface ListReviewsResponse extends PaginatedResponse<ProductReview> {}
+
+/**
+ * Create/Update review response
+ */
+export interface ReviewResponse {
+  /** Review */
+  review: ProductReview;
+}
+
+/**
+ * List shipping addresses response
+ */
+export interface ListShippingAddressesResponse {
+  /** Addresses */
+  addresses: UserShippingAddress[];
+}
+
+/**
+ * Shipping address response
+ */
+export interface ShippingAddressResponse {
+  /** Address */
+  address: UserShippingAddress;
+}
+
+/**
+ * Applied discount
+ */
+export interface AppliedDiscount {
+  /** Coupon/discount ID */
+  id: string;
+  /** Code */
+  code: string;
+  /** Title */
+  title?: string | null;
+  /** Discount type */
+  discountType: string;
+  /** Discount amount */
+  discountAmount: number;
+  /** Description */
+  description?: string;
+}
+
+/**
+ * Calculate cart discounts response
+ */
+export interface CalculateCartDiscountsResponse {
+  /** Subtotal */
+  subtotal: number;
+  /** Discount amount */
+  discountAmount: number;
+  /** Total */
+  total: number;
+  /** Applied discounts */
+  appliedDiscounts: AppliedDiscount[];
+}
+
+/**
+ * Validate discount response
+ */
+export interface ValidateDiscountResponse {
+  /** Is valid */
+  valid: boolean;
+  /** Error message */
+  error?: string;
+  /** Discount */
+  discount?: {
+    /** Coupon ID */
+    id: string;
+    /** Code */
+    code: string;
+    /** Title */
+    title?: string | null;
+    /** Discount type */
+    discountType: string;
+    /** Discount amount */
+    discountAmount: number;
+  };
+  /** Subtotal */
+  subtotal?: number;
+  /** Total */
+  total?: number;
+}
+
+/**
+ * Tax breakdown item
+ */
+export interface TaxBreakdownItem {
+  /** Tax type */
+  taxType: string;
+  /** Tax name */
+  taxName: string;
+  /** Tax rate */
+  taxRate: number;
+  /** Tax amount */
+  taxAmount: number;
+  /** Country */
+  country: string;
+  /** Region */
+  region?: string;
+}
+
+/**
+ * Calculate tax response
+ */
+export interface CalculateTaxResponse {
+  /** Subtotal */
+  subtotal: number;
+  /** Tax amount */
+  taxAmount: number;
+  /** Total */
+  total: number;
+  /** Tax breakdown */
+  breakdown: TaxBreakdownItem[];
+  /** Merchant tax details (for multi-merchant) */
+  merchantTaxDetails?: Array<{
+    merchantId: string;
+    subtotal: number;
+    taxAmount: number;
+    hasNexus: boolean;
+    breakdown: TaxBreakdownItem[];
+  }>;
+}
+
+/**
+ * Merchant profile response
+ */
+export interface MerchantProfileResponse {
+  /** Merchant */
+  merchant: Merchant;
+}
+
+/**
+ * List coupons response
+ */
+export interface ListCouponsResponse {
+  /** Coupons */
+  coupons: Coupon[];
+  /** Stats */
+  stats: {
+    total: number;
+    active: number;
+    totalUsages: number;
+    totalDiscount: number;
+  };
+}
+
+/**
+ * Coupon response
+ */
+export interface CouponResponse {
+  /** Coupon */
+  coupon: Coupon;
+}
+
+/**
+ * Get coupon with usages response
+ */
+export interface GetCouponResponse {
+  /** Coupon with usages */
+  coupon: Coupon & {
+    usages: Array<CouponUsage & {
+      user: {
+        username?: string;
+      };
+    }>;
+  };
+}
+
+/**
+ * List shipping methods response
+ */
+export interface ListShippingMethodsResponse {
+  /** Methods */
+  methods: ShippingMethod[];
+}
+
+/**
+ * Shipping method response
+ */
+export interface ShippingMethodResponse {
+  /** Method */
+  method: ShippingMethod;
+}
+
+/**
+ * List shipments response
+ */
+export interface ListShipmentsResponse {
+  /** Shipments */
+  shipments: Array<Shipment & {
+    order: {
+      id: string;
+      totalUSDC: string;
+      shippingAddress: any;
+      user: {
+        id: string;
+        username?: string;
+      };
+    };
+  }>;
+}
+
+/**
+ * Shipment response
+ */
+export interface ShipmentResponse {
+  /** Shipment */
+  shipment: Shipment;
+}
+
+/**
+ * List returns response
+ */
+export interface ListReturnsResponse {
+  /** Returns */
+  returns: Array<Return & {
+    user: {
+      id: string;
+      username?: string;
+    };
+    order: {
+      id: string;
+      totalUSDC: string;
+    };
+  }>;
+}
+
+/**
+ * Return response
+ */
+export interface ReturnResponse {
+  /** Return */
+  return: Return;
+}
+
+/**
+ * List banners response
+ */
+export interface ListBannersResponse {
+  /** Banners */
+  banners: Banner[];
+}
+
+/**
+ * Banner response
+ */
+export interface BannerResponse {
+  /** Banner */
+  banner: Banner;
+}
+
+/**
+ * List media assets response
+ */
+export interface ListMediaAssetsResponse extends PaginatedResponse<MediaAsset> {}
+
+/**
+ * Media asset response
+ */
+export interface MediaAssetResponse {
+  /** Asset */
+  asset: MediaAsset;
+}
+
+/**
+ * List messages response
+ */
+export interface ListMessagesResponse {
+  /** Conversations */
+  conversations: Array<{
+    orderId: string;
+    orderNumber: string;
+    customer: {
+      id: string;
+      name?: string;
+      username?: string;
+    };
+    lastMessage: Message;
+    unreadCount: number;
+    messages: Message[];
+  }>;
+  /** Stats */
+  stats: {
+    total: number;
+    unread: number;
+  };
+}
+
+/**
+ * Message response
+ */
+export interface MessageResponse {
+  /** Message */
+  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
+ */
+export interface AnalyticsOverview {
+  /** Total revenue */
+  totalRevenue: number;
+  /** Revenue change percentage */
+  revenueChange: number;
+  /** Total orders */
+  totalOrders: number;
+  /** Orders change percentage */
+  ordersChange: number;
+  /** Average order value */
+  averageOrderValue: number;
+  /** AOV change percentage */
+  aovChange: number;
+  /** Total customers */
+  totalCustomers: number;
+  /** Customers change percentage */
+  customersChange: number;
+}
+
+/**
+ * Revenue by day
+ */
+export interface RevenueByDay {
+  /** Date */
+  date: string;
+  /** Revenue */
+  revenue: number;
+  /** Orders */
+  orders: number;
+}
+
+/**
+ * Top product
+ */
+export interface TopProduct {
+  /** Product ID */
+  id: string;
+  /** Name */
+  name: string;
+  /** Image */
+  image: string | null;
+  /** Sold count */
+  soldCount: number;
+  /** Revenue */
+  revenue: number;
+  /** View count */
+  viewCount: number;
+}
+
+/**
+ * Orders by status
+ */
+export interface OrdersByStatus {
+  /** Status */
+  status: string;
+  /** Count */
+  count: number;
+  /** Percentage */
+  percentage: number;
+}
+
+/**
+ * Recent order summary
+ */
+export interface RecentOrderSummary {
+  /** Order ID */
+  id: string;
+  /** Order number */
+  orderNumber: string;
+  /** Total amount */
+  totalAmount: number;
+  /** Status */
+  status: string;
+  /** Created at */
+  createdAt: string;
+  /** Buyer */
+  buyer: {
+    username?: string;
+  };
+}
+
+/**
+ * Get analytics response
+ */
+export interface GetAnalyticsResponse {
+  /** Overview */
+  overview: AnalyticsOverview;
+  /** Revenue by day */
+  revenueByDay: RevenueByDay[];
+  /** Top products */
+  topProducts: TopProduct[];
+  /** Orders by status */
+  ordersByStatus: OrdersByStatus[];
+  /** Recent orders */
+  recentOrders: RecentOrderSummary[];
+}
+
+/**
+ * Product metrics
+ */
+export interface ProductMetrics {
+  /** Product ID */
+  id: string;
+  /** Name */
+  name: string;
+  /** Images */
+  images: string[];
+  /** View count */
+  viewCount: number;
+  /** Sold count */
+  soldCount: number;
+  /** Revenue */
+  revenue: number;
+  /** Average rating */
+  averageRating: number;
+  /** Review count */
+  reviewCount: number;
+  /** Wishlist count */
+  wishlistCount: number;
+  /** Conversion rate */
+  conversionRate: number;
+  /** Stock */
+  stock: number;
+  /** Is active */
+  isActive: boolean;
+  /** Featured */
+  featured: boolean;
+  /** Created at */
+  createdAt: string;
+}
+
+/**
+ * Get product metrics response
+ */
+export interface GetProductMetricsResponse {
+  /** Products */
+  products: ProductMetrics[];
+  /** Summary */
+  summary: {
+    totalProducts: number;
+    totalViews: number;
+    totalSales: number;
+    totalRevenue: number;
+    averageConversion: number;
+  };
+}
+
+/**
+ * List inventory audit response
+ */
+export interface ListInventoryAuditResponse {
+  /** Entries */
+  entries: Array<InventoryAuditEntry & {
+    product: {
+      id: string;
+      title: string;
+      images: string[];
+    };
+    variant?: {
+      id: string;
+      name: string;
+    };
+  }>;
+}
+
+/**
+ * List customers response
+ */
+export interface ListCustomersResponse extends PaginatedResponse<CustomerSummary> {}
+
+/**
+ * Tax settings response
+ */
+export interface TaxSettingsResponse {
+  /** Settings */
+  settings: TaxSettings;
+}
+
+/**
+ * List tax rules response
+ */
+export interface ListTaxRulesResponse {
+  /** Rules */
+  rules: TaxRule[];
+}
+
+/**
+ * Tax rule response
+ */
+export interface TaxRuleResponse {
+  /** Rule */
+  rule: TaxRule;
+}
+
+/**
+ * List tax nexus response
+ */
+export interface ListTaxNexusResponse {
+  /** Nexus */
+  nexus: TaxNexus[];
+}
+
+/**
+ * Tax nexus response
+ */
+export interface TaxNexusResponse {
+  /** Nexus */
+  nexus: TaxNexus;
+}
+
+/**
+ * List tax reports response
+ */
+export interface ListTaxReportsResponse extends PaginatedResponse<TaxReport> {
+  /** Summary (if year filter is provided) */
+  summary?: {
+    year: number;
+    totalTaxable: string;
+    totalTax: string;
+    reportCount: number;
+  };
+}
+
+/**
+ * Tax report details
+ */
+export interface TaxReportDetails {
+  /** Order ID */
+  orderId: string;
+  /** Order date */
+  orderDate: string;
+  /** Customer */
+  customer: string;
+  /** Subtotal */
+  subtotal: string;
+  /** Tax amount */
+  taxAmount: string;
+  /** Total */
+  total: string;
+  /** Tax breakdown */
+  breakdown: TaxBreakdownItem[];
+}
+
+/**
+ * Get tax report response
+ */
+export interface GetTaxReportResponse {
+  /** Report */
+  report: TaxReport;
+  /** Details */
+  details: TaxReportDetails[];
+}
+
+/**
+ * Tax report response
+ */
+export interface TaxReportResponse {
+  /** Report */
+  report: TaxReport;
+}
+
+/**
+ * Success response
+ */
+export interface SuccessResponse {
+  /** Success flag */
+  success: boolean;
+}
+
+/**
+ * Product discounts response
+ */
+export interface ProductDiscountsResponse {
+  /** Discounts */
+  discounts: Array<{
+    id: string;
+    title: string;
+    description: string;
+    badge: string;
+    discountType: string;
+    discountValue: number;
+    discountAmount: number;
+    minPurchase: number | null;
+    minQuantity: number | null;
+    expiresAt: string;
+  }>;
+}
+
+/**
+ * Create order event response
+ */
+export interface CreateOrderEventResponse {
+  /** Event */
+  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;
+}
+