evo360-types 1.3.448 → 1.3.454

package/dist/types/evo-integrations/index.d.ts

@@ -70,7 +70,18 @@ export interface IIntegrationsCredential extends IFireDoc {
     status: IntegrationCredentialStatus;
     last_used_at?: Date | null;
 }
-export type SyncWindowType = "hot" | "warm" | "recent_reconcile" | "cold";
+/**
+ * `week` (feat-098) é diferente das outras em natureza: as demais derivam de
+ * `agora ± N dias`, ela é ANCORADA numa semana escolhida (domingo→sábado, no
+ * fuso do tenant). É a janela do read-through do calendário.
+ *
+ * Existir como tipo próprio importa porque o custo do sync é LINEAR na largura
+ * da janela — medido: 8 dias custam 29s de n8n, 22 dias custam 98s. Enquanto o
+ * read-through se disfarçava de `hot`, ele pedia o intervalo do FullCalendar
+ * (domingo→domingo, 8 dias: um dia a mais, e sobreposto com a semana seguinte,
+ * o que impedia cache por semana).
+ */
+export type SyncWindowType = "hot" | "warm" | "recent_reconcile" | "cold" | "week";
 export interface ICoveredWindow {
     start: Date;
     end: Date;
@@ -108,6 +119,42 @@ export interface ISyncState extends IFireDoc {
      */
     hashes_by_bucket?: Record<string, ISyncedHashes>;
     last_coveredWindow?: ICoveredWindow | null;
+    /**
+     * Desfecho da última run (feat-097). Sem isto, `last_sync_at` é indistinguível
+     * entre "sincronizou tudo" e "sincronizou e deixou N itens para trás" — o
+     * carimbo é gravado nos dois casos, e quem lê passa a jurar um frescor que não
+     * existe.
+     */
+    last_status?: SyncRunStatus;
+    /** Quantos itens ficaram para trás na última run. */
+    last_error_count?: number;
+    /**
+     * Timestamp da última run LIMPA por janela. `last_run_by_window` responde
+     * apenas "alguém tentou"; é este que responde "a janela está confiável".
+     */
+    last_success_by_window?: Partial<Record<SyncWindowType, Date>>;
+}
+export interface ISyncWeekState {
+    /** Data ISO do domingo (fuso do tenant). Igual ao id do doc. */
+    week_key: string;
+    /** Quando esta semana foi varrida pela última vez. */
+    synced_at: Date;
+    /** Desfecho da run que a varreu. */
+    status: SyncRunStatus;
+    /**
+     * Itens desta semana que estão na nossa base e NÃO vieram no payload.
+     * Zero é a única afirmação positiva de integridade — é o que autoriza o
+     * chip verde na agenda.
+     */
+    missing_from_payload: number;
+    /** Alguém conferiu item a item no sistema de origem? */
+    verified: boolean;
+    /** Existe na origem e não veio: prova de payload incompleto. */
+    still_present_upstream?: number;
+    /** Qual run carimbou — para cruzar com `sync_runs` no BigQuery. */
+    run_id?: string;
+    /** Alimenta a TTL policy do Firestore. */
+    expires_at: Date;
 }
 export type SyncRunStatus = "success" | "partial" | "error";
 export interface ISyncRunEventError {
@@ -162,6 +209,13 @@ export interface ISyncConfig {
     warm?: ISyncWindowConfig;
     recent_reconcile?: ISyncWindowConfig;
     cold?: ISyncWindowConfig;
+    /**
+     * feat-098 — janela do read-through do calendário (domingo→sábado da semana
+     * exibida). `window_days` aqui é ignorado: a janela é ancorada na semana, não
+     * derivada de `agora ± N dias`. O campo útil é `enabled`, que permite desligar
+     * o read-through de um tenant sem tocar em código.
+     */
+    week?: ISyncWindowConfig;
 }
 export interface IMedCalendarIntegration {
     adapter_id: string;

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

@@ -152,7 +152,18 @@ export interface IIntegrationsCredential extends IFireDoc {
 // Path: /tenants/{t}/apps/evo-med/sync-states/{calendar_id}
 // ======================================================
 
-export type SyncWindowType = "hot" | "warm" | "recent_reconcile" | "cold";
+/**
+ * `week` (feat-098) é diferente das outras em natureza: as demais derivam de
+ * `agora ± N dias`, ela é ANCORADA numa semana escolhida (domingo→sábado, no
+ * fuso do tenant). É a janela do read-through do calendário.
+ *
+ * Existir como tipo próprio importa porque o custo do sync é LINEAR na largura
+ * da janela — medido: 8 dias custam 29s de n8n, 22 dias custam 98s. Enquanto o
+ * read-through se disfarçava de `hot`, ele pedia o intervalo do FullCalendar
+ * (domingo→domingo, 8 dias: um dia a mais, e sobreposto com a semana seguinte,
+ * o que impedia cache por semana).
+ */
+export type SyncWindowType = "hot" | "warm" | "recent_reconcile" | "cold" | "week";
 
 export interface ICoveredWindow {
   start: Date;
@@ -193,6 +204,59 @@ export interface ISyncState extends IFireDoc {
    */
   hashes_by_bucket?: Record<string, ISyncedHashes>;
   last_coveredWindow?: ICoveredWindow | null;
+  /**
+   * Desfecho da última run (feat-097). Sem isto, `last_sync_at` é indistinguível
+   * entre "sincronizou tudo" e "sincronizou e deixou N itens para trás" — o
+   * carimbo é gravado nos dois casos, e quem lê passa a jurar um frescor que não
+   * existe.
+   */
+  last_status?: SyncRunStatus;
+  /** Quantos itens ficaram para trás na última run. */
+  last_error_count?: number;
+  /**
+   * Timestamp da última run LIMPA por janela. `last_run_by_window` responde
+   * apenas "alguém tentou"; é este que responde "a janela está confiável".
+   */
+  last_success_by_window?: Partial<Record<SyncWindowType, Date>>;
+}
+
+// ======================================================
+// Sync week state — 1 doc por SEMANA de cada calendar (feat-098).
+// Path: /tenants/{t}/apps/evo-med/sync-states/{calendar_id}/weeks/{week_key}
+//
+// `week_key` = data ISO do DOMINGO da semana no fuso do tenant (ex.: 2026-07-26).
+// Domingo e não ISO-week (que começa na segunda) porque é assim que a agenda é
+// exibida — e usar a data em vez de "2026-W31" elimina a ambiguidade.
+//
+// Por que subcoleção e não um mapa dentro do `sync-states`:
+//   - `expires_at` + TTL policy nativa do Firestore dá o descarte automático,
+//     que é o que se quer de um cache — sem Redis, sem VPC connector, e sem
+//     perder o `onSnapshot` que mantém o chip da agenda vivo sem polling.
+//   - o FE assina SÓ a semana visível (~200 B) em vez do doc do calendar, que
+//     chega a 40 KB por causa de `hashes_by_bucket`.
+// ======================================================
+
+export interface ISyncWeekState {
+  /** Data ISO do domingo (fuso do tenant). Igual ao id do doc. */
+  week_key: string;
+  /** Quando esta semana foi varrida pela última vez. */
+  synced_at: Date;
+  /** Desfecho da run que a varreu. */
+  status: SyncRunStatus;
+  /**
+   * Itens desta semana que estão na nossa base e NÃO vieram no payload.
+   * Zero é a única afirmação positiva de integridade — é o que autoriza o
+   * chip verde na agenda.
+   */
+  missing_from_payload: number;
+  /** Alguém conferiu item a item no sistema de origem? */
+  verified: boolean;
+  /** Existe na origem e não veio: prova de payload incompleto. */
+  still_present_upstream?: number;
+  /** Qual run carimbou — para cruzar com `sync_runs` no BigQuery. */
+  run_id?: string;
+  /** Alimenta a TTL policy do Firestore. */
+  expires_at: Date;
 }
 
 // ======================================================
@@ -262,6 +326,13 @@ export interface ISyncConfig {
   warm?: ISyncWindowConfig;
   recent_reconcile?: ISyncWindowConfig;
   cold?: ISyncWindowConfig;
+  /**
+   * feat-098 — janela do read-through do calendário (domingo→sábado da semana
+   * exibida). `window_days` aqui é ignorado: a janela é ancorada na semana, não
+   * derivada de `agora ± N dias`. O campo útil é `enabled`, que permite desligar
+   * o read-through de um tenant sem tocar em código.
+   */
+  week?: ISyncWindowConfig;
 }
 
 export interface IMedCalendarIntegration {

package/package.json

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