@canonmsg/backend-contracts 1.9.0 → 2.1.0

package/dist/sseEvents.js

@@ -1,278 +0,0 @@
-// Wire contract v1 — SSE event envelope + per-family payload schemas.
-//
-// Grounded in what stream-service ACTUALLY emits (stream-service/src/stream.ts
-// + listeners.ts) and what @canonmsg/core's CanonStream consumes — not in
-// design-doc prose. Payload slots that stream-service passes through opaquely
-// (behavior policies, runtime snapshots, raw RTDB values) stay loose objects;
-// slots stream-service constructs field-by-field are closed.
-//
-// The golden fixtures in @canonmsg/test-fixtures parse under these schemas;
-// the future Python framework must pass the same fixtures.
-import { z } from 'zod';
-import { SerializedContactRequestSchema } from './contactRequest.js';
-import { SerializedMessageSchema, SerializedReactionsSchema } from './message.js';
-export const SseAccessPolicySchema = z.enum(['open', 'approval-required', 'owner-only']);
-// ── Lifecycle events ───────────────────────────────────────────────────
-export const SseConnectedPayloadSchema = z.object({
-    connectionId: z.string(),
-    agentId: z.string(),
-});
-/** Trusted, server-injected identity & access info (stream.ts `agent.context`). */
-export const SseAgentContextPayloadSchema = z.looseObject({
-    agentId: z.string(),
-    canonContactId: z.string().optional(),
-    clientType: z.string().optional(),
-    ownerId: z.string(),
-    ownerName: z.string(),
-    /** Resolved agent behavior policy — passed through opaquely. */
-    defaultBehavior: z.record(z.string(), z.unknown()).optional(),
-    inboundPolicy: SseAccessPolicySchema,
-    groupJoinPolicy: SseAccessPolicySchema,
-    discoverable: z.boolean(),
-});
-export const SseHeartbeatPayloadSchema = z.object({
-    timestamp: z.string(),
-});
-export const SseReplayExpiredPayloadSchema = z.looseObject({
-    lastAvailableId: z.string().nullable().optional(),
-    message: z.string().optional(),
-});
-export const SseErrorPayloadSchema = z.looseObject({
-    code: z.string().optional(),
-    message: z.string().optional(),
-    retryAfterMs: z.number().optional(),
-    activeConnections: z.number().optional(),
-    maxConnections: z.number().optional(),
-});
-// ── Messages family ────────────────────────────────────────────────────
-export const SseSelfContextSchema = z.object({
-    id: z.string(),
-    type: z.literal('cross_session'),
-    context: z.string(),
-    createdAt: z.string().nullable(),
-    updatedAt: z.string().nullable(),
-});
-export const SseTurnDispatchSchema = z.looseObject({
-    kind: z.enum(['run_turn', 'observe_only']),
-    reason: z.string(),
-    addressed: z.boolean(),
-    policyVersion: z.string().optional(),
-});
-export const SseProvenanceSchema = z.looseObject({
-    conversation: z.looseObject({
-        id: z.string(),
-        type: z.enum(['direct', 'group', 'unknown']),
-    }),
-    sender: z.looseObject({
-        id: z.string(),
-        name: z.string().optional(),
-        type: z.enum(['human', 'ai_agent']),
-        isOwner: z.boolean(),
-    }),
-    mentionedAgent: z.boolean(),
-});
-/**
- * `message.created` — the inbound message envelope. `message` is exactly the
- * SerializedMessage the shared serializer emits (the E2EE S1 slot).
- */
-export const SseMessageCreatedPayloadSchema = z.looseObject({
-    conversationId: z.string(),
-    /** Resolved agent behavior policy — passed through opaquely. */
-    behavior: z.record(z.string(), z.unknown()).optional(),
-    activeSelfContextId: z.string().nullable().optional(),
-    selfContexts: z.array(SseSelfContextSchema).optional(),
-    provenance: SseProvenanceSchema.optional(),
-    turnDispatch: SseTurnDispatchSchema.optional(),
-    message: SerializedMessageSchema,
-});
-export const SseMessageUpdatedPayloadSchema = z.object({
-    conversationId: z.string(),
-    messageId: z.string(),
-    actorId: z.string().optional(),
-    updatedAt: z.string().optional(),
-    changes: z.looseObject({
-        reactions: SerializedReactionsSchema,
-    }),
-});
-export const SseMessageDeletedPayloadSchema = z.object({
-    conversationId: z.string(),
-    messageId: z.string(),
-});
-export const SseMembershipChangeSchema = z.object({
-    addedMemberIds: z.array(z.string()),
-    removedMemberIds: z.array(z.string()),
-    memberCount: z.number(),
-});
-export const SseConversationUpdatedPayloadSchema = z.object({
-    conversationId: z.string(),
-    changes: z.record(z.string(), z.unknown()),
-    membershipChange: SseMembershipChangeSchema.optional(),
-});
-// ── Contacts family ────────────────────────────────────────────────────
-/** `contact.request` / `contact.approved` carry the serialized contact request. */
-export const SseContactRequestPayloadSchema = SerializedContactRequestSchema;
-/**
- * `contact.added` / `contact.updated`. `source` is a pass-through string —
- * canonical values today: direct_add, phone_book, contact_request, link, qr,
- * group, open_inbound_message, unknown.
- */
-export const SseContactPayloadSchema = z.object({
-    id: z.string(),
-    source: z.string(),
-    addedAt: z.string().nullable(),
-    displayNameOverride: z.string().nullable(),
-});
-export const SseContactRemovedPayloadSchema = z.object({
-    id: z.string(),
-});
-// ── Typing / presence family ───────────────────────────────────────────
-export const SseTypingPayloadSchema = z.object({
-    conversationId: z.string(),
-    userId: z.string(),
-    isTyping: z.boolean(),
-    status: z.enum(['thinking', 'typing']).optional(),
-    timestamp: z.number().optional(),
-});
-export const SsePresencePayloadSchema = z.object({
-    userId: z.string(),
-    online: z.boolean(),
-    lastSeen: z.string().optional(),
-});
-// ── Runtime / turn family ──────────────────────────────────────────────
-// `runtime.updated` / `turn.updated` were retired 2026-07 (zero consumers;
-// the bridge reads RTDB directly). `runtime.control` remains — it is the
-// planned event-push control transport (housecleaning plan §6 W2-A2).
-export const SseRuntimeControlKindSchema = z.enum([
-    'session',
-    'signal',
-    'primitive',
-    'runtimeInput',
-    'runtimeCard',
-    'runtimeApproval',
-]);
-export const SseRuntimeControlPayloadSchema = z.object({
-    conversationId: z.string(),
-    agentId: z.string(),
-    kind: SseRuntimeControlKindSchema,
-    requestId: z.string().optional(),
-    updatedAt: z.number().optional(),
-    value: z.record(z.string(), z.unknown()),
-});
-// ── Voice family ───────────────────────────────────────────────────────
-export const SseVoiceSessionSchema = z.looseObject({
-    id: z.string(),
-    conversationId: z.string(),
-    roomName: z.string(),
-    mode: z.enum(['human', 'runtime_voice']),
-    status: z.enum(['active', 'ended', 'error']),
-    createdBy: z.string(),
-    participantIds: z.array(z.string()),
-    participants: z.array(z.looseObject({
-        userId: z.string(),
-        userType: z.enum(['human', 'ai_agent', 'system']),
-        displayName: z.string().nullable(),
-        joinedAt: z.string().nullable(),
-        leftAt: z.string().nullable(),
-    })).optional(),
-    targetAgentId: z.string().nullable().optional(),
-    createdAt: z.string().nullable().optional(),
-    updatedAt: z.string().nullable().optional(),
-    endedAt: z.string().nullable().optional(),
-    error: z.string().nullable().optional(),
-});
-export const SseVoiceSessionEventPayloadSchema = z.object({
-    conversationId: z.string(),
-    session: SseVoiceSessionSchema,
-});
-// ── Envelope + registry ────────────────────────────────────────────────
-/**
- * Every SSE `event:` name stream-service emits today (stream.ts + listeners.ts;
- * mirrored by CanonStream's dispatch switch in core). NOTE: `contact.updated`
- * is emitted by stream-service but not yet consumed by CanonStream.
- */
-export const SSE_EVENT_TYPES = [
-    'connected',
-    'agent.context',
-    'heartbeat',
-    'message.created',
-    'message.updated',
-    'message.deleted',
-    'conversation.updated',
-    'contact.request',
-    'contact.approved',
-    'contact.added',
-    'contact.updated',
-    'contact.removed',
-    'typing',
-    'presence',
-    'runtime.control',
-    'voice.session.started',
-    'voice.session.ended',
-    'replay.expired',
-    'error',
-];
-export const SseEventTypeSchema = z.enum(SSE_EVENT_TYPES);
-/** Payload schema for every event type — the machine-readable event registry. */
-export const SSE_EVENT_PAYLOAD_SCHEMAS = {
-    'connected': SseConnectedPayloadSchema,
-    'agent.context': SseAgentContextPayloadSchema,
-    'heartbeat': SseHeartbeatPayloadSchema,
-    'message.created': SseMessageCreatedPayloadSchema,
-    'message.updated': SseMessageUpdatedPayloadSchema,
-    'message.deleted': SseMessageDeletedPayloadSchema,
-    'conversation.updated': SseConversationUpdatedPayloadSchema,
-    'contact.request': SseContactRequestPayloadSchema,
-    'contact.approved': SseContactRequestPayloadSchema,
-    'contact.added': SseContactPayloadSchema,
-    'contact.updated': SseContactPayloadSchema,
-    'contact.removed': SseContactRemovedPayloadSchema,
-    'typing': SseTypingPayloadSchema,
-    'presence': SsePresencePayloadSchema,
-    'runtime.control': SseRuntimeControlPayloadSchema,
-    'voice.session.started': SseVoiceSessionEventPayloadSchema,
-    'voice.session.ended': SseVoiceSessionEventPayloadSchema,
-    'replay.expired': SseReplayExpiredPayloadSchema,
-    'error': SseErrorPayloadSchema,
-};
-/**
- * Subscription families (`?events=` filter). Lifecycle events (`connected`,
- * `agent.context`, `heartbeat`, `replay.expired`, `error`) are always sent.
- */
-export const SSE_EVENT_FAMILIES = [
-    'messages',
-    'contacts',
-    'typing_presence',
-    'runtime_turn',
-    'voice',
-];
-export const SseEventFamilySchema = z.enum(SSE_EVENT_FAMILIES);
-export const SSE_EVENT_FAMILY_BY_TYPE = {
-    'connected': 'lifecycle',
-    'agent.context': 'lifecycle',
-    'heartbeat': 'lifecycle',
-    'message.created': 'messages',
-    'message.updated': 'messages',
-    'message.deleted': 'messages',
-    'conversation.updated': 'messages',
-    'contact.request': 'contacts',
-    'contact.approved': 'contacts',
-    'contact.added': 'contacts',
-    'contact.updated': 'contacts',
-    'contact.removed': 'contacts',
-    'typing': 'typing_presence',
-    'presence': 'typing_presence',
-    'runtime.control': 'runtime_turn',
-    'voice.session.started': 'voice',
-    'voice.session.ended': 'voice',
-    'replay.expired': 'lifecycle',
-    'error': 'lifecycle',
-};
-/**
- * A parsed SSE frame: `id:` (replay cursor), `event:`, and the JSON-decoded
- * `data:` payload. Validate `data` with SSE_EVENT_PAYLOAD_SCHEMAS[event].
- */
-export const SseEventEnvelopeSchema = z.object({
-    id: z.string().optional(),
-    event: SseEventTypeSchema,
-    data: z.unknown(),
-});