tt-entities 0.0.32 → 0.0.34

package/libs/tatayab-entities-library/src/entities/order-item-bundle-selection.entity.ts

@@ -0,0 +1,38 @@
+import { Table, Column, Model, ForeignKey, BelongsTo } from 'sequelize-typescript';
+import { OrderItem } from './order-item.entity';
+import { Product } from './product.entity';
+import { ProductVariant } from './product-variant.entity';
+
+@Table
+export class OrderItemBundleSelection extends Model {
+  @ForeignKey(() => OrderItem)
+  @Column({ allowNull: false })
+  declare orderItemId: number;
+
+  @ForeignKey(() => Product)
+  @Column({ allowNull: false })
+  declare productId: number;
+
+  @ForeignKey(() => ProductVariant)
+  @Column({ allowNull: true })
+  declare productVariantId?: number;
+
+  @Column({ allowNull: true })
+  declare productNameEn?: string;
+
+  @Column({ allowNull: true })
+  declare productNameAr?: string;
+
+  @Column({ allowNull: true })
+  declare variantLabelEn?: string;
+
+  @Column({ allowNull: true })
+  declare variantLabelAr?: string;
+
+  @Column({ allowNull: false, defaultValue: 0 })
+  declare sortOrder: number;
+
+  @BelongsTo(() => OrderItem)  declare orderItem: OrderItem;
+  @BelongsTo(() => Product)    declare product: Product;
+  @BelongsTo(() => ProductVariant) declare variant?: ProductVariant;
+}

package/libs/tatayab-entities-library/src/entities/order-item.entity.ts

@@ -0,0 +1,132 @@
+import {
+  Table,
+  Column,
+  Model,
+  ForeignKey,
+  BelongsTo,
+  HasMany,
+  HasOne,
+  DataType,
+} from 'sequelize-typescript';
+import { Order } from './order.entity';
+import { Product } from './product.entity';
+import { ProductVariant } from './product-variant.entity';
+import { Bundle } from './bundle.entity';
+import { OrderItemBundleSelection } from './order-item-bundle-selection.entity';
+import { PurchaseOrderOrderItem } from './purchase-order-order-item.entity';
+
+export enum OrderItemType {
+  PRODUCT = 'product',
+  BUNDLE = 'bundle',
+}
+
+export enum OrderItemFulfillmentStatus {
+  PENDING = 'pending',
+  AWAITING_STOCK = 'awaiting_stock', // needs vendor PO
+  PO_LINKED = 'po_linked', // PO created and linked
+  PO_RECEIVED = 'po_received', // PO received for this item
+  STOCK_RESERVED = 'stock_reserved', // physical stock locked in inventory
+  PACKED = 'packed',
+  SHIPPED = 'shipped',
+  DELIVERED = 'delivered',
+  CANCELLED = 'cancelled',
+  RETURN_REQUESTED = 'return_requested',
+  RETURNED = 'returned',
+}
+
+@Table
+export class OrderItem extends Model {
+  @ForeignKey(() => Order)
+  @Column({ allowNull: false })
+  declare orderId: number;
+
+  @Column({
+    type: DataType.ENUM(...Object.values(OrderItemType)),
+    allowNull: false,
+    defaultValue: OrderItemType.PRODUCT,
+  })
+  declare itemType: OrderItemType;
+
+  // ── Product fields ────────────────────────────────────────────────────────────
+  @ForeignKey(() => Product)
+  @Column({ allowNull: true })
+  declare productId?: number;
+
+  @ForeignKey(() => ProductVariant)
+  @Column({ allowNull: true })
+  declare productVariantId?: number;
+
+  // ── Bundle fields ─────────────────────────────────────────────────────────────
+  @ForeignKey(() => Bundle)
+  @Column({ allowNull: true })
+  declare bundleId?: number;
+
+  @Column({ allowNull: true })
+  declare composedSku?: string;
+
+  // ── Snapshots at order time ───────────────────────────────────────────────────
+  @Column({ allowNull: true })
+  declare productNameEn?: string;
+
+  @Column({ allowNull: true })
+  declare productNameAr?: string;
+
+  @Column({ allowNull: true })
+  declare sku?: string;
+
+  @Column({ allowNull: true })
+  declare variantLabelEn?: string;
+
+  @Column({ allowNull: true })
+  declare variantLabelAr?: string;
+
+  @Column({ allowNull: true })
+  declare productImage?: string;
+
+  // ── Pricing ───────────────────────────────────────────────────────────────────
+  @Column({ allowNull: false, defaultValue: 1 })
+  declare quantity: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false })
+  declare unitPrice: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false })
+  declare lineTotal: number;
+
+  // ── Fulfillment assignment ────────────────────────────────────────────────────
+  // Which inventory is responsible for this item
+  @Column({ allowNull: true })
+  declare fulfillmentInventoryId?: number;
+
+  // Shipment group — items with the same group ship together from the same inventory
+  // Usually '1' for single-inventory orders; '2' if a second inventory is needed
+  @Column({ allowNull: false, defaultValue: 1 })
+  declare shipmentGroup: number;
+
+  @Column({
+    type: DataType.ENUM(...Object.values(OrderItemFulfillmentStatus)),
+    allowNull: false,
+    defaultValue: OrderItemFulfillmentStatus.PENDING,
+  })
+  declare fulfillmentStatus: OrderItemFulfillmentStatus;
+
+  // ── Associations ──────────────────────────────────────────────────────────────
+
+  @BelongsTo(() => Order)
+  declare order: Order;
+
+  @BelongsTo(() => Product)
+  declare product?: Product;
+
+  @BelongsTo(() => ProductVariant)
+  declare variant?: ProductVariant;
+
+  @BelongsTo(() => Bundle)
+  declare bundle?: Bundle;
+
+  @HasMany(() => OrderItemBundleSelection)
+  declare bundleSelections: OrderItemBundleSelection[];
+
+  @HasOne(() => PurchaseOrderOrderItem)
+  declare poLink?: PurchaseOrderOrderItem;
+}

package/libs/tatayab-entities-library/src/entities/order-status-history.entity.ts

@@ -0,0 +1,34 @@
+import {
+  Table, Column, Model, ForeignKey, BelongsTo, DataType,
+} from 'sequelize-typescript';
+import { Order } from './order.entity';
+
+@Table
+export class OrderStatusHistory extends Model {
+  @ForeignKey(() => Order)
+  @Column({ allowNull: false })
+  declare orderId: number;
+
+  @Column({ allowNull: true })
+  declare fromStatus?: string;
+
+  @Column({ allowNull: false })
+  declare toStatus: string;
+
+  // Bilingual label snapshots so history is readable even if status labels change
+  @Column({ allowNull: true })
+  declare toLabelEn?: string;
+
+  @Column({ allowNull: true })
+  declare toLabelAr?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare note?: string;
+
+  // Who made the change: 'system', 'user', or 'admin:<id>'
+  @Column({ allowNull: true })
+  declare changedBy?: string;
+
+  @BelongsTo(() => Order)
+  declare order: Order;
+}

package/libs/tatayab-entities-library/src/entities/order-status.entity.ts

@@ -0,0 +1,70 @@
+import {
+  Table, Column, Model, HasMany, DataType,
+} from 'sequelize-typescript';
+import { Order } from './order.entity';
+
+// All possible order statuses in the system
+export enum OrderStatusCode {
+  PENDING_PAYMENT      = 'pending_payment',
+  PAID                 = 'paid',
+  PROCESSING           = 'processing',
+  AWAITING_FULFILLMENT = 'awaiting_fulfillment',
+  PENDING_VENDOR       = 'pending_vendor',
+  VENDOR_ORDERED       = 'vendor_ordered',
+  STOCK_RECEIVED       = 'stock_received',
+  PACKED               = 'packed',
+  SHIPPED              = 'shipped',
+  OUT_FOR_DELIVERY     = 'out_for_delivery',
+  DELIVERED            = 'delivered',
+  COMPLETED            = 'completed',
+  CANCELLED            = 'cancelled',
+  RETURN_REQUESTED     = 'return_requested',
+  RETURN_APPROVED      = 'return_approved',
+  RETURNED             = 'returned',
+  REFUNDED             = 'refunded',
+  FAILED               = 'failed',
+}
+
+@Table
+export class OrderStatus extends Model {
+  @Column({ allowNull: false, unique: true })
+  declare code: string;
+
+  @Column({ allowNull: false })
+  declare labelEn: string;
+
+  @Column({ allowNull: false })
+  declare labelAr: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare descriptionEn?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare descriptionAr?: string;
+
+  @Column({ allowNull: true })
+  declare color?: string;
+
+  @Column({ allowNull: true })
+  declare icon?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare nextStatuses?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare prevStatuses?: string;
+
+  @Column({ allowNull: false, defaultValue: false })
+  declare isTerminal: boolean;
+
+  @Column({ allowNull: false, defaultValue: true })
+  declare isVisibleToUser: boolean;
+
+  @Column({ allowNull: false, defaultValue: 0 })
+  declare sortOrder: number;
+
+  // ─── Associations ─────────────────────────────────────────────────────────────
+
+  @HasMany(() => Order, { foreignKey: 'statusId' })
+  declare orders: Order[];
+}

package/libs/tatayab-entities-library/src/entities/order.entity.ts

@@ -0,0 +1,175 @@
+import {
+  Table, Column, Model, ForeignKey, BelongsTo,
+  HasMany, DataType,
+} from 'sequelize-typescript';
+import { User } from './user.entity';
+import { Store } from './store.entity';
+import { Country } from './country.entity';
+import { OrderStatus } from './order-status.entity';
+import { OrderItem } from './order-item.entity';
+import { OrderStatusHistory } from './order-status-history.entity';
+import { UserTransaction } from './user-transaction.entity';
+
+@Table
+export class Order extends Model {
+  // ── Identity ──────────────────────────────────────────────────────────────────
+  @Column({ allowNull: false, unique: true })
+  declare orderNumber: string; // e.g. TAT-2026-00001
+
+  // Null for guest orders — linked on account creation
+  @ForeignKey(() => User)
+  @Column({ allowNull: true })
+  declare userId?: number;
+
+  // Guest token for guest orders
+  @Column({ allowNull: true })
+  declare guestToken?: string;
+
+  @ForeignKey(() => Store)
+  @Column({ allowNull: false })
+  declare storeId: number;
+
+  // ── Status ────────────────────────────────────────────────────────────────────
+  // Proper FK to order_statuses so we can eager load with include: [OrderStatus]
+  @ForeignKey(() => OrderStatus)
+  @Column({ allowNull: false })
+  declare statusId: number;
+
+  // Keep statusCode as a convenience column — synced with statusId at all times
+  // Allows filtering by code string without a join: where({ statusCode: 'shipped' })
+  @Column({ allowNull: false, defaultValue: 'pending_payment' })
+  declare statusCode: string;
+
+  // ── Delivery address (snapshot at order time) ─────────────────────────────────
+  @ForeignKey(() => Country)
+  @Column({ allowNull: true })
+  declare deliveryCountryId?: number;
+
+  @Column({ allowNull: true })
+  declare deliveryFullName?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryPhoneExt?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryPhone?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryCity?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryBlock?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryStreet?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryBuilding?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryFloor?: string;
+
+  @Column({ allowNull: true })
+  declare deliveryApartment?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare deliveryAdditionalInfo?: string;
+
+  @Column({ type: DataType.DECIMAL(9, 6), allowNull: true })
+  declare deliveryLatitude?: number;
+
+  @Column({ type: DataType.DECIMAL(9, 6), allowNull: true })
+  declare deliveryLongitude?: number;
+
+  // ── Financials (all in store currency) ────────────────────────────────────────
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare subtotal: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare shippingFee: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare vatAmount: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare discountAmount: number;
+
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare total: number;
+
+  // Currency snapshot
+  @Column({ allowNull: false })
+  declare currency: string;
+
+  @Column({ allowNull: true })
+  declare currencySymbolEn?: string;
+
+  // ── Coupon ────────────────────────────────────────────────────────────────────
+  @Column({ allowNull: true })
+  declare couponCode?: string;
+
+  @Column({ allowNull: true })
+  declare couponId?: number;
+
+  // ── Payment ───────────────────────────────────────────────────────────────────
+  @Column({ allowNull: true })
+  declare paymentMethodSlug?: string;
+
+  @Column({ allowNull: true })
+  declare paymentStatus?: string; // pending | paid | failed | refunded
+
+  @Column({ allowNull: true })
+  declare paymentReference?: string; // Gateway transaction ID
+
+  @Column({ type: DataType.DATE, allowNull: true })
+  declare paidAt?: Date;
+
+  // ── Shipping ─────────────────────────────────────────────────────────────────
+  @Column({ allowNull: true })
+  declare carrierName?: string;
+
+  @Column({ allowNull: true })
+  declare trackingNumber?: string;
+
+  @Column({ allowNull: true })
+  declare trackingUrl?: string;
+
+  @Column({ type: DataType.DATE, allowNull: true })
+  declare estimatedDeliveryDate?: Date;
+
+  @Column({ type: DataType.DATE, allowNull: true })
+  declare shippedAt?: Date;
+
+  @Column({ type: DataType.DATE, allowNull: true })
+  declare deliveredAt?: Date;
+
+  // ── Notes ─────────────────────────────────────────────────────────────────────
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare customerNotes?: string;
+
+  @Column({ type: DataType.TEXT, allowNull: true })
+  declare internalNotes?: string;
+
+  // ── Associations ──────────────────────────────────────────────────────────────
+
+  @BelongsTo(() => User)
+  declare user?: User;
+
+  @BelongsTo(() => Store)
+  declare store: Store;
+
+  @BelongsTo(() => OrderStatus, { foreignKey: 'statusId' })
+  declare status: OrderStatus;
+
+  @BelongsTo(() => Country)
+  declare deliveryCountry?: Country;
+
+  @HasMany(() => OrderItem)
+  declare items: OrderItem[];
+
+  @HasMany(() => OrderStatusHistory)
+  declare statusHistory: OrderStatusHistory[];
+
+  @HasMany(() => UserTransaction)
+  declare transactions: UserTransaction[];
+}

package/libs/tatayab-entities-library/src/entities/purchase-order-order-item.entity.ts

@@ -0,0 +1,38 @@
+import {
+  Table, Column, Model, ForeignKey, BelongsTo, DataType,
+} from 'sequelize-typescript';
+import { PurchaseOrder } from './purchase-order.entity';
+import { PurchaseOrderItem } from './purchase-order-item.entity';
+import { OrderItem } from './order-item.entity';
+import { Order } from './order.entity';
+
+// Junction table: links a PO item to the order item(s) it will fulfill
+// One PO item can cover items from multiple orders
+// One order item is linked to exactly one PO item
+@Table
+export class PurchaseOrderOrderItem extends Model {
+  @ForeignKey(() => PurchaseOrder)
+  @Column({ allowNull: false })
+  declare purchaseOrderId: number;
+
+  @ForeignKey(() => PurchaseOrderItem)
+  @Column({ allowNull: false })
+  declare purchaseOrderItemId: number;
+
+  @ForeignKey(() => Order)
+  @Column({ allowNull: false })
+  declare orderId: number;
+
+  @ForeignKey(() => OrderItem)
+  @Column({ allowNull: false })
+  declare orderItemId: number;
+
+  // How many units of this PO item are allocated to this order item
+  @Column({ allowNull: false, defaultValue: 1 })
+  declare allocatedQuantity: number;
+
+  @BelongsTo(() => PurchaseOrder)     declare purchaseOrder: PurchaseOrder;
+  @BelongsTo(() => PurchaseOrderItem) declare purchaseOrderItem: PurchaseOrderItem;
+  @BelongsTo(() => Order)             declare order: Order;
+  @BelongsTo(() => OrderItem)         declare orderItem: OrderItem;
+}

package/libs/tatayab-entities-library/src/entities/user-transaction.entity.ts

@@ -0,0 +1,81 @@
+import {
+  Table, Column, Model, ForeignKey, BelongsTo, DataType,
+} from 'sequelize-typescript';
+import { User } from './user.entity';
+import { Order } from './order.entity';
+
+export enum TransactionType {
+  DEBIT  = 'debit',   // money leaves user balance
+  CREDIT = 'credit',  // money enters user balance
+}
+
+export enum TransactionCategory {
+  ORDER_PAYMENT      = 'order_payment',      // DEBIT: paid for order
+  ORDER_REFUND       = 'order_refund',       // CREDIT: refund received
+  GIFT_SENT          = 'gift_sent',          // DEBIT: sent gift to someone
+  GIFT_RECEIVED      = 'gift_received',      // CREDIT: received a gift
+  BALANCE_TOP_UP     = 'balance_top_up',     // CREDIT: topped up wallet
+  BALANCE_WITHDRAWAL = 'balance_withdrawal', // DEBIT: withdrew balance
+  COUPON_CREDIT      = 'coupon_credit',      // CREDIT: coupon cashback
+  ADJUSTMENT         = 'adjustment',         // DEBIT or CREDIT: manual admin adjustment
+  CASHBACK           = 'cashback',           // CREDIT: loyalty cashback
+}
+
+@Table
+export class UserTransaction extends Model {
+  @ForeignKey(() => User)
+  @Column({ allowNull: false })
+  declare userId: number;
+
+  @Column({
+    type: DataType.ENUM(...Object.values(TransactionType)),
+    allowNull: false,
+  })
+  declare type: TransactionType;
+
+  @Column({
+    type: DataType.ENUM(...Object.values(TransactionCategory)),
+    allowNull: false,
+  })
+  declare category: TransactionCategory;
+
+  // Transaction amount (always positive — type determines direction)
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false })
+  declare amount: number;
+
+  // Running balance AFTER this transaction
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare balanceAfter: number;
+
+  // Currency of the transaction
+  @Column({ allowNull: false, defaultValue: 'KWD' })
+  declare currency: string;
+
+  // Bilingual description shown in the app
+  @Column({ allowNull: false })
+  declare descriptionEn: string;
+
+  @Column({ allowNull: false })
+  declare descriptionAr: string;
+
+  // Reference to the related order (if applicable)
+  @ForeignKey(() => Order)
+  @Column({ allowNull: true })
+  declare orderId?: number;
+
+  // External reference (payment gateway transaction ID, etc.)
+  @Column({ allowNull: true })
+  declare externalReference?: string;
+
+  // Status: pending | completed | failed | reversed
+  @Column({ allowNull: false, defaultValue: 'completed' })
+  declare status: string;
+
+  // ── Associations ──────────────────────────────────────────────────────────────
+
+  @BelongsTo(() => User)
+  declare user: User;
+
+  @BelongsTo(() => Order)
+  declare order?: Order;
+}

package/libs/tatayab-entities-library/src/entities/user.entity.ts

@@ -13,6 +13,9 @@ import { Country } from './country.entity';
 import { Gender } from '../utils/enums/gender';
 import { UserAddress } from './user-address.entity';
 import { UserFavorite } from './user-favorite.entity';
+import { Cart } from './cart.entity';
+import { Order } from './order.entity';
+import { UserTransaction } from './user-transaction.entity';
 
 @Table
 export class User extends Model {
@@ -83,6 +86,9 @@ export class User extends Model {
   })
   declare gender: Gender;
 
+  @Column({ type: DataType.DECIMAL(10, 3), allowNull: false, defaultValue: 0 })
+  declare walletBalance: number;
+
   @BelongsTo(() => Country)
   declare country: Country;
 
@@ -91,4 +97,13 @@ export class User extends Model {
 
   @HasMany(() => UserFavorite)
   declare favorites: UserFavorite[];
+
+  @HasMany(() => Cart)
+  declare carts: Cart[];
+
+  @HasMany(() => Order)
+  declare orders: Order[];
+
+  @HasMany(() => UserTransaction)
+  declare transactions: UserTransaction[];
 }

package/libs/tatayab-entities-library/src/index.ts

@@ -64,6 +64,16 @@ import { CouponStore } from './entities/coupon-store.entity';
 import { CouponProduct } from './entities/coupon-product.entity';
 import { CouponUser } from './entities/coupon-user.entity';
 
+// ─── Orders ───────────────────────────────────────────────────────────────────
+import { OrderStatus } from './entities/order-status.entity';
+import { Order } from './entities/order.entity';
+import { OrderItem } from './entities/order-item.entity';
+import { OrderItemBundleSelection } from './entities/order-item-bundle-selection.entity';
+import { OrderStatusHistory } from './entities/order-status-history.entity';
+import { UserTransaction } from './entities/user-transaction.entity';
+import { PurchaseOrderOrderItem } from './entities/purchase-order-order-item.entity';
+
+
 // =============================================================================
 // EXPORTS
 // =============================================================================
@@ -147,6 +157,24 @@ export { CouponStore } from './entities/coupon-store.entity';
 export { CouponProduct } from './entities/coupon-product.entity';
 export { CouponUser } from './entities/coupon-user.entity';
 
+// ─── Orders ───────────────────────────────────────────────────────────────────
+export { OrderStatus, OrderStatusCode } from './entities/order-status.entity';
+export { Order } from './entities/order.entity';
+export {
+  OrderItem,
+  OrderItemType,
+  OrderItemFulfillmentStatus,
+} from './entities/order-item.entity';
+export { OrderItemBundleSelection } from './entities/order-item-bundle-selection.entity';
+export { OrderStatusHistory } from './entities/order-status-history.entity';
+export {
+  UserTransaction,
+  TransactionType,
+  TransactionCategory,
+} from './entities/user-transaction.entity';
+export { PurchaseOrderOrderItem } from './entities/purchase-order-order-item.entity';
+
+
 // ─── Enums ────────────────────────────────────────────────────────────────────
 export { OsName } from './utils/enums/osName';
 export { ProductApp } from './utils/enums/productApp';
@@ -226,5 +254,14 @@ export function getDbModels(): ModelCtor[] {
     CouponStore,
     CouponProduct,
     CouponUser,
+
+    // Orders
+    OrderStatus,
+    Order,
+    OrderItem,
+    OrderItemBundleSelection,
+    OrderStatusHistory,
+    UserTransaction,
+    PurchaseOrderOrderItem,
   ];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tt-entities",
-  "version": "0.0.32",
+  "version": "0.0.34",
   "description": "Tatayab entities library",
   "main": "dist/libs/tatayab-entities-library/index.js",
   "types": "dist/libs/tatayab-entities-library/index.d.ts",