@opencraw/core 0.1.0

package/dist/src/output-mapping/missing-value.policy.d.ts

@@ -0,0 +1,14 @@
+import type { FieldSpec, MappingRule, MissingPolicy, OutputRecipe } from '../recipe-schema/index.js';
+/** Whether a mapped value counts as missing. An empty list is a value. */
+export declare function isMissing(value: unknown): boolean;
+/**
+ * The policy for a missing value: mapping rule, then field, then recipe, then
+ * `default` when the field has one, `fail` when it is required, `null` otherwise.
+ *
+ * @param field - The output field.
+ * @param recipe - The output recipe.
+ * @param rule - The mapping rule that produced the value, if any.
+ * @returns The policy to apply.
+ */
+export declare function resolveMissingPolicy(field: FieldSpec, recipe: OutputRecipe, rule?: MappingRule): MissingPolicy;
+//# sourceMappingURL=missing-value.policy.d.ts.map

package/dist/src/output-mapping/output-field.validator.d.ts

@@ -0,0 +1,10 @@
+import type { FieldSpec } from '../recipe-schema/index.js';
+/**
+ * Checks a present, coerced value against the field's quality rules.
+ *
+ * @param value - A non-missing coerced value.
+ * @param field - The output field.
+ * @returns Every violated rule, as messages; empty when valid.
+ */
+export declare function validateField(value: unknown, field: FieldSpec): string[];
+//# sourceMappingURL=output-field.validator.d.ts.map

package/dist/src/output-mapping/output-record.model.d.ts

@@ -0,0 +1,20 @@
+/** One record a crawl produced, validated against its output recipe. */
+export interface OutputRecord {
+    data: Record<string, unknown>;
+    /** The identity from the output's `key` fields, `null` when the output declares none. */
+    key: string | null;
+    source: {
+        recipeId: string;
+        url: string;
+        emittedAt: string;
+    };
+}
+/**
+ * The identity of a record: its key field values, in output order, as one string.
+ *
+ * @param data - The validated record data.
+ * @param keyFields - The output fields marked `key`.
+ * @returns The key, or `null` when there are no key fields.
+ */
+export declare function recordKey(data: Record<string, unknown>, keyFields: readonly string[]): string | null;
+//# sourceMappingURL=output-record.model.d.ts.map

package/dist/src/recipe-loading/index.d.ts

@@ -0,0 +1,9 @@
+export { loadRecipeSet, loadRecipes, bindRecipeSet } from './load-recipe-set.use-case.js';
+export type { RecipeSetSource } from './load-recipe-set.use-case.js';
+export { readRecipeSource } from './read-recipe-source.use-case.js';
+export type { RecipeSource, RecipeBytes, RecipeDocument } from './recipe-source.contract.js';
+export { RecipeSet } from './recipe-set.model.js';
+export { validateBinding, fieldAt } from './recipe-binding.validator.js';
+export { RecipeBindingError } from './recipe-binding.error.js';
+export type { BindingIssue } from './recipe-binding.error.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-loading/load-recipe-set.use-case.d.ts

@@ -0,0 +1,45 @@
+import type { InputRecipe, OutputRecipe } from '../recipe-schema/index.js';
+import type { RecipeSource } from './recipe-source.contract.js';
+import { RecipeSet } from './recipe-set.model.js';
+/** What to load, with the output recipe kept apart from the inputs. */
+export interface RecipeSetSource {
+    /** The output recipe, or a source holding exactly one output recipe among others. */
+    output: RecipeSource;
+    /**
+     * The input recipes. The output recipe itself is skipped when found here, so
+     * one directory or bundle holding both can be passed as both.
+     */
+    inputs: readonly RecipeSource[];
+}
+/**
+ * Loads, validates and binds one output recipe with its input recipes.
+ *
+ * @param source - Where the recipes are; each part takes any {@link RecipeSource}.
+ * @returns A bound set, inputs in the order given.
+ * @throws RecipeValidationError when a recipe does not match its contract.
+ * @throws RecipeBindingError when an input cannot feed the output.
+ */
+export declare function loadRecipeSet(source: RecipeSetSource): Promise<RecipeSet>;
+/**
+ * Loads, validates and binds recipes from one source holding all of them, the
+ * output recipe told apart from the inputs by its `kind`: a directory, a JSON
+ * Lines file or string, a `Blob` or `Buffer` of either, or an array of recipe
+ * objects.
+ *
+ * @param source - Where the recipes are.
+ * @returns A bound set, inputs in the order found.
+ * @throws Error when the source does not hold exactly one output recipe.
+ * @throws RecipeValidationError when a recipe does not match its contract.
+ * @throws RecipeBindingError when an input cannot feed the output.
+ */
+export declare function loadRecipes(source: RecipeSource): Promise<RecipeSet>;
+/**
+ * Binds already-parsed recipes into a set.
+ *
+ * @param output - The output recipe.
+ * @param inputs - The input recipes.
+ * @returns A bound set.
+ * @throws RecipeBindingError when an input cannot feed the output.
+ */
+export declare function bindRecipeSet(output: OutputRecipe, inputs: readonly InputRecipe[]): RecipeSet;
+//# sourceMappingURL=load-recipe-set.use-case.d.ts.map

package/dist/src/recipe-loading/read-recipe-source.use-case.d.ts

@@ -0,0 +1,14 @@
+import type { RecipeDocument, RecipeSource } from './recipe-source.contract.js';
+/**
+ * Reads recipes from any {@link RecipeSource}: paths, JSON or JSON Lines text,
+ * bytes, decoded objects, or an array mixing them. Nothing is validated yet;
+ * the documents keep where they came from, for error messages.
+ *
+ * @param source - Where the recipes are.
+ * @param label - What to call recipes that did not come from a file.
+ * @returns The decoded recipes, in the order given.
+ * @throws Error naming the source when a path is missing, text does not
+ * decode, or a value is not a recipe source at all.
+ */
+export declare function readRecipeSource(source: RecipeSource, label?: string): Promise<RecipeDocument[]>;
+//# sourceMappingURL=read-recipe-source.use-case.d.ts.map

package/dist/src/recipe-loading/recipe-binding.error.d.ts

@@ -0,0 +1,14 @@
+/** One problem in how an input recipe binds to its output recipe. */
+export interface BindingIssue {
+    recipeId: string;
+    /** Where in the input recipe: `mapping.price`, `steps.1.steps.0`, `session.bootstrap.steps.2`. */
+    path: string;
+    message: string;
+}
+/** An input recipe that parses but cannot feed its output recipe. */
+export declare class RecipeBindingError extends Error {
+    readonly issues: readonly BindingIssue[];
+    readonly name = "RecipeBindingError";
+    constructor(issues: readonly BindingIssue[]);
+}
+//# sourceMappingURL=recipe-binding.error.d.ts.map

package/dist/src/recipe-loading/recipe-binding.validator.d.ts

@@ -0,0 +1,32 @@
+import type { FieldSpec, InputRecipe, OutputRecipe } from '../recipe-schema/index.js';
+import type { BindingIssue } from './recipe-binding.error.js';
+/**
+ * Checks that an input recipe can actually feed its output recipe:
+ *
+ * - every mapping key names an output field (dotted for nested objects), and an
+ *   `each` rule targets an array of objects;
+ * - every `from` / `each` / `over` root is a step id bound anywhere in the
+ *   recipe, a `forEach` variable, a `paginate` `as` binding, or one of `page`,
+ *   `start`, `vars` (`emit` snapshots the whole scope chain, so any id can feed
+ *   the mapping);
+ * - every required output field is mapped, defaulted, or generated;
+ * - step ids are unique along any path;
+ * - web-only steps appear only in web recipes or inside a bootstrap, api-only
+ *   steps only in api recipes, and `next.selector` only in web mode;
+ * - exactly one emitting construct exists on any path (the two branches of an
+ *   `if` are separate paths).
+ *
+ * @param input - A parsed input recipe.
+ * @param output - The parsed output recipe it names.
+ * @returns Every problem found; empty when the recipes bind.
+ */
+export declare function validateBinding(input: InputRecipe, output: OutputRecipe): BindingIssue[];
+/**
+ * The output field at a dotted target, walking into `object` members.
+ *
+ * @param fields - The output recipe's fields.
+ * @param target - A mapping key.
+ * @returns The field, or `undefined`.
+ */
+export declare function fieldAt(fields: Record<string, FieldSpec>, target: string): FieldSpec | undefined;
+//# sourceMappingURL=recipe-binding.validator.d.ts.map

package/dist/src/recipe-loading/recipe-file.repository.d.ts

@@ -0,0 +1,11 @@
+import type { RecipeDocument } from './recipe-source.contract.js';
+/**
+ * Reads one recipe file, or every `.json` and `.jsonl` file directly inside a
+ * directory. A file holds one recipe, an array of them, or JSON Lines.
+ *
+ * @param location - A file or directory path.
+ * @returns The decoded recipes, files sorted by path.
+ * @throws When the path does not exist or a file is neither JSON nor JSON Lines.
+ */
+export declare function readRecipeFiles(location: string): Promise<RecipeDocument[]>;
+//# sourceMappingURL=recipe-file.repository.d.ts.map

package/dist/src/recipe-loading/recipe-set.model.d.ts

@@ -0,0 +1,12 @@
+import type { InputRecipe, OutputRecipe } from '../recipe-schema/index.js';
+/**
+ * One output recipe and the input recipes that feed it. The invariant that
+ * every input names this output is checked on construction; deeper binding
+ * rules live in the binding validator.
+ */
+export declare class RecipeSet {
+    readonly output: OutputRecipe;
+    readonly inputs: readonly InputRecipe[];
+    constructor(output: OutputRecipe, inputs: readonly InputRecipe[]);
+}
+//# sourceMappingURL=recipe-set.model.d.ts.map

package/dist/src/recipe-loading/recipe-source.contract.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Raw bytes holding recipe JSON or JSON Lines, UTF-8: a `Buffer` or any other
+ * typed array, an `ArrayBuffer`, a `Blob` or `File`, or a stream of chunks (a
+ * Node `Readable`, a web `ReadableStream`, any async iterable of bytes or text).
+ */
+export type RecipeBytes = Blob | ArrayBuffer | ArrayBufferView | AsyncIterable<Uint8Array | string>;
+/**
+ * Where recipes come from. Each form holds one recipe or many:
+ *
+ * - a string starting with `{` or `[` (after whitespace): JSON text (one recipe
+ *   or an array of them) or JSON Lines text (one recipe per line);
+ * - any other string: a path to a `.json` or `.jsonl` file, or a directory whose
+ *   `.json` and `.jsonl` files are read (sorted, not recursive);
+ * - {@link RecipeBytes}: the same text, still encoded;
+ * - an object: one recipe, already decoded;
+ * - an array: any mix of the above.
+ */
+export type RecipeSource = string | RecipeBytes | object | readonly RecipeSource[];
+/** One decoded recipe before validation, with where it came from. */
+export interface RecipeDocument {
+    /**
+     * A file path, `path:line` for a JSON Lines file, a `File`'s name, or a
+     * positional label (`recipes[2]`, `recipes:3`) for recipes that came from memory.
+     */
+    source: string;
+    content: unknown;
+}
+//# sourceMappingURL=recipe-source.contract.d.ts.map

package/dist/src/recipe-loading/recipe-text.mapper.d.ts

@@ -0,0 +1,14 @@
+import type { RecipeDocument } from './recipe-source.contract.js';
+/**
+ * Decodes recipe text: one JSON document (a recipe, or an array of recipes) or
+ * JSON Lines (one recipe per non-blank line).
+ *
+ * @param text - The text.
+ * @param label - Where it came from, prefixed to each document's source.
+ * @returns The decoded recipes: `label` for a single one, `label[i]` for array
+ * items, `label:line` for JSON Lines.
+ * @throws Error naming the label (and the line, for JSON Lines) when the text
+ * is neither.
+ */
+export declare function parseRecipeText(text: string, label: string): RecipeDocument[];
+//# sourceMappingURL=recipe-text.mapper.d.ts.map

package/dist/src/recipe-schema/index.d.ts

@@ -0,0 +1,15 @@
+export * from './recipe-kind.enum.js';
+export { fieldSpecSchema, outputRecipeSchema } from './output-recipe.contract.js';
+export type { FieldSpec, OutputRecipe } from './output-recipe.contract.js';
+export { stepSchema, errorPolicySchema, paginateNextSchema } from './step.contract.js';
+export type { Step, StepType, StepBaseFields, TargetFields, ErrorPolicy, PaginateNext, TakeKind, GotoStep, ClickStep, FillStep, PressStep, SelectStep, ScrollStep, WaitStep, EvaluateStep, ScreenshotStep, RequestStep, ExtractStep, SetStep, CollectStep, ForEachStep, IfStep, PaginateStep, EmitStep, HookStep, } from './step.contract.js';
+export { transformRuleSchema, mappingRuleSchema } from './transform-rule.contract.js';
+export type { TransformRule, TransformOp, MappingRule, FromRule, EachRule } from './transform-rule.contract.js';
+export { inputRecipeSchema, sessionSpecSchema, startPointSchema } from './input-recipe.contract.js';
+export type { InputRecipe, SessionSpec, SessionBootstrap, SessionAccess, BlockRule, BlockRotation, StartPoint, CrawlLimits, RecipeCookie } from './input-recipe.contract.js';
+export { parseInputRecipe, parseOutputRecipe, recipeKindOf } from './recipe.validator.js';
+export { RecipeValidationError } from './recipe-validation.error.js';
+export type { RecipeIssue } from './recipe-validation.error.js';
+export { inputRecipeJsonSchema, outputRecipeJsonSchema } from './json-schema.mapper.js';
+export type { JsonSchemaDocument } from './json-schema.mapper.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/recipe-schema/input-recipe.contract.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import type { CrawlMode, KeepKind } from './recipe-kind.enum.js';
+import type { ErrorPolicy, Step } from './step.contract.js';
+import type { MappingRule } from './transform-rule.contract.js';
+/** A URL the crawl starts from, with variables visible to its templates as `vars.*`. */
+export interface StartPoint {
+    url: string;
+    vars?: Record<string, string | number | boolean>;
+}
+/** A cookie in Playwright's shape. */
+export interface RecipeCookie {
+    name: string;
+    value: string;
+    domain: string;
+    path?: string;
+    expires?: number;
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+}
+/** Runs before the crawl, always in a browser, to obtain cookies or storage (a login, a consent wall). */
+export interface SessionBootstrap {
+    steps: Step[];
+    keep: KeepKind[];
+    /** Persist the resulting storage state for the next run. */
+    saveTo?: string;
+}
+/**
+ * What the site needs from the network, never how to get it: the runner's
+ * access config maps a profile name to a provider and credentials.
+ */
+export interface SessionAccess {
+    /** An access profile of the runner's config; its default when omitted. */
+    profile?: string;
+    /** ISO 3166 country the traffic should come from, for profiles that target by country. */
+    country?: string;
+    /** `false` lets the provider rotate IPs per request; the profile decides when omitted. */
+    sticky?: boolean;
+}
+/**
+ * What counts as the site refusing the crawl, checked on every navigation and
+ * request. Any condition that matches is a block. When omitted: status 403 or
+ * 429, or an AWS WAF challenge (`x-amzn-waf-action: challenge`).
+ */
+export interface BlockRule {
+    status?: number[];
+    /** Header name to a regular expression its value must match (case-insensitive). */
+    header?: Record<string, string>;
+    /** A regular expression the response body must match (case-insensitive). */
+    text?: string;
+}
+/** What to do when blocked: take a new access lease (a new IP), reopen the session, and retry the step. */
+export interface BlockRotation {
+    rotate: boolean;
+    /** How many rotations a recipe run may use. Default 2. */
+    attempts?: number;
+}
+export interface SessionSpec {
+    headers?: Record<string, string>;
+    cookies?: RecipeCookie[];
+    userAgent?: string;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** Reuse a storage state saved by a previous bootstrap. */
+    storageStatePath?: string;
+    bootstrap?: SessionBootstrap;
+    access?: SessionAccess;
+    blockedWhen?: BlockRule;
+    onBlock?: BlockRotation;
+}
+export interface CrawlLimits {
+    maxRecords?: number;
+    /** Minimum interval between two request starts across the recipe, whatever runs in parallel. */
+    delayMs?: number;
+    timeoutMs?: number;
+    /** How many `forEach` iterations may run at once (api mode; a web recipe drives one page). Default 1. */
+    concurrency?: number;
+}
+/** Where to start, how to navigate, what to extract, and how it maps to one output recipe. */
+export interface InputRecipe {
+    $schema?: string;
+    kind: 'input';
+    id: string;
+    /** The `OutputRecipe.id` this recipe feeds. */
+    output: string;
+    mode: CrawlMode;
+    description?: string;
+    start: StartPoint[];
+    vars?: Record<string, string | number | boolean>;
+    session?: SessionSpec;
+    limits?: CrawlLimits;
+    /** Default policy for every step. */
+    onError?: ErrorPolicy;
+    steps: Step[];
+    /** Keyed by output field path, dotted for nested fields. */
+    mapping: Record<string, MappingRule>;
+}
+export declare const startPointSchema: z.ZodType<StartPoint>;
+export declare const sessionSpecSchema: z.ZodType<SessionSpec>;
+export declare const inputRecipeSchema: z.ZodType<InputRecipe>;
+//# sourceMappingURL=input-recipe.contract.d.ts.map

package/dist/src/recipe-schema/json-schema.mapper.d.ts

@@ -0,0 +1,15 @@
+/** A JSON Schema document, as `z.toJSONSchema` produces it. */
+export type JsonSchemaDocument = Record<string, unknown>;
+/**
+ * The JSON Schema for output recipe files, for editors and other tools.
+ *
+ * @returns A draft 2020-12 document.
+ */
+export declare function outputRecipeJsonSchema(): JsonSchemaDocument;
+/**
+ * The JSON Schema for input recipe files, for editors and other tools.
+ *
+ * @returns A draft 2020-12 document.
+ */
+export declare function inputRecipeJsonSchema(): JsonSchemaDocument;
+//# sourceMappingURL=json-schema.mapper.d.ts.map

package/dist/src/recipe-schema/output-recipe.contract.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import type { FieldType, GeneratedValue, MissingPolicy, RecipeMissingPolicy } from './recipe-kind.enum.js';
+/** One field of the records a crawl produces: its type, quality rules and what to do when it is missing. */
+export interface FieldSpec {
+    type: FieldType;
+    description?: string;
+    /** Default `false`. */
+    required?: boolean;
+    /** Default `false`. */
+    nullable?: boolean;
+    /** Used when the value is missing and the resolved policy is `default`. */
+    default?: unknown;
+    onMissing?: MissingPolicy;
+    /** Part of the record identity, used to drop duplicates. */
+    key?: boolean;
+    /** Supplied by the engine, never mapped. */
+    generated?: GeneratedValue;
+    /** Input format for `date` / `datetime`; output is always ISO 8601. */
+    format?: string;
+    /** ISO 4217 code for `currency`. */
+    currency?: string;
+    /** Allowed values for `enum`. */
+    values?: string[];
+    /** Element spec for `array`. */
+    items?: FieldSpec;
+    /** Member specs for `object`. A `json` field takes none: it keeps whatever it is given. */
+    fields?: Record<string, FieldSpec>;
+    min?: number;
+    max?: number;
+    pattern?: string;
+    minLength?: number;
+    maxLength?: number;
+}
+/** The schema of the records every input recipe bound to it must produce. */
+export interface OutputRecipe {
+    $schema?: string;
+    kind: 'output';
+    id: string;
+    version: number;
+    description?: string;
+    fields: Record<string, FieldSpec>;
+    /** Recipe-wide default: `fail` for required fields, `null` otherwise. */
+    onMissing?: RecipeMissingPolicy;
+}
+export declare const fieldSpecSchema: z.ZodType<FieldSpec>;
+export declare const outputRecipeSchema: z.ZodType<OutputRecipe>;
+//# sourceMappingURL=output-recipe.contract.d.ts.map

package/dist/src/recipe-schema/recipe-kind.enum.d.ts

@@ -0,0 +1,31 @@
+/** The closed vocabularies a recipe file can use. Each is a `readonly` tuple so zod and TypeScript share it. */
+export declare const RECIPE_KINDS: readonly ["input", "output"];
+export declare const CRAWL_MODES: readonly ["web", "api"];
+export declare const SELECTOR_KINDS: readonly ["css", "xpath", "jsonpath", "regex"];
+/** `take` also accepts `attr:<name>`, which is validated by pattern rather than listed. */
+export declare const TAKE_KINDS: readonly ["text", "html", "value", "json"];
+export declare const BODY_KINDS: readonly ["json", "html", "text"];
+export declare const FIELD_TYPES: readonly ["string", "number", "integer", "boolean", "date", "datetime", "currency", "url", "enum", "array", "object", "json"];
+export declare const MISSING_POLICIES: readonly ["fail", "skip-record", "null", "default"];
+export declare const RECIPE_MISSING_POLICIES: readonly ["fail", "skip-record", "null"];
+export declare const ERROR_POLICIES: readonly ["fail", "skip", "retry"];
+export declare const GENERATED_VALUES: readonly ["now", "uuid", "sourceUrl", "recipeId"];
+export declare const KEEP_KINDS: readonly ["cookies", "localStorage"];
+export declare const WAIT_UNTIL: readonly ["load", "domcontentloaded", "networkidle", "commit"];
+export declare const HTTP_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"];
+/** Steps that only make sense with a live browser page. */
+export declare const WEB_ONLY_STEPS: readonly ["goto", "click", "fill", "press", "select", "scroll", "wait", "evaluate", "screenshot"];
+/** Steps that only make sense against an HTTP request context. */
+export declare const API_ONLY_STEPS: readonly ["request"];
+export type RecipeKind = typeof RECIPE_KINDS[number];
+export type CrawlMode = typeof CRAWL_MODES[number];
+export type SelectorKind = typeof SELECTOR_KINDS[number];
+export type BodyKind = typeof BODY_KINDS[number];
+export type FieldType = typeof FIELD_TYPES[number];
+export type MissingPolicy = typeof MISSING_POLICIES[number];
+export type RecipeMissingPolicy = typeof RECIPE_MISSING_POLICIES[number];
+export type GeneratedValue = typeof GENERATED_VALUES[number];
+export type KeepKind = typeof KEEP_KINDS[number];
+export type WaitUntil = typeof WAIT_UNTIL[number];
+export type HttpMethod = typeof HTTP_METHODS[number];
+//# sourceMappingURL=recipe-kind.enum.d.ts.map

package/dist/src/recipe-schema/recipe-validation.error.d.ts

@@ -0,0 +1,17 @@
+/** One problem found in a recipe file, located by its JSON path. */
+export interface RecipeIssue {
+    /** Dotted JSON path, `''` for the root. */
+    path: string;
+    message: string;
+}
+/** A recipe that does not match its contract. `issues` lists every problem, not just the first. */
+export declare class RecipeValidationError extends Error {
+    /** Which recipe: a file path or an id when known. */
+    readonly source: string;
+    readonly issues: readonly RecipeIssue[];
+    readonly name = "RecipeValidationError";
+    constructor(
+    /** Which recipe: a file path or an id when known. */
+    source: string, issues: readonly RecipeIssue[]);
+}
+//# sourceMappingURL=recipe-validation.error.d.ts.map

package/dist/src/recipe-schema/recipe.validator.d.ts

@@ -0,0 +1,28 @@
+import type { InputRecipe } from './input-recipe.contract.js';
+import type { OutputRecipe } from './output-recipe.contract.js';
+/**
+ * Parses an unknown value (a decoded JSON file) as an output recipe.
+ *
+ * @param value - The decoded JSON.
+ * @param source - A name for error messages, usually the file path.
+ * @returns The typed recipe.
+ * @throws RecipeValidationError when it does not match the contract.
+ */
+export declare function parseOutputRecipe(value: unknown, source?: string): OutputRecipe;
+/**
+ * Parses an unknown value (a decoded JSON file) as an input recipe.
+ *
+ * @param value - The decoded JSON.
+ * @param source - A name for error messages, usually the file path.
+ * @returns The typed recipe.
+ * @throws RecipeValidationError when it does not match the contract.
+ */
+export declare function parseInputRecipe(value: unknown, source?: string): InputRecipe;
+/**
+ * Reads the `kind` of a decoded recipe without validating the rest.
+ *
+ * @param value - The decoded JSON.
+ * @returns `'input'`, `'output'`, or `undefined` when it is neither.
+ */
+export declare function recipeKindOf(value: unknown): 'input' | 'output' | undefined;
+//# sourceMappingURL=recipe.validator.d.ts.map

package/dist/src/recipe-schema/step.contract.d.ts

@@ -0,0 +1,152 @@
+import { z } from 'zod';
+import { TAKE_KINDS } from './recipe-kind.enum.js';
+import type { BodyKind, HttpMethod, SelectorKind, WaitUntil } from './recipe-kind.enum.js';
+/** What to do when a step fails. Resolved step -> recipe -> `fail`. */
+export type ErrorPolicy = {
+    policy: 'fail';
+} | {
+    policy: 'skip';
+} | {
+    policy: 'retry';
+    attempts: number;
+    backoffMs?: number;
+};
+/** What a value is taken from an element or JSON node: text, inner HTML, an attribute, an input value, or the node itself. */
+export type TakeKind = typeof TAKE_KINDS[number] | `attr:${string}`;
+/** How `paginate` finds the next page once the page body has run. */
+export type PaginateNext = {
+    selector: string;
+} | {
+    url: string;
+} | {
+    jsonpath: string;
+    as?: string;
+};
+export interface StepBaseFields {
+    /** Names the value this step produces. */
+    id?: string;
+    onError?: ErrorPolicy;
+    /** A template; the step runs only when it renders truthy. */
+    when?: string;
+}
+export interface GotoStep extends StepBaseFields {
+    type: 'goto';
+    url: string;
+    waitUntil?: WaitUntil;
+}
+/** Where an interaction lands: a selector, or a `target` template that renders to a live element (a `forEach` over `selector`) or to a selector string. */
+export interface TargetFields {
+    selector?: string;
+    target?: string;
+}
+export interface ClickStep extends StepBaseFields, TargetFields {
+    type: 'click';
+    optional?: boolean;
+}
+export interface FillStep extends StepBaseFields, TargetFields {
+    type: 'fill';
+    value: string;
+}
+export interface PressStep extends StepBaseFields, TargetFields {
+    type: 'press';
+    key: string;
+}
+/** Picks an option of a `<select>` by value, label or index. */
+export interface SelectStep extends StepBaseFields, TargetFields {
+    type: 'select';
+    value?: string;
+    label?: string;
+    index?: number;
+}
+export interface ScrollStep extends StepBaseFields {
+    type: 'scroll';
+    to: string;
+    times?: number;
+    untilStable?: boolean;
+}
+export interface WaitStep extends StepBaseFields {
+    type: 'wait';
+    selector?: string;
+    ms?: number;
+    state?: 'networkidle';
+}
+export interface EvaluateStep extends StepBaseFields {
+    type: 'evaluate';
+    script: string;
+}
+export interface ScreenshotStep extends StepBaseFields {
+    type: 'screenshot';
+    path: string;
+}
+export interface RequestStep extends StepBaseFields {
+    type: 'request';
+    method?: HttpMethod;
+    url: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    body?: unknown;
+    as?: BodyKind;
+}
+export interface ExtractStep extends StepBaseFields {
+    type: 'extract';
+    selector: string;
+    kind: SelectorKind;
+    take?: TakeKind;
+    many?: boolean;
+    /** Id of a document or fragment to read instead of the current document. */
+    from?: string;
+}
+export interface SetStep extends StepBaseFields {
+    type: 'set';
+    value: unknown;
+}
+/**
+ * Appends to a list bound in an enclosing scope (a `set` to `[]` before the
+ * loop), so values gathered page by page or item by item outlive the child
+ * scope that found them. A list value is appended item by item.
+ */
+export interface CollectStep extends StepBaseFields {
+    type: 'collect';
+    into: string;
+    value: unknown;
+}
+/** Runs a body per item of a list (`over`) or per live element matching `selector` (web mode; the elements are re-resolved on every use). */
+export interface ForEachStep extends StepBaseFields {
+    type: 'forEach';
+    over?: string;
+    selector?: string;
+    as: string;
+    steps: Step[];
+    emit?: true | {
+        output: string;
+    };
+}
+/** Runs `steps` when `test` renders truthy, else `else`; both in the current scope. */
+export interface IfStep extends StepBaseFields {
+    type: 'if';
+    test: string;
+    steps: Step[];
+    else?: Step[];
+}
+export interface PaginateStep extends StepBaseFields {
+    type: 'paginate';
+    next: PaginateNext;
+    until?: string;
+    maxPages?: number;
+    steps: Step[];
+}
+export interface EmitStep extends StepBaseFields {
+    type: 'emit';
+    output?: string;
+}
+export interface HookStep extends StepBaseFields {
+    type: 'hook';
+    name: string;
+    args?: Record<string, unknown>;
+}
+export type Step = GotoStep | ClickStep | FillStep | PressStep | SelectStep | ScrollStep | WaitStep | EvaluateStep | ScreenshotStep | RequestStep | ExtractStep | SetStep | CollectStep | ForEachStep | IfStep | PaginateStep | EmitStep | HookStep;
+export type StepType = Step['type'];
+export declare const errorPolicySchema: z.ZodType<ErrorPolicy>;
+export declare const paginateNextSchema: z.ZodType<PaginateNext>;
+export declare const stepSchema: z.ZodType<Step>;
+//# sourceMappingURL=step.contract.d.ts.map