@openlup/platform 0.0.0 → 0.16.0

package/dist/data/binding.js

@@ -0,0 +1,92 @@
+// DataGatewayPort bindings for bundle composition.
+//
+// Maps a bundle's declared `data` capability to a concrete DataGatewayPort. The supabase gateway is
+// constructed eagerly (pure factory; no client/network until a port method runs work), so the
+// default vercel-supabase path binds the slot with no secrets needed: env is read with
+// empty-string fallbacks and validated lazily inside asActor/asService. The application supplies
+// the supabase-js `createClient` once, when it creates its bindings.
+//
+// The `postgres` capability (node-postgres) uses the existing direct-PG DataGatewayPort. Its
+// PgGatewayClient exposes the same narrow RPC surface used by Supabase-backed domain ports.
+import { getBundleDescriptor, resolveBundleId, } from "../kernel/index.js";
+import { createSupabaseDataGateway } from "./supabaseGateway.js";
+import { createPostgresDataGateway, resolvePostgresDataGatewayEnv, } from "./postgresGateway.js";
+/** Create one set of data bindings; the bundle data port cache belongs to this set. */
+export function createDataBindings(deps) {
+    let cachedBundleDataPort = null;
+    const createPostgresGateway = deps.createPostgresGateway ?? ((env) => createPostgresDataGateway(env));
+    /** Resolve the DataGatewayPort for a bundle's declared data capability kind. */
+    function bindDataPort(dataKind, env, requestOptions = {}) {
+        switch (dataKind) {
+            case "supabase":
+                // Construct from env with empty-string fallbacks; the actual supabase client is created
+                // lazily when asActor/asService runs work, so the slot binds even before secrets are present
+                // (same as the blob/transactional/analytics slots — keeps composeBundle({}) non-null).
+                return createSupabaseDataGateway({
+                    url: env.SUPABASE_URL ?? env.VITE_SUPABASE_URL ?? "",
+                    anonKey: env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+                        env.VITE_SUPABASE_ANON_KEY ??
+                        env.SUPABASE_ANON_KEY ??
+                        "",
+                    serviceRoleKey: env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+                }, { ...requestOptions, createClientImpl: requestOptions.createClientImpl ?? deps.createSupabaseClient });
+            case "postgres":
+                // Direct-PG gateway (pg.Pool, tx-per-request RLS via SET LOCAL). Pure factory — no pool
+                // until asActor/asService runs work, so the slot binds even before DATABASE_URL is present
+                // (matches the supabase case's lazy null-is-no-op convention; keeps composeBundle non-null).
+                return createPostgresGateway(resolvePostgresDataGatewayEnv(env));
+            default:
+                return null;
+        }
+    }
+    /**
+     * Bind one request to actor-only data access.
+     *
+     * HTTP-backed bundles receive a fresh gateway so the raw bearer resolver cannot
+     * cross request boundaries. The direct database bundle reuses the existing
+     * cached port (and therefore its lazy pool); only this actor-only facade is new.
+     */
+    function bindRequestActorDataPort(accessToken, env, requestOptions = {}) {
+        const bundleId = resolveBundleId(env);
+        const dataKind = getBundleDescriptor(bundleId).capabilities.data;
+        const port = dataKind === "postgres"
+            ? bindBundleDataPort(env)
+            : bindDataPort(dataKind, env, {
+                ...requestOptions,
+                resolveAccessToken: () => accessToken,
+            });
+        if (!port)
+            return null;
+        return {
+            asActor: (claims, work) => port.asActor(claims, work),
+        };
+    }
+    /** Resolve and bind the active bundle's data gateway without composing the whole runtime. */
+    function bindBundleDataPort(env) {
+        const bundleId = resolveBundleId(env);
+        const descriptor = getBundleDescriptor(bundleId);
+        const cacheKey = bundleDataPortCacheKey(bundleId, descriptor.capabilities.data, env);
+        if (cachedBundleDataPort?.cacheKey === cacheKey) {
+            return cachedBundleDataPort.port;
+        }
+        const port = bindDataPort(descriptor.capabilities.data, env);
+        cachedBundleDataPort = { cacheKey, port };
+        return port;
+    }
+    return { bindDataPort, bindRequestActorDataPort, bindBundleDataPort };
+}
+function bundleDataPortCacheKey(bundleId, dataKind, env) {
+    const dataConfig = dataKind === "postgres"
+        ? [env.DATABASE_URL ?? ""]
+        : dataKind === "supabase"
+            ? [
+                env.SUPABASE_URL ?? env.VITE_SUPABASE_URL ?? "",
+                env.VITE_SUPABASE_PUBLISHABLE_KEY ??
+                    env.VITE_SUPABASE_ANON_KEY ??
+                    env.SUPABASE_ANON_KEY ??
+                    "",
+                env.SUPABASE_SERVICE_ROLE_KEY ?? "",
+            ]
+            : [];
+    return JSON.stringify([bundleId, dataKind, ...dataConfig]);
+}

package/dist/data/index.d.ts

@@ -0,0 +1,5 @@
+export { createPostgresDataGateway, createPostgresGatewayTypeOverrides, createPostgresRoleFreeTransactionLane, postgresTimestampTzToRfc3339, resolvePostgresDataGatewayEnv, type PostgresDataGatewayEnv, type PostgresDataGatewayOptions, type PostgresRoleFreeTransactionLane, } from "./postgresGateway.js";
+export { PgGatewayClient, PgQueryBuilder, type PgQueryExecutor, type PgShimError, type PgShimResult, } from "./queryBuilder.js";
+export { createActorClient, createServiceClient, readSupabaseActorDataGatewayEnv, readSupabaseDataGatewayEnv, type SupabaseCreateClient, type SupabaseDataGatewayEnv, } from "./supabaseClientFactory.js";
+export { createSupabaseDataGateway, type SupabaseDataGatewayOptions } from "./supabaseGateway.js";
+export { createDataBindings, type ActorOnlyDataPort, type DataBindingDependencies, type DataBindings, type DataPortBindingOptions, } from "./binding.js";

package/dist/data/index.js

@@ -0,0 +1,5 @@
+export { createPostgresDataGateway, createPostgresGatewayTypeOverrides, createPostgresRoleFreeTransactionLane, postgresTimestampTzToRfc3339, resolvePostgresDataGatewayEnv, } from "./postgresGateway.js";
+export { PgGatewayClient, PgQueryBuilder, } from "./queryBuilder.js";
+export { createActorClient, createServiceClient, readSupabaseActorDataGatewayEnv, readSupabaseDataGatewayEnv, } from "./supabaseClientFactory.js";
+export { createSupabaseDataGateway } from "./supabaseGateway.js";
+export { createDataBindings, } from "./binding.js";

package/dist/data/postgresGateway.d.ts

@@ -0,0 +1,42 @@
+import type { Pool } from "pg";
+import type { DataGatewayPort } from "@openlup/core/platform-runtime";
+export interface PostgresDataGatewayEnv {
+    /** Postgres connection string (DATABASE_URL). Empty until a node-postgres deploy supplies it. */
+    connectionString: string;
+}
+export interface PostgresDataGatewayOptions {
+    /** Injection seam: tests pass a stub pool; production lazily builds a real pg.Pool from env. */
+    poolFactory?: (env: PostgresDataGatewayEnv) => Pool | Promise<Pool>;
+}
+/** Convert node-postgres timestamptz text to lossless RFC 3339. */
+export declare function postgresTimestampTzToRfc3339(value: string): string;
+/** Keep PostgREST-compatible, lossless timestamp strings at the gateway edge. */
+export declare function createPostgresGatewayTypeOverrides(TypeOverridesCtor: typeof import("pg").TypeOverrides): import("pg").TypeOverrides;
+/**
+ * Capability-local, role-free transaction lane.
+ *
+ * The platform manifest intentionally creates no service role. This is not an
+ * alternate DataGatewayPort access mode: a deployment hands one lane to exactly
+ * one adapter that calls its own rail RPCs, and names that lane after the
+ * capability, because the name is the access rule. Its lifecycle reuses the same
+ * pooled BEGIN/callback/COMMIT|ROLLBACK/release implementation as the public
+ * gateway below, but it never changes the connection role.
+ */
+export interface PostgresRoleFreeTransactionLane {
+    run<T>(work: (gateway: unknown) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+}
+/**
+ * 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 declare function createPostgresDataGateway(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): DataGatewayPort;
+/**
+ * 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 declare function createPostgresRoleFreeTransactionLane(env: PostgresDataGatewayEnv, options?: PostgresDataGatewayOptions): PostgresRoleFreeTransactionLane;
+/** Resolve the gateway env from process env (DATABASE_URL), mirroring the supabase binding shape. */
+export declare function resolvePostgresDataGatewayEnv(env: Record<string, string | undefined>): PostgresDataGatewayEnv;

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;