@basedone/core 0.1.8 → 0.2.0

package/lib/ecommerce/types/requests.ts

@@ -0,0 +1,525 @@
+/**
+ * Ecommerce API Request Types
+ * 
+ * This module contains all request types for the ecommerce API.
+ */
+
+import {
+  OrderStatus,
+  PaymentMethod,
+  ProductSortBy,
+  ReviewSortBy,
+  DiscountType,
+  DiscountMethod,
+  DiscountScope,
+  BannerType,
+  TaxType,
+  TaxBehavior,
+  TaxReportPeriodType,
+  ShipmentStatus,
+} from "./enums";
+import { ShippingAddress, ProductDimensions } from "./entities";
+
+/**
+ * Pagination parameters
+ */
+export interface PaginationParams {
+  /** Number of items to return */
+  limit?: number;
+  /** Number of items to skip */
+  offset?: number;
+}
+
+/**
+ * List products request parameters
+ */
+export interface ListProductsParams extends PaginationParams {
+  /** Filter by specific product IDs */
+  ids?: string[];
+  /** Filter by merchant ID */
+  merchantId?: string;
+  /** Filter by category slug */
+  category?: string;
+  /** Search query */
+  search?: string;
+  /** Filter by tags */
+  tags?: string[];
+  /** Minimum price */
+  minPrice?: number;
+  /** Maximum price */
+  maxPrice?: number;
+  /** Filter by featured status */
+  featured?: boolean;
+  /** Sort by */
+  sortBy?: ProductSortBy;
+  /** Filter by active status */
+  isActive?: boolean;
+}
+
+/**
+ * Create product request
+ */
+export interface CreateProductRequest {
+  /** Product title */
+  title: string;
+  /** Product images URLs (from media library) */
+  images: string[];
+  /** Price in USDC */
+  priceUSDC: number;
+  /** Compare at price */
+  compareAtPrice?: number | null;
+  /** Inventory count */
+  inventory?: number | null;
+  /** SKU */
+  sku?: string | null;
+  /** Minimum order quantity */
+  moq?: number;
+  /** Category slug */
+  category?: string | null;
+  /** Rich description (HTML) */
+  richDescription?: string | null;
+  /** Weight in kg */
+  weight?: number | null;
+  /** Dimensions */
+  dimensions?: ProductDimensions | null;
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Update product request
+ */
+export interface UpdateProductRequest extends Partial<CreateProductRequest> {}
+
+/**
+ * Create product variant request
+ */
+export interface CreateProductVariantRequest {
+  /** Variant name */
+  name: string;
+  /** SKU */
+  sku?: string | null;
+  /** Price override */
+  priceUSDC?: number | null;
+  /** Inventory count */
+  inventory?: number | null;
+  /** Variant attributes */
+  attributes: Record<string, string>;
+  /** Is active */
+  isActive?: boolean;
+  /** Sort order */
+  sortOrder?: number;
+}
+
+/**
+ * Update product variant request
+ */
+export interface UpdateProductVariantRequest extends Partial<CreateProductVariantRequest> {}
+
+/**
+ * Cart item
+ */
+export interface CartItem {
+  /** Product ID */
+  productId: string;
+  /** Quantity */
+  quantity: number;
+  /** Variant ID (optional) */
+  variantId?: string;
+}
+
+/**
+ * Create order request
+ */
+export interface CreateOrderRequest {
+  /** Cart items */
+  items: CartItem[];
+  /** Payment method */
+  paymentMethod: PaymentMethod;
+  /** Shipping address */
+  shippingAddress: ShippingAddress;
+  /** Customer notes */
+  customerNotes?: string;
+  /** Coupon code */
+  couponCode?: string;
+  /** Idempotency key */
+  idempotencyKey?: string;
+}
+
+/**
+ * List orders request parameters
+ */
+export interface ListOrdersParams extends PaginationParams {
+  /** Filter by status */
+  status?: OrderStatus;
+}
+
+/**
+ * Update order status request
+ */
+export interface UpdateOrderStatusRequest {
+  /** New status */
+  status: OrderStatus;
+  /** Tracking information (required for SHIPPED status) */
+  tracking?: {
+    trackingNumber: string;
+    carrier: string;
+  };
+}
+
+/**
+ * Create order event request
+ */
+export interface CreateOrderEventRequest {
+  /** Event type */
+  eventType: string;
+  /** Event title */
+  title: string;
+  /** Event description */
+  description?: string;
+  /** Event metadata */
+  metadata?: Record<string, any>;
+}
+
+/**
+ * Create review request
+ */
+export interface CreateReviewRequest {
+  /** Rating (1-5) */
+  rating: number;
+  /** Review title */
+  title?: string;
+  /** Review comment */
+  comment?: string;
+}
+
+/**
+ * List reviews request parameters
+ */
+export interface ListReviewsParams extends PaginationParams {
+  /** Sort by */
+  sortBy?: ReviewSortBy;
+}
+
+/**
+ * Respond to review request
+ */
+export interface RespondToReviewRequest {
+  /** Merchant response */
+  merchantResponse: string;
+}
+
+/**
+ * Create/update shipping address request
+ */
+export interface ShippingAddressRequest extends ShippingAddress {
+  /** Is default address */
+  isDefault?: boolean;
+  /** Address label */
+  label?: string | null;
+}
+
+/**
+ * Calculate cart discounts request
+ */
+export interface CalculateCartDiscountsRequest {
+  /** Cart items */
+  items: CartItem[];
+}
+
+/**
+ * Validate discount code request
+ */
+export interface ValidateDiscountRequest {
+  /** Discount code */
+  code: string;
+  /** Cart items */
+  items: CartItem[];
+}
+
+/**
+ * Calculate tax request
+ */
+export interface CalculateTaxRequest {
+  /** Cart items */
+  items: CartItem[];
+  /** Shipping address */
+  shippingAddress: {
+    country: string;
+    region?: string;
+    postalCode?: string;
+  };
+}
+
+/**
+ * Create/update merchant profile request
+ */
+export interface MerchantProfileRequest {
+  /** Merchant name */
+  name: string;
+  /** Description */
+  description?: string | null;
+  /** Payout address (wallet) */
+  payoutAddress: string;
+}
+
+/**
+ * Create coupon request
+ */
+export interface CreateCouponRequest {
+  /** Coupon code */
+  code?: string;
+  /** Title */
+  title?: string | null;
+  /** Discount method */
+  discountMethod?: DiscountMethod;
+  /** Discount type */
+  discountType: DiscountType;
+  /** Discount scope */
+  discountScope?: DiscountScope;
+  /** Discount value */
+  discountValue: number;
+  /** Minimum purchase */
+  minPurchase?: number | null;
+  /** Minimum quantity */
+  minQuantity?: number | null;
+  /** Buy quantity */
+  buyQuantity?: number | null;
+  /** Get quantity */
+  getQuantity?: number | null;
+  /** Get discount value */
+  getDiscountValue?: number | null;
+  /** Maximum uses */
+  maxUses?: number | null;
+  /** Uses per customer */
+  usesPerCustomer?: number | null;
+  /** Applicable products */
+  applicableProducts?: string[];
+  /** Applicable categories */
+  applicableCategories?: string[];
+  /** Combinable */
+  combinable?: boolean;
+  /** Start date */
+  startsAt: string;
+  /** Expiry date */
+  expiresAt: string;
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Update coupon request
+ */
+export interface UpdateCouponRequest extends Partial<CreateCouponRequest> {}
+
+/**
+ * Create shipping method request
+ */
+export interface CreateShippingMethodRequest {
+  /** Method name */
+  name: string;
+  /** Carrier */
+  carrier?: string | null;
+  /** Estimated delivery days */
+  estimatedDays?: string | null;
+  /** Flat rate */
+  flatRate?: number | null;
+  /** Weight-based */
+  weightBased?: boolean;
+  /** Free threshold */
+  freeThreshold?: number | null;
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Update shipping method request
+ */
+export interface UpdateShippingMethodRequest extends Partial<CreateShippingMethodRequest> {}
+
+/**
+ * Update shipment request
+ */
+export interface UpdateShipmentRequest {
+  /** Shipment status */
+  status?: ShipmentStatus;
+  /** Tracking number */
+  trackingNumber?: string | null;
+  /** Carrier */
+  carrier?: string | null;
+  /** Shipping label URL */
+  shippingLabel?: string | null;
+}
+
+/**
+ * Create banner request
+ */
+export interface CreateBannerRequest {
+  /** Banner type */
+  type?: BannerType;
+  /** Title */
+  title: string;
+  /** Subtitle */
+  subtitle?: string | null;
+  /** Image URL */
+  imageUrl: string;
+  /** Link URL */
+  linkUrl?: string | null;
+  /** CTA text */
+  ctaText?: string | null;
+  /** Start date */
+  startDate?: string | null;
+  /** End date */
+  endDate?: string | null;
+  /** Priority */
+  priority?: number;
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Update banner request
+ */
+export interface UpdateBannerRequest extends Partial<CreateBannerRequest> {}
+
+/**
+ * Track banner request
+ */
+export interface TrackBannerRequest {
+  /** Action type */
+  action: "impression" | "click";
+}
+
+/**
+ * Send message request
+ */
+export interface SendMessageRequest {
+  /** Order ID */
+  orderId: string;
+  /** Recipient user ID */
+  recipientId: string;
+  /** Message text */
+  message: string;
+}
+
+/**
+ * Update tax settings request
+ */
+export interface UpdateTaxSettingsRequest {
+  /** 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;
+}
+
+/**
+ * Create tax rule request
+ */
+export interface CreateTaxRuleRequest {
+  /** Country */
+  country: string;
+  /** Region */
+  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 */
+  taxRate: number;
+  /** Priority */
+  priority?: number;
+  /** Is compound */
+  isCompound?: boolean;
+}
+
+/**
+ * Update tax rule request
+ */
+export interface UpdateTaxRuleRequest extends Partial<CreateTaxRuleRequest> {
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Create tax nexus request
+ */
+export interface CreateTaxNexusRequest {
+  /** Country */
+  country: string;
+  /** Region */
+  region?: string | null;
+  /** Registration ID */
+  registrationId?: string | null;
+}
+
+/**
+ * Update tax nexus request
+ */
+export interface UpdateTaxNexusRequest {
+  /** Registration ID */
+  registrationId?: string | null;
+  /** Is active */
+  isActive?: boolean;
+}
+
+/**
+ * Generate tax report request
+ */
+export interface GenerateTaxReportRequest {
+  /** Period type */
+  periodType: TaxReportPeriodType;
+  /** Year */
+  year: number;
+  /** Period (1-12 for monthly, 1-4 for quarterly, 1 for yearly) */
+  period: number;
+}
+
+/**
+ * Update tax report status request
+ */
+export interface UpdateTaxReportStatusRequest {
+  /** Report status */
+  status: "DRAFT" | "FINALIZED" | "FILED";
+}
+
+/**
+ * List tax reports params
+ */
+export interface ListTaxReportsParams extends PaginationParams {
+  /** Filter by year (for summary) */
+  year?: number;
+}
+
+/**
+ * Get analytics params
+ */
+export interface GetAnalyticsParams {
+  /** Date range */
+  range?: "7days" | "30days" | "90days" | "1year";
+}
+
+/**
+ * List customers params
+ */
+export interface ListCustomersParams extends PaginationParams {}
+
+/**
+ * List active banners params
+ */
+export interface ListActiveBannersParams {
+  /** Filter by type */
+  type?: BannerType;
+  /** Filter by merchant ID */
+  merchantId?: string;
+}
+