better-supabase 0.12.0 → 0.13.0

package/dist/tax-BHSCb5Rw.d.ts

@@ -0,0 +1,280 @@
+/// <reference lib="esnext.temporal" />
+import { b as DbError, f as Result, t as AsyncResult } from "./result-mijqfoJN.js";
+import { r as WebhookInput } from "./signatures-CzqfLlfV.js";
+import { n as Money } from "./money-BNRdJQzA.js";
+//#region src/commerce/payments.d.ts
+/**
+ * Where a payment stands. `requires_action`: the customer still has to act
+ * (pick a method, confirm, pass 3-D Secure). `authorized`: the funds are held
+ * and wait for `capture`.
+ */
+type PaymentStatus = "requires_action" | "processing" | "authorized" | "succeeded" | "failed" | "canceled";
+interface Payment {
+  /** The provider's id, stored with the order as its payment reference. */
+  readonly id: string;
+  /** The provider's `name`. */
+  readonly provider: string;
+  readonly status: PaymentStatus;
+  readonly amount: Money;
+  /** What was captured so far; zero until the payment succeeds. */
+  readonly captured: Money;
+  /** What was refunded so far. */
+  readonly refunded: Money;
+  /** The order or cart the payment is for, as `createPayment` got it. */
+  readonly reference: string;
+  /**
+   * The secret a client confirms the payment with (Stripe's `client_secret`).
+   * Hand it to the paying browser only; never store or log it.
+   */
+  readonly clientSecret?: string;
+  /** Where to send the customer to finish, when the provider redirects. */
+  readonly redirectUrl?: string;
+  readonly metadata: Readonly<Record<string, string>>;
+}
+interface CreatePaymentInput {
+  /** More than zero, in a currency the provider charges. */
+  readonly amount: Money;
+  /** The order or cart this pays for. Webhook events carry it back. */
+  readonly reference: string;
+  /** `manual` holds the funds until `capture`. Defaults to `automatic`. */
+  readonly capture?: "automatic" | "manual";
+  /** The provider's customer id. */
+  readonly customer?: string;
+  readonly description?: string;
+  /** Where a redirecting payment method returns the customer. */
+  readonly returnUrl?: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
+interface PaymentCallOptions {
+  /** The same key returns the first call's result instead of paying twice. */
+  readonly idempotencyKey?: string;
+  readonly signal?: AbortSignal;
+}
+type RefundStatus = "pending" | "succeeded" | "failed" | "canceled";
+interface Refund {
+  readonly id: string;
+  readonly paymentId: string;
+  readonly amount: Money;
+  readonly status: RefundStatus;
+}
+interface RefundInput {
+  /** Defaults to what is left of the captured amount. */
+  readonly amount?: Money;
+  readonly reason?: string;
+}
+type PaymentEventType = "payment.requires_action" | "payment.processing" | "payment.authorized" | "payment.succeeded" | "payment.failed" | "payment.canceled" | "refund.succeeded" | "refund.failed";
+/** A provider's webhook event in one shape for every provider. */
+interface PaymentEvent {
+  /**
+   * The provider's event id. A redelivered event repeats it, so key the
+   * handling on it (the webhook inbox and the `idempotency` module do).
+   */
+  readonly id: string;
+  readonly type: PaymentEventType;
+  readonly paymentId: string;
+  /** The payment's `reference`, when the event carries it. */
+  readonly reference?: string;
+  /** The payment's amount, or the refund's for `refund.*`. */
+  readonly amount?: Money;
+  readonly refundId?: string;
+  readonly occurredAt: Temporal.Instant;
+}
+/**
+ * Takes payments for orders. Versioned: a breaking change ships a new
+ * `apiVersion`. Every method returns a `Result`: `invalid_input` for an amount
+ * the provider can't charge or a refund above what was captured, `not_found`
+ * for an unknown payment, `unauthorized` for a webhook whose signature fails,
+ * and `raised` with the hint `PAYMENT_DECLINED` when the provider declines.
+ */
+interface PaymentProvider {
+  readonly apiVersion: 1;
+  readonly name: string;
+  createPayment(input: CreatePaymentInput, options?: PaymentCallOptions): AsyncResult<Payment>;
+  /** Captures an authorized payment, all of it unless `amount` is less. */
+  capture(paymentId: string, input?: {
+    readonly amount?: Money;
+  }, options?: PaymentCallOptions): AsyncResult<Payment>;
+  refund(paymentId: string, input?: RefundInput, options?: PaymentCallOptions): AsyncResult<Refund>;
+  /**
+   * Verifies a webhook delivery with the provider's secret and returns its
+   * events, none for types the contract doesn't cover.
+   */
+  parseWebhook(input: WebhookInput): AsyncResult<readonly PaymentEvent[]>;
+  /** Releases a payment that was not captured yet. */
+  cancel?(paymentId: string, options?: PaymentCallOptions): AsyncResult<Payment>;
+  get?(paymentId: string, options?: {
+    readonly signal?: AbortSignal;
+  }): AsyncResult<Payment>;
+}
+/** Checks the provider's `apiVersion` before a block uses it. */
+declare function paymentProviderOf(provider: PaymentProvider): PaymentProvider;
+/** The error for an amount a payment can't carry: not money, or not above zero. */
+declare function invalidPaymentAmount(amount: unknown): DbError | undefined;
+//#endregion
+//#region src/commerce/tax.d.ts
+/** Where the goods go (or the customer is, for services). */
+interface TaxAddress {
+  /** ISO 3166-1 alpha-2, such as `NL`. */
+  readonly country: string;
+  /** The state or province code, such as `CA`. */
+  readonly state?: string;
+  readonly postalCode?: string;
+  readonly city?: string;
+  readonly line1?: string;
+  readonly line2?: string;
+}
+interface TaxCartLine {
+  /** The cart line's id; the quote's line for it carries the same `lineId`. */
+  readonly id: string;
+  /** The line's total after discounts, in the cart's currency. */
+  readonly amount: Money;
+  readonly quantity?: number;
+  /**
+   * The product's tax category: a key of the provider's rates or a provider tax
+   * code.
+   */
+  readonly taxCategory?: string;
+  /** The amount already contains the tax (prices shown with VAT). */
+  readonly inclusive?: boolean;
+}
+interface TaxCart {
+  readonly currency: string;
+  readonly lines: readonly TaxCartLine[];
+  readonly shipping?: {
+    readonly amount: Money;
+    readonly taxCategory?: string;
+    readonly inclusive?: boolean;
+  };
+  readonly address: TaxAddress;
+  readonly customer?: {
+    /** The provider's customer id. */
+    readonly id?: string;
+    /** No tax at all, such as a reverse-charged B2B sale. */
+    readonly exempt?: boolean;
+  };
+  /** The cart or order the quote is for. */
+  readonly reference?: string;
+}
+/** The lineId of the shipping line in a quote. */
+declare const SHIPPING_LINE = "shipping";
+interface TaxLine {
+  /** The cart line's `id`, or `SHIPPING_LINE`. */
+  readonly lineId: string;
+  /** The amount the tax is computed on, without the tax. */
+  readonly taxable: Money;
+  readonly tax: Money;
+  /** The decimal fraction applied, such as `"0.21"`. */
+  readonly rate: string;
+  readonly inclusive: boolean;
+  /**
+   * The jurisdiction: Stripe's name (`Netherlands`) or the `fixedRates` region
+   * (`NL`).
+   */
+  readonly jurisdiction?: string;
+  readonly taxCategory?: string;
+}
+interface TaxQuote {
+  /**
+   * The provider's id for the calculation; `commit` turns it into a
+   * transaction.
+   */
+  readonly id: string;
+  /** The provider's `name`. */
+  readonly provider: string;
+  readonly currency: string;
+  /** One per cart line, in cart order, then the shipping line when there is one. */
+  readonly lines: readonly TaxLine[];
+  /** The tax of every line, shipping included. */
+  readonly totalTax: Money;
+  /** When the provider stops accepting the quote for `commit`. */
+  readonly expiresAt?: Temporal.Instant;
+}
+/** A recorded sale or reversal. Store it with the order to reverse it later. */
+interface TaxTransaction {
+  readonly id: string;
+  /** The order number for a sale, the refund's id for a reversal. */
+  readonly reference: string;
+  readonly currency: string;
+  /** Negative for a reversal. */
+  readonly totalTax: Money;
+  readonly lines: readonly TaxLine[];
+}
+interface TaxCommitInput {
+  readonly quote: TaxQuote;
+  /** The order number, unique per sale. */
+  readonly reference: string;
+}
+interface TaxReverseInput {
+  /** The sale `commit` returned. */
+  readonly transaction: TaxTransaction;
+  /** The refund's id, unique per reversal. */
+  readonly reference: string;
+  /**
+   * The refunded part of each line, as positive amounts without tax and their
+   * tax. Unset: the whole sale is reversed.
+   */
+  readonly lines?: readonly {
+    readonly lineId: string;
+    readonly amount: Money;
+    readonly tax: Money;
+  }[];
+}
+interface TaxCallOptions {
+  /** The same key returns the first call's result instead of recording twice. */
+  readonly idempotencyKey?: string;
+  readonly signal?: AbortSignal;
+}
+/**
+ * Computes and records sales tax. Versioned: a breaking change ships a new
+ * `apiVersion`. Every method returns a `Result`: `invalid_input` for a cart
+ * that mixes currencies or a reversal above the sale, and `not_found` for an
+ * address the provider has no rate for.
+ */
+interface TaxProvider {
+  readonly apiVersion: 1;
+  readonly name: string;
+  quote(cart: TaxCart, options?: TaxCallOptions): AsyncResult<TaxQuote>;
+  commit(input: TaxCommitInput, options?: TaxCallOptions): AsyncResult<TaxTransaction>;
+  reverse(input: TaxReverseInput, options?: TaxCallOptions): AsyncResult<TaxTransaction>;
+}
+/** Checks the provider's `apiVersion` before a block uses it. */
+declare function taxProviderOf(provider: TaxProvider): TaxProvider;
+/**
+ * The first problem with a cart: a line or shipping amount that isn't money, is
+ * negative or is in another currency, or a country that isn't two capital
+ * letters.
+ */
+declare function invalidTaxCart(cart: TaxCart): DbError | undefined;
+/** The lines and total of a reversal, checked against the sale. */
+declare function reversalOf(input: TaxReverseInput): Result<{
+  readonly lines: readonly TaxLine[];
+  readonly totalTax: Money;
+}>;
+/** Rates per tax category, such as `{ standard: "0.21", reduced: "0.09" }`. */
+type TaxRates = Readonly<Record<string, string>>;
+interface FixedRatesOptions {
+  /** Defaults to `fixed-rates`. */
+  readonly name?: string;
+  /**
+   * Rates per region: a country code (`NL`) or a country and state (`US-CA`),
+   * which wins over its country.
+   */
+  readonly rates: Readonly<Record<string, TaxRates>>;
+  /** The category of a line without one. Defaults to `standard`. */
+  readonly defaultCategory?: string;
+  /** The category of shipping. Defaults to `defaultCategory`. */
+  readonly shippingCategory?: string;
+  /**
+   * A region without rates: `error` returns `not_found` (the default), `zero`
+   * quotes no tax.
+   */
+  readonly unknownRegion?: "error" | "zero";
+}
+/**
+ * A `TaxProvider` with fixed rates per country (and state) and tax category,
+ * rounded half to even per line. It keeps nothing: `commit` and `reverse`
+ * return the transaction for the app to store.
+ */
+declare function fixedRates(options: FixedRatesOptions): TaxProvider;
+//#endregion
+export { PaymentProvider as C, RefundStatus as D, RefundInput as E, invalidPaymentAmount as O, PaymentEventType as S, Refund as T, taxProviderOf as _, TaxCart as a, PaymentCallOptions as b, TaxLine as c, TaxRates as d, TaxReverseInput as f, reversalOf as g, invalidTaxCart as h, TaxCallOptions as i, paymentProviderOf as k, TaxProvider as l, fixedRates as m, SHIPPING_LINE as n, TaxCartLine as o, TaxTransaction as p, TaxAddress as r, TaxCommitInput as s, FixedRatesOptions as t, TaxQuote as u, CreatePaymentInput as v, PaymentStatus as w, PaymentEvent as x, Payment as y };

package/dist/tax-keSd-q_1.js

@@ -0,0 +1,140 @@
+import { n as dbError } from "./errors-D7u24ZJH.js";
+import { a as ok, r as err, t as AsyncResult } from "./result-DIT_qp4G.js";
+import { c as isMoney, h as negateMoney, i as applyRate, l as isRate, v as subtractMoney, y as sumMoney } from "./money-BZl985O-.js";
+//#region src/commerce/tax.ts
+/** The lineId of the shipping line in a quote. */
+const SHIPPING_LINE = "shipping";
+/** Checks the provider's `apiVersion` before a block uses it. */
+function taxProviderOf(provider) {
+	const version = provider.apiVersion;
+	if (version !== 1) throw new TypeError(`tax "${provider.name}" targets tax provider API ${String(version)}; this better-supabase supports 1. Upgrade better-supabase or use a release of the provider for API 1.`);
+	return provider;
+}
+const invalid = (message, hint) => dbError("invalid_input", message, { hint });
+/**
+* The first problem with a cart: a line or shipping amount that isn't money, is
+* negative or is in another currency, or a country that isn't two capital
+* letters.
+*/
+function invalidTaxCart(cart) {
+	if (!/^[A-Z]{2}$/.test(cart.address.country)) return invalid(`"${cart.address.country}" is not an ISO 3166-1 alpha-2 country code`, "TAX_ADDRESS_INVALID");
+	const amounts = [...cart.lines.map((line) => line.amount), ...cart.shipping ? [cart.shipping.amount] : []];
+	for (const amount of amounts) {
+		if (!isMoney(amount) || amount.amount < 0n) return invalid("Every cart line is Money of zero or more", "TAX_AMOUNT_INVALID");
+		if (amount.currency !== cart.currency) return invalid(`A ${amount.currency} line in a ${cart.currency} cart: lines never mix currencies`, "TAX_CURRENCY_MISMATCH");
+	}
+}
+/** The lines and total of a reversal, checked against the sale. */
+function reversalOf(input) {
+	const { transaction } = input;
+	if (input.lines === void 0) {
+		const lines = transaction.lines.map((line) => ({
+			...line,
+			taxable: negateMoney(line.taxable),
+			tax: negateMoney(line.tax)
+		}));
+		return ok({
+			lines,
+			totalTax: negateMoney(transaction.totalTax)
+		});
+	}
+	const byId = new Map(transaction.lines.map((line) => [line.lineId, line]));
+	const lines = [];
+	for (const part of input.lines) {
+		const sold = byId.get(part.lineId);
+		if (sold === void 0) return err(invalid(`The sale has no line "${part.lineId}"`, "TAX_REVERSAL_UNKNOWN_LINE"));
+		if (!isMoney(part.amount) || !isMoney(part.tax) || part.amount.currency !== transaction.currency || part.tax.currency !== transaction.currency || part.amount.amount < 0n || part.tax.amount < 0n || part.tax.amount > sold.tax.amount || part.amount.amount > sold.taxable.amount) return err(invalid(`The reversal of "${part.lineId}" is not a part of the sold line in ${transaction.currency}`, "TAX_REVERSAL_TOO_LARGE"));
+		lines.push({
+			...sold,
+			taxable: negateMoney(part.amount),
+			tax: negateMoney(part.tax)
+		});
+	}
+	return ok({
+		lines,
+		totalTax: sumMoney(lines.map((line) => line.tax), transaction.currency)
+	});
+}
+/**
+* A `TaxProvider` with fixed rates per country (and state) and tax category,
+* rounded half to even per line. It keeps nothing: `commit` and `reverse`
+* return the transaction for the app to store.
+*/
+function fixedRates(options) {
+	for (const [region, rates] of Object.entries(options.rates)) {
+		if (!/^[A-Z]{2}(-[A-Z0-9]{1,3})?$/.test(region)) throw new TypeError(`fixedRates: "${region}" is not a country code (NL) or a country and state (US-CA)`);
+		for (const [category, rate] of Object.entries(rates)) if (!isRate(rate)) throw new TypeError(`fixedRates: the ${region} "${category}" rate "${String(rate)}" is not a decimal fraction such as "0.21"`);
+	}
+	const name = options.name ?? "fixed-rates";
+	const defaultCategory = options.defaultCategory ?? "standard";
+	const shippingCategory = options.shippingCategory ?? defaultCategory;
+	const regionFor = (address) => {
+		const keys = [...address.state === void 0 ? [] : [`${address.country}-${address.state}`], address.country];
+		for (const region of keys) {
+			const rates = options.rates[region];
+			if (rates !== void 0) return {
+				region,
+				rates
+			};
+		}
+	};
+	const lineOf = (lineId, amount, category, inclusive, region, exempt) => {
+		const rate = exempt || region === void 0 ? "0" : region.rates[category];
+		if (rate === void 0) return err(dbError("not_found", `No "${category}" tax rate for this region`, { hint: "TAX_RATE_UNKNOWN" }));
+		const tax = applyRate(amount, rate, { included: inclusive });
+		return ok({
+			lineId,
+			taxable: inclusive ? subtractMoney(amount, tax) : amount,
+			tax,
+			rate,
+			inclusive,
+			...region === void 0 ? {} : { jurisdiction: region.region },
+			taxCategory: category
+		});
+	};
+	return {
+		apiVersion: 1,
+		name,
+		quote: (cart) => AsyncResult.from(() => Promise.resolve(quoteOf(cart))),
+		commit: ({ quote, reference }) => AsyncResult.ok({
+			id: quote.id,
+			reference,
+			currency: quote.currency,
+			totalTax: quote.totalTax,
+			lines: quote.lines
+		}),
+		reverse: (input) => AsyncResult.from(() => Promise.resolve(reversalOf(input))).map((reversal) => ({
+			id: `${input.transaction.id}:${input.reference}`,
+			reference: input.reference,
+			currency: input.transaction.currency,
+			...reversal
+		}))
+	};
+	function quoteOf(cart) {
+		const problem = invalidTaxCart(cart);
+		if (problem) return err(problem);
+		const rates = regionFor(cart.address);
+		if (rates === void 0 && options.unknownRegion !== "zero") return err(dbError("not_found", `No tax rates for ${cart.address.country}${cart.address.state ? `-${cart.address.state}` : ""}`, { hint: "TAX_REGION_UNKNOWN" }));
+		const exempt = cart.customer?.exempt === true;
+		const lines = [];
+		for (const line of cart.lines) {
+			const taxed = lineOf(line.id, line.amount, line.taxCategory ?? defaultCategory, line.inclusive === true, rates, exempt);
+			if (!taxed.ok) return taxed;
+			lines.push(taxed.data);
+		}
+		if (cart.shipping) {
+			const taxed = lineOf(SHIPPING_LINE, cart.shipping.amount, cart.shipping.taxCategory ?? shippingCategory, cart.shipping.inclusive === true, rates, exempt);
+			if (!taxed.ok) return taxed;
+			lines.push(taxed.data);
+		}
+		return ok({
+			id: `fixed_${crypto.randomUUID()}`,
+			provider: name,
+			currency: cart.currency,
+			lines,
+			totalTax: sumMoney(lines.map((line) => line.tax), cart.currency)
+		});
+	}
+}
+//#endregion
+export { taxProviderOf as a, reversalOf as i, fixedRates as n, invalidTaxCart as r, SHIPPING_LINE as t };

package/dist/tee-1fsH3bEz.js

@@ -0,0 +1,101 @@
+import { a as ok, r as err, s as toDbError, t as AsyncResult } from "./result-DIT_qp4G.js";
+//#region src/streams/tee.ts
+/**
+* Copies `source` into `store` under `id` while passing it through. Chunks are
+* written in batches, each at its own index, so a reader that counted `n`
+* chunks of the live stream resumes with `read(id, n)`.
+*/
+function teeToStore(store, id, source, options = {}) {
+	const [live, copy] = source.tee();
+	return {
+		stream: live,
+		persisted: AsyncResult.from(() => persist(store, id, copy, options))
+	};
+}
+/**
+* Stores `source` under `id` without a live copy, for a stream the caller
+* already sends elsewhere (the second branch of its own `tee()`). Settles like
+* `teeToStore`'s `persisted`.
+*/
+function writeToStore(store, id, source, options = {}) {
+	return AsyncResult.from(() => persist(store, id, source, options));
+}
+async function persist(store, id, copy, options) {
+	const { flushMs = 100, flushBytes = 4096, onCancel } = options;
+	const opened = await store.open(id, {
+		...options.owner === void 0 ? {} : { owner: options.owner },
+		...options.tenant === void 0 ? {} : { tenant: options.tenant },
+		...options.kind === void 0 ? {} : { kind: options.kind },
+		...options.ttl === void 0 ? {} : { ttl: options.ttl }
+	});
+	if (!opened.ok) {
+		copy.cancel().catch(() => void 0);
+		return opened;
+	}
+	let next = 0;
+	let buffer = [];
+	let bytes = 0;
+	let failure;
+	let cancelled = false;
+	let timer;
+	let writing = Promise.resolve();
+	const flush = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+		if (buffer.length === 0) return writing;
+		const batch = buffer;
+		const from = next;
+		buffer = [];
+		bytes = 0;
+		next += batch.length;
+		writing = writing.then(async () => {
+			if (failure) return;
+			const appended = await store.append(id, from, batch);
+			if (!appended.ok) {
+				failure = appended.error;
+				return;
+			}
+			if (appended.data.cancelled && !cancelled) {
+				cancelled = true;
+				onCancel?.();
+			}
+		});
+		return writing;
+	};
+	const reader = copy.getReader();
+	let sourceError;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			buffer.push(value);
+			bytes += value.length;
+			if (bytes >= flushBytes) flush();
+			else timer ??= setTimeout(() => void flush(), flushMs);
+			if (failure) break;
+		}
+	} catch (cause) {
+		sourceError = cause;
+	} finally {
+		reader.releaseLock();
+	}
+	await flush();
+	if (failure) {
+		copy.cancel().catch(() => void 0);
+		return err(failure);
+	}
+	const closed = await store.close(id);
+	if (!closed.ok) return closed;
+	return sourceError === void 0 ? ok(next) : err(toDbError(sourceError));
+}
+/**
+* The rest of stream `id` from `fromIdx`, or `undefined` when there is nothing
+* to resume: no such stream, or a closed one the client has read to the end. A
+* route answers `undefined` with 204.
+*/
+function resumeFromStore(store, id, options = {}) {
+	const from = options.fromIdx ?? 0;
+	return store.status(id).map((status) => status === void 0 || status.closed && from >= status.next ? void 0 : store.read(id, from, options.signal === void 0 ? {} : { signal: options.signal }));
+}
+//#endregion
+export { teeToStore as n, writeToStore as r, resumeFromStore as t };

package/dist/template-DXsGm_R0.js

@@ -0,0 +1,126 @@
+import { t as DbException } from "./db-exception-CnWcYPxL.js";
+import { n as dbError } from "./errors-D7u24ZJH.js";
+//#region src/core/template.ts
+const PLACEHOLDER = /\{(\.\.\.)?([A-Za-z_][A-Za-z0-9_]*)\}/g;
+function parseSegment(segment) {
+	const parts = [];
+	let last = 0;
+	for (const match of segment.matchAll(PLACEHOLDER)) {
+		if (match.index > last) parts.push({
+			kind: "literal",
+			text: segment.slice(last, match.index)
+		});
+		parts.push({
+			kind: match[1] ? "rest" : "param",
+			name: match[2]
+		});
+		last = match.index + match[0].length;
+	}
+	if (last < segment.length) parts.push({
+		kind: "literal",
+		text: segment.slice(last)
+	});
+	return parts;
+}
+const escapeRegex = (text) => text.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+function parseTemplate(source, separator, validate, options = {}) {
+	const segments = source.split(separator).map(parseSegment);
+	const params = [];
+	let rest;
+	for (const [position, segment] of segments.entries()) {
+		if (segment.length === 0) throw new TypeError(`Template "${source}" has an empty segment`);
+		for (let index = 1; index < segment.length; index += 1) if (segment[index].kind !== "literal" && segment[index - 1].kind !== "literal") throw new TypeError(`Template "${source}" has adjacent placeholders`);
+		for (const part of segment) {
+			if (part.kind === "literal") continue;
+			if (part.kind === "rest") {
+				if (!options.rest) throw new TypeError(`Template "${source}" uses {...${part.name}}, which is not supported here`);
+				if (segment.length !== 1 || position !== segments.length - 1) throw new TypeError(`Template "${source}": {...${part.name}} must be the whole last segment`);
+				rest = part.name;
+			}
+			if (params.includes(part.name)) throw new TypeError(`Template "${source}" repeats {${part.name}}`);
+			params.push(part.name);
+		}
+	}
+	if (/[{}]/.test(segments.flat().map((part) => part.kind === "literal" ? part.text : "").join(""))) throw new TypeError(`Template "${source}" has an unbalanced brace`);
+	const sep = escapeRegex(separator);
+	const valueClass = `[^${separator === "/" ? "/" : sep}]+`;
+	const restClass = `${valueClass}(?:${sep}${valueClass})*`;
+	const regexFor = (withNames) => segments.map((segment) => segment.map((part) => {
+		if (part.kind === "literal") return escapeRegex(part.text);
+		const pattern = part.kind === "rest" ? restClass : valueClass;
+		return withNames ? `(?<${part.name}>${pattern})` : pattern;
+	}).join("")).join(sep);
+	const matcher = new RegExp(`^${regexFor(true)}$`);
+	const valueProblem = (name, value) => value === "" ? "is empty" : value.includes(separator) ? `contains "${separator}"` : validate(name, value);
+	const restProblem = (name, value) => {
+		if (value === "") return "is empty";
+		for (const part of value.split(separator)) {
+			const problem = part === "" ? "has an empty segment" : validate(name, part);
+			if (problem) return problem;
+		}
+	};
+	const render = (name, raw) => {
+		if (raw === void 0 || typeof raw !== "string" && typeof raw !== "number") throw new DbException(dbError("invalid_input", `Missing value for {${name}}`));
+		const value = String(raw);
+		const problem = rest === name ? restProblem(name, value) : valueProblem(name, value);
+		if (problem) throw new DbException(dbError("invalid_input", `Value for {${name}} ${problem}`));
+		return value;
+	};
+	const renderSegment = (segment, values) => segment.map((part) => part.kind === "literal" ? part.text : render(part.name, values[part.name])).join("");
+	return {
+		source,
+		separator,
+		params,
+		segments: segments.length,
+		build: (values) => segments.map((segment) => renderSegment(segment, values)).join(separator),
+		match(value) {
+			const found = matcher.exec(value);
+			if (!found?.groups) return found ? {} : null;
+			const out = {};
+			for (const name of params) {
+				const part = found.groups[name];
+				if (rest === name ? restProblem(name, part) : validate(name, part)) return null;
+				out[name] = part;
+			}
+			return out;
+		},
+		prefix(values, maxSegments = segments.length) {
+			const out = [];
+			for (const segment of segments.slice(0, maxSegments)) {
+				if (segment.some((part) => part.kind !== "literal" && values[part.name] === void 0)) break;
+				out.push(renderSegment(segment, values));
+			}
+			return out.join(separator);
+		},
+		segmentOf(name) {
+			const index = segments.findIndex((segment) => segment.length === 1 && segment[0].kind === "param" && segment[0].name === name);
+			return index === -1 ? void 0 : index + 1;
+		},
+		sqlPattern: `^${regexFor(false)}$`,
+		rest
+	};
+}
+function sqlString(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+function sqlIdent(value) {
+	return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+/** Postgres identifier-safe name part: `customer-logos` → `customer_logos`. */
+function slug(value) {
+	return value.replaceAll(/[^A-Za-z0-9]+/g, "_").replaceAll(/^_|_$/g, "").toLowerCase();
+}
+/**
+* SQL for the JWT claim at a dotted path, or the first set one of several
+* (`coalesce`).
+*/
+function claimSql(claim) {
+	const expressions = (typeof claim === "string" ? [claim] : claim).map((path) => {
+		const keys = path.split(".");
+		const last = keys.pop();
+		return `(select auth.jwt())${keys.map((key) => ` -> ${sqlString(key)}`).join("")} ->> ${sqlString(last)}`;
+	});
+	return expressions.length === 1 ? expressions[0] : `coalesce(${expressions.join(", ")})`;
+}
+//#endregion
+export { sqlString as a, sqlIdent as i, parseTemplate as n, slug as r, claimSql as t };