@pipeline-builder/pipeline-data 3.4.113 → 3.4.114

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

@@ -110,6 +110,22 @@ 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 (best-effort) with the ids about to be hard-purged, BEFORE the
+     *  delete, so a subclass can tear down dependents that lack ON DELETE CASCADE.
+     *  Throwing aborts that batch's purge (rows stay tombstoned, retried next tick). */
+    protected onBeforePurge(_ids: string[]): 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. */
+    private purgeAfterStamp;
     /**
      * 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 +257,46 @@ 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.
+     */
+    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, parentOrgId?: 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;
+    }, parentOrgId?: string): 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 system
+     * (no-tenant) context. `onBeforePurge` tears down dependents lacking ON DELETE
+     * CASCADE (inside the 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>;
 }