@neetru/sdk 1.2.0 → 2.1.0

package/dist/collection-ref-BBvTTXoG.d.cts

@@ -0,0 +1,423 @@
+/**
+ * Tipos internos da camada offline do @neetru/sdk.
+ *
+ * Estes tipos SÃO internos ao módulo `db/offline/` — não fazem parte da
+ * superfície pública do SDK. A superfície pública é o `DbCollectionRef` e
+ * o `DbSnapshot` de `src/types.ts`.
+ *
+ * Derivados de:
+ *   - I3-sdk-offline.md §3 (store schemas)
+ *   - I3-sdk-offline.md §4 (fila de escritas)
+ *   - I3-sdk-offline.md §5 (query descriptor)
+ *   - I3-sdk-offline.md §7 (conflito LWW)
+ *   - 02-sdk.md §3.2 (DbSnapshot, DbWhereFilter, DbQuery)
+ */
+/** Identificador de um documento (string opaca). */
+type DocId = string;
+/** Identificador de uma mutação (UUID v4 client-generated). */
+type MutationId = string;
+/** Operações possíveis na fila de escritas. */
+type MutationKind = 'add' | 'set' | 'update' | 'remove';
+/**
+ * Uma mutação enfileirada (escrita durável pendente).
+ * Equivalente a `QueuedMutation` do I3 §3.3 (`mutations` store).
+ */
+interface Mutation {
+    /** Número de sequência autoincrement — define a ordem total da fila. */
+    seq: number;
+    /** UUID v4 client-generated — chave de idempotência. */
+    mutationId: MutationId;
+    /** Nome da coleção. */
+    collection: string;
+    /** ID do documento alvo (client-gen para `add`, existente para os demais). */
+    docId: DocId;
+    /** Operação. */
+    op: MutationKind;
+    /** Dados da operação. `null` para `remove`. */
+    payload: Record<string, unknown> | null;
+    /**
+     * `serverVersion` que o cliente viu ao escrever.
+     * `null` para `add` (doc não existia) ou quando o cliente nunca sincronizou.
+     * Usado pelo servidor para detectar conflito (I3 §7.4).
+     */
+    baseVersion: string | null;
+    /** Epoch ms do relógio do CLIENTE — só para diagnóstico e ordenação local. */
+    enqueuedAt: number;
+    /** Número de tentativas de replay. */
+    attempts: number;
+    /** Último erro de replay (string). `null` se nenhuma tentativa ainda. */
+    lastError: string | null;
+    /** Estado de envio desta mutação. */
+    status: 'queued' | 'inflight' | 'failed';
+    /** Agrupa mutações de um `batch()` atômico. `null` se mutação individual. */
+    batchId: string | null;
+}
+/**
+ * Razão pela qual uma escrita foi descartada no LWW (I3 §3.3 `conflict_log`).
+ */
+type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation';
+/**
+ * Registro de uma escrita perdedora — gravado no `conflict_log` (I3 §3.3).
+ * Entregue ao produto via `onWriteResult` (status: `'superseded'`).
+ */
+interface ConflictRecord {
+    id?: number;
+    collection: string;
+    docId: DocId;
+    mutationId: MutationId;
+    losingData: Record<string, unknown>;
+    winningData: Record<string, unknown>;
+    reason: ConflictReason;
+    detectedAt: number;
+    delivered: boolean;
+}
+/**
+ * Estado de sincronização da camada offline (I3 §10 / 02-sdk §3.4).
+ * Exposto em `client.db.syncState`.
+ *
+ * - `idle`    — online e em repouso (sem sync ativo).
+ * - `syncing` — sync em progresso (push + pull + realtime).
+ * - `offline` — conexão perdida ou inexistente.
+ * - `error`   — erro persistente após retries (reservado para uso futuro).
+ */
+type SyncStatus = 'idle' | 'offline' | 'syncing' | 'error';
+interface SyncState {
+    status: SyncStatus;
+    pendingWrites: number;
+    lastSyncedAt: number | null;
+    isLeaderTab: boolean;
+}
+/** Função para cancelar uma subscrição (onSnapshot, onDoc, onSyncStateChanged). */
+type Unsubscribe = () => void;
+
+/**
+ * SyncEngine — orquestrador da camada offline do @neetru/sdk.
+ *
+ * Implementa as 3 fases de sincronização definidas em I3 §6:
+ *
+ *   FASE 1 — DRENAR A FILA (push)
+ *     Envia mutações pendentes ao Core via SyncTransport.
+ *     Cada mutação é marcada inflight, enviada e depois:
+ *       - CONFIRMADA    → removida da fila (markApplied)
+ *       - SUPERADA (LWW)→ ConflictRecord gravado, cache atualizado
+ *       - REJEITADA     → resolveRejected + ConflictRecord + removida
+ *       - FALHA TRANSIENTE → markRetry + PARA a drenagem (ordem preservada)
+ *
+ *   FASE 2 — RECONCILIAR O CACHE (pull)
+ *     Busca mudanças do servidor desde o watermark ou resume token.
+ *     Cada documento passa pelo ConflictResolver (LWW) e é gravado no LocalStore.
+ *     Changes são emitidos pelo ChangeBus.
+ *     Se `resyncRequired` → aciona full resync em vez de pull incremental.
+ *
+ *   FASE 3 — REABRIR LISTENERS (realtime)
+ *     Atualiza SyncState para refletir que o cache está reconciliado.
+ *     O ChangeBus já foi alimentado nas fases anteriores — os listeners
+ *     ativos na camada superior (onSnapshot/onDoc) recebem snapshots frescos.
+ *
+ * Garantias:
+ *   - SOMENTE a aba LÍDER executa o sync (TabCoordinator.isLeader()).
+ *   - Re-entrante-safe: um sync em progresso bloqueia novos disparos.
+ *   - Fail-closed: falha transiente retém a mutação; falha de pull não
+ *     corrompe o cache nem o watermark.
+ *   - Idempotente: o SyncTransport usa mutationId como chave de idempotência.
+ *
+ * O SyncTransport é INJETADO — a ligação real com o Core acontece na camada
+ * de adaptação, não aqui. Isso torna o SyncEngine 100% testável com fake.
+ */
+
+/**
+ * Documento retornado pelo servidor em push/pull/resync.
+ */
+interface ServerDoc {
+    collection: string;
+    id: string;
+    data: Record<string, unknown>;
+    serverVersion: string;
+    serverTimestamp: number;
+    /** `true` se o doc foi deletado no servidor. */
+    deleted: boolean;
+}
+/**
+ * Resultado individual de uma mutação enviada ao Core (FASE 1).
+ */
+type MutationResult = {
+    mutationId: string;
+    outcome: 'confirmed';
+    serverVersion: string;
+    serverTimestamp: number;
+} | {
+    mutationId: string;
+    outcome: 'superseded';
+    serverVersion: string;
+    serverTimestamp: number;
+    serverData: Record<string, unknown>;
+} | {
+    mutationId: string;
+    outcome: 'rejected';
+    reason: 'rejected_permission' | 'rejected_validation';
+    serverVersion: string | null;
+    serverData: Record<string, unknown> | null;
+};
+/** Retorno de pushMutations. */
+interface PushMutationsResult {
+    results: MutationResult[];
+}
+/** Retorno de pullChanges. */
+interface PullChangesResult {
+    docs: ServerDoc[];
+    newWatermark: number | null;
+    /** `true` quando o resume token / watermark ficou inválido (gap grande). */
+    resyncRequired: boolean;
+}
+/** Retorno de fullResync. */
+interface FullResyncResult {
+    docs: ServerDoc[];
+    newWatermark: number | null;
+}
+/**
+ * Contrato do transporte de sync — injetado no SyncEngine.
+ *
+ * A implementação real usa os endpoints `/api/sdk/v1/db/*` do Core.
+ * Em testes, usa-se um FakeSyncTransport.
+ *
+ * Per I3 §6:
+ *   - `pushMutations`  → FASE 1: envia mutações em ordem de seq.
+ *   - `pullChanges`    → FASE 2: busca delta desde o watermark/resumeToken.
+ *   - `fullResync`     → FASE 2 (fallback): lista completa das coleções ativas.
+ */
+interface SyncTransport {
+    /**
+     * Envia um lote de mutações ao Core.
+     * O Core aplica, verifica conflito LWW e retorna um resultado por mutação.
+     * A ordem do array deve ser preservada (seq crescente).
+     */
+    pushMutations(mutations: Mutation[]): Promise<PushMutationsResult>;
+    /**
+     * Busca documentos modificados no servidor desde `sinceWatermark`.
+     * `sinceWatermark === null` indica primeiro sync (sem base conhecida).
+     * `resumeToken` é o token de change stream (nosql-vm); pode ser null.
+     *
+     * Retorna `resyncRequired: true` se o gap é grande demais para pull incremental.
+     */
+    pullChanges(sinceWatermark: number | null, resumeToken: string | null): Promise<PullChangesResult>;
+    /**
+     * Faz um full resync das coleções informadas.
+     * Retorna TODOS os documentos atuais (paginado internamente pelo transporte).
+     * Docs ausentes na resposta foram deletados durante o gap.
+     */
+    fullResync(collections: string[]): Promise<FullResyncResult>;
+    /**
+     * (Opcional) Registra uma subscription realtime para uma coleção específica.
+     *
+     * Implementado pelo WebSocket transport (nosql-vm): chama
+     * `NeetruRealtimeClient.subscribe()` e alimenta os frames delta/resync
+     * no `ChangeBus` da camada offline.
+     *
+     * Transportes REST e Firestore não implementam este método (undefined).
+     * O chamador (`DbCollectionRefImpl.onSnapshot`) verifica antes de invocar.
+     *
+     * @param collection - Nome da coleção a subscrever.
+     * @param onChange   - Callback que recebe changes quando um delta/resync chega.
+     *                     `null` payload = resync full necessário.
+     * @returns Função de unsubscribe.
+     */
+    subscribeCollection?: (collection: string, onChange: (changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        docId: string;
+        data: Record<string, unknown> | null;
+    }>, needsResync: boolean) => void) => () => void;
+}
+
+/**
+ * DbCollectionRef — superfície de Documentos offline-first do @neetru/sdk (M2).
+ *
+ * Implementa a API pública conforme especificada em:
+ *   - 02-sdk.md §3.2 (contrato TypeScript DbCollectionRef)
+ *   - I2-mundo-documentos.md §3.2 (superfície dupla CRUD + realtime)
+ *   - I3-sdk-offline.md §10 (camada offline, lifecycle, SyncState)
+ *
+ * ### Semântica de Promise de escrita (02-sdk.md §3.2 nota negrito)
+ * `add/set/update/remove` resolvem quando a escrita está **durável localmente**
+ * (cache + fila), NÃO quando o servidor confirma. Isso é offline-first por design:
+ * sem rede, `add()` resolve imediatamente. Para saber quando sincronizou, o produto
+ * observa `onWriteResult` (future / SyncEngine). A Promise só rejeita por:
+ * - validação síncrona (nome de coleção inválido, id vazio)
+ * - `offline_quota_exceeded` (IndexedDB cheio)
+ *
+ * ### Injeção do transporte realtime
+ * O `RealtimeTransport` é injetado via `createOfflineDocumentsNamespace({ transport })`.
+ * A implementação atual usa o `SyncEngine` para push/pull (sync offline ↔ servidor).
+ * Transportes futuros (Firestore Web SDK / WebSocket gateway) são injetados aqui —
+ * sem alterar a superfície pública.
+ */
+
+interface DbWhereFilter {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in';
+    value: unknown;
+}
+interface DbQuery {
+    where?: DbWhereFilter[];
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    /** Máximo de documentos. Default 20, max 500. */
+    limit?: number;
+    /** Cursor opaco — devolvido em `DbListResult.nextCursor`. */
+    cursor?: string;
+}
+interface DbDoc<T = Record<string, unknown>> {
+    id: string;
+    data: T;
+}
+interface DbListResult<T = Record<string, unknown>> {
+    docs: DbDoc<T>[];
+    nextCursor: string | null;
+    fromCache: boolean;
+    stale: boolean;
+    hasPendingWrites: boolean;
+    changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        doc: DbDoc<T>;
+    }>;
+}
+interface DbGetResult<T = Record<string, unknown>> {
+    docs: Array<DbDoc<T>>;
+    fromCache: boolean;
+    stale: boolean;
+    hasPendingWrites: boolean;
+    changes: Array<{
+        type: 'added' | 'modified' | 'removed';
+        doc: DbDoc<T>;
+    }>;
+}
+type DbChangeType = 'added' | 'modified' | 'removed';
+interface DbBatchOp {
+    op: 'add' | 'set' | 'update' | 'remove';
+    collection: string;
+    id?: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Contrato do transporte de realtime — injetado no namespace.
+ *
+ * A implementação real usa os endpoints `/api/sdk/v1/db/*` do Core.
+ * Em testes, usa-se um fake in-memory.
+ *
+ * Este é o **seam de injeção** que conecta a camada offline ao servidor real.
+ * Transportes futuros (Firestore Web SDK direto / WebSocket gateway) são
+ * implementados aqui, sem modificar a superfície pública `DbCollectionRef`.
+ */
+type RealtimeTransport = SyncTransport;
+/**
+ * Referência a um documento específico.
+ * Parte da superfície `DbCollectionRef.doc(id)`.
+ */
+interface DbDocRef<T = Record<string, unknown>> {
+    get(): Promise<DbGetResult<T> | null>;
+    set(data: Omit<T, 'id'>): Promise<{
+        ok: true;
+    }>;
+    update(data: Partial<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    remove(): Promise<{
+        ok: true;
+    }>;
+    onSnapshot(cb: (snap: DbGetResult<T> | null) => void): Unsubscribe;
+}
+/**
+ * Referência a uma coleção — superfície dupla CRUD + realtime.
+ *
+ * Conforme 02-sdk.md §3.2 / I2 §3.2.
+ */
+interface DbCollectionRef<T = Record<string, unknown>> {
+    /** Retorna snapshot de um documento. `null` se não existir (nem no cache). */
+    get(id: string): Promise<DbGetResult<T> | null>;
+    /** Lista documentos com query opcional. */
+    list(q?: DbQuery): Promise<DbListResult<T>>;
+    /** Adiciona doc com id gerado pelo cliente (UUID v4). Durável localmente. */
+    add(data: Omit<T, 'id'>): Promise<{
+        ok: true;
+        id: string;
+    }>;
+    /** Cria ou sobrescreve um doc pelo id. Durável localmente. */
+    set(id: string, data: Omit<T, 'id'>): Promise<{
+        ok: true;
+    }>;
+    /** Atualiza campos de um doc (merge). Durável localmente. */
+    update(id: string, data: Partial<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    /** Remove um doc (tombstone local). Durável localmente. */
+    remove(id: string): Promise<{
+        ok: true;
+    }>;
+    /** Aplica múltiplas operações atomicamente na fila. */
+    batch(ops: DbBatchOp[]): Promise<{
+        ok: true;
+    }>;
+    /** Escuta um documento específico. */
+    onDoc(id: string, cb: (doc: T | null) => void): Unsubscribe;
+    /** Escuta a coleção inteira (ou subconjunto via query). */
+    onSnapshot(q: DbQuery | undefined, cb: (snap: DbListResult<T>) => void): Unsubscribe;
+    /** Retorna uma referência ao documento `id`. */
+    doc(id: string): DbDocRef<T>;
+}
+/**
+ * Namespace `db.documents` — ponto de entrada para coleções de documentos.
+ *
+ * Analogia a `NeetruDb` de 02-sdk.md §3.1 mas escoped para o Mundo Documentos.
+ */
+interface NeetruDbDocuments {
+    collection<T = Record<string, unknown>>(name: string): DbCollectionRef<T>;
+    /** Estado atual de sincronização (offline/online/syncing). */
+    readonly syncState: SyncState;
+    onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
+    /** Força flush da fila de mutações pendentes. */
+    flush(): Promise<void>;
+    /** Limpa o cache local (IndexedDB) — operação destrutiva. */
+    clearCache(): Promise<void>;
+    /**
+     * Retorna os registros do log de conflitos LWW gravados pelo SyncEngine.
+     * Um conflito ocorre quando a mutação local é descartada porque o servidor
+     * já avançou a versão do documento (Last-Write-Wins).
+     */
+    getConflicts(): Promise<ConflictRecord[]>;
+}
+interface CreateOfflineDocumentsOptions {
+    /**
+     * Nome do banco IndexedDB — deve ser único por produto × dbId × env.
+     * Convenção: `neetru-db__{productSlug}__{dbId}__{env}`.
+     */
+    dbName: string;
+    /**
+     * Transporte de sync — implementa `SyncTransport` do SyncEngine.
+     * Este é o **seam de injeção** do transporte real.
+     *
+     * Implementações possíveis:
+     *   - `RestSyncTransport`      — REST → Core (padrão em staging/prod)
+     *   - `FirestoreRealtimeTransport` — Firestore Web SDK direto (engine=firestore)
+     *   - `WebSocketTransport`     — WebSocket → gateway (engine=nosql-vm)
+     *   - `FakeRealtimeTransport`  — in-memory (testes)
+     */
+    transport: RealtimeTransport;
+    /**
+     * Estado inicial de conectividade.
+     * Default: `navigator.onLine` se disponível, senão `true`.
+     */
+    startOnline?: boolean;
+    /**
+     * `true` = sem contenção multi-aba (sempre líder).
+     * Padrão em testes; em produção usa Web Locks.
+     */
+    singleTab?: boolean;
+    /**
+     * Intervalo do sync periódico em ms. `0` desativa.
+     * Default: 5 * 60 * 1000 (5min).
+     */
+    periodicSyncIntervalMs?: number;
+}
+
+export type { ConflictRecord as C, DbBatchOp as D, NeetruDbDocuments as N, RealtimeTransport as R, SyncState as S, Unsubscribe as U, CreateOfflineDocumentsOptions as a, DbChangeType as b, DbCollectionRef as c, DbDoc as d, DbDocRef as e, DbGetResult as f, DbListResult as g, DbQuery as h, DbWhereFilter as i };