@crawlee/types 4.0.0-beta.64 → 4.0.0-beta.66

package/browser.d.ts

@@ -1,3 +1,4 @@
+import type { ISession } from './session.js';
 import type { Dictionary } from './utility-types.js';
 export interface Cookie {
     /**
@@ -60,4 +61,107 @@ export interface BrowserLikeResponse {
     url(): string;
     headers(): Dictionary<string | string[]>;
 }
+/**
+ * A snapshot of the relevant state of a page, as extracted by
+ * {@link IBrowserPool.extractPageState}.
+ */
+export interface PageState {
+    /**
+     * Cookies currently set in the page's browsing context.
+     */
+    cookies: Cookie[];
+}
+/**
+ * Options accepted by {@link IBrowserPool.newPage}.
+ */
+export interface NewPageOptions {
+    /**
+     * Assign a custom ID to the page. If you don't provide one, a random string
+     * ID is generated.
+     */
+    id?: string;
+    /**
+     * The crawling session that will use the returned page.
+     *
+     * The pool derives proxy configuration from the session's {@link
+     * ProxyInfo|proxy} (including TLS-error handling) — there are intentionally
+     * no standalone `proxyUrl` / `ignoreTlsErrors` options; configure them
+     * through the session instead.
+     *
+     * Session injection is **best-effort**: the pool may use the session's
+     * {@link ProxyInfo|proxy}, cookies, or fingerprint data to configure the
+     * page or the underlying browser, but none of this is guaranteed. Different
+     * pool implementations (or pool configurations such as `useIncognitoPages`)
+     * may support different subsets of session properties — or ignore them
+     * entirely.
+     *
+     * The crawler is still responsible for deterministic session setup (e.g.
+     * injecting cookies into the page before navigation) that must happen
+     * regardless of pool implementation.
+     */
+    session?: ISession;
+}
+/**
+ * Minimal contract that any object passed to a browser crawler as its `browserPool`
+ * option must satisfy.
+ *
+ * Lifecycle (`destroy`) is the responsibility of whoever owns the pool — since a
+ * user-supplied pool is never owned by the crawler, the crawler never tears it
+ * down.
+ *
+ * Implement this interface to plug a custom page-provisioning strategy into any
+ * Crawlee browser crawler — for example a remote browser farm, a session-aware
+ * pool that pins pages to fingerprints differently, or a thin wrapper around the
+ * built-in `BrowserPool`.
+ *
+ * @category Browser management
+ */
+export interface IBrowserPool<Page = unknown> {
+    /**
+     * Opens a new page. The pool decides which browser to use, launching a new
+     * one if needed.
+     */
+    newPage(options?: NewPageOptions): Promise<Page>;
+    /**
+     * Signals the pool that the caller is done with the page. The pool is
+     * responsible for closing the page and performing any necessary cleanup
+     * (e.g. retiring the underlying browser when a session has gone bad).
+     *
+     * @param page The page to release back to the pool.
+     * @param options.error If the page is being released because of an error,
+     *   pass the error here. In particular, if the error is a
+     *   {@link SessionError}, implementations should treat it as a signal
+     *   to purge all state associated with the session (e.g. discard any
+     *   browser that served the page).
+     */
+    closePage(page: Page, options?: {
+        error?: Error;
+    }): Promise<void>;
+    /**
+     * Extracts the relevant state from a page so the caller can persist it —
+     * for example, back-propagating cookies into the crawling {@link
+     * ISession|session}.
+     *
+     * @param page The page to read state from.
+     */
+    extractPageState(page: Page): Promise<PageState>;
+    /**
+     * Injects state (currently just cookies) into a page. This is the
+     * counterpart to {@link IBrowserPool.extractPageState} and lets the
+     * caller set up a page — for example, seeding it with the crawling
+     * {@link ISession|session}'s cookies before navigation.
+     *
+     * As with {@link IBrowserPool.newPage}, the caller decides *what* state
+     * to inject, while the pool decides *how*.
+     *
+     * Isolation between pages is **best-effort**: depending on the pool
+     * implementation and its configuration, multiple pages may share a browsing
+     * context, so injected state (such as cookies) can bleed across pages
+     * served by the same underlying browser.
+     *
+     * @param page The page to inject state into.
+     * @param state The state to inject.
+     */
+    injectPageState(page: Page, state: PageState): Promise<void>;
+}
 //# sourceMappingURL=browser.d.ts.map

package/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,MAAM;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAChC,GAAG,IAAI,MAAM,CAAC;IACd,OAAO,IAAI,UAAU,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC5C"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../src/browser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,WAAW,MAAM;IACnB;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC;;OAEG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;IAChD;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAChC,GAAG,IAAI,MAAM,CAAC;IACd,OAAO,IAAI,UAAU,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC5C;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,EAAE,QAAQ,CAAC;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,YAAY,CAAC,IAAI,GAAG,OAAO;IACxC;;;OAGG;IACH,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;;;OAMG;IACH,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAEjD;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChE"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/types",
-    "version": "4.0.0-beta.64",
+    "version": "4.0.0-beta.66",
     "description": "Shared types for the crawlee projects",
     "engines": {
         "node": ">=22.0.0"
@@ -53,5 +53,5 @@
             }
         }
     },
-    "gitHead": "76ba0fe1101b1e14fb5e1962540107775ad4e513"
+    "gitHead": "3a7bed61f54a8bf2c8b2efef17ffa3a37cb18940"
 }