@octocrawl/sdk 0.3.0

package/dist/types/cjs/contracts/map.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Map contract: the URLs of a site, discovered without fetching each page.
+ *
+ * A map reads robots.txt, at most one page body (the start URL, on the http
+ * rung) and the sitemaps the site declares, inside one deadline, and returns
+ * what it found as links with the evidence for each: how it was found, the
+ * sitemap file that listed it, the robots.txt verdict, and a title only where
+ * one was already in hand (the start page's own metadata, an anchor's text, a
+ * sitemap's `<news:title>`). Deeper discovery is a crawl. Types only, no I/O:
+ * the runtime's MapRunner composes the sources, the API engine wires the real
+ * ones.
+ */
+import type { AgentHints, MapRequest } from './api.js';
+import type { CrawlMode } from './compliance.js';
+import type { SitemapFileRecord, SitemapMode, SitemapSource, SitemapSourceKind } from './crawl.js';
+import type { ExecutionContext } from './execution.js';
+import type { Evidence, FetchResult } from './result.js';
+import type { FailureReason, ResultStatus } from './status.js';
+/** Sitemap files one map reads at most, an index and its children each counting as one (gov.uk's index lists 35 children). A crawl keeps its own 20. */
+export declare const MAP_SITEMAP_MAX_FILES = 50;
+/** Hosts beside the start host whose robots.txt one map reads at most; URLs on further hosts are refused unchecked. */
+export declare const MAP_MAX_ROBOTS_HOSTS = 20;
+/** Samples each refused counter keeps at most. */
+export declare const MAP_REFUSED_SAMPLES = 20;
+/** The longest anchor-text title a map link carries, in characters. */
+export declare const MAP_TITLE_MAX_CHARS = 300;
+/** How a map link was found: it is the start URL, a link on the start page, or a sitemap entry. */
+export type MapLinkVia = 'start' | 'link' | 'sitemap';
+export interface MapLink {
+    /** The canonical URL: fragment and tracking parameters dropped (the whole query with ignoreQueryParameters). */
+    url: string;
+    /** Present only when a title was in hand: the start page's own, an anchor's text, or a sitemap's `<news:title>`. Never generated, never empty. */
+    title?: string;
+    /** The start page's own meta description; no other link has one. */
+    description?: string;
+    /** Where `title` came from; present exactly when `title` is. */
+    titleSource?: 'page' | 'anchor' | 'sitemap';
+    via: MapLinkVia[];
+    /** The first sitemap file that listed the URL. */
+    sitemapFile?: string;
+    /** The `<lastmod>` the sitemap gave, as written. */
+    lastmod?: string;
+    /** The robots.txt verdict for the URL under the map's declared identity; a disallowed URL is never a link. */
+    robots: 'allowed' | 'no_robots';
+}
+export type MapStatus = 'completed' | 'partial' | 'failed';
+/** What the start page read gave, or why it was not read (`failed/policy_denied` when robots.txt disallows the start URL or could not be read). */
+export interface MapStartPage {
+    url: string;
+    finalUrl: string | null;
+    httpStatus: number | null;
+    status: ResultStatus;
+    failureReason: FailureReason | null;
+    lane: 'http';
+    /**
+     * The start URL's robots.txt verdict; `unreachable` when its robots.txt
+     * could not be read (a 5xx, a network error, its lookup's timeout or the
+     * egress policy), which counts as a complete disallow but is no rule the
+     * publisher wrote; null when it was not read before the deadline.
+     */
+    robots: 'allowed' | 'no_robots' | 'disallowed' | 'unreachable' | null;
+    /** Why robots.txt could not be read (`server_error`, `network_error`, `timeout`, ...); present only with robots `unreachable`. */
+    robotsUnreachable?: string;
+    rawBodySha256: string | null;
+    /** http(s) links the page holds, each once, before scope, robots and limit. */
+    linksFound: number;
+    title: string | null;
+    description: string | null;
+}
+export interface MapSitemapSource {
+    mode: SitemapMode;
+    sources: SitemapSourceKind[];
+    files: SitemapFileRecord[];
+    /** Entries the reader offered the map. */
+    listed: number;
+    /** Entries the map returned as new links (a URL already found on the page is merged, not counted). */
+    accepted: number;
+    truncated: 'files' | 'urls' | 'time' | null;
+    /** Why the load itself failed, when it threw; null otherwise. */
+    error: string | null;
+}
+/** Candidates the map did not return, by reason, with samples. */
+export interface MapRefused {
+    /** The same URL again (merged into the link it repeats when that link was returned). */
+    duplicate: number;
+    /** A variant folded into a URL seen first (`/a/` after `/a`, the www twin, ...), or an http link replaced by its https variant; `samples.collapsed` names both, `into` being the URL returned. */
+    collapsed: number;
+    hostDenied: number;
+    subtreeDenied: number;
+    pathDenied: number;
+    assetDenied: number;
+    /** Disallowed by robots.txt, or on a host whose robots.txt was unreachable or denied by the egress policy. */
+    robots: number;
+    /** On a host whose robots.txt was not read: past MAP_MAX_ROBOTS_HOSTS, or after the deadline. */
+    robotsUnchecked: number;
+    /** In scope but left out by `search`: not every word is in the URL or the title in hand. Counted before robots.txt and `limit`. */
+    searchFiltered: number;
+    /** Accepted candidates offered after `limit` links were in hand. */
+    overLimit: number;
+    samples: {
+        collapsed: Array<{
+            url: string;
+            into: string;
+        }>;
+        hostDenied: string[];
+        robots: string[];
+    };
+}
+export declare const MAP_WARNING_CODES: readonly ["map_timeout", "start_page_unreadable", "start_page_client_rendered", "sitemap_unreadable", "sitemap_files_capped", "robots_host_cap", "robots_unreachable", "map_record_unwritten"];
+export type MapWarningCode = (typeof MAP_WARNING_CODES)[number];
+export interface MapWarning {
+    code: MapWarningCode;
+    message: string;
+}
+export interface MapResponse {
+    /** The map run's id: its record key (GET /v1/maps/:id). */
+    id: string;
+    url: string;
+    /**
+     * `completed`: every source asked for was read or is definitively absent,
+     * and the deadline did not cut the run (reaching `limit` is completed).
+     * `partial`: links came back, but the deadline cut the run or a source
+     * failed. `failed`: no links, and a source failed or the deadline fired.
+     */
+    status: MapStatus;
+    stoppedBy: 'limit' | 'timeout' | null;
+    /** The start URL, then the start page's links in document order, then sitemap entries not already present, in listed order. */
+    links: MapLink[];
+    sources: {
+        startPage: MapStartPage | null;
+        sitemap: MapSitemapSource | null;
+    };
+    refused: MapRefused;
+    /** The declared identity robots.txt, the start page and the sitemaps were read under. */
+    identity: {
+        mode: CrawlMode;
+        userAgent: string;
+    };
+    warnings: MapWarning[];
+    agentHints?: AgentHints;
+    elapsedMs: number;
+}
+/** One map call as stored under `<taskRoot>/maps/<id>.json` and read back by GET /v1/maps/:id. */
+export interface MapRecord {
+    requestedAt: string;
+    /** The request as parsed, `origin` and `integration` included. */
+    request: MapRequest;
+    response: MapResponse;
+}
+/** One link of the start page: its absolute URL (fragment stripped) and the first non-empty text an anchor gave it, or null. */
+export interface MapPageLink {
+    url: string;
+    text: string | null;
+}
+/** What the start page read gave a map. */
+export interface MapStartPageRead {
+    result: Pick<FetchResult, 'status' | 'failureReason' | 'metadata'> & {
+        evidence: Pick<Evidence, 'finalUrl' | 'httpStatus' | 'rawBodySha256'>;
+    };
+    links: readonly MapPageLink[];
+    /** The http lane found the page filled by script, so its links may be incomplete. */
+    clientRendered?: boolean;
+}
+/** A robots.txt verdict for one URL under the map's declared identity. */
+export type MapRobotsVerdict = 'allowed' | 'no_robots' | {
+    disallowed: true;
+    unreachable?: string;
+};
+/** The fetch paths a map uses; the API engine wires the real ones, tests inject fakes. */
+export interface MapSources {
+    /** The start URL on the http rung alone; never a browser. */
+    readStartPage(url: string, context: ExecutionContext): Promise<MapStartPageRead>;
+    sitemap: SitemapSource;
+    robotsVerdict(url: string, context: ExecutionContext): Promise<MapRobotsVerdict>;
+    identity: {
+        mode: CrawlMode;
+        userAgent: string;
+    };
+}
+//# sourceMappingURL=map.d.ts.map

package/dist/types/cjs/contracts/monitor.d.ts

@@ -0,0 +1,217 @@
+import type { ScrapeOutcome } from './crawl.js';
+/** Deliberately one public document adapter for the first B1/B2 slice. */
+export declare const FIRECRAWL_INTRO_URL = "https://docs.firecrawl.dev/introduction";
+export declare const FIRECRAWL_MONITOR_ID = "firecrawl-introduction";
+export declare const DOCUMENT_RULE_VERSION = "firecrawl-introduction/v1";
+export type FieldValue<T = string | boolean> = {
+    state: 'present';
+    value: T;
+    evidenceRefs: string[];
+} | {
+    state: 'explicit_null';
+    reason: string;
+    evidenceRefs: string[];
+} | {
+    state: 'unobserved';
+    reason: string;
+} | {
+    state: 'conflicting';
+    candidates: {
+        value: T;
+        evidenceRefs: string[];
+    }[];
+} | {
+    state: 'redacted';
+    reason: string;
+};
+export type DocumentFields = Record<string, string | FieldValue>;
+export interface MonitorFieldRule {
+    name: string;
+    heading: string;
+    type: 'text' | 'code' | 'decimal' | 'boolean';
+    required: boolean;
+    nullMarker?: string;
+    redactedMarker?: string;
+    /** Changes in field meaning are schema migrations, not price changes. */
+    unit?: string;
+    currency?: string;
+}
+export interface DocumentMonitorConfig {
+    adapter: 'markdown-sections/v1';
+    workspaceId: string;
+    entityKey: string;
+    viewKey: string;
+    expectedTitle: string;
+    schemaVersion: string;
+    fields: MonitorFieldRule[];
+    conditionalRequests: boolean;
+    /** Acquisition capability is independent of transport caching. Defaults to ladder. */
+    captureMode?: 'http' | 'ladder';
+}
+export type DocumentField = keyof DocumentFields;
+export interface FieldEvidence {
+    field: DocumentField;
+    start: number;
+    end: number;
+    quote: string;
+}
+export interface DocumentAssessment {
+    ruleVersion: string;
+    quality: 'valid' | 'partial' | 'invalid' | 'unknown';
+    reasons: string[];
+    fields: DocumentFields | null;
+    evidence: FieldEvidence[];
+}
+export interface MonitorRevision {
+    monitorId: string;
+    revision: number;
+    url: string;
+    ruleVersion: string;
+    config?: DocumentMonitorConfig;
+    intervalMs: number;
+    staleAfterMs: number;
+    createdAt: number;
+}
+export type MonitorChange = 'initialized' | 'changed' | 'unchanged' | 'cannot_verify';
+/**
+ * Why a committed run moved the baseline. `extraction_reprocessed`: W2L's
+ * reading changed, either a revised rule or fields that changed over a
+ * byte-identical raw body (an extractor upgrade).
+ */
+export type MonitorChangeReason = 'source_changed' | 'initialized' | 'extraction_reprocessed' | 'schema_migrated';
+export interface DocumentDiff {
+    field: DocumentField;
+    before: string | FieldValue | null;
+    after: string | FieldValue | null;
+}
+export interface MonitorRun {
+    id: string;
+    monitorId: string;
+    revision: number;
+    triggerKey: string;
+    state: 'queued' | 'running' | 'waiting_retry' | 'completed' | 'failed' | 'cancelled' | 'expired';
+    epoch: number;
+    fencingToken: number;
+    attemptId: string | null;
+    leaseUntil: number | null;
+    deadlineAt: number | null;
+    nextAttemptAt?: number | null;
+    expectedBaselineId: string | null;
+    createdAt: number;
+    endedAt: number | null;
+    quality: DocumentAssessment['quality'] | null;
+    change: MonitorChange | null;
+    /**
+     * Set when the run initialized or changed the baseline, also when no event
+     * was emitted for it (an extractor upgrade over an unchanged raw body). Null
+     * otherwise and for runs committed before W2L recorded it.
+     */
+    changeReason?: MonitorChangeReason | null;
+    error: string | null;
+}
+export interface MonitorAttempt {
+    id: string;
+    runId: string;
+    fencingToken: number;
+    state: 'running' | 'succeeded' | 'failed' | 'interrupted' | 'cancelled';
+    startedAt: number;
+    endedAt: number | null;
+    recoveredFromAttemptId: string | null;
+}
+export interface MonitorObservation {
+    id: string;
+    runId: string;
+    attemptId: string;
+    observedAt: number;
+    clientWallMs: number;
+    markdownSha256: string | null;
+    /** sha256 of the raw body the assessed Markdown came from; after a 304, the reused body's. Null or absent when unknown. */
+    rawBodySha256?: string | null;
+    /** EXTRACTOR_VERSION of the extractor that produced that Markdown. Null or absent when unknown: rows and cached bodies from before W2L recorded it. */
+    extractorVersion?: string | null;
+    transport?: {
+        etag: string | null;
+        lastModified: string | null;
+        representationKey: string;
+        reusedFrom?: string;
+        responseStatus?: number | null;
+    } | null;
+    outcome: ScrapeOutcome | null;
+    error: string | null;
+}
+export interface MonitorSnapshot {
+    id: string;
+    monitorId: string;
+    revision: number;
+    version: number;
+    observationId: string;
+    assessmentId: string;
+    fields: DocumentFields;
+    /** The extractor that produced these fields; null for snapshots committed before W2L recorded it. */
+    extractorVersion?: string | null;
+    createdAt: number;
+}
+export interface MonitorEvent {
+    id: string;
+    runId: string;
+    monitorId: string;
+    kind: 'initialized' | 'changed';
+    reason: MonitorChangeReason;
+    fromSnapshotId: string | null;
+    toSnapshotId: string;
+    /**
+     * Present when the extractor behind this snapshot differs from the one behind
+     * the previous snapshot: part of `changes` may then come from W2L, not the
+     * source. `from: null` means the previous snapshot predates recorded versions.
+     */
+    extractorChange?: {
+        from: string | null;
+        to: string | null;
+    };
+    changes: DocumentDiff[];
+    observedAt: number;
+}
+export interface MonitorView {
+    revision: MonitorRevision;
+    enabled: boolean;
+    controlEpoch: number;
+    nextRunAt: number;
+    lastCheckedAt: number | null;
+    lastVerifiedAt: number | null;
+    freshness: 'fresh' | 'stale';
+    baseline: MonitorSnapshot | null;
+    runs: MonitorRun[];
+    events: MonitorEvent[];
+    outbox: {
+        eventId: string;
+        state: 'pending' | 'acknowledged';
+        acknowledgedAt: number | null;
+    }[];
+}
+/** A bounded first-use sample. Preview never creates a run, baseline, or event. */
+export interface MonitorPreview {
+    url: string;
+    finalUrl: string | null;
+    status: string;
+    assessment: DocumentAssessment;
+    sampleMarkdown: string | null;
+    capturedAt: number;
+}
+export interface MonitorRunDetail {
+    run: MonitorRun;
+    assessment: DocumentAssessment | null;
+    observation: MonitorObservation | null;
+    attempts: MonitorAttempt[];
+}
+export interface TransportRepresentation {
+    bodySha256?: string;
+    key: string;
+    url: string;
+    etag: string | null;
+    lastModified: string | null;
+    outcome: ScrapeOutcome;
+    /** EXTRACTOR_VERSION that produced `outcome.result.markdown`; absent on bodies cached before W2L recorded it. */
+    extractorVersion?: string;
+    storedAt: number;
+}
+//# sourceMappingURL=monitor.d.ts.map

package/dist/types/cjs/contracts/monitorConfig.d.ts

@@ -0,0 +1,9 @@
+import type { MonitorRevision } from './monitor.js';
+export declare function parseMonitorRevision(input: unknown): MonitorRevision;
+export declare function monitorIdentity(r: MonitorRevision): {
+    resourceKey: string;
+    viewKey: string;
+    workspaceId: string;
+    entityKey: string;
+};
+//# sourceMappingURL=monitorConfig.d.ts.map

package/dist/types/cjs/contracts/policy.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Network egress policy.
+ *
+ * Contract: there is no per-request "allow private network" flag. Private-range
+ * access requires an explicit host/CIDR allowlist that only a server operator can
+ * set (config file or env at process start). API callers cannot widen it.
+ */
+export type PolicyOrigin = 
+/** Set by the operator at process start. The only origin allowed to permit private ranges. */
+'operator'
+/** Derived from an API request. May narrow the effective policy, never widen it. */
+ | 'request';
+export interface NetworkPolicy {
+    origin: PolicyOrigin;
+    /**
+     * Hosts and CIDRs exempt from private-range blocking.
+     * Entries are literal hostnames, IPs, or CIDR blocks (e.g. '127.0.0.1/32').
+     * Ignored — and a violation — when origin is 'request'.
+     */
+    privateAllowlist: readonly string[];
+    maxRedirects: number;
+    maxBodyBytes: number;
+    /**
+     * Cap on a file saved as received (PDF, CSV, XLSX, ZIP, JSON, text), in
+     * place of maxBodyBytes: the operator's `W2L_MAX_FILE_BYTES`. Absent means
+     * DEFAULT_MAX_FILE_BYTES; a request may only lower it (`maxFileBytes`).
+     */
+    maxFileBytes?: number;
+    /** Cap on post-decompression size, to bound zip bombs. */
+    maxDecompressedBytes: number;
+    /** Per-host concurrent request ceiling. */
+    perHostConcurrency: number;
+    /** Minimum delay between requests to the same host. */
+    perHostMinDelayMs: number;
+    respectRobotsTxt: boolean;
+    /** How long one robots.txt lookup may take before the file counts as unreachable. Default 5000. */
+    robotsTimeoutMs?: number;
+    /**
+     * How long an unreachable robots.txt (a 5xx, a network error or a lookup
+     * timeout) stays a complete disallow for its origin before it is fetched
+     * again. Other robots.txt results are kept for the life of the process.
+     * Default 300000 (5 minutes).
+     */
+    robotsUnreachableTtlMs?: number;
+    /**
+     * The operator's forward proxy, read from the standard environment
+     * variables by local-mode entry points (`withEnvironmentProxy`). Hosted
+     * policies never carry one. A proxied host is resolved by the proxy, so only
+     * the literal host checks apply to it (`proxyFor`). Ignored unless origin
+     * is 'operator'.
+     */
+    egressProxy?: EgressProxy | null;
+    /**
+     * The operator's contact from `W2L_CONTACT` (`withOperatorContact`), which
+     * research mode declares in its User-Agent. Absent or null declares none.
+     */
+    contact?: string | null;
+}
+/**
+ * Where outbound requests go when the operator's environment names a proxy:
+ * one proxy per URL scheme, and NO_PROXY entries that go direct. Loopback
+ * always goes direct. `https` and `http` are equal or one of them is null,
+ * because the browser lane can route through only one proxy.
+ */
+export interface EgressProxy {
+    source: 'environment';
+    /** From HTTPS_PROXY / https_proxy. Null sends https: URLs direct. */
+    https: ProxyServer | null;
+    /** From HTTP_PROXY / http_proxy. Null sends http: URLs direct. */
+    http: ProxyServer | null;
+    /** NO_PROXY / no_proxy entries, lower-cased. */
+    noProxy: readonly string[];
+}
+export interface ProxyServer {
+    /** `http://host:port` or `https://host:port`, without credentials. */
+    url: string;
+    /** `host:port`: the only form of the proxy that results record. */
+    endpoint: string;
+    /** Credentials from the variable's userinfo. Held in memory for the proxy, never recorded or logged. */
+    username?: string;
+    password?: string;
+}
+export declare const DEFAULT_NETWORK_POLICY: NetworkPolicy;
+export declare const POLICY_VIOLATION: readonly ["private_address", "loopback_address", "link_local_address", "cloud_metadata_address", "unspecified_address", "unsupported_scheme", "malformed_url", "privilege_escalation"];
+export type PolicyViolation = (typeof POLICY_VIOLATION)[number];
+export interface PolicyDecision {
+    allowed: boolean;
+    violation: PolicyViolation | null;
+    /** The IP the hostname resolved to, pinned for the actual connection. */
+    pinnedAddress: string | null;
+    detail: string | null;
+}
+//# sourceMappingURL=policy.d.ts.map

package/dist/types/cjs/contracts/proxy.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The operator's forward proxy from the standard environment variables, for
+ * local mode only. Hosted mode never reads them: its SSRF guarantees depend
+ * on direct connections to DNS-pinned addresses.
+ *
+ * Semantics follow curl. HTTPS_PROXY serves https: URLs and HTTP_PROXY http:
+ * URLs (the lower-case names win). A NO_PROXY entry matches its host and
+ * every subdomain (a leading "." or "*." is ignored), `*` disables the proxy,
+ * and `host:port` limits an entry to one port. IP and CIDR entries match IP
+ * literal hosts only: nothing here resolves a name. Loopback always goes
+ * direct. `W2L_PROXY=off` ignores the variables.
+ *
+ * The proxy resolves the hosts it is asked for, so local mode trusts the
+ * operator's proxy for resolution: before a proxied request only the checks
+ * that need no DNS run (scheme, credentials, IP literals, metadata names).
+ * Direct requests keep the resolve-validate-pin checks.
+ */
+import type { EgressProxy, NetworkPolicy, ProxyServer } from './policy.js';
+export declare const PROXY_ENV_NAMES: readonly ["HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy", "NO_PROXY", "no_proxy"];
+type Env = Readonly<Record<string, string | undefined>>;
+export declare class ProxyConfigError extends Error {
+    constructor(message: string);
+}
+/** The proxy the environment names, or null when none applies. Error messages never repeat a variable's value. */
+export declare function environmentProxy(env: Env): EgressProxy | null;
+/** A local-mode policy that routes through the environment's proxy, when one is set. */
+export declare function withEnvironmentProxy(policy: NetworkPolicy, env: Env): NetworkPolicy;
+/** The operator proxy a URL leaves through under this policy; null means a direct connection. */
+export declare function proxyFor(url: string | URL, policy: Pick<NetworkPolicy, 'origin' | 'egressProxy'>): ProxyServer | null;
+export type NoProxyEntry = {
+    kind: 'all';
+} | {
+    kind: 'host';
+    host: string;
+    port: number | null;
+} | {
+    kind: 'ip';
+    address: string;
+    cidr: string;
+    port: number | null;
+} | {
+    kind: 'cidr';
+    cidr: string;
+};
+/** One NO_PROXY entry, or null for a form W2L does not match (such as an inner wildcard). */
+export declare function parseNoProxyEntry(raw: string): NoProxyEntry | null;
+/** Startup line for local mode: which proxy outbound requests use and what goes direct. */
+export declare function describeEgressProxy(proxy: EgressProxy): string;
+/** Startup line for hosted mode when proxy variables are set: they are ignored. */
+export declare function hostedProxyNotice(env: Env): string | null;
+export {};
+//# sourceMappingURL=proxy.d.ts.map

package/dist/types/cjs/contracts/recipe.d.ts

@@ -0,0 +1,74 @@
+/** Operator-reviewed, data-only recipes. No script/evaluate/write operation. */
+export interface RecipeLocator {
+    css: string;
+}
+export interface RecipeCondition {
+    target: RecipeLocator;
+    text: string;
+}
+export type RecipeStep = {
+    id: string;
+    op: 'navigate';
+    url: string;
+} | {
+    id: string;
+    op: 'assertAccount';
+} | {
+    id: string;
+    op: 'fill';
+    target: RecipeLocator;
+    value: string;
+} | {
+    id: string;
+    op: 'query';
+    target: RecipeLocator;
+    postcondition: RecipeCondition;
+    request: {
+        method: 'GET' | 'POST';
+        path: string;
+    };
+} | {
+    id: string;
+    op: 'extract';
+    field: string;
+    target: RecipeLocator;
+} | {
+    id: string;
+    op: 'download';
+    target: RecipeLocator;
+    field: string;
+};
+export interface BackendRecipe {
+    id: string;
+    revision: number;
+    origin: string;
+    account: RecipeLocator;
+    login: RecipeLocator;
+    steps: RecipeStep[];
+    limits: {
+        timeoutMs: number;
+        maxSteps: number;
+        maxOutputBytes: number;
+        maxDownloadBytes: number;
+    };
+}
+export type RecipeState = 'running' | 'completed' | 'failed' | 'waiting_user' | 'effect_unknown' | 'cancelled';
+export interface RecipeRun {
+    id: string;
+    recipeId: string;
+    revision: number;
+    recipeHash: string;
+    sessionRef: string;
+    workspaceId: string;
+    accountRef: string;
+    triggerKey: string;
+    grantEpoch: number;
+    state: RecipeState;
+    attempt: number;
+    createdAt: number;
+    updatedAt: number;
+    reason: string | null;
+    output: Record<string, string>;
+}
+export declare function validateRecipe(value: unknown): BackendRecipe;
+//# sourceMappingURL=recipe.d.ts.map

package/dist/types/cjs/contracts/regexSafety.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A static check for regular expressions a caller supplies and W2L runs, on
+ * a backtracking engine, against text a web page controls: crawl
+ * `includePaths` / `excludePaths`, and JSON Schema `pattern`. Such a pattern
+ * can take time exponential or polynomial in the text's length (ReDoS).
+ * `unsafeRegexReason` refuses the shapes that cause it:
+ *
+ * - a repeated group with a repeated or optional part inside, unless each
+ *   repetition is delimited by a character none of those parts can match:
+ *   `(a+)+`, `(\w+\s?)*` and `(.*,)*` are refused,
+ *   `[a-z0-9]+(?:-[a-z0-9]+)*` is not;
+ * - a repeated group whose alternatives can start with the same character:
+ *   `(a|ab)*` and `(\d|\w)+` are refused, `(?:ab|cd)+` and `(?:[a-z]|-)+`
+ *   are not;
+ * - three or more variable parts in a row that can take the same characters,
+ *   counting the start of an unanchored pattern, which is tried at every
+ *   position: `.*a.*b`, `^\d+\d+\d+x` and `^a?a?a?aaa` are refused,
+ *   `^.*a.*b`, `.*\.pdf$` and `.*blog.*` are not.
+ *
+ * A pattern it accepts backtracks at most quadratically in the text's
+ * length, so a caller that runs it on the backtracking engine caps the text
+ * at REGEX_SUBJECT_MAX_LENGTH characters (a few milliseconds per match). The
+ * check reads JavaScript syntax and is conservative: what it cannot place (a
+ * backreference, a Unicode property) counts as matching any character. It
+ * assumes the pattern compiles; check that first.
+ */
+/** The longest text a pattern unsafeRegexReason accepts should be matched against on a backtracking engine. */
+export declare const REGEX_SUBJECT_MAX_LENGTH = 2048;
+/** Why `pattern` can backtrack catastrophically, or null when it cannot. */
+export declare function unsafeRegexReason(pattern: string): string | null;
+//# sourceMappingURL=regexSafety.d.ts.map