docs: Add overview page (#783)

Part of the fix for apify/apify-docs#1869

Author: marcel-rbro

docs/getting-started.md

@@ -0,0 +1,287 @@
+---
+sidebar_label: 'Getting started'
+title: 'Getting started with JavaScript client'
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+The Apify API 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.
+
+## 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>
+
+## 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
+
+:::
+
+## Quick start
+
+One of the most common use cases is starting [Actors](https://docs.apify.com/platform/actors) (serverless programs running in the [Apify platform](https://docs.apify.com/platform)) and getting results from their [datasets](https://docs.apify.com/platform/storage/dataset) after they finish the job (either scraping, automation processes or data processing).
+
+```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('username/actor-name').call();
+
+// Lists items from the Actor's dataset
+const { items } = await client.dataset(defaultDatasetId).listItems();
+```
+
+### Running Actors
+
+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 name and the Actor owner's username. You can run both your own Actors and Actors from Apify Store.
+
+#### Passing input to the Actor
+
+To define the Actor's input, call the [`call()`](/reference/class/ActorClient#call) method with a JSON object 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',
+});
+```
+
+### Getting 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' });
+
+// Lists items from the Actor's dataset.
+const { items } = await client.dataset('dataset-id').listItems();
+```
+
+:::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).
+
+:::
+
+## 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();
+```
+
+### 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.
+
+## Features
+
+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
+});
+```
+
+### Convenience functions and options
+
+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
+});
+```
+
+### Pagination
+
+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');
+
+// Number of items per page
+const limit = 1000;
+// Initial offset
+let offset = 0;
+// Array to store all items
+let allItems = [];
+
+while (true) {
+    const { items, total } = await datasetClient.listItems({ limit, offset });
+
+    console.log(`Fetched ${items.length} items`);
+
+    // Merge new items with other already loaded items
+    allItems.push(...items);
+
+    // If there are no more items to fetch, exit the loading
+    if (offset + limit >= total) {
+        break;
+    }
+
+    offset += limit;
+}
+
+console.log(`Overall fetched ${allItems.length} items`);
+```