@neetru/sdk 3.3.0 → 3.4.1

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-DslphKIM.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-DslphKIM.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 {
     /**
@@ -1626,7 +1691,32 @@ type NeetruDbEngine = NeetruDbTransport;
 interface NeetruDbOptions {
     /**
      * ID opaco do banco lógico — emitido pelo Core em `POST /api/sdk/v1/db`.
-     * Necessário para o lease SQL e para scoping das coleções.
+     *
+     * **O que `dbId` REALMENTE faz** (bug_58811a43 — o texto antigo deste
+     * JSDoc afirmava, incorretamente, que ele era "necessário para scoping
+     * das coleções"):
+     * - Nomeia o cache offline LOCAL (IndexedDB) e o canal de coordenação
+     *   entre abas (Web Locks): `neetru-db__{productId}__{dbId}__{env}`.
+     * - Quando `transport === 'nosql-vm'`, é embutido como `_dbId` nos frames
+     *   de subscribe/validate enviados ao gateway realtime (filtra a
+     *   subscription no servidor — ver `NeetruRealtimeClient`).
+     *
+     * **O que `dbId` NÃO faz:**
+     * - NÃO escopa as escritas/leituras REST do mundo Documentos
+     *   (`add`/`set`/`update`/`remove`/`list`, via
+     *   `/api/sdk/v1/datastore/*`) — elas são escopadas SOMENTE por
+     *   `x-neetru-tenant` (`tenantId` ?? `productId`), em QUALQUER
+     *   transport (inclusive `nosql-vm`: writes sempre saem pelo REST por
+     *   baixo — ver `createRestSyncTransport`).
+     * - NÃO é usado pelo lease SQL. `client.db.sql(schema, { database })`
+     *   desambigua entre N bancos SQL via `SqlOptions.database`, um
+     *   parâmetro totalmente separado — `dbId` nunca chega lá.
+     *
+     * 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`. 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;
     /**
@@ -1766,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.
@@ -1794,6 +1891,8 @@ 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` — uso exclusivo de testes. */
+declare function __resetDbIdWarningForTests(): void;
 /**
  * Cria o namespace `client.db` completo.
  *
@@ -2400,6 +2499,43 @@ interface SupportTicket {
     updatedAt?: string;
     /** Slug do produto referenciado. */
     productSlug?: string;
+    /**
+     * 3.4: URL da página onde o feedback/problema foi originado (input de
+     * `createTicket`). `null` quando não informado.
+     */
+    pageUrl: string | null;
+    /**
+     * 3.4: URL do primeiro anexo (screenshot) do ticket, quando enviado via
+     * `createTicket({ screenshotBase64 })`. `null` se nenhum anexo.
+     */
+    screenshotUrl: string | null;
+    /**
+     * 3.4: ISO — setado pelo Core na transição do ticket pra `resolved`.
+     * `null` enquanto não resolvido.
+     */
+    resolvedAt: string | null;
+    /**
+     * 3.4: ISO — setado por `markResolvedSeen` (idempotente, só na 1ª vez que
+     * o cliente vê a notificação de resolução). `null` até então.
+     */
+    resolvedNotifiedAt: string | null;
+    /**
+     * 3.4: quantas vezes o modal de satisfação foi exibido
+     * (`recordSatisfactionAttempt`). Default `0`.
+     */
+    satisfactionAttempts: number;
+    /** 3.4: ISO da última tentativa de exibição do modal de satisfação. */
+    lastSatisfactionAttemptAt: string | null;
+    /**
+     * 3.4: ISO — setado por `submitSatisfaction` (avaliação OU skip). Marca o
+     * ciclo de satisfação como concluído (terminal, até uma eventual
+     * `contestTicket`).
+     */
+    satisfiedAt: string | null;
+    /** 3.4: nota CSAT 1-5, ou `null` se ainda não avaliado / pulado. */
+    rating: number | null;
+    /** 3.4: comentário opcional da avaliação de satisfação. */
+    satisfactionComment: string | null;
 }
 interface CreateTicketInput {
     subject: string;
@@ -2414,6 +2550,19 @@ interface CreateTicketInput {
      * Chaves limitadas a 64 chars; valores primitive (string/number/boolean/null).
      */
     metadata?: Record<string, string | number | boolean | null>;
+    /**
+     * 3.4: URL da página onde o problema/feedback ocorreu. Propagado como
+     * `pageUrl` no ticket.
+     */
+    pageUrl?: string;
+    /**
+     * 3.4: screenshot em data URL base64 (cap ~700KB — mesmo limite do
+     * `report-problem.ts` do Core). O Core converte em `attachments`/
+     * `screenshotAttached`.
+     */
+    screenshotBase64?: string;
+    /** 3.4: logs de console relevantes capturados no momento do report. */
+    consoleLogs?: string;
 }
 interface SupportNamespace {
     /**
@@ -2429,6 +2578,45 @@ interface SupportNamespace {
     listMyTickets(options?: {
         productSlug?: string;
     }): Promise<SupportTicket[]>;
+    /**
+     * 3.4: marca que o usuário viu a notificação de resolução do ticket
+     * (`resolvedNotifiedAt`, idempotente — só seta se ainda `null` no Core).
+     * POST `/api/sdk/v1/support/tickets/{id}/resolved-seen`. Requer Bearer +
+     * ownership + ticket em `resolved`.
+     */
+    markResolvedSeen(ticketId: string): Promise<void>;
+    /**
+     * 3.4: registra uma tentativa de exibição do modal de satisfação
+     * (`satisfactionAttempts += 1`, `lastSatisfactionAttemptAt = now`).
+     * **Chamar no SHOW do modal, não na resposta** — exibir já conta como
+     * tentativa, evita reprompt infinito. POST
+     * `/api/sdk/v1/support/tickets/{id}/satisfaction-attempt`. Requer Bearer +
+     * ownership + ticket em `resolved`.
+     */
+    recordSatisfactionAttempt(ticketId: string): Promise<void>;
+    /**
+     * 3.4: envia (ou pula) a avaliação de satisfação. `rating` é CSAT 1-5 ou
+     * `null` (junto de `skipped: true`). Terminal — seta `satisfiedAt`. POST
+     * `/api/sdk/v1/support/tickets/{id}/satisfaction`. Requer Bearer +
+     * ownership.
+     */
+    submitSatisfaction(input: {
+        ticketId: string;
+        rating: number | null;
+        comment?: string | null;
+        skipped: boolean;
+    }): Promise<void>;
+    /**
+     * 3.4: contesta um ticket resolvido — reabre (`status='open'`) e zera o
+     * ciclo de satisfação/notificação (`resolvedAt`, `resolvedNotifiedAt`,
+     * `satisfactionAttempts`, `lastSatisfactionAttemptAt`, `satisfiedAt`,
+     * `rating`, `satisfactionComment`). POST
+     * `/api/sdk/v1/support/tickets/{id}/contest`. Requer Bearer + ownership +
+     * ticket em `resolved`.
+     */
+    contestTicket(ticketId: string, opts?: {
+        comment?: string;
+    }): Promise<void>;
 }
 /**
  * Modo do SDK. `dev` ativa mocks automáticos (úteis pra testes e
@@ -2458,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, createAiNamespace as aH, createCheckoutNamespace as aI, createNeetruDb as aJ, createNotificationsNamespace as aK, createRestSyncTransport as aL, createWebhooksNamespace as aM, getWebSocketRealtimeClient as aN, increment as aO, isFieldSentinel as aP, isIncrementSentinel as aQ, isServerTimestampSentinel as aR, serverTimestamp as aS, verifyWebhookRequest as aT, verifyWebhookSignature as aU, 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-DQplLXIk.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 {
     /**
@@ -1626,7 +1691,32 @@ type NeetruDbEngine = NeetruDbTransport;
 interface NeetruDbOptions {
     /**
      * ID opaco do banco lógico — emitido pelo Core em `POST /api/sdk/v1/db`.
-     * Necessário para o lease SQL e para scoping das coleções.
+     *
+     * **O que `dbId` REALMENTE faz** (bug_58811a43 — o texto antigo deste
+     * JSDoc afirmava, incorretamente, que ele era "necessário para scoping
+     * das coleções"):
+     * - Nomeia o cache offline LOCAL (IndexedDB) e o canal de coordenação
+     *   entre abas (Web Locks): `neetru-db__{productId}__{dbId}__{env}`.
+     * - Quando `transport === 'nosql-vm'`, é embutido como `_dbId` nos frames
+     *   de subscribe/validate enviados ao gateway realtime (filtra a
+     *   subscription no servidor — ver `NeetruRealtimeClient`).
+     *
+     * **O que `dbId` NÃO faz:**
+     * - NÃO escopa as escritas/leituras REST do mundo Documentos
+     *   (`add`/`set`/`update`/`remove`/`list`, via
+     *   `/api/sdk/v1/datastore/*`) — elas são escopadas SOMENTE por
+     *   `x-neetru-tenant` (`tenantId` ?? `productId`), em QUALQUER
+     *   transport (inclusive `nosql-vm`: writes sempre saem pelo REST por
+     *   baixo — ver `createRestSyncTransport`).
+     * - NÃO é usado pelo lease SQL. `client.db.sql(schema, { database })`
+     *   desambigua entre N bancos SQL via `SqlOptions.database`, um
+     *   parâmetro totalmente separado — `dbId` nunca chega lá.
+     *
+     * 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`. 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;
     /**
@@ -1766,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.
@@ -1794,6 +1891,8 @@ 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` — uso exclusivo de testes. */
+declare function __resetDbIdWarningForTests(): void;
 /**
  * Cria o namespace `client.db` completo.
  *
@@ -2400,6 +2499,43 @@ interface SupportTicket {
     updatedAt?: string;
     /** Slug do produto referenciado. */
     productSlug?: string;
+    /**
+     * 3.4: URL da página onde o feedback/problema foi originado (input de
+     * `createTicket`). `null` quando não informado.
+     */
+    pageUrl: string | null;
+    /**
+     * 3.4: URL do primeiro anexo (screenshot) do ticket, quando enviado via
+     * `createTicket({ screenshotBase64 })`. `null` se nenhum anexo.
+     */
+    screenshotUrl: string | null;
+    /**
+     * 3.4: ISO — setado pelo Core na transição do ticket pra `resolved`.
+     * `null` enquanto não resolvido.
+     */
+    resolvedAt: string | null;
+    /**
+     * 3.4: ISO — setado por `markResolvedSeen` (idempotente, só na 1ª vez que
+     * o cliente vê a notificação de resolução). `null` até então.
+     */
+    resolvedNotifiedAt: string | null;
+    /**
+     * 3.4: quantas vezes o modal de satisfação foi exibido
+     * (`recordSatisfactionAttempt`). Default `0`.
+     */
+    satisfactionAttempts: number;
+    /** 3.4: ISO da última tentativa de exibição do modal de satisfação. */
+    lastSatisfactionAttemptAt: string | null;
+    /**
+     * 3.4: ISO — setado por `submitSatisfaction` (avaliação OU skip). Marca o
+     * ciclo de satisfação como concluído (terminal, até uma eventual
+     * `contestTicket`).
+     */
+    satisfiedAt: string | null;
+    /** 3.4: nota CSAT 1-5, ou `null` se ainda não avaliado / pulado. */
+    rating: number | null;
+    /** 3.4: comentário opcional da avaliação de satisfação. */
+    satisfactionComment: string | null;
 }
 interface CreateTicketInput {
     subject: string;
@@ -2414,6 +2550,19 @@ interface CreateTicketInput {
      * Chaves limitadas a 64 chars; valores primitive (string/number/boolean/null).
      */
     metadata?: Record<string, string | number | boolean | null>;
+    /**
+     * 3.4: URL da página onde o problema/feedback ocorreu. Propagado como
+     * `pageUrl` no ticket.
+     */
+    pageUrl?: string;
+    /**
+     * 3.4: screenshot em data URL base64 (cap ~700KB — mesmo limite do
+     * `report-problem.ts` do Core). O Core converte em `attachments`/
+     * `screenshotAttached`.
+     */
+    screenshotBase64?: string;
+    /** 3.4: logs de console relevantes capturados no momento do report. */
+    consoleLogs?: string;
 }
 interface SupportNamespace {
     /**
@@ -2429,6 +2578,45 @@ interface SupportNamespace {
     listMyTickets(options?: {
         productSlug?: string;
     }): Promise<SupportTicket[]>;
+    /**
+     * 3.4: marca que o usuário viu a notificação de resolução do ticket
+     * (`resolvedNotifiedAt`, idempotente — só seta se ainda `null` no Core).
+     * POST `/api/sdk/v1/support/tickets/{id}/resolved-seen`. Requer Bearer +
+     * ownership + ticket em `resolved`.
+     */
+    markResolvedSeen(ticketId: string): Promise<void>;
+    /**
+     * 3.4: registra uma tentativa de exibição do modal de satisfação
+     * (`satisfactionAttempts += 1`, `lastSatisfactionAttemptAt = now`).
+     * **Chamar no SHOW do modal, não na resposta** — exibir já conta como
+     * tentativa, evita reprompt infinito. POST
+     * `/api/sdk/v1/support/tickets/{id}/satisfaction-attempt`. Requer Bearer +
+     * ownership + ticket em `resolved`.
+     */
+    recordSatisfactionAttempt(ticketId: string): Promise<void>;
+    /**
+     * 3.4: envia (ou pula) a avaliação de satisfação. `rating` é CSAT 1-5 ou
+     * `null` (junto de `skipped: true`). Terminal — seta `satisfiedAt`. POST
+     * `/api/sdk/v1/support/tickets/{id}/satisfaction`. Requer Bearer +
+     * ownership.
+     */
+    submitSatisfaction(input: {
+        ticketId: string;
+        rating: number | null;
+        comment?: string | null;
+        skipped: boolean;
+    }): Promise<void>;
+    /**
+     * 3.4: contesta um ticket resolvido — reabre (`status='open'`) e zera o
+     * ciclo de satisfação/notificação (`resolvedAt`, `resolvedNotifiedAt`,
+     * `satisfactionAttempts`, `lastSatisfactionAttemptAt`, `satisfiedAt`,
+     * `rating`, `satisfactionComment`). POST
+     * `/api/sdk/v1/support/tickets/{id}/contest`. Requer Bearer + ownership +
+     * ticket em `resolved`.
+     */
+    contestTicket(ticketId: string, opts?: {
+        comment?: string;
+    }): Promise<void>;
 }
 /**
  * Modo do SDK. `dev` ativa mocks automáticos (úteis pra testes e
@@ -2458,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, createAiNamespace as aH, createCheckoutNamespace as aI, createNeetruDb as aJ, createNotificationsNamespace as aK, createRestSyncTransport as aL, createWebhooksNamespace as aM, getWebSocketRealtimeClient as aN, increment as aO, isFieldSentinel as aP, isIncrementSentinel as aQ, isServerTimestampSentinel as aR, serverTimestamp as aS, verifyWebhookRequest as aT, verifyWebhookSignature as aU, 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-DQplLXIk.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-DslphKIM.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, aM as createWebhooksNamespace, aT as verifyWebhookRequest, aU as verifyWebhookSignature } from './types-DQplLXIk.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, aM as createWebhooksNamespace, aT as verifyWebhookRequest, aU as verifyWebhookSignature } from './types-DslphKIM.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.3.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",