better-supabase 0.8.0 → 0.10.0

package/dist/topic-Dgs-eSYQ.d.ts

@@ -0,0 +1,373 @@
+import { E as ValidationIssue, b as DbError, t as AsyncResult } from "./result-Cj3yWhjH.js";
+import { M as Row, a as AnyModels, i as AnyFunctions, r as AccessTopicPolicy, z as TableKey } from "./types-BO8lVTun.js";
+import { t as AuthorizationFunctions } from "./authorization-CdJRoZgV.js";
+import { t as RealtimeStatus } from "./realtime-status-DcsO00Gw.js";
+import { J as TemplateValues, q as TemplateParams } from "./storage-api-B4Ib2Zpo.js";
+import { t as BetterSupabase } from "./define-DXTC706J.js";
+import { g as SubscriberPolicy, h as SubscriberEvent, i as AuthorizationHooks, m as Subscriber } from "./authorization-hooks-Do5djkpz.js";
+import { RealtimeChannel, SupabaseClient } from "@supabase/supabase-js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/realtime/fan-out.d.ts
+interface TopicFanOutOptions<P extends string, E extends EventSchemas, K extends TopicEvent<E>, S extends Subscriber> {
+  readonly subscribers: readonly S[];
+  /** The topic values of one subscriber, e.g. `(s) => ({ userId: s.principal })`. */
+  readonly values: (subscriber: S) => TemplateValues<P>;
+  readonly event: K;
+  readonly payload: TopicPayload<E, K>;
+  /** What the subscriber policy reads about the event. */
+  readonly source: SubscriberEvent;
+  /**
+   * Defaults to the topic's `subscribers`, then
+   * `server.authorization.delivery.subscribers`. With `server.authorization`
+   * and none of them, an event with a `subject` goes to no one
+   * (`REALTIME_SUBSCRIBER_POLICY_REQUIRED`); pass `subjectReaders(transport)`.
+   */
+  readonly policy?: SubscriberPolicy;
+  readonly server?: {
+    readonly authorization?: AuthorizationHooks | undefined;
+  };
+}
+interface FanOutResult<S> {
+  readonly sent: readonly S[];
+  /** Left out by the subscriber policy. */
+  readonly skipped: readonly S[];
+  /** Sends that failed, with their error. */
+  readonly failed: readonly {
+    readonly subscriber: S;
+    readonly error: DbError;
+  }[];
+}
+//#endregion
+//#region src/realtime/topic.d.ts
+type EventSchemas = Readonly<Record<string, StandardSchemaV1>>;
+/** `true`, or a schema every tracked presence state is validated against. */
+type PresenceSchema = boolean | StandardSchemaV1;
+interface TopicOptions<E extends EventSchemas, R extends PresenceSchema = PresenceSchema> {
+  /** Name used for generated policies and functions. Defaults to the template's literal parts. */
+  readonly name?: string;
+  /** Payload schemas per event. Incoming and outgoing payloads are validated. */
+  readonly events?: E;
+  /** Private channels are authorized by `realtime.messages` policies. Defaults to `true`. */
+  readonly private?: boolean;
+  /**
+   * Tenant check for the generated policy. Defaults to `{organizationId}` against
+   * `tenant_id` / `app_metadata.tenant_id` when the template has `{organizationId}`.
+   */
+  readonly tenant?: false | {
+    readonly param?: string;
+    readonly claim?: string | readonly string[];
+    readonly sql?: string;
+  };
+  /** Owner check. Defaults to `{userId}` against `auth.uid()` when the template has `{userId}`. */
+  readonly owner?: false | {
+    readonly param?: string;
+  };
+  /**
+   * Authorize with the SQL modules' access contract instead of the tenant
+   * claim: `tenant_ids_with(receive)` on the tenant segment (or
+   * `is_platform` for `scope: 'platform'`), or the `sql` templates it is
+   * given, and `send` for broadcasting.
+   *
+   * The checks decide by role and scope only: for a permission with row
+   * conditions (e.g. `authorId = principal.id`) every member of the scope
+   * could join. `better-supabase doctor` (BS214) refuses keys the
+   * authorization provider doesn't mark `sqlComplete: true`.
+   */
+  readonly access?: AccessTopicPolicy;
+  /**
+   * A permission on the instance the topic is about, such as
+   * `'posts.read'` on `org:{organizationId}:posts:{postId}`: every receiver
+   * and sender must hold it on that instance. With an authorization
+   * provider, `sql({ functions })` checks it with the provider's `permitted`
+   * template; without one, with the access contract's tenant check.
+   */
+  readonly permission?: string | TopicPermission;
+  /**
+   * Narrows `fanOut` to the subscribers that may read the event. Defaults
+   * to `server.authorization.delivery.subscribers` when `fanOut` gets the
+   * server.
+   */
+  readonly subscribers?: SubscriberPolicy;
+  /** Let clients broadcast on the topic, not only receive. Defaults to `false`. */
+  readonly send?: boolean;
+  /**
+   * Presence: authorizes it in the policies and adds `track` and
+   * `onPresence` to subscriptions. Pass a schema to validate the states
+   * this client tracks and the ones it receives. Defaults to `false`.
+   */
+  readonly presence?: R;
+}
+/** A topic's instance permission. */
+interface TopicPermission {
+  readonly key: string;
+  /** The placeholder holding the instance id, as a whole segment. Defaults to the last one. */
+  readonly param?: string;
+  /** `{resource}` in the `permitted` template. Defaults to the key up to its first `.`. */
+  readonly resource?: string;
+  /** `{scope}` in the `permitted` template. Defaults to `tenant`. */
+  readonly scope?: string;
+}
+interface TopicMessage {
+  readonly event: string;
+  readonly payload: unknown;
+  readonly topic: string;
+}
+type Output<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<S> : unknown;
+type Input<S> = S extends StandardSchemaV1 ? StandardSchemaV1.InferInput<S> : unknown;
+type TopicHandlers<E extends EventSchemas> = [keyof E] extends [never] ? {
+  readonly [event: string]: ((payload: unknown, message: TopicMessage) => void) | undefined;
+} : { readonly [K in keyof E & string]?: (payload: Output<E[K]>, message: TopicMessage) => void; } & {
+  readonly "*"?: (payload: unknown, message: TopicMessage) => void;
+};
+type TopicEvent<E extends EventSchemas> = [keyof E] extends [never] ? string : keyof E & string;
+type TopicPayload<E extends EventSchemas, K extends string> = [keyof E] extends [never] ? unknown : Input<E[K]>;
+type SubscriptionStatus = "joining" | "subscribed" | "closed" | "error";
+interface SubscribeOptions {
+  /** Receive your own broadcasts. */
+  readonly self?: boolean;
+  readonly onStatus?: (status: SubscriptionStatus, error?: Error) => void;
+  /** Called when a payload fails its event schema. The handler is skipped. */
+  readonly onInvalid?: (message: TopicMessage, issues: readonly ValidationIssue[]) => void;
+}
+interface Subscription extends Disposable, AsyncDisposable {
+  readonly topic: string;
+  readonly channel: RealtimeChannel;
+  /** Resolves once joined; rejects if the join is refused or times out. */
+  readonly ready: Promise<void>;
+  unsubscribe(): Promise<void>;
+}
+/** One tracked state on a presence topic. */
+interface PresenceMember<S> {
+  /** The connection's presence key; a client tracking twice keeps one key. */
+  readonly key: string;
+  readonly state: S;
+}
+interface PresenceOptions<S> {
+  /**
+   * Called with everyone on the topic, this client included, after each
+   * presence sync. States that fail the presence schema are left out and
+   * passed to `onInvalid` as a `presence` message.
+   */
+  readonly onPresence?: (members: readonly PresenceMember<S>[]) => void;
+}
+interface PresenceSubscription<I, O> extends Subscription {
+  /**
+   * Validates the state, waits for the join and shares it with the topic.
+   * One state per client and topic: the last `track` wins, and leaving the
+   * topic removes it.
+   */
+  track(state: I): AsyncResult<void>;
+  /** Removes this client's state from the topic. */
+  untrack(): AsyncResult<void>;
+  /** Everyone from the last sync, as `onPresence` received them. */
+  members(): readonly PresenceMember<O>[];
+}
+type PresenceState = Readonly<Record<string, unknown>>;
+type PresenceInput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferInput<R> : PresenceState;
+type PresenceOutput<R> = R extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<R> : PresenceState;
+/** What `subscribe` returns: with `track` and `members` on presence topics. */
+type TopicSubscription<R> = [R] extends [false] ? Subscription : PresenceSubscription<PresenceInput<R>, PresenceOutput<R>>;
+/** `subscribe` options: with `onPresence` on presence topics. */
+type TopicSubscribeOptions<R> = [R] extends [false] ? SubscribeOptions : SubscribeOptions & PresenceOptions<PresenceOutput<R>>;
+type RealtimeClient = Pick<SupabaseClient, "channel" | "getChannels" | "removeChannel" | "realtime">;
+/**
+ * A value read from another table: the `select` column of the `from` row
+ * whose `key` (its primary key by default) equals `via`, a column of the
+ * changed row or another lookup.
+ */
+interface TriggerLookup<M extends AnyModels> {
+  readonly from: TableKey<M>;
+  readonly via: string | TriggerLookup<M>;
+  readonly select: string;
+  readonly key?: string;
+}
+/** A trigger value: a column of the changed row, or a lookup through it. */
+type TriggerValue<M extends AnyModels, T extends keyof M> = Extract<keyof Row<M, T>, string> | TriggerLookup<M>;
+type TriggerOperation = "insert" | "update" | "delete";
+/**
+ * What a broadcast trigger sends. `"keys"` (the default) sends
+ * `{ operation, schema, table, id, values }`: the primary key and the
+ * topic's placeholder values, so clients refetch the row through RLS.
+ * `"row"` sends the whole row as `record` and `old_record`, which bypasses
+ * column grants: every receiver of the topic sees every column.
+ */
+type TriggerPayloadMode = "keys" | "row";
+/** A topic the same row change also goes to (`topics` on `trigger()`). */
+interface TriggerTopic<V> {
+  readonly topic: {
+    readonly template: string;
+    readonly params: readonly string[];
+    readonly private: boolean;
+  };
+  /** What fills each of its placeholders, as in `values`. */
+  readonly values?: Readonly<Record<string, V>>;
+}
+interface TriggerCommonOptions {
+  /** Defaults to all three. */
+  readonly events?: readonly TriggerOperation[];
+  /**
+   * The broadcast event name, or one per operation. Defaults to the
+   * operation (`INSERT`, `UPDATE`, `DELETE`).
+   */
+  readonly event?: string | { readonly [O in TriggerOperation]?: string; };
+  /**
+   * Schema for a generated function. Defaults to `better_supabase`, which
+   * the Data API does not expose.
+   */
+  readonly functionSchema?: string;
+}
+/** `topic.trigger()` with the app's `betterSupabase`: typed columns and lookups. */
+interface TriggerOptions<M extends AnyModels, T extends keyof M, P extends string> extends TriggerCommonOptions {
+  /**
+   * What fills each placeholder: a column of the changed row, or a lookup
+   * (`{ from, via, select }`) for a value on a parent row. A row whose
+   * topic comes out null is not sent to that topic.
+   */
+  readonly values: { readonly [K in TemplateParams<P>]: TriggerValue<M, T>; };
+  /**
+   * `"keys"` (default), `"row"` (bypasses column grants), or the payload
+   * itself: each key is a column, a lookup, or `{ sql }`, an expression on
+   * the row `{row}` (`tg_op` is the operation).
+   */
+  readonly payload?: TriggerPayloadMode | Readonly<Record<string, TriggerValue<M, T> | {
+    readonly sql: string;
+  }>>;
+  /** More topics the row change goes to, each with its own values. */
+  readonly topics?: readonly TriggerTopic<TriggerValue<M, T>>[];
+}
+interface TopicTriggerLookup {
+  readonly from: string;
+  readonly via: string | TopicTriggerLookup;
+  readonly select: string;
+  readonly key?: string;
+}
+type TopicTriggerValue = string | TopicTriggerLookup;
+/** `topic.trigger()` without `betterSupabase`: database names. */
+interface TopicTriggerOptions<P extends string> extends TriggerCommonOptions {
+  /**
+   * The column or lookup that fills each placeholder. Defaults to the
+   * placeholder in snake_case (`{organizationId}` reads `organization_id`).
+   */
+  readonly values?: { readonly [K in TemplateParams<P>]?: TopicTriggerValue; };
+  /**
+   * `"keys"` (default), `"row"` (bypasses column grants), or the payload
+   * itself: each key is a column, a lookup, or `{ sql }`, an expression on
+   * the row `{row}` (`tg_op` is the operation).
+   */
+  readonly payload?: TriggerPayloadMode | Readonly<Record<string, TopicTriggerValue | {
+    readonly sql: string;
+  }>>;
+  /** More topics the row change goes to, each with its own values. */
+  readonly topics?: readonly TriggerTopic<TopicTriggerValue>[];
+}
+/** A row change sent with `payload: "row"`. */
+interface RowChange<R> {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly table: string;
+  readonly record: R | null;
+  readonly oldRecord: Partial<R> | null;
+}
+/** A row change sent with the default `payload: "keys"`: refetch the row through RLS. */
+interface RowKeys {
+  readonly operation: "INSERT" | "UPDATE" | "DELETE";
+  readonly schema: string;
+  readonly table: string;
+  /** The primary key value, or an object keyed by column for a composite key. */
+  readonly id: unknown;
+  /** The topic's placeholder values. */
+  readonly values: Readonly<Record<string, string>>;
+}
+/** Options for `topic.sql()`. */
+interface TopicSqlOptions {
+  /**
+   * The provider's templates, for an access policy with `sql: "provider"`
+   * and for `permission` (its `permitted` template).
+   */
+  readonly functions?: AuthorizationFunctions;
+}
+interface Topic<P extends string, E extends EventSchemas, R extends PresenceSchema = false> {
+  readonly template: P;
+  readonly name: string;
+  readonly params: readonly TemplateParams<P>[];
+  readonly private: boolean;
+  /** Whether subscriptions get `track` and `onPresence`. */
+  readonly presence: boolean;
+  /** The schema tracked presence states are validated against, if any. */
+  readonly presenceSchema: StandardSchemaV1 | undefined;
+  /** Payload schemas per event, as given to `defineTopic`. */
+  readonly events: E;
+  /** Whether clients may broadcast on the topic (the `send` option). */
+  readonly clientSend: boolean;
+  /** The instance permission's key, when the topic has one. */
+  readonly permission: string | undefined;
+  /**
+   * Supabase's status for what the topic relies on: `beta` for a private
+   * topic (Realtime Authorization is in public beta), `ga` otherwise.
+   */
+  readonly status: RealtimeStatus;
+  topic(values: TemplateValues<P>): string;
+  match(topic: string): TemplateValues<P> | null;
+  /**
+   * `realtime.messages` policies for this topic. Idempotent. An access
+   * policy with `sql: "provider"` needs the provider's templates in
+   * `options.functions`; `better-supabase sql sync` passes them.
+   */
+  sql(options?: TopicSqlOptions): string;
+  /**
+   * A trigger that broadcasts row changes on `table` to this topic, and to
+   * each of `topics`. A topic whose values come out null is skipped, and
+   * a value topics don't allow skips that topic with a warning instead of
+   * failing the write.
+   *
+   * With `betterSupabase`, `table`, columns and lookup tables are app keys.
+   * Without it they are database names, and a single topic whose values
+   * are columns, with a mode payload and one event name, calls
+   * `better_supabase.broadcast_topic()` from the `realtime-tables` module.
+   * Every other trigger creates a function for the topic.
+   *
+   * The payload carries keys only unless `payload` says otherwise:
+   * `payload: "row"` sends whole rows and bypasses column grants.
+   */
+  trigger<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(table: T, options: TriggerOptions<M, T, P> & {
+    readonly betterSupabase: BetterSupabase<M, D, F, X>;
+  }): string;
+  trigger(table: string, options?: TopicTriggerOptions<P>): string;
+  /**
+   * @deprecated Use `trigger(table, { ...options, betterSupabase })`. The
+   * payload default is keys only; pass `payload: "row"` for whole rows.
+   */
+  triggerSql<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, options: TriggerOptions<M, T, P>): string;
+  subscribe(client: RealtimeClient, values: TemplateValues<P>, handlers: TopicHandlers<E>, options?: TopicSubscribeOptions<R>): TopicSubscription<R>;
+  /** Sends over HTTP, without joining the channel. */
+  send<K extends TopicEvent<E>>(client: RealtimeClient, values: TemplateValues<P>, event: K, payload: TopicPayload<E, K>): AsyncResult<void>;
+  /**
+   * Sends one event to each subscriber's own topic (such as
+   * `notifications:{userId}`) after the subscriber policy narrows them.
+   * A policy that throws sends to no one and returns a `forbidden` error.
+   */
+  fanOut<S extends Subscriber, K extends TopicEvent<E>>(client: RealtimeClient, options: TopicFanOutOptions<P, E, K, S>): AsyncResult<FanOutResult<S>>;
+}
+/**
+ * A typed Realtime broadcast topic: names from a template, RLS policies for
+ * private channels, row-change triggers, and disposable subscriptions.
+ *
+ * ```ts
+ * export const notifications = defineTopic('organization:{organizationId}:notifications:{userId}', {
+ *   events: { created: v.object({ id: v.string(), title: v.string() }) },
+ * });
+ * using sub = notifications.subscribe(supabase, { organizationId, userId }, { created: (n) => toast(n.title) });
+ * ```
+ */
+declare function defineTopic<const P extends string, const E extends EventSchemas = Record<never, never>, const R extends PresenceSchema = false>(template: P, options?: TopicOptions<E, R>): Topic<P, E, R>;
+/**
+ * Reads a broadcast trigger's default message (`payload: "keys"`). Returns
+ * `null` for messages about other tables or with another shape.
+ */
+declare function rowKeys<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowKeys | null;
+/**
+ * Reads a `payload: "row"` message as an app-cased row change. Returns
+ * `null` for messages about other tables.
+ */
+declare function rowChange<M extends AnyModels, D, F extends AnyFunctions, X, T extends TableKey<M>>(betterSupabase: BetterSupabase<M, D, F, X>, table: T, message: TopicMessage): RowChange<Row<M, T>> | null;
+//#endregion
+export { TriggerTopic as A, TopicSubscription as C, TriggerLookup as D, TopicTriggerValue as E, FanOutResult as F, TopicFanOutOptions as I, defineTopic as M, rowChange as N, TriggerOptions as O, rowKeys as P, TopicSubscribeOptions as S, TopicTriggerOptions as T, TopicMessage as _, PresenceOutput as a, TopicPermission as b, RealtimeClient as c, SubscribeOptions as d, Subscription as f, TopicHandlers as g, TopicEvent as h, PresenceOptions as i, TriggerValue as j, TriggerPayloadMode as k, RowChange as l, Topic as m, PresenceInput as n, PresenceSchema as o, SubscriptionStatus as p, PresenceMember as r, PresenceSubscription as s, EventSchemas as t, RowKeys as u, TopicOptions as v, TopicTriggerLookup as w, TopicSqlOptions as x, TopicPayload as y };