better-supabase 0.12.0 → 0.14.0

package/dist/engagements-CsJhf2OM.d.ts

@@ -0,0 +1,179 @@
+/// <reference lib="esnext.temporal" />
+import { T as ErrorMapper, t as AsyncResult } from "./result-C6jDfedy.js";
+import { t as StandardSchemaV1 } from "./standard-DbQsD2xZ.js";
+import { r as FieldsOf } from "./block-fields-3w4MZr8U.js";
+import { n as Logger } from "./logger-DWVYUmwi.js";
+import { r as BlockTemporalOptions } from "./block-helpers-BaugZlJV.js";
+import { t as BlockTransport } from "./block-transport-d53POsem.js";
+import { n as BlockHooks } from "./block-hooks-CmjPKqQ_.js";
+import { f as AiFiles } from "./types-BEDfwXL4.js";
+import { g as JobHandler } from "./types-CGUDoF5I.js";
+import { a as EngagementRecording, d as Transcript, f as TranscriptSegment, i as EngagementNotesInput, l as Transcriber, r as EngagementNotes, s as NoteTaker } from "./recordings-DgDu7AOt.js";
+//#region src/blocks/engagements/engagements.d.ts
+/** A record an engagement is on. */
+interface EngagementSubject {
+  readonly type: string;
+  readonly id: string;
+}
+/** A call, email, meeting, note or task logged on one or more records. */
+interface Engagement<F extends object = Record<never, never>> {
+  readonly id: string;
+  readonly organizationId: string;
+  /** `call`, `email`, `meeting`, `note`, `task` or a configured type. */
+  readonly type: string;
+  readonly title: string;
+  readonly body?: string;
+  /** How it went, such as `connected`, `no_answer` or `replied`. */
+  readonly outcome?: string;
+  readonly ownerId?: string;
+  readonly dueAt?: Temporal.Instant;
+  readonly doneAt?: Temporal.Instant;
+  readonly durationSeconds?: number;
+  /** The id in the system it came from, such as a mail or calendar provider. */
+  readonly externalRef?: string;
+  /** The records it is on; the first is its main record. */
+  readonly subjects: readonly EngagementSubject[];
+  /** Open and past its due time. */
+  readonly overdue: boolean;
+  readonly createdBy?: string;
+  readonly createdAt: Temporal.Instant;
+  /** The app's extra columns (`options.extraColumns`), by column name. */
+  readonly fields: Readonly<Record<string, unknown>> & F;
+}
+/**
+ * The fields of a write. On update, left out keeps the value and `null` clears
+ * it.
+ */
+interface EngagementInput<F extends object = Record<never, never>> {
+  readonly type?: string;
+  readonly title?: string;
+  readonly body?: string | null;
+  readonly outcome?: string | null;
+  /** Defaults to the caller on `log`. */
+  readonly ownerId?: string | null;
+  readonly dueAt?: Temporal.Instant | null;
+  readonly doneAt?: Temporal.Instant | null;
+  readonly durationSeconds?: number | null;
+  /** Logging the same `externalRef` again updates the engagement. */
+  readonly externalRef?: string | null;
+  /** Values for the extra columns, by column name. */
+  readonly fields?: Partial<F> & Readonly<Record<string, unknown>>;
+}
+/** `F` types the engagements' extra columns, from the `fields` schema. */
+interface Engagements<F extends object = Record<never, never>> {
+  /**
+   * Logs an engagement on the records in `subjects`, the first being its main
+   * record.
+   */
+  log(organizationId: string, input: EngagementInput<F> & {
+    readonly type: string;
+    readonly title: string;
+  }, subjects: readonly EngagementSubject[]): AsyncResult<Engagement<F>>;
+  /** Changes an engagement, and its records when `subjects` is given. */
+  update(id: string, input: EngagementInput<F>, subjects?: readonly EngagementSubject[]): AsyncResult<Engagement<F>>;
+  /** Marks it done now, with an outcome, or open again with `done: false`. */
+  complete(id: string, options?: {
+    readonly done?: boolean;
+    readonly outcome?: string;
+  }): AsyncResult<Engagement<F>>;
+  remove(id: string): AsyncResult<boolean>;
+  /** A record's engagements, newest first (50 by default, at most 200). */
+  of(subject: EngagementSubject, options?: {
+    readonly types?: readonly string[];
+    readonly before?: Temporal.Instant;
+    readonly limit?: number;
+  }): AsyncResult<Engagement<F>[]>;
+  /** The next open engagement with a due time on a record, or `undefined`. */
+  next(subject: EngagementSubject): AsyncResult<Engagement<F> | undefined>;
+  /** A member's open engagements, earliest due first. Default: the caller's. */
+  open(organizationId: string, options?: {
+    readonly ownerId?: string;
+    readonly dueBefore?: Temporal.Instant;
+    readonly limit?: number;
+  }): AsyncResult<Engagement<F>[]>;
+  /**
+   * Attaches a ready ai-files file as a call or meeting recording
+   * (`options.recordings`). With the jobs block it queues a transcription on
+   * `engagements.transcribe`.
+   */
+  attachRecording(engagementId: string, fileId: string, options?: {
+    readonly language?: string;
+  }): AsyncResult<EngagementRecording>;
+  /** An engagement's recordings, oldest first. */
+  recordings(engagementId: string): AsyncResult<EngagementRecording[]>;
+  /** A recording's speaker turns in order (500 by default, at most 5000). */
+  transcript(recordingId: string, options?: {
+    readonly after?: number;
+    readonly limit?: number;
+  }): AsyncResult<TranscriptSegment[]>;
+  /** Replaces a recording's transcript, from a transcriber or an import. */
+  saveTranscript(recordingId: string, transcript: Transcript & {
+    readonly model?: string;
+  }): AsyncResult<EngagementRecording>;
+  /**
+   * Transcribes a recording with `transcriber`, reading the file through
+   * `files`, and saves the result. Runs on `service` when given.
+   */
+  transcribe(recordingId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<EngagementRecording>;
+  /**
+   * The handler for the `engagements.transcribe` queue. The last attempt marks
+   * the recording failed with the error.
+   */
+  transcribeJob(): JobHandler<{
+    readonly recordingId: string;
+  }>;
+  /**
+   * Transcribes pending recordings without a queue (service role). Returns how
+   * many succeeded; a failure marks its recording failed.
+   */
+  drainRecordings(options?: {
+    readonly batch?: number;
+    readonly signal?: AbortSignal;
+  }): AsyncResult<number>;
+  /** The engagement's notes, or `undefined`. */
+  notes(engagementId: string): AsyncResult<EngagementNotes | undefined>;
+  /** Saves notes a member wrote, replacing earlier ones. */
+  saveNotes(engagementId: string, notes: EngagementNotesInput): AsyncResult<EngagementNotes>;
+  /**
+   * Writes the engagement's notes with `noteTaker` from its transcripts and
+   * saves them.
+   */
+  summarize(engagementId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<EngagementNotes>;
+}
+interface EngagementsOptions<S extends StandardSchemaV1 | undefined = undefined> extends BlockTemporalOptions {
+  readonly transport: BlockTransport;
+  /**
+   * The module schema, or its API schema: `defineBlocks` passes it from
+   * `blocks.generated.ts`.
+   */
+  readonly schema?: string;
+  /**
+   * A Standard Schema for the engagements' extra columns
+   * (`blocks.engagements.options.extraColumns`), keyed by column name. It types
+   * and parses `fields` on reads and validates them on writes.
+   */
+  readonly fields?: S;
+  readonly hooks?: NoInfer<BlockHooks<Engagements<FieldsOf<S>>>>;
+  readonly logger?: Logger;
+  readonly mappers?: readonly ErrorMapper[];
+  /** Calls as the service role, for `transcribe`, its job and the drain. */
+  readonly service?: BlockTransport;
+  /** The ai-files block, which `transcribe` reads recordings through. */
+  readonly files?: AiFiles;
+  /** Turns recordings into transcripts, for `transcribe`. */
+  readonly transcriber?: Transcriber;
+  /** Writes notes from transcripts, for `summarize`. */
+  readonly noteTaker?: NoteTaker;
+}
+/**
+ * The engagements block: calls, emails, meetings, notes and tasks on any record
+ * registered in `config.subjects`, for a record's activity panel, a "next step"
+ * and a member's task list.
+ */
+declare function createEngagements<S extends StandardSchemaV1 | undefined = undefined>(options: EngagementsOptions<S>): Engagements<FieldsOf<S>>;
+//#endregion
+export { EngagementsOptions as a, Engagements as i, EngagementInput as n, createEngagements as o, EngagementSubject as r, Engagement as t };

package/dist/entitlements-B_ttRvI6.js

@@ -0,0 +1,45 @@
+import { t as AsyncResult } from "./result-B3m7xtRY.js";
+import { j as run, o as blockCall } from "./block-helpers-CiKtrb6g.js";
+import { r as withBlockHooks } from "./block-hooks-BymdcD0V.js";
+//#region src/blocks/entitlements/entitlements.ts
+/** The Stripe event sent when a customer's active entitlements change. */
+const ENTITLEMENTS_UPDATED = "entitlements.active_entitlement_summary.updated";
+function stripeCustomerOf(payload) {
+	if (typeof payload !== "object" || payload === null) return;
+	const customer = (payload.data?.object)?.customer;
+	if (typeof customer === "string") return customer;
+	const id = customer?.id;
+	return typeof id === "string" ? id : void 0;
+}
+/**
+* Users whose `memberships` claim carries the entitlements of the Stripe
+* customer in an `entitlements.active_entitlement_summary.updated` event, so a
+* job can invalidate their sessions. Empty for other payloads.
+*/
+function entitlementMembers(sql, payload) {
+	const customer = stripeCustomerOf(payload);
+	if (customer === void 0) return AsyncResult.ok([]);
+	return run(() => sql.queryRaw("select user_id from better_supabase.entitlement_members($1) as user_id", [customer])).map((rows) => rows.map((row) => row.user_id));
+}
+/**
+* Reads the caller's entitlements through the `entitlements` module's
+* `has_entitlement` and `entitlement_value`, which check membership.
+*/
+function createEntitlements(options) {
+	const call = blockCall(options.transport, options.schema, options.mappers);
+	return withBlockHooks({
+		has: (organizationId, key) => call("has_entitlement", {
+			tenant: organizationId,
+			key
+		}, (value) => value === true),
+		value: (organizationId, key) => call("entitlement_value", {
+			tenant: organizationId,
+			key
+		}, (value) => value === null ? void 0 : value)
+	}, options.hooks, {
+		block: "entitlements",
+		...options.logger ? { logger: options.logger } : {}
+	});
+}
+//#endregion
+export { createEntitlements as n, entitlementMembers as r, ENTITLEMENTS_UPDATED as t };

package/dist/entitlements-DDevu4ZE.d.ts

@@ -0,0 +1,54 @@
+import { t as AuthSnapshot } from "./bind-Dz8y3T5T.js";
+import { t as AuthSession } from "./view-2_I-2ukO.js";
+//#region src/auth/entitlements.d.ts
+/**
+ * One entry of the `memberships` claim when a hook writes it as a list. Hooks
+ * strip `null`s, so optional fields are absent rather than `null`.
+ */
+interface MembershipClaim {
+  /** The scope the membership is in, e.g. `tenant` or `organization`. */
+  readonly scope: string;
+  readonly id: string;
+  /** Parent scopes, e.g. `{ organization: '...' }` for a project membership. */
+  readonly within?: Readonly<Record<string, string>>;
+  readonly roles: readonly string[];
+  readonly via?: string;
+  /** Unix seconds. */
+  readonly expiresAt?: number;
+  readonly grantedBy?: string;
+  readonly reason?: string;
+  readonly member?: {
+    readonly group: string;
+  };
+  readonly managedBy?: "idp";
+  /** Seats, not plan features: those are in the `features` claim. */
+  readonly entitlements?: readonly string[];
+}
+/**
+ * Entitlement keys of the `features` claim: the literal union when
+ * `betterSupabase.claims(schema)` declares one (`z.enum([...])`), otherwise
+ * `string`.
+ */
+type EntitlementKey<C> = C extends {
+  readonly features?: infer F;
+} ? NonNullable<F> extends Readonly<Record<string, readonly (infer K)[]>> ? K extends string ? K : string : string : string;
+/** Where `hasEntitlement` reads the features claim, and its short codes. */
+interface EntitlementClaimOptions {
+  /** `config.claims.features`, default `features`. */
+  readonly claim?: string;
+  /** `entitlements.claim.keys`: the short code written for each feature key. */
+  readonly keys?: Readonly<Record<string, string>>;
+}
+/**
+ * Whether the session's plan-features claim grants `key` in `tenantId`. `claim`
+ * is `config.claims.features` (default `features`), the claim
+ * `better_supabase.feature_claims()` fills, or `{ claim, keys }` when
+ * `entitlements.claim.keys` writes short codes. The claim is as fresh as the
+ * token: enforce it in RLS with `better_supabase.has_entitlement()`, and
+ * refresh the session after checkout. A tenant left out by
+ * `entitlements.claim.maxTenants` reads as not granted. Takes a server session
+ * or the client's `useAuth()` snapshot.
+ */
+declare function hasEntitlement<C>(session: AuthSession<C> | AuthSnapshot, tenantId: string, key: EntitlementKey<C>, claim?: string | EntitlementClaimOptions): boolean;
+//#endregion
+export { hasEntitlement as i, EntitlementKey as n, MembershipClaim as r, EntitlementClaimOptions as t };

package/dist/entity-form-B67vq97h.d.ts

@@ -0,0 +1,82 @@
+import { rn as EntitySchema } from "./define-block-COpcS6aT.js";
+import { s as FormFieldType } from "./form-definition-BjEtH8BT.js";
+//#region src/records/entity-form.d.ts
+/** The input a field renders: a forms block field type, or a date and time. */
+type EntityFormInput = FormFieldType | "datetime";
+/** One field of an entity form, in render order. */
+interface EntityFormField {
+  /** The input key, or the custom field key. */
+  readonly key: string;
+  readonly label: string;
+  readonly input: EntityFormInput;
+  readonly required: boolean;
+  /** `entity` for the block's input, `custom` for the tenant's custom fields. */
+  readonly source: "entity" | "custom";
+  readonly description?: string;
+  /** The values an `option` or `multi` field offers. */
+  readonly options?: readonly string[];
+  readonly minimum?: number;
+  readonly maximum?: number;
+  readonly minLength?: number;
+  readonly maxLength?: number;
+  /** A custom field marked sensitive. */
+  readonly sensitive?: boolean;
+}
+/** A custom field definition; `customFields.listDefinitions(entity)` fits. */
+interface EntityFormCustomField {
+  readonly key: string;
+  readonly label: string;
+  readonly type: string;
+  readonly required: boolean;
+  readonly sensitive?: boolean;
+}
+/** What a submitted form splits into: the block input and the custom values. */
+interface EntityFormValues<T> {
+  readonly input: T;
+  readonly custom: Readonly<Record<string, unknown>>;
+}
+type EntityFormResult<T> = ({
+  readonly ok: true;
+} & EntityFormValues<T>) | {
+  readonly ok: false;
+  /** One message per field key; `""` for an issue not on one field. */
+  readonly errors: Readonly<Record<string, string>>;
+};
+interface EntityForm<T> {
+  readonly fields: readonly EntityFormField[];
+  /** Checks the values with the entity schema and the custom fields' `required`. */
+  validate(values: Readonly<Record<string, unknown>>): Promise<EntityFormResult<T>>;
+}
+interface EntityFormOptions<T> {
+  /**
+   * The input keys to show, in order. Default: every key the schema accepts,
+   * except read-only ones.
+   */
+  readonly fields?: readonly (keyof T & string)[];
+  /** Labels by key. Default: the key in words (`dueAt` is `Due at`). */
+  readonly labels?: Readonly<Partial<Record<string, string>>>;
+  /** The tenant's custom fields for the entity, shown after the input fields. */
+  readonly customFields?: readonly EntityFormCustomField[];
+  /**
+   * The zone a `datetime-local` value is read in for an instant field. Default:
+   * `UTC`.
+   */
+  readonly timeZone?: string;
+}
+/**
+ * The fields of a form for one of a block's entities, from its input schema
+ * (`block.schemas.<entity>.input`) and the tenant's custom fields. `validate`
+ * runs the schema, so the form accepts what the block's `create` accepts.
+ *
+ * ```ts
+ * const form = entityForm(workItemsBlock.schemas.work_item.input, {
+ *   fields: ["title", "body", "priority", "dueAt"],
+ *   customFields: await customFields
+ *     .listDefinitions("work_item")
+ *     .orThrow(),
+ * });
+ * ```
+ */
+declare function entityForm<T>(schema: EntitySchema<T>, options?: EntityFormOptions<T>): EntityForm<T>;
+//#endregion
+export { EntityFormOptions as a, entityForm as c, EntityFormInput as i, EntityFormCustomField as n, EntityFormResult as o, EntityFormField as r, EntityFormValues as s, EntityForm as t };

package/dist/entity-naming-DLDhHTbK.js

@@ -0,0 +1,131 @@
+//#region src/core/entity-naming.ts
+const DEFAULT_TENANT = {
+	singular: "organization",
+	plural: "organizations"
+};
+const ENTITY_NAME = /^[a-z][a-z0-9_]{0,40}$/;
+const ALL_CASES = [
+	"snake",
+	"kebab",
+	"camel",
+	"pascal"
+];
+const LOWER_CASES = [
+	"snake",
+	"kebab",
+	"camel"
+];
+/** The English plural of a snake_case noun: `company` to `companies`. */
+function pluralOf(word) {
+	if (/[^aeiou]y$/.test(word)) return `${word.slice(0, -1)}ies`;
+	if (/(s|x|z|ch|sh)$/.test(word)) return `${word}es`;
+	return `${word}s`;
+}
+/** Throws unless `name` is a lowercase identifier a noun can be. */
+function checkEntityName(where, name) {
+	if (!ENTITY_NAME.test(name)) throw new TypeError(`${where}: "${name}" is not a lowercase identifier (letters, digits and underscores)`);
+	return name;
+}
+/** A noun with its plural, derived unless given. */
+function entityNoun(singular, plural) {
+	return {
+		singular,
+		plural: plural ?? pluralOf(singular)
+	};
+}
+function camel(snake) {
+	return snake.replaceAll(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+function form(snake, kind) {
+	switch (kind) {
+		case "snake": return snake;
+		case "kebab": return snake.replaceAll("_", "-");
+		case "camel": return camel(snake);
+		case "pascal": {
+			const value = camel(snake);
+			return value.charAt(0).toUpperCase() + value.slice(1);
+		}
+		default: return kind;
+	}
+}
+/** The case a matched form is used in, read from the character after it. */
+function caseAt(next) {
+	if (next !== void 0 && /[A-Z]/.test(next)) return "camel";
+	return next === "-" ? "kebab" : "snake";
+}
+function escape(value) {
+	return value.replaceAll(/[.*+?^${}()|[\]\\-]/g, String.raw`\$&`);
+}
+function alternatives(rename, direction) {
+	const [source, target] = direction === "forward" ? [rename.from, rename.to] : [rename.to, rename.from];
+	const bounded = rename.bounded ?? true;
+	const found = /* @__PURE__ */ new Map();
+	for (const kind of rename.cases ?? ALL_CASES) for (const number of ["plural", "singular"]) {
+		const match = form(source[number], kind);
+		const replace = form(target[number], kind);
+		const known = found.get(match);
+		if (known !== void 0) {
+			found.set(match, {
+				...known,
+				replace: {
+					...known.replace,
+					[kind]: replace
+				}
+			});
+			continue;
+		}
+		const before = bounded && kind !== "pascal" ? "(?<![A-Za-z0-9])" : "";
+		const after = bounded ? "(?![a-z0-9])" : "";
+		found.set(match, {
+			match,
+			replace: { [kind]: replace },
+			pattern: `${before}${escape(match)}${after}`
+		});
+	}
+	return [...found.values()];
+}
+function compile(renames, direction) {
+	const active = renames.filter((rename) => rename.from.singular !== rename.to.singular || rename.from.plural !== rename.to.plural);
+	if (active.length === 0) return (identifier) => identifier;
+	const all = active.flatMap((rename) => alternatives(rename, direction)).toSorted((a, b) => b.match.length - a.match.length);
+	const replacements = new Map(all.map((each) => [each.match, each.replace]));
+	const pattern = new RegExp(all.map((each) => each.pattern).join("|"), "g");
+	return (identifier) => identifier.replaceAll(pattern, (matched, offset) => {
+		const options = replacements.get(matched) ?? {};
+		return options[caseAt(identifier[offset + matched.length])] ?? Object.values(options)[0] ?? matched;
+	});
+}
+/** Renames for `renames`, longest form first, in one pass. */
+function entityNames(renames = []) {
+	const forward = compile(renames, "forward");
+	const back = compile(renames, "back");
+	return {
+		renames,
+		renamed: renames.some((rename) => rename.from.singular !== rename.to.singular || rename.from.plural !== rename.to.plural),
+		rename: forward,
+		reverse: back
+	};
+}
+/** Several rename sets as one, applied in the same pass. */
+function composeNames(...names) {
+	return entityNames(names.flatMap((each) => each.renames));
+}
+/**
+* The tenant rename (`blocks.tenant.entities.organization`): lowercase forms,
+* anywhere in an identifier, as the tenant rename has always worked.
+*/
+function tenantRename(to = DEFAULT_TENANT) {
+	const noun = typeof to === "string" ? entityNoun(checkEntityName("blocks.tenant.entities.organization", to)) : to;
+	return {
+		from: DEFAULT_TENANT,
+		to: noun,
+		cases: LOWER_CASES,
+		bounded: false
+	};
+}
+/** The renames for the tenant concept alone. */
+function tenantNames(to) {
+	return entityNames(to === void 0 ? [] : [tenantRename(to)]);
+}
+//#endregion
+export { entityNoun as a, entityNames as i, checkEntityName as n, tenantNames as o, composeNames as r, tenantRename as s, DEFAULT_TENANT as t };

package/dist/entity-schema-BXXC1NnT.js

@@ -0,0 +1,39 @@
+import { n as tableSchema } from "./table-schema-BcB-VCQb.js";
+//#region src/blocks/entity-schema.ts
+/** The keys of `EntitySchemas`. */
+const ENTITY_SCHEMA_KINDS = [
+	"input",
+	"change",
+	"listFilter"
+];
+/**
+* The Standard Schema for one of a block's input types, without a validation
+* library: it validates like `tableSchema`, drops unknown keys, and converts to
+* JSON Schema. The spec names every key of `T`.
+*/
+function entitySchema(spec) {
+	return {
+		...tableSchema(spec),
+		spec
+	};
+}
+/** A `Money` field: an amount in minor units and an ISO 4217 code. */
+const moneyField = {
+	kind: "custom",
+	schema: entitySchema({
+		title: "Money",
+		fields: {
+			amount: {
+				kind: "bigint",
+				description: "The amount in minor units."
+			},
+			currency: {
+				kind: "string",
+				minLength: 3,
+				maxLength: 3
+			}
+		}
+	})
+};
+//#endregion
+export { entitySchema as n, moneyField as r, ENTITY_SCHEMA_KINDS as t };

package/dist/env/index.d.ts

@@ -1,2 +1,2 @@
-import { a as EnvResult, c as InlineJwks, d as loadEnv, f as parseEnv, i as EnvOptions, l as PublicEnv, m as toServerEnv, n as ENV_VARIABLES, o as EnvSource, p as publicEnv, r as EnvIssue, s as EnvValidationError, t as BetterSupabaseEnv, u as envSchema } from "../index-CxmVzT-3.js";
+import { a as EnvResult, c as InlineJwks, d as loadEnv, f as parseEnv, i as EnvOptions, l as PublicEnv, m as toServerEnv, n as ENV_VARIABLES, o as EnvSource, p as publicEnv, r as EnvIssue, s as EnvValidationError, t as BetterSupabaseEnv, u as envSchema } from "../index-NRMMhhEi.js";
 export { BetterSupabaseEnv, ENV_VARIABLES, EnvIssue, EnvOptions, EnvResult, EnvSource, EnvValidationError, InlineJwks, PublicEnv, envSchema, loadEnv, parseEnv, publicEnv, toServerEnv };

package/dist/env/index.js

@@ -67,7 +67,10 @@ function preferred(keys) {
 function isJwk(value) {
 	return typeof value === "object" && value !== null && "kty" in value && typeof value.kty === "string";
 }
-/** At least one key, each an object with a string `kty`, the shape the verifier reads. */
+/**
+* At least one key, each an object with a string `kty`, the shape the verifier
+* reads.
+*/
 function isJwkList(value) {
 	return Array.isArray(value) && value.length > 0 && value.every(isJwk);
 }
@@ -207,13 +210,19 @@ function parseEnv(source, options = {}) {
 function processEnv() {
 	return globalThis.process?.env ?? {};
 }
-/** Like `parseEnv`, but throws `EnvValidationError`. Reads `process.env` by default. */
+/**
+* Like `parseEnv`, but throws `EnvValidationError`. Reads `process.env` by
+* default.
+*/
 function loadEnv(source = processEnv(), options = {}) {
 	const result = parseEnv(source, options);
 	if (!result.ok) throw new EnvValidationError(result.issues);
 	return result.env;
 }
-/** The env validator as a Standard Schema, for t3-env, framework config or any validator slot. */
+/**
+* The env validator as a Standard Schema, for t3-env, framework config or any
+* validator slot.
+*/
 function envSchema(options = {}) {
 	return { "~standard": {
 		version: 1,
@@ -236,7 +245,10 @@ function publicEnv(env) {
 		publishableKey: env.publishableKey
 	};
 }
-/** Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of `withSupabase`). */
+/**
+* Converts to `@supabase/server`'s `SupabaseEnv` (the `env` option of
+* `withSupabase`).
+*/
 function toServerEnv(env) {
 	return {
 		url: env.url,

package/dist/envelope-DCfHtVtZ.js

@@ -0,0 +1,90 @@
+import { n as dbError } from "./errors-03ysrOt4.js";
+import { a as ok, r as err } from "./result-B3m7xtRY.js";
+import { n as isRecord } from "./guards-6F2bCtQR.js";
+import { o as tenantFrom, s as tenantPathsFor } from "./claims-Bp9My7XP.js";
+import { n as impersonatorClaim, r as impersonatorOf } from "./impersonation-CZD9AOAk.js";
+import { i as delegatedClaims, n as PERMISSION_CAP_CLAIM, o as permissionCapOf, t as DELEGATION_CLAIMS } from "./delegation-CeXm9AJ3.js";
+//#region src/blocks/jobs/envelope.ts
+/** Marks a payload that carries a job context; pgmq stores it as the payload. */
+const ENVELOPE = "$bs";
+function ticketOf(context, options) {
+	const ticket = options.ticket ?? context?.["ticket"];
+	if (ticket === void 0) return ok(void 0);
+	if (typeof ticket === "string" && ticket !== "") return ok(ticket);
+	return err(dbError("validation", "A job ticket is a non-empty string", { issues: [{
+		message: "Expected a non-empty string",
+		path: ["ticket"]
+	}] }));
+}
+/**
+* The context a job records: the actor, the tenant, the ticket, and the `act`
+* chain and delegation of the token, so a job an OAuth or MCP client queued
+* runs with that client's scopes, never the user's full rights. An invalid
+* `act` chain or malformed delegation is `forbidden`.
+*/
+function recordContext(context, options = {}) {
+	const ticket = ticketOf(context, options);
+	if (!ticket.ok) return ticket;
+	if (!context) return ok(ticket.data === void 0 ? void 0 : { ticket: ticket.data });
+	const claims = context.claims ?? {};
+	const delegated = delegatedClaims(claims);
+	if (!delegated.ok) return err(dbError("forbidden", delegated.reason === "invalid-chain" ? "The job context has an invalid act claim" : "The job context has invalid delegation claims"));
+	const cap = permissionCapOf(claims);
+	if (cap === false) return err(dbError("forbidden", "The job context has an invalid permission cap"));
+	const tenant = tenantFrom(context, tenantPathsFor(void 0));
+	const impersonator = impersonatorOf(claims);
+	const recorded = {
+		...context.actor ? { actor: context.actor } : {},
+		...tenant === void 0 ? {} : { tenant },
+		...ticket.data === void 0 ? {} : { ticket: ticket.data },
+		...delegated.delegation,
+		...cap === void 0 ? {} : { [PERMISSION_CAP_CLAIM]: cap },
+		...impersonator ? { act: impersonatorClaim(impersonator) } : {}
+	};
+	if (!recorded.actor && recorded.tenant === void 0 && recorded.ticket === void 0) return ok(void 0);
+	return ok(recorded);
+}
+/** Wraps a payload with the recorded context of `context`, when there is one. */
+function wrapPayload(payload, context, options = {}) {
+	const recorded = recordContext(context, options);
+	if (!recorded.ok) return recorded;
+	return ok(recorded.data === void 0 ? payload : {
+		[ENVELOPE]: 1,
+		context: recorded.data,
+		payload
+	});
+}
+/** `wrapPayload` that throws a `TypeError` for a context it refuses. */
+function withContext(payload, context, options = {}) {
+	const wrapped = wrapPayload(payload, context, options);
+	if (!wrapped.ok) throw new TypeError(wrapped.error.message);
+	return wrapped.data;
+}
+function isActor(value) {
+	return isRecord(value) && typeof value["id"] === "string" && (value["kind"] === "user" || value["kind"] === "service" || value["kind"] === "anon");
+}
+/**
+* Splits a stored payload into the payload and its recorded context. The
+* recorded `act` and delegation claims come back as they were stored, so
+* `forContext` checks them again and refuses a malformed one.
+*/
+function unwrap(stored) {
+	if (!isRecord(stored) || stored[ENVELOPE] !== 1 || !Object.hasOwn(stored, "payload")) return {
+		payload: stored,
+		context: {}
+	};
+	const recorded = isRecord(stored["context"]) ? stored["context"] : {};
+	const { actor, tenant, ticket } = recorded;
+	const claims = Object.fromEntries(DELEGATION_CLAIMS.filter((key) => Object.hasOwn(recorded, key) && recorded[key] !== void 0).map((key) => [key, recorded[key]]));
+	return {
+		payload: stored["payload"],
+		context: {
+			...isActor(actor) ? { actor } : {},
+			...typeof tenant === "string" && tenant.length > 0 ? { tenant } : {},
+			...ticket === void 0 ? {} : { ticket },
+			...Object.keys(claims).length > 0 ? { claims } : {}
+		}
+	};
+}
+//#endregion
+export { withContext as n, wrapPayload as r, unwrap as t };