@gonvex/react 0.1.31 → 0.3.0

package/README.md

@@ -3,8 +3,9 @@
 React bindings for Gonvex.
 
 This package provides the provider and hooks used by generated Gonvex bindings:
-`useQuery`, `useQueryResult`, `useMutation`, `useAction`, `useSync`,
-`useSyncSelector`, auth-aware providers, and Convex-style compatibility exports.
+`useQuery`, `useQueryResult`, `useLiveQuery`, `useLiveQueryState`, `useReducer`, `useAction`, `useEntity`,
+`useReplicaCollection`, `useReplicaCollectionState`, `useReplicaEntities`,
+`useRetainedLiveQuery`, `useControlQuery`, and auth-aware providers.
 
 ## Install
 
@@ -16,7 +17,7 @@ npm install @gonvex/react @gonvex/client
 
 ```tsx
 import { GonvexClient } from "@gonvex/client";
-import { GonvexProvider, useMutation, useQuery } from "@gonvex/react";
+import { GonvexProvider, useReducer, useQuery } from "@gonvex/react";
 import { api } from "./gonvex/_generated/api";
 
 const client = new GonvexClient("ws://localhost:8080/ws", {
@@ -33,7 +34,7 @@ export function AppRoot() {
 
 function Tasks() {
   const tasks = useQuery(api.tasks.list, { status: "open" });
-  const createTask = useMutation(api.tasks.create);
+  const createTask = useReducer(api.tasks.create);
 
   return (
     <button onClick={() => void createTask({ title: "New task" })}>
@@ -43,16 +44,14 @@ function Tasks() {
 }
 ```
 
-`useQuery` automatically benefits from the browser query-result cache. On a
-warm load it may receive the last scoped snapshot first, followed by the
-authoritative server result. Its signature remains `T | undefined`, but a
-server `query.error` now **throws** during render (Convex-compatible) so error
-boundaries can catch it instead of looking like an endless loading state.
+`useQuery` executes a read-only Query once. Persistent, continuously verified
+windows use `useLiveQueryState`, which returns normalized rows plus `source`,
+`completeness`, and `freshness`.
 
-### `useQueryResult` (preferred for new UI)
+### `useQueryResult`
 
-Use when you need loading vs error vs timeout vs disconnected, last-good data,
-or a retry button:
+Use when a one-shot Query needs explicit loading, error, timeout, and retry
+state. A retry can retain its last successful value while verifying again:
 
 ```tsx
 const { data, status, error, isStale, retry } = useQueryResult(api.tasks.list, { status: "open" });
@@ -61,35 +60,51 @@ if (status === "loading" && !data) return <Spinner />;
 if (status === "error") {
   return <button onClick={retry}>Retry: {error?.message}</button>;
 }
-// status success | timeout | disconnected — data may still be last-good (isStale)
+// status success | timeout, data may still be last-good during a retry
 ```
 
-Statuses: `skip` | `loading` | `success` | `error` | `timeout` | `disconnected`.
+Statuses: `skip` | `loading` | `success` | `error` | `timeout`.
 Soft timeout default is 15s (subscription stays alive; does not reject).
 
 ### Connection state
 
 ```tsx
-const { isWebSocketConnected, hasEverConnected, connectionRetries } = useConvexConnectionState();
+const { isWebSocketConnected, hasEverConnected, connectionRetries } = useGonvexConnectionState();
 ```
 
-This reflects the real WebSocket lifecycle (not a stub). Mutations/actions
+This reflects the real WebSocket lifecycle (not a stub). Reducers/Actions
 reject with `GonvexClientError` on timeout or disconnect and never hang forever.
 
-## Durable sync collections
+## Replica Collections
 
-`useSync` reads a bounded entity collection from the client's normalized
+`useReplicaCollection` reads a bounded entity collection from the client's normalized
 IndexedDB store, then updates it as the server resumes or snapshots the durable
 Postgres cursor:
 
 ```tsx
-const tasks = useSync<Task>(api.tasks.recent, { workspaceId });
+const tasks = useReplicaCollection<Task>(api.tasks.recent, { workspaceId });
 ```
 
-Use `useSyncSelector` when a component needs only derived state:
+Read completeness and truncation from the protocol instead of guessing from a
+row count:
 
 ```tsx
-const openCount = useSyncSelector<Task, number>(
+const state = useReplicaCollectionState<Task>(api.tasks.recent, { workspaceId });
+// state: { rows, source, completeness, freshness, truncated, computedRevision }
+```
+
+Virtualized grids retain query membership as ordered IDs and resolve all rows
+with one Replica subscription:
+
+```tsx
+const window = useRetainedLiveQuery<Task>(api.tasks.grid, args);
+const rows = useReplicaEntities<Task>("tasks", window.ids);
+```
+
+Use `useReplicaSelector` when a component needs only derived state:
+
+```tsx
+const openCount = useReplicaSelector<Task, number>(
   api.tasks.recent,
   { workspaceId },
   (tasks) => tasks.filter((task) => task.status === "open").length,
@@ -100,9 +115,9 @@ Both hooks return `undefined` before any local/server snapshot is available and
 accept `"skip"` as the args value. Selectors use `Object.is` by default and
 accept a custom equality function as the fourth argument.
 
-## Native Google auth
+## Native authentication
 
-Enable Google for the project and generate a configured auth module:
+Configure the providers needed by the project and generate an auth module:
 
 ```bash
 npx gonvex auth add google --origin http://localhost:5173
@@ -120,31 +135,34 @@ function Root() {
 }
 
 function Account() {
-  const { activeTenant, user } = useGonvexAuth();
-  return <>{user?.email} · {activeTenant?.name}<GoogleSignInButton /></>;
+  const {
+    account,
+    activeTenant,
+    signInWithPassword,
+    signInWithProvider,
+  } = useGonvexAuth();
+
+  return (
+    <>
+      {account?.email} · {activeTenant?.name}
+      <button onClick={() => void signInWithProvider("microsoft")}>Microsoft</button>
+      <button onClick={() => void signInWithPassword(email, password)}>Password</button>
+      <GoogleSignInButton />
+    </>
+  );
 }
 ```
 
-The provider performs Authorization Code + PKCE against the Gonvex runtime and
-attaches the resulting project-scoped session to the realtime client. Access tokens
-are short-lived and refresh tokens rotate across tabs. Multi-tenant memberships are
-verified by the runtime and switched with `setActiveTenant`. The provider does not
-load a Google browser SDK.
-
-## Convex Compatibility
-
-The package also exports Convex-style names for incremental migration:
-
-- `ConvexProvider`
-- `ConvexProviderWithAuth`
-- `ConvexReactClient`
-- `useConvex`
-- `useConvexAuth`
-- `useConvexConnectionState`
-- `usePaginatedQuery`
-- `useQueryResult`
-- `useSync`
-- `useSyncSelector`
+`signInWithProvider` accepts `google`, `microsoft`, or `apple` and performs
+Authorization Code + PKCE through Gonvex. `signInWithPassword` installs the
+native password session through the same path. Access tokens are short-lived,
+refresh tokens rotate across tabs, and the provider persists the active tenant.
+The host verifies tenant membership before switching with `setActiveTenant`.
+
+Use `useCurrentTenantProfile()` for subscribed domain, timezone, description,
+and public profile fields. Use `useControlQuery(reference, args)` for an
+authorized Control Plane live Query. Reducers refresh those subscriptions, so
+the application must not refetch them manually.
 
 ## Related Packages
 

package/dist/index.d.ts

@@ -1,40 +1,47 @@
 import { type ButtonHTMLAttributes, type ReactNode } from "react";
-import { ConvexReactClient, type ConnectionState, type FunctionReference, type GonvexClient } from "@gonvex/client";
+import { GonvexClient, type ConnectionState, type ControlInvitationAcceptance, type ControlInvitationListItem, type ControlToken, type FunctionReference, type LiveQueryResult, type ReplicaCollectionState, type ReplicaRow } from "@gonvex/client";
 import type { JsonValue } from "@gonvex/protocol";
 export { GonvexClientError, type ConnectionState } from "@gonvex/client";
-export declare const ConvexProvider: typeof GonvexProvider;
 export declare function GonvexProvider(props: {
     client: GonvexClient;
     children: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
-export { ConvexReactClient };
 export type AuthState = {
     isLoading: boolean;
     isAuthenticated: boolean;
+    /** Terminal runtime rejection after one forced token refresh attempt. */
+    authError?: Error | null;
     fetchAccessToken?: (args: {
         forceRefreshToken: boolean;
     }) => Promise<string | null>;
 };
-export type GonvexAuthUser = {
+export type GonvexAuthAccount = {
     id: string;
     email?: string;
     emailVerified: boolean;
     name?: string;
     picture?: string;
-    provider: "google" | string;
+    provider: "password" | "google" | "microsoft" | "apple" | string;
 };
 export type GonvexAuthTenant = {
     id: string;
     name: string;
     role: "owner" | "admin" | "member" | "viewer" | string;
     permissions?: Record<string, unknown>;
+    domain: string;
+    timezone: string;
+    description: string;
+    profile: JsonValue;
 };
+export type GonvexAuthProviderName = "google" | "microsoft" | "apple";
 export type GonvexAuthValue = AuthState & {
-    user: GonvexAuthUser | null;
+    account: GonvexAuthAccount | null;
     tenants: GonvexAuthTenant[];
     activeTenant: GonvexAuthTenant | null;
     error: string | null;
-    signIn: () => Promise<void>;
+    signIn: (provider?: GonvexAuthProviderName) => Promise<void>;
+    signInWithProvider: (provider: GonvexAuthProviderName) => Promise<void>;
+    signInWithPassword: (email: string, password: string) => Promise<void>;
     signOut: (options?: {
         allDevices?: boolean;
     }) => Promise<void>;
@@ -44,17 +51,20 @@ export type GonvexAuthValue = AuthState & {
     inviteMember: (tenantId: string, email: string, options?: {
         role?: GonvexAuthTenant["role"];
         permissions?: Record<string, unknown>;
-    }) => Promise<void>;
+        teamIds?: string[];
+        allowedAuthProviders?: string[];
+        payload?: JsonValue;
+    }) => Promise<ControlToken>;
+    acceptInvitation: (token: string) => Promise<ControlInvitationAcceptance>;
     revokeInvitation: (tenantId: string, email: string) => Promise<void>;
-    removeMember: (tenantId: string, userId: string) => Promise<void>;
 };
 export type GonvexAuthConfig = {
     runtimeUrl: string;
     projectId: string;
     callbackPath?: string;
 };
-export declare function ConvexProviderWithAuth(props: {
-    client: ConvexReactClient;
+export declare function GonvexProviderWithAuth(props: {
+    client: GonvexClient;
     children: ReactNode;
     useAuth: () => AuthState;
 }): import("react/jsx-runtime").JSX.Element;
@@ -63,6 +73,12 @@ export declare function GonvexAuthProvider(props: GonvexAuthConfig & {
     children: ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
 export declare function useGonvexAuth(): GonvexAuthValue;
+/** Subscribed profile for the active tenant, reconciled by GonvexAuthProvider. */
+export declare function useCurrentTenantProfile(): GonvexAuthTenant | null;
+/** Live tenant-admin invitation list; reducer changes reconcile automatically. */
+export declare function useInvitationList(): ControlInvitationListItem[] | undefined;
+/** Read the auth state installed by either auth provider. */
+export declare function useGonvexAuthState(): AuthState;
 export declare function GonvexGoogleAuthButton(props: ButtonHTMLAttributes<HTMLButtonElement> & {
     signOutLabel?: string;
 }): import("react/jsx-runtime").JSX.Element;
@@ -74,7 +90,7 @@ export declare function createGonvexAuth(config: GonvexAuthConfig): {
     GoogleSignInButton: typeof GonvexGoogleAuthButton;
     useGonvexAuth: typeof useGonvexAuth;
 };
-export type QueryStatus = "skip" | "loading" | "success" | "error" | "timeout" | "disconnected";
+export type QueryStatus = "skip" | "loading" | "success" | "error" | "timeout";
 export type UseQueryResultOptions = {
     /**
      * Soft "pending too long" signal for the live subscription. When no result
@@ -101,30 +117,31 @@ export type UseQueryResult<T> = {
     /** Re-request the query from the server (drops error/timeout state). */
     retry: () => void;
 };
-/**
- * Live query hook with an explicit status surface. Unlike `useQuery`, this
- * distinguishes loading / success / error / timeout / disconnected, keeps the
- * last good result while reconnecting, and exposes `retry()`.
- */
-export declare function useQueryResult<T = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip", options?: UseQueryResultOptions): UseQueryResult<T>;
-export declare function useQuery<T = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T | undefined;
-export declare function useSync<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T[] | undefined;
-export declare function useSyncSelector<T extends JsonValue = JsonValue, Selected = unknown>(ref: FunctionReference, args: JsonValue | "skip", selector: (rows: T[]) => Selected, isEqual?: (left: Selected, right: Selected) => boolean): Selected | undefined;
-export type UseMutationOptions = {
+/** One-shot Query hook with explicit loading/error/timeout status and retry. */
+export declare function useQueryResult<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip", options?: UseQueryResultOptions): UseQueryResult<T>;
+export declare function useLiveQuery<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T | undefined;
+/** Subscribe to a host-owned Control Plane Query on the existing Gonvex connection. */
+export declare function useControlQuery<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T | undefined;
+/** Read one normalized entity from the single Gonvex Local Replica. */
+export declare function useEntity<T extends ReplicaRow = ReplicaRow>(entity: string, id: string): T | undefined;
+/** Resolve an ordered entity batch with one Local Replica subscription. */
+export declare function useReplicaEntities<T extends ReplicaRow = ReplicaRow>(entity: string, ids: readonly string[]): Array<T | undefined>;
+/** Read a persisted Live Query window without opening another server subscription. */
+export declare function useRetainedLiveQuery<T extends ReplicaRow = ReplicaRow>(signatureOrReference: string | FunctionReference, args?: JsonValue): LiveQueryResult<T>;
+/** Structured Live Query state backed by normalized Local Replica entities. */
+export declare function useLiveQueryState<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue | "skip"): LiveQueryResult<T>;
+/** Execute a read-only Query once. Queries never subscribe or rerun. */
+export declare function useQuery<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T | undefined;
+export declare function useReplicaCollection<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T[] | undefined;
+/** Replica rows plus authoritative completeness, truncation, and freshness metadata. */
+export declare function useReplicaCollectionState<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue | "skip"): ReplicaCollectionState<T> | undefined;
+export declare function useReplicaSelector<T extends JsonValue = JsonValue, Selected = unknown>(ref: FunctionReference, args: JsonValue | "skip", selector: (rows: T[]) => Selected, isEqual?: (left: Selected, right: Selected) => boolean): Selected | undefined;
+export type UseReducerOptions = {
     /** Per-call timeout override forwarded to the client. `0` disables. */
     timeoutMs?: number;
 };
-export declare function useMutation(ref: FunctionReference, options?: UseMutationOptions): (args?: JsonValue) => Promise<JsonValue>;
-export declare function useAction(ref: FunctionReference, options?: UseMutationOptions): (args?: JsonValue) => Promise<JsonValue>;
-export declare function useConvex(): GonvexClient;
-export declare function useConvexAuth(): AuthState;
-export declare function useConvexConnectionState(): ConnectionState;
-export declare function usePaginatedQuery<T = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip", options?: {
-    initialNumItems?: number;
-}): {
-    results: T[];
-    status: string;
-    isLoading: boolean;
-    loadMore: (_numItems: number) => undefined;
-};
+export declare function useReducer(ref: FunctionReference, options?: UseReducerOptions): (args?: JsonValue) => Promise<JsonValue>;
+export declare function useAction(ref: FunctionReference, options?: UseReducerOptions): (args?: JsonValue) => Promise<JsonValue>;
+export declare function useGonvexConnectionState(): ConnectionState;
+export declare function useGonvexClient(): GonvexClient;
 export { useSignalValue } from "./useSignal.js";