apify 4.0.0-beta.12 → 4.0.0-beta.13

package/dist/key_value_store.js

@@ -1,7 +1,6 @@
 import { KeyValueStore as CoreKeyValueStore } from '@crawlee/core';
+import { KeyValueStoreClient as RemoteKeyValueStoreClient } from 'apify-client';
 import { createHmacSignature } from '@apify/utilities';
-// @ts-ignore newer crawlee versions already declare this method in core
-const { getPublicUrl } = CoreKeyValueStore.prototype;
 /**
  * @inheritDoc
  */
@@ -9,15 +8,27 @@ export class KeyValueStore extends CoreKeyValueStore {
     /**
      * Returns a URL for the given key that may be used to publicly
      * access the value in the remote key-value store.
+     *
+     * On the Apify platform the URL is signed with the store's
+     * `urlSigningSecretKey` so that anyone with the URL can read the record
+     * without authentication. Locally we delegate to crawlee's default
+     * implementation (which produces a `file://` URL or returns `undefined`).
      */
-    getPublicUrl(key) {
+    async getPublicUrl(key) {
         const config = this.config;
-        if (!config.get('isAtHome') && getPublicUrl) {
-            return getPublicUrl.call(this, key);
+        // Detect a remote (Apify) store by its client type rather than by
+        // `isAtHome`, so that a `forceCloud` store opened locally still gets a
+        // signed Apify URL (matching the platform behaviour). `client` is
+        // `private` on `CoreKeyValueStore`, so bypass the visibility check.
+        const { client } = this;
+        const isLocalStore = !(client instanceof RemoteKeyValueStoreClient);
+        if (isLocalStore) {
+            return super.getPublicUrl(key);
         }
-        const publicUrl = new URL(`${config.get('apiPublicBaseUrl')}/v2/key-value-stores/${this.id}/records/${key}`);
-        if (this.storageObject?.urlSigningSecretKey) {
-            publicUrl.searchParams.append('signature', createHmacSignature(this.storageObject.urlSigningSecretKey, key));
+        const publicUrl = new URL(`${config.apiPublicBaseUrl}/v2/key-value-stores/${this.id}/records/${key}`);
+        const metadata = (await client.getMetadata());
+        if (metadata?.urlSigningSecretKey) {
+            publicUrl.searchParams.append('signature', createHmacSignature(metadata.urlSigningSecretKey, key));
         }
         return publicUrl.toString();
     }
@@ -28,6 +39,3 @@ export class KeyValueStore extends CoreKeyValueStore {
         return super.open(storeIdOrName, options);
     }
 }
-// @ts-ignore newer crawlee versions already declare this method in core
-CoreKeyValueStore.prototype.getPublicUrl = KeyValueStore.prototype.getPublicUrl;
-//# sourceMappingURL=key_value_store.js.map

package/dist/platform_event_manager.d.ts

@@ -56,4 +56,3 @@ export declare class PlatformEventManager extends EventManager {
      */
     close(): Promise<void>;
 }
-//# sourceMappingURL=platform_event_manager.d.ts.map

package/dist/platform_event_manager.js

@@ -46,7 +46,9 @@ export class PlatformEventManager extends EventManager {
     /** Websocket connection to Actor events. */
     eventsWs;
     constructor(config = Configuration.getGlobalConfig()) {
-        super();
+        super({
+            persistStateIntervalMillis: config.persistStateIntervalMillis,
+        });
         this.config = config;
     }
     /**
@@ -58,7 +60,7 @@ export class PlatformEventManager extends EventManager {
             return;
         }
         await super.init();
-        const eventsWsUrl = this.config.get('actorEventsWsUrl');
+        const eventsWsUrl = this.config.actorEventsWsUrl;
         // Locally there is no web socket to connect, so just print a log message.
         if (!eventsWsUrl) {
             this.log.debug(`Environment variable ${ACTOR_ENV_VARS.EVENTS_WEBSOCKET_URL} is not set, no events from Apify platform will be emitted.`);
@@ -87,8 +89,7 @@ export class PlatformEventManager extends EventManager {
         });
         this.eventsWs.on('error', (err) => {
             // Don't print this error as this happens in the case of very short Actor.main().
-            if (err.message ===
-                'WebSocket was closed before the connection was established')
+            if (err.message === 'WebSocket was closed before the connection was established')
                 return;
             this.log.exception(err, 'web socket connection failed');
         });
@@ -110,4 +111,3 @@ export class PlatformEventManager extends EventManager {
         this.eventsWs?.close();
     }
 }
-//# sourceMappingURL=platform_event_manager.js.map

package/dist/proxy_configuration.d.ts

@@ -1,6 +1,8 @@
-import type { ProxyConfigurationOptions as CoreProxyConfigurationOptions, ProxyInfo as CoreProxyInfo } from '@crawlee/core';
+import type { ProxyConfigurationOptions as CoreProxyConfigurationOptions } from '@crawlee/core';
 import { ProxyConfiguration as CoreProxyConfiguration } from '@crawlee/core';
+import type { ProxyInfo as CoreProxyInfo } from '@crawlee/types';
 import { Configuration } from './configuration.js';
+type NewUrlOptions = Parameters<CoreProxyConfiguration['newProxyInfo']>[0];
 export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions {
     /**
      * User's password for the proxy. By default, it is taken from the `APIFY_PROXY_PASSWORD`
@@ -24,6 +26,12 @@ export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions
      * on the Apify cloud, or when using the [Apify CLI](https://github.com/apify/apify-cli).
      */
     countryCode?: string;
+    /**
+     * If set, all proxied requests will use IP addresses geolocated to the specified subdivision (e.g. US state).
+     * Requires `countryCode` to be set. The value must follow the ISO 3166-2 subdivision code format,
+     * e.g. `'CA'` for California when `countryCode` is `'US'`.
+     */
+    subdivisionCode?: string;
     /**
      * Same option as `groups` which can be used to
      * configurate the proxy by UI input schema. You should use the `groups` option in your crawler code.
@@ -35,10 +43,15 @@ export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions
      */
     apifyProxyCountry?: string;
     /**
-     * Multiple different ProxyConfigurationOptions stratified into tiers. Crawlee crawlers will switch between those tiers
-     * based on the blocked request statistics.
+     * Same option as `subdivisionCode` which can be used to
+     * configurate the proxy by UI input schema. You should use the `subdivisionCode` option in your crawler code.
+     */
+    apifyProxySubdivision?: string;
+    /**
+     * As part of the init process, we verify the configuration by checking the proxy status endpoint.
+     * This can make the init slower, to opt-out of this, use `checkAccess: false` (defaults to `true`).
      */
-    tieredProxyConfig?: Omit<ProxyConfigurationOptions, keyof CoreProxyConfigurationOptions | 'tieredProxyConfig'>[];
+    checkAccess?: boolean;
 }
 /**
  * The main purpose of the ProxyInfo object is to provide information
@@ -64,9 +77,6 @@ export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions
  *   requestHandler({ proxyInfo }) {
  *       // Getting used proxy URL
  *       const proxyUrl = proxyInfo.url;
- *
- *       // Getting ID of used Session
- *       const sessionIdentifier = proxyInfo.sessionId;
  *   }
  * })
  *
@@ -77,7 +87,7 @@ export interface ProxyInfo extends CoreProxyInfo {
      * An array of proxy groups to be used by the [Apify Proxy](https://docs.apify.com/proxy).
      * If not provided, the proxy will select the groups automatically.
      */
-    groups: string[];
+    groups?: string[];
     /**
      * If set and relevant proxies are available in your Apify account, all proxied requests will
      * use IP addresses that are geolocated to the specified country. For example `GB` for IPs
@@ -89,6 +99,11 @@ export interface ProxyInfo extends CoreProxyInfo {
      * This parameter is optional, by default, the proxy uses all available proxy servers from all countries.
      */
     countryCode?: string;
+    /**
+     * If set, all proxied requests use IP addresses geolocated to the specified subdivision (e.g. US state).
+     * ISO 3166-2 subdivision code, e.g. `'CA'` when `countryCode` is `'US'`.
+     */
+    subdivisionCode?: string;
     /**
      * User's password for the proxy. By default, it is taken from the `APIFY_PROXY_PASSWORD`
      * environment variable, which is automatically set by the system when running the Actors
@@ -133,6 +148,7 @@ export declare class ProxyConfiguration extends CoreProxyConfiguration {
     readonly config: Configuration;
     private groups;
     private countryCode?;
+    private subdivisionCode?;
     private password?;
     private hostname;
     private port?;
@@ -149,45 +165,26 @@ export declare class ProxyConfiguration extends CoreProxyConfiguration {
      * You should use the {@link createProxyConfiguration} function to create a pre-initialized
      * `ProxyConfiguration` instance instead of calling this manually.
      */
-    initialize(): Promise<boolean>;
-    /**
-     * This function creates a new {@link ProxyInfo} info object.
-     * It is used by CheerioCrawler and PuppeteerCrawler to generate proxy URLs and also to allow the user to inspect
-     * the currently used proxy via the requestHandler parameter `proxyInfo`.
-     * Use it if you want to work with a rich representation of a proxy URL.
-     * If you need the URL string only, use {@link ProxyConfiguration.newUrl}.
-     * @param [sessionId]
-     *  Represents the identifier of user {@link Session} that can be managed by the {@link SessionPool} or
-     *  you can use the Apify Proxy [Session](https://docs.apify.com/proxy#sessions) identifier.
-     *  When the provided sessionId is a number, it's converted to a string. Property sessionId of
-     *  {@link ProxyInfo} is always returned as a type string.
-     *
-     *  All the HTTP requests going through the proxy with the same session identifier
-     *  will use the same target proxy server (i.e. the same IP address).
-     *  The identifier must not be longer than 50 characters and include only the following: `0-9`, `a-z`, `A-Z`, `"."`, `"_"` and `"~"`.
-     * @return Represents information about used proxy and its configuration.
-     */
-    newProxyInfo(sessionId?: string | number, options?: Parameters<CoreProxyConfiguration['newProxyInfo']>[1]): Promise<ProxyInfo | undefined>;
-    /**
-     * Returns a new proxy URL based on provided configuration options and the `sessionId` parameter.
-     * @param [sessionId]
-     *  Represents the identifier of user {@link Session} that can be managed by the {@link SessionPool} or
-     *  you can use the Apify Proxy [Session](https://docs.apify.com/proxy#sessions) identifier.
-     *  When the provided sessionId is a number, it's converted to a string.
-     *
-     *  All the HTTP requests going through the proxy with the same session identifier
-     *  will use the same target proxy server (i.e. the same IP address).
-     *  The identifier must not be longer than 50 characters and include only the following: `0-9`, `a-z`, `A-Z`, `"."`, `"_"` and `"~"`.
-     * @return A string with a proxy URL, including authentication credentials and port number.
-     *  For example, `http://bob:password123@proxy.example.com:8000`
+    initialize(options?: {
+        checkAccess?: boolean;
+    }): Promise<boolean>;
+    /**
+     * Returns a new {@link ProxyInfo} object with a fresh proxy URL. Each call mints an
+     * independent URL; for Apify Proxy a random session id is embedded so consecutive
+     * calls resolve to different IPs.
+     */
+    newProxyInfo(options?: NewUrlOptions): Promise<ProxyInfo | undefined>;
+    /**
+     * Returns a new proxy URL. For Apify Proxy, each call generates a URL with a fresh
+     * random session id, so consecutive calls return independent URLs. For custom
+     * `proxyUrls`, the URLs are rotated round-robin.
      */
-    newUrl(sessionId?: string | number, options?: Parameters<CoreProxyConfiguration['newUrl']>[1]): Promise<string | undefined>;
-    protected _generateTieredProxyUrls(tieredProxyConfig: NonNullable<ProxyConfigurationOptions['tieredProxyConfig']>, globalOptions: ProxyConfigurationOptions): string[][];
+    newUrl(options?: NewUrlOptions): Promise<string | undefined>;
     /**
      * Returns proxy username.
      */
-    protected _getUsername(sessionId?: string): string;
-    protected composeDefaultUrl(sessionId?: string): string;
+    protected _getUsername(sessionId: string): string;
+    protected composeDefaultUrl(sessionId: string): string;
     /**
      * Fetch & set the proxy password from Apify API if an Apify token is provided.
      */
@@ -212,4 +209,4 @@ export declare class ProxyConfiguration extends CoreProxyConfiguration {
      */
     protected _throwCannotCombineCustomWithApify(): void;
 }
-//# sourceMappingURL=proxy_configuration.d.ts.map
+export {};

package/dist/proxy_configuration.js

@@ -5,11 +5,15 @@ import { APIFY_ENV_VARS, APIFY_PROXY_VALUE_REGEX } from '@apify/consts';
 import { cryptoRandomObjectId } from '@apify/utilities';
 import { Actor } from './actor.js';
 import { Configuration } from './configuration.js';
-// https://docs.apify.com/proxy/datacenter-proxy#username-parameters
-const MAX_SESSION_ID_LENGTH = 50;
 const CHECK_ACCESS_REQUEST_TIMEOUT_MILLIS = 4_000;
 const CHECK_ACCESS_MAX_ATTEMPTS = 2;
 const COUNTRY_CODE_REGEX = /^[A-Z]{2}$/;
+// ISO 3166-2 subdivision codes are 1–3 uppercase alphanumeric characters, e.g. 'CA' (California), 'NSW' (New South Wales), '9' (Wien, AT-9)
+const SUBDIVISION_CODE_REGEX = /^[A-Z0-9]{1,3}$/;
+// Apify Proxy session identifier embedded in the proxy username — opaque to
+// users; a fresh one is minted for every URL the SDK hands out so that the
+// returned proxy URLs are independent.
+const SESSION_ID_LENGTH = 12;
 /**
  * Configures connection to a proxy server with the provided options. Proxy servers are used to prevent target websites from blocking
  * your crawlers based on IP address rate limits or blacklists. Setting proxy configuration in your crawlers automatically configures
@@ -47,6 +51,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
     config;
     groups;
     countryCode;
+    subdivisionCode;
     password;
     hostname;
     port;
@@ -67,35 +72,37 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
             apifyProxyGroups: ow.optional.array.ofType(ow.string.matches(APIFY_PROXY_VALUE_REGEX)),
             countryCode: ow.optional.string.matches(COUNTRY_CODE_REGEX),
             apifyProxyCountry: ow.optional.string.matches(COUNTRY_CODE_REGEX),
+            subdivisionCode: ow.optional.string.matches(SUBDIVISION_CODE_REGEX),
+            apifyProxySubdivision: ow.optional.string.matches(SUBDIVISION_CODE_REGEX),
             password: ow.optional.string,
-            tieredProxyUrls: ow.optional.array.ofType(ow.array.ofType(ow.string)),
-            tieredProxyConfig: ow.optional.array.ofType(ow.object),
         }));
-        const { groups = [], apifyProxyGroups = [], countryCode, apifyProxyCountry, password = config.get('proxyPassword'), tieredProxyConfig, tieredProxyUrls, } = options;
-        this.tieredProxyUrls ??= tieredProxyUrls;
-        if (tieredProxyConfig) {
-            this.tieredProxyUrls = this._generateTieredProxyUrls(tieredProxyConfig, options);
-        }
+        const { groups = [], apifyProxyGroups = [], countryCode, apifyProxyCountry, subdivisionCode, apifyProxySubdivision, password = config.proxyPassword, } = options;
         const groupsToUse = groups.length ? groups : apifyProxyGroups;
         const countryCodeToUse = countryCode || apifyProxyCountry;
-        const hostname = config.get('proxyHostname');
-        const port = config.get('proxyPort');
+        const subdivisionCodeToUse = subdivisionCode || apifyProxySubdivision;
+        const hostname = config.proxyHostname;
+        const port = config.proxyPort;
+        // The Apify Proxy subdivision is expressed as part of the country
+        // username parameter (`country-US_CA`), so a country is required.
+        if (subdivisionCodeToUse && !countryCodeToUse) {
+            throw new Error('ProxyConfiguration: "subdivisionCode" requires "countryCode" to be set.');
+        }
         // Validation
-        if ((proxyUrls || newUrlFunction) &&
-            (groupsToUse.length || countryCodeToUse)) {
+        if ((proxyUrls || newUrlFunction) && (groupsToUse.length || countryCodeToUse || subdivisionCodeToUse)) {
             this._throwCannotCombineCustomWithApify();
         }
         if (proxyUrls && newUrlFunction)
             this._throwCannotCombineCustomMethods();
         this.groups = groupsToUse;
         this.countryCode = countryCodeToUse;
+        this.subdivisionCode = subdivisionCodeToUse;
         this.password = password;
         this.hostname = hostname;
         this.port = port;
         this.usesApifyProxy = !this.proxyUrls && !this.newUrlFunction;
-        if (proxyUrls && proxyUrls.some((url) => url.includes('apify.com'))) {
+        if (proxyUrls && proxyUrls.some((url) => url?.includes('apify.com'))) {
             this.log.warning('Some Apify proxy features may work incorrectly. Please consider setting up Apify properties instead of `proxyUrls`.\n' +
-                'See https://sdk.apify.com/docs/guides/proxy-management#apify-proxy-configuration');
+                'See https://docs.apify.com/sdk/js/docs/concepts/proxy-management#apify-proxy-configuration');
         }
     }
     /**
@@ -106,7 +113,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
      * You should use the {@link createProxyConfiguration} function to create a pre-initialized
      * `ProxyConfiguration` instance instead of calling this manually.
      */
-    async initialize() {
+    async initialize(options) {
         if (this.usesApifyProxy) {
             if (!this.password) {
                 await this._setPasswordIfToken();
@@ -124,111 +131,66 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
                         `so that the SDK can fetch the proxy password from Apify API, when ${APIFY_ENV_VARS.PROXY_PASSWORD} is not defined`);
                 }
             }
-            return this._checkAccess();
+            if (options?.checkAccess !== false) {
+                return this._checkAccess();
+            }
         }
         return true;
     }
     /**
-     * This function creates a new {@link ProxyInfo} info object.
-     * It is used by CheerioCrawler and PuppeteerCrawler to generate proxy URLs and also to allow the user to inspect
-     * the currently used proxy via the requestHandler parameter `proxyInfo`.
-     * Use it if you want to work with a rich representation of a proxy URL.
-     * If you need the URL string only, use {@link ProxyConfiguration.newUrl}.
-     * @param [sessionId]
-     *  Represents the identifier of user {@link Session} that can be managed by the {@link SessionPool} or
-     *  you can use the Apify Proxy [Session](https://docs.apify.com/proxy#sessions) identifier.
-     *  When the provided sessionId is a number, it's converted to a string. Property sessionId of
-     *  {@link ProxyInfo} is always returned as a type string.
-     *
-     *  All the HTTP requests going through the proxy with the same session identifier
-     *  will use the same target proxy server (i.e. the same IP address).
-     *  The identifier must not be longer than 50 characters and include only the following: `0-9`, `a-z`, `A-Z`, `"."`, `"_"` and `"~"`.
-     * @return Represents information about used proxy and its configuration.
+     * Returns a new {@link ProxyInfo} object with a fresh proxy URL. Each call mints an
+     * independent URL; for Apify Proxy a random session id is embedded so consecutive
+     * calls resolve to different IPs.
      */
-    async newProxyInfo(sessionId, options) {
-        if (typeof sessionId === 'number')
-            sessionId = `${sessionId}`;
-        ow(sessionId, ow.optional.string
-            .maxLength(MAX_SESSION_ID_LENGTH)
-            .matches(APIFY_PROXY_VALUE_REGEX));
-        const proxyInfo = await super.newProxyInfo(sessionId, options);
-        if (!proxyInfo)
-            return proxyInfo;
-        const { groups, countryCode, password, port, hostname } = (this.usesApifyProxy ? this : new URL(proxyInfo.url));
-        return {
-            ...proxyInfo,
-            sessionId,
-            groups,
-            countryCode,
-            // this.password is not encoded, but the password from the URL will be, we need to normalize
-            password: this.usesApifyProxy
-                ? (password ?? '')
-                : decodeURIComponent(password),
-            hostname,
-            port: port,
+    async newProxyInfo(options) {
+        const url = await this.newUrl(options);
+        if (!url)
+            return undefined;
+        const parsed = new URL(url);
+        const result = {
+            url,
+            username: decodeURIComponent(parsed.username),
+            password: decodeURIComponent(parsed.password),
+            hostname: parsed.hostname,
+            port: parsed.port,
         };
+        if (this.usesApifyProxy) {
+            result.groups = this.groups;
+            if (this.countryCode !== undefined)
+                result.countryCode = this.countryCode;
+            if (this.subdivisionCode !== undefined)
+                result.subdivisionCode = this.subdivisionCode;
+        }
+        return result;
     }
     /**
-     * Returns a new proxy URL based on provided configuration options and the `sessionId` parameter.
-     * @param [sessionId]
-     *  Represents the identifier of user {@link Session} that can be managed by the {@link SessionPool} or
-     *  you can use the Apify Proxy [Session](https://docs.apify.com/proxy#sessions) identifier.
-     *  When the provided sessionId is a number, it's converted to a string.
-     *
-     *  All the HTTP requests going through the proxy with the same session identifier
-     *  will use the same target proxy server (i.e. the same IP address).
-     *  The identifier must not be longer than 50 characters and include only the following: `0-9`, `a-z`, `A-Z`, `"."`, `"_"` and `"~"`.
-     * @return A string with a proxy URL, including authentication credentials and port number.
-     *  For example, `http://bob:password123@proxy.example.com:8000`
+     * Returns a new proxy URL. For Apify Proxy, each call generates a URL with a fresh
+     * random session id, so consecutive calls return independent URLs. For custom
+     * `proxyUrls`, the URLs are rotated round-robin.
      */
-    async newUrl(sessionId, options) {
-        if (typeof sessionId === 'number')
-            sessionId = `${sessionId}`;
-        ow(sessionId, ow.optional.string
-            .maxLength(MAX_SESSION_ID_LENGTH)
-            .matches(APIFY_PROXY_VALUE_REGEX));
-        if (this.newUrlFunction) {
-            return ((await this._callNewUrlFunction(sessionId, {
-                request: options?.request,
-            })) ?? undefined);
-        }
-        if (this.proxyUrls) {
-            return this._handleCustomUrl(sessionId);
+    async newUrl(options) {
+        if (this.newUrlFunction || this.proxyUrls) {
+            return super.newUrl(options);
         }
-        if (this.tieredProxyUrls) {
-            return (this._handleTieredUrl(sessionId ?? cryptoRandomObjectId(6), options).proxyUrl ?? undefined);
-        }
-        return this.composeDefaultUrl(sessionId);
-    }
-    _generateTieredProxyUrls(tieredProxyConfig, globalOptions) {
-        return tieredProxyConfig.map((config) => [
-            new ProxyConfiguration({
-                ...globalOptions,
-                ...config,
-                tieredProxyConfig: undefined,
-            }).composeDefaultUrl(),
-        ]);
+        return this.composeDefaultUrl(cryptoRandomObjectId(SESSION_ID_LENGTH));
     }
     /**
      * Returns proxy username.
      */
     _getUsername(sessionId) {
-        let username;
-        const { groups, countryCode } = this;
+        const { groups, countryCode, subdivisionCode } = this;
         const parts = [];
         if (groups && groups.length) {
             parts.push(`groups-${groups.join('+')}`);
         }
-        if (sessionId) {
-            parts.push(`session-${sessionId}`);
+        parts.push(`session-${sessionId}`);
+        if (subdivisionCode) {
+            parts.push(`country-${countryCode}_${subdivisionCode}`);
         }
-        if (countryCode) {
+        else if (countryCode) {
             parts.push(`country-${countryCode}`);
         }
-        username = parts.join(',');
-        if (parts.length === 0)
-            username = 'auto';
-        return username;
+        return parts.join(',');
     }
     composeDefaultUrl(sessionId) {
         const username = this._getUsername(sessionId);
@@ -243,7 +205,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
      */
     // TODO: Make this private
     async _setPasswordIfToken() {
-        const token = this.config.get('token');
+        const { token } = this.config;
         if (!token)
             return;
         try {
@@ -291,7 +253,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
      * Apify Proxy can be down for a second or a minute, but this should not crash processes.
      */
     async _fetchStatus() {
-        const proxyStatusUrl = this.config.get('proxyStatusUrl', 'http://proxy.apify.com');
+        const { proxyStatusUrl } = this.config;
         const requestOpts = {
             url: `${proxyStatusUrl}/?format=json`,
             proxyUrl: await this.newUrl(),
@@ -316,7 +278,7 @@ export class ProxyConfiguration extends CoreProxyConfiguration {
     _throwCannotCombineCustomWithApify() {
         throw new Error('Cannot combine custom proxies with Apify Proxy! ' +
             'It is not allowed to set "options.proxyUrls" or "options.newUrlFunction" combined with ' +
-            '"options.groups" or "options.apifyProxyGroups" and "options.countryCode" or "options.apifyProxyCountry".');
+            '"options.groups", "options.apifyProxyGroups", "options.countryCode", "options.apifyProxyCountry", ' +
+            '"options.subdivisionCode" or "options.apifyProxySubdivision".');
     }
 }
-//# sourceMappingURL=proxy_configuration.js.map

package/dist/storage.d.ts

@@ -0,0 +1,58 @@
+import type { Constructor, IStorage, StorageOpenOptions } from '@crawlee/core';
+import type { StorageClient } from '@crawlee/types';
+import type { Configuration } from './configuration.js';
+export interface OpenStorageOptions {
+    /**
+     * If set to `true` then the cloud storage is used even if the `CRAWLEE_STORAGE_DIR`
+     * environment variable is set. This way it is possible to combine local and cloud storage.
+     * @default false
+     */
+    forceCloud?: boolean;
+}
+/**
+ * Identifies a storage by its alias from the Actor's schema storages
+ * (resolved via the `ACTOR_STORAGES_JSON` environment variable).
+ */
+export interface StorageAlias {
+    alias: string;
+}
+/**
+ * Identifies a storage by its platform ID.
+ */
+export interface StorageId {
+    id: string;
+}
+/**
+ * Identifies a storage by its name.
+ */
+export interface StorageName {
+    name: string;
+}
+/**
+ * Identifies a storage to open. Can be:
+ * - A plain `string` for backward compatibility (treated as ID or name)
+ * - `{ alias: string }` to resolve from the Actor's schema storages (`ACTOR_STORAGES_JSON`)
+ * - `{ id: string }` to open by explicit platform ID
+ * - `{ name: string }` to open by explicit name
+ */
+export type StorageIdentifier = string | StorageAlias | StorageId | StorageName;
+/**
+ * Identifies a storage to open, without alias support.
+ * Used for key-value stores and request queues, which do not support aliases.
+ * Can be:
+ * - A plain `string` for backward compatibility (treated as ID or name)
+ * - `{ id: string }` to open by explicit platform ID
+ * - `{ name: string }` to open by explicit name
+ */
+export type StorageIdentifierWithoutAlias = string | StorageId | StorageName;
+export interface OpenStorageContext {
+    config: Configuration;
+    client?: StorageClient;
+    purgedStorageAliases: Set<string>;
+}
+/**
+ * Opens a storage by its identifier, handling Apify alias resolution and local purging.
+ */
+export declare function openStorage<T extends IStorage>(storageClass: Constructor<T> & {
+    open(id?: string | null, options?: StorageOpenOptions): Promise<T>;
+}, identifier: StorageIdentifier | null | undefined, context: OpenStorageContext): Promise<T>;

package/dist/storage.js

@@ -0,0 +1,79 @@
+import { ApifyStorageClient } from './apify_storage_client.js';
+const STORAGE_TYPE_KEYS = {
+    Dataset: 'datasets',
+    KeyValueStore: 'keyValueStores',
+    RequestQueue: 'requestQueues',
+};
+const parsedStoragesJson = new Map();
+/**
+ * Resolves a {@link StorageIdentifier} to a plain string ID or name
+ * that can be passed to crawlee v4's `<Storage>.open()`.
+ */
+function resolveStorageIdentifier(storageType, identifier, config) {
+    if (identifier === null || identifier === undefined) {
+        return undefined;
+    }
+    if (typeof identifier === 'string') {
+        return identifier;
+    }
+    if ('id' in identifier) {
+        return identifier.id;
+    }
+    if ('name' in identifier) {
+        return identifier.name;
+    }
+    // { alias: string }
+    const storagesJson = config.actorStoragesJson;
+    if (config.isAtHome && storagesJson) {
+        let storages;
+        try {
+            if (!parsedStoragesJson.has(storagesJson)) {
+                parsedStoragesJson.set(storagesJson, JSON.parse(storagesJson));
+            }
+            storages = parsedStoragesJson.get(storagesJson);
+        }
+        catch {
+            throw new Error(`Failed to parse ACTOR_STORAGES_JSON environment variable: ${storagesJson}`);
+        }
+        const typeKey = STORAGE_TYPE_KEYS[storageType];
+        const resolvedId = storages[typeKey]?.[identifier.alias];
+        if (resolvedId) {
+            return resolvedId;
+        }
+        throw new Error(`Storage alias "${identifier.alias}" not found in ACTOR_STORAGES_JSON for storage type "${storageType}". ` +
+            `Available aliases: ${Object.keys(storages[typeKey] ?? {}).join(', ') || '(none)'}`);
+    }
+    // When using local storage, just use the alias as a name.
+    // When using platform storage, we can't just make up a name — the alias must be
+    // in ACTOR_STORAGES_JSON.
+    if (config.isAtHome) {
+        throw new Error(`Storage alias "${identifier.alias}" cannot be resolved because ACTOR_STORAGES_JSON is not set. ` +
+            `Aliases are only available for storages declared in the Actor's schema.`);
+    }
+    return identifier.alias;
+}
+/**
+ * Opens a storage by its identifier, handling Apify alias resolution and local purging.
+ */
+export async function openStorage(storageClass, identifier, context) {
+    const isAlias = identifier !== null && identifier !== undefined && typeof identifier === 'object' && 'alias' in identifier;
+    if (isAlias && !context.config.isAtHome && context.client instanceof ApifyStorageClient) {
+        throw new Error('The `alias` option is not allowed for Apify-based storages running outside of Apify');
+    }
+    const resolvedIdOrName = resolveStorageIdentifier(storageClass.name, identifier, context.config);
+    // When running locally, purge aliased storages on first open
+    // (similar to how crawlee purges default storages on start).
+    if (isAlias &&
+        !context.config.isAtHome &&
+        context.config.purgeOnStart &&
+        !context.purgedStorageAliases.has(identifier.alias)) {
+        context.purgedStorageAliases.add(identifier.alias);
+        const existingStorage = await storageClass.open(resolvedIdOrName ?? null, {
+            storageClient: context.client,
+        });
+        await existingStorage.drop();
+    }
+    return storageClass.open(resolvedIdOrName ?? null, {
+        storageClient: context.client,
+    });
+}

package/dist/utils.d.ts

@@ -18,4 +18,3 @@ export declare function checkCrawleeVersion(): void;
  * @ignore
  */
 export declare function printOutdatedSdkWarning(): void;
-//# sourceMappingURL=utils.d.ts.map