@neetru/sdk 3.0.2 → 3.1.1

package/dist/{types-Dc4bjrrt.d.cts → types-DePdSU3P.d.cts}

@@ -1,4 +1,3 @@
-import { c as DbCollectionRef$1, k as SyncState, U as Unsubscribe, C as ConflictRecord, R as RealtimeTransport } from './collection-ref-BDdfD87k.cjs';
 import { NodePgDatabase } from 'drizzle-orm/node-postgres';
 import { NeetruError } from './errors.cjs';
 
@@ -254,6 +253,65 @@ interface WebhooksNamespace {
  *   inválida" (return false) de "ambiente não suporta" (throw).
  */
 declare function verifyWebhookSignature(payload: string | Uint8Array, signature: string | null | undefined, secret: string): Promise<boolean>;
+/**
+ * Opções de `verifyWebhookRequest`.
+ */
+interface VerifyWebhookRequestOptions {
+    /**
+     * Janela de tolerância em milliseconds para o skew de timestamp.
+     * Default: 300_000 (5 minutos), conforme documentado na spec de webhooks.
+     * Valores menores aumentam a proteção contra replay; valores maiores acomodam
+     * clocks com drift. Não use valores acima de 600_000 (10 min).
+     */
+    toleranceMs?: number;
+}
+/**
+ * Resultado de `verifyWebhookRequest`.
+ */
+type VerifyWebhookRequestResult = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'invalid_signature' | 'timestamp_missing' | 'timestamp_expired' | 'runtime_unsupported';
+};
+/**
+ * Helper server-only que combina:
+ *   1. Verificação de assinatura HMAC-SHA256 (`X-Neetru-Signature`)
+ *   2. **Replay-protection** via skew de timestamp (`X-Neetru-Timestamp`)
+ *
+ * Rejeita o request se o timestamp estiver fora da janela `toleranceMs`
+ * (default ±5 min). Isso fecha a janela de replay onde um atacante captura
+ * um request válido e o re-envia mais tarde.
+ *
+ * **Use este helper em vez de `verifyWebhookSignature` diretamente** — ele
+ * é a forma correta de validar um webhook Neetru em produção.
+ *
+ * @param payload Corpo cru da request (string ou Uint8Array).
+ * @param headers Headers do request (pode ser um `Headers` Web API ou
+ *   `Record<string, string | undefined>`). Lidos: `X-Neetru-Signature` e
+ *   `X-Neetru-Timestamp`.
+ * @param secret Secret registrado em `webhooks.register({ secret })`.
+ * @param options Opções adicionais (ex: `toleranceMs`).
+ * @returns `{ ok: true }` ou `{ ok: false, reason }` — nunca lança, a menos
+ *   que o runtime não suporte WebCrypto (então propaga `NeetruError('runtime_unsupported')`).
+ *
+ * @example
+ * ```ts
+ * // Next.js Route Handler
+ * export async function POST(req: Request) {
+ *   const raw = await req.text();
+ *   const result = await verifyWebhookRequest(raw, req.headers, process.env.NEETRU_WEBHOOK_SECRET!);
+ *   if (!result.ok) {
+ *     console.warn('Webhook rejeitado:', result.reason);
+ *     return new Response('unauthorized', { status: 401 });
+ *   }
+ *   const event = JSON.parse(raw);
+ *   // ... handle event
+ *   return Response.json({ ok: true });
+ * }
+ * ```
+ */
+declare function verifyWebhookRequest(payload: string | Uint8Array, headers: Headers | Record<string, string | undefined>, secret: string, options?: VerifyWebhookRequestOptions): Promise<VerifyWebhookRequestResult>;
 declare function createWebhooksNamespace(config: ResolvedConfig): WebhooksNamespace;
 declare class MockWebhooks implements WebhooksNamespace {
     private endpoints;
@@ -266,6 +324,328 @@ declare class MockWebhooks implements WebhooksNamespace {
     test(id: string, _options?: WebhookScopeOptions): Promise<WebhookTestResult>;
 }
 
+/**
+ * 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;
+}
+
+/**
+ * field-value.ts — Sentinels de escrita server-side para o Mundo Documentos.
+ *
+ * Resolve duas lacunas confirmadas (bug_05aedb8b) da superfície `client.db`:
+ *
+ *  1. **Timestamp resolvido no servidor** — antes deste módulo, o produto que
+ *     quisesse `createdAt`/`updatedAt` confiáveis tinha que usar `Date.now()`
+ *     no CLIENTE, que é spoofável e sofre clock-skew. Agora:
+ *
+ *         await orders.add({ total: 99, createdAt: serverTimestamp() });
+ *
+ *     O marcador atravessa o transporte REST como um objeto JSON namespaceado
+ *     e o Core o substitui por `FieldValue.serverTimestamp()` no momento da
+ *     escrita — relógio do SERVIDOR, não do cliente.
+ *
+ *  2. **Increment atômico** — antes, `update(id, { n: x+1 })` era read-modify-write
+ *     no cliente, sujeito a lost-update sob concorrência. Agora:
+ *
+ *         await counters.update('global', { hits: increment(1) });
+ *
+ *     O Core aplica `FieldValue.increment(1)` atomicamente no documento.
+ *
+ * ## Contrato de fio (wire format)
+ *
+ * Os sentinels são objetos JSON simples — sobrevivem `JSON.stringify` no
+ * transporte REST e ao `IndexedDB structured clone` da camada offline:
+ *
+ *   serverTimestamp()  → `{ "__neetru__": "serverTimestamp" }`
+ *   increment(n)       → `{ "__neetru__": "increment", "operand": n }`
+ *
+ * A chave-âncora `__neetru__` é deliberadamente improvável de colidir com
+ * dados de produto. O Core valida e resolve esses marcadores; qualquer objeto
+ * com `__neetru__` desconhecido é rejeitado server-side (fail-closed).
+ *
+ * ## Aplicação otimista (offline-first)
+ *
+ * A camada offline aplica uma APROXIMAÇÃO local imediata (para a UI não piscar):
+ *   - `serverTimestamp()` → `Date.now()` local (substituído pelo valor real no sync).
+ *   - `increment(n)`      → soma `n` ao valor numérico atual do campo (0 se ausente).
+ * O valor canônico vem sempre do servidor no pull/confirm subsequente.
+ *
+ * @module
+ */
+/** Chave-âncora dos marcadores de sentinel no wire format. */
+declare const NEETRU_SENTINEL_KEY: "__neetru__";
+/** Marcador de timestamp resolvido pelo servidor. */
+interface ServerTimestampSentinel {
+    readonly __neetru__: 'serverTimestamp';
+}
+/** Marcador de incremento atômico aplicado pelo servidor. */
+interface IncrementSentinel {
+    readonly __neetru__: 'increment';
+    /** Delta a somar (pode ser negativo para decremento). */
+    readonly operand: number;
+}
+/**
+ * União de todos os sentinels de campo. Use `serverTimestamp()` / `increment()`
+ * para construir — nunca monte o objeto à mão.
+ */
+type FieldSentinel = ServerTimestampSentinel | IncrementSentinel;
+/**
+ * Sentinel que instrui o servidor a gravar o timestamp do MOMENTO da escrita
+ * usando o relógio do servidor (não do cliente).
+ *
+ * @example
+ * ```ts
+ * import { serverTimestamp } from '@neetru/sdk/db';
+ * await orders.add({ total: 99, createdAt: serverTimestamp() });
+ * ```
+ */
+declare function serverTimestamp(): ServerTimestampSentinel;
+/**
+ * Sentinel que instrui o servidor a incrementar atomicamente o campo numérico
+ * por `n` (negativo decrementa). Se o campo não existir/não for numérico, o
+ * servidor o trata como `0` antes de somar (semântica `FieldValue.increment`).
+ *
+ * @param n — delta inteiro ou fracionário a somar.
+ * @example
+ * ```ts
+ * import { increment } from '@neetru/sdk/db';
+ * await counters.update('global', { hits: increment(1) });
+ * await wallet.update(uid, { balance: increment(-50) });
+ * ```
+ */
+declare function increment(n: number): IncrementSentinel;
+/** `true` se `v` é qualquer sentinel de campo Neetru. */
+declare function isFieldSentinel(v: unknown): v is FieldSentinel;
+/** `true` se `v` é o sentinel `serverTimestamp()`. */
+declare function isServerTimestampSentinel(v: unknown): v is ServerTimestampSentinel;
+/** `true` se `v` é o sentinel `increment(n)` com `operand` numérico válido. */
+declare function isIncrementSentinel(v: unknown): v is IncrementSentinel;
+
 /**
  * NeetruDbError — classe de erro especializada para o módulo `db`.
  *
@@ -323,6 +703,264 @@ declare class NeetruDbError extends NeetruError {
     constructor(code: NeetruDbErrorCode, message: string, dbId?: string);
 }
 
+/**
+ * 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.
+ */
+
+/**
+ * Permite que cada campo de `T` aceite, além do seu tipo declarado, um sentinel
+ * de escrita server-side (`serverTimestamp()` / `increment()`).
+ *
+ * Sem isso, um produto que tipa `createdAt: number` veria erro de tipo ao passar
+ * `serverTimestamp()`. Esta projeção mantém o autocomplete dos campos do produto
+ * e ainda autoriza os sentinels onde fizer sentido.
+ *
+ * @example
+ * ```ts
+ * interface Order { total: number; createdAt: number; hits: number }
+ * orders.add({ total: 10, createdAt: serverTimestamp(), hits: increment(1) });
+ * ```
+ */
+type WithFieldSentinels<T> = {
+    [K in keyof T]: T[K] | FieldSentinel;
+};
+interface DbWhereFilter$1 {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=' | 'array-contains' | 'in' | 'not-in';
+    value: unknown;
+}
+interface DbQuery$1 {
+    where?: DbWhereFilter$1[];
+    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';
+/**
+ * Operação atômica para uso em `DbCollectionRef.batch()`.
+ *
+ * Discriminated union pelo campo `kind` — cada variante deixa claro
+ * quais campos são obrigatórios:
+ *
+ * - `add`    — insere com id gerado pelo cliente; `data` obrigatório.
+ * - `set`    — cria ou sobrescreve pelo `id`; `data` obrigatório.
+ * - `update` — mescla campos em doc existente pelo `id`; `data` obrigatório.
+ * - `remove` — tombstone pelo `id`; sem `data`.
+ *
+ * @example
+ * ```ts
+ * const ops: DbBatchOp[] = [
+ *   { kind: 'add',    data: { name: 'produto A', price: 10 } },
+ *   { kind: 'set',    id: 'sku-1', data: { name: 'produto B', price: 20 } },
+ *   { kind: 'update', id: 'sku-2', data: { price: 25 } },
+ *   { kind: 'remove', id: 'sku-3' },
+ * ];
+ * await col.batch(ops);
+ * ```
+ */
+type DbBatchOp<T = Record<string, unknown>> = {
+    kind: 'add';
+    data: WithFieldSentinels<Omit<T, 'id'>>;
+} | {
+    kind: 'set';
+    id: string;
+    data: WithFieldSentinels<Omit<T, 'id'>>;
+} | {
+    kind: 'update';
+    id: string;
+    data: Partial<WithFieldSentinels<Omit<T, 'id'>>>;
+} | {
+    kind: 'remove';
+    id: string;
+};
+/**
+ * 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)`.
+ *
+ * Expõe as propriedades de identidade do documento de forma análoga ao
+ * `DocumentReference` do Firestore SDK, evitando a necessidade de adaptadores
+ * externos que reattachavam `collection` + `id` manualmente.
+ *
+ * @example
+ * ```ts
+ * const ref = orders.doc('order-123');
+ * console.log(ref.id);         // "order-123"
+ * console.log(ref.collection); // "orders"
+ * console.log(ref.path);       // "orders/order-123"
+ * ```
+ */
+interface DbDocRef<T = Record<string, unknown>> {
+    /** ID do documento dentro da coleção. */
+    readonly id: string;
+    /** Caminho completo no formato "collection/docId". */
+    readonly path: string;
+    /** Nome da coleção parent. */
+    readonly collection: string;
+    get(): Promise<DbGetResult<T> | null>;
+    set(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    update(data: Partial<WithFieldSentinels<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$1<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$1): Promise<DbListResult<T>>;
+    /** Adiciona doc com id gerado pelo cliente (UUID v4). Durável localmente. */
+    add(data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
+        ok: true;
+        id: string;
+    }>;
+    /** Cria ou sobrescreve um doc pelo id. Durável localmente. */
+    set(id: string, data: WithFieldSentinels<Omit<T, 'id'>>): Promise<{
+        ok: true;
+    }>;
+    /** Atualiza campos de um doc (merge). Durável localmente. */
+    update(id: string, data: Partial<WithFieldSentinels<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<T>[]): 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$1 | 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$1<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;
+}
+
 declare const DELTA_OPS: readonly ["delta", "resync", "stale", "error", "pong", "drain"];
 type DeltaOp = (typeof DELTA_OPS)[number];
 interface DbQuery {
@@ -1515,4 +2153,4 @@ interface CatalogListOptions {
     includeDrafts?: boolean;
 }
 
-export { type UsageQuota as $, type AuthNamespace as A, type ProductNotification as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type EntitlementCheck as E, type ProductNotificationSeverity as F, type ProductPlan as G, type ProductStatus as H, type ResolvedConfig as I, type SignInOptions as J, type SqlOptions as K, type ListNotificationsOptions as L, MockCheckout as M, type NeetruClient as N, type SupportNamespace as O, type Product as P, type SupportSeverity as Q, type RegisterWebhookInput as R, type SendNotificationInput as S, type SupportStatus as T, type SupportTicket as U, type TelemetryEventAck as V, type TelemetryEventInput as W, type TelemetryLogAck as X, type TelemetryLogInput as Y, type UsageEventInput as Z, type UsageNamespace as _, type AuthStateListener as a, type VerifyTokenOptions as a0, type WebhookEndpoint as a1, type WebhookEvent as a2, type WebhookScopeOptions as a3, type WebhookTestResult as a4, type WebhooksNamespace as a5, createCheckoutNamespace as a6, createNeetruDb as a7, createNotificationsNamespace as a8, createRestSyncTransport as a9, createWebhooksNamespace as aa, getWebSocketRealtimeClient as ab, verifyWebhookSignature as ac, type CatalogListResponse as b, type CheckoutIntentInfo as c, type CheckoutIntentStatus as d, type CheckoutNamespace as e, type CheckoutStartInput as f, type CheckoutStartResult as g, type CheckoutTenantType as h, type CreateTicketInput as i, type DbNamespace as j, type DbSqlLease as k, type DbWhereFilter as l, MockNotifications as m, MockWebhooks as n, type NeetruClientConfig as o, type NeetruDb as p, type NeetruDbEngine as q, NeetruDbError as r, type NeetruDbErrorCode as s, type NeetruDbOptions as t, type NeetruDbTransport as u, type NeetruEnv as v, type NeetruSqlClient as w, type NeetruUser as x, type NotificationScopeOptions as y, type NotificationsNamespace as z };
+export { type RealtimeTransport as $, type AuthNamespace as A, type NeetruClientConfig as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type EntitlementCheck as E, type FieldSentinel as F, type NeetruDb as G, type NeetruDbDocuments as H, type IncrementSentinel as I, type NeetruDbEngine as J, NeetruDbError as K, type ListNotificationsOptions as L, MockCheckout as M, NEETRU_SENTINEL_KEY as N, type NeetruDbErrorCode as O, type NeetruDbOptions as P, type NeetruDbTransport as Q, type NeetruEnv as R, type NeetruSqlClient as S, type NeetruUser as T, type NotificationScopeOptions as U, type NotificationsNamespace as V, type Product as W, type ProductNotification as X, type ProductNotificationSeverity as Y, type ProductPlan as Z, type ProductStatus as _, type AuthStateListener as a, type RegisterWebhookInput as a0, type ResolvedConfig as a1, type SendNotificationInput as a2, type ServerTimestampSentinel as a3, type SignInOptions as a4, type SqlOptions as a5, type SupportNamespace as a6, type SupportSeverity as a7, type SupportStatus as a8, type SupportTicket as a9, isIncrementSentinel as aA, isServerTimestampSentinel as aB, serverTimestamp as aC, verifyWebhookRequest as aD, verifyWebhookSignature as aE, type SyncState as aa, type TelemetryEventAck as ab, type TelemetryEventInput as ac, type TelemetryLogAck as ad, type TelemetryLogInput as ae, type Unsubscribe as af, type UsageEventInput as ag, type UsageNamespace as ah, type UsageQuota as ai, type VerifyTokenOptions as aj, type VerifyWebhookRequestOptions as ak, type VerifyWebhookRequestResult as al, type WebhookEndpoint as am, type WebhookEvent as an, type WebhookScopeOptions as ao, type WebhookTestResult as ap, type WebhooksNamespace as aq, type WithFieldSentinels as ar, createCheckoutNamespace as as, createNeetruDb as at, createNotificationsNamespace as au, createRestSyncTransport as av, createWebhooksNamespace as aw, getWebSocketRealtimeClient as ax, increment as ay, isFieldSentinel as az, type CatalogListResponse as b, type CheckoutIntentInfo as c, type CheckoutIntentStatus as d, type CheckoutNamespace as e, type CheckoutStartInput as f, type CheckoutStartResult as g, type CheckoutTenantType as h, type ConflictRecord as i, type CreateOfflineDocumentsOptions as j, type CreateTicketInput as k, type DbBatchOp as l, type DbChangeType as m, type DbCollectionRef$1 as n, type DbDoc as o, type DbDocRef as p, type DbGetResult as q, type DbListResult as r, type DbNamespace as s, type DbQuery$1 as t, type DbSqlLease as u, type DbWhereFilter as v, type DbWhereFilter$1 as w, MockNotifications as x, MockWebhooks as y, type NeetruClient as z };