@everystack/api 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@everystack/api` are documented here.
 
 Format based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.4.4] - 2026-10-15
+
+### Added
+
+- PATCH honours ?deleted=include|only so a soft-deleted row can be restored
+
+### Fixed
+
+- refuse a JOIN embed list that names no real column
+- restore through PATCH is off unless softDelete.restore names the caller's role
+- a PATCH whose final body has nothing to write answers 400, not 500
+
 ## [0.4.3] - 2026-10-14
 
 ### BREAKING CHANGES

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@everystack/api",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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

@@ -39,6 +39,9 @@ export interface CountResponse<T> extends ClientResponse<T> {
   total: number;
 }
 
+/** Soft-delete scope: `include` reads or writes live and deleted rows, `only` deleted rows. */
+export type DeletedMode = 'include' | 'only';
+
 export interface QueryBuilder {
   eq(column: string, value: string): QueryBuilder;
   neq(column: string, value: string): QueryBuilder;
@@ -68,6 +71,9 @@ export interface QueryBuilder {
   order(column: string, direction?: 'asc' | 'desc'): QueryBuilder;
   limit(count: number): QueryBuilder;
   offset(count: number): QueryBuilder;
+  /** Soft-delete tables: ?deleted=include|only on select and update. `.deleted('only').update({ deletedAt: null })` restores,
+   *  for a role the handler lists in `softDelete.restore`; for anyone else update ignores it. */
+  deleted(mode: DeletedMode): QueryBuilder;
   execute(): Promise<ClientResponse<unknown[]>>;
   executeWithCount(): Promise<CountResponse<unknown[]>>;
   single(): Promise<ClientResponse<unknown>>;
@@ -123,6 +129,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
   let orderParam: string | null = null;
   let limitParam: number | null = null;
   let offsetParam: number | null = null;
+  let deletedParam: DeletedMode | null = null;
 
   const builder: QueryBuilder = {
     eq(column, value) { filters.push([column, `eq.${value}`]); return builder; },
@@ -151,9 +158,10 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     order(column, direction = 'asc') { orderParam = `${column}.${direction}`; return builder; },
     limit(count) { limitParam = count; return builder; },
     offset(count) { offsetParam = count; return builder; },
+    deleted(mode) { deletedParam = mode; return builder; },
 
     async execute(): Promise<ClientResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam, deletedParam);
       const headers = await buildHeaders(options);
       const { response, retried } = await fetchWithRetry(url, { method: 'GET', headers }, options);
 
@@ -168,7 +176,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     },
 
     async executeWithCount(): Promise<CountResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, limitParam, offsetParam, deletedParam);
       const headers = await buildHeaders(options);
       headers['Prefer'] = 'count=exact';
 
@@ -220,7 +228,7 @@ function createQueryBuilder(options: ClientOptions, table: string): QueryBuilder
     },
 
     async update(data: Record<string, unknown>): Promise<ClientResponse<unknown[]>> {
-      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null);
+      const url = buildUrl(options.baseUrl, table, filters, selectParam, orderParam, null, null, deletedParam);
       const headers = await buildHeaders(options);
       headers['Content-Type'] = 'application/json';
 
@@ -340,6 +348,7 @@ function buildUrl(
   order: string | null,
   limit: number | null,
   offset: number | null,
+  deleted: DeletedMode | null = null,
 ): string {
   const path = `${baseUrl}/${table}`;
   const base = typeof globalThis.location !== 'undefined' ? globalThis.location.origin : undefined;
@@ -355,6 +364,7 @@ function buildUrl(
   if (order) url.searchParams.set('order', order);
   if (limit !== null) url.searchParams.set('limit', String(limit));
   if (offset !== null) url.searchParams.set('offset', String(offset));
+  if (deleted) url.searchParams.set('deleted', deleted);
 
   return url.toString();
 }

package/src/handler/index.ts

@@ -233,6 +233,13 @@ export interface SoftDeleteConfig {
   column?: string;
   /** Tables with soft-delete enabled. If omitted, all tables with the column are treated as soft-delete. */
   tables?: string[];
+  /** Who may restore through PATCH, per table: table name -> role names. Keyed like `tables`.
+   *  PATCH honours `?deleted=include|only` only when the caller's role claim (`auth.roleField`,
+   *  default `role`) is in the table's list: exact string match, no hierarchy, no case folding.
+   *  Anyone else gets live rows only, as if the param were absent. A restore body must be
+   *  exactly `{ <column>: null }`, or 400. Omitted: no one restores through the API.
+   *  This is a backstop. RLS must also keep other roles off deleted rows (docs/handler.md). */
+  restore?: Record<string, string[]>;
 }
 
 export interface HookConfig {
@@ -395,6 +402,17 @@ function getSoftDeleteColumn(table: DrizzleTable, options?: HandlerOptions): Dri
   return getColumn(table, colName);
 }
 
+/**
+ * The soft-delete condition for a GET or PATCH: ?deleted=include adds none, ?deleted=only
+ * matches deleted rows, anything else (absent or unknown) matches live rows. DELETE does
+ * not use it: it always matches live rows only.
+ */
+function softDeleteCondition(sdCol: DrizzleColumn, params: URLSearchParams): SQL | null {
+  const mode = params.get('deleted');
+  if (mode === 'include') return null;
+  return mode === 'only' ? isNotNull(sdCol) : isNull(sdCol);
+}
+
 function isSoftDeleteTable(tableName: string, table: DrizzleTable, options?: HandlerOptions): boolean {
   if (!options?.softDelete) return false;
   if (options.softDelete.tables) {
@@ -766,8 +784,14 @@ function expandTableKeyedOptions(
     ...(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) } }
+    ...(options.softDelete
+      ? {
+        softDelete: {
+          ...options.softDelete,
+          ...(options.softDelete.tables ? { tables: expandList(options.softDelete.tables) } : {}),
+          ...(options.softDelete.restore ? { restore: expandMap(options.softDelete.restore) } : {}),
+        },
+      }
       : {}),
   };
 }
@@ -826,6 +850,48 @@ function validateRowOwnership(schema: Schema, options: HandlerOptions | undefine
   }
 }
 
+/**
+ * Refuse to start on a softDelete.restore config the handler cannot honour. Every entry
+ * must name a soft-delete table. A restorable table must not list the soft-delete column
+ * in protectedFields: the strip would leave every restore body empty. Takes the expanded
+ * options, so both spellings of a table are checked.
+ */
+function validateSoftDeleteRestore(schema: Schema, options: HandlerOptions | undefined): void {
+  const softDelete = options?.softDelete;
+  const colName = softDelete?.column || 'deletedAt';
+  for (const [tableName, roles] of Object.entries(softDelete?.restore ?? {})) {
+    const table = schema[tableName];
+    const isSoftDelete = table
+      ? isSoftDeleteTable(tableName, table, options)
+      : (softDelete?.tables?.includes(tableName) ?? false);
+    if (!isSoftDelete) {
+      throw new Error(
+        `[everystack/api] softDelete.restore.${tableName}: table "${tableName}" is not a soft-delete table. Add it to softDelete.tables or remove the entry.`,
+      );
+    }
+    const sameColumn = (field: string): boolean => (table
+      ? getColumn(table, field) !== null && getColumn(table, field) === getColumn(table, colName)
+      : toSnakeCase(field) === toSnakeCase(colName));
+    if (roles.length > 0 && (options?.protectedFields?.[tableName] ?? []).some(sameColumn)) {
+      throw new Error(
+        `[everystack/api] softDelete.restore.${tableName}: the soft-delete column "${colName}" is in protectedFields.${tableName}, so every restore body is stripped to {}. Remove it from protectedFields.${tableName} or remove the restore entry.`,
+      );
+    }
+  }
+}
+
+/**
+ * True when the caller may restore on this table: its role claim is an exact member of
+ * softDelete.restore[tableName]. Fail closed: no option, no list, no user, or a missing or
+ * non-string role claim is not a member.
+ */
+function mayRestore(tableName: string, options: HandlerOptions | undefined, user: Record<string, unknown> | null): boolean {
+  const roles = options?.softDelete?.restore?.[tableName];
+  if (!roles?.length || !user) return false;
+  const role = readRoleClaim(user, options?.auth?.roleField ?? 'role');
+  return role !== '' && roles.includes(role);
+}
+
 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
@@ -847,6 +913,7 @@ export function createHandler(db: DrizzleDb, rawSchema: Schema, rawOptions?: Han
     }
   }
   validateRowOwnership(schema, rawOptions);
+  validateSoftDeleteRestore(schema, options);
   const tableNames = new Set(Object.keys(schema));
   const canonicalTables = [...new Set(Object.entries(rawSchema).map(([key, value]) => sqlNameOf(value) ?? key))];
 
@@ -1294,9 +1361,11 @@ function buildWithClause(
     }
     const config: Record<string, any> = {};
     if (embed.columns !== null) {
+      // Drop names that are not columns of a known table: Drizzle ignores them,
+      // and throws when nothing else is left. An emptied list is the 400 below.
       config.columns = Object.fromEntries(embed.columns
-        .map(name => columnPropertyName(table, name) ?? name)
-        .filter(name => !hidden.has(name))
+        .map(name => (table ? columnPropertyName(table, name) : name))
+        .filter((name): name is string => name !== undefined && !hidden.has(name))
         .map(name => [name, true]));
       if (Object.keys(config.columns).length === 0) return null;
     } else if (hidden.size > 0) {
@@ -1462,13 +1531,8 @@ async function handleGet(
   if (isSoftDeleteTable(tableName, table, options)) {
     const sdCol = getSoftDeleteColumn(table, options);
     if (sdCol) {
-      const deletedParam = params.get('deleted');
-      if (deletedParam === 'only') {
-        conditions.push(isNotNull(sdCol));
-      } else if (deletedParam !== 'include') {
-        // Default: exclude deleted records
-        conditions.push(isNull(sdCol));
-      }
+      const condition = softDeleteCondition(sdCol, params);
+      if (condition) conditions.push(condition);
     }
   }
 
@@ -2094,6 +2158,23 @@ async function handlePatch(
     throw err;
   }
 
+  // Restore: ?deleted=include|only is honoured only for a role in softDelete.restore for
+  // this table. Anyone else is matched to live rows, as if the param were absent.
+  const sdCol = isSoftDeleteTable(tableName, table, options) ? getSoftDeleteColumn(table, options) : null;
+  const restoring = sdCol !== null && mayRestore(tableName, options, user);
+  const deletedMode = params.get('deleted');
+  if (restoring && (deletedMode === 'include' || deletedMode === 'only')) {
+    // Checked after the protectedFields strip, so a body stripped to {} is refused here.
+    const key = columnPropertyName(table, options?.softDelete?.column || 'deletedAt');
+    const isRestoreBody = body !== null && typeof body === 'object' && !Array.isArray(body)
+      && Object.keys(body).length === 1 && key !== undefined && Object.hasOwn(body, key) && body[key] === null;
+    if (!isRestoreBody) {
+      const column = options?.softDelete?.column || 'deletedAt';
+      const wire = options?.naming === 'snake_case' ? toSnakeCase(column) : column;
+      return json({ message: `restore accepts only { ${wire}: null }` }, 400);
+    }
+  }
+
   // With the ownership backstop lifted, an unfiltered PATCH would write every row the
   // role's RLS allows. Refuse it, the same filter test DELETE applies to every caller.
   const ownership = options?.rowOwnership?.[tableName];
@@ -2119,16 +2200,22 @@ async function handlePatch(
     }
   }
 
+  // The final body, after the strip and the hook, must have something to write: an empty
+  // SET is a 500 from PostgreSQL. A hook may fill a body the strip emptied, so check here.
+  if (body === null || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).length === 0) {
+    return json({ message: 'No writable fields in request body' }, 400);
+  }
+
   const filterResult = buildAllConditions(table, params);
   if ('error' in filterResult) {
     return sanitizeError(filterResult.error, 400, options);
   }
   const conditions = filterResult.conditions;
 
-  // Soft-delete: exclude deleted records from updates
-  if (isSoftDeleteTable(tableName, table, options)) {
-    const sdCol = getSoftDeleteColumn(table, options);
-    if (sdCol) conditions.push(isNull(sdCol));
+  // Soft-delete: update live records, unless a restore role sent ?deleted=include|only
+  if (sdCol) {
+    const condition = restoring ? softDeleteCondition(sdCol, params) : isNull(sdCol);
+    if (condition) conditions.push(condition);
   }
 
   // Row ownership: AND WHERE <column> = user[<userField>] for IDOR protection