better-supabase 0.12.0 → 0.14.0

package/dist/live-CZtRMh62.js

@@ -0,0 +1,246 @@
+import { t as refreshRealtimeAuth } from "./auth-DyF_LRxd.js";
+import { REALTIME_SUBSCRIBE_STATES } from "@supabase/supabase-js";
+//#region src/realtime/live.ts
+/**
+* Topic a `realtime-tables` trigger broadcasts on:
+* `bs:t:<schema>.<table>[:<tenant>]`, or `bs:t:<schema>.<table>:u:<user>` for a
+* `realtime.users` table.
+*/
+function liveTopic(meta, table, tenant, user) {
+	const found = meta.tables[table];
+	if (!found) throw new TypeError(`better-supabase: unknown table "${table}"`);
+	const base = `bs:t:${found.schema}.${found.name}`;
+	if (meta.realtime?.[table]?.user) {
+		if (user === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per user; pass \`user\` to watch it`);
+		return `${base}:u:${user}`;
+	}
+	if (!meta.realtime?.[table]?.tenant) return base;
+	if (tenant === void 0) throw new TypeError(`better-supabase: "${table}" broadcasts per tenant; pass \`tenant\` to watch it`);
+	return `${base}:${tenant}`;
+}
+const channels = /* @__PURE__ */ new WeakMap();
+function join(client, topic, listener, onStatus) {
+	let byTopic = channels.get(client);
+	if (!byTopic) {
+		byTopic = /* @__PURE__ */ new Map();
+		channels.set(client, byTopic);
+	}
+	let shared = byTopic.get(topic);
+	if (!shared) {
+		const channel = client.channel(topic, { config: { private: true } });
+		const listeners = /* @__PURE__ */ new Set();
+		const statuses = /* @__PURE__ */ new Set();
+		channel.on("broadcast", { event: "change" }, () => {
+			for (const notify of listeners) notify();
+		});
+		let joined = false;
+		const evict = () => {
+			if (byTopic.get(topic) !== entry) return;
+			byTopic.delete(topic);
+			client.removeChannel(channel);
+		};
+		const ready = (async () => {
+			await refreshRealtimeAuth(client);
+			await new Promise((resolve, reject) => {
+				channel.subscribe((status, error) => {
+					switch (status) {
+						case REALTIME_SUBSCRIBE_STATES.SUBSCRIBED:
+							if (joined) {
+								for (const notify of listeners) notify();
+								for (const notify of statuses) notify("subscribed");
+							}
+							joined = true;
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CLOSED:
+							resolve();
+							return;
+						case REALTIME_SUBSCRIBE_STATES.CHANNEL_ERROR:
+						case REALTIME_SUBSCRIBE_STATES.TIMED_OUT: {
+							const failure = error ?? /* @__PURE__ */ new Error(`Realtime ${status.toLowerCase()} on ${topic}`);
+							if (joined) for (const notify of statuses) notify("error", failure);
+							reject(failure);
+							if (!joined) evict();
+							return;
+						}
+						default: reject(/* @__PURE__ */ new Error(`Unknown realtime status ${String(status)}`));
+					}
+				});
+			});
+		})();
+		ready.catch(() => void 0);
+		const entry = {
+			channel,
+			listeners,
+			statuses,
+			ready
+		};
+		shared = entry;
+		byTopic.set(topic, entry);
+	}
+	const current = shared;
+	current.listeners.add(listener);
+	if (onStatus) current.statuses.add(onStatus);
+	let left = false;
+	return {
+		ready: current.ready,
+		leave: async () => {
+			if (left) return;
+			left = true;
+			current.listeners.delete(listener);
+			if (onStatus) current.statuses.delete(onStatus);
+			if (current.listeners.size > 0) return;
+			await new Promise((resolve) => {
+				setTimeout(resolve, 0);
+			});
+			if (current.listeners.size > 0 || byTopic.get(topic) !== current) return;
+			byTopic.delete(topic);
+			await client.removeChannel(current.channel);
+		}
+	};
+}
+/**
+* Calls `onChange` when a table the spec reads changes, so you can refetch.
+* Needs the `realtime-tables` SQL module and the tables in `realtime.tables`.
+* Live queries on the same client share one channel per table, so any number of
+* them can run at once.
+*
+* ```ts
+* using live = liveQuery(betterSupabase, supabase, spec, {
+*   onChange: () => refetch(),
+* });
+* ```
+*/
+function liveQuery(betterSupabase, client, spec, options) {
+	const touched = Array.isArray(spec) ? spec : betterSupabase.tablesOf(spec);
+	const tables = touched.filter((table) => betterSupabase.meta.realtime?.[table]);
+	const unwatched = touched.filter((table) => !betterSupabase.meta.realtime?.[table]);
+	const debounceMs = options.debounceMs ?? 100;
+	const changed = /* @__PURE__ */ new Set();
+	let timer;
+	let closed = false;
+	const flush = () => {
+		timer = void 0;
+		if (closed || changed.size === 0) return;
+		const batch = [...changed];
+		changed.clear();
+		options.onChange(batch);
+	};
+	const onTableChange = (table) => () => {
+		changed.add(table);
+		if (timer !== void 0) clearTimeout(timer);
+		timer = setTimeout(flush, debounceMs);
+	};
+	const failed = /* @__PURE__ */ new Set();
+	const onChannelStatus = (topic) => (status, error) => {
+		if (closed) return;
+		if (status === "error") failed.add(topic);
+		else failed.delete(topic);
+		if (status === "error") options.onStatus?.("error", error);
+		else if (failed.size === 0) options.onStatus?.("subscribed");
+	};
+	const topics = tables.map((table) => ({
+		table,
+		topic: liveTopic(betterSupabase.meta, table, options.tenant, options.user)
+	}));
+	const joinAll = () => topics.map(({ table, topic }) => join(client, topic, onTableChange(table), onChannelStatus(topic)));
+	let memberships = joinAll();
+	let retryTimer;
+	let delay = 1e3;
+	const settle = (attempt) => Promise.all(attempt.map((member) => member.ready)).then(() => {
+		if (!closed && tables.length > 0) options.onStatus?.("subscribed");
+	}, (cause) => {
+		const error = cause instanceof Error ? cause : new Error(String(cause));
+		if (!closed) {
+			options.onStatus?.("error", error);
+			if (options.retry !== false) scheduleRetry(attempt);
+		}
+		throw error;
+	});
+	const scheduleRetry = (attempt) => {
+		retryTimer = setTimeout(() => {
+			retryTimer = void 0;
+			if (closed || attempt !== memberships) return;
+			Promise.all(attempt.map((member) => member.leave()));
+			memberships = joinAll();
+			options.onStatus?.("joining");
+			settle(memberships).then(() => {
+				if (closed) return;
+				for (const table of tables) changed.add(table);
+				flush();
+			}, () => void 0);
+		}, delay);
+		delay = Math.min(delay * 2, 3e4);
+	};
+	options.onStatus?.(tables.length === 0 ? "closed" : "joining");
+	const ready = settle(memberships);
+	ready.catch(() => void 0);
+	const unsubscribe = async () => {
+		if (closed) return;
+		closed = true;
+		if (timer !== void 0) clearTimeout(timer);
+		if (retryTimer !== void 0) clearTimeout(retryTimer);
+		await Promise.all(memberships.map((member) => member.leave()));
+		options.onStatus?.("closed");
+	};
+	return {
+		tables,
+		unwatched,
+		ready,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+/**
+* Keeps a count current: runs the `count` spec (a HEAD request) now, after each
+* debounced change to a table it reads, and after the channel rejoins.
+* Responses that arrive out of order are dropped.
+*
+* ```ts
+* using live = liveCount(
+*   betterSupabase,
+*   supabase,
+*   db,
+*   betterSupabase.spec.notes.count(),
+*   { onCount: (count) => render(count) },
+* );
+* ```
+*/
+function liveCount(betterSupabase, client, db, spec, options) {
+	let latest = 0;
+	let closed = false;
+	const refetch = () => {
+		latest += 1;
+		const call = latest;
+		Promise.resolve(db.$run(spec)).then((result) => {
+			if (closed || call !== latest) return;
+			if (result.ok) options.onCount(result.data);
+			else options.onError?.(result.error);
+		});
+	};
+	const live = liveQuery(betterSupabase, client, spec, {
+		onChange: refetch,
+		...options.tenant === void 0 ? {} : { tenant: options.tenant },
+		...options.user === void 0 ? {} : { user: options.user },
+		...options.debounceMs === void 0 ? {} : { debounceMs: options.debounceMs },
+		...options.onStatus ? { onStatus: options.onStatus } : {}
+	});
+	if (options.immediate ?? true) refetch();
+	const since = options.since;
+	if (since !== void 0) live.ready.then(() => {
+		if (!closed && Date.now() - since > 1e3) refetch();
+	}, () => void 0);
+	const unsubscribe = async () => {
+		closed = true;
+		await live.unsubscribe();
+	};
+	return {
+		...live,
+		unsubscribe,
+		[Symbol.dispose]: () => void unsubscribe(),
+		[Symbol.asyncDispose]: unsubscribe
+	};
+}
+//#endregion
+export { liveQuery as n, liveTopic as r, liveCount as t };

package/dist/management-wtecfrNf.d.ts

@@ -0,0 +1,57 @@
+//#region src/create/supabase/management.d.ts
+declare const SMART_REGIONS: readonly ["americas", "emea", "apac"];
+type SmartRegion = (typeof SMART_REGIONS)[number];
+/** A Supabase project ref: lowercase letters and digits, never a path. */
+declare function isProjectRef(value: string): boolean;
+interface SupabaseOrganization {
+  readonly id: string;
+  readonly slug: string;
+  readonly name: string;
+}
+interface SupabaseProject {
+  readonly ref: string;
+  readonly name: string;
+  readonly organization_slug: string;
+  readonly region: string;
+  readonly status: string;
+}
+interface SupabaseLint {
+  readonly name: string;
+  readonly title: string;
+  readonly level: "ERROR" | "WARN" | "INFO";
+  readonly detail?: string | undefined;
+  readonly remediation?: string | undefined;
+}
+/**
+ * A Management API call that failed; `status` is the HTTP status, 0 for a bad
+ * response.
+ */
+declare class ManagementError extends Error {
+  override readonly name = "ManagementError";
+  readonly status: number;
+  constructor(message: string, status: number);
+}
+/** The Management API calls the deploy flow makes. */
+interface ManagementClient {
+  organizations(): Promise<SupabaseOrganization[]>;
+  projects(): Promise<SupabaseProject[]>;
+  createProject(input: {
+    name: string;
+    organizationSlug: string;
+    region: SmartRegion;
+    dbPass: string;
+  }): Promise<SupabaseProject>;
+  project(ref: string): Promise<SupabaseProject>;
+  databaseHealthy(ref: string): Promise<boolean>;
+  publicTableCount(ref: string): Promise<number>;
+  applyMigration(ref: string, name: string, query: string): Promise<void>;
+  securityLints(ref: string): Promise<readonly SupabaseLint[]>;
+}
+/**
+ * The Management API calls the deploy dialog makes, with the user's OAuth
+ * access token. Responses are parsed, and every failure is a
+ * `ManagementError`.
+ */
+declare function managementClient(accessToken: string, fetchImpl?: typeof fetch): ManagementClient;
+//#endregion
+export { SupabaseLint as a, isProjectRef as c, SmartRegion as i, managementClient as l, ManagementError as n, SupabaseOrganization as o, SMART_REGIONS as r, SupabaseProject as s, ManagementClient as t };

package/dist/mcp/index.d.ts

@@ -1,20 +1,23 @@
-import { B as TableKey, a as AnyModels, i as AnyFunctions } from "../types-BrpW5ixT.js";
-import { t as OperationTable } from "../operations-DQCWqkt3.js";
-import { D as ResourceOperation } from "../model-lUafmeBQ.js";
-import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-eiOjo-3l.js";
-import { t as BetterSupabase } from "../define-DYZnvAbs.js";
-import { a as ServerContext, c as ServerOptions, n as BetterServer } from "../server-types-fLdep4gb.js";
-import { r as GuardOptions } from "../respond-BSL36dQp.js";
-import { l as ResourceRouteOptions } from "../resource-types-LW1i5-h3.js";
+import { M as AnyFunctions, N as AnyModels, mt as TableKey } from "../executor-CPyrQdjh.js";
+import { t as OperationTable } from "../operations-nWYRexee.js";
+import { D as ResourceOperation } from "../model-Btl8X9cs.js";
+import { s as PermissionRef, t as AnyAuthorizer } from "../authorizer-DFP3gHv8.js";
+import { t as BetterSupabase } from "../define-Dw7pRO4h.js";
+import { a as ServerContext, c as ServerOptions, n as BetterServer } from "../server-types-BOs-eFpo.js";
+import { r as GuardOptions } from "../respond-CZYibxUx.js";
+import { l as ResourceRouteOptions } from "../resource-types-Bzt_bpR5.js";
 import { StandardSchemaV1 } from "@standard-schema/spec";
+//#region src/mcp/dialect.d.ts
+/**
+ * The JSON Schema dialect of tool schemas, which depends on the protocol
+ * revision.
+ */
+type ToolSchemaTarget = "draft-2020-12" | "draft-07";
+//#endregion
 //#region src/mcp/json-rpc.d.ts
 /** A JSON object. */
 type Json = Readonly<Record<string, unknown>>;
 //#endregion
-//#region src/mcp/dialect.d.ts
-/** The JSON Schema dialect of tool schemas, which depends on the protocol revision. */
-type ToolSchemaTarget = "draft-2020-12" | "draft-07";
-//#endregion
 //#region src/mcp/permissions.d.ts
 /** `McpOptions.requiredRoles`: the roles, or the roles and the claim to read. */
 type RequiredRoles = readonly string[] | {
@@ -65,8 +68,8 @@ interface ProtocolServer extends ServerDescription {
   callTool(name: string, args: unknown): Promise<ToolResult | undefined>;
 }
 /**
- * The JSON-RPC response to one message, or `undefined` for a notification.
- * It answers `initialize`, `server/discover`, `ping`, `tools/list` and
+ * The JSON-RPC response to one message, or `undefined` for a notification. It
+ * answers `initialize`, `server/discover`, `ping`, `tools/list` and
  * `tools/call`, for message-based transports such as stdio.
  */
 export declare function answerMessage(message: unknown, server: ProtocolServer): Promise<Json | undefined>;
@@ -89,7 +92,10 @@ interface McpTool<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P
   readonly input?: StandardSchemaV1;
   /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
   readonly meta?: unknown;
-  /** Checked by the authorizer on every call; callers it denies don't see the tool. */
+  /**
+   * Checked by the authorizer on every call; callers it denies don't see the
+   * tool.
+   */
   readonly permission?: unknown;
   /** The provider operation the tool checks, in place of `mcp.tool.<name>`. */
   readonly operation?: string;
@@ -98,7 +104,10 @@ interface McpTool<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P
 /** What the `authorize` and `visible` hooks see of a tool. */
 interface ToolRef {
   readonly info: ToolInfo;
-  /** The tool's `meta`, e.g. a permission. For table tools, the resource's `meta` for that operation. */
+  /**
+   * The tool's `meta`, e.g. a permission. For table tools, the resource's
+   * `meta` for that operation.
+   */
   readonly meta: unknown;
 }
 /** The outcome of `authorize`. `scopes` turns a refusal into an OAuth challenge. */
@@ -131,9 +140,9 @@ interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I, C =
   /** Opaque data for the `authorize` and `visible` hooks. Never sent to clients. */
   readonly meta?: unknown;
   /**
-   * Checked by the authorizer after the arguments are validated, with the
-   * tool as the resource (`mcp_tool`). `tools/list` hides the tool from
-   * callers it denies.
+   * Checked by the authorizer after the arguments are validated, with the tool
+   * as the resource (`mcp_tool`). `tools/list` hides the tool from callers it
+   * denies.
    */
   readonly permission?: Ref;
   /**
@@ -143,12 +152,15 @@ interface ToolDefinition<M extends AnyModels, F extends AnyFunctions, E, I, C =
   readonly operation?: string;
   run(args: I, ctx: ToolContext<M, F, E, C, P, B>): unknown;
 }
-/** A table's tools: the REST resource options, plus `meta` per operation for `authorize` and `visible`. */
+/**
+ * A table's tools: the REST resource options, plus `meta` per operation for
+ * `authorize` and `visible`.
+ */
 type ToolResourceOptions<M extends AnyModels, T extends TableKey<M>, Ref = string> = ResourceRouteOptions<M, T, Ref> & {
   /**
-   * Opaque data per operation, e.g. a permission, passed to
-   * `authorize` and `visible` as the table tool's `meta`. Never sent to
-   * clients. An operation without an entry gets `undefined`.
+   * Opaque data per operation, e.g. a permission, passed to `authorize` and
+   * `visible` as the table tool's `meta`. Never sent to clients. An operation
+   * without an entry gets `undefined`.
    */
   readonly meta?: { readonly [K in ResourceOperation]?: unknown; };
 };
@@ -159,13 +171,16 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown
   readonly title?: string;
   /** Sent to clients on `initialize`, e.g. how the tools fit together. */
   readonly instructions?: string;
-  /** Tables exposed as tools: `<table>_list`, `_get`, `_create`, `_update`, `_delete`. */
+  /**
+   * Tables exposed as tools: `<table>_list`, `_get`, `_create`, `_update`,
+   * `_delete`.
+   */
   readonly resources?: ToolResources<M, Ref>;
   readonly tools?: readonly McpTool<M, F, E, C, P, B>[];
   /**
-   * The authorization provider's operations (`authorization.operations` in
-   * the config). A tool's `mcp.tool.<name>` entry replaces its `permission`,
-   * so the provider decides what each tool needs.
+   * The authorization provider's operations (`authorization.operations` in the
+   * config). A tool's `mcp.tool.<name>` entry replaces its `permission`, so the
+   * provider decides what each tool needs.
    */
   readonly operations?: OperationTable;
   /**
@@ -191,33 +206,43 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown
    */
   readonly requiredScopes?: readonly string[];
   /**
-   * Roles a signed-in user needs to call the server at all, read from a
-   * claim (`app_metadata.role` by default; a string or an array of
-   * strings). Users without one get 403; service-role callers pass.
+   * Roles a signed-in user needs to call the server at all, read from a claim
+   * (`app_metadata.role` by default; a string or an array of strings). Users
+   * without one get 403; service-role callers pass.
    *
    * ```ts
    * requiredRoles: { roles: ['admin', 'support'], claim: 'app_metadata.roles' }
    * ```
    */
   readonly requiredRoles?: RequiredRoles;
-  /** Origins allowed to call the server (DNS rebinding protection). Defaults to any. */
+  /**
+   * Origins allowed to call the server (DNS rebinding protection). Defaults to
+   * any.
+   */
   readonly allowedOrigins?: readonly string[];
   /**
-   * Answers CORS preflights and adds `Access-Control-*` headers, so browser
-   * MCP clients can call the server. The allowed origin is `allowedOrigins`
-   * when set, any origin otherwise. Defaults to true.
+   * Answers CORS preflights and adds `Access-Control-*` headers, so browser MCP
+   * clients can call the server. The allowed origin is `allowedOrigins` when
+   * set, any origin otherwise. Defaults to true.
    */
   readonly cors?: boolean;
   /**
    * Hostnames the `Host` header may name, without the port (DNS rebinding
-   * protection). List the production, preview and local hosts. Defaults to any.
+   * protection). List the production, preview and local hosts. Defaults to
+   * any.
    */
   readonly allowedHosts?: readonly string[];
-  /** A page that explains how to connect, published as RFC 9728 `resource_documentation`. */
+  /**
+   * A page that explains how to connect, published as RFC 9728
+   * `resource_documentation`.
+   */
   readonly resourceDocumentation?: string;
   /** Custom jsonb types, as in `createOpenApi`. */
   readonly json?: Readonly<Record<string, unknown>>;
-  /** Include internal error messages in tool results. Defaults to `NODE_ENV === 'development'`. */
+  /**
+   * Include internal error messages in tool results. Defaults to `NODE_ENV ===
+   * 'development'`.
+   */
   readonly exposeErrors?: boolean;
   /**
    * Keeps the invocation alive for event sink sends a tool started, e.g.
@@ -238,7 +263,10 @@ interface McpOptions<M extends AnyModels, F extends AnyFunctions, E, C = unknown
   readonly visible?: (ctx: ToolContext<M, F, E, C, P, B>, tool: ToolRef) => boolean | Promise<boolean>;
 }
 interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown, P = unknown, Ref = string, B = unknown> extends BetterServer<M, F, E, C, P, B> {
-  /** Everything in one handler: the MCP endpoint and `/.well-known/oauth-protected-resource`. */
+  /**
+   * Everything in one handler: the MCP endpoint and
+   * `/.well-known/oauth-protected-resource`.
+   */
   readonly fetch: (request: Request) => Promise<Response>;
   /** The Streamable HTTP endpoint (POST JSON-RPC). */
   readonly endpoint: (request: Request) => Promise<Response>;
@@ -253,10 +281,10 @@ interface BetterMcp<M extends AnyModels, F extends AnyFunctions, E, C = unknown,
 /** A custom tool. Pass it in `createMcp({ tools: [...] })`. */
 export declare function defineTool<M extends AnyModels, F extends AnyFunctions, E, I = Record<string, unknown>, C = unknown, P = unknown, Ref = unknown, B = unknown>(definition: ToolDefinition<M, F, E, I, C, P, Ref, B>): McpTool<M, F, E, C, P, B>;
 /**
- * An MCP server (Streamable HTTP, stateless) whose tools run as the caller:
- * the Bearer token from the MCP client is verified and every query goes
- * through RLS. Answers 401 with RFC 9728 metadata so clients can sign in with
- * Supabase Auth's OAuth server.
+ * An MCP server (Streamable HTTP, stateless) whose tools run as the caller: the
+ * Bearer token from the MCP client is verified and every query goes through
+ * RLS. Answers 401 with RFC 9728 metadata so clients can sign in with Supabase
+ * Auth's OAuth server.
  */
 export declare function createMcp<M extends AnyModels, D, F extends AnyFunctions, E, C = unknown, P = unknown, A extends AnyAuthorizer | undefined = undefined, B = unknown>(betterSupabase: BetterSupabase<M, D, F, E, C, P, B>, options: McpOptions<M, F, E, C, P, PermissionRef<A>, B> & {
   readonly authorizer?: A;