evo360-types 1.3.570 → 1.3.574

package/dist/types/evo-telemedicine/index.ts

@@ -0,0 +1,1046 @@
+export * from "./fb_collections";
+import type { IFireDoc, IFireGlobalDoc } from "../shared";
+import type { ITenantModuleEntitlement } from "../evo-tenant";
+
+// ======================================================
+// evo-telemedicine (feat-160 — Telemedicina integrada)
+//
+// Contratos compartilhados entre `functions-telemedicine`, `packages/model`,
+// o web-app (painel) e o SPA `web-virtual-care`. Shapes seguem
+// `hub-medica-docs/features/feat-160-telemedicine-platform-mvp/data-model.md`.
+//
+// Regras que os tipos carregam:
+// - nada de PII do paciente (nome/telefone/e-mail/DOB), token do provider,
+//   capability `/qr`, cookie, URL assinada ou texto de transcrição nos docs;
+// - segredos de grant existem só como hash/HMAC (`secret_hash`);
+// - eventos são append-only e a `metadata` é allowlist sem PII/conteúdo médico;
+// - o acesso exige entitlement do tenant AND rollout operacional AND permissão.
+//
+// Convenção de datas: docs Firestore usam `Date` (como o resto do repo — o zod
+// converte Timestamp via `zFirestoreDateSchema`); DTOs HTTP usam ISO 8601 em
+// `string` (JSON não transporta Date).
+// ======================================================
+
+// ----- Permissões (spec §9.3)
+export const EvoTelemedicinePermissions = {
+  /** Ver estado e dados operacionais básicos. */
+  Read: "evo_telemedicine_read",
+  /** Preparar, admitir, entrar como médico e encerrar. */
+  Host: "evo_telemedicine_host",
+  /** Solicitar/iniciar/parar gravação. */
+  Record: "evo_telemedicine_record",
+  /** Listar e baixar gravações/transcrições. */
+  ArtifactsRead: "evo_telemedicine_artifacts_read",
+  /** Alterar defaults permitidos do tenant; reatribuir host. */
+  Configure: "evo_telemedicine_configure",
+  /** Consultar trilha detalhada (events). */
+  AuditRead: "evo_telemedicine_audit_read",
+} as const;
+
+export type EvoTelemedicinePermissions =
+  (typeof EvoTelemedicinePermissions)[keyof typeof EvoTelemedicinePermissions];
+
+// ----- Constantes de integração
+/** `action_type` do quick-reply `/qr` que redireciona para `/api/public/v1/enter/{cap}` (redirect puro, reexecutável). */
+export const TELEMEDICINE_JOIN_ACTION_TYPE = "telemedicine_join";
+
+/** Handler do lembrete/CTA de entrada — igual a `TaskAutoHandlerEnum.TelemedicineJoinReminder`. */
+export const TELEMEDICINE_JOIN_REMINDER_HANDLER = "telemedicine_join_reminder";
+
+/**
+ * Defaults de janela do MVP (spec §8.2/§8.3/D23) — configuráveis só em nível de
+ * plataforma. Em minutos, salvo indicação.
+ */
+export const TELEMEDICINE_WINDOW_DEFAULTS = {
+  /** Médico prepara/entra desde N minutos antes do início previsto. */
+  doctor_access_before_minutes: 30,
+  /** Paciente abre o fluxo desde N minutos antes do início previsto. */
+  patient_access_before_minutes: 15,
+  /** Se nunca iniciou: expira N minutos após o fim previsto. */
+  unused_expires_after_end_minutes: 120,
+  /** Reconexão após última presença do médico. */
+  reconnect_grace_minutes: 10,
+  /** Code one-time de exchange (`launch_code`). */
+  launch_code_ttl_minutes: 5,
+  /** Access da sessão pública do browser (`browser_session`), renovável de forma rotativa. */
+  browser_session_ttl_minutes: 15,
+  /** Verificação de identidade: N falhas na janela bloqueiam o grant. */
+  identity_max_failures: 5,
+  identity_failure_window_minutes: 15,
+  identity_block_minutes: 30,
+  /** URL assinada de artefato. */
+  signed_url_max_minutes: 5,
+  /** Bits aleatórios mínimos de capability/code. */
+  secret_min_bits: 128,
+} as const;
+
+// ----- Enums (espelhados à mão em apps/evo-telemedicine/zod-schemas.ts)
+
+/** Estado clínico da teleconsulta (spec §10). Presença é separada (`ParticipantState`). */
+export const TeleconsultationStatusEnum = {
+  /** Vínculo criado, janela fechada. */
+  Scheduled: "scheduled",
+  /** Janela aberta, nenhum encontro ativo. */
+  Open: "open",
+  /** Ao menos uma sessão física ativa ou presença clínica em curso. */
+  Live: "live",
+  /** Consulta iniciada, médico sem presença dentro da tolerância. */
+  Reconnecting: "reconnecting",
+  /** Encerramento em andamento; novos joins proibidos. */
+  Ending: "ending",
+  Ended: "ended",
+  Cancelled: "cancelled",
+  Expired: "expired",
+} as const;
+export type TeleconsultationStatus =
+  (typeof TeleconsultationStatusEnum)[keyof typeof TeleconsultationStatusEnum];
+
+/** Terminais: nunca ressuscitam (webhook atrasado, reschedule, join). */
+export const TELECONSULTATION_TERMINAL_STATUSES: readonly TeleconsultationStatus[] = [
+  "ended",
+  "cancelled",
+  "expired",
+] as const;
+
+export const WaitingPolicyEnum = {
+  /** Default. Médico admite manualmente. */
+  ManualAdmit: "manual_admit",
+  /** Entrada automática só com médico `connected` e `identity_level = strong`; nunca em sala vazia. */
+  AutoWhenDoctorPresent: "auto_when_doctor_present",
+} as const;
+export type WaitingPolicy = (typeof WaitingPolicyEnum)[keyof typeof WaitingPolicyEnum];
+
+export const TeleconsultationModeEnum = {
+  AudioVideo: "audio_video",
+  AudioOnlyAllowed: "audio_only_allowed",
+} as const;
+export type TeleconsultationMode =
+  (typeof TeleconsultationModeEnum)[keyof typeof TeleconsultationModeEnum];
+
+export const TeleconsultationProviderEnum = {
+  RealtimeKit: "realtimekit",
+} as const;
+export type TeleconsultationProvider =
+  (typeof TeleconsultationProviderEnum)[keyof typeof TeleconsultationProviderEnum];
+
+export const ParticipantRoleEnum = {
+  Doctor: "doctor",
+  Patient: "patient",
+} as const;
+export type ParticipantRole = (typeof ParticipantRoleEnum)[keyof typeof ParticipantRoleEnum];
+
+/** Presença — separada do estado clínico da teleconsulta. */
+export const ParticipantStateEnum = {
+  Invited: "invited",
+  Verified: "verified",
+  Waiting: "waiting",
+  Connected: "connected",
+  Disconnected: "disconnected",
+  Left: "left",
+} as const;
+export type ParticipantState =
+  (typeof ParticipantStateEnum)[keyof typeof ParticipantStateEnum];
+
+/** Subconjunto de `ParticipantState` que o cliente pode reportar em `POST /presence`. */
+export const PresenceStateEnum = {
+  Waiting: "waiting",
+  Connected: "connected",
+  Disconnected: "disconnected",
+  Left: "left",
+} as const;
+export type PresenceState = (typeof PresenceStateEnum)[keyof typeof PresenceStateEnum];
+
+/**
+ * Nível de verificação da identidade do paciente (spec §8.3): `strong` = nome +
+ * DOB conferidos; `weak` = só nome (paciente sem DOB) — proíbe `auto_admit`.
+ */
+export const IdentityLevelEnum = {
+  None: "none",
+  Weak: "weak",
+  Strong: "strong",
+} as const;
+export type IdentityLevel = (typeof IdentityLevelEnum)[keyof typeof IdentityLevelEnum];
+
+export const RecordingStatusEnum = {
+  Idle: "idle",
+  ConsentPending: "consent_pending",
+  Recording: "recording",
+  Stopping: "stopping",
+  Failed: "failed",
+} as const;
+export type RecordingStatus = (typeof RecordingStatusEnum)[keyof typeof RecordingStatusEnum];
+
+export const TranscriptionStatusEnum = {
+  NotRequested: "not_requested",
+  Queued: "queued",
+  Processing: "processing",
+  Ready: "ready",
+  Failed: "failed",
+  Deleted: "deleted",
+} as const;
+export type TranscriptionStatus =
+  (typeof TranscriptionStatusEnum)[keyof typeof TranscriptionStatusEnum];
+
+export const ConsentSubjectEnum = {
+  Terms: "terms",
+  Privacy: "privacy",
+  Recording: "recording",
+  Transcription: "transcription",
+} as const;
+export type ConsentSubject = (typeof ConsentSubjectEnum)[keyof typeof ConsentSubjectEnum];
+
+export const ConsentDecisionEnum = {
+  Accepted: "accepted",
+  Declined: "declined",
+  Withdrawn: "withdrawn",
+} as const;
+export type ConsentDecision = (typeof ConsentDecisionEnum)[keyof typeof ConsentDecisionEnum];
+
+export const ConsentActorTypeEnum = {
+  Patient: "patient",
+  Doctor: "doctor",
+} as const;
+export type ConsentActorType =
+  (typeof ConsentActorTypeEnum)[keyof typeof ConsentActorTypeEnum];
+
+export const ArtifactTypeEnum = {
+  RecordingAudioVideo: "recording_audio_video",
+  RecordingAudio: "recording_audio",
+  Transcript: "transcript",
+} as const;
+export type ArtifactType = (typeof ArtifactTypeEnum)[keyof typeof ArtifactTypeEnum];
+
+export const ArtifactStatusEnum = {
+  Pending: "pending",
+  Processing: "processing",
+  Ready: "ready",
+  Failed: "failed",
+  Deleting: "deleting",
+  Deleted: "deleted",
+} as const;
+export type ArtifactStatus = (typeof ArtifactStatusEnum)[keyof typeof ArtifactStatusEnum];
+
+export const AccessGrantKindEnum = {
+  /** Capability de 128 bits no link `/qr`; reexecutável na janela da teleconsulta. */
+  QrCapability: "qr_capability",
+  /** Code one-time de exchange (5 min) — médico (`/launch`) ou filho do `/enter`. */
+  LaunchCode: "launch_code",
+  /** Sessão do browser (cookie `__session`), 15 min, rotativa. */
+  BrowserSession: "browser_session",
+} as const;
+export type AccessGrantKind = (typeof AccessGrantKindEnum)[keyof typeof AccessGrantKindEnum];
+
+export const AccessGrantStateEnum = {
+  Active: "active",
+  Consumed: "consumed",
+  Blocked: "blocked",
+  Revoked: "revoked",
+  Expired: "expired",
+} as const;
+export type AccessGrantState =
+  (typeof AccessGrantStateEnum)[keyof typeof AccessGrantStateEnum];
+
+/** Canal pelo qual o CTA de acesso do paciente é (re)enviado. `manual` só devolve a URL mascarada (smoke). */
+export const AccessSendChannelKindEnum = {
+  WhatsApp: "whatsapp",
+  Email: "email",
+  Manual: "manual",
+} as const;
+export type AccessSendChannelKind =
+  (typeof AccessSendChannelKindEnum)[keyof typeof AccessSendChannelKindEnum];
+
+export const EndedByTypeEnum = {
+  User: "user",
+  System: "system",
+} as const;
+export type EndedByType = (typeof EndedByTypeEnum)[keyof typeof EndedByTypeEnum];
+
+export const TeleconsultationEventActorTypeEnum = {
+  User: "user",
+  Patient: "patient",
+  System: "system",
+  Provider: "provider",
+} as const;
+export type TeleconsultationEventActorType =
+  (typeof TeleconsultationEventActorTypeEnum)[keyof typeof TeleconsultationEventActorTypeEnum];
+
+export const TeleconsultationEventSourceEnum = {
+  Api: "api",
+  Webhook: "webhook",
+  AppointmentReconciler: "appointment_reconciler",
+  RetentionJob: "retention_job",
+  /** `telemed_sweep`: expiração de não usadas, timeout de reconexão, outbox órfã. */
+  Sweep: "sweep",
+} as const;
+export type TeleconsultationEventSource =
+  (typeof TeleconsultationEventSourceEnum)[keyof typeof TeleconsultationEventSourceEnum];
+
+/** Tipos de evento append-only (data-model §5 + acréscimos do plan). */
+export const TeleconsultationEventTypeEnum = {
+  TeleconsultationCreated: "teleconsultation.created",
+  TeleconsultationRescheduled: "teleconsultation.rescheduled",
+  TeleconsultationCancelled: "teleconsultation.cancelled",
+  TeleconsultationExpired: "teleconsultation.expired",
+  /** Alteração tardia na agenda com consulta já iniciada — tratamento operacional, não apaga o encontro. */
+  TeleconsultationDiverged: "teleconsultation.diverged",
+  AccessCreated: "access.created",
+  AccessRevoked: "access.revoked",
+  AccessExchanged: "access.exchanged",
+  AccessVerificationFailed: "access.verification_failed",
+  AccessBlocked: "access.blocked",
+  HostClaimed: "host.claimed",
+  HostReassigned: "host.reassigned",
+  WaitingPolicyChanged: "waiting_policy.changed",
+  DoctorPrepared: "doctor.prepared",
+  DoctorJoined: "doctor.joined",
+  DoctorDisconnected: "doctor.disconnected",
+  DoctorRejoined: "doctor.rejoined",
+  DoctorLeft: "doctor.left",
+  PatientVerified: "patient.verified",
+  PatientWaiting: "patient.waiting",
+  PatientAdmitted: "patient.admitted",
+  PatientRejected: "patient.rejected",
+  PatientJoined: "patient.joined",
+  PatientDisconnected: "patient.disconnected",
+  PatientRejoined: "patient.rejoined",
+  PatientLeft: "patient.left",
+  RecordingConsentRequested: "recording.consent_requested",
+  RecordingConsentAccepted: "recording.consent_accepted",
+  RecordingConsentDeclined: "recording.consent_declined",
+  RecordingConsentWithdrawn: "recording.consent_withdrawn",
+  RecordingStarted: "recording.started",
+  RecordingStopped: "recording.stopped",
+  RecordingFailed: "recording.failed",
+  TranscriptionQueued: "transcription.queued",
+  TranscriptionReady: "transcription.ready",
+  TranscriptionFailed: "transcription.failed",
+  TranscriptionDeleted: "transcription.deleted",
+  ConsultationStarted: "consultation.started",
+  ConsultationReconnecting: "consultation.reconnecting",
+  ConsultationEnded: "consultation.ended",
+  ArtifactAccessed: "artifact.accessed",
+  ArtifactDeleted: "artifact.deleted",
+  EntitlementDenied: "entitlement.denied",
+  RolloutDenied: "rollout.denied",
+  PermissionDenied: "permission.denied",
+  /** Evento do provider desconhecido/ignorado — registrado, não processado. */
+  WebhookObserved: "webhook.observed",
+} as const;
+export type TeleconsultationEventType =
+  (typeof TeleconsultationEventTypeEnum)[keyof typeof TeleconsultationEventTypeEnum];
+
+/** Outbox durável do webhook (data-model §6): claim/lease como o task-runner. */
+export const WebhookEventStatusEnum = {
+  Pending: "pending",
+  Claimed: "claimed",
+  Completed: "completed",
+  Failed: "failed",
+} as const;
+export type WebhookEventStatus =
+  (typeof WebhookEventStatusEnum)[keyof typeof WebhookEventStatusEnum];
+
+export const LegalTextStatusEnum = {
+  Draft: "draft",
+  Published: "published",
+  Retired: "retired",
+} as const;
+export type LegalTextStatus = (typeof LegalTextStatusEnum)[keyof typeof LegalTextStatusEnum];
+
+export const TranscriptionProviderEnum = {
+  None: "none",
+  RealtimeKit: "realtimekit",
+} as const;
+export type TranscriptionProvider =
+  (typeof TranscriptionProviderEnum)[keyof typeof TranscriptionProviderEnum];
+
+// ----- Value objects
+
+export interface ITeleconsultationEndedBy {
+  type: EndedByType;
+  /** userId quando `type = user`. */
+  id?: string;
+  /** Ex.: `doctor_end`, `reconnect_timeout`, `appointment_cancelled`, `unused_expired`, `emergency_kill`. */
+  reason: string;
+}
+
+/** Snapshot do entitlement no momento da criação — o gate vivo continua sendo `tenant.modules`. */
+export interface ITeleconsultationEntitlementSnapshot {
+  version: number;
+  capabilities: Record<string, boolean | number | string>;
+}
+
+export interface ITeleconsultationEventActor {
+  type: TeleconsultationEventActorType;
+  /** userId, participantId ou id opaco do provider — nunca nome/telefone. */
+  id?: string;
+}
+
+/** Metadata allowlisted — sem PII e sem conteúdo médico. */
+export type TeleconsultationEventMetadata = Record<string, string | number | boolean>;
+
+// ======================================================
+// Documentos (por tenant)
+// ======================================================
+
+/** `.../teleconsultations/{teleconsultationId}` (data-model §1). */
+export interface ITeleconsultation extends IFireDoc {
+  calendar_id: string;
+  appointment_id: string;
+  patient_id: string;
+  scheduled_professional_id?: string;
+  /** Claim transacional (D22): primeiro elegível vence; reassignment exige `configure` + motivo + evento. */
+  claimed_host_user_id?: string;
+  claimed_host_at?: Date | null;
+  mode: TeleconsultationMode;
+  status: TeleconsultationStatus;
+  waiting_policy: WaitingPolicy;
+  scheduled_start_at: Date;
+  scheduled_end_at: Date;
+  doctor_access_from: Date;
+  patient_access_from: Date;
+  unused_expires_at: Date;
+  reconnect_until?: Date | null;
+  started_at?: Date | null;
+  ended_at?: Date | null;
+  ended_by?: ITeleconsultationEndedBy | null;
+  provider: TeleconsultationProvider;
+  /** Id opaco do meeting no provider — nunca vai em external link nem no SPA. */
+  provider_meeting_id?: string;
+  active_provider_session_id?: string;
+  recording_status: RecordingStatus;
+  transcription_status: TranscriptionStatus;
+  entitlement_snapshot: ITeleconsultationEntitlementSnapshot;
+  /**
+   * Geração no `appointment-index`: incrementa quando o appointment volta a ser
+   * telemedicina depois de um estado terminal (nova teleconsulta, novo id).
+   */
+  generation: number;
+  /** Contagem de reagendamentos (SEQUENCE do ICS). */
+  reschedule_count?: number;
+  /** Última versão/data do appointment aplicada — descarta evento de reconciliação antigo. */
+  last_reconciled_appointment_version?: number | string | null;
+  last_reconciled_at?: Date | null;
+  /** Concorrência otimista: todo comando de estado é transação + `version`. */
+  version: number;
+  created_at: Date;
+  updated_at: Date;
+}
+
+/** `.../participants/{participantId}` (data-model §2). Id lógico estável; reconexão reutiliza o mesmo participante. */
+export interface ITeleconsultationParticipant extends IFireDoc {
+  teleconsultation_id: string;
+  role: ParticipantRole;
+  /** userId quando `role = doctor`. */
+  actor_user_id?: string;
+  /** patientId quando `role = patient`. */
+  patient_id?: string;
+  /** Id do participante no provider (pode ser renovado; o id lógico é o doc). */
+  provider_participant_id?: string;
+  /** `custom_participant_id` opaco enviado ao provider — nunca o patientId. */
+  opaque_custom_participant_id: string;
+  state: ParticipantState;
+  identity_level?: IdentityLevel;
+  admitted_at?: Date | null;
+  connected_at?: Date | null;
+  last_seen_at?: Date | null;
+  disconnected_at?: Date | null;
+  reconnect_count: number;
+  created_at: Date;
+  updated_at: Date;
+}
+
+export interface ITeleconsultationConsentEvidence {
+  ui_locale: string;
+  /** Hash da sessão pública — nunca o cookie/sid bruto. */
+  session_id_hash: string;
+}
+
+/** `.../consents/{consentId}` (data-model §3). Guarda versão/hash do texto, não o texto. */
+export interface ITeleconsultationConsent extends IFireDoc {
+  teleconsultation_id: string;
+  subject: ConsentSubject;
+  decision: ConsentDecision;
+  terms_version: string;
+  /** `content_hash` do legal text vigente na solicitação. */
+  terms_content_hash?: string;
+  participant_id: string;
+  actor_type: ConsentActorType;
+  occurred_at: Date;
+  correlation_id: string;
+  /** Vincula aceite/recusa/retirada de gravação à solicitação específica (data-model §11). */
+  recording_request_id?: string;
+  evidence: ITeleconsultationConsentEvidence;
+}
+
+/** `.../artifacts/{artifactId}` (data-model §4). Download só por endpoint `artifacts_read` + URL assinada ≤ 5 min. */
+export interface ITeleconsultationArtifact extends IFireDoc {
+  teleconsultation_id: string;
+  type: ArtifactType;
+  /** Segmento (1..n) — mais de uma sessão física do provider = vários segmentos da mesma teleconsulta. */
+  segment: number;
+  status: ArtifactStatus;
+  provider_artifact_id?: string;
+  provider_session_id?: string;
+  recording_request_id?: string;
+  storage_bucket?: string;
+  storage_object?: string;
+  content_type?: string;
+  size_bytes?: number;
+  checksum?: string;
+  started_at?: Date | null;
+  ended_at?: Date | null;
+  /** Retenção: o sweep deleta o objeto e só então marca `deleted` (auditoria preservada). */
+  expires_at?: Date | null;
+  error_code?: string;
+  created_at: Date;
+  updated_at: Date;
+}
+
+/** `.../events/{eventId}` (data-model §5) — append-only. */
+export interface ITeleconsultationEvent extends IFireDoc {
+  teleconsultation_id: string;
+  type: TeleconsultationEventType;
+  occurred_at: Date;
+  actor: ITeleconsultationEventActor;
+  source: TeleconsultationEventSource;
+  correlation_id: string;
+  causation_id?: string;
+  idempotency_key?: string;
+  from_status?: TeleconsultationStatus | string;
+  to_status?: TeleconsultationStatus | string;
+  metadata?: TeleconsultationEventMetadata;
+}
+
+/**
+ * `.../webhook-events/{providerEventId}` (data-model §6). Dedup + outbox durável:
+ * a recepção grava `pending` ANTES do 2xx; o worker faz claim, processa
+ * idempotentemente e marca `completed`. Sem payload bruto — só campos allowlisted.
+ */
+export interface ITeleconsultationWebhookEvent extends IFireDoc {
+  teleconsultation_id?: string;
+  provider: TeleconsultationProvider;
+  /** Id do evento no provider (= doc id; ex.: `rtk-uuid`). */
+  provider_event_id: string;
+  event_type: string;
+  /** Hash do corpo bruto (integridade/dedup) — nunca o corpo. */
+  payload_hash?: string;
+  /** Campos allowlisted do payload (ids opacos, status) — sem PII. */
+  sanitized_payload?: Record<string, string | number | boolean | null>;
+  status: WebhookEventStatus;
+  received_at: Date;
+  claimed_at?: Date | null;
+  claimed_by?: string;
+  lease_until?: Date | null;
+  processed_at?: Date | null;
+  attempt: number;
+  next_attempt_at?: Date | null;
+  result?: string;
+  error_code?: string;
+  correlation_id: string;
+  /** TTL nativo do Firestore. */
+  expires_at: Date;
+}
+
+/** `.../access-grants/{grantId}` (data-model §7). Segredo nunca persistido bruto. */
+export interface ITeleconsultationAccessGrant extends IFireDoc {
+  teleconsultation_id: string;
+  role: ParticipantRole;
+  kind: AccessGrantKind;
+  /** HMAC (chave rotacionável) do segredo; comparação constant-time. */
+  secret_hash: string;
+  /** Hash do destinatário (telefone/e-mail) — evita reenvio para contato diferente do agendamento. */
+  recipient_ref_hash?: string;
+  actor_user_id?: string;
+  participant_id?: string;
+  state: AccessGrantState;
+  expires_at: Date;
+  consumed_at?: Date | null;
+  revoked_at?: Date | null;
+  revoked_by?: string;
+  last_used_at?: Date | null;
+  failed_attempts: number;
+  failed_window_started_at?: Date | null;
+  blocked_until?: Date | null;
+  /** `launch_code` filho de `qr_capability`; `browser_session` filho do code/capability. */
+  parent_grant_id?: string;
+  /** Canal do envio que originou o grant (`qr_capability`). */
+  channel_kind?: AccessSendChannelKind;
+  /** Doc `quick-reply-actions/{actionId}` ligado ao grant — cancelado no revoke. */
+  quick_reply_action_id?: string;
+  version: number;
+  created_at: Date;
+  updated_at: Date;
+}
+
+/**
+ * `.../appointment-index/{calendarId}__{appointmentId}` (plan §2). Unicidade da
+ * teleconsulta ativa por appointment; o reconciliador transaciona sobre este doc.
+ */
+export interface ITelemedicineAppointmentIndex extends IFireDoc {
+  calendar_id: string;
+  appointment_id: string;
+  active_teleconsultation_id: string | null;
+  generation: number;
+  last_reconciled_appointment_version?: number | string | null;
+  updated_at: Date;
+}
+
+// ======================================================
+// Documentos de plataforma (`platform/evo-telemedicine/**`, só backend)
+// ======================================================
+
+/**
+ * `platform/evo-telemedicine/legal-texts/{subject}-{locale}-{version}` (data-model §9).
+ * Publish explícito, nunca overwrite. NÃO estende `IFireGlobalDoc`: aqui `version`
+ * é a versão do TEXTO (string, ex.: `v1`), não o contador de concorrência.
+ */
+export interface ITelemedicineLegalText {
+  readonly id: string;
+  subject: ConsentSubject;
+  locale: string;
+  version: string;
+  title: string;
+  /** HTML sanitizado; placeholders allowlisted (`{{clinic_name}}`, `{{clinic_contact}}`). */
+  content_html: string;
+  content_hash: string;
+  published_at?: Date | null;
+  effective_at?: Date | null;
+  status: LegalTextStatus;
+  placeholders?: string[];
+  created_at?: Date | null;
+  updated_at?: Date | null;
+}
+
+/** `platform/evo-telemedicine/config/rollout` (plan §2). Deny se ausente; cache 30 s. */
+export interface ITelemedicineRollout extends IFireGlobalDoc {
+  create_enabled: boolean;
+  join_enabled: boolean;
+  recording_enabled: boolean;
+  /** Só pode ser `true` em produção após o gate de D12. */
+  transcription_enabled: boolean;
+  /** Bloqueia tudo, inclusive consultas ao vivo (D19). */
+  emergency_kill: boolean;
+  updated_at: Date;
+  updated_by: string;
+}
+
+/** `platform/evo-telemedicine/config/transcription` (plan F9). */
+export interface ITelemedicineTranscriptionConfig extends IFireGlobalDoc {
+  provider: TranscriptionProvider;
+  /** `realtimekit` com `false` só funciona em staging. */
+  production_gate_approved: boolean;
+  approved_by?: string;
+  approved_at?: Date | null;
+}
+
+/** `platform/evo-telemedicine/grant-index/{hmac(cap)}` (plan §2). Só resolve o path; o grant tenant-scoped é a verdade. */
+export interface ITelemedicineGrantIndex extends IFireGlobalDoc {
+  tenant: string;
+  teleconsultation_id: string;
+  grant_id: string;
+  /** TTL nativo. */
+  expires_at: Date;
+}
+
+// ======================================================
+// Auditoria de entitlement (`.../entitlement-audit/{id}`, data-model §8)
+// ======================================================
+
+export const EntitlementAuditActionEnum = {
+  Set: "set",
+  Override: "override",
+  Revoke: "revoke",
+} as const;
+export type EntitlementAuditAction =
+  (typeof EntitlementAuditActionEnum)[keyof typeof EntitlementAuditActionEnum];
+
+export interface IEntitlementAuditActor {
+  type: "user" | "system" | "script";
+  id?: string;
+}
+
+/** Fora do doc do tenant, como pede o data-model. `before/after` são a projeção sanitizada (sem preço/contrato). */
+export interface ITelemedicineEntitlementAudit extends IFireDoc {
+  module: string;
+  action: EntitlementAuditAction;
+  before?: ITenantModuleEntitlement | null;
+  after: ITenantModuleEntitlement;
+  actor: IEntitlementAuditActor;
+  reason: string;
+  occurred_at: Date;
+  correlation_id?: string;
+}
+
+// ======================================================
+// Códigos de erro (plan §4 — `{ ok: false, error: '<CODE>', message? }` com status estável)
+// ======================================================
+
+export const TelemedicineErrorCode = {
+  /** 403 — entitlement ausente/inativo (sem bypass de super admin). */
+  TenantModuleDisabled: "TENANT_MODULE_DISABLED",
+  /** 403 — kill switch operacional (`create|join|recording|transcription`). */
+  RolloutDisabled: "ROLLOUT_DISABLED",
+  /** 403 — `emergency_kill` ligado. */
+  EmergencyKill: "EMERGENCY_KILL",
+  /** 403 — RBAC. */
+  PermissionDenied: "PERMISSION_DENIED",
+  /** 403 — capability do entitlement ausente/false (`recording`, `transcription`, `auto_admit`). */
+  CapabilityDisabled: "CAPABILITY_DISABLED",
+  /** 404 — teleconsulta/artefato/grant inexistente (ou genérico, em rota pública). */
+  NotFound: "NOT_FOUND",
+  /** 409 — fora da janela (antes de `*_access_from` ou após `unused_expires_at`). */
+  AccessWindowClosed: "ACCESS_WINDOW_CLOSED",
+  /** 409 — outro médico já fez o claim de host. */
+  HostClaimedByOther: "HOST_CLAIMED_BY_OTHER",
+  /** 409 — comando exige médico claimant presente (admit/end/recording). */
+  HostRequired: "HOST_REQUIRED",
+  /** 409 — termos/privacidade (ou gravação) não aceitos na versão vigente. */
+  ConsentRequired: "CONSENT_REQUIRED",
+  /** 409 — paciente ainda não verificou identidade. */
+  IdentityRequired: "IDENTITY_REQUIRED",
+  /** 401 — verificação de identidade falhou (erro neutro: não diz qual campo). */
+  IdentityVerificationFailed: "IDENTITY_VERIFICATION_FAILED",
+  /** 429 — grant bloqueado por excesso de falhas. */
+  GrantBlocked: "GRANT_BLOCKED",
+  /** 401 — grant/code inválido, consumido, expirado ou revogado (genérico por design). */
+  GrantInvalid: "GRANT_INVALID",
+  /** 401 — cookie `__session` ausente/inválido/expirado. */
+  SessionInvalid: "SESSION_INVALID",
+  /** 410 — estado terminal (`ended|cancelled|expired`). */
+  TeleconsultationTerminal: "TELECONSULTATION_TERMINAL",
+  /** 409 — transição de estado não permitida (spec §10). */
+  InvalidTransition: "INVALID_TRANSITION",
+  /** 409 — `expected_version` divergente. */
+  VersionConflict: "VERSION_CONFLICT",
+  /** 409 — política de espera só muda até o paciente entrar. */
+  WaitingPolicyLocked: "WAITING_POLICY_LOCKED",
+  /** 409 — já existe gravação ativa/pendente. */
+  RecordingActive: "RECORDING_ACTIVE",
+  /** 502 — provider falhou ao gravar (não derruba a consulta). */
+  RecordingFailed: "RECORDING_FAILED",
+  /** 403 — transcrição em produção sem gate aprovado (D12). */
+  TranscriptionGateClosed: "TRANSCRIPTION_GATE_CLOSED",
+  /** 409 — artefato não está `ready`. */
+  ArtifactNotReady: "ARTIFACT_NOT_READY",
+  /** 502 — erro do provider de mídia. */
+  ProviderError: "PROVIDER_ERROR",
+  /** 429 — rate limit por IP-hash/grant. */
+  RateLimited: "RATE_LIMITED",
+  /** 400 — body/params inválidos. */
+  ValidationError: "VALIDATION_ERROR",
+} as const;
+
+export type TelemedicineErrorCode =
+  (typeof TelemedicineErrorCode)[keyof typeof TelemedicineErrorCode];
+
+export interface ITelemedicineErrorResponse {
+  ok: false;
+  error: TelemedicineErrorCode;
+  message?: string;
+  error_id?: string;
+}
+
+// ======================================================
+// DTOs públicos — HTTP (plan §4). Datas em ISO 8601 (`string`).
+// ======================================================
+
+export interface ITeleconsultationParticipantDto {
+  participant_id: string;
+  role: ParticipantRole;
+  state: ParticipantState;
+  identity_level?: IdentityLevel;
+  admitted_at?: string | null;
+  connected_at?: string | null;
+  last_seen_at?: string | null;
+  disconnected_at?: string | null;
+  reconnect_count: number;
+}
+
+/** Estado do CTA de acesso do paciente, para a recepção — destinatário só mascarado. */
+export interface ITeleconsultationAccessSummaryDto {
+  grant_id?: string;
+  grant_state?: AccessGrantState;
+  channel_kind?: AccessSendChannelKind;
+  /** Ex.: `+55 11 9****-1234`, `l***@dominio.com`. */
+  recipient_masked?: string;
+  last_sent_at?: string | null;
+  expires_at?: string | null;
+}
+
+/** `GET /v1/appointments/:calendarId/:appointmentId/teleconsultation` (telemed_admin). */
+export interface ITeleconsultationSummaryDto {
+  id: string;
+  calendar_id: string;
+  appointment_id: string;
+  patient_id: string;
+  scheduled_professional_id?: string;
+  claimed_host_user_id?: string;
+  claimed_host_at?: string | null;
+  mode: TeleconsultationMode;
+  status: TeleconsultationStatus;
+  waiting_policy: WaitingPolicy;
+  scheduled_start_at: string;
+  scheduled_end_at: string;
+  doctor_access_from: string;
+  patient_access_from: string;
+  unused_expires_at: string;
+  reconnect_until?: string | null;
+  started_at?: string | null;
+  ended_at?: string | null;
+  ended_by?: ITeleconsultationEndedBy | null;
+  recording_status: RecordingStatus;
+  transcription_status: TranscriptionStatus;
+  entitlement_snapshot: ITeleconsultationEntitlementSnapshot;
+  /** Capabilities EFETIVAS agora (entitlement vivo AND rollout): `recording`, `transcription`, `auto_admit`. */
+  capabilities_now: Record<string, boolean>;
+  generation: number;
+  version: number;
+  participants?: ITeleconsultationParticipantDto[];
+  access?: ITeleconsultationAccessSummaryDto;
+}
+
+/** `POST /v1/teleconsultations/:id/launch` → `{ launch_url }` (fragment `#code=`; SPA faz o exchange). */
+export interface ILaunchResponseDto {
+  ok: true;
+  launch_url: string;
+  /** Expiração do code one-time (5 min). */
+  expires_at: string;
+  claimed_host_user_id: string;
+}
+
+export interface IRoomSessionWindowDto {
+  scheduled_start_at: string;
+  scheduled_end_at: string;
+  doctor_access_from: string;
+  patient_access_from: string;
+  unused_expires_at: string;
+  reconnect_until?: string | null;
+}
+
+export interface IRoomConsentRefDto {
+  subject: ConsentSubject;
+  terms_version: string;
+}
+
+/**
+ * `GET /api/room/v1/session` — estado SANITIZADO: sem tenant id, sem ids do
+ * provider; nome do profissional/clínica só depois da verificação.
+ */
+export interface IRoomSessionDto {
+  ok: true;
+  role: ParticipantRole;
+  participant_id: string;
+  participant_state: ParticipantState;
+  teleconsultation_status: TeleconsultationStatus;
+  mode: TeleconsultationMode;
+  waiting_policy: WaitingPolicy;
+  window: IRoomSessionWindowDto;
+  identity_level: IdentityLevel;
+  /** Paciente precisa passar por `POST /identity/verify` antes do join. */
+  identity_required: boolean;
+  recording_status: RecordingStatus;
+  transcription_status: TranscriptionStatus;
+  /** Textos vigentes que ainda precisam de aceite antes do join. */
+  required_consents: IRoomConsentRefDto[];
+  accepted_consents: IRoomConsentRefDto[];
+  /** Capabilities efetivas para esta sessão (entitlement AND rollout AND papel). */
+  capabilities: Record<string, boolean>;
+  professional_display_name?: string;
+  clinic_display_name?: string;
+  /** Expiração do access da sessão (15 min, rotativo via `/session/refresh`). */
+  session_expires_at: string;
+  server_time: string;
+}
+
+/** `POST /api/room/v1/join` — token do provider fica em MEMÓRIA do SPA; nunca em storage. */
+export interface IRoomJoinDto {
+  ok: true;
+  provider_token: string;
+  /** Id opaco do meeting (não é o `provider_meeting_id`). */
+  meeting_id_opaque: string;
+  preset: string;
+  participant_id: string;
+  custom_participant_id: string;
+  /** true quando o paciente cai na waiting room (`manual_admit` ou médico ausente). */
+  waiting: boolean;
+  /** Expiração do token do provider, quando conhecida. */
+  token_expires_at?: string;
+}
+
+/** `POST /api/room/v1/admit` — o SPA só chama `acceptWaitingRoomRequest` DEPOIS de receber isto. */
+export interface IAdmissionGrantDto {
+  ok: true;
+  participant_id: string;
+  provider_participant_id: string;
+  admitted_at: string;
+  teleconsultation_status: TeleconsultationStatus;
+}
+
+export interface ITeleconsultationArtifactDto {
+  id: string;
+  type: ArtifactType;
+  segment: number;
+  status: ArtifactStatus;
+  content_type?: string;
+  size_bytes?: number;
+  started_at?: string | null;
+  ended_at?: string | null;
+  expires_at?: string | null;
+  error_code?: string;
+  created_at: string;
+}
+
+/** `POST /v1/teleconsultations/:id/artifacts/:artifactId/signed-url` — URL ≤ 5 min; evento `artifact.accessed`. */
+export interface ISignedUrlResponseDto {
+  ok: true;
+  url: string;
+  expires_at: string;
+}
+
+export interface ITeleconsultationEventDto {
+  id: string;
+  type: TeleconsultationEventType;
+  occurred_at: string;
+  actor: ITeleconsultationEventActor;
+  source: TeleconsultationEventSource;
+  correlation_id: string;
+  causation_id?: string;
+  from_status?: string;
+  to_status?: string;
+  metadata?: TeleconsultationEventMetadata;
+}
+
+/** `GET /v1/teleconsultations/:id/events` — paginação por cursor. */
+export interface ITeleconsultationEventsPageDto {
+  ok: true;
+  events: ITeleconsultationEventDto[];
+  next_cursor?: string;
+}
+
+export interface ITelemedicineLegalTextDto {
+  subject: ConsentSubject;
+  locale: string;
+  version: string;
+  title: string;
+  content_html: string;
+  content_hash: string;
+  effective_at?: string | null;
+}
+
+/** `GET /api/room/v1/legal-texts`. */
+export interface ILegalTextsResponseDto {
+  ok: true;
+  texts: ITelemedicineLegalTextDto[];
+}
+
+/** `POST /api/room/v1/identity/verify` — sucesso; falha é `IDENTITY_VERIFICATION_FAILED` neutro. */
+export interface IIdentityVerifyResponseDto {
+  ok: true;
+  identity_level: IdentityLevel;
+}
+
+/** `POST /v1/teleconsultations/:id/access/send`. */
+export interface IAccessSendResponseDto {
+  ok: true;
+  grant_id: string;
+  channel_kind: AccessSendChannelKind;
+  recipient_masked?: string;
+  expires_at: string;
+  /** Só para `channel_kind = manual` (smoke): URL mascarada, nunca a capability inteira. */
+  url_masked?: string;
+  /** Id da task `telemedicine_join.send` criada, quando houver canal. */
+  task_id?: string;
+}
+
+// ======================================================
+// Comandos (request bodies). `tenant` sempre do contexto, nunca do body.
+// ======================================================
+
+export interface IWaitingPolicyCommand {
+  waiting_policy: WaitingPolicy;
+  expected_version?: number;
+}
+
+export interface IReassignHostCommand {
+  to_user_id: string;
+  reason: string;
+  expected_version?: number;
+}
+
+export interface IAccessSendCommand {
+  channel_kind: AccessSendChannelKind;
+  /** Revoga a capability anterior antes de emitir a nova. */
+  resend?: boolean;
+}
+
+export interface IAccessRevokeCommand {
+  /** Ausente = todos os grants ativos do paciente na teleconsulta. */
+  grant_id?: string;
+  reason: string;
+}
+
+export interface IEndCommand {
+  reason?: string;
+  expected_version?: number;
+}
+
+/** `POST /api/room/v1/exchange` — code one-time do fragment `#code=`. */
+export interface IExchangeCommand {
+  code: string;
+}
+
+/** `POST /api/room/v1/identity/verify` — DOB normalizada `YYYY-MM-DD`; comparação exata após normalização. */
+export interface IIdentityVerifyCommand {
+  display_name: string;
+  birth_date?: string;
+}
+
+/** `POST /api/room/v1/consents` — termos/privacidade (gravação usa `IRecordingConsentCommand`). */
+export interface IConsentCommand {
+  subject: ConsentSubject;
+  terms_version: string;
+  decision: Extract<ConsentDecision, "accepted" | "declined">;
+}
+
+/** `POST /api/room/v1/presence`. */
+export interface IPresenceCommand {
+  state: PresenceState;
+  provider_participant_id?: string;
+}
+
+/** `POST /api/room/v1/admit` e `/reject`. */
+export interface IAdmitCommand {
+  participant_id: string;
+}
+
+export interface IRejectCommand {
+  participant_id: string;
+  reason?: string;
+}
+
+/** `POST /api/room/v1/recording/request` (médico com `record`) — idempotente por `recording_request_id`. */
+export interface IRecordingRequestCommand {
+  recording_request_id: string;
+}
+
+/** `POST /api/room/v1/recording/accept|decline|withdraw` (paciente) — versão do texto = a da solicitação. */
+export interface IRecordingConsentCommand {
+  recording_request_id: string;
+  terms_version: string;
+}
+
+/** `POST /api/room/v1/recording/stop` (médico) — repetível. */
+export interface IRecordingStopCommand {
+  recording_request_id?: string;
+}
+
+export interface ITelemetryEvent {
+  name: string;
+  at: string;
+  attrs?: Record<string, string | number | boolean>;
+}
+
+/** `POST /api/room/v1/telemetry` — nomes allowlisted no backend; sem PII. */
+export interface ITelemetryCommand {
+  events: ITelemetryEvent[];
+}