@classytic/commerce-sdk 0.1.2 → 0.2.1

package/dist/sales/types/order.d.ts

@@ -0,0 +1,487 @@
+//#region src/sales/types/order.d.ts
+/**
+ * Order Types
+ *
+ * Source of truth: modules/commerce/order/order.model.js
+ */
+type ShippingStatus = 'pending' | 'requested' | 'picked_up' | 'in_transit' | 'out_for_delivery' | 'delivered' | 'failed_attempt' | 'returned' | 'cancelled';
+type ShippingProvider = 'redx' | 'pathao' | 'steadfast' | 'paperfly' | 'sundarban' | 'sa_paribahan' | 'dhl' | 'fedex' | 'manual' | 'other';
+declare enum OrderStatus {
+  PENDING = "pending",
+  PROCESSING = "processing",
+  CONFIRMED = "confirmed",
+  SHIPPED = "shipped",
+  DELIVERED = "delivered",
+  CANCELLED = "cancelled"
+}
+declare enum PaymentStatus {
+  PENDING = "pending",
+  VERIFIED = "verified",
+  FAILED = "failed",
+  REFUNDED = "refunded",
+  PARTIALLY_REFUNDED = "partially_refunded",
+  CANCELLED = "cancelled"
+}
+/**
+ * Order Item
+ */
+interface OrderItem {
+  _id?: string;
+  product: string;
+  productName: string;
+  productSlug?: string;
+  variantSku?: string;
+  variantAttributes?: Record<string, string>;
+  variantPriceModifier?: number;
+  quantity: number;
+  price: number;
+  /**
+   * System field: Cost of Goods Sold at time of sale
+   * Used for profit calculation. Read-only.
+   */
+  costPriceAtSale?: number;
+  vatRate?: number;
+  vatAmount?: number;
+  lineTotal?: number;
+  lineTotalExVat?: number;
+  profit?: number | null;
+  profitMargin?: number | null;
+}
+interface OrderDelivery {
+  method: string;
+  price: number;
+  estimatedDays?: number;
+}
+/**
+ * Order Delivery Address
+ */
+interface OrderAddress {
+  /** Address label (e.g., "Home", "Office") - optional */
+  label?: string;
+  /** Recipient name for delivery label */
+  recipientName?: string;
+  /** Contact phone for delivery (format: 01XXXXXXXXX) */
+  recipientPhone?: string;
+  /** Street address (required for checkout) */
+  addressLine1?: string;
+  /** Additional address details (apartment, floor, etc.) */
+  addressLine2?: string;
+  /** Area ID from @classytic/bd-areas constants */
+  areaId?: number;
+  /** Area display name (e.g., "Mohammadpur", "Dhanmondi") */
+  areaName?: string;
+  /** Zone ID for delivery pricing (1-6) */
+  zoneId?: number;
+  /** Provider-specific area IDs for logistics integration */
+  providerAreaIds?: {
+    redx?: number;
+    pathao?: number;
+    steadfast?: number;
+  };
+  /** City/District name */
+  city?: string;
+  /** Division/State */
+  division?: string;
+  /** Postal code */
+  postalCode?: string;
+  /** Country (defaults to "Bangladesh") */
+  country?: string;
+}
+interface OrderVat {
+  applicable: boolean;
+  rate: number;
+  amount: number;
+  pricesIncludeVat: boolean;
+  taxableAmount: number;
+  sellerBin?: string;
+  supplementaryDuty?: {
+    rate?: number;
+    amount?: number;
+  };
+  invoiceNumber?: string;
+  invoiceIssuedAt?: string;
+  invoiceBranch?: string;
+  invoiceDateKey?: string;
+}
+interface OrderPayment {
+  transactionId?: string;
+  /** Amount in paisa (smallest unit). Divide by 100 for BDT display. */
+  amount: number;
+  status: PaymentStatus | string;
+  method: string;
+  reference?: string;
+  verifiedAt?: string;
+  verifiedBy?: string;
+  refundedAmount?: number;
+  refundedAt?: string;
+  /** Split payments (POS multi-payment) */
+  payments?: Array<{
+    method: string;
+    amount: number;
+    reference?: string | null;
+    details?: unknown;
+  }>;
+}
+interface OrderShippingHistory {
+  status: ShippingStatus | string;
+  note?: string;
+  actor?: string;
+  timestamp: string;
+}
+interface OrderShippingCharges {
+  deliveryCharge?: number;
+  codCharge?: number;
+  totalCharge?: number;
+}
+interface OrderShippingPickup {
+  storeId?: number;
+  storeName?: string;
+  scheduledAt?: string;
+}
+interface OrderShippingCashCollection {
+  amount?: number;
+  collected?: boolean;
+  collectedAt?: string;
+}
+interface OrderShipping {
+  provider?: ShippingProvider | string;
+  status?: ShippingStatus | string;
+  trackingNumber?: string;
+  providerOrderId?: string;
+  providerStatus?: string;
+  trackingUrl?: string;
+  consignmentId?: string;
+  labelUrl?: string;
+  estimatedDelivery?: string;
+  requestedAt?: string;
+  pickedUpAt?: string;
+  deliveredAt?: string;
+  pickup?: OrderShippingPickup;
+  charges?: OrderShippingCharges;
+  cashCollection?: OrderShippingCashCollection;
+  lastWebhookAt?: string;
+  webhookCount?: number;
+  metadata?: Record<string, unknown>;
+  history?: OrderShippingHistory[];
+}
+/**
+ * Parcel metrics for delivery estimation
+ */
+interface OrderParcel {
+  /** Total weight in grams */
+  weightGrams: number;
+  /** Package dimensions in centimeters */
+  dimensionsCm?: {
+    length: number;
+    width: number;
+    height: number;
+  };
+  /** Number of items without weight data */
+  missingWeightItems: number;
+  /** Number of items without dimension data */
+  missingDimensionItems: number;
+}
+interface PromoDiscountLine {
+  programId: string;
+  programName: string;
+  rewardId: string;
+  type: 'percentage' | 'fixed';
+  scope: string;
+  amount: number;
+  description: string;
+  voucherCode?: string;
+}
+interface PromoFreeProduct {
+  programId: string;
+  productId?: string;
+  productSku?: string;
+  quantity: number;
+}
+interface PromoApplied {
+  evaluationId: string;
+  totalDiscount: number;
+  appliedDiscounts: PromoDiscountLine[];
+  freeProducts: PromoFreeProduct[];
+  appliedCodes: string[];
+  programsApplied: string[];
+}
+interface MembershipApplied {
+  cardId?: string;
+  tier?: string;
+  pointsEarned?: number;
+  pointsRedeemed?: number;
+  pointsRedemptionDiscount?: number;
+  tierDiscountApplied?: number;
+  tierDiscountPercent?: number;
+}
+/**
+ * Cancellation request details
+ */
+interface CancellationRequest {
+  requested: boolean;
+  reason?: string;
+  requestedAt?: string;
+  requestedBy?: string;
+}
+/**
+ * Main Order Interface
+ */
+interface Order {
+  _id: string;
+  /** Virtual: last 8 chars of _id (uppercase) */
+  orderNumber?: string;
+  customer?: string;
+  customerName: string;
+  customerPhone?: string;
+  customerEmail?: string;
+  userId?: string;
+  items: OrderItem[];
+  subtotal: number;
+  discountAmount: number;
+  deliveryCharge: number;
+  totalAmount: number;
+  vat?: OrderVat;
+  delivery?: OrderDelivery;
+  deliveryAddress?: OrderAddress;
+  /** True if ordering on behalf of someone else (gift order) */
+  isGift?: boolean;
+  status: OrderStatus | string;
+  source: 'web' | 'pos' | 'api' | 'guest';
+  branch?: string;
+  terminalId?: string;
+  cashier?: string;
+  /** Idempotency key for safe retries */
+  idempotencyKey?: string;
+  /** Reservation ID for stock hold */
+  stockReservationId?: string;
+  stockReservationExpiresAt?: string;
+  currentPayment?: OrderPayment;
+  shipping?: OrderShipping;
+  /** Promotion discounts applied at checkout */
+  promoApplied?: PromoApplied;
+  /** Membership/loyalty applied at checkout */
+  membershipApplied?: MembershipApplied;
+  /** Parcel metrics for delivery estimation */
+  parcel?: OrderParcel;
+  /** Customer cancellation request (awaiting admin review) */
+  cancellationRequest?: CancellationRequest;
+  /** Final cancellation reason (after cancelled) */
+  cancellationReason?: string;
+  notes?: string;
+  createdAt: string;
+  updatedAt: string;
+  canCancel?: boolean;
+  isCompleted?: boolean;
+  paymentStatus?: string;
+  paymentMethod?: string;
+  netAmount?: number;
+  grossAmount?: number;
+  trackingNumber?: string;
+  shippedAt?: string;
+  deliveredAt?: string;
+  shippingStatus?: string;
+}
+/**
+ * Payment Data for checkout
+ */
+interface PaymentData {
+  /**
+   * Payment method (optional, defaults to 'cash')
+   */
+  type?: 'cash' | 'bkash' | 'nagad' | 'rocket' | 'bank_transfer' | 'card' | string;
+  /**
+   * Payment gateway (default: 'manual')
+   */
+  gateway?: string;
+  /**
+   * Transaction ID/reference (recommended for verification)
+   */
+  reference?: string;
+  /**
+   * Mobile wallet sender phone (REQUIRED for bkash/nagad/rocket)
+   */
+  senderPhone?: string;
+  /**
+   * Additional payment verification details
+   */
+  paymentDetails?: {
+    walletNumber?: string;
+    walletType?: 'personal' | 'merchant';
+    bankName?: string;
+    accountNumber?: string;
+    accountName?: string;
+    proofUrl?: string;
+  };
+  /** Additional payment notes */
+  notes?: string;
+}
+/**
+ * Payload for Creating an Order (Web/API)
+ */
+interface CreateOrderPayload {
+  /** Delivery address (required) */
+  deliveryAddress: OrderAddress & {
+    recipientName: string;
+    recipientPhone: string;
+    addressLine1: string;
+    areaId: number;
+    areaName: string;
+    zoneId: number;
+    city: string;
+  };
+  /** Delivery method and pricing (required) */
+  delivery: OrderDelivery & {
+    method: string;
+    price: number;
+  };
+  /**
+   * Payment details for verification (optional, defaults to cash)
+   */
+  paymentData?: PaymentData;
+  /** True if ordering on behalf of someone else (gift order) */
+  isGift?: boolean;
+  /** Coupon code to apply */
+  couponCode?: string;
+  /** Order notes */
+  notes?: string;
+  /** Loyalty points to redeem as discount (requires active membership) */
+  pointsToRedeem?: number;
+  /** Preferred branch ID for fulfillment */
+  branchId?: string;
+  /** Preferred branch slug (alternative to branchId) */
+  branchSlug?: string;
+  /** Idempotency key for safe retries (prevents duplicate orders) */
+  idempotencyKey?: string;
+}
+/**
+ * Guest checkout item (from FE localStorage)
+ */
+interface GuestCheckoutItem {
+  /** Product ID */
+  productId: string;
+  /** Variant SKU (for variant products) */
+  variantSku?: string | null;
+  /** Quantity */
+  quantity: number;
+}
+/**
+ * Guest identity for unauthenticated checkout
+ */
+interface GuestInfo {
+  /** Guest name */
+  name: string;
+  /** Guest phone (BD format: 01XXXXXXXXX) */
+  phone: string;
+  /** Guest email (optional) */
+  email?: string;
+}
+/**
+ * Payload for Guest Checkout (no auth required)
+ *
+ * Items come from FE localStorage instead of a DB cart.
+ * Guest identity is provided via name + phone.
+ */
+interface GuestCheckoutPayload {
+  /** Cart items from frontend localStorage */
+  items: GuestCheckoutItem[];
+  /** Guest identity (used to create/find customer record) */
+  guest: GuestInfo;
+  /** Delivery address (required) */
+  deliveryAddress: CreateOrderPayload['deliveryAddress'];
+  /** Delivery method and pricing (required) */
+  delivery: CreateOrderPayload['delivery'];
+  /** Payment details for verification (optional, defaults to cash) */
+  paymentData?: PaymentData;
+  /** True if ordering on behalf of someone else (gift order) */
+  isGift?: boolean;
+  /** Coupon code to apply */
+  couponCode?: string;
+  /** Order notes */
+  notes?: string;
+  /** Preferred branch ID for fulfillment */
+  branchId?: string;
+  /** Preferred branch slug (alternative to branchId) */
+  branchSlug?: string;
+  /** Idempotency key for safe retries */
+  idempotencyKey?: string;
+}
+/**
+ * Payload for Updating Order Status (Admin)
+ */
+interface UpdateStatusPayload {
+  status: OrderStatus;
+  /** Optional note for status change */
+  note?: string;
+}
+/**
+ * Payload for Cancelling an Order
+ */
+interface CancelOrderPayload {
+  /** Cancellation reason */
+  reason?: string;
+  /** Process refund if payment was verified */
+  refund?: boolean;
+}
+/**
+ * Payload for Requesting Cancellation (awaits admin review)
+ */
+interface CancelRequestPayload {
+  /** Reason for cancellation request */
+  reason?: string;
+}
+/**
+ * Payload for Fulfilling/Shipping an Order (Admin)
+ */
+interface FulfillOrderPayload {
+  /** Shipping tracking number */
+  trackingNumber?: string;
+  /** Shipping carrier (e.g., Pathao, Redx) */
+  carrier?: string;
+  /** Fulfillment notes */
+  notes?: string;
+  /** Shipping date */
+  shippedAt?: string;
+  /** Estimated delivery date */
+  estimatedDelivery?: string;
+  /** Branch ID for inventory decrement (overrides order.branch) */
+  branchId?: string;
+  /** Branch slug (alternative to branchId) */
+  branchSlug?: string;
+  /**
+   * Record COGS expense transaction (default: false)
+   */
+  recordCogs?: boolean;
+}
+/**
+ * Payload for Refunding an Order (Admin)
+ */
+interface RefundOrderPayload {
+  /** Refund amount in smallest unit (paisa). Omit for full refund. */
+  amount?: number;
+  /** Refund reason */
+  reason?: string;
+}
+/**
+ * Payload for Requesting Shipping Pickup (Admin)
+ */
+interface RequestShippingPayload {
+  /** Shipping provider (required) */
+  provider: string;
+  /** Additional shipping options */
+  options?: Record<string, unknown>;
+}
+/**
+ * Payload for Updating Shipping Status (Admin/Webhook)
+ */
+interface UpdateShippingPayload {
+  /** Shipping status (required) */
+  status: string;
+  /** Status note */
+  note?: string;
+  /** Tracking number */
+  trackingNumber?: string;
+  /** Tracking URL */
+  trackingUrl?: string;
+}
+//#endregion
+export { CancelOrderPayload, CancelRequestPayload, CancellationRequest, CreateOrderPayload, FulfillOrderPayload, GuestCheckoutItem, GuestCheckoutPayload, GuestInfo, MembershipApplied, Order, OrderAddress, OrderDelivery, OrderItem, OrderParcel, OrderPayment, OrderShipping, OrderShippingCashCollection, OrderShippingCharges, OrderShippingHistory, OrderShippingPickup, OrderStatus, OrderVat, PaymentData, PaymentStatus, PromoApplied, PromoDiscountLine, PromoFreeProduct, RefundOrderPayload, RequestShippingPayload, ShippingProvider, ShippingStatus, UpdateShippingPayload, UpdateStatusPayload };

package/dist/sales/types/order.js

@@ -0,0 +1,22 @@
+//#region src/sales/types/order.ts
+let OrderStatus = /* @__PURE__ */ function(OrderStatus) {
+	OrderStatus["PENDING"] = "pending";
+	OrderStatus["PROCESSING"] = "processing";
+	OrderStatus["CONFIRMED"] = "confirmed";
+	OrderStatus["SHIPPED"] = "shipped";
+	OrderStatus["DELIVERED"] = "delivered";
+	OrderStatus["CANCELLED"] = "cancelled";
+	return OrderStatus;
+}({});
+let PaymentStatus = /* @__PURE__ */ function(PaymentStatus) {
+	PaymentStatus["PENDING"] = "pending";
+	PaymentStatus["VERIFIED"] = "verified";
+	PaymentStatus["FAILED"] = "failed";
+	PaymentStatus["REFUNDED"] = "refunded";
+	PaymentStatus["PARTIALLY_REFUNDED"] = "partially_refunded";
+	PaymentStatus["CANCELLED"] = "cancelled";
+	return PaymentStatus;
+}({});
+
+//#endregion
+export { OrderStatus, PaymentStatus };