@neetru/sdk 3.0.2 → 3.1.1

package/dist/firestore-compat.d.cts

@@ -0,0 +1,319 @@
+import { G as NeetruDb, n as DbCollectionRef, F as FieldSentinel, t as DbQuery } from './types-DePdSU3P.cjs';
+import 'drizzle-orm/node-postgres';
+import './errors.cjs';
+
+/**
+ * @neetru/sdk/firestore-compat — camada de COMPATIBILIDADE (transicional).
+ *
+ * ⚠️  **STATUS: compat / transitional.** Este módulo espelha a superfície
+ * modular do Firebase Firestore (`doc`, `collection`, `query`, `where`,
+ * `getDocs`, `setDoc`, `onSnapshot`, `writeBatch`, `runTransaction`,
+ * `serverTimestamp`, `Timestamp`, `FieldValue`, …) para que produtos que
+ * migram do Firebase **não precisem reescrever as chamadas à mão**.
+ *
+ * Ele NÃO é a API nativa do SDK e NÃO compete com `client.db` (NeetruDb).
+ * É um auxílio de migração: troque os imports de `firebase/firestore` por
+ * `@neetru/sdk/firestore-compat`, valide, e depois migre incrementalmente
+ * para a superfície nativa `client.db.collection(...)` quando fizer sentido.
+ *
+ * Esta implementação foi desenhada a partir dos shims reais que os produtos
+ * `neetru-gestovendas` (`src/neetru/firestore.ts`) e `neetru-pdvagiliza`
+ * (`src/lib/neetru/firestore-compat.ts`) escreveram à mão — espelha
+ * exatamente a superfície que eles precisam para poder **deletar os shims**.
+ *
+ * ### Backing
+ * Tudo flui por `client.db` (`NeetruDb`). As funções recebem ou um `NeetruDb`
+ * (o `client.db`) ou o `NeetruClient` inteiro como primeiro argumento — ambos
+ * são aceitos por `getFirestore(...)`/`collection(...)`/`doc(...)`.
+ *
+ * ### Diferenças deliberadas vs Firebase
+ * - `serverTimestamp()` e `increment()`/`arrayUnion()`/`arrayRemove()` retornam
+ *   sentinels do SDK (`@neetru/sdk` `serverTimestamp`/`increment`) — resolvidos
+ *   SERVER-SIDE pelo Core (não pelo relógio spoofável do cliente).
+ * - `Timestamp` é uma classe leve (sem proto de Firebase) com `toDate()`,
+ *   `toMillis()`, `seconds`, `nanoseconds` e `Timestamp.now()/fromDate()/fromMillis()`.
+ * - `onSnapshot` usa o realtime nativo do `client.db` (`onSnapshot`/`doc().onSnapshot`)
+ *   quando o transporte oferece; caso contrário entrega o snapshot inicial e
+ *   reage às mudanças locais (offline-first do SDK).
+ *
+ * @module
+ */
+
+/**
+ * Aceita tanto o `NeetruDb` (`client.db`) quanto o `NeetruClient` inteiro.
+ * Produtos legados chamam `getFirestore(client)` ou `getFirestore(client.db)`;
+ * ambos resolvem para o `NeetruDb` subjacente.
+ */
+type FirestoreLike = NeetruDb | {
+    db: NeetruDb;
+};
+/** Marker brand reconhecível em runtime — `getFirestore()` devolve isto. */
+interface Firestore {
+    readonly __neetruFirestore: true;
+    readonly db: NeetruDb;
+}
+/**
+ * Equivalente compat de `getFirestore(app)`. Aceita o `NeetruClient` ou o
+ * `client.db` (`NeetruDb`) e devolve um handle `Firestore` opaco.
+ *
+ * @example
+ * ```ts
+ * import { getFirestore } from '@neetru/sdk/firestore-compat';
+ * const db = getFirestore(client); // ou getFirestore(client.db)
+ * ```
+ */
+declare function getFirestore(handle: FirestoreLike): Firestore;
+/** Operadores `where` suportados (subset do Firestore + ops do SDK). */
+type WhereFilterOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any';
+interface CollectionReference<T = Record<string, unknown>> {
+    readonly type: 'collection';
+    readonly __kind: 'collection';
+    readonly id: string;
+    readonly path: string;
+    readonly db: NeetruDb;
+    /** Handle nativo do SDK — atalho para a superfície `client.db`. */
+    readonly ref: DbCollectionRef<T>;
+}
+interface DocumentReference<T = Record<string, unknown>> {
+    readonly type: 'document';
+    readonly __kind: 'document';
+    readonly id: string;
+    readonly path: string;
+    readonly collection: string;
+    readonly db: NeetruDb;
+    /** Marcador de tipo (phantom) — preserva `T` para inferência do caller. */
+    readonly __doc?: T;
+}
+/** Aceita tanto `Firestore` quanto `NeetruDb`/`NeetruClient` direto. */
+type DbArg = Firestore | FirestoreLike;
+/**
+ * `collection(db, name)` — referência a uma coleção.
+ *
+ * Aceita `db` como `Firestore` (de `getFirestore`), `NeetruClient` ou `client.db`.
+ */
+declare function collection<T = Record<string, unknown>>(db: DbArg, name: string): CollectionReference<T>;
+/**
+ * `doc(...)` — referência a um documento. Suporta as 3 assinaturas legadas:
+ *   doc(db, 'collection', 'id')   → coleção + id
+ *   doc(collectionRef, 'id')      → id dentro de uma CollectionReference
+ *   doc(db, 'collection/id')      → path com barra (id auto-gerado se id ausente)
+ *
+ * Quando o `id` é omitido, gera um id v4 (espelha `doc(collectionRef)` do Firebase
+ * que cria uma ref com id automático antes do `setDoc`).
+ */
+declare function doc<T = Record<string, unknown>>(dbOrCollection: DbArg | CollectionReference<T>, ...path: string[]): DocumentReference<T>;
+type QueryConstraintType = 'where' | 'orderBy' | 'limit';
+interface QueryConstraint {
+    readonly __constraint: QueryConstraintType;
+}
+interface WhereConstraint extends QueryConstraint {
+    readonly __constraint: 'where';
+    readonly field: string;
+    readonly op: WhereFilterOp;
+    readonly value: unknown;
+}
+interface OrderByConstraint extends QueryConstraint {
+    readonly __constraint: 'orderBy';
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+interface LimitConstraint extends QueryConstraint {
+    readonly __constraint: 'limit';
+    readonly value: number;
+}
+interface Query<T = Record<string, unknown>> {
+    readonly type: 'query';
+    readonly __kind: 'query';
+    readonly path: string;
+    readonly collection: string;
+    readonly db: NeetruDb;
+    readonly ref: DbCollectionRef<T>;
+    readonly constraints: QueryConstraint[];
+}
+/**
+ * `query(collectionRef, ...constraints)` — combina `where`/`orderBy`/`limit`.
+ * Aceita também uma `Query` como fonte (encadeamento de constraints).
+ */
+declare function query<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T>, ...constraints: QueryConstraint[]): Query<T>;
+declare function where(field: string, op: WhereFilterOp, value: unknown): WhereConstraint;
+declare function orderBy(field: string, direction?: 'asc' | 'desc'): OrderByConstraint;
+declare function limit(value: number): LimitConstraint;
+/**
+ * Converte os constraints de uma `Query` compat para o `DbQuery` nativo do SDK.
+ *
+ * Exportado para que os hooks React (`@neetru/sdk/react`) possam reusar a mesma
+ * tradução — fonte única de verdade da conversão de constraints.
+ */
+declare function toDbQuery(constraints: QueryConstraint[]): DbQuery;
+declare class DocumentSnapshot<T = Record<string, unknown>> {
+    readonly id: string;
+    private readonly _data;
+    readonly ref?: DocumentReference<T> | undefined;
+    constructor(id: string, _data: T | null, ref?: DocumentReference<T> | undefined);
+    exists(): boolean;
+    data(): T | undefined;
+    /** Compat: `snap.get('field')` lê um campo top-level. */
+    get(field: string): unknown;
+}
+interface QueryDocumentSnapshot<T = Record<string, unknown>> {
+    readonly id: string;
+    data(): T;
+    exists(): boolean;
+    get(field: string): unknown;
+    readonly ref: DocumentReference<T>;
+}
+declare class QuerySnapshot<T = Record<string, unknown>> {
+    readonly docs: Array<QueryDocumentSnapshot<T>>;
+    readonly empty: boolean;
+    readonly size: number;
+    constructor(rows: Array<{
+        id: string;
+        data: Record<string, unknown>;
+    }>, db?: NeetruDb, collectionName?: string);
+    forEach(cb: (doc: QueryDocumentSnapshot<T>) => void): void;
+}
+declare function getDoc<T = Record<string, unknown>>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+declare function getDocs<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T>): Promise<QuerySnapshot<T>>;
+interface SetOptions {
+    merge?: boolean;
+    mergeFields?: string[];
+}
+declare function setDoc<T = Record<string, unknown>>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, options?: SetOptions): Promise<void>;
+declare function addDoc<T = Record<string, unknown>>(source: CollectionReference<T>, data: Partial<T> | Record<string, unknown>): Promise<DocumentReference<T>>;
+declare function updateDoc<T = Record<string, unknown>>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): Promise<void>;
+declare function deleteDoc(ref: DocumentReference): Promise<void>;
+declare class WriteBatch {
+    private readonly db;
+    private ops;
+    constructor(db: NeetruDb);
+    set<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, _options?: SetOptions): this;
+    update<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): this;
+    delete(ref: DocumentReference): this;
+    commit(): Promise<void>;
+}
+declare function writeBatch(db: DbArg): WriteBatch;
+/**
+ * Handle de transação compat. O SDK não expõe transações multi-doc atômicas
+ * com lock server-side, então emulamos a forma do Firebase: `tx.get` lê do
+ * `client.db`, e `tx.set/update/delete` enfileiram escritas que são aplicadas
+ * no fim do callback.
+ *
+ * ⚠️  **LIMITAÇÃO CONHECIDA — sem isolamento server-side (lost-update silencioso):**
+ *
+ * Diferente do Firestore nativo (que usa serializable snapshot isolation com
+ * contention detection), este shim executa reads e writes em rounds separados
+ * sem garantia de atomicidade:
+ *
+ *   1. `tx.get(ref)` faz um read imediato via `client.db`.
+ *   2. As escritas (`tx.set/update/delete`) são **enfileiradas** — não bloqueiam
+ *      outros writers.
+ *   3. No fim do callback, `batch.commit()` aplica as escritas. Se outro processo
+ *      tiver modificado o mesmo documento entre o read e o commit, a escrita
+ *      será um **lost-update silencioso** (sem erro, sem retry automático).
+ *
+ * **Quando isso importa:** counters, saldos, estoques — qualquer dado
+ * que precise de leitura-modificação-escrita atômica.
+ *
+ * **Alternativas seguras:**
+ *   - Use **Server Actions no Core** (`src/lib/actions/`) que rodam dentro
+ *     de transações Firestore Admin SDK reais (com locks server-side).
+ *   - Use `increment()` sentinel para contadores numéricos — server-side atomic.
+ *   - Use `arrayUnion()`/`arrayRemove()` para sets (também server-side atomic).
+ *
+ * Esta emulação é aceitável para migrações transitórias e para operações
+ * onde a probabilidade de concorrência é baixa (ex: dados de um único usuário
+ * sem write concorrente). **Não use para dados financeiros ou de inventário.**
+ */
+interface Transaction {
+    get<T>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    set<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, options?: SetOptions): Transaction;
+    update<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): Transaction;
+    delete(ref: DocumentReference): Transaction;
+}
+declare function runTransaction<R>(db: DbArg, updateFunction: (transaction: Transaction) => Promise<R>): Promise<R>;
+type Unsubscribe = () => void;
+type DocOnNext<T> = (snap: DocumentSnapshot<T>) => void;
+type QueryOnNext<T> = (snap: QuerySnapshot<T>) => void;
+type OnError = (err: Error) => void;
+declare function onSnapshot<T>(ref: DocumentReference<T>, onNext: DocOnNext<T>, onError?: OnError): Unsubscribe;
+declare function onSnapshot<T>(source: Query<T> | CollectionReference<T>, onNext: QueryOnNext<T>, onError?: OnError): Unsubscribe;
+/**
+ * Reimplementação compat de `Timestamp` do Firestore. Sem proto do Firebase.
+ * Cobre `seconds`, `nanoseconds`, `toDate()`, `toMillis()`, `isEqual()`,
+ * `valueOf()`, `toJSON()` + estáticos `now()`, `fromDate()`, `fromMillis()`.
+ */
+declare class Timestamp {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+    constructor(seconds: number, nanoseconds: number);
+    static now(): Timestamp;
+    static fromDate(date: Date): Timestamp;
+    static fromMillis(millis: number): Timestamp;
+    toDate(): Date;
+    toMillis(): number;
+    isEqual(other: Timestamp): boolean;
+    valueOf(): string;
+    toJSON(): {
+        seconds: number;
+        nanoseconds: number;
+    };
+    toString(): string;
+}
+/**
+ * Sentinel de `arrayUnion`/`arrayRemove`. O SDK ainda não tem sentinel de array
+ * server-side, então emitimos um marker namespaceado que o Core reconhece
+ * (mesma família de `__neetru__`). Se o backing não suportar, o produto deve
+ * preferir read-modify-write via Server Action. Documentado como compat.
+ */
+interface ArrayUnionSentinel {
+    readonly __neetru__: 'arrayUnion';
+    readonly elements: unknown[];
+}
+interface ArrayRemoveSentinel {
+    readonly __neetru__: 'arrayRemove';
+    readonly elements: unknown[];
+}
+/**
+ * Sentinel de campo a deletar (compat `deleteField()`).
+ */
+interface DeleteFieldSentinel {
+    readonly __neetru__: 'deleteField';
+}
+/**
+ * `serverTimestamp()` — delega ao sentinel do SDK (resolvido SERVER-SIDE).
+ * NÃO retorna mais ISO/Date do cliente (que era spoofável).
+ */
+declare function serverTimestamp(): FieldSentinel;
+/**
+ * `increment(n)` — incremento atômico server-side (delega ao sentinel do SDK).
+ */
+declare function increment(n: number): FieldSentinel;
+/** `arrayUnion(...elements)` — sentinel compat (resolvido pelo Core). */
+declare function arrayUnion(...elements: unknown[]): ArrayUnionSentinel;
+/** `arrayRemove(...elements)` — sentinel compat (resolvido pelo Core). */
+declare function arrayRemove(...elements: unknown[]): ArrayRemoveSentinel;
+/** `deleteField()` — sentinel compat para remover um campo. */
+declare function deleteField(): DeleteFieldSentinel;
+/**
+ * Namespace estático `FieldValue` — espelha `firebase/firestore`'s `FieldValue`.
+ * Os métodos delegam às funções modulares acima.
+ *
+ * @example
+ * ```ts
+ * import { FieldValue } from '@neetru/sdk/firestore-compat';
+ * await updateDoc(ref, {
+ *   tags: FieldValue.arrayUnion('novo'),
+ *   counter: FieldValue.increment(1),
+ *   updatedAt: FieldValue.serverTimestamp(),
+ * });
+ * ```
+ */
+declare const FieldValue: {
+    readonly serverTimestamp: typeof serverTimestamp;
+    readonly increment: typeof increment;
+    readonly arrayUnion: typeof arrayUnion;
+    readonly arrayRemove: typeof arrayRemove;
+    readonly delete: typeof deleteField;
+};
+
+export { type ArrayRemoveSentinel, type ArrayUnionSentinel, type CollectionReference, type DeleteFieldSentinel, type DocumentReference, DocumentSnapshot, FieldValue, type Firestore, type FirestoreLike, type Query, type QueryConstraint, type QueryConstraintType, type QueryDocumentSnapshot, QuerySnapshot, type SetOptions, Timestamp, type Transaction, type Unsubscribe, type WhereFilterOp, WriteBatch, addDoc, arrayRemove, arrayUnion, collection, deleteDoc, deleteField, doc, getDoc, getDocs, getFirestore, increment, limit, onSnapshot, orderBy, query, runTransaction, serverTimestamp, setDoc, toDbQuery, updateDoc, where, writeBatch };

package/dist/firestore-compat.d.ts

@@ -0,0 +1,319 @@
+import { G as NeetruDb, n as DbCollectionRef, F as FieldSentinel, t as DbQuery } from './types-B3XFHD4A.js';
+import 'drizzle-orm/node-postgres';
+import './errors.js';
+
+/**
+ * @neetru/sdk/firestore-compat — camada de COMPATIBILIDADE (transicional).
+ *
+ * ⚠️  **STATUS: compat / transitional.** Este módulo espelha a superfície
+ * modular do Firebase Firestore (`doc`, `collection`, `query`, `where`,
+ * `getDocs`, `setDoc`, `onSnapshot`, `writeBatch`, `runTransaction`,
+ * `serverTimestamp`, `Timestamp`, `FieldValue`, …) para que produtos que
+ * migram do Firebase **não precisem reescrever as chamadas à mão**.
+ *
+ * Ele NÃO é a API nativa do SDK e NÃO compete com `client.db` (NeetruDb).
+ * É um auxílio de migração: troque os imports de `firebase/firestore` por
+ * `@neetru/sdk/firestore-compat`, valide, e depois migre incrementalmente
+ * para a superfície nativa `client.db.collection(...)` quando fizer sentido.
+ *
+ * Esta implementação foi desenhada a partir dos shims reais que os produtos
+ * `neetru-gestovendas` (`src/neetru/firestore.ts`) e `neetru-pdvagiliza`
+ * (`src/lib/neetru/firestore-compat.ts`) escreveram à mão — espelha
+ * exatamente a superfície que eles precisam para poder **deletar os shims**.
+ *
+ * ### Backing
+ * Tudo flui por `client.db` (`NeetruDb`). As funções recebem ou um `NeetruDb`
+ * (o `client.db`) ou o `NeetruClient` inteiro como primeiro argumento — ambos
+ * são aceitos por `getFirestore(...)`/`collection(...)`/`doc(...)`.
+ *
+ * ### Diferenças deliberadas vs Firebase
+ * - `serverTimestamp()` e `increment()`/`arrayUnion()`/`arrayRemove()` retornam
+ *   sentinels do SDK (`@neetru/sdk` `serverTimestamp`/`increment`) — resolvidos
+ *   SERVER-SIDE pelo Core (não pelo relógio spoofável do cliente).
+ * - `Timestamp` é uma classe leve (sem proto de Firebase) com `toDate()`,
+ *   `toMillis()`, `seconds`, `nanoseconds` e `Timestamp.now()/fromDate()/fromMillis()`.
+ * - `onSnapshot` usa o realtime nativo do `client.db` (`onSnapshot`/`doc().onSnapshot`)
+ *   quando o transporte oferece; caso contrário entrega o snapshot inicial e
+ *   reage às mudanças locais (offline-first do SDK).
+ *
+ * @module
+ */
+
+/**
+ * Aceita tanto o `NeetruDb` (`client.db`) quanto o `NeetruClient` inteiro.
+ * Produtos legados chamam `getFirestore(client)` ou `getFirestore(client.db)`;
+ * ambos resolvem para o `NeetruDb` subjacente.
+ */
+type FirestoreLike = NeetruDb | {
+    db: NeetruDb;
+};
+/** Marker brand reconhecível em runtime — `getFirestore()` devolve isto. */
+interface Firestore {
+    readonly __neetruFirestore: true;
+    readonly db: NeetruDb;
+}
+/**
+ * Equivalente compat de `getFirestore(app)`. Aceita o `NeetruClient` ou o
+ * `client.db` (`NeetruDb`) e devolve um handle `Firestore` opaco.
+ *
+ * @example
+ * ```ts
+ * import { getFirestore } from '@neetru/sdk/firestore-compat';
+ * const db = getFirestore(client); // ou getFirestore(client.db)
+ * ```
+ */
+declare function getFirestore(handle: FirestoreLike): Firestore;
+/** Operadores `where` suportados (subset do Firestore + ops do SDK). */
+type WhereFilterOp = '==' | '!=' | '<' | '<=' | '>' | '>=' | 'in' | 'not-in' | 'array-contains' | 'array-contains-any';
+interface CollectionReference<T = Record<string, unknown>> {
+    readonly type: 'collection';
+    readonly __kind: 'collection';
+    readonly id: string;
+    readonly path: string;
+    readonly db: NeetruDb;
+    /** Handle nativo do SDK — atalho para a superfície `client.db`. */
+    readonly ref: DbCollectionRef<T>;
+}
+interface DocumentReference<T = Record<string, unknown>> {
+    readonly type: 'document';
+    readonly __kind: 'document';
+    readonly id: string;
+    readonly path: string;
+    readonly collection: string;
+    readonly db: NeetruDb;
+    /** Marcador de tipo (phantom) — preserva `T` para inferência do caller. */
+    readonly __doc?: T;
+}
+/** Aceita tanto `Firestore` quanto `NeetruDb`/`NeetruClient` direto. */
+type DbArg = Firestore | FirestoreLike;
+/**
+ * `collection(db, name)` — referência a uma coleção.
+ *
+ * Aceita `db` como `Firestore` (de `getFirestore`), `NeetruClient` ou `client.db`.
+ */
+declare function collection<T = Record<string, unknown>>(db: DbArg, name: string): CollectionReference<T>;
+/**
+ * `doc(...)` — referência a um documento. Suporta as 3 assinaturas legadas:
+ *   doc(db, 'collection', 'id')   → coleção + id
+ *   doc(collectionRef, 'id')      → id dentro de uma CollectionReference
+ *   doc(db, 'collection/id')      → path com barra (id auto-gerado se id ausente)
+ *
+ * Quando o `id` é omitido, gera um id v4 (espelha `doc(collectionRef)` do Firebase
+ * que cria uma ref com id automático antes do `setDoc`).
+ */
+declare function doc<T = Record<string, unknown>>(dbOrCollection: DbArg | CollectionReference<T>, ...path: string[]): DocumentReference<T>;
+type QueryConstraintType = 'where' | 'orderBy' | 'limit';
+interface QueryConstraint {
+    readonly __constraint: QueryConstraintType;
+}
+interface WhereConstraint extends QueryConstraint {
+    readonly __constraint: 'where';
+    readonly field: string;
+    readonly op: WhereFilterOp;
+    readonly value: unknown;
+}
+interface OrderByConstraint extends QueryConstraint {
+    readonly __constraint: 'orderBy';
+    readonly field: string;
+    readonly direction: 'asc' | 'desc';
+}
+interface LimitConstraint extends QueryConstraint {
+    readonly __constraint: 'limit';
+    readonly value: number;
+}
+interface Query<T = Record<string, unknown>> {
+    readonly type: 'query';
+    readonly __kind: 'query';
+    readonly path: string;
+    readonly collection: string;
+    readonly db: NeetruDb;
+    readonly ref: DbCollectionRef<T>;
+    readonly constraints: QueryConstraint[];
+}
+/**
+ * `query(collectionRef, ...constraints)` — combina `where`/`orderBy`/`limit`.
+ * Aceita também uma `Query` como fonte (encadeamento de constraints).
+ */
+declare function query<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T>, ...constraints: QueryConstraint[]): Query<T>;
+declare function where(field: string, op: WhereFilterOp, value: unknown): WhereConstraint;
+declare function orderBy(field: string, direction?: 'asc' | 'desc'): OrderByConstraint;
+declare function limit(value: number): LimitConstraint;
+/**
+ * Converte os constraints de uma `Query` compat para o `DbQuery` nativo do SDK.
+ *
+ * Exportado para que os hooks React (`@neetru/sdk/react`) possam reusar a mesma
+ * tradução — fonte única de verdade da conversão de constraints.
+ */
+declare function toDbQuery(constraints: QueryConstraint[]): DbQuery;
+declare class DocumentSnapshot<T = Record<string, unknown>> {
+    readonly id: string;
+    private readonly _data;
+    readonly ref?: DocumentReference<T> | undefined;
+    constructor(id: string, _data: T | null, ref?: DocumentReference<T> | undefined);
+    exists(): boolean;
+    data(): T | undefined;
+    /** Compat: `snap.get('field')` lê um campo top-level. */
+    get(field: string): unknown;
+}
+interface QueryDocumentSnapshot<T = Record<string, unknown>> {
+    readonly id: string;
+    data(): T;
+    exists(): boolean;
+    get(field: string): unknown;
+    readonly ref: DocumentReference<T>;
+}
+declare class QuerySnapshot<T = Record<string, unknown>> {
+    readonly docs: Array<QueryDocumentSnapshot<T>>;
+    readonly empty: boolean;
+    readonly size: number;
+    constructor(rows: Array<{
+        id: string;
+        data: Record<string, unknown>;
+    }>, db?: NeetruDb, collectionName?: string);
+    forEach(cb: (doc: QueryDocumentSnapshot<T>) => void): void;
+}
+declare function getDoc<T = Record<string, unknown>>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+declare function getDocs<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T>): Promise<QuerySnapshot<T>>;
+interface SetOptions {
+    merge?: boolean;
+    mergeFields?: string[];
+}
+declare function setDoc<T = Record<string, unknown>>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, options?: SetOptions): Promise<void>;
+declare function addDoc<T = Record<string, unknown>>(source: CollectionReference<T>, data: Partial<T> | Record<string, unknown>): Promise<DocumentReference<T>>;
+declare function updateDoc<T = Record<string, unknown>>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): Promise<void>;
+declare function deleteDoc(ref: DocumentReference): Promise<void>;
+declare class WriteBatch {
+    private readonly db;
+    private ops;
+    constructor(db: NeetruDb);
+    set<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, _options?: SetOptions): this;
+    update<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): this;
+    delete(ref: DocumentReference): this;
+    commit(): Promise<void>;
+}
+declare function writeBatch(db: DbArg): WriteBatch;
+/**
+ * Handle de transação compat. O SDK não expõe transações multi-doc atômicas
+ * com lock server-side, então emulamos a forma do Firebase: `tx.get` lê do
+ * `client.db`, e `tx.set/update/delete` enfileiram escritas que são aplicadas
+ * no fim do callback.
+ *
+ * ⚠️  **LIMITAÇÃO CONHECIDA — sem isolamento server-side (lost-update silencioso):**
+ *
+ * Diferente do Firestore nativo (que usa serializable snapshot isolation com
+ * contention detection), este shim executa reads e writes em rounds separados
+ * sem garantia de atomicidade:
+ *
+ *   1. `tx.get(ref)` faz um read imediato via `client.db`.
+ *   2. As escritas (`tx.set/update/delete`) são **enfileiradas** — não bloqueiam
+ *      outros writers.
+ *   3. No fim do callback, `batch.commit()` aplica as escritas. Se outro processo
+ *      tiver modificado o mesmo documento entre o read e o commit, a escrita
+ *      será um **lost-update silencioso** (sem erro, sem retry automático).
+ *
+ * **Quando isso importa:** counters, saldos, estoques — qualquer dado
+ * que precise de leitura-modificação-escrita atômica.
+ *
+ * **Alternativas seguras:**
+ *   - Use **Server Actions no Core** (`src/lib/actions/`) que rodam dentro
+ *     de transações Firestore Admin SDK reais (com locks server-side).
+ *   - Use `increment()` sentinel para contadores numéricos — server-side atomic.
+ *   - Use `arrayUnion()`/`arrayRemove()` para sets (também server-side atomic).
+ *
+ * Esta emulação é aceitável para migrações transitórias e para operações
+ * onde a probabilidade de concorrência é baixa (ex: dados de um único usuário
+ * sem write concorrente). **Não use para dados financeiros ou de inventário.**
+ */
+interface Transaction {
+    get<T>(ref: DocumentReference<T>): Promise<DocumentSnapshot<T>>;
+    set<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>, options?: SetOptions): Transaction;
+    update<T>(ref: DocumentReference<T>, data: Partial<T> | Record<string, unknown>): Transaction;
+    delete(ref: DocumentReference): Transaction;
+}
+declare function runTransaction<R>(db: DbArg, updateFunction: (transaction: Transaction) => Promise<R>): Promise<R>;
+type Unsubscribe = () => void;
+type DocOnNext<T> = (snap: DocumentSnapshot<T>) => void;
+type QueryOnNext<T> = (snap: QuerySnapshot<T>) => void;
+type OnError = (err: Error) => void;
+declare function onSnapshot<T>(ref: DocumentReference<T>, onNext: DocOnNext<T>, onError?: OnError): Unsubscribe;
+declare function onSnapshot<T>(source: Query<T> | CollectionReference<T>, onNext: QueryOnNext<T>, onError?: OnError): Unsubscribe;
+/**
+ * Reimplementação compat de `Timestamp` do Firestore. Sem proto do Firebase.
+ * Cobre `seconds`, `nanoseconds`, `toDate()`, `toMillis()`, `isEqual()`,
+ * `valueOf()`, `toJSON()` + estáticos `now()`, `fromDate()`, `fromMillis()`.
+ */
+declare class Timestamp {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+    constructor(seconds: number, nanoseconds: number);
+    static now(): Timestamp;
+    static fromDate(date: Date): Timestamp;
+    static fromMillis(millis: number): Timestamp;
+    toDate(): Date;
+    toMillis(): number;
+    isEqual(other: Timestamp): boolean;
+    valueOf(): string;
+    toJSON(): {
+        seconds: number;
+        nanoseconds: number;
+    };
+    toString(): string;
+}
+/**
+ * Sentinel de `arrayUnion`/`arrayRemove`. O SDK ainda não tem sentinel de array
+ * server-side, então emitimos um marker namespaceado que o Core reconhece
+ * (mesma família de `__neetru__`). Se o backing não suportar, o produto deve
+ * preferir read-modify-write via Server Action. Documentado como compat.
+ */
+interface ArrayUnionSentinel {
+    readonly __neetru__: 'arrayUnion';
+    readonly elements: unknown[];
+}
+interface ArrayRemoveSentinel {
+    readonly __neetru__: 'arrayRemove';
+    readonly elements: unknown[];
+}
+/**
+ * Sentinel de campo a deletar (compat `deleteField()`).
+ */
+interface DeleteFieldSentinel {
+    readonly __neetru__: 'deleteField';
+}
+/**
+ * `serverTimestamp()` — delega ao sentinel do SDK (resolvido SERVER-SIDE).
+ * NÃO retorna mais ISO/Date do cliente (que era spoofável).
+ */
+declare function serverTimestamp(): FieldSentinel;
+/**
+ * `increment(n)` — incremento atômico server-side (delega ao sentinel do SDK).
+ */
+declare function increment(n: number): FieldSentinel;
+/** `arrayUnion(...elements)` — sentinel compat (resolvido pelo Core). */
+declare function arrayUnion(...elements: unknown[]): ArrayUnionSentinel;
+/** `arrayRemove(...elements)` — sentinel compat (resolvido pelo Core). */
+declare function arrayRemove(...elements: unknown[]): ArrayRemoveSentinel;
+/** `deleteField()` — sentinel compat para remover um campo. */
+declare function deleteField(): DeleteFieldSentinel;
+/**
+ * Namespace estático `FieldValue` — espelha `firebase/firestore`'s `FieldValue`.
+ * Os métodos delegam às funções modulares acima.
+ *
+ * @example
+ * ```ts
+ * import { FieldValue } from '@neetru/sdk/firestore-compat';
+ * await updateDoc(ref, {
+ *   tags: FieldValue.arrayUnion('novo'),
+ *   counter: FieldValue.increment(1),
+ *   updatedAt: FieldValue.serverTimestamp(),
+ * });
+ * ```
+ */
+declare const FieldValue: {
+    readonly serverTimestamp: typeof serverTimestamp;
+    readonly increment: typeof increment;
+    readonly arrayUnion: typeof arrayUnion;
+    readonly arrayRemove: typeof arrayRemove;
+    readonly delete: typeof deleteField;
+};
+
+export { type ArrayRemoveSentinel, type ArrayUnionSentinel, type CollectionReference, type DeleteFieldSentinel, type DocumentReference, DocumentSnapshot, FieldValue, type Firestore, type FirestoreLike, type Query, type QueryConstraint, type QueryConstraintType, type QueryDocumentSnapshot, QuerySnapshot, type SetOptions, Timestamp, type Transaction, type Unsubscribe, type WhereFilterOp, WriteBatch, addDoc, arrayRemove, arrayUnion, collection, deleteDoc, deleteField, doc, getDoc, getDocs, getFirestore, increment, limit, onSnapshot, orderBy, query, runTransaction, serverTimestamp, setDoc, toDbQuery, updateDoc, where, writeBatch };