better-supabase 0.12.0 → 0.13.0

package/dist/channel-BjvGO39m.d.ts

@@ -0,0 +1,77 @@
+/// <reference lib="esnext.temporal" />
+//#region src/blocks/notifications/types.d.ts
+/** A subject a notification is about, e.g. `{ type: 'task', id: '42' }`. */
+interface NotificationSubject {
+  readonly type: string;
+  readonly id: string;
+  /** Shown in the list, e.g. the task title, kept as it was at send time. */
+  readonly label?: string;
+}
+/** One notification as its recipient sees it. */
+interface NotificationItem<K extends string = string, D = unknown> {
+  /** The recipient row id: pass it to `markRead` and `dismiss`. */
+  readonly id: string;
+  /** The shared event id, the same for every recipient. */
+  readonly eventId: string;
+  readonly type: K;
+  readonly data: D;
+  readonly tenant: string | null;
+  readonly actorId: string | null;
+  readonly subject: NotificationSubject | null;
+  readonly summary: string | null;
+  readonly actionPath: string | null;
+  readonly priority: string | null;
+  readonly createdAt: Temporal.Instant;
+  readonly readAt: Temporal.Instant | null;
+  readonly resolvedAt: Temporal.Instant | null;
+  /** The events table's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: Readonly<Record<string, unknown>>;
+}
+/** What `render` returns: the text for one notification, in one locale. */
+interface RenderedText {
+  readonly title: string;
+  readonly body?: string;
+}
+//#endregion
+//#region src/blocks/notifications/channel.d.ts
+/** One pending delivery a channel sends: the notification and who gets it. */
+interface NotificationMessage {
+  readonly deliveryId: string;
+  /** The channel name, e.g. `email`. */
+  readonly channel: string;
+  /** 1 on the first try. */
+  readonly attempts: number;
+  readonly userId: string;
+  /** The recipient's `auth.users` email, for email channels. */
+  readonly email: string | null;
+  readonly notification: NotificationItem;
+  /** What `render` returned for it, when `createNotifications` has one. */
+  readonly text?: RenderedText;
+}
+interface NotificationSendResult {
+  /** `skipped` when the channel decided not to send. Defaults to `sent`. */
+  readonly status?: "sent" | "skipped";
+  /** The provider's name, e.g. `resend` or `fcm`. */
+  readonly provider?: string;
+  /** The provider's id for the message, kept for support and webhooks. */
+  readonly providerMessageId?: string;
+  /**
+   * The template the message was built from, e.g. `task-assigned-v2`, stored on
+   * the delivery for `subjectDeliveries`. Needs notifications module version 6.
+   */
+  readonly templateKey?: string;
+}
+/**
+ * Sends notifications on one channel (email, push, Slack). The delivery worker
+ * (`notifications.deliver()`) claims pending deliveries for the channel's
+ * `name` and calls `send` for each. Throwing retries the delivery after its
+ * lease, up to `maxAttempts`, then marks it `failed`.
+ */
+interface NotificationChannel {
+  readonly apiVersion: 1;
+  /** Matches the `channel` the deliveries were created for. */
+  readonly name: string;
+  send(message: NotificationMessage): NotificationSendResult | void | Promise<NotificationSendResult | void>;
+}
+//#endregion
+export { NotificationSubject as a, NotificationItem as i, NotificationMessage as n, RenderedText as o, NotificationSendResult as r, NotificationChannel as t };

package/dist/channels-CfcFPuo_.js

@@ -0,0 +1,114 @@
+import { t as refreshRealtimeAuth } from "./auth-DyF_LRxd.js";
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/channels.ts
+const topicChannels = /* @__PURE__ */ new WeakMap();
+/**
+* One channel per topic and client, shared by every `subscribe()` on it:
+* supabase-js hands back the open channel for a topic, so a second join or an
+* early `removeChannel` would break the first subscription.
+*/
+function joinTopic(client, topic, isPrivate, self, presence, subscriber) {
+	let byTopic = topicChannels.get(client);
+	if (!byTopic) {
+		byTopic = /* @__PURE__ */ new Map();
+		topicChannels.set(client, byTopic);
+	}
+	const topics = byTopic;
+	let shared = topics.get(topic);
+	if (shared && shared.self !== self) throw new TypeError(`better-supabase: "${topic}" is already subscribed with self: ${String(shared.self)}; every subscription on a topic needs the same \`self\``);
+	if (shared && shared.presence !== presence) throw new TypeError(`better-supabase: "${topic}" is already subscribed ${shared.presence ? "with" : "without"} presence; every topic definition for it needs the same \`presence\``);
+	if (!shared) {
+		const channel = client.channel(topic, { config: {
+			private: isPrivate,
+			broadcast: { self }
+		} });
+		const subscribers = /* @__PURE__ */ new Set();
+		const status = (next, error) => {
+			for (const each of subscribers) each.onStatus?.(next, error);
+		};
+		channel.on("broadcast", { event: "*" }, (raw) => {
+			const message = {
+				event: raw.event,
+				payload: raw["payload"],
+				topic
+			};
+			for (const each of subscribers) each.receive(message);
+		});
+		if (presence) channel.on("presence", { event: "sync" }, () => {
+			entry.synced = true;
+			const state = channel.presenceState();
+			for (const each of subscribers) each.sync?.(state);
+		});
+		const evict = () => {
+			if (topics.get(topic) !== entry) return;
+			topics.delete(topic);
+			client.removeChannel(channel);
+		};
+		const ready = (async () => {
+			await (isPrivate ? refreshRealtimeAuth(client) : void 0);
+			if (subscribers.size === 0) return;
+			await new Promise((resolve, reject) => {
+				channel.subscribe((state, error) => {
+					if (topics.get(topic) !== entry) return;
+					switch (state) {
+						case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+							entry.subscribed = true;
+							status("subscribed");
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CLOSED:
+							entry.subscribed = false;
+							status("closed");
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+						case REALTIME_SUBSCRIBE_STATES.TIMED_OUT: {
+							const failure = error ?? /* @__PURE__ */ new Error(`Realtime ${state.toLowerCase()} on ${topic}`);
+							status("error", failure);
+							reject(failure);
+							if (!entry.subscribed) evict();
+							return;
+						}
+						default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(state)}`));
+					}
+				});
+			});
+		})();
+		ready.catch(() => void 0);
+		const entry = {
+			channel,
+			self,
+			presence,
+			subscribers,
+			ready,
+			subscribed: false,
+			synced: false,
+			tracker: void 0
+		};
+		shared = entry;
+		topics.set(topic, entry);
+	}
+	const current = shared;
+	current.subscribers.add(subscriber);
+	subscriber.onStatus?.("joining");
+	if (current.subscribed) subscriber.onStatus?.("subscribed");
+	if (current.synced) subscriber.sync?.(current.channel.presenceState());
+	return {
+		shared: current,
+		leave: async () => {
+			current.subscribers.delete(subscriber);
+			if (current.subscribers.size > 0) {
+				if (current.tracker === subscriber) {
+					current.tracker = void 0;
+					await current.channel.untrack();
+				}
+				return;
+			}
+			if (topics.get(topic) !== current) return;
+			topics.delete(topic);
+			await client.removeChannel(current.channel);
+		}
+	};
+}
+//#endregion
+export { joinTopic as t };

package/dist/chat-sdk/index.d.ts

@@ -1,10 +1,10 @@
 /// <reference lib="esnext.temporal" />
-import { T as ErrorMapper, t as AsyncResult } from "../result-BREt7qOh.js";
-import { a as CredentialSubject, i as CredentialRef, o as CredentialToken, r as CredentialProvider } from "../provider-DXgx5oSA.js";
-import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../block-transport-DezJPPA0.js";
-import { o as StreamStore } from "../store-B18bIvKc.js";
-import { c as ChatActionHook, d as IdentityRef, f as IdentityTarget, i as AuthorizationHooks, p as PrincipalByIdentity, s as ChatAction, t as ApprovalRequestRef } from "../authorization-hooks-WDQMKIsc.js";
-import { E as MessageAttachment, M as StoredInboundEvent, a as Inbox, b as DeliveryStatus, g as Conversation, w as InboxMessage, x as InboundResult } from "../inbox-Du5aPwKB.js";
+import { T as ErrorMapper, t as AsyncResult } from "../result-mijqfoJN.js";
+import { a as CredentialSubject, i as CredentialRef, o as CredentialToken, r as CredentialProvider } from "../provider-Dmsbl8ug.js";
+import { a as dbTransport, o as rpcTransport, s as sqlTransport, t as BlockTransport } from "../block-transport-DBPhgF3W.js";
+import { o as StreamStore } from "../store-DKqbuNvw.js";
+import { c as ChatActionHook, d as IdentityRef, f as IdentityTarget, i as AuthorizationHooks, p as PrincipalByIdentity, s as ChatAction, t as ApprovalRequestRef } from "../authorization-hooks-HXVZXxUk.js";
+import { E as MessageAttachment, M as StoredInboundEvent, a as Inbox, b as DeliveryStatus, g as Conversation, w as InboxMessage, x as InboundResult } from "../inbox-CLsIrPXs.js";
 import { Adapter, AdapterPostableMessage, Attachment, Author, Message, RawMessage, StateAdapter, WebhookOptions } from "chat";
 //#region src/chat-sdk/delivery.d.ts
 /** One status callback for a message the bot sent on a channel. */
@@ -21,16 +21,25 @@ interface ParsedDeliveries {
   readonly updates: readonly DeliveryUpdate[];
   readonly only: boolean;
 }
-/** Reads delivery statuses from a stored webhook event; `null` when the body is not one it knows. */
+/**
+ * Reads delivery statuses from a stored webhook event; `null` when the body is
+ * not one it knows.
+ */
 type DeliveryParser = (event: {
   readonly body: string;
   readonly headers: Readonly<Record<string, string>>;
 }) => ParsedDeliveries | null;
 /** WhatsApp Cloud API: `entry[].changes[].value.statuses[]`. */
 export declare const whatsappDeliveries: DeliveryParser;
-/** Messenger and Instagram: `entry[].messaging[].delivery.mids`. Read receipts carry no ids and are skipped. */
+/**
+ * Messenger and Instagram: `entry[].messaging[].delivery.mids`. Read receipts
+ * carry no ids and are skipped.
+ */
 export declare const messengerDeliveries: DeliveryParser;
-/** Twilio status callbacks: a form body with `MessageSid` and `MessageStatus` and no `Body`. */
+/**
+ * Twilio status callbacks: a form body with `MessageSid` and `MessageStatus`
+ * and no `Body`.
+ */
 export declare const twilioDeliveries: DeliveryParser;
 /** The parsers `inboundHandler` uses by default, keyed by adapter name. */
 export declare const DELIVERY_PARSERS: Readonly<Record<string, DeliveryParser>>;
@@ -47,10 +56,16 @@ interface ChannelAdapterOptions<A> {
   /** The install's `credential_ref`, from `installations.get`. */
   readonly ref: CredentialRef;
   readonly subject?: CredentialSubject;
-  /** Builds the platform adapter with the token, e.g. `(t) => createSlackAdapter({ botToken: t.token })`. */
+  /**
+   * Builds the platform adapter with the token, e.g. `(t) =>
+   * createSlackAdapter({ botToken: t.token })`.
+   */
   readonly create: (token: CredentialToken) => A | Promise<A>;
 }
-/** A platform adapter built from the token the credential provider holds, so no secret sits in env. */
+/**
+ * A platform adapter built from the token the credential provider holds, so no
+ * secret sits in env.
+ */
 export declare function channelAdapter<A>(options: ChannelAdapterOptions<A>): Promise<A>;
 interface InboxWebhookOptions {
   /** `createInbox` on a service transport. */
@@ -59,10 +74,16 @@ interface InboxWebhookOptions {
   readonly adapter: string;
   readonly inboxId?: string;
   readonly tenant?: string;
-  /** With `ref`, checks the request with `credentials.verifyInbound` before storing it. */
+  /**
+   * With `ref`, checks the request with `credentials.verifyInbound` before
+   * storing it.
+   */
   readonly credentials?: CredentialProvider;
   readonly ref?: CredentialRef;
-  /** Checks the request when no credential ref does. Without either, every request is stored. */
+  /**
+   * Checks the request when no credential ref does. Without either, every
+   * request is stored.
+   */
   readonly verify?: (request: Request, body: string) => boolean | Promise<boolean>;
   /** The platform's event id, so a retried delivery is stored once. */
   readonly externalId?: (body: string, request: Request) => string | undefined;
@@ -81,10 +102,9 @@ interface InboxWebhookOptions {
   }) => void;
 }
 /**
- * A route handler that verifies a channel webhook, stores the raw event in
- * the inbox's `inbound_events` and answers 200 at once. `inboundHandler`
- * replays it into Chat SDK later, so a slow bot never makes the platform
- * retry.
+ * A route handler that verifies a channel webhook, stores the raw event in the
+ * inbox's `inbound_events` and answers 200 at once. `inboundHandler` replays it
+ * into Chat SDK later, so a slow bot never makes the platform retry.
  */
 export declare function webhook(options: InboxWebhookOptions): (request: Request) => Promise<Response>;
 /** The thread a Chat SDK handler gets, as much as `mirror` needs. */
@@ -100,18 +120,24 @@ interface InboundHandlerOptions {
   readonly inbox: Inbox;
   /** The inbox each adapter's threads land in, by adapter name. */
   readonly inboxes: Readonly<Record<string, string>>;
-  /** Delivery status parsers by adapter name. Defaults to WhatsApp, Messenger, Instagram and Twilio. */
+  /**
+   * Delivery status parsers by adapter name. Defaults to WhatsApp, Messenger,
+   * Instagram and Twilio.
+   */
   readonly parsers?: Readonly<Record<string, DeliveryParser>>;
   /**
-   * Copies a platform file into storage for the inbox. Without it a file
-   * is kept only when it has a public URL; platform URLs often need the
-   * bot's token, so copy them.
+   * Copies a platform file into storage for the inbox. Without it a file is
+   * kept only when it has a public URL; platform URLs often need the bot's
+   * token, so copy them.
    */
   readonly copyFile?: (file: Attachment, context: {
     readonly adapter: string;
     readonly threadId: string;
   }) => Promise<MessageAttachment | null>;
-  /** The URL replayed requests carry. Defaults to `https://inbox.local/<adapter>`. */
+  /**
+   * The URL replayed requests carry. Defaults to
+   * `https://inbox.local/<adapter>`.
+   */
   readonly baseUrl?: string;
 }
 interface DrainResult {
@@ -119,7 +145,10 @@ interface DrainResult {
   readonly failed: number;
 }
 interface InboundHandler {
-  /** Replays one stored event: delivery statuses go to the inbox, the rest into Chat SDK. */
+  /**
+   * Replays one stored event: delivery statuses go to the inbox, the rest into
+   * Chat SDK.
+   */
   process(event: StoredInboundEvent): Promise<void>;
   /** Processes pending events, oldest first. */
   drain(options?: {
@@ -127,9 +156,9 @@ interface InboundHandler {
     readonly maxAttempts?: number;
   }): Promise<DrainResult>;
   /**
-   * Records a channel message in the inbox, from a Chat SDK handler. Skips
-   * bot messages, its own and the ones `deliver` posted (their echo);
-   * returns `null` for those.
+   * Records a channel message in the inbox, from a Chat SDK handler. Skips bot
+   * messages, its own and the ones `deliver` posted (their echo); returns
+   * `null` for those.
    */
   mirror(thread: MirrorThread, message: Message): Promise<InboundResult | null>;
 }
@@ -145,12 +174,15 @@ interface DeliverOptions {
   readonly chat: ChatLike;
   /** `createInbox` on a service transport. */
   readonly inbox: Inbox;
-  /** The adapter that posts a conversation's replies. Defaults to the inbox's channel (`sms` posts with `twilio`). */
+  /**
+   * The adapter that posts a conversation's replies. Defaults to the inbox's
+   * channel (`sms` posts with `twilio`).
+   */
   readonly adapterFor?: (conversation: Conversation) => string;
   /**
-   * The approved template to send when the channel's reply window is
-   * closed, such as WhatsApp's 24 hours after the contact's last message.
-   * Return `null` to post the message as is.
+   * The approved template to send when the channel's reply window is closed,
+   * such as WhatsApp's 24 hours after the contact's last message. Return `null`
+   * to post the message as is.
    */
   readonly template?: (context: {
     readonly conversation: Conversation;
@@ -158,13 +190,16 @@ interface DeliverOptions {
     readonly adapter: Adapter;
   }) => Promise<AdapterPostableMessage | null> | AdapterPostableMessage | null;
 }
-/** True while WhatsApp's customer service window is open: within 24 hours of the contact's last message. */
+/**
+ * True while WhatsApp's customer service window is open: within 24 hours of the
+ * contact's last message.
+ */
 export declare function whatsappWindowOpen(inbox: Inbox, conversationId: string, now?: Temporal.Instant): Promise<boolean>;
 /**
- * Posts a staff reply the `inbox` module queued on its channel, records
- * the delivery with the platform's message id, and remembers the id so
- * `mirror` skips the platform's echo. A failed post is recorded and thrown,
- * so the job retries.
+ * Posts a staff reply the `inbox` module queued on its channel, records the
+ * delivery with the platform's message id, and remembers the id so `mirror`
+ * skips the platform's echo. A failed post is recorded and thrown, so the job
+ * retries.
  */
 export declare function deliver(options: DeliverOptions): (job: InboxOutboundJob) => Promise<RawMessage | null>;
 interface MaintainOptions {
@@ -172,7 +207,10 @@ interface MaintainOptions {
   readonly inbox: Inbox;
   /** Replays events a crashed request left pending. */
   readonly handler?: InboundHandler;
-  /** `createSupabaseState(...)`: deletes expired locks, cache rows, lists and queues. */
+  /**
+   * `createSupabaseState(...)`: deletes expired locks, cache rows, lists and
+   * queues.
+   */
   readonly state?: {
     purge(options?: {
       readonly batch?: number;
@@ -187,7 +225,10 @@ interface MaintainResult {
   readonly replayed: DrainResult;
   readonly purgedState: number;
 }
-/** The inbox's periodic work: wake snoozed conversations, replay and purge webhook events, sweep state. Run it from a cron job. */
+/**
+ * The inbox's periodic work: wake snoozed conversations, replay and purge
+ * webhook events, sweep state. Run it from a cron job.
+ */
 export declare function maintain(options: MaintainOptions): Promise<MaintainResult>;
 //#endregion
 //#region src/chat-sdk/identity.d.ts
@@ -195,22 +236,31 @@ export declare function maintain(options: MaintainOptions): Promise<MaintainResu
 interface ChatIdentityOptions {
   /** Wins over `server.authorization.identities.principalByIdentity`. */
   readonly principalByIdentity?: PrincipalByIdentity;
-  /** `createServer(...)`: its `authorization` hooks fill the slots this call leaves out. */
+  /**
+   * `createServer(...)`: its `authorization` hooks fill the slots this call
+   * leaves out.
+   */
   readonly server?: {
     readonly authorization: AuthorizationHooks | undefined;
   };
 }
 /**
- * The `IdentityRef` of a Chat SDK author: `kind: "chat"`, the adapter name
- * as the provider and the platform's user id. Pass `workspace` (a Slack
- * team id) when one app serves several workspaces.
+ * The `IdentityRef` of a Chat SDK author: `kind: "chat"`, the adapter name as
+ * the provider and the platform's user id. Pass `workspace` (a Slack team id)
+ * when one app serves several workspaces.
  */
 export declare function chatIdentityOf(author: Pick<Author, "userId">, adapter: {
   readonly name: string;
 }, workspace?: string): IdentityRef;
-/** The user or contact `identity` is linked to; `null` without a resolver or a link. */
+/**
+ * The user or contact `identity` is linked to; `null` without a resolver or a
+ * link.
+ */
 export declare function resolveChatAuthor(identity: IdentityRef, options: ChatIdentityOptions): Promise<IdentityTarget | null>;
-/** What a bot job is enqueued with: a ticket for a linked user, nothing otherwise. */
+/**
+ * What a bot job is enqueued with: a ticket for a linked user, nothing
+ * otherwise.
+ */
 interface BotJobEnqueueOptions {
   readonly ticket?: string;
 }
@@ -222,9 +272,8 @@ interface BotJobsOptions<P, R> extends ChatIdentityOptions {
    */
   readonly enqueue: (payload: P, options: BotJobEnqueueOptions) => R;
   /**
-   * Issues the opaque ticket the job runs as for a linked user. The
-   * provider's `tickets.subject` turns it back into that user's context
-   * in `forContext`.
+   * Issues the opaque ticket the job runs as for a linked user. The provider's
+   * `tickets.subject` turns it back into that user's context in `forContext`.
    */
   readonly ticketFor: (userId: string) => string | Promise<string>;
 }
@@ -237,9 +286,9 @@ interface EnqueuedBotJob<R> {
 interface BotJobs<P, R> {
   /**
    * Resolves the author, then enqueues `payload` with a ticket for a linked
-   * user. An unlinked author, or one linked to a contact, gets no ticket
-   * and no user context; the job never falls back to the bot's service
-   * role. A resolver or ticket error rejects without enqueuing.
+   * user. An unlinked author, or one linked to a contact, gets no ticket and no
+   * user context; the job never falls back to the bot's service role. A
+   * resolver or ticket error rejects without enqueuing.
    */
   enqueue(author: IdentityRef, payload: P): Promise<EnqueuedBotJob<R>>;
 }
@@ -259,7 +308,10 @@ type ChatActionRefusal = "unlinked" | "unhandled" | "refused" | "error";
 type ChatActionDecision = {
   readonly allowed: true;
   readonly author: IdentityTarget;
-  /** The user who acts: the linked author, or the user the hook named for a contact. */
+  /**
+   * The user who acts: the linked author, or the user the hook named for a
+   * contact.
+   */
   readonly userId?: string;
 } | {
   readonly allowed: false;
@@ -270,10 +322,10 @@ interface ChatActionsOptions extends ChatIdentityOptions {
   readonly onAction?: ChatActionHook;
 }
 /**
- * Decides a chat button press through the provider: the author is
- * resolved, then `onAction(action, author)` runs. Everything but
- * `allowed: true` refuses, and an unlinked author is refused before the
- * hook runs. Act on the decision, never on the button alone.
+ * Decides a chat button press through the provider: the author is resolved,
+ * then `onAction(action, author)` runs. Everything but `allowed: true` refuses,
+ * and an unlinked author is refused before the hook runs. Act on the decision,
+ * never on the button alone.
  */
 export declare function chatActions(options: ChatActionsOptions): (action: ChatAction) => Promise<ChatActionDecision>;
 interface ApprovalPromptOptions {
@@ -287,8 +339,8 @@ interface ApprovalPromptOptions {
 }
 /**
  * The approval page URL for `request`, with `kind` and `subject` as query
- * parameters. Opening it approves nothing: the signed-in approver decides
- * on the page, and the page's server action or POST route checks them.
+ * parameters. Opening it approves nothing: the signed-in approver decides on
+ * the page, and the page's server action or POST route checks them.
  */
 export declare function approvalLink(page: string | URL, request: ApprovalRequestRef): string;
 /** A chat message that links to the approval page, for `thread.post`. */
@@ -297,7 +349,10 @@ export declare function approvalPrompt(options: ApprovalPromptOptions): {
 };
 //#endregion
 //#region src/chat-sdk/inbox-adapter.d.ts
-/** The job the `inbox` module queues for a contact message while `bot_mode = 'bot'`. */
+/**
+ * The job the `inbox` module queues for a contact message while `bot_mode =
+ * 'bot'`.
+ */
 interface InboxBotJob {
   readonly conversation_id: string;
   readonly message_id: string;
@@ -315,21 +370,27 @@ interface InboxAdapterOptions {
    * `dispatch` instead.
    */
   readonly verify?: (request: Request) => boolean | Promise<boolean>;
-  /** Stores streamed replies so a reader can resume them; the stream id lands in the message's `metadata.stream_id`. */
+  /**
+   * Stores streamed replies so a reader can resume them; the stream id lands in
+   * the message's `metadata.stream_id`.
+   */
   readonly streams?: StreamStore;
   /**
-   * Issues a ticket for the contact's linked user before the bot's
-   * handlers run, so they read and write as that user: `dispatch` resolves
-   * `inboxIdentityOf(contactId)` through `principalByIdentity` (or the
-   * server's `identities` hook) and calls `ticketFor` for a `kind: "user"`
-   * link, as `botJobs` does. Read it with `ticketOf(message)`. A contact
-   * with no link stays a visitor and gets no ticket.
+   * Issues a ticket for the contact's linked user before the bot's handlers
+   * run, so they read and write as that user: `dispatch` resolves
+   * `inboxIdentityOf(contactId)` through `principalByIdentity` (or the server's
+   * `identities` hook) and calls `ticketFor` for a `kind: "user"` link, as
+   * `botJobs` does. Read it with `ticketOf(message)`. A contact with no link
+   * stays a visitor and gets no ticket.
    */
   readonly identities?: Omit<BotJobsOptions<unknown, unknown>, "enqueue">;
 }
 interface InboxAdapter extends Adapter<string, InboxMessage> {
   readonly name: "inbox";
-  /** Hands a queued bot job to Chat SDK: loads the contact's message and runs the bot's handlers. Other authors are skipped. */
+  /**
+   * Hands a queued bot job to Chat SDK: loads the contact's message and runs
+   * the bot's handlers. Other authors are skipped.
+   */
   dispatch(job: InboxBotJob): Promise<void>;
   /**
    * The ticket `dispatch` issued for the message's linked user, for
@@ -338,15 +399,18 @@ interface InboxAdapter extends Adapter<string, InboxMessage> {
    */
   ticketOf(message: Message<InboxMessage>): string | undefined;
 }
-/** The `IdentityRef` of an inbox contact: `kind: "chat"`, `provider: "inbox"` and the contact id. */
+/**
+ * The `IdentityRef` of an inbox contact: `kind: "chat"`, `provider: "inbox"`
+ * and the contact id.
+ */
 export declare function inboxIdentityOf(contactId: string): IdentityRef;
 /** `inbox:<conversation id>` to the conversation id. */
 export declare function conversationIdOf(threadId: string): string;
 /**
- * A Chat SDK adapter for the in-app inbox: the bot reads and writes the
- * `inbox` module's conversations, so one `Chat` instance answers the
- * widget and the other channels. Contact messages reach the bot as jobs
- * on the module's bot queue; pass them to `dispatch`.
+ * A Chat SDK adapter for the in-app inbox: the bot reads and writes the `inbox`
+ * module's conversations, so one `Chat` instance answers the widget and the
+ * other channels. Contact messages reach the bot as jobs on the module's bot
+ * queue; pass them to `dispatch`.
  */
 export declare function inboxAdapter(options: InboxAdapterOptions): InboxAdapter;
 //#endregion
@@ -372,7 +436,10 @@ interface InstallInput {
   readonly metadata?: Readonly<Record<string, unknown>>;
 }
 interface ChatInstallationsOptions {
-  /** `sqlTransport(postgres.asService())` or `rpcTransport` with the service role key. */
+  /**
+   * `sqlTransport(postgres.asService())` or `rpcTransport` with the service
+   * role key.
+   */
   readonly transport: BlockTransport;
   /** Revokes the ref a reinstall replaces and the ref an uninstall clears. */
   readonly credentials: CredentialProvider;
@@ -382,9 +449,15 @@ interface ChatInstallationsOptions {
 interface ChatInstallations {
   /** Records an install; a reinstall revokes the credential it replaces. */
   install(input: InstallInput): AsyncResult<ChatInstallation>;
-  /** Marks the install removed and revokes its credential; false when none was live. */
+  /**
+   * Marks the install removed and revokes its credential; false when none was
+   * live.
+   */
   uninstall(adapter: string, externalId: string): AsyncResult<boolean>;
-  /** Uninstalls every live install of a tenant before it is purged; returns how many. */
+  /**
+   * Uninstalls every live install of a tenant before it is purged; returns how
+   * many.
+   */
   uninstallTenant(tenant: string): AsyncResult<number>;
   get(adapter: string, externalId: string): AsyncResult<ChatInstallation | null>;
   list(filter?: {
@@ -394,14 +467,17 @@ interface ChatInstallations {
   }): AsyncResult<readonly ChatInstallation[]>;
 }
 /**
- * The `chat_installations` registry with the credential lifecycle: every
- * ref an install drops is revoked through the `CredentialProvider`.
+ * The `chat_installations` registry with the credential lifecycle: every ref an
+ * install drops is revoked through the `CredentialProvider`.
  */
 export declare function createChatInstallations(options: ChatInstallationsOptions): ChatInstallations;
 //#endregion
 //#region src/chat-sdk/state.d.ts
 interface SupabaseStateOptions {
-  /** `sqlTransport(postgres.asService())` or `rpcTransport` with the service role key. */
+  /**
+   * `sqlTransport(postgres.asService())` or `rpcTransport` with the service
+   * role key.
+   */
   readonly transport: BlockTransport;
   /** The schema of the `chat-sdk-state` module. Defaults to `better_supabase`. */
   readonly schema?: string;
@@ -419,8 +495,8 @@ interface SupabaseState extends StateAdapter {
 }
 /**
  * A Chat SDK `StateAdapter` on the `chat-sdk-state` SQL module: thread
- * subscriptions, locks, the cache, lists and the per-thread queue in
- * Postgres, so a bot needs no Redis. Service role only.
+ * subscriptions, locks, the cache, lists and the per-thread queue in Postgres,
+ * so a bot needs no Redis. Service role only.
  */
 export declare function createSupabaseState(options: SupabaseStateOptions): SupabaseState;
 //#endregion