@sonisoft/now-sdk-ext-core 6.15.1 → 6.16.0

package/dist/sn/flow/FlowDebugger.d.ts

@@ -0,0 +1,162 @@
+import type { ServiceNowInstance } from '../ServiceNowInstance.js';
+import type { FlowDebugBreakpoint, FlowDebugCancelResult, FlowDebugCommand, FlowDebugListOptions, FlowDebugLocation, FlowDebugRunToOptions, FlowDebugRunToResult, FlowDebugSession, FlowDebugSessionSummary, FlowDebugSnapshot, FlowDebugStartOptions, FlowDebugStepRef, FlowDebugWaitOptions } from './FlowDebugModels.js';
+/**
+ * Drives the Workflow Studio flow debugger (**Test ▸ Debug**) over REST.
+ *
+ * A debug run executes the flow or subflow for real, so its actions create and change records,
+ * and it holds a flow context open while paused. Every run must be ended: by running it to the
+ * end, or with {@link cancel}. {@link withSession}, and {@link runTo} by default, cancel the run
+ * for you; `runTo` with `after: 'resume'` or `'stay'` leaves it running or paused.
+ *
+ * The APIs are Workflow Studio's own (`/api/now/processflow/debug/…`), not a published REST
+ * contract. They work with the ordinary OAuth credential; no UI session is needed.
+ *
+ * Starting a run and sending a step command need execute permission under an installed policy;
+ * breakpoint changes and cancel need write, so a run stays cancellable under `--deny-execute`.
+ *
+ * Every method takes the **root** context id that {@link start} returns. When step into enters a
+ * subflow, the subflow runs in a child context of its own; commands, breakpoints and snapshots
+ * then apply to that child, and the snapshot's `chain` shows the path to it.
+ */
+export declare class FlowDebugger {
+    private readonly _logger;
+    private readonly _request;
+    private readonly _flows;
+    /** allowed-breakpoints never changes for a context, so it is read once. */
+    private readonly _allowed;
+    /**
+     * Poll schedule while waiting for a run to settle. `waitingSettleMs`: right after step into a
+     * subflow the parent is WAITING before its child context exists, so WAITING only counts as
+     * settled once it has lasted this long.
+     */
+    protected _poll: {
+        firstMs: number;
+        maxMs: number;
+        factor: number;
+        waitingSettleMs: number;
+    };
+    constructor(instance: ServiceNowInstance);
+    /**
+     * Start a debug run and wait for it to first pause.
+     *
+     * The flow's current draft is what runs, as in Workflow Studio. Inputs are checked against a
+     * subflow's declared inputs before anything is sent. If the run cannot be set up after it
+     * started, it is cancelled again before the error is thrown, and the error carries its
+     * `contextId` and whether the cancel worked.
+     *
+     * Under an installed policy, a run is only started when a cancel would also be permitted:
+     * starting needs execute, and breakpoints and cancel need write.
+     *
+     * A run normally pauses before its first step. One that fails or finishes first is returned
+     * as it ended; check `snapshot.state`.
+     */
+    start(options: FlowDebugStartOptions): Promise<FlowDebugSession>;
+    /**
+     * Classify a failed start call. Its request is marked sensitive, so only the status survives;
+     * a 400 or 404 is checked against a harmless debugger read to tell an instance without the
+     * debugger from a start it refused.
+     */
+    private startFailure;
+    /** The run as it is now, without moving it. */
+    inspect(contextId: string): Promise<FlowDebugSnapshot>;
+    /** Where the active context (the root, or the child subflow it is paused in) can stop. */
+    locations(contextId: string): Promise<FlowDebugLocation[]>;
+    /** Breakpoints the active context holds. */
+    getBreakpoints(contextId: string): Promise<FlowDebugBreakpoint[]>;
+    /**
+     * Replace the active context's breakpoints with these steps, and read them back.
+     *
+     * Steps are resolved against the debugger's own list of locations, never sent as given: the
+     * debugger accepts any element id on a valid line, so a guessed pair would be "verified" and
+     * stop somewhere else.
+     */
+    setBreakpoints(contextId: string, steps: FlowDebugStepRef[]): Promise<FlowDebugBreakpoint[]>;
+    /** Remove every breakpoint from the active context. */
+    clearBreakpoints(contextId: string): Promise<void>;
+    /** Run the paused step; stop at the next one. */
+    stepOver(contextId: string, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /** Like step over, but a subflow call is entered and paused in, in a child context. */
+    stepInto(contextId: string, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /** Run the rest of the active context; at the top level, that is the rest of the run. */
+    stepOut(contextId: string, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /** Run to the next breakpoint, or to the end. */
+    resume(contextId: string, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /** Run to the end, ignoring breakpoints. */
+    skipAll(contextId: string, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /**
+     * Send one debugger command to the paused context and wait for the run to settle: paused
+     * again, ended, waiting, or still executing when the wait times out (`timedOut`).
+     */
+    command(contextId: string, command: FlowDebugCommand, options?: FlowDebugWaitOptions): Promise<FlowDebugSnapshot>;
+    /**
+     * End the run. Cancelling the root also ends any child subflow context. The state is read
+     * back, because the debugger answers "cancelled flow" whatever it did. Safe to repeat.
+     *
+     * @throws FlowDebugError `not_a_debug_session` for a context the debugger did not start, so
+     *   this can never cancel someone's real flow run.
+     */
+    cancel(contextId: string): Promise<FlowDebugCancelResult>;
+    /**
+     * Start, run to the first of the breakpoints, and report the run there. By default the run is
+     * then cancelled, so one call leaves nothing open.
+     */
+    runTo(options: FlowDebugRunToOptions): Promise<FlowDebugRunToResult>;
+    /**
+     * Start a run, hand it to `work`, and cancel it afterwards unless it has ended.
+     *
+     * If `work` throws, the run is cancelled and `work`'s error is rethrown. If `work` succeeds but
+     * the final cancel fails, the cancel's error is thrown instead of the result: a run that may
+     * still be open matters more than the result.
+     */
+    withSession<T>(options: FlowDebugStartOptions, work: (session: FlowDebugSession) => Promise<T>): Promise<T>;
+    /** Debug runs that are still open (paused, waiting or executing), newest first. */
+    listSessions(options?: FlowDebugListOptions): Promise<FlowDebugSessionSummary[]>;
+    private resolveFlow;
+    private definition;
+    /**
+     * The `outputMap` the start call takes. For a subflow, names are checked against its declared
+     * inputs, and a JavaScript array for an `array.*` input becomes `{children: [...]}`, the shape
+     * Workflow Studio sends; a plain array reaches the flow as an empty list.
+     */
+    private outputMap;
+    /** Read the root and follow it into the child subflow context a step into left paused. */
+    private observe;
+    /** Poll until the run differs from `previous` and is no longer executing, or the time runs out. */
+    private waitFor;
+    private snapshot;
+    private state;
+    private values;
+    /** The run's flow snapshot, indexed by instance id and by uiUniqueIdentifier. */
+    private instances;
+    private locationsOf;
+    private readBreakpoints;
+    private match;
+    private requireDebug;
+    private requireOpen;
+    private postCancel;
+    /** Wait (about 10 seconds at most) for a cancelled context to reach an end state. */
+    private settleCancel;
+    /** Child subflow contexts of `parent` that are still open: a paused one first, then newest first. */
+    private openChildren;
+    /**
+     * Every open context below `root`, at any depth up to MAX_DEPTH. Ended contexts are walked
+     * through too: a cancel can end a middle context and leave the one below it paused.
+     */
+    private openDescendants;
+    /** The root of a subflow context's chain; a root is its own. */
+    private rootOf;
+    private read;
+    private debugCall;
+    private call;
+    private table;
+    /**
+     * Turn a failed call into a FlowDebugError. Policy refusals, session errors and anything that
+     * is not an HTTP failure pass through untouched.
+     */
+    private translate;
+    private id;
+    private refs;
+    private timeout;
+    /** Overridable in tests. */
+    protected sleep(ms: number): Promise<void>;
+}