@de./types 1.0.0

package/src/realm/queries.ts

@@ -0,0 +1,608 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ContextSchema } from '../context'
+import { DateTimeZoneSchema, ActionRecordSchema } from '../time'
+import { CoordinatesSchema } from '../geo'
+import { SPPerformanceSummarySchema, SPTypeSchema } from '../context'
+import { CoverageAreaTypeSchema } from '../lsp/coverage'
+import { APIResponseBaseSchema, APIResponseDataSchemaFactory, APIHeadersSchema } from '../api'
+
+// ===== SERVICE REGISTRY TYPES =====
+
+export const ServiceLocationSchema = Type.Object({
+  // Coverage-based location (aligns with LSP coverage system)
+  coverageId: Type.Optional(Type.String({ description: 'Reference to LSP coverage area ID' })),
+  areaType: Type.Optional(CoverageAreaTypeSchema),
+  
+  // Standard location fields
+  address: Type.String(),
+  city: Type.Optional(Type.String()),
+  state: Type.Optional(Type.String()),
+  region: Type.Optional(Type.String()),
+  country: Type.String({ minLength: 2, maxLength: 2, description: 'ISO country code' }),
+  coordinates: Type.Optional(CoordinatesSchema)
+})
+
+export const ServiceProviderSchema = Type.Object({
+  wid: Type.String({ description: 'Workspace ID' }),
+  xcode: Type.String({ description: 'LSP xcode' }),
+  name: Type.String({ description: 'LSP name' })
+})
+
+export const RegisteredServiceSchema = Type.Object({
+  id: Type.String({ description: 'Service ID from LSP' }),
+  type: SPTypeSchema,
+  name: Type.String(),
+  location: ServiceLocationSchema,
+  status: Type.Union([
+    Type.Literal('ACTIVE'),
+    Type.Literal('INACTIVE'),
+    Type.Literal('MAINTENANCE')
+  ])
+})
+
+// Service Registry Entry (Capabilities only, NO capacities)
+export const ServiceRegistryEntrySchema = Type.Object({
+  id: Type.String({ description: 'Composite ID: lsp.xcode:service.id' }),
+  lsp: ServiceProviderSchema,
+  service: RegisteredServiceSchema,
+  
+  // Capabilities (static/semi-static data synced from LSP)
+  // Wildcard to support all service types (WAREHOUSE, HUB, CARRIER, TELEMATICS, IOT_PLATFORM, etc.)
+  // Structure enforced by syncCapability() and LSP-specific schemas
+  capabilities: Type.Any(),
+  
+  // Performance Summary (normalized 0-100 metrics for matching)
+  performance: Type.Optional(SPPerformanceSummarySchema),
+  
+  // Metadata
+  lastUpdated: ActionRecordSchema,
+  syncStatus: Type.Union([
+    Type.Literal('SYNCED'),
+    Type.Literal('PENDING'),
+    Type.Literal('FAILED')
+  ]),
+  
+  context: ContextSchema
+})
+
+// ===== QUERY CRITERIA TYPES =====
+
+export const QueryCriteriaSchema = Type.Object({
+  // Geographic filters (coverage-based)
+  coverageId: Type.Optional(Type.String({ description: 'Filter by LSP coverage area ID' })),
+  areaType: Type.Optional(CoverageAreaTypeSchema),
+  country: Type.Optional(Type.String({ minLength: 2, maxLength: 2 })),
+  region: Type.Optional(Type.String()),
+  state: Type.Optional(Type.String()),
+  city: Type.Optional(Type.String()),
+  
+  // Service filters
+  type: Type.Optional(SPTypeSchema),
+  capabilities: Type.Optional(Type.Array(Type.String())),
+  status: Type.Optional(Type.Array(Type.String())),
+  lsp: Type.Optional(Type.String({ description: 'Filter by specific LSP xcode' })),
+  
+  // Pagination
+  limit: Type.Optional(Type.Number({ minimum: 1, maximum: 100, default: 50 })),
+  offset: Type.Optional(Type.Number({ minimum: 0, default: 0 }))
+})
+
+export const CapabilityFilterSchema = Type.Object({
+  key: Type.String({ description: 'Capability path, e.g. environmental.coldStorage.supported' }),
+  operator: Type.Union([
+    Type.Literal('equals'),
+    Type.Literal('contains'),
+    Type.Literal('exists')
+  ]),
+  value: Type.Any()
+})
+
+export const AdvancedQueryCriteriaSchema = Type.Intersect([
+  QueryCriteriaSchema,
+  Type.Object({
+    capabilityFilters: Type.Optional(Type.Array(CapabilityFilterSchema)),
+    coordinates: Type.Optional(Type.Object({
+      lat: Type.Number(),
+      lng: Type.Number(),
+      radiusKm: Type.Number({ minimum: 1, maximum: 500 })
+    }))
+  })
+])
+
+// ===== QUERY RESULTS =====
+
+export const QueryResultSchema = Type.Object({
+  services: Type.Array(ServiceRegistryEntrySchema),
+  total: Type.Number({ minimum: 0 }),
+  executionTimeMs: Type.Number(),
+  cached: Type.Boolean()
+})
+
+// ===== MATCHING TYPES =====
+
+export const MatchRequestSchema = Type.Object({
+  // Service types to match (supports multiple for flexibility)
+  serviceTypes: Type.Array(SPTypeSchema, { 
+    minItems: 1,
+    description: 'Types of services to match (e.g., WAREHOUSE, CARRIER, IOT_PLATFORM)' 
+  }),
+  
+  delivery: Type.Object({
+    // Coverage-based delivery location
+    coverageId: Type.Optional(Type.String({ description: 'Target LSP coverage area ID' })),
+    areaType: Type.Optional(CoverageAreaTypeSchema),
+    
+    // Standard delivery address
+    address: Type.String(),
+    city: Type.Optional(Type.String()),
+    state: Type.Optional(Type.String()),
+    region: Type.Optional(Type.String()),
+    country: Type.Optional(Type.String({ minLength: 2, maxLength: 2 })),
+    coordinates: Type.Optional(CoordinatesSchema)
+  }),
+  
+  items: Type.Optional(Type.Array(Type.Object({
+    sku: Type.String(),
+    quantity: Type.Number({ minimum: 1 }),
+    requirements: Type.Optional(Type.Array(Type.String()))
+  }))),
+  
+  requirements: Type.Optional(Type.Array(Type.String())),
+  
+  strategy: Type.Optional(Type.Union([
+    Type.Literal('CHEAPEST'),
+    Type.Literal('FASTEST'),
+    Type.Literal('NEAREST'),
+    Type.Literal('BALANCED')
+  ]))
+})
+
+export const MatchScoreSchema = Type.Object({
+  total: Type.Number({ minimum: 0, maximum: 100 }),
+  breakdown: Type.Object({
+    capabilityMatch: Type.Number({ minimum: 0, maximum: 100 }),
+    proximityScore: Type.Number({ minimum: 0, maximum: 100 }),
+    capacityScore: Type.Number({ minimum: 0, maximum: 100 }),
+    performanceScore: Type.Number({ minimum: 0, maximum: 100 }),
+    costScore: Type.Number({ minimum: 0, maximum: 100 })
+  })
+})
+
+export const MatchRecommendationSchema = Type.Object({
+  service: ServiceRegistryEntrySchema,
+  score: MatchScoreSchema,
+  reasoning: Type.Array(Type.String()),
+  warnings: Type.Optional(Type.Array(Type.String()))
+})
+
+export const MatchResultSchema = Type.Object({
+  recommendations: Type.Array(MatchRecommendationSchema),
+  recommended: Type.Optional(MatchRecommendationSchema),
+  executionTimeMs: Type.Number()
+})
+
+// ===== CAPACITY QUERY TYPES (for LSP direct queries) =====
+
+export const CapacityQueryRequestSchema = Type.Object({
+  lsp: Type.String({ description: 'LSP xcode' }),
+  serviceId: Type.String(),
+  capacityType: Type.Union([
+    Type.Literal('PHYSICAL'),
+    Type.Literal('OPERATIONAL'),
+    Type.Literal('SERVICE_LEVELS'),
+    Type.Literal('RESOURCES'),
+    Type.Literal('ENVIRONMENTAL'),
+    Type.Literal('FINANCIAL')
+  ])
+})
+
+export const BatchCapacityQueryRequestSchema = Type.Object({
+  services: Type.Array(Type.Object({
+    lsp: Type.String(),
+    serviceId: Type.String()
+  })),
+  capacityType: Type.String()
+})
+
+// ===== SYNC TYPES =====
+
+export const CapabilitySyncRequestSchema = Type.Object({
+  lsp: Type.String({ description: 'LSP xcode' }),
+  serviceId: Type.String(),
+  serviceType: SPTypeSchema,
+  capabilityType: Type.String(),
+  capability: Type.Any(),
+  action: Type.Union([
+    Type.Literal('UPSERT'),
+    Type.Literal('DELETE')
+  ])
+})
+
+export const ServiceSyncStatusSchema = Type.Object({
+  lsp: Type.String(),
+  serviceId: Type.String(),
+  lastSync: DateTimeZoneSchema,
+  status: Type.Union([
+    Type.Literal('SYNCED'),
+    Type.Literal('PENDING'),
+    Type.Literal('FAILED')
+  ]),
+  error: Type.Optional(Type.String())
+})
+
+// ===== TYPE EXPORTS =====
+
+export type ServiceLocation = Static<typeof ServiceLocationSchema>
+export type ServiceProvider = Static<typeof ServiceProviderSchema>
+export type RegisteredService = Static<typeof RegisteredServiceSchema>
+export type ServiceRegistryEntry = Static<typeof ServiceRegistryEntrySchema>
+
+export type QueryCriteria = Static<typeof QueryCriteriaSchema>
+export type CapabilityFilter = Static<typeof CapabilityFilterSchema>
+export type AdvancedQueryCriteria = Static<typeof AdvancedQueryCriteriaSchema>
+export type QueryResult = Static<typeof QueryResultSchema>
+
+export type MatchRequest = Static<typeof MatchRequestSchema>
+export type MatchScore = Static<typeof MatchScoreSchema>
+export type MatchRecommendation = Static<typeof MatchRecommendationSchema>
+export type MatchResult = Static<typeof MatchResultSchema>
+
+export type CapacityQueryRequest = Static<typeof CapacityQueryRequestSchema>
+export type BatchCapacityQueryRequest = Static<typeof BatchCapacityQueryRequestSchema>
+
+export type CapabilitySyncRequest = Static<typeof CapabilitySyncRequestSchema>
+export type ServiceSyncStatus = Static<typeof ServiceSyncStatusSchema>
+
+// ─── Discovery RVS ────────────────────────────────────────────────────────────
+
+export const QueryDiscoverRVS = {
+	headers: APIHeadersSchema,
+	body: QueryCriteriaSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			services: Type.Array(ServiceRegistryEntrySchema),
+			total: Type.Number(),
+			executionTimeMs: Type.Number()
+		})
+	])
+}
+export type QueryDiscoverValidation = {
+	body: Static<typeof QueryDiscoverRVS.body>
+	response: Static<typeof QueryDiscoverRVS.response>
+}
+
+export const QueryAdvancedDiscoverRVS = {
+	headers: APIHeadersSchema,
+	body: AdvancedQueryCriteriaSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			services: Type.Array(ServiceRegistryEntrySchema),
+			total: Type.Number(),
+			executionTimeMs: Type.Number()
+		})
+	])
+}
+export type QueryAdvancedDiscoverValidation = {
+	body: Static<typeof QueryAdvancedDiscoverRVS.body>
+	response: Static<typeof QueryAdvancedDiscoverRVS.response>
+}
+
+export const QueryFindAvailableRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		criteria: QueryCriteriaSchema,
+		minCapacity: Type.Optional(Type.Number()),
+		capacityType: Type.Optional(Type.String())
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			services: Type.Array(Type.Any()),
+			total: Type.Number(),
+			executionTimeMs: Type.Number()
+		})
+	])
+}
+export type QueryFindAvailableValidation = {
+	body: Static<typeof QueryFindAvailableRVS.body>
+	response: Static<typeof QueryFindAvailableRVS.response>
+}
+
+export const QueryCountServicesRVS = {
+	headers: APIHeadersSchema,
+	body: QueryCriteriaSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ count: Type.Number() })
+	])
+}
+export type QueryCountServicesValidation = {
+	body: Static<typeof QueryCountServicesRVS.body>
+	response: Static<typeof QueryCountServicesRVS.response>
+}
+
+export const QueryGetServiceRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ compositeId: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ service: ServiceRegistryEntrySchema })
+	])
+}
+export type QueryGetServiceValidation = {
+	params: Static<typeof QueryGetServiceRVS.params>
+	response: Static<typeof QueryGetServiceRVS.response>
+}
+
+// ─── Matching RVS ─────────────────────────────────────────────────────────────
+
+export const QueryMatchRVS = {
+	headers: APIHeadersSchema,
+	body: MatchRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		Type.Object({ data: MatchResultSchema })
+	])
+}
+export type QueryMatchValidation = {
+	body: Static<typeof QueryMatchRVS.body>
+	response: Static<typeof QueryMatchRVS.response>
+}
+
+// ─── Capacity RVS ─────────────────────────────────────────────────────────────
+
+export const QueryCapacityRVS = {
+	headers: APIHeadersSchema,
+	body: CapacityQueryRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ capacity: Type.Any() })
+	])
+}
+export type QueryCapacityValidation = {
+	body: Static<typeof QueryCapacityRVS.body>
+	response: Static<typeof QueryCapacityRVS.response>
+}
+
+export const QueryBatchCapacityRVS = {
+	headers: APIHeadersSchema,
+	body: BatchCapacityQueryRequestSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			capacities: Type.Record(Type.String(), Type.Any()),
+			total: Type.Number()
+		})
+	])
+}
+export type QueryBatchCapacityValidation = {
+	body: Static<typeof QueryBatchCapacityRVS.body>
+	response: Static<typeof QueryBatchCapacityRVS.response>
+}
+
+export const QueryAllCapacitiesRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ lsp: Type.String(), serviceId: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			capacities: Type.Array(Type.Any()),
+			total: Type.Number()
+		})
+	])
+}
+export type QueryAllCapacitiesValidation = {
+	params: Static<typeof QueryAllCapacitiesRVS.params>
+	response: Static<typeof QueryAllCapacitiesRVS.response>
+}
+
+export const QueryCapacityInvalidateCacheRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ lsp: Type.String(), serviceId: Type.String() }),
+	querystring: Type.Object({ capacityType: Type.Optional(Type.String()) }),
+	response: APIResponseBaseSchema
+}
+export type QueryCapacityInvalidateCacheValidation = {
+	params: Static<typeof QueryCapacityInvalidateCacheRVS.params>
+	querystring: Static<typeof QueryCapacityInvalidateCacheRVS.querystring>
+	response: Static<typeof QueryCapacityInvalidateCacheRVS.response>
+}
+
+export const QueryCapacityCacheStatsRVS = {
+	headers: APIHeadersSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			size: Type.Number(),
+			entries: Type.Array(Type.Object({
+				key: Type.String(),
+				expiresIn: Type.Number()
+			}))
+		})
+	])
+}
+export type QueryCapacityCacheStatsValidation = {
+	response: Static<typeof QueryCapacityCacheStatsRVS.response>
+}
+
+// ─── Performance RVS ──────────────────────────────────────────────────────────
+
+export const QuerySyncPerformanceRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		lsp: Type.String(),
+		serviceId: Type.String(),
+		performance: SPPerformanceSummarySchema
+	}),
+	response: APIResponseBaseSchema
+}
+export type QuerySyncPerformanceValidation = {
+	body: Static<typeof QuerySyncPerformanceRVS.body>
+	response: Static<typeof QuerySyncPerformanceRVS.response>
+}
+
+export const QueryBatchSyncPerformanceRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		lsp: Type.String(),
+		services: Type.Array(Type.Object({
+			serviceId: Type.String(),
+			performance: SPPerformanceSummarySchema
+		}))
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ synced: Type.Number(), failed: Type.Number() })
+	])
+}
+export type QueryBatchSyncPerformanceValidation = {
+	body: Static<typeof QueryBatchSyncPerformanceRVS.body>
+	response: Static<typeof QueryBatchSyncPerformanceRVS.response>
+}
+
+export const QueryGetPerformanceRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ lsp: Type.String(), serviceId: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({ performance: SPPerformanceSummarySchema })
+	])
+}
+export type QueryGetPerformanceValidation = {
+	params: Static<typeof QueryGetPerformanceRVS.params>
+	response: Static<typeof QueryGetPerformanceRVS.response>
+}
+
+// ─── Pricing RVS ──────────────────────────────────────────────────────────────
+
+export const QueryGetPricingRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ lsp: Type.String(), serviceId: Type.String() }),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			pricing: Type.Array(Type.Any()),
+			total: Type.Number()
+		})
+	])
+}
+export type QueryGetPricingValidation = {
+	params: Static<typeof QueryGetPricingRVS.params>
+	response: Static<typeof QueryGetPricingRVS.response>
+}
+
+export const QueryEstimateCostRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		lsp: Type.String(),
+		serviceId: Type.String(),
+		serviceType: SPTypeSchema,
+		orderContext: Type.Object({
+			items: Type.Optional(Type.Array(Type.Object({
+				sku: Type.String(),
+				quantity: Type.Number({ minimum: 1 })
+			}))),
+			requirements: Type.Optional(Type.Array(Type.String())),
+			deliveryLocation: Type.Optional(Type.Object({
+				country: Type.Optional(Type.String()),
+				city: Type.Optional(Type.String()),
+				areaType: Type.Optional(Type.String())
+			})),
+			strategy: Type.Optional(Type.String())
+		})
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			estimate: Type.Object({
+				totalCost: Type.Number(),
+				currency: Type.String(),
+				breakdown: Type.Object({
+					baseRate: Type.Number(),
+					surcharges: Type.Number(),
+					taxes: Type.Number(),
+					fees: Type.Number()
+				}),
+				appliedRules: Type.Array(Type.String())
+			})
+		})
+	])
+}
+export type QueryEstimateCostValidation = {
+	body: Static<typeof QueryEstimateCostRVS.body>
+	response: Static<typeof QueryEstimateCostRVS.response>
+}
+
+export const QueryComparePricingRVS = {
+	headers: APIHeadersSchema,
+	body: Type.Object({
+		services: Type.Array(Type.Object({
+			lsp: Type.String(),
+			serviceId: Type.String(),
+			serviceType: SPTypeSchema
+		}), { minItems: 2 }),
+		orderContext: Type.Object({
+			items: Type.Optional(Type.Array(Type.Object({
+				sku: Type.String(),
+				quantity: Type.Number({ minimum: 1 })
+			}))),
+			requirements: Type.Optional(Type.Array(Type.String())),
+			deliveryLocation: Type.Optional(Type.Object({
+				country: Type.Optional(Type.String()),
+				city: Type.Optional(Type.String())
+			}))
+		})
+	}),
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			comparisons: Type.Array(Type.Object({
+				lsp: Type.String(),
+				serviceId: Type.String(),
+				totalCost: Type.Number(),
+				currency: Type.String(),
+				breakdown: Type.Object({
+					baseRate: Type.Number(),
+					surcharges: Type.Number(),
+					taxes: Type.Number(),
+					fees: Type.Number()
+				})
+			})),
+			cheapest: Type.Optional(Type.Object({
+				lsp: Type.String(),
+				serviceId: Type.String(),
+				totalCost: Type.Number()
+			}))
+		})
+	])
+}
+export type QueryComparePricingValidation = {
+	body: Static<typeof QueryComparePricingRVS.body>
+	response: Static<typeof QueryComparePricingRVS.response>
+}
+
+export const QueryPricingInvalidateCacheRVS = {
+	headers: APIHeadersSchema,
+	params: Type.Object({ lsp: Type.String(), serviceId: Type.String() }),
+	response: APIResponseBaseSchema
+}
+export type QueryPricingInvalidateCacheValidation = {
+	params: Static<typeof QueryPricingInvalidateCacheRVS.params>
+	response: Static<typeof QueryPricingInvalidateCacheRVS.response>
+}
+
+export const QueryPricingCacheStatsRVS = {
+	headers: APIHeadersSchema,
+	response: Type.Intersect([
+		APIResponseBaseSchema,
+		APIResponseDataSchemaFactory({
+			size: Type.Number(),
+			entries: Type.Array(Type.String())
+		})
+	])
+}
+export type QueryPricingCacheStatsValidation = {
+	response: Static<typeof QueryPricingCacheStatsRVS.response>
+}