@isdk/web-fetcher 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1603 @@
+import { CrawlingContext, BasicCrawler, BasicCrawlerOptions, RequestQueue, Cookie, CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions, PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions } from 'crawlee';
+export { Cookie } from 'crawlee';
+import { EventEmitter } from 'events-ex';
+
+declare global {
+	// eslint-disable-next-line @typescript-eslint/consistent-type-definitions -- It has to be an `interface` so that it can be merged.
+	interface SymbolConstructor {
+		readonly observable: symbol;
+	}
+}
+
+/**
+Extract all optional keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the optional keys only.
+
+@example
+```
+import type {OptionalKeysOf, Except} from 'type-fest';
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const REMOVE_FIELD = Symbol('remove field symbol');
+type UpdateOperation<Entity extends object> = Except<Partial<Entity>, OptionalKeysOf<Entity>> & {
+	[Key in OptionalKeysOf<Entity>]?: Entity[Key] | typeof REMOVE_FIELD;
+};
+
+const update1: UpdateOperation<User> = {
+	name: 'Alice'
+};
+
+const update2: UpdateOperation<User> = {
+	name: 'Bob',
+	luckyNumber: REMOVE_FIELD
+};
+```
+
+@category Utilities
+*/
+type OptionalKeysOf<BaseType extends object> =
+	BaseType extends unknown // For distributing `BaseType`
+		? (keyof {
+			[Key in keyof BaseType as BaseType extends Record<Key, BaseType[Key]> ? never : Key]: never
+		}) & (keyof BaseType) // Intersect with `keyof BaseType` to ensure result of `OptionalKeysOf<BaseType>` is always assignable to `keyof BaseType`
+		: never; // Should never happen
+
+/**
+Extract all required keys from the given type.
+
+This is useful when you want to create a new type that contains different type values for the required keys only or use the list of keys for validation purposes, etc...
+
+@example
+```
+import type {RequiredKeysOf} from 'type-fest';
+
+declare function createValidation<Entity extends object, Key extends RequiredKeysOf<Entity> = RequiredKeysOf<Entity>>(field: Key, validator: (value: Entity[Key]) => boolean): ValidatorFn;
+
+interface User {
+	name: string;
+	surname: string;
+
+	luckyNumber?: number;
+}
+
+const validator1 = createValidation<User>('name', value => value.length < 25);
+const validator2 = createValidation<User>('surname', value => value.length < 25);
+```
+
+@category Utilities
+*/
+type RequiredKeysOf<BaseType extends object> =
+	BaseType extends unknown // For distributing `BaseType`
+		? Exclude<keyof BaseType, OptionalKeysOf<BaseType>>
+		: never; // Should never happen
+
+/**
+Returns a boolean for whether the given type is `never`.
+
+@link https://github.com/microsoft/TypeScript/issues/31751#issuecomment-498526919
+@link https://stackoverflow.com/a/53984913/10292952
+@link https://www.zhenghao.io/posts/ts-never
+
+Useful in type utilities, such as checking if something does not occur.
+
+@example
+```
+import type {IsNever, And} from 'type-fest';
+
+// https://github.com/andnp/SimplyTyped/blob/master/src/types/strings.ts
+type AreStringsEqual<A extends string, B extends string> =
+	And<
+		IsNever<Exclude<A, B>> extends true ? true : false,
+		IsNever<Exclude<B, A>> extends true ? true : false
+	>;
+
+type EndIfEqual<I extends string, O extends string> =
+	AreStringsEqual<I, O> extends true
+		? never
+		: void;
+
+function endIfEqual<I extends string, O extends string>(input: I, output: O): EndIfEqual<I, O> {
+	if (input === output) {
+		process.exit(0);
+	}
+}
+
+endIfEqual('abc', 'abc');
+//=> never
+
+endIfEqual('abc', '123');
+//=> void
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsNever<T> = [T] extends [never] ? true : false;
+
+/**
+An if-else-like type that resolves depending on whether the given type is `never`.
+
+@see {@link IsNever}
+
+@example
+```
+import type {IfNever} from 'type-fest';
+
+type ShouldBeTrue = IfNever<never>;
+//=> true
+
+type ShouldBeBar = IfNever<'not never', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IfNever<T, TypeIfNever = true, TypeIfNotNever = false> = (
+	IsNever<T> extends true ? TypeIfNever : TypeIfNotNever
+);
+
+// Can eventually be replaced with the built-in once this library supports
+// TS5.4+ only. Tracked in https://github.com/sindresorhus/type-fest/issues/848
+type NoInfer<T> = T extends infer U ? U : never;
+
+/**
+Returns a boolean for whether the given type is `any`.
+
+@link https://stackoverflow.com/a/49928360/1490091
+
+Useful in type utilities, such as disallowing `any`s to be passed to a function.
+
+@example
+```
+import type {IsAny} from 'type-fest';
+
+const typedObject = {a: 1, b: 2} as const;
+const anyObject: any = {a: 1, b: 2};
+
+function get<O extends (IsAny<O> extends true ? {} : Record<string, number>), K extends keyof O = keyof O>(obj: O, key: K) {
+	return obj[key];
+}
+
+const typedA = get(typedObject, 'a');
+//=> 1
+
+const anyA = get(anyObject, 'a');
+//=> any
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsAny<T> = 0 extends 1 & NoInfer<T> ? true : false;
+
+/**
+Returns a boolean for whether the two given types are equal.
+
+@link https://github.com/microsoft/TypeScript/issues/27024#issuecomment-421529650
+@link https://stackoverflow.com/questions/68961864/how-does-the-equals-work-in-typescript/68963796#68963796
+
+Use-cases:
+- If you want to make a conditional branch based on the result of a comparison of two types.
+
+@example
+```
+import type {IsEqual} from 'type-fest';
+
+// This type returns a boolean for whether the given array includes the given item.
+// `IsEqual` is used to compare the given array at position 0 and the given item and then return true if they are equal.
+type Includes<Value extends readonly any[], Item> =
+	Value extends readonly [Value[0], ...infer rest]
+		? IsEqual<Value[0], Item> extends true
+			? true
+			: Includes<rest, Item>
+		: false;
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IsEqual<A, B> =
+	(<G>() => G extends A & G | G ? 1 : 2) extends
+	(<G>() => G extends B & G | G ? 1 : 2)
+		? true
+		: false;
+
+/**
+Useful to flatten the type output to improve type hints shown in editors. And also to transform an interface into a type to aide with assignability.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+type PositionProps = {
+	top: number;
+	left: number;
+};
+
+type SizeProps = {
+	width: number;
+	height: number;
+};
+
+// In your editor, hovering over `Props` will show a flattened object with all the properties.
+type Props = Simplify<PositionProps & SizeProps>;
+```
+
+Sometimes it is desired to pass a value as a function argument that has a different type. At first inspection it may seem assignable, and then you discover it is not because the `value`'s type definition was defined as an interface. In the following example, `fn` requires an argument of type `Record<string, unknown>`. If the value is defined as a literal, then it is assignable. And if the `value` is defined as type using the `Simplify` utility the value is assignable.  But if the `value` is defined as an interface, it is not assignable because the interface is not sealed and elsewhere a non-string property could be added to the interface.
+
+If the type definition must be an interface (perhaps it was defined in a third-party npm package), then the `value` can be defined as `const value: Simplify<SomeInterface> = ...`. Then `value` will be assignable to the `fn` argument.  Or the `value` can be cast as `Simplify<SomeInterface>` if you can't re-declare the `value`.
+
+@example
+```
+import type {Simplify} from 'type-fest';
+
+interface SomeInterface {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+}
+
+type SomeType = {
+	foo: number;
+	bar?: string;
+	baz: number | undefined;
+};
+
+const literal = {foo: 123, bar: 'hello', baz: 456};
+const someType: SomeType = literal;
+const someInterface: SomeInterface = literal;
+
+function fn(object: Record<string, unknown>): void {}
+
+fn(literal); // Good: literal object type is sealed
+fn(someType); // Good: type is sealed
+fn(someInterface); // Error: Index signature for type 'string' is missing in type 'someInterface'. Because `interface` can be re-opened
+fn(someInterface as Simplify<SomeInterface>); // Good: transform an `interface` into a `type`
+```
+
+@link https://github.com/microsoft/TypeScript/issues/15300
+@see SimplifyDeep
+@category Object
+*/
+type Simplify<T> = {[KeyType in keyof T]: T[KeyType]} & {};
+
+/**
+Omit any index signatures from the given object type, leaving only explicitly defined properties.
+
+This is the counterpart of `PickIndexSignature`.
+
+Use-cases:
+- Remove overly permissive signatures from third-party types.
+
+This type was taken from this [StackOverflow answer](https://stackoverflow.com/a/68261113/420747).
+
+It relies on the fact that an empty object (`{}`) is assignable to an object with just an index signature, like `Record<string, unknown>`, but not to an object with explicitly defined keys, like `Record<'foo' | 'bar', unknown>`.
+
+(The actual value type, `unknown`, is irrelevant and could be any type. Only the key type matters.)
+
+```
+const indexed: Record<string, unknown> = {}; // Allowed
+
+const keyed: Record<'foo', unknown> = {}; // Error
+// => TS2739: Type '{}' is missing the following properties from type 'Record<"foo" | "bar", unknown>': foo, bar
+```
+
+Instead of causing a type error like the above, you can also use a [conditional type](https://www.typescriptlang.org/docs/handbook/2/conditional-types.html) to test whether a type is assignable to another:
+
+```
+type Indexed = {} extends Record<string, unknown>
+	? '✅ `{}` is assignable to `Record<string, unknown>`'
+	: '❌ `{}` is NOT assignable to `Record<string, unknown>`';
+// => '✅ `{}` is assignable to `Record<string, unknown>`'
+
+type Keyed = {} extends Record<'foo' | 'bar', unknown>
+	? "✅ `{}` is assignable to `Record<'foo' | 'bar', unknown>`"
+	: "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`";
+// => "❌ `{}` is NOT assignable to `Record<'foo' | 'bar', unknown>`"
+```
+
+Using a [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html#further-exploration), you can then check for each `KeyType` of `ObjectType`...
+
+```
+import type {OmitIndexSignature} from 'type-fest';
+
+type OmitIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType // Map each key of `ObjectType`...
+	]: ObjectType[KeyType]; // ...to its original value, i.e. `OmitIndexSignature<Foo> == Foo`.
+};
+```
+
+...whether an empty object (`{}`) would be assignable to an object with that `KeyType` (`Record<KeyType, unknown>`)...
+
+```
+import type {OmitIndexSignature} from 'type-fest';
+
+type OmitIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType
+		// Is `{}` assignable to `Record<KeyType, unknown>`?
+		as {} extends Record<KeyType, unknown>
+			? ... // ✅ `{}` is assignable to `Record<KeyType, unknown>`
+			: ... // ❌ `{}` is NOT assignable to `Record<KeyType, unknown>`
+	]: ObjectType[KeyType];
+};
+```
+
+If `{}` is assignable, it means that `KeyType` is an index signature and we want to remove it. If it is not assignable, `KeyType` is a "real" key and we want to keep it.
+
+@example
+```
+import type {OmitIndexSignature} from 'type-fest';
+
+interface Example {
+	// These index signatures will be removed.
+	[x: string]: any
+	[x: number]: any
+	[x: symbol]: any
+	[x: `head-${string}`]: string
+	[x: `${string}-tail`]: string
+	[x: `head-${string}-tail`]: string
+	[x: `${bigint}`]: string
+	[x: `embedded-${number}`]: string
+
+	// These explicitly defined keys will remain.
+	foo: 'bar';
+	qux?: 'baz';
+}
+
+type ExampleWithoutIndexSignatures = OmitIndexSignature<Example>;
+// => { foo: 'bar'; qux?: 'baz' | undefined; }
+```
+
+@see PickIndexSignature
+@category Object
+*/
+type OmitIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
+		? never
+		: KeyType]: ObjectType[KeyType];
+};
+
+/**
+Pick only index signatures from the given object type, leaving out all explicitly defined properties.
+
+This is the counterpart of `OmitIndexSignature`.
+
+@example
+```
+import type {PickIndexSignature} from 'type-fest';
+
+declare const symbolKey: unique symbol;
+
+type Example = {
+	// These index signatures will remain.
+	[x: string]: unknown;
+	[x: number]: unknown;
+	[x: symbol]: unknown;
+	[x: `head-${string}`]: string;
+	[x: `${string}-tail`]: string;
+	[x: `head-${string}-tail`]: string;
+	[x: `${bigint}`]: string;
+	[x: `embedded-${number}`]: string;
+
+	// These explicitly defined keys will be removed.
+	['kebab-case-key']: string;
+	[symbolKey]: string;
+	foo: 'bar';
+	qux?: 'baz';
+};
+
+type ExampleIndexSignature = PickIndexSignature<Example>;
+// {
+// 	[x: string]: unknown;
+// 	[x: number]: unknown;
+// 	[x: symbol]: unknown;
+// 	[x: `head-${string}`]: string;
+// 	[x: `${string}-tail`]: string;
+// 	[x: `head-${string}-tail`]: string;
+// 	[x: `${bigint}`]: string;
+// 	[x: `embedded-${number}`]: string;
+// }
+```
+
+@see OmitIndexSignature
+@category Object
+*/
+type PickIndexSignature<ObjectType> = {
+	[KeyType in keyof ObjectType as {} extends Record<KeyType, unknown>
+		? KeyType
+		: never]: ObjectType[KeyType];
+};
+
+// Merges two objects without worrying about index signatures.
+type SimpleMerge<Destination, Source> = {
+	[Key in keyof Destination as Key extends keyof Source ? never : Key]: Destination[Key];
+} & Source;
+
+/**
+Merge two types into a new type. Keys of the second type overrides keys of the first type.
+
+@example
+```
+import type {Merge} from 'type-fest';
+
+interface Foo {
+	[x: string]: unknown;
+	[x: number]: unknown;
+	foo: string;
+	bar: symbol;
+}
+
+type Bar = {
+	[x: number]: number;
+	[x: symbol]: unknown;
+	bar: Date;
+	baz: boolean;
+};
+
+export type FooBar = Merge<Foo, Bar>;
+// => {
+// 	[x: string]: unknown;
+// 	[x: number]: number;
+// 	[x: symbol]: unknown;
+// 	foo: string;
+// 	bar: Date;
+// 	baz: boolean;
+// }
+```
+
+@category Object
+*/
+type Merge<Destination, Source> =
+Simplify<
+SimpleMerge<PickIndexSignature<Destination>, PickIndexSignature<Source>>
+& SimpleMerge<OmitIndexSignature<Destination>, OmitIndexSignature<Source>>
+>;
+
+/**
+An if-else-like type that resolves depending on whether the given type is `any`.
+
+@see {@link IsAny}
+
+@example
+```
+import type {IfAny} from 'type-fest';
+
+type ShouldBeTrue = IfAny<any>;
+//=> true
+
+type ShouldBeBar = IfAny<'not any', 'foo', 'bar'>;
+//=> 'bar'
+```
+
+@category Type Guard
+@category Utilities
+*/
+type IfAny<T, TypeIfAny = true, TypeIfNotAny = false> = (
+	IsAny<T> extends true ? TypeIfAny : TypeIfNotAny
+);
+
+// Should never happen
+
+/**
+An if-else-like type that resolves depending on whether the given type is `any` or `never`.
+
+@example
+```
+// When `T` is a NOT `any` or `never` (like `string`) => Returns `IfNotAnyOrNever` branch
+type A = IfNotAnyOrNever<string, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'VALID'
+
+// When `T` is `any` => Returns `IfAny` branch
+type B = IfNotAnyOrNever<any, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'IS_ANY'
+
+// When `T` is `never` => Returns `IfNever` branch
+type C = IfNotAnyOrNever<never, 'VALID', 'IS_ANY', 'IS_NEVER'>;
+//=> 'IS_NEVER'
+```
+*/
+type IfNotAnyOrNever<T, IfNotAnyOrNever, IfAny = any, IfNever = never> =
+	IsAny<T> extends true
+		? IfAny
+		: IsNever<T> extends true
+			? IfNever
+			: IfNotAnyOrNever;
+
+/**
+Merges user specified options with default options.
+
+@example
+```
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
+type SpecifiedOptions = {leavesOnly: true};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//=> {maxRecursionDepth: 10; leavesOnly: true}
+```
+
+@example
+```
+// Complains if default values are not provided for optional options
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10};
+type SpecifiedOptions = {};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                              ~~~~~~~~~~~~~~~~~~~
+// Property 'leavesOnly' is missing in type 'DefaultPathsOptions' but required in type '{ maxRecursionDepth: number; leavesOnly: boolean; }'.
+```
+
+@example
+```
+// Complains if an option's default type does not conform to the expected type
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: 'no'};
+type SpecifiedOptions = {};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                              ~~~~~~~~~~~~~~~~~~~
+// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.
+```
+
+@example
+```
+// Complains if an option's specified type does not conform to the expected type
+
+type PathsOptions = {maxRecursionDepth?: number; leavesOnly?: boolean};
+type DefaultPathsOptions = {maxRecursionDepth: 10; leavesOnly: false};
+type SpecifiedOptions = {leavesOnly: 'yes'};
+
+type Result = ApplyDefaultOptions<PathsOptions, DefaultPathsOptions, SpecifiedOptions>;
+//                                                                   ~~~~~~~~~~~~~~~~
+// Types of property 'leavesOnly' are incompatible. Type 'string' is not assignable to type 'boolean'.
+```
+*/
+type ApplyDefaultOptions<
+	Options extends object,
+	Defaults extends Simplify<Omit<Required<Options>, RequiredKeysOf<Options>> & Partial<Record<RequiredKeysOf<Options>, never>>>,
+	SpecifiedOptions extends Options,
+> =
+	IfAny<SpecifiedOptions, Defaults,
+	IfNever<SpecifiedOptions, Defaults,
+	Simplify<Merge<Defaults, {
+		[Key in keyof SpecifiedOptions
+		as Key extends OptionalKeysOf<Options>
+			? Extract<SpecifiedOptions[Key], undefined> extends never
+				? Key
+				: never
+			: Key
+		]: SpecifiedOptions[Key]
+	}> & Required<Options>> // `& Required<Options>` ensures that `ApplyDefaultOptions<SomeOption, ...>` is always assignable to `Required<SomeOption>`
+	>>;
+
+/**
+Filter out keys from an object.
+
+Returns `never` if `Exclude` is strictly equal to `Key`.
+Returns `never` if `Key` extends `Exclude`.
+Returns `Key` otherwise.
+
+@example
+```
+type Filtered = Filter<'foo', 'foo'>;
+//=> never
+```
+
+@example
+```
+type Filtered = Filter<'bar', string>;
+//=> never
+```
+
+@example
+```
+type Filtered = Filter<'bar', 'foo'>;
+//=> 'bar'
+```
+
+@see {Except}
+*/
+type Filter<KeyType, ExcludeType> = IsEqual<KeyType, ExcludeType> extends true ? never : (KeyType extends ExcludeType ? never : KeyType);
+
+type ExceptOptions = {
+	/**
+	Disallow assigning non-specified properties.
+
+	Note that any omitted properties in the resulting type will be present in autocomplete as `undefined`.
+
+	@default false
+	*/
+	requireExactProps?: boolean;
+};
+
+type DefaultExceptOptions = {
+	requireExactProps: false;
+};
+
+/**
+Create a type from an object type without certain keys.
+
+We recommend setting the `requireExactProps` option to `true`.
+
+This type is a stricter version of [`Omit`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-5.html#the-omit-helper-type). The `Omit` type does not restrict the omitted keys to be keys present on the given type, while `Except` does. The benefits of a stricter type are avoiding typos and allowing the compiler to pick up on rename refactors automatically.
+
+This type was proposed to the TypeScript team, which declined it, saying they prefer that libraries implement stricter versions of the built-in types ([microsoft/TypeScript#30825](https://github.com/microsoft/TypeScript/issues/30825#issuecomment-523668235)).
+
+@example
+```
+import type {Except} from 'type-fest';
+
+type Foo = {
+	a: number;
+	b: string;
+};
+
+type FooWithoutA = Except<Foo, 'a'>;
+//=> {b: string}
+
+const fooWithoutA: FooWithoutA = {a: 1, b: '2'};
+//=> errors: 'a' does not exist in type '{ b: string; }'
+
+type FooWithoutB = Except<Foo, 'b', {requireExactProps: true}>;
+//=> {a: number} & Partial<Record<"b", never>>
+
+const fooWithoutB: FooWithoutB = {a: 1, b: '2'};
+//=> errors at 'b': Type 'string' is not assignable to type 'undefined'.
+
+// The `Omit` utility type doesn't work when omitting specific keys from objects containing index signatures.
+
+// Consider the following example:
+
+type UserData = {
+	[metadata: string]: string;
+	email: string;
+	name: string;
+	role: 'admin' | 'user';
+};
+
+// `Omit` clearly doesn't behave as expected in this case:
+type PostPayload = Omit<UserData, 'email'>;
+//=> type PostPayload = { [x: string]: string; [x: number]: string; }
+
+// In situations like this, `Except` works better.
+// It simply removes the `email` key while preserving all the other keys.
+type PostPayload = Except<UserData, 'email'>;
+//=> type PostPayload = { [x: string]: string; name: string; role: 'admin' | 'user'; }
+```
+
+@category Object
+*/
+type Except<ObjectType, KeysType extends keyof ObjectType, Options extends ExceptOptions = {}> =
+	_Except<ObjectType, KeysType, ApplyDefaultOptions<ExceptOptions, DefaultExceptOptions, Options>>;
+
+type _Except<ObjectType, KeysType extends keyof ObjectType, Options extends Required<ExceptOptions>> = {
+	[KeyType in keyof ObjectType as Filter<KeyType, KeysType>]: ObjectType[KeyType];
+} & (Options['requireExactProps'] extends true
+	? Partial<Record<KeysType, never>>
+	: {});
+
+/**
+Create a type that requires at least one of the given keys. The remaining keys are kept as is.
+
+@example
+```
+import type {RequireAtLeastOne} from 'type-fest';
+
+type Responder = {
+	text?: () => string;
+	json?: () => string;
+	secure?: boolean;
+};
+
+const responder: RequireAtLeastOne<Responder, 'text' | 'json'> = {
+	json: () => '{"message": "ok"}',
+	secure: true
+};
+```
+
+@category Object
+*/
+type RequireAtLeastOne<
+	ObjectType,
+	KeysType extends keyof ObjectType = keyof ObjectType,
+> =
+	IfNotAnyOrNever<ObjectType,
+	IfNever<KeysType,
+	never,
+	_RequireAtLeastOne<ObjectType, IfAny<KeysType, keyof ObjectType, KeysType>>
+	>>;
+
+type _RequireAtLeastOne<
+	ObjectType,
+	KeysType extends keyof ObjectType,
+> = {
+	// For each `Key` in `KeysType` make a mapped type:
+	[Key in KeysType]-?: Required<Pick<ObjectType, Key>> & // 1. Make `Key`'s type required
+	// 2. Make all other keys in `KeysType` optional
+	Partial<Pick<ObjectType, Exclude<KeysType, Key>>>;
+}[KeysType] &
+// 3. Add the remaining keys not in `KeysType`
+Except<ObjectType, KeysType>;
+
+type ExtractSchema = ExtractObjectSchema | ExtractArraySchema | ExtractValueSchema;
+interface ExtractValueSchema {
+    type?: 'string' | 'number' | 'boolean' | 'html';
+    selector?: string;
+    attribute?: string;
+    has?: string;
+    exclude?: string;
+}
+interface ExtractArraySchema {
+    type: 'array';
+    selector: string;
+    has?: string;
+    exclude?: string;
+    items?: ExtractSchema;
+    attribute?: string;
+}
+interface ExtractObjectSchema {
+    type: 'object';
+    selector?: string;
+    has?: string;
+    exclude?: string;
+    properties: {
+        [key: string]: ExtractSchema;
+    };
+}
+
+interface PromiseLock extends Promise<void> {
+    release: () => void;
+}
+
+/**
+ * Options for the {@link FetchEngine.goto}, allowing configuration of HTTP method, payload, headers, and navigation behavior.
+ *
+ * @remarks
+ * Used when navigating to a URL to specify additional parameters beyond the basic URL.
+ *
+ * @example
+ * ```ts
+ * await engine.goto('https://example.com', {
+ *   method: 'POST',
+ *   payload: { username: 'user', password: 'pass' },
+ *   headers: { 'Content-Type': 'application/json' },
+ *   waitUntil: 'networkidle'
+ * });
+ * ```
+ */
+interface GotoActionOptions {
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE' | 'OPTIONS' | 'CONNECT' | 'PATCH';
+    payload?: any;
+    headers?: Record<string, string>;
+    waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    timeoutMs?: number;
+}
+/**
+ * Options for the {@link FetchEngine.waitFor} action, specifying conditions to wait for before continuing.
+ *
+ * @remarks
+ * Controls timing behavior for interactions, allowing waiting for elements, time intervals, or network conditions.
+ */
+interface WaitForActionOptions {
+    ms?: number;
+    selector?: string;
+    networkIdle?: boolean;
+}
+/**
+ * Options for the {@link FetchEngine.submit} action, configuring form submission behavior.
+ *
+ * @remarks
+ * Specifies encoding type for form submissions, particularly relevant for JSON-based APIs.
+ */
+interface SubmitActionOptions {
+    enctype?: 'application/x-www-form-urlencoded' | 'application/json' | 'multipart/form-data';
+}
+/**
+ * Union type representing all possible engine actions that can be dispatched.
+ *
+ * @remarks
+ * Defines the command structure processed during page interactions. Each action type corresponds to
+ * a specific user interaction or navigation command within the action loop architecture.
+ */
+type FetchEngineAction = {
+    type: 'click';
+    selector: string;
+} | {
+    type: 'fill';
+    selector: string;
+    value: string;
+} | {
+    type: 'waitFor';
+    options?: WaitForActionOptions;
+} | {
+    type: 'submit';
+    selector?: any;
+    options?: SubmitActionOptions;
+} | {
+    type: 'getContent';
+} | {
+    type: 'navigate';
+    url: string;
+    opts?: GotoActionOptions;
+} | {
+    type: 'extract';
+    schema: ExtractSchema;
+} | {
+    type: 'pause';
+    message?: string;
+} | {
+    type: 'dispose';
+};
+/**
+ * Represents an action that has been dispatched and is awaiting execution in the active page context.
+ *
+ * @remarks
+ * Connects the action request with its resolution mechanism. Used internally by the action dispatch system
+ * to handle promises while maintaining the page context validity window.
+ */
+interface DispatchedEngineAction {
+    action: FetchEngineAction;
+    resolve: (value?: any) => void;
+    reject: (reason?: any) => void;
+}
+/**
+ * Represents a pending navigation request awaiting resolution.
+ *
+ * @remarks
+ * Tracks navigation requests that have been queued but not yet processed by the request handler.
+ */
+interface PendingEngineRequest {
+    resolve: (value: any) => void;
+    reject: (reason?: any) => void;
+}
+/**
+ * Abstract base class for all fetch engines, providing a unified interface for web content fetching and interaction.
+ *
+ * @remarks
+ * The `FetchEngine` class serves as the foundation for concrete engine implementations (e.g., `CheerioFetchEngine`,
+ * `PlaywrightFetchEngine`). It abstracts underlying crawling technology and provides a consistent API for navigation,
+ * content retrieval, and user interaction.
+ *
+ * The engine architecture uses an event-driven action loop to bridge Crawlee's stateless request handling with
+ * the need for a stateful, sequential API for page interactions. This solves the critical challenge of maintaining
+ * page context validity across asynchronous operations.
+ *
+ * @example
+ * ```ts
+ * import "./playwright"; // 引入注册 Playwright browser 引擎
+ * const engine = await FetchEngine.create(context, { engine: 'browser' });
+ * await engine.goto('https://example.com');
+ * await engine.fill('#username', 'user');
+ * await engine.click('#submit');
+ * const response = await engine.getContent();
+ * ```
+ */
+type AnyFetchEngine = FetchEngine<any, any, any>;
+type AnyFetchEngineCtor = new (...args: any[]) => AnyFetchEngine;
+declare abstract class FetchEngine<TContext extends CrawlingContext = any, TCrawler extends BasicCrawler<TContext> = any, TOptions extends BasicCrawlerOptions<TContext> = any> {
+    private static registry;
+    /**
+     * Registers a fetch engine implementation with the global registry.
+     *
+     * @param engineClass - The engine class to register
+     * @throws {Error} When engine class lacks static `id` or ID is already registered
+     *
+     * @example
+     * ```ts
+     * FetchEngine.register(CheerioFetchEngine);
+     * ```
+     */
+    static register(engineClass: AnyFetchEngineCtor): void;
+    /**
+     * Retrieves a fetch engine implementation by its unique ID.
+     *
+     * @param id - The ID of the engine to retrieve
+     * @returns Engine class if found, otherwise `undefined`
+     */
+    static get(id: string): AnyFetchEngineCtor | undefined;
+    /**
+     * Retrieves a fetch engine implementation by execution mode.
+     *
+     * @param mode - Execution mode (`'http'` or `'browser'`)
+     * @returns Engine class if found, otherwise `undefined`
+     */
+    static getByMode(mode: FetchEngineType): AnyFetchEngineCtor | undefined;
+    /**
+     * Factory method to create and initialize a fetch engine instance.
+     *
+     * @param ctx - Fetch engine context
+     * @param options - Configuration options
+     * @returns Initialized fetch engine instance
+     * @throws {Error} When no suitable engine implementation is found
+     *
+     * @remarks
+     * Primary entry point for engine creation. Selects appropriate implementation based on `engine` name of the option or context.
+     */
+    static create(ctx: FetchEngineContext, options?: BaseFetcherProperties): Promise<AnyFetchEngine | undefined>;
+    /**
+     * Unique identifier for the engine implementation.
+     *
+     * @remarks
+     * Must be defined by concrete implementations. Used for registration and lookup in engine registry.
+     */
+    static readonly id: string;
+    /**
+     * Execution mode of the engine (`'http'` or `'browser'`).
+     *
+     * @remarks
+     * Must be defined by concrete implementations. Indicates whether engine operates at HTTP level or uses full browser.
+     */
+    static readonly mode: FetchEngineType;
+    protected ctx?: FetchEngineContext;
+    protected opts?: BaseFetcherProperties;
+    protected crawler?: TCrawler;
+    protected isCrawlerReady?: boolean;
+    protected requestQueue?: RequestQueue;
+    protected hdrs: Record<string, string>;
+    protected jar: Cookie[];
+    protected pendingRequests: Map<string, PendingEngineRequest>;
+    protected requestCounter: number;
+    protected actionEmitter: EventEmitter;
+    protected isPageActive: boolean;
+    protected navigationLock: PromiseLock;
+    protected lastResponse?: FetchResponse;
+    protected blockedTypes: Set<string>;
+    protected _cleanup?(): Promise<void>;
+    protected abstract _querySelectorAll(context: any, selector: string): Promise<any[]>;
+    protected abstract _extractValue(schema: ExtractValueSchema, context: any): Promise<any>;
+    protected _extract(schema: ExtractSchema, context: any): Promise<any>;
+    /**
+     * Creates the crawler instance for the specific engine implementation.
+     * @param options - The final crawler options.
+     * @internal
+     */
+    protected abstract _createCrawler(options: TOptions): TCrawler;
+    /**
+     * Gets the crawler-specific options from the subclass.
+     * @param ctx - The fetch engine context.
+     * @internal
+     */
+    protected abstract _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<TOptions>> | Partial<TOptions>;
+    /**
+     * Abstract method for building standard [FetchResponse] from Crawlee context.
+     *
+     * @param context - Crawlee crawling context
+     * @returns Promise resolving to [FetchResponse] object
+     *
+     * @remarks
+     * Converts implementation-specific context (Playwright `page` or Cheerio `$`) to standardized response.
+     * @internal
+     */
+    protected abstract buildResponse(context: TContext): Promise<FetchResponse>;
+    /**
+     * Abstract method for executing action within current page context.
+     *
+     * @param context - Crawlee crawling context
+     * @param action - Action to execute
+     * @returns Promise resolving to action result
+     *
+     * @remarks
+     * Handles specific user interactions using underlying technology (Playwright/Cheerio).
+     * @internal
+     */
+    protected abstract executeAction(context: TContext, action: FetchEngineAction): Promise<any>;
+    /**
+     * Navigates to the specified URL.
+     *
+     * @param url - Target URL
+     * @param params - Navigation options
+     * @returns Promise resolving when navigation completes
+     *
+     * @example
+     * ```ts
+     * await engine.goto('https://example.com');
+     * ```
+     */
+    abstract goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
+    /**
+     * Waits for specified condition before continuing.
+     *
+     * @param params - Wait conditions
+     * @returns Promise resolving when wait condition is met
+     *
+     * @example
+     * ```ts
+     * await engine.waitFor({ ms: 1000 }); // Wait 1 second
+     * await engine.waitFor({ selector: '#content' }); // Wait for element
+     * ```
+     */
+    waitFor(params?: WaitForActionOptions): Promise<void>;
+    /**
+     * Clicks on element matching selector.
+     *
+     * @param selector - CSS selector of element to click
+     * @returns Promise resolving when click is processed
+     * @throws {Error} When no active page context exists
+     */
+    click(selector: string): Promise<void>;
+    /**
+     * Fills input element with specified value.
+     *
+     * @param selector - CSS selector of input element
+     * @param value - Value to fill
+     * @returns Promise resolving when fill operation completes
+     * @throws {Error} When no active page context exists
+     */
+    fill(selector: string, value: string): Promise<void>;
+    /**
+     * Submits a form.
+     *
+     * @param selector - Optional form/submit button selector
+     * @param options - Submission options
+     * @returns Promise resolving when form is submitted
+     * @throws {Error} When no active page context exists
+     */
+    submit(selector?: any, options?: SubmitActionOptions): Promise<void>;
+    /**
+     * Pauses execution, allowing for manual intervention or inspection.
+     *
+     * @param message - Optional message to display during pause
+     * @returns Promise resolving when execution is resumed
+     * @throws {Error} When no active page context exists
+     */
+    pause(message?: string): Promise<void>;
+    /**
+     * Extracts structured data from the current page content.
+     *
+     * @param schema - An object defining the data to extract.
+     * @returns A promise that resolves to an object with the extracted data.
+     */
+    extract<T>(schema: ExtractSchema): Promise<T>;
+    protected _normalizeSchema(schema: ExtractSchema): ExtractSchema;
+    /**
+     * Gets the unique identifier of this engine implementation.
+     */
+    get id(): string;
+    /**
+     * Gets the execution mode of this engine (`'http'` or `'browser'`).
+     */
+    get mode(): FetchEngineType;
+    /**
+     * Gets the fetch engine context associated with this instance.
+     */
+    get context(): FetchEngineContext | undefined;
+    /**
+     * Initializes the fetch engine with provided context and options.
+     *
+     * @param context - Fetch engine context
+     * @param options - Configuration options
+     * @returns Promise resolving when initialization completes
+     *
+     * @remarks
+     * Sets up internal state and calls implementation-specific [_initialize](file:///home/riceball/Documents/mywork/public/@isdk/ai-tools/packages/web-fetcher/src/engine/cheerio.ts#L169-L204) method.
+     * Automatically called when creating engine via `FetchEngine.create()`.
+     */
+    initialize(context: FetchEngineContext, options?: BaseFetcherProperties): Promise<void>;
+    cleanup(): Promise<void>;
+    /**
+     * Executes all pending fetch engine actions within the current Crawlee request handler context.
+     *
+     * **Critical Execution Constraint**: This method **MUST** be awaited within the synchronous execution path
+     * of Crawlee's [requestHandler](https://crawlee.dev/js/api/basic-crawler) (before any `await` that yields control back to the event loop).
+     *
+     * ### Why This Constraint Exists
+     * - Crawlee's page context ([PlaywrightCrawler](https://crawlee.dev/js/api/playwright-crawler)'s `page` or [CheerioCrawler](https://crawlee.dev/js/api/cheerio-crawler)'s `$`)
+     *   is **only valid during the synchronous execution phase** of the request handler
+     * - After any `await` (e.g., `await page.goto()`), the page context may be destroyed
+     *   due to Crawlee's internal resource management
+     *
+     * ### How It Works
+     * 1. Processes all actions queued via {@link dispatchAction} (click, fill, submit, etc.)
+     * 2. Maintains the page context validity window via {@link isPageActive} lifecycle flag
+     * 3. Automatically cleans up event listeners upon completion
+     *
+     * Usage see {@link _sharedRequestHandler}
+     * @see {@link _sharedRequestHandler}
+     * @param context The active Crawlee crawling context containing the page/$ object
+     * @throws {Error} If called outside valid page context window (`!this.isPageActive`)
+     * @internal Engine infrastructure method - not for direct consumer use
+     */
+    protected _executePendingActions(context: TContext): Promise<void>;
+    protected _sharedRequestHandler(context: TContext): Promise<void>;
+    protected _sharedFailedRequestHandler(context: TContext, error?: Error): Promise<void>;
+    protected dispatchAction<T>(action: FetchEngineAction): Promise<T>;
+    private _requestHandler;
+    private _failedRequestHandler;
+    protected _commonCleanup(): Promise<void>;
+    /**
+     * Blocks specified resource types from loading.
+     *
+     * @param types - Resource types to block
+     * @param overwrite - Whether to replace existing blocked types
+     * @returns Number of blocked resource types
+     *
+     * @example
+     * ```ts
+     * await engine.blockResources(['image', 'stylesheet']);
+     * await engine.blockResources(['script'], true); // Replace existing
+     * ```
+     */
+    blockResources(types: ResourceType[], overwrite?: boolean): Promise<number>;
+    /**
+     * Gets content of current page.
+     *
+     * @returns Promise resolving to fetch response
+     * @throws {Error} When no content has been fetched yet
+     */
+    getContent(): Promise<FetchResponse>;
+    /**
+     * Manages HTTP headers for requests with multiple overloads.
+     *
+     * @overload
+     * Gets all headers.
+     * @returns All headers as record
+     *
+     * @overload
+     * Gets specific header value.
+     * @param name - Header name
+     * @returns Header value
+     *
+     * @overload
+     * Sets multiple headers.
+     * @param headers - Headers to set
+     * @param replaced - Whether to replace all existing headers
+     * @returns `true` if successful
+     *
+     * @overload
+     * Sets single header.
+     * @param name - Header name
+     * @param value - Header value or `null` to remove
+     * @returns `true` if successful
+     *
+     * @example
+     * ```ts
+     * const allHeaders = await engine.headers();
+     * const userAgent = await engine.headers('user-agent');
+     * await engine.headers({ 'x-custom': 'value' });
+     * await engine.headers('auth', 'token');
+     * ```
+     */
+    headers(): Promise<Record<string, string>>;
+    headers(name: string): Promise<string>;
+    headers(headers: Record<string, string>, replaced?: boolean): Promise<boolean>;
+    headers(name: string, value: string | null): Promise<boolean>;
+    /**
+     * Manages cookies for current session with multiple overloads.
+     *
+     * @overload
+     * Gets all cookies.
+     * @returns Array of cookies
+     *
+     * @overload
+     * Sets cookies for session.
+     * @param cookies - Cookies to set
+     * @returns `true` if successful
+     *
+     * @example
+     * ```ts
+     * const cookies = await engine.cookies();
+     * await engine.cookies([{ name: 'session', value: '123' }]);
+     * ```
+     */
+    cookies(): Promise<Cookie[]>;
+    cookies(cookies: Cookie[]): Promise<boolean>;
+    /**
+     * Disposes of engine, cleaning up all resources.
+     *
+     * @returns Promise resolving when disposal completes
+     */
+    dispose(): Promise<void>;
+}
+
+type FetchReturnType = 'response' | 'context' | 'outputs' | 'any' | 'none';
+interface FetchReturnTypeRegistry {
+    response: FetchResponse;
+    context: FetchContext;
+    result: FetchActionResult<any> | undefined;
+    outputs: Record<string, any>;
+    any: any;
+    none: void;
+}
+type FetchReturnTypeFor<R extends FetchReturnType> = R extends keyof FetchReturnTypeRegistry ? FetchReturnTypeRegistry[R] : never;
+
+interface FetchActionInContext extends FetchActionProperties {
+    index?: number;
+    error?: Error;
+    depth?: number;
+}
+interface BaseFetchContextInteralState {
+    engine?: FetchEngine;
+    [key: string]: any;
+}
+interface FetchContextInteralState extends BaseFetchContextInteralState {
+    actionStack?: FetchActionInContext[];
+    actionIndex?: number;
+}
+interface FetchEngineContext extends BaseFetcherProperties {
+    id: string;
+    url?: string;
+    finalUrl?: string;
+    lastResponse?: FetchResponse;
+    lastResult?: FetchActionResult;
+    internal: BaseFetchContextInteralState;
+}
+interface FetchContext extends FetchEngineContext {
+    currentAction?: FetchActionInContext;
+    outputs: Record<string, any>;
+    execute<R extends FetchReturnType = 'any'>(actionOptions: FetchActionOptions): Promise<FetchActionResult<R>>;
+    action<R extends FetchReturnType = 'any'>(name: string, params?: any, options?: Partial<FetchActionOptions>): Promise<FetchActionResult<R>>;
+    internal: FetchContextInteralState;
+    eventBus: EventEmitter;
+}
+
+type CheerioAPI = NonNullable<CheerioCrawlingContext['$']>;
+type CheerioSelection = ReturnType<CheerioAPI>;
+type CheerioNode = ReturnType<CheerioSelection['first']>;
+declare class CheerioFetchEngine extends FetchEngine<CheerioCrawlingContext, CheerioCrawler, CheerioCrawlerOptions> {
+    static readonly id = "cheerio";
+    static readonly mode = "http";
+    protected buildResponse(context: CheerioCrawlingContext): Promise<FetchResponse>;
+    protected _querySelectorAll(context: {
+        $: CheerioAPI;
+        el: CheerioNode;
+    }, selector: string): Promise<any[]>;
+    protected _extractValue(schema: ExtractValueSchema, context: {
+        el: CheerioNode;
+    }): Promise<any>;
+    protected executeAction(context: CheerioCrawlingContext, action: FetchEngineAction): Promise<any>;
+    private _updateStateAfterNavigation;
+    protected _createCrawler(options: CheerioCrawlerOptions): CheerioCrawler;
+    protected _getSpecificCrawlerOptions(ctx: FetchEngineContext): CheerioCrawlerOptions;
+    goto(url: string, params?: GotoActionOptions): Promise<void | FetchResponse>;
+}
+
+type Page = NonNullable<PlaywrightCrawlingContext['page']>;
+type Locator = ReturnType<Page['locator']>;
+declare class PlaywrightFetchEngine extends FetchEngine<PlaywrightCrawlingContext, PlaywrightCrawler, PlaywrightCrawlerOptions> {
+    static readonly id = "playwright";
+    static readonly mode = "browser";
+    protected buildResponse(context: PlaywrightCrawlingContext): Promise<FetchResponse>;
+    protected _querySelectorAll(context: Locator, selector: string): Promise<any[]>;
+    protected _extractValue(schema: ExtractValueSchema, context: Locator): Promise<any>;
+    protected executeAction(context: PlaywrightCrawlingContext, action: FetchEngineAction): Promise<any>;
+    protected _createCrawler(options: PlaywrightCrawlerOptions): PlaywrightCrawler;
+    protected _getSpecificCrawlerOptions(ctx: FetchEngineContext): Promise<Partial<PlaywrightCrawlerOptions>>;
+    goto(url: string, opts?: GotoActionOptions): Promise<FetchResponse>;
+}
+
+declare enum FetchActionResultStatus {
+    /**
+     * 动作执行失败但未抛出（通常因 failOnError=false）；错误信息在 error 字段
+     */
+    Failed = 0,
+    /**
+     * 动作按预期完成（即便产生 warnings）
+     */
+    Success = 1,
+    /**
+     * 动作被判定为不执行/降级为 noop（比如引擎不支持且 degradeTo='noop'）
+     * 能力不支持且 degradeTo='noop' 时：status='skipped'，warnings 增加 { code:'capability-not-supported' }
+     */
+    Skipped = 2
+}
+type FetchActionCapabilityMode = 'native' | 'simulate' | 'noop';
+interface FetchActionMeta {
+    id: string;
+    index?: number;
+    engineType?: FetchEngineType;
+    capability?: FetchActionCapabilityMode;
+    response?: FetchResponse;
+    timings?: {
+        start: number;
+        total: number;
+    };
+    retries?: number;
+}
+interface FetchActionResult<R extends FetchReturnType = FetchReturnType> {
+    status: FetchActionResultStatus;
+    returnType?: R;
+    result?: FetchReturnTypeFor<R>;
+    error?: Error;
+    meta?: FetchActionMeta;
+}
+interface BaseFetchActionProperties {
+    id?: string;
+    name?: string;
+    params?: any;
+    storeAs?: string;
+    failOnError?: boolean;
+    failOnTimeout?: boolean;
+    timeoutMs?: number;
+    maxRetries?: number;
+    [key: string]: any;
+}
+type BaseFetchActionOptions = RequireAtLeastOne<BaseFetchActionProperties, 'id' | 'name'>;
+interface BaseFetchCollectorActionProperties extends BaseFetchActionProperties {
+    activateOn?: string | RegExp | Array<string | RegExp>;
+    deactivateOn?: string | RegExp | Array<string | RegExp>;
+    collectOn?: string | RegExp | Array<string | RegExp>;
+    background?: boolean;
+}
+type BaseFetchCollectorOptions = RequireAtLeastOne<BaseFetchCollectorActionProperties, 'id' | 'name'>;
+interface FetchActionProperties extends BaseFetchActionProperties {
+    collectors?: BaseFetchCollectorOptions[];
+}
+type FetchActionOptions = RequireAtLeastOne<FetchActionProperties, 'id' | 'name'>;
+type FetchActionCapabilities = {
+    [mode in FetchEngineType]?: FetchActionCapabilityMode;
+};
+declare abstract class FetchAction {
+    private static registry;
+    static register(actionClass: typeof FetchAction): void;
+    static get(id: string): typeof FetchAction | undefined;
+    static create(id: FetchActionOptions): FetchAction | undefined;
+    static create(id: string): FetchAction | undefined;
+    static has(name: string): boolean;
+    static list(): string[];
+    static id: string;
+    static returnType: FetchReturnType;
+    static capabilities: FetchActionCapabilities;
+    static getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
+    getCapability(mode?: FetchEngineType): FetchActionCapabilityMode;
+    get id(): string;
+    get returnType(): FetchReturnType;
+    get capabilities(): FetchActionCapabilities;
+    protected onBeforeExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
+    protected onAfterExec?(context: FetchContext, options?: FetchActionProperties): Promise<void> | void;
+    abstract onExecute(context: FetchContext, options?: FetchActionProperties, eventPayload?: any): Promise<any> | any;
+    protected delegateToEngine(context: FetchContext, method: keyof FetchEngine, ...args: any[]): Promise<any>;
+    protected installCollectors(context: FetchContext, options?: FetchActionProperties): CollectorsRuntime | undefined;
+    /**
+     * Action 开始生命周期
+     * 负责：初始化 stack、设置 currentAction、触发事件、调用钩子
+     */
+    beforeExec(context: FetchContext, options?: FetchActionProperties): Promise<{
+        entry: FetchActionInContext;
+        collectors: CollectorsRuntime | undefined;
+    }>;
+    /**
+     * Action 结束生命周期
+     * 负责：调用钩子、赋值lastResult, 触发事件、清理 stack、恢复 currentAction
+     */
+    afterExec(context: FetchContext, options?: BaseFetchCollectorActionProperties, result?: FetchActionResult, scope?: {
+        entry: FetchActionInContext;
+        collectors?: CollectorsRuntime;
+    }): Promise<void>;
+    execute<R extends FetchReturnType = 'any'>(context: FetchContext, options?: FetchActionProperties): Promise<FetchActionResult<R>>;
+}
+type CollectorsRuntime = {
+    cleanup: () => void;
+    awaitExecPendings: () => Promise<void>;
+};
+
+type FetchEngineType = 'http' | 'browser';
+type BrowserEngine = 'playwright' | 'puppeteer';
+type FetchEngineMode = FetchEngineType | 'auto' | string;
+type ResourceType = 'image' | 'stylesheet' | 'font' | 'script' | 'media' | string;
+interface BaseFetcherProperties {
+    /**
+     * 抓取模式
+     *
+     * - `http`: 使用 HTTP 进行抓取
+     * - `browser`: 使用浏览器进行抓取
+     * - `auto`: auto 会走“智能探测”选择 http 或 browser, 但是如果没有启用 smart，并且在站点注册表中没有，那么则等价为 http.
+     */
+    engine?: FetchEngineMode;
+    enableSmart?: boolean;
+    useSiteRegistry?: boolean;
+    antibot?: boolean;
+    headers?: Record<string, string>;
+    cookies?: Cookie[];
+    reuseCookies?: boolean;
+    throwHttpErrors?: boolean;
+    proxy?: string | string[];
+    blockResources?: ResourceType[];
+    ignoreSslErrors?: boolean;
+    browser?: {
+        /**
+         * 浏览器引擎，默认为 playwright
+         *
+         * - `playwright`: 使用 Playwright 引擎
+         * - `puppeteer`: 使用 Puppeteer 引擎
+         */
+        engine?: BrowserEngine;
+        headless?: boolean;
+        waitUntil?: 'load' | 'domcontentloaded' | 'networkidle' | 'commit';
+    };
+    http?: {
+        method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        body?: any;
+    };
+    timeoutMs?: number;
+    maxConcurrency?: number;
+    maxRequestsPerMinute?: number;
+    delayBetweenRequestsMs?: number;
+    retries?: number;
+    sites?: FetchSite[];
+    url?: string;
+}
+interface FetchSite extends BaseFetcherProperties {
+    domain: string;
+    pathScope?: string[];
+    meta?: {
+        updatedAt?: number;
+        ttlMs?: number;
+        source?: 'manual' | 'smart';
+    };
+}
+type OnFetchPauseCallback = (options: {
+    message?: string;
+}) => Promise<void>;
+interface FetcherOptions extends BaseFetcherProperties {
+    actions?: FetchActionOptions[];
+    onPause?: OnFetchPauseCallback;
+}
+interface FetchMetadata {
+    mode: FetchEngineType;
+    engine?: BrowserEngine;
+    timings?: {
+        start: number;
+        total: number;
+        ttfb?: number;
+        dns?: number;
+        tcp?: number;
+        firstByte?: number;
+        download?: number;
+    };
+    proxy?: string;
+    [key: string]: any;
+}
+interface FetchResponse {
+    url: string;
+    finalUrl: string;
+    statusCode?: number;
+    statusText?: string;
+    headers: Record<string, string>;
+    contentType?: string;
+    body?: string | Buffer<ArrayBufferLike>;
+    html?: string;
+    text?: string;
+    json?: any;
+    cookies?: Cookie[];
+    metadata?: FetchMetadata;
+}
+declare const DefaultFetcherProperties: BaseFetcherProperties;
+
+declare class FetchSession {
+    private options;
+    readonly id: string;
+    readonly context: FetchContext;
+    private closed;
+    constructor(options?: FetcherOptions);
+    /**
+     * 执行单个动作
+     */
+    execute<R extends FetchReturnType = 'response'>(actionOptions: FetchActionOptions): Promise<FetchActionResult<R>>;
+    executeAll(actions: FetchActionOptions[]): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
+    getOutputs(): Record<string, any>;
+    dispose(): Promise<void>;
+    private ensureEngine;
+    private createContext;
+}
+
+declare class WebFetcher {
+    private defaults;
+    constructor(defaults?: FetcherOptions);
+    createSession(options?: FetcherOptions): Promise<FetchSession>;
+    fetch(url: string, options?: FetcherOptions): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
+    fetch(options: FetcherOptions): Promise<{
+        result: FetchResponse | undefined;
+        outputs: Record<string, any>;
+    }>;
+}
+
+declare class ClickAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "simulate";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+declare class FillAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "simulate";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+declare class GetContentAction extends FetchAction {
+    static id: string;
+    static returnType: "response";
+    static capabilities: {
+        http: "native";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<any>;
+}
+
+declare class GotoAction extends FetchAction {
+    static id: string;
+    static returnType: "response";
+    static capabilities: {
+        http: "native";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties, eventPayload?: any): Promise<FetchResponse | void>;
+}
+
+declare class SubmitAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "simulate";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+declare class WaitForAction extends FetchAction {
+    static id: string;
+    static returnType: "none";
+    static capabilities: {
+        http: "native";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+interface ExtractActionProperties extends BaseFetchActionProperties {
+    params: ExtractSchema;
+}
+declare class ExtractAction extends FetchAction {
+    static id: string;
+    static returnType: "any";
+    static capabilities: {
+        http: "native";
+        browser: "native";
+    };
+    onExecute(context: FetchContext, options?: ExtractActionProperties): Promise<any>;
+}
+
+declare class PauseAction extends FetchAction {
+    static id: string;
+    static capabilities: {
+        http: "native";
+        browser: "native";
+    };
+    static returnType: "none";
+    onExecute(context: FetchContext, options?: BaseFetchActionProperties): Promise<void>;
+}
+
+declare function fetchWeb(options: FetcherOptions): Promise<{
+    result: FetchResponse | undefined;
+    outputs: Record<string, any>;
+}>;
+declare function fetchWeb(url: string, options?: FetcherOptions): Promise<{
+    result: FetchResponse | undefined;
+    outputs: Record<string, any>;
+}>;
+
+export { type BaseFetchActionOptions, type BaseFetchActionProperties, type BaseFetchCollectorActionProperties, type BaseFetchCollectorOptions, type BaseFetcherProperties, type BrowserEngine, CheerioFetchEngine, ClickAction, DefaultFetcherProperties, type DispatchedEngineAction, ExtractAction, type ExtractActionProperties, FetchAction, type FetchActionCapabilities, type FetchActionCapabilityMode, type FetchActionInContext, type FetchActionOptions, type FetchActionProperties, type FetchActionResult, FetchActionResultStatus, type FetchContext, FetchEngine, type FetchEngineAction, type FetchEngineContext, type FetchEngineType, type FetchMetadata, type FetchResponse, type FetchReturnType, type FetchReturnTypeFor, type FetchReturnTypeRegistry, FetchSession, type FetchSite, type FetcherOptions, FillAction, GetContentAction, GotoAction, type GotoActionOptions, type OnFetchPauseCallback, PauseAction, type PendingEngineRequest, PlaywrightFetchEngine, type ResourceType, SubmitAction, type SubmitActionOptions, WaitForAction, type WaitForActionOptions, WebFetcher, fetchWeb };