scrapme-flow 0.0.0-stage → 0.2.0

package/dist/src/flow/flow-validator.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { FlowDefinitionError } from './flow-errors.js';
+import { VALUE_TYPE, } from './flow.models.js';
+import { StatePath } from './state-path.js';
+/**
+ * Checks a flow config (a `*.flow.ts` file) and turns it into a FlowDefinition, or throws FlowDefinitionError saying
+ * where (`flow "hello": steps[0] "printed".input["text"]: …`). Shape with zod; then what zod can't see: unique keys
+ * (a step's key defaults to its command's name), `from` paths that start with a param or an EARLIER step, commands
+ * that have an `execute` method. Field functions are plain JS and are not looked into.
+ */
+export class FlowValidator {
+    /**
+     * Step keys and param names become state properties and the first part of paths, so they must be plain
+     * identifiers. A regex is the clearest way to say that (it's a rule about characters, not about structure).
+     */
+    static IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+    static IDENTIFIER_RULE = 'letters, digits, _ and - only, not starting with a digit or -';
+    static identifier = z.string().regex(FlowValidator.IDENTIFIER, FlowValidator.IDENTIFIER_RULE);
+    static int = (min) => z.number().int().min(min);
+    static field = z.union([
+        z.strictObject({ from: z.string(), optional: z.boolean().optional() }),
+        z.strictObject({ value: z.unknown() }),
+        z.custom((v) => typeof v === 'function', 'a field is { from }, { value } or a function (state) => value'),
+    ]);
+    static schema = z.strictObject({
+        name: FlowValidator.identifier,
+        description: z.string().optional(),
+        tags: z.record(z.string(), z.string()).optional(),
+        retries: FlowValidator.int(0).optional(),
+        retryDelaySeconds: FlowValidator.int(0).optional(),
+        retryBackoff: z.boolean().optional(),
+        timeoutSeconds: FlowValidator.int(1).optional(),
+        params: z
+            .record(FlowValidator.identifier, z.strictObject({
+            required: z.boolean().optional(),
+            type: z.enum(VALUE_TYPE).optional(),
+            default: z.unknown().optional(),
+            description: z.string().optional(),
+        }))
+            .optional(),
+        steps: z
+            .array(z.strictObject({
+            key: FlowValidator.identifier.optional(),
+            command: z.custom((v) => FlowValidator.isCommand(v), 'must be a command class (with execute()) or a command object'),
+            inputFrom: z.string().optional(),
+            input: z.record(z.string(), FlowValidator.field).optional(),
+            description: z.string().optional(),
+            retries: FlowValidator.int(0).optional(),
+            timeoutMs: FlowValidator.int(1).optional(),
+            retryDelayMs: FlowValidator.int(0).optional(),
+            maxRetryDelayMs: FlowValidator.int(0).optional(),
+        }))
+            .min(1, 'a flow needs at least one step'),
+    });
+    validate(config) {
+        const label = typeof config?.name === 'string' && config.name ? config.name : 'flow';
+        const parsed = FlowValidator.schema.safeParse(config);
+        if (!parsed.success)
+            throw new FlowDefinitionError(z.prettifyError(parsed.error).split('\n').join(' '), label);
+        const params = Object.entries(config.params ?? {}).map(([name, p]) => this.param(label, name, p));
+        const known = new Set(params.map((p) => p.name));
+        const steps = config.steps.map((step, index) => {
+            const definition = this.step(label, index, step, known);
+            known.add(definition.key);
+            return definition;
+        });
+        const queue = Object.fromEntries(Object.entries({ retries: config.retries, retryDelaySeconds: config.retryDelaySeconds, retryBackoff: config.retryBackoff, timeoutSeconds: config.timeoutSeconds }).filter(([, v]) => v !== undefined));
+        return {
+            name: config.name,
+            queue,
+            tags: { ...config.tags },
+            params,
+            steps,
+            ...(config.description ? { description: config.description } : {}),
+        };
+    }
+    /** A class whose prototype has execute(), or an object with execute(). */
+    static isCommand(value) {
+        if (typeof value === 'function')
+            return typeof value.prototype?.execute === 'function';
+        return value !== null && typeof value === 'object' && typeof value.execute === 'function';
+    }
+    /** Class name, the name of a FunctionCommand, or the object's class name. */
+    static commandName(command) {
+        if (typeof command === 'function')
+            return command.name || 'AnonymousCommand';
+        const named = command.name;
+        return typeof named === 'string' && named ? named : (command.constructor?.name ?? 'Command');
+    }
+    param(label, name, p) {
+        const required = p.required ?? false;
+        if (required && p.default !== undefined)
+            throw new FlowDefinitionError(`params.${name}: required and a default don't go together`, label);
+        return { name, required, type: p.type ?? VALUE_TYPE.STRING, ...(p.default !== undefined ? { default: structuredClone(p.default) } : {}) };
+    }
+    step(label, index, step, known) {
+        const { key: givenKey, command, inputFrom, input, description, ...options } = step;
+        const commandName = FlowValidator.commandName(command);
+        const key = givenKey ?? commandName;
+        const where = `steps[${index}] "${key}"`;
+        if (!FlowValidator.IDENTIFIER.test(key)) {
+            throw new FlowDefinitionError(`${where}: the command's name can't be a key (${FlowValidator.IDENTIFIER_RULE}) - give the step a key`, label);
+        }
+        if (known.has(key)) {
+            throw new FlowDefinitionError(`${where}: the key is already used by a param or an earlier step${givenKey ? '' : ' (the same command twice? give the steps their own keys)'}`, label);
+        }
+        if (inputFrom !== undefined)
+            this.reference(label, `${where}.inputFrom`, inputFrom, known);
+        const fields = Object.entries(input ?? {}).map(([name, field]) => this.field(label, `${where}.input["${name}"]`, name, field, known));
+        const spec = inputFrom === undefined && input === undefined ? undefined : { ...(inputFrom !== undefined ? { from: inputFrom } : {}), fields };
+        return {
+            key,
+            command: command,
+            commandName,
+            options: Object.fromEntries(Object.entries(options).filter(([, v]) => v !== undefined)),
+            ...(spec ? { input: spec } : {}),
+            ...(description ? { description } : {}),
+        };
+    }
+    field(label, where, name, field, known) {
+        if (!StatePath.split(name))
+            throw new FlowDefinitionError(`${where}: the name must be a name or a dotted path (a.b)`, label);
+        if (typeof field === 'function')
+            return { name, compute: field };
+        if ('from' in field) {
+            this.reference(label, where, field.from, known);
+            return { name, from: field.from, optional: field.optional ?? false };
+        }
+        return { name, value: structuredClone(field.value) };
+    }
+    /** A path must start with a param or an earlier step's key. */
+    reference(label, where, path, known) {
+        const segments = StatePath.split(path);
+        if (!segments)
+            throw new FlowDefinitionError(`${where}: "${path}" is not a valid path (names joined with ".")`, label);
+        if (!known.has(segments[0])) {
+            throw new FlowDefinitionError(`${where}: "${path}" - "${segments[0]}" is neither a param nor an earlier step (known: ${[...known].join(', ') || 'nothing'})`, label);
+        }
+    }
+}
+//# sourceMappingURL=flow-validator.js.map

package/dist/src/flow/flow-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow-validator.js","sourceRoot":"","sources":["../../../src/flow/flow-validator.ts"],"names":[],"mappings":"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"}

package/dist/src/flow/flow.d.ts

@@ -0,0 +1,32 @@
+import type { Command, CommandContext, CommandOptions, FlowConfig, FlowDefinition, FlowParam, FlowQueueOptions, StepDefinition } from './flow.models.js';
+/**
+ * A flow: an ordered list of steps, each running one command. Write it in a `*.flow.ts` file and export it; the
+ * config is checked here (FlowValidator), so a broken flow throws FlowDefinitionError when the file is imported.
+ *
+ *   export const helloFlow = new Flow({
+ *     name: 'hello',
+ *     params: { name: { default: 'World' } },
+ *     steps: [{ command: PrintMessageCommand, input: { text: (s) => 'Hello, ' + s.name + '!' } }],
+ *   });
+ *
+ * Queue a run of it with `scrapme.flow(helloFlow, { name: 'Ada' })`.
+ */
+export declare class Flow implements FlowDefinition {
+    readonly name: string;
+    readonly queue: FlowQueueOptions;
+    readonly tags: Readonly<Record<string, string>>;
+    readonly params: readonly FlowParam[];
+    readonly steps: readonly StepDefinition[];
+    readonly description?: string;
+    constructor(config: FlowConfig);
+    /** "page (ScrapePageCommand) → report (ParseIncomeStatementCommand) → …" — for logs and CLIs. */
+    describe(): string;
+}
+/** A command made from a function — for small glue steps that need no dependencies. */
+export declare class FunctionCommand<I, O> implements Command<I, O> {
+    readonly name: string;
+    private readonly fn;
+    readonly options: CommandOptions;
+    constructor(name: string, fn: (input: I, ctx: CommandContext) => Promise<O> | O, options?: CommandOptions);
+    execute(input: I, ctx: CommandContext): Promise<O>;
+}

package/dist/src/flow/flow.js

@@ -0,0 +1,50 @@
+import { FlowValidator } from './flow-validator.js';
+/**
+ * A flow: an ordered list of steps, each running one command. Write it in a `*.flow.ts` file and export it; the
+ * config is checked here (FlowValidator), so a broken flow throws FlowDefinitionError when the file is imported.
+ *
+ *   export const helloFlow = new Flow({
+ *     name: 'hello',
+ *     params: { name: { default: 'World' } },
+ *     steps: [{ command: PrintMessageCommand, input: { text: (s) => 'Hello, ' + s.name + '!' } }],
+ *   });
+ *
+ * Queue a run of it with `scrapme.flow(helloFlow, { name: 'Ada' })`.
+ */
+export class Flow {
+    name;
+    queue;
+    tags;
+    params;
+    steps;
+    description;
+    constructor(config) {
+        const definition = new FlowValidator().validate(config);
+        this.name = definition.name;
+        this.queue = Object.freeze({ ...definition.queue });
+        this.tags = Object.freeze({ ...definition.tags });
+        this.params = Object.freeze([...definition.params]);
+        this.steps = Object.freeze([...definition.steps]);
+        if (definition.description)
+            this.description = definition.description;
+    }
+    /** "page (ScrapePageCommand) → report (ParseIncomeStatementCommand) → …" — for logs and CLIs. */
+    describe() {
+        return this.steps.map((s) => `${s.key} (${s.commandName})`).join(' → ');
+    }
+}
+/** A command made from a function — for small glue steps that need no dependencies. */
+export class FunctionCommand {
+    name;
+    fn;
+    options;
+    constructor(name, fn, options = {}) {
+        this.name = name;
+        this.fn = fn;
+        this.options = options;
+    }
+    async execute(input, ctx) {
+        return this.fn(input, ctx);
+    }
+}
+//# sourceMappingURL=flow.js.map

package/dist/src/flow/flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.js","sourceRoot":"","sources":["../../../src/flow/flow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,IAAI;IACC,IAAI,CAAS;IACb,KAAK,CAAmB;IACxB,IAAI,CAAmC;IACvC,MAAM,CAAuB;IAC7B,KAAK,CAA4B;IACjC,WAAW,CAAU;IAErC,YAAmB,MAAkB;QACnC,MAAM,UAAU,GAAG,IAAI,aAAa,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;QACpD,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC;QAClD,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;QACpD,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;QAClD,IAAI,UAAU,CAAC,WAAW;YAAE,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;IACxE,CAAC;IAED,iGAAiG;IAC1F,QAAQ;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1E,CAAC;CACF;AAED,uFAAuF;AACvF,MAAM,OAAO,eAAe;IAER;IACC;IACD;IAHlB,YACkB,IAAY,EACX,EAAqD,EACtD,UAA0B,EAAE;QAF5B,SAAI,GAAJ,IAAI,CAAQ;QACX,OAAE,GAAF,EAAE,CAAmD;QACtD,YAAO,GAAP,OAAO,CAAqB;IAC3C,CAAC;IAEG,KAAK,CAAC,OAAO,CAAC,KAAQ,EAAE,GAAmB;QAChD,OAAO,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7B,CAAC;CACF"}

package/dist/src/flow/flow.models.d.ts

@@ -0,0 +1,288 @@
+import type { Logger } from '../logging/logger.js';
+/**
+ * Status of a run (stored in its run document). queued → running → succeeded | retrying (pg-boss runs the whole
+ * flow again later) | failed (no attempts left, or a permanent error).
+ */
+export declare const RUN_STATUS: {
+    readonly QUEUED: "queued";
+    readonly RUNNING: "running";
+    readonly RETRYING: "retrying";
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+};
+export type RunStatus = (typeof RUN_STATUS)[keyof typeof RUN_STATUS];
+/** A run in one of these never changes again. */
+export declare const FINAL_RUN_STATUSES: readonly RunStatus[];
+/** Status of one step of a run. A failed step becomes running again when the flow is retried. */
+export declare const STEP_STATUS: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+};
+export type StepStatus = (typeof STEP_STATUS)[keyof typeof STEP_STATUS];
+/** How one attempt of a step ended. */
+export declare const ATTEMPT_OUTCOME: {
+    readonly SUCCEEDED: "succeeded";
+    readonly FAILED: "failed";
+    readonly TIMEOUT: "timeout";
+};
+export type AttemptOutcome = (typeof ATTEMPT_OUTCOME)[keyof typeof ATTEMPT_OUTCOME];
+/** `code` of the errors scrapme itself throws (your commands may use their own codes too). */
+export declare const ERROR_CODE: {
+    /** PermanentError without a more specific code. */
+    readonly PERMANENT: "PERMANENT";
+    /** A command got an input it can't work with. */
+    readonly BAD_INPUT: "BAD_INPUT";
+    /** A step input refers to a value the state doesn't have (e.g. a field missing in a previous output). */
+    readonly MISSING_VALUE: "MISSING_VALUE";
+    readonly COMMAND_TIMEOUT: "COMMAND_TIMEOUT";
+    readonly FLOW_CANCELLED: "FLOW_CANCELLED";
+    readonly FLOW_FAILED: "FLOW_FAILED";
+    /** The flow definition is invalid (shape, bad reference, duplicate key, not a command). */
+    readonly FLOW_DEFINITION: "FLOW_DEFINITION";
+    /** The run input doesn't match the flow's `<param>`s. */
+    readonly FLOW_INPUT: "FLOW_INPUT";
+    /** ScrapePageCommand: the URL is a file (PDF…), not an HTML page. */
+    readonly NOT_HTML: "NOT_HTML";
+    /** ScrapePageCommand: the target answered 4xx (allowHttpErrors not set). */
+    readonly HTTP_STATUS: "HTTP_STATUS";
+    /** SendMailCommand: the SMTP server refused the message (5xx). */
+    readonly MAIL_REJECTED: "MAIL_REJECTED";
+    /** A command needs a service that wasn't given to Scrapme.create (scrapAnything, couch, mail). */
+    readonly NOT_CONFIGURED: "NOT_CONFIGURED";
+};
+export type ErrorCode = (typeof ERROR_CODE)[keyof typeof ERROR_CODE];
+/** Retry/timeout settings. Precedence: step > command.options > FLOW_* config defaults. */
+export interface CommandOptions {
+    /** Retries after the first attempt (attempts = retries + 1). */
+    retries?: number;
+    /** Limit of one attempt in ms; on expiry ctx.signal aborts and the attempt fails with CommandTimeoutError. */
+    timeoutMs?: number;
+    /** First retry delay (doubled per retry, with jitter). */
+    retryDelayMs?: number;
+    maxRetryDelayMs?: number;
+}
+/** What a command gets besides its input. */
+export interface CommandContext {
+    readonly runId: string;
+    readonly flow: string;
+    /** Key of the step in the flow (the name its output is stored under). */
+    readonly step: string;
+    /** Attempt of this step within the current flow attempt, 1-based. */
+    readonly attempt: number;
+    readonly maxAttempts: number;
+    /** Attempt of the whole flow (pg-boss job), 1-based: > 1 means pg-boss runs the flow again. */
+    readonly flowAttempt: number;
+    /** Aborted on timeout or when the run is cancelled — pass it on and stop early. */
+    readonly signal: AbortSignal;
+    /** Logger with run/flow/step/attempt fields already set. */
+    readonly logger: Logger;
+    /** Everything produced so far: the flow input plus the outputs of all previous steps, by step key. */
+    readonly state: Readonly<Record<string, unknown>>;
+}
+/**
+ * One unit of work. Implement it as an `@injectable()` class: dependencies come through the constructor
+ * (`@inject(SomeService)` — resolved from your app's container), the input is what the step's `input` builds
+ * (default: the whole state),
+ * the returned value is stored in the state under the step key.
+ */
+export interface Command<I = unknown, O = unknown> {
+    /** Defaults for this command; the step can override them. */
+    readonly options?: CommandOptions;
+    execute(input: I, ctx: CommandContext): Promise<O>;
+    /** Override the default retry decision (see isRetryable in flow-errors). */
+    isRetryable?(error: unknown): boolean;
+}
+/** A command class (resolved from the DI container, so its constructor injections work). */
+export type CommandClass<I = unknown, O = unknown> = abstract new (...args: never[]) => Command<I, O>;
+/** What a step runs: a command class (resolved from the DI container) or a ready instance (e.g. new FunctionCommand(...)). */
+export type CommandRef<I = unknown, O = unknown> = CommandClass<I, O> | Command<I, O>;
+/** Kind of a param value (checked when a run starts). */
+export declare const VALUE_TYPE: {
+    readonly STRING: "string";
+    readonly NUMBER: "number";
+    readonly BOOLEAN: "boolean";
+    readonly JSON: "json";
+};
+export type ValueType = (typeof VALUE_TYPE)[keyof typeof VALUE_TYPE];
+/** The state as a field function sees it: the run input plus the outputs of the steps so far, by key (shape up to the flow). */
+export type FlowState = Readonly<Record<string, any>>;
+/** One property of a step input, as written in a flow file. */
+export type FieldConfig = 
+/** A value from the state (dotted path: "page.finalUrl"); missing → MISSING_VALUE, unless optional. */
+{
+    readonly from: string;
+    readonly optional?: boolean;
+}
+/** A literal. */
+ | {
+    readonly value: unknown;
+}
+/** Computed from the state in plain JS: `(s) => 'doc:' + s.report.symbol`. */
+ | ((state: FlowState) => unknown);
+/** A value the caller passes into the run, as written in a flow file. */
+export interface ParamConfig {
+    readonly required?: boolean;
+    /** Default `string`. */
+    readonly type?: ValueType;
+    readonly default?: unknown;
+    readonly description?: string;
+}
+/** One step, as written in a flow file. */
+export interface StepConfig extends CommandOptions {
+    /** Name the output is stored under in the state. Default: the command's name (class name). */
+    readonly key?: string;
+    readonly command: CommandRef<never, unknown>;
+    /** The step input is (a copy of) this value of the state. Without it and without `input`: the whole state. */
+    readonly inputFrom?: string;
+    /** The step input is an object with these properties (names may be dotted paths: "headers.Accept-Language"). */
+    readonly input?: Readonly<Record<string, FieldConfig>>;
+    readonly description?: string;
+}
+/** How the whole flow runs on its pg-boss queue (each run = one job; a failed job runs the flow again from its first step). */
+export interface FlowQueueOptions {
+    /** Flow attempts after the first one (pg-boss retryLimit). Default: the `queue.retries` option (3). */
+    readonly retries?: number;
+    /** Delay before a flow attempt is retried (pg-boss retryDelay). Default: the `queue.retryDelaySeconds` option. */
+    readonly retryDelaySeconds?: number;
+    /** Double the delay on every retry (pg-boss retryBackoff). Default: the `queue.retryBackoff` option. */
+    readonly retryBackoff?: boolean;
+    /** One flow attempt may run this long, then pg-boss fails (and retries) it (expireInSeconds). */
+    readonly timeoutSeconds?: number;
+}
+/**
+ * A flow as written in a `*.flow.ts` file: `export const myFlow = new Flow({ name, params, steps })`.
+ * JSON-like data plus the command classes (and plain functions where a value is computed).
+ */
+export interface FlowConfig extends FlowQueueOptions {
+    /** Letters, digits, _ and -; the flow's pg-boss queue is named after it (queue prefix + name). */
+    readonly name: string;
+    readonly description?: string;
+    /** Stored with every run, sent as tags with error reports. */
+    readonly tags?: Readonly<Record<string, string>>;
+    readonly params?: Readonly<Record<string, ParamConfig>>;
+    readonly steps: readonly StepConfig[];
+}
+/** A param after validation. */
+export interface FlowParam {
+    readonly name: string;
+    readonly required: boolean;
+    readonly type: ValueType;
+    readonly default?: unknown;
+}
+/** A field after validation (`name` may be a dotted path). */
+export type InputField = {
+    readonly name: string;
+    readonly from: string;
+    readonly optional: boolean;
+} | {
+    readonly name: string;
+    readonly value: unknown;
+} | {
+    readonly name: string;
+    readonly compute: (state: FlowState) => unknown;
+};
+/** How a step builds its input; undefined on the step = the whole state. */
+export interface InputSpec {
+    readonly from?: string;
+    readonly fields: readonly InputField[];
+}
+/** A step after validation. */
+export interface StepDefinition {
+    readonly key: string;
+    readonly command: CommandRef;
+    /** Class name or FunctionCommand name — for logs, stored runs and reports. */
+    readonly commandName: string;
+    readonly options: CommandOptions;
+    readonly input?: InputSpec;
+    readonly description?: string;
+}
+/** A flow after validation (Flow). */
+export interface FlowDefinition {
+    readonly name: string;
+    /** Only what the flow sets; the rest comes from Scrapme.create({ queue }). */
+    readonly queue: FlowQueueOptions;
+    readonly tags: Readonly<Record<string, string>>;
+    readonly params: readonly FlowParam[];
+    readonly steps: readonly StepDefinition[];
+    readonly description?: string;
+}
+export interface SerializedError {
+    name: string;
+    message: string;
+    code?: string;
+    retryable: boolean;
+    stack?: string;
+    cause?: SerializedError;
+}
+export interface AttemptReport {
+    /** Attempt of the step within its flow attempt. */
+    attempt: number;
+    flowAttempt: number;
+    startedAt: string;
+    durationMs: number;
+    outcome: AttemptOutcome;
+    error?: SerializedError;
+    /** Delay before the next attempt, when there is one. */
+    retryInMs?: number;
+}
+/** One step of a run, as stored in the run document and shown by the monitor. */
+export interface StepReport {
+    key: string;
+    command: string;
+    status: StepStatus;
+    /** Every attempt, over all flow attempts (each says which flow attempt it belonged to). */
+    attempts: AttemptReport[];
+    startedAt?: string;
+    finishedAt?: string;
+    durationMs?: number;
+    /** The output, shortened (long strings cut at defaults.maxStoredChars). */
+    output?: unknown;
+    error?: SerializedError;
+}
+/** One attempt of the whole flow (one execution of its pg-boss job). */
+export interface FlowAttemptReport {
+    attempt: number;
+    jobId: string;
+    startedAt: string;
+    finishedAt?: string;
+    outcome?: typeof ATTEMPT_OUTCOME.SUCCEEDED | typeof ATTEMPT_OUTCOME.FAILED;
+    error?: SerializedError;
+}
+export interface ScheduleOptions {
+    /** Your own id (e.g. an idempotency key); default random UUID. Scheduling the same id twice is refused. */
+    runId?: string;
+    /** Run later. */
+    startAfter?: Date;
+    /** Higher runs first. */
+    priority?: number;
+}
+export interface WaitOptions {
+    /** Give up after this many ms (the run goes on). Default 10 minutes. */
+    timeoutMs?: number;
+    /** Default 1 000. */
+    pollIntervalMs?: number;
+}
+/** Outcome of executing one step with retries (CommandExecutor). */
+export type StepExecution = {
+    ok: true;
+    value: unknown;
+    attempts: AttemptReport[];
+    durationMs: number;
+} | {
+    ok: false;
+    error: unknown;
+    attempts: AttemptReport[];
+    durationMs: number;
+};
+/** Called by CommandExecutor after every failed attempt (recorded in the run document). */
+export type AttemptFailedListener = (report: AttemptReport, error: unknown, final: boolean) => Promise<void> | void;
+/** Called by CommandExecutor before every attempt (the monitor shows the step as running). */
+export type AttemptStartedListener = (attempt: number) => Promise<void> | void;
+export interface ResolvedStepPolicy {
+    maxAttempts: number;
+    timeoutMs: number;
+    retryDelayMs: number;
+    maxRetryDelayMs: number;
+}

package/dist/src/flow/flow.models.js

@@ -0,0 +1,38 @@
+/**
+ * Status of a run (stored in its run document). queued → running → succeeded | retrying (pg-boss runs the whole
+ * flow again later) | failed (no attempts left, or a permanent error).
+ */
+export const RUN_STATUS = { QUEUED: 'queued', RUNNING: 'running', RETRYING: 'retrying', SUCCEEDED: 'succeeded', FAILED: 'failed' };
+/** A run in one of these never changes again. */
+export const FINAL_RUN_STATUSES = [RUN_STATUS.SUCCEEDED, RUN_STATUS.FAILED];
+/** Status of one step of a run. A failed step becomes running again when the flow is retried. */
+export const STEP_STATUS = { PENDING: 'pending', RUNNING: 'running', SUCCEEDED: 'succeeded', FAILED: 'failed' };
+/** How one attempt of a step ended. */
+export const ATTEMPT_OUTCOME = { SUCCEEDED: 'succeeded', FAILED: 'failed', TIMEOUT: 'timeout' };
+/** `code` of the errors scrapme itself throws (your commands may use their own codes too). */
+export const ERROR_CODE = {
+    /** PermanentError without a more specific code. */
+    PERMANENT: 'PERMANENT',
+    /** A command got an input it can't work with. */
+    BAD_INPUT: 'BAD_INPUT',
+    /** A step input refers to a value the state doesn't have (e.g. a field missing in a previous output). */
+    MISSING_VALUE: 'MISSING_VALUE',
+    COMMAND_TIMEOUT: 'COMMAND_TIMEOUT',
+    FLOW_CANCELLED: 'FLOW_CANCELLED',
+    FLOW_FAILED: 'FLOW_FAILED',
+    /** The flow definition is invalid (shape, bad reference, duplicate key, not a command). */
+    FLOW_DEFINITION: 'FLOW_DEFINITION',
+    /** The run input doesn't match the flow's `<param>`s. */
+    FLOW_INPUT: 'FLOW_INPUT',
+    /** ScrapePageCommand: the URL is a file (PDF…), not an HTML page. */
+    NOT_HTML: 'NOT_HTML',
+    /** ScrapePageCommand: the target answered 4xx (allowHttpErrors not set). */
+    HTTP_STATUS: 'HTTP_STATUS',
+    /** SendMailCommand: the SMTP server refused the message (5xx). */
+    MAIL_REJECTED: 'MAIL_REJECTED',
+    /** A command needs a service that wasn't given to Scrapme.create (scrapAnything, couch, mail). */
+    NOT_CONFIGURED: 'NOT_CONFIGURED',
+};
+/** Kind of a param value (checked when a run starts). */
+export const VALUE_TYPE = { STRING: 'string', NUMBER: 'number', BOOLEAN: 'boolean', JSON: 'json' };
+//# sourceMappingURL=flow.models.js.map

package/dist/src/flow/flow.models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flow.models.js","sourceRoot":"","sources":["../../../src/flow/flow.models.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAW,CAAC;AAE5I,iDAAiD;AACjD,MAAM,CAAC,MAAM,kBAAkB,GAAyB,CAAC,UAAU,CAAC,SAAS,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;AAElG,iGAAiG;AACjG,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAW,CAAC;AAGzH,uCAAuC;AACvC,MAAM,CAAC,MAAM,eAAe,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAW,CAAC;AAGzG,8FAA8F;AAC9F,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mDAAmD;IACnD,SAAS,EAAE,WAAW;IACtB,iDAAiD;IACjD,SAAS,EAAE,WAAW;IACtB,yGAAyG;IACzG,aAAa,EAAE,eAAe;IAC9B,eAAe,EAAE,iBAAiB;IAClC,cAAc,EAAE,gBAAgB;IAChC,WAAW,EAAE,aAAa;IAC1B,2FAA2F;IAC3F,eAAe,EAAE,iBAAiB;IAClC,yDAAyD;IACzD,UAAU,EAAE,YAAY;IACxB,qEAAqE;IACrE,QAAQ,EAAE,UAAU;IACpB,4EAA4E;IAC5E,WAAW,EAAE,aAAa;IAC1B,kEAAkE;IAClE,aAAa,EAAE,eAAe;IAC9B,kGAAkG;IAClG,cAAc,EAAE,gBAAgB;CACxB,CAAC;AAqDX,yDAAyD;AACzD,MAAM,CAAC,MAAM,UAAU,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAW,CAAC"}

package/dist/src/flow/retry-policy.d.ts

@@ -0,0 +1,9 @@
+import type { ResolvedStepPolicy } from './flow.models.js';
+/** Exponential backoff with "equal jitter": half fixed, half random — retries of many runs do not line up. */
+export declare class RetryPolicy {
+    private readonly policy;
+    private readonly random;
+    constructor(policy: Pick<ResolvedStepPolicy, 'retryDelayMs' | 'maxRetryDelayMs'>, random?: () => number);
+    /** Delay before attempt `failedAttempt + 1` (failedAttempt is 1-based). */
+    delayAfter(failedAttempt: number): number;
+}

package/dist/src/flow/retry-policy.js

@@ -0,0 +1,15 @@
+/** Exponential backoff with "equal jitter": half fixed, half random — retries of many runs do not line up. */
+export class RetryPolicy {
+    policy;
+    random;
+    constructor(policy, random = Math.random) {
+        this.policy = policy;
+        this.random = random;
+    }
+    /** Delay before attempt `failedAttempt + 1` (failedAttempt is 1-based). */
+    delayAfter(failedAttempt) {
+        const base = Math.min(this.policy.maxRetryDelayMs, this.policy.retryDelayMs * 2 ** (failedAttempt - 1));
+        return Math.round(base / 2 + (base / 2) * this.random());
+    }
+}
+//# sourceMappingURL=retry-policy.js.map

package/dist/src/flow/retry-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry-policy.js","sourceRoot":"","sources":["../../../src/flow/retry-policy.ts"],"names":[],"mappings":"AAEA,8GAA8G;AAC9G,MAAM,OAAO,WAAW;IAEH;IACA;IAFnB,YACmB,MAAoE,EACpE,SAAuB,IAAI,CAAC,MAAM;QADlC,WAAM,GAAN,MAAM,CAA8D;QACpE,WAAM,GAAN,MAAM,CAA4B;IAClD,CAAC;IAEJ,2EAA2E;IACpE,UAAU,CAAC,aAAqB;QACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,GAAG,CAAC,IAAI,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC;QACxG,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC3D,CAAC;CACF"}

package/dist/src/flow/state-path.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Dotted paths into the flow state: `page.html`, `report.periods`. Only plain property access — no indexes or
+ * expressions; anything smarter belongs in a command.
+ */
+export declare class StatePath {
+    static readonly SEPARATOR = ".";
+    /** "a.b.c" → ["a","b","c"]; null when a segment is empty ("a..b", ".a", ""). */
+    static split(path: string): string[] | null;
+    /** The value at `path`, or `{ found: false }` when some part of it is missing. */
+    static get(root: unknown, path: string): {
+        found: true;
+        value: unknown;
+    } | {
+        found: false;
+    };
+    /**
+     * A copy of `root` with `value` at `path`; objects on the way are copied (never mutated) or created.
+     * A non-object in the way is replaced by an object.
+     */
+    static set(root: Record<string, unknown>, path: string, value: unknown): Record<string, unknown>;
+}