@pipeline-builder/pipeline-data 3.4.113 → 3.4.115

package/lib/api/crud-service.d.ts

@@ -1,6 +1,7 @@
 import { SQL } from 'drizzle-orm';
 import type { AnyColumn } from 'drizzle-orm/column';
 import type { PgTable } from 'drizzle-orm/pg-core';
+import { withTenantTx } from '../database/tenancy.js';
 /**
  * Cast Drizzle query results to a typed array.
  * Drizzle's generic return type (`PgSelectBase<...>`) doesn't narrow to our
@@ -12,6 +13,10 @@ export declare function drizzleRows<T>(rows: unknown): T[];
 export declare function drizzleCount(rows: unknown): [{
     count: number;
 }];
+/** The Drizzle transaction object handed to `withTenantTx` callbacks. Passed to
+ *  `onBeforePurge` so a subclass's dependent teardown runs in the SAME purge
+ *  transaction (atomic with the parent DELETE), not a fresh connection. */
+export type CrudTx = Parameters<Parameters<typeof withTenantTx>[0]>[0];
 /**
  * Base interface for entities with common fields
  */
@@ -53,6 +58,11 @@ export interface PaginatedResult<T> {
     /** Cursor pointing to the last item, for cursor-based pagination. */
     nextCursor?: string;
 }
+/** The shared soft-delete retention window in ms (`SOFT_DELETE_RETENTION_DAYS`,
+ *  default 30d; 0 disables purge-deadline stamping). Exposed so non-CrudService
+ *  soft-delete paths (e.g. platform's hand-rolled dashboard/alert services)
+ *  stamp `purge_after` with the SAME window the CrudService entities use. */
+export declare function softDeleteRetentionMs(): number;
 export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, TInsert, TUpdate> {
     /** Drizzle schema table for this entity */
     protected abstract get schema(): PgTable;
@@ -110,6 +120,27 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
     protected onAfterUpdate(_id: string, _entity: TEntity, _userId: string): Promise<void>;
     /** Called after an entity is soft-deleted */
     protected onAfterDelete(_id: string, _entity: TEntity, _userId: string): Promise<void>;
+    /** Called after a soft-deleted entity is restored (undo the delete). Override
+     *  for entities whose restore has side-effects (e.g. re-notify). Best-effort. */
+    protected onAfterRestore(_id: string, _entity: TEntity, _userId: string): Promise<void>;
+    /** Called with the ids about to be hard-purged, BEFORE the delete, inside the
+     *  purge transaction (`tx`) — a subclass tearing down dependents that lack ON
+     *  DELETE CASCADE MUST use `tx` so the teardown is atomic with the parent
+     *  DELETE (and can't self-deadlock against its row locks). Throwing aborts that
+     *  batch's purge (rows stay tombstoned, retried next tick). */
+    protected onBeforePurge(_ids: string[], _tx: CrudTx): Promise<void>;
+    /** Called after rows are hard-purged, for external side-effects (e.g. plugin
+     *  image GC). Best-effort: errors are logged, never block the sweep. */
+    protected onAfterPurge(_ids: string[]): Promise<void>;
+    /** Retention before a soft-deleted row becomes purge-eligible. Defaults to the
+     *  shared `SOFT_DELETE_RETENTION_DAYS`; override per entity for a bespoke window. */
+    protected get softDeleteRetentionMs(): number;
+    /** The `purge_after` value to stamp on a soft-delete: `now + retention`, or the
+     *  spread-friendly empty object when the entity has no `purge_after` column.
+     *  `protected` so subclasses with hand-rolled soft-delete paths (e.g.
+     *  message-service's thread cascade / sysadmin moderation) stamp it too — an
+     *  un-stamped tombstone has NULL `purge_after` and is never hard-purged. */
+    protected purgeAfterStamp(now: Date): Record<string, unknown>;
     /**
      * Org → team hierarchy: when a read is widened to a parent org (`parentOrgId`
      * set), the parent's rows are outside the caller's RLS scope, so the read must
@@ -241,4 +272,52 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      *  (shared/sysadmin-managed) records. No-op for entities without an
      *  `accessModifier` column. Callers pass `!isSystemAdmin(req)`. */
     restrictToPrivate?: boolean): Promise<TEntity[]>;
+    /**
+     * Restore a soft-deleted (tombstoned) entity: clear `isActive`/`deletedAt`/
+     * `deletedBy`/`purgeAfter` so it reappears in normal reads.
+     *
+     * Matches ONLY a genuine tombstone — `isActive = false` AND `deletedAt IS NOT
+     * NULL` — so a merely *deactivated* row (isActive=false, no deletedAt) is never
+     * silently "restored". Pinned to the caller's own org (orgId-less sysadmin
+     * context spans orgs, matching delete/update). Returns null when there is no
+     * such tombstone (already active, purged, or unknown) so the route can 404.
+     * A unique-key collision (a live row already holds the key) surfaces as the
+     * driver's unique-violation for the route to map to 409 — in practice the
+     * tombstone IS the key holder, so this is defensive.
+     */
+    /** Conditions matching a GENUINE tombstone (`isActive=false` AND `deletedAt IS
+     *  NOT NULL`), optionally pinned to `id` and/or `orgId`. Single source of truth
+     *  for restore/findDeletedById/findDeleted so the "what is a tombstone" rule
+     *  lives in one place. */
+    private tombstoneConditions;
+    restore(id: string, orgId: string, userId: string): Promise<TEntity | null>;
+    /**
+     * Read a soft-deleted entity by id (the inverse of the default `isActive=true`
+     * reads) — used by restore routes to load the tombstone for access-control
+     * gating before restoring. Returns null unless the row exists AND is a genuine
+     * tombstone (`isActive=false` + `deletedAt IS NOT NULL`).
+     */
+    findDeletedById(id: string, orgId?: string): Promise<TEntity | null>;
+    /**
+     * List an org's soft-deleted tombstones (`isActive=false` + `deletedAt IS NOT
+     * NULL`), most-recently-deleted first — powers the "recently deleted" restore
+     * UI. Returns `[]` for entities without a soft-delete lifecycle. `limit` is
+     * clamped to [1, 200] to keep the response bounded (the retention sweep hard-
+     * deletes old tombstones anyway, so this is a short, self-limiting list).
+     */
+    findDeleted(orgId: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<TEntity[]>;
+    /**
+     * Hard-delete a batch of tombstones whose purge deadline has passed
+     * (`deletedAt IS NOT NULL AND purge_after < now`). Batched (`limit`) so a
+     * sweep tick stays bounded; the per-service sweep loops until a tick returns
+     * `< limit`. Runs across ALL orgs, so callers MUST invoke it from a sysadmin
+     * scope (`runSoftDeletePurge` establishes one). `onBeforePurge(ids, tx)` tears
+     * down dependents lacking ON DELETE CASCADE inside the same tx; `onAfterPurge`
+     * handles external side-effects.
+     * Returns the number of rows purged. No-op (0) for entities without the columns.
+     */
+    purgeExpired(now: Date, limit?: number): Promise<number>;
 }