@neetru/sdk 3.4.0 → 3.4.1

package/dist/mocks.d.cts

@@ -1,4 +1,4 @@
-import { a5 as NeetruUser, g as AiNamespace, b as AiChatOptions, c as AiChatResult, i as AiStreamHandle, l as AuthNamespace, aj as SignInOptions, m as AuthStateListener, ae as RedirectCallbackResult, v as CompleteSignInResult, Y as NeetruDb, E as DbCollectionRef, a4 as NeetruSqlClient, ap as SyncState, au as Unsubscribe, w as ConflictRecord, O as EntitlementCheck, al as SupportNamespace, y as CreateTicketInput, ao as SupportTicket, aw as UsageNamespace, ax as UsageQuota } from './types-BoFSCHF_.cjs';
+import { a5 as NeetruUser, g as AiNamespace, b as AiChatOptions, c as AiChatResult, i as AiStreamHandle, l as AuthNamespace, aj as SignInOptions, m as AuthStateListener, ae as RedirectCallbackResult, v as CompleteSignInResult, Y as NeetruDb, E as DbCollectionRef, a4 as NeetruSqlClient, aq as SyncState, av as Unsubscribe, w as ConflictRecord, O as EntitlementCheck, al as SupportNamespace, y as CreateTicketInput, ao as SupportTicket, ax as UsageNamespace, ay as UsageQuota } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/mocks.d.ts

@@ -1,4 +1,4 @@
-import { a5 as NeetruUser, g as AiNamespace, b as AiChatOptions, c as AiChatResult, i as AiStreamHandle, l as AuthNamespace, aj as SignInOptions, m as AuthStateListener, ae as RedirectCallbackResult, v as CompleteSignInResult, Y as NeetruDb, E as DbCollectionRef, a4 as NeetruSqlClient, ap as SyncState, au as Unsubscribe, w as ConflictRecord, O as EntitlementCheck, al as SupportNamespace, y as CreateTicketInput, ao as SupportTicket, aw as UsageNamespace, ax as UsageQuota } from './types-DdJyqBy-.js';
+import { a5 as NeetruUser, g as AiNamespace, b as AiChatOptions, c as AiChatResult, i as AiStreamHandle, l as AuthNamespace, aj as SignInOptions, m as AuthStateListener, ae as RedirectCallbackResult, v as CompleteSignInResult, Y as NeetruDb, E as DbCollectionRef, a4 as NeetruSqlClient, aq as SyncState, av as Unsubscribe, w as ConflictRecord, O as EntitlementCheck, al as SupportNamespace, y as CreateTicketInput, ao as SupportTicket, ax as UsageNamespace, ay as UsageQuota } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/notifications.d.cts

@@ -1,3 +1,3 @@
-export { R as ListNotificationsOptions, T as MockNotifications, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a9 as ProductNotification, aa as ProductNotificationSeverity, ah as SendNotificationInput, aL as createNotificationsNamespace } from './types-BoFSCHF_.cjs';
+export { R as ListNotificationsOptions, T as MockNotifications, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a9 as ProductNotification, aa as ProductNotificationSeverity, ah as SendNotificationInput, aM as createNotificationsNamespace } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/notifications.d.ts

@@ -1,3 +1,3 @@
-export { R as ListNotificationsOptions, T as MockNotifications, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a9 as ProductNotification, aa as ProductNotificationSeverity, ah as SendNotificationInput, aL as createNotificationsNamespace } from './types-DdJyqBy-.js';
+export { R as ListNotificationsOptions, T as MockNotifications, a6 as NotificationScopeOptions, a7 as NotificationsNamespace, a9 as ProductNotification, aa as ProductNotificationSeverity, ah as SendNotificationInput, aM as createNotificationsNamespace } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { W as NeetruClient, t as CheckoutStartResult, l as AuthNamespace, a5 as NeetruUser } from './types-BoFSCHF_.cjs';
+import { W as NeetruClient, t as CheckoutStartResult, l as AuthNamespace, a5 as NeetruUser } from './types-D-QdG502.cjs';
 import { CollectionReference, Query, DocumentReference } from './firestore-compat.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { W as NeetruClient, t as CheckoutStartResult, l as AuthNamespace, a5 as NeetruUser } from './types-DdJyqBy-.js';
+import { W as NeetruClient, t as CheckoutStartResult, l as AuthNamespace, a5 as NeetruUser } from './types-BlOLDMR0.js';
 import { CollectionReference, Query, DocumentReference } from './firestore-compat.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/dist/support.d.cts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, al as SupportNamespace } from './types-BoFSCHF_.cjs';
+import { ag as ResolvedConfig, al as SupportNamespace } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/support.d.ts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, al as SupportNamespace } from './types-DdJyqBy-.js';
+import { ag as ResolvedConfig, al as SupportNamespace } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/telemetry.d.cts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, ar as TelemetryEventInput, aq as TelemetryEventAck, at as TelemetryLogInput, as as TelemetryLogAck } from './types-BoFSCHF_.cjs';
+import { ag as ResolvedConfig, as as TelemetryEventInput, ar as TelemetryEventAck, au as TelemetryLogInput, at as TelemetryLogAck } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/telemetry.d.ts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, ar as TelemetryEventInput, aq as TelemetryEventAck, at as TelemetryLogInput, as as TelemetryLogAck } from './types-DdJyqBy-.js';
+import { ag as ResolvedConfig, as as TelemetryEventInput, ar as TelemetryEventAck, au as TelemetryLogInput, at as TelemetryLogAck } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/{types-DdJyqBy-.d.ts → types-BlOLDMR0.d.ts}

@@ -531,6 +531,12 @@ interface Mutation {
     attempts: number;
     /** Último erro de replay (string). `null` se nenhuma tentativa ainda. */
     lastError: string | null;
+    /**
+     * Epoch ms da ÚLTIMA tentativa real de envio (falha transiente).
+     * `undefined` se nunca foi tentada. Base do backoff exponencial keyed em
+     * `attempts` do SyncEngine — evita marretar o Core com uma mutação-veneno.
+     */
+    lastAttemptAt?: number;
     /** Estado de envio desta mutação. */
     status: 'queued' | 'inflight' | 'failed';
     /** Agrupa mutações de um `batch()` atômico. `null` se mutação individual. */
@@ -546,7 +552,14 @@ interface Mutation {
 /**
  * Razão pela qual uma escrita foi descartada no LWW (I3 §3.3 `conflict_log`).
  */
-type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation';
+type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation'
+/**
+ * Dead-letter: a mutação esgotou o teto de tentativas de replay (5xx/timeout
+ * persistente) e foi descartada da fila para não travar o FIFO de todas as
+ * coleções (head-of-line block). `winningData` fica vazio — o servidor nunca
+ * aceitou a escrita. A escrita LOCAL otimista pode ter sido revertida.
+ */
+ | 'failed_max_attempts';
 /**
  * Registro de uma escrita perdedora — gravado no `conflict_log` (I3 §3.3).
  * Entregue ao produto via `onWriteResult` (status: `'superseded'`).
@@ -577,6 +590,13 @@ interface SyncState {
     pendingWrites: number;
     lastSyncedAt: number | null;
     isLeaderTab: boolean;
+    /**
+     * Diagnóstico do ÚLTIMO ciclo de sync que falhou (push/pull/resync ou
+     * dead-letter de uma mutação-veneno). `null`/`undefined` = último ciclo OK.
+     * Reset a cada ciclo bem-sucedido. Antes disso a falha era engolida em
+     * silêncio — agora o produto pode reagir via `onSyncStateChanged`/`onError`.
+     */
+    lastError?: string | null;
 }
 /** Função para cancelar uma subscrição (onSnapshot, onDoc, onSyncStateChanged). */
 type Unsubscribe = () => void;
@@ -616,6 +636,15 @@ type Unsubscribe = () => void;
  * de adaptação, não aqui. Isso torna o SyncEngine 100% testável com fake.
  */
 
+/** Diagnóstico entregue ao hook `onError` do SyncEngine. */
+interface SyncErrorEvent {
+    /** Fase onde o ciclo falhou. */
+    phase: 'push' | 'pull' | 'resync' | 'cycle';
+    /** Mensagem legível. */
+    message: string;
+    /** Epoch ms. */
+    at: number;
+}
 /**
  * Documento retornado pelo servidor em push/pull/resync.
  */
@@ -664,6 +693,15 @@ interface PullChangesResult {
 interface FullResyncResult {
     docs: ServerDoc[];
     newWatermark: number | null;
+    /**
+     * Coleções cujo resultado bateu no teto de paginação do transporte (o REST
+     * Documentos devolve no MÁXIMO 200 docs/coleção — paginação por cursor é
+     * tarefa Core, gated). Para essas coleções o conjunto veio TRUNCADO: o
+     * SyncEngine (a) NÃO roda detecção-de-deleção-por-ausência (senão docs além
+     * do teto virariam tombstone por engano) e (b) persiste o sinal para
+     * `DbListResult.truncated`. Transportes sem teto (realtime) omitem o campo.
+     */
+    truncatedCollections?: string[];
 }
 /**
  * Contrato do transporte de sync — injetado no SyncEngine.
@@ -949,6 +987,15 @@ interface DbListResult<T = Record<string, unknown>> {
         type: 'added' | 'modified' | 'removed';
         doc: DbDoc<T>;
     }>;
+    /**
+     * `true` quando o último full-resync desta coleção bateu no TETO de 200 docs
+     * do transporte REST Documentos (ver `list()`): o cache local pode estar
+     * INCOMPLETO — existem mais docs no servidor além dos 200 baixados. Também
+     * força `stale: true`. Paginação por cursor > 200 exige mudança no Core
+     * (gated), então por ora o SDK apenas SINALIZA. `undefined`/`false` = sem
+     * truncamento conhecido (ou transporte sem teto, ex.: realtime).
+     */
+    truncated?: boolean;
 }
 interface DbGetResult<T = Record<string, unknown>> {
     docs: Array<DbDoc<T>>;
@@ -1053,7 +1100,18 @@ interface DbDocRef<T = Record<string, unknown>> {
 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. */
+    /**
+     * Lista documentos com query opcional.
+     *
+     * **TETO DE 200 DOCS (transporte REST Documentos).** O reconciliador offline
+     * baixa NO MÁXIMO 200 docs por coleção do Core em cada full-resync — o
+     * endpoint REST não expõe paginação por cursor server-side (é tarefa Core,
+     * gated). Se a coleção tem mais de 200 docs no servidor, o cache local fica
+     * INCOMPLETO e `DbListResult.truncated === true` (+ `stale: true`). O
+     * `q.limit`/`nextCursor` paginam apenas sobre o que já está no CACHE LOCAL,
+     * não sobre o servidor. Para coleções grandes, filtre por `where` no Core ou
+     * modele os dados para caber sob o teto até a paginação server-side existir.
+     */
     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<{
@@ -1112,6 +1170,13 @@ interface NeetruDbDocuments {
      * já avançou a versão do documento (Last-Write-Wins).
      */
     getConflicts(): Promise<ConflictRecord[]>;
+    /**
+     * Subscreve a erros de ciclo de sync (P2-C) — falha inesperada nas fases ou
+     * dead-letter de uma mutação-veneno que antes eram engolidos em silêncio. O
+     * mesmo diagnóstico também aparece em `syncState.lastError`. Retorna
+     * uma função de unsubscribe.
+     */
+    onError(cb: (err: SyncErrorEvent) => void): Unsubscribe;
 }
 interface CreateOfflineDocumentsOptions {
     /**
@@ -1649,8 +1714,9 @@ interface NeetruDbOptions {
      *
      * Se o produto precisa de bancos logicamente separados no **servidor**,
      * isso é uma decisão server-side (tenant/produto ou schema do Core), não
-     * `dbId`. Omitir `dbId` em contexto browser dispara um aviso único no
-     * console (dev-only) lembrando dessa distinção.
+     * `dbId`. PASSAR `dbId` em contexto browser dispara um aviso único no
+     * console (dev-only): usar dbIds distintos no mesmo tenant/produto NÃO isola
+     * os dados no servidor (co-mingling) — a falsa sensação de isolamento é a mina.
      */
     dbId?: string;
     /**
@@ -1790,6 +1856,13 @@ interface NeetruDb {
      * Permite ao produto inspecionar escritas perdidas.
      */
     getConflicts(): Promise<ConflictRecord[]>;
+    /**
+     * (Opcional) Subscreve a erros de ciclo de sync (P2-C) — falha inesperada nas
+     * fases ou dead-letter de uma mutação-veneno que antes eram engolidos em
+     * silêncio. O mesmo diagnóstico também aparece em `syncState.lastError`.
+     * Retorna uma função de unsubscribe. Ausente em implementações mock.
+     */
+    onError?(cb: (err: SyncErrorEvent) => void): Unsubscribe;
 }
 /**
  * Transporte REST puro — usa os endpoints `/api/sdk/v1/datastore/*` do Core.
@@ -1818,7 +1891,7 @@ declare function createRestSyncTransport(config?: ResolvedConfig): RealtimeTrans
  * @param wsFactory       Factory de WebSocket injetável (testes).
  */
 declare function getWebSocketRealtimeClient(gatewayUrl: string, ticketProvider: TicketProvider, dbId?: string, wsFactory?: WebSocketFactory): NeetruRealtimeClient;
-/** @internal Reseta o guard one-time do aviso de `dbId` ausente — uso exclusivo de testes. */
+/** @internal Reseta o guard one-time do aviso de `dbId` — uso exclusivo de testes. */
 declare function __resetDbIdWarningForTests(): void;
 /**
  * Cria o namespace `client.db` completo.
@@ -2573,4 +2646,4 @@ interface CatalogListOptions {
     includeDrafts?: boolean;
 }
 
-export { NeetruDbError as $, type AiChatChoice as A, type DbChangeType as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type DbCollectionRef$1 as E, type DbDoc as F, type DbDocRef as G, type DbGetResult as H, type DbListResult as I, type DbNamespace as J, type DbQuery$1 as K, type DbSqlLease as L, type DbWhereFilter as M, type DbWhereFilter$1 as N, type EntitlementCheck as O, type FieldSentinel as P, type IncrementSentinel as Q, type ListNotificationsOptions as R, MockCheckout as S, MockNotifications as T, MockWebhooks as U, NEETRU_SENTINEL_KEY as V, type NeetruClient as W, type NeetruClientConfig as X, type NeetruDb as Y, type NeetruDbDocuments as Z, type NeetruDbEngine as _, type AiChatMessage as a, type NeetruDbErrorCode as a0, type NeetruDbOptions as a1, type NeetruDbTransport as a2, type NeetruEnv as a3, type NeetruSqlClient as a4, type NeetruUser as a5, type NotificationScopeOptions as a6, type NotificationsNamespace as a7, type Product as a8, type ProductNotification as a9, type VerifyWebhookRequestResult as aA, type WebhookEndpoint as aB, type WebhookEvent as aC, type WebhookScopeOptions as aD, type WebhookTestResult as aE, type WebhooksNamespace as aF, type WithFieldSentinels as aG, __resetDbIdWarningForTests as aH, createAiNamespace as aI, createCheckoutNamespace as aJ, createNeetruDb as aK, createNotificationsNamespace as aL, createRestSyncTransport as aM, createWebhooksNamespace as aN, getWebSocketRealtimeClient as aO, increment as aP, isFieldSentinel as aQ, isIncrementSentinel as aR, isServerTimestampSentinel as aS, serverTimestamp as aT, verifyWebhookRequest as aU, verifyWebhookSignature as aV, type ProductNotificationSeverity as aa, type ProductPlan as ab, type ProductStatus as ac, type RealtimeTransport as ad, type RedirectCallbackResult as ae, type RegisterWebhookInput as af, type ResolvedConfig as ag, type SendNotificationInput as ah, type ServerTimestampSentinel as ai, type SignInOptions as aj, type SqlOptions as ak, type SupportNamespace as al, type SupportSeverity as am, type SupportStatus as an, type SupportTicket as ao, type SyncState as ap, type TelemetryEventAck as aq, type TelemetryEventInput as ar, type TelemetryLogAck as as, type TelemetryLogInput as at, type Unsubscribe as au, type UsageEventInput as av, type UsageNamespace as aw, type UsageQuota as ax, type VerifyTokenOptions as ay, type VerifyWebhookRequestOptions as az, type AiChatOptions as b, type AiChatResult as c, type AiChatUsage as d, type AiContentPart as e, type AiImageUrlPart as f, type AiNamespace as g, type AiResponseFormat as h, type AiStreamHandle as i, type AiStreamMeta as j, type AiTextPart as k, type AuthNamespace as l, type AuthStateListener as m, type CatalogListResponse as n, type CheckoutAuthOpts as o, type CheckoutIntentInfo as p, type CheckoutIntentStatus as q, type CheckoutNamespace as r, type CheckoutStartInput as s, type CheckoutStartResult as t, type CheckoutTenantType as u, type CompleteSignInResult as v, type ConflictRecord as w, type CreateOfflineDocumentsOptions as x, type CreateTicketInput as y, type DbBatchOp as z };
+export { NeetruDbError as $, type AiChatChoice as A, type DbChangeType as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type DbCollectionRef$1 as E, type DbDoc as F, type DbDocRef as G, type DbGetResult as H, type DbListResult as I, type DbNamespace as J, type DbQuery$1 as K, type DbSqlLease as L, type DbWhereFilter as M, type DbWhereFilter$1 as N, type EntitlementCheck as O, type FieldSentinel as P, type IncrementSentinel as Q, type ListNotificationsOptions as R, MockCheckout as S, MockNotifications as T, MockWebhooks as U, NEETRU_SENTINEL_KEY as V, type NeetruClient as W, type NeetruClientConfig as X, type NeetruDb as Y, type NeetruDbDocuments as Z, type NeetruDbEngine as _, type AiChatMessage as a, type NeetruDbErrorCode as a0, type NeetruDbOptions as a1, type NeetruDbTransport as a2, type NeetruEnv as a3, type NeetruSqlClient as a4, type NeetruUser as a5, type NotificationScopeOptions as a6, type NotificationsNamespace as a7, type Product as a8, type ProductNotification as a9, type VerifyWebhookRequestOptions as aA, type VerifyWebhookRequestResult as aB, type WebhookEndpoint as aC, type WebhookEvent as aD, type WebhookScopeOptions as aE, type WebhookTestResult as aF, type WebhooksNamespace as aG, type WithFieldSentinels as aH, __resetDbIdWarningForTests as aI, createAiNamespace as aJ, createCheckoutNamespace as aK, createNeetruDb as aL, createNotificationsNamespace as aM, createRestSyncTransport as aN, createWebhooksNamespace as aO, getWebSocketRealtimeClient as aP, increment as aQ, isFieldSentinel as aR, isIncrementSentinel as aS, isServerTimestampSentinel as aT, serverTimestamp as aU, verifyWebhookRequest as aV, verifyWebhookSignature as aW, type ProductNotificationSeverity as aa, type ProductPlan as ab, type ProductStatus as ac, type RealtimeTransport as ad, type RedirectCallbackResult as ae, type RegisterWebhookInput as af, type ResolvedConfig as ag, type SendNotificationInput as ah, type ServerTimestampSentinel as ai, type SignInOptions as aj, type SqlOptions as ak, type SupportNamespace as al, type SupportSeverity as am, type SupportStatus as an, type SupportTicket as ao, type SyncErrorEvent as ap, type SyncState as aq, type TelemetryEventAck as ar, type TelemetryEventInput as as, type TelemetryLogAck as at, type TelemetryLogInput as au, type Unsubscribe as av, type UsageEventInput as aw, type UsageNamespace as ax, type UsageQuota as ay, type VerifyTokenOptions as az, type AiChatOptions as b, type AiChatResult as c, type AiChatUsage as d, type AiContentPart as e, type AiImageUrlPart as f, type AiNamespace as g, type AiResponseFormat as h, type AiStreamHandle as i, type AiStreamMeta as j, type AiTextPart as k, type AuthNamespace as l, type AuthStateListener as m, type CatalogListResponse as n, type CheckoutAuthOpts as o, type CheckoutIntentInfo as p, type CheckoutIntentStatus as q, type CheckoutNamespace as r, type CheckoutStartInput as s, type CheckoutStartResult as t, type CheckoutTenantType as u, type CompleteSignInResult as v, type ConflictRecord as w, type CreateOfflineDocumentsOptions as x, type CreateTicketInput as y, type DbBatchOp as z };

package/dist/{types-BoFSCHF_.d.cts → types-D-QdG502.d.cts}

@@ -531,6 +531,12 @@ interface Mutation {
     attempts: number;
     /** Último erro de replay (string). `null` se nenhuma tentativa ainda. */
     lastError: string | null;
+    /**
+     * Epoch ms da ÚLTIMA tentativa real de envio (falha transiente).
+     * `undefined` se nunca foi tentada. Base do backoff exponencial keyed em
+     * `attempts` do SyncEngine — evita marretar o Core com uma mutação-veneno.
+     */
+    lastAttemptAt?: number;
     /** Estado de envio desta mutação. */
     status: 'queued' | 'inflight' | 'failed';
     /** Agrupa mutações de um `batch()` atômico. `null` se mutação individual. */
@@ -546,7 +552,14 @@ interface Mutation {
 /**
  * Razão pela qual uma escrita foi descartada no LWW (I3 §3.3 `conflict_log`).
  */
-type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation';
+type ConflictReason = 'lww_server_newer' | 'rejected_permission' | 'rejected_validation'
+/**
+ * Dead-letter: a mutação esgotou o teto de tentativas de replay (5xx/timeout
+ * persistente) e foi descartada da fila para não travar o FIFO de todas as
+ * coleções (head-of-line block). `winningData` fica vazio — o servidor nunca
+ * aceitou a escrita. A escrita LOCAL otimista pode ter sido revertida.
+ */
+ | 'failed_max_attempts';
 /**
  * Registro de uma escrita perdedora — gravado no `conflict_log` (I3 §3.3).
  * Entregue ao produto via `onWriteResult` (status: `'superseded'`).
@@ -577,6 +590,13 @@ interface SyncState {
     pendingWrites: number;
     lastSyncedAt: number | null;
     isLeaderTab: boolean;
+    /**
+     * Diagnóstico do ÚLTIMO ciclo de sync que falhou (push/pull/resync ou
+     * dead-letter de uma mutação-veneno). `null`/`undefined` = último ciclo OK.
+     * Reset a cada ciclo bem-sucedido. Antes disso a falha era engolida em
+     * silêncio — agora o produto pode reagir via `onSyncStateChanged`/`onError`.
+     */
+    lastError?: string | null;
 }
 /** Função para cancelar uma subscrição (onSnapshot, onDoc, onSyncStateChanged). */
 type Unsubscribe = () => void;
@@ -616,6 +636,15 @@ type Unsubscribe = () => void;
  * de adaptação, não aqui. Isso torna o SyncEngine 100% testável com fake.
  */
 
+/** Diagnóstico entregue ao hook `onError` do SyncEngine. */
+interface SyncErrorEvent {
+    /** Fase onde o ciclo falhou. */
+    phase: 'push' | 'pull' | 'resync' | 'cycle';
+    /** Mensagem legível. */
+    message: string;
+    /** Epoch ms. */
+    at: number;
+}
 /**
  * Documento retornado pelo servidor em push/pull/resync.
  */
@@ -664,6 +693,15 @@ interface PullChangesResult {
 interface FullResyncResult {
     docs: ServerDoc[];
     newWatermark: number | null;
+    /**
+     * Coleções cujo resultado bateu no teto de paginação do transporte (o REST
+     * Documentos devolve no MÁXIMO 200 docs/coleção — paginação por cursor é
+     * tarefa Core, gated). Para essas coleções o conjunto veio TRUNCADO: o
+     * SyncEngine (a) NÃO roda detecção-de-deleção-por-ausência (senão docs além
+     * do teto virariam tombstone por engano) e (b) persiste o sinal para
+     * `DbListResult.truncated`. Transportes sem teto (realtime) omitem o campo.
+     */
+    truncatedCollections?: string[];
 }
 /**
  * Contrato do transporte de sync — injetado no SyncEngine.
@@ -949,6 +987,15 @@ interface DbListResult<T = Record<string, unknown>> {
         type: 'added' | 'modified' | 'removed';
         doc: DbDoc<T>;
     }>;
+    /**
+     * `true` quando o último full-resync desta coleção bateu no TETO de 200 docs
+     * do transporte REST Documentos (ver `list()`): o cache local pode estar
+     * INCOMPLETO — existem mais docs no servidor além dos 200 baixados. Também
+     * força `stale: true`. Paginação por cursor > 200 exige mudança no Core
+     * (gated), então por ora o SDK apenas SINALIZA. `undefined`/`false` = sem
+     * truncamento conhecido (ou transporte sem teto, ex.: realtime).
+     */
+    truncated?: boolean;
 }
 interface DbGetResult<T = Record<string, unknown>> {
     docs: Array<DbDoc<T>>;
@@ -1053,7 +1100,18 @@ interface DbDocRef<T = Record<string, unknown>> {
 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. */
+    /**
+     * Lista documentos com query opcional.
+     *
+     * **TETO DE 200 DOCS (transporte REST Documentos).** O reconciliador offline
+     * baixa NO MÁXIMO 200 docs por coleção do Core em cada full-resync — o
+     * endpoint REST não expõe paginação por cursor server-side (é tarefa Core,
+     * gated). Se a coleção tem mais de 200 docs no servidor, o cache local fica
+     * INCOMPLETO e `DbListResult.truncated === true` (+ `stale: true`). O
+     * `q.limit`/`nextCursor` paginam apenas sobre o que já está no CACHE LOCAL,
+     * não sobre o servidor. Para coleções grandes, filtre por `where` no Core ou
+     * modele os dados para caber sob o teto até a paginação server-side existir.
+     */
     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<{
@@ -1112,6 +1170,13 @@ interface NeetruDbDocuments {
      * já avançou a versão do documento (Last-Write-Wins).
      */
     getConflicts(): Promise<ConflictRecord[]>;
+    /**
+     * Subscreve a erros de ciclo de sync (P2-C) — falha inesperada nas fases ou
+     * dead-letter de uma mutação-veneno que antes eram engolidos em silêncio. O
+     * mesmo diagnóstico também aparece em `syncState.lastError`. Retorna
+     * uma função de unsubscribe.
+     */
+    onError(cb: (err: SyncErrorEvent) => void): Unsubscribe;
 }
 interface CreateOfflineDocumentsOptions {
     /**
@@ -1649,8 +1714,9 @@ interface NeetruDbOptions {
      *
      * Se o produto precisa de bancos logicamente separados no **servidor**,
      * isso é uma decisão server-side (tenant/produto ou schema do Core), não
-     * `dbId`. Omitir `dbId` em contexto browser dispara um aviso único no
-     * console (dev-only) lembrando dessa distinção.
+     * `dbId`. PASSAR `dbId` em contexto browser dispara um aviso único no
+     * console (dev-only): usar dbIds distintos no mesmo tenant/produto NÃO isola
+     * os dados no servidor (co-mingling) — a falsa sensação de isolamento é a mina.
      */
     dbId?: string;
     /**
@@ -1790,6 +1856,13 @@ interface NeetruDb {
      * Permite ao produto inspecionar escritas perdidas.
      */
     getConflicts(): Promise<ConflictRecord[]>;
+    /**
+     * (Opcional) Subscreve a erros de ciclo de sync (P2-C) — falha inesperada nas
+     * fases ou dead-letter de uma mutação-veneno que antes eram engolidos em
+     * silêncio. O mesmo diagnóstico também aparece em `syncState.lastError`.
+     * Retorna uma função de unsubscribe. Ausente em implementações mock.
+     */
+    onError?(cb: (err: SyncErrorEvent) => void): Unsubscribe;
 }
 /**
  * Transporte REST puro — usa os endpoints `/api/sdk/v1/datastore/*` do Core.
@@ -1818,7 +1891,7 @@ declare function createRestSyncTransport(config?: ResolvedConfig): RealtimeTrans
  * @param wsFactory       Factory de WebSocket injetável (testes).
  */
 declare function getWebSocketRealtimeClient(gatewayUrl: string, ticketProvider: TicketProvider, dbId?: string, wsFactory?: WebSocketFactory): NeetruRealtimeClient;
-/** @internal Reseta o guard one-time do aviso de `dbId` ausente — uso exclusivo de testes. */
+/** @internal Reseta o guard one-time do aviso de `dbId` — uso exclusivo de testes. */
 declare function __resetDbIdWarningForTests(): void;
 /**
  * Cria o namespace `client.db` completo.
@@ -2573,4 +2646,4 @@ interface CatalogListOptions {
     includeDrafts?: boolean;
 }
 
-export { NeetruDbError as $, type AiChatChoice as A, type DbChangeType as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type DbCollectionRef$1 as E, type DbDoc as F, type DbDocRef as G, type DbGetResult as H, type DbListResult as I, type DbNamespace as J, type DbQuery$1 as K, type DbSqlLease as L, type DbWhereFilter as M, type DbWhereFilter$1 as N, type EntitlementCheck as O, type FieldSentinel as P, type IncrementSentinel as Q, type ListNotificationsOptions as R, MockCheckout as S, MockNotifications as T, MockWebhooks as U, NEETRU_SENTINEL_KEY as V, type NeetruClient as W, type NeetruClientConfig as X, type NeetruDb as Y, type NeetruDbDocuments as Z, type NeetruDbEngine as _, type AiChatMessage as a, type NeetruDbErrorCode as a0, type NeetruDbOptions as a1, type NeetruDbTransport as a2, type NeetruEnv as a3, type NeetruSqlClient as a4, type NeetruUser as a5, type NotificationScopeOptions as a6, type NotificationsNamespace as a7, type Product as a8, type ProductNotification as a9, type VerifyWebhookRequestResult as aA, type WebhookEndpoint as aB, type WebhookEvent as aC, type WebhookScopeOptions as aD, type WebhookTestResult as aE, type WebhooksNamespace as aF, type WithFieldSentinels as aG, __resetDbIdWarningForTests as aH, createAiNamespace as aI, createCheckoutNamespace as aJ, createNeetruDb as aK, createNotificationsNamespace as aL, createRestSyncTransport as aM, createWebhooksNamespace as aN, getWebSocketRealtimeClient as aO, increment as aP, isFieldSentinel as aQ, isIncrementSentinel as aR, isServerTimestampSentinel as aS, serverTimestamp as aT, verifyWebhookRequest as aU, verifyWebhookSignature as aV, type ProductNotificationSeverity as aa, type ProductPlan as ab, type ProductStatus as ac, type RealtimeTransport as ad, type RedirectCallbackResult as ae, type RegisterWebhookInput as af, type ResolvedConfig as ag, type SendNotificationInput as ah, type ServerTimestampSentinel as ai, type SignInOptions as aj, type SqlOptions as ak, type SupportNamespace as al, type SupportSeverity as am, type SupportStatus as an, type SupportTicket as ao, type SyncState as ap, type TelemetryEventAck as aq, type TelemetryEventInput as ar, type TelemetryLogAck as as, type TelemetryLogInput as at, type Unsubscribe as au, type UsageEventInput as av, type UsageNamespace as aw, type UsageQuota as ax, type VerifyTokenOptions as ay, type VerifyWebhookRequestOptions as az, type AiChatOptions as b, type AiChatResult as c, type AiChatUsage as d, type AiContentPart as e, type AiImageUrlPart as f, type AiNamespace as g, type AiResponseFormat as h, type AiStreamHandle as i, type AiStreamMeta as j, type AiTextPart as k, type AuthNamespace as l, type AuthStateListener as m, type CatalogListResponse as n, type CheckoutAuthOpts as o, type CheckoutIntentInfo as p, type CheckoutIntentStatus as q, type CheckoutNamespace as r, type CheckoutStartInput as s, type CheckoutStartResult as t, type CheckoutTenantType as u, type CompleteSignInResult as v, type ConflictRecord as w, type CreateOfflineDocumentsOptions as x, type CreateTicketInput as y, type DbBatchOp as z };
+export { NeetruDbError as $, type AiChatChoice as A, type DbChangeType as B, type CatalogListOptions as C, DEFAULT_BASE_URL as D, type DbCollectionRef$1 as E, type DbDoc as F, type DbDocRef as G, type DbGetResult as H, type DbListResult as I, type DbNamespace as J, type DbQuery$1 as K, type DbSqlLease as L, type DbWhereFilter as M, type DbWhereFilter$1 as N, type EntitlementCheck as O, type FieldSentinel as P, type IncrementSentinel as Q, type ListNotificationsOptions as R, MockCheckout as S, MockNotifications as T, MockWebhooks as U, NEETRU_SENTINEL_KEY as V, type NeetruClient as W, type NeetruClientConfig as X, type NeetruDb as Y, type NeetruDbDocuments as Z, type NeetruDbEngine as _, type AiChatMessage as a, type NeetruDbErrorCode as a0, type NeetruDbOptions as a1, type NeetruDbTransport as a2, type NeetruEnv as a3, type NeetruSqlClient as a4, type NeetruUser as a5, type NotificationScopeOptions as a6, type NotificationsNamespace as a7, type Product as a8, type ProductNotification as a9, type VerifyWebhookRequestOptions as aA, type VerifyWebhookRequestResult as aB, type WebhookEndpoint as aC, type WebhookEvent as aD, type WebhookScopeOptions as aE, type WebhookTestResult as aF, type WebhooksNamespace as aG, type WithFieldSentinels as aH, __resetDbIdWarningForTests as aI, createAiNamespace as aJ, createCheckoutNamespace as aK, createNeetruDb as aL, createNotificationsNamespace as aM, createRestSyncTransport as aN, createWebhooksNamespace as aO, getWebSocketRealtimeClient as aP, increment as aQ, isFieldSentinel as aR, isIncrementSentinel as aS, isServerTimestampSentinel as aT, serverTimestamp as aU, verifyWebhookRequest as aV, verifyWebhookSignature as aW, type ProductNotificationSeverity as aa, type ProductPlan as ab, type ProductStatus as ac, type RealtimeTransport as ad, type RedirectCallbackResult as ae, type RegisterWebhookInput as af, type ResolvedConfig as ag, type SendNotificationInput as ah, type ServerTimestampSentinel as ai, type SignInOptions as aj, type SqlOptions as ak, type SupportNamespace as al, type SupportSeverity as am, type SupportStatus as an, type SupportTicket as ao, type SyncErrorEvent as ap, type SyncState as aq, type TelemetryEventAck as ar, type TelemetryEventInput as as, type TelemetryLogAck as at, type TelemetryLogInput as au, type Unsubscribe as av, type UsageEventInput as aw, type UsageNamespace as ax, type UsageQuota as ay, type VerifyTokenOptions as az, type AiChatOptions as b, type AiChatResult as c, type AiChatUsage as d, type AiContentPart as e, type AiImageUrlPart as f, type AiNamespace as g, type AiResponseFormat as h, type AiStreamHandle as i, type AiStreamMeta as j, type AiTextPart as k, type AuthNamespace as l, type AuthStateListener as m, type CatalogListResponse as n, type CheckoutAuthOpts as o, type CheckoutIntentInfo as p, type CheckoutIntentStatus as q, type CheckoutNamespace as r, type CheckoutStartInput as s, type CheckoutStartResult as t, type CheckoutTenantType as u, type CompleteSignInResult as v, type ConflictRecord as w, type CreateOfflineDocumentsOptions as x, type CreateTicketInput as y, type DbBatchOp as z };

package/dist/usage.d.cts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, aw as UsageNamespace } from './types-BoFSCHF_.cjs';
+import { ag as ResolvedConfig, ax as UsageNamespace } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/usage.d.ts

@@ -1,4 +1,4 @@
-import { ag as ResolvedConfig, aw as UsageNamespace } from './types-DdJyqBy-.js';
+import { ag as ResolvedConfig, ax as UsageNamespace } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/webhooks.d.cts

@@ -1,3 +1,3 @@
-export { U as MockWebhooks, af as RegisterWebhookInput, az as VerifyWebhookRequestOptions, aA as VerifyWebhookRequestResult, aB as WebhookEndpoint, aC as WebhookEvent, aD as WebhookScopeOptions, aE as WebhookTestResult, aF as WebhooksNamespace, aN as createWebhooksNamespace, aU as verifyWebhookRequest, aV as verifyWebhookSignature } from './types-BoFSCHF_.cjs';
+export { U as MockWebhooks, af as RegisterWebhookInput, aA as VerifyWebhookRequestOptions, aB as VerifyWebhookRequestResult, aC as WebhookEndpoint, aD as WebhookEvent, aE as WebhookScopeOptions, aF as WebhookTestResult, aG as WebhooksNamespace, aO as createWebhooksNamespace, aV as verifyWebhookRequest, aW as verifyWebhookSignature } from './types-D-QdG502.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/webhooks.d.ts

@@ -1,3 +1,3 @@
-export { U as MockWebhooks, af as RegisterWebhookInput, az as VerifyWebhookRequestOptions, aA as VerifyWebhookRequestResult, aB as WebhookEndpoint, aC as WebhookEvent, aD as WebhookScopeOptions, aE as WebhookTestResult, aF as WebhooksNamespace, aN as createWebhooksNamespace, aU as verifyWebhookRequest, aV as verifyWebhookSignature } from './types-DdJyqBy-.js';
+export { U as MockWebhooks, af as RegisterWebhookInput, aA as VerifyWebhookRequestOptions, aB as VerifyWebhookRequestResult, aC as WebhookEndpoint, aD as WebhookEvent, aE as WebhookScopeOptions, aF as WebhookTestResult, aG as WebhooksNamespace, aO as createWebhooksNamespace, aV as verifyWebhookRequest, aW as verifyWebhookSignature } from './types-BlOLDMR0.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neetru/sdk",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "description": "Neetru SDK 3.0 — biblioteca runtime universal (browser/Node/Edge) para consumir o ecossistema Neetru. Paths canonical /api/sdk/v1/*, productId obrigatório, Idempotency-Key em mutations, WebCrypto signatures, baseUrl allowlist fail-closed.",
   "type": "module",
   "main": "./dist/index.cjs",