@wildo-ai/saas-models 1.0.1

package/dist/esm/requests/websocket.shared.schemas.js

@@ -0,0 +1,682 @@
+import { z } from 'zod';
+import { DataMode } from '../resources/resources-config.shared.schemas.js';
+import { FrontendDisplayHintsSchema } from '../notifications/notifications.shared.schemas.js';
+import { ValueMomentRole, ValueMomentScope } from '../config/analytics-value-moments.shared.schemas.js';
+import { OnboardingStatus } from '../config/frontend/onboarding.shared.schemas.js';
+import { GuidanceFlowScope, GuidanceRenderMode } from '../guidance/guidance-flow.shared.schemas.js';
+import { ProgressionScope, MilestoneRewardType } from '../guidance/milestone-definition.shared.schemas.js';
+import { LifecycleStage, LifecycleScope } from '../guidance/lifecycle-state.shared.schemas.js';
+import { ResourcePrimaryScope } from '../resources/resources.shared.schemas.js';
+// =====================================================
+// WebSocket Event Types (Core Framework Events)
+// =====================================================
+/**
+ * Core WebSocket events defined by the engine.
+ * Custom events use the RESOURCE_CUSTOM type with eventName field.
+ */
+export var CoreWebSocketEvent;
+(function (CoreWebSocketEvent) {
+    // === Room Management Events (client → server) ===
+    CoreWebSocketEvent["RESOURCE_SUBSCRIBE"] = "resource:subscribe";
+    CoreWebSocketEvent["RESOURCE_UNSUBSCRIBE"] = "resource:unsubscribe";
+    CoreWebSocketEvent["RESOURCE_SUBSCRIBED"] = "resource:subscribed";
+    CoreWebSocketEvent["RESOURCE_UNSUBSCRIBED"] = "resource:unsubscribed";
+    // === Target-Based Notification Events (server → client, via identity rooms) ===
+    CoreWebSocketEvent["RESOURCE_NOTIFICATION"] = "resource:notification";
+    CoreWebSocketEvent["USER_NOTIFICATION"] = "user:notification";
+    CoreWebSocketEvent["BADGE_UPDATE"] = "badge:update";
+    CoreWebSocketEvent["BADGE_GET"] = "badge:get";
+    CoreWebSocketEvent["BADGE_GET_ALL"] = "badge:get-all";
+    // === Resource Room Events (bidirectional, via resource rooms) ===
+    CoreWebSocketEvent["RESOURCE_UPDATED"] = "resource:updated";
+    CoreWebSocketEvent["RESOURCE_DELETED"] = "resource:deleted";
+    CoreWebSocketEvent["RESOURCE_EDITING_START"] = "resource:editing:start";
+    CoreWebSocketEvent["RESOURCE_EDITING_END"] = "resource:editing:end";
+    CoreWebSocketEvent["RESOURCE_EDITING_STARTED"] = "resource:editing:started";
+    CoreWebSocketEvent["RESOURCE_EDITING_ERROR"] = "resource:editing:error";
+    CoreWebSocketEvent["RESOURCE_LOCKED"] = "resource:locked";
+    CoreWebSocketEvent["RESOURCE_UNLOCKED"] = "resource:unlocked";
+    CoreWebSocketEvent["RESOURCE_CUSTOM"] = "resource:custom";
+    CoreWebSocketEvent["RESOURCE_CUSTOM_ERROR"] = "resource:custom:error";
+    // === FlowsActors Events (bidirectional) ===
+    CoreWebSocketEvent["FLOWS_ACTORS_START"] = "flows-actors:start";
+    CoreWebSocketEvent["FLOWS_ACTORS_STARTED"] = "flows-actors:started";
+    CoreWebSocketEvent["FLOWS_ACTORS_MESSAGE"] = "flows-actors:message";
+    CoreWebSocketEvent["FLOWS_ACTORS_APPROVAL_REQUEST"] = "flows-actors:approval-request";
+    CoreWebSocketEvent["FLOWS_ACTORS_APPROVAL_RESPONSE"] = "flows-actors:approval-response";
+    CoreWebSocketEvent["FLOWS_ACTORS_STATUS_UPDATE"] = "flows-actors:status-update";
+    CoreWebSocketEvent["FLOWS_ACTORS_COMPLETED"] = "flows-actors:completed";
+    CoreWebSocketEvent["FLOWS_ACTORS_ERROR"] = "flows-actors:error";
+    // === Billing Events (server → client, invalidation triggers) ===
+    CoreWebSocketEvent["BILLING_STATUS_CHANGED"] = "billing:status_changed";
+    CoreWebSocketEvent["BILLING_SUBSCRIPTION_UPDATED"] = "billing:subscription_updated";
+    CoreWebSocketEvent["BILLING_ACCOUNT_CHANGED"] = "billing:account_changed";
+    CoreWebSocketEvent["BILLING_USAGE_UPDATED"] = "billing:usage_updated";
+    CoreWebSocketEvent["BILLING_CREDIT_POOL_UPDATED"] = "billing:credit_pool_updated";
+    CoreWebSocketEvent["BILLING_FEATURES_UPDATED"] = "billing:features_updated";
+    // === Analytics Events ===
+    CoreWebSocketEvent["ANALYTICS_MOMENT_ACHIEVED"] = "analytics:moment-achieved";
+    // === Guidance Events ===
+    CoreWebSocketEvent["GUIDANCE_STATE_CHANGED"] = "guidance:state-changed";
+    // === Progression Events ===
+    CoreWebSocketEvent["MILESTONE_ACHIEVED"] = "progression:milestone-achieved";
+    // === Lifecycle Events ===
+    CoreWebSocketEvent["LIFECYCLE_STAGE_CHANGED"] = "lifecycle:stage-changed";
+    // === System Events ===
+    CoreWebSocketEvent["AUTH_REFRESH"] = "auth:refresh";
+    CoreWebSocketEvent["ORGANIZATION_SWITCH"] = "organization:switch";
+    CoreWebSocketEvent["SYSTEM_TOKEN_REFRESHED"] = "system:token-refreshed";
+    CoreWebSocketEvent["SYSTEM_ERROR"] = "system:error";
+})(CoreWebSocketEvent || (CoreWebSocketEvent = {}));
+export var ResourceAction;
+(function (ResourceAction) {
+    ResourceAction["CREATED"] = "created";
+    ResourceAction["UPDATED"] = "updated";
+    ResourceAction["DELETED"] = "deleted";
+})(ResourceAction || (ResourceAction = {}));
+export const ResourceActionSchema = z.union([z.enum(ResourceAction), z.string()]);
+export var WebSocketResourceDeliveryTarget;
+(function (WebSocketResourceDeliveryTarget) {
+    WebSocketResourceDeliveryTarget["RESOURCE_ROOM_SYNC"] = "resource-room-sync";
+    WebSocketResourceDeliveryTarget["RESOURCE_ROOM_NOTIFICATION"] = "resource-room-notification";
+    WebSocketResourceDeliveryTarget["SCOPE_ROOM_NOTIFICATION"] = "scope-room-notification";
+})(WebSocketResourceDeliveryTarget || (WebSocketResourceDeliveryTarget = {}));
+export const WebSocketResourceDeliveryTargetSchema = z.enum(WebSocketResourceDeliveryTarget);
+// =====================================================
+// Common Schemas (reusable across payloads)
+// =====================================================
+export const ContextResourceIdentifiersSchema = z.record(z.string(), z.string());
+const WebSocketTimestampInputSchema = z.union([
+    z.date(),
+    z.string().datetime({ offset: true }),
+]);
+const WebSocketTimestampSchema = WebSocketTimestampInputSchema.pipe(z.coerce.date());
+const WebSocketOptionalTimestampSchema = WebSocketTimestampSchema.optional();
+// =====================================================
+// Room Management Payloads (client → server)
+// =====================================================
+const WS_ResourceSubscribePayloadBaseSchema = z.object({
+    resourceType: z.string().min(1),
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema,
+});
+/** Subscribe to a specific resource room. */
+const WS_ResourceSubscribeSinglePayloadSchema = WS_ResourceSubscribePayloadBaseSchema.extend({
+    resourceId: z.string().min(1),
+    scopeKey: z.undefined().optional(),
+    scopeId: z.undefined().optional(),
+});
+/** Subscribe to a scoped collection room. */
+const WS_ResourceSubscribeScopePayloadSchema = WS_ResourceSubscribePayloadBaseSchema.extend({
+    resourceId: z.undefined().optional(),
+    scopeKey: z.string().min(1),
+    scopeId: z.string().min(1),
+});
+/** Subscribe to a resource room - either single-resource or scoped collection. */
+export const WS_ResourceSubscribePayloadSchema = z.union([
+    WS_ResourceSubscribeSinglePayloadSchema,
+    WS_ResourceSubscribeScopePayloadSchema,
+]);
+/** Server confirmation of subscription */
+export const WS_ResourceSubscribedPayloadSchema = z.object({
+    roomName: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+    /** List of user IDs currently editing this resource (only for single resource subscriptions) */
+    editingUsers: z.array(z.string()).optional(),
+});
+// =====================================================
+// Notification Payloads (server → client, target-based)
+// =====================================================
+/**
+ * Notification level enum for typed notifications
+ */
+export var NotificationLevel;
+(function (NotificationLevel) {
+    NotificationLevel["INFO"] = "info";
+    NotificationLevel["SUCCESS"] = "success";
+    NotificationLevel["WARNING"] = "warning";
+    NotificationLevel["ERROR"] = "error";
+})(NotificationLevel || (NotificationLevel = {}));
+export const NotificationLevelSchema = z.enum(NotificationLevel);
+/** Resource notification via identity rooms (org, role, user) */
+export const WS_ResourceNotificationPayloadSchema = z.object({
+    // Operation path fields (for EventBus matching)
+    resourceType: z.string(),
+    operationIdentifier: z.string(),
+    isOperationDefault: z.boolean().default(false),
+    isBulkOperation: z.boolean().default(false),
+    variantKey: z.string().optional(),
+    // Context for scoped matching
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema.optional(),
+    // Notification data
+    action: ResourceActionSchema,
+    /** Explicit notification level (overrides action-based default) */
+    notificationLevel: NotificationLevelSchema.optional(),
+    affectedIds: z.array(z.string()),
+    notificationIdentifier: z.string().optional(),
+    initiatorUserId: z.string().optional(),
+    timestamp: WebSocketTimestampSchema.default(() => new Date()),
+    /**
+     * Frontend display hints (only populated for FRONT_END_SUCCESS channel).
+     * Contains optional celebration mode and next-step suggestion.
+     * Backend passes these through without interpreting them — the frontend
+     * reads them to decide rendering (toast vs overlay vs confetti, with or without CTA).
+     */
+    frontendDisplayHints: FrontendDisplayHintsSchema.optional(),
+});
+/** Badge count update */
+export const WS_BadgeUpdatePayloadSchema = z.object({
+    badgeReference: z.string(),
+    badgeCount: z.number().int().min(0),
+    organizationId: z.string().optional(),
+});
+/**
+ * Display target enum for user notifications
+ */
+export var NotificationDisplayTarget;
+(function (NotificationDisplayTarget) {
+    NotificationDisplayTarget["TOAST"] = "toast";
+    NotificationDisplayTarget["CENTER"] = "center";
+    NotificationDisplayTarget["BOTH"] = "both";
+})(NotificationDisplayTarget || (NotificationDisplayTarget = {}));
+export const NotificationDisplayTargetSchema = z.enum(NotificationDisplayTarget);
+/**
+ * Direct user notification (not tied to resource operation)
+ * Used for arbitrary backend-initiated notifications like:
+ * - "Your export is ready"
+ * - "Payment received"
+ * - "System maintenance scheduled"
+ */
+export const WS_UserNotificationPayloadSchema = z.object({
+    /** Notification level (info, success, warning, error) */
+    notificationLevel: NotificationLevelSchema,
+    /** i18n identifier for message lookup (FrontendNotificationCustomMessageRefs) */
+    identifier: z.string().optional(),
+    /** Direct message (fallback if identifier not found or not provided) */
+    message: z.string().optional(),
+    /** Optional notification title */
+    title: z.string().optional(),
+    /** Additional context data */
+    data: z.record(z.string(), z.unknown()).optional(),
+    /** Where to display the notification */
+    displayTarget: NotificationDisplayTargetSchema.default(NotificationDisplayTarget.BOTH),
+    /** Organization context (if notification is org-scoped) */
+    organizationId: z.string().optional(),
+    /** Timestamp */
+    timestamp: WebSocketTimestampSchema.default(() => new Date()),
+});
+// =====================================================
+// Analytics Payloads (server → client)
+// =====================================================
+/** Analytics moment achievement notification */
+export const WS_AnalyticsMomentAchievedPayloadSchema = z.object({
+    momentIdentifier: z.string(),
+    role: z.enum(ValueMomentRole),
+    scope: z.enum(ValueMomentScope),
+    scopeEntityId: z.string(),
+    achievedAt: WebSocketTimestampSchema,
+    triggerSource: z.enum(['frontend', 'backend']),
+});
+// =====================================================
+// Guidance Event Payloads
+// =====================================================
+/** Guidance state changed event — pushed by backend or frontend for real-time sync */
+export const GuidanceRealtimeStatusSchema = z.union([
+    z.literal(OnboardingStatus.IN_PROGRESS),
+    z.literal(OnboardingStatus.COMPLETED),
+    z.literal(OnboardingStatus.DISMISSED),
+]);
+/** Guidance state changed event — only statuses broadcast through the realtime bridge. */
+export const WS_GuidanceStateChangedPayloadSchema = z.object({
+    flowRef: z.string(),
+    status: GuidanceRealtimeStatusSchema,
+    elementRef: z.string().optional(),
+    triggerSource: z.enum(['frontend', 'backend']),
+    /** Which scope this event pertains to — determines how frontend routes state updates */
+    scope: z.enum(GuidanceFlowScope),
+    renderMode: z.enum(GuidanceRenderMode).optional(),
+});
+// =====================================================
+// Progression Event Payloads
+// =====================================================
+/** Milestone achieved event — pushed by backend when a milestone condition is met */
+export const WS_MilestoneAchievedPayloadSchema = z.object({
+    milestoneRef: z.string(),
+    category: z.string(),
+    points: z.number().int().optional(),
+    /** Which scope this milestone belongs to — determines how frontend routes state updates */
+    scope: z.enum(ProgressionScope),
+    reward: z.object({
+        type: z.enum(MilestoneRewardType),
+        featureRef: z.string().optional(),
+        guidanceFlowRef: z.string().optional(),
+        celebrationLevel: z.enum(['low', 'medium', 'high']).optional(),
+    }),
+    /** Phase 5 integration: lifecycle transition triggered by this milestone */
+    lifecycleTransition: z.object({
+        from: z.string(),
+        to: z.string(),
+    }).optional(),
+    /** Timestamp of achievement */
+    achievedAt: WebSocketTimestampSchema,
+    /** Updated total points (post-achievement) */
+    totalPoints: z.number().int(),
+});
+// =====================================================
+// Lifecycle Event Payloads
+// =====================================================
+/** Lifecycle stage changed event — pushed by backend when a lifecycle transition occurs */
+export const WS_LifecycleStageChangedPayloadSchema = z.object({
+    /** Previous stage before transition */
+    previousStage: z.enum(LifecycleStage),
+    /** New stage after transition */
+    newStage: z.enum(LifecycleStage),
+    /** Which scope this lifecycle state belongs to */
+    scope: z.enum(LifecycleScope),
+    /** What triggered the transition */
+    trigger: z.string().optional(),
+    /** When the transition occurred */
+    changedAt: WebSocketTimestampSchema,
+    /** Activation progress snapshot (for SIGNED_UP → ACTIVATED tracking) */
+    activationCriteriaMet: z.record(z.string(), z.boolean()).optional(),
+});
+// =====================================================
+// CRDT Field Metadata (shared between backend + frontend)
+// =====================================================
+/**
+ * Per-field CRDT metadata: server-authoritative timestamp + last editor.
+ * `meta` is an extensibility slot for future per-field metadata (e.g. merge strategy hints,
+ * conflict resolution context) without requiring a schema migration.
+ */
+export const FieldMetaEntrySchema = z.object({
+    ts: z.number(),
+    by: z.string(),
+    meta: z.record(z.string(), z.unknown()).optional(),
+});
+export const FieldMetaMapSchema = z.record(z.string(), FieldMetaEntrySchema);
+// =====================================================
+// Resource Room Payloads (path-independent collaboration)
+// =====================================================
+const ResourceUpdateSyncActionSchema = z.union([
+    z.literal(ResourceAction.CREATED),
+    z.literal(ResourceAction.UPDATED),
+]);
+const WS_ResourceEventCommonPayloadSchema = z.object({
+    resourceType: z.string(),
+    resourceId: z.string(),
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema,
+    affectedIds: z.array(z.string()).optional(),
+    timestamp: WebSocketTimestampSchema.default(() => new Date()),
+});
+const WS_ResourceUpdateNotificationPayloadCommonSchema = WS_ResourceEventCommonPayloadSchema.extend({
+    affectedIds: z.array(z.string()).min(1),
+    action: ResourceActionSchema,
+    operationIdentifier: z.string().optional(),
+    initiatorUserId: z.string().optional(),
+    version: z.number().optional(),
+    resourceData: z.unknown().optional(),
+    fieldMeta: FieldMetaMapSchema.optional(),
+    // DataMode values match directly: DataMode.RAW === 'raw', etc.
+    dataMode: z.enum(DataMode).optional(),
+});
+/** Notification-grade resource update event delivered to scope rooms. */
+export const WS_ScopeRoomUpdateNotificationPayloadSchema = WS_ResourceUpdateNotificationPayloadCommonSchema.extend({
+    deliveryTarget: z.literal(WebSocketResourceDeliveryTarget.SCOPE_ROOM_NOTIFICATION),
+});
+/** Notification-grade resource update event delivered to resource rooms. */
+export const WS_ResourceRoomUpdateNotificationPayloadSchema = WS_ResourceUpdateNotificationPayloadCommonSchema.extend({
+    deliveryTarget: z.literal(WebSocketResourceDeliveryTarget.RESOURCE_ROOM_NOTIFICATION),
+});
+export const WS_ResourceUpdateNotificationPayloadSchema = z.discriminatedUnion('deliveryTarget', [
+    WS_ScopeRoomUpdateNotificationPayloadSchema,
+    WS_ResourceRoomUpdateNotificationPayloadSchema,
+]);
+/** Synchronization-grade resource update event (resource rooms, RMM replay). */
+export const WS_ResourceSyncUpdatedPayloadSchema = WS_ResourceEventCommonPayloadSchema.extend({
+    deliveryTarget: z.literal(WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC),
+    action: ResourceUpdateSyncActionSchema,
+    operationIdentifier: z.string().min(1),
+    initiatorUserId: z.string().optional(),
+    version: z.number(),
+    resourceData: z.record(z.string(), z.unknown()),
+    fieldMeta: FieldMetaMapSchema.optional(),
+    dataMode: z.enum(DataMode).optional(),
+});
+/** Update events can be either notification-grade or sync-grade, distinguished explicitly. */
+export const WS_ResourceUpdatedPayloadSchema = z.discriminatedUnion('deliveryTarget', [
+    WS_ScopeRoomUpdateNotificationPayloadSchema,
+    WS_ResourceRoomUpdateNotificationPayloadSchema,
+    WS_ResourceSyncUpdatedPayloadSchema,
+]);
+/** Resource deleted event for resource rooms. */
+export const WS_ResourceDeletedPayloadSchema = WS_ResourceEventCommonPayloadSchema.extend({
+    deliveryTarget: z.literal(WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC),
+    action: z.literal(ResourceAction.DELETED),
+    operationIdentifier: z.string().min(1),
+    initiatorUserId: z.string().optional(),
+});
+/** Lightweight resource-room state payload for lock/unlock style events. */
+export const WS_ResourceRoomStatePayloadSchema = WS_ResourceEventCommonPayloadSchema.extend({
+    deliveryTarget: z.literal(WebSocketResourceDeliveryTarget.RESOURCE_ROOM_SYNC),
+    action: ResourceActionSchema.optional(),
+    operationIdentifier: z.string().optional(),
+    initiatorUserId: z.string().optional(),
+});
+/**
+ * Editing start/end payload
+ * - Incoming: contextResourceIdentifiers REQUIRED for UPDATE authorization
+ * - Outgoing (broadcast): contextResourceIdentifiers omitted
+ */
+export const WS_ResourceEditingPayloadSchema = z.object({
+    resourceType: z.string(),
+    resourceId: z.string(),
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema.optional(), // Required on input
+    initiatorUserId: z.string().optional(),
+    timestamp: WebSocketOptionalTimestampSchema,
+    reason: z.enum(['manual', 'disconnect', 'timeout', 'auth_refresh', 'organization_switch']).optional(), // For editing:end
+});
+/** Editing confirmation/error */
+export const WS_ResourceEditingResultPayloadSchema = z.object({
+    resourceType: z.string(),
+    resourceId: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+/**
+ * Custom collaboration event
+ * - Incoming: contextResourceIdentifiers REQUIRED for READ authorization
+ * - Outgoing (broadcast): contextResourceIdentifiers omitted
+ */
+export const WS_ResourceCustomEventPayloadSchema = z.object({
+    resourceType: z.string(),
+    resourceId: z.string(),
+    eventName: z.string().min(1), // Custom event name (e.g., 'cursor:move', 'comment:add')
+    data: z.unknown().optional(),
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema.optional(), // Required on input
+    initiatorUserId: z.string().optional(),
+    includeSelf: z.boolean().optional(), // Only for outgoing
+    timestamp: WebSocketOptionalTimestampSchema,
+    // Phase 7.1: Optional resource data for custom events with resource context
+    // When included, will be validated against appropriate DTO based on dataMode.
+    resourceData: z.unknown().optional(),
+    // DataMode values match directly: DataMode.RAW === 'raw', etc.
+    dataMode: z.enum(DataMode).optional(),
+});
+/** Error response for custom events */
+export const WS_ResourceCustomErrorPayloadSchema = z.object({
+    eventName: z.string(),
+    error: z.string(),
+});
+// =====================================================
+// Badge Request/Response Payloads
+// =====================================================
+/** Badge get request (client → server) */
+export const WS_BadgeGetRequestSchema = z.object({
+    identifier: z.string(),
+    scope: z.string(),
+    scopeId: z.string(),
+});
+/** Badge get-all request (client → server) */
+export const WS_BadgeGetAllRequestSchema = z.object({
+    scope: z.string(),
+    scopeId: z.string(),
+});
+/** Badge get-all response (server → client) */
+export const WS_BadgeGetAllResponseSchema = z.array(z.object({
+    identifier: z.string(),
+    count: z.number().min(0),
+}));
+// =====================================================
+// FlowsActors Payloads (bidirectional)
+// =====================================================
+/** Start a FlowActorSystem execution (client → server) */
+export const WS_FlowsActorsStartPayloadSchema = z.object({
+    systemRef: z.string().min(1),
+    executionId: z.string().optional(), // Server generates if not provided
+    contextResourceIdentifiers: ContextResourceIdentifiersSchema,
+    initialInput: z.record(z.string(), z.unknown()).optional(),
+});
+/** Confirmation of FlowActorSystem start (server → client) */
+export const WS_FlowsActorsStartedPayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    success: z.boolean(),
+    error: z.string().optional(),
+});
+/** Message from agent/flow (server → client) */
+export const WS_FlowsActorsMessagePayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    messageType: z.enum(['text', 'markdown', 'progress', 'data']),
+    content: z.string(),
+    data: z.record(z.string(), z.unknown()).optional(),
+    timestamp: WebSocketTimestampSchema.default(() => new Date()),
+});
+/** Human approval request (server → client) */
+export const WS_FlowsActorsApprovalRequestPayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    approvalId: z.string(),
+    actionDescription: z.string(),
+    riskLevel: z.enum(['low', 'medium', 'high', 'critical']),
+    requiredRoles: z.array(z.string()).optional(),
+    expiresAt: WebSocketOptionalTimestampSchema,
+});
+/** Human approval response (client → server) */
+export const WS_FlowsActorsApprovalResponsePayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    approvalId: z.string(),
+    approved: z.boolean(),
+    comment: z.string().optional(),
+});
+/** Status update during execution (server → client) */
+export const WS_FlowsActorsStatusUpdatePayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    status: z.string(),
+    progress: z.number().min(0).max(100).optional(),
+    currentStep: z.string().optional(),
+    timestamp: WebSocketTimestampSchema.default(() => new Date()),
+});
+/** Execution completed (server → client) */
+export const WS_FlowsActorsCompletedPayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    success: z.boolean(),
+    result: z.record(z.string(), z.unknown()).optional(),
+    duration: z.number().optional(), // in ms
+});
+/** Execution error (server → client) */
+export const WS_FlowsActorsErrorPayloadSchema = z.object({
+    systemRef: z.string(),
+    executionId: z.string(),
+    errorCode: z.string(),
+    errorMessage: z.string(),
+    recoverable: z.boolean().default(false),
+});
+// =====================================================
+// System Payloads
+// =====================================================
+export const WS_AuthRefreshPayloadSchema = z.object({
+    token: z.string(),
+});
+export const WS_OrganizationSwitchPayloadSchema = z.object({
+    organizationId: z.string(),
+    previousOrganizationId: z.string().optional(),
+});
+export const WS_SystemErrorPayloadSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+    details: z.unknown().optional(),
+});
+// =====================================================
+// Billing Payloads (server → client, invalidation triggers)
+// =====================================================
+export const WS_BillingEventPayloadSchema = z.object({
+    scopeType: z.enum(ResourcePrimaryScope),
+    scopeEntityId: z.string(),
+    billingAccountId: z.string(),
+});
+// =====================================================
+// Event-to-Schema Map (for validation)
+// =====================================================
+export const WebSocketEventSchemas = {
+    // Room management
+    [CoreWebSocketEvent.RESOURCE_SUBSCRIBE]: WS_ResourceSubscribePayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_UNSUBSCRIBE]: WS_ResourceSubscribePayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_SUBSCRIBED]: WS_ResourceSubscribedPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_UNSUBSCRIBED]: WS_ResourceSubscribedPayloadSchema,
+    // Notifications
+    [CoreWebSocketEvent.RESOURCE_NOTIFICATION]: WS_ResourceNotificationPayloadSchema,
+    [CoreWebSocketEvent.USER_NOTIFICATION]: WS_UserNotificationPayloadSchema,
+    [CoreWebSocketEvent.BADGE_UPDATE]: WS_BadgeUpdatePayloadSchema,
+    [CoreWebSocketEvent.BADGE_GET]: WS_BadgeGetRequestSchema,
+    [CoreWebSocketEvent.BADGE_GET_ALL]: WS_BadgeGetAllRequestSchema,
+    // Resource room events
+    [CoreWebSocketEvent.RESOURCE_UPDATED]: WS_ResourceUpdatedPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_DELETED]: WS_ResourceDeletedPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_EDITING_START]: WS_ResourceEditingPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_EDITING_END]: WS_ResourceEditingPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_EDITING_STARTED]: WS_ResourceEditingResultPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_EDITING_ERROR]: WS_ResourceEditingResultPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_LOCKED]: WS_ResourceRoomStatePayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_UNLOCKED]: WS_ResourceRoomStatePayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_CUSTOM]: WS_ResourceCustomEventPayloadSchema,
+    [CoreWebSocketEvent.RESOURCE_CUSTOM_ERROR]: WS_ResourceCustomErrorPayloadSchema,
+    // FlowsActors
+    [CoreWebSocketEvent.FLOWS_ACTORS_START]: WS_FlowsActorsStartPayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_STARTED]: WS_FlowsActorsStartedPayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_MESSAGE]: WS_FlowsActorsMessagePayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_APPROVAL_REQUEST]: WS_FlowsActorsApprovalRequestPayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_APPROVAL_RESPONSE]: WS_FlowsActorsApprovalResponsePayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_STATUS_UPDATE]: WS_FlowsActorsStatusUpdatePayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_COMPLETED]: WS_FlowsActorsCompletedPayloadSchema,
+    [CoreWebSocketEvent.FLOWS_ACTORS_ERROR]: WS_FlowsActorsErrorPayloadSchema,
+    // Billing
+    [CoreWebSocketEvent.BILLING_STATUS_CHANGED]: WS_BillingEventPayloadSchema,
+    [CoreWebSocketEvent.BILLING_SUBSCRIPTION_UPDATED]: WS_BillingEventPayloadSchema,
+    [CoreWebSocketEvent.BILLING_ACCOUNT_CHANGED]: WS_BillingEventPayloadSchema,
+    [CoreWebSocketEvent.BILLING_USAGE_UPDATED]: WS_BillingEventPayloadSchema,
+    [CoreWebSocketEvent.BILLING_CREDIT_POOL_UPDATED]: WS_BillingEventPayloadSchema,
+    [CoreWebSocketEvent.BILLING_FEATURES_UPDATED]: WS_BillingEventPayloadSchema,
+    // Analytics
+    [CoreWebSocketEvent.ANALYTICS_MOMENT_ACHIEVED]: WS_AnalyticsMomentAchievedPayloadSchema,
+    // Guidance
+    [CoreWebSocketEvent.GUIDANCE_STATE_CHANGED]: WS_GuidanceStateChangedPayloadSchema,
+    // Progression
+    [CoreWebSocketEvent.MILESTONE_ACHIEVED]: WS_MilestoneAchievedPayloadSchema,
+    // Lifecycle
+    [CoreWebSocketEvent.LIFECYCLE_STAGE_CHANGED]: WS_LifecycleStageChangedPayloadSchema,
+    // System
+    [CoreWebSocketEvent.AUTH_REFRESH]: WS_AuthRefreshPayloadSchema,
+    [CoreWebSocketEvent.ORGANIZATION_SWITCH]: WS_OrganizationSwitchPayloadSchema,
+    [CoreWebSocketEvent.SYSTEM_TOKEN_REFRESHED]: WS_AuthRefreshPayloadSchema,
+    [CoreWebSocketEvent.SYSTEM_ERROR]: WS_SystemErrorPayloadSchema,
+};
+// =====================================================
+// Room Naming Utilities
+// =====================================================
+/**
+ * WebSocket room name prefixes for different room types.
+ * These prefixes are used to create room names for Socket.IO.
+ */
+export var WebSocketRoomPrefix;
+(function (WebSocketRoomPrefix) {
+    /** User-specific room: user:{userId} */
+    WebSocketRoomPrefix["USER"] = "user";
+    /** Organization room: org:{organizationId} */
+    WebSocketRoomPrefix["ORGANIZATION"] = "org";
+    /** Organization role room: org:{organizationId}:role:{role} */
+    WebSocketRoomPrefix["ORGANIZATION_ROLE"] = "role";
+    /** Application-level role room: app:role:{role} */
+    WebSocketRoomPrefix["APP_ROLE"] = "app:role";
+    /** Resource room: resource:{resourceType}:{resourceId} */
+    WebSocketRoomPrefix["RESOURCE"] = "resource";
+    /** Public room for unauthenticated users */
+    WebSocketRoomPrefix["PUBLIC"] = "public";
+})(WebSocketRoomPrefix || (WebSocketRoomPrefix = {}));
+/**
+ * Build a user room name
+ */
+export function buildUserRoomName(userId) {
+    return `${WebSocketRoomPrefix.USER}:${userId}`;
+}
+/**
+ * Build an organization room name
+ */
+export function buildOrganizationRoomName(organizationId) {
+    return `${WebSocketRoomPrefix.ORGANIZATION}:${organizationId}`;
+}
+/**
+ * Build an organization role room name
+ */
+export function buildOrganizationRoleRoomName(organizationId, role) {
+    return `${WebSocketRoomPrefix.ORGANIZATION}:${organizationId}:${WebSocketRoomPrefix.ORGANIZATION_ROLE}:${role}`;
+}
+/**
+ * Build an application-level role room name
+ */
+export function buildAppRoleRoomName(role) {
+    return `${WebSocketRoomPrefix.APP_ROLE}:${role}`;
+}
+/**
+ * Build a resource room name
+ */
+export function buildResourceRoomName(resourceType, resourceId) {
+    return `${WebSocketRoomPrefix.RESOURCE}:${resourceType}:${resourceId}`;
+}
+/**
+ * Build a scope room name for collection subscriptions
+ */
+export function buildScopeRoomName(resourceType, scopeKey, scopeId) {
+    return `${WebSocketRoomPrefix.RESOURCE}:${resourceType}:${scopeKey}:${scopeId}`;
+}
+/**
+ * Parse a resource room name into its components
+ */
+export function parseResourceRoomName(roomName) {
+    const parts = roomName.split(':');
+    if (parts.length < 3 || parts[0] !== WebSocketRoomPrefix.RESOURCE)
+        return null;
+    if (parts.length === 3) {
+        return { resourceType: parts[1], resourceId: parts[2] };
+    }
+    else if (parts.length === 4) {
+        return { resourceType: parts[1], scopeKey: parts[2], scopeId: parts[3] };
+    }
+    return null;
+}
+/**
+ * Extract organization ID from an organization room name
+ */
+export function parseOrganizationRoomName(roomName) {
+    if (roomName.startsWith(`${WebSocketRoomPrefix.ORGANIZATION}:`)) {
+        // Handle both org:{orgId} and org:{orgId}:role:{role}
+        const parts = roomName.split(':');
+        return parts[1] || null;
+    }
+    return null;
+}
+// =====================================================
+// Validation Helpers
+// =====================================================
+/**
+ * Validate an incoming WebSocket event payload
+ */
+export function validateWebSocketPayload(event, payload) {
+    const schema = WebSocketEventSchemas[event];
+    return schema.parse(payload);
+}
+/**
+ * Safe validation (returns result instead of throwing)
+ */
+export function safeValidateWebSocketPayload(event, payload) {
+    const schema = WebSocketEventSchemas[event];
+    const result = schema.safeParse(payload);
+    if (result.success) {
+        return { success: true, data: result.data };
+    }
+    return { success: false, error: result.error };
+}
+//# sourceMappingURL=websocket.shared.schemas.js.map