@pipeline-builder/pipeline-data 0.0.1

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

@@ -0,0 +1,343 @@
+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
+ * entity generics, so an explicit cast is needed. Centralised here so every
+ * call-site stays one-liner clean and the cast is documented in one place.
+ */
+export declare function drizzleRows<T>(rows: unknown): T[];
+/** Cast a Drizzle aggregate result to extract `[{ count: number }]`. */
+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
+ */
+export interface BaseEntity {
+    id: string;
+    orgId: string;
+    isDefault: boolean;
+    createdAt: Date;
+    updatedAt: Date;
+    createdBy: string;
+    updatedBy: string;
+    [key: string]: unknown;
+}
+/**
+ * Pagination and sorting options
+ */
+export interface QueryOptions {
+    limit?: number;
+    offset?: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    /** When true, runs a separate COUNT(*) query to include exact total. Default: false. */
+    includeTotal?: boolean;
+    /** Cursor-based pagination: fetch rows after this cursor value (uses sortBy column). */
+    cursor?: string;
+    /** Sparse fieldset: column names to select. Returns all columns when omitted. */
+    fields?: string[];
+}
+/**
+ * Paginated result with metadata
+ */
+export interface PaginatedResult<T> {
+    data: T[];
+    /** Total count of matching entities. Only present when includeTotal is true. */
+    total?: number;
+    limit: number;
+    offset: number;
+    hasMore: boolean;
+    /** 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;
+    /**
+     * Typed column view of {@link schema}. `PgTable` exposes no static columns, so
+     * the base class previously reached for `(this.schema as any).id` etc. at each
+     * use; centralize that single unavoidable cast here so callers get structured,
+     * typed access instead. `visibility` is optional (not every entity has it)
+     * and the index signature covers dynamic sparse-fieldset column lookup.
+     */
+    private get cols();
+    /**
+     * Build SQL conditions for filtering entities.
+     * `parentOrgId` (org → team hierarchy) is optional and only honored by
+     * services that opt into parent-inherited visibility (e.g. plugins).
+     */
+    protected abstract buildConditions(filter: Partial<TFilter>, orgId?: string, parentOrgId?: string): SQL[];
+    /** Get the schema column for sorting by field name */
+    protected abstract getSortColumn(sortBy: string): AnyColumn | null;
+    /** Get the project column for setDefault scoping (null if entity has no project scope) */
+    protected abstract getProjectColumn(): AnyColumn | null;
+    /**
+     * Get the tenant org-id column. Used both to scope `setDefault` and to pin
+     * every write (update/delete/bulkDelete) to the caller's own org — so it MUST
+     * be the tenant `orgId` column, not a display/name column.
+     */
+    protected abstract getOrgColumn(): AnyColumn;
+    /** Get the unique constraint columns for onConflictDoUpdate */
+    protected abstract get conflictTarget(): AnyColumn[];
+    private readonly _logger;
+    constructor();
+    /** Build conditions for a single entity by ID.
+     *  `parentOrgId` widens visibility to a parent org's public rows (org → team
+     *  hierarchy) — same opt-in semantics as `find`/`findPaginated`. Omitted by the
+     *  write path (`writeConditions`), which must stay own-org scoped. */
+    private idConditions;
+    /**
+     * Conditions for a MUTATION (update/delete) of a single entity.
+     *
+     * `idConditions` reuses the READ access-control clause, which also matches
+     * system-org / other-org PUBLIC records — so without an extra ownership pin any
+     * tenant could update or soft-delete another org's (or the system org's) public
+     * records. AND a strict `orgId === caller` predicate: the read clause's
+     * public-OR branch requires `org_id = 'system'`, which then can't be satisfied,
+     * leaving only own-org rows. orgId-less (sysadmin) context keeps full access.
+     */
+    private writeConditions;
+    /** Exact id equality, lower-cased to match `buildIdFilter`'s full-UUID branch.
+     *  `schema` is typed `PgTable` (no static `.id`), so cast — same pattern the
+     *  sort/default helpers use for column access. */
+    private exactIdCondition;
+    /** Called after a new entity is created */
+    protected onAfterCreate(_entity: TEntity, _userId: string): Promise<void>;
+    /** Called after an entity is updated */
+    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
+     * run under sysadmin context — the access-control WHERE clause (own + parent +
+     * system public, built server-side from a trusted JWT claim) is then the
+     * authoritative tenancy gate. Without `parentOrgId` it stays RLS-scoped.
+     *
+     * INVARIANT (why the sysadmin bypass is safe): the WHERE clause is always
+     * server-built by `buildConditions(filter, orgId, parentOrgId)` from values
+     * derived from the validated JWT (`orgId` = active org, `parentOrgId` = the
+     * active org's parent). None of them is a raw user-supplied predicate, so the
+     * bypass only ever widens the read to the caller's own subtree + system public
+     * rows — it can NOT be steered at an arbitrary org. NOTE: this does remove the
+     * RLS backstop for the widened read; a single-GUC `app.org_id` can't express
+     * the "own OR parent OR system" set the policy would need, so replacing the
+     * bypass would require a tenancy-layer change (e.g. a multi-org RLS policy).
+     * Deferred deliberately — do not swap this for a blanket bypass without
+     * re-checking the WHERE is still fully server-built.
+     */
+    private runRead;
+    /**
+     * Find entities matching filter criteria
+     *
+     * @param filter - Filter criteria
+     * @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
+     *
+     * @param filter - Filter criteria
+     * @param orgId - User's organization ID (optional — omit for anonymous/system-public-only access)
+     * @param options - Pagination and sorting options
+     */
+    findPaginated(filter: Partial<TFilter>, orgId?: string, options?: QueryOptions, parentOrgId?: string): Promise<PaginatedResult<TEntity>>;
+    /**
+     * Build a column selection map for sparse fieldsets.
+     * Falls back to full select if no matching columns found.
+     *
+     * `sortBy` (when set) is always folded into the projection even if the caller's
+     * `fields` omits it — cursor pagination reads the next cursor from the sort
+     * column's value on the last row, so dropping it from the SELECT would yield an
+     * undefined cursor and stall paging. Included the same way `id` always is.
+     */
+    private buildFieldSelect;
+    /**
+     * Count entities matching filter criteria
+     *
+     * @param filter - Filter criteria
+     * @param orgId - User's organization ID (optional — omit for anonymous/system-public-only access)
+     * @param parentOrgId - Org → team hierarchy: widen the count to the parent org's
+     *   public rows. MUST mirror `find`/`findPaginated`'s widening (same
+     *   `buildConditions` args + sysadmin-scoped read via `runRead`) so a paged
+     *   list's `total` matches the rows a widened `find()` returns — otherwise the
+     *   count omits the parent's rows and reports a narrower total than the data set.
+     */
+    count(filter: Partial<TFilter>, orgId?: string, parentOrgId?: string): Promise<number>;
+    /**
+     * Find a single entity by ID
+     *
+     * @param id - Entity ID
+     * @param orgId - User's organization ID (optional — omit for anonymous/system-public-only access)
+     * @param parentOrgId - Org → team hierarchy: widen visibility to the parent
+     *   org's public rows (so a team can fetch a parent's public entity by id).
+     *   Same opt-in + sysadmin-scoped read as `find`/`findPaginated`; the
+     *   access-control WHERE clause is the authoritative tenancy gate.
+     */
+    findById(id: string, orgId?: string, parentOrgId?: string): Promise<TEntity | null>;
+    /**
+     * Defense-in-depth tenant stamp. RLS is in owner-bypass mode, so the app layer
+     * is the only tenant gate on writes. A NON-sysadmin caller may only write into
+     * its OWN org, so pin the row to the trusted tenant-context org.
+     *
+     * The stamp fires whenever the payload's `orgId` differs from the context org —
+     * which covers BOTH a forged/mismatched `data.orgId` AND an ABSENT one. The
+     * absent case is the important tenant-boundary fix: the `org_id` column DEFAULTs
+     * to `SYSTEM_ORG_ID` (schema/pipeline.ts, schema/plugin.ts), so an insert that
+     * omits `orgId` would otherwise land the tenant's row in the public system
+     * catalog — a cross-tenant fail-open. Always injecting `ctx.orgId` closes it.
+     *
+     * Sysadmin (and out-of-context worker/system paths, where `getTenantContext()`
+     * is undefined) keep the supplied org, matching the RLS policy
+     * `current_is_sysadmin() OR org_id = current_org_id()`.
+     */
+    protected enforceOrgId<T>(data: T, isCreate?: boolean): T;
+    /**
+     * Create a new entity
+     */
+    create(data: TInsert, userId: string): Promise<TEntity>;
+    /**
+     * Update an existing entity
+     */
+    update(id: string, data: Partial<TUpdate>, orgId: string, userId: string): Promise<TEntity | null>;
+    /**
+     * Delete an entity (soft delete by setting isActive = false)
+     */
+    delete(id: string, orgId: string, userId: string): Promise<TEntity | null>;
+    /**
+     * Set an entity as the default for a project/organization scope.
+     * Marks all other entities as non-default, then sets the specified entity.
+     * Uses a transaction to ensure atomicity.
+     */
+    setDefault(project: string, org: string, id: string, userId: string): Promise<TEntity>;
+    /**
+     * Update multiple entities matching filter
+     */
+    updateMany(filter: Partial<TFilter>, data: Partial<TUpdate>, orgId: string, userId: string): Promise<TEntity[]>;
+    /**
+     * Create multiple entities in a single batch insert.
+     * Uses upsert (onConflictDoUpdate) — all rows are inserted in one query per chunk.
+     * Chunks of 100 to stay within PostgreSQL parameter limits.
+     */
+    /**
+     * Build the `onConflictDoUpdate` SET for a bulk upsert. Unlike a single-row
+     * create (which can spread the one row's data), a batched insert has many rows,
+     * so each updatable column is written from `excluded.*` (the would-be-inserted
+     * value) — otherwise an existing row's fields are silently discarded and only
+     * timestamps bump. Skips identity/immutable (`id`, `createdAt`, `createdBy`)
+     * and the conflict-target columns; `updatedAt`/`updatedBy` get the fresh values.
+     */
+    private buildBulkUpsertSet;
+    bulkCreate(items: TInsert[], userId: string): Promise<TEntity[]>;
+    /**
+     * Soft-delete multiple entities by IDs in a single batch operation.
+     */
+    bulkDelete(ids: string[], orgId: string, userId: string, 
+    /** When true, only PRIVATE records are deleted — mirrors the single-delete
+     *  `requirePublicAccess` gate so a non-sysadmin can't bulk-delete public
+     *  (shared/sysadmin-managed) records. No-op for entities without an
+     *  `visibility` 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>;
+    /**
+     * On-demand hard-delete of a SINGLE tombstone by id — the manual counterpart
+     * to the retention sweep's `purgeExpired`. Permanently removes the row ONLY
+     * when it is a genuine tombstone (`isActive=false` + `deletedAt IS NOT NULL`),
+     * optionally pinned to `orgId` (an orgId-less sysadmin context spans orgs,
+     * matching restore/delete). Runs the same `onBeforePurge` dependent teardown
+     * inside the tx and the same `onAfterPurge` side-effects as the sweep.
+     *
+     * Ignores `purgeAfter`: a manual purge finalizes an already-soft-deleted item
+     * immediately rather than waiting for the retention deadline. Returns the
+     * purged id, or null when there is no such tombstone (already active, purged,
+     * out of scope, or unknown) so the route can 404.
+     */
+    purgeById(id: string, orgId?: string): Promise<string | null>;
+}