@axova/shared 1.0.2 → 1.1.0

package/src/schemas/order/cart-schema.ts

@@ -0,0 +1,652 @@
+import { createId } from "@paralleldrive/cuid2";
+import { relations } from "drizzle-orm";
+import {
+	boolean,
+	decimal,
+	index,
+	integer,
+	jsonb,
+	pgEnum,
+	pgTable,
+	text,
+	timestamp,
+	unique,
+	varchar,
+} from "drizzle-orm/pg-core";
+
+// =====================================================
+// CART ENUMS
+// =====================================================
+
+export const cartStatusEnum = pgEnum("cart_status", [
+	"ACTIVE",
+	"ABANDONED",
+	"CONVERTED",
+	"EXPIRED",
+	"MERGED",
+	"ARCHIVED",
+]);
+
+export const cartTypeEnum = pgEnum("cart_type", [
+	"STANDARD",
+	"WISHLIST",
+	"SAVE_FOR_LATER",
+	"QUOTE",
+	"SUBSCRIPTION",
+	"RECURRING",
+]);
+
+// =====================================================
+// SHOPPING CARTS TABLE
+// =====================================================
+
+export const shoppingCarts = pgTable(
+	"shopping_carts",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+
+		// Ownership
+		storeId: text("store_id").notNull(),
+		customerId: text("customer_id"), // Null for guest carts
+		userId: text("user_id"),
+		sessionId: text("session_id").notNull(), // Browser/device session
+		deviceFingerprint: text("device_fingerprint"),
+
+		// Cart Classification
+		cartType: cartTypeEnum("cart_type").notNull().default("STANDARD"),
+		status: cartStatusEnum("status").notNull().default("ACTIVE"),
+		isGuestCart: boolean("is_guest_cart").notNull().default(false),
+		isCheckoutStarted: boolean("is_checkout_started").notNull().default(false),
+
+		// Contact Information (for guest carts)
+		guestEmail: varchar("guest_email", { length: 255 }),
+		guestPhone: varchar("guest_phone", { length: 20 }),
+		guestName: varchar("guest_name", { length: 100 }),
+
+		// Financial Information
+		currency: varchar("currency", { length: 3 }).notNull().default("USD"),
+		
+		// Calculated Amounts
+		subtotalAmount: decimal("subtotal_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+		taxAmount: decimal("tax_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+		shippingAmount: decimal("shipping_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+		discountAmount: decimal("discount_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+		totalAmount: decimal("total_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+
+		// Item Summary
+		itemCount: integer("item_count").notNull().default(0),
+		totalQuantity: integer("total_quantity").notNull().default(0),
+
+		// Discount and Promotion
+		appliedCoupons: jsonb("applied_coupons").$type<
+			Array<{
+				code: string;
+				discountAmount: string;
+				discountType: string;
+			}>
+		>().default([]),
+		availableDiscounts: jsonb("available_discounts").$type<
+			Array<{
+				id: string;
+				title: string;
+				description?: string;
+				discountAmount: string;
+			}>
+		>().default([]),
+
+		// Shipping Information
+		selectedShippingMethod: jsonb("selected_shipping_method").$type<{
+			id?: string;
+			name?: string;
+			cost?: string;
+			estimatedDays?: number;
+		}>(),
+		shippingAddressId: text("shipping_address_id"),
+		billingAddressId: text("billing_address_id"),
+
+		// Checkout Progress
+		checkoutStep: varchar("checkout_step", { length: 50 }).$type<
+			| "CART"
+			| "SHIPPING"
+			| "PAYMENT"
+			| "REVIEW"
+			| "CONFIRMATION"
+		>().default("CART"),
+		checkoutStartedAt: timestamp("checkout_started_at", { withTimezone: true }),
+		checkoutCompletedAt: timestamp("checkout_completed_at", {
+			withTimezone: true,
+		}),
+
+		// Conversion Tracking
+		convertedOrderId: text("converted_order_id"),
+		conversionRate: decimal("conversion_rate", { precision: 5, scale: 2 }),
+
+		// Abandonment Tracking
+		abandonedAt: timestamp("abandoned_at", { withTimezone: true }),
+		abandonmentReason: varchar("abandonment_reason", { length: 100 }).$type<
+			| "PRICE_TOO_HIGH"
+			| "UNEXPECTED_COSTS"
+			| "COMPLEX_CHECKOUT"
+			| "PAYMENT_ISSUES"
+			| "BROWSING_ONLY"
+			| "FOUND_BETTER_DEAL"
+			| "SECURITY_CONCERNS"
+			| "TECHNICAL_ISSUES"
+			| "UNKNOWN"
+		>(),
+		recoveryEmailSent: boolean("recovery_email_sent")
+			.notNull()
+			.default(false),
+		recoveryEmailSentAt: timestamp("recovery_email_sent_at", {
+			withTimezone: true,
+		}),
+		recoveryEmailCount: integer("recovery_email_count").notNull().default(0),
+		isRecovered: boolean("is_recovered").notNull().default(false),
+		recoveredAt: timestamp("recovered_at", { withTimezone: true }),
+
+		// Expiration and Cleanup
+		expiresAt: timestamp("expires_at", { withTimezone: true }),
+		autoExpireDays: integer("auto_expire_days").notNull().default(30),
+
+		// Marketing Attribution
+		referrerUrl: text("referrer_url"),
+		utmSource: varchar("utm_source", { length: 100 }),
+		utmMedium: varchar("utm_medium", { length: 100 }),
+		utmCampaign: varchar("utm_campaign", { length: 100 }),
+		affiliateId: text("affiliate_id"),
+
+		// Technical Information
+		userAgent: text("user_agent"),
+		ipAddress: varchar("ip_address", { length: 45 }),
+		browserInfo: jsonb("browser_info").$type<{
+			name?: string;
+			version?: string;
+			platform?: string;
+			language?: string;
+		}>(),
+		deviceInfo: jsonb("device_info").$type<{
+			type?: string;
+			brand?: string;
+			model?: string;
+			os?: string;
+		}>(),
+
+		// Cart Rules and Validation
+		validationErrors: jsonb("validation_errors").$type<
+			Array<{
+				field: string;
+				message: string;
+				code: string;
+			}>
+		>().default([]),
+		minimumOrderMet: boolean("minimum_order_met").notNull().default(true),
+		stockAvailable: boolean("stock_available").notNull().default(true),
+
+		// Special Features
+		isGiftCart: boolean("is_gift_cart").notNull().default(false),
+		giftMessage: text("gift_message"),
+		notes: text("notes"),
+		customerNotes: text("customer_notes"),
+		internalNotes: text("internal_notes"),
+
+		// Merge Tracking
+		mergedFromCartId: text("merged_from_cart_id"),
+		mergedToCartId: text("merged_to_cart_id"),
+		mergedAt: timestamp("merged_at", { withTimezone: true }),
+
+		// Analytics and Insights
+		totalViewTime: integer("total_view_time").notNull().default(0), // seconds
+		modificationsCount: integer("modifications_count").notNull().default(0),
+		lastModifiedBy: varchar("last_modified_by", { length: 50 }).$type<
+			"CUSTOMER" | "ADMIN" | "SYSTEM" | "AUTOMATION"
+		>(),
+
+		// Custom Fields
+		customFields: jsonb("custom_fields")
+			.$type<Record<string, unknown>>()
+			.default({}),
+		metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+		tags: jsonb("tags").$type<string[]>().default([]),
+
+		// Timestamps
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		lastActivityAt: timestamp("last_activity_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		deletedAt: timestamp("deleted_at", { withTimezone: true }),
+	},
+	(table) => ({
+		// Primary Indexes
+		sessionIndex: index("idx_carts_session").on(table.sessionId),
+		customerIndex: index("idx_carts_customer").on(table.customerId),
+		userIndex: index("idx_carts_user").on(table.userId),
+		guestEmailIndex: index("idx_carts_guest_email").on(table.guestEmail),
+
+		// Status and Type Indexes
+		statusIndex: index("idx_carts_status").on(table.status),
+		cartTypeIndex: index("idx_carts_type").on(table.cartType),
+		guestCartIndex: index("idx_carts_guest").on(table.isGuestCart),
+
+		// Store Indexes
+		storeIndex: index("idx_carts_store").on(table.storeId),
+
+		// Conversion Tracking
+		convertedOrderIndex: index("idx_carts_converted_order").on(
+			table.convertedOrderId,
+		),
+		checkoutStartedIndex: index("idx_carts_checkout_started").on(
+			table.isCheckoutStarted,
+		),
+
+		// Abandonment Tracking
+		abandonedIndex: index("idx_carts_abandoned").on(table.abandonedAt),
+		recoveryIndex: index("idx_carts_recovery").on(table.recoveryEmailSent),
+
+		// Expiration
+		expiresAtIndex: index("idx_carts_expires_at").on(table.expiresAt),
+
+		// Activity Tracking
+		lastActivityIndex: index("idx_carts_last_activity").on(
+			table.lastActivityAt,
+		),
+		createdAtIndex: index("idx_carts_created_at").on(table.createdAt),
+
+		// Composite Indexes
+		storeStatusIndex: index("idx_carts_store_status").on(
+			table.storeId,
+			table.status,
+		),
+		storeCustomerIndex: index("idx_carts_store_customer").on(
+			table.storeId,
+			table.customerId,
+		),
+		sessionStoreIndex: index("idx_carts_session_store").on(
+			table.sessionId,
+			table.storeId,
+		),
+		customerStatusIndex: index("idx_carts_customer_status").on(
+			table.customerId,
+			table.status,
+		),
+
+		// Unique Constraints
+		activeCartPerSession: unique("unq_active_cart_session").on(
+			table.sessionId,
+			table.storeId,
+			table.status,
+		),
+	}),
+);
+
+// =====================================================
+// CART ITEMS TABLE
+// =====================================================
+
+export const cartItems = pgTable(
+	"cart_items",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+
+		cartId: text("cart_id")
+			.notNull()
+			.references(() => shoppingCarts.id, { onDelete: "cascade" }),
+
+		// Product Information
+		productId: text("product_id").notNull(),
+		variantId: text("variant_id"),
+		sku: varchar("sku", { length: 100 }).notNull(),
+		productHandle: varchar("product_handle", { length: 255 }),
+
+		// Product Details (snapshot)
+		productTitle: varchar("product_title", { length: 255 }).notNull(),
+		variantTitle: varchar("variant_title", { length: 255 }),
+		productType: varchar("product_type", { length: 50 }),
+		vendor: varchar("vendor", { length: 100 }),
+		productImage: text("product_image"),
+
+		// Quantity and Availability
+		quantity: integer("quantity").notNull().default(1),
+		availableQuantity: integer("available_quantity"),
+		isInStock: boolean("is_in_stock").notNull().default(true),
+		isBackordered: boolean("is_backordered").notNull().default(false),
+		estimatedRestockDate: timestamp("estimated_restock_date", {
+			withTimezone: true,
+		}),
+
+		// Pricing
+		unitPrice: decimal("unit_price", { precision: 12, scale: 2 }).notNull(),
+		compareAtPrice: decimal("compare_at_price", { precision: 12, scale: 2 }),
+		salePrice: decimal("sale_price", { precision: 12, scale: 2 }),
+		lineTotal: decimal("line_total", { precision: 12, scale: 2 }).notNull(),
+
+		// Discounts
+		discountAmount: decimal("discount_amount", { precision: 12, scale: 2 })
+			.notNull()
+			.default("0.00"),
+		appliedDiscounts: jsonb("applied_discounts").$type<
+			Array<{
+				id: string;
+				title: string;
+				discountAmount: string;
+			}>
+		>().default([]),
+
+		// Product Options and Customization
+		selectedOptions: jsonb("selected_options").$type<
+			Record<string, string>
+		>().default({}),
+		customization: jsonb("customization").$type<{
+			personalization?: string;
+			engraving?: string;
+			specialRequests?: string;
+			giftWrap?: boolean;
+			giftMessage?: string;
+		}>(),
+
+		// Subscription Information
+		isSubscription: boolean("is_subscription").notNull().default(false),
+		subscriptionFrequency: varchar("subscription_frequency", { length: 20 }),
+		subscriptionDiscount: decimal("subscription_discount", {
+			precision: 5,
+			scale: 2,
+		}),
+
+		// Item Flags
+		isGiftWrap: boolean("is_gift_wrap").notNull().default(false),
+		requiresShipping: boolean("requires_shipping").notNull().default(true),
+		isDigital: boolean("is_digital").notNull().default(false),
+		isFreeShipping: boolean("is_free_shipping").notNull().default(false),
+
+		// Inventory Location
+		inventoryLocationId: text("inventory_location_id"),
+		warehouseId: text("warehouse_id"),
+
+		// Product Snapshot (preserve data)
+		productSnapshot: jsonb("product_snapshot").$type<{
+			images?: string[];
+			description?: string;
+			attributes?: Record<string, unknown>;
+			categories?: string[];
+			weight?: number;
+			dimensions?: { length: number; width: number; height: number };
+		}>(),
+
+		// Validation
+		hasErrors: boolean("has_errors").notNull().default(false),
+		validationErrors: jsonb("validation_errors").$type<
+			Array<{
+				field: string;
+				message: string;
+			}>
+		>().default([]),
+
+		// Tracking
+		addedBy: varchar("added_by", { length: 50 }).$type<
+			"CUSTOMER" | "ADMIN" | "RECOMMENDATION" | "UPSELL" | "CROSS_SELL"
+		>().default("CUSTOMER"),
+		source: varchar("source", { length: 50 }).$type<
+			| "PRODUCT_PAGE"
+			| "CATEGORY"
+			| "SEARCH"
+			| "RECOMMENDATION"
+			| "WISHLIST"
+			| "QUICK_ADD"
+			| "ADMIN"
+		>().default("PRODUCT_PAGE"),
+
+		// Save for Later
+		savedForLater: boolean("saved_for_later").notNull().default(false),
+		savedForLaterAt: timestamp("saved_for_later_at", { withTimezone: true }),
+
+		// Notes
+		itemNotes: text("item_notes"),
+		
+		// Analytics
+		viewCount: integer("view_count").notNull().default(0),
+		lastViewedAt: timestamp("last_viewed_at", { withTimezone: true }),
+
+		// Timestamps
+		addedAt: timestamp("added_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		// Foreign Key Indexes
+		cartIdIndex: index("idx_cart_items_cart_id").on(table.cartId),
+		productIdIndex: index("idx_cart_items_product_id").on(table.productId),
+		variantIdIndex: index("idx_cart_items_variant_id").on(table.variantId),
+		skuIndex: index("idx_cart_items_sku").on(table.sku),
+
+		// Inventory
+		inventoryLocationIndex: index("idx_cart_items_inventory_location").on(
+			table.inventoryLocationId,
+		),
+		warehouseIndex: index("idx_cart_items_warehouse").on(table.warehouseId),
+
+		// Stock Status
+		inStockIndex: index("idx_cart_items_in_stock").on(table.isInStock),
+		backorderedIndex: index("idx_cart_items_backordered").on(
+			table.isBackordered,
+		),
+
+		// Item Flags
+		savedForLaterIndex: index("idx_cart_items_saved_for_later").on(
+			table.savedForLater,
+		),
+		subscriptionIndex: index("idx_cart_items_subscription").on(
+			table.isSubscription,
+		),
+
+		// Composite Indexes
+		cartProductIndex: index("idx_cart_items_cart_product").on(
+			table.cartId,
+			table.productId,
+		),
+		cartSkuIndex: index("idx_cart_items_cart_sku").on(table.cartId, table.sku),
+
+		// Unique Constraint - prevent duplicate items in same cart
+		uniqueCartProduct: unique("unq_cart_product_variant").on(
+			table.cartId,
+			table.productId,
+			table.variantId,
+		),
+	}),
+);
+
+// =====================================================
+// CART ADDRESSES TABLE
+// =====================================================
+
+export const cartAddresses = pgTable(
+	"cart_addresses",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+
+		cartId: text("cart_id")
+			.notNull()
+			.references(() => shoppingCarts.id, { onDelete: "cascade" }),
+
+		addressType: varchar("address_type", { length: 20 })
+			.notNull()
+			.$type<"SHIPPING" | "BILLING">(),
+
+		// Contact Information
+		firstName: varchar("first_name", { length: 100 }),
+		lastName: varchar("last_name", { length: 100 }),
+		company: varchar("company", { length: 100 }),
+		email: varchar("email", { length: 255 }),
+		phone: varchar("phone", { length: 20 }),
+
+		// Address Information
+		address1: varchar("address1", { length: 255 }).notNull(),
+		address2: varchar("address2", { length: 255 }),
+		city: varchar("city", { length: 100 }).notNull(),
+		province: varchar("province", { length: 100 }),
+		provinceCode: varchar("province_code", { length: 10 }),
+		country: varchar("country", { length: 100 }).notNull(),
+		countryCode: varchar("country_code", { length: 2 }).notNull(),
+		postalCode: varchar("postal_code", { length: 20 }),
+
+		// Validation
+		isValidated: boolean("is_validated").notNull().default(false),
+		isResidential: boolean("is_residential").notNull().default(true),
+
+		// Delivery Preferences
+		deliveryInstructions: text("delivery_instructions"),
+		isDefaultShipping: boolean("is_default_shipping").notNull().default(false),
+		isDefaultBilling: boolean("is_default_billing").notNull().default(false),
+
+		// Timestamps
+		createdAt: timestamp("created_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+		updatedAt: timestamp("updated_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		cartIdIndex: index("idx_cart_addresses_cart_id").on(table.cartId),
+		addressTypeIndex: index("idx_cart_addresses_type").on(table.addressType),
+
+		// Ensure one address per type per cart
+		uniqueCartAddressType: unique("unq_cart_address_type").on(
+			table.cartId,
+			table.addressType,
+		),
+	}),
+);
+
+// =====================================================
+// CART ACTIVITY LOG TABLE
+// =====================================================
+
+export const cartActivityLog = pgTable(
+	"cart_activity_log",
+	{
+		id: text("id")
+			.primaryKey()
+			.$defaultFn(() => createId()),
+
+		cartId: text("cart_id")
+			.notNull()
+			.references(() => shoppingCarts.id, { onDelete: "cascade" }),
+
+		// Activity Information
+		activityType: varchar("activity_type", { length: 50 })
+			.notNull()
+			.$type<
+				| "CREATED"
+				| "ITEM_ADDED"
+				| "ITEM_REMOVED"
+				| "ITEM_UPDATED"
+				| "QUANTITY_CHANGED"
+				| "COUPON_APPLIED"
+				| "COUPON_REMOVED"
+				| "CHECKOUT_STARTED"
+				| "CHECKOUT_COMPLETED"
+				| "ABANDONED"
+				| "RECOVERED"
+				| "MERGED"
+				| "EXPIRED"
+				| "SAVED_FOR_LATER"
+				| "MOVED_FROM_SAVED"
+			>(),
+
+		// Details
+		activityDetails: jsonb("activity_details")
+			.$type<Record<string, unknown>>()
+			.default({}),
+		itemId: text("item_id"), // Reference to cart item if applicable
+		productId: text("product_id"),
+		variantId: text("variant_id"),
+
+		// Change Tracking
+		previousValue: jsonb("previous_value").$type<unknown>(),
+		newValue: jsonb("new_value").$type<unknown>(),
+
+		// Actor Information
+		actorType: varchar("actor_type", { length: 20 })
+			.notNull()
+			.$type<"CUSTOMER" | "ADMIN" | "SYSTEM" | "AUTOMATION">(),
+		actorId: text("actor_id"),
+
+		// Context
+		sessionId: text("session_id"),
+		ipAddress: varchar("ip_address", { length: 45 }),
+		userAgent: text("user_agent"),
+
+		// Timestamps
+		occurredAt: timestamp("occurred_at", { withTimezone: true })
+			.defaultNow()
+			.notNull(),
+	},
+	(table) => ({
+		cartIdIndex: index("idx_cart_activity_cart_id").on(table.cartId),
+		activityTypeIndex: index("idx_cart_activity_type").on(table.activityType),
+		productIdIndex: index("idx_cart_activity_product").on(table.productId),
+		occurredAtIndex: index("idx_cart_activity_occurred_at").on(
+			table.occurredAt,
+		),
+
+		// Composite Indexes
+		cartActivityIndex: index("idx_cart_activity_cart_type").on(
+			table.cartId,
+			table.activityType,
+		),
+	}),
+);
+
+// =====================================================
+// RELATIONS
+// =====================================================
+
+export const shoppingCartsRelations = relations(shoppingCarts, ({ many }) => ({
+	items: many(cartItems),
+	addresses: many(cartAddresses),
+	activityLog: many(cartActivityLog),
+}));
+
+export const cartItemsRelations = relations(cartItems, ({ one }) => ({
+	cart: one(shoppingCarts, {
+		fields: [cartItems.cartId],
+		references: [shoppingCarts.id],
+	}),
+}));
+
+export const cartAddressesRelations = relations(cartAddresses, ({ one }) => ({
+	cart: one(shoppingCarts, {
+		fields: [cartAddresses.cartId],
+		references: [shoppingCarts.id],
+	}),
+}));
+
+export const cartActivityLogRelations = relations(cartActivityLog, ({ one }) => ({
+	cart: one(shoppingCarts, {
+		fields: [cartActivityLog.cartId],
+		references: [shoppingCarts.id],
+	}),
+}));