better-supabase 0.5.1 → 0.6.0

package/dist/inbox-i7E1ppo6.d.ts

@@ -0,0 +1,384 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { i as CursorPageOptions, r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+//#region src/blocks/inbox/types.d.ts
+/** The channels an inbox can sit on. */
+type InboxChannel = "in_app" | "email" | "slack" | "teams" | "discord" | "telegram" | "whatsapp" | "messenger" | "instagram" | "sms" | "github" | "linear" | "other";
+/** `bot`: the bot answers; `human`: staff answer; `paused`: nobody answers. */
+type BotMode = "bot" | "human" | "paused";
+type ConversationStatus = "open" | "pending" | "snoozed" | "resolved";
+type ConversationPriority = "low" | "normal" | "high" | "urgent";
+type MessageDirection = "inbound" | "outbound";
+type MessageKind = "message" | "note";
+type AuthorType = "contact" | "agent" | "bot" | "system";
+type DeliveryStatus = "queued" | "sent" | "delivered" | "read" | "failed";
+interface InboxRow {
+  readonly id: string;
+  readonly tenant: string;
+  readonly name: string;
+  readonly channel: InboxChannel;
+  readonly address: string | null;
+  readonly installationId: string | null;
+  readonly botMode: BotMode;
+  readonly settings: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly archivedAt: Temporal.Instant | null;
+}
+interface Contact {
+  readonly id: string;
+  readonly tenant?: string;
+  readonly userId: string | null;
+  readonly name: string | null;
+  readonly email: string | null;
+  readonly phone: string | null;
+  readonly avatarUrl: string | null;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface Conversation {
+  readonly id: string;
+  readonly tenant: string;
+  readonly inboxId: string;
+  readonly contactId: string;
+  readonly subject: string | null;
+  readonly status: ConversationStatus;
+  readonly priority: ConversationPriority;
+  readonly assigneeId: string | null;
+  readonly teamId: string | null;
+  readonly botMode: BotMode;
+  /** The Chat SDK thread id, or `inbox:<id>` for the in-app widget. */
+  readonly threadId: string;
+  readonly snoozedUntil: Temporal.Instant | null;
+  readonly lastMessageAt: Temporal.Instant | null;
+  readonly preview: string | null;
+  readonly firstResponseAt: Temporal.Instant | null;
+  readonly resolvedAt: Temporal.Instant | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly contact: Contact | null;
+  readonly inbox: {
+    readonly id: string;
+    readonly name: string;
+    readonly channel: InboxChannel;
+  } | null;
+  /** When the caller last read it. */
+  readonly lastReadAt: Temporal.Instant | null;
+  /** When the contact last read it; `null` for contacts and before they read. */
+  readonly contactReadAt: Temporal.Instant | null;
+  /** In lists: whether a message arrived after `lastReadAt`. */
+  readonly unread?: boolean;
+}
+interface MessageAttachment {
+  readonly path?: string;
+  readonly url?: string;
+  readonly name?: string;
+  readonly contentType?: string;
+  readonly size?: number;
+}
+interface MessageDelivery {
+  readonly channel: string;
+  readonly status: DeliveryStatus;
+  readonly error: string | null;
+}
+interface InboxMessage {
+  readonly id: string;
+  readonly conversationId: string;
+  readonly direction: MessageDirection;
+  readonly kind: MessageKind;
+  readonly authorType: AuthorType;
+  readonly authorId: string | null;
+  readonly body: string;
+  readonly format: "text" | "markdown";
+  readonly attachments: readonly MessageAttachment[];
+  /** Emoji to the actors (user ids or channel ids) who reacted. */
+  readonly reactions: Readonly<Record<string, readonly string[]>>;
+  readonly mentions: readonly string[];
+  readonly externalId: string | null;
+  readonly replyTo: string | null;
+  readonly metadata: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+  readonly editedAt: Temporal.Instant | null;
+  readonly deletedAt: Temporal.Instant | null;
+  readonly delivery?: MessageDelivery | null;
+}
+interface ConversationEvent {
+  readonly id: string;
+  readonly type: string;
+  readonly actorId: string | null;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly createdAt: Temporal.Instant;
+}
+interface InboxCounts {
+  readonly open: number;
+  readonly mine: number;
+  readonly unassigned: number;
+  readonly unread: number;
+}
+/** What `purgeContact` erased. */
+interface PurgedContact {
+  readonly conversations: number;
+  readonly messages: number;
+  /** Storage paths of the erased messages' attachments, for the caller to remove. */
+  readonly attachments: readonly string[];
+}
+interface InboundResult {
+  readonly conversationId: string;
+  readonly messageId: string;
+  readonly contactId: string;
+  readonly tenant: string;
+  /** A new conversation was opened for the thread. */
+  readonly created: boolean;
+  /** The message's `externalId` was already stored. */
+  readonly duplicate: boolean;
+}
+interface MessageTemplate {
+  readonly id: string;
+  readonly tenant: string;
+  readonly inboxId: string | null;
+  readonly name: string;
+  readonly channel: string;
+  readonly language: string;
+  readonly body: string;
+  readonly variables: readonly string[];
+  /** The provider's approved template name (WhatsApp). */
+  readonly externalId: string | null;
+}
+interface StoredInboundEvent {
+  readonly id: string;
+  readonly adapter: string;
+  readonly externalId: string | null;
+  readonly inboxId: string | null;
+  readonly tenant: string | null;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly attempts: number;
+  readonly receivedAt: Temporal.Instant;
+}
+//#endregion
+//#region src/blocks/inbox/inbox.d.ts
+interface InboxOptions extends BlockTemporalOptions {
+  /**
+   * `sqlTransport(postgres.asUser(claims))` or `rpcTransport(supabase)` for a
+   * member or a contact; over the service role for webhooks and workers.
+   */
+  readonly transport: BlockTransport;
+  /** `sql.modules.inbox.schema`. Defaults to `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+}
+interface CreateInboxInput {
+  readonly tenant: string;
+  readonly name: string;
+  readonly channel?: InboxChannel;
+  /** The channel's address: a phone number, a Slack team id, an email. */
+  readonly address?: string;
+  readonly botMode?: BotMode;
+  /** `widget: true` lets signed-in visitors open conversations in an in-app inbox. */
+  readonly settings?: Readonly<Record<string, unknown>>;
+}
+interface InboxPatch {
+  readonly name?: string;
+  readonly botMode?: BotMode;
+  readonly settings?: Readonly<Record<string, unknown>>;
+  readonly address?: string | null;
+  readonly installationId?: string | null;
+  readonly archived?: boolean;
+}
+interface ContactInput {
+  readonly id?: string;
+  readonly userId?: string;
+  readonly name?: string;
+  readonly email?: string;
+  readonly phone?: string;
+  readonly avatarUrl?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** The contact's id on a channel, such as a WhatsApp number. */
+  readonly identity?: {
+    readonly channel: string;
+    readonly externalId: string;
+  };
+}
+interface MessageInput {
+  readonly body: string;
+  /** `note` is an internal note only staff see. */
+  readonly kind?: "message" | "note";
+  readonly format?: "text" | "markdown";
+  readonly attachments?: readonly MessageAttachment[];
+  /** User ids; those who cannot read the inbox are dropped. */
+  readonly mentions?: readonly string[];
+  readonly replyTo?: string;
+  readonly externalId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  /** For the service: who writes. Defaults to `bot`. */
+  readonly authorType?: "contact" | "bot" | "system";
+  /** For the service: the caller posts to the channel itself, so no outbound job is queued. */
+  readonly deliveredByCaller?: boolean;
+}
+interface StartConversationInput {
+  /**
+   * A contact id or the fields to find or create one. Leave it out on a
+   * widget inbox to open the conversation as the signed-in visitor, staff
+   * included.
+   */
+  readonly contact?: string | ContactInput;
+  readonly subject?: string;
+  readonly priority?: ConversationPriority;
+  readonly botMode?: BotMode;
+  /** The Chat SDK thread id. Defaults to `inbox:<conversation id>`. */
+  readonly threadId?: string;
+  readonly assigneeId?: string;
+  readonly metadata?: Readonly<Record<string, unknown>>;
+  readonly message?: string | MessageInput;
+}
+interface InboundInput {
+  readonly inboxId: string;
+  readonly threadId: string;
+  readonly contact: ContactInput & {
+    /** Shorthand for `identity` on the inbox's channel. */
+    readonly externalId?: string;
+  };
+  readonly message: Omit<MessageInput, "kind" | "authorType">;
+  readonly subject?: string;
+  /** `outbound` records a message sent from the platform by someone else. */
+  readonly direction?: "inbound" | "outbound";
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+interface ConversationFilter extends CursorPageOptions<Pick<Conversation, "id" | "lastMessageAt">> {
+  readonly inboxId?: string;
+  /** Defaults to `open`. */
+  readonly status?: ConversationStatus | "all";
+  readonly assignee?: "me" | "unassigned" | (string & {});
+  readonly teamId?: string;
+  readonly contactId?: string;
+  readonly search?: string;
+  /** The last item of the previous page. */
+  readonly cursor?: Pick<Conversation, "id" | "lastMessageAt">;
+  /** Up to 200. Defaults to 50. */
+  readonly limit?: number;
+}
+interface TemplateInput {
+  readonly name: string;
+  readonly channel: string;
+  readonly body: string;
+  readonly language?: string;
+  readonly inboxId?: string;
+  readonly variables?: readonly string[];
+  readonly externalId?: string;
+}
+/** The `inbox` SQL module as typed calls. */
+interface Inbox {
+  readonly inboxes: {
+    create(input: CreateInboxInput): AsyncResult<InboxRow>;
+    update(id: string, patch: InboxPatch): AsyncResult<InboxRow>;
+    /** `null` removes the member. */
+    setMember(inboxId: string, userId: string, role: "agent" | "lead" | null): AsyncResult<boolean>;
+    createTeam(tenant: string, name: string): AsyncResult<{
+      readonly id: string;
+      readonly name: string;
+    }>;
+    setTeamMember(teamId: string, userId: string, present?: boolean): AsyncResult<boolean>;
+  };
+  readonly contacts: {
+    /** Finds the contact by id, identity, user or email, filling in what is missing. */
+    upsert(tenant: string, input: ContactInput): AsyncResult<Contact>;
+  };
+  readonly conversations: {
+    open(inboxId: string, input?: StartConversationInput): AsyncResult<Conversation>;
+    list(tenant: string | null, filter?: ConversationFilter): AsyncResult<readonly Conversation[]>;
+    get(conversationId: string): AsyncResult<Conversation | null>;
+    assign(conversationId: string, to: {
+      readonly assigneeId: string | null;
+      readonly teamId?: string | null;
+    }): AsyncResult<Conversation>;
+    setStatus(conversationId: string, status: ConversationStatus, options?: {
+      readonly snoozedUntil?: Temporal.Instant;
+    }): AsyncResult<Conversation>;
+    snooze(conversationId: string, until: Temporal.Instant): AsyncResult<Conversation>;
+    resolve(conversationId: string): AsyncResult<Conversation>;
+    reopen(conversationId: string): AsyncResult<Conversation>;
+    /** Hands a bot conversation to staff (`bot_mode = 'human'`) and tells them. */
+    handoff(conversationId: string, reason?: string): AsyncResult<Conversation>;
+    setBotMode(conversationId: string, mode: BotMode, reason?: string): AsyncResult<Conversation>;
+    markRead(conversationId: string): AsyncResult<Temporal.Instant>;
+    /** A typing ping on `inbox:<id>`; the service names the bot in `actor`. */
+    typing(conversationId: string, typing?: boolean, actor?: string): AsyncResult<boolean>;
+    events(conversationId: string): AsyncResult<readonly ConversationEvent[]>;
+    counts(tenant: string): AsyncResult<InboxCounts>;
+  };
+  readonly messages: {
+    send(conversationId: string, input: MessageInput): AsyncResult<InboxMessage>;
+    /** An internal note only staff see. */
+    note(conversationId: string, body: string, input?: Pick<MessageInput, "mentions" | "attachments" | "format">): AsyncResult<InboxMessage>;
+    list(conversationId: string, options?: CursorPageOptions<Temporal.Instant>): AsyncResult<readonly InboxMessage[]>;
+    get(messageId: string): AsyncResult<InboxMessage | null>;
+    edit(messageId: string, body: string): AsyncResult<InboxMessage>;
+    /** Leaves a tombstone with an empty body. */
+    remove(messageId: string): AsyncResult<InboxMessage>;
+    react(messageId: string, emoji: string, options?: {
+      readonly present?: boolean;
+      readonly actor?: string;
+    }): AsyncResult<Readonly<Record<string, readonly string[]>>>;
+  };
+  readonly deliveries: {
+    /** Service only: after posting a message on its channel. */
+    record(input: {
+      readonly messageId: string;
+      readonly channel: string;
+      readonly externalId?: string;
+      readonly status?: DeliveryStatus;
+      readonly error?: string;
+    }): AsyncResult<void>;
+    /** Service only: a status callback; returns how many deliveries moved. */
+    setStatus(input: {
+      readonly channel: string;
+      readonly externalId: string;
+      readonly status: DeliveryStatus;
+      readonly error?: string;
+    }): AsyncResult<number>;
+  };
+  readonly templates: {
+    upsert(tenant: string, input: TemplateInput): AsyncResult<MessageTemplate>;
+    delete(id: string): AsyncResult<boolean>;
+  };
+  /** Service only: channel messages, the webhook store and its sweeps. */
+  readonly inbound: {
+    /** A message that arrived on a channel: finds or opens the thread's conversation. */
+    record(input: InboundInput): AsyncResult<InboundResult>;
+    store(input: {
+      readonly adapter: string;
+      readonly body: string;
+      readonly externalId?: string;
+      readonly headers?: Readonly<Record<string, string>>;
+      readonly inboxId?: string;
+      readonly tenant?: string;
+    }): AsyncResult<{
+      readonly id: string;
+      readonly duplicate: boolean;
+    }>;
+    setStatus(id: string, status: "processing" | "processed" | "ignored" | "failed", error?: string): AsyncResult<boolean>;
+    pending(options?: {
+      readonly limit?: number;
+      readonly maxAttempts?: number;
+    }): AsyncResult<readonly StoredInboundEvent[]>;
+    purge(options?: {
+      readonly olderThan?: number | string;
+      readonly batch?: number;
+    }): AsyncResult<number>;
+  };
+  /** Service only: reopens snoozed conversations whose time came. */
+  wakeSnoozed(): AsyncResult<number>;
+  /**
+   * Erases a contact and its conversations for a data subject request
+   * (`inbox.manage` or the service). Remove the returned attachment paths
+   * from Storage afterwards.
+   */
+  purgeContact(contactId: string): AsyncResult<PurgedContact>;
+}
+/**
+ * The `inbox` SQL module as typed calls: inboxes, contacts, conversations,
+ * messages and notes, assignment, bot hand-off, read state, deliveries and
+ * the stored webhook events. The database checks every permission.
+ */
+declare function createInbox(options: InboxOptions): Inbox;
+//#endregion
+export { PurgedContact as A, InboxMessage as C, MessageDirection as D, MessageDelivery as E, MessageKind as O, InboxCounts as S, MessageAttachment as T, ConversationPriority as _, Inbox as a, InboundResult as b, MessageInput as c, createInbox as d, AuthorType as f, ConversationEvent as g, Conversation as h, InboundInput as i, StoredInboundEvent as j, MessageTemplate as k, StartConversationInput as l, Contact as m, ConversationFilter as n, InboxOptions as o, BotMode as p, CreateInboxInput as r, InboxPatch as s, ContactInput as t, TemplateInput as u, ConversationStatus as v, InboxRow as w, InboxChannel as x, DeliveryStatus as y };

package/dist/index-ACiNPN4Z.d.ts

@@ -0,0 +1,74 @@
+import { x as SubscriptionStatus } from "./index-DunNRdnT.js";
+//#region src/blocks/inbox/react/index.d.ts
+/** Loads one list, e.g. a server action that calls `inbox.conversations.list()`. */
+type InboxSource<T> = () => Promise<readonly T[]>;
+interface UseInboxOptions<T> {
+  /** The organization; the hook joins `inbox:org:<id>`. `null` waits. */
+  readonly organizationId: string | null;
+  readonly load: InboxSource<T>;
+  /** `sql.modules.inbox.options.topic`. 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> {
+  /** `undefined` until the first load. */
+  readonly items: readonly T[] | undefined;
+  readonly status: SubscriptionStatus;
+  readonly error: unknown;
+  readonly refresh: () => Promise<void>;
+}
+/**
+ * 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> {
+  /** `null` waits, e.g. before the widget opens a conversation. */
+  readonly conversationId: string | null;
+  /** The messages, oldest first. */
+  readonly load: InboxSource<T>;
+  readonly topic?: string;
+  /** How long a typing ping counts. Defaults to 5000 ms. */
+  readonly typingMs?: number;
+}
+interface ConversationState<T> extends InboxListState<T> {
+  /** User ids typing now, the caller left out. */
+  readonly typing: readonly string[];
+  /** Tells the others the caller is typing; call it on input, throttled. */
+  readonly setTyping: (typing: boolean) => void;
+}
+/**
+ * One conversation's messages, kept current over `inbox:<id>`, with typing
+ * pings between staff and the contact. Notes never reach this topic.
+ */
+declare function useConversation<T>(options: UseConversationOptions<T>): ConversationState<T>;
+interface UseInboxWidgetOptions<T> {
+  /**
+   * 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[]>;
+  /** Remembers the conversation across reloads. Defaults to `better-supabase:inbox-widget`. */
+  readonly storageKey?: string | null;
+  readonly topic?: string;
+}
+interface InboxWidgetState<T> extends ConversationState<T> {
+  readonly conversationId: string | null;
+  /** Opens the conversation with the first message, or sends into it. */
+  readonly submit: (message: string) => Promise<void>;
+  /** Forgets the conversation, so the next message opens a new one. */
+  readonly reset: () => void;
+}
+/**
+ * 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>(options: UseInboxWidgetOptions<T>): InboxWidgetState<T>;
+//#endregion
+export { UseConversationOptions as a, useConversation as c, InboxWidgetState as i, useInbox as l, InboxListState as n, UseInboxOptions as o, InboxSource as r, UseInboxWidgetOptions as s, ConversationState as t, useInboxWidget as u };

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 };