@neetru/sdk 3.0.2 → 3.1.0

package/dist/react.d.cts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { N as NeetruClient, g as CheckoutStartResult } from './types-Dc4bjrrt.cjs';
-import './collection-ref-BDdfD87k.cjs';
+import { z as NeetruClient, g as CheckoutStartResult, A as AuthNamespace, T as NeetruUser } from './types-nwErcRX8.cjs';
+import { CollectionReference, Query, DocumentReference } from './firestore-compat.cjs';
 import 'drizzle-orm/node-postgres';
 import './errors.cjs';
 
@@ -111,5 +111,119 @@ interface EntitlementGateProps {
  * deve preferir `mode='readonly'` pra preservar engajamento (não hard-block).
  */
 declare function EntitlementGate({ client, feature, productSlug, mode, fallback, loading, children, }: EntitlementGateProps): React.ReactElement;
+/** Resultado de `useCollection`. */
+interface UseCollectionResult<T> {
+    /** Documentos (cada um com `id` embutido) ou `null` enquanto carrega/sem ref. */
+    data: Array<T & {
+        id: string;
+    }> | null;
+    /** `true` enquanto o primeiro snapshot não chegou. */
+    isLoading: boolean;
+    /** Erro do último refresh (dados exibidos podem estar defasados). */
+    error: Error | null;
+    /** `true` quando um refresh falhou ou o snapshot veio do cache/offline. */
+    isStale: boolean;
+    /** epoch ms do último snapshot bem-sucedido, ou `null`. */
+    lastUpdated: number | null;
+}
+/** Resultado de `useDoc`. */
+interface UseDocResult<T> {
+    data: (T & {
+        id: string;
+    }) | null;
+    isLoading: boolean;
+    error: Error | null;
+    isStale: boolean;
+    lastUpdated: number | null;
+}
+/** Opções comuns dos hooks de dados. */
+interface UseDataOptions {
+    /**
+     * Intervalo de polling de fallback em ms (quando o transporte não oferece
+     * realtime nativo). Default 5000. O polling pausa quando a aba está oculta.
+     */
+    intervalMs?: number;
+    /**
+     * Força polling mesmo quando o `onSnapshot` nativo está disponível. Útil para
+     * transportes REST onde `onSnapshot` só entrega o snapshot inicial.
+     * Default: `false` (usa realtime quando o transporte oferece).
+     */
+    poll?: boolean;
+}
+/**
+ * Hook de tempo real para uma coleção (ou subconjunto filtrado via `query`).
+ *
+ * Aceita uma `CollectionReference` ou `Query` do `@neetru/sdk/firestore-compat`.
+ * Subscreve ao `onSnapshot` nativo do `client.db`; quando o transporte é REST
+ * (sem realtime nativo), faz polling visibility-aware no `intervalMs`.
+ *
+ * ```tsx
+ * import { collection, query, where } from '@neetru/sdk/firestore-compat';
+ * import { useCollection } from '@neetru/sdk/react';
+ *
+ * const ref = useMemo(
+ *   () => query(collection(client.db, 'orders'), where('status', '==', 'open')),
+ *   [],
+ * );
+ * const { data, isLoading, error, isStale } = useCollection<Order>(ref);
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useCollection<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T> | null | undefined, options?: UseDataOptions): UseCollectionResult<T>;
+/**
+ * Hook de tempo real para um documento.
+ *
+ * Aceita uma `DocumentReference` do `@neetru/sdk/firestore-compat`.
+ *
+ * ```tsx
+ * import { doc } from '@neetru/sdk/firestore-compat';
+ * import { useDoc } from '@neetru/sdk/react';
+ *
+ * const ref = useMemo(() => doc(client.db, 'profiles', uid), [uid]);
+ * const { data, isLoading } = useDoc<Profile>(ref);
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useDoc<T = Record<string, unknown>>(ref: DocumentReference<T> | null | undefined, options?: UseDataOptions): UseDocResult<T>;
+/**
+ * Fonte de auth aceita por `useUser`: o `NeetruClient` inteiro (resolve
+ * `client.auth`) ou o `AuthNamespace` direto.
+ */
+type UseUserInput = NeetruClient | {
+    auth: AuthNamespace;
+} | AuthNamespace;
+/** Resultado de `useUser`. */
+interface UseUserResult {
+    /** Usuário autenticado ou `null`. */
+    user: NeetruUser | null;
+    /** `true` enquanto o estado de auth inicial não foi resolvido. */
+    isLoading: boolean;
+    /** Erro na resolução de auth (raro — listener nunca deveria lançar). */
+    error: Error | null;
+}
+/**
+ * Hook de estado de autenticação.
+ *
+ * Subscreve a `client.auth.onAuthStateChanged` e devolve `{ user, isLoading,
+ * error }`. Inclui um **timeout de seed** (default 8s): se o estado de auth não
+ * resolver nesse prazo, `isLoading` cai para `false` com `user: null` — evita
+ * spinners infinitos quando o provedor de auth nunca dispara o callback.
+ *
+ * ```tsx
+ * import { useUser } from '@neetru/sdk/react';
+ * const { user, isLoading } = useUser(client);
+ * if (isLoading) return <Spinner />;
+ * if (!user) return <SignInButton />;
+ * return <Avatar user={user} />;
+ * ```
+ *
+ * Aceita o `NeetruClient`, `{ auth }` ou o `AuthNamespace` direto.
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useUser(input: UseUserInput, options?: {
+    timeoutMs?: number;
+}): UseUserResult;
 
-export { CheckoutLink, type CheckoutLinkProps, EntitlementGate, type EntitlementGateMode, type EntitlementGateProps, useEntitlementContext };
+export { CheckoutLink, type CheckoutLinkProps, EntitlementGate, type EntitlementGateMode, type EntitlementGateProps, type UseCollectionResult, type UseDataOptions, type UseDocResult, type UseUserInput, type UseUserResult, useCollection, useDoc, useEntitlementContext, useUser };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as React from 'react';
-import { N as NeetruClient, g as CheckoutStartResult } from './types-D7zVkO3n.js';
-import './collection-ref-BDdfD87k.js';
+import { z as NeetruClient, g as CheckoutStartResult, A as AuthNamespace, T as NeetruUser } from './types-BRv8wBxX.js';
+import { CollectionReference, Query, DocumentReference } from './firestore-compat.js';
 import 'drizzle-orm/node-postgres';
 import './errors.js';
 
@@ -111,5 +111,119 @@ interface EntitlementGateProps {
  * deve preferir `mode='readonly'` pra preservar engajamento (não hard-block).
  */
 declare function EntitlementGate({ client, feature, productSlug, mode, fallback, loading, children, }: EntitlementGateProps): React.ReactElement;
+/** Resultado de `useCollection`. */
+interface UseCollectionResult<T> {
+    /** Documentos (cada um com `id` embutido) ou `null` enquanto carrega/sem ref. */
+    data: Array<T & {
+        id: string;
+    }> | null;
+    /** `true` enquanto o primeiro snapshot não chegou. */
+    isLoading: boolean;
+    /** Erro do último refresh (dados exibidos podem estar defasados). */
+    error: Error | null;
+    /** `true` quando um refresh falhou ou o snapshot veio do cache/offline. */
+    isStale: boolean;
+    /** epoch ms do último snapshot bem-sucedido, ou `null`. */
+    lastUpdated: number | null;
+}
+/** Resultado de `useDoc`. */
+interface UseDocResult<T> {
+    data: (T & {
+        id: string;
+    }) | null;
+    isLoading: boolean;
+    error: Error | null;
+    isStale: boolean;
+    lastUpdated: number | null;
+}
+/** Opções comuns dos hooks de dados. */
+interface UseDataOptions {
+    /**
+     * Intervalo de polling de fallback em ms (quando o transporte não oferece
+     * realtime nativo). Default 5000. O polling pausa quando a aba está oculta.
+     */
+    intervalMs?: number;
+    /**
+     * Força polling mesmo quando o `onSnapshot` nativo está disponível. Útil para
+     * transportes REST onde `onSnapshot` só entrega o snapshot inicial.
+     * Default: `false` (usa realtime quando o transporte oferece).
+     */
+    poll?: boolean;
+}
+/**
+ * Hook de tempo real para uma coleção (ou subconjunto filtrado via `query`).
+ *
+ * Aceita uma `CollectionReference` ou `Query` do `@neetru/sdk/firestore-compat`.
+ * Subscreve ao `onSnapshot` nativo do `client.db`; quando o transporte é REST
+ * (sem realtime nativo), faz polling visibility-aware no `intervalMs`.
+ *
+ * ```tsx
+ * import { collection, query, where } from '@neetru/sdk/firestore-compat';
+ * import { useCollection } from '@neetru/sdk/react';
+ *
+ * const ref = useMemo(
+ *   () => query(collection(client.db, 'orders'), where('status', '==', 'open')),
+ *   [],
+ * );
+ * const { data, isLoading, error, isStale } = useCollection<Order>(ref);
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useCollection<T = Record<string, unknown>>(source: CollectionReference<T> | Query<T> | null | undefined, options?: UseDataOptions): UseCollectionResult<T>;
+/**
+ * Hook de tempo real para um documento.
+ *
+ * Aceita uma `DocumentReference` do `@neetru/sdk/firestore-compat`.
+ *
+ * ```tsx
+ * import { doc } from '@neetru/sdk/firestore-compat';
+ * import { useDoc } from '@neetru/sdk/react';
+ *
+ * const ref = useMemo(() => doc(client.db, 'profiles', uid), [uid]);
+ * const { data, isLoading } = useDoc<Profile>(ref);
+ * ```
+ *
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useDoc<T = Record<string, unknown>>(ref: DocumentReference<T> | null | undefined, options?: UseDataOptions): UseDocResult<T>;
+/**
+ * Fonte de auth aceita por `useUser`: o `NeetruClient` inteiro (resolve
+ * `client.auth`) ou o `AuthNamespace` direto.
+ */
+type UseUserInput = NeetruClient | {
+    auth: AuthNamespace;
+} | AuthNamespace;
+/** Resultado de `useUser`. */
+interface UseUserResult {
+    /** Usuário autenticado ou `null`. */
+    user: NeetruUser | null;
+    /** `true` enquanto o estado de auth inicial não foi resolvido. */
+    isLoading: boolean;
+    /** Erro na resolução de auth (raro — listener nunca deveria lançar). */
+    error: Error | null;
+}
+/**
+ * Hook de estado de autenticação.
+ *
+ * Subscreve a `client.auth.onAuthStateChanged` e devolve `{ user, isLoading,
+ * error }`. Inclui um **timeout de seed** (default 8s): se o estado de auth não
+ * resolver nesse prazo, `isLoading` cai para `false` com `user: null` — evita
+ * spinners infinitos quando o provedor de auth nunca dispara o callback.
+ *
+ * ```tsx
+ * import { useUser } from '@neetru/sdk/react';
+ * const { user, isLoading } = useUser(client);
+ * if (isLoading) return <Spinner />;
+ * if (!user) return <SignInButton />;
+ * return <Avatar user={user} />;
+ * ```
+ *
+ * Aceita o `NeetruClient`, `{ auth }` ou o `AuthNamespace` direto.
+ * Seguro em React 18/19 StrictMode.
+ */
+declare function useUser(input: UseUserInput, options?: {
+    timeoutMs?: number;
+}): UseUserResult;
 
-export { CheckoutLink, type CheckoutLinkProps, EntitlementGate, type EntitlementGateMode, type EntitlementGateProps, useEntitlementContext };
+export { CheckoutLink, type CheckoutLinkProps, EntitlementGate, type EntitlementGateMode, type EntitlementGateProps, type UseCollectionResult, type UseDataOptions, type UseDocResult, type UseUserInput, type UseUserResult, useCollection, useDoc, useEntitlementContext, useUser };

package/dist/react.mjs

@@ -1,5 +1,34 @@
 import * as React from 'react';
 
+// src/react.ts
+
+// src/firestore-compat.ts
+function toDbQuery(constraints) {
+  const whereFilters = [];
+  let orderByClause;
+  let limitValue;
+  for (const c of constraints) {
+    if (c.__constraint === "where") {
+      const w = c;
+      whereFilters.push({ field: w.field, op: normalizeOp(w.op), value: w.value });
+    } else if (c.__constraint === "orderBy") {
+      const o = c;
+      orderByClause = { field: o.field, direction: o.direction };
+    } else if (c.__constraint === "limit") {
+      limitValue = c.value;
+    }
+  }
+  const out = {};
+  if (whereFilters.length > 0) out.where = whereFilters;
+  if (orderByClause) out.orderBy = orderByClause;
+  if (limitValue !== void 0) out.limit = limitValue;
+  return out;
+}
+function normalizeOp(op) {
+  if (op === "array-contains-any") return "array-contains";
+  return op;
+}
+
 // src/react.ts
 function CheckoutLink({
   client,
@@ -132,7 +161,242 @@ function EntitlementGate({
     children
   );
 }
+var DEFAULT_INTERVAL_MS = 5e3;
+function isDocumentHidden() {
+  return typeof document !== "undefined" && document.hidden === true;
+}
+function serializeSource(source) {
+  if (!source) return null;
+  if (source.__kind === "collection") {
+    return `collection:${source.id}`;
+  }
+  const dbQuery = toDbQuery(source.constraints);
+  return `query:${source.collection}:${JSON.stringify(dbQuery)}`;
+}
+function rowsFromList(snap) {
+  return snap.docs.map((d) => {
+    const data = d.data;
+    const { id: _omit, ...rest } = data;
+    return { ...rest, id: d.id };
+  });
+}
+function rowFromGet(snap, id) {
+  const first = snap?.docs[0];
+  if (!first) return null;
+  const data = first.data;
+  const { id: _omit, ...rest } = data;
+  return { ...rest, id };
+}
+function useCollection(source, options) {
+  const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const poll = options?.poll ?? false;
+  const sourceKey = serializeSource(
+    source
+  );
+  const [state, setState] = React.useState({
+    data: null,
+    isLoading: sourceKey !== null,
+    error: null,
+    isStale: false,
+    lastUpdated: null
+  });
+  const mountedRef = React.useRef(true);
+  const sourceRef = React.useRef(source);
+  sourceRef.current = source;
+  React.useEffect(() => {
+    mountedRef.current = true;
+    const current = sourceRef.current;
+    if (!current || sourceKey === null) {
+      setState({ data: null, isLoading: false, error: null, isStale: false, lastUpdated: null });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
+    setState((prev) => ({ ...prev, isLoading: prev.data === null }));
+    const collectionName = current.__kind === "query" ? current.collection : current.id;
+    const dbQuery = current.__kind === "query" ? toDbQuery(current.constraints) : void 0;
+    const col = current.db.collection(collectionName);
+    const applySnap = (snap) => {
+      if (!mountedRef.current) return;
+      setState({
+        data: rowsFromList(snap),
+        isLoading: false,
+        error: null,
+        isStale: snap.stale === true,
+        lastUpdated: Date.now()
+      });
+    };
+    const applyError = (e) => {
+      if (!mountedRef.current) return;
+      setState((prev) => ({
+        ...prev,
+        // Mantém o último data bom — não limpa em erro de refresh.
+        isLoading: false,
+        error: e instanceof Error ? e : new Error(String(e)),
+        isStale: true
+      }));
+    };
+    if (poll) {
+      let cancelled = false;
+      const fetchOnce = async () => {
+        if (cancelled || isDocumentHidden()) return;
+        try {
+          const snap = await col.list(dbQuery);
+          if (!cancelled) applySnap(snap);
+        } catch (e) {
+          if (!cancelled) applyError(e);
+        }
+      };
+      void fetchOnce();
+      const timer = setInterval(fetchOnce, intervalMs);
+      return () => {
+        cancelled = true;
+        clearInterval(timer);
+        mountedRef.current = false;
+      };
+    }
+    let unsub;
+    try {
+      unsub = col.onSnapshot(dbQuery, applySnap);
+    } catch (e) {
+      applyError(e);
+    }
+    return () => {
+      mountedRef.current = false;
+      unsub?.();
+    };
+  }, [sourceKey, intervalMs, poll]);
+  return state;
+}
+function useDoc(ref, options) {
+  const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
+  const poll = options?.poll ?? false;
+  const refKey = ref && ref.id ? `${ref.collection}/${ref.id}` : null;
+  const [state, setState] = React.useState({
+    data: null,
+    isLoading: refKey !== null,
+    error: null,
+    isStale: false,
+    lastUpdated: null
+  });
+  const mountedRef = React.useRef(true);
+  const refRef = React.useRef(ref);
+  refRef.current = ref;
+  React.useEffect(() => {
+    mountedRef.current = true;
+    const current = refRef.current;
+    if (!current || refKey === null) {
+      setState({ data: null, isLoading: false, error: null, isStale: false, lastUpdated: null });
+      return () => {
+        mountedRef.current = false;
+      };
+    }
+    setState((prev) => ({ ...prev, isLoading: prev.data === null }));
+    const docRef = current.db.collection(current.collection).doc(current.id);
+    const id = current.id;
+    const applySnap = (snap) => {
+      if (!mountedRef.current) return;
+      setState({
+        data: rowFromGet(snap, id),
+        isLoading: false,
+        error: null,
+        isStale: snap?.stale === true,
+        lastUpdated: Date.now()
+      });
+    };
+    const applyError = (e) => {
+      if (!mountedRef.current) return;
+      setState((prev) => ({
+        ...prev,
+        isLoading: false,
+        error: e instanceof Error ? e : new Error(String(e)),
+        isStale: true
+      }));
+    };
+    if (poll) {
+      let cancelled = false;
+      const fetchOnce = async () => {
+        if (cancelled || isDocumentHidden()) return;
+        try {
+          const snap = await docRef.get();
+          if (!cancelled) applySnap(snap);
+        } catch (e) {
+          if (!cancelled) applyError(e);
+        }
+      };
+      void fetchOnce();
+      const timer = setInterval(fetchOnce, intervalMs);
+      return () => {
+        cancelled = true;
+        clearInterval(timer);
+        mountedRef.current = false;
+      };
+    }
+    let unsub;
+    try {
+      unsub = docRef.onSnapshot(applySnap);
+    } catch (e) {
+      applyError(e);
+    }
+    return () => {
+      mountedRef.current = false;
+      unsub?.();
+    };
+  }, [refKey, intervalMs, poll]);
+  return state;
+}
+function resolveAuth(input) {
+  const maybe = input;
+  if (maybe.auth && typeof maybe.auth.onAuthStateChanged === "function") {
+    return maybe.auth;
+  }
+  return input;
+}
+function useUser(input, options) {
+  const timeoutMs = options?.timeoutMs ?? 8e3;
+  const auth = resolveAuth(input);
+  const [state, setState] = React.useState(() => {
+    let seeded = null;
+    try {
+      seeded = auth.getUser();
+    } catch {
+      seeded = null;
+    }
+    return { user: seeded, isLoading: seeded === null, error: null };
+  });
+  const mountedRef = React.useRef(true);
+  React.useEffect(() => {
+    mountedRef.current = true;
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (!mountedRef.current || settled) return;
+      setState((prev) => prev.isLoading ? { ...prev, isLoading: false } : prev);
+    }, timeoutMs);
+    let unsub;
+    try {
+      unsub = auth.onAuthStateChanged((user) => {
+        if (!mountedRef.current) return;
+        settled = true;
+        setState({ user: user ?? null, isLoading: false, error: null });
+      });
+    } catch (e) {
+      if (mountedRef.current) {
+        setState({
+          user: null,
+          isLoading: false,
+          error: e instanceof Error ? e : new Error(String(e))
+        });
+      }
+    }
+    return () => {
+      mountedRef.current = false;
+      clearTimeout(timer);
+      unsub?.();
+    };
+  }, [auth, timeoutMs]);
+  return state;
+}
 
-export { CheckoutLink, EntitlementGate, useEntitlementContext };
+export { CheckoutLink, EntitlementGate, useCollection, useDoc, useEntitlementContext, useUser };
 //# sourceMappingURL=react.mjs.map
 //# sourceMappingURL=react.mjs.map