@pipeline-builder/pipeline-data 3.4.114 → 3.4.116

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;
@@ -113,10 +123,12 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
     /** 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 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>;
@@ -124,8 +136,11 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      *  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;
+     *  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
@@ -153,6 +168,12 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      * @param orgId - User's organization ID (optional — omit for anonymous/system-public-only access)
      */
     find(filter: Partial<TFilter>, orgId?: string, parentOrgId?: string): Promise<TEntity[]>;
+    /**
+     * Find the FIRST entity matching `filter` — a bounded (`LIMIT 1`) variant of
+     * `find` for the "match by filter, take one" read paths (e.g. `GET /find`), so
+     * they don't `SELECT` every matching org row just to return `[0]`.
+     */
+    findFirst(filter: Partial<TFilter>, orgId?: string, parentOrgId?: string): Promise<TEntity | null>;
     /**
      * Find entities with pagination and sorting
      *
@@ -210,7 +231,7 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      * is undefined) keep the supplied org, matching the RLS policy
      * `current_is_sysadmin() OR org_id = current_org_id()`.
      */
-    protected enforceOrgId(data: TInsert): TInsert;
+    protected enforceOrgId<T>(data: T): T;
     /**
      * Create a new entity
      */
@@ -270,6 +291,11 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      * 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`
@@ -277,7 +303,7 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
      * 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>;
+    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
@@ -288,14 +314,15 @@ export declare abstract class CrudService<TEntity extends BaseEntity, TFilter, T
     findDeleted(orgId: string, opts?: {
         limit?: number;
         offset?: number;
-    }, parentOrgId?: string): Promise<TEntity[]>;
+    }): 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.
+     * `< 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>;