@classytic/commerce-sdk 0.1.1 → 0.2.1

package/dist/sales/prefetch.js

@@ -0,0 +1,13 @@
+import orderApi from "./api/order.js";
+import { customerApi } from "./api/customer.js";
+import { createCrudPrefetcher } from "../core/prefetch.js";
+
+//#region src/sales/prefetch.ts
+/**
+* Sales SSR Prefetchers
+*/
+const ordersPrefetcher = createCrudPrefetcher(orderApi, "orders");
+const customersPrefetcher = createCrudPrefetcher(customerApi, "customers");
+
+//#endregion
+export { customersPrefetcher, ordersPrefetcher };

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

@@ -0,0 +1,123 @@
+import { Product, ProductVariant } from "../../catalog/types/product.js";
+//#region src/sales/types/cart.d.ts
+/**
+ * Cart Item (Backend Response Format)
+ * Represents a single item in the shopping cart as returned by API
+ */
+interface CartItem {
+  /** Cart item ID (for update/remove operations via PATCH/DELETE /cart/items/:itemId) */
+  _id: string;
+  /** Product reference (fully populated Product object from backend) */
+  product: Product;
+  /**
+   * Variant SKU (optional)
+   * - null/undefined for simple products
+   * - Required for variant products (e.g., "TSHIRT-M-RED")
+   * - Must match a valid variant.sku from product.variants[]
+   */
+  variantSku?: string | null;
+  /** Quantity of this item (minimum: 1) */
+  quantity: number;
+}
+/**
+ * Shopping Cart
+ * Represents a user's shopping cart
+ */
+interface Cart {
+  /** Cart ID */
+  _id: string;
+  /** User/Customer ID */
+  user: string;
+  /** Cart items */
+  items: CartItem[];
+  /** Creation timestamp */
+  createdAt: string;
+  /** Last update timestamp */
+  updatedAt: string;
+}
+/**
+ * Populated Cart Item
+ * Cart item with fully populated product for display
+ */
+interface PopulatedCartItem {
+  /** Fully populated product */
+  product: Product;
+  /** Variant SKU */
+  variantSku?: string | null;
+  /** Quantity */
+  quantity: number;
+  /** Resolved variant (if variantSku is provided) */
+  variant?: ProductVariant;
+  /** Final price (basePrice + variant.priceModifier) */
+  finalPrice: number;
+  /** Line total (finalPrice * quantity) */
+  lineTotal: number;
+}
+/**
+ * Cart Summary
+ * Complete cart with computed totals
+ */
+interface CartSummary {
+  /** Populated cart items with derived fields */
+  items: PopulatedCartItem[];
+  /** Total item count (sum of all quantities) */
+  itemCount: number;
+  /** Subtotal (sum of all line totals) */
+  subtotal: number;
+}
+/**
+ * Add Item Payload
+ * Data required to add an item to cart via POST /api/v1/cart/items
+ */
+interface AddCartItemPayload {
+  /** Product ID (required) */
+  productId: string;
+  /**
+   * Variant SKU (required for variant products, omit for simple products)
+   * - For simple products: omit this field
+   * - For variant products: must match a valid variant.sku from product.variants[]
+   */
+  variantSku?: string | null;
+  /** Quantity to add (minimum: 1, required) */
+  quantity: number;
+}
+/** Alias for AddCartItemPayload (for consistency with hooks) */
+type AddToCartPayload = AddCartItemPayload;
+/**
+ * Update Item Payload
+ * Data required to update cart item quantity
+ */
+interface UpdateCartItemPayload {
+  /** Cart item ID */
+  itemId: string;
+  /** New quantity (minimum: 1) */
+  quantity: number;
+}
+/**
+ * Remove Item Payload
+ * Data required to remove an item from cart
+ */
+interface RemoveCartItemPayload {
+  /** Cart item ID */
+  itemId: string;
+}
+/**
+ * Cart API Response
+ */
+interface CartResponse {
+  success: boolean;
+  data: Cart;
+}
+/**
+ * @deprecated Use the new variant system instead
+ * Legacy type for old variation system - kept for backwards compatibility
+ */
+interface CartItemVariation {
+  name: string;
+  option: {
+    value: string;
+    priceModifier: number;
+  };
+}
+//#endregion
+export { AddCartItemPayload, AddToCartPayload, Cart, CartItem, CartItemVariation, CartResponse, CartSummary, PopulatedCartItem, RemoveCartItemPayload, UpdateCartItemPayload };

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

@@ -0,0 +1,119 @@
+import { ApiResponse, PaginatedResponse } from "../../core/api-factory.js";
+
+//#region src/sales/types/customer.d.ts
+type CustomerGender = 'male' | 'female' | 'other' | 'prefer-not-to-say';
+type CustomerTier = 'bronze' | 'silver' | 'gold' | 'platinum';
+/**
+ * Customer Address
+ *
+ * Stores user's saved addresses with area info for delivery.
+ */
+interface CustomerAddress {
+  _id?: string;
+  recipientName?: string;
+  /** Contact phone for delivery */
+  recipientPhone?: string;
+  label?: string;
+  addressLine1?: string;
+  addressLine2?: string;
+  city?: string;
+  division?: string;
+  postalCode?: string;
+  country?: string;
+  /** @deprecated Use recipientPhone instead */
+  phone?: string;
+  isDefault?: boolean;
+  /** Area internalId from @classytic/bd-areas */
+  areaId?: number;
+  /** Area name for display */
+  areaName?: string;
+  /** Delivery zone (1-6) for pricing tier */
+  zoneId?: number;
+  /** Provider-specific area IDs for logistics */
+  providerAreaIds?: {
+    redx?: number;
+    pathao?: number;
+  };
+}
+interface CustomerStats {
+  orders?: {
+    total?: number;
+    completed?: number;
+    cancelled?: number;
+    refunded?: number;
+  };
+  revenue?: {
+    total?: number;
+    lifetime?: number;
+  };
+  firstOrderDate?: string;
+  lastOrderDate?: string;
+  /**
+   * Some deployments may include subscription stats; keep optional to avoid breaking.
+   */
+  subscriptions?: {
+    active?: number;
+    cancelled?: number;
+  };
+}
+interface CustomerMembership {
+  cardId: string;
+  isActive: boolean;
+  enrolledAt?: string;
+  points?: {
+    current?: number;
+    lifetime?: number;
+    redeemed?: number;
+  };
+  tier?: string;
+  tierOverride?: string;
+  tierOverrideReason?: string;
+  tierOverrideBy?: string;
+}
+interface Customer {
+  _id: string;
+  id?: string;
+  userId?: string;
+  name: string;
+  phone: string;
+  email?: string;
+  dateOfBirth?: string;
+  gender?: CustomerGender;
+  addresses?: CustomerAddress[];
+  stats?: CustomerStats;
+  tags?: string[];
+  notes?: string;
+  isActive?: boolean;
+  membership?: CustomerMembership | null;
+  defaultAddress?: CustomerAddress | null;
+  tier?: CustomerTier;
+  createdAt?: string;
+  updatedAt?: string;
+}
+interface CustomerPayload {
+  name?: string;
+  phone?: string;
+  email?: string;
+  dateOfBirth?: string;
+  gender?: CustomerGender;
+  addresses?: CustomerAddress[];
+  tags?: string[];
+  notes?: string;
+  isActive?: boolean;
+}
+interface CustomerQueryParams {
+  page?: number;
+  limit?: number;
+  after?: string;
+  sort?: string | Record<string, 1 | -1 | 'asc' | 'desc'>;
+  name?: string;
+  phone?: string;
+  email?: string;
+  userId?: string;
+  populate?: 'userId' | Array<'userId'> | string | string[];
+  [key: string]: unknown;
+}
+type CustomerListResponse = PaginatedResponse<Customer>;
+type CustomerResponse = ApiResponse<Customer>;
+//#endregion
+export { Customer, CustomerAddress, CustomerGender, CustomerListResponse, CustomerMembership, CustomerPayload, CustomerQueryParams, CustomerResponse, CustomerStats, CustomerTier };

package/dist/sales/types/earning-rules.d.ts

@@ -0,0 +1,75 @@
+import { ApiResponse } from "../../core/api-factory.js";
+
+//#region src/sales/types/earning-rules.d.ts
+type EarningRuleType = 'order' | 'action' | 'category' | 'tier_bonus';
+type EarningRuleStatus = 'active' | 'paused' | 'expired';
+interface EarningConditions {
+  minOrderAmount?: number;
+  categories?: string[];
+  tiers?: string[];
+  actions?: string[];
+  dayOfWeek?: number[];
+  dateRange?: {
+    start?: string;
+    end?: string;
+  };
+}
+interface EarningReward {
+  pointsPerAmount?: number;
+  amountPerPoint?: number;
+  fixedPoints?: number;
+  multiplier?: number;
+  roundingMode?: 'floor' | 'round' | 'ceil';
+  maxPointsPerTransaction?: number;
+}
+interface EarningRule {
+  _id: string;
+  programId: string;
+  name: string;
+  description?: string;
+  type: EarningRuleType;
+  status: EarningRuleStatus;
+  priority: number;
+  conditions: EarningConditions;
+  reward: EarningReward;
+  startsAt?: string;
+  endsAt?: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreateEarningRulePayload {
+  name: string;
+  type: EarningRuleType;
+  priority?: number;
+  conditions?: EarningConditions;
+  reward: EarningReward;
+  description?: string;
+  startsAt?: string;
+  endsAt?: string;
+}
+interface UpdateEarningRulePayload {
+  name?: string;
+  priority?: number;
+  conditions?: EarningConditions;
+  reward?: EarningReward;
+  description?: string;
+  startsAt?: string;
+  endsAt?: string;
+}
+interface EarningRuleListParams {
+  page?: number;
+  limit?: number;
+  status?: EarningRuleStatus;
+}
+type EarningRuleResponse = ApiResponse<EarningRule>;
+type EarningRuleListResponse = ApiResponse<{
+  docs: EarningRule[];
+  total: number;
+  page: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}>;
+//#endregion
+export { CreateEarningRulePayload, EarningConditions, EarningReward, EarningRule, EarningRuleListParams, EarningRuleListResponse, EarningRuleResponse, EarningRuleStatus, EarningRuleType, UpdateEarningRulePayload };

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

@@ -0,0 +1,8 @@
+import { AddCartItemPayload, AddToCartPayload, Cart, CartItem, CartItemVariation, CartResponse, CartSummary, PopulatedCartItem, RemoveCartItemPayload, UpdateCartItemPayload } from "./cart.js";
+import { 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 } from "./order.js";
+import { Customer, CustomerAddress, CustomerGender, CustomerListResponse, CustomerMembership, CustomerPayload, CustomerQueryParams, CustomerResponse, CustomerStats, CustomerTier } from "./customer.js";
+import { BranchStock, PaymentOption, PaymentState, PosCartItem, PosCustomer, PosLookupData, PosLookupProduct, PosLookupResponse, PosLookupResult, PosOrderItem, PosOrderPayload, PosPayment, PosPaymentMethod, PosProduct, PosProductsBranch, PosProductsParams, PosProductsResponse, PosProductsSummary, PosReceipt, PosReceiptData, PosReceiptItem, PosReceiptResponse, PosReceiptVat, SplitPaymentEntry, VariantStock } from "./pos.js";
+import { AdjustPointsPayload, AdjustPointsResponse, EnrollMemberPayload, LoyaltyBalance, LoyaltyBalanceSummary, LoyaltyHistoryParams, LoyaltyHistoryResponse, LoyaltyMember, LoyaltyMemberDetailResponse, LoyaltyMemberResponse, LoyaltyMemberStatus, LoyaltyMyStatusResponse, LoyaltyTransaction, LoyaltyTransactionType, Redemption, RedemptionStatus, RedemptionValidation, ReserveRedemptionPayload, ValidateRedemptionPayload } from "./loyalty.js";
+import { CreateEarningRulePayload, EarningConditions, EarningReward, EarningRule, EarningRuleListParams, EarningRuleListResponse, EarningRuleResponse, EarningRuleStatus, EarningRuleType, UpdateEarningRulePayload } from "./earning-rules.js";
+import { CreateTierPayload, TierBenefits, TierDefinition, TierDowngrade, TierEvaluationResponse, TierListResponse, TierQualification, TierResponse, UpdateTierPayload } from "./tiers.js";
+import { RecordReferralPayload, Referral, ReferralListParams, ReferralListResponse, ReferralLookupResponse, ReferralResponse, ReferralStatus, RejectReferralPayload, SelfReferralPayload } from "./referrals.js";

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

@@ -0,0 +1,120 @@
+import { ApiResponse } from "../../core/api-factory.js";
+
+//#region src/sales/types/loyalty.d.ts
+type LoyaltyMemberStatus = 'active' | 'inactive' | 'suspended';
+interface LoyaltyBalance {
+  current: number;
+  lifetime: number;
+  redeemed: number;
+  expired: number;
+}
+interface LoyaltyMember {
+  _id: string;
+  externalId: string;
+  externalType: string;
+  programId: string;
+  status: LoyaltyMemberStatus;
+  /** Public loyalty card identifier (e.g., MBR-DHK-00004821-8) */
+  cardId?: string;
+  /** Referral code for the referral system (separate from cardId) */
+  referralCode: string;
+  tier: string | null;
+  tierOverride: string | null;
+  tierOverrideReason?: string;
+  balance: LoyaltyBalance;
+  enrolledAt: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+}
+interface LoyaltyBalanceSummary extends LoyaltyBalance {
+  tier: string | null;
+  tierOverride: string | null;
+}
+type LoyaltyTransactionType = 'earn' | 'redeem' | 'adjust' | 'expire' | 'transfer' | 'referral_bonus';
+interface LoyaltyTransaction {
+  _id: string;
+  memberId: string;
+  programId: string;
+  type: LoyaltyTransactionType;
+  points: number;
+  balanceAfter: number;
+  description: string;
+  referenceType?: string;
+  referenceId?: string;
+  idempotencyKey?: string;
+  earningRuleId?: string;
+  actorId: string;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+}
+type RedemptionStatus = 'reserved' | 'confirmed' | 'released' | 'expired';
+interface RedemptionValidation {
+  valid: boolean;
+  error?: string;
+  pointsToRedeem: number;
+  discountAmount: number;
+  maxAllowedPoints: number;
+}
+interface Redemption {
+  _id: string;
+  memberId: string;
+  programId: string;
+  pointsReserved: number;
+  pointsConfirmed: number;
+  discountAmount: number;
+  conversionRate: number;
+  status: RedemptionStatus;
+  ownerType: string;
+  ownerId: string;
+  expiresAt?: string;
+  confirmedAt?: string;
+  releasedAt?: string;
+  createdAt: string;
+}
+interface EnrollMemberPayload {
+  customerId: string;
+}
+interface AdjustPointsPayload {
+  points: number;
+  reason: string;
+}
+interface ValidateRedemptionPayload {
+  pointsToRedeem: number;
+  orderTotal: number;
+}
+interface ReserveRedemptionPayload {
+  pointsToRedeem: number;
+  orderTotal: number;
+  ownerType: string;
+  ownerId: string;
+}
+interface LoyaltyHistoryParams {
+  page?: number;
+  limit?: number;
+  [key: string]: unknown;
+}
+type LoyaltyMemberResponse = ApiResponse<LoyaltyMember>;
+type LoyaltyMemberDetailResponse = ApiResponse<{
+  member: LoyaltyMember;
+  balance: LoyaltyBalanceSummary;
+}>;
+type LoyaltyHistoryResponse = ApiResponse<{
+  docs: LoyaltyTransaction[];
+  total: number;
+  page: number;
+  pages: number;
+  hasNext: boolean;
+  hasPrev: boolean;
+}>;
+type LoyaltyMyStatusResponse = ApiResponse<{
+  enrolled: boolean;
+  member?: LoyaltyMember;
+  balance?: LoyaltyBalanceSummary;
+}>;
+type AdjustPointsResponse = ApiResponse<{
+  transaction: LoyaltyTransaction;
+  balanceAfter: number;
+}>;
+//#endregion
+export { AdjustPointsPayload, AdjustPointsResponse, EnrollMemberPayload, LoyaltyBalance, LoyaltyBalanceSummary, LoyaltyHistoryParams, LoyaltyHistoryResponse, LoyaltyMember, LoyaltyMemberDetailResponse, LoyaltyMemberResponse, LoyaltyMemberStatus, LoyaltyMyStatusResponse, LoyaltyTransaction, LoyaltyTransactionType, Redemption, RedemptionStatus, RedemptionValidation, ReserveRedemptionPayload, ValidateRedemptionPayload };