docs: Refactor documentation structure and add new guides

docs/01_introduction/index.md

@@ -0,0 +1,16 @@
+---
+sidebar_label: 'Overview'
+title: 'Overview'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Apify Client is the official library to access the [Apify REST API](https://docs.apify.com/api/v2) from your JavaScript/TypeScript applications. 
+
+It runs both in Node.js and browser and provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding.
+
+## Next steps
+
+- Learn how to install the Apify Client in the [Installation](installation.md) guide
+- Start with the Apify Client using the [Quick start](quick-start.md) guide

docs/01_introduction/installation.md

@@ -0,0 +1,119 @@
+---
+sidebar_label: 'Installation'
+title: 'Installation'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+Learn how to install Apify Client using NPM, Yarn, PNPM, or Bun.
+
+---
+
+## Prerequisites
+
+Apify Client requires Node.js version 22 or higher. Node.js is available for download on the [official website](https://nodejs.org/). 
+
+Check for your current node version by running:
+
+```bash
+node -v
+```
+
+## Installation
+
+You can install the client via [NPM](https://www.npmjs.com/) or use 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>
+
+## Authentication and Initialization
+
+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 Apify client
+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
+
+:::
+
+## Usage concepts
+
+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();
+```
+
+## Next steps
+
+- Check out the [quick start](quick-start.md) guide

docs/01_introduction/quick-start.md

@@ -0,0 +1,89 @@
+---
+sidebar_label: 'Quick Start'
+title: 'Quick Start'
+description: 'Get started with the Apify client for JavaScript by running your first Actor and retrieving results.'
+---
+
+Learn how to start Actors and retrieve their results using the Apify Client.
+
+---
+
+## Step 1: Authentication and initialization
+
+To use the client, you need an [API token](/platform/integrations/api#api-token). You can find your token under the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing it as a parameter to the `ApifyClient` constructor.
+
+```js
+import { ApifyClient } from 'apify-client';
+
+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: Running your first Actor
+
+To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the Actor name and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify Store](https://docs.apify.com/platform/actors/running/actors-in-store).
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+});
+
+// Starts an Actor and waits for it to finish
+const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();
+```
+
+### Passing input to the Actor
+
+Actors often require input, such as URLs to scrape, search terms, or other configuration data. You can pass input as a JSON object when starting the Actor using the [`ActorClient.call`](/reference/class/ActorClient#call) method. Actors respect the input schema defined in the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema).
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+});
+
+// Runs an Actor with input and waits for it to finish
+const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call({
+    startUrls: [{ url: 'https://example.com' }],
+    maxDepth: 3,
+});
+```
+
+## Step 3: Getting results from the dataset
+
+To get the results from the dataset, you can use the [`DatasetClient`](/reference/class/DatasetClient) ([`ApifyClient.dataset`](/reference/class/ApifyClient#dataset)) and [`DatasetClient.listItems`](/reference/class/DatasetClient#listItems) method. You need to pass the dataset ID to define which dataset you want to access. 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',
+});
+
+// Starts an Actor and waits for it to finish
+const { defaultDatasetId } = await client.actor('john-doe/my-cool-actor').call();
+
+// Lists items from the Actor's dataset
+const { items } = await client.dataset(defaultDatasetId).listItems();
+
+// Process the results
+items.forEach((item) => {
+    console.log(item);
+});
+```
+
+:::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).
+
+:::

docs/02_concepts/01_authentication.md

@@ -0,0 +1,107 @@
+---
+sidebar_label: 'Authentication'
+title: 'Authentication'
+description: 'Learn how to authenticate with the Apify API using API tokens and manage credentials securely in your applications.'
+---
+
+## API Token Authentication
+
+To use the Apify Client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). The API token authorizes your requests to the Apify API and identifies your account.
+
+### Getting Your API Token
+
+You can find your API token in the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console:
+
+1. Log in to [Apify Console](https://console.apify.com/)
+2. Navigate to **Settings** → **Integrations**
+3. Copy your API token from the **Personal API tokens** section
+
+### Initializing the Client
+
+Pass your API token to the `ApifyClient` constructor:
+
+```js
+import { ApifyClient } from 'apify-client';
+
+// Initialize the client with your API token
+const client = new ApifyClient({
+    token: 'MY-APIFY-TOKEN',
+});
+```
+
+### Using Environment Variables
+
+For better security, store your API token in an environment variable rather than hardcoding it:
+
+```js
+import { ApifyClient } from 'apify-client';
+
+// Initialize with token from environment variable
+const client = new ApifyClient({
+    token: process.env.APIFY_TOKEN,
+});
+```
+
+Set the environment variable before running your script:
+
+```bash
+export APIFY_TOKEN='MY-APIFY-TOKEN'
+node your-script.js
+```
+
+:::tip Best Practice
+
+The Apify Client automatically reads the `APIFY_TOKEN` environment variable if you don't provide a token explicitly:
+
+```js
+// This will use process.env.APIFY_TOKEN automatically
+const client = new ApifyClient();
+```
+
+:::
+
+## Token Storage Best Practices
+
+Follow these security guidelines when working with API tokens:
+
+- **Never commit tokens to version control** - Use environment variables or secret management tools
+- **Don't expose tokens on the client side** - Only use API tokens in server-side code
+- **Rotate tokens regularly** - Generate new tokens periodically and revoke old ones
+- **Use separate tokens for different projects** - Create multiple tokens for better access control
+- **Store tokens securely** - Use encrypted storage or secure secret management services
+
+:::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.
+
+:::
+
+## Handling Authentication Errors
+
+If authentication fails, the client will throw an error with a `401 Unauthorized` status code:
+
+```js
+import { ApifyClient } from 'apify-client';
+
+const client = new ApifyClient({ token: 'invalid-token' });
+
+try {
+    await client.user().get();
+} catch (error) {
+    if (error.statusCode === 401) {
+        console.error('Authentication failed: Invalid API token');
+    }
+}
+```
+
+Common authentication issues:
+
+- **Invalid token format** - Ensure you copied the entire token
+- **Expired token** - Tokens can be revoked; generate a new one
+- **Missing token** - Make sure the token is properly set
+- **Wrong token** - Verify you're using the correct token for your account
+
+## Next Steps
+
+- Learn about [client architecture](02_client_architecture.md) to understand how clients work
+- See [error handling](03_error_handling.md) for comprehensive error management strategies