@axova/shared 1.0.0

package/src/interfaces/order-events.ts

@@ -0,0 +1,381 @@
+// Order Service Event Interfaces
+
+// Service Configuration
+export interface OrderServiceConfig {
+	serviceName: string;
+	version: string;
+	kafkaTopics: {
+		orderCreated: string;
+		orderUpdated: string;
+		orderStatusChanged: string;
+		orderPaymentProcessed: string;
+		orderShipped: string;
+		orderDelivered: string;
+		orderCancelled: string;
+		orderRefunded: string;
+		orderNoteAdded: string;
+		orderItemAdded: string;
+		orderItemRemoved: string;
+		orderDiscountApplied: string;
+	};
+	features: {
+		multiOrderTypes: boolean;
+		advancedPayments: boolean;
+		realTimeTracking: boolean;
+		inventoryIntegration: boolean;
+		advancedDiscounts: boolean;
+		fraudDetection: boolean;
+		subscriptionSupport: boolean;
+		marketplaceIntegration: boolean;
+	};
+	limits: {
+		maxOrderValue: number;
+		maxItemsPerOrder: number;
+		maxAddressesPerOrder: number;
+		maxNotesPerOrder: number;
+		orderRetentionDays: number;
+	};
+}
+
+// Order Event Payloads
+export interface OrderCreatedEvent {
+	orderId: string;
+	orderNumber: string;
+	storeId: string;
+	customerId?: string;
+	userId?: string;
+	orderType: string;
+	orderSource: string;
+	status: string;
+	totalAmount: string;
+	currency: string;
+	itemCount: number;
+	isGuestOrder: boolean;
+	paymentMethod?: string;
+	shippingRequired: boolean;
+	priority: string;
+}
+
+export interface OrderUpdatedEvent {
+	orderId: string;
+	orderNumber: string;
+	storeId: string;
+	customerId?: string;
+	changes: Record<string, unknown>;
+	previousValues: Record<string, unknown>;
+	statusChanged: boolean;
+	paymentStatusChanged: boolean;
+	fulfillmentStatusChanged: boolean;
+	amountChanged: boolean;
+}
+
+export interface OrderStatusChangedEvent {
+	orderId: string;
+	orderNumber: string;
+	storeId: string;
+	customerId?: string;
+	fromStatus: string;
+	toStatus: string;
+	reason?: string;
+	actorId: string;
+	actorType: string;
+	timestamp: string;
+}
+
+export interface OrderPaymentProcessedEvent {
+	orderId: string;
+	paymentId: string;
+	transactionId?: string;
+	paymentMethod: string;
+	paymentProvider?: string;
+	amount: string;
+	currency: string;
+	status: string;
+	isSuccessful: boolean;
+	failureReason?: string;
+}
+
+export interface OrderShippedEvent {
+	orderId: string;
+	fulfillmentId: string;
+	trackingNumber?: string;
+	trackingUrl?: string;
+	shippingCarrier?: string;
+	shippingService?: string;
+	estimatedDeliveryDate?: string;
+	packedBy?: string;
+	shippedBy?: string;
+}
+
+export interface OrderDeliveredEvent {
+	orderId: string;
+	fulfillmentId: string;
+	deliveredAt: string;
+	deliveredBy?: string;
+	signedBy?: string;
+	deliveryLocation?: string;
+	proofOfDelivery?: Record<string, unknown>;
+}
+
+export interface OrderCancelledEvent {
+	orderId: string;
+	orderNumber: string;
+	storeId: string;
+	customerId?: string;
+	cancellationReason: string;
+	cancelledBy: string;
+	cancelledByType: string;
+	refundRequired: boolean;
+	refundAmount?: string;
+	inventoryReleased: boolean;
+}
+
+export interface OrderRefundedEvent {
+	orderId: string;
+	paymentId: string;
+	refundId: string;
+	refundAmount: string;
+	refundReason: string;
+	refundMethod: string;
+	isPartialRefund: boolean;
+	processedBy: string;
+	customerNotified: boolean;
+}
+
+export interface OrderNoteAddedEvent {
+	orderId: string;
+	noteId: string;
+	noteType: string;
+	content: string;
+	isCustomerVisible: boolean;
+	priority: string;
+	createdBy: string;
+	createdByName: string;
+	requiresFollowUp: boolean;
+}
+
+export interface OrderItemAddedEvent {
+	orderId: string;
+	itemId: string;
+	productId: string;
+	variantId?: string;
+	sku: string;
+	productTitle: string;
+	quantity: number;
+	unitPrice: string;
+	totalPrice: string;
+	addedBy: string;
+}
+
+export interface OrderItemRemovedEvent {
+	orderId: string;
+	itemId: string;
+	productId: string;
+	sku: string;
+	productTitle: string;
+	quantity: number;
+	removedBy: string;
+	removalReason?: string;
+}
+
+export interface OrderDiscountAppliedEvent {
+	orderId: string;
+	discountId: string;
+	discountCode?: string;
+	discountType: string;
+	discountAmount: string;
+	discountPercentage?: number;
+	appliedBy?: string;
+	campaignId?: string;
+}
+
+// Service Event Types
+export type OrderServiceEvent =
+	| OrderCreatedEvent
+	| OrderUpdatedEvent
+	| OrderStatusChangedEvent
+	| OrderPaymentProcessedEvent
+	| OrderShippedEvent
+	| OrderDeliveredEvent
+	| OrderCancelledEvent
+	| OrderRefundedEvent
+	| OrderNoteAddedEvent
+	| OrderItemAddedEvent
+	| OrderItemRemovedEvent
+	| OrderDiscountAppliedEvent;
+
+// Event Handler Types
+export interface OrderEventHandler<T = OrderServiceEvent> {
+	handle(event: T): Promise<void>;
+	canHandle(eventType: string): boolean;
+	priority: number;
+}
+
+export interface OrderEventEmitter {
+	emit(eventType: string, data: OrderServiceEvent): Promise<void>;
+	on(eventType: string, handler: OrderEventHandler): void;
+	off(eventType: string, handler: OrderEventHandler): void;
+	removeAllListeners(): void;
+}
+
+// Business Logic Interfaces
+export interface OrderCalculation {
+	subtotal: string;
+	taxAmount: string;
+	shippingAmount: string;
+	discountAmount: string;
+	totalAmount: string;
+	currency: string;
+}
+
+export interface OrderValidation {
+	isValid: boolean;
+	errors: string[];
+	warnings: string[];
+}
+
+export interface OrderInventoryCheck {
+	isAvailable: boolean;
+	unavailableItems: Array<{
+		productId: string;
+		variantId?: string;
+		requestedQuantity: number;
+		availableQuantity: number;
+		reason: string;
+	}>;
+}
+
+export interface OrderFraudCheck {
+	riskScore: number;
+	riskLevel: "LOW" | "MEDIUM" | "HIGH" | "CRITICAL";
+	fraudIndicators: string[];
+	recommendation: "APPROVE" | "REVIEW" | "DECLINE";
+	requiresManualReview: boolean;
+}
+
+export interface OrderShippingCalculation {
+	rates: Array<{
+		carrier: string;
+		service: string;
+		cost: string;
+		estimatedDays: number;
+		estimatedDeliveryDate: string;
+	}>;
+	recommendedRate?: {
+		carrier: string;
+		service: string;
+		cost: string;
+	};
+}
+
+// Advanced Features
+export interface OrderSplitRequest {
+	originalOrderId: string;
+	splitReason: string;
+	splits: Array<{
+		items: Array<{
+			orderItemId: string;
+			quantity: number;
+		}>;
+		shippingAddress?: Record<string, unknown>;
+		fulfillmentType?: string;
+		priority?: string;
+	}>;
+}
+
+export interface OrderMergeRequest {
+	orderIds: string[];
+	mergeReason: string;
+	newShippingAddress?: Record<string, unknown>;
+	newPaymentMethod?: string;
+}
+
+export interface OrderModificationRequest {
+	orderId: string;
+	modificationType:
+		| "ADD_ITEM"
+		| "REMOVE_ITEM"
+		| "UPDATE_QUANTITY"
+		| "CHANGE_ADDRESS"
+		| "CHANGE_PAYMENT";
+	modifications: Record<string, unknown>;
+	reason: string;
+	requestedBy: string;
+}
+
+export interface OrderEscalationRequest {
+	orderId: string;
+	escalationType:
+		| "PAYMENT_ISSUE"
+		| "SHIPPING_DELAY"
+		| "QUALITY_ISSUE"
+		| "CUSTOMER_COMPLAINT"
+		| "FRAUD_ALERT";
+	priority: "LOW" | "MEDIUM" | "HIGH" | "URGENT";
+	description: string;
+	assignedTo?: string;
+	department?: string;
+}
+
+// Reporting and Analytics
+export interface OrderMetrics {
+	totalOrders: number;
+	totalRevenue: string;
+	averageOrderValue: string;
+	ordersByStatus: Record<string, number>;
+	ordersByType: Record<string, number>;
+	ordersBySource: Record<string, number>;
+	conversionRate: number;
+	cancelationRate: number;
+	refundRate: number;
+	averageProcessingTime: number;
+	customerSatisfactionScore?: number;
+}
+
+export interface OrderReportFilter {
+	dateRange?: {
+		start: string;
+		end: string;
+	};
+	storeIds?: string[];
+	orderTypes?: string[];
+	orderSources?: string[];
+	customerTypes?: string[];
+	paymentMethods?: string[];
+	statuses?: string[];
+	minAmount?: number;
+	maxAmount?: number;
+	includeTestOrders?: boolean;
+}
+
+// Integration Interfaces
+export interface MarketplaceOrderSync {
+	marketplacePlatform: string;
+	externalOrderId: string;
+	syncStatus: "PENDING" | "SUCCESS" | "FAILED";
+	lastSyncAt?: string;
+	syncErrors?: string[];
+	marketplaceData?: Record<string, unknown>;
+}
+
+export interface InventoryReservation {
+	orderId: string;
+	reservations: Array<{
+		productId: string;
+		variantId?: string;
+		quantity: number;
+		locationId: string;
+		reservedAt: string;
+		expiresAt: string;
+	}>;
+}
+
+export interface PaymentIntentRequest {
+	orderId: string;
+	amount: string;
+	currency: string;
+	paymentMethod: string;
+	customerInfo: Record<string, unknown>;
+	billingAddress: Record<string, unknown>;
+	metadata?: Record<string, unknown>;
+}