@webiny/api-workflows 0.0.0-unstable.0156a4c312

package/domain/review/Review.d.ts

@@ -0,0 +1,258 @@
+import { Result } from "@webiny/feature/api";
+import type { Workflow } from "../../domain/workflow/types.js";
+import type { Actor, AiIssue, ReviewData, ReviewPick, ReviewStep, ReviewSystemWorkflow, StepAssignmentResolution, TargetContext } from "./types.js";
+import type { ReviewFact } from "./facts.js";
+import { ReviewActorNotUserError, ReviewAlreadyOwnerError, ReviewInvalidStateError, ReviewNotCandidateError, ReviewNotOwnerError, ReviewRequesterCannotReviewError, ReviewStepNotCurrentError, ReviewStepNotReassignableError, ReviewStepNotTakeableError, ReviewValidationError } from "./errors.js";
+/** A requested title, trimmed, has at least this many characters (D100, D135). */
+export declare const REVIEW_TITLE_MIN_LENGTH = 5;
+/** A rejection comment, trimmed, has at least this many characters (D100). */
+export declare const REJECT_COMMENT_MIN_LENGTH = 10;
+export interface ReviewRequestParams {
+    id: string;
+    workflow: Workflow;
+    model: string;
+    targetId: string;
+    targetRevisionId: string;
+    /** The target's title; the review title when `requestedTitle` is missing or blank. */
+    title: string;
+    /** The title the requester typed (D135); trimmed, at least 5 characters when given. */
+    requestedTitle?: string | null;
+    targetContext: TargetContext;
+    picks: ReviewPick[];
+    requester: Actor;
+    now: string;
+}
+export interface ReviewReachParams {
+    resolution: StepAssignmentResolution;
+    /** Who caused the step to be reached. */
+    actor: Actor;
+    now: string;
+}
+export interface ReviewStepParams {
+    /** The step the caller acts on; must be the current step (R17). */
+    stepId: string;
+}
+/** Who acts on the step. The checks take this; the transitions add `now`. */
+export interface ReviewActorCheckParams extends ReviewStepParams {
+    actor: Actor;
+    /** Teams of the actor, resolved by the caller (the aggregate never reads identity, D5). */
+    actorTeamIds: string[];
+}
+export interface ReviewActorParams extends ReviewActorCheckParams {
+    now: string;
+}
+export interface ReviewTakeOverParams extends ReviewActorParams {
+    /** D111: whether the previous owner is told; omitted means true. Carried on the fact, never stored. */
+    notifyPreviousOwner?: boolean;
+}
+/** `actorTeamIds` is not read by approve or reject: only the owner decides (spec 5.1). */
+export interface ReviewDecisionParams extends ReviewActorParams {
+    comment: string | null;
+    /** The findings of an AI decision, stored on the step (R171); omitted means none. */
+    issues?: AiIssue[];
+}
+export interface ReviewCancelParams {
+    actor: Actor;
+    now: string;
+    /** Recorded on the cancelled fact (D134); omitted for a normal cancel. */
+    reason?: string | null;
+}
+export interface ReviewReassignToCheckParams extends ReviewStepParams {
+    /** The chosen user; the current owner is refused (R126). */
+    userId: string;
+}
+export interface ReviewReassignParams extends ReviewStepParams {
+    /** Who reassigns; recorded as `by` (D127). */
+    actor: Actor;
+    /** The chosen user, validated by the caller (R112, R119). */
+    owner: Actor;
+    now: string;
+}
+export interface ReviewReachRunParams {
+    /** Who caused the step to be reached: the requester or the approver of the previous step. */
+    actor: Actor;
+    /** The automation actor (R141); `getAutomationActor(requester)`. */
+    owner: Actor;
+    /** The background task started for this attempt; `null` when none was started. */
+    taskId: string | null;
+    now: string;
+}
+export interface ReviewFailParams extends ReviewStepParams {
+    /** A fixed reason text (R146); stored in the step's `comment` and on its `runs` entry. */
+    reason: string;
+    now: string;
+}
+export interface ReviewRestartParams extends ReviewStepParams {
+    /** Who restarts; recorded on the fact (the wrapper checked it, D132). */
+    actor: Actor;
+    now: string;
+}
+export type ReviewReviewerError = ReviewInvalidStateError | ReviewStepNotCurrentError | ReviewActorNotUserError | ReviewRequesterCannotReviewError | ReviewNotCandidateError;
+export type ReviewTakeOverError = ReviewReviewerError | ReviewAlreadyOwnerError | ReviewStepNotTakeableError;
+export type ReviewDecisionError = ReviewInvalidStateError | ReviewStepNotCurrentError | ReviewNotOwnerError;
+/** Reject adds the comment rule (D100) to the decision rules. */
+export type ReviewRejectError = ReviewDecisionError | ReviewValidationError;
+export type ReviewReassignError = ReviewInvalidStateError | ReviewStepNotCurrentError | ReviewStepNotReassignableError;
+/** With a chosen user, the reassign check adds the same-owner rule (R126). */
+export type ReviewReassignCheckError = ReviewReassignError | ReviewAlreadyOwnerError;
+/** The transition adds the requester rule to the check (spec 5.1). */
+export type ReviewReassignTransitionError = ReviewReassignCheckError | ReviewRequesterCannotReviewError;
+/** Fail needs the current step; the check for a finished review is `InvalidState` (R140). */
+export type ReviewFailError = ReviewInvalidStateError | ReviewStepNotCurrentError;
+/** Restart needs a failed current step (R140, R153). */
+export type ReviewRestartError = ReviewInvalidStateError | ReviewStepNotCurrentError;
+/**
+ * One run of a workflow on one target revision (spec 3, 4.2, 5.1). Transitions take an explicit
+ * actor and `now`, never read identity, and record facts; `ReviewSaver` persists the review and
+ * publishes one event per fact.
+ *
+ * Each transition has a pure `check*` twin that runs the same private guard (R31), so viewer
+ * flags (spec 5.3) and the transitions cannot drift. Who may cancel or reassign is a permission
+ * rule, not a domain rule: the app wrappers decide it with `canCancelByPermission` and
+ * `canReassignByPermission` (D132, R41) and leave the state errors to these guards.
+ */
+export declare class Review {
+    private readonly data;
+    private readonly facts;
+    private constructor();
+    static fromData(data: ReviewData): Review;
+    static request(params: ReviewRequestParams): Result<Review, ReviewValidationError>;
+    get id(): string;
+    /**
+     * The step transitions act on: the first step that is not approved; `null` when all are.
+     * Not the persisted `ReviewData.currentStepId`, which keeps the last step after the final
+     * approval (D75).
+     */
+    get actionableStepId(): string | null;
+    toData(): ReviewData;
+    /**
+     * The requester is a user. AI and automation actors carry the requester's id (D58) but are not
+     * the requester.
+     */
+    isRequestedBy(actor: Actor): boolean;
+    /** The task running for the current step, if any: only an in-review step has one (R151). */
+    getRunningTaskId(): string | null;
+    /**
+     * The task of every attempt of every step, in step order: a step's earlier attempts first,
+     * oldest first, then its current one (R256).
+     */
+    getTaskIds(): string[];
+    /** The current step when it still has to be reached (spec 5.2). */
+    getStepToReach(): ReviewStep | null;
+    /** Reaches the `pending` current step of a review step; a run step is reached with `reachRun`. */
+    reach(params: ReviewReachParams): Result<void, ReviewInvalidStateError>;
+    /**
+     * Reaches the `pending` current step of an automation (spec 5.2, R140): the automation actor
+     * owns it at once, there is no pool and no assignment, and the id of the task started for it
+     * is stored. The caller triggered the task as the requester (R149) before saving.
+     */
+    reachRun(params: ReviewReachRunParams): Result<void, ReviewInvalidStateError>;
+    checkStart(params: ReviewActorCheckParams): Result<void, ReviewReviewerError>;
+    start(params: ReviewActorParams): Result<void, ReviewReviewerError>;
+    checkTakeOver(params: ReviewActorCheckParams): Result<void, ReviewTakeOverError>;
+    takeOver(params: ReviewTakeOverParams): Result<void, ReviewTakeOverError>;
+    checkApprove(params: ReviewActorCheckParams): Result<void, ReviewDecisionError>;
+    /**
+     * Owner (user, AI or automation) approves; the next step is reached by the caller (D6). The
+     * comment is optional: it is stored trimmed, and a blank one is stored as none.
+     */
+    approve(params: ReviewDecisionParams): Result<void, ReviewDecisionError>;
+    checkReject(params: ReviewActorCheckParams): Result<void, ReviewDecisionError>;
+    /**
+     * Owner rejects; reject is final for the revision (D10). Needs a comment of at least 10
+     * characters after trimming (D100), checked after the state and owner rules. `checkReject`
+     * (the viewer flag) does not take a comment, so it leaves this rule out.
+     */
+    reject(params: ReviewDecisionParams): Result<void, ReviewRejectError>;
+    checkCancel(): Result<void, ReviewInvalidStateError>;
+    /**
+     * Allowed while the review is in progress (D25, D75). Who may cancel (requester or
+     * `reassign`, D54) is checked by the app wrapper with `canCancelByPermission` (D132, R41).
+     */
+    cancel(params: ReviewCancelParams): Result<void, ReviewInvalidStateError>;
+    /**
+     * Reassign is possible on an `awaiting` or human-owned `inReview` step (D33). Who may reassign
+     * (`reassign`) is checked by the app wrapper with `canReassignByPermission` (D132, R41).
+     */
+    checkReassign(params: ReviewStepParams): Result<void, ReviewReassignError>;
+    /**
+     * `checkReassign` plus the same-owner rule for the chosen user (R126), so a reassign to the
+     * current owner is refused before the caller validates the user.
+     */
+    checkReassignTo(params: ReviewReassignToCheckParams): Result<void, ReviewReassignCheckError>;
+    /**
+     * Gives the step to the chosen user (spec 5.1, R119), through the same guard as
+     * `checkReassignTo`, with the new owner as the chosen user. The caller has validated the user
+     * like a pick (R112); the requester is refused here too, as on start and take over. An
+     * `awaiting` step starts now; an `inReview` step keeps its `startedOn`.
+     */
+    reassign(params: ReviewReassignParams): Result<void, ReviewReassignTransitionError>;
+    /**
+     * Fails the current step with a reason (spec 5.1, D8, R140): a `pending` or `inReview` step,
+     * the owner kept, `comment` = the reason. The review stays in progress; the step can be
+     * restarted. An already failed step is a no-op without a fact, so a late hook, stuck
+     * detection or a second failure path cannot fail it twice or overwrite its reason.
+     */
+    fail(params: ReviewFailParams): Result<void, ReviewFailError>;
+    /**
+     * Restart is possible on a failed current step only (spec 5.1, D8, R153); a rejected step is
+     * final (D10). Who may restart (requester or `reassign`) is checked by the app wrapper with
+     * `canRestartByPermission` (D132, R41).
+     */
+    checkRestart(params: ReviewStepParams): Result<void, ReviewRestartError>;
+    /**
+     * Moves the failed attempt into `runs` and makes the step `pending` again (R140, D82). The
+     * owner stays; the times of the attempt are cleared because a `pending` step has none. The
+     * caller re-reaches the step afterwards (`reachRun`).
+     */
+    restart(params: ReviewRestartParams): Result<void, ReviewRestartError>;
+    /**
+     * Called by the single save path before persisting (D19). Derives the review-level fields from
+     * the steps; `lastChangedOn` moves only when a review event happened (D119), and never
+     * backwards: it becomes the later of the stored value and the newest unpulled fact. Cancel
+     * moves it too: D119 does not list cancel, but a cancelled review leaves every list
+     * (`isActive: false`), so this is harmless and keeps the field monotonic.
+     */
+    prepareForSave(): void;
+    /**
+     * `system.workflow` for the target revision (spec 4.5). Derived from the steps, so it does not
+     * depend on `prepareForSave` having run.
+     */
+    getSystemWorkflow(): ReviewSystemWorkflow | null;
+    /** Returns and clears the facts recorded since the last call. */
+    pullFacts(): ReviewFact[];
+    private guardStart;
+    private guardTakeOver;
+    /** The current step (if any) of a review that can still be cancelled. */
+    private guardCancel;
+    private guardReassign;
+    /** The reassign guard, then the same-owner rule for the chosen user (R126). */
+    private guardReassignTo;
+    /** The current step when it can fail: `pending`, `inReview`, or already `failed` (R140). */
+    private guardFail;
+    /** The current step when it is failed (R140): rejected, in review and the rest are refused. */
+    private guardRestart;
+    /** Turns a guard's result into a check's result: same error, no step. */
+    private static toCheck;
+    /** The first step that is not approved; null when every step is approved. */
+    private findCurrentStep;
+    private getCurrentStepIn;
+    private createInvalidStateError;
+    /**
+     * Like `getCurrentStepIn`, for transitions that name the step they act on (R17). While the
+     * review is in progress, a `stepId` other than the current step fails with `StepNotCurrent`.
+     */
+    private getRequestedStepIn;
+    /** The requester never reviews their own content (spec 5.1): such an owner goes to the pool. */
+    private withoutRequesterOwner;
+    /**
+     * The step the review-level fields and `system.workflow` describe: the first step that is not
+     * approved, else the last step (after approve the last step stays current, after reject the
+     * rejecting step, D75). `null` for cancelled reviews. `request` guarantees at least one step.
+     */
+    private resolveCurrentStep;
+    private getOwnedStep;
+    private static deriveState;
+    /** Human actions: a user, not the requester, member of the step's candidate teams (spec 5.1). */
+    private checkReviewer;
+}