@de./types 1.0.0

package/src/billing.ts

@@ -0,0 +1,330 @@
+import { Type, Static } from '@sinclair/typebox'
+import { ActionRecordSchema, DateTimeZoneSchema } from './time'
+
+export const AccountTierSchema = Type.Union([
+  Type.Literal('LITE'),
+  Type.Literal('SCALE'),
+  Type.Literal('VOLUME')
+])
+
+export const BillingStatusSchema = Type.Union([
+  Type.Literal('ACTIVE'),
+  Type.Literal('SUSPENDED'),
+  Type.Literal('PAST_DUE'),
+  Type.Literal('CANCELLED')
+])
+
+export const TierConfigSchema = Type.Object({
+  tier: AccountTierSchema,
+  freeAllowance: Type.Number(),
+  pricePerRequest: Type.Number(),
+  autoUpgradeThreshold: Type.Optional(Type.Number()),
+  features: Type.Array(Type.String()),
+  rateLimit: Type.Object({
+    requestsPerSecond: Type.Number(),
+    burstCapacity: Type.Number()
+  }),
+  support: Type.Object({
+    level: Type.String(),
+    responseTime: Type.String()
+  }),
+  sla: Type.Object({
+    uptime: Type.Number(),
+    hasPenalties: Type.Boolean()
+  })
+})
+
+export const UsageRecordSchema = Type.Object({
+  id: Type.String(),
+  wid: Type.String(),
+  billingPeriod: Type.Object({
+    start: DateTimeZoneSchema,
+    end: DateTimeZoneSchema
+  }),
+  requestCount: Type.Number(),
+  tier: AccountTierSchema,
+  billableRequests: Type.Number(),
+  estimatedCost: Type.Number(),
+  breakdown: Type.Object({
+    free: Type.Number(),
+    billable: Type.Number()
+  }),
+  lastUpdated: DateTimeZoneSchema
+})
+
+export const TierUpgradeEventSchema = Type.Object({
+  id: Type.String(),
+  wid: Type.String(),
+  fromTier: AccountTierSchema,
+  toTier: AccountTierSchema,
+  reason: Type.Union([
+    Type.Literal('AUTO_THRESHOLD'),
+    Type.Literal('MANUAL_UPGRADE'),
+    Type.Literal('MANUAL_DOWNGRADE')
+  ]),
+  triggerThreshold: Type.Optional(Type.Number()),
+  requestCount: Type.Number(),
+  upgraded: ActionRecordSchema,
+  metadata: Type.Optional(Type.Record(Type.String(), Type.Any()))
+})
+
+export const ThresholdNotificationSchema = Type.Object({
+  id: Type.String(),
+  wid: Type.String(),
+  type: Type.Union([
+    Type.Literal('USAGE_WARNING_80'),
+    Type.Literal('USAGE_WARNING_95'),
+    Type.Literal('TIER_UPGRADE_IMMINENT'),
+    Type.Literal('TIER_UPGRADED'),
+    Type.Literal('BILLING_ESTIMATE')
+  ]),
+  threshold: Type.Number(),
+  currentUsage: Type.Number(),
+  estimatedCost: Type.Optional(Type.Number()),
+  sent: DateTimeZoneSchema,
+  acknowledged: Type.Optional(Type.Boolean())
+})
+
+export const AccountBillingSchema = Type.Object({
+  wid: Type.String(),
+  status: BillingStatusSchema,
+  paymentMethod: Type.Optional(Type.Object({
+    type: Type.Union([
+      Type.Literal('CARD'),
+      Type.Literal('BANK_TRANSFER'),
+      Type.Literal('INVOICE')
+    ]),
+    fingerprint: Type.String(),
+    last4: Type.Optional(Type.String()),
+    expiryMonth: Type.Optional(Type.Number()),
+    expiryYear: Type.Optional(Type.Number()),
+    verified: Type.Boolean()
+  })),
+  currentPeriod: Type.Object({
+    start: DateTimeZoneSchema,
+    end: DateTimeZoneSchema,
+    requestCount: Type.Number(),
+    billableRequests: Type.Number(),
+    estimatedCost: Type.Number(),
+    byConnector: Type.Array(Type.Object({
+      cid: Type.String(),
+      tier: AccountTierSchema,
+      requestCount: Type.Number(),
+      billableRequests: Type.Number(),
+      estimatedCost: Type.Number()
+    }))
+  }),
+  connectors: Type.Object({
+    total: Type.Number(),
+    byTier: Type.Object({
+      LITE: Type.Number(),
+      SCALE: Type.Number(),
+      VOLUME: Type.Number()
+    })
+  }),
+  abuseFlags: Type.Optional(Type.Array(Type.Object({
+    type: Type.Union([
+      Type.Literal('MULTIPLE_ACCOUNTS'),
+      Type.Literal('TIER_CYCLING'),
+      Type.Literal('SUSPICIOUS_PATTERN')
+    ]),
+    detected: DateTimeZoneSchema,
+    severity: Type.Union([
+      Type.Literal('LOW'),
+      Type.Literal('MEDIUM'),
+      Type.Literal('HIGH')
+    ]),
+    resolved: Type.Optional(Type.Boolean())
+  }))),
+  created: ActionRecordSchema,
+  updated: Type.Optional(ActionRecordSchema)
+})
+
+export const BillingInvoiceSchema = Type.Object({
+  id: Type.String(),
+  invoiceNumber: Type.String(),
+  wid: Type.String(),
+  period: Type.Object({
+    start: DateTimeZoneSchema,
+    end: DateTimeZoneSchema
+  }),
+  lineItems: Type.Array(Type.Object({
+    description: Type.String(),
+    quantity: Type.Number(),
+    unitPrice: Type.Number(),
+    amount: Type.Number()
+  })),
+  subtotal: Type.Number(),
+  tax: Type.Number(),
+  total: Type.Number(),
+  currency: Type.String(),
+  status: Type.Union([
+    Type.Literal('DRAFT'),
+    Type.Literal('OPEN'),
+    Type.Literal('PAID'),
+    Type.Literal('VOID'),
+    Type.Literal('UNCOLLECTIBLE')
+  ]),
+  dueDate: DateTimeZoneSchema,
+  paidAt: Type.Optional(DateTimeZoneSchema),
+  created: ActionRecordSchema
+})
+
+export const DowngradeCooldownSchema = Type.Object({
+  cid: Type.String(),
+  wid: Type.String(),
+  lastDowngrade: DateTimeZoneSchema,
+  cooldownUntil: DateTimeZoneSchema,
+  fromTier: AccountTierSchema,
+  toTier: AccountTierSchema,
+  canChangeAt: DateTimeZoneSchema,
+  downgraded: ActionRecordSchema
+})
+
+// Connector Billing Schema - Per-connector tier and usage tracking
+export const ConnectorBillingSchema = Type.Object({
+  wid: Type.String(),
+  cid: Type.String(),
+  tier: AccountTierSchema,
+  status: Type.Union([
+    Type.Literal('ACTIVE'),
+    Type.Literal('PAUSED')
+  ]),
+  currentPeriod: Type.Object({
+    start: DateTimeZoneSchema,
+    end: DateTimeZoneSchema,
+    requestCount: Type.Number(),
+    billableRequests: Type.Number(),
+    estimatedCost: Type.Number()
+  }),
+  tierHistory: Type.Array(TierUpgradeEventSchema),
+  lastTierChange: Type.Optional(Type.Object({
+    date: DateTimeZoneSchema,
+    fromTier: AccountTierSchema,
+    toTier: AccountTierSchema,
+    cooldownUntil: Type.Optional(DateTimeZoneSchema)
+  })),
+  created: ActionRecordSchema,
+  updated: Type.Optional(ActionRecordSchema)
+})
+
+// ─── Subscription ─────────────────────────────────────────────────────────────
+
+export const SubscriptionSchema = Type.Object({
+	status:   Type.String(),
+	package:  Type.String(),
+	history:  Type.Array(Type.Any()),
+	datetime: DateTimeZoneSchema
+})
+
+export type AccountTier = Static<typeof AccountTierSchema>
+export type BillingStatus = Static<typeof BillingStatusSchema>
+export type TierConfig = Static<typeof TierConfigSchema>
+export type UsageRecord = Static<typeof UsageRecordSchema>
+export type TierUpgradeEvent = Static<typeof TierUpgradeEventSchema>
+export type ThresholdNotification = Static<typeof ThresholdNotificationSchema>
+export type AccountBilling = Static<typeof AccountBillingSchema>
+export type BillingInvoice = Static<typeof BillingInvoiceSchema>
+export type DowngradeCooldown = Static<typeof DowngradeCooldownSchema>
+export type ConnectorBilling = Static<typeof ConnectorBillingSchema>
+export type Subscription = Static<typeof SubscriptionSchema>
+
+export const TIER_CONFIGS: Record<AccountTier, TierConfig> = {
+  LITE: {
+    tier: 'LITE',
+    freeAllowance: 25000,
+    pricePerRequest: 0,
+    autoUpgradeThreshold: 25000,
+    features: [
+      'Full API access',
+      'Community support',
+      'Public documentation',
+      'No feature restrictions'
+    ],
+    rateLimit: {
+      requestsPerSecond: 10,
+      burstCapacity: 50
+    },
+    support: {
+      level: 'Community',
+      responseTime: 'Best effort (Discord/Forum)'
+    },
+    sla: {
+      uptime: 99.5,
+      hasPenalties: false
+    }
+  },
+  SCALE: {
+    tier: 'SCALE',
+    freeAllowance: 0,
+    pricePerRequest: 0.0025,
+    autoUpgradeThreshold: 1000000,
+    features: [
+      'All Developer features',
+      'Email support (24hr response)',
+      '99.9% uptime SLA',
+      'Enhanced rate limits',
+      'Beta feature access',
+      'Monthly usage reports'
+    ],
+    rateLimit: {
+      requestsPerSecond: 50,
+      burstCapacity: 200
+    },
+    support: {
+      level: 'Email',
+      responseTime: '24 hours'
+    },
+    sla: {
+      uptime: 99.9,
+      hasPenalties: false
+    }
+  },
+  VOLUME: {
+    tier: 'VOLUME',
+    freeAllowance: 0,
+    pricePerRequest: 0.001,
+    features: [
+      'All Pro features',
+      'Dedicated account manager',
+      'Priority support (4hr response)',
+      '99.95% uptime SLA with penalties',
+      'Custom contract terms',
+      'On-premise deployment options',
+      'White-label capabilities',
+      'Custom feature development',
+      'Quarterly business reviews'
+    ],
+    rateLimit: {
+      requestsPerSecond: 200,
+      burstCapacity: 1000
+    },
+    support: {
+      level: 'Priority',
+      responseTime: '4 hours (Slack channel)'
+    },
+    sla: {
+      uptime: 99.95,
+      hasPenalties: true
+    }
+  }
+}
+
+export const PRICING_CONSTANTS = {
+  LITE_FREE_LIMIT: 25000,
+  SCALE_UPGRADE_THRESHOLD: 25000,
+  VOLUME_UPGRADE_THRESHOLD: 1000000,
+  BASE_PRICE_PER_REQUEST: 0.0025,
+  NOTIFICATION_THRESHOLDS: {
+    WARNING_80: 0.8,
+    WARNING_95: 0.95,
+    UPGRADE_100: 1.0
+  },
+  DOWNGRADE_COOLDOWN_DAYS: 30,
+  CUSTOM_VOLUME_TIERS: [
+    { min: 1000000, max: 10000000, price: 0.0025 },
+    { min: 10000000, max: 50000000, price: 0.002 },
+    { min: 50000000, max: 100000000, price: 0.0018 },
+    { min: 100000000, max: Infinity, price: 0.0015 }
+  ]
+}

package/src/bucket.ts

@@ -0,0 +1,58 @@
+import { Type, Static } from '@sinclair/typebox'
+import { UserAssigneeSchema } from './user'
+import { ActionRecordSchema } from './time'
+import { ContextSchema } from './context'
+
+// ─── Bucket ───────────────────────────────────────────────────────────────────
+//
+// A Bucket groups multiple orders under a shared reference for consolidated
+// dispatch, routing, or workspace-level tracking.
+
+export const BucketLogSchema = Type.Intersect([
+	ActionRecordSchema,
+	Type.Object({
+		status: Type.Union([
+			Type.Literal('LSP_ASSIGNED'),
+			Type.Literal('LSP_UNASSIGNED'),
+			Type.Literal('WSP_ASSIGNED'),
+			Type.Literal('WSP_UNASSIGNED'),
+			Type.Literal('LOCKED'),
+			Type.Literal('UNLOCKED'),
+			Type.Literal('PACKAGED'),
+			Type.Literal('EXPIRED')
+		]),
+		assignee: Type.Optional(UserAssigneeSchema),
+		reason:   Type.Optional(Type.String({ maxLength: 500 }))
+	})
+])
+
+export const BucketSchema = Type.Object({
+	reference:   Type.String(),
+	PTC:         Type.Optional(Type.String()),
+	context:     ContextSchema,
+	name:        Type.Optional(Type.String({ maxLength: 100 })),
+	description: Type.Optional(Type.String({ maxLength: 500 })),
+	categories:  Type.Array(Type.String()),
+	tags:        Type.Optional(Type.Array(Type.String())),
+	items:       Type.Array(Type.String()),
+	assignees:   Type.Array(UserAssigneeSchema),
+	locked:      Type.Optional(Type.Boolean()),
+	packaged:    Type.Optional(Type.Boolean()),
+	logs:        Type.Array(BucketLogSchema),
+	created:     ActionRecordSchema,
+	updated:     Type.Optional(ActionRecordSchema)
+})
+
+export const BucketUpdateSchema = Type.Object({
+	PTC:         Type.Optional(Type.String()),
+	name:        Type.Optional(Type.String({ maxLength: 100 })),
+	description: Type.Optional(Type.String({ maxLength: 500 })),
+	categories:  Type.Optional(Type.Array(Type.String())),
+	tags:        Type.Optional(Type.Array(Type.String()))
+})
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type BucketLog    = Static<typeof BucketLogSchema>
+export type Bucket       = Static<typeof BucketSchema>
+export type BucketUpdate = Static<typeof BucketUpdateSchema>

package/src/context.ts

@@ -0,0 +1,167 @@
+import { Type, Static } from '@sinclair/typebox'
+import { AddressSchema, ContactsSchema, CompanySchema } from './geo'
+import { ActionRecordSchema } from './time'
+
+// ─── Service provider types ───────────────────────────────────────────────────
+
+export const SPCodeSchema = Type.String({
+	minLength: 3,
+	maxLength: 20,
+	description: 'Integration code for system reference'
+})
+
+export const SPTypeSchema = Type.Union([
+	// Logistics
+	Type.Literal('FLEET'),
+	Type.Literal('CARRIER'),
+	Type.Literal('WAREHOUSE'),
+	Type.Literal('TERMINAL'),
+	Type.Literal('HUB'),
+	Type.Literal('POD'),
+	Type.Literal('BROKER'),
+	Type.Literal('FORWARDER'),
+	Type.Literal('3PL'),
+	Type.Literal('4PL'),
+	// Commerce
+	Type.Literal('RETAIL'),
+	Type.Literal('VENDOR'),
+	Type.Literal('SHIPPER'),
+	Type.Literal('MANUFACTURER'),
+	// Professional services
+	Type.Literal('CONSULTANCY'),
+	Type.Literal('ENTERPRISE'),
+	Type.Literal('FREELANCE'),
+	// IoT — tracking & monitoring
+	Type.Literal('ASSET_TRACKING'),
+	Type.Literal('FLEET_TRACKING'),
+	Type.Literal('CARGO_MONITORING'),
+	Type.Literal('COLD_CHAIN'),
+	Type.Literal('LOCATION_SERVICES'),
+	// IoT — telematics
+	Type.Literal('TELEMATICS'),
+	Type.Literal('DRIVER_BEHAVIOR'),
+	Type.Literal('VEHICLE_DIAGNOSTICS'),
+	Type.Literal('FUEL_MONITORING'),
+	// IoT — sensors
+	Type.Literal('ENVIRONMENTAL_SENSORS'),
+	Type.Literal('SECURITY_SENSORS'),
+	Type.Literal('SHOCK_VIBRATION'),
+	Type.Literal('LIGHT_EXPOSURE'),
+	// IoT — connectivity
+	Type.Literal('CONNECTIVITY_PROVIDER'),
+	Type.Literal('SATELLITE_IOT'),
+	Type.Literal('EDGE_COMPUTING'),
+	// IoT — platforms
+	Type.Literal('IOT_PLATFORM'),
+	Type.Literal('ANALYTICS'),
+	Type.Literal('INTEGRATION'),
+	// IoT — specialized
+	Type.Literal('WAREHOUSE_IOT'),
+	Type.Literal('YARD_MANAGEMENT'),
+	Type.Literal('SMART_LOCKS'),
+	Type.Literal('RFID'),
+	Type.Literal('BARCODE_SCANNING'),
+	// General
+	Type.Literal('HARDWARE_PROVIDER'),
+	Type.Literal('SOFTWARE_PROVIDER'),
+	Type.Literal('FULL_SOLUTION'),
+	Type.Literal('OTHER')
+])
+
+export const SPProfileSchema = Type.Object({
+	wid:         Type.String(),
+	xcode:       SPCodeSchema,
+	name:        Type.String({ minLength: 1, maxLength: 100 }),
+	description: Type.String({ maxLength: 1000 }),
+	logo:        Type.String({ format: 'uri', description: 'Logo URL' }),
+	contacts:    ContactsSchema,
+	address:     Type.Optional(AddressSchema),
+	website:     Type.Optional(Type.String({ format: 'uri' })),
+	company:     Type.Optional(CompanySchema),
+	created:     ActionRecordSchema,
+	updated:     Type.Optional(ActionRecordSchema)
+})
+export const SPProfileUpdateSchema = Type.Partial(
+	Type.Omit(SPProfileSchema, ['wid', 'xcode', 'created', 'updated'])
+)
+export const SPAvailabilitySchema = Type.Object({
+	isAcceptingOrders:   Type.Boolean(),
+	isFullyOperational:  Type.Boolean(),
+	hasCapacity:         Type.Boolean(),
+	healthStatus:        Type.Union([
+		Type.Literal('HEALTHY'),
+		Type.Literal('DEGRADED'),
+		Type.Literal('CRITICAL')
+	])
+})
+export const SPPerformanceSummarySchema = Type.Object({
+	reliability:          Type.Number({ minimum: 0, maximum: 100 }),
+	onTimePerformance:    Type.Number({ minimum: 0, maximum: 100 }),
+	accuracy:             Type.Number({ minimum: 0, maximum: 100 }),
+	customerSatisfaction: Type.Number({ minimum: 0, maximum: 100 }),
+	capacityUtilization:  Type.Number({ minimum: 0, maximum: 100 }),
+	availableCapacity:    Type.Number({ minimum: 0, maximum: 100 }),
+	capacityStress:       Type.Number({ minimum: 0, maximum: 100 }),
+	operationalEfficiency: Type.Number({ minimum: 0, maximum: 100 }),
+	costEfficiency:        Type.Number({ minimum: 0, maximum: 100 }),
+	performanceTrend: Type.Union([
+		Type.Literal('IMPROVING'),
+		Type.Literal('STABLE'),
+		Type.Literal('DECLINING')
+	]),
+	overallScore: Type.Number({ minimum: 0, maximum: 100 })
+})
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+export const ContextTypeSchema = Type.Union([
+	Type.Literal('WORKSPACE'),
+	Type.Literal('REALM'),
+	Type.Literal('IoTSP'),
+	Type.Literal('LSP'),
+	Type.Literal('CSP'),
+	Type.Literal('DEV')
+])
+export const ContextSchema = Type.Object({
+	wid:   Type.String(),      // Workspace ID
+	type:  ContextTypeSchema,
+	xcode: SPCodeSchema        // Service provider code
+})
+export const UserContextTypeSchema = Type.Union([
+	Type.Literal('LSP'),
+	Type.Literal('CSP'),
+	Type.Literal('DEV'),
+	Type.Literal('IoTSP'),
+])
+export const OperatorContextTypeSchema = Type.Union([
+	Type.Literal('LSP'),
+	Type.Literal('CSP'),
+	Type.Literal('DEV'),
+	Type.Literal('IoTSP')
+])
+export const GenericServiceContextSchema = Type.Object({
+	ptype:       SPTypeSchema,
+	type:        Type.Any(),   // warehouse | carrier | hub | ...
+	id:          Type.String(),
+	description: Type.Optional(Type.String({ minLength: 10, maxLength: 250 }))
+})
+export const PipelineContextSchema = Type.Object({
+	id:                     Type.String(),
+	description:            Type.Optional(Type.String({ minLength: 10, maxLength: 250 })),
+	applicabilityCriteria:  Type.Optional(Type.String())
+})
+
+// ─── TypeScript types ─────────────────────────────────────────────────────────
+
+export type SPCode                = Static<typeof SPCodeSchema>
+export type SPType                = Static<typeof SPTypeSchema>
+export type SPProfile             = Static<typeof SPProfileSchema>
+export type SPProfileUpdate       = Static<typeof SPProfileUpdateSchema>
+export type SPAvailability        = Static<typeof SPAvailabilitySchema>
+export type SPPerformanceSummary  = Static<typeof SPPerformanceSummarySchema>
+export type ContextType           = Static<typeof ContextTypeSchema>
+export type Context               = Static<typeof ContextSchema>
+export type UserContextType 			= Static<typeof UserContextTypeSchema>
+export type OperatorContextType   = Static<typeof OperatorContextTypeSchema>
+export type GenericServiceContext = Static<typeof GenericServiceContextSchema>
+export type PipelineContext       = Static<typeof PipelineContextSchema>