better-supabase 0.5.0 → 0.6.0

package/dist/{config-DreERlKo.js → config-Dn7F5k9A.js}

@@ -1,4 +1,4 @@
-import { a as parseImport, c as schemaName, d as variantsFor, i as fieldsFor, l as siblingPath, o as propertyKey, r as HEADER, s as rowType, u as tableEntries } from "./json-schema-m1fiwKgN.js";
+import { a as fieldsFor, c as propertyKey, d as siblingPath, f as tableDocs, g as variantsFor, h as variantTitle, i as fieldDocs, l as rowType, m as temporalGuardImport, o as optionalLine, p as tableEntries, r as HEADER, s as parseImport, u as schemaName } from "./json-schema-CvER4kgT.js";
 //#region src/generators/valibot.ts
 function scalar$1(kind) {
 	switch (kind.kind) {
@@ -9,8 +9,8 @@ function scalar$1(kind) {
 		case "boolean": return "v.boolean()";
 		case "datetime": return "v.pipe(v.string(), v.isoTimestamp())";
 		case "date": return "v.pipe(v.string(), v.isoDate())";
-		case "instant": return "v.instance(Temporal.Instant)";
-		case "plainDateTime": return "v.instance(Temporal.PlainDateTime)";
+		case "instant": return "v.custom<Temporal.Instant>(isInstant)";
+		case "plainDateTime": return "v.custom<Temporal.PlainDateTime>(isPlainDateTime)";
 		case "bigint": return "v.bigint()";
 		case "json": return "json";
 		case "enum": return `v.picklist([${kind.values.map((value) => JSON.stringify(value)).join(", ")}])`;
@@ -18,16 +18,36 @@ function scalar$1(kind) {
 		default: return kind;
 	}
 }
-function field$1(table, plan, jsonImports) {
-	let expr = jsonImports.get(`${table}.${plan.column.db}`) ?? (plan.customJson ? `v.custom<NonNullable<RowOf<'${table}'>['${plan.name}']>>((value) => value !== undefined)` : plan.column.storage === void 0 ? scalar$1(plan.scalar) : `(v.string() as unknown as v.GenericSchema<${rowType(table, plan)}>)`);
+/** `expr` with `actions` appended, flattening an existing top-level `v.pipe`. */
+function piped(expr, actions) {
+	if (actions.length === 0) return expr;
+	return `v.pipe(${/^v\.pipe\((.*)\)$/s.exec(expr)?.[1] ?? expr}, ${actions.join(", ")})`;
+}
+function boundActions(docs) {
+	return [
+		docs.minimum === void 0 ? void 0 : `v.minValue(${docs.minimum})`,
+		docs.exclusiveMinimum === void 0 ? void 0 : `v.gtValue(${docs.exclusiveMinimum})`,
+		docs.maximum === void 0 ? void 0 : `v.maxValue(${docs.maximum})`,
+		docs.exclusiveMaximum === void 0 ? void 0 : `v.ltValue(${docs.exclusiveMaximum})`,
+		docs.minLength === void 0 ? void 0 : `v.minLength(${docs.minLength})`,
+		docs.maxLength === void 0 ? void 0 : `v.maxLength(${docs.maxLength})`
+	].filter((action) => action !== void 0);
+}
+function docActions(docs) {
+	return [...docs.description === void 0 ? [] : [`v.description(${JSON.stringify(docs.description)})`], ...docs.examples === void 0 ? [] : [`v.examples(${JSON.stringify(docs.examples)})`]];
+}
+function field$1(table, plan, jsonImports, docs) {
+	let expr = jsonImports.get(`${table}.${plan.column.db}`) ?? (plan.customJson ? `v.custom<NonNullable<RowOf<'${table}'>['${plan.name}']>>((value) => value !== undefined)` : plan.column.storage === void 0 ? piped(scalar$1(plan.scalar), boundActions(docs)) : `(v.string() as unknown as v.GenericSchema<${rowType(table, plan)}>)`);
 	if (plan.column.array) expr = `v.array(${expr})`;
 	if (plan.nullable) expr = `v.nullable(${expr})`;
+	expr = piped(expr, docActions(docs));
 	if (plan.optional) expr = `v.exactOptional(${expr})`;
 	return `  ${propertyKey(plan.name)}: ${expr},`;
 }
 /** Valibot schemas for every table's Row, Insert and Update shape. */
 function valibot(options = {}) {
 	return {
+		apiVersion: 1,
 		name: "valibot",
 		generate(input) {
 			const path = options.output ?? siblingPath(input.config.output, "valibot.ts");
@@ -44,6 +64,7 @@ function valibot(options = {}) {
 			const lines = [
 				HEADER,
 				"import * as v from \"valibot\";",
+				...optionalLine(temporalGuardImport(input)),
 				"",
 				`import type { InsertOf, Json, RowOf, UpdateOf } from ${JSON.stringify(input.importPath(path, input.config.output))};`
 			];
@@ -54,11 +75,13 @@ function valibot(options = {}) {
 			for (const [key, table] of tableEntries(input)) {
 				lines.push("");
 				const variants = variantsFor(table);
+				const docs = tableDocs(input, table);
 				for (const variant of variants) {
 					const name = schemaName(key, variant);
-					lines.push(`export const ${name}: v.GenericSchema<${variant}Of<'${key}'>> = v.object({`);
-					for (const plan of fieldsFor(table, variant, input)) lines.push(field$1(key, plan, jsonImports));
-					lines.push("});");
+					const objectActions = docs ? [`v.title(${JSON.stringify(variantTitle(docs, variant))})`, ...docs.description === void 0 ? [] : [`v.description(${JSON.stringify(docs.description)})`]] : [];
+					lines.push(`export const ${name}: v.GenericSchema<${variant}Of<'${key}'>> = ${objectActions.length > 0 ? "v.pipe(" : ""}v.object({`);
+					for (const plan of fieldsFor(table, variant, input)) lines.push(field$1(key, plan, jsonImports, fieldDocs(docs, plan)));
+					lines.push(objectActions.length > 0 ? `}), ${objectActions.join(", ")});` : "});");
 				}
 				if (variants.includes("Insert")) {
 					const insert = schemaName(key, "Insert");
@@ -86,8 +109,8 @@ function scalar(kind) {
 		case "boolean": return "z.boolean()";
 		case "datetime": return "z.iso.datetime({ offset: true })";
 		case "date": return "z.iso.date()";
-		case "instant": return "z.instanceof(Temporal.Instant)";
-		case "plainDateTime": return "z.instanceof(Temporal.PlainDateTime)";
+		case "instant": return "z.custom<Temporal.Instant>(isInstant)";
+		case "plainDateTime": return "z.custom<Temporal.PlainDateTime>(isPlainDateTime)";
 		case "bigint": return "z.bigint()";
 		case "json": return "z.json()";
 		case "enum": return `z.enum([${kind.values.map((value) => JSON.stringify(value)).join(", ")}])`;
@@ -95,16 +118,36 @@ function scalar(kind) {
 		default: return kind;
 	}
 }
-function field(table, plan, jsonImports) {
-	let expr = jsonImports.get(`${table}.${plan.column.db}`) ?? (plan.customJson ? `z.custom<NonNullable<RowOf<'${table}'>['${plan.name}']>>((value) => value !== undefined)` : plan.column.storage === void 0 ? scalar(plan.scalar) : `(z.string() as unknown as z.ZodType<${rowType(table, plan)}>)`);
+function bounds(docs) {
+	return [
+		docs.minimum === void 0 ? "" : `.min(${docs.minimum})`,
+		docs.exclusiveMinimum === void 0 ? "" : `.gt(${docs.exclusiveMinimum})`,
+		docs.maximum === void 0 ? "" : `.max(${docs.maximum})`,
+		docs.exclusiveMaximum === void 0 ? "" : `.lt(${docs.exclusiveMaximum})`,
+		docs.minLength === void 0 ? "" : `.min(${docs.minLength})`,
+		docs.maxLength === void 0 ? "" : `.max(${docs.maxLength})`
+	].join("");
+}
+/** `.meta({ ... })` for the entries that are set, or nothing. */
+function meta(entries) {
+	const set = Object.entries(entries).filter(([, value]) => value !== void 0);
+	return set.length === 0 ? "" : `.meta({ ${set.map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join(", ")} })`;
+}
+function field(table, plan, jsonImports, docs) {
+	let expr = jsonImports.get(`${table}.${plan.column.db}`) ?? (plan.customJson ? `z.custom<NonNullable<RowOf<'${table}'>['${plan.name}']>>((value) => value !== undefined)` : plan.column.storage === void 0 ? `${scalar(plan.scalar)}${bounds(docs)}` : `(z.string() as unknown as z.ZodType<${rowType(table, plan)}>)`);
 	if (plan.column.array) expr = `z.array(${expr})`;
 	if (plan.nullable) expr = `${expr}.nullable()`;
+	expr += meta({
+		description: docs.description,
+		examples: docs.examples
+	});
 	if (plan.optional) expr = `${expr}.exactOptional()`;
 	return `  ${propertyKey(plan.name)}: ${expr},`;
 }
 /** Zod 4 schemas for every table's Row, Insert and Update shape. */
 function zod(options = {}) {
 	return {
+		apiVersion: 1,
 		name: "zod",
 		generate(input) {
 			const path = options.output ?? siblingPath(input.config.output, "zod.ts");
@@ -121,6 +164,7 @@ function zod(options = {}) {
 			const lines = [
 				HEADER,
 				"import { z } from \"zod\";",
+				...optionalLine(temporalGuardImport(input)),
 				"",
 				`import type { InsertOf, RowOf, UpdateOf } from ${JSON.stringify(input.importPath(path, input.config.output))};`
 			];
@@ -129,11 +173,15 @@ function zod(options = {}) {
 			for (const [key, table] of tableEntries(input)) {
 				lines.push("");
 				const variants = variantsFor(table);
+				const docs = tableDocs(input, table);
 				for (const variant of variants) {
 					const name = schemaName(key, variant);
 					lines.push(`export const ${name}: z.ZodType<${variant}Of<'${key}'>> = z.object({`);
-					for (const plan of fieldsFor(table, variant, input)) lines.push(field(key, plan, jsonImports));
-					lines.push("});");
+					for (const plan of fieldsFor(table, variant, input)) lines.push(field(key, plan, jsonImports, fieldDocs(docs, plan)));
+					lines.push(`})${docs ? meta({
+						title: variantTitle(docs, variant),
+						description: docs.description
+					}) : ""};`);
 				}
 				if (variants.includes("Insert")) validators.push(`  ${propertyKey(key)}: { insert: ${schemaName(key, "Insert")}, update: ${schemaName(key, "Update")} },`);
 			}

package/dist/connector-Dv8kK0MO.d.ts

@@ -0,0 +1,107 @@
+import { b as DbError, f as Result, x as DbErrorKind } from "./result-D7y2fT87.js";
+//#region src/powersync/connector.d.ts
+/** A queued local change: PowerSync's `CrudEntry`. */
+interface CrudEntryLike {
+  /** `PUT`, `PATCH` or `DELETE` (PowerSync's `UpdateType`). */
+  readonly op: string;
+  readonly table: string;
+  readonly id: string;
+  readonly opData?: Readonly<Record<string, unknown>> | undefined;
+}
+/** The part of a PowerSync database the connector reads the queue from. */
+interface CrudQueueLike {
+  getCrudBatch(limit?: number): Promise<{
+    readonly crud: readonly CrudEntryLike[];
+    complete(): Promise<void>;
+  } | null>;
+}
+/**
+ * A repository a table's changes replay through (`bs.db.customers`), so
+ * RLS, plugins and validation run as they do online.
+ */
+interface UploadRepository {
+  upsert(data: never): PromiseLike<Result<unknown>>;
+  update(id: never, patch: never): PromiseLike<Result<unknown>>;
+  delete(id: never): PromiseLike<Result<unknown>>;
+}
+/** A table's route: its repository, or a function for custom replay. */
+type UploadRoute = UploadRepository | ((entry: CrudEntryLike) => PromiseLike<Result<unknown>>);
+/** What an upload error means for the queued change. */
+type UploadOutcome = "retry" | "conflict" | "discard";
+/** A change the server refused, kept for the UI. */
+interface RejectedChange {
+  readonly entry: CrudEntryLike;
+  readonly error: DbError;
+  readonly outcome: "conflict" | "discard";
+}
+/** A `useSyncExternalStore`-compatible list of refused changes. */
+interface RejectedStore {
+  readonly current: () => readonly RejectedChange[];
+  readonly subscribe: (listener: () => void) => () => void;
+  /** Forgets one change, or all of them. */
+  readonly dismiss: (change?: RejectedChange) => void;
+}
+interface SessionClient {
+  readonly auth: {
+    getSession(): Promise<{
+      readonly data: {
+        readonly session: {
+          readonly access_token: string;
+          readonly expires_at?: number | undefined;
+        } | null;
+      };
+    }>;
+  };
+}
+interface UploadConnectorOptions {
+  /** The PowerSync service URL. */
+  readonly endpoint: string;
+  /** The supabase-js client whose session authenticates sync and uploads. */
+  readonly supabase: SessionClient;
+  /** Every synced table that takes local writes, by its SQLite name. */
+  readonly tables: Readonly<Record<string, UploadRoute>>;
+  /** Changes per upload batch. Defaults to 100. */
+  readonly batchSize?: number;
+  /** Overrides `uploadOutcome` for some errors. */
+  readonly classify?: (error: DbError, entry: CrudEntryLike) => UploadOutcome | undefined;
+  readonly onConflict?: (change: RejectedChange) => void;
+  readonly onDiscard?: (change: RejectedChange) => void;
+}
+/** PowerSync's `PowerSyncBackendConnector`. */
+interface UploadConnector {
+  fetchCredentials(): Promise<{
+    readonly endpoint: string;
+    readonly token: string;
+    readonly expiresAt?: Date;
+  } | null>;
+  uploadData(database: CrudQueueLike): Promise<void>;
+  /** Changes the server refused since the app started. */
+  readonly rejected: RejectedStore;
+}
+/**
+ * The default for a failed upload: transient errors retry, a newer server
+ * row is a conflict, and a change the server will never accept is
+ * discarded so it doesn't block the queue.
+ */
+declare function uploadOutcome(kind: DbErrorKind): UploadOutcome;
+/**
+ * A PowerSync connector that authenticates with the Supabase session and
+ * replays queued changes through repositories. Changes upload in batches;
+ * a transient error keeps the batch queued for PowerSync's retry, and
+ * refused changes land in `rejected` instead of blocking the queue. A table
+ * without a route stops the upload with an error, so no change is dropped
+ * silently. When the session is gone (the refresh token was revoked), the
+ * upload stops until the user signs in again.
+ *
+ * ```ts
+ * const connector = createUploadConnector({
+ *   endpoint: process.env.EXPO_PUBLIC_POWERSYNC_URL,
+ *   supabase,
+ *   tables: { customers: bs.db.customers },
+ * });
+ * await powersync.connect(connector);
+ * ```
+ */
+declare function createUploadConnector(options: UploadConnectorOptions): UploadConnector;
+//#endregion
+export { UploadConnector as a, UploadRepository as c, uploadOutcome as d, RejectedStore as i, UploadRoute as l, CrudQueueLike as n, UploadConnectorOptions as o, RejectedChange as r, UploadOutcome as s, CrudEntryLike as t, createUploadConnector as u };

package/dist/connectors-hkLCwyEz.d.ts

@@ -0,0 +1,120 @@
+/// <reference lib="esnext.temporal" />
+import { t as AsyncResult, w as ErrorMapper } from "./result-D7y2fT87.js";
+import { t as BlockTransport } from "./block-transport-DvaoPuZ9.js";
+import { i as CredentialRef, r as CredentialProvider } from "./provider-BH5UWZJ6.js";
+import { r as BlockTemporalOptions } from "./block-helpers-CKtbFcRv.js";
+//#region src/blocks/connectors/connectors.d.ts
+type ConnectorTransport = "http" | "sse";
+/** `none`, OAuth per user (a grant each), or a header from the server's credential_ref. */
+type ConnectorAuth = "none" | "oauth" | "header";
+type FingerprintStatus = "approved" | "pending" | "rejected";
+interface ConnectorGrant {
+  readonly id: string;
+  readonly userId: string;
+  readonly serverId: string;
+  readonly organizationId: string;
+  readonly credentialRef: CredentialRef;
+  readonly scopes: readonly string[];
+  readonly expiresAt: Temporal.Instant | undefined;
+  readonly grantedAt: Temporal.Instant;
+  readonly revokedAt: Temporal.Instant | undefined;
+}
+interface ConnectorServer {
+  readonly id: string;
+  readonly organizationId: string;
+  readonly name: string;
+  readonly url: string;
+  readonly transport: ConnectorTransport;
+  readonly authType: ConnectorAuth;
+  /** For `header` auth: the app credential sent with every request. */
+  readonly credentialRef: CredentialRef | undefined;
+  /** The OAuth scopes to ask for. */
+  readonly scopes: readonly string[];
+  /** OAuth client metadata for dynamic client registration. */
+  readonly clientMetadata: Readonly<Record<string, unknown>>;
+  readonly enabled: boolean;
+  /** The caller's (or `ownerId`'s) active grant, from `list` and `get`. */
+  readonly grant: ConnectorGrant | undefined;
+  readonly createdAt: Temporal.Instant;
+  readonly updatedAt: Temporal.Instant;
+}
+interface ConnectorServerFields {
+  readonly name?: string;
+  readonly url?: string;
+  readonly transport?: ConnectorTransport;
+  readonly authType?: ConnectorAuth;
+  readonly credentialRef?: CredentialRef | null;
+  readonly scopes?: readonly string[];
+  readonly clientMetadata?: Readonly<Record<string, unknown>>;
+  readonly enabled?: boolean;
+}
+interface ConnectorSession {
+  readonly sessionId: string | undefined;
+  readonly initializeResult: Readonly<Record<string, unknown>> | undefined;
+  readonly expiresAt: Temporal.Instant;
+}
+interface ConnectorsOptions extends BlockTemporalOptions {
+  /** Calls as the user: `rpcTransport(supabase)`. */
+  readonly transport: BlockTransport;
+  /** Calls as the service role, for grants and renewals. */
+  readonly service?: BlockTransport;
+  /** The module schema (`sql.modules.connectors.schema`), default `better_supabase`. */
+  readonly schema?: string;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Revokes a grant's credential when the grant or its server goes away. */
+  readonly credentials?: CredentialProvider;
+}
+interface Connectors {
+  readonly servers: {
+    list(organizationId: string): AsyncResult<readonly ConnectorServer[]>;
+    /** With `ownerId` (service role), the grant is that user's. */
+    get(serverId: string, options?: {
+      readonly ownerId?: string;
+    }): AsyncResult<ConnectorServer>;
+    create(organizationId: string, server: ConnectorServerFields & {
+      readonly name: string;
+      readonly url: string;
+    }): AsyncResult<ConnectorServer>;
+    update(organizationId: string, serverId: string, fields: ConnectorServerFields): AsyncResult<ConnectorServer>;
+    /** Deletes a server and revokes its grants' credentials. Returns how many. */
+    remove(serverId: string): AsyncResult<number>;
+  };
+  readonly grants: {
+    /**
+     * Records a user's grant after the provider stored the credential
+     * (service role), revoking the grant it replaces.
+     */
+    record(serverId: string, userId: string, credentialRef: CredentialRef, options?: {
+      readonly scopes?: readonly string[];
+      readonly expiresAt?: Temporal.Instant;
+    }): AsyncResult<ConnectorGrant>;
+    /** Revokes a grant (its owner or the service role) and its credential. */
+    revoke(grantId: string): AsyncResult<boolean>;
+    /** Active grants expiring before `before` (service role). */
+    expiring(before: Temporal.Instant, options?: {
+      readonly limit?: number;
+    }): AsyncResult<readonly ConnectorGrant[]>;
+    renew(grantId: string, expiresAt: Temporal.Instant): AsyncResult<boolean>;
+  };
+  readonly sessions: {
+    get(serverId: string, chatKey?: string): AsyncResult<ConnectorSession | undefined>;
+    save(serverId: string, session: {
+      readonly chatKey?: string;
+      readonly sessionId?: string;
+      readonly initializeResult?: Readonly<Record<string, unknown>>;
+    }): AsyncResult<boolean>;
+    forget(serverId: string, chatKey?: string): AsyncResult<boolean>;
+    /** Deletes expired sessions (service role). */
+    purge(): AsyncResult<number>;
+  };
+  readonly fingerprints: {
+    /** Records a tool list's fingerprint and returns whether it may be called. */
+    check(serverId: string, fingerprint: string, tools?: Readonly<Record<string, unknown>>): AsyncResult<FingerprintStatus>;
+    approve(serverId: string, fingerprint: string): AsyncResult<boolean>;
+    reject(serverId: string, fingerprint: string): AsyncResult<boolean>;
+  };
+}
+/** MCP servers, per-user grants, sessions and tool list fingerprints. */
+declare function createConnectors(options: ConnectorsOptions): Connectors;
+//#endregion
+export { ConnectorSession as a, ConnectorsOptions as c, ConnectorServerFields as i, FingerprintStatus as l, ConnectorGrant as n, ConnectorTransport as o, ConnectorServer as r, Connectors as s, ConnectorAuth as t, createConnectors as u };

package/dist/context-BCrWe7ow.d.ts

@@ -0,0 +1,237 @@
+import { u as ClaimsMeta } from "./types-6BdhkmZe.js";
+import { C as BlockEventMap, E as BlockEventType } from "./events-DWDhx77e.js";
+import { c as ResolvedModule, o as ModuleMode, s as ModulesConfig } from "./modules-DpPwzC7E.js";
+//#region src/sql/context.d.ts
+/** The scope id types SQL modules render. */
+declare const MODULE_ID_TYPES: readonly ["uuid", "text", "bigint", "integer"];
+type ModuleIdType = (typeof MODULE_ID_TYPES)[number];
+declare const isModuleIdType: (value: string) => value is ModuleIdType;
+/**
+ * A Postgres type name as one of `MODULE_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.
+ */
+declare function moduleIdType(value: string): ModuleIdType | undefined;
+/** One logical table of a module: its default name and logical columns. */
+interface ModuleTableSpec {
+  /** 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 (`sql.modules.<name>.tables.<table>: null`). */
+  readonly optionalTable?: boolean;
+  readonly lifecycle?: ModuleTableLifecycle;
+}
+interface ModuleTableLifecycle {
+  readonly user?: string;
+  readonly tenant?: string;
+  readonly purge?: boolean;
+  readonly omit?: readonly string[];
+  readonly export?: boolean;
+  /**
+   * Columns that hold a `credential_ref`. Exports leave them out, and the
+   * organization purger revokes each ref that carries the row's tenant
+   * through the `CredentialProvider` before the purge deletes the row.
+   */
+  readonly credentials?: readonly string[];
+  /** Revoke for the row's `user` instead of the app. Default `app`. */
+  readonly credentialSubject?: "app" | "user";
+}
+interface ModuleNames {
+  readonly tables: Readonly<Record<string, ModuleTableSpec>>;
+  /** The `before_*` and `after_*` hooks the module calls, so `sql.modules.<name>.hooks.functions` is checked. */
+  readonly hooks?: readonly string[];
+  /** The `sql.modules.<name>.options` keys the module reads; any other key is rejected. */
+  readonly options?: readonly string[];
+  /** The events the module records; `record` rejects any other type. */
+  readonly events?: ModuleEvents;
+}
+/** An event in a module's catalog, checked against what `record` renders. */
+interface ModuleEventSpec<K extends BlockEventType = BlockEventType> {
+  /** The kebab-case collection every subject starts with, e.g. `organizations`. */
+  readonly subject: string;
+  /** The payload keys, all of them in the event's `BlockEventMap` data. */
+  readonly payload: readonly PayloadKey<K>[];
+  /** A job, a webhook or an engine may call the writer again, so the event needs a `key`. */
+  readonly retries?: boolean;
+}
+type PayloadKey<K extends BlockEventType> = K extends BlockEventType ? keyof BlockEventMap[K] & string : never;
+type ModuleEvents = { readonly [K in BlockEventType]?: ModuleEventSpec<K>; };
+/** An event a module writes to the outbox, as SQL expressions. */
+interface ModuleEmit {
+  /** The event type, e.g. `organization.created`. */
+  readonly type: string;
+  /** A `jsonb` expression. */
+  readonly payload: string;
+  /** A `text` expression, e.g. `'organizations/' || new_organization`. */
+  readonly subject?: string;
+  /** The tenant id expression; it is cast to text. */
+  readonly tenant?: string;
+  /** A `text` idempotency key expression. */
+  readonly key?: string;
+}
+/**
+ * The categories module actions are audited under. An adopted log with its
+ * own names maps them through `sql.modules.audit.options.values.category`.
+ */
+declare const AUDIT_CATEGORIES: readonly ["membership", "access", "security", "configuration", "billing", "data", "ai", "integration"];
+type AuditCategory = (typeof AUDIT_CATEGORIES)[number];
+/** How `record` writes an action to the audit log, as SQL expressions. */
+interface ModuleAudit {
+  /** The audit category, mapped through `sql.modules.audit.options.values`. */
+  readonly category: AuditCategory;
+  /** What the action changed, e.g. `user` or `api_key`. */
+  readonly targetType?: string;
+  /** A `text` expression for the changed record's id. */
+  readonly recordId?: string;
+  /** A `text` expression people recognize the target by. */
+  readonly targetLabel?: string;
+  /** A `text` expression that says what happened. */
+  readonly summary?: string;
+  /** A `jsonb` expression; defaults to the event payload. */
+  readonly metadata?: string;
+  /** A `uuid` expression for the actor; defaults to the caller. */
+  readonly actor?: string;
+}
+/**
+ * An action a module records once: the outbox gets it as an event and the
+ * audit log as an entry, each when its module is installed.
+ */
+interface ModuleAction extends ModuleEmit {
+  /**
+   * How the action is audited, or `false` for an event that is not an
+   * audited action, such as a chat message or a run status.
+   */
+  readonly audit: ModuleAudit | false;
+}
+/** A function of a module's contract: what other modules and the TypeScript side call. */
+interface ModuleContractFunction {
+  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 ModuleContext {
+  readonly module: string;
+  readonly mode: ModuleMode;
+  readonly config: ResolvedModule;
+  /** The quoted schema of the module's functions and managed tables. */
+  readonly schema: string;
+  readonly schemaName: string;
+  readonly idType: ModuleIdType;
+  readonly claims: ClaimsMeta;
+  readonly modules: ModulesConfig;
+  /** `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;
+  readonly names: ModuleNames;
+  readonly installedModules: readonly string[];
+  /** The permission key for a module action, as a SQL literal. */
+  permission(action: string, fallback: string): string;
+  /** The permission key for a module 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): ModuleContext;
+  /** A string module option (`sql.modules.<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;
+  /**
+   * `options.extraColumns` (column name to SQL type), checked: names are
+   * lower-case identifiers, types are SQL types, and no name shadows one of
+   * `table`'s mapped columns or a key in `reserved`, the stable keys the
+   * module's read functions return next to them.
+   */
+  extraColumns(table: string, reserved?: readonly string[]): readonly ExtraColumn[];
+  /**
+   * PL/pgSQL that calls the app's hook function when it exists, with
+   * `[type, expression]` arguments: `if to_regprocedure(...) is not null
+   * then execute format(...) using ...; end if;`. The name comes from
+   * `to_regprocedure` rather than a literal: plpgsql_check (`supabase db
+   * lint`) checks constant dynamic SQL and fails when the hook is missing.
+   */
+  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 `sql.modules.<name>.events` isn't false;
+   * otherwise an empty string. `record` without the audit entry.
+   */
+  emit(event: ModuleEmit): string;
+  /**
+   * PL/pgSQL that writes the action to the outbox (as `emit` does) and, when
+   * it carries `audit` and the `audit` module is installed, to the audit log
+   * (`audit_event`), with `key` as the idempotency key of both. `null;`
+   * when neither applies, so it is always a valid statement.
+   */
+  record(action: ModuleAction): string;
+  /**
+   * PL/pgSQL that calls `notify(fields)` as the service role, which
+   * `notify()` requires, then restores the caller's claims. The function
+   * declares `v_claims text`. `null;` without the `notifications` module.
+   */
+  notify(fields: string, options?: {
+    readonly indent?: string;
+  }): string;
+  /** PL/pgSQL that enqueues a job (`enqueue_job`); `null;` without the `jobs` module. */
+  enqueue(queue: string, payload: string, dedupe: string): string;
+  /** The `text[]` of a tenant's entitlements, or `fallback` without the `entitlements` module. */
+  entitlements(tenant: string): string | undefined;
+  entitlements(tenant: string, fallback: string): string;
+  /**
+   * PL/pgSQL that broadcasts on a Realtime topic when `realtime.send`
+   * exists: projects without Realtime skip it.
+   */
+  broadcast(topic: string, event: string, payload: string, options?: {
+    readonly indent?: string;
+  }): string;
+  /** `coalesce(better_supabase.can(scope, id, permission), false)`; `permission` is a SQL expression. */
+  can(scope: string, id: string, permission: string): string;
+  /**
+   * True for the service role and platform staff holding `permission` (a SQL
+   * expression); the service role only without the `access` module.
+   */
+  staff(permission: string): string;
+}
+/** A column from `options.extraColumns`. */
+interface ExtraColumn {
+  /** The column name, as reads return it. */
+  readonly name: string;
+  /** The name, quoted. */
+  readonly ident: string;
+  /** Its SQL type, such as `text not null default 'en'`. */
+  readonly type: string;
+}
+/** The contract's argument list with `{id}` resolved, as Postgres prints it. */
+declare function contractSignature(fn: ModuleContractFunction, idType: string): string;
+//#endregion
+export { ModuleAudit as a, ModuleEmit as c, ModuleTableSpec as d, contractSignature as f, ModuleAction as i, ModuleIdType as l, moduleIdType as m, AuditCategory as n, ModuleContext as o, isModuleIdType as p, MODULE_ID_TYPES as r, ModuleContractFunction as s, AUDIT_CATEGORIES as t, ModuleNames as u };

package/dist/credentials/index.d.ts

@@ -0,0 +1,31 @@
+import { t as AsyncResult } from "../result-D7y2fT87.js";
+import { i as sqlTransport, r as rpcTransport, t as BlockTransport } from "../block-transport-DvaoPuZ9.js";
+import { a as CredentialSubject, c as SetCredentialOptions, d as foreignCredentialRef, f as subjectFor, i as CredentialRef, l as StartAuthorizationOptions, n as CredentialCapabilities, o as CredentialToken, p as tenantCredentialRef, r as CredentialProvider, s as GetTokenOptions, t as CompleteAuthorizationOptions, u as credentialRefInTenant } from "../provider-BH5UWZJ6.js";
+import { a as vaultCredentials, i as VaultInboundScheme, n as VaultCredentials, r as VaultCredentialsOptions, t as VaultCredentialRef } from "../vault-CSO7ss5C.js";
+//#region src/credentials/compose.d.ts
+/**
+ * One provider over several: each call goes to the provider whose `name`
+ * is the ref's `provider`. A ref no provider handles fails with
+ * `invalid_input` (`CREDENTIAL_PROVIDER_UNKNOWN`), and an optional method
+ * the chosen provider lacks with `unsupported`.
+ */
+export declare function credentialRouter(providers: readonly CredentialProvider[], options?: {
+  readonly name?: string;
+}): CredentialProvider;
+interface RevokeIfConfiguredOptions {
+  readonly subject: CredentialSubject;
+  /**
+   * The tenant of the row that holds the ref, or `undefined` for an
+   * app-level row. When the key is present, a ref outside that tenant is
+   * left alone, so a row can never revoke another tenant's credential.
+   */
+  readonly tenant?: string | undefined;
+}
+/**
+ * Revokes the credential a ref names when a provider is configured and can
+ * revoke it. Resolves `false` without a provider, for a provider without
+ * revocation, or for a ref outside `options.tenant`.
+ */
+export declare function revokeIfConfigured(provider: CredentialProvider | undefined, ref: CredentialRef, options: RevokeIfConfiguredOptions): AsyncResult<boolean>;
+//#endregion
+export { type BlockTransport, type CompleteAuthorizationOptions, type CredentialCapabilities, type CredentialProvider, type CredentialRef, type CredentialSubject, type CredentialToken, type GetTokenOptions, type RevokeIfConfiguredOptions, type SetCredentialOptions, type StartAuthorizationOptions, type VaultCredentialRef, type VaultCredentials, type VaultCredentialsOptions, type VaultInboundScheme, credentialRefInTenant, foreignCredentialRef, rpcTransport, sqlTransport, subjectFor, tenantCredentialRef, vaultCredentials };