@pipeline-builder/pipeline-data 4.1.24 → 4.1.25

package/lib/api/reporting/stakeholder/store.d.ts

@@ -0,0 +1,450 @@
+import type { ReportCadence, ReportDefinition, ReportPauseReason, ReportRecipient, ReportRun, ReportRunStatus, ReportScope, ReportShareLink, ReportTemplate } from '../../../database/schema/reporting-stakeholder.js';
+/** How long a freshly minted share link lives when the caller names no window. */
+export declare const DEFAULT_SHARE_LINK_TTL_DAYS = 30;
+/** The longest a share link may live. Beyond this it is a permanent URL. */
+export declare const MAX_SHARE_LINK_TTL_DAYS = 180;
+/** A recipient's verification link. Short: it is clicked within minutes or never. */
+export declare const VERIFICATION_TTL_MS: number;
+/**
+ * Bounces before an address is treated as undeliverable and skipped. Three, not
+ * one: a single bounce is often an out-of-office autoresponder or a full mailbox,
+ * and dropping a manager off the list for one of those is a silent failure.
+ */
+export declare const MAX_BOUNCES = 3;
+/** SHA-256 hex of a token. The only form any token is ever stored in. */
+export declare function hashToken(token: string): string;
+/** A fresh URL-safe token, and its hash. The raw value is returned exactly once. */
+export declare function mintToken(): {
+    token: string;
+    tokenHash: string;
+};
+/** What creating a definition needs. */
+export interface CreateDefinitionInput {
+    orgId: string;
+    name: string;
+    template: ReportTemplate;
+    sections: string[];
+    cadence: ReportCadence;
+    timezone: string;
+    weekStart: 'monday' | 'sunday';
+    scope: ReportScope;
+    recipients: string[];
+    autoSend: boolean;
+    ownerId: string;
+    createdBy: string;
+    nextRunAt?: Date | null;
+}
+/** The mutable half of a definition. */
+export interface UpdateDefinitionInput {
+    name?: string;
+    template?: ReportTemplate;
+    sections?: string[];
+    cadence?: ReportCadence;
+    timezone?: string;
+    weekStart?: 'monday' | 'sunday';
+    scope?: ReportScope;
+    recipients?: string[];
+    autoSend?: boolean;
+    isActive?: boolean;
+    pausedReason?: ReportPauseReason | null;
+    nextRunAt?: Date | null;
+}
+/** A share link plus the one-time token, returned only from the mint call. */
+export interface MintedShareLink {
+    link: ReportShareLink;
+    /** Shown once. Never stored, never logged, never in a response again. */
+    token: string;
+}
+/** What the public route needs: the link, its run, and the owning org. */
+export interface ResolvedShareLink {
+    link: ReportShareLink;
+    run: ReportRun;
+}
+export declare class StakeholderReportStore {
+    createDefinition(input: CreateDefinitionInput): Promise<ReportDefinition>;
+    listDefinitions(orgId: string): Promise<ReportDefinition[]>;
+    getDefinition(orgId: string, id: string): Promise<ReportDefinition | null>;
+    /** Throws {@link NotFoundError} rather than returning null, for route bodies. */
+    requireDefinition(orgId: string, id: string): Promise<ReportDefinition>;
+    updateDefinition(orgId: string, id: string, patch: UpdateDefinitionInput, updatedBy: string): Promise<ReportDefinition>;
+    /**
+     * Hand a definition to a new owner. The owner is who a scheduled run is
+     * authorized AS, so this is a privilege move, not a metadata edit — the route
+     * checks the new owner is a live member of the org before calling.
+     */
+    transferOwner(orgId: string, id: string, newOwnerId: string, actorId: string): Promise<ReportDefinition>;
+    /**
+     * Pause every definition a user owns, with the reason recorded. Called when the
+     * owner is deactivated or loses `reports:author` — a report must stop when the
+     * person accountable for it can no longer see the data behind it.
+     *
+     * Returns the paused definitions so the caller can notify an org admin: a
+     * silently stopped weekly report is discovered by a manager not receiving it.
+     */
+    pauseDefinitionsForOwner(orgId: string, ownerId: string, reason: ReportPauseReason): Promise<ReportDefinition[]>;
+    deleteDefinition(orgId: string, id: string, deletedBy: string): Promise<void>;
+    /**
+     * Insert a run for a period, or return the existing one.
+     *
+     * Idempotent on (definition, periodStart, version): a retry, a catch-up pass
+     * and a manual backfill can all ask for the same period, and without this each
+     * would insert a row and the lead would review three copies. `onConflictDoNothing`
+     * plus a re-read is deliberate — the unique index is the arbiter, so two pods
+     * racing produce one row whichever wins.
+     */
+    createRun(input: {
+        orgId: string;
+        definitionId: string;
+        periodStart: Date;
+        periodEnd: Date;
+        periodLabel: string;
+        version?: number;
+        status?: ReportRunStatus;
+        snapshot?: Record<string, unknown> | null;
+        failureReason?: string | null;
+    }): Promise<{
+        run: ReportRun;
+        created: boolean;
+    }>;
+    /** The next version number for a period: `max(version) + 1`. */
+    nextVersion(definitionId: string, periodStart: Date): Promise<number>;
+    /** Point an older run at the version that replaced it. */
+    supersede(orgId: string, oldRunId: string, newRunId: string): Promise<void>;
+    listRuns(orgId: string, definitionId: string, limit?: number): Promise<ReportRun[]>;
+    getRun(orgId: string, id: string): Promise<ReportRun | null>;
+    requireRun(orgId: string, id: string): Promise<ReportRun>;
+    /** Store a computed snapshot and move the run to `ready_for_review`. */
+    completeRun(orgId: string, id: string, snapshot: Record<string, unknown>, status?: ReportRunStatus): Promise<ReportRun>;
+    failRun(orgId: string, id: string, failureReason: string): Promise<void>;
+    /**
+     * Edit the lead's own words on a run that has NOT been published.
+     *
+     * Refused after publish: the notes are part of what the manager read, and a
+     * report whose narrative can be edited after delivery is a report whose
+     * delivered version cannot be reconstructed. Regenerating produces version N+1,
+     * which is the supported way to correct a published report.
+     */
+    setRunNotes(orgId: string, id: string, patch: {
+        leadNotes?: string;
+        aiDraft?: string;
+    }): Promise<ReportRun>;
+    /**
+     * Record what happened when a run was delivered.
+     *
+     * Deliberately NOT part of {@link setRunNotes}, which refuses a published run: delivery
+     * happens AT publish, so a method that refused published runs could never record it.
+     * This one writes exactly one column and nothing else, which is why it is safe to allow
+     * after publish — it cannot change a number a recipient has read.
+     */
+    recordDelivery(orgId: string, id: string, delivery: Record<string, unknown>): Promise<void>;
+    /**
+     * Publish a run.
+     *
+     * Conditional on the row still being unpublished (`published_at IS NULL`), so
+     * two clicks — or two tabs — produce one publish and one set of deliveries
+     * rather than two. A run with no snapshot cannot be published: there would be
+     * nothing for a recipient to read.
+     */
+    publishRun(orgId: string, id: string, publishedBy: string): Promise<{
+        run: ReportRun;
+        alreadyPublished: boolean;
+    }>;
+    /**
+     * Mint a read-only link to a published run. The raw token is returned here and
+     * nowhere else — only its hash is stored, so a database copy cannot be turned
+     * back into working URLs.
+     */
+    createShareLink(input: {
+        orgId: string;
+        runId: string;
+        createdBy: string;
+        ttlDays?: number;
+        redactNames?: boolean;
+        now?: Date;
+    }): Promise<MintedShareLink>;
+    listShareLinks(orgId: string, runId: string): Promise<ReportShareLink[]>;
+    revokeShareLink(orgId: string, id: string, revokedBy: string): Promise<ReportShareLink>;
+    /** Revoke every live link to any run of a definition. Used on delete. */
+    revokeLinksForDefinition(orgId: string, definitionId: string, revokedBy: string): Promise<number>;
+    /**
+     * Resolve a share token to its link and run, for the UNAUTHENTICATED public
+     * route.
+     *
+     * This is the one read in this module that runs as sysadmin, and the reason is
+     * structural: the reader holds a token and nothing else — no account, no org,
+     * no JWT — so there is no tenant context for RLS to scope by, and the org can
+     * only be learned FROM the row. The escalation is kept as narrow as the problem:
+     *
+     *  - The sysadmin scope covers the token-hash lookup ONLY. The run is read back
+     *    under the link's OWN org, so a bug in the run query cannot reach another
+     *    tenant's rows.
+     *  - The lookup is by a 256-bit hash on a unique index. It is not a filter a
+     *    caller can widen — there is no other predicate to influence.
+     *  - Expired and revoked links resolve to null here, so the caller cannot
+     *    accidentally serve one by forgetting a check.
+     *
+     * Returns null for every failure — unknown, revoked, expired, or pointing at a
+     * run that is no longer published — so the route answers one indistinguishable
+     * 404 and a holder of a dead link learns nothing about which of those it was.
+     */
+    resolveShareLink(token: string, now?: Date): Promise<ResolvedShareLink | null>;
+    /**
+     * Count one human view of a shared report.
+     *
+     * Separate from {@link resolveShareLink} so the route can serve a link preview,
+     * a HEAD probe or a mail scanner's fetch WITHOUT counting it — a view count that
+     * jumps the moment a link is pasted into Slack tells the lead their manager read
+     * the report when nobody has.
+     */
+    recordShareView(link: ReportShareLink, now?: Date): Promise<void>;
+    /**
+     * Add (or re-add) a delivery address.
+     *
+     * Upserts on (org, email) and deliberately does NOT reset `unsubscribed_at` or
+     * `verified_at`: a lead must not be able to undo someone's unsubscribe by
+     * removing and re-adding them, and an address already verified should not have
+     * to confirm twice. A verification token is minted only when the address is not
+     * yet verified.
+     */
+    upsertRecipient(input: {
+        orgId: string;
+        email: string;
+        displayName?: string;
+        createdBy: string;
+        /** Set when an admin pre-approved an out-of-domain address. */
+        approvedBy?: string | null;
+        /** Org members skip verification — they already authenticated to this org. */
+        preVerified?: boolean;
+        now?: Date;
+    }): Promise<{
+        recipient: ReportRecipient;
+        verificationToken?: string;
+    }>;
+    listRecipients(orgId: string): Promise<ReportRecipient[]>;
+    getRecipients(orgId: string, ids: string[]): Promise<ReportRecipient[]>;
+    /** Mint a fresh verification token for a recipient that has not confirmed yet. */
+    resendVerification(orgId: string, id: string): Promise<{
+        recipient: ReportRecipient;
+        token: string;
+    }>;
+    /**
+     * Confirm an address from the emailed token. Cross-org by necessity (the person
+     * clicking has no session), so it runs as sysadmin over a unique 256-bit hash —
+     * the same shape, and the same reasoning, as {@link resolveShareLink}.
+     *
+     * The token is CONSUMED: it is cleared on success, so a forwarded confirmation
+     * link cannot be replayed by whoever the mail was forwarded to.
+     */
+    verifyRecipientByToken(token: string, now?: Date): Promise<ReportRecipient | null>;
+    /** Honour an unsubscribe across every definition in the org. */
+    unsubscribeByEmail(orgId: string, email: string, now?: Date): Promise<boolean>;
+    /**
+     * Honour an unsubscribe from the link in a report email.
+     *
+     * Looked up by TOKEN across orgs, as sysadmin, for the same reason the share-link
+     * resolve is: the person clicking has no account and no tenant, and the token is the
+     * only thing that identifies the row. It is the narrowest possible shape — one indexed
+     * lookup, one column written, nothing returned to the caller but whether a row
+     * matched.
+     *
+     * Idempotent. A mail client that sends the one-click POST twice, or a manager who
+     * clicks again months later, gets the same answer rather than an error page — the
+     * second call finds the row already unsubscribed and reports success, because from the
+     * clicker's point of view it is.
+     */
+    unsubscribeByToken(token: string, now?: Date): Promise<boolean>;
+    /** Record a delivery bounce. At {@link MAX_BOUNCES} the address is skipped. */
+    recordBounce(orgId: string, email: string, now?: Date): Promise<number>;
+    deleteRecipient(orgId: string, id: string, deletedBy: string): Promise<void>;
+    /**
+     * Is this address deliverable right now? The single place the delivery rules
+     * live, so the scheduler and the UI agree about why a recipient is being
+     * skipped.
+     */
+    deliverability(recipient: ReportRecipient): {
+        deliverable: boolean;
+        reason?: string;
+    };
+    /**
+     * The org's admin-owned report policy. Read through the reporting settings row,
+     * which may not exist — an org that has never configured anything gets the
+     * closed defaults (no external sharing, no external domains, approval required).
+     */
+    getReportPolicy(orgId: string): Promise<{
+        externalSharing: boolean;
+        recipientDomains: string[] | null;
+        requireApproval: boolean;
+        defaultTimezone: string | null;
+        defaultWeekStart: string | null;
+    }>;
+    setReportPolicy(orgId: string, patch: {
+        externalSharing?: boolean;
+        recipientDomains?: string[] | null;
+        requireApproval?: boolean;
+        defaultTimezone?: string | null;
+        defaultWeekStart?: string | null;
+    }): Promise<void>;
+    /**
+     * Apply a Stakeholder Reports entitlement change from billing: pause everything, or
+     * resume what the lapse paused.
+     *
+     * THE WATERMARK AND THE WORK ARE ONE TRANSACTION, and the watermark update is what
+     * serializes concurrent pushes. Billing's legs are best-effort and retried, so
+     * "lapsed at 10:00" and "renewed at 10:05" can arrive in either order; applying the
+     * older one last would leave a lapsed account producing reports, or a paying one
+     * paused. The conditional update takes a row lock on `dora_settings`, so a second
+     * push waits and then sees the newer watermark — no advisory lock needed.
+     *
+     * RESUME IS SCOPED TO `entitlement`. It must not un-pause a definition whose OWNER was
+     * deactivated or who lost the permission: those are different problems with different
+     * fixes, and resuming one by fixing the other is how a report starts running under
+     * somebody who left.
+     *
+     * `nextRunFor` is a callback because the period arithmetic needs each definition's
+     * cadence, timezone and week start, and that belongs with the period resolver rather
+     * than the store — while the write still has to happen inside this transaction.
+     *
+     * This leg makes the change IMMEDIATE; it is not what makes it safe. Every scheduled
+     * run re-checks the entitlement against platform anyway, so a lost push delays
+     * enforcement to the next run rather than defeating it.
+     */
+    syncReportEntitlement(orgId: string, entitled: boolean, opts?: {
+        occurredAt?: Date;
+        nextRunFor?: (d: ReportDefinition) => Date;
+        now?: Date;
+    }): Promise<{
+        skipped: boolean;
+        paused: ReportDefinition[];
+        resumed: ReportDefinition[];
+    }>;
+    /**
+     * Claim the org's ONE free preview, or report that it is already spent.
+     *
+     * A CONDITIONAL insert-or-update, not read-then-write: two tabs clicking "see a sample"
+     * at the same moment must produce one preview, and a check followed by a separate write
+     * has a window between them wide enough for both to pass. `WHERE report_preview_used_at
+     * IS NULL` on the update, and `onConflictDoUpdate` for the row that may not exist yet,
+     * make the claim itself the guard.
+     *
+     * Returns whether THIS caller won it. A loser is told the preview is spent, which is
+     * the truth and is also the upsell.
+     */
+    claimReportPreview(orgId: string, now?: Date): Promise<boolean>;
+    /** Whether the org has already spent its free preview. */
+    reportPreviewUsed(orgId: string): Promise<boolean>;
+    /**
+     * Is `email` admissible as a recipient for this org, and does it need an
+     * admin's approval first?
+     *
+     * `orgMemberEmails` is the set of addresses that already authenticate to this
+     * org — they are always admissible and never need verification, because the org
+     * has already established they belong to it. Everything else is measured against
+     * the allowed-domain list, and a NULL list means "no external addresses at all",
+     * not "any address": the closed reading is the one that cannot leak a report by
+     * an admin forgetting to configure something.
+     */
+    admitRecipient(email: string, policy: {
+        recipientDomains: string[] | null;
+        requireApproval: boolean;
+    }, orgMemberEmails: ReadonlySet<string>): {
+        admitted: true;
+        member: boolean;
+        needsApproval: boolean;
+    } | {
+        admitted: false;
+        reason: string;
+    };
+    /**
+     * Hard-delete expired tombstones across every org, for the shared soft-delete
+     * sweep. Runs inside the sweep's own sysadmin scope.
+     *
+     * Runs go first: a purged definition with orphaned runs would leave snapshots
+     * nothing can reach, and share links are deleted with their runs so a purge
+     * cannot leave a live token pointing at a row that no longer exists.
+     */
+    purgeableEntities(): Array<{
+        name: string;
+        purgeExpired(now: Date, limit?: number): Promise<number>;
+    }>;
+    private purgeRuns;
+    private purgeDefinitions;
+    private purgeRecipients;
+    /** Every definition the owner must be re-checked for, for the pause sweep. */
+    listOwnedDefinitions(orgId: string, ownerId: string): Promise<ReportDefinition[]>;
+    /**
+     * Definitions whose next run is due, across every org.
+     *
+     * Runs as SYSADMIN, because the scheduler has no tenant: it is looking for work
+     * in orgs it has not been told about. This is the one read here that crosses org
+     * boundaries, and it is kept to the narrowest possible shape — the rows needed to
+     * claim and execute, ordered oldest-due first so a backlog drains in order rather
+     * than starving whichever org sorts last by id.
+     *
+     * `limit` is the per-cycle ceiling: a cycle that tried to drain everything would
+     * hold the leader lock for as long as the slowest org's compose takes, times the
+     * number of definitions.
+     */
+    dueDefinitions(now: Date, limit: number): Promise<ReportDefinition[]>;
+    /**
+     * Claim a due definition by advancing its `nextRunAt`, but only if it still holds
+     * the value the scan saw.
+     *
+     * THE CONDITIONAL UPDATE IS THE CONCURRENCY GUARD, not the leader lock. The lock
+     * stops two replicas sweeping in the same window; it does not stop a sweep that
+     * outlives its lock TTL from overlapping the next leader's sweep, and both would
+     * then select the same still-due definition. Without the `next_run_at = <seen>`
+     * predicate each would advance the schedule and each would compose and DELIVER a
+     * report — the same manager gets the same report twice, from two pods, which is
+     * the failure everyone notices.
+     *
+     * Runs as sysadmin for the same reason as the scan, and returns whether the claim
+     * won so the caller can simply skip a lost race.
+     */
+    claimDefinition(id: string, seenNextRunAt: Date, nextRunAt: Date, now?: Date): Promise<boolean>;
+    /**
+     * Set (or clear) a definition's `nextRunAt` without claiming it.
+     *
+     * Used when a definition is created, resumed, or has its cadence/timezone changed
+     * — the schedule has to be re-derived from the calendar rather than left at
+     * whatever the old cadence produced.
+     */
+    setNextRun(orgId: string, id: string, nextRunAt: Date | null): Promise<void>;
+    /**
+     * Pause ONE definition with the reason, from the scheduler.
+     *
+     * Separate from {@link pauseDefinitionsForOwner} because the trigger is different:
+     * that one is a membership change affecting every definition a person owns, this
+     * one is a per-run recheck that failed. Clears `nextRunAt` so a paused definition
+     * stops appearing in the due scan at all, rather than being re-claimed and
+     * re-rejected every cycle.
+     *
+     * Runs as sysadmin: the caller is the scheduler, which has no tenant, and the id
+     * came from its own cross-org scan.
+     */
+    pauseDefinition(id: string, reason: ReportPauseReason): Promise<void>;
+    /**
+     * Resume a paused definition, clearing the reason and re-deriving its schedule.
+     *
+     * `nextRunAt` is supplied by the caller rather than computed here: the period
+     * arithmetic needs the definition's timezone and week start, and that belongs with
+     * the period resolver, not the store.
+     */
+    resumeDefinition(orgId: string, id: string, nextRunAt: Date, actorId: string): Promise<ReportDefinition>;
+    /**
+     * Pause every ACTIVE definition in an org, with the reason.
+     *
+     * The entitlement lapse leg: billing tells reporting the add-on is gone, and every
+     * definition in the account stops. Returns the rows so the caller can notify.
+     */
+    pauseDefinitionsForOrg(orgId: string, reason: ReportPauseReason): Promise<ReportDefinition[]>;
+    /**
+     * Every definition in an org paused for `reason`, for the resume leg.
+     *
+     * Scoped to the reason on purpose: re-subscribing must not un-pause a definition
+     * whose owner was deactivated. Those are different problems with different fixes,
+     * and resuming one by fixing the other is how a report starts running under a
+     * person who left.
+     */
+    definitionsPausedFor(orgId: string, reason: ReportPauseReason): Promise<ReportDefinition[]>;
+}
+export declare const stakeholderReportStore: StakeholderReportStore;