cloudflare-next-intl 0.7.7 → 0.8.0

package/dist/src/db/context.js

@@ -0,0 +1,125 @@
+import config from '../config/intl_config';
+import requireDbConfig from './require_config';
+import connectToPostgres, { disconnectPostgres } from './connection';
+import resolveDbMode from './resolve_mode';
+import resolveSupabaseEndpoint from './supabase_config';
+import createSupabaseTransport from './supabase_transport';
+import resolveAccessToken from './access_token';
+const DEFAULT_ROLE = 'authenticated';
+/**
+ * Resolves the user id for `withUserDb`, trying, in order: the explicit `uid`
+ * argument, `db.getUserId()`, then the signed-in Firebase user.
+ */
+async function resolveUserId(uid) {
+    if (uid)
+        return uid;
+    const db = config.db;
+    requireDbConfig(db);
+    const fromConfig = await db.getUserId?.();
+    if (fromConfig)
+        return fromConfig;
+    if (config.firebaseAuth) {
+        const { getAuthUser } = await import('../firebase_auth/server/use_auth_user_server');
+        const { user } = await getAuthUser();
+        if (user?.uid)
+            return user.uid;
+    }
+    throw new Error('db: withUserDb could not resolve a user id. Pass one explicitly, set ' +
+        '`db.getUserId`, or configure `firebaseAuth` so the signed-in Firebase uid is used.');
+}
+/**
+ * Builds a Drizzle handle backed by PostgREST. `bearerToken` decides the role
+ * Postgres sees: the anon key for public access, a user JWT for `withUserDb`.
+ */
+async function supabaseDb(supabase, bearerToken) {
+    const { drizzle } = await import('drizzle-orm/pg-proxy');
+    return drizzle(createSupabaseTransport(supabase, bearerToken));
+}
+/**
+ * Runs a query as the **anonymous** role: no transaction, no role switch, no
+ * user identity attached. Use this for data any visitor may read.
+ *
+ * Because no user id is set, RLS policies that test `auth.jwt()->>'sub'` see
+ * no user and will deny access — reach for {@link withUserDb} whenever the
+ * rows depend on who is asking.
+ *
+ * In connection-string mode the connection is taken from the request's
+ * shared client and released when `fn` settles, even if it throws. In
+ * Supabase mode there is no connection to release — each call is one
+ * PostgREST round-trip authenticated as the anon key.
+ *
+ * @param fn Receives the Drizzle handle; return whatever the caller needs.
+ * @returns Whatever `fn` resolves to.
+ * @throws If `db` is not set on your `RoutingConfig`, or the connection fails.
+ *
+ * @example
+ * const rows = await withPublicDb((db) => db.select().from(bonds).limit(10));
+ */
+export async function withPublicDb(fn) {
+    const db = config.db;
+    requireDbConfig(db);
+    if (resolveDbMode(db) === 'supabase') {
+        const supabase = db.supabase;
+        const { anonKey } = resolveSupabaseEndpoint(supabase);
+        return fn(await supabaseDb(supabase, anonKey));
+    }
+    const client = await connectToPostgres(config);
+    try {
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        return await fn(drizzle(client));
+    }
+    finally {
+        disconnectPostgres(config);
+    }
+}
+/**
+ * Runs a query as the **signed-in user**.
+ *
+ * In connection-string mode this runs inside a transaction where Postgres
+ * sees the resolved user id as `auth.jwt()->>'sub'` under
+ * `db.authenticatedRole`, so RLS policies behave exactly as they do for a
+ * PostgREST-issued call. In Supabase mode identity instead rides on the JWT
+ * sent as `Authorization: Bearer` — PostgREST resolves the `authenticated`
+ * role and populates `request.jwt.claims` itself, and each statement is its
+ * own round-trip with no cross-statement transaction (the Postgres proxy
+ * Drizzle uses in this mode cannot open one). Either way this is the wrapper
+ * to use for anything user-owned.
+ *
+ * @param fn Receives the Drizzle handle. In connection-string mode it is
+ * bound to a transaction; in Supabase mode it is not — do not rely on
+ * multi-statement atomicity there.
+ * @param uid Connection-string mode only: overrides the user id. Omit it in
+ * normal use — the id then comes from `db.getUserId()` when set, otherwise
+ * from the signed-in Firebase user when `firebaseAuth` is configured.
+ * Ignored in Supabase mode, which resolves identity via `db.getAccessToken`/
+ * Firebase instead — see {@link resolveAccessToken}.
+ * @returns Whatever `fn` resolves to.
+ * @throws If `db` is not set on your `RoutingConfig`, if no user id/access
+ * token can be resolved, or the connection fails.
+ *
+ * @example
+ * const mine = await withUserDb((db) => db.select().from(orders));
+ */
+export async function withUserDb(fn, uid) {
+    const db = config.db;
+    requireDbConfig(db);
+    if (resolveDbMode(db) === 'supabase') {
+        const token = await resolveAccessToken(config);
+        return fn(await supabaseDb(db.supabase, token));
+    }
+    const userId = await resolveUserId(uid);
+    const client = await connectToPostgres(config);
+    const role = db.authenticatedRole ?? DEFAULT_ROLE;
+    try {
+        const { drizzle } = await import('drizzle-orm/node-postgres');
+        const { sql } = await import('drizzle-orm');
+        return await drizzle(client).transaction(async (transaction) => {
+            await transaction.execute(sql `select set_config('request.jwt.claims', ${JSON.stringify({ sub: userId })}, true)`);
+            await transaction.execute(sql `set local role ${sql.raw(role)}`);
+            return fn(transaction);
+        });
+    }
+    finally {
+        disconnectPostgres(config);
+    }
+}

package/dist/src/db/helpers.d.ts

@@ -0,0 +1,57 @@
+import { type SQL, type Table } from 'drizzle-orm';
+/**
+ * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
+ *
+ * Restricts property access at compile time to valid table schema keys (camelCase),
+ * and validates at runtime by throwing a descriptive error if an unknown property is accessed.
+ *
+ * @example
+ * set: {
+ *   inflation: excluded(inflation).inflation,
+ *   yearInflation: excluded(inflation).yearInflation,
+ *   updatedAt: sql`now()`,
+ * }
+ */
+export declare function excluded<T extends Table>(table: T): {
+    [K in keyof T["_"]["columns"]]: SQL;
+};
+/**
+ * Builds a runtime and compile-time validated `set` object for `onConflictDoUpdate`.
+ *
+ * Only permits valid column keys of the target table. Automatically maps
+ * property keys to database column names and appends `updatedAt: sql\`now()\``
+ * if the column exists on the table.
+ *
+ * @example
+ * .onConflictDoUpdate({
+ *   target: inflation.date,
+ *   set: onConflictSet(inflation, ["inflation", "yearInflation"]),
+ * })
+ */
+export declare function onConflictSet<T extends Table, K extends keyof T["_"]["columns"]>(table: T, fields: K[]): Record<string, SQL>;
+export type TimeUnit = "days" | "hours" | "minutes" | "months" | "years" | "weeks";
+/** General SQL helper generating a timestamp expression relative to now (`now() - (N unit)::interval`). */
+export declare function ago(amount: number, unit: TimeUnit): SQL;
+/** General SQL helper returning `current_date`. */
+export declare function currentDate(): SQL;
+/** General SQL helper for window function `count(*) over ()`. */
+export declare function windowCount(): SQL<number>;
+/** Helper generating `lateral unnest(...) as alias(alias)`. */
+export declare function unnestLateral(column: unknown, alias: string): SQL;
+/** Helper generating `column asc nulls last`. */
+export declare function ascNullsLast(column: unknown): SQL;
+/** General SQL literal `true`, for lateral joins and empty predicate lists. */
+export declare function alwaysTrue(): SQL;
+/** Wraps an expression as `lateral (<inner>) <alias>`. */
+export declare function lateral(inner: SQL, alias: string): SQL;
+/** References `<alias>.<column>` of a derived table / lateral subquery. */
+export declare function aliasColumn<T = unknown>(alias: string, column: string): SQL<T>;
+/** General aggregate helpers over an arbitrary expression. */
+export declare function minOf<T = unknown>(expression: unknown): SQL<T>;
+export declare function maxOf<T = unknown>(expression: unknown): SQL<T>;
+/** Rounds an expression to `digits` decimals, returning `real`. */
+export declare function roundReal(expression: unknown, digits: number): SQL<number>;
+/** Multiplies an expression by a factor. */
+export declare function multiply(expression: unknown, factor: number): SQL<number>;
+/** Wraps an expression as a scalar subquery over a named CTE: `(select <expr> from <cte>)`. */
+export declare function scalarFromCte<T = unknown>(cte: string, expression: unknown): SQL<T>;

package/dist/src/db/helpers.js

@@ -0,0 +1,112 @@
+import { getTableColumns, getTableName, sql } from 'drizzle-orm';
+/**
+ * Type-safe helper returning `excluded.<db_column_name>` SQL expressions for a Drizzle table.
+ *
+ * Restricts property access at compile time to valid table schema keys (camelCase),
+ * and validates at runtime by throwing a descriptive error if an unknown property is accessed.
+ *
+ * @example
+ * set: {
+ *   inflation: excluded(inflation).inflation,
+ *   yearInflation: excluded(inflation).yearInflation,
+ *   updatedAt: sql`now()`,
+ * }
+ */
+export function excluded(table) {
+    const cols = getTableColumns(table);
+    const tableName = getTableName(table);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return new Proxy({}, {
+        get(_, prop) {
+            const col = cols[prop];
+            if (!col) {
+                throw new Error(`[Drizzle Error] Column "${prop}" does not exist on table "${tableName}". ` +
+                    `Valid columns: ${Object.keys(cols).join(", ")}`);
+            }
+            return sql.raw(`excluded.${col.name}`);
+        },
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+}
+/**
+ * Builds a runtime and compile-time validated `set` object for `onConflictDoUpdate`.
+ *
+ * Only permits valid column keys of the target table. Automatically maps
+ * property keys to database column names and appends `updatedAt: sql\`now()\``
+ * if the column exists on the table.
+ *
+ * @example
+ * .onConflictDoUpdate({
+ *   target: inflation.date,
+ *   set: onConflictSet(inflation, ["inflation", "yearInflation"]),
+ * })
+ */
+export function onConflictSet(table, fields) {
+    const cols = getTableColumns(table);
+    const tableName = getTableName(table);
+    const setObj = {};
+    for (const field of fields) {
+        const key = String(field);
+        const col = cols[key];
+        if (!col) {
+            throw new Error(`[Drizzle Error] Column "${key}" does not exist on table "${tableName}". ` +
+                `Valid columns: ${Object.keys(cols).join(", ")}`);
+        }
+        setObj[key] = sql.raw(`excluded.${col.name}`);
+    }
+    if ("updatedAt" in cols) {
+        setObj.updatedAt = sql `now()`;
+    }
+    return setObj;
+}
+/** General SQL helper generating a timestamp expression relative to now (`now() - (N unit)::interval`). */
+export function ago(amount, unit) {
+    return sql `now() - (${amount} || ' ' || ${unit})::interval`;
+}
+/** General SQL helper returning `current_date`. */
+export function currentDate() {
+    return sql `current_date`;
+}
+/** General SQL helper for window function `count(*) over ()`. */
+export function windowCount() {
+    return sql `count(*) over ()`.mapWith(Number);
+}
+/** Helper generating `lateral unnest(...) as alias(alias)`. */
+export function unnestLateral(column, alias) {
+    return sql `lateral unnest(${column}) as ${sql.raw(alias)}(${sql.raw(alias)})`;
+}
+/** Helper generating `column asc nulls last`. */
+export function ascNullsLast(column) {
+    return sql `${column} asc nulls last`;
+}
+/** General SQL literal `true`, for lateral joins and empty predicate lists. */
+export function alwaysTrue() {
+    return sql `true`;
+}
+/** Wraps an expression as `lateral (<inner>) <alias>`. */
+export function lateral(inner, alias) {
+    return sql `lateral (${inner}) ${sql.raw(alias)}`;
+}
+/** References `<alias>.<column>` of a derived table / lateral subquery. */
+export function aliasColumn(alias, column) {
+    return sql.raw(`${alias}.${column}`);
+}
+/** General aggregate helpers over an arbitrary expression. */
+export function minOf(expression) {
+    return sql `min(${expression})`;
+}
+export function maxOf(expression) {
+    return sql `max(${expression})`;
+}
+/** Rounds an expression to `digits` decimals, returning `real`. */
+export function roundReal(expression, digits) {
+    return sql `round((${expression})::numeric, ${digits})::real`;
+}
+/** Multiplies an expression by a factor. */
+export function multiply(expression, factor) {
+    return sql `${expression} * ${factor}`;
+}
+/** Wraps an expression as a scalar subquery over a named CTE: `(select <expr> from <cte>)`. */
+export function scalarFromCte(cte, expression) {
+    return sql `(select ${expression} from ${sql.raw(cte)})`;
+}

package/dist/src/db/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Optional Postgres/Drizzle data-access layer, reached from
+ * `cloudflare-next-intl/db`. Enable it by setting `db` on your `RoutingConfig`;
+ * every export here throws a descriptive error if that config is missing.
+ *
+ * Pick a wrapper by who is allowed to see the rows:
+ * - {@link withPublicDb} — anonymous role, for data any visitor may read.
+ * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
+ *
+ * Two transports reach Postgres behind that same Drizzle query API, chosen by
+ * `resolveDbMode` from which `db` config fields are set: `connectionString`/
+ * `hyperdriveBinding` for a direct connection (wins if both are configured),
+ * or `supabase` for the Supabase Data API when only a project URL and anon
+ * key are available. `pg`, `drizzle-orm`, and `@supabase/supabase-js` all
+ * load through dynamic `import()` inside these functions, so an app that
+ * never calls a `db` export never bundles any of them.
+ *
+ * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
+ * the separate `cloudflare-next-intl/dbHelpers` entry point.
+ */
+export { withPublicDb, withUserDb } from './context';
+export type { DrizzleDb } from './context';
+export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';
+export type { DbRoutingConfig } from '../types/types';

package/dist/src/db/index.js

@@ -0,0 +1,22 @@
+/**
+ * Optional Postgres/Drizzle data-access layer, reached from
+ * `cloudflare-next-intl/db`. Enable it by setting `db` on your `RoutingConfig`;
+ * every export here throws a descriptive error if that config is missing.
+ *
+ * Pick a wrapper by who is allowed to see the rows:
+ * - {@link withPublicDb} — anonymous role, for data any visitor may read.
+ * - {@link withUserDb} — the signed-in user, with RLS applied to their id.
+ *
+ * Two transports reach Postgres behind that same Drizzle query API, chosen by
+ * `resolveDbMode` from which `db` config fields are set: `connectionString`/
+ * `hyperdriveBinding` for a direct connection (wins if both are configured),
+ * or `supabase` for the Supabase Data API when only a project URL and anon
+ * key are available. `pg`, `drizzle-orm`, and `@supabase/supabase-js` all
+ * load through dynamic `import()` inside these functions, so an app that
+ * never calls a `db` export never bundles any of them.
+ *
+ * Generic Drizzle SQL helpers (`excluded`, `onConflictSet`, `ago`, …) live in
+ * the separate `cloudflare-next-intl/dbHelpers` entry point.
+ */
+export { withPublicDb, withUserDb } from './context';
+export { default as connectToPostgres, disconnectPostgres, resetConnectionState } from './connection';

package/dist/src/db/require_config.d.ts

@@ -0,0 +1,15 @@
+import type { DbRoutingConfig } from '../types/types';
+/**
+ * Asserts that the optional `db` config is present, narrowing it from
+ * `DbRoutingConfig | undefined` to `DbRoutingConfig` for the rest of the
+ * caller's scope.
+ *
+ * Every `db` export calls this before touching `pg`/`drizzle-orm`. It throws
+ * rather than silently no-op'ing, so a consumer who calls e.g. `withPublicDb()`
+ * without setting `db` on their `RoutingConfig` gets an immediate, actionable
+ * error instead of a confusing failed query.
+ *
+ * @param db The `db` field off your routing config.
+ * @throws If `db` is undefined.
+ */
+export default function requireDbConfig(db: DbRoutingConfig | undefined): asserts db is DbRoutingConfig;

package/dist/src/db/require_config.js

@@ -0,0 +1,20 @@
+/**
+ * Asserts that the optional `db` config is present, narrowing it from
+ * `DbRoutingConfig | undefined` to `DbRoutingConfig` for the rest of the
+ * caller's scope.
+ *
+ * Every `db` export calls this before touching `pg`/`drizzle-orm`. It throws
+ * rather than silently no-op'ing, so a consumer who calls e.g. `withPublicDb()`
+ * without setting `db` on their `RoutingConfig` gets an immediate, actionable
+ * error instead of a confusing failed query.
+ *
+ * @param db The `db` field off your routing config.
+ * @throws If `db` is undefined.
+ */
+export default function requireDbConfig(db) {
+    if (!db) {
+        throw new Error('db: `db` is not set on your RoutingConfig. Add a `db` object ' +
+            '(connectionString or hyperdriveBinding) to the config passed to ' +
+            '`setIntlConfig` before using any db export.');
+    }
+}

package/dist/src/db/resolve_mode.d.ts

@@ -0,0 +1,17 @@
+import type { DbRoutingConfig } from '../types/types';
+/** Which transport the `db` exports use for a given config. */
+export type DbMode = 'postgres' | 'supabase';
+/**
+ * Decides how to reach the database from the shape of the `db` config.
+ *
+ * Direct Postgres wins whenever it is configured, so adding a `supabase`
+ * block to an existing config never silently reroutes live traffic. With
+ * neither set the result is still `'postgres'`, which lets
+ * `connectToPostgres` raise its existing, more specific error about the
+ * missing Hyperdrive binding.
+ *
+ * @param db The `db` field off your routing config.
+ * @returns `'postgres'` for connection-string/Hyperdrive access, `'supabase'`
+ * for PostgREST access.
+ */
+export default function resolveDbMode(db: DbRoutingConfig): DbMode;

package/dist/src/db/resolve_mode.js

@@ -0,0 +1,18 @@
+/**
+ * Decides how to reach the database from the shape of the `db` config.
+ *
+ * Direct Postgres wins whenever it is configured, so adding a `supabase`
+ * block to an existing config never silently reroutes live traffic. With
+ * neither set the result is still `'postgres'`, which lets
+ * `connectToPostgres` raise its existing, more specific error about the
+ * missing Hyperdrive binding.
+ *
+ * @param db The `db` field off your routing config.
+ * @returns `'postgres'` for connection-string/Hyperdrive access, `'supabase'`
+ * for PostgREST access.
+ */
+export default function resolveDbMode(db) {
+    if (db.connectionString || db.hyperdriveBinding)
+        return 'postgres';
+    return db.supabase ? 'supabase' : 'postgres';
+}

package/dist/src/db/supabase_config.d.ts

@@ -0,0 +1,18 @@
+import type { SupabaseDbConfig } from '../types/types';
+/** The Supabase project URL and anon key the transport builds a client from. */
+export interface ResolvedSupabaseEndpoint {
+    /** Project URL, trailing slashes stripped. */
+    url: string;
+    /** Anon key, sent as both `apikey` and the public-mode bearer token. */
+    anonKey: string;
+}
+/**
+ * Resolves the Supabase project URL and anon key, preferring explicit config
+ * over the `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`
+ * environment variables.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @returns The project URL and anon key to build a Supabase client from.
+ * @throws If neither config nor environment supplies a URL or an anon key.
+ */
+export default function resolveSupabaseEndpoint(supabase: SupabaseDbConfig): ResolvedSupabaseEndpoint;

package/dist/src/db/supabase_config.js

@@ -0,0 +1,22 @@
+/**
+ * Resolves the Supabase project URL and anon key, preferring explicit config
+ * over the `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`
+ * environment variables.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @returns The project URL and anon key to build a Supabase client from.
+ * @throws If neither config nor environment supplies a URL or an anon key.
+ */
+export default function resolveSupabaseEndpoint(supabase) {
+    const url = supabase.url ?? process.env.NEXT_PUBLIC_SUPABASE_URL;
+    if (!url) {
+        throw new Error('db: could not resolve a Supabase project URL. Set `db.supabase.url` ' +
+            'or the NEXT_PUBLIC_SUPABASE_URL environment variable.');
+    }
+    const anonKey = supabase.anonKey ?? process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY;
+    if (!anonKey) {
+        throw new Error('db: could not resolve a Supabase anon key. Set `db.supabase.anonKey` ' +
+            'or the NEXT_PUBLIC_SUPABASE_ANON_KEY environment variable.');
+    }
+    return { url: url.replace(/\/+$/, ''), anonKey };
+}

package/dist/src/db/supabase_transport.d.ts

@@ -0,0 +1,29 @@
+import type { SupabaseDbConfig } from '../types/types';
+/**
+ * The executor shape `drizzle-orm/pg-proxy` calls with each generated
+ * statement. Declared structurally so this file never imports `drizzle-orm`.
+ */
+export type SupabaseRemoteCallback = (sql: string, params: unknown[], method: 'all' | 'execute') => Promise<{
+    rows: unknown[];
+}>;
+/**
+ * Builds the transport Drizzle uses in Supabase mode: every generated
+ * statement is sent through `@supabase/supabase-js`'s `.rpc()` to the
+ * `cfni_exec` function over PostgREST.
+ *
+ * `bearerToken` decides who Postgres thinks is calling — the anon key for
+ * public reads, a user's JWT for `withUserDb` — delivered through the
+ * client's `accessToken` option (the same mechanism a signed-in Supabase
+ * session would use), so RLS is enforced by the database rather than by
+ * anything in this package. The client is created once and reused for every
+ * statement this transport is asked to run.
+ *
+ * Rows come back as positional arrays because `pg-proxy` maps result columns
+ * by index; `cfni_exec` is what guarantees that shape.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key,
+ * or a per-request user JWT.
+ * @returns A callback suitable for `drizzle-orm/pg-proxy`'s `drizzle()`.
+ */
+export default function createSupabaseTransport(supabase: SupabaseDbConfig, bearerToken: string): SupabaseRemoteCallback;

package/dist/src/db/supabase_transport.js

@@ -0,0 +1,49 @@
+import resolveSupabaseEndpoint from './supabase_config';
+const DEFAULT_EXEC_FUNCTION = 'cfni_exec';
+/**
+ * Builds the transport Drizzle uses in Supabase mode: every generated
+ * statement is sent through `@supabase/supabase-js`'s `.rpc()` to the
+ * `cfni_exec` function over PostgREST.
+ *
+ * `bearerToken` decides who Postgres thinks is calling — the anon key for
+ * public reads, a user's JWT for `withUserDb` — delivered through the
+ * client's `accessToken` option (the same mechanism a signed-in Supabase
+ * session would use), so RLS is enforced by the database rather than by
+ * anything in this package. The client is created once and reused for every
+ * statement this transport is asked to run.
+ *
+ * Rows come back as positional arrays because `pg-proxy` maps result columns
+ * by index; `cfni_exec` is what guarantees that shape.
+ *
+ * @param supabase The `db.supabase` config block.
+ * @param bearerToken Token resolved as the caller's identity — the anon key,
+ * or a per-request user JWT.
+ * @returns A callback suitable for `drizzle-orm/pg-proxy`'s `drizzle()`.
+ */
+export default function createSupabaseTransport(supabase, bearerToken) {
+    const { url, anonKey } = resolveSupabaseEndpoint(supabase);
+    const execFunction = supabase.execFunction ?? DEFAULT_EXEC_FUNCTION;
+    let clientPromise = null;
+    async function getClient() {
+        clientPromise ?? (clientPromise = (async () => {
+            const { createClient } = await import('@supabase/supabase-js');
+            return createClient(url, anonKey, { accessToken: async () => bearerToken });
+        })());
+        return clientPromise;
+    }
+    return async (sql, params) => {
+        const client = await getClient();
+        const { data, error } = await client.rpc(execFunction, { statement: sql, params });
+        if (error)
+            throw new Error(describeFailure(error, execFunction));
+        return { rows: Array.isArray(data) ? data : [] };
+    };
+}
+function describeFailure(error, execFunction) {
+    // PGRST202 is PostgREST's "no such function" — by far the most likely
+    // first-run failure, so point at the install step instead of the raw code.
+    if (error.code === 'PGRST202') {
+        return `db: Supabase rejected the query — ${error.message}. Install the ${execFunction} function from supabase/cfni_exec.sql in your database.`;
+    }
+    return `db: Supabase rejected the query — ${error.message}.`;
+}

package/dist/src/firebase_auth/server/mint_server_app_check_token.d.ts

@@ -3,20 +3,28 @@ import type { FirebaseAppCheckConfig } from '../../types/types';
  * Mints a fresh App Check token server-side via a service account, for use
  * when the client-written App Check cookie (see `appCheckTokenCookieName`)
  * is absent — e.g. a cold navigation before `AuthUserProvider` has run and
- * had a chance to write it. Requires `clientEmail`/`privateKey`/`appId` on
- * `firebaseAuth.appCheck`; returns `undefined` (never throws) if the
- * exchange fails, so a caller can always fall back to "no App Check token"
- * exactly as before this existed.
+ * had a chance to write it. Requires `clientEmail`/`appId` on
+ * `firebaseAuth.appCheck`, plus either `privateKey` or the
+ * `oauthClientId`/`oauthClientSecret`/`oauthRefreshToken` triple; returns
+ * `undefined` (never throws) if the exchange fails, so a caller can always
+ * fall back to "no App Check token" exactly as before this existed.
  *
- * Signs a short-lived custom JWT with the service account's private key
- * (`jose`, Edge/WebCrypto-compatible — no `firebase-admin`), then exchanges
- * it for an App Check token via `exchangeCustomToken`, authenticated with
- * the project's Web API key (`?key=`) — `exchangeCustomToken` otherwise
- * rejects the call outright as an unregistered/unidentified caller
- * (403 `PERMISSION_DENIED`), before the custom token itself is even
- * evaluated. Not cached beyond the caller's own request-scoped `cache()`
- * wrapper — a fresh mint costs one signing operation plus one network
- * round-trip, acceptable per-request but not worth doing more than once per
- * request.
+ * Signs a short-lived custom JWT, then exchanges it for an App Check token
+ * via `exchangeCustomToken`, authenticated with the project's Web API key
+ * (`?key=`) — `exchangeCustomToken` otherwise rejects the call outright as
+ * an unregistered/unidentified caller (403 `PERMISSION_DENIED`), before the
+ * custom token itself is even evaluated. Not cached beyond the caller's own
+ * request-scoped `cache()` wrapper — a fresh mint costs one signing
+ * operation plus one network round-trip, acceptable per-request but not
+ * worth doing more than once per request.
+ *
+ * The custom token is signed one of two ways, `privateKey` taking priority
+ * when both are set:
+ * - `privateKey` set: signed locally (`jose`, Edge/WebCrypto-compatible —
+ *   no `firebase-admin`).
+ * - OAuth triple set instead: signed remotely via
+ *   `sign_custom_token_remote.ts` (IAM Credentials `signJwt`) — the way to
+ *   mint tokens when a GCP org policy blocks creating the service-account
+ *   key `privateKey` would otherwise require.
  */
 export default function mintServerAppCheckToken(projectId: string, apiKey: string, appCheck: FirebaseAppCheckConfig | undefined): Promise<string | undefined>;