@everystack/api 0.2.11 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.2.11",
+  "version": "0.4.0",
   "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). */
@@ -501,8 +522,81 @@ function transformBodyKeys(body: Record<string, unknown>, table: DrizzleTable):
   return result;
 }
 
-export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOptions): Handler {
+/** The name a drizzle pgTable knows itself by in SQL, or null for a non-table export. */
+function sqlNameOf(value: unknown): string | null {
+  if (!value || typeof value !== 'object') return null;
+  const name = (value as Record<symbol, unknown>)[Symbol.for('drizzle:Name')];
+  return typeof name === 'string' ? name : null;
+}
+
+/** Export-key ↔ SQL-name pairs for every table whose two spellings differ. */
+function tableNamePairs(schema: Schema): Array<{ exportKey: string; sqlName: string }> {
+  const pairs: Array<{ exportKey: string; sqlName: string }> = [];
+  for (const [exportKey, value] of Object.entries(schema)) {
+    const sqlName = sqlNameOf(value);
+    if (sqlName && sqlName !== exportKey) pairs.push({ exportKey, sqlName });
+  }
+  return pairs;
+}
+
+/** The schema with each table reachable under BOTH spellings (existing keys win). */
+function expandSchema(schema: Schema, pairs: Array<{ exportKey: string; sqlName: string }>): Schema {
+  if (pairs.length === 0) return schema;
+  const expanded: Schema = { ...schema };
+  for (const { exportKey, sqlName } of pairs) {
+    if (!(sqlName in expanded)) expanded[sqlName] = schema[exportKey];
+  }
+  return expanded;
+}
+
+/**
+ * Table-keyed options written in EITHER naming domain apply to both spellings.
+ * `deriveHandlerConfig` emits SQL names; hand-written configs use export keys —
+ * each key gains its twin (same value reference), so neither authoring style
+ * can strand a table behind the other domain's gate.
+ */
+function expandTableKeyedOptions(
+  options: HandlerOptions | undefined,
+  pairs: Array<{ exportKey: string; sqlName: string }>,
+): HandlerOptions | undefined {
+  if (!options || pairs.length === 0) return options;
+  const twin = (name: string): string | undefined =>
+    pairs.find((p) => p.exportKey === name)?.sqlName ?? pairs.find((p) => p.sqlName === name)?.exportKey;
+  const expandList = (list: string[]): string[] =>
+    [...new Set(list.flatMap((name) => { const t = twin(name); return t ? [name, t] : [name]; }))];
+  const expandMap = <T,>(map: Record<string, T>): Record<string, T> => {
+    const out: Record<string, T> = { ...map };
+    for (const key of Object.keys(map)) {
+      const t = twin(key);
+      if (t && !(t in out)) out[t] = map[key];
+    }
+    return out;
+  };
+  return {
+    ...options,
+    ...(options.exposedTables ? { exposedTables: expandList(options.exposedTables) } : {}),
+    ...(options.hiddenColumns ? { hiddenColumns: expandMap(options.hiddenColumns) } : {}),
+    ...(options.protectedFields ? { protectedFields: expandMap(options.protectedFields) } : {}),
+    ...(options.rowOwnership ? { rowOwnership: expandMap(options.rowOwnership) } : {}),
+    ...(options.relations ? { relations: expandMap(options.relations) } : {}),
+    ...(options.hooks ? { hooks: expandMap(options.hooks) } : {}),
+    ...(options.softDelete?.tables
+      ? { softDelete: { ...options.softDelete, tables: expandList(options.softDelete.tables) } }
+      : {}),
+  };
+}
+
+export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: HandlerOptions): Handler {
+  // The naming seam: URLs, exposedTables, and relation targets historically mixed
+  // drizzle export keys (`texturePacks`) with SQL names (`texture_packs`), and any
+  // multi-word table failed one gate or the other — both spellings 404'd. Collapse
+  // the two domains here, once: both spellings route, and options in either domain
+  // apply. The root listing below stays one entry per table (the SQL name).
+  const namePairs = tableNamePairs(rawSchema);
+  const schema = expandSchema(rawSchema, namePairs);
+  const options = expandTableKeyedOptions(rawOptions, namePairs);
   const tableNames = new Set(Object.keys(schema));
+  const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
   return async (request: Request): Promise<Response> => {
     const url = new URL(request.url);
@@ -562,11 +656,12 @@ export function createHandler(db: DrizzleDb, schema: Schema, options?: HandlerOp
       }
     }
 
-    // Root path — table listing, always public
+    // Root path — table listing, always public. One entry per table (SQL name),
+    // regardless of how many spellings route to it.
     if (pathSegments.length === 0) {
       const tables = options?.exposedTables
-        ? Array.from(tableNames).filter(t => options.exposedTables!.includes(t))
-        : Array.from(tableNames);
+        ? canonicalTables.filter(t => options.exposedTables!.includes(t))
+        : canonicalTables;
       return json({ tables }, 200);
     }
 
@@ -639,6 +734,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