better-supabase 0.5.0 → 0.6.0

package/dist/{index-DgILJRXj.d.ts → index-Bepi-Hgg.d.ts}

@@ -1,22 +1,8 @@
-import { P as TableKey, R as UniqueWhere, _ as Insert, n as AnyFunctions, r as AnyModels, w as PrimaryKeyValue, z as Update } from "./types-Dnf_wRDz.js";
-import { x as DbException } from "./executor-BunPOO-k.js";
-import { C as FindExt, Ct as WhereInput, M as UpsertArgs, N as WriteArgs, S as DeleteExt, T as OffsetPageArgs, X as InferResult, Z as QuerySpec, _ as CursorPage, it as AggregateResult, j as UpdateArgs, k as Returned, l as CacheAdapter, lt as FindFirstArgs, rt as AggregateArgs, st as CountArgs, t as BetterSupabase, ut as FindManyArgs, v as CursorPageArgs, vt as Payload, w as OffsetPage, x as DeleteArgs, y as Db, yt as ReadArgs } from "./define-Bp_BZa5h.js";
-import { DataTag, InfiniteData, QueryClient, QueryMeta, SkipToken } from "@tanstack/query-core";
-//#region src/query/invalidate.d.ts
-/**
- * Carried by every better-supabase query: the tables whose changes make it
- * stale, on top of the app's `Register['queryMeta']`, so the options stay
- * assignable to `useQuery` when the app narrows its query meta.
- */
-type BetterQueryMeta = QueryMeta & {
-  readonly bsTables: readonly string[];
-};
-/**
- * Invalidates every query that read one of `tables`: better-supabase queries
- * by their `meta.bsTables`, and other `['bs', table, ...]` keys by prefix.
- */
-declare function invalidateTables(client: QueryClient, tables: readonly string[]): Promise<void>;
-//#endregion
+import { n as DbException } from "./escape-like-ImTK0ps_.js";
+import { E as PrimaryKeyValue, H as Update, L as TableKey, V as UniqueWhere, a as AnyModels, i as AnyFunctions, x as Insert } from "./types-6BdhkmZe.js";
+import { C as DeleteExt, D as OffsetPage, F as UpdateArgs, I as UpsertArgs, Mt as Payload, N as Returned, Nt as ReadArgs, O as OffsetPageArgs, R as WriteArgs, S as DeleteArgs, St as FindOnlyArgs, b as Db, bt as FindFirstArgs, it as QuerySpec, k as OffsetRangeArgs, pt as AggregateResult, rt as InferResult, t as BetterSupabase, u as CacheAdapter, ut as AggregateArgs, v as CursorPage, vt as CountArgs, w as FindExt, xt as FindManyArgs, y as CursorPageArgs, zt as WhereInput } from "./define-CJJkkr1-.js";
+import { t as BetterQueryMeta } from "./invalidate-BBqhpxyB.js";
+import { DataTag, InfiniteData, QueryClient, SkipToken } from "@tanstack/query-core";
 //#region src/query/queries.d.ts
 type QueryKeyOf<T> = DataTag<readonly unknown[], T, DbException>;
 type QueryFnOf<T> = ((context: {
@@ -38,9 +24,19 @@ interface InfiniteOptionsOf<P, Param> {
   }) => Promise<P>;
   readonly initialPageParam: Param;
   readonly getNextPageParam: (last: P) => Param | undefined;
+  /** Set on numbered pages, so a window trimmed by `maxPages` can load backwards. */
+  readonly getPreviousPageParam?: (first: P) => Param | undefined;
+  readonly maxPages?: number;
   readonly meta: BetterQueryMeta;
   readonly staleTime?: number;
 }
+interface InfiniteExtras {
+  /**
+   * Pages kept in the cache; older ones are dropped as new ones load. Keeps
+   * long feeds from holding every page in memory and refetching them all.
+   */
+  readonly maxPages?: number;
+}
 /** Options for `useMutation`. Invalidates every query that read a changed table. */
 interface MutationOptionsOf<V, R> {
   readonly mutationKey: readonly unknown[];
@@ -54,6 +50,7 @@ interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
   readonly key: readonly ["bs", T];
   findMany<const A extends FindManyArgs<M, T> & FindExt<E, M, T>>(args?: A | SkipToken): QueryOptionsOf<Payload<M, T, A>[]>;
   findFirst<const A extends FindFirstArgs<M, T> & FindExt<E, M, T>>(args?: A | SkipToken): QueryOptionsOf<Payload<M, T, A> | null>;
+  findOnly<const A extends FindOnlyArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<Payload<M, T, A> | null>;
   findUnique<const A extends ReadArgs<M, T> & {
     readonly where: UniqueWhere<M, T>;
   } & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<Payload<M, T, A> | null>;
@@ -63,11 +60,11 @@ interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
   exists(args?: ({
     readonly where?: WhereInput<M, T>;
   } & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<boolean>;
-  paginate<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<OffsetPage<Payload<M, T, A>>>;
+  paginate<const A extends (OffsetPageArgs<M, T> | OffsetRangeArgs<M, T>) & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<OffsetPage<Payload<M, T, A>>>;
   /** Cursor pages for `useInfiniteQuery`. */
-  infinite<const A extends Omit<CursorPageArgs<M, T>, "after"> & FindExt<E, M, T>>(args: A): InfiniteOptionsOf<CursorPage<Payload<M, T, A>>, string | null>;
+  infinite<const A extends Omit<CursorPageArgs<M, T>, "after"> & FindExt<E, M, T>>(args: A, options?: InfiniteExtras): InfiniteOptionsOf<CursorPage<Payload<M, T, A>>, string | null>;
   /** Numbered pages for `useInfiniteQuery`, starting at `args.page` (default 1). */
-  infinitePages<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A): InfiniteOptionsOf<OffsetPage<Payload<M, T, A>>, number>;
+  infinitePages<const A extends OffsetPageArgs<M, T> & FindExt<E, M, T>>(args: A, options?: InfiniteExtras): InfiniteOptionsOf<OffsetPage<Payload<M, T, A>>, number>;
   create<const A extends WriteArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
   update<const A extends UpdateArgs<M, T> = {}>(args?: A): MutationOptionsOf<{
     readonly id: PrimaryKeyValue<M, T>;
@@ -98,6 +95,13 @@ interface QueriesOptions {
    * the server so hydrated data isn't refetched on mount.
    */
   readonly staleTime?: number;
+  /**
+   * Appended to every query key. Give each executor its own scope (`'local'`
+   * for PowerSync, for instance) when several share one QueryClient, so their
+   * results never land in the same cache entry. Invalidation by table still
+   * reaches every scope.
+   */
+  readonly scope?: string;
 }
 /**
  * TanStack Query option factories for every table, framework-neutral: pass
@@ -126,18 +130,77 @@ interface UserChangeSource {
     readonly user: {
       readonly id: string;
     } | null;
+    readonly claims?: Readonly<Record<string, unknown>> | null;
   };
 }
 /**
- * Removes every `['bs', ...]` query when the signed-in user changes or signs
- * out, so the next user never sees the previous user's rows. Returns the
- * function that stops listening. `BetterSupabaseProvider` calls it for React;
- * call it yourself with Vue, Solid, Svelte or Angular Query.
+ * Resets every `['bs', ...]` query when the caller changes: another user,
+ * signing out, or new claims for the same user (an organization switch, a
+ * role change). Mounted queries refetch, so no one sees the previous
+ * identity's rows. Returns the function that stops listening.
+ * `BetterSupabaseProvider` calls it for React; call it yourself with Vue,
+ * Solid, Svelte or Angular Query.
+ *
+ * Queries that fetched while the session was still loading ran as anon, so
+ * they are reset when a user arrives. Data already in the cache when loading
+ * started (hydrated from the server) stays.
  *
  * ```ts
  * const stop = clearOnUserChange(queryClient, bs.auth);
  * ```
  */
-declare function clearOnUserChange(queryClient: Pick<QueryClient, "removeQueries">, auth: UserChangeSource): () => void;
+declare function clearOnUserChange(queryClient: Pick<QueryClient, "resetQueries" | "getQueryCache">, auth: UserChangeSource): () => void;
+//#endregion
+//#region src/query/optimistic.d.ts
+/** A query whose cached data an optimistic update rewrites: any `q.<table>.*()` option. */
+interface OptimisticTarget<T> {
+  readonly queryKey: QueryKeyOf<T>;
+}
+interface MutationContext {
+  readonly client: QueryClient;
+}
+/** What `onMutate` returns: the data each target held before the change. */
+interface OptimisticSnapshot {
+  readonly previous: readonly (readonly [queryKey: readonly unknown[], data: unknown])[];
+}
+/**
+ * `onMutate`, `onError` and `onSettled` for `useMutation`: spread them next
+ * to a mutation option, which keeps its `onSuccess` invalidation.
+ */
+interface OptimisticHandlers<V> {
+  onMutate(variables: V, context: MutationContext): Promise<OptimisticSnapshot>;
+  onError(error: Error, variables: V, snapshot: OptimisticSnapshot | undefined, context: MutationContext): void;
+  onSettled(data: unknown, error: Error | null, variables: V, snapshot: OptimisticSnapshot | undefined, context: MutationContext): Promise<void>;
+}
+type Targets<T> = OptimisticTarget<T> | readonly OptimisticTarget<T>[];
+type Keyed<R> = Extract<keyof R, string>;
+/**
+ * Optimistic updates for list queries (`findMany`), keyed by a row column
+ * (`id` by default):
+ *
+ * - `optimistic.create(list, (input) => row)` adds the row the input will make.
+ * - `optimistic.update(list)` merges `{ id, patch }` into the matching row.
+ * - `optimistic.remove(list)` drops the row whose key is the deleted id.
+ * - `optimistic(target, apply)` rewrites any cached data.
+ *
+ * ```ts
+ * const list = q.todos.findMany({ where: { done: false } });
+ * useMutation({ ...q.todos.update(), ...optimistic.update(list) });
+ * ```
+ */
+declare const optimistic: (<T, V>(targets: Targets<T>, apply: (current: T, variables: V) => T) => OptimisticHandlers<V>) & {
+  create<R, V>(targets: Targets<R[]>, toRow: (variables: V) => R, options?: {
+    readonly position?: "start" | "end";
+  }): OptimisticHandlers<V>;
+  update<R, K extends Keyed<R> = Keyed<R> & "id">(targets: Targets<R[]>, options?: {
+    readonly key?: K;
+  }): OptimisticHandlers<{
+    readonly id: R[K];
+    readonly patch: Partial<R>;
+  }>;
+  remove<R, K extends Keyed<R> = Keyed<R> & "id">(targets: Targets<R[]>, options?: {
+    readonly key?: K;
+  }): OptimisticHandlers<R[K]>;
+};
 //#endregion
-export { MutationOptionsOf as a, QueryKeyOf as c, createQueries as d, invalidateOnMutation as f, invalidateTables as h, InfiniteOptionsOf as i, QueryOptionsOf as l, BetterQueryMeta as m, clearOnUserChange as n, QueriesOptions as o, queryCache as p, BetterQueries as r, QueryHelpers as s, UserChangeSource as t, TableQueries as u };
+export { invalidateOnMutation as _, UserChangeSource as a, InfiniteExtras as c, QueriesOptions as d, QueryHelpers as f, createQueries as g, TableQueries as h, optimistic as i, InfiniteOptionsOf as l, QueryOptionsOf as m, OptimisticSnapshot as n, clearOnUserChange as o, QueryKeyOf as p, OptimisticTarget as r, BetterQueries as s, OptimisticHandlers as t, MutationOptionsOf as u, queryCache as v };

package/dist/index-BkWT_uBO.d.ts

@@ -0,0 +1,51 @@
+import { a as AnyModels, i as AnyFunctions } from "./types-6BdhkmZe.js";
+import { l as PublicEnv } from "./index-CLg87OBW.js";
+import { s as SessionEncoding } from "./session-ChiXDZdZ.js";
+import { t as BetterSupabase } from "./define-CJJkkr1-.js";
+import { r as BetterClient } from "./bind-Bu_ZNa3W.js";
+import { SupabaseClient, SupabaseClientOptions } from "@supabase/supabase-js";
+//#region src/client/index.d.ts
+interface ClientOptions {
+  /** URL and publishable key. Not needed when `client` is given. */
+  readonly env?: PublicEnv;
+  /**
+   * Bring your own supabase-js client (custom storage). React Native apps
+   * use `better-supabase/client/native`, which doesn't load `@supabase/ssr`.
+   */
+  readonly client?: SupabaseClient;
+  /**
+   * `cookies` (default) shares the session with the server through
+   * `@supabase/ssr`; `local` keeps it in localStorage for SPAs without a server.
+   */
+  readonly storage?: "cookies" | "local";
+  readonly cookies?: {
+    /**
+     * `tokens-only` keeps the user object out of the cookie (it lives in
+     * `auth.userStorage`, localStorage by default), so cookies stay small.
+     * Use the same value as the server's `encode`. Defaults to
+     * `user-and-tokens`.
+     */
+    readonly encode?: SessionEncoding;
+  };
+  readonly auth?: {
+    /** Where auth-js keeps the user object with `cookies.encode: 'tokens-only'`. */
+    readonly userStorage?: UserStorage;
+  };
+  /**
+   * `staleTime` for every query option in `bs.queries`. Above zero, a
+   * remount or a window focus reuses cached rows instead of refetching.
+   */
+  readonly staleTime?: number;
+}
+type UserStorage = NonNullable<NonNullable<SupabaseClientOptions<"public">["auth"]>["userStorage"]>;
+/**
+ * The browser side: a supabase-js client, repositories that follow the
+ * session, TanStack Query options and an auth store for UI state.
+ *
+ * ```ts
+ * export const bs = createClient(betterSupabase, { env: { url, publishableKey } });
+ * ```
+ */
+declare function createClient$1<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P>, options?: ClientOptions): BetterClient<M, F, E, C, P>;
+//#endregion
+export { createClient$1 as n, ClientOptions as t };

package/dist/index-BpFYMsi0.d.ts

@@ -0,0 +1,53 @@
+import { ChatOnFinishCallback, ChatTransport, UIMessage } from "ai";
+import { UseChatHelpers } from "@ai-sdk/react";
+//#region src/ai-sdk/react/body.d.ts
+/** What a transport factory gets from `useAssistant`. */
+interface AssistantTransportConfig {
+  readonly api: string;
+  readonly model: string | undefined;
+  readonly body: Readonly<Record<string, unknown>> | undefined;
+  readonly headers: Readonly<Record<string, string>> | undefined;
+}
+//#endregion
+//#region src/ai-sdk/react/index.d.ts
+interface UseAssistantOptions {
+  /** The chat id; make one on the client for a new chat. */
+  readonly id: string;
+  /** The route of `createAssistant`. Defaults to `/api/chat`. */
+  readonly api?: string;
+  /** The model the next answer uses; the server checks it against the catalog. */
+  readonly model?: string;
+  /** The stored history, such as `toUIMessages(path)` from the server. */
+  readonly messages?: UIMessage[];
+  /** Picks up an answer that is still being written. Defaults to true. */
+  readonly resume?: boolean;
+  /** Extra fields for the request body. */
+  readonly body?: Readonly<Record<string, unknown>>;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly onError?: (error: Error) => void;
+  readonly onFinish?: ChatOnFinishCallback<UIMessage>;
+  /** Custom throttle wait in ms for message updates. */
+  readonly throttle?: number;
+  /**
+   * Makes the transport instead of the default one, such as
+   * `durableTransport` from `better-supabase/ai-sdk/workflow/react`. Pass a
+   * function defined outside the component, so the transport is kept.
+   */
+  readonly transport?: (config: AssistantTransportConfig) => ChatTransport<UIMessage>;
+  /** Sends again without user input, such as once every approval is answered. */
+  readonly sendAutomaticallyWhen?: (options: {
+    messages: UIMessage[];
+  }) => boolean | PromiseLike<boolean>;
+}
+type AssistantState = UseChatHelpers<UIMessage> & {
+  /** Stops the answer on the server too, so it is stored as stopped. */
+  stop: () => Promise<void>;
+};
+/**
+ * `useChat` wired to `createAssistant`: it sends only the new message (the
+ * server keeps the history), resumes a running answer after a reload and
+ * stops it on the server.
+ */
+declare function useAssistant(options: UseAssistantOptions): AssistantState;
+//#endregion
+export { AssistantTransportConfig as i, UseAssistantOptions as n, useAssistant as r, AssistantState as t };

package/dist/{index-C7f8cOBM.d.ts → index-Bxih3l0u.d.ts}

@@ -1,5 +1,5 @@
-import { j as SchemaMeta } from "./types-Dnf_wRDz.js";
-import { p as OpenApiParameter } from "./index-fag8VJZ2.js";
+import { P as SchemaMeta } from "./types-6BdhkmZe.js";
+import { m as OpenApiParameter } from "./list-query-BRt-zDF7.js";
 //#region src/openapi/index.d.ts
 type Json = Record<string, unknown>;
 type ResourceOperation = "list" | "get" | "create" | "update" | "delete";

package/dist/index-CaxrMD1A.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/index-ClmjK_o-.d.ts

@@ -0,0 +1,55 @@
+import { P as SchemaMeta } from "./types-6BdhkmZe.js";
+import { h as MutationIntent } from "./executor-DvsBbNBS.js";
+import { a as EventHub, s as MutationNotice } from "./events-DWDhx77e.js";
+import { n as CloudEventOptions, r as EventSink, t as CloudEvent } from "./cloud-event-C1JCc1bH.js";
+//#region src/events/index.d.ts
+declare const ROW_EVENT_TYPES: { readonly [K in MutationIntent]: string; };
+interface RowEventData {
+  readonly table: string;
+  readonly row: Readonly<Record<string, unknown>>;
+  readonly actorId?: string;
+}
+/**
+ * One CloudEvent per mutated row: `dev.better-supabase.row.created` with the
+ * app-cased row and the actor in `data`, the primary key as `subject` and the
+ * tenant as `partitionkey`. Writes that return no rows (soft
+ * deletes, `returning: false`) send one event per known primary key, with the
+ * key as `row`.
+ */
+declare function toCloudEvents(notice: MutationNotice, options: CloudEventOptions & {
+  readonly meta?: SchemaMeta;
+}): CloudEvent<RowEventData>[];
+interface ForwardOptions extends CloudEventOptions {
+  /** Only forward these tables or kinds. */
+  readonly filter?: (notice: MutationNotice) => boolean;
+  /** Sink failures never fail the mutation. Defaults to the `Logger`. */
+  readonly onError?: (error: unknown, events: readonly CloudEvent[]) => void;
+}
+/**
+ * Sends a CloudEvent for every mutation to `sink`. Returns a function that
+ * stops forwarding. Sends in flight are tracked on `betterSupabase.events`
+ * (`settled()`), which the Next adapter hands to `after()` and the edge
+ * entry to `waitUntil`. Use an outbox (SQL modules) when events must not be lost.
+ */
+declare function forwardMutations(betterSupabase: {
+  readonly events: EventHub;
+  readonly meta: SchemaMeta;
+}, sink: EventSink, options: ForwardOptions): () => void;
+type HttpMode = "structured" | "binary" | "batch";
+/** The HTTP protocol binding: headers and body for one event (or a batch). */
+declare function toHttp(events: CloudEvent | readonly CloudEvent[], mode?: HttpMode): {
+  headers: Record<string, string>;
+  body: string;
+}[];
+declare function isCloudEvent(value: unknown): value is CloudEvent;
+/** Reads CloudEvents from a request in any of the three HTTP modes. */
+declare function fromHttp(request: Request): Promise<CloudEvent[]>;
+interface HttpSinkOptions {
+  readonly mode?: HttpMode;
+  readonly headers?: Readonly<Record<string, string>>;
+  readonly fetch?: typeof fetch;
+}
+/** POSTs events to `url`. Non-2xx responses reject. */
+declare function httpSink(url: string | URL, options?: HttpSinkOptions): EventSink;
+//#endregion
+export { RowEventData as a, httpSink as c, toHttp as d, ROW_EVENT_TYPES as i, isCloudEvent as l, HttpMode as n, forwardMutations as o, HttpSinkOptions as r, fromHttp as s, ForwardOptions as t, toCloudEvents as u };

package/dist/index-CtuakVRc.d.ts

@@ -0,0 +1,267 @@
+import { b as DbError, f as Result, t as AsyncResult } from "./result-D7y2fT87.js";
+import { it as QuerySpec } from "./define-CJJkkr1-.js";
+import { C as UrlOptions, S as UploadOptions, x as UploadBody } from "./bucket-Cl46E3jS.js";
+import { n as TemplateValues } from "./template-CwO38Do8.js";
+import { t as AuthSnapshot } from "./bind-Bu_ZNa3W.js";
+import { t as AuthSession } from "./view-DbxLNu8L.js";
+import { S as Topic, _ as RealtimeClient, f as PresenceMember, g as PresenceSubscription, p as PresenceOptions, r as LiveCountSeed, u as EventSchemas, w as TopicHandlers, x as SubscriptionStatus, y as SubscribeOptions } from "./index-DunNRdnT.js";
+import { a as BroadcastOptions, f as UseActionOptions, l as LiveQueryHookOptions, n as ActionInputOf, o as ClientLike, r as ActionResultOf, s as LiveCountHookOptions } from "./field-errors-BFOa7WhB.js";
+import { SupabaseClient } from "@supabase/supabase-js";
+import { ReactNode, SubmitEvent } from "react";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+import { QueryClient } from "@tanstack/query-core";
+//#region src/react/hooks.d.ts
+interface BetterSupabaseProviderProps {
+  readonly client: ClientLike;
+  /** better-supabase queries are removed when the user signs out or changes. */
+  readonly queryClient?: QueryClient;
+  readonly children?: ReactNode;
+}
+/** Provides the better-supabase client to the hooks. */
+declare function BetterSupabaseProvider(props: BetterSupabaseProviderProps): ReactNode;
+/** The session state for UI: `loading`, `signed-out` or `signed-in` with the user and claims. */
+declare function useAuth(): AuthSnapshot;
+declare function useSupabase(): SupabaseClient;
+interface BetterHooks<B extends ClientLike> {
+  /** Repositories bound to the current session. Re-renders when the user changes. */
+  readonly useDb: () => B["db"];
+  /** TanStack Query option factories: `useQuery(useQueries().customers.findMany())`. */
+  readonly useQueries: () => B["queries"];
+  readonly useSupabase: () => SupabaseClient;
+  readonly useAuth: () => AuthSnapshot;
+  /** `useSession()` typed by the client's `betterSupabase.claims(schema)` and `betterSupabase.userMetadata(schema)`. */
+  readonly useSession: () => AuthSession<ClaimsOf<B>, ProfileOf<B>>;
+}
+/** The claims type of a client's `betterSupabase.claims(schema)`, `unknown` without one. */
+type ClaimsOf<B extends ClientLike> = B["betterSupabase"] extends {
+  readonly claimsSchema: StandardSchemaV1<unknown, infer C> | undefined;
+} ? C : unknown;
+/** The profile type of a client's `betterSupabase.userMetadata(schema)`, `unknown` without one. */
+type ProfileOf<B extends ClientLike> = B["betterSupabase"] extends {
+  readonly userMetadataSchema: StandardSchemaV1<unknown, infer P> | undefined;
+} ? P : unknown;
+/**
+ * Hooks typed for your schema.
+ *
+ * ```ts
+ * export const { useDb, useQueries, useAuth } = createHooks<typeof bs>();
+ * ```
+ */
+declare function createHooks<B extends ClientLike>(): BetterHooks<B>;
+/**
+ * Subscribes to a topic while mounted. Pass `null` values to pause. It
+ * resubscribes when the topic or the signed-in user changes.
+ *
+ * ```ts
+ * useBroadcast(customersTopic, organizationId ? { organizationId } : null, {}, { invalidate: ['customers'] });
+ * ```
+ */
+declare function useBroadcast<P extends string, E extends EventSchemas>(topic: Topic<P, E>, values: TemplateValues<P> | null | undefined, handlers?: TopicHandlers<E>, options?: BroadcastOptions): SubscriptionStatus;
+/**
+ * Keeps a query fresh: invalidates every cached query that read a table the
+ * spec touches whenever one of them changes. Pass `null` to pause. It
+ * resubscribes when the spec, tenant or user changes.
+ *
+ * ```ts
+ * const spec = betterSupabase.spec.customers.findMany({ include: { notes: true } });
+ * const { data } = useQuery(q.$spec(spec));
+ * useLiveQuery(spec);
+ * ```
+ */
+declare function useLiveQuery(spec: QuerySpec | null | undefined, options?: LiveQueryHookOptions): SubscriptionStatus;
+interface LiveCount {
+  /** `undefined` until the first count arrives. */
+  readonly count: number | undefined;
+  readonly status: SubscriptionStatus;
+  /** The last failed refetch; the previous count stays. */
+  readonly error: DbError | undefined;
+}
+/**
+ * A count that stays current: refetches only the `count` spec (a HEAD
+ * request) after each debounced change to a table it reads, and after the
+ * channel rejoins. Takes a spec or a `bs.liveCount()` seed; pass `null` to
+ * pause. Doesn't need a `QueryClient`.
+ *
+ * ```tsx
+ * const { count } = useLiveCount(seed); // seed = await bs.liveCount(spec)
+ * ```
+ */
+declare function useLiveCount(source: QuerySpec<string, "count", number> | LiveCountSeed | null | undefined, options?: LiveCountHookOptions): LiveCount;
+//#endregion
+//#region src/react/actions.d.ts
+interface ActionHandle<I, T> {
+  /** Runs the action in a transition; resolves with its result. */
+  run(input: I): Promise<ActionResultOf<T>>;
+  /** True while a run is in flight, including the router update it causes. */
+  readonly pending: boolean;
+  /** The inputs of the runs in flight, e.g. to dim one table row. */
+  readonly pendingInputs: readonly I[];
+  /** The input of the latest run in flight. */
+  readonly pendingInput: I | undefined;
+  /** The data of the last successful run. */
+  readonly data: T | undefined;
+  /** The error of the last run, until the next one starts. */
+  readonly error: DbError | undefined;
+  reset(): void;
+}
+/**
+ * Calls a Server Action from an event handler: tracks pending inputs and the
+ * last result, and calls `onSuccess` or `onError`.
+ *
+ * ```tsx
+ * const remove = useAction(removeMember, { onError: (e) => toast.error(message(e)) });
+ * <Button disabled={remove.pendingInputs.some((p) => p.userId === id)} onClick={() => remove.run({ userId: id })} />
+ * ```
+ */
+declare function useAction<I, T>(action: (input: I) => Promise<ActionResultOf<T>>, options?: UseActionOptions<ActionInputOf<I>, T>): ActionHandle<ActionInputOf<I>, T>;
+interface UseActionFormOptions<T> {
+  readonly onSuccess?: (data: T, form: HTMLFormElement) => void;
+  readonly onError?: (error: DbError, form: HTMLFormElement) => void;
+  /** Clear the fields after a successful run. Defaults to true. */
+  readonly resetOnSuccess?: boolean;
+}
+interface ActionForm<T> {
+  /** Spread on the `<form>`. */
+  readonly formProps: {
+    readonly onSubmit: (event: SubmitEvent<HTMLFormElement>) => void;
+  };
+  readonly pending: boolean;
+  readonly data: T | undefined;
+  readonly error: DbError | undefined;
+  /** The first message per top-level field of a `validation` error. */
+  readonly fieldErrors: Readonly<Partial<Record<string, string>>>;
+  reset(): void;
+}
+/**
+ * A `<form>` that submits `FormData` to a Server Action. Fields keep what
+ * the user typed when the action fails (a `<form action>` resets them) and
+ * clear only on success.
+ *
+ * ```tsx
+ * const form = useActionForm(createCustomer, { onSuccess: () => toast.success('Saved') });
+ * <form {...form.formProps}>
+ *   <Input name="name" aria-invalid={form.fieldErrors.name !== undefined} />
+ * </form>
+ * ```
+ */
+declare function useActionForm<T>(action: (input: FormData) => Promise<ActionResultOf<T>>, options?: UseActionFormOptions<T>): ActionForm<T>;
+//#endregion
+//#region src/react/presence.d.ts
+interface PresenceHookOptions<I> {
+  /**
+   * The state this client shares while mounted. It is tracked after the
+   * join and tracked again when its JSON changes; `null` stays untracked.
+   */
+  readonly state?: I | null;
+  /** A supabase-js client for apps without `<BetterSupabaseProvider>`. */
+  readonly client?: SupabaseClient;
+}
+interface Presence<I, O> {
+  /** Everyone on the topic, this client included, from the last sync. */
+  readonly members: readonly PresenceMember<O>[];
+  readonly status: SubscriptionStatus;
+  /** Shares a state now; the `state` option tracks one for you. */
+  readonly track: (state: I) => Promise<DbError | undefined>;
+  readonly untrack: () => Promise<DbError | undefined>;
+}
+/** The parts of a `defineTopic(..., { presence })` topic the hook uses. */
+interface PresenceTopic<P extends string, I, O> {
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: Readonly<Record<string, never>>, options?: SubscribeOptions & PresenceOptions<O>): PresenceSubscription<I, O>;
+}
+/**
+ * Joins a presence topic while mounted and returns who is on it. Pass
+ * `null` values to pause. It rejoins when the topic or the user changes.
+ *
+ * ```tsx
+ * const { members } = usePresence(roomTopic, { roomId }, { state: { name } });
+ * ```
+ */
+declare function usePresence<P extends string, I, O>(topic: PresenceTopic<P, I, O>, values: TemplateValues<P> | null | undefined, options?: PresenceHookOptions<I>): Presence<I, O>;
+//#endregion
+//#region src/react/search.d.ts
+interface DebouncedSearchOptions {
+  /** Defaults to 250 ms. */
+  readonly delayMs?: number;
+  /** Shorter terms count as no search. Defaults to 1. */
+  readonly minLength?: number;
+}
+interface DebouncedSearch {
+  /** What the input shows; updates on every keystroke. */
+  readonly value: string;
+  readonly setValue: (value: string) => void;
+  /** The trimmed value once typing pauses, or `undefined` below `minLength`. */
+  readonly term: string | undefined;
+  /** `term` with `%` and `_` escaped and wrapped in `%`, for `like` and `ilike`. */
+  readonly pattern: string | undefined;
+  /** `value` changed and `term` hasn't caught up yet. */
+  readonly pending: boolean;
+}
+/**
+ * A search box's value, debounced. Pass `term` to `contains` (which
+ * escapes it) or `pattern` to `ilike`; both are `undefined` while empty.
+ *
+ * ```tsx
+ * const search = useDebouncedSearch();
+ * useQuery(q.customers.findMany({ where: search.term ? { name: { contains: search.term } } : {} }));
+ * ```
+ */
+declare function useDebouncedSearch(initial?: string, options?: DebouncedSearchOptions): DebouncedSearch;
+//#endregion
+//#region src/react/storage.d.ts
+/** The part of a connected bucket `useSignedUrl` calls. */
+interface SignedUrlSource<T> {
+  signedUrl(target: T, options?: UrlOptions): AsyncResult<string>;
+}
+interface SignedUrl {
+  /** `undefined` until the first URL arrives, and while paused. */
+  readonly url: string | undefined;
+  readonly error: DbError | undefined;
+  readonly loading: boolean;
+}
+/**
+ * A signed URL for an object, signed again before it expires. Pass `null`
+ * as the target to pause. Connect the bucket with `cacheSignedUrls: true`
+ * so components showing the same object share one URL.
+ *
+ * ```tsx
+ * const { url } = useSignedUrl(avatars, user ? { userId: user.id } : null, { ttl: 'hour' });
+ * ```
+ */
+declare function useSignedUrl<T>(bucket: SignedUrlSource<T>, target: T | null | undefined, options?: UrlOptions): SignedUrl;
+/** The part of a connected bucket `useUpload` calls. */
+interface UploadTarget<T, R> {
+  upload(target: T, body: UploadBody, options?: UploadOptions): AsyncResult<R>;
+}
+type UploadStatus = "idle" | "uploading" | "done" | "error";
+interface Upload<T, R> {
+  readonly status: UploadStatus;
+  /** 0 to 1 while uploading; see `UploadOptions.onProgress` for when it is exact. */
+  readonly progress: number;
+  readonly data: R | undefined;
+  readonly error: DbError | undefined;
+  /** Starts an upload; a new one aborts the one in flight. */
+  readonly upload: (target: T, body: UploadBody, options?: Omit<UploadOptions, "signal" | "onProgress">) => Promise<Result<R>>;
+  /** Cancels the upload in flight. */
+  readonly abort: () => void;
+  /** Back to `idle`. */
+  readonly reset: () => void;
+}
+interface UseUploadOptions<R> {
+  readonly onSuccess?: (data: R) => void;
+  readonly onError?: (error: DbError) => void;
+}
+/**
+ * Uploads to a connected bucket with progress, abort and status state.
+ * Unmounting aborts the upload in flight.
+ *
+ * ```tsx
+ * const avatar = useUpload(avatars, { onSuccess: ({ path }) => save(path) });
+ * <input type="file" onChange={(e) => avatar.upload({ userId }, e.target.files[0], { upsert: true })} />
+ * <progress value={avatar.progress} />
+ * ```
+ */
+declare function useUpload<T, R>(bucket: UploadTarget<T, R>, options?: UseUploadOptions<R>): Upload<T, R>;
+//#endregion
+export { useLiveCount as A, BetterSupabaseProviderProps as C, createHooks as D, ProfileOf as E, useSupabase as M, useAuth as O, BetterSupabaseProvider as S, LiveCount as T, ActionHandle as _, UploadTarget as a, useActionForm as b, useUpload as c, useDebouncedSearch as d, Presence as f, ActionForm as g, usePresence as h, UploadStatus as i, useLiveQuery as j, useBroadcast as k, DebouncedSearch as l, PresenceTopic as m, SignedUrlSource as n, UseUploadOptions as o, PresenceHookOptions as p, Upload as r, useSignedUrl as s, SignedUrl as t, DebouncedSearchOptions as u, UseActionFormOptions as v, ClaimsOf as w, BetterHooks as x, useAction as y };