evo360-types 1.3.570 → 1.3.578

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

@@ -0,0 +1,1299 @@
+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",
+  /**
+   * feat-160 F7 — `kind` de uma ENTRADA A MAIS no `grant-index`, apontando
+   * para o MESMO grant `qr_capability`, para o link do calendário (ICS)
+   * resolver o caminho da teleconsulta (T56/P1).
+   *
+   * ⚠️ NENHUM grant tem este kind: `ITeleconsultationAccessGrant.kind` nunca
+   * vale `ics_capability`. O poder de entrar continua amarrado ao
+   * `secret_hash` do grant, que é o HMAC do `cap` e não do `ics_cap`. Está no
+   * mesmo enum porque é o `kind` do índice e o índice é endereçado pelo mesmo
+   * espaço de nomes — não para virar um grant.
+   */
+  IcsCapability: "ics_capability",
+} 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",
+  /**
+   * feat-160 F13/D31 — alguém REVELOU/copiou o link do paciente no painel. Um
+   * evento por revelação (é o ato do usuário que fica registrado, não a
+   * abertura da tela). Distinto de `access.created`, que é a emissão do grant.
+   */
+  AccessLinkRevealed: "access.link_revealed",
+  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;
+  /**
+   * Gravação — campos de OPERAÇÃO escritos por F8 e lidos pelo `GET /session`
+   * (feat-160). Nenhum id do provedor entra aqui: o id da gravação no
+   * provedor vive em `private/provider.active_provider_recording_id` (T52).
+   */
+  recording_request_id?: string;
+  /** Versão do texto legal `recording` referenciada na solicitação (D21). */
+  recording_terms_version?: string;
+  recording_requested_at?: Date | null;
+  /** `userId` do médico que solicitou. */
+  recording_requested_by?: string;
+  recording_started_at?: Date | null;
+  recording_stopped_at?: Date | null;
+  /** Código estável, sem PII, quando `recording_status === 'failed'`. */
+  recording_failure_code?: string | null;
+  /** Segmento corrente (1..n) — mais de uma sessão física = vários segmentos. */
+  recording_segment?: number;
+  transcription_status: TranscriptionStatus;
+  /**
+   * feat-160 F10 — desmonte do meeting no provedor ainda pendente; o sweep lê e
+   * limpa. Escrito FORA do comando transacional de propósito: não é estado
+   * clínico e um `version + 1` por housekeeping faria o `expected_version` que
+   * o painel acabou de ler virar 409.
+   */
+  provider_teardown_pending?: boolean;
+  /** feat-160 F10 — até quando o metadado sensível sobrevive à retenção. */
+  metadata_retention_until?: Date | null;
+  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;
+  /**
+   * feat-160 F18 — quando a passada de bilhetagem do sweep pode contar esta
+   * consulta. Carimbado por `endForAll` (`ended_at + 15 min`): o `ready` das
+   * gravações só chega pelo webhook DEPOIS do fim, então contar no `end`
+   * classificaria toda consulta gravada como "sem gravação".
+   */
+  usage_metering_due_at?: Date | null;
+  /**
+   * Quando o evento de uso foi emitido. Presente = já contada; é o que torna a
+   * bilhetagem idempotente no doc (a dedup em BigQuery, por `target.entityId`,
+   * é a segunda camada) e a trilha para reconciliar contra o BigQuery — o
+   * publish é best-effort e pode se perder.
+   */
+  usage_metered_at?: Date | null;
+  /** Concorrência otimista: todo comando de estado é transação + `version`. */
+  version: number;
+  created_at: Date;
+  updated_at: Date;
+}
+
+/**
+ * `.../teleconsultations/{teleconsultationId}/private/provider` (data-model §7;
+ * threat model P1/T52).
+ *
+ * Tudo o que identifica o encontro NO PROVEDOR mora aqui, e só aqui: o subdoc
+ * `private/**` é negado a todo mundo nas rules, inclusive super admin, enquanto
+ * `teleconsultations/{id}` e `participants/{id}` são legíveis pelo FE com
+ * `evo_telemedicine_read`. Um id de provedor na mão do browser é exatamente o
+ * que T52 proíbe — e `runTeleconsultationCommand` LANÇA se um patch do doc
+ * principal carregar `provider_meeting_id`/`active_provider_session_id`, para
+ * que o invariante não dependa de alguém lembrar em cada PR.
+ */
+export interface ITeleconsultationPrivateProvider {
+  readonly id: string;
+  tenant: string;
+  teleconsultation_id: string;
+  provider: TeleconsultationProvider;
+  /** Id do meeting no provider — nunca sai deste doc para o FE nem para o SPA. */
+  provider_meeting_id?: string;
+  active_provider_session_id?: string;
+  /** Sessões físicas já vistas (mais de uma = segmentos do mesmo encontro). */
+  provider_session_ids?: string[];
+  /** Id do participante no provider, por id LÓGICO (`doctor`/`patient`). */
+  provider_participant_ids?: Record<string, string>;
+  /**
+   * Gravação ativa no provedor. O artefato guarda o mesmo valor em
+   * `provider_artifact_id` (é por ele que o webhook casa), mas o `stop` precisa
+   * do id sem depender de qual segmento é o corrente.
+   */
+  active_provider_recording_id?: string | null;
+  created_at?: Date | null;
+  updated_at?: Date | null;
+}
+
+/**
+ * Campos que o doc PRINCIPAL da teleconsulta jamais carrega — a asserção do
+ * `runTeleconsultationCommand` e do teste de sanidade itera esta lista.
+ */
+export const TELECONSULTATION_PROVIDER_ONLY_FIELDS = [
+  "provider_meeting_id",
+  "active_provider_session_id",
+] as const;
+
+/** `.../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;
+  /**
+   * feat-160 F10 — quando o CONTEÚDO foi apagado. O doc sobrevive (status
+   * `deleted`) porque a auditoria da deleção é preservada (D13).
+   */
+  deleted_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;
+  /**
+   * feat-160 F3 — instante do write do appointment já aplicado. A marca d'água
+   * mora AQUI, e não só na teleconsulta, porque o índice sobrevive ao que ela
+   * precisa cobrir: um `denied` não cria doc nenhum e um terminal deixa de ser
+   * a teleconsulta ativa. Sem isto, um evento antigo redelivered depois de um
+   * `denied` seria reavaliado como novo.
+   */
+  last_reconciled_at?: Date | null;
+  /**
+   * Última teleconsulta deste appointment, ativa ou não. Gravada quando o
+   * índice é liberado (terminal) para o painel continuar mostrando a
+   * teleconsulta expirada/encerrada em vez de "não tem teleconsulta". NÃO é
+   * fonte de verdade de ativo — isso é `active_teleconsultation_id`.
+   */
+  last_teleconsultation_id?: 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;
+  /**
+   * Qual segredo esta entrada resolve. Ausente = a capability do `/qr`
+   * (comportamento original); `ics_capability` = o segredo derivado do link do
+   * calendário, que aponta para o MESMO grant `qr_capability` (F7).
+   */
+  kind?: AccessGrantKind;
+  /** 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;
+}
+
+/**
+ * Projeção SANITIZADA do estado de gravação no `GET /session` (feat-160 F8).
+ * Nunca traz id do provider, path do objeto no GCS nem URL assinada — só o que
+ * a UI dos dois papéis precisa.
+ */
+export interface IRoomRecordingStateDto {
+  /** Mesma origem do `recording_status` do DTO da sessão. */
+  status: RecordingStatus;
+  /** Início do segmento ativo — única origem do cronômetro; `null` fora de gravação. */
+  started_at: string | null;
+  /** Idempotência do comando e vínculo do consentimento (T19). */
+  recording_request_id?: string;
+  /** Versão do texto legal `recording` referenciada na solicitação (D21). */
+  terms_version?: string;
+  /** Código estável, sem PII, quando `status === 'failed'`. */
+  failure_code?: 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;
+  /**
+   * Quais campos o formulário de identidade deve pedir (spec §8.3): a data de
+   * nascimento só é pedida quando EXISTE no cadastro. Para o médico vem sempre
+   * `{ birth_date: false }`.
+   */
+  identity_required_fields: { birth_date: boolean };
+  /**
+   * Contador do lockout, lido do GRANT raiz — e a ÚNICA fonte dele: o erro do
+   * `POST /identity/verify` é neutro e não devolve tentativas nem prazo. Por
+   * isso a UI relê a sessão depois de cada falha.
+   */
+  identity_attempts: { remaining: number; blocked_until: string | null };
+  recording_status: RecordingStatus;
+  recording: IRoomRecordingStateDto;
+  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>;
+  /** Presença do médico; `null` quando não há participante. Atalho de `participants`. */
+  doctor_presence: ParticipantState | null;
+  /** Presença do paciente. Atalho de `participants`. */
+  patient_presence: ParticipantState | null;
+  /** Os dois papéis, com `state`/`disconnected_at`/`reconnect_count`. */
+  participants: ITeleconsultationParticipantDto[];
+  /**
+   * Pacientes em `state === 'waiting'`, e a ponte OBRIGATÓRIA do `POST /admit`:
+   * o `participant_id` de domínio é o literal `'patient'`, enquanto o
+   * `custom_participant_id` devolvido no `POST /join` é hash opaco que nunca
+   * casaria com ele.
+   */
+  waiting_participants: ITeleconsultationParticipantDto[];
+  /**
+   * Máscara "Maria A. d. S." do titular do agendamento. SÓ na sessão do
+   * MÉDICO — o backend nunca a manda ao paciente (T01), e é por isso que é o
+   * único destes campos legitimamente opcional.
+   */
+  patient_display_masked?: string;
+  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;
+  /**
+   * VALORES dos placeholders já resolvidos e filtrados pela allowlist do
+   * próprio doc (`ITelemedicineLegalText.placeholders`, que guarda os NOMES
+   * permitidos). ux-flows §3 exige "usada para {finalidade} e ficará
+   * disponível por {prazo}", e D21 proíbe hardcode disso no bundle.
+   */
+  placeholders?: Record<string, string>;
+}
+
+/** `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 /api/room/v1/exchange` e `POST /api/room/v1/session/refresh`.
+ *
+ * O corpo NÃO repete o `sid` (está no cookie `__session`, `HttpOnly`,
+ * `Path=/api`) nem o tenant; traz o papel, que é o que permite ao SPA escolher
+ * a tela sem um `GET /session` extra.
+ */
+export interface IExchangeResponseDto {
+  ok: true;
+  role: ParticipantRole;
+  session_expires_at: string;
+}
+
+/** `POST /api/room/v1/participant-token/refresh` — token novo, MESMO participante lógico. */
+export interface IParticipantTokenRefreshDto {
+  ok: true;
+  provider_token: string;
+  /** Nome do preset no provider (`hm_doctor`, `hm_patient_waiting`, ...). */
+  preset: string;
+  token_expires_at?: string;
+}
+
+/**
+ * `POST /v1/teleconsultations/:id/access/send` (feat-160 F7).
+ *
+ * É RECIBO DE TASK, não confirmação de envio: a rota publica a mesma task fina
+ * que a rotina publicaria (`telemedicine_join_reminder`) e responde antes de
+ * existir grant — o executor é quem resolve template, canal e elegibilidade e
+ * emite a capability, uma por perna do fan-out. Por isso NÃO há `grant_id` nem
+ * `expires_at` aqui: forjá-los era mentir para a recepção sobre um acesso que
+ * ainda não existia.
+ */
+export interface IAccessSendResponseDto {
+  ok: true;
+  task_id: string;
+  /** `true` quando a chave de idempotência colapsou num envio já pedido. */
+  reused: boolean;
+  channel_kind: AccessSendChannelKind;
+  /** Eco do pedido: revogar a capability anterior antes de emitir a nova. */
+  resend: boolean;
+  /** Destinatário mascarado do canal pedido; ausente em `manual`. */
+  recipient_masked?: string;
+}
+
+/**
+ * `POST /v1/teleconsultations/:id/access/link` (feat-160 F13; D31).
+ *
+ * **A `url` é CREDENCIAL** (capability de 128 bits do `/qr`), não um
+ * identificador: não tem lugar em store, log, analytics nem storage do
+ * navegador (T01/T04). Nasce nesta resposta, vai para a área de transferência e
+ * morre com o diálogo. Cada revelação é uma chamada nova, de propósito — o que
+ * fica registrado em `access.link_revealed` é o ato do usuário.
+ */
+export interface IAccessLinkResultDto {
+  ok: true;
+  url: string;
+  grant_id: string;
+  expires_at: 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/join` — intenção de mídia do preflight ("Entrar somente
+ * com áudio"). Os dois campos são opcionais porque o backend só os REGISTRA
+ * (escolha de preset e `audio_only_allowed`) e ignora o que não vier.
+ */
+export interface IJoinCommand {
+  audio?: boolean;
+  video?: boolean;
+}
+
+/**
+ * `POST /api/room/v1/leave` — saída TEMPORÁRIA (D10); nunca encerra a consulta.
+ *
+ * `reason` é string aberta e o backend só distingue UM valor: `'temporary'` é
+ * saída explícita (`left`), qualquer outro é tratado como queda de rede
+ * (`disconnected`). Ausente = `'temporary'`. Chega pelo `pagehide` com
+ * `fetch(keepalive)`, então pode vir sem `Content-Type`.
+ */
+export interface ILeaveCommand {
+  reason?: string;
+}
+
+/** `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[];
+}