better-supabase 0.13.0 → 0.14.0

package/dist/index-DbXWcrOI.d.ts

@@ -0,0 +1,577 @@
+/// <reference lib="esnext.temporal" />
+import { n as DbException } from "./escape-like-BfXS-iVe.js";
+import { f as Result, t as AsyncResult } from "./result-C6jDfedy.js";
+import { M as AnyFunctions, N as AnyModels, X as Insert, dt as SubjectRef, mt as TableKey, tt as PrimaryKeyValue, vt as UniqueWhere, yt as Update } from "./executor-CPyrQdjh.js";
+import { o as EventHub } from "./events-DbLjvxDX.js";
+import { Ct as ReadArgs, J as QuerySpec, O as UpdateArgs, St as Payload, T as Returned, Ut as CacheAdapter, a as CursorPageArgs, c as DeleteArgs, ct as CountArgs, dt as FindManyArgs, et as AggregateArgs, ft as FindOnlyArgs, g as OffsetRangeArgs, h as OffsetPageArgs, i as CursorPage, j as WriteArgs, k as UpsertArgs, kt as WhereInput, l as DeleteExt, m as OffsetPage, o as Db, q as InferResult, rt as AggregateResult, t as BetterSupabase, u as FindExt, ut as FindFirstArgs } from "./define-Dw7pRO4h.js";
+import { Ft as AnySection, It as AnySectionWrite, Jt as SectionWriteOutput, Kt as SectionWriteInput, Rt as SectionData, Ut as SectionResult, Vt as SectionOptions, cn as GeneratedBlocks, qt as SectionWriteName, t as AnyBlock } from "./define-block-COpcS6aT.js";
+import { t as BetterQueryMeta } from "./invalidate-BLiBFbLy.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+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: {
+  readonly signal: AbortSignal;
+}) => Promise<T>) | SkipToken;
+/**
+ * Options for `useQuery`, `createQuery`, `injectQuery`,
+ * `queryClient.fetchQuery` and `prefetchQuery`.
+ */
+interface QueryOptionsOf<T> {
+  readonly queryKey: QueryKeyOf<T>;
+  readonly queryFn: QueryFnOf<T>;
+  readonly meta: BetterQueryMeta;
+  readonly staleTime?: number;
+}
+/**
+ * Options for infinite queries over cursor (`string | null`) or offset
+ * (`number`) pages.
+ */
+interface InfiniteOptionsOf<P, Param> {
+  readonly queryKey: DataTag<readonly unknown[], InfiniteData<P>, DbException>;
+  readonly queryFn: (context: {
+    readonly signal: AbortSignal;
+    readonly pageParam: 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[];
+  readonly mutationFn: (variables: V) => Promise<R>;
+  readonly onSuccess: (data: R, variables: V, onMutateResult: unknown, context: {
+    readonly client: QueryClient;
+  }) => Promise<void>;
+}
+interface TableQueries<M extends AnyModels, T extends TableKey<M>, E> {
+  /** Prefix of every key for this table's own queries. */
+  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>;
+  findById<const A extends ReadArgs<M, T> & FindExt<E, M, T>>(id: PrimaryKeyValue<M, T> | SkipToken, args?: A): QueryOptionsOf<Payload<M, T, A>>;
+  count(args?: (CountArgs<M, T> & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<number>;
+  aggregate<const A extends AggregateArgs<M, T> & FindExt<E, M, T>>(args: A | SkipToken): QueryOptionsOf<AggregateResult<M, T, A>>;
+  exists(args?: ({
+    readonly where?: WhereInput<M, T>;
+  } & FindExt<E, M, T>) | SkipToken): QueryOptionsOf<boolean>;
+  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, 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, 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>;
+    readonly patch: Update<M, T>;
+  }, Returned<M, T, A>>;
+  upsert<const A extends UpsertArgs<M, T> = {}>(args?: A): MutationOptionsOf<Insert<M, T>, Returned<M, T, A>>;
+  delete(args?: DeleteArgs & DeleteExt<E, M, T>): MutationOptionsOf<PrimaryKeyValue<M, T>, void>;
+}
+type RpcArgsOf<F extends AnyFunctions, N extends keyof F> = F[N]["Args"];
+interface QueryHelpers<M extends AnyModels, F extends AnyFunctions> {
+  /** Prefix of every better-supabase key. */
+  readonly $key: readonly ["bs"];
+  /**
+   * Query options for a `QuerySpec`, for example one sent from a Server
+   * Component.
+   */
+  $spec<S extends QuerySpec<TableKey<M>>>(spec: S | SkipToken): QueryOptionsOf<InferResult<S>>;
+  /** Fetches a spec into `queryClient` for server rendering and hydration. */
+  $prefetch(queryClient: QueryClient, spec: QuerySpec<TableKey<M>>): Promise<void>;
+  /**
+   * Query options for a database function. `tables` lists what it reads, for
+   * invalidation.
+   */
+  $rpc<N extends Extract<keyof F, string>>(name: N, args?: RpcArgsOf<F, N> | SkipToken, options?: {
+    readonly tables?: readonly TableKey<M>[];
+  }): QueryOptionsOf<F[N]["Returns"]>;
+  /**
+   * Mutation options for a database function; invalidates what
+   * `betterSupabase.defineRpc` declared.
+   */
+  $rpcMutation<N extends Extract<keyof F, string>>(name: N): MutationOptionsOf<RpcArgsOf<F, N>, F[N]["Returns"]>;
+}
+type BetterQueries<M extends AnyModels, E, F extends AnyFunctions = AnyFunctions> = { readonly [T in TableKey<M>]: TableQueries<M, T, E>; } & QueryHelpers<M, F>;
+interface QueriesOptions {
+  /**
+   * `staleTime` for every query option. Set it above zero when rendering on 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 them
+ * to `useQuery` (React), `createQuery` (Svelte, Solid), `useQuery` (Vue) or
+ * `injectQuery` (Angular). Payload types flow into the cache, errors are
+ * `DbException`s, and mutations invalidate every query that read a changed
+ * table.
+ *
+ * ```ts
+ * const q = createQueries(betterSupabase, () => bs.db);
+ * const { data } = useQuery(
+ *   q.customers.findMany({ select: ["id", "name"] }),
+ * );
+ * ```
+ */
+declare function createQueries<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, db: Db<M, F, E, unknown> | (() => Db<M, F, E, unknown>), options?: QueriesOptions): BetterQueries<M, E, F>;
+/** Invalidates every query that read a table in the target. */
+declare function queryCache(client: QueryClient): CacheAdapter;
+/**
+ * Invalidates affected queries for every mutation and declared RPC
+ * `betterSupabase` performs in this runtime.
+ */
+declare function invalidateOnMutation<M extends AnyModels, D, F extends AnyFunctions, E>(betterSupabase: BetterSupabase<M, D, F, E>, client: QueryClient): () => void;
+//#endregion
+//#region src/query/user-change.d.ts
+/** The part of `createClient().auth` that `clearOnUserChange` reads. */
+interface UserChangeSource {
+  subscribe(listener: () => void): () => void;
+  current(): {
+    readonly status: string;
+    readonly user: {
+      readonly id: string;
+    } | null;
+    readonly claims?: Readonly<Record<string, unknown>> | null;
+  };
+}
+/**
+ * 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, "resetQueries" | "getQueryCache">, auth: UserChangeSource): () => void;
+//#endregion
+//#region src/query/blocks.d.ts
+/** The first key part of every block query. */
+declare const BLOCK_KEY = "bs-block";
+/**
+ * Method name prefixes that read: these become query options, every other
+ * method becomes mutation options.
+ */
+declare const BLOCK_READ_PREFIXES: readonly ["can", "count", "find", "get", "has", "is", "list", "load", "preview", "read", "resolve", "search", "tree"];
+type ReadPrefix = (typeof BLOCK_READ_PREFIXES)[number];
+type AnyMethod = (...args: never[]) => PromiseLike<Result<unknown>>;
+type DataOf<F> = F extends ((...args: never[]) => PromiseLike<infer R>) ? R extends {
+  readonly ok: true;
+  readonly data: infer D;
+} ? D : never : never;
+/**
+ * What a block mutation takes: the one argument of a method with at most one
+ * parameter, else the arguments as a tuple.
+ */
+type BlockVariablesOf<F extends AnyMethod> = Parameters<F>["length"] extends 0 | 1 ? Parameters<F>[0] : Parameters<F>;
+type MethodKeys<C> = { readonly [K in keyof C]: C[K] extends AnyMethod ? K : never; }[keyof C] & string;
+/** The query or mutation options of one block method. */
+type BlockMethodQuery<K extends string, F extends AnyMethod> = K extends ReadPrefix | `${ReadPrefix}${Capitalize<string>}` ? (...args: Parameters<F> | [SkipToken]) => QueryOptionsOf<DataOf<F>> : () => MutationOptionsOf<BlockVariablesOf<F>, DataOf<F>>;
+/** Query and mutation options for one block client, by method. */
+type BlockClientQueries<C> = { readonly [K in MethodKeys<C>]: C[K] extends AnyMethod ? BlockMethodQuery<K, C[K]> : never; } & {
+  /** Prefix of every key for this block's queries. */
+  readonly $key: readonly [typeof BLOCK_KEY, string];
+};
+/** `blockQueries(clients)`: query and mutation options for each block. */
+type BlockQueries<C> = { readonly [K in keyof C & string]: BlockClientQueries<C[K]>; };
+/** The block clients `createBlocks` built, by key. */
+type BlockClients = Readonly<Record<string, object>>;
+/**
+ * Query options for each read method of each block client (`get*`, `list*`,
+ * `find*`, `search*` and the other `BLOCK_READ_PREFIXES`), keyed `["bs-block",
+ * block, method, ...args]`, and mutation options for every other method. A
+ * mutation makes its block's queries stale; `invalidateOnBlockEvents` does the
+ * same for block events. Renamed blocks (`renameBlock`) keep their renamed
+ * method names. A method that fails throws a `DbException`, like
+ * `createQueries`.
+ */
+declare function blockQueries<const C extends BlockClients>(clients: C, options?: QueriesOptions): BlockQueries<C>;
+/** What `invalidateOnBlockEvents` reads from each block. */
+interface BlockInvalidation {
+  readonly events: {
+    readonly types: readonly string[];
+  };
+  readonly invalidates?: Readonly<Record<string, readonly string[]>>;
+}
+/**
+ * Makes block queries stale when a block event arrives on `source.events`: the
+ * read methods the block's `invalidates` lists for the event, or every read
+ * method of the block when none lists it. Pass the blocks keyed like the
+ * clients given to `blockQueries` (`defineBlocks(...).blocks`). Returns a
+ * function that stops listening.
+ */
+declare function invalidateOnBlockEvents(queryClient: QueryClient, source: {
+  readonly events: EventHub;
+}, blocks: Readonly<Record<string, BlockInvalidation>>): () => void;
+//#endregion
+//#region src/blocks/access/permissions.d.ts
+/**
+ * The caller's permission keys in one tenant, as `my_permissions` returned
+ * them. It is plain data, so a Server Component can pass it to the client.
+ */
+interface PermissionSet {
+  /** The organization the keys hold in. */
+  readonly tenant: string;
+  /**
+   * The keys the caller holds. Keys loaded without a list keep their wildcards
+   * (`*`, `invoices.*`) as the access model grants them.
+   */
+  readonly keys: readonly string[];
+}
+/** `{ edit: "customers.write" }` as `{ canEdit: boolean }`. */
+type PermissionFlags<M extends Readonly<Record<string, string>>> = { readonly [N in keyof M & string as `can${Capitalize<N>}`]: boolean; };
+/**
+ * Whether a granted key covers a wanted one: the same rule as the SQL
+ * `permission_matches`, where `*` grants every key and `prefix.*` every key
+ * under `prefix`.
+ */
+declare function permissionMatches(granted: string, wanted: string): boolean;
+/**
+ * Whether `set` holds `key`. UX only: RLS and the SQL functions check the key
+ * again.
+ *
+ * ```ts
+ * if (can(permissionSet, permissions.customers.write)) showEditButton();
+ * ```
+ */
+declare function can(set: PermissionSet | null | undefined, key: string): boolean;
+/**
+ * One `can<Name>` boolean per entry of `flags`, for a payload query that
+ * returns data and what the caller may do with it.
+ *
+ * ```ts
+ * permissionFlags(set, { edit: permissions.customers.write });
+ * // { canEdit: true }
+ * ```
+ */
+declare function permissionFlags<const M extends Readonly<Record<string, string>>>(set: PermissionSet | null | undefined, flags: M): PermissionFlags<M>;
+//#endregion
+//#region src/records/sections.d.ts
+/** Block manifests by the key the app built them under, as `blockSet.blocks`. */
+type SectionBlocks = Readonly<Record<string, {
+  readonly sql: readonly string[];
+  readonly sections?: Readonly<Record<string, AnySection>>;
+}>>;
+/**
+ * Where sections come from: the manifests (`blockSet.blocks`) and the clients
+ * built from them (`blockSet.create(...)`), keyed alike.
+ */
+interface SectionSource<B extends SectionBlocks> {
+  readonly blocks: B;
+  readonly clients: object;
+}
+type SectionsIn<Block> = Block extends {
+  readonly sections: infer S extends Readonly<Record<string, AnySection>>;
+} ? S : Record<never, never>;
+/** Every section name the blocks declare. */
+type SectionName<B extends SectionBlocks> = { readonly [K in keyof B]: keyof SectionsIn<B[K]> & string; }[keyof B];
+/** The section a name refers to. */
+type SectionNamed<B extends SectionBlocks, N extends string> = { readonly [K in keyof B]: N extends keyof SectionsIn<B[K]> ? SectionsIn<B[K]>[N] : never; }[keyof B];
+/** The settled results of `loadSections`, by section name. */
+type LoadedSections<B extends SectionBlocks, N extends string> = { readonly [K in N]: SectionResult<SectionData<SectionNamed<B, K>>>; };
+/** The permission `loadSections` asks `can` about. */
+interface SectionCheck {
+  readonly section: string;
+  /** The SQL module whose permission keys `action` names. */
+  readonly module: string;
+  /** `read`, or the section's `permissions.write` for a write. */
+  readonly action: string;
+}
+interface LoadSectionsOptions<B extends SectionBlocks, N extends string> {
+  /**
+   * Whether the caller may see a section; a section it can't is `hidden` and
+   * not loaded. Build it with `sectionCan`. Default: every section loads and
+   * RLS decides what it returns.
+   */
+  readonly can?: (check: SectionCheck) => boolean;
+  /** Options for each section's `load`, such as `{ comments: { limit: 20 } }`. */
+  readonly options?: { readonly [K in N]?: SectionOptions<SectionNamed<B, K>>; };
+}
+/**
+ * A `can` for `loadSections` from the caller's `PermissionSet` and the
+ * `permissions` constant of `blocks.generated.ts`: a section needs the key its
+ * module's action names there. An action with no key there is allowed, and RLS
+ * decides.
+ */
+declare function sectionCan(set: PermissionSet | null | undefined, permissions: Readonly<Record<string, Readonly<Record<string, string>>>>): (check: SectionCheck) => boolean;
+/**
+ * Loads a record's sections in parallel, each one settled: `ok` with its rows,
+ * `error` with a `DbError`, or `hidden` when `can` says the caller can't read
+ * it, which never runs its query. It never throws.
+ *
+ * ```ts
+ * const { comments, tags } = await loadSections(
+ *   { blocks: blockSet.blocks, clients: blocks },
+ *   { type: "customer", id },
+ *   ["comments", "tags"],
+ *   { can: sectionCan(permissionSet, permissions) },
+ * );
+ * ```
+ */
+declare function loadSections<B extends SectionBlocks, const N extends SectionName<B>>(source: SectionSource<B>, subject: SubjectRef, names: readonly N[], options?: LoadSectionsOptions<B, N>): Promise<LoadedSections<B, N>>;
+/**
+ * How many rows a section has for each of `subjects`, keyed by `subjectKey`
+ * (`type:id`), for a badge on each row of a list. A section without `count`
+ * fails with `unsupported`.
+ */
+declare function countSection<B extends SectionBlocks>(source: SectionSource<B>, name: SectionName<B>, subjects: readonly SubjectRef[]): AsyncResult<Readonly<Record<string, number>>>;
+//#endregion
+//#region src/records/feature.d.ts
+/** The section blocks of a feature, keyed like `blockSet.blocks`. */
+type FeatureBlocks = Readonly<Record<string, AnyBlock>>;
+/** The `permissions` constant of `blocks.generated.ts`. */
+type FeaturePermissions = Readonly<Record<string, Readonly<Record<string, string>>>>;
+/** A block whose client loads the caller's keys, such as the access block. */
+interface PermissionsBlock extends AnyBlock {
+  readonly create: ((options: never) => {
+    permissions(keys: readonly string[]): AsyncResult<PermissionSet>;
+  }) | undefined;
+}
+/** What `defineRecordFeature` takes. */
+interface RecordFeatureSpec<T extends string, B extends FeatureBlocks> {
+  /** The subject type, such as `"customer"`. */
+  readonly type: T;
+  /** The blocks whose sections the record page shows. */
+  readonly blocks: B;
+  /** `blockConfig` from `blocks.generated.ts`. */
+  readonly config?: GeneratedBlocks;
+  /**
+   * `permissions` from `blocks.generated.ts`, which maps each section's actions
+   * to the keys the `can` flags check.
+   */
+  readonly permissions?: FeaturePermissions;
+  /**
+   * The access block, which loads the caller's keys for the `can` flags.
+   * Without it every flag is `true` and RLS decides.
+   */
+  readonly access?: PermissionsBlock;
+}
+/**
+ * One subject's record page: its sections, the writes each one takes, and what
+ * the caller may do. `gen` writes one per subject (`generateFeatures`); the
+ * framework bindings (`recordServer`, `recordQueries`, `createRecordProvider`)
+ * take it.
+ */
+interface RecordFeature<T extends string = string, B extends FeatureBlocks = FeatureBlocks> extends RecordFeatureSpec<T, B> {
+  /** Every section the blocks declare; the first block wins a name. */
+  readonly sections: readonly SectionName<B>[];
+}
+/** Describes one subject's record page from the blocks that own its sections. */
+declare function defineRecordFeature<const T extends string, const B extends FeatureBlocks>(spec: RecordFeatureSpec<T, B>): RecordFeature<T, B>;
+/** The record a feature's page shows. */
+declare function recordSubject<T extends string>(feature: {
+  readonly type: T;
+}, id: string): SubjectRef<T>;
+/** The writes of the section named `S`, by name. */
+type SectionWritesOf<B extends FeatureBlocks, S extends string> = SectionWriteName<SectionNamed<B, S>>;
+/** What the caller may do on each section: `read` and one flag per write. */
+type RecordCan<B extends FeatureBlocks, N extends string> = { readonly [S in N]: {
+  readonly read: boolean;
+} & { readonly [W in SectionWritesOf<B, S>]: boolean; }; };
+interface WriteFound {
+  readonly key: string;
+  readonly module: string;
+  readonly write: AnySectionWrite;
+  readonly permission: string | undefined;
+}
+/** The block key, module and write that `section.write` names. */
+declare function findSectionWrite(feature: Pick<RecordFeature, "blocks">, section: string, write: string): WriteFound | undefined;
+/**
+ * The permission keys a feature's sections check, for one
+ * `access.permissions(keys)` call.
+ */
+declare function recordPermissionKeys(feature: Pick<RecordFeature, "blocks" | "permissions"> & {
+  readonly sections: readonly string[];
+}): readonly string[];
+/**
+ * What the caller may do on each of a feature's sections, from its
+ * `PermissionSet`. A section action with no key in `permissions` is allowed,
+ * and so is everything when `set` is `undefined` (no access block): RLS and
+ * each function's checks decide.
+ */
+declare function recordCan<B extends FeatureBlocks, N extends SectionName<B>>(feature: Pick<RecordFeature<string, B>, "blocks" | "permissions"> & {
+  readonly sections: readonly N[];
+}, set: PermissionSet | null | undefined): RecordCan<B, N>;
+/** What a generated write takes: the record's id and the write's input. */
+interface RecordWriteInput<I> {
+  readonly id: string;
+  readonly input: I;
+}
+/** The input of one write of a feature's section. */
+type FeatureWriteInput<B extends FeatureBlocks, S extends string, W extends string> = SectionWriteInput<SectionNamed<B, S>, W>;
+/** What one write of a feature's section resolves to. */
+type FeatureWriteOutput<B extends FeatureBlocks, S extends string, W extends string> = SectionWriteOutput<SectionNamed<B, S>, W>;
+/**
+ * A Standard Schema for `{ id, input }`: a non-empty record id and the input
+ * `schema` validates, whose issues get the `input` path.
+ */
+declare function recordWriteInput<I>(schema: StandardSchemaV1<unknown, I>): StandardSchemaV1<unknown, RecordWriteInput<I>>;
+/** A Temporal value, from the runtime or a polyfill. */
+interface TemporalValue {
+  readonly [Symbol.toStringTag]: `Temporal.${string}`;
+  toString(): string;
+}
+/**
+ * `T` with every Temporal value as its ISO 8601 string, so it crosses the
+ * Server Component and Server Action boundary.
+ */
+type Plain<T> = T extends TemporalValue ? string : T extends readonly (infer U)[] ? Plain<U>[] : T extends ((...args: never) => unknown) ? T : T extends object ? { readonly [K in keyof T]: Plain<T[K]>; } : T;
+/**
+ * `value` with every Temporal value replaced by its ISO 8601 string, for data
+ * passed from a Server Component or returned from a Server Action.
+ */
+declare function plainData<T>(value: T): Plain<T>;
+/** A loaded section with Temporal values as strings. */
+type PlainSection<B extends FeatureBlocks, S extends string> = SectionResult<Plain<SectionData<SectionNamed<B, S>>>>;
+/** A feature's loaded sections, by name, with Temporal values as strings. */
+type PlainSections<B extends FeatureBlocks, N extends string> = { readonly [S in N]: PlainSection<B, S>; };
+//#endregion
+//#region src/query/records.d.ts
+/** The first key part of every record query. */
+declare const RECORD_KEY = "bs-record";
+/** Query options for each section of a feature, by section name. */
+type RecordSectionQueries<B extends FeatureBlocks, N extends string> = { readonly [S in N]: (id: string | SkipToken, options?: SectionOptions<SectionNamed<B, S>>) => QueryOptionsOf<SectionData<SectionNamed<B, S>>>; };
+/** Mutation options for each write of each section, by section and write. */
+type RecordWriteMutations<B extends FeatureBlocks, N extends string> = { readonly [S in N]: { readonly [W in SectionWritesOf<B, S>]: (id: string) => MutationOptionsOf<FeatureWriteInput<B, S, W>, FeatureWriteOutput<B, S, W>>; }; };
+interface RecordQueries<T extends string, B extends FeatureBlocks, N extends string> {
+  /** Prefix of every key of this feature's queries. */
+  readonly $key: readonly [typeof RECORD_KEY, T];
+  /** The key of one record's queries, or of one of its sections. */
+  key(id: string, section?: N): readonly unknown[];
+  /** Query options per section, keyed `["bs-record", type, id, section]`. */
+  readonly sections: RecordSectionQueries<B, N>;
+  /**
+   * Mutation options per section write; each one makes the section's queries of
+   * that record stale.
+   */
+  readonly writes: RecordWriteMutations<B, N>;
+  /** What the caller may do on each section, from the `access` client. */
+  can(): QueryOptionsOf<RecordCan<B, N>>;
+}
+interface RecordQueriesOptions extends QueriesOptions {
+  /**
+   * The access block's client, which loads the caller's keys for `can`. Without
+   * it every flag is `true` and RLS decides.
+   */
+  readonly access?: {
+    permissions(keys: readonly string[]): AsyncResult<PermissionSet>;
+  };
+}
+/**
+ * TanStack Query bindings of a generated feature, for apps that load records on
+ * the client (Vite, Expo, TanStack Start): query options per section, mutation
+ * options per section write, and the caller's `can` flags. Pass the block
+ * clients keyed like the feature's blocks, such as `blocks(supabase)` from
+ * `lib/blocks.ts`. A section that fails throws a `DbException`, like
+ * `blockQueries`.
+ *
+ * ```ts
+ * const customer = recordQueries(customerFeature, clients);
+ * const comments = useQuery(customer.sections.comments(id));
+ * const add = useMutation(customer.writes.comments.add(id));
+ * ```
+ */
+declare function recordQueries<T extends string, B extends FeatureBlocks, N extends SectionName<B>>(feature: RecordFeature<T, B> & {
+  readonly sections: readonly N[];
+}, clients: object, options?: RecordQueriesOptions): RecordQueries<T, B, N>;
+/**
+ * Makes a feature's section queries stale when a block event that the section
+ * lists in `events` arrives on `source.events`, for every record of the
+ * feature. Returns a function that stops listening.
+ */
+declare function invalidateOnRecordEvents(queryClient: QueryClient, source: {
+  readonly events: EventHub;
+}, feature: Pick<RecordFeature, "blocks" | "type"> & {
+  readonly sections: readonly string[];
+}): () => 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 { invalidateOnBlockEvents as $, LoadSectionsOptions as A, PermissionFlags as B, defineRecordFeature as C, recordPermissionKeys as D, recordCan as E, SectionNamed as F, BLOCK_READ_PREFIXES as G, can as H, SectionSource as I, BlockInvalidation as J, BlockClientQueries as K, countSection as L, SectionBlocks as M, SectionCheck as N, recordSubject as O, SectionName as P, blockQueries as Q, loadSections as R, SectionWritesOf as S, plainData as T, permissionFlags as U, PermissionSet as V, permissionMatches as W, BlockQueries as X, BlockMethodQuery as Y, BlockVariablesOf as Z, PlainSections as _, RecordQueries as a, MutationOptionsOf as at, RecordFeatureSpec as b, RecordWriteMutations as c, QueryKeyOf as ct, FeatureBlocks as d, createQueries as dt, UserChangeSource as et, FeaturePermissions as f, invalidateOnMutation as ft, PlainSection as g, Plain as h, optimistic as i, InfiniteOptionsOf as it, LoadedSections as j, recordWriteInput as k, invalidateOnRecordEvents as l, QueryOptionsOf as lt, FeatureWriteOutput as m, OptimisticSnapshot as n, BetterQueries as nt, RecordQueriesOptions as o, QueriesOptions as ot, FeatureWriteInput as p, queryCache as pt, BlockClients as q, OptimisticTarget as r, InfiniteExtras as rt, RecordSectionQueries as s, QueryHelpers as st, OptimisticHandlers as t, clearOnUserChange as tt, recordQueries as u, TableQueries as ut, RecordCan as v, findSectionWrite as w, RecordWriteInput as x, RecordFeature as y, sectionCan as z };

package/dist/index-U0o7kU0s.d.ts

@@ -0,0 +1,69 @@
+import { a as Identified, c as InboxListActions, d as InboxWidgetActions, i as ConversationSnapshot, l as InboxListSnapshot, m as InboxWidgetSnapshot, t as ConversationActions, u as InboxSource } from "./client-7_4Y21ue.js";
+//#region src/blocks/inbox/react/index.d.ts
+interface UseInboxOptions<T> {
+  /** The organization; the hook joins `inbox:org:<id>`. `null` waits. */
+  readonly organizationId: string | null;
+  readonly load: InboxSource<T>;
+  /**
+   * `blockConfig.inbox.options.topic` from `blocks.generated.ts`. Defaults to
+   * `inbox`.
+   */
+  readonly topic?: string;
+  /** Runs for each broadcast, e.g. to show a toast for `message`. */
+  readonly onMessage?: (event: string, payload: unknown) => void;
+}
+interface InboxListState<T> extends InboxListSnapshot<T>, InboxListActions {}
+/**
+ * The staff view of an organization's conversations, kept current: loads, then
+ * loads again after each ping on `inbox:org:<id>` and on rejoin.
+ */
+declare function useInbox<T>(options: UseInboxOptions<T>): InboxListState<T>;
+interface UseConversationOptions<T extends Identified> {
+  /** `null` waits, e.g. before the widget opens a conversation. */
+  readonly conversationId: string | null;
+  /** The messages, oldest first: on mount and after a rejoin. */
+  readonly load: InboxSource<T>;
+  /** One message after a ping; `null` when the caller cannot read it. */
+  readonly get: (messageId: string) => Promise<T | null>;
+  /** The messaging topic prefix. Defaults to `messages`. */
+  readonly topic?: string;
+  /** Runs for the other pings, such as `conversation` and `read`. */
+  readonly onEvent?: (event: string, payload: unknown) => void;
+  /** How long a typing ping counts. Defaults to 5000 ms. */
+  readonly typingMs?: number;
+}
+interface ConversationState<T extends Identified> extends ConversationSnapshot<T>, ConversationActions {}
+/**
+ * One conversation's messages, kept current over `messages:<id>`: each ping
+ * fetches the one message it names. Typing pings go between staff and the
+ * contact.
+ */
+declare function useConversation<T extends Identified>(options: UseConversationOptions<T>): ConversationState<T>;
+interface UseInboxWidgetOptions<T extends Identified> {
+  /**
+   * Opens the visitor's conversation, e.g. a server action that calls
+   * `inbox.conversations.open(inboxId, { message })` with the visitor's
+   * transport. Returns its id.
+   */
+  readonly open: (message: string) => Promise<string>;
+  /** Sends into the open conversation. */
+  readonly send: (conversationId: string, message: string) => Promise<void>;
+  readonly load: (conversationId: string) => Promise<readonly T[]>;
+  /** One message after a ping; `null` when the visitor cannot read it. */
+  readonly get: (messageId: string) => Promise<T | null>;
+  /**
+   * Remembers the conversation across reloads in the client's storage port
+   * (`localStorage` on the web). Defaults to `better-supabase:inbox-widget`.
+   */
+  readonly storageKey?: string | null;
+  readonly topic?: string;
+}
+interface InboxWidgetState<T extends Identified> extends InboxWidgetSnapshot<T>, InboxWidgetActions {}
+/**
+ * The visitor side of an in-app inbox: the first message opens the
+ * conversation, later ones go into it, and the messages and typing pings stay
+ * current. Visitors without an account sign in anonymously first.
+ */
+declare function useInboxWidget<T extends Identified>(options: UseInboxWidgetOptions<T>): InboxWidgetState<T>;
+//#endregion
+export { UseInboxOptions as a, useInbox as c, UseConversationOptions as i, useInboxWidget as l, InboxListState as n, UseInboxWidgetOptions as o, InboxWidgetState as r, useConversation as s, ConversationState as t };