@gonvex/react 0.5.2-staging.2 → 0.5.2-staging.20

package/README.md

@@ -165,13 +165,18 @@ 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`.
 
-Developer mode is provider-owned. Its activation and rotating reconnect
-credentials stay in memory and are never returned by these methods, persisted,
-or added to a URL. The provider preserves and refreshes the normal account
-session underneath the grant, then restores it on exit, expiry, reload, or an
-authentication rejection. Developer mode switches the existing Gonvex
-connection; it does not navigate to a tenant subdomain or require a browser
-handoff.
+Developer mode is provider-owned. Its credentials are never returned by these
+methods, written to localStorage, or added to a URL. The runtime rotates a
+single-use reconnect credential on every connection; the provider keeps the
+newest one with the grant in `sessionStorage`, keyed by project and account,
+so reloading the same tab resumes developer mode until the grant expires.
+Other tabs and new browser sessions never see it. The provider preserves and
+refreshes the normal account session underneath the grant, then restores it
+and forgets the grant on exit, expiry, sign-out, an account switch, or an
+authentication rejection. A stored grant the runtime no longer accepts after a
+reload falls back to the account session without an error. Developer mode
+switches the existing Gonvex connection; it does not navigate to a tenant
+subdomain or require a browser handoff.
 
 Use `useCurrentTenantProfile()` for subscribed domain, timezone, description,
 and public profile fields. Use `useControlQuery(reference, args)` for an
@@ -225,3 +230,5 @@ remain Firebase's responsibility when this adapter is configured.
 ## Documentation
 
 Full docs live at https://desarso.github.io/gonvex/
+
+[Use public tenant clients with the regular provider and query, Action, and Reducer hooks](../../docs/public-functions.md).

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { type ButtonHTMLAttributes, type ReactNode } from "react";
-import { GonvexClient, type ConnectionState, type ControlInvitationAcceptance, type ControlInvitationListItem, type ControlToken, type FunctionReference, type GonvexExternalAuthAdapter, type LiveQueryResult, type ReplicaCollectionSubscriptionState, type ReplicaRow } from "@gonvex/client";
+import { GonvexClient, type ConnectionState, type EntityIntentStatus, type LocalExecutionFallbackEvent, type OutboxIntent, type ResetLocalReplicaOptions, type ResetLocalReplicaResult, type ControlInvitationAcceptance, type ControlInvitationListItem, type ControlToken, type FunctionReference, type GonvexExternalAuthAdapter, type LiveQueryResult, type ReplicaCollectionSubscriptionState, type ReplicaRow } from "@gonvex/client";
 import type { JsonValue } from "@gonvex/protocol";
-export { GonvexClientError, type ConnectionState } from "@gonvex/client";
+export { GonvexClientError, type ConnectionState, type EntityIntentStatus, type LocalExecutionFallbackEvent, type OutboxIntent, type ResetLocalReplicaOptions, type ResetLocalReplicaResult } from "@gonvex/client";
 export { createFirebaseAuthAdapter, type GonvexExternalAuthAdapter, type GonvexExternalIdentityHint, type GonvexFirebaseAuthAdapterOptions } from "@gonvex/client";
 export declare function GonvexProvider(props: {
     client: GonvexClient;
@@ -78,14 +78,27 @@ export type GonvexAuthConfig = {
     runtimeUrl: string;
     projectId: string;
     callbackPath?: string;
-    /** Tenant routing hint used for the first authentication exchange. */
-    initialTenantId?: string;
+    /**
+     * Tenant routing scope for the first authentication exchange. Pass `null`
+     * to explicitly select account/landlord scope; omit it to restore the
+     * persisted active tenant when possible.
+     */
+    initialTenantId?: string | null;
+    /** Visible content while the external identity provider initializes. */
+    loadingFallback?: ReactNode;
     /** Trusted identity adapter such as createFirebaseAuthAdapter(). */
     externalAuth?: GonvexExternalAuthAdapter;
     /** Secure browser-to-browser handoff for apps routed across sibling subdomains. */
     crossOriginHandoff?: {
         allowedOriginSuffix: string;
         receiverPath?: string;
+        /**
+         * Load the receiver with POST when a service worker may serve a stale
+         * cached application shell for GET navigations. The POST body is empty;
+         * the canonical session still travels only through the origin-checked
+         * postMessage exchange.
+         */
+        receiverMethod?: "get" | "post";
         timeoutMs?: number;
     };
 };
@@ -161,6 +174,13 @@ export declare function useQuery<T extends JsonValue = JsonValue>(ref: FunctionR
 export declare function useReplicaCollection<T extends JsonValue = JsonValue>(ref: FunctionReference, args?: JsonValue | "skip"): T[] | undefined;
 /** Replica rows plus exact per-collection authority, completeness, truncation, and freshness. */
 export declare function useReplicaCollectionState<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args?: JsonValue | "skip"): ReplicaCollectionSubscriptionState<T> | undefined;
+/** Subscribe to a bounded, dynamic set of slices of the same Replica Collection.
+ * Results borrow normalized SDK snapshots; there is no second entity cache.
+ * Deferred watches only start when React commits the subscription.
+ */
+export declare function useReplicaCollectionStates<T extends ReplicaRow = ReplicaRow>(ref: FunctionReference, args: readonly JsonValue[]): ReadonlyArray<ReplicaCollectionSubscriptionState<T> | undefined>;
+/** Select rows and authority metadata without rerendering for unused watermarks. */
+export declare function useReplicaCollectionStateSelector<T extends ReplicaRow, Selected>(ref: FunctionReference, args: JsonValue | "skip", selector: (state: ReplicaCollectionSubscriptionState<T>) => Selected, isEqual?: (left: Selected, right: Selected) => boolean): Selected | 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. */
@@ -169,5 +189,35 @@ export type UseReducerOptions = {
 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;
+/**
+ * Every durable reducer intent of the signed-in identity, oldest first:
+ * pending and inflight intents, intents parked as `failed` after exhausting
+ * their retry budget, and server-`rejected` intents awaiting dismissal.
+ * Use `client.retryIntent(id)` / `client.discardIntent(id)` to act on them.
+ */
+export declare function useOutboxIntents(): readonly OutboxIntent[];
+/**
+ * Delivery status of one row: `failed` or `rejected` when an intent that
+ * touched it needs attention, `syncing` while one is still queued, and
+ * undefined once everything touching it has been acknowledged.
+ */
+export declare function useEntityIntentStatus(entity: string, id: string | null | undefined): EntityIntentStatus | undefined;
+/**
+ * Observe locally executing Reducers that fell back to a queued-only intent
+ * (no local result), for logging. The latest listener is always called; it
+ * does not need to be memoized.
+ */
+export declare function useLocalExecutionFallback(listener: (event: LocalExecutionFallbackEvent) => void): void;
+export type LocalReplicaReset = {
+    /** Rejects with `code: "disconnected"` while offline; nothing is cleared then. */
+    reset: (options?: ResetLocalReplicaOptions) => Promise<ResetLocalReplicaResult>;
+    isResetting: boolean;
+    error: Error | undefined;
+};
+/**
+ * Drive a "Clear cache" control: discards the persisted Local Replica and
+ * rehydrates it from the server, keeping queued intents unless asked.
+ */
+export declare function useResetLocalReplica(): LocalReplicaReset;
 export declare function useGonvexClient(): GonvexClient;
 export { useSignalValue } from "./useSignal.js";