@reatomized/convex 0.0.0-stage → 0.1.1

package/dist/browser/reatom/auth.js

@@ -0,0 +1,329 @@
+/**
+ * Token fetch, server confirmation and refresh, with the state machine in an
+ * atom. By default the client takes 3 steps:
+ *   1. Fetch a possibly cached token and send it to the server.
+ *   2. Once the server confirms it, fetch a fresh token without the cache.
+ *   3. Refetch before each fresh token expires.
+ *
+ * With `initialAuthTokenReuse` step 2 is skipped: the cached token stays and
+ * its refetch is scheduled from its remaining lifetime, estimated with the
+ * server's clock skew. When the server rejects a token, the socket stops, a
+ * fresh token is fetched and sent, and the socket restarts.
+ */
+import { atom, context, peek, wrap } from "@reatom/core";
+import { jwtDecode } from "../../vendor/jwt-decode/index.js";
+// setTimeout takes a 32-bit delay, about 24 days.
+const MAXIMUM_REFRESH_DELAY = 20 * 24 * 60 * 60 * 1000; // 20 days
+const MAX_TOKEN_CONFIRMATION_ATTEMPTS = 2;
+export function reatomAuth(sync, options, name) {
+    const { logger, refreshTokenLeewaySeconds, initialAuthTokenReuse } = options;
+    const state = atom({ state: "noAuth" }, `${name}.state`);
+    const runtime = atom(() => ({
+        root: context(),
+        configVersion: 0,
+        lastRefreshChange: false,
+        tokenConfirmationAttempts: 0,
+    }), `${name}._runtime`);
+    const logVerbose = (message) => logger.logVerbose(`${message} [v${peek(runtime).configVersion}]`);
+    const setAuthState = (next) => {
+        const authStateForLog = next.state === "waitingForServerConfirmationOfFreshToken"
+            ? {
+                hadAuth: next.hadAuth,
+                state: next.state,
+                token: `...${next.token.slice(-7)}`,
+            }
+            : { state: next.state };
+        logVerbose(`setting auth state to ${JSON.stringify(authStateForLog)}`);
+        if (next.state === "waitingForScheduledRefetch" ||
+            next.state === "notRefetching" ||
+            next.state === "noAuth") {
+            peek(runtime).tokenConfirmationAttempts = 0;
+        }
+        const current = state();
+        if (current.state === "waitingForScheduledRefetch") {
+            clearTimeout(current.refetchTokenTimeoutId);
+        }
+        state.set(next);
+    };
+    const notifyRefreshChange = (isRefreshing) => {
+        const current = state();
+        const rt = peek(runtime);
+        if (current.state !== "noAuth" &&
+            current.state !== "initialRefetch" &&
+            current.config.onRefreshChange &&
+            rt.lastRefreshChange !== isRefreshing) {
+            rt.lastRefreshChange = isRefreshing;
+            current.config.onRefreshChange(isRefreshing);
+        }
+    };
+    // The only way into `noAuth`; pairs any pending `onRefreshChange(true)`.
+    const resetAuthState = () => {
+        notifyRefreshChange(false);
+        setAuthState({ state: "noAuth" });
+    };
+    const setAndReportAuthFailed = (onAuthChange) => {
+        onAuthChange(false);
+        resetAuthState();
+    };
+    /** `isFromOutdatedConfig` when `setConfig` or `stop` ran during the fetch. */
+    const fetchTokenAndGuardAgainstRace = async (fetchToken, fetchArgs) => {
+        const rt = peek(runtime);
+        const originalConfigVersion = ++rt.configVersion;
+        logVerbose(`fetching token with config version ${originalConfigVersion}`);
+        const token = await wrap(fetchToken(fetchArgs));
+        if (rt.configVersion !== originalConfigVersion) {
+            logVerbose(`stale config version, expected ${originalConfigVersion}, got ${rt.configVersion}`);
+            return { isFromOutdatedConfig: true };
+        }
+        return { isFromOutdatedConfig: false, value: token };
+    };
+    const decodeToken = (token) => {
+        try {
+            return jwtDecode(token);
+        }
+        catch (e) {
+            logVerbose(`Error decoding token: ${e instanceof Error ? e.message : "Unknown error"}`);
+            return null;
+        }
+    };
+    const scheduleTokenRefetch = (token, clientClockSkewMs) => {
+        const current = state();
+        if (current.state === "noAuth")
+            return;
+        const decodedToken = decodeToken(token);
+        if (!decodedToken) {
+            // The server only confirms JWTs, so this should not happen.
+            logger.error("Auth token is not a valid JWT, cannot refetch the token");
+            return;
+        }
+        // iat: issued at, exp: expires at, both UTC seconds.
+        const { iat, exp } = decodedToken;
+        if (!iat || !exp) {
+            logger.error("Auth token does not have required fields, cannot refetch the token");
+            return;
+        }
+        const fullLifetimeSeconds = exp - iat;
+        if (fullLifetimeSeconds <= 2) {
+            logger.error("Auth token does not live long enough, cannot refetch the token");
+            return;
+        }
+        let tokenValiditySeconds;
+        if (clientClockSkewMs !== undefined) {
+            // A cached token's remaining lifetime, on the server's clock. The server
+            // computes clientClockSkew = clientTs - serverReceiveTs. Connect latency
+            // makes the client look further behind, so the refetch runs early.
+            const estimatedServerNowSeconds = (Date.now() - clientClockSkewMs) / 1000;
+            tokenValiditySeconds = Math.max(0, exp - estimatedServerNowSeconds);
+        }
+        else {
+            // A fresh token lives `exp - iat` from now.
+            tokenValiditySeconds = fullLifetimeSeconds;
+        }
+        let delay = Math.min(MAXIMUM_REFRESH_DELAY, (tokenValiditySeconds - refreshTokenLeewaySeconds) * 1000);
+        if (delay <= 0) {
+            logger.warn(`Refetching auth token immediately, configured leeway ${refreshTokenLeewaySeconds}s is larger than the token's lifetime ${tokenValiditySeconds}s`);
+            delay = 0;
+        }
+        const refetchTokenTimeoutId = setTimeout(wrap(() => {
+            logVerbose("running scheduled token refetch");
+            void refetchToken();
+        }, peek(runtime).root), delay);
+        setAuthState({
+            state: "waitingForScheduledRefetch",
+            refetchTokenTimeoutId,
+            config: current.config,
+        });
+        logVerbose(`scheduled preemptive auth token refetching in ${delay}ms`);
+    };
+    // Force-fetches a token and schedules the next refetch once the server
+    // confirms it, so an active client never has to reauthenticate.
+    const refetchToken = async () => {
+        const current = state();
+        if (current.state === "noAuth")
+            return;
+        logVerbose("refetching auth token");
+        const token = await wrap(fetchTokenAndGuardAgainstRace(current.config.fetchToken, {
+            forceRefreshToken: true,
+        }));
+        if (token.isFromOutdatedConfig)
+            return;
+        if (token.value) {
+            if (sync.token() !== token.value) {
+                setAuthState({
+                    state: "waitingForServerConfirmationOfFreshToken",
+                    hadAuth: sync.hasAuth(),
+                    token: token.value,
+                    config: current.config,
+                });
+                sync.authenticate(token.value);
+            }
+            else {
+                setAuthState({ state: "notRefetching", config: current.config });
+            }
+        }
+        else {
+            logVerbose("refetching token failed");
+            if (sync.hasAuth()) {
+                sync.clearAuth();
+            }
+            setAndReportAuthFailed(current.config.onAuthChange);
+        }
+        // In case a scheduled refetch ran during a reauthentication.
+        logVerbose("restarting WS after auth token fetch (if currently stopped)");
+        sync.tryRestartSocket();
+    };
+    // Like `refetchToken`, but with the socket stopped so requests don't retry
+    // with the rejected token.
+    const tryToReauthenticate = async (serverMessage) => {
+        logVerbose(`attempting to reauthenticate: ${serverMessage.error}`);
+        const current = state();
+        const rt = peek(runtime);
+        if (
+        // No way to fetch another token.
+        current.state === "noAuth" ||
+            // A fresh token failed too often; give up instead of retrying forever.
+            (current.state === "waitingForServerConfirmationOfFreshToken" &&
+                rt.tokenConfirmationAttempts >= MAX_TOKEN_CONFIRMATION_ATTEMPTS)) {
+            logger.error(`Failed to authenticate: "${serverMessage.error}", check your server auth config`);
+            if (sync.hasAuth()) {
+                sync.dropAuth();
+            }
+            if (current.state !== "noAuth") {
+                setAndReportAuthFailed(current.config.onAuthChange);
+            }
+            return;
+        }
+        if (current.state === "waitingForServerConfirmationOfFreshToken") {
+            rt.tokenConfirmationAttempts++;
+            logVerbose(`retrying reauthentication, ${MAX_TOKEN_CONFIRMATION_ATTEMPTS - rt.tokenConfirmationAttempts} attempts remaining`);
+        }
+        notifyRefreshChange(true);
+        await wrap(sync.stopSocket());
+        const afterStop = state();
+        // `setConfig` or `stop` ran during the await.
+        if (afterStop.state === "noAuth")
+            return;
+        const token = await wrap(fetchTokenAndGuardAgainstRace(afterStop.config.fetchToken, {
+            forceRefreshToken: true,
+        }));
+        if (token.isFromOutdatedConfig)
+            return;
+        const latest = state();
+        // Another auth error gave up meanwhile.
+        if (latest.state === "noAuth")
+            return;
+        if (token.value && sync.token() !== token.value) {
+            sync.authenticate(token.value);
+            setAuthState({
+                state: "waitingForServerConfirmationOfFreshToken",
+                config: latest.config,
+                token: token.value,
+                hadAuth: latest.state === "notRefetching" ||
+                    latest.state === "waitingForScheduledRefetch",
+            });
+        }
+        else {
+            logVerbose("reauthentication failed, could not fetch a new token");
+            if (sync.hasAuth()) {
+                sync.dropAuth();
+            }
+            setAndReportAuthFailed(latest.config.onAuthChange);
+        }
+        sync.tryRestartSocket();
+    };
+    return {
+        /** The auth state machine. */
+        state,
+        async setConfig(fetchToken, onChange, onRefreshChange) {
+            resetAuthState();
+            logVerbose("pausing WS for auth token fetch");
+            sync.pauseSocket();
+            const token = await wrap(fetchTokenAndGuardAgainstRace(fetchToken, {
+                forceRefreshToken: false,
+            }));
+            if (token.isFromOutdatedConfig)
+                return;
+            const config = {
+                fetchToken,
+                onAuthChange: onChange,
+                onRefreshChange,
+            };
+            if (token.value) {
+                setAuthState({
+                    state: "waitingForServerConfirmationOfCachedToken",
+                    config,
+                    hasRetried: false,
+                });
+                sync.authenticate(token.value);
+            }
+            else {
+                setAuthState({ state: "initialRefetch", config });
+                // Try again with `forceRefreshToken: true`.
+                await wrap(refetchToken());
+            }
+            logVerbose("resuming WS after auth token fetch");
+            sync.resumeSocket();
+        },
+        onTransition(serverMessage) {
+            // Stale: the client has moved on to a newer identity.
+            if (!sync.isCurrentOrNewerAuthVersion(serverMessage.endVersion.identity)) {
+                return;
+            }
+            // Not an answer to `Authenticate`.
+            if (serverMessage.endVersion.identity <= serverMessage.startVersion.identity) {
+                return;
+            }
+            const current = state();
+            logVerbose(`auth state is ${current.state} when handling transition`);
+            // The server accepted the token: client and server identities agree.
+            sync.markAuthCompletion();
+            if (current.state === "waitingForServerConfirmationOfCachedToken") {
+                logVerbose("server confirmed auth token is valid");
+                const cachedToken = sync.token();
+                if (initialAuthTokenReuse && cachedToken) {
+                    scheduleTokenRefetch(cachedToken, serverMessage.clientClockSkew);
+                }
+                else {
+                    void refetchToken();
+                }
+                current.config.onAuthChange(true);
+                return;
+            }
+            if (current.state === "waitingForServerConfirmationOfFreshToken") {
+                logVerbose("server confirmed new auth token is valid");
+                notifyRefreshChange(false);
+                scheduleTokenRefetch(current.token);
+                peek(runtime).tokenConfirmationAttempts = 0;
+                // Read after scheduling, as convex@1.48.0 does: once the refetch is
+                // scheduled the state has no `hadAuth`, so every confirmed fresh
+                // token reports `true`.
+                const after = state();
+                if (!("hadAuth" in after && after.hadAuth)) {
+                    current.config.onAuthChange(true);
+                }
+            }
+        },
+        onAuthError(serverMessage) {
+            const current = state().state;
+            // An expired-token error while a new token is already on its way.
+            if (serverMessage.authUpdateAttempted === false &&
+                (current === "waitingForServerConfirmationOfFreshToken" ||
+                    current === "waitingForServerConfirmationOfCachedToken")) {
+                logVerbose("ignoring non-auth token expired error");
+                return;
+            }
+            // The error reports the version the server stayed at, hence `+ 1`.
+            if (!sync.isCurrentOrNewerAuthVersion(serverMessage.baseVersion + 1)) {
+                logVerbose("ignoring auth error for previous auth attempt");
+                return;
+            }
+            void tryToReauthenticate(serverMessage);
+        },
+        stop() {
+            resetAuthState();
+            // Drops a token fetch in progress.
+            peek(runtime).configVersion++;
+            logVerbose(`config version bumped to ${peek(runtime).configVersion}`);
+        },
+    };
+}

package/dist/browser/reatom/client.d.ts

@@ -0,0 +1,348 @@
+/**
+ * A Convex sync client whose state lives in Reatom atoms.
+ *
+ * The query set is the set of connected query atoms: reading a query's
+ * `result` in a subscribed graph subscribes it on the server, and losing the
+ * last reader unsubscribes it. Query set changes made in one microtask go out
+ * as one `ModifyQuerySet`. A server transition updates only the queries it
+ * names; optimistic updates are replayed only while some are pending.
+ *
+ * State is per Reatom context: call the client's methods inside a frame of
+ * the context that owns it.
+ */
+import { type Action, type AtomLike, type Computed } from "@reatom/core";
+import { FunctionArgs, FunctionReference, FunctionReference_future, FunctionReturnType } from "convex/server";
+import { Value } from "convex/values";
+import { Logger } from "../logging.js";
+import { FunctionResult } from "../sync/function_result.js";
+import { OptimisticUpdate } from "convex/browser";
+import { QueryJournal, RequestId, TS } from "../sync/protocol.js";
+import { QueryToken } from "../sync/udf_path_utils.js";
+import { AuthTokenFetcher } from "./auth.js";
+import { ReatomPaginatedQuery } from "./paginated.js";
+import { SocketState } from "./socket.js";
+/**
+ * Options for {@link BaseConvexClient}.
+ *
+ * @public
+ */
+export interface BaseConvexClientOptions {
+    /**
+     * Whether to prompt the user if they have unsaved changes pending
+     * when navigating away or closing a web page.
+     *
+     * This is only possible when the `window` object exists, i.e. in a browser.
+     *
+     * The default value is `true` in browsers.
+     */
+    unsavedChangesWarning?: boolean;
+    /**
+     * Specifies an alternate
+     * [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
+     * constructor to use for client communication with the Convex cloud.
+     * The default behavior is to use `WebSocket` from the global environment.
+     */
+    webSocketConstructor?: typeof WebSocket;
+    /**
+     * Adds additional logging for debugging purposes.
+     *
+     * The default value is `false`.
+     */
+    verbose?: boolean;
+    /**
+     * A logger, `true`, or `false`. If not provided or `true`, logs to the console.
+     * If `false`, logs are not printed anywhere.
+     *
+     * You can construct your own logger to customize logging to log elsewhere.
+     * A logger is an object with 4 methods: log(), warn(), error(), and logVerbose().
+     * These methods can receive multiple arguments of any types, like console.log().
+     */
+    logger?: Logger | boolean;
+    /**
+     * Sends additional metrics to Convex for debugging purposes.
+     *
+     * The default value is `false`.
+     */
+    reportDebugInfoToConvex?: boolean;
+    /**
+     * This API is experimental: it may change or disappear.
+     *
+     * A function to call on receiving abnormal WebSocket close messages from the
+     * connected Convex deployment. The content of these messages is not stable,
+     * it is an implementation detail that may change.
+     *
+     * Consider this API an observability stopgap until higher level codes with
+     * recommendations on what to do are available, which could be a more stable
+     * interface instead of `string`.
+     *
+     * Check `connectionState` for more quantitative metrics about connection status.
+     */
+    onServerDisconnectError?: (message: string) => void;
+    /**
+     * Skip validating that the Convex deployment URL looks like
+     * `https://happy-animal-123.convex.cloud` or localhost.
+     *
+     * This can be useful if running a self-hosted Convex backend that uses a different
+     * URL.
+     *
+     * The default value is `false`
+     */
+    skipConvexDeploymentUrlCheck?: boolean;
+    /**
+     * If using auth, the number of seconds before a token expires that we should refresh it.
+     *
+     * The default value is `10`.
+     */
+    authRefreshTokenLeewaySeconds?: number;
+    /**
+     * This API is experimental: it may change or disappear.
+     *
+     * Whether query, mutation, and action requests should be held back
+     * until the first auth token can be sent.
+     *
+     * Opting into this behavior works well for pages that should
+     * only be viewed by authenticated clients.
+     *
+     * Defaults to false, not waiting for an auth token.
+     */
+    expectAuth?: boolean;
+    /**
+     * This API is experimental: it may change or disappear.
+     *
+     * When true, the client reuses the initial cached auth token instead
+     * of immediately fetching a fresh one. This avoids a second
+     * Authenticate message that causes the server to re-execute all
+     * authenticated queries.
+     *
+     * The cached token's remaining lifetime is estimated using the
+     * server's clock skew measurement, and a refresh is scheduled
+     * before it expires.
+     *
+     * Defaults to false, preserving the original behavior of immediately
+     * fetching a fresh token after the cached token is confirmed.
+     */
+    initialAuthTokenReuse?: boolean;
+}
+/**
+ * State describing the client's connection with the Convex backend.
+ *
+ * @public
+ */
+export type ConnectionState = {
+    hasInflightRequests: boolean;
+    isWebSocketConnected: boolean;
+    timeOfOldestInflightRequest: Date | null;
+    /**
+     * True if the client has ever opened a WebSocket to the "ready" state.
+     */
+    hasEverConnected: boolean;
+    /**
+     * The number of times this client has connected to the Convex backend.
+     *
+     * A number of things can cause the client to reconnect -- server errors,
+     * bad internet, auth expiring. But this number being high is an indication
+     * that the client is having trouble keeping a stable connection.
+     */
+    connectionCount: number;
+    /**
+     * The number of times this client has tried (and failed) to connect to the Convex backend.
+     */
+    connectionRetries: number;
+    /**
+     * The number of mutations currently in flight.
+     */
+    inflightMutations: number;
+    /**
+     * The number of actions currently in flight.
+     */
+    inflightActions: number;
+};
+/**
+ * Options for {@link BaseConvexClient.subscribe}.
+ *
+ * @public
+ */
+export interface SubscribeOptions {
+    /**
+     * An (optional) journal produced from a previous execution of this query
+     * function.
+     *
+     * If there is an existing subscription to a query function with the same
+     * name and arguments, this journal will have no effect.
+     */
+    journal?: QueryJournal;
+}
+/**
+ * Options for {@link BaseConvexClient.mutation}.
+ *
+ * @public
+ */
+export interface MutationOptions {
+    /**
+     * An optimistic update to apply along with this mutation.
+     *
+     * An optimistic update locally updates queries while a mutation is pending.
+     * Once the mutation completes, the update will be rolled back.
+     */
+    optimisticUpdate?: OptimisticUpdate<any> | undefined;
+}
+/**
+ * Type describing updates to a query within a `Transition`.
+ *
+ * @public
+ */
+export type QueryModification = {
+    kind: "Updated";
+    result: FunctionResult | undefined;
+} | {
+    kind: "Removed";
+};
+/**
+ * Object describing a transition passed into the `onTransition` handler.
+ *
+ * These can be from receiving a transition from the server, or from applying an
+ * optimistic update locally.
+ *
+ * @public
+ */
+export type Transition = {
+    queries: Array<{
+        token: QueryToken;
+        modification: QueryModification;
+    }>;
+    reflectedMutations: Array<{
+        requestId: RequestId;
+        result: FunctionResult;
+    }>;
+    timestamp: TS;
+};
+/**
+ * The status of a {@link ReatomQuery}.
+ *
+ * @public
+ */
+export type QueryStatus = "loading" | "success" | "error";
+/**
+ * One query function and arguments on a {@link ReatomConvexClient}.
+ *
+ * Reading any of its atoms inside a subscribed Reatom graph subscribes the
+ * query on the server; it is unsubscribed once nothing reads it. Equal
+ * queries share one entry and one server subscription.
+ *
+ * @public
+ */
+export interface ReatomQuery<T = Value> {
+    readonly token: QueryToken;
+    /** The canonical function path. */
+    readonly udfPath: string;
+    readonly args: Record<string, Value>;
+    /**
+     * The function result with optimistic updates applied, `undefined` while
+     * loading.
+     */
+    readonly result: AtomLike<FunctionResult | undefined, []>;
+    /** The value, `undefined` while loading or after an error. */
+    readonly data: Computed<T | undefined>;
+    /** The error the query failed with, a `ConvexError` when it carries data. */
+    readonly error: Computed<Error | undefined>;
+    readonly status: Computed<QueryStatus>;
+}
+/**
+ * Options for {@link ReatomConvexClient.query}.
+ *
+ * @public
+ */
+export type ReatomQueryOptions = SubscribeOptions;
+type QueryRef = FunctionReference<"query"> | FunctionReference_future<"query"> | string;
+type MutationRef = FunctionReference<"mutation"> | FunctionReference_future<"mutation"> | string;
+type ActionRef = FunctionReference<"action"> | FunctionReference_future<"action"> | string;
+type AnyRef = FunctionReference<any, any> | FunctionReference_future<any, any>;
+type ReturnOf<Ref> = Ref extends AnyRef ? FunctionReturnType<Ref> : any;
+type PaginatedItemOf<Ref> = ReturnOf<Ref> extends {
+    page: Array<infer Item>;
+} ? Item : any;
+type ArgsOf<Ref> = Ref extends AnyRef ? FunctionArgs<Ref> : Record<string, Value>;
+/**
+ * Create a Convex client whose state lives in Reatom atoms.
+ *
+ * The client connects on first use in a context: a query read, a request,
+ * `setAuth` or a `connectionState` subscriber. Call its methods inside a
+ * Reatom frame; each context gets its own connection.
+ *
+ * ```ts
+ * const convex = reatomConvexClient(import.meta.env.VITE_CONVEX_URL);
+ * const notes = computed(() => convex.query(api.notes.list, {}).data());
+ * ```
+ *
+ * @param address - The url of your Convex deployment, e.g.
+ * `https://small-mouse-123.convex.cloud`.
+ * @param options - See {@link BaseConvexClientOptions}.
+ * @param name - A prefix for the client's atom names.
+ *
+ * @public
+ */
+export declare function reatomConvexClient(address: string, options?: BaseConvexClientOptions, name?: string): ReatomConvexClient;
+/**
+ * A Convex client whose state lives in Reatom atoms, created with
+ * {@link reatomConvexClient}. Use it inside a Reatom frame.
+ *
+ * @public
+ */
+export interface ReatomConvexClient {
+    /** The prefix of the client's atom names. */
+    readonly name: string;
+    /** The deployment address. */
+    readonly url: string;
+    /** The connection with the backend; subscribing connects. */
+    readonly connectionState: Computed<ConnectionState>;
+    /**
+     * Whether the server accepted the current token: `null` while a token waits
+     * for the server, `false` without auth.
+     */
+    readonly isAuthenticated: AtomLike<boolean | null, []>;
+    /** The server rejected a confirmed token and a replacement is being fetched. */
+    readonly isRefreshingAuth: AtomLike<boolean, []>;
+    /** The current user JWT and its decoded claims. */
+    readonly authClaims: Computed<{
+        token: string;
+        decoded: Record<string, any>;
+    } | undefined>;
+    /** The socket state machine. */
+    readonly socketState: AtomLike<SocketState, []>;
+    /**
+     * A query of this client. Equal queries return the same entry.
+     *
+     * @param query - A query reference, or a function path.
+     * @param args - The query arguments, `{}` by default.
+     */
+    query<Query extends QueryRef>(query: Query, args?: ArgsOf<Query>, options?: ReatomQueryOptions): ReatomQuery<ReturnOf<Query>>;
+    /**
+     * A paginated query of this client. Equal queries with the same `id` share
+     * their pages; `id` is `-1` by default.
+     *
+     * @param query - A paginated query reference, or a function path.
+     * @param args - The query arguments without `paginationOpts`.
+     */
+    paginatedQuery<Query extends QueryRef>(query: Query, args: Omit<ArgsOf<Query>, "paginationOpts">, options: {
+        initialNumItems: number;
+        id?: number;
+    }): ReatomPaginatedQuery<PaginatedItemOf<Query>>;
+    /** Run a mutation; `optimisticUpdate` edits local results until it is reflected. */
+    mutation<Mutation extends MutationRef>(mutation: Mutation, args?: ArgsOf<Mutation>, options?: MutationOptions): Promise<ReturnOf<Mutation>>;
+    action<Action extends ActionRef>(action: Action, args?: ArgsOf<Action>): Promise<ReturnOf<Action>>;
+    /**
+     * Fetch a token, send it, and refetch it before it expires or when the
+     * server rejects it. `fetchToken` should return `null` when no token can be
+     * had, for example after the user's rights were revoked.
+     */
+    readonly setAuth: Action<[
+        fetchToken: AuthTokenFetcher,
+        onChange?: ((isAuthenticated: boolean) => void) | undefined,
+        onRefreshChange?: ((isRefreshing: boolean) => void) | undefined
+    ], void>;
+    /** Stop the auth flow and continue without an identity. */
+    readonly clearAuth: Action<[], void>;
+    /** Close the connection for good. */
+    readonly close: Action<[], Promise<void>>;
+}
+export {};