@crawlee/types 4.0.0-beta.57 → 4.0.0-beta.59

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@crawlee/types",
-    "version": "4.0.0-beta.57",
+    "version": "4.0.0-beta.59",
     "description": "Shared types for the crawlee projects",
     "engines": {
         "node": ">=22.0.0"
@@ -53,5 +53,5 @@
             }
         }
     },
-    "gitHead": "a1ebcee6aa4017e4468c4d8c00895127b1bc6ff4"
+    "gitHead": "77e1c23edec732aadfd4e27bd12a8e1a8e0ab076"
 }

package/session.d.ts

@@ -1,6 +1,4 @@
 import type { CookieJar, SerializedCookieJar } from 'tough-cookie';
-import type { Cookie } from './browser.js';
-import type { Dictionary } from './utility-types.js';
 /**
  * The main purpose of the ProxyInfo object is to provide information
  * about the current proxy connection used by the crawler for the request.
@@ -71,6 +69,7 @@ export interface SessionState {
     maxUsageCount: number;
     expiresAt: string;
     createdAt: string;
+    retired: boolean;
 }
 /**
  * Sessions are used to store information such as cookies and can be used for generating fingerprints and proxy sessions.
@@ -80,49 +79,19 @@ export interface SessionState {
  */
 export interface ISession {
     readonly id: string;
-    userData: Dictionary;
-    errorScore: number;
-    usageCount: number;
-    maxErrorScore: number;
-    errorScoreDecrement: number;
-    expiresAt: Date;
-    createdAt: Date;
-    maxUsageCount: number;
     cookieJar: CookieJar;
     proxyInfo?: ProxyInfo;
-    /**
-     * Indicates whether the session is blocked.
-     * Session is blocked once it reaches the `maxErrorScore`.
-     */
-    isBlocked(): boolean;
-    /**
-     * Indicates whether the session is expired.
-     * Session expiration is determined by the `maxAgeSecs`.
-     * Once the session is older than `createdAt + maxAgeSecs` the session is considered expired.
-     */
-    isExpired(): boolean;
-    /**
-     * Indicates whether the session is used maximum number of times.
-     * Session maximum usage count can be changed by `maxUsageCount` parameter.
-     */
-    isMaxUsageCountReached(): boolean;
     /**
      * Indicates whether the session can be used for next requests.
-     * Session is usable when it is not expired, not blocked and the maximum usage count has not be reached.
+     * Session is usable when it is not expired, not blocked and the maximum usage count has not been reached.
      */
     isUsable(): boolean;
     /**
      * This method should be called after a successful session usage.
-     * It increases `usageCount` and potentially lowers the `errorScore` by the `errorScoreDecrement`.
      */
     markGood(): void;
     /**
-     * Gets session state for persistence in KeyValueStore.
-     * @returns Represents session internal state.
-     */
-    getState(): SessionState;
-    /**
-     * Marks session as blocked and emits event on the `SessionPool`
+     * Marks session as blocked.
      * This method should be used if the session usage was unsuccessful
      * and you are sure that it is because of the session configuration and not any external matters.
      * For example when server returns 403 status code.
@@ -134,32 +103,30 @@ export interface ISession {
      * Should be used when the session has been used unsuccessfully. For example because of timeouts.
      */
     markBad(): void;
+}
+/**
+ * Minimal contract that any object passed to a crawler as its `sessionPool` option must satisfy.
+ *
+ * Crawlers only depend on a single method of the built-in `SessionPool`: `getSession()` /
+ * `getSession(id)` to hand out an {@link ISession} for a request. Lifecycle (reset, teardown)
+ * 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 session-management strategy into any Crawlee crawler —
+ * for example a remote, multi-process pool, a database-backed pool, or a thin wrapper around the
+ * built-in `SessionPool` with different rotation rules.
+ *
+ * @category Scaling
+ */
+export interface ISessionPool {
     /**
-     * Saves cookies from an HTTP response to be used with the session.
-     * It expects an object with a `headers` property that's either an `Object`
-     * (typical Node.js responses) or a `Function` (Puppeteer Response).
-     *
-     * It then parses and saves the cookies from the `set-cookie` header, if available.
-     */
-    setCookiesFromResponse(response: Response): void;
-    /**
-     * Saves an array with cookie objects to be used with the session.
-     * The objects should be in the format that
-     * [Puppeteer uses](https://pptr.dev/#?product=Puppeteer&version=v2.0.0&show=api-pagecookiesurls),
-     * but you can also use this function to set cookies manually:
+     * Returns a usable {@link ISession}. Without an id, the pool decides which session to return
+     * (creating a new one when appropriate). With an id, the pool returns the matching session if
+     * it is still usable.
      *
-     * ```
-     * [
-     *   { name: 'cookie1', value: 'my-cookie' },
-     *   { name: 'cookie2', value: 'your-cookie' }
-     * ]
-     * ```
-     */
-    setCookies(cookies: Cookie[], url: string): void;
-    /**
-     * Returns cookies in a format compatible with puppeteer/playwright and ready to be used with `page.setCookie`.
-     * @param url website url. Only cookies stored for this url will be returned
+     * In case the `SessionPool` cannot provide a usable session given the configuration,
+     * this method may return `undefined`.
      */
-    getCookies(url: string): Cookie[];
+    getSession(sessionId?: string): Promise<ISession | undefined>;
 }
 //# sourceMappingURL=session.d.ts.map

package/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,mBAAmB,CAAC;IAC/B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACrB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;;OAGG;IACH,sBAAsB,IAAI,OAAO,CAAC;IAElC;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC;IAEpB;;;OAGG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;OAGG;IACH,QAAQ,IAAI,YAAY,CAAC;IAEzB;;;;;;OAMG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;IAEhB;;;;;;OAMG;IACH,sBAAsB,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IAEjD;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjD;;;OAGG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACrC"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,WAAW,SAAS;IACtB;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IAEZ;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAEtB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,mBAAmB,CAAC;IAC/B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,OAAO,CAAC;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,SAAS,CAAC;IACrB,SAAS,CAAC,EAAE,SAAS,CAAC;IAEtB;;;OAGG;IACH,QAAQ,IAAI,OAAO,CAAC;IAEpB;;OAEG;IACH,QAAQ,IAAI,IAAI,CAAC;IAEjB;;;;;;OAMG;IACH,MAAM,IAAI,IAAI,CAAC;IAEf;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IACzB;;;;;;;OAOG;IACH,UAAU,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAAC;CACjE"}