[vdusek]

Issue

• Closes Expose the timeout tiers on the public API #1029
• This is a port of the following:
  • feat!: Introduce tiered timeout system with per-endpoint configuration apify-client-python#653
  • refactor!: Update default timeout tiers on non-storage resource clients apify-client-python#664
  • fix: Warn when a requested timeout is capped at timeout_max apify-client-python#962

Description

The client already chose a timeout per method internally, but the only public knob was the global timeoutSecs, so a call that legitimately takes longer had no way to ask for more time. The tiers are now public, following the Python client, and every method that sends a request takes a timeoutSecs option.

Tier	Default	Covers
short	5 s	metadata reads and writes
medium	30 s	listing, batch and trigger calls
long	360 s	downloads, uploads and streaming
noTimeout	none	polling that waits for a job to finish

Every method keeps the tier its Python counterpart has. timeoutMaxSecs caps a single attempt and bounds the growth across retries, which doubles from the requested value (T, 2T, 4T, 8T). The six waitForFinish methods get the API's one-minute hold on top of their tier, so the client doesn't abort a request the API is still holding and start a second run on retry.

timeoutSecs takes a tier name, a number of seconds, or 'noTimeout'. The unit lives in the option name rather than in the value, the way waitSecs and timeoutMaxSecs already do.

The last commit also drops the leading underscore from non-public members, as agreed in review. Where the underscore was covering a collision with a public member, the helper got a new name: _url to buildUrl, _params to buildParams, _get to getResource, _list to listResources, _waitForFinish to waitForJobFinish, _batchAddRequests to addRequestBatch, and ApifyClient._options to subClientOptions. src/apify_api_error.ts and src/statistics.ts are left for #1057.

Testing

test/client_timeouts.test.ts covers the tier defaults, per-call overrides, the waitForFinish hold, runTimeoutSecs and the requestQueue(id, { timeoutSecs }) cap. test/http_client.test.ts covers the cap warning and the retry growth. test/apify_api_error.test.ts guards clientMethod, which reads the renamed helpers off the stack.

Breaking changes

• timeoutSecs on the constructor is replaced by timeoutShortSecs, timeoutMediumSecs, timeoutLongSecs and timeoutMaxSecs.
• Outside the storage clients, methods used the global 360 s and now use short or medium, so a call that waited out a slow API can fail sooner.
• The run timeout of ActorClient.start() / call(), TaskClient.start() / call() and RunClient.resurrect() is now runTimeoutSecs. TypeScript reports a leftover timeout at compile time, and the option schemas are strict, so JavaScript gets an ArgumentValidationError instead of a silently dropped run limit.
• client.httpClient.call() takes timeoutSecs in seconds, where the axios field it replaces took milliseconds. A direct call that passed timeout: 30000 becomes timeoutSecs: 30.
• Methods without options gained an options parameter, and methods that take a payload gained a second one.
• The protected helpers of ApiClient, ResourceClient and ResourceCollectionClient are renamed, which reaches anyone subclassing them.

KeyValueStoreClient.setRecord() keeps its timeoutSecs, and a plain number still means what it did in v2, so Crawlee's setValue() needs no paired PR. The option now takes a tier name or 'noTimeout' as well. The same goes for client.requestQueue(id, { timeoutSecs }), which caps the tier of every request that queue client sends.

✍️ Drafted by Claude Code

[github-actions]

⚠️ There are broken links in the documentation.

See more at https://github.com/apify/apify-client-js/actions/runs/34573272623#summary-103179907823