@everystack/api 0.2.3 → 0.2.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "publishConfig": {

package/src/client/index.ts

@@ -76,6 +76,8 @@ export interface QueryBuilder {
 
 export interface Client {
   from(table: string): QueryBuilder;
+  /** Call a named RPC on the handler: POST {baseUrl}/rpc/{fn}. */
+  rpc<T = unknown>(fn: string, body?: unknown): Promise<ClientResponse<T>>;
 }
 
 /**
@@ -89,6 +91,27 @@ export function createClient(options: ClientOptions): Client {
     from(table: string): QueryBuilder {
       return createQueryBuilder(options, table);
     },
+
+    async rpc<T = unknown>(fn: string, body?: unknown): Promise<ClientResponse<T>> {
+      const url = `${options.baseUrl}/rpc/${encodeURIComponent(fn)}`;
+      const headers = await buildHeaders(options);
+      headers['Content-Type'] = 'application/json';
+
+      const { response, retried } = await fetchWithRetry(
+        url,
+        { method: 'POST', headers, body: JSON.stringify(body ?? {}) },
+        options,
+      );
+
+      if (retried) return retried as ClientResponse<T>;
+
+      if (!response.ok) {
+        return { data: null, error: await parseError(response) };
+      }
+
+      const data = (await response.json()) as T;
+      return { data, error: null };
+    },
   };
 }
 

package/src/handler/index.ts

@@ -108,14 +108,25 @@ export interface CacheConfig {
   private?: string;
 }
 
-/** RPC handler — plain function (backward compatible) */
-export type RpcHandler = (body: unknown, user?: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Promise<unknown>;
-
-/** RPC handler with per-function role requirement */
+/** RPC handler — plain function (backward compatible).
+ *  Plain handlers dispatch directly: no transaction, no pgSettings — they own
+ *  their DB access through whatever they close over, same privilege model as
+ *  SSR loaders. The optional 4th argument is only provided to handlers
+ *  registered with `settings: true` (see RpcHandlerWithRole). */
+export type RpcHandler = (body: unknown, user?: Record<string, unknown> | null, client?: Record<string, unknown> | null, db?: DrizzleDb) => Promise<unknown>;
+
+/** RPC handler with per-function role requirement and/or RLS context opt-in */
 export interface RpcHandlerWithRole {
   fn: RpcHandler;
   /** Role required to call this RPC (e.g., 'admin', 'authenticated') */
-  role: string;
+  role?: string;
+  /** Run this RPC inside a pgSettings transaction (SET LOCAL ROLE +
+   *  request.jwt.claims) and pass that transaction as the handler's 4th
+   *  argument. The handler MUST query through the passed transaction —
+   *  queries through a captured outer db run on a different pooled
+   *  connection without the settings, and on a single-connection pool
+   *  (Lambda) they deadlock against the open transaction. */
+  settings?: boolean;
 }
 
 export interface HandlerOptions {
@@ -503,9 +514,19 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
 
         const fn = isObjectForm ? entry.fn : entry;
         const body = method === 'POST' ? await request.json().catch(() => ({})) : {};
-        const settings = options?.pgSettings?.(user, client);
         try {
-          const result = await executeWithSettings(db, settings, () => fn(body, user, client));
+          // Plain RPCs dispatch directly — wrapping them in the settings
+          // transaction deadlocks single-connection pools (the fn's queries
+          // go through a captured db that waits on the connection the
+          // transaction holds). Only `settings: true` entries get the
+          // transaction, and they receive it as the 4th argument.
+          const result = isObjectForm && entry.settings
+            ? await executeWithSettings(
+                db,
+                options?.pgSettings?.(user, client),
+                (tx) => fn(body, user, client, tx),
+              )
+            : await fn(body, user, client);
           return json(result, 200);
         } catch (error) {
           if (error instanceof HandlerError) {