@everystack/api 0.4.11 → 0.4.12

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.12] - 2026-10-23
+
+### BREAKING CHANGES
+
+- lifecycle delete and restore hand the batch id to the caller
+- lifecycle: { deleteWhen } refuses deleting a row its predicate does not allow
+- one lifecycle hook API: (rows, ctx), veto(reason), beforeStamp
+
+### Added
+
+- afterStamp and afterRestore hooks hand a lifecycle batch to app code
+
+### Fixed
+
+- a lifecycle DELETE stamps only the rows beforeStamp saw
+
+### Documentation
+
+- afterStamp, afterRestore and the batch in the restore response
+- Extending lifecycle, the phase table, the veto and failure rules
+
 ## [0.4.11] - 2026-10-23
 
 ### Added

package/README.md

@@ -101,6 +101,10 @@ createHandler(db, schema, {
       afterUpdate: async (rows, user, client) => {},
       beforeDelete: async (user, client) => {},
       afterDelete: async (rows, user, client) => {},
+      // Lifecycle tables only (see "Extending lifecycle" in docs/handler.md); veto from '@everystack/api/handler':
+      beforeStamp: (row, ctx) => (ctx.user ? undefined : veto('sign in to delete')), // in the transaction; veto -> 409
+      afterStamp: async (rows, ctx) => {},   // after commit, once per batch (ctx.batch)
+      afterRestore: async (rows, ctx) => {}, // after commit, ctx.batch and ctx.counts
     },
   },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.11",
+  "version": "0.4.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/client/index.ts

@@ -84,7 +84,7 @@ export interface QueryBuilder {
   update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>>;
   remove(): Promise<ClientResponse<unknown[]>>;
   /** Lifecycle tables: restore a deleted row and its delete batch, on the table's delete rule.
-   *  POSTs `{baseUrl}/{table}/restore` with `{ id }`; the data is `{ restored, skipped }`. */
+   *  POSTs `{baseUrl}/{table}/restore` with `{ id }`; the data is `{ restored, skipped, batch }`. */
   restore(id: string | number): Promise<ClientResponse<RestoreResult>>;
 }
 
@@ -92,6 +92,9 @@ export interface QueryBuilder {
 export interface RestoreResult {
   restored: number;
   skipped: number;
+  /** The batch restored; null for a row deleted before batches existed. Absent from a server
+   *  whose restore functions predate it (its next db:apply adds it). */
+  batch?: string | null;
 }
 
 export interface Client {

package/src/handler/index.ts

@@ -28,6 +28,19 @@ type Handler = (request: Request) => Promise<Response>;
 
 export { HandlerError } from './errors';
 import { HandlerError } from './errors';
+export { veto, isVeto } from './veto';
+export type { HookVeto, LifecycleContext, DestroyContext, DestroyHook, BeforeLifecycleHook, AfterLifecycleHook } from './veto';
+import { isVeto, type AfterLifecycleHook, type BeforeLifecycleHook, type DestroyContext, type DestroyHook, type LifecycleContext } from './veto';
+
+/** A before hook returned veto(reason): the request is refused with 409 and its transaction rolls back. */
+class VetoRefusal extends Error {
+  constructor(readonly reason: string) { super(reason); }
+}
+
+/** A lifecycle before hook threw inside its transaction; carried out so the handler can answer as for any before hook. */
+class BeforeHookThrew extends Error {
+  constructor(readonly thrown: unknown) { super('before hook threw'); }
+}
 
 /**
  * A 5xx system fault surfaced to the observability sink. Distinct from a 4xx
@@ -272,15 +285,6 @@ export interface SoftDeleteConfig {
   lifecycle?: string[];
 }
 
-/** Context for a real removal. External effects must be idempotent across retries. */
-export interface DestroyContext {
-  source: 'purge' | 'api';
-  user: Record<string, unknown> | null;
-  client: Record<string, unknown> | null;
-}
-
-export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | Promise<void>;
-
 export interface HookConfig {
   /** Called before INSERT. Can modify the body (e.g., inject userId). Throw to abort. */
   beforeCreate?: (body: Record<string, unknown>, user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<Record<string, unknown>>;
@@ -294,14 +298,33 @@ export interface HookConfig {
   beforeDelete?: (user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
   /** Called after DELETE with all deleted rows. Fire-and-forget. */
   afterDelete?: (rows: Record<string, unknown>[], user: Record<string, unknown> | null, client: Record<string, unknown> | null) => Promise<void>;
-  /** After the hard DELETE statement and before commit, for each returned row. A throw
-   * rolls back the database delete only. No transaction is passed; external effects
+  /** After the hard DELETE statement and before commit, for each returned row. Return
+   * `veto(reason)` to refuse the request (409 `{ message, code: 'vetoed' }`, nothing deleted). A
+   * throw rolls back the database delete only. No transaction is passed; external effects
    * cannot be undone and must be idempotent. Lifecycle API deletes do not call this.
    * Treat the row as read-only: it is the same object later serialized into the response. */
   beforeDestroy?: DestroyHook;
   /** After a real removal commits, per returned row, best-effort. Must be idempotent.
    * Treat the row as read-only: it is the same object later serialized into the response. */
   afterDestroy?: DestroyHook;
+  /** Lifecycle tables only: inside the DELETE's transaction, before the DELETE statement, once per
+   * matched ROOT row (the pre-image), with `{ phase: 'stamp', batch: null }`. Return `veto(reason)` to
+   * refuse the whole request: 409 `{ message: reason, code: 'vetoed' }`, nothing stamped, no after
+   * hooks. A throw is a failure (a HandlerError keeps its status, anything else is 500). Cascaded
+   * children run no hook: guard them with the model's `deleteWhen`. */
+  beforeStamp?: BeforeLifecycleHook;
+  /** Lifecycle tables only: after a DELETE that stamped rows COMMITS, once per batch, with the
+   * stamped root rows of that batch (the pre-image, as the response lists them) and `ctx.batch`. A
+   * DELETE matching several rows stamps one batch per row, so this runs once per row then.
+   * Best-effort like afterDelete: a throw goes to onError and never changes the response. Not
+   * called when nothing was stamped, nor on a table that is not lifecycle. */
+  afterStamp?: AfterLifecycleHook;
+  /** Lifecycle tables only: after `POST {table}/restore` COMMITS, with `[{ <key>: id }]` (the id as
+   * the request sent it), `ctx.batch` and `ctx.counts`. Not called for a row deleted before batches
+   * existed (batch null). Best-effort: a throw goes to onError and never changes the response. */
+  afterRestore?: AfterLifecycleHook;
+  /** Reserved for a future release: createHandler refuses it, so it is never silently ignored. */
+  beforeRestore?: never;
 }
 
 /** Cache-Control header configuration for different response categories. */
@@ -463,6 +486,8 @@ export interface HandlerOptions {
 
 /** The lifecycle machinery's timestamp column: fixed, whatever softDelete.column says. */
 const LIFECYCLE_DELETED_AT = 'deletedAt';
+/** The SQL name of the lifecycle batch column (columnPropertyName maps it to the table's key). */
+const LIFECYCLE_DELETED_BATCH = 'deleted_batch';
 
 function isLifecycleTable(tableName: string, options?: HandlerOptions): boolean {
   return options?.softDelete?.lifecycle?.includes(tableName) ?? false;
@@ -950,6 +975,18 @@ function declaredTables(options: HandlerOptions): Set<string> {
   return new Set(names.map(toSnakeCase));
 }
 
+/**
+ * Refuse a hook name reserved for a future release, so adding it later is additive and no one
+ * ships a hook that is silently ignored. Every other unknown hook key is ignored, as before.
+ */
+function refuseReservedHooks(options: HandlerOptions | undefined): void {
+  for (const [tableName, hook] of Object.entries(options?.hooks ?? {})) {
+    if (hook && (hook as { beforeRestore?: unknown }).beforeRestore !== undefined) {
+      throw new Error(`[everystack/api] hooks.${tableName}.beforeRestore is reserved for a future release; remove it`);
+    }
+  }
+}
+
 /**
  * Refuse to start on a rowOwnership config the handler cannot enforce. The owner clause
  * needs a user, so rowOwnership without auth is an error. An entry whose column does not
@@ -1336,6 +1373,11 @@ function mapIntegrityError(
     if (constraint !== undefined) body.constraint = constraint;
     if (code === '23502' && typeof fields.column === 'string') body.column = fields.column;
   }
+  // lifecycle: { deleteWhen }'s guard (`<table>_lifecycle_delete_when`): a stable message, never a
+  // row value. An author's constraintMessages entry for the name still wins.
+  if (declared === undefined && code === '23514' && constraint?.endsWith('_lifecycle_delete_when')) {
+    body.message = "Deleting this row is not allowed by its model's deleteWhen.";
+  }
   // A failing trigger or FK action can name a different table than the URL.
   // Missing driver tables (and unknown RPC policies) use every configured list.
   const driverTable = typeof fields.table === 'string' ? fields.table : undefined;
@@ -1368,6 +1410,7 @@ function validateConstraintMessages(options?: HandlerOptions): void {
 }
 
 export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: HandlerOptions): Handler {
+  refuseReservedHooks(rawOptions);
   // 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
@@ -1822,6 +1865,16 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
       }
       return response;
     } catch (error) {
+      // A before hook's veto: a decision, not a fault. Its transaction has rolled back.
+      if (error instanceof VetoRefusal) {
+        if (isWrite) {
+          await emitAudit(options?.audit, {
+            kind: 'rest', name: tableName, user, client, result: 'deny',
+            requestId, operation: auditOp, filter: auditFilter, columns: auditColumns,
+          });
+        }
+        return json({ message: error.reason, code: 'vetoed' }, 409);
+      }
       const appError = error instanceof HandlerError;
       const unavailable = !appError && isServiceUnavailable(error);
       const integrity = appError || unavailable ? undefined : mapIntegrityError(error, tableName, options);
@@ -3186,12 +3239,35 @@ async function handleDelete(
 
   // Lifecycle: a real DELETE, which the table's trigger turns into a stamp (it reports 0 rows).
   if (isLifecycleTable(tableName, options)) {
-    const rows = await lifecycleDelete(db, table, tableName, conditions, options);
+    let stamped: Awaited<ReturnType<typeof lifecycleDelete>>;
+    try {
+      stamped = await lifecycleDelete(db, table, tableName, conditions, options, hook?.beforeStamp
+        ? { run: hook.beforeStamp.bind(hook), ctx: { phase: 'stamp', source: 'api', batch: null, user, client } } : undefined);
+    } catch (err) {
+      // Its transaction has rolled back: nothing was stamped.
+      if (err instanceof BeforeHookThrew) return beforeHookFailure(err.thrown, options, { requestId, name: `${tableName}.beforeStamp`, method: 'DELETE' }, deferred);
+      throw err;
+    }
+    const { rows, batchOf } = stamped;
+    // The pre-image carries deletedBatch NULL; give each root its batch. stripHiddenColumns keeps
+    // it for a plain manage role only.
+    const batchKey = columnPropertyName(table, LIFECYCLE_DELETED_BATCH);
+    if (batchKey) for (const [row, batch] of batchOf) row[batchKey] = batch;
     if (hook?.afterDelete && rows.length > 0) {
       const { afterDelete } = hook;
       deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDelete`, method: 'DELETE' },
         () => afterDelete.call(hook, rows, user, client));
     }
+    if (hook?.afterStamp && batchOf.size > 0) {
+      const { afterStamp } = hook;
+      const roots = new Map<string, Record<string, unknown>[]>();
+      for (const [row, batch] of batchOf) roots.set(batch, [...(roots.get(batch) ?? []), row]);
+      for (const [batch, batchRoots] of roots) {
+        const ctx: LifecycleContext = { phase: 'stamp', source: 'api', batch, user, client };
+        deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterStamp`, method: 'DELETE' },
+          async () => { await afterStamp.call(hook, batchRoots, ctx); });
+      }
+    }
     return json(stripHiddenColumns(transformResponse(rows, options), tableName, options), 200);
   }
 
@@ -3235,15 +3311,18 @@ async function handleDelete(
 
   // RETURNING proves DELETE authority, including policies that differ from SELECT.
   // The dispatcher keeps this statement and beforeDestroy in one caller transaction.
-  const ctx: DestroyContext = { source: 'api', user, client };
+  // A veto throws out of the caller transaction, so the DELETE rolls back; the dispatcher answers 409.
+  const ctx: DestroyContext = { phase: 'destroy', source: 'api', batch: null, user, client };
   for (const row of rows) {
-    if (hook?.beforeDestroy) await hook.beforeDestroy(row, ctx);
+    if (!hook?.beforeDestroy) break;
+    const verdict = await hook.beforeDestroy(row, ctx);
+    if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
   }
   if (hook?.afterDestroy) {
     const { afterDestroy } = hook;
     for (const row of rows) {
       deferAfterHook(deferred, options?.onError, { requestId, name: `${tableName}.afterDestroy`, method: 'DELETE' },
-        () => Promise.resolve(afterDestroy.call(hook, row, ctx)));
+        async () => { await afterDestroy.call(hook, row, ctx); });
     }
   }
 
@@ -3259,10 +3338,12 @@ async function handleDelete(
 /**
  * DELETE on a lifecycle table. The trigger stamps each row and cancels its delete, so DELETE
  * reports 0 rows and RETURNING has nothing. In one transaction: read the live rows the request
- * matches (the pre-image), DELETE with the same conditions, then drop every row still live: RLS
- * refused its delete. What is left is the pre-image of the rows this request soft-deleted.
- * Under READ COMMITTED a row another request stamps between the read and the DELETE is still
- * listed (and reaches afterDelete): a false attribution, never a leak, since the caller could read it.
+ * matches (the pre-image), run beforeStamp on each, DELETE those keys only (with the same
+ * conditions), then drop every row still live: RLS or the filter refused its delete. What is left is
+ * the pre-image of the rows this request soft-deleted. The read takes no lock, so a hook sees the
+ * row as read; a rule that must hold on the stamped values belongs in deleteWhen, which the trigger
+ * checks on the current row. Under READ COMMITTED a row another request stamps between the read
+ * and the DELETE is still listed (and reaches afterDelete): a false attribution, never a leak.
  */
 async function lifecycleDelete(
   db: DrizzleDb,
@@ -3270,27 +3351,56 @@ async function lifecycleDelete(
   tableName: string,
   conditions: SQL[],
   options?: HandlerOptions,
-): Promise<Record<string, unknown>[]> {
+  beforeStamp?: { run: BeforeLifecycleHook; ctx: LifecycleContext },
+): Promise<{ rows: Record<string, unknown>[]; batchOf: Map<Record<string, unknown>, string> }> {
   const sdCol = getSoftDeleteColumn(tableName, table, options);
-  const keys = primaryKeyColumns(table)
-    .map(column => columnPropertyName(table, column.name))
-    .filter((key): key is string => key !== undefined);
-  if (!sdCol || keys.length === 0) {
-    throw new Error(`[everystack/api] softDelete.lifecycle.${tableName}: the table needs a ${LIFECYCLE_DELETED_AT} column and a primary key`);
-  }
-  const where = and(...conditions, isNull(sdCol))!;
-  const keyOf = (row: Record<string, unknown>): string => JSON.stringify(keys.map(key => row[key]));
-  return db.transaction(async (tx: DrizzleDb) => {
-    const matched: Record<string, unknown>[] = await tx.select().from(table).where(where);
+  const pk = primaryKeyColumns(table);
+  const key = pk.length === 1 ? columnPropertyName(table, pk[0].name) : undefined;
+  if (!sdCol || key === undefined) {
+    throw new Error(`[everystack/api] softDelete.lifecycle.${tableName}: the table needs a ${LIFECYCLE_DELETED_AT} column and a single-column primary key`);
+  }
+  const keyColumn = getTableColumns(table)[key];
+  const batchOf = new Map<Record<string, unknown>, string>();
+  const rows = await db.transaction(async (tx: DrizzleDb) => {
+    // No row lock: FOR UPDATE needs UPDATE privilege, which a delete-only role does not hold.
+    const matched: Record<string, unknown>[] = await tx.select().from(table).where(and(...conditions, isNull(sdCol)));
     if (matched.length === 0) return [];
-    await tx.delete(table).where(where);
+    // beforeStamp: once per matched root, before the DELETE, inside this transaction. A veto or a
+    // throw leaves it, so nothing is stamped.
+    if (beforeStamp) {
+      for (const row of matched) {
+        let verdict: unknown;
+        try { verdict = await beforeStamp.run(row, beforeStamp.ctx); } catch (err) { throw new BeforeHookThrew(err); }
+        if (isVeto(verdict)) throw new VetoRefusal(verdict.reason);
+      }
+    }
+    // The transition appends one `<JSON key> <batch>` line per stamped root to this setting (a
+    // caller that is not a manage role cannot read deleted_batch). Cleared first, so only this
+    // DELETE's lines are read back; informational, the stamp columns stay the truth.
+    await tx.execute(sql`SELECT pg_catalog.set_config('everystack.lifecycle_batch', '', true)`);
+    // Exactly the rows the hook saw: a row that starts to match while a hook runs is not stamped.
+    // The request filter stays, so a matched row edited out of it meanwhile is not stamped either.
+    const matchedKeys = matched.map(row => row[key]);
+    await tx.delete(table).where(and(...conditions, isNull(sdCol), inArray(keyColumn, matchedKeys)));
     const stillLive: Record<string, unknown>[] = await tx
-      .select(Object.fromEntries(keys.map(key => [key, getTableColumns(table)[key]])))
+      .select({ [key]: keyColumn })
       .from(table)
-      .where(where);
-    const live = new Set(stillLive.map(keyOf));
-    return matched.filter(row => !live.has(keyOf(row)));
+      .where(and(isNull(sdCol), inArray(keyColumn, matchedKeys)));
+    const lines = await tx.execute(sql`SELECT pg_catalog.current_setting('everystack.lifecycle_batch', true) AS v`) as unknown as Array<{ v: string | null }>;
+    const byKey = new Map<string, string>();
+    for (const line of String(lines[0]?.v ?? '').split('\n')) {
+      if (line.length < 38) continue;
+      try { byKey.set(String(JSON.parse(line.slice(0, -37))), line.slice(-36)); } catch { /* not a line the transition wrote */ }
+    }
+    const live = new Set(stillLive.map(row => String(row[key])));
+    const stamped = matched.filter(row => !live.has(String(row[key])));
+    for (const row of stamped) {
+      const batch = byKey.get(String(row[key]));
+      if (batch) batchOf.set(row, batch);
+    }
+    return stamped;
   });
+  return { rows, batchOf };
 }
 
 /**
@@ -3329,6 +3439,19 @@ async function handleRestore(
       const rows = await tx.execute(sql`SELECT ${fn}(CAST(${id} AS ${sql.raw(keyType)})) AS result`);
       return (rows as unknown as Array<{ result: unknown }>)[0]?.result;
     });
+    // After the commit (executeWithSettings has returned). Best-effort: never changes the response.
+    const hook = ownEntry(options?.hooks, tableName);
+    const r = result as { restored?: unknown; skipped?: unknown; batch?: unknown } | null;
+    if (hook?.afterRestore && r && typeof r.batch === 'string') {
+      try {
+        await hook.afterRestore([{ [columnPropertyName(table, key.name) ?? key.name]: id }], {
+          phase: 'restore', source: 'api', batch: r.batch, user, client,
+          counts: { restored: Number(r.restored), skipped: Number(r.skipped) },
+        });
+      } catch (err) {
+        await reportHookFault(options?.onError, { requestId, name: `${tableName}.afterRestore`, method: 'POST' }, err);
+      }
+    }
     return json(result, 200);
   } catch (error) {
     // Code and message from the one object that carries the code: a wrapper's message can quote the query.

package/src/handler/veto.ts

@@ -0,0 +1,53 @@
+/**
+ * The lifecycle hook contract. A structurally identical twin of `@everystack/model`'s
+ * lifecycle-hooks (this package has no runtime dependencies): a veto made by either is
+ * recognized by both, and the types are interchangeable. Keep the two in step.
+ */
+
+const VETO_KIND = 'everystack.hookVeto';
+
+/** What a before hook returns to refuse its operation. Make it with {@link veto}. */
+export interface HookVeto {
+  readonly kind: typeof VETO_KIND;
+  readonly reason: string;
+}
+
+/** Refuse the operation a before hook guards. A throw is a failure; a veto is a decision. */
+export function veto(reason: string): HookVeto {
+  if (typeof reason !== 'string' || reason.trim() === '') throw new TypeError('veto(reason) needs a non-empty reason string');
+  return Object.freeze({ kind: VETO_KIND, reason });
+}
+
+/** True only for a value {@link veto} made (or its twin in `@everystack/model`). */
+export function isVeto(value: unknown): value is HookVeto {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    && (value as { kind?: unknown }).kind === VETO_KIND && typeof (value as { reason?: unknown }).reason === 'string';
+}
+
+/** The one context every lifecycle hook receives. */
+export interface LifecycleContext {
+  /** `stamp`: the row was marked deleted. `restore`: a batch came back. `destroy`: physical removal. */
+  phase: 'stamp' | 'restore' | 'destroy';
+  /** `api`: a request through createHandler. `purge`: purgeExpired. */
+  source: 'api' | 'purge';
+  /** The lifecycle batch, or null when there is none to report (before a stamp, a non-lifecycle table, a pre-batch row). Never invented. */
+  batch: string | null;
+  user: Record<string, unknown> | null;
+  client: Record<string, unknown> | null;
+  /** Restore only: what the restore function reported. */
+  counts?: { restored: number; skipped: number };
+}
+
+/** Context for a real removal. External effects must be idempotent across retries. */
+export interface DestroyContext extends LifecycleContext {
+  phase: 'destroy';
+}
+
+/** beforeDestroy may return {@link veto}; afterDestroy's return value is ignored. */
+export type DestroyHook = (row: Record<string, unknown>, ctx: DestroyContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** A before hook of the lifecycle: called once per root row; returns nothing or a veto. */
+export type BeforeLifecycleHook = (row: Record<string, unknown>, ctx: LifecycleContext) => void | HookVeto | Promise<void | HookVeto>;
+
+/** An after hook of the lifecycle: called after commit with the root rows of one batch. Best-effort. */
+export type AfterLifecycleHook = (rows: Record<string, unknown>[], ctx: LifecycleContext) => void | Promise<void>;