evo360-types 1.3.570 → 1.3.578

package/dist/apps/evo-telemedicine/zod-schemas.ts

@@ -0,0 +1,794 @@
+import { z } from "zod";
+import {
+  zFireDocSchema,
+  zFirestoreDateSchema,
+} from "../shared/zod-schemas";
+import { zTenantModuleEntitlementSchema } from "../evo-tenant/zod-schemas";
+
+// ======================================================
+// evo-telemedicine (feat-160) — zod schemas
+//
+// Espelhos À MÃO dos enums/interfaces em types/evo-telemedicine/index.ts (o
+// repo não gera um lado a partir do outro). Ao acrescentar um valor no `*Enum`
+// TS, acrescente aqui — e vice-versa. Doc schemas usam `.passthrough()` para
+// tolerar campos aditivos sem republish; command schemas são ESTRITOS (fronteira
+// HTTP) e nunca aceitam `tenant` no body.
+// ======================================================
+
+// ----- Enums ----------------------------------------------------------------
+
+/** Espelha `TeleconsultationStatusEnum`. */
+export const zTeleconsultationStatusSchema = z.enum([
+  "scheduled",
+  "open",
+  "live",
+  "reconnecting",
+  "ending",
+  "ended",
+  "cancelled",
+  "expired",
+]);
+
+/** Espelha `WaitingPolicyEnum`. */
+export const zWaitingPolicySchema = z.enum([
+  "manual_admit",
+  "auto_when_doctor_present",
+]);
+
+/** Espelha `TeleconsultationModeEnum`. */
+export const zTeleconsultationModeSchema = z.enum([
+  "audio_video",
+  "audio_only_allowed",
+]);
+
+/** Espelha `TeleconsultationProviderEnum`. */
+export const zTeleconsultationProviderSchema = z.enum(["realtimekit"]);
+
+/** Espelha `ParticipantRoleEnum`. */
+export const zParticipantRoleSchema = z.enum(["doctor", "patient"]);
+
+/** Espelha `ParticipantStateEnum`. */
+export const zParticipantStateSchema = z.enum([
+  "invited",
+  "verified",
+  "waiting",
+  "connected",
+  "disconnected",
+  "left",
+]);
+
+/** Espelha `PresenceStateEnum` (subconjunto reportável pelo cliente). */
+export const zPresenceStateSchema = z.enum([
+  "waiting",
+  "connected",
+  "disconnected",
+  "left",
+]);
+
+/** Espelha `IdentityLevelEnum`. */
+export const zIdentityLevelSchema = z.enum(["none", "weak", "strong"]);
+
+/** Espelha `RecordingStatusEnum`. */
+export const zRecordingStatusSchema = z.enum([
+  "idle",
+  "consent_pending",
+  "recording",
+  "stopping",
+  "failed",
+]);
+
+/** Espelha `TranscriptionStatusEnum`. */
+export const zTranscriptionStatusSchema = z.enum([
+  "not_requested",
+  "queued",
+  "processing",
+  "ready",
+  "failed",
+  "deleted",
+]);
+
+/** Espelha `ConsentSubjectEnum`. */
+export const zConsentSubjectSchema = z.enum([
+  "terms",
+  "privacy",
+  "recording",
+  "transcription",
+]);
+
+/** Espelha `ConsentDecisionEnum`. */
+export const zConsentDecisionSchema = z.enum([
+  "accepted",
+  "declined",
+  "withdrawn",
+]);
+
+/** Espelha `ConsentActorTypeEnum`. */
+export const zConsentActorTypeSchema = z.enum(["patient", "doctor"]);
+
+/** Espelha `ArtifactTypeEnum`. */
+export const zArtifactTypeSchema = z.enum([
+  "recording_audio_video",
+  "recording_audio",
+  "transcript",
+]);
+
+/** Espelha `ArtifactStatusEnum`. */
+export const zArtifactStatusSchema = z.enum([
+  "pending",
+  "processing",
+  "ready",
+  "failed",
+  "deleting",
+  "deleted",
+]);
+
+/** Espelha `AccessGrantKindEnum`. */
+export const zAccessGrantKindSchema = z.enum([
+  "qr_capability",
+  "launch_code",
+  "browser_session",
+  // feat-160 F7: `kind` de uma ENTRADA do `grant-index`, nunca de um grant.
+  "ics_capability",
+]);
+
+/** Espelha `AccessGrantStateEnum`. */
+export const zAccessGrantStateSchema = z.enum([
+  "active",
+  "consumed",
+  "blocked",
+  "revoked",
+  "expired",
+]);
+
+/** Espelha `AccessSendChannelKindEnum`. */
+export const zAccessSendChannelKindSchema = z.enum([
+  "whatsapp",
+  "email",
+  "manual",
+]);
+
+/** Espelha `EndedByTypeEnum`. */
+export const zEndedByTypeSchema = z.enum(["user", "system"]);
+
+/** Espelha `TeleconsultationEventActorTypeEnum`. */
+export const zTeleconsultationEventActorTypeSchema = z.enum([
+  "user",
+  "patient",
+  "system",
+  "provider",
+]);
+
+/** Espelha `TeleconsultationEventSourceEnum`. */
+export const zTeleconsultationEventSourceSchema = z.enum([
+  "api",
+  "webhook",
+  "appointment_reconciler",
+  "retention_job",
+  "sweep",
+]);
+
+/** Espelha `TeleconsultationEventTypeEnum`. ADITIVO: eventos já gravados dependem desta lista. */
+export const zTeleconsultationEventTypeSchema = z.enum([
+  "teleconsultation.created",
+  "teleconsultation.rescheduled",
+  "teleconsultation.cancelled",
+  "teleconsultation.expired",
+  "teleconsultation.diverged",
+  "access.created",
+  "access.link_revealed",
+  "access.revoked",
+  "access.exchanged",
+  "access.verification_failed",
+  "access.blocked",
+  "host.claimed",
+  "host.reassigned",
+  "waiting_policy.changed",
+  "doctor.prepared",
+  "doctor.joined",
+  "doctor.disconnected",
+  "doctor.rejoined",
+  "doctor.left",
+  "patient.verified",
+  "patient.waiting",
+  "patient.admitted",
+  "patient.rejected",
+  "patient.joined",
+  "patient.disconnected",
+  "patient.rejoined",
+  "patient.left",
+  "recording.consent_requested",
+  "recording.consent_accepted",
+  "recording.consent_declined",
+  "recording.consent_withdrawn",
+  "recording.started",
+  "recording.stopped",
+  "recording.failed",
+  "transcription.queued",
+  "transcription.ready",
+  "transcription.failed",
+  "transcription.deleted",
+  "consultation.started",
+  "consultation.reconnecting",
+  "consultation.ended",
+  "artifact.accessed",
+  "artifact.deleted",
+  "entitlement.denied",
+  "rollout.denied",
+  "permission.denied",
+  "webhook.observed",
+]);
+
+/** Espelha `WebhookEventStatusEnum`. */
+export const zWebhookEventStatusSchema = z.enum([
+  "pending",
+  "claimed",
+  "completed",
+  "failed",
+]);
+
+/** Espelha `LegalTextStatusEnum`. */
+export const zLegalTextStatusSchema = z.enum(["draft", "published", "retired"]);
+
+/** Espelha `TranscriptionProviderEnum`. */
+export const zTranscriptionProviderSchema = z.enum(["none", "realtimekit"]);
+
+/** Espelha `EntitlementAuditActionEnum`. */
+export const zEntitlementAuditActionSchema = z.enum(["set", "override", "revoke"]);
+
+/** Espelha `TelemedicineErrorCode`. */
+export const zTelemedicineErrorCodeSchema = z.enum([
+  "TENANT_MODULE_DISABLED",
+  "ROLLOUT_DISABLED",
+  "EMERGENCY_KILL",
+  "PERMISSION_DENIED",
+  "CAPABILITY_DISABLED",
+  "NOT_FOUND",
+  "ACCESS_WINDOW_CLOSED",
+  "HOST_CLAIMED_BY_OTHER",
+  "HOST_REQUIRED",
+  "CONSENT_REQUIRED",
+  "IDENTITY_REQUIRED",
+  "IDENTITY_VERIFICATION_FAILED",
+  "GRANT_BLOCKED",
+  "GRANT_INVALID",
+  "SESSION_INVALID",
+  "TELECONSULTATION_TERMINAL",
+  "INVALID_TRANSITION",
+  "VERSION_CONFLICT",
+  "WAITING_POLICY_LOCKED",
+  "RECORDING_ACTIVE",
+  "RECORDING_FAILED",
+  "TRANSCRIPTION_GATE_CLOSED",
+  "ARTIFACT_NOT_READY",
+  "PROVIDER_ERROR",
+  "RATE_LIMITED",
+  "VALIDATION_ERROR",
+]);
+
+// ----- Value objects ----------------------------------------------------------
+
+const zDate = zFirestoreDateSchema;
+const zDateNullable = zFirestoreDateSchema.nullable().optional();
+
+/** Metadata allowlisted (sem PII/conteúdo médico): só primitivos. */
+export const zTeleconsultationEventMetadataSchema = z.record(
+  z.string().min(1).max(60),
+  z.union([z.string().max(500), z.number(), z.boolean()])
+);
+
+export const zTeleconsultationEndedBySchema = z
+  .object({
+    type: zEndedByTypeSchema,
+    id: z.string().optional(),
+    reason: z.string().min(1).max(120),
+  })
+  .passthrough();
+
+export const zTeleconsultationEntitlementSnapshotSchema = z
+  .object({
+    version: z.number().int().min(0),
+    capabilities: z.record(
+      z.string(),
+      z.union([z.boolean(), z.number(), z.string()])
+    ),
+  })
+  .passthrough();
+
+export const zTeleconsultationEventActorSchema = z
+  .object({
+    type: zTeleconsultationEventActorTypeSchema,
+    id: z.string().optional(),
+  })
+  .passthrough();
+
+// ----- Documentos (por tenant) -------------------------------------------------
+
+/** Espelha `ITeleconsultation`. */
+export const zTeleconsultationSchema = zFireDocSchema
+  .extend({
+    calendar_id: z.string().min(1),
+    appointment_id: z.string().min(1),
+    patient_id: z.string().min(1),
+    scheduled_professional_id: z.string().optional(),
+    claimed_host_user_id: z.string().optional(),
+    claimed_host_at: zDateNullable,
+    mode: zTeleconsultationModeSchema,
+    status: zTeleconsultationStatusSchema,
+    waiting_policy: zWaitingPolicySchema,
+    scheduled_start_at: zDate,
+    scheduled_end_at: zDate,
+    doctor_access_from: zDate,
+    patient_access_from: zDate,
+    unused_expires_at: zDate,
+    reconnect_until: zDateNullable,
+    started_at: zDateNullable,
+    ended_at: zDateNullable,
+    ended_by: zTeleconsultationEndedBySchema.nullable().optional(),
+    provider: zTeleconsultationProviderSchema,
+    provider_meeting_id: z.string().optional(),
+    active_provider_session_id: z.string().optional(),
+    recording_status: zRecordingStatusSchema,
+    recording_request_id: z.string().optional(),
+    recording_terms_version: z.string().optional(),
+    recording_requested_at: zDateNullable,
+    recording_requested_by: z.string().optional(),
+    recording_started_at: zDateNullable,
+    recording_stopped_at: zDateNullable,
+    recording_failure_code: z.string().nullable().optional(),
+    recording_segment: z.number().int().min(0).optional(),
+    transcription_status: zTranscriptionStatusSchema,
+    provider_teardown_pending: z.boolean().optional(),
+    metadata_retention_until: zDateNullable,
+    entitlement_snapshot: zTeleconsultationEntitlementSnapshotSchema,
+    generation: z.number().int().min(0),
+    reschedule_count: z.number().int().min(0).optional(),
+    last_reconciled_appointment_version: z
+      .union([z.number(), z.string()])
+      .nullable()
+      .optional(),
+    last_reconciled_at: zDateNullable,
+    usage_metering_due_at: zDateNullable,
+    usage_metered_at: zDateNullable,
+    version: z.number().int().min(0),
+  })
+  .passthrough();
+
+/**
+ * Espelha `ITeleconsultationPrivateProvider` (subdoc `private/provider`).
+ *
+ * NÃO estende `zFireDocSchema`: o subdoc não é um IFireDoc (não tem `version`
+ * de concorrência nem `ref`), e é lido sempre pelo backend com `id` do snap.
+ */
+export const zTeleconsultationPrivateProviderSchema = z
+  .object({
+    id: z.string(),
+    tenant: z.string().min(1),
+    teleconsultation_id: z.string().min(1),
+    provider: zTeleconsultationProviderSchema,
+    provider_meeting_id: z.string().optional(),
+    active_provider_session_id: z.string().optional(),
+    provider_session_ids: z.array(z.string().min(1)).optional(),
+    provider_participant_ids: z.record(z.string(), z.string()).optional(),
+    active_provider_recording_id: z.string().nullable().optional(),
+    created_at: zDateNullable,
+    updated_at: zDateNullable,
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationParticipant`. */
+export const zTeleconsultationParticipantSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().min(1),
+    role: zParticipantRoleSchema,
+    actor_user_id: z.string().optional(),
+    patient_id: z.string().optional(),
+    provider_participant_id: z.string().optional(),
+    opaque_custom_participant_id: z.string().min(1),
+    state: zParticipantStateSchema,
+    identity_level: zIdentityLevelSchema.optional(),
+    admitted_at: zDateNullable,
+    connected_at: zDateNullable,
+    last_seen_at: zDateNullable,
+    disconnected_at: zDateNullable,
+    reconnect_count: z.number().int().min(0),
+  })
+  .passthrough();
+
+export const zTeleconsultationConsentEvidenceSchema = z
+  .object({
+    ui_locale: z.string().min(2).max(10),
+    session_id_hash: z.string().min(1),
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationConsent`. */
+export const zTeleconsultationConsentSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().min(1),
+    subject: zConsentSubjectSchema,
+    decision: zConsentDecisionSchema,
+    terms_version: z.string().min(1).max(40),
+    terms_content_hash: z.string().optional(),
+    participant_id: z.string().min(1),
+    actor_type: zConsentActorTypeSchema,
+    occurred_at: zDate,
+    correlation_id: z.string().min(1),
+    recording_request_id: z.string().optional(),
+    evidence: zTeleconsultationConsentEvidenceSchema,
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationArtifact`. */
+export const zTeleconsultationArtifactSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().min(1),
+    type: zArtifactTypeSchema,
+    segment: z.number().int().min(1),
+    status: zArtifactStatusSchema,
+    provider_artifact_id: z.string().optional(),
+    provider_session_id: z.string().optional(),
+    recording_request_id: z.string().optional(),
+    storage_bucket: z.string().optional(),
+    storage_object: z.string().optional(),
+    content_type: z.string().optional(),
+    size_bytes: z.number().int().min(0).optional(),
+    checksum: z.string().optional(),
+    started_at: zDateNullable,
+    ended_at: zDateNullable,
+    expires_at: zDateNullable,
+    deleted_at: zDateNullable,
+    error_code: z.string().optional(),
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationEvent` (append-only). */
+export const zTeleconsultationEventSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().min(1),
+    type: zTeleconsultationEventTypeSchema,
+    occurred_at: zDate,
+    actor: zTeleconsultationEventActorSchema,
+    source: zTeleconsultationEventSourceSchema,
+    correlation_id: z.string().min(1),
+    causation_id: z.string().optional(),
+    idempotency_key: z.string().optional(),
+    from_status: z.string().optional(),
+    to_status: z.string().optional(),
+    metadata: zTeleconsultationEventMetadataSchema.optional(),
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationWebhookEvent` (dedup + outbox). */
+export const zTeleconsultationWebhookEventSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().optional(),
+    provider: zTeleconsultationProviderSchema,
+    provider_event_id: z.string().min(1),
+    event_type: z.string().min(1),
+    payload_hash: z.string().optional(),
+    sanitized_payload: z
+      .record(
+        z.string(),
+        z.union([z.string(), z.number(), z.boolean(), z.null()])
+      )
+      .optional(),
+    status: zWebhookEventStatusSchema,
+    received_at: zDate,
+    claimed_at: zDateNullable,
+    claimed_by: z.string().optional(),
+    lease_until: zDateNullable,
+    processed_at: zDateNullable,
+    attempt: z.number().int().min(0),
+    next_attempt_at: zDateNullable,
+    result: z.string().optional(),
+    error_code: z.string().optional(),
+    correlation_id: z.string().min(1),
+    expires_at: zDate,
+  })
+  .passthrough();
+
+/** Espelha `ITeleconsultationAccessGrant`. `secret_hash` é HMAC — nunca o segredo. */
+export const zTeleconsultationAccessGrantSchema = zFireDocSchema
+  .extend({
+    teleconsultation_id: z.string().min(1),
+    role: zParticipantRoleSchema,
+    kind: zAccessGrantKindSchema,
+    secret_hash: z.string().min(1),
+    recipient_ref_hash: z.string().optional(),
+    actor_user_id: z.string().optional(),
+    participant_id: z.string().optional(),
+    state: zAccessGrantStateSchema,
+    expires_at: zDate,
+    consumed_at: zDateNullable,
+    revoked_at: zDateNullable,
+    revoked_by: z.string().optional(),
+    last_used_at: zDateNullable,
+    failed_attempts: z.number().int().min(0),
+    failed_window_started_at: zDateNullable,
+    blocked_until: zDateNullable,
+    parent_grant_id: z.string().optional(),
+    channel_kind: zAccessSendChannelKindSchema.optional(),
+    quick_reply_action_id: z.string().optional(),
+    version: z.number().int().min(0),
+  })
+  .passthrough();
+
+/** Espelha `ITelemedicineAppointmentIndex`. */
+export const zTelemedicineAppointmentIndexSchema = zFireDocSchema
+  .extend({
+    calendar_id: z.string().min(1),
+    appointment_id: z.string().min(1),
+    active_teleconsultation_id: z.string().nullable(),
+    generation: z.number().int().min(0),
+    last_reconciled_appointment_version: z
+      .union([z.number(), z.string()])
+      .nullable()
+      .optional(),
+    last_reconciled_at: zDateNullable,
+    last_teleconsultation_id: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+/** Espelha `ITelemedicineEntitlementAudit`. */
+export const zTelemedicineEntitlementAuditSchema = zFireDocSchema
+  .extend({
+    module: z.string().min(1).max(40),
+    action: zEntitlementAuditActionSchema,
+    before: zTenantModuleEntitlementSchema.nullable().optional(),
+    after: zTenantModuleEntitlementSchema,
+    actor: z
+      .object({
+        type: z.enum(["user", "system", "script"]),
+        id: z.string().optional(),
+      })
+      .passthrough(),
+    reason: z.string().min(1).max(500),
+    occurred_at: zDate,
+    correlation_id: z.string().optional(),
+  })
+  .passthrough();
+
+// ----- Documentos de plataforma -------------------------------------------------
+
+// Docs globais (`IFireGlobalDoc`): sem `tenant`.
+const zGlobalDocSchema = z.object({
+  id: z.string(),
+  ref: z.any().optional(),
+  model_ver: z.number().optional(),
+  version: z.number().optional(),
+  created_at: zDateNullable,
+  updated_at: zDateNullable,
+  deleted_at: zDateNullable,
+});
+
+/** Espelha `ITelemedicineLegalText` (standalone: `version` aqui é a versão do texto). */
+export const zTelemedicineLegalTextSchema = z
+  .object({
+    id: z.string(),
+    subject: zConsentSubjectSchema,
+    locale: z.string().min(2).max(10),
+    version: z.string().min(1).max(40),
+    title: z.string().min(1).max(200),
+    content_html: z.string().min(1),
+    content_hash: z.string().min(1),
+    published_at: zDateNullable,
+    effective_at: zDateNullable,
+    status: zLegalTextStatusSchema,
+    placeholders: z.array(z.string().min(1).max(60)).optional(),
+    created_at: zDateNullable,
+    updated_at: zDateNullable,
+  })
+  .passthrough();
+
+/** Espelha `ITelemedicineRollout`. Ausência do doc = deny. */
+export const zTelemedicineRolloutSchema = zGlobalDocSchema
+  .extend({
+    create_enabled: z.boolean(),
+    join_enabled: z.boolean(),
+    recording_enabled: z.boolean(),
+    transcription_enabled: z.boolean(),
+    emergency_kill: z.boolean(),
+    updated_at: zDate,
+    updated_by: z.string().min(1),
+  })
+  .passthrough();
+
+/** Espelha `ITelemedicineTranscriptionConfig`. */
+export const zTelemedicineTranscriptionConfigSchema = zGlobalDocSchema
+  .extend({
+    provider: zTranscriptionProviderSchema,
+    production_gate_approved: z.boolean(),
+    approved_by: z.string().optional(),
+    approved_at: zDateNullable,
+  })
+  .passthrough();
+
+/** Espelha `ITelemedicineGrantIndex`. */
+export const zTelemedicineGrantIndexSchema = zGlobalDocSchema
+  .extend({
+    tenant: z.string().min(1),
+    teleconsultation_id: z.string().min(1),
+    grant_id: z.string().min(1),
+    kind: zAccessGrantKindSchema.optional(),
+    expires_at: zDate,
+  })
+  .passthrough();
+
+// ----- Comandos (request bodies — fronteira HTTP, estritos) --------------------
+
+const zExpectedVersion = z.number().int().min(0).optional();
+const zReason = z.string().trim().min(1).max(500);
+
+/** `PATCH /waiting-policy` — espelha `IWaitingPolicyCommand`. */
+export const zWaitingPolicyCommandSchema = z
+  .object({
+    waiting_policy: zWaitingPolicySchema,
+    expected_version: zExpectedVersion,
+  })
+  .strict();
+
+/** `POST /reassign-host` — espelha `IReassignHostCommand` (motivo obrigatório, D22). */
+export const zReassignHostCommandSchema = z
+  .object({
+    to_user_id: z.string().trim().min(1).max(128),
+    reason: zReason,
+    expected_version: zExpectedVersion,
+  })
+  .strict();
+
+/** `POST /access/send` — espelha `IAccessSendCommand`. */
+export const zAccessSendCommandSchema = z
+  .object({
+    channel_kind: zAccessSendChannelKindSchema,
+    resend: z.boolean().optional(),
+  })
+  .strict();
+
+/** `POST /access/revoke` — espelha `IAccessRevokeCommand`. */
+export const zAccessRevokeCommandSchema = z
+  .object({
+    grant_id: z.string().trim().min(1).max(128).optional(),
+    reason: zReason,
+  })
+  .strict();
+
+/** `POST /end` — espelha `IEndCommand`. */
+export const zEndCommandSchema = z
+  .object({
+    reason: z.string().trim().min(1).max(120).optional(),
+    expected_version: zExpectedVersion,
+  })
+  .strict();
+
+/** `POST /api/room/v1/exchange` — espelha `IExchangeCommand` (code base64url de 128 bits = 22 chars). */
+export const zExchangeCommandSchema = z
+  .object({
+    code: z
+      .string()
+      .trim()
+      .min(16)
+      .max(128)
+      .regex(/^[A-Za-z0-9_-]+$/, "code must be base64url"),
+  })
+  .strict();
+
+/** `POST /api/room/v1/identity/verify` — espelha `IIdentityVerifyCommand`. */
+export const zIdentityVerifyCommandSchema = z
+  .object({
+    display_name: z.string().trim().min(2).max(120),
+    // Normalizada no cliente para YYYY-MM-DD; o backend normaliza de novo antes
+    // da comparação constant-time. Erro de formato NÃO revela qual campo falhou.
+    birth_date: z
+      .string()
+      .trim()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, "birth_date must be YYYY-MM-DD")
+      .optional(),
+  })
+  .strict();
+
+/** `POST /api/room/v1/consents` — espelha `IConsentCommand` (só `accepted|declined`; retirada é rota de gravação). */
+export const zConsentCommandSchema = z
+  .object({
+    subject: zConsentSubjectSchema,
+    terms_version: z.string().trim().min(1).max(40),
+    decision: z.enum(["accepted", "declined"]),
+  })
+  .strict();
+
+/**
+ * `POST /api/room/v1/join` — espelha `IJoinCommand`.
+ *
+ * `.passthrough()`, não `.strict()`, ao contrário dos outros comandos: o
+ * backend hoje LÊ os dois booleanos à mão e ignora o resto, e o corpo é a
+ * intenção de mídia do preflight. Trocar por `.strict()` faria um campo novo do
+ * SPA derrubar o join inteiro em `400` — alto preço para um corpo que o
+ * servidor pode ignorar por completo.
+ */
+export const zJoinCommandSchema = z
+  .object({
+    audio: z.boolean().optional(),
+    video: z.boolean().optional(),
+  })
+  .passthrough();
+
+/**
+ * `POST /api/room/v1/leave` — espelha `ILeaveCommand`.
+ *
+ * `.passthrough()` pelo mesmo motivo, agravado: este corpo chega pelo
+ * `pagehide` com `fetch(keepalive)` e é a ÚLTIMA chance de registrar a saída.
+ * Um 400 aqui é uma saída perdida, e o backend já trata corpo ausente
+ * (`reason` default `'temporary'`).
+ */
+export const zLeaveCommandSchema = z
+  .object({
+    reason: z.string().trim().min(1).max(60).optional(),
+  })
+  .passthrough();
+
+/** `POST /api/room/v1/presence` — espelha `IPresenceCommand`. */
+export const zPresenceCommandSchema = z
+  .object({
+    state: zPresenceStateSchema,
+    provider_participant_id: z.string().trim().min(1).max(128).optional(),
+  })
+  .strict();
+
+/** `POST /api/room/v1/admit` — espelha `IAdmitCommand`. */
+export const zAdmitCommandSchema = z
+  .object({
+    participant_id: z.string().trim().min(1).max(128),
+  })
+  .strict();
+
+/** `POST /api/room/v1/reject` — espelha `IRejectCommand`. */
+export const zRejectCommandSchema = z
+  .object({
+    participant_id: z.string().trim().min(1).max(128),
+    reason: z.string().trim().min(1).max(120).optional(),
+  })
+  .strict();
+
+/** `POST /api/room/v1/recording/request` — espelha `IRecordingRequestCommand`. */
+export const zRecordingRequestCommandSchema = z
+  .object({
+    recording_request_id: z.string().trim().min(8).max(128),
+  })
+  .strict();
+
+/** `POST /api/room/v1/recording/accept|decline|withdraw` — espelha `IRecordingConsentCommand`. */
+export const zRecordingConsentCommandSchema = z
+  .object({
+    recording_request_id: z.string().trim().min(8).max(128),
+    terms_version: z.string().trim().min(1).max(40),
+  })
+  .strict();
+
+/** `POST /api/room/v1/recording/stop` — espelha `IRecordingStopCommand`. */
+export const zRecordingStopCommandSchema = z
+  .object({
+    recording_request_id: z.string().trim().min(8).max(128).optional(),
+  })
+  .strict();
+
+/** `POST /api/room/v1/telemetry` — espelha `ITelemetryCommand`; nomes allowlisted no backend. */
+export const zTelemetryCommandSchema = z
+  .object({
+    events: z
+      .array(
+        z
+          .object({
+            name: z.string().trim().min(1).max(60),
+            at: z.string().datetime({ offset: true }),
+            attrs: z
+              .record(
+                z.string().min(1).max(40),
+                z.union([z.string().max(200), z.number(), z.boolean()])
+              )
+              .optional(),
+          })
+          .strict()
+      )
+      .min(1)
+      .max(50),
+  })
+  .strict();