@everystack/api 0.2.11 → 0.2.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "PostgREST-compatible HTTP handler + typed fetch client for Drizzle ORM",
   "license": "AGPL-3.0-only",
   "author": "Scalable Technology, Inc. <licensing@scalable.technology>",

package/src/handler/index.ts

@@ -156,6 +156,23 @@ export interface CacheConfig {
   private?: string;
 }
 
+/** Global post-RPC hook — fired after a SUCCESSFUL RPC dispatch, fire-and-forget.
+ *  The RPC counterpart to the per-table after* hooks (afterCreate/afterUpdate/
+ *  afterDelete). RPCs are function-scoped, not table-scoped, so this is global
+ *  rather than keyed by table. Receives the RPC's return value (the row(s) it
+ *  produced), the function name, the request body, the verified user/client, and
+ *  the trace-id ctx. Errors are swallowed and never affect the response — a
+ *  side-effect failure (cache purge, webhook) must not fail the write. Runs only
+ *  on the success path. See docs/plans/afterrpc-cache-purge.md. */
+export type AfterRpcHook = (
+  result: unknown,
+  fnName: string,
+  body: unknown,
+  user: Record<string, unknown> | null,
+  client: Record<string, unknown> | null,
+  ctx: RequestContext,
+) => Promise<void>;
+
 /** 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
@@ -212,6 +229,10 @@ export interface HandlerOptions {
   pgSettings?: (user: Record<string, unknown> | null, client?: Record<string, unknown> | null) => Record<string, string>;
   /** Per-table lifecycle hooks for mutations. */
   hooks?: Record<string, HookConfig>;
+  /** Global hook fired after a successful RPC. Fire-and-forget; errors swallowed.
+   *  RPC writes fire no per-table hooks, so this is the only post-RPC side-effect
+   *  seam (cache purge, webhooks, audit enrichment). See docs/plans/afterrpc-cache-purge.md. */
+  afterRpc?: AfterRpcHook;
   /** API naming convention for query params, request bodies, and responses.
    *  'snake_case': accept snake_case inbound, return snake_case outbound.
    *  Default: use Drizzle property names as-is (typically camelCase). */
@@ -639,6 +660,12 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
             kind: 'rpc', name: fnName, user, client,
             result: 'allow', requestId, body: body as Record<string, unknown>,
           });
+          // Global post-RPC hook: fire-and-forget side effects (cache purge,
+          // webhooks). Swallow errors — a side-effect failure must not fail the
+          // write, exactly like the after* REST hooks. Success path only.
+          if (options?.afterRpc) {
+            try { await options.afterRpc(result, fnName, body, user, client, ctx); } catch {}
+          }
           // Same cache discipline as table GETs: with pgSettings configured the
           // response can vary by identity (opportunistic auth on public RPCs),
           // so it must forbid shared caching ITSELF — never rely on the CDN