@openlup/platform 0.0.0-stage → 0.15.0

package/dist/data/postgresGateway.js

@@ -0,0 +1,135 @@
+import { PgGatewayClient } from "./queryBuilder.js";
+/** Convert node-postgres timestamptz text to lossless RFC 3339. */
+export function postgresTimestampTzToRfc3339(value) {
+    const parts = /^(\d{4,}-\d{2}-\d{2}) (\d{2}:\d{2}:\d{2}(?:\.\d+)?)([+-])(\d{2})(?::?(\d{2}))?$/.exec(value);
+    if (!parts)
+        return value;
+    const [, date, time, sign, offsetHours, offsetMinutes = "00"] = parts;
+    return `${date}T${time}${sign}${offsetHours}:${offsetMinutes}`;
+}
+/** Keep PostgREST-compatible, lossless timestamp strings at the gateway edge. */
+export function createPostgresGatewayTypeOverrides(TypeOverridesCtor) {
+    const overrides = new TypeOverridesCtor();
+    // node-postgres otherwise turns timestamptz into a millisecond Date and drops
+    // PostgreSQL microseconds, making an immediate schedule round-trip look stale.
+    overrides.setTypeParser(1184, "text", postgresTimestampTzToRfc3339);
+    return overrides;
+}
+/**
+ * Build a node-postgres-backed DataGatewayPort. Pure: NO pool/connection is created until a port
+ * method runs work (lazy, like the supabase adapter), so the slot binds even before DATABASE_URL is
+ * present (keeps composeBundle({}) non-null). The pool is created once and reused across calls.
+ */
+export function createPostgresDataGateway(env, options = {}) {
+    const transactions = createPooledPostgresTransactions(env, options);
+    return {
+        async asService(work) {
+            return transactions.run(async (client) => {
+                await client.query("SET LOCAL ROLE service_role");
+            }, work);
+        },
+        async asActor(claims, work) {
+            return transactions.run(async (client) => {
+                const jwtClaims = buildJwtClaims(claims);
+                if (jwtClaims) {
+                    // Parameterized: the claims JSON is bound as $1, never interpolated into the SET statement.
+                    await client.query("SELECT set_config('request.jwt.claims', $1, true)", [jwtClaims]);
+                    await client.query("SET LOCAL ROLE authenticated");
+                }
+                else {
+                    // No usable principal → drop to the `anon` role so RLS evaluates the request as
+                    // unauthenticated. CRITICAL: the connection's own login role may be a superuser/owner
+                    // (which BYPASSes RLS), so we MUST switch roles rather than leave the default — otherwise an
+                    // unauthenticated actor would silently see everything. Fail-safe: anon is RLS-bound, never
+                    // elevated. (No request.jwt.claims is set, so auth.uid() returns NULL.)
+                    await client.query("SET LOCAL ROLE anon");
+                }
+            }, work);
+        },
+    };
+}
+/**
+ * Build one role-free, per-operation lane. Do not use this for generic service
+ * work: DataGatewayPort.asService remains the mandatory service_role boundary.
+ * Only a named owner-authority capability of the deployment may hold a lane.
+ */
+export function createPostgresRoleFreeTransactionLane(env, options = {}) {
+    const transactions = createPooledPostgresTransactions(env, options);
+    return { run: (work) => transactions.run(async () => { }, work), close: transactions.close };
+}
+function createPooledPostgresTransactions(env, options) {
+    let poolPromise = null;
+    async function getPool() {
+        // Cache the in-flight promise (not the resolved Pool) so concurrent first calls share ONE pool
+        // rather than racing to build two. Promise.resolve normalizes the factory's Pool | Promise<Pool>.
+        if (!poolPromise) {
+            const factory = options.poolFactory ?? defaultPoolFactory;
+            poolPromise = Promise.resolve(factory(env));
+        }
+        return poolPromise;
+    }
+    async function withClient(setup, work) {
+        const activePool = await getPool();
+        const client = await activePool.connect();
+        try {
+            await client.query("BEGIN");
+            await setup(client);
+            const result = await work(new PgGatewayClient(client));
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (error) {
+            try {
+                await client.query("ROLLBACK");
+            }
+            catch {
+                // ignore rollback failure; surface the original error
+            }
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    return {
+        run: withClient,
+        async close() {
+            if (poolPromise)
+                await (await poolPromise).end();
+        },
+    };
+}
+/**
+ * Build the request.jwt.claims JSON PostgREST would set. Returns null when there is no usable
+ * principal (no sub) so the caller stays anon rather than asserting an authenticated-but-empty role.
+ */
+function buildJwtClaims(claims) {
+    if (!claims || !claims.sub)
+        return null;
+    const role = claims.role && claims.role.trim() !== "" ? claims.role : "authenticated";
+    return JSON.stringify({ sub: claims.sub, role });
+}
+// Lazy default: only import `pg` and build the Pool when actually invoked, so typecheck/test paths
+// that never run work do not load the driver. SET LOCAL keeps pooled-connection reuse safe.
+async function defaultPoolFactory(env) {
+    const pg = await import("pg").catch(peerMissing);
+    const PoolCtor = (pg.default?.Pool ?? pg.Pool);
+    const TypeOverridesCtor = (pg.default?.TypeOverrides ?? pg.TypeOverrides);
+    return new PoolCtor({
+        connectionString: env.connectionString,
+        types: createPostgresGatewayTypeOverrides(TypeOverridesCtor),
+    });
+}
+/** Resolve the gateway env from process env (DATABASE_URL), mirroring the supabase binding shape. */
+export function resolvePostgresDataGatewayEnv(env) {
+    return { connectionString: env.DATABASE_URL ?? "" };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres data gateway; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}

package/dist/data/queryBuilder.d.ts

@@ -0,0 +1,54 @@
+import type { PoolClient } from "pg";
+import { type PgQueryExecutor, type PgShimError, type PgShimResult } from "./queryBuilderSql.js";
+export type { PgQueryExecutor, PgShimError, PgShimResult };
+/**
+ * Builder over one pg client. Chainable + awaitable (PromiseLike). Every value flows through a param
+ * accumulator, so the rendered SQL contains only $N placeholders for values.
+ */
+export declare class PgQueryBuilder<T = unknown> implements PromiseLike<PgShimResult<T>> {
+    private readonly client;
+    private state;
+    constructor(client: PgQueryExecutor, table: string);
+    select(columns: string, options?: {
+        count?: string;
+        head?: boolean;
+    }): this;
+    insert(values: Record<string, unknown> | Array<Record<string, unknown>>): this;
+    update(values: Record<string, unknown>): this;
+    eq(column: string, value: unknown): this;
+    gt(column: string, value: unknown): this;
+    gte(column: string, value: unknown): this;
+    lte(column: string, value: unknown): this;
+    in(column: string, values: unknown[]): this;
+    is(column: string, value: unknown): this;
+    ilike(column: string, value: string): this;
+    order(column: string, options?: {
+        ascending?: boolean;
+    }): this;
+    limit(count: number): this;
+    range(from: number, to: number): Promise<PgShimResult<T>>;
+    maybeSingle(): Promise<PgShimResult<T>>;
+    single(): Promise<PgShimResult<T>>;
+    then<R1 = PgShimResult<T>, R2 = never>(onfulfilled?: ((value: PgShimResult<T>) => R1 | PromiseLike<R1>) | null, onrejected?: ((reason: unknown) => R2 | PromiseLike<R2>) | null): Promise<R1 | R2>;
+    private run;
+    private runExactCount;
+    private shape;
+    private compile;
+    private compileSelect;
+    private compileInsert;
+    private compileUpdate;
+    private renderWhere;
+    private renderOrder;
+    private renderLimitOffset;
+}
+/** supabase-js-style client over one acquired pg client: `.from(t)` + `.rpc(fn, args)`. */
+export declare class PgGatewayClient {
+    private readonly client;
+    constructor(client: PgQueryExecutor);
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+    from<T = Record<string, unknown>>(table: string): PgQueryBuilder<T>;
+    rpc(functionName: string, args?: Record<string, unknown>): Promise<PgShimResult>;
+}
+export type { PoolClient };

package/dist/data/queryBuilder.js

@@ -0,0 +1,240 @@
+// Vanilla-Postgres query-builder shim.
+//
+// Option A (approved): a SCOPED, injection-safe builder that emulates ONLY the supabase-js methods
+// the 6 existing gateway consumers actually call — never a full PostgREST reimplementation. It
+// translates a builder chain into a single PARAMETERIZED `pg` query ($1,$2,…). Values are never
+// string-interpolated and identifiers are allowlist-validated; both invariants live in the pure SQL
+// layer (queryBuilderSql.ts), which this file composes.
+//
+// Result semantics mirror PostgREST for the methods used:
+//   - default (await builder)            -> { data: Row[], error }
+//   - .maybeSingle()                     -> { data: Row | null, error } (0/1 row; >1 is an error)
+//   - .single()                          -> { data: Row, error }       (exactly 1 row; else error)
+//   - .range(from,to)/.limit(n)          -> LIMIT/OFFSET, returns { data: Row[], error }
+//   - .select(c, {count:"exact"[,head]}) -> { data, count } from a separate aggregate; head omits rows
+//   - .insert(v).select(c).maybeSingle() -> INSERT ... RETURNING c, single row
+//   - .update(v)...                      -> UPDATE ... [RETURNING c]
+//   - error.code carries the pg SQLSTATE (e.g. 23505 unique-violation) so consumers' code-based
+//     branches (idempotency replay) keep working unchanged.
+//
+// The shim is constructed over a SINGLE acquired pg client (one per asActor/asService tx in the
+// DataGatewayPort), so every query here runs inside that request's transaction with its RLS GUCs set.
+import { ParamAccumulator, joinParts, quoteIdent, rangeNotSatisfiable, renderColumns, renderCountQuery, renderFilter, renderInsertStatement, toShimError, unwrapRpcRows, } from "./queryBuilderSql.js";
+/**
+ * Builder over one pg client. Chainable + awaitable (PromiseLike). Every value flows through a param
+ * accumulator, so the rendered SQL contains only $N placeholders for values.
+ */
+export class PgQueryBuilder {
+    client;
+    state;
+    constructor(client, table) {
+        this.client = client;
+        this.state = {
+            table,
+            mode: "select",
+            columns: "*",
+            filters: [],
+            orders: [],
+            limit: null,
+            offset: null,
+            insertRows: null,
+            updateValues: null,
+            exactCount: false,
+            head: false,
+            rangeRequested: false,
+        };
+    }
+    select(columns, options) {
+        this.state.columns = columns;
+        this.state.exactCount = options?.count === "exact";
+        this.state.head = options?.head === true;
+        return this;
+    }
+    insert(values) {
+        this.state.mode = "insert";
+        this.state.insertRows = Array.isArray(values) ? values : [values];
+        return this;
+    }
+    update(values) {
+        this.state.mode = "update";
+        this.state.updateValues = values;
+        return this;
+    }
+    eq(column, value) {
+        this.state.filters.push({ kind: "eq", column, value });
+        return this;
+    }
+    gt(column, value) {
+        this.state.filters.push({ kind: "gt", column, value });
+        return this;
+    }
+    gte(column, value) {
+        this.state.filters.push({ kind: "gte", column, value });
+        return this;
+    }
+    lte(column, value) {
+        this.state.filters.push({ kind: "lte", column, value });
+        return this;
+    }
+    in(column, values) {
+        this.state.filters.push({ kind: "in", column, values });
+        return this;
+    }
+    is(column, value) {
+        this.state.filters.push({ kind: "is", column, value });
+        return this;
+    }
+    ilike(column, value) {
+        this.state.filters.push({ kind: "ilike", column, value });
+        return this;
+    }
+    order(column, options) {
+        this.state.orders.push({ column, ascending: options?.ascending !== false });
+        return this;
+    }
+    limit(count) {
+        this.state.limit = count;
+        return this;
+    }
+    range(from, to) {
+        // PostgREST range is inclusive on both ends → LIMIT (to-from+1) OFFSET from.
+        this.state.offset = from;
+        this.state.limit = to - from + 1;
+        this.state.rangeRequested = true;
+        return this.run("many");
+    }
+    async maybeSingle() {
+        return this.run("maybe");
+    }
+    async single() {
+        return this.run("single");
+    }
+    then(onfulfilled, onrejected) {
+        return this.run("many").then(onfulfilled, onrejected);
+    }
+    async run(cardinality) {
+        try {
+            const count = this.state.exactCount ? await this.runExactCount() : null;
+            // A page past the end is a REFUSAL upstream, not an empty answer — but only once the total is
+            // known, which is why this sits behind the count and not behind `.range()` itself.
+            const unsatisfiable = this.state.rangeRequested ? rangeNotSatisfiable(this.state.offset, count) : null;
+            if (unsatisfiable)
+                return { data: [], error: unsatisfiable, count: null };
+            // head:true is a HEAD request: no body, so the client contract reports data:null and no row query.
+            if (this.state.head)
+                return { data: null, error: null, count };
+            const { text, values } = this.compile();
+            const { rows } = await this.client.query(text, values);
+            // The client contract reports count: null unless a count was requested; `shape` must not invent one.
+            return { ...this.shape(rows, cardinality), count };
+        }
+        catch (error) {
+            return { data: (cardinality === "many" ? [] : null), error: toShimError(error), count: null };
+        }
+    }
+    async runExactCount() {
+        const params = new ParamAccumulator();
+        const { rows } = await this.client.query(renderCountQuery(this.state.table, this.state.filters, params), params.values);
+        return Number(rows[0]?.exact_count ?? 0);
+    }
+    shape(rows, cardinality) {
+        if (cardinality === "many") {
+            return { data: rows, error: null };
+        }
+        if (rows.length > 1) {
+            // PostgREST returns 406 (PGRST116) when maybeSingle/single match multiple rows.
+            return { data: null, error: { code: "PGRST116", message: "multiple rows returned" } };
+        }
+        if (cardinality === "single" && rows.length === 0) {
+            return { data: null, error: { code: "PGRST116", message: "no rows returned" } };
+        }
+        return { data: (rows[0] ?? null), error: null };
+    }
+    compile() {
+        const params = new ParamAccumulator();
+        if (this.state.mode === "insert")
+            return this.compileInsert(params);
+        if (this.state.mode === "update")
+            return this.compileUpdate(params);
+        return this.compileSelect(params);
+    }
+    compileSelect(params) {
+        const parts = [`SELECT ${renderColumns(this.state.columns)} FROM ${quoteIdent(this.state.table)}`];
+        parts.push(this.renderWhere(params));
+        parts.push(this.renderOrder());
+        parts.push(this.renderLimitOffset(params));
+        return { text: joinParts(parts), values: params.values };
+    }
+    compileInsert(params) {
+        const text = renderInsertStatement(this.state.table, this.state.insertRows ?? [], this.state.columns, params);
+        return { text, values: params.values };
+    }
+    compileUpdate(params) {
+        const values = this.state.updateValues ?? {};
+        const assignments = Object.keys(values)
+            .map((c) => `${quoteIdent(c)} = ${params.add(values[c])}`)
+            .join(", ");
+        if (assignments === "")
+            throw new Error("pg-shim: update requires at least one column");
+        const parts = [`UPDATE ${quoteIdent(this.state.table)} SET ${assignments}`];
+        parts.push(this.renderWhere(params));
+        const returning = this.state.columns && this.state.columns !== "*"
+            ? `RETURNING ${renderColumns(this.state.columns)}`
+            : "";
+        if (returning)
+            parts.push(returning);
+        return { text: joinParts(parts), values: params.values };
+    }
+    renderWhere(params) {
+        if (this.state.filters.length === 0)
+            return "";
+        const clauses = this.state.filters.map((f) => renderFilter(f, params));
+        return `WHERE ${clauses.join(" AND ")}`;
+    }
+    renderOrder() {
+        if (this.state.orders.length === 0)
+            return "";
+        const cols = this.state.orders
+            .map((o) => `${quoteIdent(o.column)} ${o.ascending ? "ASC" : "DESC"}`)
+            .join(", ");
+        return `ORDER BY ${cols}`;
+    }
+    renderLimitOffset(params) {
+        const parts = [];
+        if (this.state.limit !== null)
+            parts.push(`LIMIT ${params.add(this.state.limit)}`);
+        if (this.state.offset !== null)
+            parts.push(`OFFSET ${params.add(this.state.offset)}`);
+        return parts.join(" ");
+    }
+}
+/** supabase-js-style client over one acquired pg client: `.from(t)` + `.rpc(fn, args)`. */
+export class PgGatewayClient {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    query(text, values) { return this.client.query(text, values); }
+    from(table) {
+        return new PgQueryBuilder(this.client, table);
+    }
+    async rpc(functionName, args = {}) {
+        try {
+            const name = quoteIdent(functionName);
+            const params = new ParamAccumulator();
+            // Named-arg invocation: every existing RPC uses `p_*` named params. `name => $n` binds by name
+            // so arg order is irrelevant and values are fully parameterized.
+            const namedArgs = Object.keys(args)
+                .map((key) => `${quoteIdent(key)} => ${params.add(args[key])}`)
+                .join(", ");
+            const text = `SELECT * FROM ${name}(${namedArgs})`;
+            const { rows } = await this.client.query(text, params.values);
+            // RPCs returning a scalar set-returning function expose the value under the function name;
+            // a single-column single-row result unwraps to that value (matches supabase-js rpc shape).
+            return { data: unwrapRpcRows(rows, functionName), error: null };
+        }
+        catch (error) {
+            return { data: null, error: toShimError(error) };
+        }
+    }
+}

package/dist/data/queryBuilderSql.d.ts

@@ -0,0 +1,76 @@
+/** PostgREST-shaped error the consumers narrow on (`.code`, `.message`, `.details`, `.hint`). */
+export interface PgShimError {
+    code?: string;
+    message?: string;
+    details?: string;
+    hint?: string;
+}
+export interface PgShimResult<T = unknown> {
+    data: T;
+    error: PgShimError | null;
+    count?: number | null;
+}
+/** Minimal query surface we need from a pg client (Pool acquires a PoolClient per request). */
+export interface PgQueryExecutor {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: Record<string, unknown>[];
+    }>;
+}
+export type Filter = {
+    kind: "eq" | "gte" | "lte" | "gt";
+    column: string;
+    value: unknown;
+} | {
+    kind: "in";
+    column: string;
+    values: unknown[];
+} | {
+    kind: "ilike";
+    column: string;
+    value: string;
+} | {
+    kind: "is";
+    column: string;
+    value: unknown;
+};
+export interface OrderBy {
+    column: string;
+    ascending: boolean;
+}
+export declare function quoteIdent(raw: string): string;
+export declare function renderColumns(columns: string): string;
+export declare function renderFilter(filter: Filter, params: ParamAccumulator): string;
+/**
+ * PostgREST `count=exact` rendered as a SEPARATE aggregate over the same FROM/WHERE — deliberately
+ * NOT a `COUNT(*) OVER()` folded into the row query. PostgREST's exact count ignores limit/offset,
+ * and a window function emits no row at all for an empty page, so an offset past the end would
+ * report 0 instead of the true total. Keeping it separate also leaves the row projection
+ * byte-identical: there is no synthetic column to strip before cardinality shaping.
+ */
+export declare function renderCountQuery(table: string, filters: readonly Filter[], params: ParamAccumulator): string;
+/**
+ * PostgREST refuses an out-of-bounds page instead of answering an empty one -- but ONLY when it
+ * knows the total, i.e. when an exact count was requested; without one it answers 200 and `[]`,
+ * which is what this shim already did. The boundary is strict: offset === total is a legal empty
+ * page, offset === total + 1 is not. Measured against PostgREST 14.10 before this was written,
+ * including the `details` sentence, which carries the two numbers a caller pages on.
+ */
+export declare function rangeNotSatisfiable(offset: number | null, total: number | null): PgShimError | null;
+/**
+ * INSERT ... VALUES ... RETURNING, with the column list taken from the FIRST row and every later
+ * row required to carry the same key set. Deriving the columns from row 0 alone and binding the
+ * rest positionally is how a batch used to lose a column silently: an extra key vanished, a missing
+ * one bound NULL over a DEFAULT. PostgREST answers PGRST102 "All object keys must match" to exactly
+ * this payload -- and keeps answering it under `Prefer: missing=default`, measured -- so the shim
+ * refuses too. Refusal, not union: parity is the point, and this builder exposes no Prefer header
+ * through which a caller could ask for anything else.
+ */
+export declare function renderInsertStatement(table: string, rows: readonly Record<string, unknown>[], projection: string, params: ParamAccumulator): string;
+export declare function unwrapRpcRows(rows: Record<string, unknown>[], functionName: string): unknown;
+/** Accumulates values and hands back $1,$2,… placeholders — the single injection-safety chokepoint. */
+export declare class ParamAccumulator {
+    readonly values: unknown[];
+    add(value: unknown): string;
+}
+export declare function joinParts(parts: string[]): string;
+export declare function toShimError(error: unknown): PgShimError;

package/dist/data/queryBuilderSql.js

@@ -0,0 +1,145 @@
+// Vanilla-Postgres query-builder SQL primitives.
+//
+// Extracted from queryBuilder.ts (300-LOC cap) — the pure, stateless SQL-fragment layer the builder
+// composes: result/error shapes, the injection-safety chokepoint (ParamAccumulator), identifier
+// quoting (allowlist), column projection, and filter rendering. VALUES ARE NEVER string-interpolated;
+// they flow through ParamAccumulator as $N placeholders. Identifiers (table/column names) are validated
+// against a strict allowlist regex and double-quoted, so they cannot smuggle SQL either.
+// Identifiers (table + column names) are NEVER parameterizable in SQL, so they are validated against
+// a strict allowlist and quoted. Consumers only ever pass static, code-literal identifiers; this
+// guard turns any attempt to pass a crafted identifier into a thrown error rather than injected SQL.
+const IDENTIFIER_RE = /^[a-z_][a-z0-9_]*$/i;
+export function quoteIdent(raw) {
+    if (!IDENTIFIER_RE.test(raw)) {
+        throw new Error(`pg-shim: unsafe identifier ${JSON.stringify(raw)}`);
+    }
+    return `"${raw}"`;
+}
+// `select("a, b")` etc. — a comma list of identifiers or "*". Each segment is validated; "*" passes
+// through. PostgREST embedding syntax (foo(bar)) is NOT used by any consumer, so it is rejected
+// (fail-closed) rather than silently mistranslated.
+export function renderColumns(columns) {
+    const trimmed = columns.trim();
+    if (trimmed === "" || trimmed === "*")
+        return "*";
+    return trimmed
+        .split(",")
+        .map((c) => c.trim())
+        .map((c) => (c === "*" ? "*" : quoteIdent(c)))
+        .join(", ");
+}
+export function renderFilter(filter, params) {
+    const col = quoteIdent(filter.column);
+    switch (filter.kind) {
+        case "eq":
+            return `${col} = ${params.add(filter.value)}`;
+        case "gt":
+            return `${col} > ${params.add(filter.value)}`;
+        case "gte":
+            return `${col} >= ${params.add(filter.value)}`;
+        case "lte":
+            return `${col} <= ${params.add(filter.value)}`;
+        case "ilike":
+            return `${col} ILIKE ${params.add(filter.value)}`;
+        case "in": {
+            // Empty IN () is invalid SQL; PostgREST treats `.in([])` as matching nothing.
+            if (filter.values.length === 0)
+                return "false";
+            const placeholders = filter.values.map((v) => params.add(v)).join(", ");
+            return `${col} IN (${placeholders})`;
+        }
+        case "is":
+            // .is(col, null) → IS NULL; .is(col, true/false) → IS TRUE/FALSE. Value is a literal keyword,
+            // not user data (consumers only pass null/true/false), so it is rendered, not parameterized.
+            if (filter.value === null)
+                return `${col} IS NULL`;
+            if (filter.value === true)
+                return `${col} IS TRUE`;
+            if (filter.value === false)
+                return `${col} IS FALSE`;
+            throw new Error("pg-shim: .is() only supports null/true/false");
+    }
+}
+/**
+ * PostgREST `count=exact` rendered as a SEPARATE aggregate over the same FROM/WHERE — deliberately
+ * NOT a `COUNT(*) OVER()` folded into the row query. PostgREST's exact count ignores limit/offset,
+ * and a window function emits no row at all for an empty page, so an offset past the end would
+ * report 0 instead of the true total. Keeping it separate also leaves the row projection
+ * byte-identical: there is no synthetic column to strip before cardinality shaping.
+ */
+export function renderCountQuery(table, filters, params) {
+    const where = filters.length === 0
+        ? ""
+        : `WHERE ${filters.map((filter) => renderFilter(filter, params)).join(" AND ")}`;
+    return joinParts([`SELECT count(*) AS exact_count FROM ${quoteIdent(table)}`, where]);
+}
+/**
+ * PostgREST refuses an out-of-bounds page instead of answering an empty one -- but ONLY when it
+ * knows the total, i.e. when an exact count was requested; without one it answers 200 and `[]`,
+ * which is what this shim already did. The boundary is strict: offset === total is a legal empty
+ * page, offset === total + 1 is not. Measured against PostgREST 14.10 before this was written,
+ * including the `details` sentence, which carries the two numbers a caller pages on.
+ */
+export function rangeNotSatisfiable(offset, total) {
+    if (offset === null || total === null || offset <= total)
+        return null;
+    return {
+        code: "PGRST103",
+        message: "Requested range not satisfiable",
+        details: `An offset of ${offset} was requested, but there are only ${total} rows.`,
+    };
+}
+/**
+ * INSERT ... VALUES ... RETURNING, with the column list taken from the FIRST row and every later
+ * row required to carry the same key set. Deriving the columns from row 0 alone and binding the
+ * rest positionally is how a batch used to lose a column silently: an extra key vanished, a missing
+ * one bound NULL over a DEFAULT. PostgREST answers PGRST102 "All object keys must match" to exactly
+ * this payload -- and keeps answering it under `Prefer: missing=default`, measured -- so the shim
+ * refuses too. Refusal, not union: parity is the point, and this builder exposes no Prefer header
+ * through which a caller could ask for anything else.
+ */
+export function renderInsertStatement(table, rows, projection, params) {
+    if (rows.length === 0)
+        throw new Error("pg-shim: insert requires at least one row");
+    const columns = Object.keys(rows[0]);
+    const signature = [...columns].sort().join("\u0000");
+    for (const row of rows) {
+        if ([...Object.keys(row)].sort().join("\u0000") !== signature) {
+            throw Object.assign(new Error("All object keys must match"), { code: "PGRST102" });
+        }
+    }
+    const tuples = rows.map((row) => `(${columns.map((column) => params.add(row[column])).join(", ")})`).join(", ");
+    return `INSERT INTO ${quoteIdent(table)} (${columns.map(quoteIdent).join(", ")}) VALUES ${tuples} `
+        + `RETURNING ${renderColumns(projection)}`;
+}
+// supabase-js rpc() returns the function's return value directly: a scalar/json function yields that
+// value; a TABLE/SETOF function yields the row array. Heuristic mirrors that: 1 row × 1 column whose
+// name equals the function → the scalar; otherwise the rows array (TABLE-returning).
+export function unwrapRpcRows(rows, functionName) {
+    if (rows.length === 1) {
+        const keys = Object.keys(rows[0]);
+        if (keys.length === 1 && keys[0] === functionName)
+            return rows[0][functionName];
+    }
+    return rows;
+}
+/** Accumulates values and hands back $1,$2,… placeholders — the single injection-safety chokepoint. */
+export class ParamAccumulator {
+    values = [];
+    add(value) {
+        this.values.push(value);
+        return `$${this.values.length}`;
+    }
+}
+export function joinParts(parts) {
+    return parts.filter((p) => p.trim() !== "").join(" ");
+}
+export function toShimError(error) {
+    const e = error;
+    return {
+        code: e?.code,
+        message: e?.message ?? "query failed",
+        details: e?.detail,
+        hint: e?.hint,
+    };
+}