scrapely 1.2.7 → 1.2.9

package/dist/actor.d.ts

@@ -371,7 +371,9 @@ export declare class Actor {
     static getInputOrThrow<T = ActorInput>(): Promise<T>;
     /**
      * Synchronously get the actor input (cached from first access).
-     * This matches Apify's Actor.input behavior.
+     * The platform sets ACTOR_INPUT only for small inputs; for large ones this
+     * returns the input once `await Actor.getInput()` has loaded it from the
+     * default key-value store.
      */
     static get input(): Record<string, any> | undefined;
     /**
@@ -546,8 +548,8 @@ export declare class Actor {
      * });
      * ```
      *
-     * For compatibility with existing Actor Input UI (Input Schema), this function returns
-     * `undefined` when `{ useApifyProxy: false }` is passed.
+     * Pass the proxy input field (`editor: "proxy"`) as is: this function returns
+     * `undefined` when `{ useScrapelyProxy: false }` is passed without custom proxies.
      *
      * @param options - Proxy configuration options
      * @returns Promise resolving to ProxyConfiguration instance, or undefined
@@ -701,3 +703,5 @@ export declare class Actor {
         enqueueLinks: typeof import("./utils.js").enqueueLinks;
     };
 }
+/** Resolves once stdout and stderr have flushed their buffers, or after `maxMs`. */
+export declare function waitForStdioDrain(maxMs: number, streams?: NodeJS.WritableStream[]): Promise<void>;

package/dist/actor.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Actor = exports.EXIT_CODES = exports.ACTOR_PERMISSION_LEVEL = void 0;
+exports.waitForStdioDrain = waitForStdioDrain;
 require("./log-env.js");
 const node_events_1 = require("node:events");
 /** Actor permission level - matches Apify's ACTOR_PERMISSION_LEVEL enum */
@@ -172,6 +173,7 @@ class Actor {
     async init(options = {}) {
         if (this.initialized)
             return;
+        cachedInput = undefined; // a fresh init reads this run's input again
         // NOTE: `initialized` is set at the END of init — a failed platform init
         // must stay retryable instead of leaving a half-initialized Actor.
         Actor.installFatalChargeHandlers();
@@ -410,6 +412,13 @@ class Actor {
                 const metamorphKey = `INPUT-METAMORPH-${count}`;
                 const metamorphInput = await store.getValue(metamorphKey);
                 if (metamorphInput !== null && metamorphInput !== undefined) {
+                    // Same treatment as the regular input: decrypt secret fields
+                    // and let the synchronous Actor.input getter return it.
+                    if (typeof metamorphInput === 'object' && !Array.isArray(metamorphInput)) {
+                        const decrypted = (0, secrets_js_1.decryptSecretInputs)(metamorphInput);
+                        cachedInput = decrypted;
+                        return decrypted;
+                    }
                     return metamorphInput;
                 }
                 // Fall through to regular INPUT if metamorph key not found
@@ -437,7 +446,11 @@ class Actor {
         // Decrypt secret inputs after loading (must happen here, not in init(),
         // because the input needs to be available first)
         if (input && typeof input === 'object' && !Array.isArray(input)) {
-            return (0, secrets_js_1.decryptSecretInputs)(input);
+            const decrypted = (0, secrets_js_1.decryptSecretInputs)(input);
+            // Large inputs are only in the INPUT record (no ACTOR_INPUT env):
+            // let the synchronous Actor.input getter return what was loaded here.
+            cachedInput = decrypted;
+            return decrypted;
         }
         return input;
     }
@@ -450,14 +463,16 @@ class Actor {
     }
     /**
      * Synchronously get the actor input (cached from first access).
-     * This matches Apify's Actor.input behavior.
+     * The platform sets ACTOR_INPUT only for small inputs; for large ones this
+     * returns the input once `await Actor.getInput()` has loaded it from the
+     * default key-value store.
      */
     static get input() {
         if (cachedInput !== undefined)
             return cachedInput ?? undefined;
         const raw = process.env.ACTOR_INPUT;
         if (!raw) {
-            cachedInput = null;
+            // Not cached: a later Actor.getInput() fills it from the INPUT record.
             return undefined;
         }
         try {
@@ -928,10 +943,11 @@ class Actor {
         await eventManager.close();
         (0, events_client_js_1.disconnectEvents)();
         (0, patch_storage_js_1.disconnectStorage)();
-        // Brief grace for in-flight I/O after flush (bounded).
-        await new Promise((resolve) => {
-            setTimeout(resolve, Math.min(1000, flushDeadlineMs));
-        });
+        // Let buffered stdout/stderr reach the log pipe before the process exits
+        // (pipe writes are async in Node). Storage was flushed above, so this
+        // replaces the old fixed 1 s sleep: it resolves as soon as both streams
+        // drain, usually within milliseconds, and is still bounded.
+        await waitForStdioDrain(Math.min(1000, flushDeadlineMs));
     }
     /**
      * Sets the status message for the current Actor run.
@@ -1015,8 +1031,8 @@ class Actor {
      * });
      * ```
      *
-     * For compatibility with existing Actor Input UI (Input Schema), this function returns
-     * `undefined` when `{ useApifyProxy: false }` is passed.
+     * Pass the proxy input field (`editor: "proxy"`) as is: this function returns
+     * `undefined` when `{ useScrapelyProxy: false }` is passed without custom proxies.
      *
      * @param options - Proxy configuration options
      * @returns Promise resolving to ProxyConfiguration instance, or undefined
@@ -1439,3 +1455,22 @@ class Actor {
     static utils = utils_js_1.utils;
 }
 exports.Actor = Actor;
+/** Resolves once stdout and stderr have flushed their buffers, or after `maxMs`. */
+async function waitForStdioDrain(maxMs, streams = [process.stdout, process.stderr]) {
+    const drained = Promise.all(streams.map((stream) => new Promise((resolve) => {
+        const s = stream;
+        if (!s.writableLength || s.writableFinished)
+            return resolve();
+        // An ended stream accepts no more writes; wait for it to finish flushing.
+        if (s.writableEnded) {
+            s.once('finish', () => resolve());
+            return;
+        }
+        // A zero-length write's callback runs after everything queued before it.
+        s.write('', () => resolve());
+    })));
+    let timer;
+    await Promise.race([drained, new Promise((resolve) => { timer = setTimeout(resolve, maxMs); })]);
+    if (timer)
+        clearTimeout(timer);
+}

package/dist/charging.d.ts

@@ -76,6 +76,10 @@ export declare class ChargingManager {
     private chargingState?;
     private chargingLogDataset?;
     private notPpeWarningPrinted;
+    /** Idempotency key of the last charge the platform accepted (pushDataAndCharge void-on-failure). */
+    private lastAcceptedOperationId;
+    /** Voids not yet confirmed by the platform; retried before the next push and at exit. */
+    private pendingVoids;
     /** Unresolved platform POSTs: key = idempotency UUID (never event name). */
     private readonly pendingCharges;
     private flushInFlight;
@@ -126,6 +130,19 @@ export declare class ChargingManager {
      * Returns null when the outcome is uncertain after retries.
      */
     private postChargeWithRetries;
+    /** @internal Idempotency key of the charge accepted by the last _chargeExclusive call, if any. */
+    _takeLastAcceptedOperationId(): string | undefined;
+    /**
+     * @internal Reverse an accepted charge whose items were never stored
+     * (POST /v2/actor-runs/:runId/charge/void), then unwind the local
+     * reservation. Returns true when the platform voided it.
+     */
+    _voidCharge(eventName: string, operationId: string, reservedCount: number): Promise<boolean>;
+    /**
+     * @internal Retry unconfirmed voids (caller holds the operation lock).
+     * Returns false while any earlier void is still unconfirmed.
+     */
+    _retryPendingVoids(): Promise<boolean>;
     /** Clamp local reservation down when the server accepted fewer events. */
     /** @internal Used by pushDataAndCharge dual-event reconciliation. */
     applyAcceptedCount(eventName: string, reservedCount: number, acceptedCount: number, eventPrice?: number): number;
@@ -151,3 +168,9 @@ export declare function pushDataAndCharge<T>({ chargingManager, items, eventName
     isDefaultDataset: boolean;
     pushFn: (limitedItems: T | T[]) => Promise<void>;
 }): Promise<ChargeResult>;
+/**
+ * @internal True when a dataset push certainly stored nothing: the storage API
+ * answered with an error status, or the request never reached it. Timeouts and
+ * resets after the request was sent are not proof (the write may have landed).
+ */
+export declare function pushCertainlyFailed(err: unknown): boolean;

package/dist/charging.js

@@ -6,6 +6,7 @@ exports.resolveDefaultDatasetItemEventName = resolveDefaultDatasetItemEventName;
 exports.hasDefaultDatasetItemEventInPricing = hasDefaultDatasetItemEventInPricing;
 exports.mergeChargeResults = mergeChargeResults;
 exports.pushDataAndCharge = pushDataAndCharge;
+exports.pushCertainlyFailed = pushCertainlyFailed;
 const node_crypto_1 = require("node:crypto");
 /** Client safe-replay window; server TTL is longer (35d). */
 exports.CHARGE_IDEMPOTENCY_SAFE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
@@ -108,6 +109,10 @@ class ChargingManager {
     chargingState;
     chargingLogDataset;
     notPpeWarningPrinted = false;
+    /** Idempotency key of the last charge the platform accepted (pushDataAndCharge void-on-failure). */
+    lastAcceptedOperationId;
+    /** Voids not yet confirmed by the platform; retried before the next push and at exit. */
+    pendingVoids = [];
     /** Unresolved platform POSTs: key = idempotency UUID (never event name). */
     pendingCharges = new Map();
     flushInFlight = null;
@@ -398,6 +403,59 @@ class ChargingManager {
             `${lastError?.message ?? lastError}`);
         return null;
     }
+    /** @internal Idempotency key of the charge accepted by the last _chargeExclusive call, if any. */
+    _takeLastAcceptedOperationId() {
+        const id = this.lastAcceptedOperationId;
+        this.lastAcceptedOperationId = undefined;
+        return id;
+    }
+    /**
+     * @internal Reverse an accepted charge whose items were never stored
+     * (POST /v2/actor-runs/:runId/charge/void), then unwind the local
+     * reservation. Returns true when the platform voided it.
+     */
+    async _voidCharge(eventName, operationId, reservedCount) {
+        if (!this.isAtHome || !this.actorRunId)
+            return false;
+        const runClient = this.apifyClient.run(this.actorRunId);
+        for (let attempt = 0; attempt < this.postAttempts; attempt++) {
+            try {
+                await runClient.httpClient.call({
+                    url: runClient._url('charge/void'),
+                    method: 'POST',
+                    headers: { 'idempotency-key': operationId },
+                });
+                // Confirmed (voided or already voided): only now give the budget back.
+                this.applyAcceptedCount(eventName, reservedCount, 0);
+                return true;
+            }
+            catch (err) {
+                const status = httpStatusOf(err);
+                // 404: nothing to void; 409: already settled; 4xx auth: permanent.
+                // The charge stands; keep the local reservation that matches it.
+                if (status !== undefined && status >= 400 && status < 500)
+                    return false;
+                if (attempt + 1 < this.postAttempts)
+                    await new Promise((r) => setTimeout(r, 250 * (attempt + 1)));
+            }
+        }
+        // Outcome unknown: keep the reservation and retry before the next push / at exit.
+        this.pendingVoids.push({ eventName, operationId, reservedCount });
+        console.error(`[Scrapely] Void of charge ${operationId} ('${eventName}') not confirmed yet; will retry`);
+        return false;
+    }
+    /**
+     * @internal Retry unconfirmed voids (caller holds the operation lock).
+     * Returns false while any earlier void is still unconfirmed.
+     */
+    async _retryPendingVoids() {
+        const pending = this.pendingVoids;
+        this.pendingVoids = [];
+        for (const v of pending) {
+            await this._voidCharge(v.eventName, v.operationId, v.reservedCount);
+        }
+        return this.pendingVoids.length === 0;
+    }
     /** Clamp local reservation down when the server accepted fewer events. */
     /** @internal Used by pushDataAndCharge dual-event reconciliation. */
     applyAcceptedCount(eventName, reservedCount, acceptedCount, eventPrice) {
@@ -431,6 +489,7 @@ class ChargingManager {
     async _flushPendingExclusive(maxIntents = 32, deadlineMs) {
         if (!this.actorRunId)
             return 0;
+        await this._retryPendingVoids();
         if (this.flushInFlight) {
             return this.flushInFlight;
         }
@@ -584,6 +643,8 @@ class ChargingManager {
             }
             if (accepted !== null) {
                 this.pendingCharges.delete(intent.idempotencyKey);
+                if (accepted > 0)
+                    this.lastAcceptedOperationId = intent.idempotencyKey;
                 chargedCount = this.applyAcceptedCount(normalizedEventName, chargedCount, accepted, eventPricing.price);
             }
             else {
@@ -683,11 +744,22 @@ async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultD
         if (chargingManager.isClosed()) {
             throw new Error('ChargingManager is closed (actor is shutting down); charge rejected');
         }
+        // A void that did not go through for an earlier failed push must land
+        // before this push charges again, or one unsaved result is billed twice.
+        const voidsConfirmed = (await chargingManager._retryPendingVoids?.()) !== false;
         const { limitedItems, eventsToCharge } = chargingManager.calculatePushDataLimits({
             items,
             eventName,
             isDefaultDataset,
         });
+        // Only events sent to the platform count: the synthetic default-dataset
+        // event is local bookkeeping and never charged through the API.
+        if (!voidsConfirmed && Object.keys(eventsToCharge).some((name) => !isSyntheticEvent(name))) {
+            // The charge for an earlier, unsaved push may still stand: charging
+            // this push now could bill one result twice. Let the caller retry.
+            // Pushes that charge nothing go through.
+            throw new Error('[Scrapely] An earlier charge for a failed dataset push could not be voided yet; retry the push');
+        }
         const itemsArray = Array.isArray(items) ? items : [items];
         const allItemsTrimmed = itemsArray.length > 0 && limitedItems.length === 0;
         if (limitedItems.length === 0) {
@@ -711,12 +783,13 @@ async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultD
             const reservedInOp = [];
             try {
                 for (const [name, chargeCount] of ordered) {
+                    chargingManager._takeLastAcceptedOperationId?.();
                     const r = await chargingManager._chargeExclusive({
                         eventName: name,
                         count: chargeCount,
                     });
                     results.push(r);
-                    reservedInOp.push({ name, reserved: r.chargedCount });
+                    reservedInOp.push({ name, reserved: r.chargedCount, operationId: chargingManager._takeLastAcceptedOperationId?.() });
                 }
             }
             catch (err) {
@@ -762,11 +835,30 @@ async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultD
                 await pushFn(Array.isArray(items) ? toPersist : toPersist[0]);
             }
             catch (pushErr) {
-                // Charge already accepted server-side; storage failed. Do not unwind
-                // server ledger (no reverse API). Surface error so caller can retry
-                // storage; local counters already match accepted charges.
+                // Storage failed after the charge was accepted: a result is billed
+                // only if it was saved, so void this operation's platform charges
+                // and unwind the local (synthetic) reservations, then surface the
+                // error so the caller can retry the push (which charges again).
                 console.error(`[Scrapely] Dataset push failed after charge accepted ` +
-                    `(items=${acceptedForItems}): ${pushErr.message}`);
+                    `(items=${acceptedForItems}): ${pushErr.message}; voiding the charge`);
+                // Only when the push certainly stored nothing: the storage API
+                // answered with an error, or the connection was never made. A
+                // timeout or reset after sending may have stored the items, so
+                // the charge stands for those (they may be in the dataset).
+                if (!pushCertainlyFailed(pushErr))
+                    throw pushErr;
+                for (let i = 0; i < reservedInOp.length; i++) {
+                    const { name, operationId } = reservedInOp[i];
+                    const reserved = results[i].chargedCount;
+                    if (reserved <= 0)
+                        continue;
+                    if (operationId) {
+                        await chargingManager._voidCharge(name, operationId, reserved);
+                    }
+                    else if (isSyntheticEvent(name)) {
+                        chargingManager.applyAcceptedCount(name, reserved, 0);
+                    }
+                }
                 throw pushErr;
             }
             return chargeResult;
@@ -780,3 +872,26 @@ async function pushDataAndCharge({ chargingManager, items, eventName, isDefaultD
         };
     });
 }
+/** HTTP status of an API/client error, if the server answered. */
+function httpStatusOf(err) {
+    const e = err;
+    const raw = e?.statusCode ?? e?.status ?? e?.response?.status ?? e?.response?.statusCode;
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : undefined;
+}
+const NOT_SENT_CODES = new Set(['ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EHOSTUNREACH', 'ENETUNREACH']);
+/**
+ * @internal True when a dataset push certainly stored nothing: the storage API
+ * answered with an error status, or the request never reached it. Timeouts and
+ * resets after the request was sent are not proof (the write may have landed).
+ */
+function pushCertainlyFailed(err) {
+    for (let e = err, depth = 0; e && depth < 4; e = e.cause, depth++) {
+        const status = httpStatusOf(e);
+        if (status !== undefined)
+            return status >= 400;
+        const code = e.code;
+        if (typeof code === 'string' && NOT_SENT_CODES.has(code))
+            return true;
+    }
+    return false;
+}

package/dist/proxy-configuration.d.ts

@@ -53,14 +53,17 @@ export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions
     /**
      * Input-schema alias for groups. Normalized to groups.
      */
-    apifyProxyGroups?: string[];
+    scrapelyProxyGroups?: string[];
     /**
      * Input-schema alias for subdivisionCode. Normalized to subdivisionCode.
      */
-    apifyProxySubdivision?: string;
+    scrapelyProxySubdivision?: string;
     /**
      * Input-schema alias for countryCode. Normalized to countryCode.
      */
+    scrapelyProxyCountry?: string;
+    apifyProxyGroups?: string[];
+    apifyProxySubdivision?: string;
     apifyProxyCountry?: string;
     /**
      * Platform proxy password. Defaults to the password injected by the
@@ -73,9 +76,10 @@ export interface ProxyConfigurationOptions extends CoreProxyConfigurationOptions
  */
 export interface CreateProxyConfigurationOptions extends ProxyConfigurationOptions {
     /**
-     * For compatibility with existing Actor Input UI (Input Schema).
-     * When set to `false`, this method returns `undefined`.
+     * The proxy input field's switch (input schema `editor: "proxy"`). When
+     * `false` and no custom proxies are given, this method returns `undefined`.
      */
+    useScrapelyProxy?: boolean;
     useApifyProxy?: boolean;
     /**
      * Whether to verify the proxy configuration by testing a connection.

package/dist/proxy-configuration.js

@@ -39,14 +39,17 @@ function hasCustomProxyOptions(options) {
 }
 function normalizeProxyInput(options) {
     const normalized = { ...options };
-    if (normalized.apifyProxyGroups && !normalized.groups) {
-        normalized.groups = normalized.apifyProxyGroups;
+    const groups = normalized.scrapelyProxyGroups ?? normalized.apifyProxyGroups;
+    if (groups && !normalized.groups) {
+        normalized.groups = groups;
     }
-    if (normalized.apifyProxyCountry && !normalized.countryCode) {
-        normalized.countryCode = normalized.apifyProxyCountry;
+    const countryCode = normalized.scrapelyProxyCountry ?? normalized.apifyProxyCountry;
+    if (countryCode && !normalized.countryCode) {
+        normalized.countryCode = countryCode;
     }
-    if (normalized.apifyProxySubdivision && !normalized.subdivisionCode) {
-        normalized.subdivisionCode = normalized.apifyProxySubdivision;
+    const subdivisionCode = normalized.scrapelyProxySubdivision ?? normalized.apifyProxySubdivision;
+    if (subdivisionCode && !normalized.subdivisionCode) {
+        normalized.subdivisionCode = subdivisionCode;
     }
     return normalized;
 }
@@ -60,17 +63,19 @@ function normalizeProxyInput(options) {
  */
 async function createProxyConfiguration(options = {}) {
     const normalized = normalizeProxyInput(options);
-    const { useApifyProxy, checkAccess = true, ...proxyOptions } = normalized;
-    // Apify parity: `useApifyProxy: false` explicitly disables the PLATFORM proxy
+    const { useScrapelyProxy, useApifyProxy, checkAccess = true, ...proxyOptions } = normalized;
+    // `useScrapelyProxy: false` (or the legacy `useApifyProxy: false`; a boolean
+    // useScrapelyProxy wins) explicitly disables the PLATFORM proxy
     // only — custom proxies from the same input must still be used. The standard
-    // "Custom proxy URLs" input shape is `{ useApifyProxy: false, proxyUrls: [...] }`;
+    // "Custom proxy URLs" input shape is `{ useScrapelyProxy: false, proxyUrls: [...] }`;
     // returning undefined for it would silently drop the user's own proxies and
     // crawl on their real IPs. We only bail when NO custom proxy mode is given —
     // proxyUrls, tieredProxyUrls, tieredProxyConfig and newUrlFunction all count
     // (Python SDK Actor.create_proxy_configuration parity).
-    const dontUseApifyProxy = useApifyProxy === false;
+    const usePlatformProxy = typeof useScrapelyProxy === 'boolean' ? useScrapelyProxy : useApifyProxy;
+    const dontUsePlatformProxy = usePlatformProxy === false;
     const dontUseCustomProxies = !hasCustomProxyOptions(proxyOptions);
-    if (dontUseApifyProxy && dontUseCustomProxies) {
+    if (dontUsePlatformProxy && dontUseCustomProxies) {
         return undefined;
     }
     if (!hasCustomProxyOptions(proxyOptions)) {

package/dist/scrapely-proxy-configuration.d.ts

@@ -89,7 +89,10 @@ export declare class ProxyConfiguration extends CrawleeProxyConfiguration {
     /**
      * Verifies the proxy configuration. For platform proxy mode with an
      * injected status URL, performs the Apify-format access check through the
-     * gateway (`GET {statusUrl}/?format=json`, best-effort, never fatal);
+     * gateway (`GET {statusUrl}/?format=json`). When the gateway answers
+     * `connected: false` (e.g. an unknown proxy group), it throws with the
+     * gateway's `connectionError` on the platform and warns locally, like
+     * Apify's `_checkAccess`; timeouts and HTTP errors only warn.
      * BYOP mode only verifies that a test URL can be generated.
      */
     initialize(options?: {

package/dist/scrapely-proxy-configuration.js

@@ -73,6 +73,12 @@ function validateProxySessionId(sessionId) {
     }
     return sessionId;
 }
+/** `groups`, else the input-schema alias `scrapelyProxyGroups`, else the legacy `apifyProxyGroups`. */
+function platformGroups(options) {
+    if (options.groups?.length)
+        return options.groups;
+    return options.scrapelyProxyGroups ?? options.apifyProxyGroups;
+}
 /**
  * Resolves and validates the country/subdivision options (Apify parity).
  * Country must be a two-letter ISO code; subdivision an ISO 3166-2 code
@@ -80,8 +86,8 @@ function validateProxySessionId(sessionId) {
  * the normalized values used by the username grammar.
  */
 function resolveCountryOptions(options) {
-    const countryCode = options.countryCode ?? options.apifyProxyCountry;
-    const subdivisionCode = options.subdivisionCode ?? options.apifyProxySubdivision;
+    const countryCode = options.countryCode ?? options.scrapelyProxyCountry ?? options.apifyProxyCountry;
+    const subdivisionCode = options.subdivisionCode ?? options.scrapelyProxySubdivision ?? options.apifyProxySubdivision;
     if (countryCode != null && !COUNTRY_CODE_REGEX.test(countryCode)) {
         throw new Error(`ProxyConfiguration: "countryCode" must be a two-letter ISO country code (got "${countryCode}").`);
     }
@@ -225,7 +231,7 @@ async function requestThroughProxy(targetUrl, proxyUrl, timeoutMs) {
  * server.
  */
 function buildPlatformProxyUrl(options, env, sessionId) {
-    const groups = options.groups?.length ? options.groups : options.apifyProxyGroups;
+    const groups = platformGroups(options);
     const { countryCode, subdivisionCode } = resolveCountryOptions(options);
     const password = options.password ?? env.password;
     // Apify username grammar: groups, then session, then country — with the
@@ -334,7 +340,7 @@ function toCrawleeOptions(options, env, placeholderOptions) {
     return crawleeOptions;
 }
 function hasApifyOnlyOptions(options) {
-    const groups = options.groups?.length ? options.groups : options.apifyProxyGroups;
+    const groups = platformGroups(options);
     const { countryCode, subdivisionCode } = resolveCountryOptions(options);
     return !!(groups?.length || countryCode || subdivisionCode || options.password);
 }
@@ -382,10 +388,10 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
         // values throw at construction, not on the first newUrl() call).
         resolveCountryOptions(options);
         if (hasRealCustomProxyOptions(options) && hasApifyOnlyOptions(options)) {
-            throw new Error('Cannot combine custom proxies with Apify Proxy! ' +
+            throw new Error('Cannot combine custom proxies with Scrapely 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.subdivisionCode" or "options.apifyProxySubdivision".');
+                '"options.groups" or "options.scrapelyProxyGroups" and "options.countryCode" or ' +
+                '"options.scrapelyProxyCountry", "options.subdivisionCode" or "options.scrapelyProxySubdivision".');
         }
         if (needsPlatformProxyUrls(options) && !platformEnv) {
             throw new Error('[Scrapely] The platform proxy was requested (via the "auto" sentinel, tieredProxyConfig tiers without ' +
@@ -445,9 +451,7 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
         const sid = sessionId != null ? validateProxySessionId(String(sessionId)) : undefined;
         const info = await super.newProxyInfo(sid, options);
         if (info && this.platformEnv && info.hostname === this.platformEnv.hostname) {
-            const groups = this.platformOptions.groups?.length
-                ? this.platformOptions.groups
-                : this.platformOptions.apifyProxyGroups;
+            const groups = platformGroups(this.platformOptions);
             const { countryCode, subdivisionCode } = resolveCountryOptions(this.platformOptions);
             return {
                 ...info,
@@ -483,6 +487,7 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
                         connectionError: 'Platform proxy authentication failed (HTTP 407). Check the injected ' +
                             'SCRAPELY_PROXY_*/APIFY_PROXY_* credentials.',
                         isManInTheMiddle: false,
+                        fromPayload: false,
                     };
                 }
                 if (statusCode >= 590 && statusCode <= 599) {
@@ -491,6 +496,7 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
                         connected: false,
                         connectionError: `Platform proxy upstream error (HTTP ${statusCode}: ${description}).`,
                         isManInTheMiddle: false,
+                        fromPayload: false,
                     };
                 }
                 if (statusCode >= 200 && statusCode < 300) {
@@ -500,6 +506,7 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
                             connected: parsed.connected === true,
                             connectionError: parsed.connectionError ?? '',
                             isManInTheMiddle: parsed.isManInTheMiddle === true,
+                            fromPayload: true,
                         };
                     }
                     catch {
@@ -516,7 +523,10 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
     /**
      * Verifies the proxy configuration. For platform proxy mode with an
      * injected status URL, performs the Apify-format access check through the
-     * gateway (`GET {statusUrl}/?format=json`, best-effort, never fatal);
+     * gateway (`GET {statusUrl}/?format=json`). When the gateway answers
+     * `connected: false` (e.g. an unknown proxy group), it throws with the
+     * gateway's `connectionError` on the platform and warns locally, like
+     * Apify's `_checkAccess`; timeouts and HTTP errors only warn.
      * BYOP mode only verifies that a test URL can be generated.
      */
     async initialize(options = {}) {
@@ -526,7 +536,7 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
         }
         // Apify-parity access check: GET {statusUrl}/?format=json *through the
         // platform gateway* so the proxy handshake itself authenticates the
-        // run's credentials. Best-effort — never hard fails the run.
+        // run's credentials.
         if (checkAccess && this.platformEnv?.statusUrl) {
             const status = await this.fetchProxyStatus();
             if (!status) {
@@ -535,6 +545,9 @@ class ProxyConfiguration extends core_1.ProxyConfiguration {
             }
             else {
                 this.isManInTheMiddle = status.isManInTheMiddle;
+                if (!status.connected && status.fromPayload && this.config.get('isAtHome')) {
+                    throw new Error(status.connectionError);
+                }
                 if (!status.connected) {
                     console.warn(`[Scrapely] Platform proxy access check failed: ${status.connectionError}`);
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "scrapely",
-    "version": "1.2.7",
+    "version": "1.2.9",
     "description": "Scrapely SDK for building JavaScript and TypeScript Actors",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -19,6 +19,7 @@
     "scripts": {
         "test": "npx tsx tests/test-mvp.ts",
         "test:charging": "npx tsx --test tests/charging-pending.test.ts",
+        "test:stdio-drain": "npx tsx --test tests/stdio-drain.test.ts",
         "test:charging-client": "npx tsx --test tests/charging-client.test.ts",
         "test:proxy": "npx tsx --test tests/proxy-configuration.test.ts",
         "test:browser-pool": "npx tsx --test tests/patch-browser-pool.test.ts",
@@ -30,6 +31,7 @@
         "prod:update": "bash scripts/deploy-prod.sh --update-only",
         "migrate": "npx tsx scripts/run-migration.ts",
         "test:local-run": "npx tsx --test tests/local-run.test.ts",
+        "test:input-from-kv": "npx tsx --test tests/input-from-kv.test.ts",
         "test:init-rollback": "npx tsx --test tests/init-rollback.test.ts",
         "test:apify-parity": "npx tsx --test tests/apify-parity.test.ts",
         "test:run-control": "npx tsx --test tests/run-control.test.ts",