@de./types 1.0.0

package/src/csp/order.ts

@@ -0,0 +1,485 @@
+import { Type, Static } from '@sinclair/typebox'
+import {
+  BaseOrderStatusSchema,
+  BaseOrderSchema,
+  OrderItemSchema,
+  OrderPrioritySchema,
+  OrderRequirementSchema,
+  OrderRoutingConfigSchema,
+  OrderPaymentSchema,
+  BaseOrderFlowPrioritySchema,
+  OrderAssigneeSchema
+} from '../order'
+import { DProfileReferenceSchema } from '../de.profile'
+import { ActionRecordSchema, DateTimeZoneSchema } from '../time'
+import {
+	APIResponseBaseSchema,
+	APIResponseDataSchemaFactory,
+	APIHeadersSchema,
+	APIErrorSchema,
+	FetchByQueryRequestSchema
+} from '../api'
+
+// CSP Order Process - High-level customer order lifecycle
+export const CSPOrderProcessSchema = Type.Union([
+  Type.Literal('ORDER_RECEIVED'),      // Initial order intake
+  Type.Literal('ORDER_VALIDATION'),    // Validating order details
+  Type.Literal('ORDER_ROUTING'),       // Determining fulfillment strategy
+  Type.Literal('ORDER_FULFILLMENT'),   // Active fulfillment (delegated to LSP)
+  Type.Literal('ORDER_DELIVERY'),      // Final delivery tracking
+  Type.Literal('ORDER_COMPLETION'),    // Order completed
+  Type.Literal('ORDER_EXCEPTION')      // Exception handling
+])
+
+// CSP Order Stage - Customer-facing order stages
+export const CSPOrderStageSchema = Type.Union([
+  Type.Literal('RECEIVED'),           // Order received from customer
+  Type.Literal('VALIDATING'),         // Validating order
+  Type.Literal('CONFIRMED'),          // Order confirmed
+  Type.Literal('ROUTING'),            // Determining routing
+  Type.Literal('ASSIGNED'),           // Assigned to LSP/pipeline
+  Type.Literal('PROCESSING'),         // Being processed
+  Type.Literal('IN_TRANSIT'),         // In transit to customer
+  Type.Literal('OUT_FOR_DELIVERY'),   // Out for delivery
+  Type.Literal('DELIVERED'),          // Delivered to customer
+  Type.Literal('COMPLETED'),          // Order completed
+  Type.Literal('EXCEPTION')           // Exception state
+])
+
+// CSP Order Status (extends base with CSP-specific statuses)
+export const CSPOrderStatusSchema = Type.Union([
+  ...BaseOrderStatusSchema.anyOf,
+  Type.Literal('ROUTE_ASSIGNED'),     // Routing determined
+  Type.Literal('LSP_ASSIGNED'),       // Assigned to LSP
+  Type.Literal('AWAITING_PICKUP'),    // Waiting for pickup
+  Type.Literal('DELIVERED'),          // Successfully delivered
+  Type.Literal('DELIVERY_FAILED'),    // Delivery attempt failed
+  Type.Literal('RETURNED')            // Order returned
+])
+
+// CSP Order Channel - Where the order originated
+export const CSPOrderChannelSchema = Type.Union([
+  Type.Literal('ONLINE'),
+  Type.Literal('STORE'),
+  Type.Literal('MOBILE'),
+  Type.Literal('MARKETPLACE'),
+  Type.Literal('API'),
+  Type.Literal('PHONE')
+])
+
+// CSP Order Flow - Tracks CSP-level order lifecycle
+export const CSPOrderFlowSchema = Type.Object({
+  process: CSPOrderProcessSchema,
+  stage: CSPOrderStageSchema,
+  status: CSPOrderStatusSchema,
+  priority: BaseOrderFlowPrioritySchema
+})
+
+// Integration metadata for external platforms
+export const CSPOrderMetaSchema = Type.Object({
+  callbackUrl: Type.Optional(Type.String({ 
+    format: 'uri', 
+    description: 'URL to push order status events back to the originating platform' 
+  })),
+  platformOrderId: Type.Optional(Type.String({ description: 'Order ID in the external platform' })),
+  platformOrderNumber: Type.Optional(Type.String({ description: 'Order number in the external platform' })),
+  platform: Type.Optional(Type.String({ description: 'Platform name (e.g., Shopify, WooCommerce)' })),
+  extra: Type.Optional(Type.Record(Type.String(), Type.Any(), { description: 'Additional platform-specific data' })),
+  customerRating: Type.Optional(Type.Number({ minimum: 1, maximum: 5, description: 'Customer-submitted rating for this order' }))
+})
+
+// CSP Order SLA — service-level agreement for delivery promise
+export const CSPOrderSLASchema = Type.Object({
+  promisedDeliveryAt: Type.Optional(DateTimeZoneSchema), // Unix ms deadline for on-time delivery
+  cutoffAt: Type.Optional(DateTimeZoneSchema) // Unix ms processing cutoff
+})
+
+// CSP status history entry — tracks every flow.status transition
+export const CSPStatusHistoryEntrySchema = Type.Object({
+  from: CSPOrderStatusSchema,
+  to: CSPOrderStatusSchema,
+  reason: Type.Optional(Type.String({ maxLength: 500 })),
+  changed: ActionRecordSchema
+})
+
+// Full CSP Order Schema (extends BaseOrder with CSP-specific fields)
+export const CSPOrderSchema = Type.Intersect([
+  BaseOrderSchema,
+  Type.Object({
+    // Order Details
+    items: Type.Array(OrderItemSchema),
+    channel: CSPOrderChannelSchema,
+    
+    // CSP Flow State
+    flow: CSPOrderFlowSchema,
+    
+    // Service tracking
+    service: Type.Optional(Type.Object({
+      type: Type.String({ description: 'Service type (e.g., DELIVERY, PICKUP)' }),
+      level: Type.Optional(Type.String({ description: 'Service level (e.g., STANDARD, EXPRESS)' }))
+    })),
+    
+    // Integration Metadata
+    meta: Type.Optional(CSPOrderMetaSchema),
+
+    // SLA / delivery promise
+    sla: Type.Optional(CSPOrderSLASchema),
+
+    // Lifecycle action records
+    delivered: Type.Optional(ActionRecordSchema),
+    completed: Type.Optional(ActionRecordSchema),
+    cancelled: Type.Optional(ActionRecordSchema),
+    cancellationReason: Type.Optional(Type.String({ maxLength: 1000 })),
+
+    // Manual dispatch tracking
+    dispatched: Type.Optional(ActionRecordSchema),
+    dispatchNotes: Type.Optional(Type.String({ maxLength: 2000 })),
+
+    // Status transition log
+    statusHistory: Type.Optional(Type.Array(CSPStatusHistoryEntrySchema))
+  })
+])
+
+export const CreateCSPOrderSchema = Type.Object({
+  items: Type.Array(OrderItemSchema),
+  reference: Type.Optional(Type.String()),
+  dprofile: Type.Optional(DProfileReferenceSchema),
+  routing: OrderRoutingConfigSchema,
+  channel: CSPOrderChannelSchema,
+  priority: Type.Optional(OrderPrioritySchema),
+  requirements: Type.Optional(Type.Array(OrderRequirementSchema)),
+  customerNotes: Type.Optional(Type.String({ maxLength: 1000 })),
+  meta: Type.Optional(CSPOrderMetaSchema)
+})
+
+export const CSPOrderLogSchema = Type.Intersect([
+  ActionRecordSchema,
+  Type.Object({
+    orderId: Type.String(),
+    flow: CSPOrderFlowSchema,
+    assignee: Type.Optional(OrderAssigneeSchema),
+    reason: Type.Optional(Type.String({ maxLength: 500 })),
+    changes: Type.Optional(Type.Record(Type.String(), Type.Any()))
+  })
+])
+
+export type CSPOrderProcess = Static<typeof CSPOrderProcessSchema>
+export type CSPOrderStage = Static<typeof CSPOrderStageSchema>
+export type CSPOrderStatus = Static<typeof CSPOrderStatusSchema>
+export type CSPOrderChannel = Static<typeof CSPOrderChannelSchema>
+export type CSPOrderFlow = Static<typeof CSPOrderFlowSchema>
+export type CSPOrderMeta = Static<typeof CSPOrderMetaSchema>
+export type CSPOrderSLA = Static<typeof CSPOrderSLASchema>
+export type CSPStatusHistoryEntry = Static<typeof CSPStatusHistoryEntrySchema>
+export type CSPOrder = Static<typeof CSPOrderSchema>
+export type CreateCSPOrder = Static<typeof CreateCSPOrderSchema>
+export type CSPOrderLog = Static<typeof CSPOrderLogSchema>
+
+// ─── CSP Order RVS (Request Validation Schemas) ────────────────────────────
+
+export const CSPOrderCreateRVS = {
+	headers: APIHeadersSchema,
+	body: CreateCSPOrderSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			reference: Type.String(),
+			masterTrackingNumber: Type.String()
+		})
+	])
+}
+export type CSPOrderCreateValidation = {
+	body: Static<typeof CSPOrderCreateRVS.body>
+	response: Static<typeof CSPOrderCreateRVS.response>
+}
+
+export const CSPOrderRetrieveRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			order: Type.Any()
+		})
+	])
+}
+export type CSPOrderRetrieveValidation = {
+	params: Static<typeof CSPOrderRetrieveRVS.params>
+	response: Static<typeof CSPOrderRetrieveRVS.response>
+}
+
+export const CSPOrderListRVS = {
+	headers: APIHeadersSchema,
+	querystring: Type.Composite([
+		FetchByQueryRequestSchema,
+		Type.Object({
+			status: Type.Optional(Type.String()),
+			channel: Type.Optional(Type.String()),
+			startDate: Type.Optional(Type.Number()),
+			endDate: Type.Optional(Type.Number())
+		})
+	]),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orders: Type.Array(Type.Any()),
+			total: Type.Number(),
+			page: Type.Number(),
+			limit: Type.Number()
+		})
+	])
+}
+export type CSPOrderListValidation = {
+	querystring: Static<typeof CSPOrderListRVS.querystring>
+	response: Static<typeof CSPOrderListRVS.response>
+}
+
+export const CSPOrderUpdateRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		customerNotes: Type.Optional(Type.String())
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String()
+		})
+	])
+}
+export type CSPOrderUpdateValidation = {
+	params: Static<typeof CSPOrderUpdateRVS.params>
+	body: Static<typeof CSPOrderUpdateRVS.body>
+	response: Static<typeof CSPOrderUpdateRVS.response>
+}
+
+export const CSPOrderTrackingRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			order: Type.Any(),
+			children: Type.Array(Type.Any())
+		})
+	])
+}
+export type CSPOrderTrackingValidation = {
+	params: Static<typeof CSPOrderTrackingRVS.params>
+	response: Static<typeof CSPOrderTrackingRVS.response>
+}
+
+export const CSPOrderCancelRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		reason: Type.String({ minLength: 1, maxLength: 500 })
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			status: Type.String()
+		})
+	])
+}
+export type CSPOrderCancelValidation = {
+	params: Static<typeof CSPOrderCancelRVS.params>
+	body: Static<typeof CSPOrderCancelRVS.body>
+	response: Static<typeof CSPOrderCancelRVS.response>
+}
+
+export const CSPOrderTimelineRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			events: Type.Array(Type.Object({
+				type: Type.String(),
+				timestamp: Type.Number(),
+				actor: Type.Optional(Type.String()),
+				data: Type.Optional(Type.Any())
+			}))
+		})
+	])
+}
+export type CSPOrderTimelineValidation = {
+	params: Static<typeof CSPOrderTimelineRVS.params>
+	response: Static<typeof CSPOrderTimelineRVS.response>
+}
+
+export const CSPOrderReportExceptionRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		type: Type.Union([
+			Type.Literal('DAMAGE'),
+			Type.Literal('DELAY'),
+			Type.Literal('LOST'),
+			Type.Literal('DELIVERY_FAILED'),
+			Type.Literal('WRONG_ADDRESS'),
+			Type.Literal('REFUSED'),
+			Type.Literal('OTHER')
+		]),
+		description: Type.String({ minLength: 1, maxLength: 1000 }),
+		severity: Type.Optional(Type.Union([
+			Type.Literal('LOW'),
+			Type.Literal('MEDIUM'),
+			Type.Literal('HIGH'),
+			Type.Literal('CRITICAL')
+		]))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			exceptionId: Type.String()
+		})
+	])
+}
+export type CSPOrderReportExceptionValidation = {
+	params: Static<typeof CSPOrderReportExceptionRVS.params>
+	body: Static<typeof CSPOrderReportExceptionRVS.body>
+	response: Static<typeof CSPOrderReportExceptionRVS.response>
+}
+
+export const CSPOrderListExceptionsRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			exceptions: Type.Array(Type.Object({
+				id: Type.String(),
+				type: Type.String(),
+				severity: Type.String(),
+				description: Type.String(),
+				reported: Type.Any(),
+				resolved: Type.Optional(Type.Any())
+			}))
+		})
+	])
+}
+export type CSPOrderListExceptionsValidation = {
+	params: Static<typeof CSPOrderListExceptionsRVS.params>
+	response: Static<typeof CSPOrderListExceptionsRVS.response>
+}
+
+export const CSPOrderResolveExceptionRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({
+		reference: Type.String(),
+		exceptionId: Type.String()
+	}),
+	body: Type.Object({
+		resolution: Type.String({ minLength: 1, maxLength: 1000 }),
+		action: Type.Optional(Type.Union([
+			Type.Literal('REPLACED'),
+			Type.Literal('REFUNDED'),
+			Type.Literal('WAIVED'),
+			Type.Literal('REROUTED'),
+			Type.Literal('OTHER')
+		]))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			exceptionId: Type.String()
+		})
+	])
+}
+export type CSPOrderResolveExceptionValidation = {
+	params: Static<typeof CSPOrderResolveExceptionRVS.params>
+	body: Static<typeof CSPOrderResolveExceptionRVS.body>
+	response: Static<typeof CSPOrderResolveExceptionRVS.response>
+}
+
+export const CSPOrderDispatchRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		lsp: Type.Object({
+			providerType: Type.String(),
+			type: Type.String(),
+			id: Type.String()
+		}),
+		notes: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			status: Type.String()
+		})
+	])
+}
+export type CSPOrderDispatchValidation = {
+	params: Static<typeof CSPOrderDispatchRVS.params>
+	body: Static<typeof CSPOrderDispatchRVS.body>
+	response: Static<typeof CSPOrderDispatchRVS.response>
+}
+
+export const CSPOrderSplitRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		splits: Type.Array(
+			Type.Object({
+				lsp: Type.Object({
+					providerType: Type.String(),
+					type: Type.String(),
+					id: Type.String()
+				}),
+				items: Type.Array(Type.Object({
+					sku: Type.String(),
+					quantity: Type.Number({ minimum: 1 })
+				}), { minItems: 1 })
+			}),
+			{ minItems: 2 }
+		)
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			subOrders: Type.Array(Type.Object({
+				orderReference: Type.String(),
+				lspId: Type.String(),
+				itemCount: Type.Number()
+			}))
+		})
+	])
+}
+export type CSPOrderSplitValidation = {
+	params: Static<typeof CSPOrderSplitRVS.params>
+	body: Static<typeof CSPOrderSplitRVS.body>
+	response: Static<typeof CSPOrderSplitRVS.response>
+}
+
+export const CSPOrderUpdateStatusRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ reference: Type.String() }),
+	body: Type.Object({
+		status: Type.String(),
+		stage: Type.Optional(Type.String()),
+		process: Type.Optional(Type.String()),
+		reason: Type.Optional(Type.String({ maxLength: 500 }))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			orderReference: Type.String(),
+			status: Type.String()
+		})
+	])
+}
+export type CSPOrderUpdateStatusValidation = {
+	params: Static<typeof CSPOrderUpdateStatusRVS.params>
+	body: Static<typeof CSPOrderUpdateStatusRVS.body>
+	response: Static<typeof CSPOrderUpdateStatusRVS.response>
+}