@basedone/core 0.1.10 → 0.2.0

package/lib/ecommerce/types/entities.ts

@@ -0,0 +1,722 @@
+/**
+ * Ecommerce Entity Interfaces
+ * 
+ * This module contains all core entity interfaces used in the ecommerce API.
+ */
+
+import {
+  OrderStatus,
+  PaymentMethod,
+  PaymentStatus,
+  MerchantStatus,
+  ShipmentStatus,
+  ReturnStatus,
+  ReviewStatus,
+  DiscountType,
+  DiscountMethod,
+  DiscountScope,
+  BannerType,
+  TaxType,
+  TaxBehavior,
+  TaxReportPeriodType,
+  TaxReportStatus,
+  InventoryAuditAction,
+} from "./enums";
+
+/**
+ * Base entity interface with common fields
+ */
+export interface BaseEntity {
+  /** Unique identifier */
+  id: string;
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt: string;
+  /** Tenant ID for multi-tenancy */
+  tenantId?: string | null;
+}
+
+/**
+ * Product dimensions
+ */
+export interface ProductDimensions {
+  /** Length in cm */
+  length?: number;
+  /** Width in cm */
+  width?: number;
+  /** Height in cm */
+  height?: number;
+}
+
+/**
+ * Product entity
+ */
+export interface Product extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Product title */
+  title: string;
+  /** Product description (plain text) */
+  description?: string | null;
+  /** Rich description (HTML) */
+  richDescription?: string | null;
+  /** Product images URLs */
+  images: string[];
+  /** Legacy single image URL (for backward compatibility) */
+  imageUrl?: string | null;
+  /** Price in USDC */
+  priceUSDC: string;
+  /** Compare at price (original price for discount display) */
+  compareAtPrice?: string | null;
+  /** Stock keeping unit */
+  sku?: string | null;
+  /** Inventory count */
+  inventory?: number | null;
+  /** Minimum order quantity */
+  moq: number;
+  /** Product category slug */
+  category?: string | null;
+  /** Category ID */
+  categoryId?: string | null;
+  /** Product tags */
+  tags?: string[];
+  /** Weight in kg */
+  weight?: string | null;
+  /** Product dimensions */
+  dimensions?: ProductDimensions | null;
+  /** Is product active */
+  isActive: boolean;
+  /** Is product featured */
+  featured: boolean;
+  /** View count */
+  viewCount: number;
+  /** Sold count */
+  soldCount: number;
+  /** Average rating (computed from reviews) */
+  averageRating?: number | null;
+  /** Review count */
+  reviewCount?: number;
+  /** Merchant information */
+  merchant?: Merchant;
+  /** Product variants */
+  variants?: ProductVariant[];
+  /** Product reviews */
+  reviews?: ProductReview[];
+}
+
+/**
+ * Product variant entity
+ */
+export interface ProductVariant extends BaseEntity {
+  /** Product ID */
+  productId: string;
+  /** Variant name */
+  name: string;
+  /** SKU */
+  sku?: string | null;
+  /** Price override (if different from base product) */
+  priceUSDC?: string | null;
+  /** Inventory count */
+  inventory?: number | null;
+  /** Variant attributes (e.g., {color: "red", size: "L"}) */
+  attributes: Record<string, string>;
+  /** Is variant active */
+  isActive: boolean;
+  /** Sort order */
+  sortOrder: number;
+}
+
+/**
+ * Merchant entity
+ */
+export interface Merchant extends BaseEntity {
+  /** Owner user ID */
+  ownerUserId: string;
+  /** Merchant name */
+  name: string;
+  /** Merchant description */
+  description?: string | null;
+  /** Payout address (wallet) */
+  payoutAddress: string;
+  /** Merchant status */
+  status: MerchantStatus;
+}
+
+/**
+ * Shipping address
+ */
+export interface ShippingAddress {
+  /** Full name */
+  fullName: string;
+  /** Phone number */
+  phone: string;
+  /** Email address */
+  email?: string | null;
+  /** Address line 1 */
+  addressLine1: string;
+  /** Address line 2 */
+  addressLine2?: string | null;
+  /** City */
+  city: string;
+  /** State or province */
+  stateProvince: string;
+  /** Postal code */
+  postalCode: string;
+  /** Country */
+  country: string;
+  /** Delivery instructions */
+  deliveryInstructions?: string | null;
+}
+
+/**
+ * User shipping address entity (saved addresses)
+ */
+export interface UserShippingAddress extends BaseEntity, ShippingAddress {
+  /** User ID */
+  userId: string;
+  /** Is default address */
+  isDefault: boolean;
+  /** Address label (e.g., "Home", "Work") */
+  label?: string | null;
+}
+
+/**
+ * Order item
+ */
+export interface OrderItem extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Product ID */
+  productId: string;
+  /** Variant ID */
+  variantId?: string | null;
+  /** Quantity */
+  quantity: number;
+  /** Unit price in USDC (snapshot at order time) */
+  unitPriceUSDC: string;
+  /** Product title snapshot */
+  titleSnapshot: string;
+  /** Product details (for display) */
+  product?: Product;
+  /** Variant details (for display) */
+  variant?: ProductVariant;
+}
+
+/**
+ * Payment entity
+ */
+export interface Payment extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Payment method */
+  method: PaymentMethod;
+  /** Payment status */
+  status: PaymentStatus;
+  /** Amount in USDC */
+  amountUSDC: string;
+  /** Deposit transaction hash */
+  depositTxHash?: string | null;
+  /** Settlement transaction hash */
+  settlementTxHash?: string | null;
+}
+
+/**
+ * Settlement entity
+ */
+export interface Settlement extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Merchant ID */
+  merchantId: string;
+  /** Merchant payout address */
+  merchantPayoutAddress: string;
+  /** Amount in USDC */
+  amountUSDC: string;
+  /** Settlement status */
+  status: string;
+  /** Transaction hash */
+  txHash?: string | null;
+  /** Next attempt timestamp */
+  nextAttemptAt?: string | null;
+  /** Attempt count */
+  attemptCount: number;
+  /** Last error */
+  lastError?: string | null;
+}
+
+/**
+ * Shipment entity
+ */
+export interface Shipment extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Shipment status */
+  status: ShipmentStatus;
+  /** Carrier name */
+  carrier?: string | null;
+  /** Tracking number */
+  trackingNumber?: string | null;
+  /** Shipping label URL */
+  shippingLabel?: string | null;
+  /** Shipped timestamp */
+  shippedAt?: string | null;
+  /** Delivered timestamp */
+  deliveredAt?: string | null;
+}
+
+/**
+ * Order entity
+ */
+export interface Order extends BaseEntity {
+  /** User ID (customer) */
+  userId: string;
+  /** Merchant ID */
+  merchantId: string;
+  /** Order status */
+  status: OrderStatus;
+  /** Total amount in USDC */
+  totalUSDC: string;
+  /** Payment method */
+  paymentMethod: PaymentMethod;
+  /** Shipping address */
+  shippingAddress: ShippingAddress;
+  /** Customer notes */
+  customerNotes?: string | null;
+  /** Order items */
+  items: OrderItem[];
+  /** Payment information */
+  payment?: Payment;
+  /** Settlement information */
+  settlement?: Settlement;
+  /** Shipment information */
+  shipment?: Shipment;
+  /** Merchant information */
+  merchant?: Merchant;
+  /** Customer information */
+  user?: {
+    id: string;
+    username?: string;
+    email?: string;
+  };
+  /** Order events */
+  events?: OrderEvent[];
+}
+
+/**
+ * Order event entity
+ */
+export interface OrderEvent extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Event type */
+  eventType: string;
+  /** Event title */
+  title: string;
+  /** Event description */
+  description?: string | null;
+  /** Event metadata */
+  metadata?: Record<string, any> | null;
+  /** Performer user ID */
+  performedBy?: string | null;
+  /** Performer information */
+  performer?: {
+    id: string;
+    username?: string;
+  };
+}
+
+/**
+ * Product review entity
+ */
+export interface ProductReview extends BaseEntity {
+  /** Product ID */
+  productId: string;
+  /** User ID */
+  userId: string;
+  /** Order ID (for verified purchase) */
+  orderId?: string | null;
+  /** Rating (1-5) */
+  rating: number;
+  /** Review title */
+  title?: string | null;
+  /** Review comment */
+  comment?: string | null;
+  /** Review images */
+  images?: string[];
+  /** Merchant response */
+  merchantResponse?: string | null;
+  /** Merchant responded timestamp */
+  merchantRespondedAt?: string | null;
+  /** Is verified purchase */
+  isVerifiedPurchase: boolean;
+  /** Is visible */
+  isVisible: boolean;
+  /** Review status */
+  status: ReviewStatus;
+  /** Helpfulness count (thumbs up) */
+  helpfulCount: number;
+  /** User information */
+  user?: {
+    id: string;
+    address: string;
+  };
+  /** Product information */
+  product?: Product;
+}
+
+/**
+ * Return entity
+ */
+export interface Return extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** User ID */
+  userId: string;
+  /** Merchant ID */
+  merchantId: string;
+  /** Return status */
+  status: ReturnStatus;
+  /** Return reason */
+  reason?: string | null;
+  /** Requested timestamp */
+  requestedAt: string;
+  /** Approved timestamp */
+  approvedAt?: string | null;
+  /** Rejected timestamp */
+  rejectedAt?: string | null;
+  /** Received timestamp */
+  receivedAt?: string | null;
+  /** Completed timestamp */
+  completedAt?: string | null;
+  /** Return items */
+  items: ReturnItem[];
+}
+
+/**
+ * Return item
+ */
+export interface ReturnItem {
+  /** Item ID */
+  id: string;
+  /** Product ID */
+  productId: string;
+  /** Quantity */
+  quantity: number;
+  /** Reason */
+  reason?: string | null;
+  /** Product information */
+  product?: Product;
+}
+
+/**
+ * Coupon entity
+ */
+export interface Coupon extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Coupon code */
+  code: string;
+  /** Coupon title */
+  title?: string | null;
+  /** Discount method */
+  discountMethod: DiscountMethod;
+  /** Discount type */
+  discountType: DiscountType;
+  /** Discount scope */
+  discountScope: DiscountScope;
+  /** Discount value */
+  discountValue: number;
+  /** Minimum purchase amount */
+  minPurchase?: number | null;
+  /** Minimum quantity */
+  minQuantity?: number | null;
+  /** Buy quantity (for BUY_X_GET_Y) */
+  buyQuantity?: number | null;
+  /** Get quantity (for BUY_X_GET_Y) */
+  getQuantity?: number | null;
+  /** Get discount value (for BUY_X_GET_Y) */
+  getDiscountValue?: number | null;
+  /** Maximum uses */
+  maxUses?: number | null;
+  /** Uses per customer */
+  usesPerCustomer?: number | null;
+  /** Used count */
+  usedCount: number;
+  /** Applicable product IDs */
+  applicableProducts: string[];
+  /** Applicable category IDs */
+  applicableCategories: string[];
+  /** Can be combined with other discounts */
+  combinable: boolean;
+  /** Start timestamp */
+  startsAt: string;
+  /** Expiry timestamp */
+  expiresAt: string;
+  /** Is active */
+  isActive: boolean;
+  /** Coupon usages */
+  usages?: CouponUsage[];
+}
+
+/**
+ * Coupon usage entity
+ */
+export interface CouponUsage extends BaseEntity {
+  /** Coupon ID */
+  couponId: string;
+  /** User ID */
+  userId: string;
+  /** Order ID */
+  orderId: string;
+  /** Discount amount */
+  discount: string;
+  /** Used timestamp */
+  usedAt: string;
+  /** User information */
+  user?: {
+    username?: string;
+  };
+}
+
+/**
+ * Shipping method entity
+ */
+export interface ShippingMethod extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Method name */
+  name: string;
+  /** Carrier */
+  carrier?: string | null;
+  /** Estimated delivery days */
+  estimatedDays?: string | null;
+  /** Flat rate */
+  flatRate?: number | null;
+  /** Is weight-based */
+  weightBased: boolean;
+  /** Free shipping threshold */
+  freeThreshold?: number | null;
+  /** Is active */
+  isActive: boolean;
+}
+
+/**
+ * Banner entity
+ */
+export interface Banner extends BaseEntity {
+  /** Merchant ID (null for admin banners) */
+  merchantId?: string | null;
+  /** Banner type */
+  type: BannerType;
+  /** Title */
+  title: string;
+  /** Subtitle */
+  subtitle?: string | null;
+  /** Image URL */
+  imageUrl: string;
+  /** Link URL */
+  linkUrl?: string | null;
+  /** Call-to-action text */
+  ctaText?: string | null;
+  /** Start date */
+  startDate?: string | null;
+  /** End date */
+  endDate?: string | null;
+  /** Priority (higher = shown first) */
+  priority: number;
+  /** Is active */
+  isActive: boolean;
+  /** Impressions count */
+  impressions: number;
+  /** Clicks count */
+  clicks: number;
+  /** Merchant information */
+  merchant?: {
+    id: string;
+    name: string;
+  };
+}
+
+/**
+ * Media asset entity
+ */
+export interface MediaAsset extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Blob URL */
+  blobUrl: string;
+  /** Blob pathname */
+  blobPathname: string;
+  /** Download URL */
+  downloadUrl: string;
+  /** Filename */
+  filename: string;
+  /** Content type */
+  contentType: string;
+  /** File size in bytes */
+  size: number;
+}
+
+/**
+ * Message entity
+ */
+export interface Message extends BaseEntity {
+  /** Order ID */
+  orderId: string;
+  /** Sender user ID */
+  senderId: string;
+  /** Recipient user ID */
+  recipientId: string;
+  /** Message text */
+  message: string;
+  /** Is read */
+  isRead: boolean;
+  /** Sender information */
+  sender?: {
+    id: string;
+    username?: string;
+  };
+  /** Recipient information */
+  recipient?: {
+    id: string;
+    username?: string;
+  };
+  /** Order information */
+  order?: Order;
+}
+
+/**
+ * Tax settings entity
+ */
+export interface TaxSettings extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Is tax enabled */
+  taxEnabled: boolean;
+  /** Prices include tax */
+  pricesIncludeTax: boolean;
+  /** Default tax behavior */
+  defaultTaxBehavior: TaxBehavior;
+  /** Tax registration number */
+  taxRegistrationNumber?: string | null;
+  /** Registration country */
+  registrationCountry?: string | null;
+}
+
+/**
+ * Tax rule entity
+ */
+export interface TaxRule extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Country */
+  country: string;
+  /** Region/state */
+  region?: string | null;
+  /** Postal code from */
+  postalCodeFrom?: string | null;
+  /** Postal code to */
+  postalCodeTo?: string | null;
+  /** Tax type */
+  taxType: TaxType;
+  /** Tax name */
+  taxName: string;
+  /** Tax rate (percentage) */
+  taxRate: number;
+  /** Priority (higher = applied first) */
+  priority: number;
+  /** Is compound tax */
+  isCompound: boolean;
+  /** Is active */
+  isActive: boolean;
+}
+
+/**
+ * Tax nexus entity
+ */
+export interface TaxNexus extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Country */
+  country: string;
+  /** Region/state */
+  region?: string | null;
+  /** Registration ID */
+  registrationId?: string | null;
+  /** Is active */
+  isActive: boolean;
+}
+
+/**
+ * Tax report entity
+ */
+export interface TaxReport extends BaseEntity {
+  /** Merchant ID */
+  merchantId: string;
+  /** Period type */
+  periodType: TaxReportPeriodType;
+  /** Period start */
+  periodStart: string;
+  /** Period end */
+  periodEnd: string;
+  /** Total taxable amount */
+  totalTaxable: string;
+  /** Total tax amount */
+  totalTax: string;
+  /** Report status */
+  status: TaxReportStatus;
+  /** Exported timestamp */
+  exportedAt?: string | null;
+}
+
+/**
+ * Inventory audit entry
+ */
+export interface InventoryAuditEntry extends BaseEntity {
+  /** Product ID */
+  productId: string;
+  /** Variant ID */
+  variantId?: string | null;
+  /** Action */
+  action: InventoryAuditAction;
+  /** Previous quantity */
+  previousQuantity?: number | null;
+  /** New quantity */
+  newQuantity?: number | null;
+  /** Change amount */
+  changeAmount: number;
+  /** Reason */
+  reason?: string | null;
+  /** Reference ID (e.g., order ID) */
+  referenceId?: string | null;
+  /** Product information */
+  product?: Product;
+  /** Variant information */
+  variant?: ProductVariant;
+}
+
+/**
+ * Customer summary (for merchant view)
+ */
+export interface CustomerSummary {
+  /** Customer user ID */
+  id: string;
+  /** Username */
+  username?: string;
+  /** Email */
+  email?: string;
+  /** Wallet address */
+  address?: string;
+  /** Total orders */
+  totalOrders: number;
+  /** Total spent */
+  totalSpent: string;
+  /** Average order value */
+  averageOrderValue: string;
+  /** Last order date */
+  lastOrderDate?: string;
+  /** First order date */
+  firstOrderDate?: string;
+}
+