@particle-academy/fancy-flow 0.45.0 → 0.47.0

package/dist/types-Jx1TwehV.d.ts

@@ -0,0 +1,247 @@
+import { Node, Edge } from '@xyflow/react';
+
+/**
+ * Who is running, which step this is, and how many times it has been tried.
+ *
+ * ## Why an engine needs this at all
+ *
+ * A node that WRITES to somebody else's system — charge a card, send a message,
+ * open a pull request — can only survive a retry if the retry carries the same
+ * idempotency key the first attempt did. Otherwise the provider treats the
+ * second call as a new request and the customer is charged twice.
+ *
+ * Until this existed the executor context was `{ node, inputs, emit, abort }`,
+ * which is not enough to derive one. Both obvious fallbacks are worse than
+ * sending no key at all:
+ *
+ * - **the node id alone** is stable across retries, and also across RUNS — two
+ *   legitimate payments share a key and the provider silently collapses the
+ *   second into the first. A payment that never happened, reported as success;
+ * - **a fresh random value** is unique per run, and also per ATTEMPT — a retry
+ *   creates a second charge, which is the thing being avoided.
+ *
+ * ## What actually identifies a step
+ *
+ * Not `(run, node)`. A node legitimately executes more than once inside one
+ * run: once per subflow invocation, once per iteration of a loop an executor
+ * drives itself. `(run, node)` would give every one of those the same key, and
+ * a provider would honour exactly one of them.
+ *
+ * So a step is identified by the **path of invocations that led to it**, plus
+ * an optional **occurrence** for repetition at the same level:
+ *
+ * ```text
+ * runKey ":" segment ("/" segment)*        segment := escape(id) ["#" occurrence]
+ * ```
+ *
+ * And the part that is easy to get backwards: **`attempt` is NOT in the key.**
+ * It is carried here for logging and for {@link RunIdentity.isReplaySafe}, and
+ * putting it in the key would restore the exact bug the key exists to prevent.
+ *
+ * Pinned cross-runtime by `shared/flow-run-identity` in
+ * `@particle-academy/fancy-conformance`.
+ */
+/** The wire shape — what a queue job payload carries. */
+type RunIdentityJson = {
+    runKey: string;
+    path?: string[];
+    attempt?: number;
+    firstAttemptAt?: string;
+};
+/**
+ * Escape one segment so the composition is injective.
+ *
+ * `%` FIRST, or the escaping is not reversible: escaping `/` before `%` turns a
+ * literal `a%2Fb` into the same text as the escaped form of `a/b`, which is the
+ * collision this exists to prevent, reintroduced by its own fix.
+ */
+declare function escapeSegment(value: string): string;
+/**
+ * A run, a position inside it, and how many times this position has been tried.
+ *
+ * Immutable. {@link descend} returns a new identity rather than mutating, so an
+ * executor cannot change what its siblings see.
+ */
+declare class RunIdentity {
+    /** Stable for the whole run: same across retries, resumes, workers and hosts. */
+    readonly runKey: string;
+    /**
+     * Enclosing invocation segments, outermost first, ALREADY RENDERED.
+     *
+     * Empty at the top level. A subflow pushes the invoking node's id; an
+     * executor that loops pushes `id#i`.
+     */
+    readonly path: readonly string[];
+    /**
+     * 1-based attempt of THIS logical step. Never part of the key.
+     *
+     * The durable driver sets it from the node's claim row, which is exact. A
+     * plain in-process `runFlow` gets whatever the host passed, which is
+     * run-scoped and therefore conservative — see `isReplaySafe`.
+     */
+    readonly attempt: number;
+    /** ISO-8601 UTC instant of attempt 1 of this step. */
+    readonly firstAttemptAt: string;
+    constructor(runKey: string, path?: readonly string[], attempt?: number, firstAttemptAt?: string);
+    /**
+     * The identity of one execution of one node — stable across retries of that
+     * execution, distinct from every other execution of the same node.
+     *
+     * Pass `occurrence` when an executor runs the same node more than once at the
+     * same level (a loop body, one item of a fan-out it drives itself).
+     */
+    stepKey(nodeId: string, occurrence?: number | null): string;
+    /**
+     * A child identity for work nested inside this step.
+     *
+     * `subflow` pushes the invoking node's id, so a node inside the child graph
+     * cannot collide with a same-named node in the parent. Attempt and
+     * `firstAttemptAt` are carried down unchanged: the nested work happens inside
+     * this step's attempt, and shares its clock.
+     */
+    descend(segment: string, occurrence?: number | null): RunIdentity;
+    /** A copy on a different attempt, first-attempt clock preserved. */
+    withAttempt(attempt: number, firstAttemptAt?: string): RunIdentity;
+    /**
+     * May this attempt reuse the step key and still be deduplicated?
+     *
+     * Providers forget idempotency keys — Stripe after 24 hours. Past that
+     * window, resending the key creates a second charge and sending a fresh one
+     * creates a second charge, so **the caller must refuse rather than pick
+     * between them**: a loud stuck run beats a silent double write.
+     *
+     * `true` on attempt 1 whatever the elapsed time — nothing was sent on an
+     * earlier attempt, so there is nothing for the provider to have forgotten.
+     * That is what lets a run park on a human gate for a week and then write.
+     *
+     * `windowSeconds: null` means the provider does not expire keys. `0` means
+     * it does not dedupe at all, so no retry may reuse a key — it is a real
+     * window, not an absent one, and the two must not be conflated: reading `0`
+     * as `null` turns "this provider does not dedupe" into "this provider
+     * dedupes forever", which is the more dangerous of the two by a distance.
+     */
+    isReplaySafe(windowSeconds: number | null | undefined, now?: Date | string): boolean;
+    toJSON(): Required<RunIdentityJson>;
+    /** Rebuild from a queue payload. */
+    static from(value: RunIdentity | RunIdentityJson | string): RunIdentity;
+}
+
+/**
+ * Public domain types for fancy-flow. Built-in nodes are layered on top of
+ * @xyflow/react's `Node` so consumers can mix custom xyflow nodes alongside
+ * the kit. Edges remain xyflow's standard `Edge`.
+ */
+
+type FlowNodeKind = "trigger" | "action" | "decision" | "output" | "note" | "subgraph";
+/** Status surfaced on the node while a run is in progress. */
+type NodeRunStatus = "idle" | "queued" | "running" | "done" | "error";
+/** Port description on a node. Ports are visual handles xyflow can connect. */
+type PortDescriptor = {
+    id: string;
+    label?: string;
+    /** Optional logical type for hosts that want to validate connections. */
+    type?: string;
+};
+/** Common shape every kit node carries in its `data` slot. */
+type BaseNodeData = {
+    label: string;
+    description?: string;
+    /** Free-form configuration the host owns (form values, code, parameters). */
+    config?: Record<string, unknown>;
+    /** Set by the runner; hosts shouldn't edit this directly. */
+    status?: NodeRunStatus;
+    /** Optional human-readable status detail (e.g. error message, current step). */
+    statusText?: string;
+    /** Per-node accent override, e.g. for theming a custom subclass. */
+    color?: string;
+    /** Input ports rendered on the node. Defaults vary by kind. */
+    inputs?: PortDescriptor[];
+    /** Output ports rendered on the node. Defaults vary by kind. */
+    outputs?: PortDescriptor[];
+};
+type TriggerNodeData = BaseNodeData & {
+    kind: "trigger";
+};
+type ActionNodeData = BaseNodeData & {
+    kind: "action";
+};
+type DecisionNodeData = BaseNodeData & {
+    kind: "decision";
+};
+type OutputNodeData = BaseNodeData & {
+    kind: "output";
+};
+type NoteNodeData = BaseNodeData & {
+    kind: "note";
+    body?: string;
+};
+type SubgraphNodeData = BaseNodeData & {
+    kind: "subgraph";
+    /** Ids of the nodes contained in this subgraph. */
+    childIds?: string[];
+    /** Whether the subgraph is shown collapsed (default true — children hidden). */
+    collapsed?: boolean;
+};
+type FlowNodeData = TriggerNodeData | ActionNodeData | DecisionNodeData | OutputNodeData | NoteNodeData | SubgraphNodeData;
+type FlowNode = Node<FlowNodeData>;
+type FlowEdge = Edge;
+/** A serializable graph — what hosts persist, what agents read/write. */
+type FlowGraph = {
+    nodes: FlowNode[];
+    edges: FlowEdge[];
+};
+/** Per-node executor signature. Inputs are keyed by input-port id. */
+type NodeExecutor<TIn = Record<string, unknown>, TOut = unknown> = (ctx: {
+    node: FlowNode;
+    inputs: TIn;
+    /** Stops the run if called. */
+    abort: (reason?: string) => never;
+    /** Lets the executor stream status updates and partial outputs. */
+    emit: (event: RunEvent) => void;
+    /**
+     * How deep this run is nested. 0 for a top-level run; `subflow` passes
+     * depth + 1 to its child, so runaway recursion can be reported by name
+     * rather than as a stack overflow.
+     */
+    depth?: number;
+    /**
+     * Who is running, and which attempt of which step this is.
+     *
+     * `ctx.run.stepKey(ctx.node.id)` is the idempotency key for a node that
+     * writes to somebody else's system — stable across retries of this step,
+     * distinct for every other execution of the same node.
+     *
+     * `undefined` when the host supplied no identity, and that is a real
+     * answer: a write with no key must decline or accept one attempt, never
+     * invent a key. See `RunIdentity`.
+     */
+    run?: RunIdentity;
+}) => Promise<TOut> | TOut;
+type ExecutorRegistry = Partial<Record<FlowNodeKind | string, NodeExecutor>>;
+type RunEvent = {
+    type: "node-status";
+    nodeId: string;
+    status: NodeRunStatus;
+    text?: string;
+} | {
+    type: "node-output";
+    nodeId: string;
+    portId: string;
+    value: unknown;
+} | {
+    type: "log";
+    nodeId?: string;
+    level: "info" | "warn" | "error";
+    message: string;
+    detail?: unknown;
+} | {
+    type: "run-start";
+} | {
+    type: "run-end";
+    ok: boolean;
+} | {
+    type: "run-error";
+    error: string;
+};
+
+export { type ActionNodeData as A, type BaseNodeData as B, type DecisionNodeData as D, type ExecutorRegistry as E, type FlowGraph as F, type NodeExecutor as N, type OutputNodeData as O, type PortDescriptor as P, type RunEvent as R, type SubgraphNodeData as S, type TriggerNodeData as T, type FlowNode as a, RunIdentity as b, type RunIdentityJson as c, type FlowEdge as d, type FlowNodeData as e, type FlowNodeKind as f, type NodeRunStatus as g, type NoteNodeData as h, escapeSegment as i };