better-supabase 0.0.0 → 0.1.0

package/dist/plugin-HvGqCurB.d.ts

@@ -0,0 +1,118 @@
+import { A as TableMeta, E as SchemaMeta, n as AnyModels } from "./types-C2fslP1z.js";
+import { g as Operation, h as MutationOp, r as Executor } from "./executor-Bazhgsgq.js";
+import { v as ErrorMapper } from "./result-CTkCZ6JA.js";
+//#region src/core/plugin.d.ts
+/** Who is making the request. */
+interface Actor {
+  readonly id: string;
+  readonly kind: "user" | "service" | "anon";
+  readonly role?: string;
+  readonly email?: string;
+  /** The admin acting as this user (the `act` claim's `sub`). */
+  readonly impersonator?: string;
+}
+/**
+ * Per-connection context. Server adapters fill it from the verified JWT;
+ * plugins read it (`tenant()` reads `tenant`, `actor()` reads `actor`).
+ */
+interface RequestContext {
+  readonly actor?: Actor;
+  readonly tenant?: string;
+  readonly claims?: Readonly<Record<string, unknown>>;
+  readonly [key: string]: unknown;
+}
+/** Plugin-specific per-call options (`withDeleted`, `hard`, ...). */
+type CallOptions = Readonly<Record<string, unknown>>;
+interface HookArgs {
+  readonly table: TableMeta;
+  readonly schema: SchemaMeta;
+  readonly context: RequestContext;
+  readonly options: CallOptions;
+  readonly now: () => Date;
+}
+type MutationKind = "insert" | "upsert" | "update" | "delete";
+interface MutationEvent {
+  readonly table: TableMeta;
+  readonly kind: MutationKind;
+  /** App-cased rows returned by the mutation. */
+  readonly rows: readonly Readonly<Record<string, unknown>>[];
+  readonly context: RequestContext;
+}
+/** Runtime handle passed to `Plugin.repository`. */
+interface RepositoryApi {
+  readonly table: TableMeta;
+  readonly base: Readonly<Record<string, (...args: never[]) => unknown>>;
+}
+/**
+ * Type-level repository extension, applied per table. Implement it as an
+ * interface that reads `this['M']` and `this['T']`:
+ *
+ * ```ts
+ * interface RestoreExtension extends RepositoryExtension {
+ *   readonly methods: HasFlag<this['M'], this['T'], 'softDelete'> extends true
+ *     ? { restore(id: string): AsyncResult<unknown> }
+ *     : unknown;
+ * }
+ * ```
+ */
+interface RepositoryExtension {
+  readonly M: AnyModels;
+  readonly T: string;
+  readonly methods: unknown;
+  readonly findArgs: unknown;
+  readonly deleteArgs: unknown;
+}
+/**
+ * Applies the extensions in `E` to table `T`. `E` is a tuple of extensions (as
+ * built by `use()`) or a single extension. Each is applied on its own because
+ * indexing an intersection of `this`-typed interfaces overflows TS < 7.
+ */
+/** Default extension of plugins that add no repository types. */
+interface NoExtension extends RepositoryExtension {
+  readonly "~none": true;
+}
+type ApplyExtension<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends readonly [infer Head, ...infer Rest] ? ApplyOne<Head, M, T, K> & ApplyExtension<Rest, M, T, K> : ApplyOne<E, M, T, K>;
+type ApplyOne<E, M extends AnyModels, T extends keyof M, K extends "methods" | "findArgs" | "deleteArgs"> = E extends RepositoryExtension ? (E & {
+  readonly M: M;
+  readonly T: T;
+})[K] : unknown;
+/** True when table `T` has the flag set by codegen. */
+type HasFlag<M, T, F extends string> = M extends AnyModels ? T extends keyof M ? M[T]["Flags"] extends { readonly [K in F]: unknown; } ? true : false : false : false;
+declare const PLUGIN_API_VERSION = 1;
+/**
+ * Plugin API v1. Every hook is optional. Hooks run in `use()` order.
+ */
+interface Plugin<Name extends string = string, Ext extends RepositoryExtension = NoExtension> {
+  readonly apiVersion: 1;
+  readonly name: Name;
+  /**
+   * Hook order: `pre` plugins run first, `post` plugins last, the rest in
+   * `use()` order. Validation is `post` so it sees columns other plugins fill.
+   */
+  readonly enforce?: "pre" | "post";
+  /** `ir`: rewrite an operation before it runs (filters, defaults). */
+  readonly transformQuery?: (op: Operation, args: HookArgs) => Operation;
+  /** `mutation`: rewrite a mutation or reject it by throwing a `DbException`. */
+  readonly beforeMutation?: (op: MutationOp, args: HookArgs) => MutationOp | Promise<MutationOp>;
+  /** `mutation`: observe a finished mutation. Cannot change the result. */
+  readonly afterMutation?: (event: MutationEvent) => void | Promise<void>;
+  /** `execute`: wrap the executor for tracing, caching or retries. */
+  readonly wrapExecutor?: (executor: Executor) => Executor;
+  /** `errors`: map custom SQLSTATE or hint codes to `DbError`s. */
+  readonly mapError?: ErrorMapper;
+  /** `repository`: add methods to the repositories of matching tables. */
+  readonly repository?: (api: RepositoryApi) => Readonly<Record<string, (...args: never[]) => unknown>> | undefined;
+  /** Phantom carrying the repository extension type. */
+  readonly "~ext"?: Ext;
+}
+type AnyPlugin = Plugin<string, any>;
+/** The plugin's repository extension; `unknown` for plugins that add none. */
+type ExtensionOf<P> = P extends Plugin<string, infer E> ? E extends NoExtension ? unknown : E : never;
+/** `E` with extension `X` appended, as a tuple. */
+type WithExtension<E, X> = unknown extends X ? E : E extends readonly unknown[] ? readonly [...E, X] : unknown extends E ? readonly [X] : readonly [E, X];
+/** Identity helper that fixes `apiVersion` and infers the plugin types. */
+declare function definePlugin<const Name extends string, Ext extends RepositoryExtension = NoExtension>(plugin: Omit<Plugin<Name, Ext>, "apiVersion"> & {
+  readonly apiVersion?: 1;
+}): Plugin<Name, Ext>;
+//#endregion
+export { definePlugin as _, ExtensionOf as a, MutationEvent as c, PLUGIN_API_VERSION as d, Plugin as f, WithExtension as g, RequestContext as h, CallOptions as i, MutationKind as l, RepositoryExtension as m, AnyPlugin as n, HasFlag as o, RepositoryApi as p, ApplyExtension as r, HookArgs as s, Actor as t, NoExtension as u };

package/dist/plugins/actor/index.d.ts

@@ -0,0 +1,13 @@
+import { f as Plugin, h as RequestContext } from "../../plugin-HvGqCurB.js";
+//#region src/plugins/actor/index.d.ts
+export interface ActorOptions {
+  /** Custom actor id resolution. Defaults to `context.actor.id` for users and services. */
+  readonly resolve?: (context: RequestContext) => string | undefined;
+}
+/**
+ * Stamps the columns generated as `Flags.actor`: `createdBy` on insert and
+ * `updatedBy` on insert and update. Soft deletes are updates, so they record
+ * who deleted the row. Without an actor (anonymous requests) nothing is set.
+ */
+export declare function actor(options?: ActorOptions): Plugin<"actor">;
+//#endregion

package/dist/plugins/actor/index.js

@@ -0,0 +1,43 @@
+import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
+import { i as insertsOnly, l as withDefault, t as dbName } from "../../shared-_6-uPL7E.js";
+//#region src/plugins/actor/index.ts
+function defaultActor(context) {
+	const actor = context.actor;
+	return actor && actor.kind !== "anon" ? actor.id : void 0;
+}
+/**
+* Stamps the columns generated as `Flags.actor`: `createdBy` on insert and
+* `updatedBy` on insert and update. Soft deletes are updates, so they record
+* who deleted the row. Without an actor (anonymous requests) nothing is set.
+*/
+function actor(options = {}) {
+	const resolve = options.resolve ?? defaultActor;
+	return definePlugin({
+		name: "actor",
+		beforeMutation(op, { table, context }) {
+			const flags = table.flags.actor;
+			if (!flags) return op;
+			const id = resolve(context);
+			if (id === void 0) return op;
+			const created = dbName(table, flags.createdBy);
+			const updated = dbName(table, flags.updatedBy);
+			switch (op.kind) {
+				case "insert": {
+					const stampCreated = insertsOnly(op);
+					return {
+						...op,
+						rows: op.rows.map((row) => withDefault(stampCreated ? withDefault(row, created, id) : row, updated, id))
+					};
+				}
+				case "update": return {
+					...op,
+					set: withDefault(op.set, updated, id)
+				};
+				case "delete": return op;
+				default: return op;
+			}
+		}
+	});
+}
+//#endregion
+export { actor };

package/dist/plugins/rules/index.d.ts

@@ -0,0 +1,88 @@
+import { g as Operation } from "../../executor-Bazhgsgq.js";
+import { f as Plugin, m as RepositoryExtension } from "../../plugin-HvGqCurB.js";
+//#region src/plugins/rules/index.d.ts
+export type RuleLevel = "off" | "warn" | "error";
+/** A level, or a level with the rule's option: `['error', 500]`. */
+export type RuleSetting<Option = never> = RuleLevel | ([Option] extends [never] ? never : readonly [RuleLevel, Option]);
+export interface RuleSet {
+  /** `findMany` without `limit` (reads the whole table). */
+  readonly noUnboundedFindMany?: RuleSetting;
+  /** `limit` above the given maximum (default 1000). */
+  readonly maxLimit?: RuleSetting<number>;
+  /**
+   * Paging (`offset`, or `limit` above 1) without `orderBy`: Postgres returns
+   * rows in no particular order, so pages overlap or skip rows. `findMany`
+   * orders by the primary key by default, so this only fires on views and
+   * tables without one.
+   */
+  readonly requireOrderByForCursor?: RuleSetting;
+  /** Includes nested deeper than the given depth (default 3). */
+  readonly maxIncludeDepth?: RuleSetting<number>;
+  /**
+   * Tenant tables queried without a tenant: neither `context.tenant` nor the
+   * given claim (default `org_id`). Service connections are exempt.
+   */
+  readonly requireTenantContext?: RuleSetting<string>;
+  /** A service-role connection used where `window` and `document` exist. */
+  readonly noAdminInBrowser?: RuleSetting;
+  /**
+   * Reads of columns listed in `config.sensitive` without `sensitive: true`
+   * on the call.
+   */
+  readonly noSensitiveSelect?: RuleSetting;
+  /**
+   * Delete operations without `where`. The repository refuses `deleteMany`
+   * without `where` on its own, so this catches deletes built by plugins;
+   * the lint rule of the same name flags the call in the editor.
+   */
+  readonly noDeleteManyWithoutWhere?: RuleSetting;
+  /**
+   * Storage objects written to `*_url` text columns: a column listed in
+   * `storagePaths`, or a value that is a Storage URL or matches a bucket's
+   * path template. Signed URLs expire and public URLs pin the project host,
+   * so store the path in a `*_path` column and build URLs when rendering.
+   */
+  readonly storagePathColumns?: RuleSetting;
+}
+export type RuleName = keyof RuleSet;
+export interface RuleViolation {
+  readonly rule: RuleName;
+  readonly level: "warn" | "error";
+  readonly table: string;
+  readonly operation: Operation["kind"];
+  readonly message: string;
+}
+export interface RulesOptions {
+  readonly rules?: RuleSet;
+  /**
+   * Called for every violation. Defaults to `console.warn` for warnings.
+   * Errors fail the call with `invalid_request` after reporting.
+   */
+  readonly report?: (violation: RuleViolation) => void;
+}
+export interface RulesFindArgs {
+  /** Allow reading `config.sensitive` columns in this call. */
+  readonly sensitive?: boolean;
+}
+export interface RulesExtension extends RepositoryExtension {
+  readonly findArgs: RulesFindArgs;
+}
+/** Catches data-exposure and correctness mistakes; everything else off. */
+export declare function safe(): RuleSet;
+/** `safe()` plus performance warnings. */
+export declare function recommended(): RuleSet;
+/** Every rule as an error. */
+export declare function strict(): RuleSet;
+/**
+ * Runtime query rules, checked before each request is built:
+ *
+ * ```ts
+ * defineSupabase(schema, { plugins: [rules({ rules: recommended() })] });
+ * ```
+ *
+ * Runs first (`enforce: 'pre'`) so it sees the query as written, before
+ * tenant or soft-delete filters are added. Pair with the static
+ * `better-supabase/lint` plugin to catch the same mistakes in the editor.
+ */
+export declare function rules(options?: RulesOptions): Plugin<"rules", RulesExtension>;
+//#endregion

package/dist/plugins/rules/index.js

@@ -0,0 +1,174 @@
+import { n as dbError, t as DbException } from "../../errors-Bl3rkOzo.js";
+import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
+//#region src/plugins/rules/index.ts
+/** Catches data-exposure and correctness mistakes; everything else off. */
+function safe() {
+	return {
+		noAdminInBrowser: "error",
+		noDeleteManyWithoutWhere: "error",
+		noSensitiveSelect: "error",
+		requireTenantContext: "error"
+	};
+}
+/** `safe()` plus performance warnings. */
+function recommended() {
+	return {
+		...safe(),
+		noUnboundedFindMany: "warn",
+		maxLimit: ["warn", 1e3],
+		requireOrderByForCursor: "warn",
+		maxIncludeDepth: ["warn", 3],
+		storagePathColumns: "warn"
+	};
+}
+/** Every rule as an error. */
+function strict() {
+	return {
+		...safe(),
+		noUnboundedFindMany: "error",
+		maxLimit: ["error", 1e3],
+		requireOrderByForCursor: "error",
+		maxIncludeDepth: ["error", 3],
+		storagePathColumns: "error"
+	};
+}
+function levelOf(setting) {
+	if (setting === void 0) return "off";
+	return typeof setting === "string" ? setting : setting[0];
+}
+function optionOf(setting, fallback) {
+	return Array.isArray(setting) ? setting[1] : fallback;
+}
+function includeDepth(selection) {
+	let depth = 0;
+	for (const include of selection.includes) if (include.count !== void 0 || include.aggregate !== void 0) depth = Math.max(depth, 1);
+	else depth = Math.max(depth, 1 + includeDepth(include.selection));
+	return depth;
+}
+function sensitiveColumns(selection, table) {
+	const found = [];
+	const sensitive = new Set(Object.values(table.columns).filter((column) => column.sensitive).map((column) => column.db));
+	const columns = [...selection.columns, ...selection.aggregate?.measures ?? []];
+	for (const column of columns) if (sensitive.has(column.column)) found.push(`${table.key}.${column.column}`);
+	for (const include of selection.includes) found.push(...sensitiveColumns(include.selection, include.target));
+	return found;
+}
+function isBrowser() {
+	return typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined";
+}
+function claimValue(context, claim) {
+	let value = context.claims;
+	for (const part of claim.split(".")) {
+		if (typeof value !== "object" || value === null) return void 0;
+		value = value[part];
+	}
+	return value;
+}
+const TEXT_TYPES = /* @__PURE__ */ new Set([
+	"text",
+	"varchar",
+	"bpchar"
+]);
+const STORAGE_URL = /\/storage\/v1\/(?:object|render\/image)\/(?:public|sign|authenticated)\//;
+const templatesBySchema = /* @__PURE__ */ new WeakMap();
+/** Bucket templates specific enough to identify a path: some literal text besides `/`. */
+function bucketTemplates(schema) {
+	let templates = templatesBySchema.get(schema);
+	if (!templates) {
+		templates = Object.values(schema.buckets ?? {}).filter((bucket) => bucket.path.replace(/\{[^}]*\}|\//g, "").length > 0).map((bucket) => new RegExp(`^${bucket.path.split(/\{[^}]*\}/).map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("[^/]+")}$`));
+		templatesBySchema.set(schema, templates);
+	}
+	return templates;
+}
+function storedObjectColumn(op, schema) {
+	const rows = op.kind === "insert" ? op.rows : op.kind === "update" ? [op.set] : [];
+	if (rows.length === 0) return void 0;
+	for (const column of Object.values(op.table.columns)) {
+		if (!rows.some((row) => column.db in row) || !column.db.endsWith("_url") || column.array || !TEXT_TYPES.has(column.type)) continue;
+		const path = `${column.db.slice(0, -4)}_path`;
+		if (column.storage !== void 0) return `"${column.db}" holds paths in bucket "${column.storage}"; name it "${path}"`;
+		if (rows.some((row) => {
+			const value = row[column.db];
+			return typeof value === "string" && (STORAGE_URL.test(value) || bucketTemplates(schema).some((template) => template.test(value)));
+		})) return `"${column.db}" is given a storage object; store its path in "${path}" and build URLs with signedUrl() or renderUrl()`;
+	}
+}
+function checks(rules) {
+	return {
+		noUnboundedFindMany: (op) => op.kind === "select" && op.single === void 0 && !op.head && op.limit === void 0 ? "findMany without limit reads every visible row" : void 0,
+		maxLimit: (op) => {
+			const max = optionOf(rules.maxLimit, 1e3);
+			return op.kind === "select" && op.limit !== void 0 && op.limit > max ? `limit ${op.limit} is above the maximum of ${max}` : void 0;
+		},
+		requireOrderByForCursor: (op) => op.kind === "select" && !op.head && op.orderBy.length === 0 && (op.offset !== void 0 || op.limit !== void 0 && op.limit > 1) ? "paging without orderBy returns rows in no stable order" : void 0,
+		maxIncludeDepth: (op) => {
+			const max = optionOf(rules.maxIncludeDepth, 3);
+			const selection = op.kind === "select" ? op.selection : op.returning;
+			const depth = selection ? includeDepth(selection) : 0;
+			return depth > max ? `includes nest ${depth} levels deep (maximum ${max})` : void 0;
+		},
+		requireTenantContext: (op, { context }) => {
+			if (!op.table.flags.tenant || context.actor?.kind === "service") return void 0;
+			const claim = optionOf(rules.requireTenantContext, "org_id");
+			return context.tenant === void 0 && claimValue(context, claim) === void 0 ? `"${op.table.key}" is tenant-scoped but the request has no tenant (context.tenant or claim "${claim}")` : void 0;
+		},
+		noAdminInBrowser: (_op, { context }) => context.actor?.kind === "service" && isBrowser() ? "a service-role connection is running in a browser" : void 0,
+		noSensitiveSelect: (op, { options }) => {
+			if (options["sensitive"] === true) return void 0;
+			const selection = op.kind === "select" ? op.selection : op.returning;
+			const columns = selection ? sensitiveColumns(selection, op.table) : [];
+			return columns.length > 0 ? `reads sensitive column(s) ${columns.join(", ")}; pass { sensitive: true } to allow` : void 0;
+		},
+		noDeleteManyWithoutWhere: (op) => op.kind === "delete" && op.where === void 0 ? "delete without where removes every visible row" : void 0,
+		storagePathColumns: (op, { schema }) => storedObjectColumn(op, schema)
+	};
+}
+function defaultReport(violation) {
+	if (violation.level === "warn") console.warn(`[better-supabase] ${violation.rule} (${violation.table}): ${violation.message}`);
+}
+/**
+* Runtime query rules, checked before each request is built:
+*
+* ```ts
+* defineSupabase(schema, { plugins: [rules({ rules: recommended() })] });
+* ```
+*
+* Runs first (`enforce: 'pre'`) so it sees the query as written, before
+* tenant or soft-delete filters are added. Pair with the static
+* `better-supabase/lint` plugin to catch the same mistakes in the editor.
+*/
+function rules(options = {}) {
+	const set = options.rules ?? recommended();
+	const report = options.report ?? defaultReport;
+	const all = checks(set);
+	const active = Object.keys(all).flatMap((rule) => {
+		const level = levelOf(set[rule]);
+		return level === "off" ? [] : [{
+			rule,
+			level,
+			check: all[rule]
+		}];
+	});
+	return definePlugin({
+		name: "rules",
+		enforce: "pre",
+		transformQuery(op, hook) {
+			for (const { rule, level, check } of active) {
+				const message = check(op, hook);
+				if (message === void 0) continue;
+				const violation = {
+					rule,
+					level,
+					table: op.table.key,
+					operation: op.kind,
+					message
+				};
+				report(violation);
+				if (level === "error") throw new DbException(dbError("invalid_request", `${rule}: ${message}`, { table: op.table.key }));
+			}
+			return op;
+		}
+	});
+}
+//#endregion
+export { recommended, rules, safe, strict };

package/dist/plugins/soft-delete/index.d.ts

@@ -0,0 +1,38 @@
+import { y as PrimaryKeyValue } from "../../types-C2fslP1z.js";
+import { t as AsyncResult } from "../../result-CTkCZ6JA.js";
+import { f as Plugin, m as RepositoryExtension, o as HasFlag } from "../../plugin-HvGqCurB.js";
+//#region src/plugins/soft-delete/index.d.ts
+export interface SoftDeleteFindArgs {
+  /** Include soft-deleted rows of the queried table. */
+  readonly withDeleted?: boolean;
+  /** Only return soft-deleted rows of the queried table. */
+  readonly onlyDeleted?: boolean;
+}
+export interface SoftDeleteDeleteArgs {
+  /** Delete the row for real instead of setting the soft-delete column. */
+  readonly hard?: boolean;
+}
+export interface SoftDeleteMethods<K> {
+  /** Clears the soft-delete column. `not_found` when the row does not exist. */
+  readonly restore: (key: K, args?: {
+    readonly signal?: AbortSignal;
+  }) => AsyncResult<void>;
+}
+export interface SoftDeleteExtension extends RepositoryExtension {
+  readonly methods: HasFlag<this["M"], this["T"], "softDelete"> extends true ? SoftDeleteMethods<PrimaryKeyValue<this["M"], this["T"]>> : unknown;
+  readonly findArgs: HasFlag<this["M"], this["T"], "softDelete"> extends true ? SoftDeleteFindArgs : unknown;
+  readonly deleteArgs: HasFlag<this["M"], this["T"], "softDelete"> extends true ? SoftDeleteDeleteArgs : unknown;
+}
+/**
+ * Soft delete for tables generated with `Flags.softDelete`:
+ *
+ * - reads, updates and deletes skip deleted rows, including inside includes
+ *   and relation filters (`withDeleted` / `onlyDeleted` change the root table);
+ * - `delete` sets the column instead (`{ hard: true }` really deletes);
+ * - `restore(key)` clears it.
+ *
+ * Deletes become updates without `RETURNING`, so a SELECT policy that hides
+ * deleted rows does not make them fail.
+ */
+export declare function softDelete(): Plugin<"softDelete", SoftDeleteExtension>;
+//#endregion

package/dist/plugins/soft-delete/index.js

@@ -0,0 +1,69 @@
+import { t as and } from "../../types-6cYK9pbJ.js";
+import { i as ok, t as AsyncResult } from "../../result-DWXatkd6.js";
+import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
+import { n as scopeOperation } from "../../scope-CDHcS7dE.js";
+import { a as isNotNull, o as isNull, t as dbName } from "../../shared-_6-uPL7E.js";
+//#region src/plugins/soft-delete/index.ts
+function deletedColumn(table) {
+	return dbName(table, table.flags.softDelete);
+}
+function scopeFor(table) {
+	const column = deletedColumn(table);
+	return column ? isNull(column) : void 0;
+}
+/**
+* Soft delete for tables generated with `Flags.softDelete`:
+*
+* - reads, updates and deletes skip deleted rows, including inside includes
+*   and relation filters (`withDeleted` / `onlyDeleted` change the root table);
+* - `delete` sets the column instead (`{ hard: true }` really deletes);
+* - `restore(key)` clears it.
+*
+* Deletes become updates without `RETURNING`, so a SELECT policy that hides
+* deleted rows does not make them fail.
+*/
+function softDelete() {
+	return definePlugin({
+		name: "softDelete",
+		enforce: "pre",
+		transformQuery(op, { options }) {
+			const hardDelete = op.kind === "delete" && options["hard"] === true;
+			const withDeleted = options["withDeleted"] === true || hardDelete;
+			const onlyDeleted = options["onlyDeleted"] === true;
+			const scoped = scopeOperation(op, scopeFor, !withDeleted && !onlyDeleted);
+			const column = deletedColumn(op.table);
+			if (!onlyDeleted || !column || scoped.kind === "insert") return scoped;
+			return {
+				...scoped,
+				where: and(scoped.where, isNotNull(column))
+			};
+		},
+		beforeMutation(op, { table, options, now }) {
+			if (op.kind !== "delete" || options["hard"] === true) return op;
+			const column = deletedColumn(table);
+			if (!column) return op;
+			return {
+				kind: "update",
+				table,
+				set: { [column]: now().toISOString() },
+				where: op.where,
+				returning: void 0
+			};
+		},
+		repository({ table, base }) {
+			const flag = table.flags.softDelete;
+			if (!flag) return void 0;
+			const update = base["update"];
+			return { restore: (key, args) => AsyncResult.from(async () => {
+				const result = await update(key, { [flag]: null }, {
+					...args,
+					withDeleted: true,
+					returning: false
+				});
+				return result.ok ? ok(void 0) : result;
+			}) };
+		}
+	});
+}
+//#endregion
+export { softDelete };

package/dist/plugins/tenant/index.d.ts

@@ -0,0 +1,43 @@
+import { f as Plugin, h as RequestContext, m as RepositoryExtension, o as HasFlag } from "../../plugin-HvGqCurB.js";
+//#region src/plugins/tenant/index.d.ts
+/**
+ * Dotted paths to the string claims of `C` (up to three levels), e.g.
+ * `'tenant_id' | 'app_metadata.tenant_id'`. Any string without a claims type.
+ */
+export type ClaimPath<C> = unknown extends C ? string : StringPaths<C, [1, 2, 3]>;
+type StringPaths<T, Depth extends readonly unknown[]> = T extends object ? T extends readonly unknown[] ? never : { [K in keyof T & string]-?: (NonNullable<T[K]> extends string ? K : never) | (Depth extends readonly [unknown, ...infer Rest] ? `${K}.${StringPaths<NonNullable<T[K]>, Rest>}` : never); }[keyof T & string] : never;
+/** `C` is the claims type (`sb.claims(schema)`'s output); it types `claim`. */
+export interface TenantOptions<C = unknown> {
+  /**
+   * JWT claim path(s) holding the tenant id when `context.tenant` is not set.
+   * Dots walk into objects. Default `['org_id', 'app_metadata.org_id']`.
+   */
+  readonly claim?: ClaimPath<C> | readonly ClaimPath<C>[];
+  /** Custom resolution, e.g. from a header validated against memberships. */
+  readonly resolve?: (context: RequestContext) => string | undefined;
+  /**
+   * What happens on a tenant table without a tenant in the context:
+   * `error` (default) fails with `forbidden`; `skip` leaves it to RLS.
+   */
+  readonly onMissing?: "error" | "skip";
+}
+export interface TenantFindArgs {
+  /** Skip the tenant filter for this call (admin tooling, jobs). RLS still applies. */
+  readonly allTenants?: boolean;
+}
+export interface TenantExtension extends RepositoryExtension {
+  readonly findArgs: HasFlag<this["M"], this["T"], "tenant"> extends true ? TenantFindArgs : unknown;
+  readonly methods: unknown;
+  readonly deleteArgs: HasFlag<this["M"], this["T"], "tenant"> extends true ? TenantFindArgs : unknown;
+}
+/** The tenant for a request: `context.tenant`, then the configured claim. */
+export declare function resolveTenant<C = unknown>(context: RequestContext, options?: TenantOptions<C>): string | undefined;
+/**
+ * Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads,
+ * updates and deletes to the request's tenant (nested includes and relation
+ * filters too), fills the tenant column on insert and rejects writes that
+ * would move rows to another tenant. It complements RLS; it does not replace
+ * it.
+ */
+export declare function tenant<C = unknown>(options?: TenantOptions<C>): Plugin<"tenant", TenantExtension>;
+//#endregion

package/dist/plugins/tenant/index.js

@@ -0,0 +1,73 @@
+import { n as dbError, t as DbException } from "../../errors-Bl3rkOzo.js";
+import { n as definePlugin } from "../../plugin-BqR6wKMB.js";
+import { n as scopeOperation } from "../../scope-CDHcS7dE.js";
+import { n as equals, r as forbidden, t as dbName } from "../../shared-_6-uPL7E.js";
+//#region src/plugins/tenant/index.ts
+/** The tenant for a request: `context.tenant`, then the configured claim. */
+function resolveTenant(context, options = {}) {
+	if (options.resolve) return options.resolve(context);
+	if (typeof context.tenant === "string") return context.tenant;
+	const claim = options.claim;
+	const paths = typeof claim === "string" ? [claim] : claim ?? DEFAULT_CLAIMS;
+	for (const path of paths) {
+		let value = context.claims;
+		for (const segment of path.split(".")) value = typeof value === "object" && value !== null ? value[segment] : void 0;
+		if (typeof value === "string" && value.length > 0) return value;
+	}
+}
+const DEFAULT_CLAIMS = ["org_id", "app_metadata.org_id"];
+function tenantColumn(table) {
+	return dbName(table, table.flags.tenant);
+}
+/**
+* Multi-tenancy for tables generated with `Flags.tenant`. Scopes reads,
+* updates and deletes to the request's tenant (nested includes and relation
+* filters too), fills the tenant column on insert and rejects writes that
+* would move rows to another tenant. It complements RLS; it does not replace
+* it.
+*/
+function tenant(options = {}) {
+	const onMissing = options.onMissing ?? "error";
+	const current = (table, context) => {
+		const id = resolveTenant(context, options);
+		if (id === void 0 && onMissing === "error" && tenantColumn(table)) throw new DbException(dbError("forbidden", `No tenant in the request context for "${table.key}"`));
+		return id;
+	};
+	return definePlugin({
+		name: "tenant",
+		transformQuery(op, { context, options: call }) {
+			if (call["allTenants"] === true) return op;
+			const id = current(op.table, context);
+			if (id === void 0) return op;
+			return scopeOperation(op, (table) => {
+				const column = tenantColumn(table);
+				return column ? equals(column, id) : void 0;
+			});
+		},
+		beforeMutation(op, { table, context, options: call }) {
+			const column = tenantColumn(table);
+			if (!column || call["allTenants"] === true) return op;
+			const id = current(table, context);
+			if (id === void 0) return op;
+			switch (op.kind) {
+				case "insert": return {
+					...op,
+					rows: op.rows.map((row) => {
+						if (column in row && row[column] !== id) forbidden(`Cannot write a ${table.key} row for another tenant`);
+						return {
+							...row,
+							[column]: id
+						};
+					})
+				};
+				case "update":
+					if (column in op.set && op.set[column] !== id) forbidden(`Cannot move a ${table.key} row to another tenant`);
+					return op;
+				case "delete": return op;
+				default: return op;
+			}
+		}
+	});
+}
+//#endregion
+export { resolveTenant, tenant };

package/dist/plugins/timestamps/index.d.ts

@@ -0,0 +1,9 @@
+import { f as Plugin } from "../../plugin-HvGqCurB.js";
+//#region src/plugins/timestamps/index.d.ts
+/**
+ * Stamps the columns generated as `Flags.timestamps`: `createdAt` on insert,
+ * `updatedAt` on insert and update. Values the caller passes win. Pair it with
+ * the `updated-at` SQL kit trigger to cover writes that bypass the app.
+ */
+export declare function timestamps(): Plugin<"timestamps">;
+//#endregion