evo360-types 1.3.574 → 1.3.578

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

@@ -227,6 +227,18 @@ export const AccessGrantKindEnum = {
   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];
 
@@ -284,6 +296,12 @@ export const TeleconsultationEventTypeEnum = {
   /** 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",
@@ -408,7 +426,33 @@ export interface ITeleconsultation extends IFireDoc {
   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
@@ -420,12 +464,69 @@ export interface ITeleconsultation extends IFireDoc {
   /** Ú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;
@@ -491,6 +592,11 @@ export interface ITeleconsultationArtifact extends IFireDoc {
   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;
@@ -582,6 +688,21 @@ export interface ITelemedicineAppointmentIndex extends IFireDoc {
   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;
 }
 
@@ -638,6 +759,12 @@ 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;
 }
@@ -822,6 +949,24 @@ export interface IRoomConsentRefDto {
   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.
@@ -838,13 +983,45 @@ export interface IRoomSessionDto {
   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`). */
@@ -925,6 +1102,13 @@ export interface ITelemedicineLegalTextDto {
   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`. */
@@ -939,17 +1123,64 @@ export interface IIdentityVerifyResponseDto {
   identity_level: IdentityLevel;
 }
 
-/** `POST /v1/teleconsultations/:id/access/send`. */
+/**
+ * `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;
-  grant_id: string;
+  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;
-  /** 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;
 }
 
 // ======================================================
@@ -1002,6 +1233,28 @@ export interface IConsentCommand {
   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;

package/dist/types/shared/index.d.ts

@@ -32,6 +32,7 @@ export interface IContact {
     type?: string | null;
     instagram?: string | null;
     instagram_username?: string | null;
+    bsuid?: string | null;
 }
 export interface IAddress {
     name?: string;

package/dist/types/shared/index.ts

@@ -43,6 +43,8 @@ export interface IContact {
   type?: string | null;
   instagram?: string | null;
   instagram_username?: string | null;
+  // WhatsApp BSUID (Business-Scoped User ID) — contato que a Meta entrega sem telefone
+  bsuid?: string | null;
 }
 export interface IAddress {
   name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evo360-types",
-  "version": "1.3.574",
+  "version": "1.3.578",
   "description": "HREVO360 Shared Types",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",