@crawlee/core 4.0.0-beta.14 → 4.0.0-beta.140

package/enqueue_links/index.d.ts

@@ -1,3 +1,2 @@
 export * from './enqueue_links.js';
 export * from './shared.js';
-//# sourceMappingURL=index.d.ts.map

package/enqueue_links/index.js

@@ -1,3 +1,2 @@
 export * from './enqueue_links.js';
 export * from './shared.js';
-//# sourceMappingURL=index.js.map

package/enqueue_links/shared.d.ts

@@ -1,25 +1,27 @@
-import type { Awaitable } from '@crawlee/types';
+import type { Awaitable, Dictionary } from '@crawlee/types';
+import { z } from 'zod';
 import type { RequestOptions } from '../request.js';
-import { Request } from '../request.js';
-import type { EnqueueLinksOptions } from './enqueue_links.js';
-export { tryAbsoluteURL } from '@crawlee/utils';
-export type UrlPatternObject = {
+import type { EnqueueStrategyOption } from './enqueue_links.js';
+export interface UrlPatternObject {
     glob?: string;
     regexp?: RegExp;
-} & Pick<RequestOptions, 'method' | 'payload' | 'label' | 'userData' | 'headers'>;
-export type PseudoUrlObject = {
-    purl: string;
-} & Pick<RequestOptions, 'method' | 'payload' | 'label' | 'userData' | 'headers'>;
-export type PseudoUrlInput = string | PseudoUrlObject;
-export type GlobObject = {
+}
+export interface GlobObject {
     glob: string;
-} & Pick<RequestOptions, 'method' | 'payload' | 'label' | 'userData' | 'headers'>;
+}
 export type GlobInput = string | GlobObject;
-export type RegExpObject = {
+export interface RegExpObject {
     regexp: RegExp;
-} & Pick<RequestOptions, 'method' | 'payload' | 'label' | 'userData' | 'headers'>;
+}
 export type RegExpInput = RegExp | RegExpObject;
-export type SkippedRequestReason = 'robotsTxt' | 'limit' | 'enqueueLimit' | 'filters' | 'redirect' | 'depth';
+/** Unified URL pattern input — accepts glob strings, glob objects, RegExp instances, or regexp objects. */
+export type UrlPatternInput = GlobInput | RegExpInput;
+/**
+ * Accepts one {@link UrlPatternInput} — a glob string, a RegExp instance, or a `{ glob }` / `{ regexp }` object.
+ * @internal
+ */
+export declare const urlPatternSchema: z.ZodType<UrlPatternInput>;
+export type SkippedRequestReason = 'robotsTxt' | 'limit' | 'enqueueLimit' | 'filters' | 'transform' | 'redirect' | 'depth';
 export type SkippedRequestCallback = (args: {
     url: string;
     reason: SkippedRequestReason;
@@ -27,13 +29,7 @@ export type SkippedRequestCallback = (args: {
 /**
  * @ignore
  */
-export declare function updateEnqueueLinksPatternCache(item: GlobInput | RegExpInput | PseudoUrlInput, pattern: RegExpObject | GlobObject): void;
-/**
- * Helper factory used in the `enqueueLinks()` and enqueueLinksByClickingElements() function
- * to construct RegExps from PseudoUrl strings.
- * @ignore
- */
-export declare function constructRegExpObjectsFromPseudoUrls(pseudoUrls: readonly PseudoUrlInput[]): RegExpObject[];
+export declare function updateEnqueueLinksPatternCache(item: GlobInput | RegExpInput, pattern: RegExpObject | GlobObject): void;
 /**
  * Helper factory used in the `enqueueLinks()` and enqueueLinksByClickingElements() function
  * to construct Glob objects from Glob pattern strings.
@@ -51,23 +47,46 @@ export declare function validateGlobPattern(glob: string): string;
  */
 export declare function constructRegExpObjectsFromRegExps(regexps: readonly RegExpInput[]): RegExpObject[];
 /**
+ * Helper factory used in the `enqueueLinks()` function to construct UrlPatternObjects
+ * from a mixed array of glob strings, glob objects, RegExp instances, and regexp objects.
+ * @ignore
+ */
+export declare function constructUrlPatternObjects(patterns: readonly UrlPatternInput[]): UrlPatternObject[];
+/**
+ * Filters request options by URL patterns.
+ *
+ * When `includePatterns` is empty/undefined, all options pass through (only exclude filtering applies).
  * @ignore
  */
-export declare function createRequests(requestOptions: (string | RequestOptions)[], urlPatternObjects?: UrlPatternObject[], excludePatternObjects?: UrlPatternObject[], strategy?: EnqueueLinksOptions['strategy'], onSkippedUrl?: (url: string) => void): Request[];
-export declare function filterRequestsByPatterns(requests: Request[], patterns?: UrlPatternObject[], onSkippedUrl?: (url: string) => void): Request[];
+export declare function filterRequestOptionsByPatterns(requestOptions: RequestOptions[], includePatterns: UrlPatternObject[] | undefined, excludePatterns?: UrlPatternObject[], strategy?: EnqueueStrategyOption, onSkippedUrl?: (url: string) => void): RequestOptions[];
 /**
  * @ignore
  */
-export declare function createRequestOptions(sources: readonly (string | Record<string, unknown>)[], options?: Pick<EnqueueLinksOptions, 'label' | 'userData' | 'baseUrl' | 'skipNavigation' | 'strategy'>): RequestOptions[];
+export declare function createRequestOptions(sources: readonly (string | Record<string, unknown>)[], options?: {
+    label?: string;
+    userData?: Dictionary;
+    baseUrl?: string;
+    skipNavigation?: boolean;
+    sessionId?: string;
+    strategy?: EnqueueStrategyOption;
+}): RequestOptions[];
 /**
- * Takes an Apify {@link RequestOptions} object and changes its attributes in a desired way. This user-function is used
- * {@link enqueueLinks} to modify requests before enqueuing them.
+ * Takes a {@link RequestOptions} object and changes its attributes in a desired way. This user-function is used
+ * by {@link enqueueLinks} to modify request options before they are converted to {@link Request} instances.
  */
 export interface RequestTransform {
     /**
      * @param original Request options to be modified.
-     * @returns The modified request options to enqueue.
+     * @returns The modified request options to enqueue, `'unchanged'` to keep the original options as-is,
+     *   or a falsy value / `'skip'` to exclude the request from the queue.
      */
-    (original: RequestOptions): RequestOptions | false | undefined | null;
+    (original: RequestOptions): RequestOptions | false | undefined | null | 'skip' | 'unchanged';
 }
-//# sourceMappingURL=shared.d.ts.map
+/**
+ * Applies a {@link RequestTransform} function to a list of request options.
+ * Options for which the transform returns a falsy value are removed from the list.
+ * @param onSkipped Called with the original request options when the transform returns a falsy value (i.e. the request is skipped).
+ * @ignore
+ * @internal
+ */
+export declare function applyRequestTransform(requestOptions: RequestOptions[], transformFn: RequestTransform, onSkipped?: (requestOptions: RequestOptions) => void): RequestOptions[];

package/enqueue_links/shared.js

@@ -1,16 +1,24 @@
 import { URL } from 'node:url';
 import { Minimatch } from 'minimatch';
-import { purlToRegExp } from '@apify/pseudo_url';
-import { Request } from '../request.js';
-export { tryAbsoluteURL } from '@crawlee/utils';
+import { z } from 'zod';
+import { schemas } from '../validators.js';
 const MAX_ENQUEUE_LINKS_CACHE_SIZE = 1000;
 /**
- * To enable direct use of the Actor UI `globs`/`regexps`/`pseudoUrls` output while keeping high performance,
- * all the regexps from the output are only constructed once and kept in a cache
- * by the `enqueueLinks()` function.
+ * To keep high performance when the same patterns are passed on every `enqueueLinks()` call,
+ * each glob/regexp is only compiled once and then kept in a cache.
  * @ignore
  */
 const enqueueLinksPatternCache = new Map();
+/**
+ * Accepts one {@link UrlPatternInput} — a glob string, a RegExp instance, or a `{ glob }` / `{ regexp }` object.
+ * @internal
+ */
+export const urlPatternSchema = z.union([
+    z.string(),
+    z.instanceof(RegExp),
+    schemas.objectWithKeys(['glob']),
+    schemas.objectWithKeys(['regexp']),
+]);
 /**
  * @ignore
  */
@@ -21,28 +29,6 @@ export function updateEnqueueLinksPatternCache(item, pattern) {
         enqueueLinksPatternCache.delete(key);
     }
 }
-/**
- * Helper factory used in the `enqueueLinks()` and enqueueLinksByClickingElements() function
- * to construct RegExps from PseudoUrl strings.
- * @ignore
- */
-export function constructRegExpObjectsFromPseudoUrls(pseudoUrls) {
-    return pseudoUrls.map((item) => {
-        // Get pseudoUrl object from cache.
-        let regexpObject = enqueueLinksPatternCache.get(item);
-        if (regexpObject)
-            return regexpObject;
-        if (typeof item === 'string') {
-            regexpObject = { regexp: purlToRegExp(item) };
-        }
-        else {
-            const { purl, ...requestOptions } = item;
-            regexpObject = { regexp: purlToRegExp(purl), ...requestOptions };
-        }
-        updateEnqueueLinksPatternCache(item, regexpObject);
-        return regexpObject;
-    });
-}
 /**
  * Helper factory used in the `enqueueLinks()` and enqueueLinksByClickingElements() function
  * to construct Glob objects from Glob pattern strings.
@@ -72,8 +58,7 @@ export function constructGlobObjectsFromGlobs(globs) {
             globObject = { glob: validateGlobPattern(item) };
         }
         else {
-            const { glob, ...requestOptions } = item;
-            globObject = { glob: validateGlobPattern(glob), ...requestOptions };
+            globObject = { glob: validateGlobPattern(item.glob) };
         }
         updateEnqueueLinksPatternCache(item, globObject);
         return globObject;
@@ -103,62 +88,70 @@ export function constructRegExpObjectsFromRegExps(regexps) {
             regexpObject = { regexp: item };
         }
         else {
-            regexpObject = item;
+            regexpObject = { regexp: item.regexp };
         }
         updateEnqueueLinksPatternCache(item, regexpObject);
         return regexpObject;
     });
 }
 /**
+ * Helper factory used in the `enqueueLinks()` function to construct UrlPatternObjects
+ * from a mixed array of glob strings, glob objects, RegExp instances, and regexp objects.
+ * @ignore
+ */
+export function constructUrlPatternObjects(patterns) {
+    const result = [];
+    for (const item of patterns) {
+        if (typeof item === 'string' || 'glob' in item) {
+            result.push(...constructGlobObjectsFromGlobs([item]));
+        }
+        else if (item instanceof RegExp || 'regexp' in item) {
+            result.push(...constructRegExpObjectsFromRegExps([item]));
+        }
+    }
+    return result;
+}
+/**
+ * Filters request options by URL patterns.
+ *
+ * When `includePatterns` is empty/undefined, all options pass through (only exclude filtering applies).
  * @ignore
  */
-export function createRequests(requestOptions, urlPatternObjects, excludePatternObjects = [], strategy, onSkippedUrl) {
-    const excludePatternObjectMatchers = excludePatternObjects.map(createPatternObjectMatcher);
-    const urlPatternObjectMatchers = urlPatternObjects?.map(createPatternObjectMatcher);
+export function filterRequestOptionsByPatterns(requestOptions, includePatterns, excludePatterns = [], strategy, onSkippedUrl) {
+    const excludeMatchers = excludePatterns.map(createPatternObjectMatcher);
+    const includeMatchers = includePatterns?.length ? includePatterns.map(createPatternObjectMatcher) : undefined;
     return requestOptions
-        .map((opts) => ({ url: typeof opts === 'string' ? opts : opts.url, opts }))
         .filter(({ url }) => {
-        const matchesExcludePatterns = excludePatternObjectMatchers.some(({ match }) => match(url));
-        if (matchesExcludePatterns) {
+        const matchesExclude = excludeMatchers.some(({ match }) => match(url));
+        if (matchesExclude) {
             onSkippedUrl?.(url);
         }
-        return !matchesExcludePatterns;
+        return !matchesExclude;
     })
-        .map(({ url, opts }) => {
-        if (!urlPatternObjectMatchers || !urlPatternObjectMatchers.length) {
-            return new Request(typeof opts === 'string' ? { url: opts, enqueueStrategy: strategy } : { ...opts });
-        }
-        for (const urlPatternObject of urlPatternObjectMatchers) {
-            const { match, glob, regexp, ...requestRegExpOptions } = urlPatternObject;
-            if (match(url)) {
-                const request = typeof opts === 'string'
-                    ? { url: opts, ...requestRegExpOptions, enqueueStrategy: strategy }
-                    : { ...opts, ...requestRegExpOptions, enqueueStrategy: strategy };
-                return new Request(request);
+        .map((opts) => {
+        if (!includeMatchers) {
+            return { ...opts, enqueueStrategy: strategy };
+        }
+        for (const { match } of includeMatchers) {
+            if (match(opts.url)) {
+                return { ...opts, enqueueStrategy: strategy };
             }
         }
         // didn't match any positive pattern
-        onSkippedUrl?.(url);
+        onSkippedUrl?.(opts.url);
         return null;
     })
-        .filter((request) => request);
+        .filter((opts) => opts !== null);
 }
-export function filterRequestsByPatterns(requests, patterns, onSkippedUrl) {
-    if (!patterns?.length) {
-        return requests;
+function isAbsoluteUrl(url) {
+    try {
+        // eslint-disable-next-line no-new
+        new URL(url);
+        return true;
     }
-    const filtered = [];
-    const patternMatchers = patterns?.map(createPatternObjectMatcher);
-    for (const request of requests) {
-        const matchingPattern = patternMatchers.find(({ match }) => match(request.url));
-        if (matchingPattern !== undefined) {
-            filtered.push(request);
-        }
-        else {
-            onSkippedUrl?.(request.url);
-        }
+    catch {
+        return false;
     }
-    return filtered;
 }
 /**
  * @ignore
@@ -177,7 +170,12 @@ export function createRequestOptions(sources, options = {}) {
         }
     })
         .map((requestOptions) => {
-        requestOptions.url = new URL(requestOptions.url, options.baseUrl).href;
+        // Leave already-absolute URLs untouched - re-deriving them via `new URL()` would normalize them
+        // (e.g. adding a trailing slash to a bare domain), which is surprising for URLs that didn't need
+        // resolving against `baseUrl` in the first place.
+        if (!isAbsoluteUrl(requestOptions.url)) {
+            requestOptions.url = new URL(requestOptions.url, options.baseUrl).href;
+        }
         requestOptions.userData ??= options.userData ?? {};
         if (typeof options.label === 'string') {
             requestOptions.userData = {
@@ -188,6 +186,9 @@ export function createRequestOptions(sources, options = {}) {
         if (options.skipNavigation) {
             requestOptions.skipNavigation = true;
         }
+        if (options.sessionId) {
+            requestOptions.sessionId = options.sessionId;
+        }
         return requestOptions;
     });
 }
@@ -207,6 +208,31 @@ function createPatternObjectMatcher(urlPatternObject) {
     else {
         match = () => false;
     }
-    return { ...urlPatternObject, match };
+    return { match };
+}
+/**
+ * Applies a {@link RequestTransform} function to a list of request options.
+ * Options for which the transform returns a falsy value are removed from the list.
+ * @param onSkipped Called with the original request options when the transform returns a falsy value (i.e. the request is skipped).
+ * @ignore
+ * @internal
+ */
+export function applyRequestTransform(requestOptions, transformFn, onSkipped) {
+    return requestOptions
+        .map((opts) => {
+        const transformed = transformFn(opts);
+        if (transformed === 'skip') {
+            onSkipped?.(opts);
+            return null;
+        }
+        if (transformed === 'unchanged') {
+            return opts;
+        }
+        if (!transformed) {
+            onSkipped?.(opts);
+            return null;
+        }
+        return transformed;
+    })
+        .filter((r) => r !== null);
 }
-//# sourceMappingURL=shared.js.map

package/errors.d.ts

@@ -14,6 +14,37 @@ export declare class CriticalError extends NonRetryableError {
  */
 export declare class MissingRouteError extends CriticalError {
 }
+/**
+ * A schema validation issue, structurally compatible with `StandardSchemaV1.Issue`. Declared here so that
+ * error types do not have to depend on `@standard-schema/spec`.
+ */
+export interface SchemaIssue {
+    readonly message: string;
+    readonly path?: readonly (PropertyKey | {
+        key: PropertyKey;
+    })[];
+}
+/**
+ * Thrown when a request's `userData` does not match the {@link RouteSchemas|Standard Schema} registered for its label.
+ *
+ * As the `userData` does not change between attempts, this error is non-retryable.
+ */
+export declare class RequestValidationError extends NonRetryableError {
+    readonly label: string | symbol;
+    readonly issues: readonly SchemaIssue[];
+    constructor(label: string | symbol, issues: readonly SchemaIssue[]);
+}
+/**
+ * Thrown by {@link RecoverableState} when a persisted state record does not match its `stateSchema`.
+ *
+ * Whether a corrupt record should abort the run or be discarded in favour of the defaults depends on what the
+ * state is for, so {@link RecoverableState.initialize} always throws and leaves the choice to the caller.
+ */
+export declare class StateValidationError extends Error {
+    readonly persistStateKey: string;
+    readonly issues: readonly SchemaIssue[];
+    constructor(persistStateKey: string, issues: readonly SchemaIssue[]);
+}
 /**
  * Errors of `RetryRequestError` type will always be retried by the crawler.
  *
@@ -23,13 +54,39 @@ export declare class RetryRequestError extends Error {
     constructor(message?: string);
 }
 /**
- * Errors of `SessionError` type will trigger a session rotation.
+ * Thrown when a domain has rate-limited us and the request should simply be attempted again later.
  *
- * This error doesn't respect the `maxRequestRetries` option and has a separate limit of `maxSessionRotations`.
+ * The request is reclaimed without recording a failure: it costs neither a retry nor session reputation, because
+ * nothing about the request or the session was at fault. A {@link ThrottlingRequestManager} holds it back until
+ * the domain's backoff expires, so retries are paced rather than immediate.
  */
-export declare class SessionError extends RetryRequestError {
+export declare class RequestThrottledError extends RetryRequestError {
     constructor(message?: string);
 }
+/**
+ * Thrown when a domain has rate-limited us for so long that no request has got through, and the crawl is
+ * abandoned rather than kept waiting.
+ *
+ * Waiting longer will not help: at this point the concurrency is too high for the domain, or it has blocked us.
+ * The affected requests are deliberately left in their queue, so re-running the crawl without purging storages
+ * resumes them once the domain recovers.
+ */
+export declare class PersistentRateLimitError extends CriticalError {
+}
+/**
+ * Errors of `SessionError` type retire the session associated with the request and trigger a regular retry.
+ *
+ * The retry counts towards the `maxRequestRetries` limit, just like any other error.
+ */
+export declare class SessionError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a requested session is not found in the referenced SessionPool.
+ */
+export declare class MissingSessionError extends Error {
+    constructor(sessionId?: string);
+}
 export declare class ContextPipelineInterruptedError extends Error {
     constructor(message?: string);
 }
@@ -42,4 +99,15 @@ export declare class ContextPipelineCleanupError extends CriticalError {
 export declare class RequestHandlerError extends Error {
     constructor(error: unknown, options?: ErrorOptions);
 }
-//# sourceMappingURL=errors.d.ts.map
+/**
+ * Thrown when attempting to set a different service instance after one has already been retrieved.
+ */
+export declare class ServiceConflictError extends Error {
+    constructor(serviceName: string, newValue: unknown, existingValue: unknown);
+}
+/**
+ * Thrown by crawlers when `skipNavigation` is used on a request.
+ * Subclasses can catch this error to skip their own navigation-dependent logic.
+ */
+export declare class NavigationSkippedError extends NonRetryableError {
+}

package/errors.js

@@ -1,3 +1,4 @@
+import { inspectValue } from './debug.js';
 /**
  * Errors of `NonRetryableError` type will never be retried by the crawler.
  */
@@ -14,6 +15,45 @@ export class CriticalError extends NonRetryableError {
  */
 export class MissingRouteError extends CriticalError {
 }
+function formatIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = (issue.path ?? [])
+            .map((segment) => (typeof segment === 'object' ? segment.key : segment))
+            .join('.');
+        return `- ${path ? `${path}: ` : ''}${issue.message}`;
+    })
+        .join('\n');
+}
+/**
+ * Thrown when a request's `userData` does not match the {@link RouteSchemas|Standard Schema} registered for its label.
+ *
+ * As the `userData` does not change between attempts, this error is non-retryable.
+ */
+export class RequestValidationError extends NonRetryableError {
+    label;
+    issues;
+    constructor(label, issues) {
+        super(`Request userData for label '${String(label)}' failed schema validation:\n${formatIssues(issues)}`);
+        this.label = label;
+        this.issues = issues;
+    }
+}
+/**
+ * Thrown by {@link RecoverableState} when a persisted state record does not match its `stateSchema`.
+ *
+ * Whether a corrupt record should abort the run or be discarded in favour of the defaults depends on what the
+ * state is for, so {@link RecoverableState.initialize} always throws and leaves the choice to the caller.
+ */
+export class StateValidationError extends Error {
+    persistStateKey;
+    issues;
+    constructor(persistStateKey, issues) {
+        super(`State persisted under key '${persistStateKey}' failed schema validation:\n${formatIssues(issues)}`);
+        this.persistStateKey = persistStateKey;
+        this.issues = issues;
+    }
+}
 /**
  * Errors of `RetryRequestError` type will always be retried by the crawler.
  *
@@ -25,13 +65,43 @@ export class RetryRequestError extends Error {
     }
 }
 /**
- * Errors of `SessionError` type will trigger a session rotation.
+ * Thrown when a domain has rate-limited us and the request should simply be attempted again later.
+ *
+ * The request is reclaimed without recording a failure: it costs neither a retry nor session reputation, because
+ * nothing about the request or the session was at fault. A {@link ThrottlingRequestManager} holds it back until
+ * the domain's backoff expires, so retries are paced rather than immediate.
+ */
+export class RequestThrottledError extends RetryRequestError {
+    constructor(message) {
+        super(message ?? 'Request is being retried later because its domain is rate-limiting us');
+    }
+}
+/**
+ * Thrown when a domain has rate-limited us for so long that no request has got through, and the crawl is
+ * abandoned rather than kept waiting.
+ *
+ * Waiting longer will not help: at this point the concurrency is too high for the domain, or it has blocked us.
+ * The affected requests are deliberately left in their queue, so re-running the crawl without purging storages
+ * resumes them once the domain recovers.
+ */
+export class PersistentRateLimitError extends CriticalError {
+}
+/**
+ * Errors of `SessionError` type retire the session associated with the request and trigger a regular retry.
  *
- * This error doesn't respect the `maxRequestRetries` option and has a separate limit of `maxSessionRotations`.
+ * The retry counts towards the `maxRequestRetries` limit, just like any other error.
  */
-export class SessionError extends RetryRequestError {
+export class SessionError extends Error {
     constructor(message) {
-        super(`Detected a session error, rotating session... ${message ? `\n${message}` : ''}`);
+        super(`Detected a session error, retiring session... ${message ? `\n${message}` : ''}`);
+    }
+}
+/**
+ * Thrown when a requested session is not found in the referenced SessionPool.
+ */
+export class MissingSessionError extends Error {
+    constructor(sessionId) {
+        super(`The current SessionPool instance couldn't find a valid session${sessionId ? ` for the following id: ${sessionId}.` : '.'}`);
     }
 }
 export class ContextPipelineInterruptedError extends Error {
@@ -54,4 +124,18 @@ export class RequestHandlerError extends Error {
         super(undefined, { cause: error, ...options });
     }
 }
-//# sourceMappingURL=errors.js.map
+/**
+ * Thrown when attempting to set a different service instance after one has already been retrieved.
+ */
+export class ServiceConflictError extends Error {
+    constructor(serviceName, newValue, existingValue) {
+        super(`Service ${serviceName} is already in use. ` +
+            `Existing value: ${inspectValue(existingValue)}, attempted new value: ${inspectValue(newValue)}.`);
+    }
+}
+/**
+ * Thrown by crawlers when `skipNavigation` is used on a request.
+ * Subclasses can catch this error to skip their own navigation-dependent logic.
+ */
+export class NavigationSkippedError extends NonRetryableError {
+}

package/events/event_manager.d.ts

@@ -1,28 +1,55 @@
 import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
 import type { BetterIntervalID } from '@apify/utilities';
-import { Configuration } from '../configuration.js';
-export declare const enum EventType {
+export interface EventManagerOptions {
+    /** Interval between emitted `persistState` events in milliseconds. */
+    persistStateIntervalMillis: number;
+}
+export declare enum EventType {
     PERSIST_STATE = "persistState",
     SYSTEM_INFO = "systemInfo",
     MIGRATING = "migrating",
     ABORTING = "aborting",
-    EXIT = "exit"
+    EXIT = "exit",
+    STATUS_MESSAGE = "statusMessage"
+}
+export type EventTypeName = EventType | 'systemInfo' | 'persistState' | 'migrating' | 'aborting' | 'exit' | 'statusMessage';
+/**
+ * Payload emitted with the {@link EventType.STATUS_MESSAGE|`statusMessage`} event.
+ *
+ * The crawler broadcasts these whenever it wants to report its progress (e.g. periodically, or on
+ * start/finish). Consumers such as the Apify SDK can listen for the event and propagate the message
+ * to the platform. This keeps the crawler decoupled from any specific status-reporting backend.
+ */
+export interface EventStatusMessageData {
+    /**
+     * Identifies the crawler that emitted the message.
+     *
+     * Either the user-provided `id` from the crawler options, or a randomly generated one.
+     * Since a single event manager may be shared by multiple crawlers, consumers can use this
+     * to attribute the message to a specific crawler instance.
+     */
+    crawlerId: string;
+    /** The human-readable status message. */
+    message: string;
+    /** Whether this is the final status message of the run. */
+    isStatusMessageTerminal?: boolean;
+    /** The log level the message was logged with. */
+    level?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR';
 }
-export type EventTypeName = EventType | 'systemInfo' | 'persistState' | 'migrating' | 'aborting' | 'exit';
 interface Intervals {
     persistState?: BetterIntervalID;
     systemInfo?: BetterIntervalID;
 }
 export declare abstract class EventManager {
-    readonly config: Configuration;
+    #private;
     protected events: AsyncEventEmitter<{}>;
     protected initialized: boolean;
     protected intervals: Intervals;
 // @ts-ignore optional peer dependency or compatibility with es2022
-    protected log: import("@apify/log").Log;
-    constructor(config?: Configuration);
+    protected log: import("@crawlee/types").CrawleeLogger;
+    constructor(options: EventManagerOptions);
     /**
-     * Initializes the event manager by creating the `persistState` event interval.
+     * Initializes the event manager by starting the `persistState` event interval.
      * This is automatically called at the beginning of `crawler.run()`.
      */
     init(): Promise<void>;
@@ -49,4 +76,3 @@ export declare abstract class EventManager {
     waitForAllListenersToComplete(): Promise<boolean>;
 }
 export {};
-//# sourceMappingURL=event_manager.d.ts.map