@neetru/sdk 3.0.1 → 3.1.0

package/dist/catalog.d.cts

@@ -1,5 +1,4 @@
-import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-Lfd3LiAF.cjs';
-import './collection-ref-DqAAhuhX.cjs';
+import { a1 as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, W as Product } from './types-nwErcRX8.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 

package/dist/catalog.d.ts

@@ -1,5 +1,4 @@
-import { I as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, P as Product } from './types-DALIhcbq.js';
-import './collection-ref-DqAAhuhX.js';
+import { a1 as ResolvedConfig, C as CatalogListOptions, b as CatalogListResponse, W as Product } from './types-BRv8wBxX.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 

package/dist/checkout.d.cts

@@ -1,4 +1,3 @@
-export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-Lfd3LiAF.cjs';
-import './collection-ref-DqAAhuhX.cjs';
+export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, aq as createCheckoutNamespace } from './types-nwErcRX8.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';

package/dist/checkout.d.ts

@@ -1,4 +1,3 @@
-export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, a6 as createCheckoutNamespace } from './types-DALIhcbq.js';
-import './collection-ref-DqAAhuhX.js';
+export { c as CheckoutIntentInfo, d as CheckoutIntentStatus, e as CheckoutNamespace, f as CheckoutStartInput, g as CheckoutStartResult, h as CheckoutTenantType, M as MockCheckout, aq as createCheckoutNamespace } from './types-BRv8wBxX.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';

package/dist/db-react.cjs

@@ -23,6 +23,15 @@ function _interopNamespace(e) {
 var React__namespace = /*#__PURE__*/_interopNamespace(React);
 
 // src/db/react.ts
+function isNeetruClient(input) {
+  const maybe = input;
+  if (typeof maybe.syncState !== "undefined") return false;
+  const db = maybe.db;
+  return !!db && typeof db.syncState !== "undefined" && typeof db.onSyncStateChanged === "function";
+}
+function resolveSyncStateSource(input) {
+  return isNeetruClient(input) ? input.db : input;
+}
 function serializeQuery(query) {
   if (!query) return "";
   try {
@@ -109,15 +118,16 @@ function useCollection(ref, query) {
   }, [ref, queryKey]);
   return state;
 }
-function useSyncState(ns) {
-  const [state, setState] = React__namespace.useState(() => ns.syncState);
+function useSyncState(input) {
+  const source = resolveSyncStateSource(input);
+  const [state, setState] = React__namespace.useState(() => source.syncState);
   const mountedRef = React__namespace.useRef(true);
   React__namespace.useEffect(() => {
     mountedRef.current = true;
     if (mountedRef.current) {
-      setState(ns.syncState);
+      setState(source.syncState);
     }
-    const unsubscribe = ns.onSyncStateChanged((s) => {
+    const unsubscribe = source.onSyncStateChanged((s) => {
       if (!mountedRef.current) return;
       setState(s);
     });
@@ -125,7 +135,7 @@ function useSyncState(ns) {
       mountedRef.current = false;
       unsubscribe();
     };
-  }, [ns]);
+  }, [source]);
   return state;
 }
 

package/dist/db-react.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/db/react.ts"],"names":["React"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAiFA,SAAS,eAAe,KAAA,EAAoC;AAC1D,EAAA,IAAI,CAAC,OAAO,OAAO,EAAA;AACnB,EAAA,IAAI;AACF,IAAA,OAAO,IAAA,CAAK,UAAU,KAAA,EAAO,MAAA,CAAO,KAAK,KAAK,CAAA,CAAE,MAAM,CAAA;AAAA,EACxD,CAAA,CAAA,MAAQ;AACN,IAAA,OAAO,OAAO,KAAK,CAAA;AAAA,EACrB;AACF;AAoBO,SAAS,WAAA,CACd,KACA,EAAA,EACsB;AACtB,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAUA,gBAAA,CAAA,QAAA,CAA+B;AAAA,IAC7D,IAAA,EAAM,IAAA;AAAA,IACN,OAAA,EAAS,IAAA;AAAA,IACT,SAAA,EAAW,IAAA;AAAA,IACX,KAAA,EAAO;AAAA,GACR,CAAA;AAGD,EAAA,MAAM,UAAA,GAAmBA,wBAAO,IAAI,CAAA;AAEpC,EAAMA,2BAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAErB,IAAA,QAAA,CAAS,EAAE,MAAM,IAAA,EAAM,OAAA,EAAS,MAAM,SAAA,EAAW,IAAA,EAAM,KAAA,EAAO,KAAA,EAAO,CAAA;AAErE,IAAA,MAAM,MAAA,GAAS,GAAA,CAAI,GAAA,CAAI,EAAE,CAAA;AAEzB,IAAA,MAAM,cAA2B,MAAA,CAAO,UAAA;AAAA,MACtC,CAAC,IAAA,KAAgC;AAC/B,QAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,QAAA,IAAI,IAAA,KAAS,IAAA,IAAQ,IAAA,CAAK,IAAA,CAAK,WAAW,CAAA,EAAG;AAC3C,UAAA,QAAA,CAAS;AAAA,YACP,IAAA,EAAM,IAAA;AAAA,YACN,OAAA,EAAS,KAAA;AAAA,YACT,SAAA,EAAW,MAAM,SAAA,IAAa,IAAA;AAAA,YAC9B,KAAA,EAAO,MAAM,KAAA,IAAS;AAAA,WACvB,CAAA;AAAA,QACH,CAAA,MAAO;AACL,UAAA,QAAA,CAAS;AAAA,YACP,IAAA,EAAM,IAAA,CAAK,IAAA,CAAK,CAAC,GAAG,IAAA,IAAQ,IAAA;AAAA,YAC5B,OAAA,EAAS,KAAA;AAAA,YACT,WAAW,IAAA,CAAK,SAAA;AAAA,YAChB,OAAO,IAAA,CAAK;AAAA,WACb,CAAA;AAAA,QACH;AAAA,MACF;AAAA,KACF;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,GAAA,EAAK,EAAE,CAAC,CAAA;AAEZ,EAAA,OAAO,KAAA;AACT;AAmBO,SAAS,aAAA,CACd,KACA,KAAA,EACwB;AACxB,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,CAAA,GAAUA,gBAAA,CAAA,QAAA,CAAiC;AAAA,IAC/D,MAAM,EAAC;AAAA,IACP,OAAA,EAAS,IAAA;AAAA,IACT,SAAA,EAAW,IAAA;AAAA,IACX,KAAA,EAAO,KAAA;AAAA,IACP,gBAAA,EAAkB;AAAA,GACnB,CAAA;AAED,EAAA,MAAM,UAAA,GAAmBA,wBAAO,IAAI,CAAA;AAIpC,EAAA,MAAM,QAAA,GAAW,eAAe,KAAK,CAAA;AAErC,EAAMA,2BAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAErB,IAAA,QAAA,CAAS;AAAA,MACP,MAAM,EAAC;AAAA,MACP,OAAA,EAAS,IAAA;AAAA,MACT,SAAA,EAAW,IAAA;AAAA,MACX,KAAA,EAAO,KAAA;AAAA,MACP,gBAAA,EAAkB;AAAA,KACnB,CAAA;AAED,IAAA,MAAM,cAA2B,GAAA,CAAI,UAAA;AAAA,MACnC,KAAA;AAAA,MACA,CAAC,IAAA,KAA0B;AACzB,QAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,QAAA,QAAA,CAAS;AAAA,UACP,MAAM,IAAA,CAAK,IAAA;AAAA,UACX,OAAA,EAAS,KAAA;AAAA,UACT,WAAW,IAAA,CAAK,SAAA;AAAA,UAChB,OAAO,IAAA,CAAK,KAAA;AAAA,UACZ,kBAAkB,IAAA,CAAK;AAAA,SACxB,CAAA;AAAA,MACH;AAAA,KACF;AAEA,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,GAAA,EAAK,QAAQ,CAAC,CAAA;AAElB,EAAA,OAAO,KAAA;AACT;AAwBO,SAAS,aAAa,EAAA,EAAgC;AAC3D,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,IAAUA,gBAAA,CAAA,QAAA,CAAoB,MAAM,GAAG,SAAS,CAAA;AAEtE,EAAA,MAAM,UAAA,GAAmBA,wBAAO,IAAI,CAAA;AAEpC,EAAMA,2BAAU,MAAM;AACpB,IAAA,UAAA,CAAW,OAAA,GAAU,IAAA;AAGrB,IAAA,IAAI,WAAW,OAAA,EAAS;AACtB,MAAA,QAAA,CAAS,GAAG,SAAS,CAAA;AAAA,IACvB;AAEA,IAAA,MAAM,WAAA,GAA2B,EAAA,CAAG,kBAAA,CAAmB,CAAC,CAAA,KAAiB;AACvE,MAAA,IAAI,CAAC,WAAW,OAAA,EAAS;AACzB,MAAA,QAAA,CAAS,CAAC,CAAA;AAAA,IACZ,CAAC,CAAA;AAED,IAAA,OAAO,MAAM;AACX,MAAA,UAAA,CAAW,OAAA,GAAU,KAAA;AACrB,MAAA,WAAA,EAAY;AAAA,IACd,CAAA;AAAA,EAEF,CAAA,EAAG,CAAC,EAAE,CAAC,CAAA;AAEP,EAAA,OAAO,KAAA;AACT","file":"db-react.cjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o SyncState do namespace offline.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda.\r\n * Usado para renderizar indicadores \"sincronizando…\" ou \"offline\" na UI.\r\n *\r\n * ```tsx\r\n * const state = useSyncState(ns);\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou\r\n * qualquer objeto com `syncState` + `onSyncStateChanged`).\r\n *\r\n * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.\r\n * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)\r\n * pois o `NeetruClient.db` completo está fora do escopo do M2.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(ns: SyncStateSource): SyncState {\r\n  const [state, setState] = React.useState<SyncState>(() => ns.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(ns.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = ns.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ns]);\r\n\r\n  return state;\r\n}\r\n"]}
+{"version":3,"sources":["../src/db/react.ts"],"names":["React"],"mappings":"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","file":"db-react.cjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}

package/dist/db-react.d.cts

@@ -1,4 +1,6 @@
-import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-DqAAhuhX.cjs';
+import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-nwErcRX8.cjs';
+import 'drizzle-orm/node-postgres';
+import './errors.cjs';
 
 /**
  * Resultado de `useDocument`.
@@ -36,11 +38,23 @@ interface UseCollectionResult<T> {
  *
  * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.
  * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.
+ *
+ * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz
+ * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso
+ * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro
+ * (ver `UseSyncStateInput`).
  */
 interface SyncStateSource {
     readonly syncState: SyncState;
     onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
 }
+/**
+ * Entrada aceita por `useSyncState`:
+ *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,
+ *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).
+ *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).
+ */
+type UseSyncStateInput = NeetruClient | SyncStateSource;
 /**
  * Hook de tempo real para um documento específico.
  *
@@ -75,25 +89,33 @@ declare function useDocument<T>(ref: DbCollectionRef<T>, id: string): UseDocumen
  */
 declare function useCollection<T>(ref: DbCollectionRef<T>, query?: DbQuery): UseCollectionResult<T>;
 /**
- * Hook para observar o SyncState do namespace offline.
+ * Hook para observar o `SyncState` da camada offline em tempo real.
+ *
+ * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para
+ * renderizar indicadores "sincronizando…" / "offline" / contadores de escritas
+ * pendentes na UI.
  *
- * Retorna o `SyncState` atual e re-renderiza quando ele muda.
- * Usado para renderizar indicadores "sincronizando…" ou "offline" na UI.
+ * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):
  *
  * ```tsx
- * const state = useSyncState(ns);
+ * // Forma oficial — passe o client; o hook resolve client.db internamente.
+ * const client = createNeetruClient({ apiKey });
+ * const state = useSyncState(client);
+ *
+ * // Forma direta — passe a fonte (client.db ou o namespace offline cru).
+ * const state = useSyncState(client.db);
+ *
  * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;
  * ```
  *
- * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou
- * qualquer objeto com `syncState` + `onSyncStateChanged`).
- *
- * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.
- * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)
- * pois o `NeetruClient.db` completo está fora do escopo do M2.
+ * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava
+ * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.
+ * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona
+ * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são
+ * reais.
  *
  * Seguro em React 18/19 StrictMode.
  */
-declare function useSyncState(ns: SyncStateSource): SyncState;
+declare function useSyncState(input: UseSyncStateInput): SyncState;
 
-export { type SyncStateSource, type UseCollectionResult, type UseDocumentResult, useCollection, useDocument, useSyncState };
+export { type SyncStateSource, type UseCollectionResult, type UseDocumentResult, type UseSyncStateInput, useCollection, useDocument, useSyncState };

package/dist/db-react.d.ts

@@ -1,4 +1,6 @@
-import { S as SyncState, U as Unsubscribe, d as DbDoc, c as DbCollectionRef, h as DbQuery } from './collection-ref-DqAAhuhX.js';
+import { aa as SyncState, af as Unsubscribe, o as DbDoc, z as NeetruClient, n as DbCollectionRef, t as DbQuery } from './types-BRv8wBxX.js';
+import 'drizzle-orm/node-postgres';
+import './errors.js';
 
 /**
  * Resultado de `useDocument`.
@@ -36,11 +38,23 @@ interface UseCollectionResult<T> {
  *
  * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.
  * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.
+ *
+ * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz
+ * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso
+ * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro
+ * (ver `UseSyncStateInput`).
  */
 interface SyncStateSource {
     readonly syncState: SyncState;
     onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;
 }
+/**
+ * Entrada aceita por `useSyncState`:
+ *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,
+ *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).
+ *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).
+ */
+type UseSyncStateInput = NeetruClient | SyncStateSource;
 /**
  * Hook de tempo real para um documento específico.
  *
@@ -75,25 +89,33 @@ declare function useDocument<T>(ref: DbCollectionRef<T>, id: string): UseDocumen
  */
 declare function useCollection<T>(ref: DbCollectionRef<T>, query?: DbQuery): UseCollectionResult<T>;
 /**
- * Hook para observar o SyncState do namespace offline.
+ * Hook para observar o `SyncState` da camada offline em tempo real.
+ *
+ * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para
+ * renderizar indicadores "sincronizando…" / "offline" / contadores de escritas
+ * pendentes na UI.
  *
- * Retorna o `SyncState` atual e re-renderiza quando ele muda.
- * Usado para renderizar indicadores "sincronizando…" ou "offline" na UI.
+ * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):
  *
  * ```tsx
- * const state = useSyncState(ns);
+ * // Forma oficial — passe o client; o hook resolve client.db internamente.
+ * const client = createNeetruClient({ apiKey });
+ * const state = useSyncState(client);
+ *
+ * // Forma direta — passe a fonte (client.db ou o namespace offline cru).
+ * const state = useSyncState(client.db);
+ *
  * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;
  * ```
  *
- * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou
- * qualquer objeto com `syncState` + `onSyncStateChanged`).
- *
- * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.
- * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)
- * pois o `NeetruClient.db` completo está fora do escopo do M2.
+ * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava
+ * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.
+ * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona
+ * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são
+ * reais.
  *
  * Seguro em React 18/19 StrictMode.
  */
-declare function useSyncState(ns: SyncStateSource): SyncState;
+declare function useSyncState(input: UseSyncStateInput): SyncState;
 
-export { type SyncStateSource, type UseCollectionResult, type UseDocumentResult, useCollection, useDocument, useSyncState };
+export { type SyncStateSource, type UseCollectionResult, type UseDocumentResult, type UseSyncStateInput, useCollection, useDocument, useSyncState };

package/dist/db-react.mjs

@@ -1,6 +1,15 @@
 import * as React from 'react';
 
 // src/db/react.ts
+function isNeetruClient(input) {
+  const maybe = input;
+  if (typeof maybe.syncState !== "undefined") return false;
+  const db = maybe.db;
+  return !!db && typeof db.syncState !== "undefined" && typeof db.onSyncStateChanged === "function";
+}
+function resolveSyncStateSource(input) {
+  return isNeetruClient(input) ? input.db : input;
+}
 function serializeQuery(query) {
   if (!query) return "";
   try {
@@ -87,15 +96,16 @@ function useCollection(ref, query) {
   }, [ref, queryKey]);
   return state;
 }
-function useSyncState(ns) {
-  const [state, setState] = React.useState(() => ns.syncState);
+function useSyncState(input) {
+  const source = resolveSyncStateSource(input);
+  const [state, setState] = React.useState(() => source.syncState);
   const mountedRef = React.useRef(true);
   React.useEffect(() => {
     mountedRef.current = true;
     if (mountedRef.current) {
-      setState(ns.syncState);
+      setState(source.syncState);
     }
-    const unsubscribe = ns.onSyncStateChanged((s) => {
+    const unsubscribe = source.onSyncStateChanged((s) => {
       if (!mountedRef.current) return;
       setState(s);
     });
@@ -103,7 +113,7 @@ function useSyncState(ns) {
       mountedRef.current = false;
       unsubscribe();
     };
-  }, [ns]);
+  }, [source]);
   return state;
 }
 

package/dist/db-react.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/db/react.ts"],"names":[],"mappings":"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","file":"db-react.mjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o SyncState do namespace offline.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda.\r\n * Usado para renderizar indicadores \"sincronizando…\" ou \"offline\" na UI.\r\n *\r\n * ```tsx\r\n * const state = useSyncState(ns);\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * `ns` deve ser o namespace retornado por `createOfflineDocumentsNamespace` (ou\r\n * qualquer objeto com `syncState` + `onSyncStateChanged`).\r\n *\r\n * Alinhado com 02-sdk.md §3.6: `useSyncState(client: NeetruClient): NeetruSyncState`.\r\n * Na camada M2, aceita diretamente o namespace de documentos (`SyncStateSource`)\r\n * pois o `NeetruClient.db` completo está fora do escopo do M2.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(ns: SyncStateSource): SyncState {\r\n  const [state, setState] = React.useState<SyncState>(() => ns.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(ns.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = ns.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ns]);\r\n\r\n  return state;\r\n}\r\n"]}
+{"version":3,"sources":["../src/db/react.ts"],"names":[],"mappings":"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","file":"db-react.mjs","sourcesContent":["/**\r\n * Bindings React do módulo db (M2) — `@neetru/sdk/react`.\r\n *\r\n * Exporta três hooks de tempo real que se integram com a camada offline do\r\n * `@neetru/sdk/db`:\r\n *\r\n *   - `useDocument(ref, id)` — subscreve ao onSnapshot de um documento.\r\n *   - `useCollection(ref, query?)` — subscreve ao onSnapshot de uma coleção.\r\n *   - `useSyncState(ns)` — observa o SyncState do namespace offline.\r\n *\r\n * ### Design\r\n * Segue o padrão do subpath `/react` existente (cliente/ref passados\r\n * explicitamente, sem Context Provider obrigatório). Alinhado com 02-sdk.md §3.6.\r\n *\r\n * ### React 18/19 StrictMode\r\n * Cada hook usa um ref interno para rastrear se o componente foi desmontado,\r\n * e a função `useEffect` retorna sempre a função de unsubscribe. Em StrictMode,\r\n * o duplo-mount/unmount do React 18 chama cleanup corretamente — não há leak.\r\n *\r\n * ### Dependências\r\n * `react` é peer dependency — não importada como dep direta.\r\n */\r\nimport * as React from 'react';\r\nimport type { DbCollectionRef, DbDoc, DbQuery, DbListResult, DbGetResult } from './collection-ref';\r\nimport type { SyncState, Unsubscribe } from './offline/types';\r\nimport type { NeetruClient } from '../types';\r\n\r\n// ─── Tipos públicos dos hooks ─────────────────────────────────────────────────\r\n\r\n/**\r\n * Resultado de `useDocument`.\r\n *\r\n * - `data` — dados do documento, ou `null` se não existe / ainda carregando.\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local, não do servidor.\r\n * - `stale` — conexão caída ou sincronizando; pode haver dados mais novos.\r\n */\r\nexport interface UseDocumentResult<T> {\r\n  data: T | null;\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n}\r\n\r\n/**\r\n * Resultado de `useCollection`.\r\n *\r\n * - `docs` — documentos da coleção (ou subconjunto via query).\r\n * - `loading` — `true` enquanto o primeiro snapshot não foi entregue.\r\n * - `fromCache` — o snapshot veio do cache local.\r\n * - `stale` — conexão caída ou sincronizando.\r\n * - `hasPendingWrites` — ao menos um doc tem escrita local não confirmada.\r\n */\r\nexport interface UseCollectionResult<T> {\r\n  docs: DbDoc<T>[];\r\n  loading: boolean;\r\n  fromCache: boolean;\r\n  stale: boolean;\r\n  hasPendingWrites: boolean;\r\n}\r\n\r\n/**\r\n * Subconjunto mínimo do namespace offline que `useSyncState` precisa.\r\n * Compatível com `NeetruDbDocuments` de `collection-ref.ts`.\r\n *\r\n * Passado explicitamente (sem Context) para alinhar com o padrão do SDK.\r\n * Tipicamente: o namespace retornado por `createOfflineDocumentsNamespace`.\r\n *\r\n * `client.db` (o `NeetruDb` retornado por `createNeetruClient`) também satisfaz\r\n * este contrato — expõe `syncState` + `onSyncStateChanged` reais. Por isso\r\n * `useSyncState` aceita tanto a fonte direta quanto o `NeetruClient` inteiro\r\n * (ver `UseSyncStateInput`).\r\n */\r\nexport interface SyncStateSource {\r\n  readonly syncState: SyncState;\r\n  onSyncStateChanged(cb: (s: SyncState) => void): Unsubscribe;\r\n}\r\n\r\n/**\r\n * Entrada aceita por `useSyncState`:\r\n *   - `NeetruClient`     → resolve `client.db` automaticamente (forma oficial,\r\n *                          alinhada com 02-sdk.md §3.6 `useSyncState(client)`).\r\n *   - `SyncStateSource`  → fonte direta (`client.db` ou o namespace offline cru).\r\n */\r\nexport type UseSyncStateInput = NeetruClient | SyncStateSource;\r\n\r\n/**\r\n * Type guard — detecta se a entrada é um `NeetruClient` (tem `.db` que é, ele\r\n * próprio, um `SyncStateSource`) e não uma fonte direta. Distinção em runtime\r\n * porque os shapes não se sobrepõem: a fonte direta expõe `syncState` no nível\r\n * de topo; o client expõe via `.db`.\r\n */\r\nfunction isNeetruClient(input: UseSyncStateInput): input is NeetruClient {\r\n  const maybe = input as { db?: unknown; syncState?: unknown };\r\n  // Fonte direta já tem `syncState` no topo → não é o client wrapper.\r\n  if (typeof maybe.syncState !== 'undefined') return false;\r\n  const db = maybe.db as { syncState?: unknown; onSyncStateChanged?: unknown } | undefined;\r\n  return (\r\n    !!db &&\r\n    typeof db.syncState !== 'undefined' &&\r\n    typeof db.onSyncStateChanged === 'function'\r\n  );\r\n}\r\n\r\n/** Normaliza qualquer entrada aceita para a `SyncStateSource` subjacente. */\r\nfunction resolveSyncStateSource(input: UseSyncStateInput): SyncStateSource {\r\n  return isNeetruClient(input) ? (input.db as unknown as SyncStateSource) : input;\r\n}\r\n\r\n// ─── Serialização estável de query ────────────────────────────────────────────\r\n\r\n/**\r\n * Serializa uma DbQuery para string estável, usada como chave de efeito.\r\n *\r\n * `useCollection` re-subscreve somente quando a serialização muda, NÃO por\r\n * identidade de objeto. Isso evita a armadilha clássica de inline-object em\r\n * JSX que causaria re-subscribe em todo render.\r\n */\r\nfunction serializeQuery(query: DbQuery | undefined): string {\r\n  if (!query) return '';\r\n  try {\r\n    return JSON.stringify(query, Object.keys(query).sort());\r\n  } catch {\r\n    return String(query);\r\n  }\r\n}\r\n\r\n// ─── useDocument ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para um documento específico.\r\n *\r\n * Subscreve a `ref.doc(id).onSnapshot` no mount. Re-subscreve quando `ref`\r\n * ou `id` mudam. Cancela a subscrição no unmount.\r\n *\r\n * ```tsx\r\n * const { data, loading, fromCache, stale } = useDocument(ordersRef, orderId);\r\n * if (loading) return <Spinner />;\r\n * if (!data) return <NotFound />;\r\n * return <OrderCard order={data} fromCache={fromCache} />;\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode: a cleanup function do useEffect cancela\r\n * o listener no unmount, e o double-mount do StrictMode não vaza estado.\r\n */\r\nexport function useDocument<T>(\r\n  ref: DbCollectionRef<T>,\r\n  id: string,\r\n): UseDocumentResult<T> {\r\n  const [state, setState] = React.useState<UseDocumentResult<T>>({\r\n    data: null,\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n  });\r\n\r\n  // Ref para detectar unmount e evitar setState após cleanup.\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset para loading quando ref/id muda\r\n    setState({ data: null, loading: true, fromCache: true, stale: false });\r\n\r\n    const docRef = ref.doc(id);\r\n\r\n    const unsubscribe: Unsubscribe = docRef.onSnapshot(\r\n      (snap: DbGetResult<T> | null) => {\r\n        if (!mountedRef.current) return;\r\n        if (snap === null || snap.docs.length === 0) {\r\n          setState({\r\n            data: null,\r\n            loading: false,\r\n            fromCache: snap?.fromCache ?? true,\r\n            stale: snap?.stale ?? false,\r\n          });\r\n        } else {\r\n          setState({\r\n            data: snap.docs[0]?.data ?? null,\r\n            loading: false,\r\n            fromCache: snap.fromCache,\r\n            stale: snap.stale,\r\n          });\r\n        }\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, id]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useCollection ────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook de tempo real para uma coleção (ou subconjunto filtrado).\r\n *\r\n * Subscreve a `ref.onSnapshot(query, cb)` no mount. Re-subscreve quando `ref`\r\n * ou a serialização de `query` muda — NÃO por identidade de objeto, o que\r\n * evita re-subscribe desnecessário em inline objects.\r\n *\r\n * ```tsx\r\n * const { docs, loading, hasPendingWrites } = useCollection(ordersRef, {\r\n *   where: [{ field: 'status', op: '==', value: 'open' }],\r\n * });\r\n * ```\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useCollection<T>(\r\n  ref: DbCollectionRef<T>,\r\n  query?: DbQuery,\r\n): UseCollectionResult<T> {\r\n  const [state, setState] = React.useState<UseCollectionResult<T>>({\r\n    docs: [],\r\n    loading: true,\r\n    fromCache: true,\r\n    stale: false,\r\n    hasPendingWrites: false,\r\n  });\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  // Serializamos a query para garantir que mudanças de valor (não de referência)\r\n  // triggam o re-subscribe, mas que objetos iguais não causem loop.\r\n  const queryKey = serializeQuery(query);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n    // Reset loading ao trocar de query/ref\r\n    setState({\r\n      docs: [],\r\n      loading: true,\r\n      fromCache: true,\r\n      stale: false,\r\n      hasPendingWrites: false,\r\n    });\r\n\r\n    const unsubscribe: Unsubscribe = ref.onSnapshot(\r\n      query,\r\n      (snap: DbListResult<T>) => {\r\n        if (!mountedRef.current) return;\r\n        setState({\r\n          docs: snap.docs,\r\n          loading: false,\r\n          fromCache: snap.fromCache,\r\n          stale: snap.stale,\r\n          hasPendingWrites: snap.hasPendingWrites,\r\n        });\r\n      },\r\n    );\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [ref, queryKey]);\r\n\r\n  return state;\r\n}\r\n\r\n// ─── useSyncState ─────────────────────────────────────────────────────────────\r\n\r\n/**\r\n * Hook para observar o `SyncState` da camada offline em tempo real.\r\n *\r\n * Retorna o `SyncState` atual e re-renderiza quando ele muda. Usado para\r\n * renderizar indicadores \"sincronizando…\" / \"offline\" / contadores de escritas\r\n * pendentes na UI.\r\n *\r\n * Aceita duas formas de entrada (SDK-QW-4 — wiring ao client real):\r\n *\r\n * ```tsx\r\n * // Forma oficial — passe o client; o hook resolve client.db internamente.\r\n * const client = createNeetruClient({ apiKey });\r\n * const state = useSyncState(client);\r\n *\r\n * // Forma direta — passe a fonte (client.db ou o namespace offline cru).\r\n * const state = useSyncState(client.db);\r\n *\r\n * if (state.status === 'offline') return <OfflineBanner pending={state.pendingWrites} />;\r\n * ```\r\n *\r\n * Antes desta versão o hook só aceitava a `SyncStateSource` crua, o que levava\r\n * consumers a stub-arem o estado pra sempre `'idle'` em vez de ligar no client.\r\n * Agora `useSyncState(client)` (a forma documentada em 02-sdk.md §3.6) funciona\r\n * de ponta a ponta — `client.db.syncState` / `client.db.onSyncStateChanged` são\r\n * reais.\r\n *\r\n * Seguro em React 18/19 StrictMode.\r\n */\r\nexport function useSyncState(input: UseSyncStateInput): SyncState {\r\n  // Resolve uma única vez por render; se a identidade da fonte resolvida mudar,\r\n  // o efeito abaixo re-subscreve (dependência `source`).\r\n  const source = resolveSyncStateSource(input);\r\n\r\n  const [state, setState] = React.useState<SyncState>(() => source.syncState);\r\n\r\n  const mountedRef = React.useRef(true);\r\n\r\n  React.useEffect(() => {\r\n    mountedRef.current = true;\r\n\r\n    // Snapshot inicial imediato ao montar (pode ter mudado entre render e effect)\r\n    if (mountedRef.current) {\r\n      setState(source.syncState);\r\n    }\r\n\r\n    const unsubscribe: Unsubscribe = source.onSyncStateChanged((s: SyncState) => {\r\n      if (!mountedRef.current) return;\r\n      setState(s);\r\n    });\r\n\r\n    return () => {\r\n      mountedRef.current = false;\r\n      unsubscribe();\r\n    };\r\n    // eslint-disable-next-line react-hooks/exhaustive-deps\r\n  }, [source]);\r\n\r\n  return state;\r\n}\r\n"]}