better-supabase 0.3.0 → 0.5.0

package/dist/signers-Cc6r98SW.d.ts

@@ -0,0 +1,162 @@
+/// <reference lib="esnext.temporal" />
+import { t as KitTransport } from "./kit-transport-B82k1djG.js";
+//#region src/webhooks/url-policy.d.ts
+/** Decides whether a webhook may be sent to `url`. Rejecting counts as `false`. */
+type AllowUrl = (url: URL) => boolean | Promise<boolean>;
+/** The addresses a host name resolves to. */
+type ResolveHost = (hostname: string) => Promise<readonly string[]>;
+interface PublicUrlOptions {
+  /**
+   * Resolves host names so each address can be checked. Defaults to
+   * `node:dns` where the runtime has it (Node, Bun, Deno); pass one on other
+   * runtimes, or `false` to check only the URL.
+   */
+  readonly resolve?: ResolveHost | false;
+  /** Allow `http:` URLs, e.g. for local development. */
+  readonly allowHttp?: boolean;
+  /** Host names that skip every check, e.g. an internal receiver you trust. */
+  readonly allowHosts?: readonly string[];
+}
+/**
+ * Whether an IP address is reachable on the public internet: not loopback,
+ * private, link-local (cloud metadata), carrier-grade NAT, multicast or
+ * reserved. Returns `false` for anything that isn't an IP address.
+ */
+declare function isPublicAddress(address: string): boolean;
+/**
+ * The default `allowUrl`: HTTPS only, no credentials in the URL, no local
+ * host names, and every address the host resolves to must be public. The
+ * delivery transport calls it again for each redirect.
+ *
+ * DNS can change between this check and the connection. Route webhooks
+ * through an egress proxy when that matters.
+ */
+declare function publicUrl(options?: PublicUrlOptions): AllowUrl;
+//#endregion
+//#region src/webhooks/http.d.ts
+interface WebhookRequest {
+  readonly url: string;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly body: string;
+  readonly signal?: AbortSignal;
+}
+interface WebhookResponse {
+  readonly status: number;
+  readonly body: string;
+  /** Seconds from the `Retry-After` header, when the receiver sent one. */
+  readonly retryAfter?: number;
+}
+/**
+ * Sends one signed webhook request. Throw `WebhookPolicyError` when the
+ * request must never be retried (a blocked URL); any other error retries.
+ */
+interface WebhookTransport {
+  readonly apiVersion: 1;
+  readonly name: string;
+  send(request: WebhookRequest): Promise<WebhookResponse>;
+}
+/** A delivery that must not be retried, e.g. a URL `allowUrl` rejected. */
+declare class WebhookPolicyError extends Error {
+  override readonly name = "WebhookPolicyError";
+}
+interface FetchTransportOptions {
+  readonly fetch?: typeof fetch;
+  /** Checked before the first request and before each redirect. */
+  readonly allowUrl?: AllowUrl;
+  /**
+   * Defaults to 0: a redirect fails the delivery without a retry. Each hop
+   * you allow is checked with `allowUrl` first.
+   */
+  readonly maxRedirects?: number;
+  /** Per request. Defaults to 10 seconds. */
+  readonly timeoutMs?: number;
+  /** The response body bytes kept; the rest is not read. Defaults to 64 KiB. */
+  readonly maxResponseBytes?: number;
+}
+/** Sends webhooks with `fetch`, following redirects only to allowed URLs. */
+declare function fetchTransport(options?: FetchTransportOptions): WebhookTransport;
+//#endregion
+//#region src/webhooks/secrets.d.ts
+interface RotateSecretOptions {
+  /** How long older secrets keep signing, e.g. `'24 hours'` (the default). */
+  readonly overlap?: string;
+  /** Use this secret instead of a generated one, e.g. when migrating. */
+  readonly secret?: string;
+}
+/**
+ * Where endpoint signing secrets live. `sqlSecretStore` (Vault or a
+ * column, set in `kits.webhooks-out.options.secretStorage`) is the default;
+ * implement it for a KMS or a secrets manager.
+ */
+interface WebhookSecretStore {
+  readonly apiVersion: 1;
+  /** The live secrets of an endpoint, newest first. */
+  secrets(endpointId: string): Promise<readonly string[]>;
+  /** Creates a new secret and returns it once. */
+  rotate?(endpointId: string, options?: RotateSecretOptions): Promise<string>;
+}
+/** The kit's `webhook_secrets` and `rotate_webhook_secret` functions. */
+declare function sqlSecretStore(transport: KitTransport, options?: {
+  readonly schema?: string;
+}): WebhookSecretStore;
+//#endregion
+//#region src/webhooks/signers.d.ts
+interface WebhookSignInput {
+  /** The delivery id, the same on every retry so receivers can deduplicate. */
+  readonly id: string;
+  readonly body: string;
+  readonly timestamp: Temporal.Instant;
+  /** The endpoint's live secrets, newest first. Sign with each while rotating. */
+  readonly secrets: readonly string[];
+}
+/**
+ * Adds the signature headers to an outgoing webhook. `standardWebhooks()`
+ * is the default; `hmacSigner()` covers custom header and payload formats.
+ */
+interface WebhookSigner {
+  readonly apiVersion: 1;
+  readonly name: string;
+  sign(input: WebhookSignInput): Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+}
+interface StandardWebhooksOptions {
+  /** Header names, for receivers that expect a prefix such as `svix-`. */
+  readonly headers?: {
+    readonly id?: string;
+    readonly timestamp?: string;
+    readonly signature?: string;
+  };
+}
+/**
+ * Signs with the [Standard Webhooks](https://www.standardwebhooks.com/)
+ * scheme: `webhook-id`, `webhook-timestamp` and one `v1,` signature per
+ * secret in `webhook-signature`. `verifyWebhook` checks it.
+ */
+declare function standardWebhooks(options?: StandardWebhooksOptions): WebhookSigner;
+interface HmacSignerOptions {
+  readonly name?: string;
+  /** e.g. `x-acme-signature`. */
+  readonly signatureHeader: string;
+  /** Sends the epoch-seconds timestamp in this header. */
+  readonly timestampHeader?: string;
+  /** Sends the delivery id in this header. */
+  readonly idHeader?: string;
+  /** The signed text. Defaults to `${timestamp}.${body}`. */
+  readonly content?: (input: {
+    readonly id: string;
+    readonly timestamp: string;
+    readonly body: string;
+  }) => string;
+  /** Defaults to `hex`. */
+  readonly encoding?: "hex" | "base64";
+  /** Written before each signature. Defaults to `v1=`. */
+  readonly prefix?: string;
+  /** Joins the signatures of several secrets. Defaults to `,`. */
+  readonly separator?: string;
+}
+/**
+ * HMAC-SHA256 with the secret's UTF-8 bytes as the key, for receivers that
+ * verify an existing format, e.g. `v1=<hex>` over `timestamp.body`.
+ */
+declare function hmacSigner(options: HmacSignerOptions): WebhookSigner;
+//#endregion
+export { PublicUrlOptions as _, hmacSigner as a, publicUrl as b, WebhookSecretStore as c, WebhookPolicyError as d, WebhookRequest as f, AllowUrl as g, fetchTransport as h, WebhookSigner as i, sqlSecretStore as l, WebhookTransport as m, StandardWebhooksOptions as n, standardWebhooks as o, WebhookResponse as p, WebhookSignInput as r, RotateSecretOptions as s, HmacSignerOptions as t, FetchTransportOptions as u, ResolveHost as v, isPublicAddress as y };

package/dist/{simplify-LakqK1vH.js → simplify-_0oUKqCd.js}

@@ -1,7 +1,8 @@
-import { n as dbError, t as DbException } from "./errors-Bl3rkOzo.js";
-import { i as temporalText } from "./temporal-BwshQk0W.js";
-import { t as temporal } from "./temporal-required-CMxeSVPo.js";
+import { n as isPlainObject } from "./clone-BfgmLU90.js";
+import { n as dbError, t as DbException } from "./errors-DtwXa6b8.js";
+import { t as lookupOf } from "./lookup-BaP5bI27.js";
 import { i as or, r as not, t as and } from "./types-6cYK9pbJ.js";
+import { r as encodeValue } from "./wire-D2dT86vi.js";
 //#region src/schema/define.ts
 /**
 * Binds generated model types to runtime metadata. Called from the generated
@@ -28,90 +29,6 @@ function relationMeta(meta, table, relation) {
 	};
 }
 //#endregion
-//#region src/ir/codec.ts
-/** Wire form of an app value: Temporal values to ISO text, `bigint` to decimal text. */
-function encodeValue(value) {
-	if (typeof value === "bigint") return value.toString();
-	const text = temporalText(value);
-	if (text !== void 0) return text;
-	if (Array.isArray(value)) return value.map(encodeValue);
-	return value;
-}
-function decodeScalar(codec, value) {
-	if (value === null || value === void 0) return value;
-	switch (codec) {
-		case "instant": return temporal().Instant.from(String(value));
-		case "plainDateTime": return temporal().PlainDateTime.from(String(value));
-		case "bigint": return BigInt(value);
-		case "string": return String(value);
-		default: return codec;
-	}
-}
-function decode(codec, value) {
-	return Array.isArray(value) ? value.map((item) => decodeScalar(codec, item)) : decodeScalar(codec, value);
-}
-/** Whether decoding `selection` changes anything, so plain reads skip the walk. */
-function needsDecoding(selection) {
-	return selection.aggregate !== void 0 || selection.columns.some((column) => column.codec !== void 0) || selection.includes.some((include) => include.count !== void 0 || include.aggregate !== void 0 || needsDecoding(include.selection));
-}
-/** PostgREST returns `[{ count }]` for a `(count)` embed; SQL returns the number. */
-function countOf(value) {
-	if (Array.isArray(value)) {
-		const first = value[0];
-		return Number(first?.count ?? 0);
-	}
-	return Number(value ?? 0);
-}
-function measureOf(measure, value) {
-	if (value === void 0 || value === null) return null;
-	return measure.codec ? decodeScalar(measure.codec, value) : value;
-}
-/** Adds `value` under `row[key][name]`, next to what is already there. */
-function fold(row, key, name, value) {
-	row[key] = {
-		...row[key] ?? {},
-		[name]: value
-	};
-}
-function decodeRow(selection, row) {
-	const out = { ...row };
-	for (const column of selection.columns) if (column.codec && column.alias in out) out[column.alias] = decode(column.codec, out[column.alias]);
-	if (selection.aggregate) {
-		if (selection.aggregate.count) out["_count"] = countOf(out["_count"]);
-		for (const measure of selection.aggregate.measures) {
-			const value = out[measure.key];
-			delete out[measure.key];
-			fold(out, `_${measure.fn}`, measure.alias, measureOf(measure, value));
-		}
-	}
-	for (const include of selection.includes) {
-		const value = out[include.alias];
-		if (include.count !== void 0) {
-			if (!(include.alias in out)) continue;
-			delete out[include.alias];
-			fold(out, "_count", include.count, countOf(value));
-			continue;
-		}
-		if (include.aggregate !== void 0) {
-			if (!(include.alias in out)) continue;
-			delete out[include.alias];
-			const inner = Array.isArray(value) ? value[0] : value;
-			const measures = {};
-			for (const measure of include.selection.aggregate?.measures ?? []) measures[measure.alias] = measureOf(measure, inner?.[measure.key]);
-			fold(out, `_${include.aggregate.fn}`, include.aggregate.name, measures);
-			continue;
-		}
-		if (Array.isArray(value)) out[include.alias] = value.map((item) => decodeRow(include.selection, item));
-		else if (value && typeof value === "object") out[include.alias] = decodeRow(include.selection, value);
-	}
-	return out;
-}
-/** Applies column codecs to returned rows, including embedded relations. */
-function decodeRows(selection, rows) {
-	if (!selection || !needsDecoding(selection)) return rows;
-	return rows.map((row) => decodeRow(selection, row));
-}
-//#endregion
 //#region src/ir/build.ts
 const AGGREGATE_KEYS = {
 	_sum: "sum",
@@ -158,11 +75,6 @@ const FIELD_OPS = /* @__PURE__ */ new Set([
 	"has",
 	"containedBy"
 ]);
-function isPlainObject(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const proto = Object.getPrototypeOf(value);
-	return proto === Object.prototype || proto === null;
-}
 function isOpsObject(value) {
 	if (!isPlainObject(value)) return false;
 	const keys = Object.keys(value);
@@ -176,8 +88,20 @@ function writable(meta, mode) {
 function escapeLike(value) {
 	return value.replaceAll(/[\\%_]/g, (char) => `\\${char}`);
 }
+const builders = /* @__PURE__ */ new WeakMap();
+/** The shared builder for a schema; a builder holds no per-call state. */
+function builderFor(meta) {
+	let builder = builders.get(meta);
+	if (!builder) {
+		builder = new IrBuilder(meta);
+		builders.set(meta, builder);
+	}
+	return builder;
+}
 var IrBuilder = class {
 	meta;
+	/** Every column of a table, the selection of reads without `select`. */
+	#allColumns = /* @__PURE__ */ new WeakMap();
 	constructor(meta) {
 		this.meta = meta;
 	}
@@ -323,7 +247,7 @@ var IrBuilder = class {
 		}
 	}
 	selection(table, select, include) {
-		const columns = (select ?? Object.keys(table.columns)).map((alias) => this.selectColumn(table, alias));
+		const columns = select?.map((alias) => this.selectColumn(table, alias)) ?? this.allColumns(table);
 		const includes = [];
 		if (include !== void 0) {
 			if (!isPlainObject(include)) invalidRequest(`"include" on "${table.key}" must be an object`, table.key);
@@ -424,6 +348,14 @@ var IrBuilder = class {
 			codec
 		};
 	}
+	allColumns(table) {
+		let columns = this.#allColumns.get(table);
+		if (!columns) {
+			columns = Object.keys(table.columns).map((alias) => this.selectColumn(table, alias));
+			this.#allColumns.set(table, columns);
+		}
+		return columns;
+	}
 	/** A selected column, with the cast and codec its metadata asks for. */
 	selectColumn(table, alias) {
 		const column = this.column(table, alias);
@@ -531,7 +463,7 @@ var IrBuilder = class {
 	uniqueKey(table, input) {
 		if (!isPlainObject(input)) invalidRequest(`"where" on "${table.key}" must be an object`, table.key);
 		const given = Object.keys(input).filter((key) => input[key] !== void 0);
-		const keys = [table.primaryKey, ...Object.values(table.uniqueKeys)];
+		const { keys } = lookupOf(table);
 		const match = keys.find((key) => key.length > 0 && key.length === given.length && key.every((column) => given.includes(column)));
 		if (!match) {
 			const names = keys.filter((key) => key.length > 0).map((key) => `{ ${key.join(", ")} }`).join(", ");
@@ -656,4 +588,4 @@ function simplifyOrFalse(condition) {
 	};
 }
 //#endregion
-export { invalidRequest as a, needsDecoding as c, escapeLike as i, defineSchema as l, simplifyOrFalse as n, decodeRows as o, IrBuilder as r, encodeValue as s, simplify as t, tableMeta as u };
+export { invalidRequest as a, escapeLike as i, simplifyOrFalse as n, defineSchema as o, builderFor as r, tableMeta as s, simplify as t };

package/dist/sql/index.d.ts

@@ -1,8 +1,154 @@
-import { s as ClaimsMeta } from "../types-DONv9SHN.js";
-import { B as ReadSet } from "../define-DUbydmJa.js";
-import { b as ResolvedConfig } from "../config-C1CYcm6o.js";
-import { n as permdockKeys } from "../permdock-sql-DImJULY-.js";
+import { c as ClaimsMeta } from "../types-Dnf_wRDz.js";
+import { B as ReadSet } from "../define-Bp_BZa5h.js";
+import { b as ResolvedConfig, ct as KitsConfig, lt as ResolvedKitModule, ot as KitMode } from "../config-T_ejwyd3.js";
+import { a as permdockKeys, i as permdockKeyStatus, n as PermdockCatalog, r as PermdockKeyStatus, t as PERMDOCK_SCHEMA } from "../permdock-sql-C2Inc6Xc.js";
+//#region src/sql/context.d.ts
+/** The scope id types kit modules render. */
+export declare const KIT_ID_TYPES: readonly ["uuid", "text", "bigint", "integer"];
+type KitIdType = (typeof KIT_ID_TYPES)[number];
+export declare const isKitIdType: (value: string) => value is KitIdType;
+/**
+ * A Postgres type name as one of `KIT_ID_TYPES`: case and spacing are
+ * normalised and aliases such as `int8` resolved. `undefined` for any other
+ * type, so callers refuse it instead of guessing.
+ */
+export declare function kitIdType(value: string): KitIdType | undefined;
+/** One logical table of a module: its default name and logical columns. */
+interface KitTableSpec {
+  /** Default name, in the module's schema. */
+  readonly name: string;
+  /** Logical column to default column name. */
+  readonly columns: Readonly<Record<string, string>>;
+  /**
+   * Logical columns an adopted table may lack (mapped to `null`): the module
+   * leaves out the feature that needs them.
+   */
+  readonly optional?: readonly string[];
+  /** The app may lack the whole table (`kits.<name>.tables.<table>: null`). */
+  readonly optionalTable?: boolean;
+}
+interface KitNames {
+  readonly tables: Readonly<Record<string, KitTableSpec>>;
+  /** The `before_*` and `after_*` hooks the module calls, so `kits.<name>.hooks.functions` is checked. */
+  readonly hooks?: readonly string[];
+  /** The `kits.<name>.options` keys the module reads; any other key is rejected. */
+  readonly options?: readonly string[];
+}
+/** An event a module writes to the outbox, as SQL expressions. */
+interface KitEmit {
+  /** The event type, e.g. `org.created`. */
+  readonly type: string;
+  /** A `jsonb` expression. */
+  readonly payload: string;
+  /** A `text` expression, e.g. `'organizations/' || new_org`. */
+  readonly subject?: string;
+  /** The tenant id expression; it is cast to text. */
+  readonly tenant?: string;
+  /** A `text` idempotency key expression. */
+  readonly key?: string;
+}
+/** A function of a module's contract: what other modules and the TypeScript side call. */
+interface KitContractFunction {
+  readonly name: string;
+  /** Argument types; `{id}` stands for the module's id type. */
+  readonly args: readonly string[];
+  readonly returns: string;
+}
+/** What a module's `build` reads: resolved names for one layout. */
+interface KitContext {
+  readonly module: string;
+  readonly mode: KitMode;
+  readonly config: ResolvedKitModule;
+  /** The quoted schema of the module's functions and managed tables. */
+  readonly schema: string;
+  readonly schemaName: string;
+  readonly idType: KitIdType;
+  readonly claims: ClaimsMeta;
+  readonly kits: KitsConfig;
+  /** `schema.name` of a module function, quoted. */
+  fn(name: string): string;
+  /** `schema.table` of a logical table, quoted. */
+  table(logical: string): string;
+  /** The unquoted schema and name of a logical table. */
+  tableName(logical: string): {
+    readonly schema: string;
+    readonly name: string;
+  };
+  /** A logical column, quoted. Throws when an adopted table lacks it. */
+  col(table: string, column: string): string;
+  /** Whether a logical column exists (adopted tables can map it to `null`). */
+  has(table: string, column: string): boolean;
+  /** Whether an optional logical table exists (it can be mapped to `null`). */
+  hasTable(table: string): boolean;
+  /** Whether the module owns `table` (managed mode). */
+  readonly manages: boolean;
+  /** The permission key for a kit action, as a SQL literal. */
+  permission(action: string, fallback: string): string;
+  /** The permission key for a kit action. */
+  permissionKey(action: string, fallback: string): string;
+  /** A trigger name with the module's prefix, quoted. */
+  trigger(name: string): string;
+  /** Whether `module` is installed alongside this one. */
+  installed(module: string): boolean;
+  /** The context of another module in the same layout. */
+  of(module: string): KitContext;
+  /** A string module option (`kits.<name>.options`). */
+  text(name: string, fallback: string): string;
+  number(name: string, fallback: number): number;
+  flag(name: string, fallback: boolean): boolean;
+  /** A module option that is a list of strings. */
+  list(name: string, fallback: readonly string[]): readonly string[];
+  /** A declared module option as configured, for object-shaped options. */
+  option(name: string): unknown;
+  /**
+   * PL/pgSQL that calls the app's hook function when it exists, with
+   * `[type, expression]` arguments: `if to_regprocedure(...) is not null
+   * then perform ...; end if;`.
+   */
+  hook(name: string, args: readonly (readonly [string, string])[]): string;
+  /** The app function a hook calls, quoted, for hooks that return a value. */
+  hookTarget(name: string): string;
+  /**
+   * PL/pgSQL that writes the event to the outbox (`emit_event`) when the
+   * `outbox` module is installed and `kits.<name>.events` isn't false;
+   * otherwise an empty string.
+   */
+  emit(event: KitEmit): string;
+}
+/** The contract's argument list with `{id}` resolved, as Postgres prints it. */
+export declare function contractSignature(fn: KitContractFunction, idType: string): string;
+//#endregion
 //#region src/sql/kit.d.ts
+/** The step from one module version to the next, for `sql upgrade`. */
+interface KitUpgrade {
+  /** The installed version this step upgrades from. */
+  readonly from: number;
+  readonly description: string;
+  /** SQL run before the module's current file, e.g. renames and backfills. */
+  readonly sql: (ctx: KitContext) => string;
+}
+/**
+ * A renamed kit symbol. It keeps a compatibility wrapper for at least one
+ * minor release, then is removed; doctor reports uses of both (BS309), and
+ * the name stays reserved.
+ */
+interface KitDeprecation {
+  readonly kind: "function" | "claim" | "table" | "column";
+  /** The old name: `schema.function`, a claim name, `schema.table` or `table.column`. */
+  readonly symbol: string;
+  /** What to use instead. */
+  readonly use: string;
+  /** The package version that deprecated it. */
+  readonly since: string;
+  /** The package version that removed it; until then `wrapper` is written. */
+  readonly removed?: string;
+  /**
+   * The compatibility wrapper the module file keeps, e.g. a function with the
+   * old name that calls the new one and a `comment on function ... is
+   * 'deprecated: use X'`.
+   */
+  readonly wrapper?: (ctx: KitContext) => string;
+}
 /**
  * SQL kit modules for `better-supabase sql add`. Every module is idempotent
  * (`create or replace`, `if not exists`), so re-running it upgrades in place.
@@ -15,19 +161,42 @@ interface SqlModule {
   readonly requires: readonly string[];
   /** What it needs instead when the layout has `permdock`. */
   readonly permdockRequires?: readonly string[];
+  /** What it needs for this layout, e.g. per `kits.access.model`; overrides both. */
+  readonly dependencies?: (layout: KitLayout) => readonly string[];
   /** `schema` files go with your schemas; `test` files go to `supabase/tests`. */
   readonly target: "schema" | "test";
   /** The module with the default claim names. */
   readonly sql: string;
   /** The module for configured claim names (`config.claims`), when it reads claims. */
   readonly render?: (claims: ClaimsMeta, layout: KitLayout) => string;
+  /** Bumped when installed databases need an upgrade step. Defaults to 1. */
+  readonly version?: number;
+  /** The modes `kits.<name>.mode` accepts. Defaults to `managed` only. */
+  readonly modes?: readonly KitMode[];
+  /** The logical tables and columns `kits.<name>.tables` and `columns` map. */
+  readonly names?: KitNames;
+  /** The functions other modules and the TypeScript side call. */
+  readonly contract?: (ctx: KitContext) => readonly KitContractFunction[];
+  /** Renders the module for a layout; takes precedence over `render`. */
+  readonly build?: (ctx: KitContext, layout: KitLayout) => string;
+  readonly upgrades?: readonly KitUpgrade[];
+  readonly deprecated?: readonly KitDeprecation[];
+  /**
+   * Rows, role settings and calls that a schema diff doesn't capture. They
+   * go to `better-supabase-data/` next to the schema folder and a migration
+   * (`sql data`) instead of the schema file.
+   */
+  readonly data?: (ctx: KitContext, layout: KitLayout) => string;
 }
+export declare const moduleVersion: (module: SqlModule) => number;
 /** New modules go at the end: the position is part of the file name. */
 export declare const SQL_MODULES: Readonly<Record<string, SqlModule>>;
 /** The modules to install for `names`, dependencies first. Throws on an unknown name. */
 export declare function resolveModules(names: readonly string[], layout?: KitLayout): SqlModule[];
 interface KitFile {
   readonly module: string;
+  /** `schema` and `test` files are diffed; `data` files go in a migration too. */
+  readonly kind: "schema" | "data" | "test";
   readonly path: string;
   readonly contents: string;
 }
@@ -42,7 +211,9 @@ interface KitLayout {
   readonly version?: string;
   /** `config.realtime.tables`: registered at the end of the `realtime-tables` module. */
   readonly realtimeTables?: readonly string[];
-  /** Tenant column passed to `track_realtime`; tables without it broadcast unscoped. */
+  /** `config.realtime.global`: tables registered with `tenant_column => null`. */
+  readonly realtimeGlobal?: readonly string[];
+  /** Tenant column passed to `track_realtime` for the other tables. */
   readonly tenantColumn?: string;
   /** Check constraints for the `jsonb-schemas` module. */
   readonly jsonSchemas?: readonly JsonSchemaCheck[];
@@ -61,6 +232,8 @@ interface KitLayout {
   readonly claims?: ClaimsMeta;
   /** PermDock's helpers and membership sources, from its manifest: `entitlements` reads them instead of `tenant`. */
   readonly permdock?: KitPermdock;
+  /** `config.kits`: modes, names and permission keys per module. */
+  readonly kits?: KitsConfig;
 }
 /** One PermDock membership source, from the manifest's `memberships`. */
 interface KitMembershipSource {
@@ -80,6 +253,8 @@ interface KitPermdock {
   readonly schema: string;
   /** The PermDock scope tenants map to, e.g. `organization`. */
   readonly scope: string;
+  /** The scope's id type, from the manifest's `rls.scopes[].type`. */
+  readonly idType: KitIdType;
   readonly memberships: readonly KitMembershipSource[];
 }
 /** An embedding column `db.$search` can query. */
@@ -91,10 +266,10 @@ interface VectorSearchTable {
 }
 /** The table holding each tenant's Stripe customer id. */
 interface EntitlementsSource {
-  /** `table` or `schema.table`. */
-  readonly table: string;
+  /** `table` or `schema.table`; unset uses the `organizations` module's. */
+  readonly table?: string;
   /** Column with the Stripe customer id (`cus_...`). */
-  readonly column: string;
+  readonly column?: string;
   /** Column with the tenant id. */
   readonly key: string;
 }
@@ -114,13 +289,75 @@ interface JsonSchemaCheck {
 }
 /** Whether an installed file matches, ignoring the version stamped in its header. */
 export declare function sameKitFile(current: string | undefined, expected: string): boolean;
-/** The files `sql add` writes for these modules. */
+/** The installed version of a kit file, from its `@bs-kit` line. */
+export declare function kitFileVersion(contents: string): {
+  readonly module: string;
+  readonly version: number;
+} | undefined;
+/** A module's SQL for `layout`, without header; `undefined` in custom mode. */
+export declare function moduleBody(name: string, layout?: KitLayout): string | undefined;
+/**
+ * The files `sql add` writes for these modules. Modules in `custom` mode
+ * write nothing: the app implements their contract. A schema module's rows,
+ * role settings and other statements a schema diff can't capture go to a
+ * second file in `better-supabase-data/` (`kind: 'data'`), which
+ * `sql data` writes into a migration.
+ */
 export declare function renderKit(names: readonly string[], layout?: KitLayout): KitFile[];
+/** An installed module, from its file's `@bs-kit` line or `kit_modules`. */
+interface InstalledKitModule {
+  readonly module: string;
+  readonly version: number;
+}
+/** What `sql upgrade` runs for one module behind the current version. */
+interface KitUpgradePlan {
+  readonly module: string;
+  readonly from: number;
+  readonly to: number;
+  readonly steps: readonly {
+    readonly from: number;
+    readonly description: string;
+    readonly sql: string;
+  }[];
+}
+/**
+ * The upgrade steps for modules installed at an older version. A version
+ * without a step needs none: the module file upgrades in place. Modules in
+ * custom mode belong to the app and are skipped.
+ */
+export declare function upgradePlan(installed: readonly InstalledKitModule[], layout?: KitLayout, modules?: Readonly<Record<string, SqlModule>>): KitUpgradePlan[];
+/** Every deprecated or removed kit symbol, with its module. */
+export declare function kitDeprecations(modules?: Readonly<Record<string, SqlModule>>): readonly (KitDeprecation & {
+  readonly module: string;
+})[];
+/** The contract functions of the modules in `custom` mode, for doctor. */
+export declare function customContracts(names: readonly string[], layout?: KitLayout): {
+  readonly module: string;
+  readonly schema: string;
+  readonly idType: KitIdType;
+  readonly functions: readonly KitContractFunction[];
+}[];
 //#endregion
 //#region src/sql/layout.d.ts
 /** Where and how `sql add` writes kit files for this config. */
 export declare function kitLayout(config: ResolvedConfig, testsDir?: string, readSets?: KitLayout["readSets"], permdock?: KitPermdock): KitLayout;
 //#endregion
+//#region src/sql/migration-options.d.ts
+/** A migration-only option a config sets. */
+interface MigrationOptionUse {
+  readonly module: string;
+  readonly option: string;
+  readonly value: unknown;
+  readonly adopted: boolean;
+  /** `kits.<module>.options.<option> ... It <effect>.` */
+  readonly message: string;
+}
+/**
+ * The migration-only options `kits` sets to a value other than the managed
+ * default. They are accepted in `adopt` mode only; doctor warns about each.
+ */
+export declare function migrationOptionUses(kits?: KitsConfig): MigrationOptionUse[];
+//#endregion
 //#region src/sql/read-sets.d.ts
 /** A read set compiled to the SQL of its function. */
 interface CompiledReadSet {
@@ -136,4 +373,4 @@ export declare function compileReadSet(set: ReadSet): Promise<CompiledReadSet>;
 /** Compiles every set, sorted by name. Throws on a duplicate name. */
 export declare function compileReadSets(sets: readonly ReadSet[]): Promise<CompiledReadSet[]>;
 //#endregion
-export { type CompiledReadSet, type KitFile, type KitLayout, type KitPermdock, type SqlModule, permdockKeys };
+export { type CompiledReadSet, type InstalledKitModule, type KitContext, type KitContractFunction, type KitDeprecation, type KitFile, type KitIdType, type KitLayout, type KitNames, type KitPermdock, type KitTableSpec, type KitUpgrade, type KitUpgradePlan, type MigrationOptionUse, PERMDOCK_SCHEMA, type PermdockCatalog, type PermdockKeyStatus, type SqlModule, permdockKeyStatus, permdockKeys };