refactor: reorganize documentation structure

website/versioned_docs/version-2/index.md → docs/01_introduction/index.md

@@ -1,6 +1,9 @@
 ---
-sidebar_label: 'Overview'
-title: 'Apify API client for JavaScript'
+id: introduction
+title: Overview
+sidebar_label: Overview
+slug: /
+description: 'The official JavaScript library to access the Apify API, with automatic retries, TypeScript support, and cross-platform compatibility.'
 ---
 
 import Tabs from '@theme/Tabs';
@@ -12,13 +15,54 @@ The client simplifies interaction with the Apify platform by providing:
 
 - Intuitive methods for working with [Actors](https://docs.apify.com/platform/actors), [datasets](https://docs.apify.com/platform/storage/dataset), [key-value stores](https://docs.apify.com/platform/storage/key-value-store), and other Apify resources
 - Intelligent parsing of API responses and rich error messages for debugging
-- Built-in [exponential backoff](./getting-started.md#retries-with-exponential-backoff) for failed requests
+- Built-in [exponential backoff](../02_concepts/02_error-handling.md#retries-with-exponential-backoff) for failed requests
 - Full TypeScript support with comprehensive type definitions
 - Cross-platform compatibility in [Node.js](https://nodejs.org/) v16+ and modern browsers
 
 All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding.
 
-> For installation instructions, check the [Getting Started Guide](./getting-started.md).
+## Pre-requisites
+
+`apify-client` requires Node.js version 16 or higher. Node.js is available for download on the [official website](https://nodejs.org/). Check for your current Node.js version by running:
+
+```bash
+node -v
+```
+
+## Installation
+
+You can install the client via [NPM](https://www.npmjs.com/) or any other package manager of your choice.
+
+<Tabs groupId="main">
+<TabItem value="npm" label="NPM">
+
+```bash
+npm i apify-client
+```
+
+</TabItem>
+<TabItem value="yarn" label="Yarn">
+
+```bash
+yarn add apify-client
+```
+
+</TabItem>
+<TabItem value="pnpm" label="PNPM">
+
+```bash
+pnpm add apify-client
+```
+
+</TabItem>
+<TabItem value="bun" label="Bun">
+
+```bash
+bun add apify-client
+```
+
+</TabItem>
+</Tabs>
 
 ## Quick example
 
@@ -43,4 +87,4 @@ const { items } = await client.dataset(run.defaultDatasetId).listItems();
 console.log(items);
 ```
 
-> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console. See the [Getting Started Guide](./getting-started.md#authentication-and-initialization) for more details on authentication.
+> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console. See the [Quick start guide](./quick-start.md) for more details on authentication.

docs/01_introduction/quick-start.md

@@ -0,0 +1,84 @@
+---
+id: quick-start
+title: Quick start
+sidebar_label: Quick start
+description: 'Get started with the Apify API client for JavaScript by running an Actor and retrieving results from its dataset.'
+---
+
+Learn how to authenticate, run Actors, and retrieve results using the Apify API client for JavaScript.
+
+---
+
+## Step 1: Authenticate the client
+
+To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+// Client initialization with the API token
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+});
+```
+
+:::warning Secure access
+
+The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications.
+
+:::
+
+## Step 2: Run an Actor
+
+To start an Actor, call the [`client.actor()`](/reference/class/ActorClient) method with the Actor's ID (e.g. `john-doe/my-cool-actor`). The Actor's ID is a combination of the Actor owner's username and the Actor name. You can run both your own Actors and Actors from Apify Store.
+
+To define the Actor's input, pass a JSON object to the [`call()`](/reference/class/ActorClient#call) method that matches the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema). The input can include URLs to scrape, search terms, or other configuration data.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Runs an Actor with an input and waits for it to finish.
+const { defaultDatasetId } = await client.actor('username/actor-name').call({
+    some: 'input',
+});
+```
+
+## Step 3: Get results from the dataset
+
+To get the results from the dataset, call the [`client.dataset()`](/reference/class/DatasetClient) method with the dataset ID, then call [`listItems()`](/reference/class/DatasetClient#listItems) to retrieve the data. You can get the dataset ID from the Actor's run object (represented by `defaultDatasetId`).
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Runs an Actor and waits for it to finish
+const { defaultDatasetId } = await client.actor('username/actor-name').call();
+
+// Lists items from the Actor's dataset
+const { items } = await client.dataset(defaultDatasetId).listItems();
+console.log(items);
+```
+
+:::note Dataset access
+
+Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs).
+
+:::
+
+## Next steps
+
+### Concepts
+
+To learn more about how the client works, check out the Concepts section in the sidebar:
+
+- [Usage patterns](../02_concepts/01_usage-patterns.md) - resource clients, collection clients, and nested clients
+- [Error handling and retries](../02_concepts/02_error-handling.md) - automatic retries with exponential backoff
+- [Convenience functions](../02_concepts/03_convenience-functions.md) - `call()`, `waitForFinish()`, and more
+- [Pagination](../02_concepts/04_pagination.md) - iterating through large result sets
+
+### Guides
+
+For practical examples of common tasks, see [Code examples](../03_guides/01_examples.md).

docs/02_concepts/01_usage-patterns.md

@@ -0,0 +1,69 @@
+---
+id: usage-patterns
+title: Usage patterns
+sidebar_label: Usage patterns
+description: 'Learn the resource client and collection client patterns used by the Apify API client for JavaScript.'
+---
+
+The `ApifyClient` interface follows a generic pattern that applies to all of its components. By calling individual methods of `ApifyClient`, specific clients that target individual API resources are created. There are two types of those clients:
+
+- [`ActorClient`](/reference/class/ActorClient): a client for the management of a single resource
+- [`ActorCollectionClient`](/reference/class/ActorCollectionClient): a client for the collection of resources
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Collection clients do not require a parameter.
+const actorCollectionClient = client.actors();
+// Creates an actor with the name: my-actor.
+const myActor = await actorCollectionClient.create({ name: 'my-actor-name' });
+// List all your used Actors (both own and from Apify Store)
+const { items } = await actorCollectionClient.list();
+```
+
+:::note Resource identification
+
+The resource ID can be either the `id` of the said resource, or a combination of your `username/resource-name`.
+
+:::
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Resource clients accept an ID of the resource.
+const actorClient = client.actor('username/actor-name');
+// Fetches the john-doe/my-actor object from the API.
+const myActor = await actorClient.get();
+// Starts the run of john-doe/my-actor and returns the Run object.
+const myActorRun = await actorClient.start();
+```
+
+## Nested clients
+
+Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given Actor.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+const actorClient = client.actor('username/actor-name');
+const runsClient = actorClient.runs();
+// Lists the last 10 runs of your Actor.
+const { items } = await runsClient.list({
+    limit: 10,
+    desc: true,
+});
+
+// Select the last run of your Actor that finished
+// with a SUCCEEDED status.
+const lastSucceededRunClient = actorClient.lastRun({ status: 'SUCCEEDED' });
+// Fetches items from the run's dataset.
+const { items } = await lastSucceededRunClient.dataset().listItems();
+```
+
+The quick access to `dataset` and other storage directly from the run client can be used with the [`lastRun()`](/reference/class/ActorClient#lastRun) method.

docs/02_concepts/02_error-handling.md

@@ -0,0 +1,40 @@
+---
+id: error-handling
+title: Error handling and retries
+sidebar_label: Error handling and retries
+description: 'Handle API errors and configure automatic retries with exponential backoff in the Apify API client for JavaScript.'
+---
+
+Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `Date` objects. For exceptions, the client throws an [`ApifyApiError`](/reference/class/ApifyApiError), which wraps the plain JSON errors returned by API and enriches them with other contexts for easier debugging.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+try {
+    const { items } = await client.dataset('non-existing-dataset-id').listItems();
+} catch (error) {
+    // The error is an instance of ApifyApiError
+    const { message, type, statusCode, clientMethod, path } = error;
+    // Log error for easier debugging
+    console.log({ message, statusCode, clientMethod, type });
+}
+```
+
+## Retries with exponential backoff
+
+The client automatically retries requests that fail due to network errors, Apify API internal errors (HTTP 500+), or rate limit errors (HTTP 429). By default, the client retries up to 8 times with exponential backoff starting at 500ms.
+
+To configure retry behavior, set the `maxRetries` and `minDelayBetweenRetriesMillis` options in the `ApifyClient` constructor:
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+    maxRetries: 8,
+    minDelayBetweenRetriesMillis: 500, // 0.5s
+    timeoutSecs: 360, // 6 mins
+});
+```

docs/02_concepts/03_convenience-functions.md

@@ -0,0 +1,24 @@
+---
+id: convenience-functions
+title: Convenience functions
+sidebar_label: Convenience functions
+description: 'Use call(), waitForFinish(), and other convenience functions in the Apify API client for JavaScript.'
+---
+
+Some actions can't be performed by the API itself, such as indefinite waiting for an Actor run to finish (because of network timeouts). The client provides convenient `call()` and `waitForFinish()` functions that do that. If the limit is reached, the returned promise is resolved to a run object that will have status `READY` or `RUNNING` and it will not contain the Actor run output.
+
+[Key-value store](https://docs.apify.com/platform/storage/key-value-store) records can be retrieved as objects, buffers, or streams via the respective options, dataset items can be fetched as individual objects or serialized data.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Starts an Actor and waits for it to finish.
+const finishedActorRun = await client.actor('username/actor-name').call();
+
+// Starts an Actor and waits maximum 60s for the finish
+const { status } = await client.actor('username/actor-name').start({
+    waitForFinish: 60, // 1 minute
+});
+```

docs/02_concepts/04_pagination.md

@@ -0,0 +1,31 @@
+---
+id: pagination
+title: Pagination
+sidebar_label: Pagination
+description: 'Paginate through large result sets and use async iteration with the Apify API client for JavaScript.'
+---
+
+Methods that return lists (such as `list()` or `listSomething()`) return a [`PaginatedList`](/reference/interface/PaginatedList) object. Exceptions include `listKeys()` and `listHead()`, which use different pagination mechanisms.
+
+The list results are stored in the `items` property. Use the `limit` parameter to retrieve a specific number of results. Additional properties vary by method—see the method reference for details.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'MY-APIFY-TOKEN' });
+
+// Resource clients accept an ID of the resource.
+const datasetClient = client.dataset('dataset-id');
+
+// Maximum amount of items to fetch in total
+const limit = 1000;
+// Maximum amount of items to fetch in one API call
+const chunkSize = 100;
+// Initial offset
+const offset = 0;
+
+for await (const item of datasetClient.listItems({ limit, offset, chunkSize })) {
+    // Processs individual item
+    console.log(item);
+}
+```

docs/02_concepts/05_bundled-environments.md

@@ -0,0 +1,22 @@
+---
+id: bundled-environments
+title: Use in bundled environments
+sidebar_label: Bundled environments
+description: 'Use the Apify API client for JavaScript in browsers, Cloudflare Workers, and other edge runtimes.'
+---
+
+:::warning Advanced
+
+This applies only to non-Node.js environments (browsers, Cloudflare Workers, edge runtimes). If you're running on Node.js, you can skip this section.
+
+:::
+
+The package ships a pre-built browser bundle that is automatically resolved when your bundler targets a browser environment. If it isn't picked up automatically, you can import it directly:
+
+```js
+import { ApifyClient } from 'apify-client/browser';
+```
+
+For Cloudflare Workers or other edge runtimes that don't provide Node built-ins, you may need to enable Node compatibility in your runtime config (e.g. `node_compat = true`.
+
+Note that some Node-specific features (streaming APIs, proxy) are not available in the browser bundle.

docs/examples/index.md → docs/03_guides/01_examples.md

@@ -1,6 +1,8 @@
 ---
+id: examples
+title: Code examples
 sidebar_label: Examples
-title: 'Code examples'
+description: 'Practical code examples for common tasks with the Apify API client for JavaScript, including webhooks and datasets.'
 ---
 
 ## Passing an input to the Actor